企业官网建设流程全解析

1. 从 obdiag 采集到 RAG 检索：自动诊断 Agent 到底解决什么问题

OceanBase 集群规模一大，故障排查就会变成一件很磨人的事。我接触过的场景里，一个 CPU 使用率异常的问题，往往要同时看 top、日志、perf、obstack、OCP 面板，数据散落在多个节点，工具用法各不相同。更麻烦的是，收集到的错误码和日志片段需要人工判断，再拿着这些信息去社区或历史工单里翻相似案例。整个链路是断的：采集归采集，分析归分析，检索归检索。

自动诊断 Agent 要做的，就是把这几个环节串起来。用 obdiag 负责标准化采集和初步诊断，用 RAG 从历史案例和官方文档里检索相似故障，再通过大模型把采集结果和检索结果融合成一份可读的诊断结论。OpenManus 在这里扮演的是“调度中枢”的角色，它本身是一个通用型 Agent 框架，能理解任务、调用工具、观察结果，再决定下一步动作。

适合谁看这篇内容？如果你正在维护 OceanBase 集群，或者手头有类似的分布式数据库运维场景，想用 Agent 把重复性的排查工作自动化，那这套链路可以直接参考。如果你只是想了解 Agent 怎么调用外部工具、怎么接 RAG，也可以把 obdiag 换成你自己的采集脚本。

核心检索词先明确：OpenManus 自动诊断 Agent、obdiag 采集 OceanBase 故障数据、RAG 检索历史案例、TaoToken 统一 Key 调用模型。这四个词贯穿全文，后面每一步都会落到具体配置和命令上。

我试过把 obdiag 的输出直接丢给模型，效果并不好，因为模型缺少上下文，容易给出泛泛的建议。后来把 RAG 检索到的相似案例一起塞进提示词，诊断结论的针对性明显提升。这也是为什么这套链路里 RAG 不是可选项，而是必要环节。

整条链路的数据流是这样的：obdiag 在目标集群执行采集和诊断命令，输出结构化的日志和报告；Agent 读取这些输出，提取关键错误码和指标；RAG 模块用这些关键信息去向量库检索相似历史案例；最后把采集结果、检索结果、系统提示词一起发给模型，生成诊断结论。下面按这个顺序拆开讲。

2. TaoToken 统一 Key 接入：给 Agent 配一个稳定的模型通道

OpenManus 本身不绑定特定模型供应商，它通过配置里的模型接口来调用大模型。问题在于，如果你在 Agent 里硬编码某个厂商的 Key，后续换模型、加模型、做多模型对比都会很麻烦。TaoToken 在这里的作用是提供一个统一的 API 通道，用同一个 Key 和 Base URL 就能调用多种模型，Agent 侧只需要改 Model ID 就能切换。

先拿 Key。访问 https://taotoken.net/api-keys ，登录后创建一个 API Key，复制保存。这个 Key 后面会写进 OpenManus 的配置文件里。注意不要把它提交到 Git 仓库，建议用环境变量或者本地配置文件管理。

Base URL 用 https://taotoken.net/api ，这是 API 调用的根地址，不要加多余的路径。Model ID 根据你的场景选，诊断类任务建议用推理能力较强的模型，比如 claude-sonnet 系列或者 gpt-4o 系列，具体可用的 Model ID 可以在模型对话页面查看：https://taotoken.net/models 。

OpenManus 的配置文件通常是 config/config.toml，里面有一个 llm 段落。你需要把 base_url、api_key、model 三个字段填对。下面是一个可复制的 TOML 片段，路径和字段名以你本地 OpenManus 版本为准，如果字段名有差异，按实际结构调整：

[llm] model = "claude-sonnet-4-20250514" base_url = "https://taotoken.net/api" api_key = "sk-你的TaoTokenKey" max_tokens = 8192 temperature = 0.3

temperature 设 0.3 是为了让诊断结论更稳定，减少发散。max_tokens 根据你的诊断报告长度调整，8192 一般够用。如果你用的是 OpenManus 的 Python 配置方式，也可以在代码里通过环境变量读取：

import os from openmanus.config import Config config = Config() config.llm.base_url = "https://taotoken.net/api" config.llm.api_key = os.environ.get("TAOTOKEN_API_KEY") config.llm.model = "claude-sonnet-4-20250514"

这样配置的好处是，Agent 代码里不需要出现任何厂商特定的逻辑。后面如果要换模型，只改 model 字段，Base URL 和 Key 都不动。对于需要长期跑诊断任务的场景，这种统一通道能省掉很多切换成本。

如果你打算把诊断 Agent 做成长期运行的服务，建议了解一下 Coding Plan，它在持续调用场景下更合适：https://taotoken.net/coding-plan 。接入文档在 https://taotoken.net/doc ，里面有各语言的调用示例，遇到参数问题可以先查文档。

配置完成后，先别急着接 obdiag，用一段最小请求验证通道是否通。下面这段 Python 代码可以直接跑：

import requests url = "https://taotoken.net/api/v1/chat/completions" headers = { "Authorization": "Bearer sk-你的TaoTokenKey", "Content-Type": "application/json" } payload = { "model": "claude-sonnet-4-20250514", "messages": [ {"role": "user", "content": "回复一句：通道正常"} ] } resp = requests.post(url, headers=headers, json=payload, timeout=30) print(resp.status_code) print(resp.json()["choices"][0]["message"]["content"])

如果返回 200 并且内容里有“通道正常”，说明 Key 和 Base URL 都没问题。这一步很重要，因为后面 Agent 报错时，你需要先排除是模型通道的问题还是工具调用的问题。

3. 可复制配置：OpenManus Agent 接入 obdiag 与 RAG 检索脚本

这一节给出三个可复制的配置片段：OpenManus 的 Agent 配置、obdiag 采集命令、RAG 检索脚本。三者的关系是：Agent 配置定义工具和提示词，obdiag 命令负责采集，RAG 脚本负责检索，Agent 在运行时依次调用。

先看 OpenManus 的 Agent 配置。OpenManus 的工具注册通常在 tool 模块里，你需要新增一个 obdiag 工具类，继承基础 Tool 类，实现 execute 方法。下面是一个简化版的工具定义，放在 openmanus/tool/obdiag_tool.py：

import subprocess from openmanus.tool.base import BaseTool class ObdiagTool(BaseTool): name = "obdiag" description = "执行 obdiag 诊断命令，采集 OceanBase 集群故障数据" def execute(self, command: str) -> str: allowed = ["obdiag check", "obdiag analyze", "obdiag gather"] if not any(command.startswith(prefix) for prefix in allowed): return "命令不在允许范围内" result = subprocess.run( command, shell=True, capture_output=True, text=True, timeout=300 ) return result.stdout + result.stderr

这个工具做了命令白名单，只允许 check、analyze、gather 三类操作，避免 Agent 执行危险命令。实际使用时可以把白名单收得更紧，比如只允许特定参数组合。

Agent 的提示词配置放在 prompt 模块，核心是告诉 Agent 它的角色和可用工具。下面是一段系统提示词示例：

你是一个 OceanBase 诊断助手。你可以使用 obdiag 工具采集集群数据， 使用 rag_search 工具检索历史案例。你的任务是： 1. 根据用户描述的问题，选择合适的 obdiag 命令采集数据 2. 从采集结果中提取错误码和关键指标 3. 调用 rag_search 检索相似历史案例 4. 综合采集结果和检索结果，生成诊断结论 诊断结论必须包含：问题定位、可能原因、建议操作。

接下来是 obdiag 采集命令。假设你要排查一个 CPU 使用率异常的问题，可以按下面的顺序执行：

# 一键巡检，发现集群整体问题 obdiag check --cluster-name obcluster_prod # 日志分析，定位错误码 obdiag analyze log --cluster-name obcluster_prod --since 2h # 信息收集，打包关键日志和指标 obdiag gather scene --cluster-name obcluster_prod --scene cpu_high

这三条命令的输出会作为 Agent 的观察结果。注意 --since 参数控制时间范围，故障排查时建议从 2h 开始，范围太大输出会很多。gather scene 的 --scene 参数根据故障类型选，cpu_high 是 CPU 高场景，其他场景可以查 obdiag 文档。

RAG 检索脚本负责把采集结果转成查询向量，从向量库检索相似案例。下面是一个基于 sentence-transformers 和 faiss 的简化脚本：

import faiss import numpy as np from sentence_transformers import SentenceTransformer model = SentenceTransformer("BAAI/bge-small-zh-v1.5") index = faiss.read_index("ob_cases.index") cases = load_cases("ob_cases.json") def rag_search(query: str, top_k: int = 3) -> list: query_vec = model.encode([query]) distances, indices = index.search(np.array(query_vec), top_k) results = [] for idx in indices[0]: results.append(cases[idx]) return results if __name__ == "__main__": query = "CPU 使用率过高 错误码 4013" for case in rag_search(query): print(case["title"]) print(case["solution"])

这个脚本需要你先准备好向量库。ob_cases.json 里存历史案例，每条包含 title、symptom、solution 字段。用 bge-small-zh 做 embedding，faiss 做相似度检索。检索结果会作为上下文拼进提示词，和 obdiag 采集结果一起发给模型。

把这三个片段串起来，Agent 的执行流程就是：用户输入问题 → Agent 选择 obdiag 命令 → 执行采集 → 提取关键信息 → 调用 rag_search → 综合生成结论。OpenManus 的 react 模式会自动完成这个循环，你只需要把工具注册好、提示词写清楚。

4. 验证请求与成功结果：一次真实故障的端到端演示

配置写完，得跑一次真实故障才能确认链路是通的。下面用一个模拟的 CPU 使用率异常场景，走一遍完整流程，并给出每一步的预期输出。

第一步，启动 OpenManus Agent。假设你的入口是 app.py，运行：

python app.py --task "诊断 obcluster_prod 集群 CPU 使用率异常"

Agent 启动后会先分析任务，然后决定调用 obdiag 工具。你会在终端看到类似这样的思考过程：

[Thought] 用户报告 CPU 使用率异常，我需要先执行巡检确认集群状态 [Action] obdiag check --cluster-name obcluster_prod [Observation] 巡检完成，发现 2 个节点 CPU 使用率超过 80%，错误码 4013

第二步，Agent 根据巡检结果，继续执行日志分析：

[Thought] 巡检发现错误码 4013，需要分析日志定位具体原因 [Action] obdiag analyze log --cluster-name obcluster_prod --since 2h [Observation] 日志分析完成，发现大量 4013 错误，集中在 SQL 执行阶段

第三步，Agent 提取关键信息，调用 RAG 检索：

[Thought] 错误码 4013 与 SQL 执行相关，检索历史案例 [Action] rag_search("错误码 4013 SQL 执行 CPU 高") [Observation] 检索到 3 条相似案例，其中一条为“4013 错误导致 CPU 飙升的排查”

第四步，Agent 综合采集结果和检索结果，生成诊断结论：

[Conclusion] 问题定位：obcluster_prod 集群 2 个节点 CPU 使用率超过 80%，错误码 4013 集中在 SQL 执行阶段。 可能原因：根据历史案例，4013 错误通常与 SQL 执行计划异常有关，可能导致全表扫描或资源争抢。 建议操作： 1. 检查相关 SQL 的执行计划，确认是否存在全表扫描 2. 查看对应节点的 obstack 输出，定位热点函数 3. 如确认执行计划异常，考虑绑定执行计划或优化 SQL

到这里，一次端到端诊断就完成了。整个过程 Agent 自动执行了巡检、日志分析、RAG 检索、结论生成四个环节，你只需要在最后确认建议操作是否合理。

验证成功的关键指标有三个：obdiag 命令返回了非空输出、RAG 检索返回了相似案例、模型生成的结论里包含了具体的错误码和建议操作。如果这三个都满足，说明链路是通的。

如果你想手动验证模型通道，可以单独调一次模型对话，把 obdiag 输出和 RAG 结果拼成提示词发过去，看返回是否符合预期。模型对话入口在 https://taotoken.net/models ，可以直接在页面上测试。

实际跑的时候，obdiag 采集可能耗时较长，建议给 Agent 设置合理的超时时间。OpenManus 的工具调用默认超时可能不够，可以在工具类里把 timeout 调到 300 秒以上。另外，RAG 检索的 top_k 不要设太大，3 到 5 条比较合适，太多会稀释提示词的焦点。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth

链路跑起来之后，最容易出问题的地方是模型通道和工具调用。下面列出四类真实报错和对应的排查方法，你可以对照自己的日志定位。

第一类，401 未授权。报错信息通常是：

{"error": {"message": "Invalid API key", "type": "invalid_request_error"}}

这说明 API Key 不对或者没传。检查三个地方：配置文件里的 api_key 是否和 TaoToken 控制台里的一致、请求头里的 Authorization 格式是否是 Bearer 加空格加 Key、环境变量是否被正确读取。如果 Key 刚创建，确认没有多余空格。401 还有一种可能是 Base URL 写错了，比如多加了 /v1 或者少了 /api，正确的 Base URL 是 https://taotoken.net/api 。

第二类，local proxy failed。报错信息通常是：

Error: local proxy failed, connection refused

这个报错说明请求没有到达 TaoToken 的接口，而是被本地网络配置拦截了。检查你的 HTTP_PROXY 和 HTTPS_PROXY 环境变量，如果设置了本地代理，先取消掉再试。另外确认你的网络能正常访问 https://taotoken.net/api ，可以用 curl 测一下：

curl -I https://taotoken.net/api

如果返回 200 或 401，说明网络是通的。如果连接被拒绝，检查防火墙和 DNS 配置。

第三类，reading choices 报错。报错信息通常是：

KeyError: 'choices'

或者：

TypeError: 'NoneType' object is not subscriptable

这说明模型返回的 JSON 结构里没有 choices 字段，通常是请求参数不对或者模型名写错了。检查 model 字段是否和 TaoToken 支持的 Model ID 一致，不要自己拼模型名。另外检查 messages 格式是否正确，必须是 role 和 content 的列表。如果返回的是错误信息，先打印完整响应再解析：

resp = requests.post(url, headers=headers, json=payload) print(resp.status_code) print(resp.text) data = resp.json() if "choices" in data: print(data["choices"][0]["message"]["content"]) else: print("返回结构异常:", data)

第四类，OAuth 相关报错。如果你用的是 Claude Code 或者 Codex 这类工具，可能会遇到 OAuth 认证失败：

OAuth token expired or invalid

这类工具通常有自己的认证流程，如果你是通过 TaoToken 接入，需要确认工具侧配置的是 API Key 而不是 OAuth。以 Claude Code 为例，配置文件通常在 ~/.claude/settings.json，需要写全三件套：Base URL、API Key、Model ID。下面是一个可复制的 settings 片段：

{ "api": { "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoTokenKey", "model": "claude-sonnet-4-20250514" } }

Codex 的 auth.json 类似，路径在 ~/.codex/auth.json，同样需要 Base URL、Key、Model ID 三个字段。Cline MCP 的配置在 settings 里，也是这三件套。如果只填了 Key 没填 Base URL，请求会发到默认地址，导致认证失败。

排查顺序建议是：先确认模型通道通不通（用第 2 节的最小请求测），再确认工具调用通不通（单独跑 obdiag 命令），最后确认 RAG 检索通不通（单独跑检索脚本）。分层排查比一上来就看 Agent 日志效率高得多。

6. 把诊断链路跑稳：从单 Agent 到可维护的运维工具

这套链路跑通之后，下一步要考虑的是怎么让它稳定运行。单 Agent 模式在简单诊断场景下够用，但遇到需要多步骤确认、多工具协作的复杂故障，会显得吃力。OpenManus 的 run_flow.py 支持任务流模式，可以定义多个 Agent 分工，比如一个负责采集、一个负责检索、一个负责生成结论。不过多 Agent 的调试成本更高，建议先把单 Agent 跑稳再考虑拆分。

RAG 的知识库维护是另一个关键点。历史案例的质量直接决定检索效果，如果案例里只有标题没有详细解决过程，检索回来也没法用。建议每条案例至少包含症状描述、错误码、排查过程、解决方案四个字段。向量库定期重建，新案例及时入库。embedding 模型可以选 bge 系列，中文场景下效果比较稳。

obdiag 的命令白名单要随着使用场景逐步收紧。一开始可以放开 check、analyze、gather，跑一段时间后根据实际调用情况，把不用的命令去掉。对于生产集群，建议在 Agent 和 obdiag 之间加一层确认机制，关键操作比如 gather 打包大量日志时，先让用户确认再执行。

模型通道方面，TaoToken 的统一 Key 让切换模型变得简单，但不同模型对提示词的敏感度不一样。换模型后建议重新跑一遍验证用例，确认诊断结论的质量没有下降。如果发现某个模型在诊断场景下容易发散，把 temperature 调低，或者在提示词里加更严格的格式约束。

最后，诊断 Agent 的输出建议结构化存储，比如每次诊断生成一条记录，包含时间、集群、问题描述、obdiag 输出摘要、RAG 检索结果、模型结论。这些记录积累起来，本身就是一份高质量的运维知识库，可以反哺 RAG 检索。长期来看，这套链路的价值不只是自动化一次诊断，而是让每次诊断都成为下一次诊断的输入。