1. 从 SKILL.md 到模型响应：Tool call 链路到底断在哪
Agent 调用 Skills 的过程，本质上是把「说明书」塞进 system prompt，让 LLM 决定读哪份说明书、执行哪条命令，再把执行结果喂回去继续推理。这条链路里，LLM 只负责「说」要调用什么工具，真正干活的是 Agent 和它背后的 CLI。问题就出在这条链路的每一跳都可能断：请求发不出去、鉴权过不了、模型返回格式对不上、工具结果追加错位。
我最近在调一个 wiki 自动化 Skill，SKILL.md 里声明了citadel这个工具，frontmatter 长这样：
--- name: citadel description: "wiki官方Skill：支持读取文档信息和内容、获取模板内容、读取文档的目录..." metadata: skillhub.version: "V36" skillhub.high_sensitive: "true" ---Agent 启动新会话时会扫描~/.openclaw/skills/*/SKILL.md、/app/skills/*/SKILL.md、工作区~/.openclaw/workspace-xxx/skills/*/SKILL.md这些路径，把所有 Skill 的 name + description 收集起来，注入到 system prompt 的<available_skills>块里。用户输入一句话，LLM 看到 wiki 链接，匹配到 citadel，决定先读 SKILL.md，返回一个read的 tool_call。Agent 在本地执行读取，把文件内容作为role: tool的消息追加到 messages，再发给 LLM。LLM 读完说明书，知道要用oa-skills citadel get-page --contentId 1234567890，返回exec的 tool_call。Agent 执行 shell 命令，CLI 去调 wiki API，拿到页面内容 JSON，再追加回 messages。LLM 最终生成回复。
这条链路里，任何一跳出问题都会表现为「Agent 卡住」「工具没反应」「报错但不知道哪层报的」。常见断点集中在几个地方：Base URL 配错导致 401、本地代理配置残留导致 local proxy failed、并发或限流触发 429、模型返回的 tool_calls 格式和 Agent 预期不一致导致 reading choices 报错、OAuth 鉴权过期导致工具执行层拿不到 token。
这篇排查清单就是按这条链路的顺序，从配置到验证到排错，把每一跳都拆开看。适合正在调试 Agent 工具链的开发者，尤其是用 Claude Code、Cline、Codex 这类工具接入自定义 Skill 时遇到报错的场景。核心检索词就三个：Agent、Skills、Tool call，加上 LLM 底层交互这条线，把请求从 SKILL.md 声明到模型响应的完整路径理清楚。
2. TaoToken 前置：Base URL、Key 与模型 ID 三件套怎么配
在排查链路之前，先把 LLM 这一端的接入配置固定下来。Agent 调 Skills 时，LLM 请求最终要发到某个兼容 OpenAI 或 Anthropic 协议的端点。TaoToken 提供的就是这个端点，Base URL 和 API Key 是两件必须配对的东西，模型 ID 决定 LLM 用哪个模型做推理。
先拿 Key。访问 API Keys 管理页：
https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api_keys在控制台里创建一个新 Key，复制出来。注意 Key 只在创建时完整显示一次，后面只能看到前缀。如果你用的是 Claude Code 这类工具，Key 通常写在环境变量或配置文件里。
Base URL 分两种协议，看你的 Agent 框架用哪种：
| 协议 | Base URL | 适用场景 |
|---|---|---|
| OpenAI 兼容 | https://taotoken.net/api | Cline、Codex、大多数 Agent 框架 |
| Anthropic 兼容 | https://taotoken.net/api | Claude Code、Anthropic SDK |
注意 API 端点不加 UTM 参数，直接写https://taotoken.net/api。模型 ID 根据你实际用的模型填，比如claude-sonnet-4-20250514或gpt-4o这类，具体以控制台模型列表为准。
如果你用 Claude Code，配置走~/.claude/settings.json或环境变量。用 Cline 的话，在 VS Code 设置里填 Base URL 和 Key。用 Codex 的话，配置在~/.codex/auth.json和~/.codex/config.toml。这三件套——Base URL、Key、Model ID——必须同时正确，缺一个都会在 Tool call 链路的第一跳就断掉。
我试过把 Base URL 写成带路径的https://taotoken.net/api/v1，结果 401，因为端点本身已经包含了版本路径。正确的写法就是https://taotoken.net/api，后面由 SDK 自己拼/v1/chat/completions或/v1/messages。
配置文档在这里，里面有各工具的详细接入步骤：
https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc配好之后，先别急着跑 Agent，用一条最简单的 curl 验证 LLM 端点通不通。这一步过了，再往下排查 Tool call 链路才有意义。
3. 可复制配置：settings.json、auth.json 与 MCP 三件套
这一节给可直接复制的配置片段。路径和原文一致，你按自己的工具选对应的那份。
3.1 Claude Code settings.json
Claude Code 的配置在~/.claude/settings.json。如果你要用 TaoToken 作为 LLM 端点，同时保留 Skill 的 Tool call 能力，配置如下：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" }, "permissions": { "allow": [ "Read", "Exec" ] } }这里ANTHROPIC_BASE_URL指向 TaoToken 的 API 端点，ANTHROPIC_API_KEY填你创建的 Key，ANTHROPIC_MODEL填模型 ID。三件套齐了，Claude Code 启动时就会用这个端点做推理。
如果你用 Claude Code 的 coding plan 模式，配置入口在：
https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding_plan3.2 Codex auth.json 与 config.toml
Codex 的鉴权在~/.codex/auth.json：
{ "OPENAI_API_KEY": "sk-你的Key" }模型和端点配置在~/.codex/config.toml：
model = "gpt-4o" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "OPENAI_API_KEY"base_url指向 TaoToken，env_key告诉 Codex 从环境变量读 Key。这样 Codex 的 Tool call 请求就会走 TaoToken 端点。
3.3 Cline MCP 配置
Cline 在 VS Code 里配置 MCP Server 时，如果 Skill 依赖 MCP 协议暴露工具，配置片段如下：
{ "mcpServers": { "citadel": { "command": "oa-skills", "args": ["citadel", "mcp"], "env": { "TAOTOKEN_BASE_URL": "https://taotoken.net/api", "TAOTOKEN_API_KEY": "sk-你的Key" } } } }这里command是 Skill 对应的 CLI，args是启动 MCP 模式的参数，env里带上 Base URL 和 Key。Cline 启动时会拉起这个 MCP Server，Skill 的工具就注册到 Agent 的工具列表里了。
三件套的对应关系再强调一遍：Base URL 是https://taotoken.net/api，Key 是控制台创建的sk-开头字符串，Model ID 是具体模型名。任何一份配置里这三个值都要对得上，否则 Tool call 链路在 LLM 请求这一跳就会返回 401。
4. 验证请求：从 curl 到 Tool call 打通的检查动作
配置写好了，接下来逐步验证。不要一上来就跑完整 Agent，按链路顺序一层层测。
4.1 第一层：LLM 端点连通性
先用 curl 直接打 TaoToken 的 chat completions 端点，确认 Key 和 Base URL 没问题：
curl -s https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的Key" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [ {"role": "user", "content": "回复 OK 两个字母"} ] }'如果返回里有choices数组，且message.content是OK，说明 LLM 端点通了。如果返回 401，检查 Key 是否复制完整、Base URL 是否写成了https://taotoken.net/api。如果返回 429，说明触发了限流，等几秒重试或检查并发数。
4.2 第二层：带 tools 参数的请求
LLM 端点通了之后，加上tools参数，模拟 Agent 发给 LLM 的请求格式：
curl -s https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的Key" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [ {"role": "system", "content": "When a skill is relevant, read SKILL.md FIRST."}, {"role": "user", "content": "帮我读一下这个wiki文档：https://wiki.com/collabpage/1234567890"} ], "tools": [ { "type": "function", "function": { "name": "read", "description": "读取本地文件内容", "parameters": { "type": "object", "properties": { "path": {"type": "string", "description": "文件路径"} }, "required": ["path"] } } } ] }'关键看返回的choices[0].message.tool_calls是否存在。如果模型决定调用read工具，这里会返回类似：
{ "tool_calls": [ { "id": "call_xxx", "type": "function", "function": { "name": "read", "arguments": "{\"path\": \"~/.openclaw/skills/citadel/SKILL.md\"}" } } ] }如果tool_calls为空，说明模型没决定调工具，可能是 system prompt 里的 Skill 描述不够明确，或者模型不支持 function calling。如果返回reading choices相关报错，说明模型返回的格式和 Agent 解析逻辑对不上，检查 Agent 用的 SDK 版本是否匹配。
4.3 第三层：完整 Tool call 循环
前两层都过了，跑完整 Agent。观察日志里这几跳：
第一跳，Agent 构造请求，system prompt 里包含<available_skills>块，tools 列表里有read和exec。第二跳，LLM 返回read的 tool_call，Agent 执行本地读取，把 SKILL.md 内容作为role: tool消息追加。第三跳，LLM 返回exec的 tool_call，命令是oa-skills citadel get-page --contentId 1234567890。第四跳，Agent 执行 shell 命令，CLI 调 wiki API，拿到 JSON 结果追加回 messages。第五跳，LLM 生成最终回复。
每一跳的日志里，检查messages数组的长度是否在增长，tool_calls的id是否和后续role: tool消息的tool_call_id对应。如果tool_call_id对不上，Agent 会报错或静默丢弃结果，表现为「工具执行了但模型没反应」。
4.4 第四层：Skill 执行层鉴权
CLI 执行时，oa-skills citadel get-page需要 SSO token 或 API token。如果这一层鉴权过期，会返回 401 或 OAuth 相关报错。检查 CLI 的配置文件，确认 token 有效期。有些 Skill 的 token 存在~/.oa-skills/config.json里，过期后需要重新登录。
验证 Tool call 是否打通，最直接的标志是：Agent 最终回复里包含了 wiki 文档的实际内容，比如标题、作者、正文片段。如果回复是「我无法访问该链接」或「工具执行失败」，说明链路在某一跳断了，按上面的层次往回查。
5. 常见报错排查：401、local proxy failed、429、reading choices、OAuth
这一节对照真实报错，给出排查路径。
5.1 401 Unauthorized
最常见。表现是 LLM 请求直接返回 401，Agent 日志里显示authentication failed或invalid api key。
排查顺序：先确认 Key 是否复制完整，有没有多余空格。再确认 Base URL 是否写成了https://taotoken.net/api，不要带/v1后缀。然后确认请求头里的Authorization格式，OpenAI 兼容协议是Bearer sk-xxx，Anthropic 协议是x-api-key: sk-xxx。如果用的是 Claude Code，检查ANTHROPIC_API_KEY环境变量是否被其他配置覆盖。
还有一种情况是 Key 被禁用或额度耗尽，控制台里能看到 Key 的状态。如果 Key 正常但依然 401，检查是不是请求发到了错误的端点，比如把 Anthropic 协议的请求发到了 OpenAI 兼容路径。
5.2 local proxy failed
这个报错通常出现在 Agent 框架尝试走本地代理时。表现是local proxy failed或connection refused，Agent 无法连接到 LLM 端点。
排查：检查环境变量里有没有HTTP_PROXY、HTTPS_PROXY、ALL_PROXY这类设置。如果有，且代理服务没启动，请求就会失败。把这类环境变量清掉，或者确认代理服务正常运行。另外检查 Agent 配置文件里有没有写死proxy字段，比如 Cline 的设置里可能有http.proxy项，清空即可。
还有一种情况是本地端口被占用，Agent 启动时想监听某个端口做回调但失败了。换一个端口或重启 Agent 进程。
5.3 429 Too Many Requests
触发限流。表现是 LLM 请求返回 429，Agent 日志里显示rate limit exceeded。
排查：降低并发请求数。Agent 调 Skills 时，如果一轮里同时发多个 tool_call，可能瞬间打满限流。可以在 Agent 配置里限制并发，或者加请求间隔。另外检查是不是短时间内重复发了相同请求，比如 Agent 陷入循环，反复读同一个 SKILL.md。
如果是 Coding Plan 用户，检查套餐的速率限制。控制台里能看到当前用量和限额。
5.4 reading choices 报错
这个报错通常出现在 Agent 解析 LLM 响应时。表现是error reading choices或cannot read property 'choices' of undefined。
原因一般是 LLM 返回的 JSON 结构和 Agent 预期的不一致。比如 Agent 期望choices[0].message.tool_calls，但模型返回的是choices[0].message.content里嵌了工具调用文本。检查模型是否支持 function calling，以及 Agent 用的 SDK 是否把tools参数正确序列化了。
还有一种情况是流式响应（stream）模式下，Agent 没有正确处理 SSE 分块，导致解析到不完整的 JSON。关掉 stream 模式试试，或者升级 Agent 框架版本。
5.5 OAuth 相关报错
Skill 执行层需要 OAuth token 时，如果 token 过期或未授权，会返回OAuth token expired或invalid_grant。
排查：找到 Skill 对应的 CLI 配置文件，通常在~/.oa-skills/或~/.config/下。检查 token 的过期时间，重新执行登录命令。有些 Skill 的 OAuth 流程需要浏览器回调，确认回调地址和端口没有被防火墙拦截。
如果 Skill 的 frontmatter 里标了high_sensitive: "true"，说明这个 Skill 涉及敏感操作，鉴权会更严格。确认当前账号有对应权限。
5.6 Tool call 链路断点速查表
| 报错 | 断点位置 | 排查动作 |
|---|---|---|
| 401 | LLM 请求层 | 检查 Key、Base URL、Authorization 头 |
| local proxy failed | 网络层 | 清代理环境变量，检查端口占用 |
| 429 | LLM 请求层 | 降并发，检查套餐限额 |
| reading choices | Agent 解析层 | 检查模型 function calling 支持，关 stream |
| OAuth | Skill 执行层 | 重新登录，检查 token 过期时间 |
| tool_call_id 不匹配 | Agent 调度层 | 检查 messages 追加逻辑 |
排查时按链路顺序从下往上查：先确认 LLM 端点通，再确认 tools 参数生效，再确认 Agent 解析正确，最后确认 Skill 执行层鉴权。每一层都有对应的验证动作，不要跳步。
6. 把 Tool call 链路固定下来：模型对话验证与长期编码接入
链路排查完之后，建议做两件事：一是用模型对话快速验证当前配置下 Tool call 是否稳定，二是把配置固化到长期编码环境里，避免每次重启 Agent 都要重新调。
验证模型对话的入口：
https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=model_chat在对话界面里，你可以手动构造带 tools 的请求，观察模型返回的 tool_calls 结构。这比在 Agent 里跑完整流程更快，适合快速确认模型端是否正常。
如果你要长期跑 Agent 编码任务，用 Coding Plan 接入：
https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding_planCoding Plan 的配置和前面 settings.json 里的一致，Base URL 用https://taotoken.net/api，Key 用控制台创建的，Model ID 按需选。把这三件套写进配置文件后，Agent 每次启动都会自动加载，不用手动改。
最后给一个实用技巧：在 Agent 的 system prompt 里加一句「每次 tool_call 后，检查 tool_call_id 是否与上一条 assistant 消息对应」。这能帮你在日志里快速定位链路断点。另外，把 SKILL.md 的 frontmatter 里的description写清楚，模型匹配 Skill 的准确率会高很多，减少无效的 tool_call 轮次。
链路调通之后，Agent 调 Skills 的完整路径就是：system prompt 注入 Skill 摘要 → LLM 决策读 SKILL.md → Agent 执行 read → LLM 决策执行 CLI → Agent 执行 exec → CLI 调 API → 结果追加 → LLM 生成回复。每一跳都有日志可查，每一跳都有对应的验证动作。把这套排查清单存下来，下次遇到报错直接按表查。
