谁会遇到问题：已经能启动 OpenClaw Gateway，但要把 MCP（Model Context Protocol） 工具挂进会话、或从 ClawHub 拉 Skills，却遇到「工具列表里看不到」「调用即超时」「重启后 Skill 消失」。本文结论：把安装与网络留给《三平台安装》与《Docker 生产 Runbook》，把卷与权限留给《数据卷与 Skills 权限篇》；本篇只解决声明 → 进程可见 → Gateway 识别 → 通道/模型调用链上的分诊。结构：六类痛点、两张症状表、配置示意、六步 Runbook、三条验证口径、收束与 CTA。
MCP 的本质是 Gateway 与子进程或远端端点之间的 JSON-RPC 会话：注册表项存在不等于子进程能启动，子进程能启动也不等于工具 schema 已成功回传。下列六条是 2026 年社区排障里最高频的误判。
~/.zshrc 里的 PATH 或 API Key，导致 MCP 命令行找不到二进制或鉴权失败。AGENTS.md / bootstrap 注入叠床架屋：同一能力既在 MCP 又在 Skills 文本里重复描述，模型会在两轮工具协议间来回试探，表现为上下文暴涨与重复调用。《Skills 与 memory_search 调参篇》给出了边界拆分方法。建议把 openclaw doctor 与 Gateway 健康检查放在《装后 doctor 排错篇》的顺序里跑：本篇新增的是「工具注册」这一层的证据链，而不是重复安装步骤。
实操上可为每个 MCP Server 维护一张「最小复现卡片」：一条只读查询、一条越权应被拒绝的负例、以及期望的日志关键字三行；值班同学只需对照卡片即可判断是配置回归还是上游事故，而不必每次从头阅读长篇 prompt。该卡片还应注明允许的出口与数据分级，避免在事故响应时临时放宽 token 范围却无人记录。
下表用于值周与变更评审附件；具体键名以你正在使用的 OpenClaw 版本文档为准，本表只锁排查顺序。
| 症状 | 优先收集的证据 | 高概率根因 | 动作（可审计） |
|---|---|---|---|
| 工具列表为空或缺项 | Gateway 启动日志、MCP 子进程退出码 | 命令找不到、工作目录错误、权限拒绝 | 把 command/args/cwd 改成绝对路径；在同一用户下手工跑一遍子进程 |
| 首次调用超时，随后恢复 | 冷启动耗时、依赖下载日志 | npx -y 拉包、语言运行时 JIT | 预热 job；把 MCP 依赖预装到镜像或固定版本号；放宽首次超时 |
| 稳定超时 / 无响应 | 子进程存活、CPU、文件描述符 | 死锁、阻塞 IO、错误的工作目录 | strace/采样（合规允许范围内）；降级为只读工具做 A/B |
| 报「工具未注册」类错误 | schema 回传日志、协议版本 | MCP 实现与 Gateway 期望不匹配 | 对齐协议版本；固定依赖小版本；阅读上游 changelog |
团队需要一页「能力来源矩阵」，避免同一业务动作被三套机制重复描述。
| 来源 | 适用 | 版本策略 | 主要风险 |
|---|---|---|---|
| ClawHub / 市场包 | 快速引入社区能力、试验新工具 | 锁 commit 或 semver 范围；每周 diff | 上游变更导致行为漂移；需回归用例 |
仓库内 SKILL.md / 私有包 | 强合规、需代码评审的能力 | 与主分支同行；走 PR | 维护成本；要与 MCP 工具边界对齐 |
| MCP（外部系统真相源） | 数据库、工单、内部 HTTP API | 独立发布节奏；最小权限 token | 过度授权；需白名单工具清单 |
# 以下为「结构示意」——真实键名、嵌套路径与热加载行为请以当前 OpenClaw 官方文档为准。
# 目标：让 Gateway 以固定用户启动 MCP Server（stdio 示例）
#
# mcpServers:
# internal-readonly-lookup:
# command: /usr/local/bin/node
# args: ["/opt/mcp-servers/lookup/dist/index.js"]
# env:
# LOOKUP_API_TOKEN: "${LOOKUP_TOKEN_READONLY}"
# # cwd、超时、最大并发等按文档补充
#
# ClawHub Skill：将包解压/克隆到团队约定的 skills 目录后，
# 在网关中「刷新技能索引」或按文档执行 reload（具体命令随版本变化）。
注意：MCP 让你能把生产数据接到对话里；最小权限与审计比「先跑通」更重要。只读查询与写操作务必分 Server、分 token，并在变更单里留下白名单截屏或配置片段。
PATH、工作目录与卷挂载画在一张图上。memory_search 或文档工具，避免上下文膨胀。AGENTS.md 同时出现的次数；大于 1 必须有负责人签字豁免。在远程 Mac 或云主机上常驻 Gateway 时，磁盘与日志轮转同样影响 MCP：子进程若把临时文件写到系统盘而小实例未扩容，会在高压期表现为「随机超时」。这与单纯调模型参数完全不同，需要把主机运维与工具配置放在同一变更包里评审。
若 MCP Server 通过 HTTP/SSE 暴露而非 stdio，还要把反向代理层的 Upgrade、空闲超时与 TLS 终止一并纳入检查：网关日志显示「工具握手成功」但边缘代理提前掐掉长连接时，症状与「子进程崩溃」几乎相同，唯有在代理访问日志里才能看到 499/504 类指纹。此类问题请与《Nginx/Caddy 反代与 WebSocket》篇交叉阅读，避免在 OpenClaw 配置里无限加大超时而忽略入口层。
社区经验（非官方基准）：当单会话并行挂载 3 个以上重工具 MCP 且仍开启宽上下文检索时，上下文与排队延迟往往在分钟级波动；因此「能力矩阵 + 白名单工具」比「无限堆插件」更利于稳定 SLA。
笔记本睡眠、VPN 抖动与目录漂移会让 MCP 子进程与 Skills 索引处于不可预测状态；一旦团队要把 OpenClaw 接进真实业务数据，就需要7×24 在线、路径持久、权限可审计的主机。
自管物理机若缺乏全球可选区域与弹性租期，跨区同事常常在高峰时段共抢一台机器，工具冷启动与日志 IO 互相踩踏；相比之下，把 Gateway 放在具备独占 Apple Silicon、可按项目拆分租期、磁盘与出口可预期的专业 Mac 云环境，通常更容易把 MCP 与 Skills 策略固化成合同条款。MACCOME 提供多地区 Mac Mini M4 / M4 Pro 与灵活租期，适合作为 OpenClaw Gateway 与各语言构建机的稳定底座；公开价格与帮助中心可在下单前核对 SLA 与区域选择。
落地建议：先在远程 Mac 上跑通本篇 Runbook 的三条验证，再决定是否把同一镜像推广到生产池；避免「本地能调用、上云即超时」的重复劳动。若计划把 Gateway 暴露到公网，务必把 TLS、限流与 IP 允许列表写进同一张变更单，而不是事后补洞。