MCP

openclaw mcp có hai nhiệm vụ:

• chạy OpenClaw dưới dạng máy chủ MCP với openclaw mcp serve
• quản lý các định nghĩa máy chủ MCP đi ra do OpenClaw quản lý bằng list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload, và unset

Nói cách khác:

• serve là OpenClaw hoạt động như một máy chủ MCP
• các lệnh con khác là OpenClaw hoạt động như một registry phía máy khách MCP cho các máy chủ MCP mà runtime của nó có thể dùng sau này

Dùng openclaw acp khi OpenClaw cần tự lưu trữ một phiên coding harness và định tuyến runtime đó qua ACP.

Chọn đường dẫn MCP phù hợp

OpenClaw có nhiều bề mặt MCP. Chọn bề mặt khớp với bên sở hữu runtime agent và bên sở hữu công cụ.

OpenClaw dưới dạng máy chủ MCP

Đây là đường dẫn openclaw mcp serve.

Khi nào dùng serve

Dùng openclaw mcp serve khi:

• Codex, Claude Code, hoặc một máy khách MCP khác cần nói chuyện trực tiếp với các cuộc hội thoại kênh được OpenClaw hỗ trợ
• bạn đã có một OpenClaw Gateway cục bộ hoặc từ xa với các phiên đã định tuyến
• bạn muốn một máy chủ MCP hoạt động trên các backend kênh của OpenClaw thay vì chạy các cầu nối riêng cho từng kênh

Thay vào đó, dùng openclaw acp khi OpenClaw cần tự lưu trữ runtime coding và giữ phiên agent bên trong OpenClaw.

Cách hoạt động

openclaw mcp serve khởi động một máy chủ MCP stdio. Máy khách MCP sở hữu tiến trình đó. Khi máy khách giữ phiên stdio mở, cầu nối kết nối đến một OpenClaw Gateway cục bộ hoặc từ xa qua WebSocket và phơi bày các cuộc hội thoại kênh đã định tuyến qua MCP.

Chọn chế độ máy khách

Dùng cùng một cầu nối theo hai cách khác nhau:

serve phơi bày những gì

Cầu nối dùng metadata định tuyến phiên Gateway hiện có để phơi bày các cuộc hội thoại được kênh hỗ trợ. Một cuộc hội thoại xuất hiện khi OpenClaw đã có trạng thái phiên với tuyến đã biết như:

• channel
• metadata người nhận hoặc đích
• accountId tùy chọn
• threadId tùy chọn

Điều này cung cấp cho máy khách MCP một nơi để:

• liệt kê các cuộc hội thoại đã định tuyến gần đây
• đọc lịch sử bản ghi gần đây
• chờ sự kiện đến mới
• gửi phản hồi trở lại qua cùng tuyến
• xem các yêu cầu phê duyệt đến khi cầu nối đang kết nối

Cách dùng

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

Công cụ cầu nối

Cầu nối hiện tại phơi bày các công cụ MCP này:

Mô hình sự kiện

Cầu nối giữ một hàng đợi sự kiện trong bộ nhớ khi nó đang kết nối.

Các loại sự kiện hiện tại:

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

Thông báo kênh Claude

Cầu nối cũng có thể phơi bày thông báo kênh dành riêng cho Claude. Đây là tương đương trong OpenClaw của một adapter kênh Claude Code: các công cụ MCP tiêu chuẩn vẫn khả dụng, nhưng tin nhắn trực tiếp đến cũng có thể xuất hiện dưới dạng thông báo MCP dành riêng cho Claude.

Khi chế độ kênh Claude được bật, máy chủ quảng bá các khả năng thử nghiệm Claude và có thể phát ra:

• notifications/claude/channel
• notifications/claude/channel/permission

Hành vi cầu nối hiện tại:

• tin nhắn bản ghi user đến được chuyển tiếp dưới dạng notifications/claude/channel
• các yêu cầu quyền Claude nhận qua MCP được theo dõi trong bộ nhớ
• nếu chủ sở hữu lệnh trong cuộc hội thoại đã liên kết sau đó gửi yes abcde hoặc no abcde, cầu nối chuyển đổi nội dung đó thành notifications/claude/channel/permission
• các thông báo này chỉ dành cho phiên trực tiếp; nếu máy khách MCP ngắt kết nối, không còn đích đẩy

Điều này được thiết kế riêng cho máy khách. Máy khách MCP chung nên dựa vào các công cụ polling tiêu chuẩn.

Cấu hình máy khách MCP

Ví dụ cấu hình máy khách stdio:

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

Với hầu hết máy khách MCP chung, hãy bắt đầu với bề mặt công cụ tiêu chuẩn và bỏ qua chế độ Claude. Chỉ bật chế độ Claude cho các máy khách thực sự hiểu các phương thức thông báo dành riêng cho Claude.

Tùy chọn

openclaw mcp serve hỗ trợ:

Bảo mật và ranh giới tin cậy

Cầu nối không tự tạo định tuyến. Nó chỉ hiển thị những cuộc trò chuyện mà Gateway đã biết cách định tuyến.

Điều đó có nghĩa là:

• danh sách cho phép người gửi, ghép nối và độ tin cậy cấp kênh vẫn thuộc về cấu hình kênh OpenClaw bên dưới
• messages_send chỉ có thể trả lời qua một tuyến đã lưu hiện có
• trạng thái phê duyệt chỉ hoạt động trực tiếp/trong bộ nhớ cho phiên cầu nối hiện tại
• xác thực cầu nối nên dùng cùng các kiểm soát token hoặc mật khẩu Gateway mà bạn sẽ tin cậy cho bất kỳ máy khách Gateway từ xa nào khác

Nếu một cuộc trò chuyện bị thiếu trong conversations_list, nguyên nhân thường không phải là cấu hình MCP. Đó là siêu dữ liệu tuyến bị thiếu hoặc chưa đầy đủ trong phiên Gateway bên dưới.

Kiểm thử

OpenClaw cung cấp một Docker smoke xác định cho cầu nối này:

pnpm test:docker:mcp-channels

Smoke đó:

• khởi động một container Gateway đã gieo dữ liệu
• khởi động một container thứ hai để sinh openclaw mcp serve
• xác minh việc khám phá cuộc trò chuyện, đọc bản ghi hội thoại, đọc siêu dữ liệu tệp đính kèm, hành vi hàng đợi sự kiện trực tiếp và định tuyến gửi đi
• xác thực thông báo kênh và quyền kiểu Claude qua cầu nối MCP stdio thật

Đây là cách nhanh nhất để chứng minh cầu nối hoạt động mà không cần nối tài khoản Telegram, Discord hoặc iMessage thật vào lượt chạy kiểm thử.

Để biết thêm ngữ cảnh kiểm thử rộng hơn, xem Kiểm thử.

Khắc phục sự cố

OpenClaw dưới dạng sổ đăng ký máy khách MCP

Đây là đường dẫn openclaw mcp list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload và unset.

Các lệnh này không hiển thị OpenClaw qua MCP. Chúng quản lý các định nghĩa máy chủ MCP do OpenClaw quản lý bên dưới mcp.servers trong cấu hình OpenClaw. Chúng không đọc máy chủ mcporter từ config/mcporter.json.

Các định nghĩa đã lưu đó dành cho những môi trường chạy mà OpenClaw khởi chạy hoặc cấu hình về sau, chẳng hạn như OpenClaw nhúng và các bộ điều hợp môi trường chạy khác. OpenClaw lưu trữ các định nghĩa tập trung để các môi trường chạy đó không cần giữ danh sách máy chủ MCP trùng lặp riêng.

Các bộ điều hợp môi trường chạy có thể chuẩn hóa sổ đăng ký dùng chung này thành dạng mà máy khách hạ nguồn của chúng mong đợi. Ví dụ, OpenClaw nhúng tiêu thụ trực tiếp các giá trị transport của OpenClaw, trong khi Claude Code và Gemini nhận các giá trị type gốc CLI như http, sse hoặc stdio.

Codex app-server cũng tôn trọng một khối codex tùy chọn trên mỗi máy chủ. Đây là siêu dữ liệu chiếu của OpenClaw chỉ dành cho các luồng Codex app-server; nó không thay đổi phiên ACP, cấu hình harness Codex chung hoặc các bộ điều hợp môi trường chạy khác. Dùng codex.agents không rỗng để chỉ chiếu một máy chủ vào các id tác tử OpenClaw cụ thể. Danh sách tác tử rỗng, trống hoặc không hợp lệ bị cấu hình xác thực từ chối và bị đường dẫn chiếu runtime bỏ qua thay vì trở thành toàn cục. Dùng codex.defaultToolsApprovalMode (auto, prompt hoặc approve) để phát ra default_tools_approval_mode gốc của Codex cho một máy chủ đáng tin cậy. OpenClaw loại bỏ siêu dữ liệu codex trước khi chuyển giao cấu hình mcp_servers gốc cho Codex.

Định nghĩa máy chủ MCP đã lưu

OpenClaw cũng lưu một sổ đăng ký máy chủ MCP gọn nhẹ trong cấu hình cho các bề mặt muốn dùng định nghĩa MCP do OpenClaw quản lý.

Lệnh:

• 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>

Ghi chú:

• list sắp xếp tên máy chủ.
• show không có tên sẽ in toàn bộ đối tượng máy chủ MCP đã cấu hình.
• status phân loại các transport đã cấu hình mà không kết nối. --verbose bao gồm chi tiết khởi chạy, thời gian chờ, OAuth, bộ lọc và lệnh gọi song song đã phân giải.
• doctor thực hiện kiểm tra tĩnh mà không kết nối. Thêm --probe khi lệnh cũng cần xác minh rằng các máy chủ đã bật có thể kết nối.
• probe kết nối và báo cáo số lượng công cụ, hỗ trợ tài nguyên/prompt, hỗ trợ thay đổi danh sách và chẩn đoán.
• add chấp nhận các cờ stdio như --command, --arg, --env và --cwd, hoặc các cờ HTTP như --url, --transport, --header, --auth oauth, TLS, thời gian chờ và cờ chọn công cụ.
• set mong đợi một giá trị đối tượng JSON trên dòng lệnh.
• configure cập nhật trạng thái bật, bộ lọc công cụ, thời gian chờ, OAuth, TLS và gợi ý lệnh gọi công cụ song song mà không thay thế toàn bộ định nghĩa máy chủ.
• tools cập nhật bộ lọc công cụ theo từng máy chủ. Mục include/exclude là tên công cụ MCP và glob * đơn giản.
• login chạy luồng OAuth cho máy chủ HTTP đã cấu hình với auth: "oauth". Lần chạy đầu tiên in ra URL ủy quyền; chạy lại với --code sau khi phê duyệt.
• logout xóa thông tin xác thực OAuth đã lưu cho máy chủ được đặt tên mà không xóa định nghĩa máy chủ đã lưu.
• reload giải phóng các môi trường chạy MCP trong tiến trình đã lưu trong bộ nhớ đệm. Các tiến trình Gateway hoặc tác tử trong một tiến trình khác vẫn cần đường dẫn reload hoặc khởi động lại riêng.
• Dùng transport: "streamable-http" cho máy chủ MCP Streamable HTTP. openclaw mcp set cũng chuẩn hóa type: "http" gốc CLI về cùng dạng cấu hình chuẩn để tương thích.
• unset thất bại nếu máy chủ được đặt tên không tồn tại.

Ví dụ:

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

Công thức máy chủ phổ biến

Các ví dụ này chỉ lưu định nghĩa máy chủ. Chạy openclaw mcp doctor --probe sau đó để chứng minh rằng máy chủ khởi động và hiển thị công cụ.

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

Dạng đầu ra JSON

Sử dụng --json cho script và dashboard. Tập trường có thể mở rộng theo thời gian, vì vậy các consumer nên bỏ qua khóa không xác định.

{  "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": false,  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "ok": false,      "issues": [        {          "level": "error",          "message": "OAuth credentials are not authorized; run openclaw mcp login docs"        }      ]    }  ]}

{  "path": "/home/user/.openclaw/openclaw.json",  "generatedAt": "2026-05-31T09:00:00.000Z",  "servers": {    "docs": {      "launch": "streamable-http https://mcp.example.com/mcp",      "tools": 2,      "resources": true,      "prompts": false,      "listChanged": {        "tools": true,        "resources": false,        "prompts": false      }    }  },  "tools": ["docs__read_page", "docs__search"],  "diagnostics": []}

Ví dụ dạng cấu hình:

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

Transport stdio

Khởi chạy tiến trình con cục bộ và giao tiếp qua stdin/stdout.

Transport SSE / HTTP

Kết nối tới máy chủ MCP từ xa qua HTTP Server-Sent Events.

Ví dụ:

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

Các giá trị nhạy cảm trong url (userinfo) và headers được biên tập trong log và đầu ra trạng thái. openclaw mcp doctor cảnh báo khi các mục headers hoặc env trông giống dữ liệu nhạy cảm chứa giá trị dạng văn bản trực tiếp, để operator có thể chuyển các giá trị đó ra khỏi cấu hình đã commit.

Quy trình OAuth

OAuth dành cho các máy chủ MCP HTTP quảng bá luồng OAuth MCP. Header Authorization tĩnh bị bỏ qua cho một máy chủ khi auth: "oauth" được bật.

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 --verboseopenclaw mcp doctor docs --probe

openclaw mcp logout docs

Nếu provider xoay vòng token hoặc trạng thái ủy quyền bị kẹt, hãy chạy openclaw mcp logout <name>, rồi lặp lại login. logout có thể xóa thông tin xác thực cho một máy chủ HTTP đã lưu ngay cả sau khi auth: "oauth" đã bị gỡ khỏi cấu hình, miễn là tên máy chủ và URL vẫn xác định mục kho lưu trữ thông tin xác thực.

Transport HTTP có thể stream

streamable-http là tùy chọn transport bổ sung bên cạnh sse và stdio. Nó sử dụng HTTP streaming để giao tiếp hai chiều với máy chủ MCP từ xa.

Cấu hình OpenClaw sử dụng transport: "streamable-http" làm cách viết chuẩn. Các giá trị MCP CLI-native type: "http" được chấp nhận khi lưu qua openclaw mcp set và được sửa bởi openclaw doctor --fix trong cấu hình hiện có, nhưng transport là thứ OpenClaw nhúng tiêu thụ trực tiếp.

Ví dụ:

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

Control UI

Control UI trên trình duyệt bao gồm một trang cài đặt MCP chuyên dụng tại /mcp. Trang này hiển thị số lượng máy chủ đã cấu hình, tóm tắt bật/OAuth/bộ lọc, hàng transport theo từng máy chủ, điều khiển bật/tắt, các lệnh CLI phổ biến, và trình chỉnh sửa có phạm vi cho phần cấu hình mcp.

Sử dụng trang này cho chỉnh sửa của operator và kiểm kê nhanh. Sử dụng openclaw mcp doctor --probe hoặc openclaw mcp probe khi bạn cần bằng chứng máy chủ trực tiếp.

Quy trình operator:

1. Mở Giao diện điều khiển và chọn MCP.
2. Xem lại các thẻ tóm tắt cho tổng số máy chủ, máy chủ đã bật, OAuth và máy chủ đã lọc.
3. Sử dụng từng hàng máy chủ để xem gợi ý về transport, xác thực, bộ lọc, thời gian chờ và lệnh.
4. Bật/tắt enablement khi bạn muốn giữ một định nghĩa nhưng loại trừ định nghĩa đó khỏi quá trình khám phá runtime.
5. Chỉnh sửa phần cấu hình mcp theo phạm vi cho các thay đổi cấu trúc như máy chủ mới, header, TLS, metadata OAuth hoặc bộ lọc công cụ.
6. Chọn Lưu để chỉ lưu cấu hình, hoặc Lưu & Xuất bản để áp dụng thông qua đường dẫn cấu hình Gateway.
7. Chạy openclaw mcp doctor --probe khi bạn cần bằng chứng trực tiếp rằng máy chủ đã chỉnh sửa khởi động và liệt kê công cụ.

Ghi chú:

• các đoạn lệnh đặt tên máy chủ trong dấu ngoặc kép để những tên bất thường vẫn có thể sao chép vào shell
• các giá trị giống URL được hiển thị sẽ được biên tập trước khi render khi chúng chứa thông tin xác thực được nhúng
• trang này không tự khởi động các transport MCP
• các runtime đang hoạt động có thể cần openclaw mcp reload, xuất bản cấu hình Gateway hoặc khởi động lại tiến trình, tùy thuộc vào tiến trình nào sở hữu các client MCP

Giới hạn hiện tại

Trang này ghi lại bridge như được phát hành hiện nay.

Giới hạn hiện tại:

• khám phá cuộc trò chuyện phụ thuộc vào metadata tuyến phiên Gateway hiện có
• chưa có giao thức push chung ngoài adapter dành riêng cho Claude
• chưa có công cụ chỉnh sửa tin nhắn hoặc phản ứng
• transport HTTP/SSE/streamable-http kết nối tới một máy chủ từ xa duy nhất; chưa có upstream ghép kênh
• permissions_list_open chỉ bao gồm các phê duyệt được quan sát trong khi bridge được kết nối

Liên quan

• Tham chiếu CLI
• Plugin