MCP 接入：给 Claw 外挂工具箱

上一课的浏览器给了 Claw 上网的手；这一课给它配一个外挂工具箱。MCP（Model Context Protocol，模型上下文协议）官方文档一句话就说清了本质：「an agent borrows tools from another program」——agent 从另一个程序借工具。MCP 服务器对外暴露工具、资源和提示词，OpenClaw 连上它，这些工具就会出现在你 agent 的工具目录里，随取随用。

OpenClaw MCP 接入有三个面：Control UI 点点点、openclaw mcp 命令行、mcp.servers 配置文件——殊途同归，写的都是同一份配置。另外还有个反方向：openclaw mcp serve 把 OpenClaw 的渠道对话反向暴露给 Claude Code / Codex 这类 MCP 客户端。全部示例基于 OpenClaw v2026.10.9。

学完你能做什么

• 用三种方式（Control UI / openclaw mcp CLI / mcp.servers 配置文件）给 OpenClaw 挂载 MCP 服务器
• 用 openclaw mcp doctor <name> --probe 验证服务器真的在线、真的暴露了工具
• 用 --include / toolFilter / openclaw mcp tools 只把需要的工具暴露给 agent
• 给需要 OAuth 的远程 HTTP 服务器完成登录
• 用 openclaw mcp serve 把 OpenClaw 渠道对话反向暴露给 Claude Code / Codex

你现在的困境

• Claw 能聊天、能跑命令、能上网，但一碰到内部系统或特定数据源就没辙——它没有对应的工具
• 找到了现成的 MCP 服务器，却不知道怎么接到 OpenClaw 上：配置写哪儿、格式长什么样、接完怎么验证，全靠猜
• 担心外挂工具不受管束：接了第三方服务器，它带的工具会不会绕过我设的权限

什么时候用这一招

当你需要：

• 给 Claw 加内置工具没有的能力：读写指定目录、外部记忆库、内部 API、桌面控制……
• 复用 MCP 生态里现成的服务器——npx 一条命令挂上，不用自己写插件
• 多个 agent / 多种运行时共享同一份工具定义——OpenClaw 集中存在 mcp.servers，运行时不用各自维护一份

而且不想：

• 为每个新能力去改 OpenClaw 本体或写插件
• 把工具用法硬塞进提示词——MCP 工具自带 schema，agent 自动发现

🎒 开始前的准备

• 读过本阶段导读 高效工作流：自动化、浏览器与 MCP
• OpenClaw 已安装并完成 onboarding（没装先看 安装：5 分钟跑通 OpenClaw）
• 手里有想挂的服务器信息：本地 stdio 服务器的启动命令，或远程 HTTP 服务器的 URL
• 会打开 Control UI（方式 B 会用到）

核心思路

先建立方向感。 MCP 有两个方向，别搞混：

方向	谁是 MCP 服务器	干什么	入口
接入（本课主线）	第三方程序	OpenClaw 连它，把它的工具借给自己的 agent	Settings → MCP / openclaw mcp add / mcp.servers
反向暴露（进阶）	OpenClaw 自己	别的 MCP 客户端来读取 / 发送 OpenClaw 的渠道对话	openclaw mcp serve

三条官方明确写的底线：

1. 服务器定义统一存在配置的 mcp.servers 下，三种接入面写的是同一份东西；
2. MCP 工具走同一套 tool-profile / tool-policy 管控——「connecting a server does not bypass your policy」，接入不等于放行；
3. 凭据别写进配置字面量——敏感 header 和环境变量用受支持的 secret 机制存。

三种传输，按服务器在哪选：

传输	适合	要填什么
Stdio	本地命令启动的服务器	command + args（可选 cwd / env）
Streamable HTTP	远程服务器	http(s):// URL
SSE	老式远程服务器	http(s):// URL

规则一句话：command（stdio）和 URL（HTTP 系）二选一，两者都写会被配置校验拒绝；enabled: false 保留定义但不连接；服务器名 __proto__ 是保留字，起别的名。

三个接入面，按习惯选：

接入面	适合谁	特点
Control UI（Settings → MCP）	不想碰终端	Gateway 运行时也能改，OAuth 浏览器里点一下
CLI（openclaw mcp）	想复制粘贴、脚本化	写入类命令要独占状态，先停 Gateway（见踩坑 1）
配置文件（mcp.servers）	要版本管理、批量初始化	字段最全，直接编辑

跟我做

第 1 步：摸清 OpenClaw MCP 现状（openclaw mcp status --verbose）

为什么：动手前先看家里有什么。status 只读配置、不连接任何服务器，Gateway 运行时也能跑。

openclaw mcp status --verbose

你应该看到：已保存服务器定义的清单——每个服务器的传输类型、启动参数、超时、OAuth 状态、工具过滤器。全新安装时列表是空的，正好从零开始。

💡 拿不准就先跑它

官方给的建议也一样：不确定走哪条路，先 openclaw mcp status --verbose——它告诉你 OpenClaw 存了什么，而不启动任何 MCP 服务器。

第 2 步：添加第一个 MCP 服务器（三种方式任选）

为什么：拿官方 recipes 里的 memory 服务器当第一个——npx 一条命令就能跑起来，零配置。三种方式写的是同一份 mcp.servers，选顺手的就行。

方式 A（推荐）：CLI 一个停机窗口搞定

为什么包着 stop / restart：add 这类写入命令要独占状态目录，Gateway 正在运行并持有它时会拒绝写入、提示先停再试——这是设计不是故障。

openclaw gateway stop
openclaw mcp add memory \
  --command npx \
  --arg -y \
  --arg @modelcontextprotocol/server-memory
openclaw gateway restart

你应该看到：add 先做检查再保存定义（默认自带检查，除非 --no-probe 或需要先走 OAuth），保存后 restart 让 Gateway 带着新定义跑起来。

• 小检查：openclaw mcp list 能看到 memory

方式 B：Control UI 运行时直接加

1. 打开 Control UI，进 Settings → MCP（浏览器地址栏直接输 /settings/mcp 或别名 /mcp 也行）。
2. 在 Configured servers 下选 Add server。
3. 起个唯一名字，选传输：Streamable HTTP / SSE / Stdio。
4. HTTP 系传输填服务器的 http:// 或 https:// URL；stdio 填启动命令和参数。
5. 选 Add server——定义经 Gateway 写进 mcp.servers。

你应该看到：服务器出现在列表里，每一行都能启用、禁用或删除；headers、环境变量、OAuth、TLS、超时这些进阶项在页面下方的分区配置编辑器里。

聊天窗口里也能加：+ → Plugins → Add MCP server…（需要管理员权限），作用域选 This session（仅本会话）或 Everywhere（全局）。

方式 C：直接写配置文件

同一个 memory 服务器，写进 mcp.servers 长这样（JSON5）：

{
  mcp: {
    servers: {
      memory: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-memory"],
        enabled: true,
      },
    },
  },
}

你应该看到：保存后，开了 Gateway 热重载的安装里变更立即生效——被改或被删的服务器立刻退役，下一回合的工具发现用新定义；没动过的服务器保持连接和缓存。

第 3 步：体检——doctor --probe 证明服务器真的在线

为什么：官方原话「Saving a definition proves nothing about reachability」——保存定义什么也证明不了，连得上才算数。排错梯子从轻到重：

openclaw mcp status --verbose      # 只读配置，随时能跑
openclaw mcp doctor memory         # 静态检查，随时能跑
openclaw mcp doctor memory --probe # 真实连接，要独占状态（Gateway 在跑会拒绝）
openclaw mcp probe memory          # 只做真实连接、列工具（同样要独占状态）

你应该看到：doctor 先查本地配置问题——stdio 命令缺失、cwd 不存在、TLS 文件缺失、服务器被禁用、明文敏感值、OAuth 授权不完整；--probe 再开一条真实连接，报告服务器暴露的工具和其它能力。

如果服务器暂时连不上，先别急着排错：OpenClaw 内置客户端会指数退避重连——30 秒起、逐次翻倍、最长 10 分钟；恢复在后台跑，工具在下一回合边界可用，不阻塞当前对话。

• 小检查：doctor --probe 的输出里能看到工具列表

第 4 步：过滤工具，只暴露需要的

为什么：一个服务器可能带一堆工具，全暴露既吵又不安全。文件系统服务器是官方给的典型例子——只留读和搜索，不给写：

openclaw gateway stop
openclaw mcp add files \
  --command npx \
  --arg -y \
  --arg @modelcontextprotocol/server-filesystem \
  --arg "$HOME/Documents" \
  --include 'read_file,list_directory,search_files'
openclaw mcp doctor files --probe
openclaw gateway restart

你应该看到：doctor files --probe 连上服务器并报告工具；--include 过滤发生在工具进入 agent 目录之前，写类工具不会出现。官方建议把文件系统服务器圈到 agent 需要的最小目录树。

已保存的服务器事后调整用 tools（同样要停机窗口）：

openclaw mcp tools files --include 'read_file,list_directory,search_files'
openclaw mcp tools files --clear   # 清除过滤

配置文件里对应 toolFilter.include / toolFilter.exclude，支持 * 通配。会话里还能细调：聊天窗口 + → Plugins → Tool access，可以逐个查看或禁用该会话的工具。

第 5 步：接入要 OAuth 登录的远程服务器

为什么：远程 HTTP 服务器常用 OAuth 认证。以官方 docs 服务器配方为例，add 时直接声明：

openclaw gateway stop
openclaw mcp add docs \
  --url https://mcp.example.com/mcp \
  --transport streamable-http \
  --auth oauth \
  --oauth-scope docs.read \
  --timeout 20 \
  --connect-timeout 5 \
  --include 'search,read_*'
openclaw mcp login docs
openclaw gateway restart

为什么要停机：openclaw mcp login 只在离线状态运行（要独占状态目录走完 OAuth 回调）。

你应该看到：终端打印授权 URL；浏览器完成授权后，OpenClaw 通常自动捕获回环重定向并存好凭据。浏览器够不到回调监听时（远程、无头环境），用打印出来的 --code 命令兜底。

Control UI 里更省事：Settings → MCP 里管理员对启用中的 OAuth 服务器直接选 Sign in，浏览器里批准访问后回到 Settings 即可。

检查点 ✅

• openclaw mcp status --verbose 能列出你保存的服务器与传输类型
• openclaw mcp doctor <name> --probe 连上服务器并列出了它的工具
• 对话里让 Claw 用一次新工具，它调用成功
• 用 openclaw mcp tools <name> --include … 收紧过工具暴露面
• 能说出写入类 CLI 命令为什么要先停 Gateway（或改用 Control UI）

踩坑提醒

❌ Gateway 运行中，CLI 写入命令被拒绝

add / set / configure / tools / unset / login / logout / probe / doctor --probe 都要独占状态目录。Gateway 正在运行并持有它时，命令会拒绝写入并给出「先停再试」的提示。

正确做法：要么 openclaw gateway stop → 操作 → openclaw gateway restart，要么直接用 Control UI（Settings → MCP 支持运行时修改和登录）。list / show / status / doctor（不带 --probe）不受影响，Gateway 运行时随时能跑。

❌ 服务器在列表里，对话里却没工具

保存 ≠ 可达。排查顺序：

openclaw mcp doctor <name> --probe

• 连上了但工具比预期少 → 查 toolFilter.include / toolFilter.exclude 是不是过滤狠了
• enabled: false 的服务器保留定义但不连接，不会进工具发现
• 都正常还不行 → 改动可能没到达正在跑的 agent：openclaw mcp reload 只刷新当前 CLI 进程的运行时，Gateway 或别处的 agent 要各自的 reload / 配置发布 / 重启

❌ stdio 服务器起不来

三个常见原因，doctor 都能查出来：

• command 在 Gateway 进程环境里解析不到——你在自己 shell 里能跑，不代表 Gateway 环境里能跑
• cwd 目录不存在
• 参数放错了位置：参数属于 args，别拼进 command；显式 transport: "stdio" 必须有非空 command

❌ HTTP 服务器报 401（authentication refused）

启动日志和目录诊断会报 authentication refused (401)。这是服务器要认证，不是 OpenClaw 坏了：

• OAuth 服务器：确认配置了 auth: "oauth" 和所需的 oauth 元数据，再走第 5 步的登录流程
• 静态凭据：检查 mcp.servers 里该服务器的 header / 凭据配置——同时别把 token 明文写进配置，用 secret 机制存

进阶技巧（可选）

反向：把渠道对话暴露给 Claude Code / Codex。 openclaw mcp serve 让 OpenClaw 自己当 MCP 服务器（stdio）：MCP 客户端启动并持有这个进程，桥接经 WebSocket 连到本地或远程 Gateway，把已路由的渠道会话变成 MCP 会话。

openclaw mcp serve                                                 # 本地 Gateway
openclaw mcp serve --url wss://gateway-host:18789 \
  --token-file ~/.openclaw/gateway.token                          # 远程 Gateway（token）

桥接暴露的工具：conversations_list、conversation_get、messages_read、attachments_fetch、events_poll、events_wait、messages_send，外加 permissions_list_open / permissions_respond 处理 exec 和插件审批。注意事件队列是实时的——桥接一断就没了，历史消息用 messages_read 读。

给信任的服务器设审批模式。 Codex 的 MCP 工具审批默认跟随会话权限姿态；受信任的服务器可以显式放宽：

openclaw mcp add memory \
  --command npx \
  --arg -y \
  --arg @modelcontextprotocol/server-memory \
  --approval approve

三档：approve（跳过逐次审批，只给信任服务器用）/ prompt（每次都问）/ auto（按工具安全注解）。已保存的服务器用 openclaw mcp configure <name> --approval … 单独改。

每服务器超时与并发。 connectionTimeoutMs / requestTimeoutMs 设连接与请求超时（毫秒）；supportsParallelToolCalls: true 标记可以被适配器并发调用的服务器。

本课小结

✅ MCP = agent 从别的程序借工具的协议。OpenClaw 连上 MCP 服务器后，工具自动进 agent 的工具目录，而且走同一套 tool-profile / tool-policy 管控——接入不绕过你的策略。

✅ OpenClaw MCP 接入三面一体：Control UI（Settings → MCP）、CLI（openclaw mcp）、配置文件（mcp.servers），写的是同一份配置。

✅ 验证链：status --verbose（只读配置）→ doctor（静态检查）→ doctor --probe / probe（真实连接列工具）。保存定义什么也证明不了。

✅ 收紧暴露面：--include / toolFilter / openclaw mcp tools；文件系统服务器圈最小目录树；会话内用 + → Plugins → Tool access 逐个禁用。

✅ 写入类 CLI 命令（add / set / configure / tools / unset / login / logout / probe / doctor --probe）要独占状态——Gateway 在跑就先停再试，或改用 Control UI。

✅ 反方向 openclaw mcp serve：OpenClaw 当 MCP 服务器，把渠道对话借给 Claude Code / Codex。

关键配置字段	推荐值	说明
mcp.servers.<name>.transport	streamable-http / sse / stdio	远程服务器用 HTTP 系，本地命令用 stdio
command + args vs url	二选一	stdio 填命令与参数，HTTP 填 URL；两者都写会被校验拒绝
toolFilter.include / exclude	只留需要的工具（支持 * 通配）	过滤发生在工具进入目录之前
enabled	true / false	false 保留定义但不连接
connectionTimeoutMs / requestTimeoutMs	5000 / 20000	每服务器连接 / 请求超时（毫秒）
auth	"oauth"	HTTP 服务器 OAuth，配 openclaw mcp login 用
codex.defaultToolsApprovalMode	approve / prompt / auto	Codex 工具审批模式，--approval 写入

CLI 速查：openclaw mcp list / show / status / doctor / probe / add / set / configure / tools / login / logout / reload / unset。完整命令表见 CLI 命令与配置速查。

下一课预告

工作流三件套到齐了：定时任务管什么时候干、浏览器管上网拿料、MCP 管外挂能力。下一课 场景实战：选择你的路线，按你的身份挑一条路线，把三件套拼成真活。

你会学到：

• 国内 IM 接入矩阵：企业微信、飞书、微信 / QQ / 元宝各自怎么接
• 定时 + 上网拼成 每日晨报 与 网页监控
• 让 Claw 写代码、盯 PR：写代码 与 GitHub 值班
• 服务器部署：让 Claw 在 VPS / Docker 上 7×24 在线

相关教程

• 浏览器控制：让 Claw 替你上网操作——内置的上网能力，与 MCP 外挂互补
• 定时任务 Automations：cron、提醒与 Webhook 触发——MCP 工具 + 定时触发 = 无人值守流水线
• Skills 上手：安装、使用与配置——另一种扩展方式，技能与 MCP 工具怎么选