MCP

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

​

選擇正確的 MCP 路徑

​

OpenClaw 作為 MCP 伺服器

​

何時使用 serve

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

​

運作方式

​

選擇用戶端模式

​

serve 暴露的內容

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

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

​

用法

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

​

橋接工具

​

事件模型

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

​

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 用戶端設定

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

​

選項

​

安全性與信任邊界

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

​

測試

pnpm test:docker:mcp-channels

​

疑難排解

​

OpenClaw 作為 MCP 用戶端登錄

​

已儲存的 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 執行階段。另一個處理程序中的閘道或 agent 處理程序仍需要自己的重新載入或重新啟動路徑。
• 對 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 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

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 輸出形狀

{
  "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 credentials are not authorized; run 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 傳輸

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

​

OAuth 工作流程

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

openclaw mcp login docs

openclaw mcp login docs --code abc123

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

openclaw mcp logout docs

​

Streamable HTTP 傳輸

{
  "mcp": {
    "servers": {
      "streaming-tools": {
        "url": "https://mcp.example.com/stream",
        "transport": "streamable-http",
        "connectTimeout": 10,
        "timeout": 30,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

​

控制 UI

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

• 命令片段會引用伺服器名稱，讓不尋常的名稱仍可在 shell 中複製使用
• 顯示的類 URL 值若包含嵌入式憑證，會在轉譯前先經過遮蔽
• 此頁面本身不會啟動 MCP 傳輸
• 作用中的執行階段可能需要 openclaw mcp reload、閘道設定發布或程序重新啟動，取決於哪個程序擁有 MCP 用戶端

​

目前限制

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

​

相關

• 命令列介面參考
• 外掛