Giao thức Gateway

Giao thức Gateway WS là mặt phẳng điều khiển + truyền tải nút duy nhất cho OpenClaw. Tất cả client (CLI, giao diện web, ứng dụng macOS, nút iOS/Android, nút headless) kết nối qua WebSocket và khai báo role + scope của chúng tại thời điểm bắt tay.

Truyền tải

• WebSocket, khung văn bản với payload JSON.
• Khung đầu tiên phải là yêu cầu connect.
• Các khung trước khi kết nối được 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, khung gửi vào quá lớn và bộ đệm gửi ra chậm sẽ phát sự kiện payload.large trước khi gateway đóng hoặc loại bỏ khung bị ảnh hưởng. Các sự kiện này giữ kích thước, giới hạn, bề mặt và mã lý do an toàn. Chúng không giữ thân thông điệp, 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)

Gateway → Client (thử thách trước khi kết nối):

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

Client → Gateway:

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 3,    "maxProtocol": 4,    "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": "…"    }  }}

Gateway → Client:

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

Trong khi Gateway vẫn đang hoàn tất các sidecar khởi động, yêu cầu connect có thể trả về lỗi UNAVAILABLE có thể thử lại với details.reason được đặt thành "startup-sidecars" và retryAfterMs. Client nên thử lại phản hồi đó trong ngân sách kết nối tổng thể của mình thay vì hiển thị nó như một lỗi bắt tay cuối cùng.

server, features, snapshot và policy đều là bắt buộc theo schema (packages/gateway-protocol/src/schema/frames.ts). auth cũng bắt buộc và báo cáo role/scope đã thương lượng. pluginSurfaceUrls là tùy chọn và ánh xạ tên bề mặt plugin, chẳng hạn như canvas, tới URL được lưu trữ theo phạm vi.

URL bề mặt plugin theo phạm vi có thể hết hạn. Nút có thể gọi node.pluginSurface.refresh với { "surface": "canvas" } để nhận một mục mới trong pluginSurfaceUrls. Bản tái cấu trúc Plugin Canvas thử nghiệm không hỗ trợ đường tương thích đã ngừng dùng canvasHostUrl, canvasCapability hoặc node.canvas.capability.refresh; client native và gateway hiện tại phải dùng bề mặt plugin.

Khi không có token thiết bị nào được cấp, hello-ok.auth báo cáo các quyền đã thương lượng không có trường token:

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

Client backend cùng tiến trình đáng tin cậy (client.id: "gateway-client", client.mode: "backend") có thể bỏ qua device trên kết nối loopback trực tiếp khi chúng xác thực bằng token/mật khẩu gateway dùng chung. Đường này được dành riêng cho RPC mặt phẳng điều khiển nội bộ và ngăn baseline ghép nối CLI/thiết bị đã cũ chặn công việc backend cục bộ như cập nhật phiên subagent. Client từ xa, client có nguồn gốc trình duyệt, client nút và client dùng token thiết bị/danh tính thiết bị rõ ràng vẫn dùng các bước kiểm tra ghép nối và nâng cấp phạm vi thông thường.

Khi token thiết bị được cấp, hello-ok cũng bao gồm:

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

Bootstrap mã QR/mã thiết lập tích hợp là đường bàn giao di động mới. Một kết nối setup-code baseline thành công trả về một token nút chính cộng với một token operator có giới hạn:

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

Bàn giao operator được giới hạn có chủ ý để onboarding QR có thể khởi động vòng lặp operator di động mà không cấp operator.admin hoặc operator.pairing. Nó có bao gồm operator.talk.secrets để client native có thể đọc cấu hình Talk cần thiết sau bootstrap. Phạm vi admin và ghép nối rộng hơn yêu cầu một luồng ghép nối operator hoặc token riêng đã được phê duyệt. Client chỉ nên lưu hello-ok.auth.deviceTokens khi kết nối đã dùng xác thực bootstrap trên truyền tải đáng tin cậy như wss:// hoặc ghép nối loopback/cục bộ.

Ví dụ node

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 3,    "maxProtocol": 4,    "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?}

Các phương thức có tác dụng phụ yêu cầu khóa idempotency (xem schema).

Role + scope

Để xem đầy đủ mô hình phạm vi operator, kiểm tra tại thời điểm phê duyệt và ngữ nghĩa shared-secret, hãy xem Phạm vi operator.

Role

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

Scope (operator)

Các phạm vi phổ biến:

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

talk.config với includeSecrets: true yêu cầu operator.talk.secrets (hoặc operator.admin). Khi bao gồm secret, client nên đọc thông tin xác thực nhà cung cấp Talk đang hoạt động từ talk.resolved.config.apiKey; talk.providers.<id>.apiKey giữ nguyên hình dạng nguồn và có thể là đối tượng SecretRef hoặc chuỗi đã được biên tập.

Các phương thức RPC Gateway do plugin đăng ký có thể yêu cầu phạm vi operator riêng, nhưng các tiền tố admin lõi được dành riêng (config.*, exec.approvals.*, wizard.*, update.*) luôn phân giải thành operator.admin.

Phạm vi phương thức chỉ là cổng đầu tiên. Một số lệnh slash đi qua chat.send áp dụng kiểm tra cấp lệnh nghiêm ngặt hơn ở phía trên. Ví dụ, các thao tác ghi /config set và /config unset bền vững yêu cầu operator.admin.

node.pair.approve cũng có thêm một kiểm tra phạm vi tại thời điểm phê duyệt bên trên phạm vi phương thức cơ sở:

• yêu cầu không có lệnh: operator.pairing
• yêu cầu có lệnh nút 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

Caps/commands/permissions (node)

Nút khai báo các xác nhận năng lực tại thời điểm kết nối:

• caps: các danh mục năng lực cấp cao như camera, canvas, screen, location, voice và talk.
• commands: danh sách cho phép lệnh để invoke.
• permissions: các công tắc chi tiết (ví dụ screen.record, camera.capture).

Gateway coi chúng là xác nhận và thực thi danh sách cho phép phía máy chủ.

Hiện diện

• system-presence trả về các mục được khóa theo danh tính thiết bị.
• 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 dưới cả operator và node.
• node.list bao gồm các trường tùy chọn lastSeenAtMs và lastSeenReason. Nút đã 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; nút đã ghép nố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 nút đáng tin cậy cập nhật metadata ghép nối của chúng.

Sự kiện node còn hoạt động trong nền

Nút có thể gọi node.event với event: "node.presence.alive" để ghi nhận rằng một nút đã ghép nối còn hoạt động trong một lần đánh thức nền mà không đánh dấu nó là đã kết nối.

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

trigger là một enum đóng: background, silent_push, bg_app_refresh, significant_location, manual hoặc connect. Chuỗi trigger không xác định được gateway chuẩn hóa thành background trước khi lưu bền vững. Sự kiện chỉ bền vững cho phiên thiết bị nút đã xác thực; phiên không có thiết bị hoặc chưa ghép nối trả về handled: false.

Gateway thành công trả về kết quả có cấu trúc:

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

Gateway cũ hơn vẫn có thể trả về { "ok": true } cho node.event; client nên coi đó là một RPC đã được xác nhận, không phải là lưu bền vững hiện diện.

Phạm vi sự kiện broadcast

Các sự kiện broadcast WebSocket do máy chủ đẩy được kiểm soát theo phạm vi để phiên chỉ có phạm vi ghép nối hoặc chỉ dành cho nút không thụ động nhận nội dung phiên.

• Khung chat, agent và kết quả công cụ (bao gồm sự kiện agent được stream và kết quả lời gọi công cụ) yêu cầu ít nhất operator.read. 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 bằng 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ế để mọi phiên đã xác thực đều quan sát được tình trạng truyền tải.
• Nhóm 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 rõ ràng.

Mỗi kết nối client giữ số thứ tự riêng theo từng client để broadcast duy trì thứ tự đơn điệu trên socket đó ngay cả khi các client khác nhau thấy các tập con đã lọc theo phạm vi khác nhau của luồng sự kiện.

Các nhóm phương thức RPC phổ biến

Bề mặt WS công khai rộng hơn các ví dụ bắt tay/xác thực ở trên. Đây không phải là bản xuất được tạo tự động — hello-ok.features.methods là danh sách khám phá thận trọng được xây dựng từ src/gateway/server-methods-list.ts cộng với các export phương thức plugin/kênh đã tải. Hãy coi nó là khám phá tính năng, không phải là liệt kê đầy đủ src/gateway/server-methods/*.ts.

Các nhóm sự kiện phổ biến

• chat: các 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 khác. Trong giao thức v4, payload delta mang deltaText; message vẫn là ảnh chụp nhanh trợ lý tích lũy. Các thay thế không theo tiền tố đặt replace=true và dùng deltaText làm văn bản thay thế.
• session.message, session.operation và session.tool: các cập nhật bản ghi, thao tác phiên đang diễn ra và 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 nhanh hiện diện hệ thống.
• tick: sự kiện keepalive / liveness định kỳ.
• health: cập nhật ảnh chụp nhanh sức khỏe 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 nối nút.
• node.invoke.request: phát rộng yêu cầu invoke nút.
• device.pair.requested / device.pair.resolved: vòng đời thiết bị đã ghép nối.
• voicewake.changed: cấu hình kích hoạt từ đánh thức đã thay đổi.
• exec.approval.requested / exec.approval.resolved: vòng đời phê duyệt exec.
• plugin.approval.requested / plugin.approval.resolved: vòng đời phê duyệt plugin.

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

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

RPC sổ cái tác vụ

Client toán tử có thể kiểm tra và hủy bản ghi tác vụ nền Gateway thông qua các RPC sổ cái tác vụ. Các phương thức này trả về tóm tắt tác vụ đã được làm sạch, không phải trạng thái runtime thô.

• tasks.list yêu cầu operator.read.
  • Tham số: status tùy chọn ("queued", "running", "completed", "failed", "cancelled" hoặc "timed_out") hoặc một mảng các trạng thái đó, agentId tùy chọn, sessionKey tùy chọn, limit tùy chọn từ 1 đến 500 và chuỗi cursor tùy chọn.
  • Kết quả: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get yêu cầu operator.read.
  • Tham số: { "taskId": string }.
  • Kết quả: { "task": TaskSummary }.
  • Id tác vụ bị thiếu trả về dạng lỗi không tìm thấy của Gateway.
• tasks.cancel yêu cầu operator.write.
  • Tham số: { "taskId": string, "reason"?: string }.
  • Kết quả: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
  • found báo cáo sổ cái có tác vụ khớp hay không. cancelled báo cáo runtime đã chấp nhận hoặc ghi nhận việc hủy hay chưa.

TaskSummary bao gồm id, status và siêu dữ liệu tùy chọn như kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, dấu thời gian, tiến độ, tóm tắt kết thúc và văn bản lỗi đã được làm sạch. agentId xác định tác nhân đang thực thi tác vụ; sessionKey và ownerKey giữ lại ngữ cảnh bên yêu cầu và điều khiển.

Phương thức trợ giúp toán tử

• Người vận hành có thể gọi commands.list (operator.read) để lấy danh mục lệnh runtime cho một agent.

• Xác thực Gateway bằng bí mật dùng chung sử 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 danh tính như Tailscale Serve (gateway.auth.allowTailscale: true) hoặc non-loopback gateway.auth.mode: "trusted-proxy" đáp ứng kiểm tra xác thực khi kết nối từ header yêu cầu thay vì connect.params.auth.*.

• Private-ingress gateway.auth.mode: "none" bỏ qua hoàn toàn xác thực kết nối bằng bí mật dùng chung; không phơi bày chế độ đó trên ingress công khai/không tin cậy.

• Sau khi ghép cặp, Gateway cấp một mã thông báo thiết bị có phạm vi theo vai trò kết nối + các phạm vi. Nó được trả về trong hello-ok.auth.deviceToken và nên được client lưu bền vững cho các lần kết nối sau.

• Client nên lưu bền vững hello-ok.auth.deviceToken chính sau mọi lần kết nối thành công.

• Kết nối lại bằng mã thông báo thiết bị đã lưu đó cũng nên tái sử dụng tập phạm vi đã phê duyệt được lưu cho mã thông báo đó. Đ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 về phạm vi ngầm định chỉ dành cho admin.

• Lắp ráp xác thực kết nối phía client (selectConnectAuth trong src/gateway/client.ts):

  • auth.password là trực giao và luôn được chuyển tiếp khi được đặt.
  • auth.token được điền theo thứ tự ưu tiên: mã thông báo dùng chung tường minh trước, rồi một deviceToken tường minh, rồi mã thông báo theo thiết bị đã lưu (được khóa theo deviceId + role).
  • auth.bootstrapToken chỉ được gửi khi không mục nào ở trên phân giải được auth.token. Một mã thông báo dùng chung hoặc bất kỳ mã thông báo thiết bị đã phân giải nào sẽ chặn nó.
  • Tự động nâng cấp một mã thông báo thiết bị đã lưu trong lần thử lại một lần AUTH_TOKEN_MISMATCH chỉ được cho phép với điểm cuối tin cậy — loopback, hoặc wss:// với tlsFingerprint đã ghim. wss:// công khai không ghim không đủ điều kiện.

• Bootstrap bằng mã thiết lập tích hợp trả về node chính hello-ok.auth.deviceToken cùng một mã thông báo operator có giới hạn trong hello-ok.auth.deviceTokens cho chuyển giao di động tin cậy. Mã thông báo operator bao gồm operator.talk.secrets để đọc cấu hình Talk gốc và loại trừ operator.admin và operator.pairing.

• Trong khi bootstrap bằng mã thiết lập không phải baseline đang chờ phê duyệt, chi tiết PAIRING_REQUIRED bao gồm recommendedNextStep: "wait_then_retry", retryable: true, và pauseReconnect: false. Client nên tiếp tục kết nối lại bằng cùng mã thông báo bootstrap cho đến khi yêu cầu được phê duyệt hoặc mã thông báo không còn hợp lệ.

• Chỉ lưu bền vững hello-ok.auth.deviceTokens khi lần kết nối dùng xác thực bootstrap trên transport tin cậy như wss:// hoặc ghép cặp loopback/local.

• Nếu client cung cấp deviceToken tường minh hoặc scopes tường minh, tập phạm vi do caller yêu cầu đó vẫn là nguồn có thẩm quyền; các phạm vi trong cache chỉ được tái sử dụng khi client tái sử dụng mã thông báo theo thiết bị đã lưu.

• Mã thông báo thiết bị 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). Xoay vòng hoặc thu hồi một node hoặc vai trò không phải operator khác cũng yêu cầu operator.admin.

• device.token.rotate trả về metadata xoay vòng. Nó chỉ echo mã thông báo bearer thay thế cho các lệnh gọi cùng thiết bị đã được xác thực bằng mã thông báo thiết bị đó, để client chỉ dùng mã thông báo có thể lưu bền vững bản thay thế trước khi kết nối lại. Các xoay vòng dùng chung/admin không echo mã thông báo bearer.

• Việc cấp, xoay vòng và thu hồi mã thông báo vẫn bị giới hạn trong tập vai trò đã phê duyệt được ghi lại trong mục ghép cặp của thiết bị đó; đột biến mã thông báo không thể mở rộng hoặc nhắm tới vai trò thiết bị mà phê duyệt ghép cặp chưa từng cấp.

• Với các phiên mã thông báo thiết bị đã ghép cặp, quản lý thiết bị tự giới hạn phạm vi trừ khi caller cũng có operator.admin: caller không phải admin chỉ có thể quản lý mã thông báo operator cho mục thiết bị của chính họ. Quản lý mã thông báo node và các mã thông báo không phải operator khác chỉ dành cho admin, kể cả với thiết bị của chính caller.

• device.token.rotate và device.token.revoke cũng kiểm tra tập phạm vi mã thông báo operator đích so với phạm vi phiên hiện tại của caller. Caller không phải admin không thể xoay vòng hoặc thu hồi mã thông báo operator rộng hơn phạm vi họ đang có.

• 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 client cho AUTH_TOKEN_MISMATCH:

  • Client tin cậy có thể thử lại một lần có giới hạn bằng mã thông báo theo thiết bị trong cache.
  • Nếu lần thử lại đó thất bại, client nên dừng các vòng lặp tự động kết nối lại và hiển thị hướng dẫn thao tác cho operator.

• AUTH_SCOPE_MISMATCH nghĩa là mã thông báo thiết bị đã được nhận diện nhưng không bao phủ vai trò/phạm vi được yêu cầu. Client không nên trình bày lỗi này như mã thông báo không hợp lệ; hãy nhắc operator ghép cặp lại hoặc phê duyệt hợp đồng phạm vi hẹp/rộng hơn.

Danh tính thiết bị + ghép cặp

• Node nên bao gồm danh tính thiết bị ổn định (device.id) được dẫn xuất từ fingerprint của keypair.
• Gateway cấp mã thông báo theo thiết bị + vai trò.
• Cần phê duyệt ghép cặp cho ID thiết bị mới trừ khi tự động phê duyệt local được bật.
• Tự động phê duyệt ghép cặp tập trung vào các kết nối local loopback trực tiếp.
• OpenClaw cũng có một đường dẫn tự kết nối backend/container-local hẹp cho các luồng helper bí mật dùng chung tin cậy.
• Các kết nối tailnet cùng host hoặc LAN vẫn được coi là từ xa cho ghép cặp và yêu cầu phê duyệt.
• Client WS thường bao gồm danh tính device trong connect (operator + node). Các ngoại lệ operator không có thiết bị duy nhất là các đường dẫn tin cậy tường minh:
  • gateway.controlUi.allowInsecureAuth=true để tương thích HTTP không an toàn chỉ dành cho localhost.
  • xác thực operator Control UI thành công với gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (break-glass, hạ cấp bảo mật nghiêm trọng).
  • RPC backend gateway-client direct-loopback trên đường dẫn helper nội bộ dành riêng.
• Bỏ qua danh tính thiết bị có hệ quả về phạm vi. Khi một kết nối operator không có thiết bị được cho phép qua đường dẫn tin cậy tường minh, OpenClaw vẫn xóa các phạm vi tự khai báo về tập rỗng trừ khi đường dẫn đó có ngoại lệ bảo toàn phạm vi được đặt tên. Các phương thức có kiểm soát phạm vi sau đó thất bại với missing scope.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true là đường dẫn bảo toàn phạm vi break-glass của Control UI. Nó không cấp phạm vi cho các WebSocket client backend tùy chỉnh hoặc dạng CLI tùy ý.
• Đường dẫn helper backend gateway-client direct-loopback dành riêng bảo toàn phạm vi chỉ cho RPC control-plane local nội bộ; ID backend tùy chỉnh không nhận ngoại lệ này.
• Tất cả kết nối phải ký nonce connect.challenge do server cung cấp.

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

Với các client legacy vẫn dùng hành vi ký trước challenge, connect hiện trả về mã chi tiết DEVICE_AUTH_* trong error.details.code cùng error.details.reason ổn định.

Các lỗi di trú thường gặp:

Mục tiêu di trú:

• Luôn chờ connect.challenge.
• Ký payload v2 bao gồm nonce của server.
• Gửi cùng nonce trong connect.params.device.nonce.
• Payload chữ ký ưu tiên là v3, liên kết platform và deviceFamily ngoài các trường device/client/role/scopes/token/nonce.
• Chữ ký legacy v2 vẫn được chấp nhận để tương thích, nhưng ghim metadata thiết bị đã ghép cặp 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 fingerprint chứng chỉ Gateway (xem cấu hình gateway.tls cùng gateway.remote.tlsFingerprint hoặc CLI --tls-fingerprint).

Phạm vi

Giao thức này phơi bày toàn bộ API Gateway (trạng thái, kênh, mô hình, chat, agent, phiên, node, phê duyệt, v.v.). Bề mặt chính xác được định nghĩa bởi các schema TypeBox trong packages/gateway-protocol/src/schema.ts.

Liên quan

• Giao thức bridge
• Runbook Gateway