| name | openclaw-external-mcp-setup |
| description | 当用户要给 OpenClaw 配置外部 MCP，或者要把某个 MCP 服务接进 OpenClaw，让智能体可以稳定调用外部工具时，必须使用这个技能。适用于“接搜索、浏览器、数据库、视觉理解、第三方平台工具”等所有 OpenClaw 外部 MCP 接入场景。优先走官方当前明文推荐方案，不要先猜原生配置键。 |
openclaw-external-mcp-setup
这个技能解决的是：如何把一个外部 MCP 稳定接进 OpenClaw，并且让智能体不只是“技术上装好了”，而是真的会调用。
先判断走哪条路线
官方当前明文推荐
默认优先走 mcporter 路线。
原因：
- 这是 OpenClaw 当前最明确、最稳定、最可落地的外部 MCP 入口
- 不需要先猜 OpenClaw 原生
mcpServers 键名
- 更适合给已有 agent 逐步加能力
什么时候才考虑原生配置
只有在官方文档已经明确写出：
这三样都齐了，才考虑改成原生配置。
如果没有，就不要自己猜。
标准接入架构
把 OpenClaw 外部 MCP 理解成 4 层：
-
凭据层
- 真正的 API Key、base URL、账号信息放在统一来源
- 优先复用已有配置，不要复制出第二份密钥
-
MCP 注册层
- 用
~/.mcporter/mcporter.json 注册一个命名好的 MCP 服务
-
桥接层
- 如果这个 MCP 需要复用 OpenClaw 已有凭据，就写一个启动器脚本
- 启动器负责把
~/.openclaw/openclaw.json 里的配置翻译成环境变量，再启动 MCP
-
Agent 触发层
- 不要只停留在“mcporter 能调用”
- 还要在目标工作区给智能体加“工作区本地 skill”与长期规则，让它知道什么场景该调哪个能力
具体怎么配
第一步：确定凭据来源
优先顺序：
~/.openclaw/openclaw.json- 工作区
config/*.env / config/*.json
- 独立的 MCP 专用 env
原则：
- 只保留一个真实来源
- 文档、记忆、daily note 不写真实密钥
- 如果 OpenClaw 已经有这份凭据，桥接脚本就去读
~/.openclaw/openclaw.json
第二步：注册 mcporter 服务
在 ~/.mcporter/mcporter.json 里注册 MCP：
{
"mcpServers": {
"your_mcp_name": {
"command": "/absolute/path/to/launcher_or_server",
"description": "Short description"
}
}
}
如果 MCP 本身就能直接启动，可以直接写服务命令。
如果要复用 OpenClaw 里的现有凭据，优先写一个启动器，再把 command 指向启动器。
第三步：必要时写桥接启动器
桥接启动器常见职责：
- 读取
~/.openclaw/openclaw.json
- 从
models.providers.* 或其它配置段取值
- 转成 MCP 需要的环境变量
- 最后
exec 真正的 MCP 服务
什么时候需要桥接：
- 不想重复保存 API Key
- 要兼容国内/国际 host
- 要兼容不同 Python/Node 运行时
第四步：给智能体加“稳定入口”
不要假设智能体自己会正确手写 mcporter call。
更稳的做法是：
- 提供一个固定命令入口
- 再给目标工作区放本地 skill
固定命令入口示例：
openclaw-your-mcp-router some_tool --arg "value"
工作区本地 skill 的作用：
- 把触发条件写得很明确
- 告诉智能体“什么情况下必须优先走这个能力”
- 避免它退回内置工具或手写错误命令
怎样让 agent 真会调用
只完成 mcporter list 还不够。
要再做两层：
1. 工作区本地 skill
把 skill 直接放到目标工作区：
~/.openclaw/workspace/skills/...~/.openclaw/workspace-mia/skills/...
建议按能力拆开，而不是做一个很宽泛的大 skill。
例如：
- 一个 skill 专门管“外部搜索”
- 一个 skill 专门管“图片理解”
- 一个 skill 专门管“数据库查询”
这样比一个总路由 skill 更容易触发。
2. 长期记忆规则
在目标工作区的 MEMORY.md 里明确写：
- 什么场景用哪个 skill
- 不要优先走哪个内置工具
- 不要手写哪些高错误率命令
这一步的作用是把“配置”升级成“习惯”。
OpenClaw 侧的辅助配置
如有需要，可以在 ~/.openclaw/openclaw.json 里补两类辅助项：
- 让 OpenClaw 能读到项目里的额外 skill 目录
- 显式启用
mcporter
例如结构上会看到：
{
"skills": {
"load": {
"extraDirs": [
"/path/to/project/.codex/skills"
]
},
"entries": {
"mcporter": {
"enabled": true
}
}
}
}
注意：
- 这只是辅助层
- 真正决定智能体是否“稳定调用”的，仍然是工作区本地 skill + MEMORY 规则
验证
至少做 3 轮验证：
1. 服务层验证
mcporter list your_mcp_name --schema
确认服务已经注册，工具能列出来。
2. 调用层验证
mcporter call your_mcp_name.some_tool --args '{"key":"value"}' --output json
确认工具真的能返回结果，而不是只注册成功。
3. Agent 层验证
直接给目标智能体一个真实任务，看它是否：
- 优先触发工作区本地 skill
- 走稳定入口命令
- 没有退回内置工具
- 没有手写错误的
mcporter call
常见坑
坑 1：只配了 mcporter，没有配 agent 触发层
表现：
坑 2：复制了第二份密钥
表现：
坑 3：过度依赖“一个总 skill”
表现：
更稳的方式是按具体能力拆 skill。
坑 4：只看“running”，不看真实调用
表现：
- 服务看起来在线
- 但真正调用报错，或者智能体根本不用
输出要求
交付时要明确说清楚：
- 外部 MCP 的真实凭据放在哪
~/.mcporter/mcporter.json 里注册了什么- 是否用了桥接启动器；如果用了，路径在哪
- 工作区本地 skill 放在哪
MEMORY.md 写了哪些调用规则- 命令层和 agent 层是否都测通
