Giao thức Gateway

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Lớp truyền tải

• WebSocket, khung văn bản với payload JSON.
• Khung đầu tiên phải là một yêu cầu connect.
• Các khung trước kết nối bị giới hạn ở 64 KiB. Sau khi bắt tay thành công, client nên tuân theo các giới hạn hello-ok.policy.maxPayload và hello-ok.policy.maxBufferedBytes. Khi bật chẩn đoán, các khung inbound quá cỡ và bộ đệm outbound chậm sẽ phát sự kiện payload.large trước khi Gateway đóng hoặc bỏ khung bị ảnh hưởng. Các sự kiện này giữ lại kích thước, giới hạn, bề mặt và mã lý do an toàn. Chúng không giữ phần thân thông báo, nội dung tệp đính kèm, thân khung thô, token, cookie hoặc giá trị bí mật.

​

Bắt tay (connect)

{
  "type": "event",
  "event": "connect.challenge",
  "payload": { "nonce": "…", "ts": 1737264000000 }
}

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 3,
    "client": {
      "id": "cli",
      "version": "1.2.3",
      "platform": "macos",
      "mode": "operator"
    },
    "role": "operator",
    "scopes": ["operator.read", "operator.write"],
    "caps": [],
    "commands": [],
    "permissions": {},
    "auth": { "token": "…" },
    "locale": "en-US",
    "userAgent": "openclaw-cli/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "…",
      "signature": "…",
      "signedAt": 1737264000000,
      "nonce": "…"
    }
  }
}

{
  "type": "res",
  "id": "…",
  "ok": true,
  "payload": {
    "type": "hello-ok",
    "protocol": 3,
    "server": { "version": "…", "connId": "…" },
    "features": { "methods": ["…"], "events": ["…"] },
    "snapshot": { "…": "…" },
    "auth": {
      "role": "operator",
      "scopes": ["operator.read", "operator.write"]
    },
    "policy": {
      "maxPayload": 26214400,
      "maxBufferedBytes": 52428800,
      "tickIntervalMs": 15000
    }
  }
}

{
  "auth": {
    "role": "operator",
    "scopes": ["operator.read", "operator.write"]
  }
}

{
  "auth": {
    "deviceToken": "…",
    "role": "operator",
    "scopes": ["operator.read", "operator.write"]
  }
}

{
  "auth": {
    "deviceToken": "…",
    "role": "node",
    "scopes": [],
    "deviceTokens": [
      {
        "deviceToken": "…",
        "role": "operator",
        "scopes": ["operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"]
      }
    ]
  }
}

​

Ví dụ node

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 3,
    "client": {
      "id": "ios-node",
      "version": "1.2.3",
      "platform": "ios",
      "mode": "node"
    },
    "role": "node",
    "scopes": [],
    "caps": ["camera", "canvas", "screen", "location", "voice"],
    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],
    "permissions": { "camera.capture": true, "screen.record": false },
    "auth": { "token": "…" },
    "locale": "en-US",
    "userAgent": "openclaw-ios/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "…",
      "signature": "…",
      "signedAt": 1737264000000,
      "nonce": "…"
    }
  }
}

​

Đóng khung

• Yêu cầu: {type:"req", id, method, params}
• Phản hồi: {type:"res", id, ok, payload|error}
• Sự kiện: {type:"event", event, payload, seq?, stateVersion?}

​

Vai trò + phạm vi

​

Vai trò

• operator = client mặt phẳng điều khiển (CLI/UI/tự động hóa).
• node = máy chủ năng lực (camera/screen/canvas/system.run).

​

Phạm vi (operator)

• operator.read
• operator.write
• operator.admin
• operator.approvals
• operator.pairing
• operator.talk.secrets

• yêu cầu không có lệnh: operator.pairing
• yêu cầu có lệnh node không phải exec: operator.pairing + operator.write
• yêu cầu bao gồm system.run, system.run.prepare hoặc system.which: operator.pairing + operator.admin

​

Năng lực/lệnh/quyền (node)

• caps: các danh mục năng lực cấp cao.
• commands: allowlist lệnh cho invoke.
• permissions: các công tắc chi tiết (ví dụ: screen.record, camera.capture).

​

Hiện diện

• system-presence trả về các mục được khóa theo danh tính thiết bị.
• Các mục hiện diện bao gồm deviceId, roles và scopes để UI có thể hiển thị một hàng duy nhất cho mỗi thiết bị ngay cả khi thiết bị đó kết nối với cả vai trò operator và node.
• node.list bao gồm các trường tùy chọn lastSeenAtMs và lastSeenReason. Node đang kết nối báo cáo thời điểm kết nối hiện tại của chúng dưới dạng lastSeenAtMs với lý do connect; node đã ghép đôi cũng có thể báo cáo hiện diện nền bền vững khi một sự kiện node đáng tin cậy cập nhật metadata ghép đôi của chúng.

​

Sự kiện node còn sống trong nền

{
  "event": "node.presence.alive",
  "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"Peter's iPhone\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}"
}

{
  "ok": true,
  "event": "node.presence.alive",
  "handled": true,
  "reason": "persisted"
}

​

Phân phạm vi sự kiện broadcast

• Khung chat, agent và kết quả công cụ (bao gồm các sự kiện agent được stream và kết quả gọi công cụ) yêu cầu ít nhất operator.read. Các phiên không có operator.read bỏ qua hoàn toàn các khung này.
• Broadcast plugin.* do Plugin định nghĩa được kiểm soát theo operator.write hoặc operator.admin, tùy theo cách Plugin đăng ký chúng.
• Sự kiện trạng thái và truyền tải (heartbeat, presence, tick, vòng đời kết nối/ngắt kết nối, v.v.) vẫn không bị hạn chế để sức khỏe truyền tải vẫn quan sát được đối với mọi phiên đã xác thực.
• Các họ sự kiện broadcast không xác định mặc định được kiểm soát theo phạm vi (fail-closed) trừ khi một handler đã đăng ký nới lỏng chúng một cách tường minh.

​

Các họ phương thức RPC phổ biến

​

Các nhóm sự kiện chung

• chat: cập nhật trò chuyện UI như chat.inject và các sự kiện trò chuyện chỉ liên quan đến bản ghi hội thoại khác.
• session.message và session.tool: cập nhật bản ghi hội thoại/luồng sự kiện cho một phiên đã đăng ký.
• sessions.changed: chỉ mục phiên hoặc siêu dữ liệu đã thay đổi.
• presence: cập nhật ảnh chụp sự hiện diện hệ thống.
• tick: sự kiện duy trì kết nối / trạng thái sống định kỳ.
• health: cập nhật ảnh chụp tình trạng Gateway.
• heartbeat: cập nhật luồng sự kiện Heartbeat.
• cron: sự kiện thay đổi lượt chạy/công việc Cron.
• shutdown: thông báo tắt Gateway.
• node.pair.requested / node.pair.resolved: vòng đời ghép cặp Node.
• node.invoke.request: phát quảng bá yêu cầu gọi Node.
• device.pair.requested / device.pair.resolved: vòng đời thiết bị đã ghép cặp.
• voicewake.changed: cấu hình trình kích hoạt từ đánh thức đã thay đổi.
• exec.approval.requested / exec.approval.resolved: vòng đời phê duyệt thực thi.
• plugin.approval.requested / plugin.approval.resolved: vòng đời phê duyệt Plugin.

​

Phương thức trợ giúp Node

• Các Node có thể gọi skills.bins để lấy danh sách hiện tại các tệp thực thi Skills cho kiểm tra tự động cho phép.

​

Phương thức trợ giúp người vận hành

• Người vận hành có thể gọi commands.list (operator.read) để lấy danh mục lệnh thời gian chạy cho một agent.
  • agentId là tùy chọn; bỏ qua để đọc không gian làm việc agent mặc định.
  • scope kiểm soát bề mặt mà name chính nhắm tới:
    • text trả về token lệnh văn bản chính không có dấu / ở đầu
    • native và đường dẫn mặc định both trả về tên native nhận biết nhà cung cấp khi có sẵn
  • textAliases mang các bí danh slash chính xác như /model và /m.
  • nativeName mang tên lệnh native nhận biết nhà cung cấp khi tồn tại.
  • provider là tùy chọn và chỉ ảnh hưởng đến cách đặt tên native cùng khả năng có sẵn của lệnh plugin native.
  • includeArgs=false bỏ qua metadata đối số đã tuần tự hóa khỏi phản hồi.
• Người vận hành có thể gọi tools.catalog (operator.read) để lấy danh mục công cụ thời gian chạy cho một agent. Phản hồi bao gồm các công cụ được nhóm và metadata nguồn gốc:
  • source: core hoặc plugin
  • pluginId: chủ sở hữu plugin khi source="plugin"
  • optional: công cụ plugin có phải là tùy chọn hay không
• Người vận hành có thể gọi tools.effective (operator.read) để lấy danh mục công cụ có hiệu lực trong thời gian chạy cho một phiên.
  • sessionKey là bắt buộc.
  • Gateway suy ra ngữ cảnh thời gian chạy đáng tin cậy từ phiên ở phía máy chủ thay vì chấp nhận ngữ cảnh xác thực hoặc phân phối do bên gọi cung cấp.
  • Phản hồi được giới hạn theo phiên và phản ánh những gì cuộc trò chuyện đang hoạt động có thể dùng ngay bây giờ, bao gồm công cụ lõi, plugin và kênh.
• Người vận hành có thể gọi skills.status (operator.read) để lấy danh mục skill hiển thị cho một agent.
  • agentId là tùy chọn; bỏ qua để đọc không gian làm việc agent mặc định.
  • Phản hồi bao gồm tính đủ điều kiện, yêu cầu còn thiếu, kiểm tra cấu hình và các tùy chọn cài đặt đã được làm sạch mà không để lộ giá trị bí mật thô.
• Người vận hành có thể gọi skills.search và skills.detail (operator.read) cho metadata khám phá ClawHub.
• Người vận hành có thể gọi skills.install (operator.admin) ở hai chế độ:
  • Chế độ ClawHub: { source: "clawhub", slug, version?, force? } cài đặt một thư mục skill vào thư mục skills/ của không gian làm việc agent mặc định.
  • Chế độ trình cài đặt Gateway: { name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? } chạy một hành động metadata.openclaw.install đã khai báo trên máy chủ Gateway.
• Người vận hành có thể gọi skills.update (operator.admin) ở hai chế độ:
  • Chế độ ClawHub cập nhật một slug được theo dõi hoặc tất cả bản cài đặt ClawHub được theo dõi trong không gian làm việc agent mặc định.
  • Chế độ cấu hình vá các giá trị skills.entries.<skillKey> như enabled, apiKey và env.

​

Các chế độ xem models.list

• Bỏ qua hoặc "default": hành vi thời gian chạy hiện tại. Nếu agents.defaults.models được cấu hình, phản hồi là danh mục được cho phép; nếu không, phản hồi là toàn bộ danh mục Gateway.
• "configured": hành vi có kích thước phù hợp với bộ chọn. Nếu agents.defaults.models được cấu hình, giá trị đó vẫn được ưu tiên. Nếu không, phản hồi dùng các mục models.providers.*.models rõ ràng, chỉ quay về toàn bộ danh mục khi không có hàng mô hình đã cấu hình nào tồn tại.
• "all": toàn bộ danh mục Gateway, bỏ qua agents.defaults.models. Dùng chế độ này cho chẩn đoán và UI khám phá, không dùng cho bộ chọn mô hình thông thường.

​

Phê duyệt exec

• Khi một yêu cầu exec cần phê duyệt, gateway phát exec.approval.requested.
• Máy khách người vận hành giải quyết bằng cách gọi exec.approval.resolve (yêu cầu phạm vi operator.approvals).
• Với host=node, exec.approval.request phải bao gồm systemRunPlan (argv/cwd/rawCommand/metadata phiên chuẩn). Yêu cầu thiếu systemRunPlan sẽ bị từ chối.
• Sau khi được phê duyệt, các lệnh gọi node.invoke system.run được chuyển tiếp sẽ tái sử dụng systemRunPlan chuẩn đó làm ngữ cảnh lệnh/cwd/phiên có thẩm quyền.
• Nếu bên gọi thay đổi command, rawCommand, cwd, agentId hoặc sessionKey giữa bước chuẩn bị và lần chuyển tiếp system.run cuối cùng đã được phê duyệt, gateway từ chối lần chạy thay vì tin payload đã bị thay đổi.

​

Dự phòng phân phối agent

• Yêu cầu agent có thể bao gồm deliver=true để yêu cầu phân phối đi.
• bestEffortDeliver=false giữ hành vi nghiêm ngặt: mục tiêu phân phối không phân giải được hoặc chỉ dùng nội bộ trả về INVALID_REQUEST.
• bestEffortDeliver=true cho phép dự phòng sang thực thi chỉ theo phiên khi không thể phân giải tuyến có thể phân phối ra bên ngoài (ví dụ phiên nội bộ/webchat hoặc cấu hình đa kênh mơ hồ).

​

Quản lý phiên bản

• PROTOCOL_VERSION nằm trong src/gateway/protocol/schema/protocol-schemas.ts.
• Máy khách gửi minProtocol + maxProtocol; máy chủ từ chối các trường hợp không khớp.
• Schema + mô hình được tạo từ định nghĩa TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

Hằng số máy khách

​

Xác thực

• Xác thực gateway bằng shared-secret dùng connect.params.auth.token hoặc connect.params.auth.password, tùy theo chế độ xác thực đã cấu hình.
• Các chế độ mang định danh như Tailscale Serve (gateway.auth.allowTailscale: true) hoặc gateway.auth.mode: "trusted-proxy" không phải loopback đáp ứng kiểm tra xác thực kết nối từ header yêu cầu thay vì connect.params.auth.*.
• gateway.auth.mode: "none" cho private-ingress bỏ qua hoàn toàn xác thực kết nối bằng shared-secret; không để lộ chế độ đó trên ingress công khai/không đáng tin cậy.
• Sau khi ghép nối, Gateway phát hành device token được giới hạn theo vai trò kết nối + phạm vi. Token này được trả về trong hello-ok.auth.deviceToken và nên được máy khách lưu lại cho các lần kết nối sau.
• Máy khách nên lưu hello-ok.auth.deviceToken chính sau bất kỳ lần kết nối thành công nào.
• Kết nối lại bằng device token đã lưu đó cũng nên tái sử dụng tập phạm vi đã được phê duyệt và lưu cho token đó. Điều này giữ nguyên quyền truy cập đọc/thăm dò/trạng thái đã được cấp và tránh âm thầm thu hẹp các lần kết nối lại xuống phạm vi ngầm chỉ dành cho quản trị viên.
• Lắp ráp xác thực kết nối phía máy khách (selectConnectAuth trong src/gateway/client.ts):
  • auth.password độc lập và luôn được chuyển tiếp khi được đặt.
  • auth.token được điền theo thứ tự ưu tiên: shared token rõ ràng trước, sau đó là deviceToken rõ ràng, rồi token theo thiết bị đã lưu (được khóa bằng deviceId + role).
  • auth.bootstrapToken chỉ được gửi khi không mục nào ở trên phân giải được auth.token. Shared token hoặc bất kỳ device token nào đã phân giải sẽ chặn nó.
  • Tự động thăng cấp device token đã lưu trong lần thử lại một lần AUTH_TOKEN_MISMATCH chỉ được cho phép với endpoint đáng tin cậy — loopback, hoặc wss:// với tlsFingerprint đã ghim. wss:// công khai không ghim không đủ điều kiện.
• Các mục hello-ok.auth.deviceTokens bổ sung là token bàn giao bootstrap. Chỉ lưu chúng khi kết nối dùng xác thực bootstrap trên một transport đáng tin cậy như wss:// hoặc ghép nối loopback/local.
• Nếu máy khách cung cấp deviceToken rõ ràng hoặc scopes rõ ràng, tập phạm vi do bên gọi yêu cầu đó vẫn có thẩm quyền; phạm vi trong cache chỉ được tái sử dụng khi máy khách đang tái sử dụng token theo thiết bị đã lưu.
• Device token có thể được xoay vòng/thu hồi qua device.token.rotate và device.token.revoke (yêu cầu phạm vi operator.pairing).
• device.token.rotate trả về metadata xoay vòng. Nó chỉ echo bearer token thay thế cho các lệnh gọi cùng thiết bị đã được xác thực bằng device token đó, để máy khách chỉ dùng token có thể lưu token thay thế trước khi kết nối lại. Các lần xoay vòng shared/admin không echo bearer token.
• Việc phát hành, xoay vòng và thu hồi token vẫn bị giới hạn trong tập vai trò đã phê duyệt được ghi trong mục ghép nối của thiết bị đó; thao tác token không thể mở rộng hoặc nhắm tới một vai trò thiết bị mà phê duyệt ghép nối chưa từng cấp.
• Với phiên token của thiết bị đã ghép nối, quản lý thiết bị được giới hạn theo chính thiết bị đó trừ khi bên gọi cũng có operator.admin: bên gọi không phải quản trị viên chỉ có thể xóa/thu hồi/xoay vòng mục thiết bị của chính họ.
• device.token.rotate và device.token.revoke cũng kiểm tra tập phạm vi token người vận hành mục tiêu so với phạm vi phiên hiện tại của bên gọi. Bên gọi không phải quản trị viên không thể xoay vòng hoặc thu hồi token người vận hành rộng hơn token họ đang giữ.
• Lỗi xác thực bao gồm error.details.code cùng gợi ý khôi phục:
  • error.details.canRetryWithDeviceToken (boolean)
  • error.details.recommendedNextStep (retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration)
• Hành vi máy khách cho AUTH_TOKEN_MISMATCH:
  • Máy khách đáng tin cậy có thể thử lại một lần có giới hạn bằng token theo thiết bị trong cache.
  • Nếu lần thử lại đó thất bại, máy khách nên dừng vòng lặp tự động kết nối lại và hiển thị hướng dẫn hành động cho người vận hành.

​

Định danh thiết bị + ghép nối

• Các Node nên bao gồm một định danh thiết bị ổn định (device.id) được suy ra từ dấu vân tay của cặp khóa.
• Các Gateway cấp token theo từng thiết bị + vai trò.
• Phê duyệt ghép nối là bắt buộc đối với ID thiết bị mới, trừ khi tự động phê duyệt cục bộ được bật.
• Tự động phê duyệt ghép nối tập trung vào các kết nối local loopback trực tiếp.
• OpenClaw cũng có một đường tự kết nối backend/container-local hẹp dành cho các luồng helper dùng shared-secret đáng tin cậy.
• Các kết nối tailnet hoặc LAN cùng host vẫn được xem là từ xa khi ghép nối và yêu cầu phê duyệt.
• Client WS thường bao gồm định danh device trong khi connect (operator + node). Các ngoại lệ operator không có thiết bị duy nhất là các đường tin cậy rõ ràng:
  • gateway.controlUi.allowInsecureAuth=true cho khả năng tương thích HTTP không an toàn chỉ dành cho localhost.
  • xác thực Control UI của operator bằng gateway.auth.mode: "trusted-proxy" thành công.
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (biện pháp khẩn cấp, hạ cấp bảo mật nghiêm trọng).
  • RPC backend gateway-client qua direct-loopback được xác thực bằng token/mật khẩu Gateway dùng chung.
• Tất cả kết nối phải ký nonce connect.challenge do máy chủ cung cấp.

​

Chẩn đoán di chuyển xác thực thiết bị

• Luôn chờ connect.challenge.
• Ký payload v2 có bao gồm nonce của máy chủ.
• Gửi cùng nonce trong connect.params.device.nonce.
• Payload chữ ký ưu tiên là v3, ràng buộc platform và deviceFamily ngoài các trường device/client/role/scopes/token/nonce.
• Chữ ký v2 cũ vẫn được chấp nhận để tương thích, nhưng việc ghim metadata thiết bị đã ghép nối vẫn kiểm soát chính sách lệnh khi kết nối lại.

​

TLS + ghim

• TLS được hỗ trợ cho kết nối WS.
• Client có thể tùy chọn ghim dấu vân tay chứng chỉ Gateway (xem cấu hình gateway.tls cùng với gateway.remote.tlsFingerprint hoặc CLI --tls-fingerprint).

​

Phạm vi

​

Liên quan

• Giao thức Bridge
• Runbook Gateway