​

Giao thức Gateway (WebSocket)

​

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.

​

Handshake (kết nối)

{
  "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, "policy": { "tickIntervalMs": 15000 } }
}

{
  "auth": {
    "deviceToken": "…",
    "role": "operator",
    "scopes": ["operator.read", "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

• Request: {type:"req", id, method, params}
• Response: {type:"res", id, ok, payload|error}
• Event: {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

​

Caps/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 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ị.
• Các 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 nó kết nối đồng thời với vai trò operator và node.

​

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

• Node có thể gọi skills.bins để lấy danh sách hiện tại các skill executable phục vụ kiểm tra auto-allow.

​

Phê duyệt exec

• Khi một yêu cầu exec cần phê duyệt, gateway phát exec.approval.requested.
• Client operator giải quyết bằng cách gọi exec.approval.resolve (yêu cầu phạm vi operator.approvals).

​

Phiên bản hóa

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

​

Xác thực

• Nếu OPENCLAW_GATEWAY_TOKEN (hoặc --token) được đặt, connect.params.auth.token phải khớp nếu không socket sẽ bị đóng.
• Sau khi ghép cặp, Gateway phát hành một token 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 client lưu trữ cho các lần kết nối sau.
• 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).

​

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

• Node nên bao gồm một danh tính thiết bị ổn định (device.id) được suy ra từ fingerprint của cặp khóa.
• Gateway phát hành token theo từng thiết bị + vai trò.
• Cần phê duyệt ghép cặp cho các ID thiết bị mới trừ khi bật auto-approval cục bộ.
• Kết nối Local bao gồm loopback và địa chỉ tailnet của chính máy chủ gateway (để các ràng buộc tailnet cùng máy chủ vẫn có thể auto-approve).
• Tất cả client WS phải bao gồm danh tính device trong quá trình connect (operator + node). Control UI có thể bỏ qua nó chỉ khi gateway.controlUi.allowInsecureAuth được bật (hoặc gateway.controlUi.dangerouslyDisableDeviceAuth cho trường hợp khẩn cấp).
• Các kết nối không phải local phải ký nonce connect.challenge do máy chủ cung cấp.

​

TLS + pinning

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

​

Phạm vi