chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
3eaa2a04f2
commit
e77ba0207b
@ -2,15 +2,15 @@
|
||||
read_when:
|
||||
- 你正在批准设备配对请求
|
||||
- 你需要轮换或撤销设备令牌
|
||||
summary: '`openclaw devices` 的 CLI 参考（设备配对 + 令牌轮换/撤销）'
|
||||
summary: '`openclaw devices` 的 CLI 参考（设备配对 + 令牌轮换/吊销）'
|
||||
title: 设备
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T14:14:31Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-05-03T00:43:02Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: df105135a12ec733e45a67792e8447628f1538fc2536a008d615d46d1eaff5c8
|
||||
source_hash: fa92fd3ffc671c827fa98870bf9df89f3be90adec167fd8ea32698cf2e69991a
|
||||
source_path: cli/devices.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# `openclaw devices`
|
||||
@ -28,13 +28,13 @@ openclaw devices list
|
||||
openclaw devices list --json
|
||||
```
|
||||
|
||||
当设备已配对时，待处理请求的输出会在该设备当前已批准的访问权限旁显示所请求的访问权限。这样可以明确展示作用域/角色升级，而不是看起来像配对已丢失。
|
||||
当设备已经配对时，待处理请求的输出会在设备当前已批准访问权限旁显示请求的访问权限。这样可以明确呈现作用域/角色升级，而不会看起来像配对已丢失。
|
||||
|
||||
### `openclaw devices remove <deviceId>`
|
||||
|
||||
删除一个已配对设备条目。
|
||||
移除一个已配对设备条目。
|
||||
|
||||
当你使用已配对设备令牌进行身份验证时，非管理员调用方只能删除**自己的**设备条目。删除其他设备需要 `operator.admin`。
|
||||
当你使用已配对设备令牌进行身份验证时，非管理员调用方只能移除**自己的**设备条目。移除其他设备需要 `operator.admin`。
|
||||
|
||||
```
|
||||
openclaw devices remove <deviceId>
|
||||
@ -53,15 +53,15 @@ openclaw devices clear --yes --pending --json
|
||||
|
||||
### `openclaw devices approve [requestId] [--latest]`
|
||||
|
||||
通过精确的 `requestId` 批准待处理的设备配对请求。如果省略 `requestId` 或传入 `--latest`，OpenClaw 只会打印所选的待处理请求并退出；在核实详细信息后，请使用精确的请求 ID 重新运行批准命令。
|
||||
通过精确的 `requestId` 批准待处理的设备配对请求。如果省略 `requestId` 或传入 `--latest`，OpenClaw 只会打印选中的待处理请求并退出；验证详情后，使用精确的请求 ID 重新运行批准命令。
|
||||
|
||||
<Note>
|
||||
如果设备使用变更后的认证详情（角色、作用域或公钥）重试配对，OpenClaw 会取代之前的待处理条目并签发一个新的 `requestId`。请在批准前立即运行 `openclaw devices list` 以使用当前 ID。
|
||||
如果设备使用更改后的身份验证详情（角色、作用域或公钥）重试配对，OpenClaw 会取代先前的待处理条目并签发新的 `requestId`。请在批准前立即运行 `openclaw devices list`，以使用当前 ID。
|
||||
</Note>
|
||||
|
||||
如果设备已配对且请求更宽泛的作用域或更高的角色，OpenClaw 会保留现有批准状态，并创建一个新的待处理升级请求。在批准前，请查看 `openclaw devices list` 中的 `Requested` 与 `Approved` 列，或使用 `openclaw devices approve --latest` 预览精确的升级内容。
|
||||
如果设备已经配对，并请求更宽的作用域或更高的角色，OpenClaw 会保留现有批准，并创建新的待处理升级请求。查看 `openclaw devices list` 中的 `Requested` 与 `Approved` 列，或使用 `openclaw devices approve --latest` 在批准前预览精确的升级内容。
|
||||
|
||||
如果 Gateway 网关 已显式配置 `gateway.nodes.pairing.autoApproveCidrs`，来自匹配客户端 IP 的首次 `role: node` 请求可能会在出现在此列表之前就被批准。该策略默认禁用，且绝不会应用于 operator/browser 客户端或升级请求。
|
||||
如果 Gateway 网关显式配置了 `gateway.nodes.pairing.autoApproveCidrs`，来自匹配客户端 IP 的首次 `role: node` 请求可以在出现在此列表之前被批准。该策略默认禁用，并且绝不适用于操作员/浏览器客户端或升级请求。
|
||||
|
||||
```
|
||||
openclaw devices approve
|
||||
@ -79,59 +79,58 @@ openclaw devices reject <requestId>
|
||||
|
||||
### `openclaw devices rotate --device <id> --role <role> [--scope <scope...>]`
|
||||
|
||||
为特定角色轮换设备令牌（可选地更新作用域）。
|
||||
目标角色必须已存在于该设备已批准的配对契约中；轮换不能铸造新的未批准角色。
|
||||
如果你省略 `--scope`，之后使用已存储的轮换后令牌重新连接时，会复用该令牌缓存的已批准作用域。如果你传入显式的 `--scope` 值，这些值将成为未来缓存令牌重新连接时所使用的已存储作用域集合。
|
||||
为特定角色轮换设备令牌（可选择更新作用域）。
|
||||
目标角色必须已经存在于该设备已批准的配对契约中；轮换不能生成新的未批准角色。
|
||||
如果省略 `--scope`，之后使用存储的已轮换令牌重新连接时，会复用该令牌缓存的已批准作用域。如果传入显式的 `--scope` 值，这些值会成为未来缓存令牌重新连接时存储的作用域集合。
|
||||
非管理员已配对设备调用方只能轮换**自己的**设备令牌。
|
||||
目标令牌的作用域集合必须保持在调用方当前会话自身的 operator 作用域范围内；轮换不能铸造或保留比调用方当前拥有的更宽泛的 operator 令牌。
|
||||
目标令牌作用域集合必须保持在调用方会话自身的操作员作用域内；轮换不能生成或保留比调用方现有权限更宽的操作员令牌。
|
||||
|
||||
```
|
||||
openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
|
||||
```
|
||||
|
||||
以 JSON 格式返回轮换元数据。如果调用方正在轮换自己的令牌，且当前使用该设备令牌进行身份验证，则响应还会包含替换令牌，以便客户端在重新连接前持久化保存。共享/管理员轮换不会回显 bearer token。
|
||||
以 JSON 返回轮换元数据。如果调用方在使用该设备令牌进行身份验证时轮换自己的令牌，响应还会包含替换令牌，以便客户端在重新连接前持久化它。共享/管理员轮换不会回显 bearer 令牌。
|
||||
|
||||
### `openclaw devices revoke --device <id> --role <role>`
|
||||
|
||||
撤销特定角色的设备令牌。
|
||||
|
||||
非管理员已配对设备调用方只能撤销**自己的**设备令牌。
|
||||
撤销其他设备的令牌需要 `operator.admin`。
|
||||
目标令牌的作用域集合也必须符合调用方当前会话自身的 operator 作用域；仅具备配对权限的调用方不能撤销 admin/write operator 令牌。
|
||||
非管理员已配对设备调用方只能撤销**自己的**设备令牌。撤销其他设备的令牌需要 `operator.admin`。
|
||||
目标令牌作用域集合也必须适配调用方会话自身的操作员作用域；仅配对调用方不能撤销管理员/写入操作员令牌。
|
||||
|
||||
```
|
||||
openclaw devices revoke --device <deviceId> --role node
|
||||
```
|
||||
|
||||
以 JSON 格式返回撤销结果。
|
||||
以 JSON 返回撤销结果。
|
||||
|
||||
## 常用选项
|
||||
|
||||
- `--url <url>`：Gateway 网关 WebSocket URL（配置时默认使用 `gateway.remote.url`）。
|
||||
- `--url <url>`：Gateway 网关 WebSocket URL（配置后默认为 `gateway.remote.url`）。
|
||||
- `--token <token>`：Gateway 网关令牌（如果需要）。
|
||||
- `--password <password>`：Gateway 网关密码（密码认证）。
|
||||
- `--password <password>`：Gateway 网关密码（密码身份验证）。
|
||||
- `--timeout <ms>`：RPC 超时。
|
||||
- `--json`：JSON 输出（推荐用于脚本）。
|
||||
|
||||
<Warning>
|
||||
当你设置 `--url` 时，CLI 不会回退到配置或环境变量凭证。请显式传入 `--token` 或 `--password`。如果缺少显式凭证，将报错。
|
||||
当你设置 `--url` 时，CLI 不会回退到配置或环境凭证。请显式传入 `--token` 或 `--password`。缺少显式凭证是错误。
|
||||
</Warning>
|
||||
|
||||
## 说明
|
||||
## 注释
|
||||
|
||||
- 令牌轮换会返回一个新令牌（敏感信息）。请像对待密钥一样对待它。
|
||||
- 这些命令需要 `operator.pairing`（或 `operator.admin`）作用域。
|
||||
- `gateway.nodes.pairing.autoApproveCidrs` 是一项可选启用的 Gateway 网关策略，仅适用于新的节点设备配对；它不会改变 CLI 的批准权限。
|
||||
- 令牌轮换和撤销始终限制在该设备已批准的配对角色集合和已批准的作用域基线之内。一个游离的缓存令牌条目不会授予令牌管理目标。
|
||||
- 对于已配对设备令牌会话，跨设备管理仅限管理员：`remove`、`rotate` 和 `revoke` 仅限操作自身，除非调用方具有 `operator.admin`。
|
||||
- 令牌变更同样受调用方作用域限制：仅具备配对权限的会话不能轮换或撤销当前携带 `operator.admin` 或 `operator.write` 的令牌。
|
||||
- `devices clear` 被有意通过 `--yes` 进行保护。
|
||||
- 如果 local loopback 上不可用配对作用域（且未传入显式 `--url`），`list`/`approve` 可以使用本地配对回退。
|
||||
- `devices approve` 在铸造令牌前需要显式请求 ID；省略 `requestId` 或传入 `--latest` 只会预览最新的待处理请求。
|
||||
- 令牌轮换会返回新令牌（敏感）。请像对待密钥一样处理它。
|
||||
- 这些命令需要 `operator.pairing`（或 `operator.admin`）作用域。某些批准还要求调用方持有目标设备将生成或继承的操作员作用域；请参阅[操作员作用域](/zh-CN/gateway/operator-scopes)。
|
||||
- `gateway.nodes.pairing.autoApproveCidrs` 是一个仅用于新节点设备配对的可选 Gateway 网关策略；它不会更改 CLI 批准权限。
|
||||
- 令牌轮换和撤销会保持在该设备已批准的配对角色集合和已批准作用域基线内。零散的缓存令牌条目不会授予令牌管理目标权限。
|
||||
- 对于已配对设备令牌会话，跨设备管理仅限管理员：除非调用方具有 `operator.admin`，否则 `remove`、`rotate` 和 `revoke` 只能作用于自身。
|
||||
- 令牌变更也受调用方作用域约束：仅配对会话不能轮换或撤销当前携带 `operator.admin` 或 `operator.write` 的令牌。
|
||||
- `devices clear` 有意由 `--yes` 保护。
|
||||
- 如果 local loopback 上不可用配对作用域（且未传入显式的 `--url`），list/approve 可以使用本地配对回退。
|
||||
- `devices approve` 在生成令牌前需要显式请求 ID；省略 `requestId` 或传入 `--latest` 只会预览最新的待处理请求。
|
||||
|
||||
## 令牌漂移恢复检查清单
|
||||
|
||||
当 Control UI 或其他客户端持续因 `AUTH_TOKEN_MISMATCH` 或 `AUTH_DEVICE_TOKEN_MISMATCH` 失败时，请使用此清单。
|
||||
当控制 UI 或其他客户端持续因 `AUTH_TOKEN_MISMATCH` 或 `AUTH_DEVICE_TOKEN_MISMATCH` 失败时使用此清单。
|
||||
|
||||
1. 确认当前 Gateway 网关令牌来源：
|
||||
|
||||
@ -145,13 +144,13 @@ openclaw config get gateway.auth.token
|
||||
openclaw devices list
|
||||
```
|
||||
|
||||
3. 为受影响设备轮换 operator 令牌：
|
||||
3. 为受影响设备轮换操作员令牌：
|
||||
|
||||
```bash
|
||||
openclaw devices rotate --device <deviceId> --role operator
|
||||
```
|
||||
|
||||
4. 如果轮换仍不足以解决问题，请移除过期配对并重新批准：
|
||||
4. 如果轮换仍不足以解决问题，移除过期配对并再次批准：
|
||||
|
||||
```bash
|
||||
openclaw devices remove <deviceId>
|
||||
@ -161,14 +160,14 @@ openclaw devices approve <requestId>
|
||||
|
||||
5. 使用当前共享令牌/密码重试客户端连接。
|
||||
|
||||
说明：
|
||||
注释：
|
||||
|
||||
- 正常重连认证优先级依次为：显式共享令牌/密码，然后是显式 `deviceToken`，然后是已存储设备令牌，最后是引导令牌。
|
||||
- 可信的 `AUTH_TOKEN_MISMATCH` 恢复在一次受限重试中，可以临时同时发送共享令牌和已存储设备令牌。
|
||||
- 正常重新连接的身份验证优先级是先显式共享令牌/密码，然后显式 `deviceToken`，然后存储的设备令牌，最后是引导令牌。
|
||||
- 受信任的 `AUTH_TOKEN_MISMATCH` 恢复可以在一次有界重试中临时同时发送共享令牌和存储的设备令牌。
|
||||
|
||||
相关内容：
|
||||
相关：
|
||||
|
||||
- [Dashboard 认证故障排除](/zh-CN/web/dashboard#if-you-see-unauthorized-1008)
|
||||
- [仪表板身份验证故障排除](/zh-CN/web/dashboard#if-you-see-unauthorized-1008)
|
||||
- [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#dashboard-control-ui-connectivity)
|
||||
|
||||
## 相关
|
||||
|
||||
113
docs/zh-CN/gateway/operator-scopes.md
Normal file
113
docs/zh-CN/gateway/operator-scopes.md
Normal file
@ -0,0 +1,113 @@
|
||||
---
|
||||
read_when:
|
||||
- 调试缺少操作员作用域的错误
|
||||
- 查看设备或节点配对审批
|
||||
- 添加或分类 Gateway 网关 RPC 方法
|
||||
summary: Gateway 网关客户端的操作员角色、作用域和批准时检查
|
||||
title: 操作员作用域
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T00:43:07Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 48f59f96b41333af9124ad4083ac5442eedb2d6cebdfff74e3ba256f06d36add
|
||||
source_path: gateway/operator-scopes.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Operator 作用域定义了 Gateway 网关客户端在认证后可以执行什么操作。
|
||||
它们是一个受信任 Gateway 网关 operator 域内的控制平面防护栏，
|
||||
不是敌意多租户隔离。如果你需要在人员、团队或机器之间实现强隔离，
|
||||
请在不同 OS 用户或主机下运行独立的 Gateway 网关。
|
||||
|
||||
相关：[安全](/zh-CN/gateway/security)、[Gateway 网关协议](/zh-CN/gateway/protocol)、
|
||||
[Gateway 网关配对](/zh-CN/gateway/pairing)、[设备 CLI](/zh-CN/cli/devices)。
|
||||
|
||||
## 角色
|
||||
|
||||
Gateway 网关 WebSocket 客户端以一种角色连接：
|
||||
|
||||
- `operator`：控制平面客户端，例如 CLI、Control UI、自动化以及
|
||||
受信任的辅助进程。
|
||||
- `node`：能力主机，例如 macOS、iOS、Android，或通过
|
||||
`node.invoke` 暴露命令的无头节点。
|
||||
|
||||
Operator RPC 方法要求 `operator` 角色。节点发起的方法
|
||||
要求 `node` 角色。
|
||||
|
||||
## 作用域级别
|
||||
|
||||
| 作用域 | 含义 |
|
||||
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `operator.read` | 只读 Status、列表、目录、日志、会话读取，以及其他不会变更控制平面的调用。 |
|
||||
| `operator.write` | 常规可变更 operator 操作，例如发送消息、调用工具、更新 talk/voice 设置，以及节点命令转发。也满足 `operator.read`。 |
|
||||
| `operator.admin` | 管理性控制平面访问。满足每个 `operator.*` 作用域。配置变更、更新、原生钩子、敏感保留命名空间和高风险批准都需要它。 |
|
||||
| `operator.pairing` | 设备和节点配对管理，包括列出、批准、拒绝、移除、轮换和撤销配对记录或设备令牌。 |
|
||||
| `operator.approvals` | Exec 和插件批准 API。 |
|
||||
| `operator.talk.secrets` | 读取包含密钥的 Talk 配置。 |
|
||||
|
||||
未知的未来 `operator.*` 作用域需要精确匹配，除非调用方拥有
|
||||
`operator.admin`。
|
||||
|
||||
## 方法作用域只是第一道门槛
|
||||
|
||||
每个 Gateway 网关 RPC 都有一个最小权限方法作用域。该方法作用域决定
|
||||
请求是否可以到达处理程序。然后，一些处理程序会根据具体要批准或变更的对象，
|
||||
在批准时应用更严格的检查。
|
||||
|
||||
示例：
|
||||
|
||||
- `device.pair.approve` 可通过 `operator.pairing` 访问，但批准
|
||||
operator 设备时，只能签发或保留调用方已经持有的作用域。
|
||||
- `node.pair.approve` 可通过 `operator.pairing` 访问，然后从待处理的节点命令列表中
|
||||
派生额外的批准作用域。
|
||||
- `chat.send` 通常是写入作用域方法，但持久化的 `/config set`
|
||||
和 `/config unset` 在命令级别要求 `operator.admin`。
|
||||
|
||||
这让较低作用域的 operator 可以执行低风险配对操作，而不必让
|
||||
所有配对批准都只能由管理员执行。
|
||||
|
||||
## 设备配对批准
|
||||
|
||||
设备配对记录是已批准角色和作用域的持久来源。
|
||||
已配对设备不会静默获得更广泛访问权限：重新连接时如果请求
|
||||
更广泛角色或更广泛作用域，会创建新的待处理升级请求。
|
||||
|
||||
批准设备请求时：
|
||||
|
||||
- 没有 operator 角色的请求不需要 operator 令牌作用域批准。
|
||||
- 请求 `operator.read`、`operator.write`、`operator.approvals`、
|
||||
`operator.pairing` 或 `operator.talk.secrets` 时，调用方必须持有
|
||||
这些作用域，或持有 `operator.admin`。
|
||||
- 请求 `operator.admin` 时需要 `operator.admin`。
|
||||
- 没有显式作用域的修复请求可以继承现有 operator
|
||||
令牌作用域。如果该现有令牌具有 admin 作用域，批准仍然需要
|
||||
`operator.admin`。
|
||||
|
||||
对于已配对设备令牌会话，除非调用方也拥有 `operator.admin`，
|
||||
否则管理操作受自身作用域限制：非管理员调用方只能轮换、撤销或移除
|
||||
自己的设备条目。
|
||||
|
||||
## 节点配对批准
|
||||
|
||||
旧版 `node.pair.*` 使用单独的 Gateway 网关拥有的节点配对存储。WS 节点
|
||||
使用带有 `role: node` 的设备配对，但适用相同的批准级别词汇。
|
||||
|
||||
`node.pair.approve` 使用待处理请求命令列表来派生额外的
|
||||
必需作用域：
|
||||
|
||||
- 无命令请求：`operator.pairing`
|
||||
- 非 exec 节点命令：`operator.pairing` + `operator.write`
|
||||
- `system.run`、`system.run.prepare` 或 `system.which`：
|
||||
`operator.pairing` + `operator.admin`
|
||||
|
||||
节点配对建立身份和信任。它不会替代节点自身的
|
||||
`system.run` exec 批准策略。
|
||||
|
||||
## 共享密钥认证
|
||||
|
||||
共享 gateway 令牌/密码认证会被视为该 Gateway 网关的受信任 operator 访问。
|
||||
OpenAI 兼容 HTTP 接口和 `/tools/invoke` 会为共享密钥 bearer 认证
|
||||
恢复正常的完整 operator 默认作用域集合，即使调用方发送了更窄的声明作用域。
|
||||
|
||||
带身份的模式，例如受信任代理认证或私有入口 `none`，
|
||||
仍然可以遵守显式声明的作用域。对于真正的信任边界隔离，请使用独立的 Gateway 网关。
|
||||
@ -1,40 +1,45 @@
|
||||
---
|
||||
read_when:
|
||||
- 无需 macOS 界面实现节点配对审批
|
||||
- 实现无需 macOS 界面的节点配对批准
|
||||
- 添加用于批准远程节点的 CLI 流程
|
||||
- 扩展 Gateway 网关协议以支持节点管理
|
||||
summary: 适用于 iOS 和其他远程节点的 Gateway 网关所有节点配对（选项 B）
|
||||
- 使用节点管理扩展 Gateway 网关协议
|
||||
summary: 适用于 iOS 和其他远程节点的 Gateway 网关托管节点配对（选项 B）
|
||||
title: Gateway 网关负责的配对
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T11:53:19Z"
|
||||
generated_at: "2026-05-03T00:43:10Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 5c662b8f5c1bb44cfc306d42ae19ba1c8bc36e0d96130d730b322ee07e02cad8
|
||||
source_hash: f0ce46d487990860ac572c27cc9dd83839e87329132e2624944660bafaf723de
|
||||
source_path: gateway/pairing.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
在 Gateway 网关拥有的配对中，**Gateway 网关** 是允许哪些节点加入的事实来源。UI（macOS 应用、未来的客户端）只是用于批准或拒绝待处理请求的前端。
|
||||
在 Gateway 网关负责的配对中，**Gateway 网关**是决定哪些节点
|
||||
被允许加入的事实来源。UI（macOS 应用、未来客户端）只是用于
|
||||
批准或拒绝待处理请求的前端。
|
||||
|
||||
**重要：** WS 节点在 `connect` 期间使用**设备配对**（角色 `node`）。`node.pair.*` 是单独的配对存储，并**不会**限制 WS 握手。只有显式调用 `node.pair.*` 的客户端才使用此流程。
|
||||
**重要：** WS 节点在 `connect` 期间使用**设备配对**（角色 `node`）。
|
||||
`node.pair.*` 是单独的配对存储，**不会**作为 WS 握手的准入门槛。
|
||||
只有显式调用 `node.pair.*` 的客户端才会使用此流程。
|
||||
|
||||
## 概念
|
||||
|
||||
- **待处理请求**：节点请求加入；需要批准。
|
||||
- **已配对节点**：已批准并签发了认证令牌的节点。
|
||||
- **传输协议**：Gateway 网关 WS 端点会转发请求，但不决定成员资格。（旧版 TCP 桥接支持已移除。）
|
||||
- **已配对节点**：已获批准并签发了身份验证令牌的节点。
|
||||
- **传输协议**：Gateway 网关 WS 端点会转发请求，但不决定
|
||||
成员资格。（旧版 TCP 桥接支持已移除。）
|
||||
|
||||
## 配对的工作方式
|
||||
## 配对如何工作
|
||||
|
||||
1. 节点连接到 Gateway 网关 WS 并请求配对。
|
||||
2. Gateway 网关存储一个**待处理请求**并发出 `node.pair.requested`。
|
||||
3. 你批准或拒绝该请求（CLI 或 UI）。
|
||||
4. 批准后，Gateway 网关签发一个**新令牌**（重新配对时会轮换令牌）。
|
||||
5. 节点使用该令牌重新连接，此时即为“已配对”。
|
||||
5. 节点使用令牌重新连接，此时即为“已配对”。
|
||||
|
||||
待处理请求会在 **5 分钟**后自动过期。
|
||||
|
||||
## CLI 工作流（适合无头环境）
|
||||
## CLI 工作流（适合无界面环境）
|
||||
|
||||
```bash
|
||||
openclaw nodes pending
|
||||
@ -60,64 +65,74 @@ openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"
|
||||
- `node.pair.list` — 列出待处理 + 已配对节点（`operator.pairing`）。
|
||||
- `node.pair.approve` — 批准待处理请求（签发令牌）。
|
||||
- `node.pair.reject` — 拒绝待处理请求。
|
||||
- `node.pair.remove` — 移除陈旧的已配对节点条目。
|
||||
- `node.pair.remove` — 移除过时的已配对节点条目。
|
||||
- `node.pair.verify` — 验证 `{ nodeId, token }`。
|
||||
|
||||
注意事项：
|
||||
注意：
|
||||
|
||||
- `node.pair.request` 对每个节点都是幂等的：重复调用会返回同一个待处理请求。
|
||||
- 对同一个待处理节点的重复请求也会刷新已存储的节点元数据，以及最新的允许列表内已声明命令快照，供操作员查看。
|
||||
- 批准**始终**会生成新令牌；`node.pair.request` 永远不会返回令牌。
|
||||
- `node.pair.request` 对每个节点是幂等的：重复调用会返回同一个
|
||||
待处理请求。
|
||||
- 同一待处理节点的重复请求也会刷新已存储的节点
|
||||
元数据，以及最新的已声明命令允许列表快照，供操作者查看。
|
||||
- 批准**总是**生成全新令牌；`node.pair.request`
|
||||
永远不会返回令牌。
|
||||
- 操作者作用域级别和批准时检查总结在
|
||||
[操作者作用域](/zh-CN/gateway/operator-scopes)中。
|
||||
- 请求可以包含 `silent: true`，作为自动批准流程的提示。
|
||||
- `node.pair.approve` 使用待处理请求声明的命令来强制执行额外的批准作用域：
|
||||
- `node.pair.approve` 使用待处理请求中声明的命令来强制执行
|
||||
额外批准作用域：
|
||||
- 无命令请求：`operator.pairing`
|
||||
- 非 exec 命令请求：`operator.pairing` + `operator.write`
|
||||
- `system.run` / `system.run.prepare` / `system.which` 请求：
|
||||
`operator.pairing` + `operator.admin`
|
||||
|
||||
<Warning>
|
||||
节点配对是信任与身份流程，并会签发令牌。它**不会**按节点固定实时节点命令表面。
|
||||
节点配对是一套信任和身份流程，并会签发令牌。它**不会**按节点固定实时节点命令表面。
|
||||
|
||||
- 实时节点命令来自节点在连接时声明的内容，并且会先应用 Gateway 网关的全局节点命令策略（`gateway.nodes.allowCommands` 和 `denyCommands`）。
|
||||
- 按节点的 `system.run` 允许与询问策略位于节点上的 `exec.approvals.node.*`，不在配对记录中。
|
||||
- 每个节点的 `system.run` 允许和询问策略位于节点上的 `exec.approvals.node.*`，不在配对记录中。
|
||||
|
||||
</Warning>
|
||||
|
||||
## 节点命令限制（2026.3.31+）
|
||||
## 节点命令门控（2026.3.31+）
|
||||
|
||||
<Warning>
|
||||
**破坏性变更：** 从 `2026.3.31` 开始，节点命令会被禁用，直到节点配对获得批准。仅完成设备配对已不足以暴露已声明的节点命令。
|
||||
**重大变更：** 从 `2026.3.31` 开始，节点命令会被禁用，直到节点配对获得批准。仅完成设备配对已不足以暴露声明的节点命令。
|
||||
</Warning>
|
||||
|
||||
当节点首次连接时，会自动请求配对。在配对请求获批之前，该节点的所有待处理节点命令都会被过滤，并且不会执行。一旦通过配对批准建立信任，节点声明的命令就会在正常命令策略约束下可用。
|
||||
当节点首次连接时，会自动请求配对。在配对请求获得批准之前，来自该节点的所有待处理节点命令都会被过滤，并且不会执行。一旦通过配对批准建立信任，节点声明的命令就会在正常命令策略约束下可用。
|
||||
|
||||
这意味着：
|
||||
|
||||
- 以前仅依赖设备配对来暴露命令的节点，现在必须完成节点配对。
|
||||
- 配对批准之前排队的命令会被丢弃，而不是延后执行。
|
||||
- 之前仅依赖设备配对来暴露命令的节点，现在必须完成节点配对。
|
||||
- 配对批准前排队的命令会被丢弃，而不是延后执行。
|
||||
|
||||
## 节点事件信任边界（2026.3.31+）
|
||||
|
||||
<Warning>
|
||||
**破坏性变更：** 节点发起的运行现在会停留在缩减后的受信任表面上。
|
||||
**重大变更：** 节点发起的运行现在会停留在缩减后的可信表面上。
|
||||
</Warning>
|
||||
|
||||
节点发起的摘要及相关会话事件会被限制在预期的受信任表面内。以前依赖更广泛主机或会话工具访问权限的通知驱动流程或节点触发流程可能需要调整。此加固可确保节点事件无法提升到超出节点信任边界允许范围的主机级工具访问权限。
|
||||
节点发起的摘要和相关会话事件会被限制在预期的可信表面内。之前依赖更广泛主机或会话工具访问权限的通知驱动或节点触发流程，可能需要调整。此加固确保节点事件无法提升为超出节点信任边界所允许范围的主机级工具访问。
|
||||
|
||||
持久的节点在线状态更新遵循相同的身份边界。`node.presence.alive` 事件仅接受来自已认证节点设备会话的事件，并且只有当设备/节点身份已经配对时才会更新配对元数据。自行声明的 `client.id` 值不足以写入最后在线状态。
|
||||
持久节点在线状态更新遵循相同的身份边界。`node.presence.alive` 事件
|
||||
只接受来自已认证节点设备会话的事件，并且仅在
|
||||
设备/节点身份已经配对时更新配对元数据。自声明的 `client.id` 值不足以写入
|
||||
最后在线状态。
|
||||
|
||||
## 自动批准（macOS 应用）
|
||||
|
||||
macOS 应用在以下情况下可以选择尝试**静默批准**：
|
||||
macOS 应用可以在以下情况下选择尝试**静默批准**：
|
||||
|
||||
- 请求被标记为 `silent`，并且
|
||||
- 应用可以使用同一用户验证到 Gateway 网关主机的 SSH 连接。
|
||||
|
||||
如果静默批准失败，它会回退到正常的“批准/拒绝”提示。
|
||||
如果静默批准失败，它会回退到常规的“批准/拒绝”提示。
|
||||
|
||||
## 受信任 CIDR 设备自动批准
|
||||
## 可信 CIDR 设备自动批准
|
||||
|
||||
`role: node` 的 WS 设备配对默认仍为手动。对于 Gateway 网关已信任网络路径的私有节点网络，操作员可以通过显式 CIDR 或精确 IP 选择启用：
|
||||
`role: node` 的 WS 设备配对默认仍为手动。对于 Gateway 网关已经信任网络路径的私有
|
||||
节点网络，操作者可以通过显式 CIDR 或精确 IP 选择启用：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -134,25 +149,42 @@ macOS 应用在以下情况下可以选择尝试**静默批准**：
|
||||
安全边界：
|
||||
|
||||
- 未设置 `gateway.nodes.pairing.autoApproveCidrs` 时禁用。
|
||||
- 不存在泛化的 LAN 或私有网络自动批准模式。
|
||||
- 不存在 blanket LAN 或私有网络自动批准模式。
|
||||
- 只有没有请求作用域的新 `role: node` 设备配对符合条件。
|
||||
- 操作员、浏览器、Control UI 和 WebChat 客户端仍为手动。
|
||||
- 角色、作用域、元数据和公钥升级仍为手动。
|
||||
- 同主机 loopback 受信任代理标头路径不符合条件，因为本地调用方可以伪造该路径。
|
||||
- 操作者、浏览器、Control UI 和 WebChat 客户端仍保持手动。
|
||||
- 角色、作用域、元数据和公钥升级仍保持手动。
|
||||
- 同主机 local loopback 可信代理标头路径不符合条件，因为该
|
||||
路径可能被本地调用方伪造。
|
||||
|
||||
## 元数据升级自动批准
|
||||
|
||||
当已配对设备重新连接且仅包含非敏感元数据变更（例如显示名称或客户端平台提示）时，OpenClaw 会将其视为 `metadata-upgrade`。静默自动批准的范围很窄：它仅适用于受信任的非浏览器本地重连，且这些重连已经证明拥有本地或共享凭证，包括同主机原生应用在 OS 版本元数据变更后的重连。浏览器/Control UI 客户端和远程客户端仍使用显式重新批准流程。作用域升级（从读取到写入/管理员）和公钥变更**不**符合元数据升级自动批准条件，它们仍作为显式重新批准请求处理。
|
||||
当已配对设备重新连接且只有非敏感元数据
|
||||
变更（例如显示名称或客户端平台提示）时，OpenClaw 会将其视为
|
||||
`metadata-upgrade`。静默自动批准的范围很窄：它只适用于已经证明拥有本地
|
||||
或共享凭证的可信非浏览器本地重连，包括同主机原生应用在 OS
|
||||
版本元数据变更后的重新连接。浏览器/Control UI 客户端和远程客户端仍然
|
||||
使用显式重新批准流程。作用域升级（从读取到写入/admin）和
|
||||
公钥变更**不**符合元数据升级自动批准条件 —
|
||||
它们仍保持为显式重新批准请求。
|
||||
|
||||
## QR 配对辅助工具
|
||||
|
||||
`/pair qr` 会将配对负载渲染为结构化媒体，以便移动端和浏览器客户端可以直接扫描。
|
||||
`/pair qr` 会将配对载荷渲染为结构化媒体，使移动端和
|
||||
浏览器客户端可以直接扫描。
|
||||
|
||||
删除设备也会清理该设备 ID 的任何陈旧待处理配对请求，因此撤销后 `nodes pending` 不会显示孤立行。
|
||||
删除设备也会清理该
|
||||
设备 ID 的所有过时待处理配对请求，因此 `nodes pending` 在撤销后不会显示孤立行。
|
||||
|
||||
## 本地性与转发标头
|
||||
|
||||
Gateway 网关配对只有在原始 socket 和任何上游代理证据一致时，才会将连接视为 loopback。如果请求抵达 loopback，但携带的 `X-Forwarded-For` / `X-Forwarded-Host` / `X-Forwarded-Proto` 标头指向非本地来源，则该转发标头证据会使 loopback 本地性声明失效。随后配对路径会要求显式批准，而不是静默地将请求视为同主机连接。有关操作员认证的等效规则，请参阅[受信任代理认证](/zh-CN/gateway/trusted-proxy-auth)。
|
||||
Gateway 网关配对只有在原始套接字
|
||||
和任何上游代理证据都一致时，才会将连接视为 loopback。如果请求到达 loopback，但
|
||||
携带指向非本地来源的 `X-Forwarded-For` / `X-Forwarded-Host` / `X-Forwarded-Proto` 标头，
|
||||
该转发标头证据会使
|
||||
loopback 本地性声明失效。随后配对路径会要求显式批准，
|
||||
而不是静默地将该请求视为同主机连接。等效的
|
||||
操作者身份验证规则见
|
||||
[可信代理身份验证](/zh-CN/gateway/trusted-proxy-auth)。
|
||||
|
||||
## 存储（本地，私有）
|
||||
|
||||
@ -161,20 +193,20 @@ Gateway 网关配对只有在原始 socket 和任何上游代理证据一致时
|
||||
- `~/.openclaw/nodes/paired.json`
|
||||
- `~/.openclaw/nodes/pending.json`
|
||||
|
||||
如果你覆盖 `OPENCLAW_STATE_DIR`，`nodes/` 文件夹也会随之移动。
|
||||
如果你覆盖 `OPENCLAW_STATE_DIR`，`nodes/` 文件夹会随之移动。
|
||||
|
||||
安全注意事项：
|
||||
|
||||
- 令牌是机密；请将 `paired.json` 视为敏感文件。
|
||||
- 令牌是机密；应将 `paired.json` 视为敏感文件。
|
||||
- 轮换令牌需要重新批准（或删除节点条目）。
|
||||
|
||||
## 传输协议行为
|
||||
|
||||
- 传输协议是**无状态的**；它不存储成员资格。
|
||||
- 传输协议是**无状态**的；它不存储成员资格。
|
||||
- 如果 Gateway 网关离线或配对被禁用，节点无法配对。
|
||||
- 如果 Gateway 网关处于远程模式，配对仍会针对远程 Gateway 网关的存储执行。
|
||||
|
||||
## 相关内容
|
||||
## 相关
|
||||
|
||||
- [渠道配对](/zh-CN/channels/pairing)
|
||||
- [节点](/zh-CN/nodes)
|
||||
|
||||
@ -2,25 +2,25 @@
|
||||
read_when:
|
||||
- 实现或更新 Gateway 网关 WS 客户端
|
||||
- 调试协议不匹配或连接失败
|
||||
- 重新生成协议架构/模型
|
||||
- 正在重新生成协议架构/模型
|
||||
summary: Gateway 网关 WebSocket 协议：握手、帧、版本控制
|
||||
title: Gateway 网关协议
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T13:34:01Z"
|
||||
generated_at: "2026-05-03T00:43:02Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: bc8bd6bae485f13bbd0e8762d30abdfab7e2aee635f8ebac1a38798493239798
|
||||
source_hash: 06f6e1f2188860362bff481e646bd1c4bae4cf8f9a9ccae4fbd5ceea434d2247
|
||||
source_path: gateway/protocol.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Gateway 网关 WS 协议是 OpenClaw 的**单一控制平面 + 节点传输协议**。所有客户端（CLI、Web UI、macOS 应用、iOS/Android 节点、无头节点）都通过 WebSocket 连接，并在握手时声明其**角色** + **作用域**。
|
||||
Gateway 网关 WS 协议是 OpenClaw 的**单一控制平面 + 节点传输协议**。所有客户端（CLI、Web UI、macOS 应用、iOS/Android 节点、无头节点）都通过 WebSocket 连接，并在握手时声明其 **role** + **scope**。
|
||||
|
||||
## 传输
|
||||
## 传输协议
|
||||
|
||||
- WebSocket，使用带 JSON 载荷的文本帧。
|
||||
- WebSocket，文本帧使用 JSON 载荷。
|
||||
- 第一帧**必须**是 `connect` 请求。
|
||||
- 连接前帧上限为 64 KiB。握手成功后，客户端应遵循 `hello-ok.policy.maxPayload` 和 `hello-ok.policy.maxBufferedBytes` 限制。启用诊断后，过大的入站帧和缓慢的出站缓冲区会在 Gateway 网关关闭或丢弃受影响帧之前发出 `payload.large` 事件。这些事件会保留大小、限制、表面和安全原因代码。它们不会保留消息正文、附件内容、原始帧正文、令牌、Cookie 或机密值。
|
||||
- 连接前帧大小上限为 64 KiB。握手成功后，客户端应遵循 `hello-ok.policy.maxPayload` 和 `hello-ok.policy.maxBufferedBytes` 限制。启用诊断时，过大的入站帧和缓慢的出站缓冲区会在 Gateway 网关关闭或丢弃受影响帧之前发出 `payload.large` 事件。这些事件会保留大小、限制、表面和安全原因代码。它们不会保留消息正文、附件内容、原始帧正文、令牌、Cookie 或密钥值。
|
||||
|
||||
## 握手（connect）
|
||||
|
||||
@ -95,7 +95,7 @@ Gateway 网关 → 客户端：
|
||||
}
|
||||
```
|
||||
|
||||
当 Gateway 网关仍在完成启动 sidecar 时，`connect` 请求可能返回可重试的 `UNAVAILABLE` 错误，并将 `details.reason` 设为 `"startup-sidecars"`，同时带有 `retryAfterMs`。客户端应在其整体连接预算内重试该响应，而不是将其呈现为终止性握手失败。
|
||||
当 Gateway 网关仍在完成启动 sidecar 时，`connect` 请求可能返回可重试的 `UNAVAILABLE` 错误，其中 `details.reason` 设置为 `"startup-sidecars"`，并带有 `retryAfterMs`。客户端应在其总体连接预算内重试该响应，而不是将其暴露为终止性握手失败。
|
||||
|
||||
`server`、`features`、`snapshot` 和 `policy` 都是 schema（`src/gateway/protocol/schema/frames.ts`）要求的字段。`auth` 也是必需的，并报告协商后的角色/作用域。`canvasHostUrl` 是可选的。
|
||||
|
||||
@ -110,7 +110,7 @@ Gateway 网关 → 客户端：
|
||||
}
|
||||
```
|
||||
|
||||
受信任的同进程后端客户端（`client.id: "gateway-client"`、`client.mode: "backend"`）在使用共享 Gateway 网关令牌/密码认证时，可以在直接 local loopback 连接上省略 `device`。此路径保留给内部控制平面 RPC，并避免过期的 CLI/设备配对基线阻塞本地后端工作，例如子智能体会话更新。远程客户端、浏览器来源客户端、节点客户端，以及显式设备令牌/设备身份客户端，仍使用正常的配对和作用域升级检查。
|
||||
受信任的同进程后端客户端（`client.id: "gateway-client"`、`client.mode: "backend"`）在使用共享 Gateway 网关令牌/密码进行认证时，可在直接 local loopback 连接上省略 `device`。此路径保留给内部控制平面 RPC，并防止过期的 CLI/设备配对基线阻塞本地后端工作，例如子智能体会话更新。远程客户端、浏览器源客户端、节点客户端，以及显式设备令牌/设备身份客户端仍使用正常的配对和作用域升级检查。
|
||||
|
||||
签发设备令牌时，`hello-ok` 还会包含：
|
||||
|
||||
@ -143,7 +143,7 @@ Gateway 网关 → 客户端：
|
||||
}
|
||||
```
|
||||
|
||||
对于内置的节点/operator 引导流程，主节点令牌保持 `scopes: []`，任何交接的 operator 令牌都会限制在引导 operator 允许列表（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）内。引导作用域检查保持角色前缀化：operator 条目只满足 operator 请求，非 operator 角色仍需要其自身角色前缀下的作用域。
|
||||
对于内置的节点/操作员引导流程，主节点令牌保持为 `scopes: []`，任何交接的操作员令牌都保持限制在引导操作员允许列表（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）内。引导作用域检查保持以角色为前缀：操作员条目只能满足操作员请求，非操作员角色仍需要其自身角色前缀下的作用域。
|
||||
|
||||
### 节点示例
|
||||
|
||||
@ -180,24 +180,26 @@ Gateway 网关 → 客户端：
|
||||
}
|
||||
```
|
||||
|
||||
## 帧格式
|
||||
## 成帧
|
||||
|
||||
- **请求**：`{type:"req", id, method, params}`
|
||||
- **响应**：`{type:"res", id, ok, payload|error}`
|
||||
- **事件**：`{type:"event", event, payload, seq?, stateVersion?}`
|
||||
|
||||
有副作用的方法需要**幂等键**（见 schema）。
|
||||
有副作用的方法需要**幂等键**（参见 schema）。
|
||||
|
||||
## 角色 + 作用域
|
||||
|
||||
关于完整的操作员作用域模型、审批时检查和共享密钥语义，请参阅 [操作员作用域](/zh-CN/gateway/operator-scopes)。
|
||||
|
||||
### 角色
|
||||
|
||||
- `operator` = 控制平面客户端（CLI/UI/自动化）。
|
||||
- `node` = 能力宿主（camera/screen/canvas/system.run）。
|
||||
|
||||
### 作用域（operator）
|
||||
### 作用域（操作员）
|
||||
|
||||
常见作用域：
|
||||
常用作用域：
|
||||
|
||||
- `operator.read`
|
||||
- `operator.write`
|
||||
@ -208,11 +210,11 @@ Gateway 网关 → 客户端：
|
||||
|
||||
带有 `includeSecrets: true` 的 `talk.config` 需要 `operator.talk.secrets`（或 `operator.admin`）。
|
||||
|
||||
插件注册的 Gateway 网关 RPC 方法可以请求它们自己的 operator 作用域，但保留的核心 admin 前缀（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终解析为 `operator.admin`。
|
||||
插件注册的 Gateway 网关 RPC 方法可以请求其自己的操作员作用域，但保留的核心管理员前缀（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终解析为 `operator.admin`。
|
||||
|
||||
方法作用域只是第一道门。一些通过 `chat.send` 到达的斜杠命令会在其上应用更严格的命令级检查。例如，持久化的 `/config set` 和 `/config unset` 写入需要 `operator.admin`。
|
||||
方法作用域只是第一道门槛。某些通过 `chat.send` 到达的斜杠命令会在其上应用更严格的命令级检查。例如，持久化的 `/config set` 和 `/config unset` 写入需要 `operator.admin`。
|
||||
|
||||
`node.pair.approve` 在基础方法作用域之上，还有额外的批准时作用域检查：
|
||||
`node.pair.approve` 在基础方法作用域之上还有额外的审批时作用域检查：
|
||||
|
||||
- 无命令请求：`operator.pairing`
|
||||
- 带非 exec 节点命令的请求：`operator.pairing` + `operator.write`
|
||||
@ -220,23 +222,23 @@ Gateway 网关 → 客户端：
|
||||
|
||||
### 能力/命令/权限（节点）
|
||||
|
||||
节点在连接时声明能力声明：
|
||||
节点在连接时声明能力主张：
|
||||
|
||||
- `caps`：高级能力类别。
|
||||
- `commands`：用于调用的命令允许列表。
|
||||
- `permissions`：细粒度开关（例如 `screen.record`、`camera.capture`）。
|
||||
|
||||
Gateway 网关会将这些视为**声明**，并强制执行服务器端允许列表。
|
||||
Gateway 网关将这些视为**主张**，并强制执行服务端允许列表。
|
||||
|
||||
## 在线状态
|
||||
|
||||
- `system-presence` 返回以设备身份为键的条目。
|
||||
- 在线状态条目包含 `deviceId`、`roles` 和 `scopes`，因此 UI 可以为每个设备显示单行，即使它同时以 **operator** 和**节点**身份连接。
|
||||
- `node.list` 包含可选的 `lastSeenAtMs` 和 `lastSeenReason` 字段。已连接节点会报告其当前连接时间作为 `lastSeenAtMs`，原因是 `connect`；当受信任节点事件更新其配对元数据时，已配对节点也可以报告持久的后台在线状态。
|
||||
- `system-presence` 返回按设备身份键控的条目。
|
||||
- 在线状态条目包括 `deviceId`、`roles` 和 `scopes`，因此即使同一设备同时以**操作员**和**节点**身份连接，UI 也可以为每个设备显示一行。
|
||||
- `node.list` 包含可选的 `lastSeenAtMs` 和 `lastSeenReason` 字段。已连接节点会将其当前连接时间报告为 `lastSeenAtMs`，原因为 `connect`；当受信任节点事件更新其配对元数据时，已配对节点也可以报告持久的后台在线状态。
|
||||
|
||||
### 节点后台存活事件
|
||||
|
||||
节点可以调用 `node.event`，并传入 `event: "node.presence.alive"`，以记录已配对节点在后台唤醒期间处于存活状态，而不将其标记为已连接。
|
||||
节点可以调用 `node.event` 并使用 `event: "node.presence.alive"`，记录某个已配对节点在后台唤醒期间处于存活状态，但不将其标记为已连接。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -245,7 +247,7 @@ Gateway 网关会将这些视为**声明**，并强制执行服务器端允许
|
||||
}
|
||||
```
|
||||
|
||||
`trigger` 是封闭枚举：`background`、`silent_push`、`bg_app_refresh`、`significant_location`、`manual` 或 `connect`。未知触发字符串会在持久化前由 Gateway 网关规范化为 `background`。该事件仅对已认证的节点设备会话持久；无设备或未配对会话返回 `handled: false`。
|
||||
`trigger` 是闭合枚举：`background`、`silent_push`、`bg_app_refresh`、`significant_location`、`manual` 或 `connect`。未知的触发器字符串在持久化前会由 Gateway 网关规范化为 `background`。该事件仅对已认证的节点设备会话持久化；无设备或未配对会话返回 `handled: false`。
|
||||
|
||||
成功的 Gateway 网关返回结构化结果：
|
||||
|
||||
@ -258,42 +260,42 @@ Gateway 网关会将这些视为**声明**，并强制执行服务器端允许
|
||||
}
|
||||
```
|
||||
|
||||
较旧的 Gateway 网关仍可能对 `node.event` 返回 `{ "ok": true }`；客户端应将其视为已确认的 RPC，而不是持久在线状态的持久化。
|
||||
旧版 Gateway 网关对 `node.event` 仍可能返回 `{ "ok": true }`；客户端应将其视为已确认的 RPC，而不是持久在线状态已保存。
|
||||
|
||||
## 广播事件作用域限定
|
||||
|
||||
服务器推送的 WebSocket 广播事件受作用域门控，因此配对作用域或仅节点会话不会被动接收会话内容。
|
||||
服务端推送的 WebSocket 广播事件受作用域门控，因此配对作用域或仅节点会话不会被动接收会话内容。
|
||||
|
||||
- **聊天、智能体和工具结果帧**（包括流式 `agent` 事件和工具调用结果）至少需要 `operator.read`。没有 `operator.read` 的会话会完全跳过这些帧。
|
||||
- **插件定义的 `plugin.*` 广播**会根据插件注册方式，被门控为 `operator.write` 或 `operator.admin`。
|
||||
- **Status 和传输事件**（`heartbeat`、`presence`、`tick`、连接/断开连接生命周期等）保持不受限制，以便每个已认证会话都能观察传输健康状态。
|
||||
- **未知广播事件族**默认受作用域门控（失败关闭），除非注册的处理程序显式放宽它们。
|
||||
- **插件定义的 `plugin.*` 广播**会根据插件注册方式被门控到 `operator.write` 或 `operator.admin`。
|
||||
- **Status 和传输事件**（`heartbeat`、`presence`、`tick`、连接/断开生命周期等）保持不受限制，因此每个已认证会话都可以观察传输健康状态。
|
||||
- **未知广播事件族**默认受作用域门控（失败关闭），除非已注册处理程序显式放宽限制。
|
||||
|
||||
每个客户端连接都会保留自己的按客户端序列号，因此即使不同客户端看到事件流中不同的作用域过滤子集，广播也会在该套接字上保持单调顺序。
|
||||
每个客户端连接都会保留自己的每客户端序列号，因此即使不同客户端看到事件流中不同的作用域过滤子集，广播也能在该 socket 上保持单调顺序。
|
||||
|
||||
## 常见 RPC 方法族
|
||||
|
||||
公共 WS 表面比上面的握手/认证示例更广。这不是生成的转储，`hello-ok.features.methods` 是一个保守的设备发现列表，由 `src/gateway/server-methods-list.ts` 加上已加载的插件/渠道方法导出构建。请将其视为功能设备发现，而不是 `src/gateway/server-methods/*.ts` 的完整枚举。
|
||||
公共 WS 表面比上面的握手/认证示例更广。这不是生成的转储，`hello-ok.features.methods` 是一个保守的发现列表，由 `src/gateway/server-methods-list.ts` 加上已加载的插件/渠道方法导出构建。请将其视为功能发现，而不是 `src/gateway/server-methods/*.ts` 的完整枚举。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="系统和身份">
|
||||
- `health` 返回缓存的或新探测的 Gateway 网关健康快照。
|
||||
- `diagnostics.stability` 返回最近的有界诊断稳定性记录器。它保留事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称和会话 ID 等操作元数据。它不会保留聊天文本、Webhook 正文、工具输出、原始请求或响应正文、令牌、Cookie 或机密值。需要 operator 读取作用域。
|
||||
- `status` 返回 `/status` 风格的 Gateway 网关摘要；敏感字段仅对 admin 作用域的 operator 客户端包含。
|
||||
- `diagnostics.stability` 返回最近的有界诊断稳定性记录器。它保留操作元数据，例如事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称和会话 ID。它不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、Cookie 或密钥值。需要操作员读取作用域。
|
||||
- `status` 返回 `/status` 风格的 Gateway 网关摘要；敏感字段仅包含给具有管理员作用域的操作员客户端。
|
||||
- `gateway.identity.get` 返回中继和配对流程使用的 Gateway 网关设备身份。
|
||||
- `system-presence` 返回已连接 operator/节点设备的当前在线状态快照。
|
||||
- `system-event` 追加系统事件，并可以更新/广播在线状态上下文。
|
||||
- `system-presence` 返回已连接操作员/节点设备的当前在线状态快照。
|
||||
- `system-event` 追加系统事件，并可更新/广播在线状态上下文。
|
||||
- `last-heartbeat` 返回最新持久化的 Heartbeat 事件。
|
||||
- `set-heartbeats` 切换 Gateway 网关上的 Heartbeat 处理。
|
||||
- `set-heartbeats` 在 Gateway 网关上切换 Heartbeat 处理。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Models 与用量">
|
||||
- `models.list` 返回运行时允许的模型目录。传入 `{ "view": "configured" }` 可获取适合选择器展示的已配置模型（先是 `agents.defaults.models`，然后是 `models.providers.*.models`），或传入 `{ "view": "all" }` 获取完整目录。
|
||||
<Accordion title="Models 和用量">
|
||||
- `models.list` 返回运行时允许的模型目录。传入 `{ "view": "configured" }` 可获取适合选择器展示的已配置模型（先是 `agents.defaults.models`，再是 `models.providers.*.models`），或传入 `{ "view": "all" }` 获取完整目录。
|
||||
- `usage.status` 返回提供商用量窗口/剩余额度摘要。
|
||||
- `usage.cost` 返回某个日期范围内聚合的费用用量摘要。
|
||||
- `doctor.memory.status` 返回当前默认智能体工作区的向量记忆 / 缓存嵌入就绪状态。仅当调用方明确想要实时 ping 嵌入提供商时，才传入 `{ "probe": true }` 或 `{ "deep": true }`。
|
||||
- `doctor.memory.remHarness` 为远程控制平面客户端返回有界、只读的 REM harness 预览。它可以包含工作区路径、记忆片段、渲染后的有依据 markdown，以及深度提升候选项，因此调用方需要 `operator.read`。
|
||||
- `usage.cost` 返回某个日期范围的聚合成本用量摘要。
|
||||
- `doctor.memory.status` 返回活动默认 Agent 工作区的向量记忆/缓存嵌入就绪状态。仅当调用方明确想要实时探测嵌入提供商时，才传入 `{ "probe": true }` 或 `{ "deep": true }`。
|
||||
- `doctor.memory.remHarness` 为远程控制平面客户端返回有界、只读的 REM harness 预览。它可能包含工作区路径、记忆片段、渲染后的有依据 Markdown，以及深度提升候选项，因此调用方需要 `operator.read`。
|
||||
- `sessions.usage` 返回每个会话的用量摘要。
|
||||
- `sessions.usage.timeseries` 返回一个会话的时间序列用量。
|
||||
- `sessions.usage.logs` 返回一个会话的用量日志条目。
|
||||
@ -302,44 +304,44 @@ Gateway 网关会将这些视为**声明**，并强制执行服务器端允许
|
||||
|
||||
<Accordion title="渠道和登录辅助方法">
|
||||
- `channels.status` 返回内置 + 捆绑渠道/插件的 Status 摘要。
|
||||
- `channels.logout` 在渠道支持退出登录时，退出某个特定渠道/账号。
|
||||
- `channels.logout` 在渠道支持退出登录时，退出特定渠道/账号。
|
||||
- `web.login.start` 为当前支持二维码的 Web 渠道提供商启动二维码/Web 登录流程。
|
||||
- `web.login.wait` 等待该二维码/Web 登录流程完成，并在成功后启动该渠道。
|
||||
- `web.login.wait` 等待该二维码/Web 登录流程完成，并在成功后启动渠道。
|
||||
- `push.test` 向已注册的 iOS 节点发送测试 APNs 推送。
|
||||
- `voicewake.get` 返回已存储的唤醒词触发器。
|
||||
- `voicewake.set` 更新唤醒词触发器并广播更改。
|
||||
- `voicewake.set` 更新唤醒词触发器并广播变更。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="消息和日志">
|
||||
- `send` 是在聊天运行器之外面向渠道/账号/线程目标发送消息的直接出站投递 RPC。
|
||||
- `logs.tail` 使用游标/限制和最大字节控制，返回已配置的 Gateway 网关文件日志尾部内容。
|
||||
- `send` 是在聊天运行器之外，面向渠道/账号/线程目标发送的直接出站投递 RPC。
|
||||
- `logs.tail` 返回已配置 Gateway 网关文件日志尾部，支持游标/限制和最大字节控制。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Talk 和 TTS">
|
||||
- `talk.config` 返回生效的 Talk 配置载荷；`includeSecrets` 需要 `operator.talk.secrets`（或 `operator.admin`）。
|
||||
- `talk.mode` 为 WebChat/Control UI 客户端设置/广播当前 Talk 模式状态。
|
||||
- `talk.speak` 通过当前活动的 Talk 语音提供商合成语音。
|
||||
- `tts.status` 返回 TTS 启用状态、当前活动提供商、后备提供商以及提供商配置状态。
|
||||
- `talk.speak` 通过活动的 Talk 语音提供商合成语音。
|
||||
- `tts.status` 返回 TTS 启用状态、活动提供商、回退提供商，以及提供商配置状态。
|
||||
- `tts.providers` 返回可见的 TTS 提供商清单。
|
||||
- `tts.enable` 和 `tts.disable` 切换 TTS 偏好状态。
|
||||
- `tts.setProvider` 更新首选 TTS 提供商。
|
||||
- `tts.convert` 执行一次性文本转语音转换。
|
||||
- `tts.convert` 运行一次性文本转语音转换。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="密钥、配置、更新和向导">
|
||||
- `secrets.reload` 重新解析活动 SecretRefs，并且仅在完全成功时替换运行时密钥状态。
|
||||
- `secrets.resolve` 为特定命令/目标集合解析命令目标密钥分配。
|
||||
- `secrets.reload` 重新解析活动的 SecretRefs，并且仅在完全成功时替换运行时密钥状态。
|
||||
- `secrets.resolve` 解析特定命令/目标集合的命令目标密钥分配。
|
||||
- `config.get` 返回当前配置快照和哈希。
|
||||
- `config.set` 写入经过验证的配置载荷。
|
||||
- `config.set` 写入已验证的配置载荷。
|
||||
- `config.patch` 合并部分配置更新。
|
||||
- `config.apply` 验证并替换完整配置载荷。
|
||||
- `config.schema` 返回 Control UI 和 CLI 工具使用的实时配置 schema 载荷：schema、`uiHints`、版本和生成元数据；当运行时可以加载时，还包括插件 + 渠道 schema 元数据。该 schema 包含字段 `title` / `description` 元数据，这些元数据来自 UI 使用的相同标签和帮助文本；当存在匹配的字段文档时，还包括嵌套对象、通配符、数组项，以及 `anyOf` / `oneOf` / `allOf` 组合分支。
|
||||
- `config.schema.lookup` 为一个配置路径返回按路径限定的查找载荷：规范化路径、浅层 schema 节点、匹配的提示 + `hintPath`，以及用于 UI/CLI 下钻的直接子项摘要。查找 schema 节点会保留面向用户的文档和常见验证字段（`title`、`description`、`type`、`enum`、`const`、`format`、`pattern`、数字/字符串/数组/对象边界，以及 `additionalProperties`、`deprecated`、`readOnly`、`writeOnly` 等标志）。子项摘要会暴露 `key`、规范化后的 `path`、`type`、`required`、`hasChildren`，以及匹配的 `hint` / `hintPath`。
|
||||
- `update.run` 运行 Gateway 网关更新流程，并且仅在更新本身成功时安排重启。包管理器更新会在包替换后强制执行非延迟、无冷却的更新重启，以便旧 Gateway 网关进程不会继续从已替换的 `dist` 树中延迟加载。
|
||||
- `update.status` 返回最新缓存的更新重启哨兵；如果可用，还包括重启后的运行版本。
|
||||
- `config.schema` 返回 Control UI 和 CLI 工具使用的实时配置 schema 载荷：schema、`uiHints`、版本和生成元数据；当运行时可以加载时，还包括插件 + 渠道 schema 元数据。该 schema 包含从 UI 使用的相同标签和帮助文本派生的字段 `title` / `description` 元数据；当存在匹配的字段文档时，也包括嵌套对象、通配符、数组项，以及 `anyOf` / `oneOf` / `allOf` 组合分支。
|
||||
- `config.schema.lookup` 为一个配置路径返回路径作用域的查找载荷：规范化路径、浅层 schema 节点、匹配的提示 + `hintPath`，以及用于 UI/CLI 下钻的直接子项摘要。查找 schema 节点保留面向用户的文档和常见验证字段（`title`、`description`、`type`、`enum`、`const`、`format`、`pattern`、数值/字符串/数组/对象边界，以及 `additionalProperties`、`deprecated`、`readOnly`、`writeOnly` 等标记）。子项摘要暴露 `key`、规范化 `path`、`type`、`required`、`hasChildren`，以及匹配的 `hint` / `hintPath`。
|
||||
- `update.run` 运行 Gateway 网关更新流程，并且仅在更新本身成功时安排重启。包管理器更新会在包替换后强制执行非延迟、无冷却的更新重启，以免旧 Gateway 网关进程继续从已被替换的 `dist` 树中延迟加载。
|
||||
- `update.status` 返回最新缓存的更新重启哨兵；可用时包括重启后的运行版本。
|
||||
- `wizard.start`、`wizard.next`、`wizard.status` 和 `wizard.cancel` 通过 WS RPC 暴露新手引导向导。
|
||||
|
||||
</Accordion>
|
||||
@ -348,54 +350,54 @@ Gateway 网关会将这些视为**声明**，并强制执行服务器端允许
|
||||
- `agents.list` 返回已配置的智能体条目，包括生效模型和运行时元数据。
|
||||
- `agents.create`、`agents.update` 和 `agents.delete` 管理智能体记录和工作区接线。
|
||||
- `agents.files.list`、`agents.files.get` 和 `agents.files.set` 管理为智能体暴露的引导工作区文件。
|
||||
- `artifacts.list`、`artifacts.get` 和 `artifacts.download` 为显式的 `sessionKey`、`runId` 或 `taskId` 范围暴露由转录生成的产物摘要和下载。运行和任务查询会在服务端解析所属会话，并且只返回来源匹配的转录媒体；不安全或本地 URL 来源会返回不支持的下载，而不是在服务端获取。
|
||||
- `agent.identity.get` 返回某个智能体或会话的生效助手身份。
|
||||
- `artifacts.list`、`artifacts.get` 和 `artifacts.download` 为显式 `sessionKey`、`runId` 或 `taskId` 作用域暴露从转录派生的产物摘要和下载。运行和任务查询会在服务端解析所属会话，并且只返回来源匹配的转录媒体；不安全或本地 URL 来源会返回不支持的下载，而不是在服务端获取。
|
||||
- `agent.identity.get` 返回智能体或会话的生效助手身份。
|
||||
- `agent.wait` 等待一次运行完成，并在可用时返回终止快照。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="会话控制">
|
||||
- `sessions.list` 返回当前会话索引；当配置了智能体运行时后端时，包括每行的 `agentRuntime` 元数据。
|
||||
- `sessions.list` 返回当前会话索引；当配置了 Agent Runtimes 后端时，包括每行 `agentRuntime` 元数据。
|
||||
- `sessions.subscribe` 和 `sessions.unsubscribe` 为当前 WS 客户端切换会话变更事件订阅。
|
||||
- `sessions.messages.subscribe` 和 `sessions.messages.unsubscribe` 为一个会话切换转录/消息事件订阅。
|
||||
- `sessions.preview` 返回特定会话键的有界转录预览。
|
||||
- `sessions.describe` 为精确会话键返回一行 Gateway 网关会话。
|
||||
- `sessions.describe` 返回精确会话键对应的一行 Gateway 网关会话。
|
||||
- `sessions.resolve` 解析或规范化会话目标。
|
||||
- `sessions.create` 创建新的会话条目。
|
||||
- `sessions.send` 向现有会话发送消息。
|
||||
- `sessions.steer` 是用于活动会话的中断并引导变体。
|
||||
- `sessions.abort` 中止某个会话的活动工作。调用方可以传入 `key` 加可选的 `runId`，也可以只为 Gateway 网关可解析到会话的活动运行传入 `runId`。
|
||||
- `sessions.steer` 是活动会话的中断并引导变体。
|
||||
- `sessions.abort` 中止会话的活动工作。调用方可以传入 `key` 以及可选 `runId`，也可以只传入 `runId`，用于 Gateway 网关可解析到会话的活动运行。
|
||||
- `sessions.patch` 更新会话元数据/覆盖项，并报告解析后的规范模型以及生效的 `agentRuntime`。
|
||||
- `sessions.reset`、`sessions.delete` 和 `sessions.compact` 执行会话维护。
|
||||
- `sessions.get` 返回完整存储的会话行。
|
||||
- 聊天执行仍使用 `chat.history`、`chat.send`、`chat.abort` 和 `chat.inject`。`chat.history` 会针对 UI 客户端进行显示规范化：可见文本中的内联指令标签会被剥离，纯文本工具调用 XML 载荷（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>`，以及被截断的工具调用块）和泄漏的 ASCII/全角模型控制 token 会被剥离，精确的 `NO_REPLY` / `no_reply` 等纯静默 token 助手行会被省略，过大的行可以被替换为占位符。
|
||||
- 聊天执行仍使用 `chat.history`、`chat.send`、`chat.abort` 和 `chat.inject`。`chat.history` 会为 UI 客户端进行显示规范化：从可见文本中移除内联指令标签；移除纯文本工具调用 XML 载荷（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>`，以及截断的工具调用块）和泄漏的 ASCII/全角模型控制令牌；省略精确 `NO_REPLY` / `no_reply` 等纯静默令牌助手行；超大行可以替换为占位符。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="设备配对和设备 token">
|
||||
<Accordion title="设备配对和设备令牌">
|
||||
- `device.pair.list` 返回待处理和已批准的配对设备。
|
||||
- `device.pair.approve`、`device.pair.reject` 和 `device.pair.remove` 管理设备配对记录。
|
||||
- `device.token.rotate` 在已批准角色和调用方范围边界内轮换配对设备 token。
|
||||
- `device.token.revoke` 在已批准角色和调用方范围边界内撤销配对设备 token。
|
||||
- `device.token.rotate` 在已批准角色和调用方作用域边界内轮换配对设备令牌。
|
||||
- `device.token.revoke` 在已批准角色和调用方作用域边界内撤销配对设备令牌。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="节点配对、调用和待处理工作">
|
||||
- `node.pair.request`、`node.pair.list`、`node.pair.approve`、`node.pair.reject`、`node.pair.remove` 和 `node.pair.verify` 覆盖节点配对和引导验证。
|
||||
- `node.list` 和 `node.describe` 返回已知/已连接节点状态。
|
||||
- `node.rename` 更新配对节点标签。
|
||||
- `node.rename` 更新已配对节点标签。
|
||||
- `node.invoke` 将命令转发到已连接节点。
|
||||
- `node.invoke.result` 返回调用请求的结果。
|
||||
- `node.event` 将源自节点的事件带回 Gateway 网关。
|
||||
- `node.canvas.capability.refresh` 刷新按范围限定的 canvas 能力 token。
|
||||
- `node.canvas.capability.refresh` 刷新作用域内的画布能力令牌。
|
||||
- `node.pending.pull` 和 `node.pending.ack` 是已连接节点队列 API。
|
||||
- `node.pending.enqueue` 和 `node.pending.drain` 管理离线/断开连接节点的持久待处理工作。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="审批族">
|
||||
<Accordion title="审批系列">
|
||||
- `exec.approval.request`、`exec.approval.get`、`exec.approval.list` 和 `exec.approval.resolve` 覆盖一次性 exec 审批请求以及待处理审批查找/重放。
|
||||
- `exec.approval.waitDecision` 等待一个待处理 exec 审批并返回最终决定（超时时返回 `null`）。
|
||||
- `exec.approval.waitDecision` 等待一个待处理 exec 审批，并返回最终决策（超时时返回 `null`）。
|
||||
- `exec.approvals.get` 和 `exec.approvals.set` 管理 Gateway 网关 exec 审批策略快照。
|
||||
- `exec.approvals.node.get` 和 `exec.approvals.node.set` 通过节点中继命令管理节点本地 exec 审批策略。
|
||||
- `plugin.approval.request`、`plugin.approval.list`、`plugin.approval.waitDecision` 和 `plugin.approval.resolve` 覆盖插件定义的审批流程。
|
||||
@ -409,93 +411,89 @@ Gateway 网关会将这些视为**声明**，并强制执行服务器端允许
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### 常见事件族
|
||||
### 常见事件系列
|
||||
|
||||
- `chat`：UI 聊天更新，例如 `chat.inject` 和其他仅转录的聊天
|
||||
事件。
|
||||
- `chat`：UI 聊天更新，例如 `chat.inject` 和其他仅转录聊天事件。
|
||||
- `session.message` 和 `session.tool`：已订阅会话的转录/事件流更新。
|
||||
- `sessions.changed`：会话索引或元数据已更改。
|
||||
- `presence`：系统在线状态快照更新。
|
||||
- `tick`：周期性 keepalive / 存活事件。
|
||||
- `tick`：周期性 keepalive / 活性事件。
|
||||
- `health`：Gateway 网关健康快照更新。
|
||||
- `heartbeat`：heartbeat 事件流更新。
|
||||
- `heartbeat`：Heartbeat 事件流更新。
|
||||
- `cron`：cron 运行/作业变更事件。
|
||||
- `shutdown`：Gateway 网关关闭通知。
|
||||
- `node.pair.requested` / `node.pair.resolved`：节点配对生命周期。
|
||||
- `node.invoke.request`：节点调用请求广播。
|
||||
- `device.pair.requested` / `device.pair.resolved`：配对设备生命周期。
|
||||
- `voicewake.changed`：唤醒词触发器配置已更改。
|
||||
- `exec.approval.requested` / `exec.approval.resolved`：exec 审批
|
||||
生命周期。
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved`：插件审批
|
||||
生命周期。
|
||||
- `exec.approval.requested` / `exec.approval.resolved`：exec 审批生命周期。
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved`：插件审批生命周期。
|
||||
|
||||
### 节点辅助方法
|
||||
|
||||
- 节点可以调用 `skills.bins` 来获取当前技能可执行文件列表，
|
||||
用于自动允许检查。
|
||||
- 节点可以调用 `skills.bins` 来获取当前技能可执行文件列表，用于自动允许检查。
|
||||
|
||||
### 操作员辅助方法
|
||||
### 操作者辅助方法
|
||||
|
||||
- 操作者可以调用 `commands.list`（`operator.read`）来获取智能体的运行时命令清单。
|
||||
- `agentId` 是可选的；省略它可读取默认 Agent 工作区。
|
||||
- `scope` 控制主要 `name` 面向的界面：
|
||||
- 操作员可以调用 `commands.list`（`operator.read`）来获取智能体的运行时命令清单。
|
||||
- `agentId` 是可选的；省略它可读取默认智能体工作区。
|
||||
- `scope` 控制主 `name` 目标所在的表面：
|
||||
- `text` 返回不带前导 `/` 的主文本命令令牌
|
||||
- `native` 和默认的 `both` 路径会在可用时返回感知提供商的原生命令名称
|
||||
- `native` 和默认的 `both` 路径在可用时返回感知提供商的原生命令名称
|
||||
- `textAliases` 携带精确的斜杠别名，例如 `/model` 和 `/m`。
|
||||
- `nativeName` 在存在时携带感知提供商的原生命令名称。
|
||||
- `provider` 是可选的，只影响原生命名以及原生插件命令的可用性。
|
||||
- `provider` 是可选的，并且只影响原生命名以及原生插件命令可用性。
|
||||
- `includeArgs=false` 会从响应中省略序列化的参数元数据。
|
||||
- 操作者可以调用 `tools.catalog`（`operator.read`）来获取智能体的运行时工具目录。响应包含分组工具和来源元数据：
|
||||
- 操作员可以调用 `tools.catalog`（`operator.read`）来获取智能体的运行时工具目录。响应包含分组工具和来源元数据：
|
||||
- `source`：`core` 或 `plugin`
|
||||
- `pluginId`：当 `source="plugin"` 时为插件所有者
|
||||
- `pluginId`：当 `source="plugin"` 时的插件所有者
|
||||
- `optional`：插件工具是否为可选
|
||||
- 操作者可以调用 `tools.effective`（`operator.read`）来获取会话的运行时生效工具清单。
|
||||
- 操作员可以调用 `tools.effective`（`operator.read`）来获取某个会话的运行时生效工具清单。
|
||||
- `sessionKey` 是必需的。
|
||||
- Gateway 网关会从服务端的会话中派生可信运行时上下文，而不是接受调用方提供的认证或投递上下文。
|
||||
- 响应限定在会话范围内，并反映当前活动对话现在可以使用的内容，包括核心、插件和渠道工具。
|
||||
- 操作者可以调用 `tools.invoke`（`operator.write`），通过与 `/tools/invoke` 相同的 Gateway 网关策略路径调用一个可用工具。
|
||||
- Gateway 网关会从服务器端会话推导受信任的运行时上下文，而不是接受调用方提供的身份验证或递送上下文。
|
||||
- 响应以会话为范围，并反映当前活动对话现在可以使用的内容，包括核心、插件和渠道工具。
|
||||
- 操作员可以调用 `tools.invoke`（`operator.write`），通过与 `/tools/invoke` 相同的 Gateway 网关策略路径调用一个可用工具。
|
||||
- `name` 是必需的。`args`、`sessionKey`、`agentId`、`confirm` 和 `idempotencyKey` 是可选的。
|
||||
- 如果同时存在 `sessionKey` 和 `agentId`，解析出的会话智能体必须与 `agentId` 匹配。
|
||||
- 响应是面向 SDK 的信封，包含 `ok`、`toolName`、可选的 `output`，以及带类型的 `error` 字段。审批或策略拒绝会在载荷中返回 `ok:false`，而不是绕过 Gateway 网关工具策略流水线。
|
||||
- 操作者可以调用 `skills.status`（`operator.read`）来获取智能体的可见 skill 清单。
|
||||
- `agentId` 是可选的；省略它可读取默认 Agent 工作区。
|
||||
- 响应包含资格状态、缺失要求、配置检查，以及经过净化的安装选项，且不会暴露原始密钥值。
|
||||
- 操作者可以调用 `skills.search` 和 `skills.detail`（`operator.read`）获取 ClawHub 设备发现元数据。
|
||||
- 操作者可以用两种模式调用 `skills.install`（`operator.admin`）：
|
||||
- ClawHub 模式：`{ source: "clawhub", slug, version?, force? }` 会将一个 skill 文件夹安装到默认 Agent 工作区的 `skills/` 目录。
|
||||
- Gateway 网关安装器模式：`{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` 会在 Gateway 网关主机上运行已声明的 `metadata.openclaw.install` 操作。
|
||||
- 操作者可以用两种模式调用 `skills.update`（`operator.admin`）：
|
||||
- ClawHub 模式会更新一个已跟踪的 slug，或更新默认 Agent 工作区中所有已跟踪的 ClawHub 安装项。
|
||||
- 如果同时存在 `sessionKey` 和 `agentId`，解析出的会话智能体必须匹配 `agentId`。
|
||||
- 响应是面向 SDK 的封套，包含 `ok`、`toolName`、可选的 `output`，以及带类型的 `error` 字段。审批或策略拒绝会在载荷中返回 `ok:false`，而不是绕过 Gateway 网关工具策略管线。
|
||||
- 操作员可以调用 `skills.status`（`operator.read`）来获取智能体的可见 Skills 清单。
|
||||
- `agentId` 是可选的；省略它可读取默认智能体工作区。
|
||||
- 响应包含资格、缺失的要求、配置检查，以及经过净化的安装选项，且不会暴露原始密钥值。
|
||||
- 操作员可以调用 `skills.search` 和 `skills.detail`（`operator.read`）获取 ClawHub 发现元数据。
|
||||
- 操作员可以通过两种模式调用 `skills.install`（`operator.admin`）：
|
||||
- ClawHub 模式：`{ source: "clawhub", slug, version?, force? }` 会将一个 Skill 文件夹安装到默认智能体工作区的 `skills/` 目录。
|
||||
- Gateway 网关安装器模式：`{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` 会在 Gateway 网关主机上运行声明的 `metadata.openclaw.install` 动作。
|
||||
- 操作员可以通过两种模式调用 `skills.update`（`operator.admin`）：
|
||||
- ClawHub 模式会更新一个已跟踪的 slug，或默认智能体工作区中所有已跟踪的 ClawHub 安装。
|
||||
- 配置模式会修补 `skills.entries.<skillKey>` 的值，例如 `enabled`、`apiKey` 和 `env`。
|
||||
|
||||
### `models.list` 视图
|
||||
|
||||
`models.list` 接受可选的 `view` 参数：
|
||||
|
||||
- 省略或 `"default"`：当前运行时行为。如果已配置 `agents.defaults.models`，响应为允许的目录；否则响应为完整 Gateway 网关目录。
|
||||
- `"configured"`：适合选择器规模的行为。如果已配置 `agents.defaults.models`，它仍然优先。否则响应会使用显式的 `models.providers.*.models` 条目，只有在不存在已配置的模型行时才回退到完整目录。
|
||||
- `"all"`：完整 Gateway 网关目录，绕过 `agents.defaults.models`。用于诊断和发现 UI，而不是普通模型选择器。
|
||||
- 省略或 `"default"`：当前运行时行为。如果已配置 `agents.defaults.models`，响应就是允许的目录；否则响应就是完整的 Gateway 网关目录。
|
||||
- `"configured"`：适合选择器大小的行为。如果已配置 `agents.defaults.models`，它仍然优先生效。否则响应使用显式的 `models.providers.*.models` 条目，仅在不存在已配置模型行时回退到完整目录。
|
||||
- `"all"`：完整的 Gateway 网关目录，绕过 `agents.defaults.models`。将此用于诊断和发现 UI，而不是普通模型选择器。
|
||||
|
||||
## Exec 审批
|
||||
## 执行审批
|
||||
|
||||
- 当 exec 请求需要审批时，Gateway 网关会广播 `exec.approval.requested`。
|
||||
- 操作者客户端通过调用 `exec.approval.resolve` 进行处理（需要 `operator.approvals` scope）。
|
||||
- 当执行请求需要审批时，Gateway 网关会广播 `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`，Gateway 网关会拒绝本次运行，而不是信任被修改的载荷。
|
||||
- 审批之后，转发的 `node.invoke system.run` 调用会复用该规范的 `systemRunPlan`，作为权威的命令/cwd/会话上下文。
|
||||
- 如果调用方在准备阶段和最终已审批的 `system.run` 转发之间更改了 `command`、`rawCommand`、`cwd`、`agentId` 或 `sessionKey`，Gateway 网关会拒绝运行，而不是信任被更改的载荷。
|
||||
|
||||
## 智能体投递回退
|
||||
## 智能体递送回退
|
||||
|
||||
- `agent` 请求可以包含 `deliver=true` 来请求出站投递。
|
||||
- `bestEffortDeliver=false` 保持严格行为：无法解析或仅限内部的投递目标会返回 `INVALID_REQUEST`。
|
||||
- `bestEffortDeliver=true` 允许在无法解析外部可投递路由时回退到仅会话执行（例如内部/webchat 会话或多渠道配置不明确）。
|
||||
- `agent` 请求可以包含 `deliver=true` 来请求出站递送。
|
||||
- `bestEffortDeliver=false` 保持严格行为：无法解析或仅限内部的递送目标会返回 `INVALID_REQUEST`。
|
||||
- `bestEffortDeliver=true` 允许在无法解析外部可递送路由时回退到仅会话执行（例如内部/webchat 会话或模糊的多渠道配置）。
|
||||
|
||||
## 版本控制
|
||||
|
||||
- `PROTOCOL_VERSION` 位于 `src/gateway/protocol/schema/protocol-schemas.ts`。
|
||||
- 客户端发送 `minProtocol` + `maxProtocol`；服务器会拒绝不匹配项。
|
||||
- schema + 模型由 TypeBox 定义生成：
|
||||
- 客户端发送 `minProtocol` + `maxProtocol`；服务器会拒绝不匹配的情况。
|
||||
- Schema 和模型由 TypeBox 定义生成：
|
||||
- `pnpm protocol:gen`
|
||||
- `pnpm protocol:gen:swift`
|
||||
- `pnpm protocol:check`
|
||||
@ -508,83 +506,81 @@ Gateway 网关会将这些视为**声明**，并强制执行服务器端允许
|
||||
| ----------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |
|
||||
| 请求超时（每个 RPC） | `30_000` ms | `src/gateway/client.ts`（`requestTimeoutMs`） |
|
||||
| 预认证 / 连接挑战超时 | `15_000` ms | `src/gateway/handshake-timeouts.ts`（配置/环境变量可以提高成对的服务端/客户端预算） |
|
||||
| 预身份验证 / 连接质询超时 | `15_000` ms | `src/gateway/handshake-timeouts.ts`（配置/环境变量可以提高配对的服务器/客户端预算） |
|
||||
| 初始重连退避 | `1_000` ms | `src/gateway/client.ts`（`backoffMs`） |
|
||||
| 最大重连退避 | `30_000` ms | `src/gateway/client.ts`（`scheduleReconnect`） |
|
||||
| 设备令牌关闭后的快速重试限制 | `250` ms | `src/gateway/client.ts` |
|
||||
| `terminate()` 前的强制停止宽限期 | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
|
||||
| 设备令牌关闭后的快速重试钳制 | `250` ms | `src/gateway/client.ts` |
|
||||
| `terminate()` 前的强制停止宽限时间 | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
|
||||
| `stopAndWait()` 默认超时 | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |
|
||||
| 默认 tick 间隔（`hello-ok` 前） | `30_000` ms | `src/gateway/client.ts` |
|
||||
| tick 超时关闭 | 静默超过 `tickIntervalMs * 2` 时使用 code `4000` | `src/gateway/client.ts` |
|
||||
| 默认 tick 间隔（`hello-ok` 前） | `30_000` ms | `src/gateway/client.ts` |
|
||||
| tick 超时关闭 | 静默超过 `tickIntervalMs * 2` 时使用代码 `4000` | `src/gateway/client.ts` |
|
||||
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024`（25 MB） | `src/gateway/server-constants.ts` |
|
||||
|
||||
服务器会在 `hello-ok` 中公布生效的 `policy.tickIntervalMs`、`policy.maxPayload` 和 `policy.maxBufferedBytes`；客户端应遵循这些值，而不是握手前的默认值。
|
||||
服务器会在 `hello-ok` 中通告有效的 `policy.tickIntervalMs`、`policy.maxPayload` 和 `policy.maxBufferedBytes`；客户端应遵循这些值，而不是握手前的默认值。
|
||||
|
||||
## 认证
|
||||
## 身份验证
|
||||
|
||||
- 共享密钥 Gateway 网关认证使用 `connect.params.auth.token` 或
|
||||
`connect.params.auth.password`，具体取决于配置的认证模式。
|
||||
- 带身份的模式，例如 Tailscale Serve
|
||||
(`gateway.auth.allowTailscale: true`) 或非 loopback
|
||||
`gateway.auth.mode: "trusted-proxy"`，会通过请求标头满足连接认证检查，
|
||||
而不是通过 `connect.params.auth.*`。
|
||||
`connect.params.auth.password`，具体取决于已配置的认证模式。
|
||||
- Tailscale Serve（`gateway.auth.allowTailscale: true`）或非 loopback
|
||||
`gateway.auth.mode: "trusted-proxy"` 等带有身份信息的模式，会从请求标头满足连接认证检查，
|
||||
而不是使用 `connect.params.auth.*`。
|
||||
- 私有入口 `gateway.auth.mode: "none"` 会完全跳过共享密钥连接认证；
|
||||
不要在公开/不受信任的入口上暴露该模式。
|
||||
- 配对后，Gateway 网关会签发一个限定为连接角色 + 作用域的**设备令牌**。
|
||||
它会在 `hello-ok.auth.deviceToken` 中返回，客户端应将其持久化以供未来连接使用。
|
||||
- 客户端应在任何成功连接后持久化主 `hello-ok.auth.deviceToken`。
|
||||
- 使用该**已存储**设备令牌重新连接时，也应复用为该令牌存储的已批准作用域集。
|
||||
这会保留已授予的读取/探测/status 访问权限，并避免将重新连接静默收窄为
|
||||
仅管理员的隐式作用域。
|
||||
不要在公共/不受信任的入口上暴露该模式。
|
||||
- 配对后，Gateway 网关会签发一个限定到连接角色 + 作用域的**设备令牌**。
|
||||
它会在 `hello-ok.auth.deviceToken` 中返回，客户端应将其持久化用于后续连接。
|
||||
- 客户端应在任何成功连接后持久化主要的 `hello-ok.auth.deviceToken`。
|
||||
- 使用该**已存储**的设备令牌重新连接时，也应复用为该令牌存储的已批准作用域集合。
|
||||
这会保留已经授予的读取/探测/status 访问权限，并避免将重连静默收窄为隐式的仅管理员作用域。
|
||||
- 客户端连接认证组装（`src/gateway/client.ts` 中的 `selectConnectAuth`）：
|
||||
- `auth.password` 是正交的，设置后始终会被转发。
|
||||
- `auth.token` 按优先级填充：显式共享令牌优先，
|
||||
然后是显式 `deviceToken`，再然后是已存储的每设备令牌（按
|
||||
`deviceId` + `role` 作为键）。
|
||||
- 仅当上述任一项都未解析出 `auth.token` 时，才会发送
|
||||
- `auth.password` 是正交的，设置后始终会转发。
|
||||
- `auth.token` 按优先级填充：先使用显式共享令牌，
|
||||
然后是显式 `deviceToken`，最后是已存储的按设备令牌（按
|
||||
`deviceId` + `role` 键控）。
|
||||
- 只有当上述任何一项都没有解析出 `auth.token` 时，才会发送
|
||||
`auth.bootstrapToken`。共享令牌或任何已解析的设备令牌都会抑制它。
|
||||
- 在一次性 `AUTH_TOKEN_MISMATCH` 重试中，自动提升已存储设备令牌仅限于**受信任端点** —
|
||||
loopback，或带有固定 `tlsFingerprint` 的 `wss://`。未固定的公开
|
||||
`wss://` 不符合条件。
|
||||
- 额外的 `hello-ok.auth.deviceTokens` 条目是引导交接令牌。
|
||||
仅当连接在受信任传输上使用引导认证时才持久化它们，例如 `wss://` 或
|
||||
loopback/本地配对。
|
||||
- 如果客户端提供**显式** `deviceToken` 或显式 `scopes`，则该调用方请求的作用域集仍为权威来源；
|
||||
缓存作用域仅在客户端复用已存储的每设备令牌时才会被复用。
|
||||
- 在一次性 `AUTH_TOKEN_MISMATCH` 重试中自动提升已存储设备令牌，仅限于**受信任端点**：
|
||||
loopback，或带有已固定 `tlsFingerprint` 的 `wss://`。没有固定的公共 `wss://`
|
||||
不符合条件。
|
||||
- 额外的 `hello-ok.auth.deviceTokens` 条目是 bootstrap 交接令牌。
|
||||
只有当连接在受信任传输上使用 bootstrap 认证时才持久化它们，
|
||||
例如 `wss://` 或 loopback/local 配对。
|
||||
- 如果客户端提供**显式** `deviceToken` 或显式 `scopes`，
|
||||
则该调用方请求的作用域集合仍然具有权威性；只有当客户端复用已存储的按设备令牌时，
|
||||
才会复用缓存的作用域。
|
||||
- 设备令牌可通过 `device.token.rotate` 和
|
||||
`device.token.revoke` 轮换/撤销（需要 `operator.pairing` 作用域）。
|
||||
- `device.token.rotate` 返回轮换元数据。只有在同设备调用且已使用
|
||||
该设备令牌完成认证时，它才会回显替换用 bearer 令牌，这样仅令牌客户端可在
|
||||
重新连接前持久化替换令牌。共享/管理员轮换不会回显 bearer 令牌。
|
||||
- 令牌签发、轮换和撤销都会受限于该设备配对条目中记录的已批准角色集；
|
||||
令牌变更不能扩展或指向配对批准从未授予的设备角色。
|
||||
- 对于已配对设备令牌会话，除非调用方还拥有 `operator.admin`，否则设备管理是自限定作用域的：
|
||||
非管理员调用方只能移除/撤销/轮换其**自己的**设备条目。
|
||||
- `device.token.rotate` 和 `device.token.revoke` 还会将目标 operator
|
||||
令牌作用域集与调用方当前会话作用域进行检查。非管理员调用方不能轮换或撤销比自己已持有作用域更宽的
|
||||
operator 令牌。
|
||||
`device.token.revoke` 轮换/吊销（需要 `operator.pairing` 作用域）。
|
||||
- `device.token.rotate` 返回轮换元数据。只有在同一设备调用且已使用该设备令牌完成认证时，
|
||||
它才会回显替换用的 bearer 令牌，因此仅令牌客户端可以在重新连接前持久化替换令牌。
|
||||
共享/管理员轮换不会回显 bearer 令牌。
|
||||
- 令牌签发、轮换和吊销始终受限于该设备配对条目中记录的已批准角色集合；
|
||||
令牌变更不能扩展到或指向配对批准从未授予的设备角色。
|
||||
- 对于已配对设备令牌会话，设备管理默认限定到自身范围，除非调用方还拥有
|
||||
`operator.admin`：非管理员调用方只能移除/吊销/轮换其**自己的**设备条目。
|
||||
- `device.token.rotate` 和 `device.token.revoke` 还会根据调用方当前会话作用域检查目标操作员令牌作用域集合。
|
||||
非管理员调用方不能轮换或吊销比自己已持有范围更宽的操作员令牌。
|
||||
- 认证失败包含 `error.details.code` 以及恢复提示：
|
||||
- `error.details.canRetryWithDeviceToken`（布尔值）
|
||||
- `error.details.recommendedNextStep`（`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`）
|
||||
- 客户端针对 `AUTH_TOKEN_MISMATCH` 的行为：
|
||||
- 受信任客户端可以尝试一次有界重试，使用缓存的每设备令牌。
|
||||
- 如果该重试失败，客户端应停止自动重新连接循环，并显示 operator 操作指导。
|
||||
- `AUTH_TOKEN_MISMATCH` 的客户端行为：
|
||||
- 受信任客户端可以尝试一次有界重试，并使用缓存的按设备令牌。
|
||||
- 如果该重试失败，客户端应停止自动重连循环，并显示操作员操作指引。
|
||||
|
||||
## 设备身份 + 配对
|
||||
|
||||
- 节点应包含从密钥对指纹派生的稳定设备身份（`device.id`）。
|
||||
- Gateway 网关会按设备 + 角色签发令牌。
|
||||
- 除非启用了本地自动批准，否则新的设备 ID 需要配对批准。
|
||||
- 新设备 ID 需要配对批准，除非启用了本地自动批准。
|
||||
- 配对自动批准以直接 local loopback 连接为中心。
|
||||
- OpenClaw 还提供一个狭窄的后端/容器本地自连接路径，用于受信任的共享密钥辅助流程。
|
||||
- 同主机 tailnet 或 LAN 连接仍会被视为远程配对，并需要批准。
|
||||
- WS 客户端通常会在 `connect` 期间包含 `device` 身份（operator +
|
||||
节点）。仅以下显式信任路径属于无设备 operator 例外：
|
||||
- `gateway.controlUi.allowInsecureAuth=true`，用于仅限 localhost 的不安全 HTTP 兼容。
|
||||
- 成功的 `gateway.auth.mode: "trusted-proxy"` operator Control UI 认证。
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（应急破窗，严重降低安全性）。
|
||||
- OpenClaw 还为受信任的共享密钥辅助流程提供一条狭窄的后端/容器本地自连接路径。
|
||||
- 同主机 tailnet 或 LAN 连接在配对时仍视为远程连接，并需要批准。
|
||||
- WS 客户端通常会在 `connect` 期间包含 `device` 身份（操作员 + 节点）。
|
||||
唯一无设备的操作员例外是显式信任路径：
|
||||
- `gateway.controlUi.allowInsecureAuth=true`，用于仅限 localhost 的不安全 HTTP 兼容性。
|
||||
- 成功的 `gateway.auth.mode: "trusted-proxy"` 操作员 Control UI 认证。
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（应急开关，严重降低安全性）。
|
||||
- 使用共享 Gateway 网关令牌/密码认证的 direct-loopback `gateway-client` 后端 RPC。
|
||||
- 所有连接都必须签署服务器提供的 `connect.challenge` nonce。
|
||||
- 所有连接都必须签名服务器提供的 `connect.challenge` nonce。
|
||||
|
||||
### 设备认证迁移诊断
|
||||
|
||||
@ -605,26 +601,25 @@ Gateway 网关会将这些视为**声明**，并强制执行服务器端允许
|
||||
迁移目标：
|
||||
|
||||
- 始终等待 `connect.challenge`。
|
||||
- 签署包含服务器 nonce 的 v2 载荷。
|
||||
- 签名包含服务器 nonce 的 v2 载荷。
|
||||
- 在 `connect.params.device.nonce` 中发送相同的 nonce。
|
||||
- 首选签名载荷是 `v3`，它除了绑定设备/客户端/角色/作用域/令牌/nonce 字段外，
|
||||
- 首选签名载荷是 `v3`，它除了设备/客户端/角色/作用域/令牌/nonce 字段外，
|
||||
还会绑定 `platform` 和 `deviceFamily`。
|
||||
- 为保持兼容性，旧版 `v2` 签名仍会被接受，但已配对设备的
|
||||
元数据固定仍会控制重新连接时的命令策略。
|
||||
- 为了兼容性，旧版 `v2` 签名仍会被接受，但已配对设备的元数据固定仍会控制重连时的命令策略。
|
||||
|
||||
## TLS + 固定
|
||||
|
||||
- WS 连接支持 TLS。
|
||||
- 客户端可以选择固定 Gateway 网关证书指纹（见 `gateway.tls`
|
||||
- 客户端可以选择固定 Gateway 网关证书指纹（请参阅 `gateway.tls`
|
||||
配置以及 `gateway.remote.tlsFingerprint` 或 CLI `--tls-fingerprint`）。
|
||||
|
||||
## 作用域
|
||||
## 范围
|
||||
|
||||
该协议暴露**完整的 Gateway 网关 API**（status、渠道、模型、聊天、
|
||||
此协议暴露**完整 Gateway 网关 API**（status、渠道、模型、聊天、
|
||||
智能体、会话、节点、批准等）。确切接口由
|
||||
`src/gateway/protocol/schema.ts` 中的 TypeBox schema 定义。
|
||||
|
||||
## 相关
|
||||
|
||||
- [Bridge protocol](/zh-CN/gateway/bridge-protocol)
|
||||
- [Gateway runbook](/zh-CN/gateway)
|
||||
- [Gateway 网关运行手册](/zh-CN/gateway)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user