OpenClaw 接入 MCP 教程 — 添加 / 配置 / 调用完整流程

三种接入方式怎么选

如果你用的是 OpenClaw Launch 托管版，常见 MCP 已经预装，在控制面板里勾选开关就行 — 不用碰下面三种方式。 下面的步骤主要针对自建 Docker / 本地用户。

方式一：clawhub 一键安装

clawhub 是 OpenClaw 自带的扩展管理工具。进入容器后跑：

docker exec -it openclaw clawhub install <mcp-name>

例如安装文件系统访问、网页搜索、浏览器自动化：

# Filesystem — 让 AI 读写本地文件
docker exec -it openclaw clawhub install filesystem-mcp

# Tavily — 网页搜索
docker exec -it openclaw clawhub install tavily-mcp

# Playwright — 浏览器自动化
docker exec -it openclaw clawhub install playwright-mcp

安装完成后 clawhub 会：(1) 拉 npm 包到容器内、(2) 在 openclaw.json 的 mcpServers 段加好对应条目、(3) 触发热加载。 几秒后在 AI 对话里就能直接调用。

如果 MCP 需要 API Key（比如 Tavily），clawhub 会提示你输入，自动写到对应的 env 字段。

方式二：手动编辑 openclaw.json

clawhub 没有？自建的 MCP？需要传特殊参数？直接改配置文件：

docker exec -it openclaw vi /home/node/.openclaw/openclaw.json

在 mcpServers 段下面加一个条目。下面是几个常见模板：

模板 A — Filesystem（stdio 模式，推荐）

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"],
      "env": {}
    }
  }
}

"/data" 是允许 AI 访问的目录白名单，可以列多个。 路径必须是容器内的路径 — 如果要让 AI 操作宿主机的文件，记得 docker run 时 -v 挂进来。

模板 B — Tavily Search（带 API Key）

{
  "mcpServers": {
    "tavily": {
      "command": "npx",
      "args": ["-y", "tavily-mcp"],
      "env": {
        "TAVILY_API_KEY": "tvly-xxxxxxxx"
      }
    }
  }
}

Tavily 免费 1000 次/月，注册流程见 Tavily 完整教程。

模板 C — 本地 Python MCP Server

{
  "mcpServers": {
    "my-tool": {
      "command": "python",
      "args": ["/home/node/.openclaw/scripts/my-mcp.py"],
      "env": {
        "DB_URL": "postgres://localhost/mydb"
      }
    }
  }
}

模板 D — HTTP / SSE 模式（远程 MCP）

{
  "mcpServers": {
    "remote-mcp": {
      "url": "http://10.0.0.5:8765/sse",
      "transport": "sse"
    }
  }
}

远程 MCP 适合多个 OpenClaw 实例共享一个工具、或者把 MCP 部署在另一台机器。 本地用例 99% 都用 stdio 就够 — 简单、安全、不占端口。

改完之后生效

OpenClaw 默认开启了热加载，编辑保存后几秒内 gateway 会自动重载 MCP 列表 — 通常不需要重启容器。 如果发现没生效，跑 docker restart openclaw 强制刷新。

方式三：MCPorter 可视化

MCPorter 是一个独立的 MCP 管理工具，提供 GUI 浏览、安装、配置。 它会帮你写好 JSON、传 API Key、并把配置同步到 OpenClaw。适合：

• 第一次接触 MCP，不熟悉 JSON 格式
• 想浏览和发现新的社区 MCP
• 需要在 Claude Desktop / Cursor / OpenClaw 三处共用一份 MCP 配置

安装 MCPorter 后选目标客户端为 OpenClaw，剩下的就是点点鼠标。具体下载和操作见 MCP 配置指南 里的 MCPorter 章节。

接入完怎么验证？

MCP Server 加好之后，最直接的验证方法是开一段对话让 AI 调用它：

• Filesystem — 让 AI"列出 /data 目录下的所有 .md 文件"。能列出来就成功。
• Tavily — 让 AI"搜索一下今天的科技新闻"。会返回带链接的搜索结果。
• Playwright — 让 AI"打开 example.com 并截图"。会返回 base64 截图。

如果 AI 回复"我没有这个工具"或者"我无法访问"，说明 MCP 没接通。看下一节排错。

接入失败排查清单

1. AI 说没有这个工具

进容器看 gateway 日志：docker logs openclaw 2>&1 | grep -i mcp。 常见原因：(a) JSON 格式错误，整个 mcpServers 段没被加载； (b) command 路径不对，比如容器里没装 Python； (c) MCP 进程启动后立刻 crash —— 日志里会有 stack。

2. npm 包拉不下来

国内服务器跑 npx -y @xxx/mcp-server-yyy 时容易卡。两个办法： (a) 给容器配 npm 镜像：docker exec openclaw npm config set registry https://registry.npmmirror.com； (b) 先在能联网的机器上 npm pack 打包，再 docker cp 进去离线装。

3. AI 能看到工具但调用就报错

通常是 env 没传对。比如 Tavily 没填 API Key、Postgres MCP 没填 DSN。 在 openclaw.json 的 env 段里检查每一个必需变量。 clawhub 安装时如果跳过了输入，配置里会留空值。

4. 多个 MCP 之间冲突

如果同一类工具装了两个（比如两个 search MCP），AI 选哪个不确定。建议：(a) 每类工具只装一个； (b) 在 prompt 里明确点名，"用 tavily 搜索 …"；(c) 在 openclaw.json 的 tools.deny 里临时禁用不用的那个。

5. 端口随机 / 调用超时

这两类是 MCP 接进来之后下一步会遇到的进阶问题。详细排查见 MCP 端口与超时高级配置。

OpenClaw Launch 用户怎么接入 MCP？

托管版完全不需要执行上面的命令。登录控制面板 → 进入实例设置 → MCP / Skills → 浏览可用列表 → 勾选启用即可。 需要 API Key 的 MCP 也可以在面板里安全地填入。 热加载在几秒内完成，无需重启实例。

这也是为什么不少自建用户最后切回托管：MCP / Skills / 模型这些组件的配置和升级，集中在一个地方更省心。