网关协议（WebSocket）

网关 WebSocket 协议是 Moltbot 的唯一控制面与节点传输。所有客户端（CLI、Web UI、macOS 应用、iOS/Android 节点、无头节点）通过 WebSocket 连接，并在握手时声明角色与作用域。

传输

WebSocket，文本帧，JSON payload。
首帧必须为 connect 请求。

握手（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": "moltbot-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 } }
}

下发设备 token 时，hello-ok 还会包含：


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

节点示例


{
  "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": "moltbot-ios/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "…",
      "signature": "…",
      "signedAt": 1737264000000,
      "nonce": "…"
    }
  }
}

帧格式

请求：{type:"req", id, method, params}
响应：{type:"res", id, ok, payload|error}
事件：{type:"event", event, payload, seq?, stateVersion?}

有副作用的 method 需要幂等键（见 schema）。

角色与作用域

角色

operator = 控制面客户端（CLI/UI/自动化）。
node = 能力宿主（camera/screen/canvas/system.run）。

作用域（operator）

常见作用域：

operator.read
operator.write
operator.admin
operator.approvals
operator.pairing

Caps/commands/permissions（节点）

节点在连接时声明能力声明：

caps：高层能力分类。
commands：可调用的命令白名单。
permissions：细粒度开关（如 screen.record、camera.capture）。

网关将这些视为声明并强制服务端白名单。

在线状态

system-presence 返回以设备身份为键的条目。
在线状态条目包含 deviceId、roles、scopes，便于 UI 在设备同时以 operator 和 node 连接时仍按设备显示一行。

节点辅助方法

节点可调用 skills.bins 获取当前 skill 可执行列表，用于自动放行检查。

Exec 审批

当 exec 请求需要审批时，网关会广播 exec.approval.requested。
操作员客户端通过调用 exec.approval.resolve 完成（需 operator.approvals 作用域）。

版本

PROTOCOL_VERSION 定义在 src/gateway/protocol/schema.ts。
客户端发送 minProtocol 与 maxProtocol；服务端拒绝不匹配。
Schema 与模型由 TypeBox 定义生成：
- pnpm protocol:gen
- pnpm protocol:gen:swift
- pnpm protocol:check

认证

若设置了 CLAWDBOT_GATEWAY_TOKEN（或 --token），connect.params.auth.token 必须匹配，否则关闭连接。
配对后，网关会下发与连接角色/作用域绑定的设备 token。在 hello-ok.auth.deviceToken 中返回，客户端应持久化以供后续连接。
设备 token 可通过 device.token.rotate 和 device.token.revoke 轮换/撤销（需 operator.pairing 作用域）。

设备身份与配对

节点应提供由密钥对指纹派生的稳定设备身份（device.id）。
网关按设备 + 角色下发 token。
新设备 ID 需经配对批准，除非启用了本地自动批准。
本地连接包括回环及网关主机自身的 tailnet 地址（同机 tailnet 绑定仍可自动批准）。
所有 WS 客户端在 connect 时都必须包含 device 身份（operator 与 node）。仅当启用 gateway.controlUi.allowInsecureAuth（或应急用 gateway.controlUi.dangerouslyDisableDeviceAuth）时，控制 UI 可省略。
非本地连接必须对服务端提供的 connect.challenge nonce 签名。

TLS 与固定

支持 WS 连接的 TLS。
客户端可选择性固定网关证书指纹（见 gateway.tls 配置及 gateway.remote.tlsFingerprint 或 CLI --tls-fingerprint）。

范围

本协议暴露完整网关 API（状态、频道、模型、聊天、agent、会话、节点、审批等）。具体表面由 src/gateway/protocol/schema.ts 中的 TypeBox schema 定义。