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。

選擇正確的 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.<name>.codex`	`codex` 區塊只會影響 Codex app-server 執行緒投射，並會在交接原生設定前移除。
執行由 ACP 託管的工具框架工作階段	`openclaw acp` 和 ACP 代理程式	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。

運作方式

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

用戶端產生橋接器

MCP 用戶端會產生 openclaw mcp serve。

橋接器連線至閘道

橋接器會透過 WebSocket 連線至 OpenClaw 閘道。

工作階段成為 MCP 對話

已路由的工作階段會成為 MCP 對話及逐字稿／歷程工具。

即時事件進入佇列

橋接器連線期間，即時事件會在記憶體中排入佇列。

選用的 Claude 推送

如果已啟用 Claude 頻道模式，同一工作階段也可以接收 Claude 專用推播通知。

重要行為

即時佇列狀態會在橋接器連線時開始
較舊的逐字稿歷程會使用 messages_read 讀取
Claude 推播通知只會在 MCP 工作階段存續期間存在
當用戶端中斷連線時，橋接器會結束，且即時佇列會消失
一次性的代理程式進入點（例如 openclaw agent 和 openclaw infer model run）會在回覆完成時終止其開啟的任何內建 MCP 執行階段，因此重複執行指令碼不會累積 stdio MCP 子程序
OpenClaw 啟動的 stdio MCP 伺服器（內建或使用者設定）會在關閉時以程序樹形式終止，因此伺服器啟動的子程序不會在父 stdio 用戶端結束後繼續存續
刪除或重設工作階段時，會透過共用的執行階段清理路徑處置該工作階段的 MCP 用戶端，因此不會留下與已移除工作階段相關聯的 stdio 連線

選擇用戶端模式

一般 MCP 用戶端
Claude Code

僅提供標準 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 用戶端可以在同一處：

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

使用方式

本機閘道
遠端閘道（權杖）
遠端閘道（密碼）
詳細輸出／關閉 Claude

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 --verbose
openclaw mcp serve --claude-channel-mode off

橋接工具

conversations_list

列出閘道工作階段狀態中已具有路由中繼資料、由工作階段支援的近期對話。篩選器：limit（上限 500）、search、channel、includeDerivedTitles、includeLastMessage。

conversation_get

使用直接的閘道工作階段查詢，依 session_key 傳回一個對話。

messages_read

讀取由工作階段支援之單一對話的近期逐字稿訊息。limit 預設為 20，上限為 200。

attachments_fetch

從一則逐字稿訊息中擷取非文字訊息內容區塊。這是逐字稿內容的中繼資料檢視，而不是獨立的持久附件二進位大型物件儲存區。

events_poll

讀取數值游標之後排入佇列的即時事件。limit 上限為 200。

events_wait

長輪詢，直到下一個相符的佇列事件抵達或逾時（預設 30s，上限 300s）。當一般 MCP 用戶端需要近乎即時的傳遞，而不使用 Claude 專用推送通訊協定時，請使用此工具。

messages_send

透過工作階段中已記錄的相同路由傳回文字。目前行為：

需要現有的對話路由
使用工作階段的頻道、收件者、帳戶 ID 和執行緒 ID
僅傳送文字

permissions_list_open

列出橋接器自連線至閘道以來觀察到的待處理執行／外掛核准要求。

permissions_respond

使用下列其中一項結果處理待處理的執行／外掛核准要求：

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 <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 支援：

string

閘道 WebSocket URL。設定後預設為 gateway.remote.url。

string

閘道權杖。

string

從檔案讀取權杖。

string

閘道密碼。

string

從檔案讀取密碼。

"auto" | "on" | "off"

Claude 通知模式。預設為 auto。

boolean

在 stderr 輸出詳細記錄。

可行時，請優先使用 --token-file 或 --password-file，而非行內密鑰。

安全性與信任邊界

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

傳送者允許清單、配對與頻道層級的信任仍由底層 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 帳號接入測試執行的情況下，證明橋接器可正常運作的最快方式。如需更廣泛的測試背景資訊，請參閱測試。

疑難排解

未傳回任何對話

通常表示閘道工作階段尚無法路由。請確認底層工作階段已儲存頻道／提供者、收件者，以及選用的帳號／討論串路由中繼資料。

events_poll 或 events_wait 遺漏較舊的訊息

這是預期行為。即時佇列會在橋接器連線時啟動。請使用 messages_read 讀取較舊的逐字稿歷程。

未顯示 Claude 通知

請檢查以下所有項目：

用戶端持續開啟 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 <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 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，以確認伺服器能啟動並公開工具。

檔案系統
記憶體
本機指令碼
遠端 HTTP
桌面/CUA

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-memory
openclaw 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.example
openclaw mcp status --verbose

doctor 會檢查 cwd 是否存在，以及該命令能否從已設定的環境中解析。

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。如果伺服器需要靜態標頭，請避免提交常值持有人權杖。

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。欄位集可能會隨時間增加，因此取用端應忽略未知的鍵。

status --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
    }
  ]
}

doctor --json

{
  "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 問題仍會回報，但其本身不會使命令失敗。

probe --json

{
  "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 證明可連線性與功能，而非用於靜態設定稽核。

設定格式範例：

{
  "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`	提示此伺服器可安全地進行並行呼叫

範例：

{
  "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 用戶端。

儲存伺服器

使用 auth: "oauth" 及任何選用的 OAuth 中繼資料新增或更新伺服器。

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

若要使用由認證設定檔支援的 Bearer 權杖，請儲存設定檔繫結：

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

開始登入

執行登入以建立授權要求。

openclaw mcp login docs

OpenClaw 會顯示授權 URL，並將暫時的 OAuth 驗證器狀態儲存在共用 SQLite 中。

使用代碼完成

在瀏覽器中核准後，將傳回的代碼交回 OpenClaw。

openclaw mcp login docs --code abc123

檢查授權

使用狀態或診斷工具確認權杖存在，且不需要額外授權。如果狀態回報 authorization-required，或診斷工具要求額外授權，請再次執行 openclaw mcp login <name>。

openclaw mcp status --verbose
openclaw mcp doctor docs --probe

清除認證資訊

登出會移除已儲存的 OAuth 認證資訊，但保留已儲存的伺服器定義。

openclaw mcp logout docs

如果提供者輪替權杖，或授權狀態卡住，請執行 openclaw mcp logout <name>，然後重複 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。範例：

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

登錄檔命令不會啟動通道橋接。只有 probe 和 doctor --probe 會開啟即時 MCP 用戶端工作階段，以驗證目標伺服器可連線。

控制介面

瀏覽器控制介面在 /settings/mcp 提供專用的 MCP 設定頁面；先前的 /mcp 路徑仍保留為別名。此頁面會顯示已設定伺服器數量、啟用/OAuth/篩選摘要、每部伺服器的傳輸列、啟用/停用控制項、常用命令列介面命令，以及 mcp 設定區段的限定範圍編輯器。此頁面適合操作員編輯及快速盤點。需要即時伺服器驗證時，請使用 openclaw mcp doctor --probe 或 openclaw mcp probe。操作員工作流程：

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

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Contributing

Release and CI

選擇正確的 MCP 路徑

將 OpenClaw 作為 MCP 伺服器

何時使用 serve

運作方式

選擇用戶端模式

serve 公開的內容

使用方式

橋接工具

事件模型

Claude 頻道通知

MCP 用戶端設定

選項

安全性與信任邊界

測試

疑難排解

將 OpenClaw 作為 MCP 用戶端登錄檔

已儲存的 MCP 伺服器定義

常見伺服器設定範例

JSON 輸出格式

Stdio 傳輸

SSE / HTTP 傳輸

OAuth 工作流程

可串流 HTTP 傳輸

控制介面

MCP Apps

目前限制

相關內容

​選擇正確的 MCP 路徑

​將 OpenClaw 作為 MCP 伺服器

​何時使用 serve

​運作方式

​選擇用戶端模式

​serve 公開的內容

​使用方式

​橋接工具

​事件模型

​Claude 頻道通知

​MCP 用戶端設定

​選項

​安全性與信任邊界

​測試

​疑難排解

​將 OpenClaw 作為 MCP 用戶端登錄檔

​已儲存的 MCP 伺服器定義

​常見伺服器設定範例

​JSON 輸出格式

​Stdio 傳輸

​SSE / HTTP 傳輸

​OAuth 工作流程

​可串流 HTTP 傳輸

​控制介面

​MCP Apps

​目前限制

​相關內容

選擇正確的 MCP 路徑

將 OpenClaw 作為 MCP 伺服器

何時使用 serve

運作方式

選擇用戶端模式

serve 公開的內容

使用方式

橋接工具

事件模型

Claude 頻道通知

MCP 用戶端設定

選項

安全性與信任邊界

測試

疑難排解

將 OpenClaw 作為 MCP 用戶端登錄檔

已儲存的 MCP 伺服器定義

常見伺服器設定範例

JSON 輸出格式

Stdio 傳輸

SSE / HTTP 傳輸

OAuth 工作流程

可串流 HTTP 傳輸

控制介面

MCP Apps

目前限制

相關內容