网关协议

​

传输

• WebSocket，使用 JSON 负载的文本帧。
• 第一帧必须是 connect 请求。
• 连接前的帧上限为 64 KiB。成功完成握手后，客户端应遵循 hello-ok.policy.maxPayload 和 hello-ok.policy.maxBufferedBytes 限制。启用诊断后，过大的入站帧和过慢的出站缓冲会在网关关闭或丢弃受影响帧之前发出 payload.large 事件。这些事件会保留大小、限制、表面和安全原因代码。它们不会保留消息正文、附件内容、原始帧正文、令牌、cookie 或密钥值。

​

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

​

节点示例

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

​

帧格式

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

​

角色 + scopes

​

角色

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

​

Scopes（operator）

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

• 无命令请求：operator.pairing
• 带有非 exec 节点命令的请求：operator.pairing + operator.write
• 包含 system.run、system.run.prepare 或 system.which 的请求： operator.pairing + operator.admin

​

Caps/commands/permissions（node）

• caps: camera、canvas、screen、location、voice 和 talk 等高级能力类别。
• commands: 调用的命令允许列表。
• permissions: 细粒度开关（例如 screen.record、camera.capture）。

​

在线状态

• system-presence 返回以设备身份为键的条目。
• 在线状态条目包含 deviceId、roles 和 scopes，因此 UI 即使在同一设备同时以operator和node身份连接时，也能显示单行。
• node.list 包含可选的 lastSeenAtMs 和 lastSeenReason 字段。已连接的节点会将其当前连接时间作为 lastSeenAtMs 并以 connect 作为原因上报；已配对的节点在受信任的节点事件更新其配对元数据时，也可以上报持久化的后台在线状态。

​

节点后台存活事件

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

​

广播事件作用域

• 聊天、agent 和 tool-result 帧（包括流式 agent 事件和工具调用结果）至少需要 operator.read。没有 operator.read 的会话会完全跳过这些帧。
• 插件定义的 plugin.* 广播 会根据插件注册方式，被门控为 operator.write 或 operator.admin。
• 状态和传输事件（heartbeat、presence、tick、连接/断开生命周期等）保持不受限制，以便每个已认证会话都能观察传输健康状况。
• 未知的广播事件族 默认进行 scope 门控（fail-closed），除非注册的处理器显式放宽它们。

​

常见 RPC 方法族

​

常见事件族

• chat：UI 聊天更新，例如 chat.inject 和其他仅 transcript 的聊天 事件。在协议 v4 中，delta 负载携带 deltaText；message 仍然是 累积的 assistant 快照。非前缀替换会设置 replace=true，并使用 deltaText 作为替换文本。
• session.message、session.operation 和 session.tool：订阅的 会话的 transcript、进行中的会话操作，以及事件流更新。
• sessions.changed：会话索引或元数据已更改。
• presence：系统 presence 快照更新。
• tick：周期性 keepalive / 存活事件。
• health：网关健康快照更新。
• heartbeat：heartbeat 事件流更新。
• cron：cron 运行/作业变更事件。
• shutdown：网关关闭通知。
• node.pair.requested / node.pair.resolved：节点配对生命周期。
• node.invoke.request：节点 invoke 请求广播。
• device.pair.requested / device.pair.resolved：已配对设备生命周期。
• voicewake.changed：唤醒词触发配置已更改。
• exec.approval.requested / exec.approval.resolved：exec 审批 生命周期。
• plugin.approval.requested / plugin.approval.resolved：插件审批 生命周期。

​

节点助手方法

• 节点可以调用 skills.bins 来获取当前技能可执行文件列表，用于自动放行检查。

​

Task 账本 RPC

• tasks.list 需要 operator.read。
  • 参数：可选 status（"queued"、"running"、"completed"、 "failed"、"cancelled" 或 "timed_out"）或这些状态的数组， 可选 agentId，可选 sessionKey，可选范围为 1 到 500 的 limit，以及可选字符串 cursor。
  • 结果：{ "tasks": TaskSummary[], "nextCursor"?: string }。
• tasks.get 需要 operator.read。
  • 参数：{ "taskId": string }。
  • 结果：{ "task": TaskSummary }。
  • 缺失的 task id 会返回 Gateway 的 not-found 错误形状。
• tasks.cancel 需要 operator.write。
  • 参数：{ "taskId": string, "reason"?: string }。
  • 结果： { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }。
  • found 表示账本中是否存在匹配任务。cancelled 表示运行时是否接受或记录了取消请求。

​

Operator 辅助方法

• Operators may call commands.list (operator.read) to fetch the runtime command inventory for an agent.
  • agentId is optional; omit it to read the default agent workspace.
  • scope controls which surface the primary name targets:
    • text returns the primary text command token without the leading /
    • native and the default both path return provider-aware native names when available
  • textAliases carries exact slash aliases such as /model and /m.
  • nativeName carries the provider-aware native command name when one exists.
  • provider is optional and only affects native naming plus native plugin command availability.
  • includeArgs=false omits serialized argument metadata from the response.
• Operators may call tools.catalog (operator.read) to fetch the runtime tool catalog for an agent. The response includes grouped tools and provenance metadata:
  • source: core or plugin
  • pluginId: plugin owner when source="plugin"
  • optional: whether a plugin tool is optional
• Operators may call tools.effective (operator.read) to fetch the runtime-effective tool inventory for a session.
  • sessionKey is required.
  • The gateway derives trusted runtime context from the session server-side instead of accepting caller-supplied auth or delivery context.
  • The response is a session-scoped server-derived projection of the active inventory, including core, plugin, channel, and already-discovered MCP server tools.
  • tools.effective is read-only for MCP: it may project a warm session MCP catalog through the final tool policy, but it does not create MCP runtimes, connect transports, or issue tools/list. If no matching warm catalog exists, the response may include a notice such as mcp-not-yet-connected, mcp-not-yet-listed, or mcp-stale-catalog.
  • Effective tool entries use source="core", source="plugin", source="channel", or source="mcp".
• Operators may call tools.invoke (operator.write) to invoke one available tool through the same gateway policy path as /tools/invoke.
  • name is required. args, sessionKey, agentId, confirm, and idempotencyKey are optional.
  • If both sessionKey and agentId are present, the resolved session agent must match agentId.
  • Owner-only core wrappers such as cron, gateway, and nodes require owner/admin identity (operator.admin) even though the tools.invoke method itself is operator.write.
  • The response is an SDK-facing envelope with ok, toolName, optional output, and typed error fields. Approval or policy refusals return ok:false in the payload rather than bypassing the gateway tool policy pipeline.
• Operators may call skills.status (operator.read) to fetch the visible skill inventory for an agent.
  • agentId is optional; omit it to read the default agent workspace.
  • The response includes eligibility, missing requirements, config checks, and sanitized install options without exposing raw secret values.
• Operators may call skills.search and skills.detail (operator.read) for ClawHub discovery metadata.
• Operators may call skills.upload.begin, skills.upload.chunk, and skills.upload.commit (operator.admin) to stage a private skill archive before installing it. This is a separate admin upload path for trusted clients, not the normal ClawHub skill install flow, and is disabled by default unless skills.install.allowUploadedArchives is enabled.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) creates an upload bound to that slug and force value.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) appends bytes at the exact decoded offset.
  • skills.upload.commit({ uploadId, sha256? }) verifies the final size and SHA-256. Commit only finalizes the upload; it does not install the skill.
  • Uploaded skill archives are zip archives containing a SKILL.md root. The archive’s internal directory name never selects the install target.
• Operators may call skills.install (operator.admin) in three modes:
  • ClawHub mode: { source: "clawhub", slug, version?, force? } installs a skill folder into the default agent workspace skills/ directory.
  • Upload mode: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } installs a committed upload into the default agent workspace skills/<slug> directory. The slug and force value must match the original skills.upload.begin request. This mode is rejected unless skills.install.allowUploadedArchives is enabled. The setting does not affect ClawHub installs.
  • Gateway installer mode: { name, installId, timeoutMs? } runs a declared metadata.openclaw.install action on the gateway host. Older clients may still send dangerouslyForceUnsafeInstall; this field is deprecated, accepted only for protocol compatibility, and ignored. Use security.installPolicy for operator-owned install decisions.
• Operators may call skills.update (operator.admin) in two modes:
  • ClawHub mode updates one tracked slug or all tracked ClawHub installs in the default agent workspace.
  • Config mode patches skills.entries.<skillKey> values such as enabled, apiKey, and env.

​

models.list 视图

• 省略或 "default"：当前运行时行为。如果配置了 agents.defaults.models，响应为允许的目录，包括动态发现的 provider/* 条目模型。否则响应为完整的 Gateway 目录。
• "configured"：适合选择器大小的行为。如果配置了 agents.defaults.models，它仍然生效，包括 provider/* 条目的 provider 作用域发现。若没有 allowlist，响应会使用显式的 models.providers.*.models 条目，仅在不存在任何已配置模型行时才回退到完整目录。
• "all"：完整的 Gateway 目录，绕过 agents.defaults.models。用于诊断和发现 UI，而不是普通模型选择器。

​

Exec 审批

• 当 exec 请求需要批准时，网关会广播 exec.approval.requested。
• 操作员客户端通过调用 exec.approval.resolve 来完成处理（需要 operator.approvals 范围）。
• 对于 host=node，exec.approval.request 必须包含 systemRunPlan（规范化的 argv/cwd/rawCommand/会话元数据）。缺少 systemRunPlan 的请求会被拒绝。
• 批准后，转发的 node.invoke system.run 调用会复用该规范化的 systemRunPlan，作为权威的命令/cwd/会话上下文。
• 如果调用方在 prepare 与最终获批的 system.run 转发之间篡改了 command、rawCommand、cwd、agentId 或 sessionKey，网关会拒绝该运行，而不会信任被篡改的负载。

​

Agent 投递回退

• agent 请求可以包含 deliver=true 以请求出站投递。
• bestEffortDeliver=false 保持严格行为：未解析或仅内部可用的投递目标会返回 INVALID_REQUEST。
• bestEffortDeliver=true 允许在无法解析到外部可投递路由时回退到仅会话执行（例如内部/webchat 会话或多通道配置不明确的情况）。
• 最终的 agent 结果在请求了投递时，可能包含 result.deliveryStatus，其状态与 openclaw agent --json --deliver 中文档化的 sent、suppressed、partial_failed 和 failed 状态一致。

​

版本管理

• PROTOCOL_VERSION 位于 packages/gateway-protocol/src/version.ts。
• 客户端发送 minProtocol + maxProtocol；服务器会拒绝不包含其当前协议版本的范围。当前客户端和服务器要求协议 v4。
• 模式 + 模型由 TypeBox 定义生成：
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

客户端常量

​

认证

• Shared-secret gateway auth uses connect.params.auth.token or connect.params.auth.password, depending on the configured auth mode.
• Identity-bearing modes such as Tailscale Serve (gateway.auth.allowTailscale: true) or non-loopback gateway.auth.mode: "trusted-proxy" satisfy the connect auth check from request headers instead of connect.params.auth.*.
• Private-ingress gateway.auth.mode: "none" skips shared-secret connect auth entirely; do not expose that mode on public/untrusted ingress.
• After pairing, the Gateway issues a device token scoped to the connection role + scopes. It is returned in hello-ok.auth.deviceToken and should be persisted by the client for future connects.
• Clients should persist the primary hello-ok.auth.deviceToken after any successful connect.
• Reconnecting with that stored device token should also reuse the stored approved scope set for that token. This preserves read/probe/status access that was already granted and avoids silently collapsing reconnects to a narrower implicit admin-only scope.
• Client-side connect auth assembly (selectConnectAuth in src/gateway/client.ts):
  • auth.password is orthogonal and is always forwarded when set.
  • auth.token is populated in priority order: explicit shared token first, then an explicit deviceToken, then a stored per-device token (keyed by deviceId + role).
  • auth.bootstrapToken is sent only when none of the above resolved an auth.token. A shared token or any resolved device token suppresses it.
  • Auto-promotion of a stored device token on the one-shot AUTH_TOKEN_MISMATCH retry is gated to trusted endpoints only — loopback, or wss:// with a pinned tlsFingerprint. Public wss:// without pinning does not qualify.
• Built-in setup-code bootstrap returns the primary node hello-ok.auth.deviceToken plus a bounded operator token in hello-ok.auth.deviceTokens for trusted mobile handoff. The operator token includes operator.talk.secrets for native Talk configuration reads and excludes operator.admin and operator.pairing.
• While a non-baseline setup-code bootstrap is waiting for approval, PAIRING_REQUIRED details include recommendedNextStep: "wait_then_retry", retryable: true, and pauseReconnect: false. Clients should keep reconnecting with the same bootstrap token until the request is approved or the token becomes invalid.
• Persist hello-ok.auth.deviceTokens only when the connect used bootstrap auth on a trusted transport such as wss:// or loopback/local pairing.
• If a client supplies an explicit deviceToken or explicit scopes, that caller-requested scope set remains authoritative; cached scopes are only reused when the client is reusing the stored per-device token.
• Device tokens can be rotated/revoked via device.token.rotate and device.token.revoke (requires operator.pairing scope). Rotating or revoking a node or other non-operator role also requires operator.admin.
• device.token.rotate returns rotation metadata. It echoes the replacement bearer token only for same-device calls that are already authenticated with that device token, so token-only clients can persist their replacement before reconnecting. Shared/admin rotations do not echo the bearer token.
• Token issuance, rotation, and revocation stay bounded to the approved role set recorded in that device’s pairing entry; token mutation cannot expand or target a device role that pairing approval never granted.
• For paired-device token sessions, device management is self-scoped unless the caller also has operator.admin: non-admin callers can manage only the operator token for their own device entry. Node and other non-operator token management is admin-only, even for the caller’s own device.
• device.token.rotate and device.token.revoke also check the target operator token scope set against the caller’s current session scopes. Non-admin callers cannot rotate or revoke a broader operator token than they already hold.
• Auth failures include error.details.code plus recovery hints:
  • error.details.canRetryWithDeviceToken (boolean)
  • error.details.recommendedNextStep (retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration)
• Client behavior for AUTH_TOKEN_MISMATCH:
  • Trusted clients may attempt one bounded retry with a cached per-device token.
  • If that retry fails, clients should stop automatic reconnect loops and surface operator action guidance.
• AUTH_SCOPE_MISMATCH means the device token was recognized but does not cover the requested role/scopes. Clients should not present this as a bad token; prompt the operator to re-pair or approve the narrower/broader scope contract.

​

设备身份 + 配对

• Nodes should include a stable device identity (device.id) derived from a keypair fingerprint.
• Gateways issue tokens per device + role.
• Pairing approvals are required for new device IDs unless local auto-approval is enabled.
• Pairing auto-approval is centered on direct local loopback connects.
• OpenClaw also has a narrow backend/container-local self-connect path for trusted shared-secret helper flows.
• Same-host tailnet or LAN connects are still treated as remote for pairing and require approval.
• WS clients normally include device identity during connect (operator + node). The only device-less operator exceptions are explicit trust paths:
  • gateway.controlUi.allowInsecureAuth=true for localhost-only insecure HTTP compatibility.
  • successful gateway.auth.mode: "trusted-proxy" operator Control UI auth.
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (break-glass, severe security downgrade).
  • direct-loopback gateway-client backend RPCs authenticated with the shared gateway token/password.
• Omitting device identity has scope consequences. When a Control UI connection lacks device identity, shouldClearUnboundScopesForMissingDeviceIdentity clears self-declared scopes to an empty set for token, password, and trusted-proxy auth. The connection is allowed on explicit trust paths, but scope-gated methods fail. The exception is local Control UI token/password sessions with allowInsecureAuth, which preserve scopes. For other cases, set gateway.controlUi.dangerouslyDisableDeviceAuth=true only as a break-glass scope-preservation path.
• All connections must sign the server-provided connect.challenge nonce.

​

设备认证迁移诊断

• 始终等待 connect.challenge。
• 签名包含服务器 nonce 的 v2 负载。
• 在 connect.params.device.nonce 中发送相同的 nonce。
• 首选签名负载为 v3，它除了 device/client/role/scopes/token/nonce 字段外，还会绑定 platform 和 deviceFamily。
• 为兼容性，旧的 v2 签名仍然被接受，但已配对设备的元数据固定仍会在重连时控制命令策略。

​

TLS + 固定指纹

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

​

范围

​

相关

• Bridge protocol
• 网关运行手册