OpenClaw + Skills + MCP 联动作战手册（2026-03-13）

目的：在 10 分钟内让新同事同时跑通 OpenClaw、Skills 与 MCP 服务器的协同链路。详细安装命令请参考同目录的《20260302_01_OpenClaw安装与Skills配置教程.md》，本文只给关键检查点与联调顺序。

1. 快速认知

• OpenClaw：本地/云端可部署的 AI 助手框架，负责消息路由与 UI。
• Skills：放在 $CODEX_HOME/skills/<name>/SKILL.md 的能力插件，按触发规则被调用。
• MCP（Model Context Protocol）：通过 MCP 服务器把外部系统（设计、监控、私有 API 等）安全接入助手。

2. 环境前置检查（硬性）

• OS：macOS / Linux / Windows（推荐 WSL2）。
• Node.js ≥ 22，pnpm ≥ 9（确认 node -v、pnpm -v）。
• 可用的模型密钥：OpenAI / Anthropic / DeepSeek 任选其一，先放到 .env.local 或系统环境变量中，不要写进仓库。

3. 安装 / 更新路径

1. 首次安装：直接按《20260302_01_OpenClaw安装与Skills配置教程.md》执行一键脚本；安装完跑一次 openclaw doctor（或等价健康检查命令）确保依赖齐全。
2. 已有环境：拉代码更新后重跑依赖安装；如升级 Node 版本，记得 pnpm install --frozen-lockfile 以避免二进制缓存失配。
3. 服务形态：建议前期用本地前台模式，联调完成后再改为 systemd / pm2 常驻。

4. Skills 管理清单

• 目录规范：每个技能一个文件夹，必须包含 SKILL.md 描述触发条件、输入输出与安全注意事项；如有脚本，放 scripts/；引用资料放 references/。
• 命名原则：用领域+用途，例如 figma-export、openai-docs；避免空格与大写。
• 测试办法：
  • 干跑（Dry-run）：阅读 SKILL.md 中的“触发规则”并在聊天中刻意触发，确认上下文加载正常。
  • 资源引用：若技能依赖外部文件/数据库，先在本地填好示例配置，避免线上缺参。
• 版本控制：SKILL.md 与脚本同提交；禁止把密钥、cookie、token 写入仓库，统一走环境变量。

5. MCP 接入步骤

1. 确定服务信息：MCP 服务器地址、认证方式（API Key / Bearer / Basic）、可调用的资源或函数名。
2. 配置客户端：按服务器 README 填入客户端配置（通常是 mcp.json 或项目配置文件中的 mcp.servers[] 列表），逐项填写：name、url、auth、超时。
3. 健康检查：用 curl / httpie 对 MCP 的 /health 或 /version 端点做一次探活，确认证书与跨域没问题。
4. 限流与重试：为高延迟接口显式设置超时时间与重试（如 3 次指数退避），避免阻塞对话线程。
5. 安全隔离：对有副作用的接口（写库、发消息）默认关闭自动调用，只在明确确认后手动触发；必要时在技能层增加白名单。

6. 联调顺序（建议流水）

1. 运行 OpenClaw，打开前端控制台确认无红色报错。
2. 触发一个现有技能（如 $openai-docs 或 Figma）验证技能加载成功。
3. 在配置中启用一个 MCP 服务器，调用其最简单的只读方法（如 ping/list）。
4. 将技能与 MCP 组合：让技能调用 MCP 返回的数据（例如技能读取设计稿，再把结果交给模型总结）。
5. 记录耗时与失败率，超过 3 秒或错误>5% 需要调优（缓存、并行、缩减上下文）。

7. 常见故障速查

• 模型 401/403：检查环境变量名是否匹配所选模型供应商，地区网络是否可直连。
• MCP 连接超时：确认服务器端口是否暴露、TLS 证书是否合法；临时可在本地 hosts 绑定测试。
• 技能未触发：查看 SKILL.md 的触发词是否与对话匹配；在对话中明确给出技能名或关键触发句。
• 前端报 CORS：MCP 服务器缺少跨域响应头，需在服务端加 Access-Control-Allow-Origin 等。

8. 后续维护

• 每次升级 Node / pnpm 后，先跑健康检查再上线。
• 新增技能或 MCP 时，同步在团队 wiki/本仓库添加记录，避免“暗技能”。
• 建议每月做一次依赖安全扫描与密钥轮换。