Giao thức Gateway

​

Vận chuyển

• 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 khi kết nối bị giới hạn ở 64 KiB. Sau khi bắt tay thành công, máy khách 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 đầu vào quá lớn và bộ đệm đầu ra 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ữ lại phần thân thông điệp, nội dung tệp đính kèm, phần 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": 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": "…"
    }
  }
}

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

{
  "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ụ nút

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

​

Vai trò + phạm vi

​

Vai trò

• operator = máy khách 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 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

​

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

• 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 lệnh được phép để invoke.
• permissions: bật/tắt 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ị.
• 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 nó 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. Nút đã kết nối báo cáo thời gian 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 đô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 đôi của chúng.

​

Sự kiện nút 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ạm vi hóa sự kiện broadcast

• Khung chat, agent và kết quả công cụ (bao gồm 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 những khung này.
• Broadcast plugin.* do Plugin định nghĩa được chặn ở operator.write hoặc operator.admin, tùy theo cách Plugin đăng ký chúng.
• Sự kiện trạng thái và vận chuyển (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 vận chuyển.
• Các họ sự kiện broadcast không xác định mặc định bị chặn theo phạm vi (fail-closed) trừ khi một handler đã đăng ký nới lỏng chúng rõ ràng.

​

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

​

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ỉ trong transcript khác. Trong giao thức v4, payload delta mang deltaText; message vẫn là ảnh chụp tích lũy của trợ lý. 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: transcript, thao tác phiên đang diễn ra, và các cập nhật 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 trạng thái hiện diện của hệ thống.
• tick: sự kiện keepalive / liveness đị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ần 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 rộng 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 kích hoạt bằng 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 hỗ trợ Node

• Các node 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ụ

• 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 liệu sổ cái có tác vụ khớp hay không. cancelled báo liệu runtime đã chấp nhận hoặc ghi nhận việc hủy hay chưa.

​

Phương thức hỗ trợ vận hành

• Người vận hành có thể gọi commands.list (operator.read) để lấy kho lệnh runtime cho một agent.
  • agentId là tùy chọn; bỏ qua để đọc workspace 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ó / ở đầu
    • native và đường dẫn mặc định both trả về tên native có nhận biết provider khi có sẵn
  • textAliases chứa các bí danh slash chính xác như /model và /m.
  • nativeName chứa tên lệnh native có nhận biết provider khi tồn tại.
  • provider là tùy chọn và chỉ ảnh hưởng đến việc đặt tên native cùng với khả năng sẵn có 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 catalog công cụ runtime 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: liệu 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 kho công cụ có hiệu lực trong runtime cho một phiên.
  • sessionKey là bắt buộc.
  • Gateway suy ra ngữ cảnh runtime đáng tin cậy từ phiên ở phía máy chủ thay vì chấp nhận auth hoặc ngữ cảnh phân phối do bên gọi cung cấp.
  • Phản hồi là một phép chiếu do máy chủ suy ra theo phạm vi phiên của kho đang hoạt động, bao gồm các công cụ core, plugin, kênh và máy chủ MCP đã được phát hiện.
  • tools.effective là chỉ đọc đối với MCP: nó có thể chiếu một catalog MCP của phiên đã warm qua chính sách công cụ cuối cùng, nhưng không tạo runtime MCP, kết nối transport hoặc phát hành tools/list. Nếu không có catalog warm khớp, phản hồi có thể bao gồm một thông báo như mcp-not-yet-connected, mcp-not-yet-listed, hoặc mcp-stale-catalog.
  • Các mục công cụ hiệu lực dùng source="core", source="plugin", source="channel", hoặc source="mcp".
• Người vận hành có thể gọi tools.invoke (operator.write) để gọi một công cụ sẵn có qua cùng đường dẫn chính sách Gateway như /tools/invoke.
  • name là bắt buộc. args, sessionKey, agentId, confirm, và idempotencyKey là tùy chọn.
  • Nếu cả sessionKey và agentId đều hiện diện, agent của phiên đã phân giải phải khớp với agentId.
  • Các wrapper core chỉ dành cho owner như cron, gateway, và nodes yêu cầu danh tính owner/admin (operator.admin) dù bản thân phương thức tools.invoke là operator.write.
  • Phản hồi là một envelope hướng SDK với các trường ok, toolName, output tùy chọn, và error có kiểu. Từ chối phê duyệt hoặc chính sách trả về ok:false trong payload thay vì bỏ qua pipeline chính sách công cụ của Gateway.
• Người vận hành có thể gọi skills.status (operator.read) để lấy kho skill hiển thị cho một agent.
  • agentId là tùy chọn; bỏ qua để đọc workspace 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.upload.begin, skills.upload.chunk, và skills.upload.commit (operator.admin) để chuẩn bị một kho lưu trữ skill riêng trước khi cài đặt. Đây là đường dẫn tải lên admin riêng cho các client đáng tin cậy, không phải luồng cài đặt skill ClawHub thông thường, và bị tắt theo mặc định trừ khi skills.install.allowUploadedArchives được bật.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) tạo một lượt tải lên được gắn với slug và giá trị force đó.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) nối thêm byte tại offset đã giải mã chính xác.
  • skills.upload.commit({ uploadId, sha256? }) xác minh kích thước cuối cùng và SHA-256. Commit chỉ hoàn tất lượt tải lên; nó không cài đặt skill.
  • Các kho lưu trữ skill đã tải lên là tệp zip chứa root SKILL.md. Tên thư mục nội bộ của kho lưu trữ không bao giờ chọn đích cài đặt.
• Người vận hành có thể gọi skills.install (operator.admin) ở ba 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 workspace agent mặc định.
  • Chế độ tải lên: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } cài đặt một lượt tải lên đã commit vào thư mục skills/<slug> của workspace agent mặc định. Slug và giá trị force phải khớp với yêu cầu skills.upload.begin ban đầu. Chế độ này bị từ chối trừ khi skills.install.allowUploadedArchives được bật. Thiết lập này không ảnh hưởng đến các lượt cài đặt ClawHub.
  • Chế độ trình cài đặt Gateway: { name, installId, timeoutMs? } chạy một hành động metadata.openclaw.install đã khai báo trên máy chủ Gateway. Các client cũ hơn vẫn có thể gửi dangerouslyForceUnsafeInstall; trường này đã bị ngừng khuyến nghị, chỉ được chấp nhận vì tương thích giao thức, và bị bỏ qua. Dùng security.installPolicy cho các quyết định cài đặt do người vận hành sở hữu.
• 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ả các lượt cài đặt ClawHub được theo dõi trong workspace agent mặc định.
  • Chế độ cấu hình vá các giá trị skills.entries.<skillKey> như enabled, apiKey, và env.

​

Chế độ xem models.list

• Bỏ qua hoặc "default": hành vi runtime hiện tại. Nếu agents.defaults.models được cấu hình, phản hồi là catalog được cho phép, bao gồm các model được phát hiện động cho các mục provider/*. Nếu không, phản hồi là toàn bộ catalog Gateway.
• "configured": hành vi có kích thước phù hợp cho bộ chọn. Nếu agents.defaults.models được cấu hình, nó vẫn được ưu tiên, bao gồm khám phá theo phạm vi provider cho các mục provider/*. Khi không có danh sách cho phép, phản hồi dùng các mục models.providers.*.models tường minh, chỉ quay về toàn bộ catalog khi không có hàng model đã cấu hình nào tồn tại.
• "all": toàn bộ catalog 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 model thông thường.

​

Phê duyệt exec

• Khi một yêu cầu exec cần phê duyệt, Gateway phát sóng exec.approval.requested.
• Client người vận hành phân giải 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). Các yêu cầu thiếu systemRunPlan bị từ chối.
• Sau khi phê duyệt, các lời 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 command/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 đã được phê duyệt cuối cùng, Gateway từ chối lượt chạy thay vì tin payload đã bị thay đổi.

​

Fallback phân phối agent

• Các yêu cầu agent có thể bao gồm deliver=true để yêu cầu phân phối outbound.
• bestEffortDeliver=false giữ hành vi nghiêm ngặt: các đích phân phối không phân giải được hoặc chỉ nội bộ trả về INVALID_REQUEST.
• bestEffortDeliver=true cho phép fallback về thực thi chỉ trong phiên khi không thể phân giải tuyến có thể phân phối bên ngoài (ví dụ phiên nội bộ/webchat hoặc cấu hình đa kênh mơ hồ).
• Kết quả agent cuối cùng có thể bao gồm result.deliveryStatus khi phân phối đã được yêu cầu, sử dụng cùng các trạng thái sent, suppressed, partial_failed, và failed được ghi trong tài liệu cho openclaw agent --json --deliver.

​

Quản lý phiên bản

• PROTOCOL_VERSION nằm trong packages/gateway-protocol/src/version.ts.
• Client gửi minProtocol + maxProtocol; máy chủ từ chối các dải không bao gồm giao thức hiện tại của nó. Client và máy chủ hiện tại yêu cầu giao thức v4.
• Schema + model được tạo từ các định nghĩa TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

Hằng số client

​

Auth

• 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 thuộc vào 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 kết nối từ các tiêu đề yêu cầu thay vì connect.params.auth.*.
• gateway.auth.mode: "none" cho lối vào riêng tư bỏ qua hoàn toàn xác thực kết nối bằng bí mật dùng chung; không để lộ chế độ đó trên lối vào công khai/không tin cậy.
• Sau khi ghép đôi, Gateway cấp một mã thông báo thiết bị giới hạn 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 máy khách lưu giữ cho các lần kết nối sau.
• Máy khách nên lưu giữ hello-ok.auth.deviceToken chính sau mọi lần kết nối thành công.
• Việc 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 xuống phạm vi ngầm định chỉ dành cho quản trị viên hẹp hơ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: 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 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. Một mã thông báo dùng chung hoặc bất kỳ mã thông báo thiết bị nào đã phân giải đều chặn nó.
  • Tự động thăng cấp 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:// có tlsFingerprint được 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 người vận hành có giới hạn trong hello-ok.auth.deviceTokens để bàn giao di động tin cậy. Mã thông báo người vận hành bao gồm operator.talk.secrets để đọc cấu hình Talk gốc, nhưng loại trừ các phạm vi thay đổi ghép đôi và operator.admin.
• Khi một bootstrap bằng mã thiết lập không phải đường cơ sở đang chờ phê duyệt, chi tiết PAIRING_REQUIRED bao gồm recommendedNextStep: "wait_then_retry", retryable: true, và pauseReconnect: false. Máy khách 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 giữ hello-ok.auth.deviceTokens khi kết nối đã sử dụng xác thực bootstrap trên một phương thức truyền tải tin cậy như wss:// hoặc ghép đôi loopback/cục bộ.
• Nếu máy khách cung cấp một deviceToken tường minh hoặc scopes tường minh, tập phạm vi do bên gọi yêu cầu đó vẫn là nguồn quyết định; phạm vi được lưu trong bộ nhớ đệm chỉ được tái sử dụng khi máy khách đang tái sử dụng mã thông báo theo thiết bị đã lưu.
• Có thể xoay vòng/thu hồi mã thông báo thiết bị 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ã thông báo của Node hoặc vai trò không phải người vận hành khác cũng yêu cầu operator.admin.
• device.token.rotate trả về siêu dữ liệu xoay vòng. Nó chỉ phản hồi lại 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ị đó, để máy khách chỉ dùng mã thông báo có thể lưu giữ mã thay thế trước khi kết nối lại. Các lượt xoay vòng bằng mã dùng chung/quản trị không phản hồi lại mã thông báo bearer.
• Việc cấp, xoay vòng và thu hồi mã thông báo vẫn được giới hạn trong tập vai trò đã phê duyệt được ghi trong mục ghép đôi của thiết bị đó; thao tác thay đổi mã thông báo không thể mở rộng hoặc nhắm đến vai trò thiết bị mà phê duyệt ghép đôi chưa từng cấp.
• Với các phiên mã thông báo thiết bị đã ghép đôi, quản lý thiết bị tự giới hạn phạm vi 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ể quản lý mã thông báo người vận hành cho mục thiết bị của chính họ. Quản lý mã thông báo của Node và các mã thông báo không phải người vận hành khác chỉ dành cho quản trị viên, ngay cả với thiết bị của chính bên gọi.
• device.token.rotate và device.token.revoke cũng kiểm tra tập phạm vi mã thông báo người vận hành mục tiêu so với các 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 một mã thông báo người vận hành 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 máy khách cho AUTH_TOKEN_MISMATCH:
  • Máy khách tin cậy có thể thử một lần thử lại có giới hạn bằng mã thông báo theo thiết bị được lưu trong bộ nhớ đệm.
  • Nếu lần thử lại đó thất bại, máy khách 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 hành động cho người vận hành.
• 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. Máy khách không nên trình bày lỗi này như một mã thông báo sai; hãy nhắc người vận hành ghép đôi lại hoặc phê duyệt hợp đồng phạm vi hẹp hơn/rộng hơn.

​

Danh tính thiết bị + ghép đôi

• Các Node nên bao gồm một danh tính thiết bị ổn định (device.id) được suy ra từ dấu vân tay cặp khóa.
• Gateway cấp mã thông báo theo thiết bị + vai trò.
• Phê duyệt ghép đôi là bắt buộc cho 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 đô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 hẹp cục bộ phần phụ trợ/vùng chứa cho các luồng trợ giúp bằng bí mật dùng chung tin cậy.
• Các kết nối cùng máy chủ qua tailnet hoặc LAN vẫn được xử lý là từ xa đối với ghép đôi và yêu cầu phê duyệt.
• Máy khách WS thường bao gồm danh tính device trong connect (người vận hành + Node). Các ngoại lệ người vận hành không có thiết bị duy nhất là các đường tin cậy tường minh:
  • gateway.controlUi.allowInsecureAuth=true cho khả năng tương thích HTTP không an toàn chỉ trên localhost.
  • xác thực Control UI người vận hành gateway.auth.mode: "trusted-proxy" thành công.
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (phá kính khẩn cấp, hạ cấp bảo mật nghiêm trọng).
  • RPC phần phụ trợ gateway-client qua direct-loopback trên đường trợ giúp 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 người vận hành không có thiết bị được cho phép qua một đường tin cậy tường minh, OpenClaw vẫn xóa các phạm vi tự khai báo thành tập rỗng trừ khi đường đó có một ngoại lệ bảo toàn phạm vi được đặt tên. Khi đó các phương thức bị chặn theo phạm vi sẽ thất bại với missing scope.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true là một đường bảo toàn phạm vi phá kính khẩn cấp của Control UI. Nó không cấp phạm vi cho các máy khách WebSocket phần phụ trợ tùy chỉnh hoặc dạng CLI tùy ý.
• Đường trợ giúp phần phụ trợ gateway-client direct-loopback dành riêng chỉ bảo toàn phạm vi cho các RPC mặt phẳng điều khiển cục bộ nội bộ; các ID phần phụ trợ tùy chỉnh không nhận ngoại lệ này.
• Mọi 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ý tải trọng v2 bao gồm nonce máy chủ.
• Gửi cùng nonce trong connect.params.device.nonce.
• Tải trọng chữ ký ưu tiên là v3, ràng buộc platform và deviceFamily ngoài các trường thiết bị/máy khách/vai trò/phạm vi/mã thông báo/nonce.
• Chữ ký v2 cũ vẫn được chấp nhận để tương thích, nhưng việc ghim siêu dữ liệu thiết bị đã ghép đô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.
• Máy khách 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 gateway.remote.tlsFingerprint hoặc CLI --tls-fingerprint).

​

Phạm vi

​

Liên quan

• Giao thức cầu nối
• Sổ tay vận hành Gateway