自 V4.3.0 起，交互式智能诊断入口变更为顶级命令 obdiag agent。V4.x 曾提供的 obdiag tool ai_assistant 命令已移除，请使用 obdiag agent 命令。
自 V5.0.0 起，Agent 底层迁移至基于 LangChain/LangGraph 的 deepagents TUI，支持更丰富的交互体验（如 Textual 终端 UI、技能管理、子 Agent 等）。Agent 支持自然语言描述诊断需求，并调用 obdiag 的采集、分析、巡检、根因分析等能力。
注意
该功能为 BETA 版本，需配置 LLM（如 OpenAI 或兼容接口）。默认启用内置 MCP 将诊断能力以工具形式暴露给模型；可按需在 agent.yml 中接入外部 MCP。V5.0.0 版本开始命令行选项有调整，详见下方命令说明。
功能介绍
能力 |
说明 |
|---|---|
| 自然语言交互 | 用自然语言描述需求（如“收集日志”、“巡检集群”、“根因分析”），由 Agent 解析并调用相应工具。 |
| 内置 MCP 工具 | 默认启用内置 MCP，将 gather/analyze/check/rca 等命令封装为工具，由 LLM 按需调用。 |
| 多集群 | 默认使用 ~/.obdiag/config.yml 文件；会话中可用 /use 切换配置文件或短名。 |
| 会话续跑 | 退出时自动保存会话，可通过 obdiag agent -r 恢复最近会话或 obdiag agent -r <session_id> 恢复指定会话。交互模式下可用 /threads 浏览历史线程。 |
| Skills | 支持技能扩展；预设技能可在初始化时同步至 ~/.obdiag/agent/skills/（见 config/agent.yml 文件中 skills 模块）。可通过 /remember 指令从当前对话中提取并保存技能。 |
注意事项
- API 费用：调用外部 LLM 可能产生费用，请注意用量与密钥安全。
- 敏感信息：请通过
tool_approval等配置控制 SQL、bash 等敏感操作前的确认行为。 - 网络与权限：执行 gather/check/rca 等工具时，对 SSH、集群连通性的要求与直接执行对应 obdiag 子命令一致。
前置配置
配置文件路径：~/.obdiag/config/agent.yml，若目录不存在可先创建并复制样例。源码安装时，样例位于 obdiag 仓库 conf/agent.yml.example；RPM 安装通常在 /opt/oceanbase-diagnostic-tool/conf/agent.yml.example。
mkdir -p ~/.obdiag/config
# 源码安装时，样例位于 obdiag 仓库 conf/agent.yml.example；RPM 安装通常在 /opt/oceanbase-diagnostic-tool/conf/agent.yml.example
cp /opt/oceanbase-diagnostic-tool/conf/agent.yml.example ~/.obdiag/config/agent.yml
配置结构概要
模块 |
说明 |
|---|---|
| llm | 配置大模型信息，api_key 通常需要配置，也可通过环境变量提供，具体以运行报错提示为准。 |
| skills | 配置技能信息，directory 默认 ~/.obdiag/agent/skills。 |
| oceanbase_knowledge | 配置官方知识库网关，默认关闭。 |
| mcp | servers 用于配置外部 MCP 的 JSON 配置字符串，空则表示仅用内置 MCP。 |
| ui | 配置交互体验。 |
详细字段与注释请以安装包或源码中的 conf/agent.yml.example 为准。
命令说明
obdiag agent [options]
常用选项：
选项名 |
是否必选 |
说明 |
|---|---|---|
| -c | 否 | 集群配置文件路径，默认 ~/.obdiag/config.yml。 |
| --config | 否 | 需被 obdiag 诊断的集群的配置，格式：--config key1=value1 --config key2=value2。支持通过该选项配置的参数可参见 obdiag 配置。 |
| --config_password | 否 | 使用加密配置文件时的解密密码。具体介绍可参见 配置文件加密。 |
| -n/--non-interactive | 否 | 单次非交互模式，运行一条任务后退出。例如：obdiag agent -n "帮我巡检一下集群"。 |
| -q/--quiet | 否 | 配合 -n 使用，仅输出 Agent 回复到标准输出，适用于管道和脚本场景。 |
| --no-stream | 否 | 配合 -n 使用，缓冲完整回复后一次性输出到标准输出，而非流式输出。 |
| -r/--resume | 否 | 恢复历史会话。裸 -r 恢复最近一次会话；-r <ID> 恢复指定 ID 的会话（可通过 /threads 指令查看）。 |
| -h/--help | 否 | 查看帮助。 |
| -v/--verbose | 否 | 详细日志。 |
交互模式内置指令（以 / 开头）
指令 |
说明 |
|---|---|
/help |
显示帮助。 |
/quit、/q |
退出（会自动保存会话）。 |
/clear |
清空当前对话并新建线程。 |
/compact |
将对话压缩摘要以释放上下文窗口空间（别名 /offload）。 |
/tokens |
查看 token 用量信息。 |
/threads |
浏览并恢复历史对话线程。 |
/mcp |
列出当前可用的 MCP 服务与工具。 |
/use <name 或 path> |
切换当前集群配置（如 /use obdiag_test 或 /use /path/to/config.yml）。无参数时显示当前激活的集群信息。 |
/model |
切换或配置模型。 |
/editor |
使用外部编辑器（$EDITOR）编辑提示词。 |
/remember |
从当前对话中更新记忆和技能。 |
/theme |
切换颜色主题。 |
/version |
显示版本信息。 |
/reload |
从环境变量和 .env 文件重新加载配置。 |
使用示例
# 交互模式
obdiag agent
# 指定配置文件
obdiag agent -c obdiag_test
# 非交互模式：单次运行一条任务后退出
obdiag agent -n "帮我巡检一下集群"
# 非交互 + 静默输出（适合管道/脚本）
obdiag agent -n "检查集群状态" -q
# 恢复最近一次会话
obdiag agent -r
# 恢复指定 ID 的会话
obdiag agent -r 20260313_142055
常见问题
- 无法连接模型或提示缺少 API Key 检查
~/.obdiag/config/agent.yml中llm.api_key、llm.base_url是否与所用服务商一致。 - 如何仅使用内置诊断工具 保持
mcp.servers为空即可使用内置 MCP；llm仍须指向可访问的模型服务。 - 如何查看可用工具 交互模式下输入
/mcp。