1. 为什么你的 OpenClaw 装完还是“四肢瘫痪”很多人把 OpenClaw 部署起来接上模型聊了两句然后陷入沉默它能回答问题但不会帮你干活。原因不复杂——你装的是一个“大脑”没给它接上“四肢”。OpenClaw Skills 就是这套四肢系统它决定了 Agent 能不能真的去读文件、调接口、跑脚本、发请求。先把三个最容易混淆的概念摆清楚不然后面写配置会一直拧巴。Prompt 是你临时说的一句话比如“帮我把这个目录整理一下”。它是一次性的说完就散。Skill 是你写好的标准操作手册注册一次以后 Agent 每次遇到匹配的任务都能翻出来用。Agent 则是那个会判断“现在该不该翻手册、翻哪一本”的调度者。三者关系可以这样理解Agent 是大脑Skill 是四肢和工具包MCP 是神经接口——它让 Skill 能连到外部世界。我见过太多人把 Skill 当成 Prompt 模板来写结果 Agent 永远触发不了。Skill 的本质是“可被调度的能力单元”它必须声明自己叫什么、需要什么参数、有什么权限Agent 才能在对的时机把它拉起来。这篇内容聚焦一条完整链路先拆 Skill 与 MCP、Agent 的协作关系再给一份可复制的 Skill 配置接着把 endpoint 改到 TaoToken 统一通道做连通性验证最后把常见报错一个个排掉。你跟着做能在本地复现从“大脑”到“四肢”的调用闭环。适合谁看已经跑起 OpenClaw、想给它加自定义能力的人正在纠结 Skill 和 MCP 怎么分工的人以及把模型调用统一到一个 Key 通道、不想每个 Skill 各配一套鉴权的人。2. OpenClaw Skills 与 MCP、Agent 的协作关系拆解2.1 Skill 在 Agent 架构里到底站哪个位置把一次用户请求的流向画出来就清楚了。用户说一句话先进网关层做路由和排队再到智能体层做意图解析和任务规划然后交给 Skill 调度器调度器根据 Skill 声明的 action 和参数去拉起对应的执行单元。关键点在于Skill 不参与意图解析。Agent 决定“要不要调用某个 Skill、传什么参数”Skill 只负责“拿到参数后把活干完”。这种思考和执行分离的设计是 OpenClaw 能不断加能力而不把主流程搞乱的根本原因。所以写 Skill 时你不需要关心模型怎么理解用户你只需要把输入输出契约定死给我什么参数我还你什么结构的结果。2.2 Skill 和 MCP 的分工一个管“做什么”一个管“怎么连”这是最容易混的地方。Skill 描述的是能力本身——比如“统计目录文件类型并生成报表”。MCP 描述的是连接方式——比如“通过标准协议去调用一个外部工具服务”。打个比方Skill 是菜谱MCP 是厨房到仓库的传送带。菜谱说“需要 200 克面粉”传送带负责把面粉从仓库送到灶台。你可以把面粉直接堆在灶台边Skill 里硬编码 API 调用也可以走传送带Skill 通过 MCP Client 连到 MCP Server 再连外部工具。硬编码能跑但一旦接口变了、鉴权换了、要复用到别的平台你就得改 Skill 本体。走 MCP 的话Skill 只认协议底层换实现不影响上层。所以进阶做法是Skill 负责编排和参数校验MCP 负责连接和鉴权。2.3 三种 Skill 设计模式对号入座工具型调一次外部 API 就完事比如搜索、天气、汇率。特点是单次、无状态。流程型多步骤、有条件判断比如“先读目录、再分类统计、再生成报表、再写文件”。这类 Skill 要注意每一步的失败处理不能中间挂了还返回成功。记忆型跨会话保存信息比如个人助理记住你的偏好。这类要特别小心持久化文件的权限和内容后面排障章节会讲。你写之前先想清楚自己属于哪类配置结构和错误处理策略完全不同。2.4 渐进式披露为什么 Skill 不能把所有内容一次性塞给模型高质量 Skill 遵循三层加载。第一层是 YAML 前置信息每次都被加载只写“这个技能干什么、什么时候触发”。第二层是 SKILL.md 正文任务匹配时才加载写完整工作流。第三层是链接文件按需加载放参考文档、脚本、模板。这么设计是为了省 Token也为了让 Agent 的上下文不被无关内容污染。你如果把所有说明都堆在第一层Agent 每次对话都要背一遍既慢又贵。3. 可复制的 OpenClaw Skill 配置与 TaoToken 接入片段3.1 环境准备与目录结构先确认基础环境。Node.js 建议 v22 及以上OpenClaw 已部署编辑器随意。node -v npm -v mkdir -p openclaw-custom-skills/file-report-skill cd openclaw-custom-skills/file-report-skill npm init -y一个 Skill 的最小结构是三件套plugin.json声明元信息和参数index.js写执行逻辑package.json管依赖。3.2 plugin.jsonSkill 的身份证这份配置直接复制注意action是 Agent 调用的唯一标识permissions遵循最小权限。{ name: file-report-skill, version: 1.0.0, description: 统计指定目录的文件类型和数量生成 Markdown 报表, author: your-name, skills: [ { action: generate-file-report, description: 统计目录文件并生成 Markdown 报表, parameters: [ { name: dirPath, type: string, required: true, description: 要统计的目录绝对路径 }, { name: outputPath, type: string, required: false, default: ./file-report.md, description: 报表保存路径 } ], permissions: [file.read, file.write] } ] }3.3 index.js核心执行逻辑const fs require(fs); const path require(path); function countFilesByType(dirPath) { const stats {}; if (!fs.existsSync(dirPath)) { throw new Error(目录不存在${dirPath}); } const files fs.readdirSync(dirPath, { withFileTypes: true }); for (const file of files) { if (file.isDirectory()) continue; const ext path.extname(file.name).toLowerCase() || 无扩展名; stats[ext] (stats[ext] || 0) 1; } return stats; } function generateMarkdownReport(stats, dirPath) { const now new Date().toLocaleString(); let md # 文件统计报表\n; md **统计目录**${dirPath}\n; md **统计时间**${now}\n\n; md | 文件类型 | 数量 |\n|----------|------|\n; Object.entries(stats).forEach(([ext, count]) { md | ${ext} | ${count} |\n; }); const total Object.values(stats).reduce((s, v) s v, 0); md \n**总文件数**${total}\n; return md; } module.exports async function run(action, params) { try { if (action ! generate-file-report) { return { success: false, message: 不支持的动作${action}, data: null }; } const { dirPath, outputPath ./file-report.md } params; const fileStats countFilesByType(dirPath); const markdown generateMarkdownReport(fileStats, dirPath); const fullOutputPath path.isAbsolute(outputPath) ? outputPath : path.join(process.cwd(), outputPath); fs.writeFileSync(fullOutputPath, markdown, utf8); return { success: true, message: 文件统计报表已生成, data: { stats: fileStats, reportPath: fullOutputPath, totalFiles: Object.values(fileStats).reduce((s, v) s v, 0) } }; } catch (error) { return { success: false, message: 执行失败${error.message}, data: null }; } };三个要点输出结构固定成功失败都返回同一套字段异常全捕获别让 Agent 崩无状态不存跨请求数据。3.4 把模型通道切到 TaoTokenSkill 本身不直接调模型但 Agent 的推理和 Skill 里可能触发的模型调用都需要一个统一的 endpoint。把 Base URL 指向 TaoToken 的 API 通道Key 用统一签发的Model ID 按你实际用的填。如果你用的是 Claude Code 类配置settings.json里这样写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你用的是 Codex 类配置auth.json里对应字段{ base_url: https://taotoken.net/api, api_key: sk-你的TaoTokenKey, model: gpt-4o }三件套缺一不可Base URL、Key、Model ID。只填 Key 不填 Base URL请求会打到默认地址只填 Base URL 不填 Model ID部分客户端会报模型不存在。Key 在控制台的 API Keys 页面签发接入细节看官方文档。地址统一用https://taotoken.net/api不要带多余路径。3.5 注册 Skill 并重启网关ln -s $(pwd)/file-report-skill ~/.openclaw/skills/ openclaw gateway restart openclaw logs --skill file-report-skill日志里能看到 Skill 被加载的记录说明注册成功。4. 验证请求从触发到拿到成功结果4.1 先做一次纯模型连通性验证在正式跑 Skill 前先确认模型通道是通的。用 curl 打一次对话接口curl -s https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的TaoTokenKey \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 只回复两个字通了}] }返回里能看到content数组带文本说明 Base URL、Key、Model ID 三件套都对。这一步不通后面 Skill 一定跑不起来别跳过。4.2 触发 Skill在 OpenClaw 对话里说帮我统计 /home/user/documents 目录下的文件类型生成报表保存到 /tmp/report.mdAgent 会解析意图匹配到generate-file-report这个 action把dirPath和outputPath作为参数传进去。Skill 执行完返回结构化结果Agent 再把结果转成自然语言回给你。4.3 检查产物cat /tmp/report.md你应该看到一张 Markdown 表格列出每种扩展名的数量最后一行是总文件数。如果文件生成了但内容是空的多半是dirPath传了个空目录或者权限不够读不到文件。4.4 验证 MCP 链路如果你走了 MCP如果你的 Skill 是通过 MCP Client 连外部工具的验证顺序是先单独测 MCP Server 能不能起来再测 Client 能不能连上最后才测 Skill 调用。任何一层断了报错都会往上冒但根因在最底下那层。# 假设你的 MCP Server 是本地 stdio 模式 node mcp-server.js --port 0Server 起来后在 Skill 里通过 MCP Client 发一次握手确认协议版本和工具列表能拿到。5. 本篇常见错误排查对照5.1 401 Unauthorized最常见。原因通常是 Key 没填、填错、或者 Base URL 和 Key 不匹配。检查settings.json或auth.json里的ANTHROPIC_API_KEY/api_key字段确认没有多余空格。如果 Key 是从控制台复制的注意别把前后引号也复制进去。还有一种情况你用了 TaoToken 的 Key但 Base URL 还指向别处两边对不上自然 401。统一改成https://taotoken.net/api。5.2 local proxy failed这个报错通常出现在你本地起了代理层、但代理层没起来或者端口不对的时候。检查你的客户端配置里有没有指向127.0.0.1:某端口的 proxy 设置。如果你不需要本地代理直接删掉相关配置让请求直连 Base URL。5.3 reading choices 报错这是 OpenAI 兼容格式的响应解析错误。典型原因是接口返回的不是标准 chat completion 结构但客户端按那个结构去读choices字段。排查两步先用 curl 看原始返回长什么样再确认你用的 Model ID 和接口路径匹配。Anthropic 格式的返回是content数组不是choices别混用。5.4 OAuth 相关报错如果你用的是需要 OAuth 的客户端报错往往出在 token 过期或回调地址不对。检查 token 刷新逻辑确认回调地址和你在控制台登记的一致。用统一 Key 通道的好处就是绕开 OAuth 这套直接 Key 鉴权少一层出错点。5.5 Skill 加载了但触发不了日志里显示 Skill 已加载但对话时 Agent 不调用它。三个检查点action名字和 Agent 期望的是否一致parameters里required的参数用户有没有提供description写得够不够清楚Agent 靠它判断什么时候该用这个 Skill。描述太模糊Agent 就不知道什么时候该拉它。5.6 权限被拒plugin.json里声明了file.read和file.write但实际运行时被系统拦了。检查 OpenClaw 的权限策略有没有覆盖这个 Skill以及运行用户对目标目录有没有读写权限。最小权限原则不是让你少声明而是声明了就要确保运行环境真的给得了。6. 把能力固化下来从一次调用到长期可用Skill 写完之后真正决定它好不好用的是两件事错误处理够不够细以及通道够不够稳。错误处理这块我自己的习惯是每个可能失败的点都单独包一层返回的message里带上足够定位问题的信息但不要把堆栈直接吐给 Agent那会污染上下文。data字段保持结构稳定Agent 解析起来不会因为某次失败就崩。通道这块把模型调用统一到 TaoToken 的 Key/API 通道之后你不需要在每个 Skill 里各配一套鉴权。Base URL 一个、Key 一个、Model ID 按需选三件套定死Skill 只管业务逻辑。这样你加第十个 Skill 的时候接入成本几乎为零。长期跑的话建议把 Coding Plan 用起来适合持续编码和 Agent 类任务不用每次单独算额度。模型对话页面可以随时验证某个 Model ID 通不通接入文档里有完整的参数说明。最后一步把你重复做的每一件小事都试着固化成 Skill。今天统计文件明天整理日志后天自动发报告。当这些 Skill 串起来Agent 才真的从“会聊天”变成“能干活”。