From da5d9f80a5d6c202475f9c658e56067bf9267efb Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 1 May 2026 09:00:45 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/cli/update.md | 99 +++++--- docs/zh-CN/gateway/protocol.md | 443 +++++++++++++++++---------------- docs/zh-CN/install/updating.md | 66 ++--- 3 files changed, 324 insertions(+), 284 deletions(-) diff --git a/docs/zh-CN/cli/update.md b/docs/zh-CN/cli/update.md index 3f226f480..55c5fa9ac 100644 --- a/docs/zh-CN/cli/update.md +++ b/docs/zh-CN/cli/update.md @@ -1,14 +1,14 @@ --- read_when: - - 你想安全地更新源代码检出副本 + - 你想安全地更新源码检出副本 - 你需要了解 `--update` 的简写行为 -summary: CLI 参考：`openclaw update`（较安全的源更新 + Gateway 网关自动重启） +summary: CLI 参考：`openclaw update`（相对安全的源更新 + Gateway 网关自动重启） title: 更新 x-i18n: - generated_at: "2026-05-01T08:52:02Z" + generated_at: "2026-05-01T08:59:08Z" model: gpt-5.5 provider: openai - source_hash: bc71740dac6b1af8f695ab60d0ffc1b44a10dd40363538c2a8a37ad518790ce9 + source_hash: bfbbd6e3cd1a83e3700fa248a6ce2cb3adf1c94d0d5491895eea21bfec5d52b0 source_path: cli/update.md workflow: 16 --- @@ -39,14 +39,14 @@ openclaw --update ## 选项 -- `--no-restart`：成功更新后跳过重启 Gateway 网关服务。会重启 Gateway 网关的软件包管理器更新，会先验证重启后的服务报告预期的更新版本，然后命令才会成功。 -- `--channel `：设置更新渠道（git + npm；持久保存到配置中）。 -- `--tag `：仅为本次更新覆盖软件包目标。对于软件包安装，`main` 映射到 `github:openclaw/openclaw#main`。 -- `--dry-run`：预览计划的更新操作（渠道/tag/目标/重启流程），但不写入配置、安装、同步插件或重启。 -- `--json`：打印机器可读的 `UpdateRunResult` JSON，包括在更新后插件同步期间检测到 npm 插件产物漂移时的 +- `--no-restart`: 成功更新后跳过重启 Gateway 网关服务。会重启 Gateway 网关的软件包管理器更新会在命令成功前，验证重启后的服务报告预期的已更新版本。 +- `--channel `: 设置更新渠道（git + npm；持久化到配置中）。 +- `--tag `: 仅为本次更新覆盖软件包目标。对于软件包安装，`main` 映射到 `github:openclaw/openclaw#main`。 +- `--dry-run`: 预览计划的更新操作（渠道/tag/目标/重启流程），不写入配置、不安装、不同步插件，也不重启。 +- `--json`: 打印机器可读的 `UpdateRunResult` JSON，包括在更新后插件同步期间检测到 npm 插件构件漂移时的 `postUpdate.plugins.integrityDrifts`。 -- `--timeout `：每个步骤的超时时间（默认 1800 秒）。 -- `--yes`：跳过确认提示（例如降级确认）。 +- `--timeout `: 每个步骤的超时时间（默认是 1800 秒）。 +- `--yes`: 跳过确认提示（例如降级确认）。 降级需要确认，因为较旧版本可能会破坏配置。 @@ -54,7 +54,7 @@ openclaw --update ## `update status` -显示当前更新渠道 + git tag/分支/SHA（用于源码检出），以及更新可用性。 +显示当前更新渠道 + git tag/branch/SHA（用于源码检出），以及更新可用性。 ```bash openclaw update status @@ -64,82 +64,101 @@ openclaw update status --timeout 10 选项： -- `--json`：打印机器可读的状态 JSON。 -- `--timeout `：检查超时时间（默认 3 秒）。 +- `--json`: 打印机器可读的状态 JSON。 +- `--timeout `: 检查超时时间（默认是 3 秒）。 ## `update wizard` -交互式流程，用于选择更新渠道，并确认更新后是否重启 Gateway 网关（默认重启）。如果你在没有 git 检出的情况下选择 `dev`，它会提示创建一个检出。 +交互式流程，用于选择更新渠道，并确认更新后是否重启 Gateway 网关 +（默认会重启）。如果你选择 `dev` 但没有 git 检出，它会提示创建一个。 选项： -- `--timeout `：每个更新步骤的超时时间（默认 `1800`） +- `--timeout `: 每个更新步骤的超时时间（默认 `1800`） ## 它会做什么 -当你显式切换渠道（`--channel ...`）时，OpenClaw 也会让安装方式保持一致： +当你显式切换渠道（`--channel ...`）时，OpenClaw 也会保持 +安装方式一致： - `dev` → 确保存在 git 检出（默认：`~/openclaw`，可用 `OPENCLAW_GIT_DIR` 覆盖）， 更新它，并从该检出安装全局 CLI。 - `stable` → 使用 `latest` 从 npm 安装。 -- `beta` → 优先使用 npm dist-tag `beta`，但当 beta 缺失或早于当前 stable 版本时回退到 `latest`。 +- `beta` → 优先使用 npm dist-tag `beta`，但当 beta 缺失或早于当前稳定版本时， + 回退到 `latest`。 -Gateway 网关核心自动更新器（通过配置启用时）会在实时 Gateway 网关请求处理程序之外启动 CLI 更新路径。控制平面 `update.run` 软件包管理器更新会在软件包替换后强制执行非延迟更新重启，因为旧的 Gateway 网关进程可能仍有指向新软件包已删除文件的内存中分块。 +Gateway 网关核心自动更新器（通过配置启用时）会在实时 Gateway 网关请求处理程序之外启动 CLI 更新路径。控制平面的 `update.run` 软件包管理器更新会在软件包替换后强制执行非延迟、无冷却的更新重启，因为旧 Gateway 网关进程内存中可能仍有指向新软件包已删除文件的分块。 -对于软件包管理器安装，`openclaw update` 会先解析目标软件包版本，再调用软件包管理器。npm 全局安装使用分阶段安装：OpenClaw 会把新软件包安装到临时 npm prefix 中，验证其中打包的 `dist` 清单，然后把这个干净的软件包树切换到真实的全局 prefix。如果验证失败，更新后 Doctor、插件同步和重启工作不会从可疑的软件包树中运行。即使已安装版本已经匹配目标，命令仍会刷新全局软件包安装，然后运行插件同步、核心命令补全刷新和重启工作。这会让打包的 sidecar 和渠道拥有的插件记录与已安装的 OpenClaw 构建保持一致，同时把完整的插件命令补全重建留给显式的 `openclaw completion --write-state` 运行。 +对于软件包管理器安装，`openclaw update` 会先解析目标软件包 +版本，再调用软件包管理器。npm 全局安装使用分阶段 +安装：OpenClaw 将新软件包安装到临时 npm 前缀中，在那里验证 +打包的 `dist` 清单，然后把这棵干净的软件包树替换到 +真实的全局前缀中。如果验证失败，更新后 Doctor、插件同步和 +重启工作都不会从可疑的软件包树运行。即使已安装版本 +已经匹配目标，命令也会刷新全局软件包安装， +然后运行插件同步、核心命令补全刷新和重启工作。这 +会让打包的 sidecar 和渠道拥有的插件记录与已安装的 +OpenClaw 构建保持一致，同时将完整的插件命令补全重建留给 +显式的 `openclaw completion --write-state` 运行。 -当本地托管的 Gateway 网关服务已安装且启用重启时，软件包管理器更新会先停止正在运行的服务，再替换软件包树，然后从更新后的安装刷新服务元数据、重启服务，并验证重启后的 Gateway 网关报告预期版本。使用 `--no-restart` 时，软件包替换仍会运行，但托管服务不会被停止或重启，因此正在运行的 Gateway 网关可能会继续使用旧代码，直到你手动重启它。 +当已安装本地托管的 Gateway 网关服务且启用重启时， +软件包管理器更新会在替换软件包树前停止正在运行的服务， +然后从更新后的安装刷新服务元数据，重启 +服务，并验证重启后的 Gateway 网关报告预期版本。使用 +`--no-restart` 时，仍会执行软件包替换，但不会停止或重启 +托管服务，因此正在运行的 Gateway 网关可能会继续使用旧代码，直到你 +手动重启它。 ## Git 检出流程 ### 渠道选择 -- `stable`：检出最新的非 beta tag，然后构建并运行 Doctor。 -- `beta`：优先使用最新的 `-beta` tag，但当 beta 缺失或更旧时回退到最新的 stable tag。 -- `dev`：检出 `main`，然后 fetch 并 rebase。 +- `stable`: 检出最新的非 beta tag，然后构建并运行 Doctor。 +- `beta`: 优先使用最新的 `-beta` tag，但当 beta 缺失或更旧时回退到最新稳定 tag。 +- `dev`: 检出 `main`，然后 fetch 并 rebase。 ### 更新步骤 - + 要求没有未提交的更改。 - - 切换到所选渠道（tag 或分支）。 + + 切换到所选渠道（tag 或 branch）。 - + 仅 dev。 - - 在临时工作树中运行 lint 和 TypeScript 构建。如果 tip 失败，会向前回退最多 10 个提交，以找到最新的干净构建。 + + 在临时 worktree 中运行 lint 和 TypeScript 构建。如果 tip 失败，会最多向前回退 10 个 commit，以找到最新的干净构建。 - Rebase 到所选提交（仅 dev）。 + Rebase 到所选 commit（仅 dev）。 - - 使用仓库的软件包管理器。对于 pnpm 检出，更新器会按需引导 `pnpm`（先通过 `corepack`，然后回退到临时 `npm install pnpm@10`），而不是在 pnpm 工作区内运行 `npm run build`。 + + 使用仓库的软件包管理器。对于 pnpm 检出，更新器会按需引导 `pnpm`（先通过 `corepack`，然后回退到临时的 `npm install pnpm@10`），而不是在 pnpm workspace 内运行 `npm run build`。 - + 构建 gateway 和 Control UI。 - + `openclaw doctor` 会作为最终的安全更新检查运行。 - - 将插件同步到当前渠道。dev 使用内置插件；stable 和 beta 使用 npm。会更新通过 npm 安装的插件。 + + 将插件同步到当前渠道。Dev 使用内置插件；stable 和 beta 使用 npm。更新通过 npm 安装的插件。 -如果精确固定的 npm 插件更新解析到的产物完整性不同于已存储的安装记录，`openclaw update` 会中止该插件产物更新，而不是安装它。只有在验证你信任新产物后，才应显式重新安装或更新该插件。 +如果精确固定的 npm 插件更新解析到某个构件，而该构件的完整性与已存储的安装记录不同，`openclaw update` 会中止该插件构件更新，而不是安装它。只有在验证你信任新构件后，才显式重新安装或更新该插件。 更新后插件同步失败会使更新结果失败，并停止后续重启工作。修复插件安装或更新错误，然后重新运行 `openclaw update`。 -更新后的 Gateway 网关启动时，已启用的内置插件运行时依赖会在插件激活前完成暂存。软件包管理器 `update.run` 重启会在软件包树被替换后绕过正常的空闲延迟，因此旧进程不能继续懒加载已删除的分块。服务管理器重启仍会在关闭 Gateway 网关前清空运行时依赖暂存。 +当更新后的 Gateway 网关启动时，已启用的内置插件运行时依赖会在插件激活前暂存。软件包管理器 `update.run` 重启会在软件包树替换后绕过常规空闲延迟和重启冷却，因此旧进程不能继续延迟加载已删除的分块。服务管理器重启仍会在关闭 Gateway 网关前耗尽运行时依赖暂存。 -如果 pnpm 引导仍然失败，更新器会提前停止并返回特定于软件包管理器的错误，而不是尝试在检出中运行 `npm run build`。 +如果 pnpm 引导仍然失败，更新器会提前停止并报告软件包管理器专用错误，而不是尝试在检出中运行 `npm run build`。 ## `--update` 简写 diff --git a/docs/zh-CN/gateway/protocol.md b/docs/zh-CN/gateway/protocol.md index 16129bc55..0db219cd4 100644 --- a/docs/zh-CN/gateway/protocol.md +++ b/docs/zh-CN/gateway/protocol.md @@ -2,29 +2,30 @@ read_when: - 实现或更新 Gateway 网关 WS 客户端 - 调试协议不匹配或连接失败 - - 重新生成协议架构/模型 + - 正在重新生成协议架构/模型 summary: Gateway 网关 WebSocket 协议：握手、帧、版本控制 title: Gateway 网关协议 x-i18n: - generated_at: "2026-05-01T08:52:00Z" + generated_at: "2026-05-01T08:59:06Z" model: gpt-5.5 provider: openai - source_hash: 8ea0181fda62326ec835ff1f28ef6079e5afff5ffe3f06e08867bf16fb84f967 + source_hash: 8295e4e416250e7381393c0aa6a0016719f96552485cf9d56bb3896c9704c4a9 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 连接，并在握手时声明它们的**角色** + **作用域**。 ## 传输协议 -- 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） -Gateway 网关 → 客户端（连接前挑战）： +Gateway 网关 → 客户端（连接前质询）： ```json { @@ -95,11 +96,11 @@ Gateway 网关 → 客户端： } ``` -当 Gateway 网关仍在完成启动 sidecar 时，`connect` 请求可能会返回可重试的 `UNAVAILABLE` 错误，其中 `details.reason` 设置为 `"startup-sidecars"` 并带有 `retryAfterMs`。客户端应在其整体连接预算内重试该响应，而不是将其作为终止性的握手失败呈现。 +当 Gateway 网关仍在完成启动 sidecar 时，`connect` 请求可能返回可重试的 `UNAVAILABLE` 错误，其中 `details.reason` 设置为 `"startup-sidecars"`，并包含 `retryAfterMs`。客户端应在整体连接预算内重试该响应，而不是将其暴露为终止性的握手失败。 -`server`、`features`、`snapshot` 和 `policy` 都是架构要求的字段（`src/gateway/protocol/schema/frames.ts`）。`auth` 也是必需的，并报告协商后的角色/作用域。`canvasHostUrl` 是可选的。 +`server`、`features`、`snapshot` 和 `policy` 都是 schema（`src/gateway/protocol/schema/frames.ts`）要求的字段。`auth` 也是必需的，并报告协商后的角色/作用域。`canvasHostUrl` 是可选的。 -当未签发设备令牌时，`hello-ok.auth` 会报告协商后的权限，不包含令牌字段： +当没有签发设备令牌时，`hello-ok.auth` 会报告协商后的权限，不包含令牌字段： ```json { @@ -110,9 +111,9 @@ Gateway 网关 → 客户端： } ``` -受信任的同进程后端客户端（`client.id: "gateway-client"`、`client.mode: "backend"`）在使用共享 Gateway 网关令牌/密码进行身份验证的直接 loopback 连接上可以省略 `device`。此路径保留给内部控制平面 RPC，并避免过期的 CLI/设备配对基线阻塞本地后端工作，例如 subagent 会话更新。远程客户端、浏览器来源客户端、节点客户端以及显式设备令牌/设备身份客户端仍使用常规配对和作用域升级检查。 +受信任的同进程后端客户端（`client.id: "gateway-client"`、`client.mode: "backend"`）在使用共享 Gateway 网关令牌/密码进行认证时，可以在直接 loopback 连接上省略 `device`。此路径保留给内部控制平面 RPC，并避免陈旧的 CLI/设备配对基线阻塞本地后端工作，例如子智能体会话更新。远程客户端、浏览器来源客户端、节点客户端以及显式设备令牌/设备身份客户端仍使用正常的配对和作用域升级检查。 -当签发设备令牌时，`hello-ok` 还会包括： +当签发设备令牌时，`hello-ok` 还会包含： ```json { @@ -124,7 +125,7 @@ Gateway 网关 → 客户端： } ``` -在受信任的引导移交期间，`hello-ok.auth` 也可能在 `deviceTokens` 中包含额外的有界角色条目： +在受信任的启动引导交接期间，`hello-ok.auth` 也可能在 `deviceTokens` 中包含额外的有界角色条目： ```json { @@ -143,7 +144,7 @@ Gateway 网关 → 客户端： } ``` -对于内置节点/操作员引导流程，主节点令牌保持 `scopes: []`，任何移交的操作员令牌都保持限制在引导操作员允许列表内（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）。引导作用域检查保持角色前缀：操作员条目只满足操作员请求，非操作员角色仍需要其自身角色前缀下的作用域。 +对于内置节点/操作员启动引导流程，主节点令牌保持 `scopes: []`，任何交接出的操作员令牌都保持限制在启动引导操作员允许列表（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）内。启动引导作用域检查保持角色前缀规则：操作员条目只满足操作员请求，非操作员角色仍需要其自身角色前缀下的作用域。 ### 节点示例 @@ -186,7 +187,7 @@ Gateway 网关 → 客户端： - **响应**：`{type:"res", id, ok, payload|error}` - **事件**：`{type:"event", event, payload, seq?, stateVersion?}` -有副作用的方法需要**幂等键**（请参见架构）。 +有副作用的方法需要**幂等键**（见 schema）。 ## 角色 + 作用域 @@ -210,33 +211,34 @@ Gateway 网关 → 客户端： 插件注册的 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` -- 包含 `system.run`、`system.run.prepare` 或 `system.which` 的请求：`operator.pairing` + `operator.admin` +- 带非 exec 节点命令的请求：`operator.pairing` + `operator.write` +- 包含 `system.run`、`system.run.prepare` 或 `system.which` 的请求： + `operator.pairing` + `operator.admin` ### 能力/命令/权限（节点） -节点在连接时声明能力主张： +节点在连接时声明能力声明： - `caps`：高级能力类别。 - `commands`：用于调用的命令允许列表。 - `permissions`：细粒度开关（例如 `screen.record`、`camera.capture`）。 -Gateway 网关将这些视为**主张**，并强制执行服务器端允许列表。 +Gateway 网关 将这些视为**声明**，并执行服务端允许列表。 -## Presence +## 在线状态 -- `system-presence` 返回以设备身份为键的条目。 -- Presence 条目包括 `deviceId`、`roles` 和 `scopes`，因此 UI 可以为每台设备显示单行，即使它同时作为**操作员**和**节点**连接。 -- `node.list` 包括可选的 `lastSeenAtMs` 和 `lastSeenReason` 字段。已连接节点会将其当前连接时间报告为 `lastSeenAtMs`，原因为 `connect`；当受信任的节点事件更新其配对元数据时，已配对节点也可以报告持久化的后台 presence。 +- `system-presence` 返回按设备身份作为键的条目。 +- 在线状态条目包含 `deviceId`、`roles` 和 `scopes`，因此即使设备同时以**操作员**和**节点**身份连接，UI 也可以为每个设备显示单行。 +- `node.list` 包含可选的 `lastSeenAtMs` 和 `lastSeenReason` 字段。已连接节点会将其当前连接时间报告为 `lastSeenAtMs`，原因是 `connect`；当受信任的节点事件更新其配对元数据时，已配对节点也可以报告持久的后台在线状态。 ### 节点后台存活事件 -节点可以调用带有 `event: "node.presence.alive"` 的 `node.event`，以记录已配对节点在后台唤醒期间处于存活状态，而不将其标记为已连接。 +节点可以使用 `event: "node.presence.alive"` 调用 `node.event`，记录已配对节点在后台唤醒期间存活，而不将其标记为已连接。 ```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,70 +260,70 @@ Gateway 网关将这些视为**主张**，并强制执行服务器端允许列 } ``` -较旧的 Gateway 网关仍可能为 `node.event` 返回 `{ "ok": true }`；客户端应将其视为已确认的 RPC，而不是持久化 presence。 +旧版 Gateway 网关可能仍会为 `node.event` 返回 `{ "ok": true }`；客户端应将其视为已确认的 RPC，而不是持久在线状态持久化。 -## 广播事件作用域 +## 广播事件作用域限定 -服务器推送的 WebSocket 广播事件受作用域门控，因此配对作用域会话或仅节点会话不会被动接收会话内容。 +服务端推送的 WebSocket 广播事件受作用域门禁保护，因此限定为配对作用域或仅节点的会话不会被动接收会话内容。 -- **聊天、智能体和工具结果帧**（包括流式传输的 `agent` 事件和工具调用结果）至少需要 `operator.read`。没有 `operator.read` 的会话会完全跳过这些帧。 -- **插件定义的 `plugin.*` 广播**会根据插件注册方式，被门控到 `operator.write` 或 `operator.admin`。 -- **Status 和传输事件**（`heartbeat`、`presence`、`tick`、连接/断开生命周期等）保持不受限制，因此每个已认证会话都可以观察传输健康状况。 -- **未知广播事件族**默认受作用域门控（失败关闭），除非已注册处理器显式放宽它们。 +- **聊天、智能体和工具结果帧**（包括流式 `agent` 事件和工具调用结果）至少需要 `operator.read`。没有 `operator.read` 的会话会完全跳过这些帧。 +- **插件定义的 `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` 的完整枚举。 - + - `health` 返回缓存的或新探测的 Gateway 网关健康快照。 - - `diagnostics.stability` 返回最近的有界诊断稳定性记录器。它会保留操作元数据，例如事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称和会话 ID。它不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、cookie 或秘密值。需要操作员读取作用域。 - - `status` 返回 `/status` 风格的 Gateway 网关摘要；敏感字段仅对具有管理员作用域的操作员客户端包含。 - - `gateway.identity.get` 返回 relay 和配对流程使用的 Gateway 网关设备身份。 - - `system-presence` 返回已连接操作员/节点设备的当前 presence 快照。 - - `system-event` 追加系统事件，并可以更新/广播 presence 上下文。 - - `last-heartbeat` 返回最新持久化的 Heartbeat 事件。 - - `set-heartbeats` 切换 Gateway 网关上的 Heartbeat 处理。 + - `diagnostics.stability` 返回最近的有界诊断稳定性记录器。它保留事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称和会话 ID 等运行元数据。它不会保留聊天文本、Webhook 正文、工具输出、原始请求或响应正文、令牌、Cookie 或密钥值。需要操作员读取作用域。 + - `status` 返回 `/status` 风格的 Gateway 网关摘要；敏感字段仅包含在管理员作用域的操作员客户端中。 + - `gateway.identity.get` 返回中继和配对流程使用的 Gateway 网关设备身份。 + - `system-presence` 返回已连接操作员/节点设备的当前在线状态快照。 + - `system-event` 追加系统事件，并可更新/广播在线状态上下文。 + - `last-heartbeat` 返回最新持久化的 heartbeat 事件。 + - `set-heartbeats` 切换 Gateway 网关上的 heartbeat 处理。 - - `models.list` 返回运行时允许的模型目录。传入 `{ "view": "configured" }` 可获取适合选择器显示的已配置模型（先是 `agents.defaults.models`，然后是 `models.providers.*.models`），或传入 `{ "view": "all" }` 获取完整目录。 + - `models.list` 返回运行时允许的模型目录。传入 `{ "view": "configured" }` 可获取适合选择器大小的已配置模型（先是 `agents.defaults.models`，然后是 `models.providers.*.models`），或传入 `{ "view": "all" }` 获取完整目录。 - `usage.status` 返回提供商用量窗口/剩余额度摘要。 - `usage.cost` 返回某个日期范围内的聚合费用用量摘要。 - - `doctor.memory.status` 返回当前默认智能体工作区的向量记忆 / 缓存嵌入就绪状态。仅当调用方明确需要实时嵌入提供商探测时，才传入 `{ "probe": true }` 或 `{ "deep": true }`。 - - `doctor.memory.remHarness` 返回面向远程控制平面客户端的有界只读 REM harness 预览。它可以包含工作区路径、记忆片段、渲染后的有依据 Markdown，以及深度提升候选项，因此调用方需要 `operator.read`。 + - `doctor.memory.status` 返回当前默认 agent 工作区的向量记忆 / 缓存 embedding 就绪状态。只有在调用方明确需要实时 ping embedding 提供商时，才传入 `{ "probe": true }` 或 `{ "deep": true }`。 + - `doctor.memory.remHarness` 为远程控制平面客户端返回有界、只读的 REM harness 预览。它可能包含工作区路径、记忆片段、渲染后的有依据 Markdown，以及深度提升候选项，因此调用方需要 `operator.read`。 - `sessions.usage` 返回每个会话的用量摘要。 - - `sessions.usage.timeseries` 返回一个会话的时间序列用量。 - - `sessions.usage.logs` 返回一个会话的用量日志条目。 + - `sessions.usage.timeseries` 返回某个会话的时间序列用量。 + - `sessions.usage.logs` 返回某个会话的用量日志条目。 - - - `channels.status` 返回内置 + 捆绑的渠道/插件状态摘要。 - - `channels.logout` 会在渠道支持登出的情况下登出特定渠道/账号。 - - `web.login.start` 为当前支持 QR 的网页渠道提供商启动 QR/网页登录流程。 - - `web.login.wait` 等待该 QR/网页登录流程完成，并在成功时启动渠道。 + + - `channels.status` 返回内置 + bundled 渠道/插件 Status 摘要。 + - `channels.logout` 在渠道支持退出登录时，为指定渠道/账号退出登录。 + - `web.login.start` 为当前支持二维码的 Web 渠道提供商启动二维码/Web 登录流程。 + - `web.login.wait` 等待该二维码/Web 登录流程完成，并在成功后启动渠道。 - `push.test` 向已注册的 iOS 节点发送测试 APNs 推送。 - - `voicewake.get` 返回已存储的唤醒词触发器。 + - `voicewake.get` 返回存储的唤醒词触发器。 - `voicewake.set` 更新唤醒词触发器并广播变更。 - - - `send` 是直接出站投递 RPC，用于在聊天运行器之外执行面向渠道/账号/线程目标的发送。 - - `logs.tail` 返回已配置的 Gateway 网关文件日志尾部内容，并带有 cursor/limit 和 max-byte 控制。 + + - `send` 是直接出站投递 RPC，用于在聊天运行器之外按渠道/账号/线程定向发送。 + - `logs.tail` 返回已配置的 Gateway 网关文件日志尾部内容，带有 cursor/limit 和最大字节数控制。 - - `talk.config` 返回有效的 Talk 配置载荷；`includeSecrets` 需要 `operator.talk.secrets`（或 `operator.admin`）。 + - `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 提供商。 @@ -330,272 +332,291 @@ Gateway 网关将这些视为**主张**，并强制执行服务器端允许列 - - `secrets.reload` 重新解析活动的 SecretRefs，并且仅在完全成功时替换运行时密钥状态。 + - `secrets.reload` 重新解析当前 SecretRefs，并且仅在完全成功时替换运行时密钥状态。 - `secrets.resolve` 为特定命令/目标集合解析命令目标密钥分配。 - `config.get` 返回当前配置快照和哈希。 - `config.set` 写入经过验证的配置载荷。 - `config.patch` 合并部分配置更新。 - `config.apply` 验证并替换完整配置载荷。 - - `config.schema` 返回 Control UI 和 CLI 工具使用的实时配置 schema 载荷：schema、`uiHints`、version 和生成元数据，包括运行时能够加载时的插件 + 渠道 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` 返回最新缓存的更新重启哨兵值，可用时包括重启后的运行版本。 - - `wizard.start`、`wizard.next`、`wizard.status` 和 `wizard.cancel` 通过 WS RPC 公开新手引导向导。 + - `config.schema` 返回 Control UI 和 CLI 工具使用的实时配置 schema 载荷：schema、`uiHints`、版本和生成元数据；在运行时可以加载时，还包括插件 + 渠道 schema 元数据。schema 包含字段 `title` / `description` 元数据，这些元数据派生自 UI 使用的相同标签和帮助文本；当存在匹配字段文档时，还包括嵌套对象、通配符、数组项以及 `anyOf` / `oneOf` / `allOf` 组合分支。 + - `config.schema.lookup` 为一个配置路径返回路径作用域的查找载荷：规范化路径、浅层 schema 节点、匹配的 hint + `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 暴露新手引导向导。 - - - `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` 返回智能体或会话的有效助手身份。 - - `agent.wait` 等待运行完成，并在可用时返回最终快照。 + + - `agents.list` 返回已配置的 agent 条目，包括生效模型和运行时元数据。 + - `agents.create`、`agents.update` 和 `agents.delete` 管理 agent 记录和工作区连线。 + - `agents.files.list`、`agents.files.get` 和 `agents.files.set` 管理为 agent 暴露的引导工作区文件。 + - `artifacts.list`、`artifacts.get` 和 `artifacts.download` 为明确的 `sessionKey`、`runId` 或 `taskId` 作用域暴露从 transcript 派生的 artifact 摘要和下载。运行和任务查询会在服务器端解析所属会话，并且只返回来源匹配的 transcript 媒体；不安全或本地 URL 来源会返回不支持的下载，而不会在服务器端抓取。 + - `agent.identity.get` 返回某个 agent 或会话的生效助手身份。 + - `agent.wait` 等待一次运行完成，并在可用时返回终态快照。 - - `sessions.list` 返回当前会话索引，配置了智能体运行时后端时，包括每行的 `agentRuntime` 元数据。 + - `sessions.list` 返回当前会话索引；当配置了 agent 运行时后端时，会包含每行的 `agentRuntime` 元数据。 - `sessions.subscribe` 和 `sessions.unsubscribe` 为当前 WS 客户端切换会话变更事件订阅。 - - `sessions.messages.subscribe` 和 `sessions.messages.unsubscribe` 为一个会话切换会话记录/消息事件订阅。 - - `sessions.preview` 返回特定会话键的有界会话记录预览。 + - `sessions.messages.subscribe` 和 `sessions.messages.unsubscribe` 为一个会话切换 transcript/消息事件订阅。 + - `sessions.preview` 返回特定会话键的有界 transcript 预览。 - `sessions.resolve` 解析或规范化会话目标。 - `sessions.create` 创建新的会话条目。 - `sessions.send` 向现有会话发送消息。 - - `sessions.steer` 是活动会话的中断并引导变体。 - - `sessions.abort` 中止会话的活动工作。调用方可以传入 `key` 加可选的 `runId`，也可以只为 Gateway 网关可解析到会话的活动运行传入 `runId`。 - - `sessions.patch` 更新会话元数据/覆盖项，并报告解析后的规范模型以及有效的 `agentRuntime`。 + - `sessions.steer` 是活动会话的中断并 Steering queue 变体。 + - `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 载荷（包括 `...`、`...`、`...`、`...` 和被截断的工具调用块）以及泄漏的 ASCII/全角模型控制令牌，省略完全为 `NO_REPLY` / `no_reply` 等纯静默令牌的助手行，并且过大的行可替换为占位符。 + - 聊天执行仍使用 `chat.history`、`chat.send`、`chat.abort` 和 `chat.inject`。`chat.history` 会为 UI 客户端进行显示规范化：从可见文本中剥离内联指令标签，剥离纯文本工具调用 XML 载荷（包括 `...`、`...`、`...`、`...` 以及截断的工具调用块）和泄漏的 ASCII/全角模型控制 token，省略精确为 `NO_REPLY` / `no_reply` 等纯静默 token 的助手行，并且过大的行可替换为占位符。 - - - `device.pair.list` 返回待处理和已批准的配对设备。 + + - `device.pair.list` 返回待处理和已批准的已配对设备。 - `device.pair.approve`、`device.pair.reject` 和 `device.pair.remove` 管理设备配对记录。 - - `device.token.rotate` 在其已批准角色和调用方作用域边界内轮换已配对设备令牌。 - - `device.token.revoke` 在其已批准角色和调用方作用域边界内撤销已配对设备令牌。 + - `device.token.rotate` 在已批准角色和调用方作用域边界内轮换已配对设备 token。 + - `device.token.revoke` 在已批准角色和调用方作用域边界内撤销已配对设备 token。 - - `node.pair.request`、`node.pair.list`、`node.pair.approve`、`node.pair.reject`、`node.pair.remove` 和 `node.pair.verify` 覆盖节点配对和引导验证。 + - `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.invoke` 向已连接节点转发命令。 + - `node.invoke` 将命令转发到已连接节点。 - `node.invoke.result` 返回调用请求的结果。 - - `node.event` 将节点发起的事件传回 Gateway 网关。 - - `node.canvas.capability.refresh` 刷新作用域限定的 canvas 能力令牌。 + - `node.event` 将节点源事件带回 Gateway 网关。 + - `node.canvas.capability.refresh` 刷新作用域 canvas-capability token。 - `node.pending.pull` 和 `node.pending.ack` 是已连接节点队列 API。 - `node.pending.enqueue` 和 `node.pending.drain` 管理离线/断开连接节点的持久待处理工作。 - - - `exec.approval.request`、`exec.approval.get`、`exec.approval.list` 和 `exec.approval.resolve` 覆盖一次性 exec 审批请求，以及待处理审批查询/重放。 + + - `exec.approval.request`、`exec.approval.get`、`exec.approval.list` 和 `exec.approval.resolve` 涵盖一次性 exec 审批请求以及待处理审批查找/重放。 - `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` 覆盖插件定义的审批流程。 + - `plugin.approval.request`、`plugin.approval.list`、`plugin.approval.waitDecision` 和 `plugin.approval.resolve` 涵盖插件定义的审批流程。 - - 自动化：`wake` 安排立即或下一次心跳时的唤醒文本注入；`cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、`cron.run`、`cron.runs` 管理定时工作。 + - 自动化：`wake` 安排立即或下一次 Heartbeat 唤醒文本注入；`cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、`cron.run`、`cron.runs` 管理定时工作。 - Skills 和工具：`commands.list`、`skills.*`、`tools.catalog`、`tools.effective`、`tools.invoke`。 -### 常见事件类别 +### 常见事件系列 -- `chat`：UI 聊天更新，例如 `chat.inject` 和其他仅限会话记录的聊天 +- `chat`：UI 聊天更新，例如 `chat.inject` 和其他仅 transcript 的聊天 事件。 -- `session.message` 和 `session.tool`：已订阅会话的会话记录/事件流更新。 +- `session.message` 和 `session.tool`：已订阅会话的 transcript/事件流更新。 - `sessions.changed`：会话索引或元数据已变更。 -- `presence`：系统在线状态快照更新。 -- `tick`：周期性保活 / 存活事件。 +- `presence`：系统 presence 快照更新。 +- `tick`：周期性 keepalive / liveness 事件。 - `health`：Gateway 网关健康快照更新。 -- `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 可执行文件列表， +- 节点可以调用 `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` 是可选的，只影响原生命名以及原生插件命令可用性。 - - `includeArgs=false` 会从响应中省略序列化的参数元数据。 -- 操作员可以调用 `tools.catalog`（`operator.read`）来获取智能体的运行时工具目录。响应包含分组后的工具和来源元数据： + - `nativeName` 在存在时携带感知提供商的原生命令名称。 + - `provider` 是可选的，并且只影响原生命名以及原生插件命令可用性。 + - `includeArgs=false` 会从响应中省略序列化后的参数元数据。 +- 操作员可以调用 `tools.catalog`（`operator.read`）来获取某个智能体的运行时工具目录。响应包含分组工具和来源元数据： - `source`：`core` 或 `plugin` - `pluginId`：当 `source="plugin"` 时的插件所有者 - - `optional`：插件工具是否可选 -- 操作员可以调用 `tools.effective`（`operator.read`）来获取会话的运行时有效工具清单。 + - `optional`：某个插件工具是否为可选项 +- 操作员可以调用 `tools.effective`（`operator.read`）来获取某个会话的运行时有效工具 + 清单。 - `sessionKey` 是必需的。 - - 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`）来获取智能体的可见 Skills 清单。 - - `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 安装。 - - 配置模式会修补 `skills.entries.` 值，例如 `enabled`、`apiKey` 和 `env`。 + - 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` 是可选的；省略它可读取默认智能体工作区。 + - 响应包含资格、缺失需求、配置检查，以及经过清理的安装选项， + 不会暴露原始密钥值。 +- 操作员可以调用 `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.` 值，例如 `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，不要用于普通模型选择器。 +- `"configured"`：适合选择器大小的行为。如果配置了 `agents.defaults.models`，它仍然优先。否则响应会使用显式的 `models.providers.*.models` 条目，只有在不存在已配置模型行时才回退到完整目录。 +- `"all"`：完整的 Gateway 网关目录，绕过 `agents.defaults.models`。将它用于诊断和发现 UI，而不是常规模型选择器。 -## Exec 批准 +## Exec 审批 -- 当 exec 请求需要批准时，Gateway 网关会广播 `exec.approval.requested`。 -- 操作员客户端通过调用 `exec.approval.resolve` 来解析（需要 `operator.approvals` scope）。 +- 当 exec 请求需要审批时，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/会话上下文。 -- 如果调用方在准备阶段和最终批准的 `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` ### 客户端常量 -`src/gateway/client.ts` 中的参考客户端使用这些默认值。这些值在协议 v3 中保持稳定，并且是第三方客户端的预期基线。 +`src/gateway/client.ts` 中的参考客户端使用这些默认值。这些值在 +协议 v3 中保持稳定，并且是第三方客户端的预期基线。 | 常量 | 默认值 | 来源 | | ----------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `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`（配置/环境变量可以提高配对的服务器/客户端预算） | +| 请求超时（每次 RPC） | `30_000` ms | `src/gateway/client.ts`（`requestTimeoutMs`） | +| 预认证 / 连接挑战超时 | `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 超时关闭 | 静默超过 `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` 或 +- shared-secret Gateway 网关认证使用 `connect.params.auth.token` 或 `connect.params.auth.password`，具体取决于配置的认证模式。 -- 带身份的模式，例如 Tailscale Serve +- 带身份信息的模式，例如 Tailscale Serve (`gateway.auth.allowTailscale: true`) 或非 loopback - `gateway.auth.mode: "trusted-proxy"`，会从请求标头而不是 `connect.params.auth.*` - 满足 connect 认证检查。 -- 私有入口 `gateway.auth.mode: "none"` 会完全跳过共享密钥 connect 认证； - 不要在公开或不受信任的入口上暴露该模式。 -- 配对后，Gateway 网关会签发一个限定于连接角色 + scopes 的**设备令牌**。 - 它会在 `hello-ok.auth.deviceToken` 中返回，客户端应将其持久化以供后续连接使用。 -- 客户端应在任何成功连接后持久化主 `hello-ok.auth.deviceToken`。 -- 使用该**已存储**设备令牌重新连接时，也应复用为该令牌存储的已批准 scope 集合。 - 这样可以保留已授予的读取、探测、Status 访问，并避免重新连接被静默收窄为 - 更窄的隐式仅管理员 scope。 -- 客户端 connect 认证组装（`src/gateway/client.ts` 中的 `selectConnectAuth`）： - - `auth.password` 是正交的，设置后始终会转发。 - - `auth.token` 按优先级填充：先使用显式共享令牌， - 然后使用显式 `deviceToken`，再使用已存储的按设备令牌（按 - `deviceId` + `role` 建键）。 - - 仅当上述任何方式都未解析出 `auth.token` 时，才发送 `auth.bootstrapToken`。 - 共享令牌或任何已解析的设备令牌都会抑制它。 - - 在一次性 `AUTH_TOKEN_MISMATCH` 重试时自动提升已存储设备令牌， - 仅限于**受信任端点**：loopback，或带有固定 `tlsFingerprint` 的 `wss://`。 - 未固定指纹的公开 `wss://` 不符合条件。 -- 额外的 `hello-ok.auth.deviceTokens` 条目是引导交接令牌。 - 仅当 connect 在受信任传输上使用引导认证时才持久化它们，例如 - `wss://` 或 loopback/local pairing。 + `gateway.auth.mode: "trusted-proxy"`，会从请求头满足 connect 认证检查， + 而不是使用 `connect.params.auth.*`。 +- 私有入口 `gateway.auth.mode: "none"` 会完全跳过 shared-secret connect 认证； + 不要在公开/不受信任的入口上暴露该模式。 +- 配对后，Gateway 网关会颁发一个限定到连接角色 + 作用域的**设备令牌**。 + 它会在 `hello-ok.auth.deviceToken` 中返回，客户端应将其持久化以供以后连接使用。 +- 客户端应在任何成功 connect 后持久化主 `hello-ok.auth.deviceToken`。 +- 使用该**已存储**设备令牌重新连接时，也应复用该令牌已存储的已批准作用域集。 + 这会保留已授予的读取/探测/status 访问权限，并避免将重连静默收窄为隐式仅管理员作用域。 +- 客户端侧 connect 认证组装（`src/gateway/client.ts` 中的 `selectConnectAuth`）： + - `auth.password` 是正交的，并且在设置后总是会转发。 + - `auth.token` 按优先级填充：先是显式 shared token， + 然后是显式 `deviceToken`，再是已存储的按设备令牌（以 + `deviceId` + `role` 为键）。 + - 仅当上述内容都未解析出 `auth.token` 时，才会发送 `auth.bootstrapToken`。 + shared token 或任何解析出的设备令牌都会抑制它。 + - 在一次性 `AUTH_TOKEN_MISMATCH` 重试中，自动提升已存储设备令牌仅限于**可信端点** — + loopback，或带有固定 `tlsFingerprint` 的 `wss://`。未固定的公共 `wss://` + 不符合条件。 +- 额外的 `hello-ok.auth.deviceTokens` 条目是 bootstrap 交接令牌。 + 仅当 connect 在可信传输上使用 bootstrap 认证时才持久化它们， + 例如 `wss://` 或 loopback/local 配对。 - 如果客户端提供**显式** `deviceToken` 或显式 `scopes`， - 该调用方请求的 scope 集合仍然具有权威性；只有当客户端复用已存储的按设备令牌时， - 才会复用缓存的 scopes。 -- 设备令牌可通过 `device.token.rotate` 和 - `device.token.revoke` 轮换/撤销（需要 `operator.pairing` scope）。 + 调用方请求的作用域集仍然具有权威性；只有当客户端复用已存储的按设备令牌时， + 才会复用缓存作用域。 +- 设备令牌可以通过 `device.token.rotate` 和 + `device.token.revoke` 轮换/撤销（需要 `operator.pairing` 作用域）。 - `device.token.rotate` 返回轮换元数据。只有在同一设备调用且已使用该设备令牌认证时， 它才会回显替换用 bearer token，因此仅令牌客户端可以在重新连接前持久化替换令牌。 - 共享/管理员轮换不会回显 bearer token。 -- 令牌签发、轮换和撤销都被限制在该设备配对条目中记录的已批准角色集合内； - 令牌变更不能扩展或指向配对批准从未授予的设备角色。 -- 对于已配对设备令牌会话，除非调用方还拥有 `operator.admin`， - 否则设备管理是自限定的：非管理员调用方只能移除/撤销/轮换**自己的**设备条目。 -- `device.token.rotate` 和 `device.token.revoke` 还会根据调用方当前会话 scopes - 检查目标 operator 令牌 scope 集合。非管理员调用方不能轮换或撤销比自己已持有范围更广的 operator 令牌。 + shared/admin 轮换不会回显 bearer token。 +- 令牌颁发、轮换和撤销都限定在该设备配对条目中记录的已批准角色集内； + 令牌变更不能扩展或目标指向配对批准从未授予的设备角色。 +- 对于已配对设备令牌会话，设备管理默认限定于自身，除非调用方还拥有 + `operator.admin`：非管理员调用方只能移除/撤销/轮换其**自己的**设备条目。 +- `device.token.rotate` 和 `device.token.revoke` 也会根据调用方当前会话作用域 + 检查目标 operator 令牌作用域集。非管理员调用方不能轮换或撤销比自己已持有范围更宽的 + operator 令牌。 - 认证失败包含 `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`） + - `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`) - `AUTH_TOKEN_MISMATCH` 的客户端行为： - - 受信任客户端可以尝试一次有界重试，并使用缓存的按设备令牌。 + - 可信客户端可以尝试一次有界重试，并使用缓存的按设备令牌。 - 如果该重试失败，客户端应停止自动重连循环，并展示 operator 操作指引。 ## 设备身份 + 配对 -- 节点应包含稳定的设备身份（`device.id`），该身份派生自密钥对指纹。 -- Gateway 网关按设备 + 角色签发令牌。 +- 节点应包含一个从密钥对指纹派生的稳定设备身份（`device.id`）。 +- Gateway 网关会按设备 + 角色颁发令牌。 - 除非启用了本地自动批准，否则新的设备 ID 需要配对批准。 - 配对自动批准以直接 local loopback 连接为中心。 -- OpenClaw 还提供一个狭窄的后端/容器本地自连接路径，用于受信任的共享密钥辅助流程。 -- 同主机 tailnet 或 LAN 连接在配对时仍会被视为远程连接，并且需要批准。 +- OpenClaw 还有一个狭窄的后端/容器本地自连接路径，用于可信 shared-secret 辅助流程。 +- 同主机 tailnet 或 LAN 连接仍会按远程配对处理，并且需要批准。 - WS 客户端通常会在 `connect` 期间包含 `device` 身份（operator + - 节点）。唯一无设备 operator 例外是显式信任路径： - - `gateway.controlUi.allowInsecureAuth=true`，用于仅限 localhost 的不安全 HTTP 兼容性。 + 节点）。仅以下显式信任路径允许无设备的 operator 例外： + - `gateway.controlUi.allowInsecureAuth=true` 用于仅 localhost 的不安全 HTTP 兼容性。 - 成功的 `gateway.auth.mode: "trusted-proxy"` operator Control UI 认证。 - - `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（紧急绕过，严重降低安全性）。 - - 使用共享 Gateway 网关令牌/密码认证的 direct-loopback `gateway-client` 后端 RPC。 -- 所有连接都必须签名服务器提供的 `connect.challenge` nonce。 + - `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（应急绕过，严重安全降级）。 + - 直接 loopback 的 `gateway-client` 后端 RPC，使用 shared + gateway token/password 认证。 +- 所有连接都必须签署服务器提供的 `connect.challenge` nonce。 ### 设备认证迁移诊断 对于仍使用挑战前签名行为的旧版客户端，`connect` 现在会在 -`error.details.code` 下返回 `DEVICE_AUTH_*` 详情代码，并带有稳定的 `error.details.reason`。 +`error.details.code` 下返回 `DEVICE_AUTH_*` 详细代码，并带有稳定的 `error.details.reason`。 常见迁移失败： | 消息 | details.code | details.reason | 含义 | | --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- | -| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | 客户端省略了 `device.nonce`（或发送了空值）。 | -| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | 客户端使用过期/错误的 nonce 进行了签名。 | +| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | 客户端省略了 `device.nonce`（或发送为空）。 | +| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | 客户端使用过期/错误的 nonce 进行了签名。 | | `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | 签名载荷与 v2 载荷不匹配。 | | `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | 已签名时间戳超出允许偏差。 | | `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` 与公钥指纹不匹配。 | @@ -604,11 +625,11 @@ Gateway 网关将这些视为**主张**，并强制执行服务器端允许列 迁移目标： - 始终等待 `connect.challenge`。 -- 签名包含服务器 nonce 的 v2 载荷。 -- 在 `connect.params.device.nonce` 中发送相同的 nonce。 -- 首选签名载荷是 `v3`，它除设备/客户端/角色/scopes/令牌/nonce 字段外， - 还绑定 `platform` 和 `deviceFamily`。 -- 为兼容性仍接受旧版 `v2` 签名，但已配对设备的元数据固定仍会控制重新连接时的命令策略。 +- 签署包含服务器 nonce 的 v2 载荷。 +- 在 `connect.params.device.nonce` 中发送同一个 nonce。 +- 首选签名载荷是 `v3`，它除了绑定 device/client/role/scopes/token/nonce + 字段外，还绑定 `platform` 和 `deviceFamily`。 +- 为了兼容性，旧版 `v2` 签名仍会被接受，但已配对设备元数据固定仍会控制重连时的命令策略。 ## TLS + 固定 @@ -616,13 +637,13 @@ Gateway 网关将这些视为**主张**，并强制执行服务器端允许列 - 客户端可以选择固定 Gateway 网关证书指纹（参见 `gateway.tls` 配置以及 `gateway.remote.tlsFingerprint` 或 CLI `--tls-fingerprint`）。 -## 范围 +## 作用域 -此协议暴露**完整 Gateway 网关 API**（Status、渠道、模型、聊天、 +此协议暴露**完整的 Gateway 网关 API**（status、渠道、模型、chat、 智能体、会话、节点、批准等）。确切表面由 `src/gateway/protocol/schema.ts` 中的 TypeBox schema 定义。 -## 相关内容 +## 相关 -- [Bridge protocol](/zh-CN/gateway/bridge-protocol) -- [Gateway runbook](/zh-CN/gateway) +- [桥接协议](/zh-CN/gateway/bridge-protocol) +- [Gateway 网关运行手册](/zh-CN/gateway) diff --git a/docs/zh-CN/install/updating.md b/docs/zh-CN/install/updating.md index f1401a915..eb7fba15e 100644 --- a/docs/zh-CN/install/updating.md +++ b/docs/zh-CN/install/updating.md @@ -5,10 +5,10 @@ read_when: summary: 安全更新 OpenClaw（全局安装或源码），以及回滚策略 title: 更新 x-i18n: - generated_at: "2026-05-01T08:51:52Z" + generated_at: "2026-05-01T08:59:00Z" model: gpt-5.5 provider: openai - source_hash: 98631ce432a28af244ec22ce0cf4a23ded356dd93e9c154f502347683eef52d1 + source_hash: b6ee340af569dde3a6cf61fff26d2a0ab8c8ec882b652f41d6ac8e22ddc5fed1 source_path: install/updating.md workflow: 16 --- @@ -17,13 +17,13 @@ x-i18n: ## 推荐：`openclaw update` -最快的更新方式。它会检测你的安装类型（npm 或 git）、拉取最新版本、运行 `openclaw doctor`，并重启 Gateway 网关。 +最快的更新方式。它会检测你的安装类型（npm 或 git）、获取最新版本、运行 `openclaw doctor`，并重启 Gateway 网关。 ```bash openclaw update ``` -要切换渠道或指定某个版本： +要切换渠道或指定特定版本： ```bash openclaw update --channel beta @@ -32,13 +32,13 @@ openclaw update --tag main openclaw update --dry-run # preview without applying ``` -`--channel beta` 优先使用 beta，但当 beta 标签缺失或早于最新稳定版时，运行时会回退到 stable/latest。如果你想对一次性包更新使用原始 npm beta dist-tag，请使用 `--tag beta`。 +`--channel beta` 优先使用 beta，但当 beta 标签缺失或早于最新稳定版时，运行时会回退到 stable/latest。如果你想为一次性软件包更新使用原始的 npm beta dist-tag，请使用 `--tag beta`。 -有关渠道语义，请参阅[开发渠道](/zh-CN/install/development-channels)。 +查看 [开发渠道](/zh-CN/install/development-channels) 了解渠道语义。 ## 在 npm 和 git 安装之间切换 -当你想更改安装类型时，请使用渠道。更新器会保留你在 `~/.openclaw` 中的状态、配置、凭证和工作区；它只会更改 CLI 和 Gateway 网关使用哪一份 OpenClaw 代码安装。 +当你想更改安装类型时，请使用渠道。更新器会保留你在 `~/.openclaw` 中的状态、配置、凭证和工作区；它只会更改 CLI 和 Gateway 网关使用的 OpenClaw 代码安装。 ```bash # npm package install -> editable git checkout @@ -48,24 +48,24 @@ openclaw update --channel dev openclaw update --channel stable ``` -先使用 `--dry-run` 运行，以预览确切的安装模式切换： +先使用 `--dry-run` 运行，以预览准确的安装模式切换： ```bash openclaw update --channel dev --dry-run openclaw update --channel stable --dry-run ``` -`dev` 渠道会确保存在 git 检出副本、构建它，并从该检出副本安装全局 CLI。`stable` 和 `beta` 渠道使用包安装。如果 Gateway 网关已经安装，`openclaw update` 会刷新服务元数据并重启它，除非你传入 `--no-restart`。 +`dev` 渠道会确保存在一个 git 检出，构建它，并从该检出安装全局 CLI。`stable` 和 `beta` 渠道使用软件包安装。如果 Gateway 网关已经安装，`openclaw update` 会刷新服务元数据并重启它，除非你传入 `--no-restart`。 -## 备选方案：重新运行安装程序 +## 替代方案：重新运行安装器 ```bash curl -fsSL https://openclaw.ai/install.sh | bash ``` -添加 `--no-onboard` 可跳过新手引导。要通过安装程序强制指定安装类型，请传入 `--install-method git --no-onboard` 或 `--install-method npm --no-onboard`。 +添加 `--no-onboard` 可跳过新手引导。要通过安装器强制指定安装类型，请传入 `--install-method git --no-onboard` 或 `--install-method npm --no-onboard`。 -如果 `openclaw update` 在 npm 包安装阶段后失败，请重新运行安装程序。安装程序不会调用旧更新器；它会直接运行全局包安装，并且可以恢复部分更新的 npm 安装。 +如果 `openclaw update` 在 npm 软件包安装阶段后失败，请重新运行安装器。安装器不会调用旧版更新器；它会直接运行全局软件包安装，并且可以恢复部分更新的 npm 安装。 ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm @@ -77,13 +77,13 @@ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version ``` -## 备选方案：手动使用 npm、pnpm 或 bun +## 替代方案：手动使用 npm、pnpm 或 bun ```bash npm i -g openclaw@latest ``` -当 `openclaw update` 管理全局 npm 安装时，它会先把目标安装到临时 npm 前缀中，验证打包后的 `dist` 清单，然后将干净的包树切换到真正的全局前缀中。这样可以避免 npm 将新包覆盖到旧包的过期文件上。如果安装命令失败，OpenClaw 会使用 `--omit=optional` 重试一次。该重试有助于原生可选依赖无法编译的主机，同时如果回退也失败，仍会保留原始失败可见。 +当 `openclaw update` 管理全局 npm 安装时，它会先将目标安装到临时 npm 前缀中，验证打包的 `dist` 清单，然后把干净的软件包树切换到真实的全局前缀中。这样可以避免 npm 将新软件包覆盖到旧软件包的陈旧文件之上。如果安装命令失败，OpenClaw 会使用 `--omit=optional` 重试一次。该重试有助于原生可选依赖无法编译的主机，同时如果回退也失败，仍会显示原始失败。 ```bash pnpm add -g openclaw@latest @@ -96,10 +96,10 @@ bun add -g openclaw@latest ### 高级 npm 安装主题 - - OpenClaw 会在运行时将打包的全局安装视为只读，即使当前用户可写入全局包目录也是如此。内置插件的运行时依赖会被暂存到可写的运行时目录，而不是修改包树。这可以避免 `openclaw update` 与正在运行的 Gateway 网关或本地智能体发生竞争，因为后者可能在同一次安装期间修复插件依赖。 + + OpenClaw 在运行时将打包的全局安装视为只读，即使当前用户可写入全局软件包目录也是如此。内置插件运行时依赖会被暂存到可写运行时目录，而不是修改软件包树。这样可以防止 `openclaw update` 与正在运行的 Gateway 网关或本地智能体在同一安装过程中修复插件依赖时发生竞争。 - 一些 Linux npm 设置会把全局包安装到 root 拥有的目录下，例如 `/usr/lib/node_modules/openclaw`。OpenClaw 通过相同的外部暂存路径支持这种布局。 + 某些 Linux npm 设置会把全局软件包安装在 root 拥有的目录下，例如 `/usr/lib/node_modules/openclaw`。OpenClaw 通过相同的外部暂存路径支持这种布局。 @@ -110,23 +110,23 @@ bun add -g openclaw@latest ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp ``` - `OPENCLAW_PLUGIN_STAGE_DIR` 也接受路径列表。OpenClaw 会从左到右解析列出的根目录中的内置插件运行时依赖，将较早的根目录视为只读的预安装层，并且只安装或修复到最后一个可写根目录中： + `OPENCLAW_PLUGIN_STAGE_DIR` 也接受路径列表。OpenClaw 会从左到右在列出的根目录中解析内置插件运行时依赖，将较早的根目录视为只读预安装层，并且只安装或修复到最后一个可写根目录中： ```ini Environment=OPENCLAW_PLUGIN_STAGE_DIR=/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp ``` - 如果未设置 `OPENCLAW_PLUGIN_STAGE_DIR`，OpenClaw 会在 systemd 提供 `$STATE_DIRECTORY` 时使用它，然后回退到 `~/.openclaw/plugin-runtime-deps`。修复步骤会将该暂存目录视为 OpenClaw 拥有的本地包根目录，并忽略用户 npm 前缀和全局设置，因此全局安装 npm 配置不会把内置插件依赖重定向到 `~/node_modules` 或全局包树中。 + 如果未设置 `OPENCLAW_PLUGIN_STAGE_DIR`，OpenClaw 会在 systemd 提供 `$STATE_DIRECTORY` 时使用它，然后回退到 `~/.openclaw/plugin-runtime-deps`。修复步骤会将该暂存位置视为 OpenClaw 拥有的本地软件包根目录，并忽略用户 npm 前缀和全局设置，因此全局安装的 npm 配置不会把内置插件依赖重定向到 `~/node_modules` 或全局软件包树中。 - 在包更新和内置运行时依赖修复之前，OpenClaw 会尽力检查目标卷的磁盘空间。空间不足会产生一条包含所检查路径的警告，但不会阻止更新，因为文件系统配额、快照和网络卷可能会在检查后发生变化。实际的 npm 安装、复制和安装后验证仍是权威结果。 + 在软件包更新和内置运行时依赖修复之前，OpenClaw 会尽力检查目标卷的磁盘空间。空间不足会产生一条带有已检查路径的警告，但不会阻止更新，因为文件系统配额、快照和网络卷可能会在检查后变化。实际的 npm 安装、复制和安装后验证仍是权威结果。 - 打包安装会让内置插件运行时依赖保持在只读包树之外。在启动时以及运行 `openclaw doctor --fix` 期间，OpenClaw 只会修复满足以下条件的内置插件的运行时依赖：在配置中处于活动状态、通过旧版渠道配置处于活动状态，或由其内置 manifest 默认启用。仅持久化的渠道认证状态不会触发 Gateway 网关启动时的运行时依赖修复。 + 打包安装会让内置插件运行时依赖保持在只读软件包树之外。在启动期间以及 `openclaw doctor --fix` 期间，OpenClaw 只会为配置中处于活动状态、通过旧版渠道配置处于活动状态，或由其内置清单默认启用的内置插件修复运行时依赖。仅持久化的渠道认证状态不会触发 Gateway 网关启动时的运行时依赖修复。 - 显式禁用优先。被禁用的插件或渠道不会仅因为它存在于包中就修复其运行时依赖。外部插件和自定义加载路径仍使用 `openclaw plugins install` 或 `openclaw plugins update`。 + 显式禁用优先。被禁用的插件或渠道不会仅仅因为它存在于软件包中，就修复其运行时依赖。外部插件和自定义加载路径仍使用 `openclaw plugins install` 或 `openclaw plugins update`。 @@ -149,15 +149,15 @@ bun add -g openclaw@latest } ``` -| 渠道 | 行为 | +| 渠道 | 行为 | | -------- | ------------------------------------------------------------------------------------------------------------- | -| `stable` | 等待 `stableDelayHours`，然后在 `stableJitterHours` 范围内通过确定性抖动应用更新（分散发布）。 | -| `beta` | 每隔 `betaCheckIntervalHours` 检查一次（默认：每小时）并立即应用。 | +| `stable` | 等待 `stableDelayHours`，然后在 `stableJitterHours` 范围内使用确定性抖动应用（分散式发布）。 | +| `beta` | 每隔 `betaCheckIntervalHours` 检查一次（默认：每小时），并立即应用。 | | `dev` | 不自动应用。请手动使用 `openclaw update`。 | -Gateway 网关还会在启动时记录更新提示（使用 `update.checkOnStart: false` 禁用）。对于降级或事故恢复，请在 Gateway 网关环境中设置 `OPENCLAW_NO_AUTO_UPDATE=1`，以便即使配置了 `update.auto.enabled` 也阻止自动应用。启动更新提示仍可运行，除非同时禁用了 `update.checkOnStart`。 +Gateway 网关还会在启动时记录一条更新提示（可用 `update.checkOnStart: false` 禁用）。对于降级或事故恢复，请在 Gateway 网关环境中设置 `OPENCLAW_NO_AUTO_UPDATE=1`，以阻止自动应用，即使已配置 `update.auto.enabled`。除非也禁用了 `update.checkOnStart`，否则启动更新提示仍可运行。 -通过实时 Gateway 网关控制平面处理程序请求的包管理器更新会在包切换后强制执行非延迟的更新重启。这样可以避免旧的内存中进程停留过久，并从已经被替换的包树中延迟加载代码块。对于受监管的安装，Shell `openclaw update` 仍是首选路径，因为它可以围绕更新停止并重启服务。 +通过实时 Gateway 网关控制平面处理器请求的软件包管理器更新，会在软件包切换后强制执行一次不延迟、无冷却的更新重启。这样可以避免旧的内存中进程停留太久，从已经被替换的软件包树中延迟加载分块。对于受监督的安装，shell `openclaw update` 仍是首选路径，因为它可以在更新前后停止并重启服务。 ## 更新后 @@ -169,7 +169,7 @@ Gateway 网关还会在启动时记录更新提示（使用 `update.checkOnStart openclaw doctor ``` -迁移配置、审计私信策略，并检查 Gateway 网关健康状况。详情：[Doctor](/zh-CN/gateway/doctor) +迁移配置、审计私信策略，并检查 Gateway 网关健康状态。详情：[Doctor](/zh-CN/gateway/doctor) ### 重启 Gateway 网关 @@ -208,17 +208,17 @@ pnpm install && pnpm build openclaw gateway restart ``` -要返回最新版本：`git checkout main && git pull`。 +要返回到最新版本：`git checkout main && git pull`。 ## 如果你卡住了 - 再次运行 `openclaw doctor`，并仔细阅读输出。 -- 对于源码检出副本上的 `openclaw update --channel dev`，更新器会在需要时自动引导 `pnpm`。如果你看到 pnpm/corepack 引导错误，请手动安装 `pnpm`（或重新启用 `corepack`）并重新运行更新。 +- 对源码检出上的 `openclaw update --channel dev`，更新器会在需要时自动引导 `pnpm`。如果你看到 pnpm/corepack 引导错误，请手动安装 `pnpm`（或重新启用 `corepack`），然后重新运行更新。 - 查看：[故障排除](/zh-CN/gateway/troubleshooting) -- 在 Discord 询问：[https://discord.gg/clawd](https://discord.gg/clawd) +- 在 Discord 中提问：[https://discord.gg/clawd](https://discord.gg/clawd) -## 相关 +## 相关内容 - [安装概览](/zh-CN/install)：所有安装方法。 - [Doctor](/zh-CN/gateway/doctor)：更新后的健康检查。 -- [迁移](/zh-CN/install/migrating)：主版本迁移指南。 +- [迁移](/zh-CN/install/migrating)：主要版本迁移指南。