1. 为什么你的 OpenClaw 总是连不上 MCP从 openclaw.json 到 mcporter 的完整链路OpenClaw 是一款开源的本地 AI 智能体框架MCPModel Context Protocol则是让模型通过统一接口调用外部工具与数据源的开放协议。把这两者接起来OpenClaw 就能直接读写本地文件、查数据库、拉 GitHub 仓库甚至对接 Google Drive 和 Slack。听起来很美好但真正动手时很多人卡在同一个地方配置文件写完了openclaw status里 MCP 服务却始终不是 running或者 AI 回复一句没有配置 MCP。我试过在 macOS 和 Windows 上各跑一遍完整链路踩过的坑集中在三处openclaw.json里MCPORTER_CONFIG写成了相对路径、mcporter.json的 JSON 格式有隐藏错误、以及改完配置忘了重启网关。这篇就按声明服务 → 管理进程 → 验证调用 → 定位报错的顺序把 OpenClaw 接入 MCP 的每一步拆开讲配置片段可以直接复制命令清单可以逐条执行。适合谁看已经在本地装好 OpenClaw、想让 AI 真正操作本地文件和远程服务的开发者以及用 mcporter 管理多个 Node.js 侧 MCP 进程、需要一套稳定排障流程的人。核心检索词就三个OpenClaw、MCP、mcporter全文围绕它们展开。先说清楚 MCP 在 OpenClaw 里的角色。以前每接一个工具都要写单独的 Skill 插件现在只要工具支持 MCPOpenClaw 就能即插即用。MCP 支持两种传输协议stdio 走本地子进程的 stdin/stdout延迟极低、一对一、无网络暴露http/SSE 走网络连接支持多客户端适合远程或团队共享。本地开发优先 stdio跨设备协作再考虑 http。环境上Node.js 建议 v22 或更高node -v和npm -v先确认OpenClaw 要能跑起来openclaw --version有输出mcporter 是可选的进程管理工具但只要你打算管多个 MCP 服务强烈建议装上。装完先跑一次openclaw doctor把运行时环境的健康状态过一遍后面排错时能少怀疑一个变量。2. 前置准备openclaw.json 声明服务与 mcporter 安装这一节解决服务从哪来的问题。OpenClaw 接入 MCP 有三条路CLI 命令行添加、mcporter 统一管理、openclaw-mcp-adapter 插件转换。日常最稳的是前两条组合——用 CLI 快速验证单个服务用 mcporter 管一批服务。先看 CLI 方式格式是openclaw mcp add --transport 协议 名称 启动命令。比如加一个本地文件系统访问openclaw mcp add --transport stdio local-files npx -y modelcontextprotocol/server-filesystem /Users/yourname/Documents这条命令注册了一个 stdio 传输的本地文件工具末尾的目录是授权 AI 访问的范围别图省事写成根目录。加完可以用openclaw mcp list看是否登记成功。但服务一多逐个用 CLI 加就乱了这时候上 mcporter。它是 OpenClaw 生态里专门连接和管理 MCP 服务器的工具全局安装npm install -g mcporter mcporter --versionmcporter 靠mcporter.json知道有哪些服务。路径按系统分系统配置文件路径WindowsC:\Users\你的用户名\.mcporter\mcporter.jsonmacOS / Linux~/.mcporter/mcporter.json配置文件长这样注意env里的密钥按实际填{ mcpServers: { my-tool: { command: npx, args: [-y, some-mcp-package], env: { API_KEY: your_api_key_here } } } }写完mcporter.json还要在 OpenClaw 主配置里启用它。编辑~/.openclaw/openclaw.json在skills.entries下加 mcporter 条目{ skills: { entries: { mcporter: { enabled: true, env: { MCPORTER_CONFIG: /Users/你的用户名/.mcporter/mcporter.json } } } } }注意MCPORTER_CONFIG必须是绝对路径写成~/.mcporter/...这种带波浪号的相对写法OpenClaw 解析时会失败。Windows 路径里的反斜杠在 JSON 中要转义成\\比如C:\\Users\\你的用户名\\.mcporter\\mcporter.json。如果你更想让 MCP 工具直接变成 OpenClaw 原生工具可以装 openclaw-mcp-adapter 插件openclaw plugins install mcp-adapter然后在openclaw.json的plugins.entries里配置openclaw-mcp-adapter用servers数组声明每个服务的name、transport、command、args或urltoolPrefix: true会给工具名加前缀避免冲突。它的原理是网关启动时连上每个 MCP 服务、调listTools()发现工具、注册成原生工具调用时再代理过去断线后下次调用自动重连。配置文件路径汇总一下方便对照文件macOS/LinuxWindows说明OpenClaw 主配置~/.openclaw/openclaw.jsonC:\Users\用户名\.openclaw\openclaw.json核心配置mcporter 配置~/.mcporter/mcporter.jsonC:\Users\用户名\.mcporter\mcporter.jsonMCP 服务列表Skills 目录~/.clawdbot/skills/~/.clawdbot/skills/Skill 文件存放MCP 日志~/openclaw/logs/mcp.log—运行日志3. 可复制配置openclaw.json 与 mcporter.json 的完整片段这一节把上一节的片段拼成能直接落地的完整配置并补上网关管理命令。很多人配置失败不是不会写而是不知道改完要重启这个动作。先给一份完整的~/.openclaw/openclaw.json骨架包含 skills 和 plugins 两部分{ skills: { entries: { mcporter: { enabled: true, env: { MCPORTER_CONFIG: /Users/yourname/.mcporter/mcporter.json } } } }, plugins: { entries: { openclaw-mcp-adapter: { enabled: true, config: { servers: [ { name: my-mcp-server, transport: stdio, command: npx, args: [-y, some-mcp-package] }, { name: remote-server, transport: http, url: http://localhost:3000/mcp } ], toolPrefix: true } } } } }对应的~/.mcporter/mcporter.json可以放多个服务每个服务独立配置{ mcpServers: { local-files: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /Users/yourname/Documents] }, my-tool: { command: npx, args: [-y, some-mcp-package], env: { API_KEY: your_api_key_here } } } }配置写完后网关必须重启才能加载新内容。OpenClaw 的 MCP 工具依赖网关进程常用命令openclaw gateway # 启动网关 openclaw gateway status # 查看网关状态 openclaw gateway restart # 重启重新加载所有 Skill 和配置 openclaw doctor # 检查系统健康状态 openclaw gateway logs # 查看网关日志注意每次改完openclaw.json或mcporter.json都要执行openclaw gateway restart。只改文件不重启是AI 说没有配置 MCP最常见的原因。如果你想把某个 HTTP MCP 服务快速转成 OpenClaw Skill社区有个一行命令的工具npx filiksyos/mcptoskilllatest https://mcp.example.com/mcp它会连上服务、发现工具、生成带描述和触发短语的SKILL.md、创建调用 MCP 的 Shell 脚本并自动装到~/.openclaw/skills/里启用。适合临时接一个远程服务、不想手写配置的场景。反过来OpenClaw 自己也能当 MCP 服务器被别的 AI 调用。比如通过 Docker 部署 openclaw-mcp 桥接服务暴露 3000 端口设置OPENCLAW_URL、OPENCLAW_GATEWAY_TOKEN、AUTH_ENABLED等环境变量再在 Claude Desktop 或 Cursor 的 MCP 配置里指向它。这部分属于反向接入本地跑通正向链路后再折腾更稳。4. 验证请求从 mcporter list 到一次真实工具调用配置写完不等于生效必须逐项验证。我习惯按状态 → 列表 → 交互 → Skill四步走每步都有明确的成功标志。第一步状态查询。运行openclaw status看 MCP 服务器是否处于 running 状态。如果显示 stopped 或根本没列出来先别往下走回到上一节检查路径和重启。第二步工具列表。运行mcporter list这条命令会列出所有已连接的 MCP 服务器及其工具。成功时你能看到服务名和它暴露的工具清单比如文件系统服务会列出 read_file、list_directory 之类。如果提示无配置说明mcporter.json路径不对或 JSON 格式有误。第三步交互验证。在 OpenClaw 对话框里发一条能触发工具的自然语言指令比如列出我授权目录下的前 5 个文件名。如果 MCP 正常AI 会调用文件系统工具并返回真实结果如果它回没有配置 MCP或Tool not found说明工具没注册成功。第四步Skill 列表。运行clawdbot skills list查看所有已加载的 Skill 及其状态确认 mcporter 或 adapter 对应的条目是 enabled。这四步里第二步和第三步最关键。mcporter list验证的是服务连得上交互验证的是工具调得动两者都过才算真正跑通。如果只想快速确认单个服务也可以直接跑mcporter config list它会打印当前 mcporter 识别到的配置用来核对路径和内容是否和你写的一致。验证通过后建议把这次成功的配置和命令记下来。MCP 服务多了以后mcporter list的输出会变长定期清理不再用的服务能减少启动时的连接开销也能避免工具名冲突。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth 过期排错的核心是看日志 对症状。MCP 日志在~/openclaw/logs/mcp.log网关日志用openclaw gateway logs看。下面按真实报错逐条对照。mcporter list提示无配置多半是mcporter.json路径错误或没创建。核对文件是否在~/.mcporter/下JSON 是否合法可以用node -e JSON.parse(require(fs).readFileSync(路径,utf8))快速校验。AI 说没有配置 MCPMCPORTER_CONFIG没设或没重启。检查openclaw.json里是不是绝对路径然后openclaw gateway restart。Tool X not foundSkill 目录错误或会话膨胀。确认 Skill 在~/.clawdbot/skills/会话太长时用/molt清除会话状态。HTTP 400 tool_call_id错误网关状态损坏直接clawdbot gateway restart。npx报错或超时npm 缓存或网络问题先npm cache clean --force再确认网络能访问 npm registry。undici错误Node 版本管理器nvm/fnm冲突。切到系统 Nodenvm use system或用官方安装脚本重装。OAuth Token 过期Google 类服务的令牌约 1 小时过期运行gog auth add email --force-consent强制刷新。工具初期正常后失效会话膨胀导致工具 Schema 被淹没。保持会话短小用/molt或clawdbot molt清理。401类鉴权失败检查mcporter.json里env的 API Key 是否正确、是否过期以及远程服务是否要求额外的认证头。本地 stdio 服务一般不会 401出现 401 基本是远程 http 服务。local proxy failed通常是本地代理进程没起来或端口被占。确认 MCP 服务进程是否在跑mcporter list能否连上如果是 http 传输检查url端口是否被其他程序占用。reading choices报错多出现在调用返回结构不符合预期时检查服务版本是否和 OpenClaw 兼容必要时升级 mcporter 和对应 MCP 包。排查时有个通用顺序先看mcporter list能不能列出服务再看交互能不能调工具最后才翻日志找具体堆栈。大部分问题在前两步就能定位不用一上来就啃日志。6. 把 MCP 纳入日常管理稳定跑通后的几个习惯链路跑通只是开始真正省心的是把它管起来。几个实测有效的习惯第一配置集中放。所有 MCP 服务都写进mcporter.json不要一部分用 CLI 加、一部分写文件否则mcporter list和openclaw status的输出会对不上排错时容易误判。第二改完必重启。把openclaw gateway restart当成肌肉记忆改任何配置文件后都执行一次能省掉大量为什么没生效的困惑。第三会话保持短小。工具 Schema 被长会话淹没是工具初期正常后失效的根因定期用/molt清理别让一个会话跑几百轮。第四密钥走环境变量。mcporter.json里的env尽量引用系统环境变量别把明文 Key 提交到任何仓库。第五定期核对路径。Windows 用户尤其注意反斜杠转义MCPORTER_CONFIG和mcporter.json里的路径都写成绝对路径并正确转义。如果你需要长期跑编码类 Agent、管理多个 MCP 服务可以考虑用 Coding Plan 把调用额度固定下来避免临时 Key 过期打断工作流日常验证某个模型或工具是否可用用模型对话快速试一次最省事接入和排障过程中需要查文档或生成 Key直接去 API Keys 和接入文档页面按步骤操作即可。把配置、验证、排障这三件事做成固定流程OpenClaw 的 MCP 就能稳定跑在本地成为日常开发里真正能用的工具层。