> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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 用戶端側登錄檔，供其自身的執行階段稍後使用其中的伺服器。 `list`、`show`、`set` 和 `unset` 只會讀寫 OpenClaw 設定中由 OpenClaw 管理的 `mcp.servers` 項目。它們不包含 `config/mcporter.json` 中的 mcporter 伺服器；該登錄檔請使用 `mcporter list`。 若 OpenClaw 應自行託管程式設計工具框架工作階段，並透過 ACP 路由該執行階段，請使用 [`openclaw acp`](/zh-TW/cli/acp)。 ## 選擇正確的 MCP 路徑 | 目標 | 使用 | 原因 | | ------------------------------------ | ---------------------------------------------------------------------------- | ---------------------------------------------------- | | 讓外部 MCP 用戶端讀取／傳送 OpenClaw 頻道對話 | `openclaw mcp serve` | OpenClaw 是 MCP 伺服器，並透過 stdio 公開由閘道支援的對話。 | | 儲存第三方 MCP 伺服器，供 OpenClaw 管理的代理程式執行使用 | `openclaw mcp add`、`set`、`configure`、`tools`、`login` | OpenClaw 是 MCP 用戶端側登錄檔，稍後會將這些伺服器投射至符合資格的執行階段。 | | 在不執行代理程式回合的情況下檢查已儲存的伺服器 | `openclaw mcp status`、`doctor`、`probe` | `status` 和 `doctor` 會檢查設定；`probe` 會開啟即時 MCP 連線並列出功能。 | | 從瀏覽器編輯 MCP 設定 | 控制介面 `/settings/mcp`（`/mcp` 別名） | 此頁面會顯示清單、啟用狀態、OAuth／篩選器摘要、命令提示，以及限定範圍的 `mcp` 編輯器。 | | 為 Codex app-server 提供限定範圍的原生 MCP 伺服器 | `mcp.servers..codex` | `codex` 區塊只會影響 Codex app-server 執行緒投射，並會在交接原生設定前移除。 | | 執行由 ACP 託管的工具框架工作階段 | [`openclaw acp`](/zh-TW/cli/acp) 和 [ACP 代理程式](/zh-TW/tools/acp-agents-setup) | ACP 橋接模式不接受逐工作階段注入 MCP 伺服器；請改為設定閘道／外掛橋接。 | 如果不確定需要哪一條路徑，請先使用 `openclaw mcp status --verbose`。它會顯示 OpenClaw 已儲存的內容，而不會啟動任何 MCP 伺服器。 ## 將 OpenClaw 作為 MCP 伺服器 這是 `openclaw mcp serve` 路徑。 ### 何時使用 serve 在下列情況下使用 `openclaw mcp serve`： * Codex、Claude Code 或其他 MCP 用戶端應直接與 OpenClaw 支援的頻道對話通訊 * 你已經擁有具有路由工作階段的本機或遠端 OpenClaw 閘道 * 你想要一個可跨 OpenClaw 頻道後端運作的 MCP 伺服器，而不是為每個頻道分別執行橋接器 如果 OpenClaw 應自行託管程式設計執行階段，並將代理程式工作階段保留在 OpenClaw 內，請改用 [`openclaw acp`](/zh-TW/cli/acp)。 ### 運作方式 `openclaw mcp serve` 會啟動 stdio MCP 伺服器。MCP 用戶端擁有該程序。當用戶端保持 stdio 工作階段開啟時，橋接器會透過 WebSocket 連線至本機或遠端 OpenClaw 閘道，並透過 MCP 公開已路由的頻道對話。 MCP 用戶端會產生 `openclaw mcp serve`。 橋接器會透過 WebSocket 連線至 OpenClaw 閘道。 已路由的工作階段會成為 MCP 對話及逐字稿／歷程工具。 橋接器連線期間，即時事件會在記憶體中排入佇列。 如果已啟用 Claude 頻道模式，同一工作階段也可以接收 Claude 專用推播通知。 * 即時佇列狀態會在橋接器連線時開始 * 較舊的逐字稿歷程會使用 `messages_read` 讀取 * Claude 推播通知只會在 MCP 工作階段存續期間存在 * 當用戶端中斷連線時，橋接器會結束，且即時佇列會消失 * 一次性的代理程式進入點（例如 `openclaw agent` 和 `openclaw infer model run`）會在回覆完成時終止其開啟的任何內建 MCP 執行階段，因此重複執行指令碼不會累積 stdio MCP 子程序 * OpenClaw 啟動的 stdio MCP 伺服器（內建或使用者設定）會在關閉時以程序樹形式終止，因此伺服器啟動的子程序不會在父 stdio 用戶端結束後繼續存續 * 刪除或重設工作階段時，會透過共用的執行階段清理路徑處置該工作階段的 MCP 用戶端，因此不會留下與已移除工作階段相關聯的 stdio 連線 ### 選擇用戶端模式 僅提供標準 MCP 工具。請使用 `conversations_list`、`messages_read`、`events_poll`、`events_wait`、`messages_send` 以及核准工具。 提供標準 MCP 工具及 Claude 專用頻道轉接器。啟用 `--claude-channel-mode on`，或保留預設值 `auto`。 目前，`auto` 的行為與 `on` 相同。目前尚無用戶端功能偵測。 ### serve 公開的內容 橋接器會使用現有的閘道工作階段路由中繼資料，公開由頻道支援的對話。當 OpenClaw 已具有包含已知路由的工作階段狀態時，對話就會出現，例如： * `channel` * 收件者或目的地中繼資料 * 選用的 `accountId` * 選用的 `threadId` 這讓 MCP 用戶端可以在同一處： * 列出最近已路由的對話 * 讀取最近的逐字稿歷程 * 等待新的傳入事件 * 透過相同路由傳送回覆 * 查看橋接器連線期間送達的核准要求 ### 使用方式 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw mcp serve ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw mcp serve --verbose openclaw mcp serve --claude-channel-mode off ``` ### 橋接工具 列出閘道工作階段狀態中已具有路由中繼資料、由工作階段支援的近期對話。 篩選器：`limit`（上限 500）、`search`、`channel`、`includeDerivedTitles`、`includeLastMessage`。 使用直接的閘道工作階段查詢，依 `session_key` 傳回一個對話。 讀取由工作階段支援之單一對話的近期逐字稿訊息。`limit` 預設為 20，上限為 200。 從一則逐字稿訊息中擷取非文字訊息內容區塊。這是逐字稿內容的中繼資料檢視，而不是獨立的持久附件二進位大型物件儲存區。 讀取數值游標之後排入佇列的即時事件。`limit` 上限為 200。 長輪詢，直到下一個相符的佇列事件抵達或逾時（預設 30s，上限 300s）。 當一般 MCP 用戶端需要近乎即時的傳遞，而不使用 Claude 專用推送通訊協定時，請使用此工具。 透過工作階段中已記錄的相同路由傳回文字。 目前行為： * 需要現有的對話路由 * 使用工作階段的頻道、收件者、帳戶 ID 和執行緒 ID * 僅傳送文字 列出橋接器自連線至閘道以來觀察到的待處理執行／外掛核准要求。 使用下列其中一項結果處理待處理的執行／外掛核准要求： * `allow-once` * `allow-always` * `deny` ### 事件模型 橋接器在連線期間會維持記憶體內事件佇列。 目前的事件類型： * `message` * `exec_approval_requested` * `exec_approval_resolved` * `plugin_approval_requested` * `plugin_approval_resolved` * `claude_permission_request` - 此佇列僅供即時使用；它會在 MCP 橋接器啟動時開始 - `events_poll` 和 `events_wait` 本身不會重播較舊的閘道歷程 - 持久待處理項目應使用 `messages_read` 讀取 ### Claude 頻道通知 橋接器也可以公開 Claude 專用頻道通知。這相當於 OpenClaw 的 Claude Code 頻道轉接器：標準 MCP 工具仍然可用，但即時傳入訊息也能以 Claude 專用 MCP 通知的形式抵達。 `--claude-channel-mode off`：僅提供標準 MCP 工具。 `--claude-channel-mode on`：啟用 Claude 頻道通知。 `--claude-channel-mode auto`：目前的預設值；橋接器行為與 `on` 相同。 啟用 Claude 頻道模式時，伺服器會宣告 Claude 實驗性功能，並可發出： * `notifications/claude/channel` * `notifications/claude/channel/permission` 目前的橋接器行為： * 傳入的 `user` 逐字稿訊息會轉送為 `notifications/claude/channel` * 透過 MCP 收到的 Claude 權限要求會在記憶體中追蹤 * 如果已連結對話中的命令擁有者稍後傳送 `yes ` 或 `no `（`` 是 5 個字母的要求 ID，不含 `l`），橋接器會將其轉換為 `notifications/claude/channel/permission` * 這些通知僅限即時工作階段；如果 MCP 用戶端中斷連線，就沒有推送目標 這是刻意為特定用戶端設計的。一般 MCP 用戶端應依賴標準輪詢工具。 ### MCP 用戶端設定 stdio 用戶端設定範例： ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "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` 支援： 閘道 WebSocket URL。設定後預設為 `gateway.remote.url`。 閘道權杖。 從檔案讀取權杖。 閘道密碼。 從檔案讀取密碼。 Claude 通知模式。預設為 `auto`。 在 stderr 輸出詳細記錄。 可行時，請優先使用 `--token-file` 或 `--password-file`，而非行內密鑰。 ### 安全性與信任邊界 橋接器不會自行建立路由。它只會公開閘道已知如何路由的對話。 這表示： * 傳送者允許清單、配對與頻道層級的信任仍由底層 OpenClaw 頻道設定負責 * `messages_send` 只能透過現有的已儲存路由回覆 * 核准狀態僅在目前橋接工作階段中即時存在於記憶體內 * 橋接驗證應使用你信任任何其他遠端閘道用戶端時所用的相同閘道權杖或密碼控制 如果 `conversations_list` 中缺少某個對話，常見原因並非 MCP 設定，而是底層閘道工作階段中的路由中繼資料缺失或不完整。 ### 測試 OpenClaw 隨附此橋接器的確定性 Docker 煙霧測試： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} pnpm test:docker:mcp-channels ``` 此煙霧測試會執行單一容器：它會植入對話狀態、啟動閘道，接著以 stdio 子程序形式產生 `openclaw mcp serve`，並將其作為 MCP 用戶端驅動。它會透過實際的 stdio MCP 橋接器，驗證對話探索、逐字稿讀取、附件中繼資料讀取、即時事件佇列行為，以及 Claude 風格的頻道與權限通知。輸出傳送路由（`messages_send` 重複使用已儲存的對話路由）則由 `src/mcp/channel-server.test.ts` 中的單元測試另行涵蓋。 這是在不將真實 Telegram、Discord 或 iMessage 帳號接入測試執行的情況下，證明橋接器可正常運作的最快方式。 如需更廣泛的測試背景資訊，請參閱[測試](/zh-TW/help/testing)。 ### 疑難排解 通常表示閘道工作階段尚無法路由。請確認底層工作階段已儲存頻道／提供者、收件者，以及選用的帳號／討論串路由中繼資料。 這是預期行為。即時佇列會在橋接器連線時啟動。請使用 `messages_read` 讀取較舊的逐字稿歷程。 請檢查以下所有項目： * 用戶端持續開啟 stdio MCP 工作階段 * `--claude-channel-mode` 為 `on` 或 `auto` * 用戶端確實理解 Claude 專屬通知方法 * 傳入訊息是在橋接器連線後發生 `permissions_list_open` 僅顯示橋接器連線期間觀察到的核准要求。它不是持久性核准歷程 API。 ## 將 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 設定 * `status`、`list`、`show`、不含 `--probe` 的 `doctor`、`set`、`configure`、`tools`、`logout`、`reload` 與 `unset` 不會連線至目標 MCP 伺服器 * `login` 會為已設定的 HTTP 伺服器執行 MCP OAuth 網路流程，並儲存產生的本機認證資訊 * `status --verbose` 會在不連線的情況下，輸出解析後的傳輸、驗證、逾時、篩選器與平行工具呼叫提示 * `doctor` 會檢查已儲存的定義是否有本機設定問題，例如缺少 stdio 命令、無效的工作目錄、缺少 TLS 檔案、已停用的伺服器、敏感標頭／環境變數的常值，以及未完成的 OAuth 授權 * 靜態檢查通過後，`doctor --probe` 會加入與 `probe` 相同的即時連線驗證 * `probe` 會連線至所選伺服器或所有已設定的伺服器、列出工具，並回報功能／診斷資訊 * `add` 會根據旗標建立定義，並在儲存前進行探查，除非已設定 `--no-probe` 或必須先完成 OAuth 授權 * 執行階段配接器會在執行時決定其實際支援的傳輸形式 * `enabled: false` 會保留已儲存的伺服器，但將其排除於內嵌執行階段探索之外 * `requestTimeoutMs` 與 `connectionTimeoutMs` 會以毫秒設定各伺服器的要求與連線逾時 * `supportsParallelToolCalls: true` 會標記配接器可並行呼叫的伺服器 * HTTP 伺服器可使用靜態標頭、OAuth 登入、TLS 驗證控制，以及 mTLS 憑證／金鑰路徑 * 內嵌 OpenClaw 會在一般 `coding` 與 `messaging` 工具設定檔中公開已設定的 MCP 工具；`minimal` 仍會將其隱藏，而 `tools.deny: ["bundle-mcp"]` 會明確停用它們 * 各伺服器的 `toolFilter.include` 與 `toolFilter.exclude` 會在探索到的 MCP 工具成為 OpenClaw 工具前加以篩選 * 宣告資源或提示詞的伺服器，也會公開用於列出／讀取資源及列出／擷取提示詞的公用工具；這些產生的公用工具名稱（`resources_list`、`resources_read`、`prompts_list`、`prompts_get`）會使用相同的包含／排除篩選器 * 動態 MCP 工具清單變更會使該工作階段的快取目錄失效；下次探索／使用時會從伺服器重新整理 * 重複發生 MCP 工具要求／通訊協定失敗時，會短暫暫停該伺服器，避免單一故障伺服器耗盡整個回合 * 工作階段範圍內的隨附 MCP 執行階段會在閒置 10 分鐘後回收，而單次內嵌執行會在執行結束時清除它們 執行階段配接器可將此共用登錄檔正規化為其下游用戶端預期的形式。例如，內嵌 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 [flags]` * `openclaw mcp set ` * `openclaw mcp configure [flags]` * `openclaw mcp tools [--include csv] [--exclude csv] [--clear]` * `openclaw mcp login [--code code]` * `openclaw mcp logout ` * `openclaw mcp reload` * `openclaw mcp unset ` 注意事項： * `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` 會失敗。 範例： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw mcp list openclaw mcp show context7 --json openclaw mcp status --verbose openclaw mcp doctor --probe openclaw mcp probe context7 --json openclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memory openclaw 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 docs openclaw mcp logout docs openclaw mcp unset context7 ``` ### 常見伺服器設定範例 這些範例只會儲存伺服器定義。之後請執行 `openclaw mcp doctor --probe`，以確認伺服器能啟動並公開工具。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ``` 將檔案系統伺服器的範圍限制在代理程式應讀取或編輯的最小目錄樹。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw mcp add memory \ --command npx \ --arg -y \ --arg @modelcontextprotocol/server-memory openclaw mcp probe memory --json ``` 如果伺服器公開了不應提供給一般代理程式的寫入工具，請使用工具篩選器。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw mcp add local-tools \ --command node \ --arg ./dist/mcp-server.js \ --cwd /srv/openclaw-tools \ --env API_BASE=https://internal.example openclaw mcp status --verbose ``` `doctor` 會檢查 `cwd` 是否存在，以及該命令能否從已設定的環境中解析。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ``` 遠端伺服器支援 OAuth 時，請使用 OAuth。如果伺服器需要靜態標頭，請避免提交常值持有人權杖。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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`。欄位集可能會隨時間增加，因此取用端應忽略未知的鍵。 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "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 } ] } ``` ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "ok": true, "path": "/home/user/.openclaw/openclaw.json", "servers": [ { "name": "docs", "ok": true, "issues": [ { "level": "warning", "message": "OAuth 認證資訊尚未獲得授權；請執行 openclaw mcp login docs" } ] } ] } ``` 任何已啟用且受檢查的伺服器出現 `error` 層級的問題時，`doctor --json` 會以非零狀態結束。`warning` 與 `info` 問題仍會回報，但其本身不會使命令失敗。 ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "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": [] } ``` `probe --json` 會開啟即時 MCP 用戶端工作階段並直接列印結果；不同於 `status`/`doctor`，輸出沒有頂層 `path` 欄位。只有在伺服器實際宣告該功能時，才會出現 `resources` 與 `prompts` 鍵（沒有提示功能的伺服器會省略 `prompts` 鍵，而不是回報 `false`）。請使用 `probe` 證明可連線性與功能，而非用於靜態設定稽核。 設定格式範例： ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "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 通訊。 | 欄位 | 說明 | | -------------------------- | ------------ | | `command` | 要啟動的可執行檔（必要） | | `args` | 命令列引數陣列 | | `env` | 額外的環境變數 | | `cwd` / `workingDirectory` | 程序的工作目錄 | **Stdio 環境變數安全篩選器** OpenClaw 在啟動 stdio MCP 伺服器前，會拒絕直譯器啟動、載入器劫持及 shell 初始化環境變數鍵，即使它們出現在伺服器的 `env` 區塊中也一樣。這會使用與其他由 OpenClaw 啟動之程序相同的主機環境安全性政策：封鎖已知的直譯器啟動掛鉤（例如 `NODE_OPTIONS`、`PYTHONSTARTUP`、`PERL5OPT`、`RUBYOPT`、`BASHOPTS`、`KSH_ENV`）、共享程式庫與函式注入前綴（`DYLD_*`、`LD_*`、`BASH_FUNC_*`），以及類似的執行階段控制變數。啟動時會悄悄捨棄這些變數並記錄警告，使其無法對 stdio 程序注入隱含的前置程式碼、替換直譯器、啟用偵錯工具或劫持動態連結器。明確的允許清單會保留一般 MCP 認證資訊環境變數的可用性（`GITHUB_TOKEN`、`GH_TOKEN`、`GITLAB_TOKEN`、`NPM_TOKEN`、`NODE_AUTH_TOKEN`、`DATABASE_URL`、`MONGODB_URI`、`REDIS_URL`、`AMQP_URL`、`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`、`AWS_SESSION_TOKEN`、`AZURE_CLIENT_ID`、`AZURE_CLIENT_SECRET`），以及一般的 Proxy 與伺服器專用環境變數（`HTTP_PROXY`、自訂 `*_API_KEY` 等）。其他 `AWS_*` 鍵（例如 `AWS_CONFIG_FILE` 與 `AWS_SHARED_CREDENTIALS_FILE`）仍會遭到封鎖，因為它們指向認證資訊檔案，而不是直接攜帶認證資訊值。 如果你的 MCP 伺服器確實需要其中一個遭封鎖的變數，請在閘道主機程序上設定，而不要設定在 stdio 伺服器的 `env` 下。 ### SSE / HTTP 傳輸 透過 HTTP Server-Sent Events 連線至遠端 MCP 伺服器。 | 欄位 | 說明 | | --------------------------- | ------------------------------------------- | | `url` | 遠端伺服器的 HTTP 或 HTTPS URL（必要） | | `headers` | 選用的 HTTP 標頭鍵值對映射（例如驗證權杖） | | `connectionTimeoutMs` | 每個伺服器的連線逾時時間，單位為毫秒（選用） | | `requestTimeoutMs` | 每個伺服器的 MCP 要求逾時時間，單位為毫秒 | | `auth: "oauth"` | 使用由 `openclaw mcp login` 儲存的 MCP OAuth 認證資訊 | | `sslVerify` | 僅針對明確信任的私人 HTTPS 端點設為 false | | `clientCert` / `clientKey` | mTLS 用戶端憑證與金鑰路徑 | | `supportsParallelToolCalls` | 提示此伺服器可安全地進行並行呼叫 | 範例： ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "mcp": { "servers": { "remote-tools": { "url": "https://mcp.example.com", "auth": "oauth", "requestTimeoutMs": 20000, "headers": { "Authorization": "Bearer " } } } } } ``` `url`（使用者資訊）與 `headers` 中的敏感值會在日誌和狀態輸出中遮蔽。當看似敏感的 `headers` 或 `env` 項目包含常值時，`openclaw mcp doctor` 會發出警告，讓操作人員能將這些值移出已提交的設定。 ### OAuth 工作流程 OAuth 適用於宣告 MCP OAuth 流程的 HTTP MCP 伺服器。啟用 `auth: "oauth"` 時，伺服器的靜態 `Authorization` 標頭會被忽略。由 `openclaw mcp login` 儲存的認證資訊可供內嵌 MCP、命令列介面執行器及本機 Codex 應用程式伺服器使用。 原生 MCP OAuth 工作階段位於 `/state/openclaw.sqlite`（`mcp_oauth_stores`）中僅限擁有者存取的共享 SQLite 資料庫。該資料列可包含存取與重新整理權杖、動態用戶端註冊密鑰、探索中繼資料及暫時的 PKCE 驗證器。重新整理、登入和登出會使用相同的 SQLite 租約，因此並行的 OpenClaw 程序無法取用同一個重新整理權杖，也無法讓已登出的工作階段復原。 從已淘汰的 `/mcp-oauth/*.json` 儲存區升級時，只會由 `openclaw doctor --fix` 處理。執行階段程式碼永遠不會讀取、寫入這些檔案，或退回使用這些檔案。 在認證資訊可用之前，OpenClaw 只會從代理程式執行階段略過該 MCP 伺服器，而不會使代理程式回合失敗。接著，操作人員或具備 shell 存取權的代理程式可以執行 `openclaw mcp login `，並在後續回合使用該伺服器。 如果伺服器以 `insufficient_scope` 拒絕權杖，OpenClaw 會保留要求的範圍並要求 `openclaw mcp login `，而不會重複無法授予新範圍的重新整理作業。該登入會啟動新的授權要求，同時保留先前的權杖，直到替代認證資訊儲存完成。 當遠端 MCP 服務已由另一個支援重新整理的 OpenClaw 驗證設定檔提供時，可以選擇設定 `oauth.authProfileId`。OpenClaw 會在投射至執行階段前重新整理任一認證資訊來源，並且只將目前的存取權杖傳遞給下游 MCP 用戶端。 使用 `auth: "oauth"` 及任何選用的 OAuth 中繼資料新增或更新伺服器。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}' ``` 若要使用由認證設定檔支援的 Bearer 權杖，請儲存設定檔繫結： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"authProfileId":"docs:mcp"}}' ``` 執行登入以建立授權要求。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw mcp login docs ``` OpenClaw 會顯示授權 URL，並將暫時的 OAuth 驗證器狀態儲存在共用 SQLite 中。 在瀏覽器中核准後，將傳回的代碼交回 OpenClaw。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw mcp login docs --code abc123 ``` 使用狀態或診斷工具確認權杖存在，且不需要額外授權。如果狀態回報 `authorization-required`，或診斷工具要求額外授權，請再次執行 `openclaw mcp login `。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw mcp status --verbose openclaw mcp doctor docs --probe ``` 登出會移除已儲存的 OAuth 認證資訊，但保留已儲存的伺服器定義。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw mcp logout docs ``` 如果提供者輪替權杖，或授權狀態卡住，請執行 `openclaw mcp logout `，然後重複 `login`。即使已從設定中移除 `auth: "oauth"`，只要伺服器名稱與 URL 仍能識別認證資訊儲存區項目，`logout` 仍可清除已儲存 HTTP 伺服器的認證資訊。 ### 可串流 HTTP 傳輸 `streamable-http` 是與 `sse` 和 `stdio` 並列的額外傳輸選項。它使用 HTTP 串流與遠端 MCP 伺服器進行雙向通訊。 | 欄位 | 說明 | | --------------------------- | --------------------------------------------------- | | `url` | 遠端伺服器的 HTTP 或 HTTPS URL（必填） | | `transport` | 設為 `"streamable-http"` 以選取此傳輸；省略時，OpenClaw 使用 `sse` | | `headers` | 選用的 HTTP 標頭鍵值對映射（例如驗證權杖） | | `connectionTimeoutMs` | 每部伺服器的連線逾時時間，單位為毫秒（選填） | | `requestTimeoutMs` | 每部伺服器的 MCP 要求逾時時間，單位為毫秒 | | `auth: "oauth"` | 使用由 `openclaw mcp login` 儲存的 MCP OAuth 認證資訊 | | `sslVerify` | 只有明確信任的私人 HTTPS 端點才可設為 false | | `clientCert` / `clientKey` | mTLS 用戶端憑證與金鑰路徑 | | `supportsParallelToolCalls` | 表示此伺服器可安全地進行並行呼叫 | OpenClaw 設定以 `transport: "streamable-http"` 作為標準拼法。透過 `openclaw mcp set` 儲存時，會接受命令列介面原生 MCP 的 `type: "http"` 值，而現有設定中的值會由 `openclaw doctor --fix` 修復；但內嵌的 OpenClaw 會直接使用 `transport`。 範例： ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "mcp": { "servers": { "streaming-tools": { "url": "https://mcp.example.com/stream", "transport": "streamable-http", "connectionTimeoutMs": 10000, "requestTimeoutMs": 30000, "headers": { "Authorization": "Bearer " } } } } } ``` 登錄檔命令不會啟動通道橋接。只有 `probe` 和 `doctor --probe` 會開啟即時 MCP 用戶端工作階段，以驗證目標伺服器可連線。 ## 控制介面 瀏覽器控制介面在 `/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 擴充功能](https://modelcontextprotocol.io/extensions/apps)的工具。Apps 採選擇性啟用，因為其 HTML 來自已設定的 MCP 伺服器，且可向同一部伺服器要求 App 可見的工具或資源。 啟用主機橋接： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw config set mcp.apps.enabled true --strict-json ``` 變更此設定後，請重新啟動閘道。啟用後，OpenClaw 會在閘道連接埠加一的位置（預設閘道為 `18790`）啟動僅供沙箱使用的 HTTP(S) 接聽程式。控制介面會從該獨立來源載入 Apps；此接聽程式絕不提供控制介面、已驗證的閘道路由或使用者資料。 直接閘道連線需要存取這兩個連接埠。如果反向代理或 TLS 終止程式公開控制介面，請為 Apps 提供專用的公開來源，並且只將該來源代理至沙箱接聽程式： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { mcp: { apps: { enabled: true, sandboxOrigin: "https://mcp-apps.example.com", sandboxPort: 18790, }, }, } ``` 沙箱來源必須與控制介面來源不同。請勿在其上託管其他已驗證或敏感內容。 例如，官方基本 React 示範可設定為： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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](/zh-TW/gateway/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` 僅包含橋接連線期間觀察到的核准 ## 相關內容 * [命令列介面參考](/zh-TW/cli) * [外掛](/zh-TW/cli/plugins)