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> 是不含 l 的 5 個字母要求 ID），橋接器會將其轉換為 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 傳輸

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

SSE / HTTP 傳輸

透過 HTTP 伺服器傳送事件連線至遠端 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。只要伺服器名稱與 URL 仍可識別認證資訊儲存區項目，即使已從設定中移除 auth: "oauth"，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. 編輯限定範圍的 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 會在閘道連接埠加一的連接埠上啟動僅供沙箱使用的 HTTP(S) 監聽器（預設閘道為 18790）。控制介面會從該獨立來源載入 Apps；此監聽器絕不會提供控制介面、經驗證的閘道路由或使用者資料。

直接連線至閘道時，需要能存取這兩個連接埠。若反向 Proxy 或 TLS 終止器對外提供控制介面，請為 Apps 指定專用的公開來源，並且只將該來源 Proxy 到沙箱監聽器：

{  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 只會在啟用 Apps 時宣告 io.modelcontextprotocol/ui 擴充功能。
• 只有 MIME 類型完全符合 text/html;profile=mcp-app 的 ui:// 資源會被算繪。
• UI 資源上限為 2 MiB，會置於專用外層來源上的雙 iframe Proxy 後方，載入至不透明的內層 App 來源，並受根據資源中繼資料衍生的 CSP 約束。
• 僅供 App 使用的工具（_meta.ui.visibility: ["app"]）不會出現在模型工具清單中。Apps 只能呼叫其所屬伺服器上對 App 可見的工具。
• 當內層 App 文件使用不透明來源進行跨 App 隔離時，不會授予攝影機、麥克風和地理位置等綁定來源的 App 權限。
• App HTML、完整工具引數與原始結果會保存在有界限的十分鐘記憶體內檢視租約中。它們不會寫入磁碟或複製到逐字稿預覽中繼資料，而且過期的檢視不會重新啟動其 MCP 執行階段。
• 啟用橋接器時，openclaw security audit 會發出警告。不需要時，請使用 openclaw config set mcp.apps.enabled false --strict-json 停用。

目前限制

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

目前限制：

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

相關內容

• 命令列介面參考
• 外掛