前言：本文適配通過官方腳本 curl -fsSL https://openclaw.ai/install.sh | bash 安裝的最新版OpenClaw（2026.4.5），解決大家配置自定義MCP時常見的「配置報錯」「MCP啟動失敗」「AI無法調(diào)用工具」等問題，全程實操，復制命令即可完成，適合新手和有自定義工具需求的開發(fā)者。

核心場景：通過命令行方式啟動自定義MCP（以Python虛擬環(huán)境運行的ultimate-mcp為例），讓OpenClaw自動加載MCP工具，實現(xiàn)AI調(diào)用自定義腳本/工具的需求，全程貼合真實開發(fā)場景。

一、前置準備（必看）

1. 確認環(huán)境與版本

首先確認你的OpenClaw版本和安裝方式，避免版本不兼容導致配置失效：

# 查看OpenClaw版本（需為2026.4.5及以上）
openclaw --version
# 確認安裝方式（官方腳本安裝，輸出如下即正常）
cat ~/.openclaw/install.log | grep "install.sh"

補充：若版本不符，重新執(zhí)行官方安裝腳本更新即可，無需卸載舊版本，腳本會自動覆蓋升級。

2. 確認自定義MCP就緒

你需提前準備好：

• MCP腳本路徑（示例：/Users/kenny/mcp/mcp_ultimate.py）
• 虛擬環(huán)境Python路徑（示例：/Users/kenny/mcp/venv/bin/python）
• 確保MCP腳本可正常運行（手動執(zhí)行腳本無報錯，已安裝所需依賴）

提示：若你的MCP是Node.js、Bash腳本，只需替換后續(xù)「command」和「args」參數(shù)即可，教程通用。

二、核心步驟：配置自定義MCP（重點，實測不報錯）

最新版OpenClaw的MCP配置有兩個關鍵坑：① 字段名不是mcpServers，而是mcp；② 必須添加type和trust參數(shù)，否則會報錯「Unrecognized key」或「MCP啟動失敗」。

Step 1：打開OpenClaw配置文件

使用系統(tǒng)默認編輯器打開配置文件（Mac端通用）：

open ~/.openclaw/openclaw.json

若提示「文件不存在」，先啟動一次OpenClaw（openclaw gateway start），系統(tǒng)會自動生成配置文件。

Step 2：添加正確的MCP配置

找到配置文件的根節(jié)點，在agents和commands之間，添加以下配置（直接復制，替換自己的路徑即可）：

{
  // ... 原有配置（wizard、auth、models、agents等，保留不變）
  
  "mcp": {
    "servers": {
      "ultimate-mcp": {  // MCP名稱，可自定義（如my-mcp）
        "type": "stdio",  // 固定值，命令行啟動模式（官方標準）
        "command": "/Users/kenny/mcp/venv/bin/python",  // 你的虛擬環(huán)境Python路徑
        "args": ["/Users/kenny/mcp/mcp_ultimate.py"],  // 你的MCP腳本路徑
        "env": {  // 可選：添加環(huán)境變量（如依賴路徑、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：保存配置并重啟網(wǎng)關

配置修改完成后，保存并關閉編輯器，重啟OpenClaw網(wǎng)關，讓配置生效：

# 保存配置（Mac端編輯器操作：Ctrl+O → 回車 → Ctrl+X）

# 重啟網(wǎng)關（核心步驟，必執(zhí)行）
openclaw gateway restart

三、驗證MCP配置成功（必做，確認可用）

重啟網(wǎng)關后，通過以下命令驗證MCP是否正常加載、運行，避免后續(xù)AI調(diào)用失敗。

1. 查看MCP列表

openclaw mcp list

? 成功輸出示例（顯示你的MCP名稱，狀態(tài)為running）：

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

? 失敗提示：若顯示「stopped」或「failed」，進入第四步排錯。

2. 查看MCP詳細狀態(tài)

openclaw mcp status

可查看MCP的運行狀態(tài)、加載的工具數(shù)量、日志路徑，確認MCP健康。

3. 測試AI調(diào)用MCP工具

啟動OpenClaw聊天界面，直接讓AI調(diào)用你的MCP工具，驗證是否可用：

# 啟動聊天界面
openclaw chat

在聊天框輸入測試指令（根據(jù)你的MCP工具調(diào)整）：

「幫我用ultimate-mcp的file_read工具，讀取/Users/kenny/mcp/test.txt文件的內(nèi)容」

? 成功效果：AI會自動調(diào)用MCP工具，返回文件內(nèi)容，無報錯。

四、常見問題排錯（實測解決90%問題）

新手配置時最容易遇到以下3個問題，直接對應解決即可，無需復雜排查。

問題1：配置后報錯「Unrecognized key: "mcpServers"」

? 原因：字段名錯誤，最新版用mcp，不是mcpServers。

? 解決：將配置中的"mcpServers": { ... } 替換為 "mcp": { "servers": { ... } }，重啟網(wǎng)關。

問題2：MCP狀態(tài)顯示「failed」，日志提示「command not found」

? 原因：command路徑錯誤（虛擬環(huán)境Python路徑不對）。

? 解決：重新確認虛擬環(huán)境Python路徑，可通過以下命令查找：

# 查找你的MCP虛擬環(huán)境Python路徑
find /Users/kenny/mcp -name python 2>/dev/null

將找到的路徑替換到配置文件的command字段，重啟網(wǎng)關和MCP。

問題3：AI無法調(diào)用MCP工具，提示「no tools available」

? 原因1：MCP腳本未正確實現(xiàn)MCP協(xié)議（未啟動服務）。

? 解決1：手動運行MCP腳本，確認無報錯，確保腳本中有server.start()等啟動邏輯。

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

? 解決2：在MCP配置中添加"trust": "trusted"，重啟網(wǎng)關。

問題4：重啟電腦后MCP無法自動啟動

? 解決：OpenClaw網(wǎng)關默認開機自啟，MCP會隨網(wǎng)關自動啟動，只需確保網(wǎng)關自啟正常：

# 查看網(wǎng)關自啟狀態(tài)
openclaw gateway status

# 開啟網(wǎng)關自啟（若未開啟）
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中添加多個節(jié)點：

"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的核心的是「正確配置字段+必加關鍵參數(shù)」，全程無需復雜操作，按以下流程即可完成：

1. 確認OpenClaw版本和MCP腳本就緒；
2. 修改配置文件，添加mcp.servers節(jié)點（替換mcpServers）；
3. 添加type: "stdio"和trust: "trusted"；
4. 重啟網(wǎng)關，驗證MCP運行狀態(tài)；
5. 測試AI調(diào)用MCP工具，完成配置。

本文所有命令和配置均實測可用，適配2026.4.5最新版，若你有其他MCP啟動方式（如HTTP）或遇到其他報錯，可在評論區(qū)留言，我會補充解決方法。

以上就是2026.4.5版OpenClaw使用自定義MCP完整教程的詳細內(nèi)容，更多關于OpenClaw使用自定義MCP的資料請關注腳本之家其它相關文章！

最新評論