MCP

openclaw mcp 有兩項工作：

• 使用 openclaw mcp serve 將 OpenClaw 作為 MCP 伺服器執行
• 使用 list、show、status、doctor、probe、add、set、configure、tools、login、logout、reload 和 unset 管理 OpenClaw 所管理的對外 MCP 伺服器定義

serve 是由 OpenClaw 充當 MCP 伺服器。其他子命令則是由 OpenClaw 充當 MCP 用戶端側登錄檔，供其自身的執行階段稍後使用其中的伺服器。

若 OpenClaw 應自行託管程式設計工具框架工作階段，並透過 ACP 路由該執行階段，請使用 openclaw acp。

選擇正確的 MCP 路徑

將 OpenClaw 作為 MCP 伺服器

這是 openclaw mcp serve 路徑。

何時使用 serve

在下列情況下使用 openclaw mcp serve：

• Codex、Claude Code 或其他 MCP 用戶端應直接與 OpenClaw 支援的頻道對話通訊
• 你已經擁有具有路由工作階段的本機或遠端 OpenClaw 閘道
• 你想要一個可跨 OpenClaw 頻道後端運作的 MCP 伺服器，而不是為每個頻道分別執行橋接器

如果 OpenClaw 應自行託管程式設計執行階段，並將代理程式工作階段保留在 OpenClaw 內，請改用 openclaw acp。

運作方式

openclaw mcp serve 會啟動 stdio MCP 伺服器。MCP 用戶端擁有該程序。當用戶端保持 stdio 工作階段開啟時，橋接器會透過 WebSocket 連線至本機或遠端 OpenClaw 閘道，並透過 MCP 公開已路由的頻道對話。

選擇用戶端模式

serve 公開的內容

橋接器會使用現有的閘道工作階段路由中繼資料，公開由頻道支援的對話。當 OpenClaw 已具有包含已知路由的工作階段狀態時，對話就會出現，例如：

• channel
• 收件者或目的地中繼資料
• 選用的 accountId
• 選用的 threadId

這讓 MCP 用戶端可以在同一處：

• 列出最近已路由的對話
• 讀取最近的逐字稿歷程
• 等待新的傳入事件
• 透過相同路由傳送回覆
• 查看橋接器連線期間送達的核准要求

使用方式

openclaw mcp serve

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

openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

openclaw mcp serve --verboseopenclaw mcp serve --claude-channel-mode off

橋接工具

事件模型

橋接器在連線期間會維持記憶體內事件佇列。

目前的事件類型：

• message
• exec_approval_requested
• exec_approval_resolved
• plugin_approval_requested
• plugin_approval_resolved
• claude_permission_request

Claude 頻道通知

橋接器也可以公開 Claude 專用頻道通知。這相當於 OpenClaw 的 Claude Code 頻道轉接器：標準 MCP 工具仍然可用，但即時傳入訊息也能以 Claude 專用 MCP 通知的形式抵達。

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

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

目前的橋接器行為：

• 傳入的 user 逐字稿訊息會轉送為 notifications/claude/channel
• 透過 MCP 收到的 Claude 權限要求會在記憶體中追蹤
• 如果已連結對話中的命令擁有者稍後傳送 yes <id> 或 no <id>（<id> 是 5 個字母的要求 ID，不含 l），橋接器會將其轉換為 notifications/claude/channel/permission
• 這些通知僅限即時工作階段；如果 MCP 用戶端中斷連線，就沒有推送目標

這是刻意為特定用戶端設計的。一般 MCP 用戶端應依賴標準輪詢工具。

MCP 用戶端設定

stdio 用戶端設定範例：

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

對於大多數通用 MCP 用戶端，請從標準工具介面開始，並忽略 Claude 模式。僅針對確實理解 Claude 專屬通知方法的用戶端開啟 Claude 模式。

選項

openclaw mcp serve 支援：

安全性與信任邊界

橋接器不會自行建立路由。它只會公開閘道已知如何路由的對話。

這表示：

• 傳送者允許清單、配對與頻道層級的信任仍由底層 OpenClaw 頻道設定負責
• messages_send 只能透過現有的已儲存路由回覆
• 核准狀態僅在目前橋接工作階段中即時存在於記憶體內
• 橋接驗證應使用你信任任何其他遠端閘道用戶端時所用的相同閘道權杖或密碼控制

如果 conversations_list 中缺少某個對話，常見原因並非 MCP 設定，而是底層閘道工作階段中的路由中繼資料缺失或不完整。

測試

OpenClaw 隨附此橋接器的確定性 Docker 煙霧測試：

pnpm test:docker:mcp-channels

此煙霧測試會執行單一容器：它會植入對話狀態、啟動閘道，接著以 stdio 子程序形式產生 openclaw mcp serve，並將其作為 MCP 用戶端驅動。它會透過實際的 stdio MCP 橋接器，驗證對話探索、逐字稿讀取、附件中繼資料讀取、即時事件佇列行為，以及 Claude 風格的頻道與權限通知。輸出傳送路由（messages_send 重複使用已儲存的對話路由）則由 src/mcp/channel-server.test.ts 中的單元測試另行涵蓋。

這是在不將真實 Telegram、Discord 或 iMessage 帳號接入測試執行的情況下，證明橋接器可正常運作的最快方式。

如需更廣泛的測試背景資訊，請參閱測試。

疑難排解

將 OpenClaw 作為 MCP 用戶端登錄檔

這是 openclaw mcp list、show、status、doctor、probe、add、set、 configure、tools、login、logout、reload 與 unset 路徑。

這些命令不會透過 MCP 公開 OpenClaw。它們會管理 OpenClaw 設定中 mcp.servers 下由 OpenClaw 管理的 MCP 伺服器定義。它們不會從 config/mcporter.json 讀取 mcporter 伺服器。

這些已儲存的定義供 OpenClaw 稍後啟動或設定的執行階段使用，例如內嵌 OpenClaw 與其他執行階段配接器。OpenClaw 會集中儲存這些定義，因此這些執行階段不需要各自維護重複的 MCP 伺服器清單。

執行階段配接器可將此共用登錄檔正規化為其下游用戶端預期的形式。例如，內嵌 OpenClaw 會直接使用 OpenClaw 的 transport 值，而 Claude Code 與 Gemini 則會收到命令列介面原生的 type 值，例如 http、sse 或 stdio。

Codex app-server 也會採用每個伺服器上選用的 codex 區塊。這是僅供 Codex app-server 討論串使用的 OpenClaw 投影中繼資料；它不會變更 ACP 工作階段、通用 Codex 控制框架設定或其他執行階段配接器。 使用非空白的 codex.agents，只將伺服器投影至特定 OpenClaw 代理程式 ID。設定驗證會拒絕空白、全空格或無效的代理程式清單， 而執行階段投影路徑也會將其省略，不會使其成為 全域設定。使用 codex.defaultToolsApprovalMode（auto、prompt 或 approve） 為可信任的伺服器發出 Codex 原生 default_tools_approval_mode。 OpenClaw 會先移除 codex 中繼資料，再將原生 mcp_servers 設定交給 Codex。

已儲存的 MCP 伺服器定義

命令：

• openclaw mcp list
• openclaw mcp show [name]
• openclaw mcp status [--verbose]
• openclaw mcp doctor [name] [--probe]
• openclaw mcp probe [name]
• openclaw mcp add <name> [flags]
• openclaw mcp set <name> <json>
• openclaw mcp configure <name> [flags]
• openclaw mcp tools <name> [--include csv] [--exclude csv] [--clear]
• openclaw mcp login <name> [--code code]
• openclaw mcp logout <name>
• openclaw mcp reload
• openclaw mcp unset <name>

注意事項：

• list 會排序伺服器名稱。
• 未指定名稱的 show 會輸出完整的已設定 MCP 伺服器物件。
• status 會在不連線的情況下分類已設定的傳輸。--verbose 包含解析後的啟動、逾時、OAuth、篩選器與平行呼叫詳細資料，包括已儲存 OAuth 權杖需要額外授權的情況。文字與 JSON 輸出中的含認證資訊 stdio 引數會經過遮蔽。
• doctor 會在不連線的情況下執行靜態檢查。若命令也應驗證已啟用的伺服器能否連線，請加入 --probe。
• probe 會連線並回報工具數量、資源／提示詞支援、清單變更支援與診斷資訊。
• add 接受 --command、--arg、--env 與 --cwd 等 stdio 旗標，或 --url、--transport、--header、--auth oauth、TLS、逾時與工具選取旗標等 HTTP 旗標。
• set 預期命令列上有一個 JSON 物件值。
• configure 會更新啟用狀態、工具篩選器、逾時、OAuth、TLS 與平行工具呼叫提示，而不會取代整個伺服器定義。加入 --probe 可在儲存前驗證更新後的伺服器。
• tools 會更新各伺服器的工具篩選器。包含／排除項目是 MCP 工具名稱與簡單的 * glob 模式。
• login 會針對使用 auth: "oauth" 設定的 HTTP 伺服器執行 OAuth 流程。第一次執行會輸出授權 URL；核准後，請使用 --code 重新執行。
• logout 會清除具名伺服器已儲存的 OAuth 認證資訊，而不移除已儲存的伺服器定義。
• reload 只會釋放目前命令列介面程序中快取的行程內 MCP 執行階段。其他程序中的閘道或代理程式程序仍需使用各自的重新載入或重新啟動路徑。
• Streamable HTTP MCP 伺服器請使用 transport: "streamable-http"。為了相容性，openclaw mcp set 也會將命令列介面原生的 type: "http" 正規化為相同的標準設定形式。
• 如果具名伺服器不存在，unset 會失敗。

範例：

openclaw mcp listopenclaw mcp show context7 --jsonopenclaw mcp status --verboseopenclaw mcp doctor --probeopenclaw mcp probe context7 --jsonopenclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memoryopenclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'openclaw mcp tools context7 --include 'resolve-library-id,get-library-docs'openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'openclaw mcp configure docs --timeout 20 --connect-timeout 5 --include 'search,read_*'openclaw mcp configure docs --auth oauth --oauth-scope 'docs.read'openclaw mcp login docsopenclaw mcp logout docsopenclaw mcp unset context7

常見伺服器設定範例

這些範例只會儲存伺服器定義。之後請執行 openclaw mcp doctor --probe，以確認伺服器能啟動並公開工具。

openclaw mcp add files \  --command npx \  --arg -y \  --arg @modelcontextprotocol/server-filesystem \  --arg "$HOME/Documents" \  --include 'read_file,list_directory,search_files'openclaw mcp doctor files --probe

openclaw mcp add memory \  --command npx \  --arg -y \  --arg @modelcontextprotocol/server-memoryopenclaw mcp probe memory --json

openclaw mcp add local-tools \  --command node \  --arg ./dist/mcp-server.js \  --cwd /srv/openclaw-tools \  --env API_BASE=https://internal.exampleopenclaw mcp status --verbose

openclaw mcp add docs \  --url https://mcp.example.com/mcp \  --transport streamable-http \  --auth oauth \  --oauth-scope docs.read \  --timeout 20 \  --connect-timeout 5 \  --include 'search,read_*'openclaw mcp doctor docs --probe

openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'openclaw mcp tools cua-driver --include 'list_apps,get_window_state,click,type_text'openclaw mcp doctor cua-driver --probe

JSON 輸出格式

指令碼與儀表板請使用 --json。欄位集可能會隨時間增加，因此取用端應忽略未知的鍵。

{  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "configured": true,      "enabled": true,      "ok": true,      "transport": "streamable-http",      "launch": "streamable-http https://mcp.example.com/mcp",      "auth": "oauth",      "authStatus": {        "hasTokens": true,        "requiresAuthorization": false,        "hasClientInformation": true,        "hasCodeVerifier": false,        "hasDiscoveryState": true,        "hasLastAuthorizationUrl": false      },      "requestTimeoutMs": 20000,      "connectionTimeoutMs": 5000,      "toolFilter": {        "include": ["search", "read_*"],        "exclude": []      },      "supportsParallelToolCalls": true    }  ]}

{  "ok": true,  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "ok": true,      "issues": [        {          "level": "warning",          "message": "OAuth 認證資訊尚未獲得授權；請執行 openclaw mcp login docs"        }      ]    }  ]}

{  "generatedAt": "2026-05-31T09:00:00.000Z",  "servers": {    "docs": {      "launch": "streamable-http https://mcp.example.com/mcp",      "tools": 2,      "resources": true,      "listChanged": {        "tools": true,        "resources": false,        "prompts": false      }    }  },  "tools": ["docs__read_page", "docs__search"],  "diagnostics": []}

設定格式範例：

{  "mcp": {    "servers": {      "context7": {        "command": "uvx",        "args": ["context7-mcp"]      },      "docs": {        "url": "https://mcp.example.com",        "transport": "streamable-http",        "requestTimeoutMs": 20000,        "connectionTimeoutMs": 5000,        "supportsParallelToolCalls": true,        "auth": "oauth",        "oauth": {          "scope": "docs.read"        },        "sslVerify": true,        "clientCert": "/path/to/client.crt",        "clientKey": "/path/to/client.key",        "toolFilter": {          "include": ["search_*"],          "exclude": ["admin_*"]        }      }    }  }}

Stdio 傳輸

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

SSE / HTTP 傳輸

透過 HTTP Server-Sent Events 連線至遠端 MCP 伺服器。

範例：

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

url（使用者資訊）與 headers 中的敏感值會在日誌和狀態輸出中遮蔽。當看似敏感的 headers 或 env 項目包含常值時，openclaw mcp doctor 會發出警告，讓操作人員能將這些值移出已提交的設定。

OAuth 工作流程

OAuth 適用於宣告 MCP OAuth 流程的 HTTP MCP 伺服器。啟用 auth: "oauth" 時，伺服器的靜態 Authorization 標頭會被忽略。由 openclaw mcp login 儲存的認證資訊可供內嵌 MCP、命令列介面執行器及本機 Codex 應用程式伺服器使用。

原生 MCP OAuth 工作階段位於 <state-dir>/state/openclaw.sqlite（mcp_oauth_stores）中僅限擁有者存取的共享 SQLite 資料庫。該資料列可包含存取與重新整理權杖、動態用戶端註冊密鑰、探索中繼資料及暫時的 PKCE 驗證器。重新整理、登入和登出會使用相同的 SQLite 租約，因此並行的 OpenClaw 程序無法取用同一個重新整理權杖，也無法讓已登出的工作階段復原。

從已淘汰的 <state-dir>/mcp-oauth/*.json 儲存區升級時，只會由 openclaw doctor --fix 處理。執行階段程式碼永遠不會讀取、寫入這些檔案，或退回使用這些檔案。

在認證資訊可用之前，OpenClaw 只會從代理程式執行階段略過該 MCP 伺服器，而不會使代理程式回合失敗。接著，操作人員或具備 shell 存取權的代理程式可以執行 openclaw mcp login <name>，並在後續回合使用該伺服器。

如果伺服器以 insufficient_scope 拒絕權杖，OpenClaw 會保留要求的範圍並要求 openclaw mcp login <name>，而不會重複無法授予新範圍的重新整理作業。該登入會啟動新的授權要求，同時保留先前的權杖，直到替代認證資訊儲存完成。

當遠端 MCP 服務已由另一個支援重新整理的 OpenClaw 驗證設定檔提供時，可以選擇設定 oauth.authProfileId。OpenClaw 會在投射至執行階段前重新整理任一認證資訊來源，並且只將目前的存取權杖傳遞給下游 MCP 用戶端。

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"authProfileId":"docs:mcp"}}'

openclaw mcp login docs

openclaw mcp login docs --code abc123

openclaw mcp status --verboseopenclaw mcp doctor docs --probe

openclaw mcp logout docs

如果提供者輪替權杖，或授權狀態卡住，請執行 openclaw mcp logout <name>，然後重複 login。即使已從設定中移除 auth: "oauth"，只要伺服器名稱與 URL 仍能識別認證資訊儲存區項目，logout 仍可清除已儲存 HTTP 伺服器的認證資訊。

可串流 HTTP 傳輸

streamable-http 是與 sse 和 stdio 並列的額外傳輸選項。它使用 HTTP 串流與遠端 MCP 伺服器進行雙向通訊。

OpenClaw 設定以 transport: "streamable-http" 作為標準拼法。透過 openclaw mcp set 儲存時，會接受命令列介面原生 MCP 的 type: "http" 值，而現有設定中的值會由 openclaw doctor --fix 修復；但內嵌的 OpenClaw 會直接使用 transport。

範例：

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

控制介面

瀏覽器控制介面在 /settings/mcp 提供專用的 MCP 設定頁面；先前的 /mcp 路徑仍保留為別名。此頁面會顯示已設定伺服器數量、啟用/OAuth/篩選摘要、每部伺服器的傳輸列、啟用/停用控制項、常用命令列介面命令，以及 mcp 設定區段的限定範圍編輯器。

此頁面適合操作員編輯及快速盤點。需要即時伺服器驗證時，請使用 openclaw mcp doctor --probe 或 openclaw mcp probe。

操作員工作流程：

1. 開啟控制介面並選擇 MCP。
2. 檢視摘要卡片中的伺服器總數、已啟用、OAuth 及已篩選數量。
3. 使用各伺服器列查看傳輸、驗證、篩選、逾時及命令提示。
4. 若要保留定義但將其排除於執行階段探索之外，請切換啟用狀態。
5. 編輯限定範圍的 mcp 設定區段，以進行新增伺服器、標頭、TLS、OAuth 中繼資料或工具篩選器等結構性變更。
6. 選擇 Save 僅儲存設定，或選擇 Save & Publish 透過閘道設定路徑套用。
7. 需要即時驗證已編輯的伺服器可啟動並列出工具時，請執行 openclaw mcp doctor --probe。

注意事項：

• 命令片段會將伺服器名稱加上引號，使不常見的名稱仍可複製到殼層中
• 顯示的類 URL 值若含有內嵌認證資訊，會在轉譯前遮蔽
• 此頁面本身不會啟動 MCP 傳輸
• 視哪個處理程序擁有 MCP 用戶端而定，作用中的執行階段可能需要 openclaw mcp reload、發布閘道設定或重新啟動處理程序

MCP Apps

OpenClaw 可轉譯實作穩定版 MCP Apps 擴充功能的工具。Apps 採選擇性啟用，因為其 HTML 來自已設定的 MCP 伺服器，且可向同一部伺服器要求 App 可見的工具或資源。

啟用主機橋接：

openclaw config set mcp.apps.enabled true --strict-json

變更此設定後，請重新啟動閘道。啟用後，OpenClaw 會在閘道連接埠加一的位置（預設閘道為 18790）啟動僅供沙箱使用的 HTTP(S) 接聽程式。控制介面會從該獨立來源載入 Apps；此接聽程式絕不提供控制介面、已驗證的閘道路由或使用者資料。

直接閘道連線需要存取這兩個連接埠。如果反向代理或 TLS 終止程式公開控制介面，請為 Apps 提供專用的公開來源，並且只將該來源代理至沙箱接聽程式：

{  mcp: {    apps: {      enabled: true,      sandboxOrigin: "https://mcp-apps.example.com",      sandboxPort: 18790,    },  },}

沙箱來源必須與控制介面來源不同。請勿在其上託管其他已驗證或敏感內容。

例如，官方基本 React 示範可設定為：

{  mcp: {    apps: { enabled: true },    servers: {      "basic-react": {        command: "npx",        args: ["-y", "@modelcontextprotocol/server-basic-react", "--stdio"],      },    },  },}

行為與安全界線：

• 只有在啟用 Apps 時，OpenClaw 才會公告 io.modelcontextprotocol/ui 擴充功能。
• 只有具備完全相符 text/html;profile=mcp-app MIME 類型的 ui:// 資源才會轉譯。
• UI 資源上限為 2 MiB，會放置在專用外層來源的雙 iframe 代理之後、載入至不透明的內層 App 來源，並受依資源中繼資料衍生的 CSP 限制。
• 僅限 App 的工具（_meta.ui.visibility: ["app"]）不會出現在模型工具清單中。Apps 只能呼叫其所屬伺服器上 App 可見，且同時通過建立該檢視之執行作業的有效 OpenClaw 工具政策的工具。
• 當內層 App 文件使用不透明來源以隔離不同 App 時，不會授予攝影機、麥克風及地理位置等繫結至來源的 App 權限。
• App HTML、完整工具引數及原始結果會存在於有界的十分鐘記憶體內檢視租約中，不會寫入磁碟或複製到逐字稿預覽中繼資料。逐字稿只會儲存繫結至原始工具呼叫 ID 的有界伺服器/工具/資源描述元。閘道重新啟動後，控制介面可根據已驗證的工作階段逐字稿驗證該描述元，並重新擷取 ui:// 資源；在新的執行作業建立目前工具權限前，重建的檢視為唯讀。
• 在通道對話中，某一輪最新成功的 App 檢視會在最終助理回覆中新增一個 開啟 App 樣式的動作。Telegram 私訊使用原生 Mini App 按鈕；Slack 與 Discord 會將相同的可攜式動作轉譯為連結。其他通道會保留原始回覆文字，並附加易於理解的 HTTPS 連結。
• 只有在閘道 Tailscale 公開功能已準備好已發布的 HTTPS 來源時，才能使用通道啟動連結。gateway.tailscale.mode: "serve" 只能從 tailnet 存取；"funnel" 可從公用網際網路存取。由 gateway.tailscale.preserveFunnel 保留並由外部管理的 Funnel 也會視為可從網際網路存取。請參閱 Tailscale。
• 啟動票證是不透明的，只會在具體化最終通道回覆時簽發，並且最多在兩分鐘後或基礎檢視租約到期時失效，以較早者為準。URL 不含閘道 Bearer 認證資訊、工作階段金鑰、檢視中繼資料、App HTML、工具輸入或工具結果。
• 如果沒有可用的已發布來源或票證容量、檢視或票證已過期，或傳輸無法轉譯原生控制項，仍可使用原始助理文字。控制介面會保留其現有的行內 App 畫布，且不會收到重複的啟動動作。
• openclaw security audit 會在橋接啟用時發出警告。不需要時，請使用 openclaw config set mcp.apps.enabled false --strict-json 停用。

目前限制

本頁記錄目前隨產品提供的橋接功能。

目前限制：

• 對話探索依賴現有的閘道工作階段路由中繼資料
• 除了 Claude 專用配接器外，沒有通用推送協定
• 目前尚無訊息編輯或回應工具
• HTTP/SSE/streamable-http 傳輸會連線至單一遠端伺服器；目前尚無多工上游
• permissions_list_open 僅包含橋接連線期間觀察到的核准

相關內容

• 命令列介面參考
• 外掛