openclaw-external-mcp-setup

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 层：

1. 凭据层

   • 真正的 API Key、base URL、账号信息放在统一来源
   • 优先复用已有配置，不要复制出第二份密钥

2. MCP 注册层

   • 用 ~/.mcporter/mcporter.json 注册一个命名好的 MCP 服务

3. 桥接层

   • 如果这个 MCP 需要复用 OpenClaw 已有凭据，就写一个启动器脚本
   • 启动器负责把 ~/.openclaw/openclaw.json 里的配置翻译成环境变量，再启动 MCP

4. Agent 触发层

   • 不要只停留在“mcporter 能调用”
   • 还要在目标工作区给智能体加“工作区本地 skill”与长期规则，让它知道什么场景该调哪个能力

具体怎么配

第一步：确定凭据来源

优先顺序：

1. ~/.openclaw/openclaw.json
2. 工作区 config/*.env / config/*.json
3. 独立的 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。

更稳的做法是：

1. 提供一个固定命令入口
2. 再给目标工作区放本地 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 里补两类辅助项：

1. 让 OpenClaw 能读到项目里的额外 skill 目录
2. 显式启用 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：复制了第二份密钥

表现：

• 配置到处都是
• 换 key 时容易漏改

坑 3：过度依赖“一个总 skill”

表现：

• skill 描述太宽泛
• 模型不容易命中

更稳的方式是按具体能力拆 skill。

坑 4：只看“running”，不看真实调用

表现：

• 服务看起来在线
• 但真正调用报错，或者智能体根本不用

输出要求

交付时要明确说清楚：

1. 外部 MCP 的真实凭据放在哪
2. ~/.mcporter/mcporter.json 里注册了什么
3. 是否用了桥接启动器；如果用了，路径在哪
4. 工作区本地 skill 放在哪
5. MEMORY.md 写了哪些调用规则
6. 命令层和 agent 层是否都测通