2026_OPENCLAW
MCP_SKILLS_
GATEWAY_
TOKEN_RUNBOOK.

// 已能对话跑通 OpenClaw,却在接 MCP 或自定义 Skill 时遇到「工具列表突然爆炸」「改完 SKILL.md 不生效」「Gateway 重启后还是旧快照」?本文按目录优先级、Gateway 行为、OAuth/PATH、MCP schema 占用上下文等维度给出对照表与 5 步验证,并附远程 Mac 托管检查项。延伸阅读:《onboard 与 Gateway 常驻》《Docker 生产部署》《常见报错排查》。

开发与自动化工具链

1. 痛点拆解:MCP 与 Skills 不是「多两个文件」

(1)加载顺序不透明:工作区 /skills、用户目录、打包内置 Skills 优先级若不清楚,会出现「我明明改了文件,Agent 却读旧版」。(2)Gateway 与内存快照:部分版本在重启前依赖内存中的技能版本计数;若只改磁盘不触发完整重载,对话里仍像没更新。(3)MCP 工具 schema 体积:多个 MCP 服务器若一次性把大 schema 注入上下文,16k~32k 窗口会被「说明书」吃掉,模型反而更容易幻觉或拒答。(4)守护进程环境:launchd/system 服务下的 PATH 不含 nvm/fnm,导致「终端里能跑、Gateway 里找不到命令」。在远程 Mac 上这些问题会被 7×24 放大,因为你不像本机那样随时开终端肉眼对比环境变量。

2. Skills 目录优先级:一张对照表

不同发行渠道路径表述可能演进,下列层级表达的是常见优先级直觉:越靠上越应覆盖下方。以你当前安装的文档为准核对绝对路径。

层级(高→低)典型用途排查提示
工作区 /skills 或项目内 skills项目专属流程、团队共享确认 Gateway 的工作目录是否指向你以为的那个 workspace
用户级 skills 目录个人偏好与实验YAML frontmatter 缩进错误会导致整文件被跳过
内置/包内 Skills官方默认能力升级版本后行为变化先查 changelog

3. MCP 接入:最小闭环与 Token 纪律

建议先接一个 MCP 服务验证端到端,再逐步加服务器。每增加一个连接点,评估其工具列表序列化后的 token 粗估值(可用离线脚本或日志里的 schema 长度做相对对比)。若发现单轮 system+tools 已逼近窗口上限,优先:收敛工具面(按场景拆多个 profile)、延迟加载(仅在子代理会话挂工具)、或换更大上下文模型——三者往往要组合使用,而不是只堆 MCP 数量。

4. 可执行的 5 步验证清单

第一步:在 Gateway 日志中确认当前 workspace 根路径与 skills 扫描范围。第二步:对单个 Skill 做「改一句可见字符串→重启 Gateway→对话里能否引用」的烟测。第三步:临时只启用一个 MCP,记录 tools 段 token 变化,再逐个加回。第四步:用 launchctl print 或等价方式核对守护进程环境变量与 PATH。第五步:对 OAuth 类工具做「过期后是否静默失败」的用例,避免生产里只看到「工具不存在」。

# 示例:本机先看 Gateway 监听与健康(按你的安装调整端口/命令) curl -sS http://127.0.0.1:18789/health 2>/dev/null || echo "adjust-endpoint"

5. Gateway 重启后「仍像旧版」:决策矩阵

现象更可能原因动作
改 SKILL.md 无变化读的是另一优先级目录打印 skills 搜索路径;用唯一字符串做 grep 验证
重启后工具数量不对MCP 连接失败被静默跳过开 debug 日志;逐个 MCP 单独启用
偶发 Tool not foundOAuth/token 过期强制重授权;检查刷新任务是否跑在 daemon 环境
上下文莫名其妙满多个大 schema 叠加减 MCP;拆子会话;换模型窗口

可引用参数(实践向):

  • 16k 级上下文模型上,未过滤的 MCP 工具描述合计吃掉 10k+ token 的情况并不罕见,应提前在架构层设预算。
  • 远程托管时,建议为 Gateway 进程单独写最小 PATH plist,显式包含 node/python 绝对路径,避免依赖 login shell。
  • 每新增一个对外通道(IM/邮件/Webhook),工具暴露面应复审一次,避免「能聊天的人」意外获得高危 MCP 能力。

6. 深度分析:为什么「工具治理」正在成为 Agent 运维核心

2026 年 MCP 把「接外部系统」从一次性脚本变成了可组合平台能力,副作用是上下文与权限面同时膨胀。与传统微服务不同,LLM 每轮都可能重新调度工具;若 schema 与策略不同步,轻则浪费 token,重则越权调用。对 macOS 托管场景而言,Apple Silicon 机器适合长期低噪运行 Gateway,但统一内存同样会被多 MCP、多通道会话放大;这与单纯「多开聊天窗口」不同,因为工具定义常驻在 system 侧。把重通道、重 MCP 的生产配置放在角色隔离的远程 Mac,把个人笔记本留给开发与试错,是越来越多团队的折中:不是否定本机 OpenClaw,而是把变更频率爆炸半径分开。

若你已在目录优先级与 MCP 预算上做完基线,仍需要在稳定网络、固定上行与免打扰运维上投入大量时间,继续堆在同一台日常用机上未必划算。将 OpenClaw Gateway 与 MCP 侧车部署在 MACGPU 的远程 Mac 节点,可以在相同 macOS 生态下获得更可预测的进程环境与带宽;按使用时长计费也便于先做小流量灰度,再决定是否长期固定资源。这与单纯「多装几个 MCP」相比,更像是给 Agent 运维补上一层托管 tier。