MCP

openclaw mcp 有兩項用途：

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

serve 是作為 MCP 伺服器運作的 OpenClaw。其他子命令則是 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 專用頻道通知。這是 Claude Code 頻道轉接器的 OpenClaw 對應功能：標準 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、篩選器和平行呼叫詳細資訊。
• doctor 會在不建立連線的情況下執行靜態檢查。若命令也應驗證已啟用的伺服器能否連線，請加上 --probe。
• probe 會建立連線，並回報工具數量、資源／提示詞支援、清單變更支援及診斷資訊。
• add 接受 stdio 旗標，例如 --command、--arg、--env 和 --cwd；或 HTTP 旗標，例如 --url、--transport、--header、--auth oauth、TLS、逾時及工具選取旗標。
• 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,observe,click,type'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,        "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",        "timeout": 20,        "connectTimeout": 5,        "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 傳輸

啟動本機子程序，並透過標準輸入／標準輸出進行通訊。

SSE / HTTP 傳輸

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

範例：

{  "mcp": {    "servers": {      "remote-tools": {        "url": "https://mcp.example.com",        "auth": "oauth",        "timeout": 20,        "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 應用程式伺服器使用。

在認證資訊可用前，OpenClaw 只會從代理程式執行階段省略該 MCP 伺服器，而不會使代理程式回合失敗。操作人員或具有殼層存取權的代理程式之後可以執行 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",        "connectTimeout": 10,        "timeout": 30,        "headers": {          "Authorization": "Bearer <token>"        }      }    }  }}

控制介面

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

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

操作員工作流程：

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

注意事項：

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

MCP 應用程式

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

啟用主機橋接器：

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

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

直接連線至閘道時，必須能存取這兩個連接埠。如果反向 Proxy 或 TLS 終止器公開控制介面，請為應用程式提供專用的公開來源，且僅將該來源代理至沙箱接聽器：

{  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"],      },    },  },}

行為與安全界線：

• OpenClaw 僅在啟用應用程式時宣告 io.modelcontextprotocol/ui 擴充功能。
• 只有具有完全相符 text/html;profile=mcp-app MIME 類型的 ui:// 資源會被轉譯。
• UI 資源上限為 2 MiB，會置於專用外層來源的雙重 iframe Proxy 後方、載入至不透明的內層應用程式來源，並受從資源中繼資料衍生的 CSP 限制。
• 應用程式專用工具（_meta.ui.visibility: ["app"]）不會出現在模型工具清單中。應用程式只能呼叫其所屬伺服器上對應用程式可見，且通過建立該檢視之執行作業的有效 OpenClaw 工具原則的工具。
• 由於內層應用程式文件使用不透明來源來隔離不同應用程式，因此不會授予繫結至來源的應用程式權限，例如相機、麥克風和地理位置。
• 應用程式 HTML、完整工具引數和原始結果會存放在有界限的 10 分鐘記憶體內檢視租約中，不會寫入磁碟或複製到逐字稿預覽中繼資料。逐字稿僅儲存繫結至原始工具呼叫 ID 的有界限伺服器／工具／資源描述元。閘道重新啟動後，控制介面可以根據已驗證工作階段的逐字稿驗證該描述元，並重新擷取 ui:// 資源；重建的檢視為唯讀，直到新的執行作業建立目前的工具權限。
• 橋接器啟用時，openclaw security audit 會顯示警告。不需要時，請使用 openclaw config set mcp.apps.enabled false --strict-json 停用。

目前限制

本頁面記錄目前已發布橋接器的狀態。

目前限制：

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

相關內容

• 命令列介面參考
• 外掛