mirror of
https://github.com/farcasclaudiu/openclaw.git
synced 2026-06-28 19:01:47 +03:00
Docs: update zh-CN translations and pipeline
What: - update zh-CN glossary, TM, and translator prompt - regenerate zh-CN docs and apply targeted fixes - add zh-CN AGENTS pipeline guidance Why: - address terminology/spacing feedback from #6995 Tests: - pnpm build && pnpm check && pnpm test
This commit is contained in:
@@ -1,31 +1,31 @@
|
||||
---
|
||||
read_when:
|
||||
- 实现或更新 Gateway网关 WebSocket 客户端
|
||||
- 调试协议不匹配或连接失败问题
|
||||
- 重新生成协议 schema/模型
|
||||
summary: Gateway网关 WebSocket 协议:握手、帧、版本控制
|
||||
title: Gateway网关协议
|
||||
- 实现或更新 Gateway 网关 WS 客户端
|
||||
- 调试协议不匹配或连接失败
|
||||
- 重新生成协议模式/模型
|
||||
summary: Gateway 网关 WebSocket 协议:握手、帧、版本控制
|
||||
title: Gateway 网关协议
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T20:35:39Z"
|
||||
generated_at: "2026-02-03T07:48:42Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: bdafac40d53565901b2df450617287664d77fe4ff52681fa00cab9046b2fd850
|
||||
source_path: gateway/protocol.md
|
||||
workflow: 14
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Gateway网关协议 (WebSocket)
|
||||
# Gateway 网关协议(WebSocket)
|
||||
|
||||
Gateway网关 WebSocket 协议是 OpenClaw 的**统一控制平面 + 节点传输层**。所有客户端(CLI、Web UI、macOS 应用、iOS/Android 节点、无头节点)均通过 WebSocket 连接,并在握手时声明其**角色** + **作用域**。
|
||||
Gateway 网关 WS 协议是 OpenClaw 的**单一控制平面 + 节点传输**。所有客户端(CLI、Web UI、macOS 应用、iOS/Android 节点、无头节点)都通过 WebSocket 连接,并在握手时声明其**角色** + **作用域**。
|
||||
|
||||
## 传输
|
||||
|
||||
- WebSocket,文本帧携带 JSON 负载。
|
||||
- WebSocket,带有 JSON 负载的文本帧。
|
||||
- 第一帧**必须**是 `connect` 请求。
|
||||
|
||||
## 握手 (connect)
|
||||
## 握手(connect)
|
||||
|
||||
Gateway网关 → 客户端(连接前挑战):
|
||||
Gateway 网关 → 客户端(连接前质询):
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -35,7 +35,7 @@ Gateway网关 → 客户端(连接前挑战):
|
||||
}
|
||||
```
|
||||
|
||||
客户端 → Gateway网关:
|
||||
客户端 → Gateway 网关:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -70,7 +70,7 @@ Gateway网关 → 客户端(连接前挑战):
|
||||
}
|
||||
```
|
||||
|
||||
Gateway网关 → 客户端:
|
||||
Gateway 网关 → 客户端:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -81,7 +81,7 @@ Gateway网关 → 客户端:
|
||||
}
|
||||
```
|
||||
|
||||
当签发设备令牌时,`hello-ok` 还包含:
|
||||
当颁发设备令牌时,`hello-ok` 还包含:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -130,20 +130,20 @@ Gateway网关 → 客户端:
|
||||
|
||||
## 帧格式
|
||||
|
||||
- **请求**:`{type:"req", id, method, params}`
|
||||
- **响应**:`{type:"res", id, ok, payload|error}`
|
||||
- **事件**:`{type:"event", event, payload, seq?, stateVersion?}`
|
||||
- **Request**:`{type:"req", id, method, params}`
|
||||
- **Response**:`{type:"res", id, ok, payload|error}`
|
||||
- **Event**:`{type:"event", event, payload, seq?, stateVersion?}`
|
||||
|
||||
具有副作用的方法需要**幂等键**(参见 schema)。
|
||||
有副作用的方法需要**幂等键**(见模式)。
|
||||
|
||||
## 角色 + 作用域
|
||||
|
||||
### 角色
|
||||
|
||||
- `operator` = 控制平面客户端(CLI/UI/自动化)。
|
||||
- `node` = 能力宿主(摄像头/屏幕/画布/system.run)。
|
||||
- `node` = 能力宿主(camera/screen/canvas/system.run)。
|
||||
|
||||
### 作用域 (operator)
|
||||
### 作用域(operator)
|
||||
|
||||
常用作用域:
|
||||
|
||||
@@ -153,59 +153,68 @@ Gateway网关 → 客户端:
|
||||
- `operator.approvals`
|
||||
- `operator.pairing`
|
||||
|
||||
### 能力/命令/权限 (node)
|
||||
### 能力/命令/权限(node)
|
||||
|
||||
节点在连接时声明能力:
|
||||
节点在连接时声明能力声明:
|
||||
|
||||
- `caps`:高级能力类别。
|
||||
- `commands`:允许调用的命令白名单。
|
||||
- `commands`:invoke 的命令允许列表。
|
||||
- `permissions`:细粒度开关(例如 `screen.record`、`camera.capture`)。
|
||||
|
||||
Gateway网关将这些视为**声明**,并在服务端执行白名单校验。
|
||||
Gateway 网关将这些视为**声明**并强制执行服务器端允许列表。
|
||||
|
||||
## 在线状态
|
||||
|
||||
- `system-presence` 返回以设备身份为键的条目。
|
||||
- 在线状态条目包含 `deviceId`、`roles` 和 `scopes`,这样 UI 可以为每个设备显示一行,即使该设备同时以 **operator** 和 **node** 身份连接。
|
||||
- 在线状态条目包含 `deviceId`、`roles` 和 `scopes`,以便 UI 可以为每个设备显示单行,
|
||||
即使它同时以 **operator** 和 **node** 身份连接。
|
||||
|
||||
### 节点辅助方法
|
||||
|
||||
- 节点可以调用 `skills.bins` 获取当前 Skills 可执行文件列表,用于自动允许检查。
|
||||
- 节点可以调用 `skills.bins` 来获取当前的 skill 可执行文件列表,
|
||||
用于自动允许检查。
|
||||
|
||||
## 执行审批
|
||||
## Exec 审批
|
||||
|
||||
- 当执行请求需要审批时,Gateway网关会广播 `exec.approval.requested`。
|
||||
- Operator 客户端通过调用 `exec.approval.resolve` 进行处理(需要 `operator.approvals` 作用域)。
|
||||
- 当 exec 请求需要审批时,Gateway 网关广播 `exec.approval.requested`。
|
||||
- 操作者客户端通过调用 `exec.approval.resolve` 来解决(需要 `operator.approvals` 作用域)。
|
||||
|
||||
## 版本控制
|
||||
|
||||
- `PROTOCOL_VERSION` 定义在 `src/gateway/protocol/schema.ts` 中。
|
||||
- 客户端发送 `minProtocol` + `maxProtocol`;服务端在不匹配时拒绝连接。
|
||||
- Schema 和模型从 TypeBox 定义生成:
|
||||
- `PROTOCOL_VERSION` 在 `src/gateway/protocol/schema.ts` 中。
|
||||
- 客户端发送 `minProtocol` + `maxProtocol`;服务器拒绝不匹配的。
|
||||
- 模式 + 模型从 TypeBox 定义生成:
|
||||
- `pnpm protocol:gen`
|
||||
- `pnpm protocol:gen:swift`
|
||||
- `pnpm protocol:check`
|
||||
|
||||
## 认证
|
||||
|
||||
- 如果设置了 `OPENCLAW_GATEWAY_TOKEN`(或 `--token`),`connect.params.auth.token` 必须匹配,否则连接将被关闭。
|
||||
- 配对完成后,Gateway网关会签发一个**设备令牌**,其作用域限定为连接的角色 + 作用域。该令牌在 `hello-ok.auth.deviceToken` 中返回,客户端应持久化保存以供后续连接使用。
|
||||
- 设备令牌可通过 `device.token.rotate` 和 `device.token.revoke` 进行轮换/撤销(需要 `operator.pairing` 作用域)。
|
||||
- 如果设置了 `OPENCLAW_GATEWAY_TOKEN`(或 `--token`),`connect.params.auth.token`
|
||||
必须匹配,否则套接字将被关闭。
|
||||
- 配对后,Gateway 网关会颁发一个作用于连接角色 + 作用域的**设备令牌**。它在 `hello-ok.auth.deviceToken` 中返回,
|
||||
客户端应将其持久化以供将来连接使用。
|
||||
- 设备令牌可以通过 `device.token.rotate` 和 `device.token.revoke` 轮换/撤销(需要 `operator.pairing` 作用域)。
|
||||
|
||||
## 设备身份 + 配对
|
||||
|
||||
- 节点应包含一个稳定的设备身份(`device.id`),由密钥对指纹派生。
|
||||
- Gateway网关按设备 + 角色签发令牌。
|
||||
- 新设备 ID 需要配对审批,除非启用了本地自动审批。
|
||||
- **本地**连接包括 local loopback 和 Gateway网关主机自身的 tailnet 地址(因此同一主机的 tailnet 绑定仍可自动审批)。
|
||||
- 所有 WebSocket 客户端在 `connect` 时必须包含 `device` 身份(operator + node)。控制 UI 仅在启用 `gateway.controlUi.allowInsecureAuth` 时可以省略(或使用 `gateway.controlUi.dangerouslyDisableDeviceAuth` 作为紧急措施)。
|
||||
- 非本地连接必须对服务端提供的 `connect.challenge` nonce 进行签名。
|
||||
- 节点应包含从密钥对指纹派生的稳定设备身份(`device.id`)。
|
||||
- Gateway 网关为每个设备 + 角色颁发令牌。
|
||||
- 新设备 ID 需要配对批准,除非启用了本地自动批准。
|
||||
- **本地**连接包括 loopback 和 Gateway 网关主机自身的 tailnet 地址
|
||||
(因此同主机 tailnet 绑定仍可自动批准)。
|
||||
- 所有 WS 客户端在 `connect` 期间必须包含 `device` 身份(operator + node)。
|
||||
控制 UI **仅**在启用 `gateway.controlUi.allowInsecureAuth` 时可以省略它
|
||||
(或使用 `gateway.controlUi.dangerouslyDisableDeviceAuth` 用于紧急情况)。
|
||||
- 非本地连接必须签署服务器提供的 `connect.challenge` nonce。
|
||||
|
||||
## TLS + 证书固定
|
||||
## TLS + 固定
|
||||
|
||||
- WebSocket 连接支持 TLS。
|
||||
- 客户端可选择固定 Gateway网关证书指纹(参见 `gateway.tls` 配置以及 `gateway.remote.tlsFingerprint` 或 CLI `--tls-fingerprint`)。
|
||||
- WS 连接支持 TLS。
|
||||
- 客户端可以选择性地固定 Gateway 网关证书指纹(见 `gateway.tls`
|
||||
配置加上 `gateway.remote.tlsFingerprint` 或 CLI `--tls-fingerprint`)。
|
||||
|
||||
## 范围
|
||||
|
||||
此协议暴露了**完整的 Gateway网关 API**(状态、渠道、模型、聊天、智能体、会话、节点、审批等)。确切的 API 接口由 `src/gateway/protocol/schema.ts` 中的 TypeBox schema 定义。
|
||||
此协议暴露**完整的 Gateway 网关 API**(status、channels、models、chat、
|
||||
agent、sessions、nodes、approvals 等)。确切的接口由 `src/gateway/protocol/schema.ts` 中的 TypeBox 模式定义。
|
||||
|
||||
Reference in New Issue
Block a user