您的位置: 首页> AI模型

最新版OpenClaw使用自定义MCP完整教程（2026.4.5版，实测可用）

匿名上传

发布时间:2026-04-09 14:00:02

前言：本文适配通过官方脚本 curl -fsSL | bash 安装的最新版OpenClaw（2026.4.5），解决大家配置自定义MCP时常见的「配置报错」「MCP启动失败」「AI无法调用工具」等问题，全程实操，复制命令即可完成，适合新手和有自定义工具需求的开发者。

核心场景：通过命令行方式启动自定义MCP（以Python虚拟环境运行的ultimate-mcp为例），让OpenClaw自动加载MCP工具，实现AI调用自定义脚本/工具的需求，全程贴合真实开发场景。

一、前置准备（必看）

1. 确认环境与版本

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

# 查看OpenClaw版本（需为2026.4.5及以上）
openclaw --version

# 确认安装方式（官方脚本安装，输出如下即正常）
cat ~/.openclaw/install.log | grep "install.sh"

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

2. 确认自定义MCP就绪

本文以上一篇 Mac 全能本地 MCP 配置教程（智谱付费模型+全数据库+向量库+浏览器）的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启动失败」。

Step 1：打开OpenClaw配置文件

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

open ~/.openclaw/openclaw.json

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

Step 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无法找到脚本。

Step 3：保存配置并重启网关

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

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

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

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

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

1. 查看MCP列表

openclaw mcp list

成功输出示例（显示你的MCP名称，状态为running）：

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

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

2. 查看MCP详细状态

openclaw mcp status

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

3. 测试AI调用MCP工具

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

# 启动聊天界面
openclaw chat

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

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

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

四、常见问题排错（实测解决90%问题）

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

问题1：配置后报错「Unrecognized key: "mcpServers"」

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

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

问题2：MCP状态显示「failed」，日志提示「command not found」

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

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

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

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

问题3：AI无法调用MCP工具，提示「no tools available」

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

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

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

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

问题4：重启电脑后MCP无法自动启动

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

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

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

五、进阶操作（可选，提升体验）

1. 手动控制MCP启停

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

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

# 重启所有MCP
openclaw mcp restart

2. 查看MCP日志（排错必备）

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

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

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"
    }
  }
}