Giao thức Gateway

Gateway WS protocol là mặt phẳng điều khiển duy nhất + truyền tải Node cho OpenClaw. Mọi client (CLI, web UI, ứng dụng macOS, Node iOS/Android, Node headless) kết nối qua WebSocket và khai báo role + scope của mình 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 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 đến quá lớn và bộ đệm gửi đi 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ữ 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)

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

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

Client → Gateway:

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 4,
    "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ể thay vì hiển thị nó như một lỗi bắt tay cuối cùng.

server, features, snapshot và policy đều được schema yêu cầu (src/gateway/protocol/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 các URL được lưu trữ có phạm vi.

URL bề mặt Plugin có phạm vi có thể hết hạn. Node 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 dẫn tương thích canvasHostUrl, canvasCapability hoặc node.canvas.capability.refresh đã ngừng dùng; các client native và Gateway hiện tại phải dùng bề mặt Plugin.

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

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

Các 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 các 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 dẫn này được dành riêng cho các RPC mặt phẳng điều khiển nội bộ và ngăn các baseline ghép đô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 Node và client token thiết bị/danh tính thiết bị rõ ràng vẫn dùng các kiểm tra ghép đôi và nâng cấp scope 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"]
  }
}

Trong quá trình bàn giao bootstrap đáng tin cậy, hello-ok.auth cũng có thể bao gồm các mục role bổ sung có giới hạn trong deviceTokens:

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

Đối với luồng bootstrap Node/operator tích hợp sẵn, token Node chính vẫn là scopes: [] và mọi token operator được bàn giao vẫn bị giới hạn trong allowlist operator bootstrap (operator.approvals, operator.read, operator.talk.secrets, operator.write). Kiểm tra scope bootstrap vẫn được đặt tiền tố theo role: các mục operator chỉ thỏa mãn yêu cầu operator, và các role không phải operator vẫn cần scope dưới tiền tố role của chính chúng.

# Ví dụ Node

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 4,
    "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 mô hình scope operator đầy đủ, các kiểm tra tại thời điểm phê duyệt và ngữ nghĩa bí mật dùng chung, xem Scope 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 scope 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).

Các phương thức RPC Gateway do Plugin đăng ký có thể yêu cầu scope operator riêng, nhưng các tiền tố quản trị core dành riêng (config.*, exec.approvals.*, wizard.*, update.*) luôn phân giải thành operator.admin.

Scope phương thức chỉ là cổng kiểm tra đầu tiên. Một số lệnh slash được truy cập qua chat.send áp dụng các 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 scope tại thời điểm phê duyệt bên trên scope phương thức cơ sở:

• 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

# Caps/commands/permissions (Node)

Node khai báo các tuyên bố 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: allowlist lệnh cho invoke.
• permissions: các công tắc chi tiết (ví dụ: screen.record, camera.capture).

Gateway xem chúng là tuyên bố và thực thi allowlist phía máy chủ.

# Presence

• system-presence trả về các mục được khóa theo danh tính thiết bị.
• Mục presence 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 gian 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 presence 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

Node có thể gọi node.event với event: "node.presence.alive" để ghi lại rằng một Node đã ghép đôi đã còn sống trong một lần đánh thức nền mà không đánh dấu nó là đang 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. Các 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 các phiên thiết bị Node đã xác thực; phiên không có thiết bị hoặc chưa ghép đôi trả về handled: false.

Gateway thành công trả về một 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 xem đó là RPC đã được xác nhận, không phải là presence đã được lưu bền vững.

# Định 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 scope để các phiên chỉ có scope ghép đôi hoặc chỉ dành cho Node 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ả 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 theo operator.write hoặc operator.admin, tùy thuộc 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ế để tình trạng truyền tải luôn quan sát được 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 scope (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 client để broadcast duy trì thứ tự tăng đơ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 scope khác nhau của luồng sự kiện.

# Các họ 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 dump đượ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 xem nó là khám phá tính năng, không phải là bản liệt kê đầy đủ của src/gateway/server-methods/*.ts.

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

• chat: các bản cập nhật trò chuyện UI như chat.inject và các sự kiện trò chuyện chỉ dành cho bản ghi khác.
• session.message và session.tool: các bản cập nhật bản ghi/luồng sự kiện cho một phiên đã đăng ký theo dõi.
• sessions.changed: chỉ mục phiên hoặc siêu dữ liệu đã thay đổi.
• presence: các bản cập nhật snapshot trạng thái hiện diện của hệ thống.
• tick: sự kiện keepalive / liveness định kỳ.
• health: bản cập nhật snapshot sức khỏe Gateway.
• heartbeat: bản cập nhật luồng sự kiện Heartbeat.
• cron: sự kiện thay đổi lần chạy/tác vụ 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 trợ giúp Node

• 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 các kiểm tra tự động cho phép.

# Phương thức trợ giúp cho 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 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ó dấu / ở đầ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 mang các bí danh slash chính xác như /model và /m.
  • nativeName mang 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 cách đặt tên native cùng tính khả dụng của lệnh Plugin native.
  • includeArgs=false bỏ qua siêu dữ liệu đố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ụ runtime cho một agent. Phản hồi bao gồm các công cụ đã nhóm và siêu dữ liệu 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 runtime cho một phiên.
  • sessionKey là bắt buộc.
  • Gateway suy ra ngữ cảnh runtime đáng tin cậy từ phía máy chủ phiên 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 hội thoại đang hoạt động có thể dùng ngay lúc này, bao gồm các công cụ core, Plugin và kênh.
• Người vận hành có thể gọi tools.invoke (operator.write) để gọi một công cụ khả dụng thông 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 có mặt, agent của phiên đã phân giải phải khớp với agentId.
  • 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. Các từ chối do 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ụ Gateway.
• Người vận hành có thể gọi skills.status (operator.read) để lấy danh mục Skills 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, các yêu cầu bị thiếu, kiểm tra cấu hình và các tùy chọn cài đặt đã 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) để lấy siêu dữ liệu 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 workspace 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 đang được theo dõi hoặc tất cả các bản cài đặt ClawHub đang đượ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.

# Các chế độ xem models.list

models.list chấp nhận tham số view tùy chọn:

• 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à 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 cho bộ chọn. Nếu agents.defaults.models được cấu hình, nó 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 model nào được cấu hình.
• "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 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 rộ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 scope operator.approvals).
• Với host=node, exec.approval.request phải bao gồm systemRunPlan (argv/cwd/rawCommand/siêu dữ liệu phiên chuẩn). Các yêu cầu thiếu systemRunPlan 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 đã được phê duyệt cuối cùng, Gateway từ chối lần chạy thay vì tin payload đã bị thay đổi.

# Dự phòng 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 dự phòng sang 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ụ các phiên nội bộ/webchat hoặc cấu hình đa kênh mơ hồ).

# Đánh phiên bản

• PROTOCOL_VERSION nằm trong src/gateway/protocol/version.ts.
• Client gửi minProtocol + maxProtocol; máy chủ từ chối các trường hợp không khớp.
• 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

Client tham chiếu trong src/gateway/client.ts dùng các giá trị mặc định này. Các giá trị ổn định trên protocol v4 và là baseline kỳ vọng cho client bên thứ ba.

Hằng số	Mặc định	Nguồn
PROTOCOL_VERSION	4	src/gateway/protocol/version.ts
Thời gian chờ yêu cầu (mỗi RPC)	30_000 ms	src/gateway/client.ts (requestTimeoutMs)
Thời gian chờ tiền xác thực / thử thách kết nối	15_000 ms	src/gateway/handshake-timeouts.ts (cấu hình/env có thể tăng ngân sách máy chủ/client đã ghép cặp)
Backoff kết nối lại ban đầu	1_000 ms	src/gateway/client.ts (backoffMs)
Backoff kết nối lại tối đa	30_000 ms	src/gateway/client.ts (scheduleReconnect)
Kẹp thử lại nhanh sau khi đóng bằng token thiết bị	250 ms	src/gateway/client.ts
Thời gian gia hạn force-stop trước terminate()	250 ms	FORCE_STOP_TERMINATE_GRACE_MS
Thời gian chờ mặc định của stopAndWait()	1_000 ms	STOP_AND_WAIT_TIMEOUT_MS
Khoảng tick mặc định (trước hello-ok)	30_000 ms	src/gateway/client.ts
Đóng do hết thời gian chờ tick	code 4000 khi im lặng vượt quá tickIntervalMs * 2	src/gateway/client.ts
MAX_PAYLOAD_BYTES	25 * 1024 * 1024 (25 MB)	src/gateway/server-constants.ts

Máy chủ quảng bá policy.tickIntervalMs, policy.maxPayload và policy.maxBufferedBytes có hiệu lực trong hello-ok; client nên tuân theo các giá trị đó thay vì các giá trị mặc định trước bắt tay.

# Xác thực

• 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 kết nối từ header của 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 để lộ chế độ đó trên ingress công khai/không đáng tin cậy.
• Sau khi ghép nối, Gateway cấp một mã thông báo thiết bị được giới hạn theo vai trò kết nối + phạm vi. Nó đượ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 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 dùng lại 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ề một phạm vi ngầm định chỉ dành cho quản trị viên.
• Tập hợp xác thực kết nối phía máy khách (selectConnectAuth trong src/gateway/client.ts):
  • auth.password là độ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, sau đó là một deviceToken tường minh, rồi đến mã thông báo theo từng 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 một auth.token. Mã thông báo dùng chung hoặc bất kỳ mã thông báo thiết bị nào được phân giải sẽ chặn nó.
  • Việc 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 đáng tin cậy — loopback, hoặc wss:// với tlsFingerprint được 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à mã thông báo 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 một deviceToken tường minh hoặc scopes tường minh, thì tập phạm vi do bên gọi yêu cầu đó vẫn là nguồn có thẩm quyền; phạm vi trong bộ nhớ đệm chỉ được dùng lại khi máy khách dùng lại mã thông báo theo từng thiết bị đã lưu.
• Mã thông báo thiết bị có thể được xoay/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ề siêu dữ liệu xoay. 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 mã thay thế trước khi kết nối lại. Các lần xoay dùng chung/quản trị viên không phản hồi lại mã thông báo bearer.
• Việc cấp, xoay 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 trong mục ghép nố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 tới vai trò thiết bị mà phê duyệt ghép nối chưa từng cấp.
• Với các phiên mã thông báo thiết bị đã ghép nối, quản lý thiết bị được giới hạn trong 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 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 mã thông báo operator đích 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 hoặc thu hồi một 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 của máy khách với 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 mã thông báo theo từng thiết bị 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.

# Danh tính thiết bị + ghép nối

• Các Node nên bao gồm một danh tính thiết bị ổn định (device.id) được dẫn xuất từ vân tay cặp khóa.
• Gateway cấp mã thông báo theo từng thiết bị + vai trò.
• Cần có phê duyệt ghép nối cho ID thiết bị mới trừ khi bật tự động phê duyệt cục bộ.
• 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 dẫn tự kết nối hẹp trong backend/container-local cho các luồng trợ giúp dùng bí mật dùng chung đáng tin cậy.
• Các kết nối tailnet hoặc LAN cùng máy chủ vẫn được xem là từ xa đối với ghép nối và yêu cầu phê duyệt.
• Máy khách WS thường bao gồm danh tính 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 dẫn 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 operator 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 qua direct-loopback được xác thực bằng mã thông báo/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ị

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

Các lỗi di chuyển thường gặp:

Thông báo	details.code	details.reason	Ý nghĩa
device nonce required	DEVICE_AUTH_NONCE_REQUIRED	device-nonce-missing	Máy khách bỏ qua device.nonce (hoặc gửi rỗng).
device nonce mismatch	DEVICE_AUTH_NONCE_MISMATCH	device-nonce-mismatch	Máy khách đã ký bằng nonce cũ/sai.
device signature invalid	DEVICE_AUTH_SIGNATURE_INVALID	device-signature	Payload chữ ký không khớp payload v2.
device signature expired	DEVICE_AUTH_SIGNATURE_EXPIRED	device-signature-stale	Dấu thời gian đã ký nằm ngoài độ lệch cho phép.
device identity mismatch	DEVICE_AUTH_DEVICE_ID_MISMATCH	device-id-mismatch	device.id không khớp vân tay khóa công khai.
device public key invalid	DEVICE_AUTH_PUBLIC_KEY_INVALID	device-public-key	Định dạng/chuẩn hóa khóa công khai thất bại.

Mục tiêu di chuyển:

• Luôn chờ connect.challenge.
• Ký payload v2 có bao gồm nonce máy chủ.
• 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 bên cạnh 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 ghim siêu dữ liệu 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.
• Máy khách có thể tùy chọn ghim 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

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 src/gateway/protocol/schema.ts.

# Liên quan

• Giao thức bridge
• Runbook Gateway