MCP

• 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

• 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

​

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

​

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

​

Khi nào dùng serve

• 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

​

Cách hoạt động

​

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

​

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

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

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

​

Công cụ cầu nối

​

Mô hình sự kiện

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

​

Thông báo kênh Claude

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

• 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

​

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

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

​

Tùy chọn

​

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

• 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

​

Kiểm thử

pnpm test:docker:mcp-channels

• 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

​

Khắc phục sự cố

​

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

​

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

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

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

​

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

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

​

Dạng đầu ra 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": 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": []
}

{
  "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

​

Transport SSE / HTTP

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

​

Quy trình 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

​

Transport HTTP có thể stream

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

​

Control UI

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ụ.

• 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

• 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