OpenClaw 2026.4.5 自定义 MCP 配置实操，修复 mcpServers 报错，实现 AI 调用自定义工具

本文适配 2026.4.5 最新版 OpenClaw（官方脚本安装），聚焦自定义 MCP 配置中的常见痛点，解决配置报错、MCP 启动失败、AI 无法调用工具等问题。全程以实操为核心，所有命令可直接复制执行，兼顾新手友好性与开发者实际需求，手把手教你实现 AI 调用自定义脚本/工具。

一、前期准备

1.1 确认环境与版本

首先确认你的 OpenClaw 版本和安装方式，避免版本不兼容导致配置失效：

# 查看 OpenClaw 版本（需为 2026.4.5 及以上）
openclaw --version
# 确认安装方式（官方脚本安装，输出如下即正常）
cat ~/.openclaw/install.log | grep "install.sh"

补充：若版本不符，重新执行官方安装脚本更新即可，无需卸载旧版本，脚本会自动覆盖升级。

1.2 确认自定义 MCP 就绪

你需提前准备好：

• MCP 脚本路径（示例：/Users/kenny/mcp/mcp_ultimate.py）
• 虚拟环境 Python 路径（示例：/Users/kenny/mcp/venv/bin/python）
• 确保 MCP 脚本可正常运行（手动执行脚本无报错，已安装所需依赖）

提示：若你的 MCP 是 Node.js、Bash 脚本，只需替换后续「command」和「args」参数即可，教程通用。

二、核心步骤：配置自定义 MCP（重点，实测不报错）

最新版 OpenClaw 的 MCP 配置有两个关键坑：① 字段名不是mcpServers，而是mcp；② 必须添加type和trust参数，否则会报错「Unrecognized key」或「MCP 启动失败」。

2.1 打开 OpenClaw 配置文件

使用系统默认编辑器打开配置文件（Mac 端通用）：

open ~/.openclaw/openclaw.json

若提示「文件不存在」，先启动一次 OpenClaw（openclaw gateway start），系统会自动生成配置文件。

2.2 添加正确的 MCP 配置

找到配置文件的根节点，在agents和commands之间，添加以下配置（直接复制，替换自己的路径即可）：

{
  // ... 原有配置（wizard、auth、models、agents 等，保留不变）
  
  "mcp": {
    "servers": {
      "ultimate-mcp": {  // MCP 名称，可自定义（如 my-mcp）
        "type": "stdio",  // 固定值，命令行启动模式（官方标准）
        "command": "/Users/kenny/mcp/venv/bin/python",  // 你的虚拟环境 Python 路径
        "args": ["/Users/kenny/mcp/mcp_ultimate.py"],  // 你的 MCP 脚本路径
        "env": {  // 可选：添加环境变量（如依赖路径、API 密钥）
          "PYTHONPATH": "/Users/kenny/mcp",
          "MCP_API_KEY": "your_key_here"  // 无则删除该字段
        },
        "cwd": "/Users/kenny/mcp",  // 可选：MCP 工作目录
        "trust": "trusted"  // 必加：最新版要求，否则无法加载 MCP
      }
    }
  },
  
  // ... 原有配置（commands、gateway 等，保留不变）
}

配置说明

• "mcp": { "servers": { ... } }：最新版固定结构，替换旧版的mcpServers，否则会报「Unrecognized key」错误。
• type: "stdio"：命令行启动 MCP 的固定值，若为 HTTP 方式可改为http，本文重点讲命令行方式。
• trust: "trusted"：2026.4.5 版本新增要求，不添加会导致 MCP 启动失败，提示「untrusted server」。
• 路径必须绝对路径：避免使用相对路径（如./mcp_ultimate.py），否则 OpenClaw 无法找到脚本。

2.3 保存配置并重启网关

配置修改完成后，保存并关闭编辑器，重启 OpenClaw 网关，让配置生效：

# 保存配置（Mac 端编辑器操作：Ctrl+O → 回车 → Ctrl+X）

# 重启网关（核心步骤，必执行）
openclaw gateway restart

三、验证 MCP 配置成功（必做，确认可用）

重启网关后，通过以下命令验证 MCP 是否正常加载、运行，避免后续 AI 调用失败。

3.1 查看 MCP 列表

openclaw mcp list

成功输出示例：

Available MCP Servers:
- ultimate-mcp (running) [stdio]
  Trust: trusted
  Tools: 3 (file_read, file_write, data_query)

显示你的 MCP 名称，状态为 running。

失败提示：若显示「stopped」或「failed」，进入第四步排错。

3.2 查看 MCP 详细状态

openclaw mcp status

可查看 MCP 的运行状态、加载的工具数量、日志路径，确认 MCP 健康。

3.3 测试 AI 调用 MCP 工具

启动 OpenClaw 聊天界面，直接让 AI 调用你的 MCP 工具，验证是否可用：

# 启动聊天界面
openclaw chat

在聊天框输入测试指令（根据你的 MCP 工具调整）：

「帮我用 ultimate-mcp 的 file_read 工具，读取/Users/kenny/mcp/test.txt 文件的内容」

成功效果：AI 会自动调用 MCP 工具，返回文件内容，无报错。

四、常见问题排错

新手配置时最容易遇到以下 3 个问题，直接对应解决即可，无需复杂排查。

4.1 配置后报错「Unrecognized key: “mcpServers”」

原因：字段名错误，最新版用mcp，不是mcpServers。

解决：将配置中的"mcpServers": { ... } 替换为 "mcp": { "servers": { ... } }，重启网关。

4.2 MCP 状态显示「failed」，日志提示「command not found」

原因：command路径错误（虚拟环境 Python 路径不对）。

解决：重新确认虚拟环境 Python 路径，可通过以下命令查找：

# 查找你的 MCP 虚拟环境 Python 路径
find /Users/kenny/mcp -name python 2>/dev/null

将找到的路径替换到配置文件的command字段，重启网关和 MCP。

4.3 AI 无法调用 MCP 工具，提示「no tools available」

原因 1：MCP 脚本未正确实现 MCP 协议（未启动服务）。

解决 1：手动运行 MCP 脚本，确认无报错，确保脚本中有server.start()等启动逻辑。

原因 2：未添加trust: "trusted"，MCP 被 OpenClaw 拦截。

解决 2：在 MCP 配置中添加"trust": "trusted"，重启网关。

4.4 重启电脑后 MCP 无法自动启动

解决：OpenClaw 网关默认开机自启，MCP 会随网关自动启动，只需确保网关自启正常：

# 查看网关自启状态
openclaw gateway status

# 开启网关自启（若未开启）
openclaw gateway install --force

五、进阶操作

5.1 手动控制 MCP 启停

# 启动指定 MCP
openclaw mcp start ultimate-mcp

# 停止指定 MCP
openclaw mcp stop ultimate-mcp

# 重启所有 MCP
openclaw mcp restart

5.2 查看 MCP 日志（排错必备）

# 查看指定 MCP 的日志（实时刷新）
openclaw mcp logs ultimate-mcp -f

# 查看日志文件（永久保存）
open ~/.openclaw/logs/mcp/ultimate-mcp.log

5.3 配置多个自定义 MCP

若有多个 MCP 脚本，可在servers中添加多个节点：

"mcp": {
  "servers": {
    "ultimate-mcp": { ... },  // 第一个 MCP
    "my-node-mcp": {          // 第二个 MCP（Node.js 示例）
      "type": "stdio",
      "command": "node",
      "args": ["/Users/kenny/mcp/node-mcp.js"],
      "trust": "trusted"
    }
  }
}

六、总结

最新版 OpenClaw 使用自定义 MCP 的核心的是「正确配置字段+必加关键参数」，全程无需复杂操作，按以下流程即可完成：

1. 确认 OpenClaw 版本和 MCP 脚本就绪；
2. 修改配置文件，添加mcp.servers节点（替换mcpServers）；
3. 添加type: "stdio"和trust: "trusted"；
4. 重启网关，验证 MCP 运行状态；
5. 测试 AI 调用 MCP 工具，完成配置。

本文所有命令和配置均实测可用，适配 2026.4.5 最新版，若你有其他 MCP 启动方式（如 HTTP）或遇到其他报错，可在评论区留言，我会补充解决方法。

以上关于OpenClaw 2026.4.5 自定义 MCP 配置实操，修复 mcpServers 报错，实现 AI 调用自定义工具的文章就介绍到这了，更多相关内容请搜索码云笔记以前的文章或继续浏览下面的相关文章，希望大家以后多多支持码云笔记。