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 outbound do OpenClaw sở hữu bằng list, show, set, và unset

Nói cách khác:

• serve là OpenClaw hoạt động như một máy chủ MCP
• list / show / set / unset là OpenClaw hoạt động như một registry phía máy khách MCP cho các máy chủ MCP khác mà các runtime của nó có thể dùng về sau

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

# 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 bridge riêng cho từng kênh

Thay vào đó, dùng openclaw acp khi OpenClaw cần tự host coding runtime 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ở, bridge kết nối tới OpenClaw Gateway cục bộ hoặc từ xa qua WebSocket và cung cấp 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 bridge theo hai cách khác nhau:

# serve cung cấp những gì

Bridge dùng metadata định tuyến phiên Gateway hiện có để cung cấp 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 một route đã 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 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ử transcript gần đây
• chờ sự kiện inbound mới
• gửi phản hồi lại qua cùng route
• xem các yêu cầu phê duyệt đến khi bridge đ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 --verbose
openclaw mcp serve --claude-channel-mode off

# Công cụ bridge

Bridge hiện tại cung cấp các công cụ MCP sau:

# Mô hình sự kiện

Bridge giữ một hàng đợi sự kiện trong bộ nhớ khi đ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

Bridge cũng có thể cung cấp thông báo kênh riêng cho Claude. Đây là tương đương của OpenClaw với 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 inbound trực tiếp cũng có thể đến dưới dạng thông báo MCP riêng cho Claude.

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

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

Hành vi bridge hiện tại:

• các tin nhắn transcript inbound user đượ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 cuộc hội thoại được liên kết sau đó gửi yes abcde hoặc no abcde, bridge 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, sẽ không có đích đẩy

Điều này cố ý dành riêng cho máy khách. Các 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 riêng cho Claude.

# Tùy chọn

openclaw mcp serve hỗ trợ:

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

Bridge không tự tạo định tuyến. Nó chỉ cung cấp các cuộc hội thoại 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, pairing, và độ tin cậy cấp kênh vẫn thuộc về cấu hình kênh OpenClaw nền bên dưới
• messages_send chỉ có thể trả lời qua một route đã lưu hiện có
• trạng thái phê duyệt chỉ là trực tiếp/trong bộ nhớ cho phiên bridge hiện tại
• xác thực bridge 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 hội thoại thiếu trong conversations_list, nguyên nhân thường không phải là cấu hình MCP. Đó là metadata route bị thiếu hoặc chưa hoàn chỉnh trong phiên Gateway nền bên dưới.

# Kiểm thử

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

pnpm test:docker:mcp-channels

Smoke đó:

• khởi động một container Gateway đã seed
• khởi động một container thứ hai tạo openclaw mcp serve
• xác minh phát hiện cuộc hội thoại, đọc transcript, đọc metadata tệp đính kèm, hành vi hàng đợi sự kiện trực tiếp, và định tuyến gửi outbound
• xác thực thông báo kênh kiểu Claude và thông báo quyền qua bridge MCP stdio thật

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

Để biết 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 registry máy khách MCP

Đây là đường dẫn openclaw mcp list, show, set và unset.

Các lệnh này không phơi bày OpenClaw qua MCP. Chúng quản lý các định nghĩa máy chủ MCP do OpenClaw sở hữu trong mcp.servers thuộc cấu hình OpenClaw.

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

Các bộ chuyển đổi runtime có thể chuẩn hóa registry dùng chung này thành dạng mà client hạ nguồn của chúng kỳ vọng. Ví dụ, Pi 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 của CLI như http, sse hoặc stdio.

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

OpenClaw cũng lưu một registry 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 set <name> <json>
• 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.
• set kỳ vọng một giá trị đối tượng JSON trên dòng lệnh.
• 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 của CLI sang 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 list
openclaw mcp show context7 --json
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'
openclaw mcp unset context7

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

{
  "mcp": {
    "servers": {
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      },
      "docs": {
        "url": "https://mcp.example.com",
        "transport": "streamable-http"
      }
    }
  }
}

# Transport Stdio

Khởi chạy một 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",
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

Các giá trị nhạy cảm trong url (userinfo) và headers được che trong nhật ký và đầu ra trạng thái.

# Transport Streamable HTTP

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

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

Ví dụ:

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

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

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

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

• việc khám phá cuộc trò chuyện phụ thuộc vào siêu dữ liệu định tuyến phiên Gateway hiện có
• chưa có giao thức đẩy chung ngoài bộ chuyển đổi dành riêng cho Claude
• chưa có công cụ chỉnh sửa tin nhắn hoặc react
• 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 khi cầu nối đang kết nối

# Liên quan

• Tham chiếu CLI
• Plugins