使用 OpenClaw MCP 伺服器：整合 Claude 與開發工具

openclaw mcp 有兩個任務：

使用 openclaw mcp serve 將 OpenClaw 作為 MCP server 執行
透過 list, show, set 和 unset 來管理 OpenClaw 擁有的外連 MCP server 定義

換句話說：

serve 是 OpenClaw 扮演 MCP server 的角色
list / show / set / unset 是 OpenClaw 扮演 MCP client 端註冊表，供其 runtime 稍後使用其他 MCP server

當 OpenClaw 需要自行託管 coding harness session 並透過 ACP 路由該 runtime 時，請使用 openclaw acp。

OpenClaw 作為 MCP server

這是 openclaw mcp serve 的路徑。

何時使用 `serve`

在以下情況使用 openclaw mcp serve：

Codex, Claude Code 或其他 MCP client 需要直接與 OpenClaw 支援的 channel 對話
你已經有一個本地或遠端的 OpenClaw Gateway，且帶有路由 session
你想要一個能跨 OpenClaw channel backend 運作的 MCP server，而不是為每個 channel 執行個別的 bridge

如果 OpenClaw 應該自行託管 coding runtime 並將 agent session 保留在 OpenClaw 內部，請改用 openclaw acp。

運作原理

openclaw mcp serve 會啟動一個 stdio MCP server。MCP client 擁有該程序。當 client 保持 stdio session 開啟時，bridge 會透過 WebSocket 連接到本地或遠端的 OpenClaw Gateway，並透過 MCP 暴露路由過的 channel 對話。

生命週期：

MCP client 啟動 openclaw mcp serve
bridge 連接到 Gateway
路由後的 session 變成 MCP 對話以及 transcript/history 工具
當 bridge 連接時，即時事件會排隊在記憶體中
如果啟用了 Claude channel 模式，同一個 session 也可以接收 Claude 特有的推播通知

重要行為：

即時隊列狀態在 bridge 連接時開始
較舊的 transcript 歷史紀錄透過 messages_read 讀取
Claude 推播通知僅在 MCP session 存活時存在
當 client 斷開連接時，bridge 會退出且即時隊列也會消失

選擇 client 模式

你可以用兩種不同方式使用同一個 bridge：

通用 MCP client：僅限標準 MCP 工具。使用 conversations_list, messages_read, events_poll, events_wait, messages_send 以及審核工具。
Claude Code：標準 MCP 工具加上 Claude 特有的 channel adapter。啟用 --claude-channel-mode on 或保留預設的 auto。

目前 auto 的行為與 on 相同。現在還沒有 client 功能偵測機制。

`serve` 指令提供了什麼

這個 bridge 利用現有的 Gateway session 路由元數據（metadata）來呈現由 channel 支援的對話。當 OpenClaw 已經擁有具備已知路由的 session 狀態時，對話就會出現，例如：

channel
接收者或目的地的元數據
選填的 accountId
選填的 threadId

這讓 MCP client 有一個統一的地方可以：

列出最近有路由的對話
讀取最近的對話紀錄
等待新的傳入事件
透過相同的路由回傳回覆
查看 bridge 連線期間到達的核准請求

使用方式

# Local Gateway
openclaw mcp serve

# Remote Gateway
openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Remote Gateway with password auth
openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

# Enable verbose bridge logs
openclaw mcp serve --verbose

# Disable Claude-specific push notifications
openclaw mcp serve --claude-channel-mode off

Bridge 工具

目前的 bridge 提供以下 MCP tools：

conversations_list
conversation_get
messages_read
attachments_fetch
events_poll
events_wait
messages_send
permissions_list_open
permissions_respond

`conversations_list`

列出最近在 Gateway session 狀態中已有路由元數據的對話。

實用的篩選條件：

limit
search
channel
includeDerivedTitles
includeLastMessage

`conversation_get`

透過 session_key 回傳單一對話。

`messages_read`

讀取特定對話的最近訊息紀錄。

`attachments_fetch`

從訊息中提取非文字內容區塊。這是對對話內容的元數據視圖，而不是獨立的持久附件儲存空間。

`events_poll`

從特定的數字游標（cursor）開始讀取佇列中的即時事件。

`events_wait`

使用長輪詢（long-polling）直到下一個符合的事件到達或逾時。

當一般的 MCP client 需要近乎即時的傳輸，但又不使用 Claude 專屬的推送協定時，請使用這個工具。

`messages_send`

透過 session 中記錄的原有路由回傳文字。

目前的運作方式：

需要現有的對話路由
使用該 session 的 channel、接收者、帳號 ID 和執行緒 ID
僅傳送文字

`permissions_list_open`

列出 bridge 連接到 Gateway 後觀察到的待處理執行/外掛程式核准請求。

`permissions_respond`

處理一個待處理的執行/外掛程式核准請求，選項包括：

allow-once
allow-always
deny

事件模型

bridge 在連線期間會維護一個記憶體內的事件佇列。

目前的事件類型：

message
exec_approval_requested
exec_approval_resolved
plugin_approval_requested
plugin_approval_resolved
claude_permission_request

重要限制：

佇列僅限即時內容；它在 MCP bridge 啟動時才開始運作
events_poll 和 events_wait 本身不會重播舊的 Gateway 歷史紀錄
持久的積壓訊息（backlog）應該透過 messages_read 來讀取

Claude 頻道通知

這個 bridge 也可以提供 Claude 特有的頻道通知。這相當於 OpenClaw 版本的 Claude Code 頻道轉接器：標準的 MCP tools 依然可用，但即時的進站訊息（inbound messages）也會以 Claude 特有的 MCP 通知形式送達。

Flags：

--claude-channel-mode off: 僅限標準 MCP tools
--claude-channel-mode on: 啟用 Claude 頻道通知
--claude-channel-mode auto: 目前的預設值；行為與 on 相同

當啟用 Claude 頻道模式時，伺服器會宣告 Claude 實驗性功能，並可以發送：

notifications/claude/channel
notifications/claude/channel/permission

目前的 bridge 行為：

進站的 user 對話紀錄訊息會被轉發為 notifications/claude/channel
透過 MCP 接收到的 Claude 權限請求會被記錄在記憶體中
如果連結的對話隨後傳送了 yes abcde 或 no abcde，bridge 會將其轉換為 notifications/claude/channel/permission
這些通知僅限於即時連線（live-session）；如果 MCP client 斷線，就沒有推送目標了

這是刻意針對特定 client 設計的。一般的 MCP client 應該依賴標準的輪詢（polling）工具。

MCP client 設定

stdio client 設定範例：

{
  "mcpServers": {
    "openclaw": {
      "command": "openclaw",
      "args": [
        "mcp",
        "serve",
        "--url",
        "wss://gateway-host:18789",
        "--token-file",
        "/path/to/gateway.token"
      ]
    }
  }
}

對於大多數通用的 MCP client，建議先從標準的 tool 介面開始，並忽略 Claude 模式。只有在 client 確實理解 Claude 特有的通知方法時，才開啟 Claude 模式。

選項

openclaw mcp serve 支援：

--url <url>: Gateway WebSocket URL
--token <token>: Gateway token
--token-file <path>: 從檔案讀取 token
--password <password>: Gateway 密碼
--password-file <path>: 從檔案讀取密碼
--claude-channel-mode <auto|on|off>: Claude 通知模式
-v, --verbose: 在 stderr 輸出詳細日誌

如果可以的話，建議優先使用 --token-file 或 --password-file，而不是直接把密鑰寫在指令裡。

安全與信任邊界

這個 bridge 不會自己發明路由規則，它只會顯示 Gateway 已經知道如何路由的對話。

這代表：

傳送者白名單、配對以及頻道層級的信任設定，仍然屬於底層 OpenClaw 頻道的配置
messages_send 只能透過現有的儲存路由進行回覆
授權狀態僅在當前 bridge session 的記憶體中生效
bridge 的認證應該使用你信任其他遠端 Gateway client 的相同 Gateway token 或密碼控制

如果你在 conversations_list 中找不到某個對話，通常不是 MCP 設定的問題，而是底層 Gateway session 缺少或路由元數據（metadata）不完整。

測試

OpenClaw 針對這個 bridge 內建了一個確定性的 Docker smoke 測試：

pnpm test:docker:mcp-channels

這個 smoke 測試會執行以下動作：

啟動一個帶有初始資料的 Gateway 容器
啟動第二個容器並執行 openclaw mcp serve
驗證對話發現、逐字稿讀取、附件 metadata 讀取、即時事件隊列行為，以及外發傳送路由
透過真實的 stdio MCP bridge 驗證 Claude 風格的 channel 與權限通知

這是證明 bridge 正常運作最快的方法，你不需要在測試過程中串接真實的 Telegram、Discord 或 iMessage 帳號。

關於更廣泛的測試背景，請參考 Testing。

疑難排解

沒有回傳任何對話

這通常代表 Gateway session 還無法路由。請確認底層 session 已經儲存了 channel/provider、收件者，以及選填的 account/thread 路由 metadata。

`events_poll` 或 `events_wait` 漏掉舊訊息

這是正常現象。即時隊列是在 bridge 連接時才開始運作。如果你要讀取舊的逐字稿歷史，請使用 messages_read。

Claude 通知沒有顯示

請檢查以下幾點：

用戶端是否保持 stdio MCP session 開啟
--claude-channel-mode 設定為 on 或 auto
用戶端是否真的支援 Claude 特有的通知方法
傳入訊息是否發生在 bridge 連接之後

找不到審批請求

permissions_list_open 只會顯示 bridge 連接期間觀察到的審批請求。它並不是一個持久化的審批歷史 API。

OpenClaw 作為 MCP client 註冊表

這是 openclaw mcp list、show、set 和 unset 的操作路徑。

這些指令並非透過 MCP 公開 OpenClaw，而是用來管理 OpenClaw 設定檔中 mcp.servers 底下的 MCP server 定義。

這些儲存的定義是給 OpenClaw 稍後啟動或設定的 runtime 使用的，例如內嵌的 Pi 或其他 runtime 轉接器。OpenClaw 集中儲存這些定義，這樣那些 runtime 就不需要各自維護重複的 MCP server 清單。

重要行為：

這些指令只會讀取或寫入 OpenClaw 設定檔
它們不會連線到目標 MCP server
它們不會驗證指令、URL 或遠端傳輸目前是否可用
runtime 轉接器會在執行時才決定實際支援哪些傳輸形式

已儲存的 MCP server 定義

OpenClaw 也會在設定檔中儲存一個輕量級的 MCP server 註冊表，供需要 OpenClaw 管理 MCP 定義的介面使用。

指令：

openclaw mcp list
openclaw mcp show [name]
openclaw mcp set <name> <json>
openclaw mcp unset <name>

範例：

openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp set docs '{"url":"https://mcp.example.com"}'
openclaw mcp unset context7

範例設定結構：

{
  "mcp": {
    "servers": {
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      },
      "docs": {
        "url": "https://mcp.example.com"
      }
    }
  }
}

Stdio 傳輸

啟動本地子程序並透過 stdin/stdout 通訊。

欄位	描述
`command`	要啟動的可執行檔（必填）
`args`	命令列參數陣列
`env`	額外的環境變數
`cwd` / `workingDirectory`	程序的當前工作目錄

SSE / HTTP 傳輸

透過 HTTP Server-Sent Events 連線到遠端 MCP server。

欄位	描述
`url`	遠端 server 的 HTTP 或 HTTPS URL（必填）
`headers`	選填的 HTTP headers 鍵值對（例如 auth tokens）
`connectionTimeout`	每個 server 的連線逾時時間，單位為 ms（選填）

範例：

{
  "mcp": {
    "servers": {
      "remote-tools": {
        "url": "https://mcp.example.com",
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

URL 中的敏感數值（userinfo）和 headers 在 log 與狀態輸出中都會被遮蔽。

Streamable HTTP 傳輸

streamable-http 是除了 sse 和 stdio 之外的額外傳輸選項。它使用 HTTP 串流與遠端 MCP server 進行雙向通訊。

欄位	描述
`url`	遠端 server 的 HTTP 或 HTTPS URL（必填）
`transport`	設定為 `"streamable-http"` 以選擇此傳輸方式
`headers`	選填的 HTTP headers 鍵值對（例如 auth tokens）
`connectionTimeout`	每個 server 的連線逾時時間，單位為 ms（選填）

範例：

{
  "mcp": {
    "servers": {
      "streaming-tools": {
        "url": "https://mcp.example.com/stream",
        "transport": "streamable-http",
        "connectionTimeout": 10000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

這些指令僅管理儲存的設定。它們不會啟動 channel bridge、開啟即時的 MCP client session，也不會證明目標 server 是可連線的。

目前限制

本頁面記錄了目前版本所提供的 bridge 功能。

目前限制：

對話發現（conversation discovery）取決於現有的 Gateway session 路由元數據
除了 Claude 專用的轉接器外，目前沒有通用的 push 協定
尚未支援訊息編輯或反應（react）工具
HTTP/SSE/streamable-http 傳輸僅連線到單一遠端 server；目前還沒有多路複用（multiplexed）的上游
permissions_list_open 僅包含在 bridge 連線期間觀察到的核准項目

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。