openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-20 12:38:15 +00:00
parent dfc38eeabc
commit 5bca17196f
4 changed files with 1401 additions and 1316 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

288
docs/zh-CN/gateway/configuration.md
View File

@ -2,32 +2,32 @@
read_when:
- 首次设置 OpenClaw
- 查找常见配置模式
- 导航到特定配置章节
summary: 配置概览：常见任务、快速设置，以及完整参考的链接
- 导航到特定配置部分
summary: 配置概览：常见任务、快速设置，以及指向完整参考的链接
title: 配置
x-i18n:
generated_at: "2026-04-10T20:41:21Z"
generated_at: "2026-04-20T12:30:06Z"
model: gpt-5.4
provider: openai
source_hash: e874be80d11b9123cac6ce597ec02667fbc798f622a076f68535a1af1f0e399c
source_hash: bad966d0333c28a94905fa8c01eba41dbdf5bfcbda25e7a71a8bea1589703b9b
source_path: gateway/configuration.md
workflow: 15
---
# 配置
OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 <Tooltip tip="JSON5 支持注释和尾随逗号">**JSON5**</Tooltip> 配置。
OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 <Tooltip tip="JSON5 supports comments and trailing commas">**JSON5**</Tooltip> 配置。
如果该文件缺失，OpenClaw 会使用安全的默认值。常见的添加配置原因包括：
如果该文件缺失，OpenClaw 会使用安全的默认值。添加配置的常见原因包括：
- 连接渠道并控制谁可以给机器人发送消息
- 连接渠道并控制谁可以向机器人发送消息
- 设置模型、工具、沙箱隔离或自动化（cron、hooks）
- 调整会话、媒体、网络或 UI
请参阅[完整参考](/zh-CN/gateway/configuration-reference)以了解每个可用字段。
查看[完整参考](/zh-CN/gateway/configuration-reference)以了解每个可用字段。
<Tip>
**刚开始接触配置？** 从 `openclaw onboard` 开始进行交互式设置，或查看[配置示例](/zh-CN/gateway/configuration-examples)指南以获取可直接复制粘贴的完整配置。
**刚开始接触配置？** 先运行 `openclaw onboard` 进行交互式设置，或查看[配置示例](/zh-CN/gateway/configuration-examples)指南，获取可直接复制粘贴的完整配置。
</Tip>
## 最小配置
@ -45,8 +45,8 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 <Tooltip tip="
<Tabs>
<Tab title="交互式向导">
```bash
openclaw onboard # full onboarding flow
openclaw configure # config wizard
openclaw onboard # 完整的新手引导流程
openclaw configure # 配置向导
```
</Tab>
<Tab title="CLI（单行命令）">
@ -57,57 +57,67 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 <Tooltip tip="
```
</Tab>
<Tab title="Control UI">
打开 [http://127.0.0.1:18789](http://127.0.0.1:18789)，然后使用 **Config** 选项卡。
打开 [http://127.0.0.1:18789](http://127.0.0.1:18789) 并使用 **Config** 选项卡。
Control UI 会根据实时配置 schema 渲染表单，其中包括字段
`title` / `description` 文档元数据，以及在可用时包含插件和渠道 schema，
并提供 **Raw JSON** 编辑器作为兜底方式。对于下钻式
UI 和其他工具，Gateway 网关还会公开 `config.schema.lookup`，用于
获取一个按路径限定的 schema 节点以及其直接子项摘要。
`title` / `description` 文档元数据，以及插件和渠道 schema（如果可用），
同时提供 **Raw JSON** 编辑器作为兜底方式。对于下钻式
UI 和其他工具，Gateway 网关 还会暴露 `config.schema.lookup`，
用于获取单个路径范围内的 schema 节点及其直接子项摘要。
</Tab>
<Tab title="直接编辑">
直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。
直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关 会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。
</Tab>
</Tabs>
## 严格校验
<Warning>
OpenClaw 仅接受与 schema 完全匹配的配置。未知键名、格式错误的类型或无效值都会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器就可以附加 JSON Schema 元数据。
OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的类型或无效值都会导致 Gateway 网关 **拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器就可以附加 JSON Schema 元数据。
</Warning>
Schema 工具说明：
- `openclaw config schema` 会输出与 Control UI 和配置校验
使用的同一套 JSON Schema。
- 请将该 schema 输出视为 `openclaw.json` 的规范性机器可读契约；
本概览和配置参考是对它的总结说明。
- 字段 `title` 和 `description` 的值会被带入 schema 输出，
- `openclaw config schema` 会输出与 Control UI
和配置校验所使用的同一套 JSON Schema。
- 将该 schema 输出视为 `openclaw.json` 的规范性机器可读契约；
本概览和配置参考只是对其进行总结。
- 字段 `title` 和 `description` 的值会保留到 schema 输出中，
供编辑器和表单工具使用。
- 嵌套对象、通配符（`*`）和数组项（`[]`）条目会继承相同的
文档元数据，只要存在匹配的字段文档说明。
- `anyOf` / `oneOf` / `allOf` 组合分支也会继承相同的文档
元数据，因此联合/交叉变体会保留相同的字段帮助信息。
- `config.schema.lookup` 会返回一个标准化的配置路径及其浅层
schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界条件
以及类似的校验字段）、匹配的 UI 提示元数据，以及直接子项
文档元数据，只要存在匹配的字段文档。
- `anyOf` / `oneOf` / `allOf` 组合分支同样会继承这些文档
元数据，因此联合 / 交叉类型变体会保留相同的字段帮助信息。
- `config.schema.lookup` 会返回一个规范化的配置路径，以及浅层
schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界
和类似校验字段）、匹配的 UI 提示元数据，以及直接子项
摘要，供下钻式工具使用。
- 当 Gateway 网关能够加载当前 manifest 注册表时，
还会合并运行时插件/渠道 schema。
- `pnpm config:docs:check` 会检测面向文档的配置基线
产物与当前 schema 表面之间的漂移。
- 当 Gateway 网关 能加载当前 manifest 注册表时，会合并运行时插件 / 渠道 schema。
- `pnpm config:docs:check` 会检测面向文档的配置基线产物
与当前 schema 表面之间的漂移。
当校验失败时：
- Gateway 网关不会启动
- Gateway 网关 不会启动
- 只有诊断命令可用（`openclaw doctor`、`openclaw logs`、`openclaw health`、`openclaw status`）
- 运行 `openclaw doctor` 查看确切问题
- 运行 `openclaw doctor --fix`（或 `--yes`）以应用修复
- 运行 `openclaw doctor` 查看精确问题
- 运行 `openclaw doctor --fix`（或 `--yes`）应用修复
此外，Gateway 网关 在成功启动后还会保留一份受信任的、最后一次已知正常副本。如果
`openclaw.json` 之后在 OpenClaw 之外被修改，并且不再通过校验，启动
和热重载会将损坏文件保留为带时间戳的 `.clobbered.*` 快照，
恢复最后一次已知正常副本，并记录一条醒目的警告，说明恢复原因。
接下来的主智能体轮次也会收到一条系统事件警告，告知它
配置已被恢复，不得盲目重写。最后一次已知正常副本的提升
会在通过校验的启动后，以及在接受的热重载后更新，其中也包括
由 OpenClaw 自身发起、且其持久化文件哈希仍与已接受写入匹配的
配置写入。如果候选内容包含被打码的 secret
占位符，例如 `***` 或缩短后的 token 值，则会跳过提升。
## 常见任务
<AccordionGroup>
<Accordion title="设置一个渠道（WhatsApp、Telegram、Discord 等）">
每个渠道在 `channels.<provider>` 下都有自己的配置区段。请查看对应渠道页面了解设置步骤：
<Accordion title="设置渠道（WhatsApp、Telegram、Discord 等）">
每个渠道在 `channels.<provider>` 下都有自己的配置部分。设置步骤请参阅对应的专用渠道页面：
- [WhatsApp](/zh-CN/channels/whatsapp) — `channels.whatsapp`
- [Telegram](/zh-CN/channels/telegram) — `channels.telegram`
@ -159,28 +169,28 @@ Schema 工具说明：
- `agents.defaults.models` 定义模型目录，并充当 `/model` 的 allowlist。
- 模型引用使用 `provider/model` 格式（例如 `anthropic/claude-opus-4-6`）。
- `agents.defaults.imageMaxDimensionPx` 控制转录/工具图像的缩放上限（默认 `1200`）；较低的值通常会在大量截图的运行场景中减少视觉 token 用量。
- 请参阅[模型 CLI](/zh-CN/concepts/models)了解如何在聊天中切换模型，并参阅[模型故障切换](/zh-CN/concepts/model-failover)了解凭证轮换和回退行为。
- 对于自定义/自托管提供商，请参阅参考中的[自定义提供商](/zh-CN/gateway/configuration-reference#custom-providers-and-base-urls)。
- `agents.defaults.imageMaxDimensionPx` 控制 transcript / tool 图像缩放下限（默认值为 `1200`）；对于截图较多的运行，较低值通常会减少视觉 token 使用量。
- 参见[模型 CLI](/zh-CN/concepts/models) 了解如何在聊天中切换模型，参见[模型故障切换](/zh-CN/concepts/model-failover) 了解凭证轮换和回退行为。
- 对于自定义 / 自托管提供商，请参见参考中的[自定义提供商](/zh-CN/gateway/configuration-reference#custom-providers-and-base-urls)。
</Accordion>
<Accordion title="控制谁可以给机器人发送消息">
私信访问通过每个渠道的 `dmPolicy` 进行控制：
<Accordion title="控制谁可以向机器人发送消息">
私信访问通过每个渠道的 `dmPolicy` 控制：
- `"pairing"`（默认）：未知发送者会收到一次性配对码以供批准
- `"allowlist"`：仅允许 `allowFrom` 中的发送者（或已配对的允许存储）
- `"open"`：允许所有入站私信（要求 `allowFrom: ["*"]`）
- `"open"`：允许所有传入私信（要求 `allowFrom: ["*"]`）
- `"disabled"`：忽略所有私信
对于群组，请使用 `groupPolicy` + `groupAllowFrom` 或渠道特定的 allowlist。
请参阅[完整参考](/zh-CN/gateway/configuration-reference#dm-and-group-access)了解各渠道的详细说明。
参见[完整参考](/zh-CN/gateway/configuration-reference#dm-and-group-access)以了解每个渠道的详细信息。
</Accordion>
<Accordion title="设置群聊提及门控">
群组消息默认是**需要提及**。可按智能体配置模式：
群消息默认 **需要提及**。可按智能体配置模式：
```json5
{
@ -204,12 +214,12 @@ Schema 工具说明：
- **元数据提及**：原生 @ 提及（WhatsApp 点按提及、Telegram @bot 等）
- **文本模式**：`mentionPatterns` 中的安全正则模式
- 请参阅[完整参考](/zh-CN/gateway/configuration-reference#group-chat-mention-gating)了解各渠道覆盖项和自聊模式。
- 有关每个渠道的覆盖项和自聊模式，请参见[完整参考](/zh-CN/gateway/configuration-reference#group-chat-mention-gating)。
</Accordion>
<Accordion title="按智能体限制 Skills">
使用 `agents.defaults.skills` 作为共享基线，然后用
使用 `agents.defaults.skills` 作为共享基线，然后通过
`agents.list[].skills` 覆盖特定智能体：
```json5
@ -227,16 +237,16 @@ Schema 工具说明：
}
```
- 省略 `agents.defaults.skills` 表示默认不限制 Skills。
- 省略 `agents.list[].skills` 以继承默认值。
- 省略 `agents.defaults.skills`，则默认 Skills 不受限制。
- 省略 `agents.list[].skills`，则继承默认值。
- 设置 `agents.list[].skills: []` 表示不启用任何 Skills。
- 请参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config)以及
- 参见 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config)，以及
[配置参考](/zh-CN/gateway/configuration-reference#agents-defaults-skills)。
</Accordion>
<Accordion title="调整 Gateway 网关的渠道健康监控">
控制 Gateway 网关对看起来已停滞渠道的重启激进程度：
<Accordion title="调整 Gateway 网关 渠道健康监控">
控制 Gateway 网关 对看起来已失活的渠道进行重启的激进程度：
```json5
{
@ -258,10 +268,10 @@ Schema 工具说明：
}
```
- 将 `gateway.channelHealthCheckMinutes: 0` 设为全局禁用健康监控重启。
- 设置 `gateway.channelHealthCheckMinutes: 0` 以全局禁用健康监控重启。
- `channelStaleEventThresholdMinutes` 应大于或等于检查间隔。
- 使用 `channels.<provider>.healthMonitor.enabled` 或 `channels.<provider>.accounts.<id>.healthMonitor.enabled` 可为单个渠道或账户禁用自动重启，而无需禁用全局监控。
- 请参阅[健康检查](/zh-CN/gateway/health)了解运维调试信息，并参阅[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。
- 使用 `channels.<provider>.healthMonitor.enabled` 或 `channels.<provider>.accounts.<id>.healthMonitor.enabled`，可为单个渠道或账户禁用自动重启，而无需禁用全局监控。
- 参见[健康检查](/zh-CN/gateway/health)了解运维调试信息，参见[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。
</Accordion>
@ -287,9 +297,9 @@ Schema 工具说明：
```
- `dmScope`：`main`（共享）| `per-peer` | `per-channel-peer` | `per-account-channel-peer`
- `threadBindings`：用于线程绑定会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。
- 请参阅[会话管理](/zh-CN/concepts/session)了解作用域、身份链接和发送策略。
- 请参阅[完整参考](/zh-CN/gateway/configuration-reference#session)了解所有字段。
- `threadBindings`：线程绑定会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。
- 参见[会话管理](/zh-CN/concepts/session)了解作用域、身份链接和发送策略。
- 参见[完整参考](/zh-CN/gateway/configuration-reference#session)了解所有字段。
</Accordion>
@ -311,14 +321,14 @@ Schema 工具说明：
请先构建镜像：`scripts/sandbox-setup.sh`
请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)了解完整指南，并参阅[完整参考](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox)了解所有选项。
参见[沙箱隔离](/zh-CN/gateway/sandboxing)获取完整指南，参见[完整参考](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox)了解所有选项。
</Accordion>
<Accordion title="为官方 iOS 构建启用基于 relay 的推送">
基于 relay 的推送在 `openclaw.json` 中配置。
在 Gateway 网关配置中设置以下内容：
在 Gateway 网关 配置中设置以下内容：
```json5
{
@ -327,7 +337,7 @@ Schema 工具说明：
apns: {
relay: {
baseUrl: "https://relay.example.com",
// Optional. Default: 10000
// 可选。默认值：10000
timeoutMs: 10000,
},
},
@ -336,39 +346,39 @@ Schema 工具说明：
}
```
对应的 CLI 命令：
等效的 CLI：
```bash
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
```
这会执行以下操作：
其作用如下：
- 允许 Gateway 网关通过外部 relay 发送 `push.test`、唤醒提示和重连唤醒。
- 使用由已配对 iOS 应用转发的、以注册为作用域的发送授权。Gateway 网关不需要部署范围的 relay token。
- 将每个基于 relay 的注册绑定到 iOS 应用所配对的 Gateway 网关身份，因此其他 Gateway 网关无法复用已存储的注册信息。
- 本地/手动构建的 iOS 版本仍然直接使用 APNs。基于 relay 的发送仅适用于通过 relay 完成注册的官方分发版本。
- 必须与官方/TestFlight iOS 构建中预置的 relay 基础 URL 保持一致，这样注册和发送流量才能到达同一个 relay 部署。
- 让 Gateway 网关 能够通过外部 relay 发送 `push.test`、唤醒提示和重连唤醒。
- 使用由已配对 iOS 应用转发的、以注册为作用域的发送授权。Gateway 网关 不需要部署范围的 relay token。
- 将每个基于 relay 的注册绑定到 iOS 应用所配对的 Gateway 网关 身份，因此其他 Gateway 网关 无法复用已存储的注册。
- 本地 / 手动构建的 iOS 版本仍然使用直连 APNs。基于 relay 的发送仅适用于通过 relay 注册的官方分发版本。
- 必须与官方 / TestFlight iOS 构建中内置的 relay base URL 一致，这样注册和发送流量才能到达同一个 relay 部署。
端到端流程：
1. 安装一个使用相同 relay 基础 URL 编译的官方/TestFlight iOS 构建。
2. 在 Gateway 网关上配置 `gateway.push.apns.relay.baseUrl`。
3. 将 iOS 应用与 Gateway 网关配对，并让节点会话和操作员会话都建立连接。
4. iOS 应用获取 Gateway 网关身份，使用 App Attest 和应用回执向 relay 注册，然后将基于 relay 的 `push.apns.register` 负载发布到已配对的 Gateway 网关。
5. Gateway 网关存储 relay 句柄和发送授权，然后将它们用于 `push.test`、唤醒提示和重连唤醒。
1. 安装一个使用相同 relay base URL 编译的官方 / TestFlight iOS 构建版本。
2. 在 Gateway 网关 上配置 `gateway.push.apns.relay.baseUrl`。
3. 将 iOS 应用与 Gateway 网关 配对，并让节点会话和操作员会话都完成连接。
4. iOS 应用获取 Gateway 网关 身份，使用 App Attest 和应用回执向 relay 注册，然后将基于 relay 的 `push.apns.register` 负载发布到已配对的 Gateway 网关。
5. Gateway 网关 存储 relay 句柄和发送授权，然后将其用于 `push.test`、唤醒提示和重连唤醒。
运行说明：
- 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接应用，以便它发布一个绑定到该 Gateway 网关的新 relay 注册。
- 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接应用，以便它发布一个绑定到该 Gateway 网关 的新 relay 注册。
- 如果你发布了一个指向不同 relay 部署的新 iOS 构建，应用会刷新其缓存的 relay 注册，而不是复用旧的 relay 来源。
兼容性说明：
- `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可作为临时环境变量覆盖项使用。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍然只是一个仅限 loopback 的开发逃生舱；不要在配置中持久化 HTTP relay URL。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍然是仅限 loopback 的开发逃生开关；不要在配置中持久保存 HTTP relay URL。
请参阅 [iOS App](/zh-CN/platforms/ios#relay-backed-push-for-official-builds) 了解端到端流程，并参阅 [Authentication and trust flow](/zh-CN/platforms/ios#authentication-and-trust-flow) 了解 relay 安全模型。
参见 [iOS App](/zh-CN/platforms/ios#relay-backed-push-for-official-builds) 了解端到端流程，参见 [Authentication and trust flow](/zh-CN/platforms/ios#authentication-and-trust-flow) 了解 relay 安全模型。
</Accordion>
@ -386,10 +396,10 @@ Schema 工具说明：
}
```
- `every`：时长字符串（`30m`、`2h`）。设为 `0m` 可禁用。
- `every`：时长字符串（`30m`、`2h`）。设置为 `0m` 可禁用。
- `target`：`last` | `none` | `<channel-id>`（例如 `discord`、`matrix`、`telegram` 或 `whatsapp`）
- `directPolicy`：用于私信式心跳目标的 `allow`（默认）或 `block`
- 请参阅[心跳](/zh-CN/gateway/heartbeat)了解完整指南。
- `directPolicy`：对于私信式心跳目标，可设为 `allow`（默认）或 `block`
- 完整指南参见[心跳](/zh-CN/gateway/heartbeat)。
</Accordion>
@ -408,14 +418,14 @@ Schema 工具说明：
}
```
- `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设为 `false` 可禁用）。
- `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设置为 `false` 可禁用）。
- `runLog`：按大小和保留行数清理 `cron/runs/<jobId>.jsonl`。
- 请参阅 [Cron jobs](/zh-CN/automation/cron-jobs) 了解功能概览和 CLI 示例。
- 功能概览和 CLI 示例参见 [Cron jobs](/zh-CN/automation/cron-jobs)。
</Accordion>
<Accordion title="设置 webhook（hooks）">
在 Gateway 网关上启用 HTTP webhook 端点：
在 Gateway 网关 上启用 HTTP webhook 端点：
```json5
{
@ -439,20 +449,20 @@ Schema 工具说明：
```
安全说明：
- 将所有 hook/webhook 负载内容都视为不可信输入。
- 使用专用的 `hooks.token`；不要复用共享的 Gateway 网关 token。
- Hook 身份验证仅支持请求头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串 token 会被拒绝。
- `hooks.path` 不能为 `/`；请将 webhook 入口放在专用子路径下，例如 `/hooks`。
- 保持不安全内容绕过标志处于禁用状态（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`），除非你正在进行严格限定范围的调试。
- 如果你启用了 `hooks.allowRequestSessionKey`，还应设置 `hooks.allowedSessionKeyPrefixes`，以限制调用方可选的会话键。
- 对于由 hook 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如仅消息传递，并在可能时启用沙箱隔离）。
- 将所有 hook / webhook 负载内容都视为不受信任的输入。
- 使用专用的 `hooks.token`；不要复用共享 Gateway 网关 token。
- Hook 认证仅支持请求头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串 token 会被拒绝。
- `hooks.path` 不能是 `/`；请将 webhook 入口保留在专用子路径下，例如 `/hooks`。
- 保持不安全内容绕过标志关闭（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`），除非你是在做严格限定范围内的调试。
- 如果你启用了 `hooks.allowRequestSessionKey`，也请设置 `hooks.allowedSessionKeyPrefixes`，以限制调用方可选择的会话键。
- 对于由 hook 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如仅限消息传递，并尽可能启用沙箱隔离）。
请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)了解所有映射选项和 Gmail 集成。
参见[完整参考](/zh-CN/gateway/configuration-reference#hooks)了解所有映射选项和 Gmail 集成。
</Accordion>
<Accordion title="配置多智能体路由">
使用单独的工作区和会话运行多个隔离智能体：
运行多个彼此隔离的智能体，并使用各自独立的工作区和会话：
```json5
{
@ -469,7 +479,7 @@ Schema 工具说明：
}
```
请参阅[多智能体](/zh-CN/concepts/multi-agent)和[完整参考](/zh-CN/gateway/configuration-reference#multi-agent-routing)了解绑定规则和每个智能体的访问配置文件。
参见 [Multi-Agent](/zh-CN/concepts/multi-agent) 和[完整参考](/zh-CN/gateway/configuration-reference#multi-agent-routing)了解绑定规则和每个智能体的访问配置文件。
</Accordion>
@ -489,26 +499,38 @@ Schema 工具说明：
- **单个文件**：替换包含它的对象
- **文件数组**：按顺序深度合并（后者优先）
- **同级键**：在 include 之后合并（覆盖 include 中的值）
- **嵌套 include**：支持，最多 10 层
- **同级键名**：在 include 之后合并（覆盖被包含的值）
- **嵌套 include**：最多支持 10 层嵌套
- **相对路径**：相对于包含它的文件解析
- **错误处理**：对缺失文件、解析错误和循环 include 提供清晰错误信息
- **错误处理**：对于缺失文件、解析错误和循环 include，都会提供清晰错误信息
</Accordion>
</AccordionGroup>
## 配置热重载
Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改——大多数设置无需手动重启。
Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改——大多数设置都不需要手动重启。
直接编辑文件在通过校验之前会被视为不受信任。监视器会等待
编辑器临时写入 / 重命名的抖动结束，读取最终文件，并通过恢复
最后一次已知正常配置来拒绝无效的外部编辑。由 OpenClaw 发起的
配置写入也会在写入前经过相同的 schema 检查；像删除 `gateway.mode`
或将文件缩小到一半以下这样的破坏性覆盖会被拒绝，并保存为
`.rejected.*` 供检查。
如果你在日志中看到 `Config auto-restored from last-known-good` 或
`config reload restored last-known-good config`，请检查 `openclaw.json`
旁边对应的 `.clobbered.*` 文件，修复被拒绝的负载，然后运行
`openclaw config validate`。恢复检查清单参见[Gateway 网关 故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。
### 重载模式
| 模式 | 行为 |
| ---------------------- | --------------------------------------------------------------------------------------- |
| **`hybrid`**（默认） | 立即热应用安全更改。对关键更改会自动重启。 |
| **`hot`** | 仅热应用安全更改。当需要重启时记录警告——由你自行处理。 |
| **`hybrid`**（默认） | 立即热应用安全更改。对于关键更改会自动重启。 |
| **`hot`** | 仅热应用安全更改。当需要重启时记录一条警告——由你来处理。 |
| **`restart`** | 对任何配置更改都重启 Gateway 网关，无论是否安全。 |
| **`off`** | 禁用文件监视。更改将在下次手动重启时生效。 |
| **`off`** | 禁用文件监视。更改会在下次手动重启时生效。 |
```json5
{
@ -520,7 +542,7 @@ Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改——
### 哪些可以热应用，哪些需要重启
大多数字段都可以在不停机的情况下热应用。在 `hybrid` 模式下，需要重启的更改会被自动处理。
大多数字段都可以无停机热应用。在 `hybrid` 模式下，需要重启的更改会自动处理。
| 类别 | 字段 | 需要重启？ |
| ------------------- | -------------------------------------------------------------------- | --------------- |
@ -529,49 +551,49 @@ Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改——
| 自动化 | `hooks`、`cron`、`agent.heartbeat` | 否 |
| 会话和消息 | `session`、`messages` | 否 |
| 工具和媒体 | `tools`、`browser`、`skills`、`audio`、`talk` | 否 |
| UI 和其他 | `ui`、`logging`、`identity`、`bindings` | 否 |
| Gateway 网关服务器 | `gateway.*`（port、bind、auth、tailscale、TLS、HTTP） | **是** |
| UI 和杂项 | `ui`、`logging`、`identity`、`bindings` | 否 |
| Gateway 网关 服务器 | `gateway.*`（port、bind、auth、tailscale、TLS、HTTP） | **是** |
| 基础设施 | `discovery`、`canvasHost`、`plugins` | **是** |
<Note>
`gateway.reload` 和 `gateway.remote` 是例外——更改它们**不会**触发重启。
`gateway.reload` 和 `gateway.remote` 是例外——更改它们 **不会** 触发重启。
</Note>
## 配置 RPC（程序化更新）
<Note>
控制平面写入 RPC（`config.apply`、`config.patch`、`update.run`）按每个 `deviceId+clientIp` 限速为**每 60 秒 3 次请求**。触发限制时，RPC 会返回带有 `retryAfterMs` 的 `UNAVAILABLE`。
控制平面写入 RPC（`config.apply`、`config.patch`、`update.run`）会按每个 `deviceId+clientIp` 做速率限制：**每 60 秒 3 次请求**。触发限制时，RPC 会返回 `UNAVAILABLE` 并附带 `retryAfterMs`。
</Note>
安全/默认流程：
安全 / 默认流程：
- `config.schema.lookup`：检查一个按路径限定的配置子树，返回浅层
schema 节点、匹配的提示元数据和直接子项摘要
- `config.schema.lookup`：检查单个路径范围内的配置子树，包括浅层
schema 节点、匹配的提示元数据以及直接子项摘要
- `config.get`：获取当前快照 + hash
- `config.patch`：首选的部分更新路径
- `config.patch`：推荐的部分更新路径
- `config.apply`：仅用于完整配置替换
- `update.run`：显式自更新 + 重启
如果你不是要替换整个配置，优先使用 `config.schema.lookup`
然后使用 `config.patch`。
当你不是要替换整个配置时，优先使用 `config.schema.lookup`
然后再使用 `config.patch`。
<AccordionGroup>
<Accordion title="config.apply（完整替换）">
在一步内校验并写入完整配置，同时重启 Gateway 网关。
校验 + 写入完整配置，并在一步中重启 Gateway 网关。
<Warning>
`config.apply` 会替换**整个配置**。部分更新请使用 `config.patch`，单个键请使用 `openclaw config set`。
`config.apply` 会替换**整个配置**。部分更新请使用 `config.patch`，单个键名请使用 `openclaw config set`。
</Warning>
参数：
- `raw`（字符串）——整个配置的 JSON5 负载
- `baseHash`（可选）——来自 `config.get` 的配置 hash（当配置已存在时为必需）
- `sessionKey`（可选）——重启后唤醒 ping 使用的会话键
- `note`（可选）——重启哨兵的说明
- `sessionKey`（可选）——重启后唤醒 ping 所用的会话键
- `note`（可选）——重启哨兵的备注
- `restartDelayMs`（可选）——重启前延迟（默认 2000）
当某个重启已经处于待处理/进行中状态时，重启请求会被合并；并且两次重启周期之间会应用 30 秒冷却时间。
当已有重启处于待处理 / 进行中时，重启请求会被合并，并且两次重启周期之间会有 30 秒冷却时间。
```bash
openclaw gateway call config.get --params '{}' # capture payload.hash
@ -587,17 +609,17 @@ Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改——
<Accordion title="config.patch（部分更新）">
将部分更新合并到现有配置中（JSON merge patch 语义）：
- 对象递归合并
- `null` 删除某个键
- 数组整体替换
- 对象会递归合并
- `null` 会删除一个键名
- 数组会整体替换
参数：
- `raw`（字符串）——仅包含要更改键名的 JSON5
- `baseHash`（必需）——来自 `config.get` 的配置 hash
- `sessionKey`、`note`、`restartDelayMs`——与 `config.apply` 相同
- `baseHash`（必填）——来自 `config.get` 的配置 hash
- `sessionKey`、`note`、`restartDelayMs` —— 与 `config.apply` 相同
重启行为与 `config.apply` 一致：会合并待处理的重启请求，并在两次重启周期之间应用 30 秒冷却时间。
重启行为与 `config.apply` 一致：会合并待处理的重启请求，并在两次重启周期之间设置 30 秒冷却时间。
```bash
openclaw gateway call config.patch --params '{
@ -614,9 +636,9 @@ Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改——
OpenClaw 会从父进程读取环境变量，另外还会读取：
- 当前工作目录中的 `.env`（如果存在）
- `~/.openclaw/.env`（全局兜底）
- `~/.openclaw/.env`（全局回退）
这两个文件都不会覆盖已存在的环境变量。你也可以在配置中设置内联环境变量：
这两个文件都不会覆盖现有环境变量。你也可以在配置中设置内联环境变量：
```json5
{
@ -627,8 +649,8 @@ OpenClaw 会从父进程读取环境变量，另外还会读取：
}
```
<Accordion title="Shell 环境导入（可选）">
如果启用且预期键名尚未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键名：
<Accordion title="Shell 环境变量导入（可选）">
如果已启用，并且预期键名尚未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键名：
```json5
{
@ -638,11 +660,11 @@ OpenClaw 会从父进程读取环境变量，另外还会读取：
}
```
环境变量等价形式：`OPENCLAW_LOAD_SHELL_ENV=1`
环境变量等效项：`OPENCLAW_LOAD_SHELL_ENV=1`
</Accordion>
<Accordion title="配置值中的环境变量替换">
你可以在任意配置字符串值中使用 `${VAR_NAME}` 引用环境变量：
你可以在任何配置字符串值中使用 `${VAR_NAME}` 引用环境变量：
```json5
{
@ -654,8 +676,8 @@ OpenClaw 会从父进程读取环境变量，另外还会读取：
规则：
- 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`
- 缺失或为空的变量会在加载时抛出错误
- 使用 `$${VAR}` 可输出字面量
- 缺失 / 为空的变量会在加载时抛出错误
- 使用 `$${VAR}` 转义以输出字面值
- 在 `$include` 文件中同样可用
- 内联替换：`"${BASE}/v1"` → `"https://api.example.com/v1"`
@ -694,15 +716,15 @@ OpenClaw 会从父进程读取环境变量，另外还会读取：
}
```
有关 SecretRef 的详细信息（包括用于 `env` / `file` / `exec` 的 `secrets.providers`），请参阅[密钥管理](/zh-CN/gateway/secrets)。
SecretRef 详情（包括用于 `env` / `file` / `exec` 的 `secrets.providers`）见[Secrets Management](/zh-CN/gateway/secrets)。
支持的凭证路径列在 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) 中。
</Accordion>
请参阅[环境](/zh-CN/help/environment)了解完整的优先级和来源。
完整优先级和来源请参见[环境](/zh-CN/help/environment)。
## 完整参考
如需完整的逐字段参考，请参阅 **[配置参考](/zh-CN/gateway/configuration-reference)**。
如需逐字段的完整参考，请参见 **[配置参考](/zh-CN/gateway/configuration-reference)**。
---

297
docs/zh-CN/gateway/troubleshooting.md
View File

@ -1,26 +1,26 @@
---
read_when:
- 故障排除中心将你引导到这里，以进行更深入的诊断
- 你需要按症状划分且稳定的手册章节，并提供精确的命令
- 故障排除中心将你引导到这里，以便进行更深入的诊断
- 你需要按稳定症状组织的手册章节，并包含精确的命令
summary: Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除手册
title: 故障排除
x-i18n:
generated_at: "2026-04-20T07:04:35Z"
generated_at: "2026-04-20T12:30:02Z"
model: gpt-5.4
provider: openai
source_hash: d93a82407dbb1314b91a809ff9433114e1e9a3b56d46547ef53a8196bac06260
source_hash: 2afb105376bb467e5a344e6d73726908cb718fa13116b751fddb494a0b641c42
source_path: gateway/troubleshooting.md
workflow: 15
---
# Gateway 网关故障排除
本页是深度故障排除手册。
如果你想先走快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。
此页面是深度排障手册。
如果你想先使用快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。
## 命令阶梯
先运行这些命令，顺序如下：
先按以下顺序运行这些命令：
```bash
openclaw status
@ -32,13 +32,13 @@ openclaw channels status --probe
预期的健康信号：
- `openclaw gateway status` 显示 `Runtime: running`、`Connectivity probe: ok` 和一行 `Capability: ...`。
- `openclaw doctor` 报告没有会阻塞的配置或服务问题。
- `openclaw channels status --probe` 显示每个账户的实时传输状态，并且在支持的情况下显示探测 / 审计结果，例如 `works` 或 `audit ok`。
- `openclaw gateway status` 显示 `Runtime: running`、`Connectivity probe: ok`，以及一行 `Capability: ...`。
- `openclaw doctor` 报告没有阻塞性的配置 / 服务问题。
- `openclaw channels status --probe` 显示每个账号的实时传输状态，并在支持的情况下显示探测 / 审计结果，例如 `works` 或 `audit ok`。
## Anthropic 429：长上下文需要额外使用额度
当日志 / 错误中包含以下内容时使用本节：
当日志 / 错误中包含以下内容时，使用本节：
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`。
```bash
@ -49,15 +49,15 @@ openclaw config get agents.defaults.models
检查以下内容：
- 选定的 Anthropic Opus / Sonnet 模型启用了 `params.context1m: true`。
- 当前 Anthropic 凭证不具备长上下文使用资格。
- 请求只会在需要走 1M beta 路径的长会话 / 模型运行中失败。
- 所选的 Anthropic Opus / Sonnet 模型设置了 `params.context1m: true`。
- 当前的 Anthropic 凭证没有长上下文使用资格。
- 请求仅在需要使用 1M beta 路径的长会话 / 模型运行中失败。
修复选项：
1. 为该模型禁用 `context1m`，回退到普通上下文窗口。
2. 使用具备长上下文请求资格的 Anthropic 凭证，或切换到 Anthropic API 密钥。
3. 配置后备模型，这样当 Anthropic 长上下文请求被拒绝时，运行仍可继续。
2. 使用具备长上下文请求资格的 Anthropic 凭证，或切换为 Anthropic API key。
3. 配置回退模型，以便在 Anthropic 长上下文请求被拒绝时继续运行。
相关内容：
@ -65,9 +65,9 @@ openclaw config get agents.defaults.models
- [/reference/token-use](/zh-CN/reference/token-use)
- [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/zh-CN/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
## 本地 OpenAI 兼容后端直接探测通过，但智能体运行失败
## 本地 OpenAI-compatible 后端直接探测通过，但智能体运行失败
当出现以下情况时使用本节：
在以下情况下使用本节：
- `curl ... /v1/models` 可用
- 很小的直接 `/v1/chat/completions` 调用可用
@ -84,22 +84,22 @@ openclaw logs --follow
检查以下内容：
- 很小的直接调用成功，但 OpenClaw 运行只会在更大的提示词下失败
- 后端报错 `messages[].content` 期望是字符串
- 后端只会在更大的 prompt token 数量或完整智能体运行时提示词下崩溃
- 直接的小请求成功，但 OpenClaw 运行只在更大的提示词上失败
- 后端报错 `messages[].content` 应为字符串
- 后端仅在更大的提示词 token 数或完整智能体运行时提示词下崩溃
常见特征：
- `messages[...].content: invalid type: sequence, expected a string` → 后端拒绝结构化的 Chat Completions 内容片段。修复方法：设置 `models.providers.<provider>.models[].compat.requiresStringContent: true`。
- 很小的直接请求成功，但 OpenClaw 智能体运行因后端 / 模型崩溃而失败（例如某些 `inferrs` 构建中的 Gemma）→ OpenClaw 传输层很可能已经正确；失败的是后端对更大智能体运行时提示词形态的处理。
- 禁用工具后失败有所减少但未消失 → 工具 schema 是压力来源之一，但剩余问题仍然是上游模型 / 服务器容量限制或后端 bug。
- 直接的小请求成功，但 OpenClaw 智能体运行因后端 / 模型崩溃而失败（例如某些 `inferrs` 构建上的 Gemma）→ OpenClaw 传输层很可能已经正确；是后端在更大的智能体运行时提示词形态下失败。
- 禁用工具后失败有所减少但没有消失 → 工具 schema 是压力来源之一，但剩余问题仍然是上游模型 / 服务器容量限制或后端 bug。
修复选项：
1. 对仅支持字符串型 Chat Completions 的后端设置 `compat.requiresStringContent: true`。
2. 对无法可靠处理 OpenClaw 工具 schema 表面的模型 / 后端设置 `compat.supportsTools: false`。
3. 在可能的情况下减轻提示词压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或使用更强长上下文支持的后端。
4. 如果很小的直接请求持续通过，但 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器 / 模型限制，并向上游提交复现，附上其可接受的负载形态。
1. 为仅支持字符串的 Chat Completions 后端设置 `compat.requiresStringContent: true`。
2. 为无法可靠处理 OpenClaw 工具 schema 表面的模型 / 后端设置 `compat.supportsTools: false`。
3. 尽可能降低提示词压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或使用长上下文支持更强的后端。
4. 如果直接的小请求持续通过，但 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器 / 模型限制，并向上游提交包含已接受负载形态的复现。
相关内容：
@ -109,7 +109,7 @@ openclaw logs --follow
## 没有回复
如果渠道已连通但没有任何回应，在重新连接任何东西之前，先检查路由和策略。
如果渠道正常，但没有任何响应，请先检查路由和策略，再考虑重新连接任何内容。
```bash
openclaw status
@ -121,14 +121,14 @@ openclaw logs --follow
检查以下内容：
- 私信发送者是否处于待配对状态。
- 私信发送者的配对仍在等待中。
- 群组提及门控（`requireMention`、`mentionPatterns`）。
- 渠道 / 群组 allowlist 不匹配。
常见特征：
- `drop guild message (mention required` → 群消息会被忽略，直到被提及。
- `pairing request` → 发送者需要获批。
- `drop guild message (mention required` → 群消息在被提及之前会被忽略。
- `pairing request` → 发送者需要批准。
- `blocked` / `allowlist` → 发送者 / 渠道被策略过滤。
相关内容：
@ -137,9 +137,9 @@ openclaw logs --follow
- [/channels/pairing](/zh-CN/channels/pairing)
- [/channels/groups](/zh-CN/channels/groups)
## 仪表板 control ui 连接问题
## Dashboard 控制 UI 连接问题
当仪表板 / control UI 无法连接时，请验证 URL、认证模式和安全上下文假设。
当 dashboard / 控制 UI 无法连接时，请验证 URL、认证模式和安全上下文假设。
```bash
openclaw gateway status
@ -151,34 +151,34 @@ openclaw gateway status --json
检查以下内容：
- 正确的探测 URL 和仪表板 URL。
- 客户端与 Gateway 网关之间的认证模式 / 令牌是否匹配。
- 是否在需要设备身份时使用了 HTTP。
- 正确的探测 URL 和 dashboard URL。
- 客户端与 Gateway 网关之间的认证模式 / token 不匹配。
- 在需要设备身份时使用了 HTTP。
常见特征：
- `device identity required` → 非安全上下文，或缺少设备认证。
- `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正从非 loopback 的浏览器 origin 连接，但没有显式 allowlist）。
- `device nonce required` / `device nonce mismatch` → 客户端未完成基于挑战的设备认证流程（`connect.challenge` + `device.nonce`）。
- `device identity required` → 非安全上下文或缺少设备认证。
- `origin not allowed` → 浏览器的 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正从非 loopback 的浏览器源发起连接，但未显式加入 allowlist）。
- `device nonce required` / `device nonce mismatch` → 客户端没有完成基于挑战的设备认证流程（`connect.challenge` + `device.nonce`）。
- `device signature invalid` / `device signature expired` → 客户端为当前握手签署了错误的负载（或使用了过期时间戳）。
- `AUTH_TOKEN_MISMATCH` 且 `canRetryWithDeviceToken=true` → 客户端可以使用缓存的设备令牌进行一次可信重试。
- 该缓存令牌重试会复用与已配对设备令牌一起存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则保持其请求的作用域集合不变。
- 在该重试路径之外，连接认证优先级依次为：显式共享令牌 / 密码、然后显式 `deviceToken`、然后存储的设备令牌、最后是引导令牌。
- 在异步 Tailscale Serve Control UI 路径中，同一个 `{scope, ip}` 的失败尝试会在限流器记录失败之前被串行化。因此，同一客户端两个错误的并发重试，第二次可能显示 `retry later`，而不是两个普通的不匹配。
- 浏览器 origin 的 loopback 客户端出现 `too many failed authentication attempts (retry later)` → 来自同一归一化 `Origin` 的重复失败会被临时锁定；另一个 localhost origin 使用单独的桶。
- 在该重试之后仍重复出现 `unauthorized` → 共享令牌 / 设备令牌发生漂移；如有需要，刷新令牌配置并重新批准 / 轮换设备令牌。
- `AUTH_TOKEN_MISMATCH` 且 `canRetryWithDeviceToken=true` → 客户端可以使用缓存的设备 token 执行一次可信重试。
- 该缓存 token 的重试会复用与已配对设备 token 一起存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则保留其请求的作用域集合。
- 在该重试路径之外，连接认证优先级依次是显式共享 token / password、显式 `deviceToken`、已存储设备 token、bootstrap token。
- 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, ip}` 的失败尝试会在限流器记录失败之前被串行化。因此，同一客户端两个错误的并发重试中，第二次可能显示 `retry later`，而不是两个普通的不匹配错误。
- 浏览器源 loopback 客户端出现 `too many failed authentication attempts (retry later)` → 来自同一归一化 `Origin` 的重复失败会被临时锁定；另一个 localhost 源会使用独立的计数桶。
- 在该重试之后反复出现 `unauthorized` → 共享 token / 设备 token 漂移；如有需要，刷新 token 配置并重新批准 / 轮换设备 token。
- `gateway connect failed:` → 主机 / 端口 / URL 目标错误。
### 认证详情代码速查表
### 认证细节代码快速对照
使用失败 `connect` 响应中的 `error.details.code` 来选择下一步操作：
使用失败的 `connect` 响应中的 `error.details.code` 来选择下一步操作：
| 详情代码 | 含义 | 建议操作 |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING` | 客户端未发送必需的共享令牌。 | 在客户端中粘贴 / 设置令牌后重试。对于仪表板路径：`openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。 |
| `AUTH_TOKEN_MISMATCH` | 共享令牌与 Gateway 网关认证令牌不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许进行一次可信重试。缓存令牌重试会复用已存储的已批准作用域；显式 `deviceToken` / `scopes` 调用方保持其请求的作用域。如果仍然失败，请运行[令牌漂移恢复清单](/cli/devices#token-drift-recovery-checklist)。 |
| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的每设备令牌已过期或被撤销。 | 使用 [devices CLI](/cli/devices) 轮换 / 重新批准设备令牌，然后重新连接。 |
| `PAIRING_REQUIRED` | 设备身份需要批准。查看 `error.details.reason`，其值可能为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。 | 批准待处理请求：`openclaw devices list`，然后 `openclaw devices approve <requestId>`。作用域 / 角色升级在你审查所请求的访问权限后也使用相同流程。 |
| Detail code | 含义 | 推荐操作 |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING` | 客户端没有发送必需的共享 token。 | 在客户端中粘贴 / 设置 token 后重试。对于 dashboard 路径：`openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。 |
| `AUTH_TOKEN_MISMATCH` | 共享 token 与 Gateway 网关认证 token 不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次可信重试。缓存 token 的重试会复用已存储的已批准作用域；显式 `deviceToken` / `scopes` 调用方则保留请求的作用域。如果仍失败，请运行 [token 漂移恢复清单](/cli/devices#token-drift-recovery-checklist)。 |
| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的每设备 token 已过期或被撤销。 | 使用 [devices CLI](/cli/devices) 轮换 / 重新批准设备 token，然后重新连接。 |
| `PAIRING_REQUIRED` | 设备身份需要批准。检查 `error.details.reason` 是否为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。 | 批准待处理请求：`openclaw devices list`，然后执行 `openclaw devices approve <requestId>`。在你审核所请求的访问权限后，作用域 / 角色升级也使用相同流程。 |
设备认证 v2 迁移检查：
@ -188,16 +188,16 @@ openclaw doctor
openclaw gateway status
```
如果日志显示 nonce / signature 错误，请更新连接客户端并验证它会：
如果日志显示 nonce / signature 错误，请更新发起连接的客户端并验证它是否：
1. 等待 `connect.challenge`
2. 对绑定该挑战的负载进行签名
3. 使用相同的挑战 nonce 发送 `connect.params.device.nonce`
2. 对绑定 challenge 的负载进行签名
3. 使用相同的 challenge nonce 发送 `connect.params.device.nonce`
如果 `openclaw devices rotate` / `revoke` / `remove` 意外被拒绝：
如果 `openclaw devices rotate` / `revoke` / `remove` 被意外拒绝：
- 已配对设备令牌会话只能管理**它们自己的**设备，除非调用方还拥有 `operator.admin`
- `openclaw devices rotate --scope ...` 只能请求调用方当前会话已持有的 operator 作用域
- 已配对设备 token 会话只能管理**它们自己的**设备，除非调用方同时具有 `operator.admin`
- `openclaw devices rotate --scope ...` 只能请求调用方会话已持有的 operator 作用域
相关内容：
@ -216,21 +216,21 @@ openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep # also scan system-level services
openclaw gateway status --deep # 也会扫描系统级服务
```
检查以下内容：
- `Runtime: stopped` 以及退出提示。
- 服务配置不匹配（`Config (cli)` 对比 `Config (service)`）。
- 带有退出提示的 `Runtime: stopped`。
- 服务配置不匹配（`Config (cli)` 与 `Config (service)`）。
- 端口 / 监听器冲突。
- 使用 `--deep` 时发现额外的 launchd / systemd / schtasks 安装。
- 使用 `--deep` 时发现的额外 launchd / systemd / schtasks 安装。
- `Other gateway-like services detected (best effort)` 清理提示。
常见特征：
- `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 未启用本地 Gateway 网关模式，或者配置文件被覆盖并丢失了 `gateway.mode`。修复方法：在你的配置中设置 `gateway.mode="local"`，或者重新运行 `openclaw onboard --mode local` / `openclaw setup`，重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。
- `refusing to bind gateway ... without auth` → 非 loopback 绑定时，没有有效的 Gateway 网关认证路径（令牌 / 密码，或在已配置情况下使用 trusted-proxy）。
- `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 未启用本地 Gateway 网关模式，或者配置文件被覆盖后丢失了 `gateway.mode`。修复方法：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup` 以重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。
- `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径的情况下尝试绑定到非 loopback 地址（token / password，或在已配置时使用 trusted-proxy）。
- `another gateway instance is already listening` / `EADDRINUSE` → 端口冲突。
- `Other gateway-like services detected (best effort)` → 存在陈旧或并行的 launchd / systemd / schtasks 单元。大多数环境每台机器应只保留一个 Gateway 网关；如果你确实需要多个，请隔离端口 + 配置 / 状态 / 工作区。参见 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。
@ -240,9 +240,66 @@ openclaw gateway status --deep # also scan system-level services
- [/gateway/configuration](/zh-CN/gateway/configuration)
- [/gateway/doctor](/zh-CN/gateway/doctor)
## Gateway 网关已恢复最后一次已知正常配置
当 Gateway 网关能启动，但日志显示它恢复了 `openclaw.json` 时，使用本节。
```bash
openclaw logs --follow
openclaw config file
openclaw config validate
openclaw doctor
```
检查以下内容：
- `Config auto-restored from last-known-good`
- `gateway: invalid config was restored from last-known-good backup`
- `config reload restored last-known-good config after invalid-config`
- 活动配置旁边带时间戳的 `openclaw.json.clobbered.*` 文件
- 以 `Config recovery warning` 开头的主智能体系统事件
发生了什么：
- 被拒绝的配置在启动或热重载期间未通过校验。
- OpenClaw 将被拒绝的负载保留为 `.clobbered.*`。
- 活动配置已从最后一次验证通过的已知正常副本恢复。
- 下一次主智能体轮次会收到警告，不要盲目重写被拒绝的配置。
检查并修复：
```bash
CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor
```
常见特征：
- 存在 `.clobbered.*` → 外部直接编辑或启动时读取的内容已被恢复。
- 存在 `.rejected.*` → OpenClaw 自身的配置写入在提交前未通过 schema 或 clobber 检查。
- `Config write rejected:` → 此次写入尝试删除必需结构、使文件明显缩小，或持久化无效配置。
- `Config last-known-good promotion skipped` → 候选配置包含被脱敏的 secret 占位符，例如 `***`。
修复选项：
1. 如果恢复后的活动配置是正确的，则保留它。
2. 仅从 `.clobbered.*` 或 `.rejected.*` 复制你想要的键，然后使用 `openclaw config set` 或 `config.patch` 应用。
3. 重启前运行 `openclaw config validate`。
4. 如果你手动编辑，请保留完整的 JSON5 配置，而不是只写入你想修改的局部对象。
相关内容：
- [/gateway/configuration#strict-validation](/zh-CN/gateway/configuration#strict-validation)
- [/gateway/configuration#config-hot-reload](/zh-CN/gateway/configuration#config-hot-reload)
- [/cli/config](/cli/config)
- [/gateway/doctor](/zh-CN/gateway/doctor)
## Gateway 网关探测警告
当 `openclaw gateway probe` 探测到了目标，但仍然打印警告块时，使用本节。
当 `openclaw gateway probe` 能探测到目标，但仍然打印警告块时，使用本节。
```bash
openclaw gateway probe
@ -253,14 +310,14 @@ openclaw gateway probe --ssh user@gateway-host
检查以下内容：
- JSON 输出中的 `warnings[].code` 和 `primaryTargetId`。
- 警告是否与 SSH 回退、多个 Gateway 网关、缺失作用域或未解析的认证引用有关。
- 该警告是否与 SSH 回退、多个 Gateway 网关、缺少作用域，或未解析的认证引用有关。
常见特征：
- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍尝试了已配置的 / loopback 目标的直接探测。
- `multiple reachable gateways detected` → 有多个目标作出响应。通常这意味着有意的多 Gateway 网关设置，或存在陈旧 / 重复的监听器。
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功了，但详细 RPC 受作用域限制；请配对设备身份，或使用带有 `operator.read` 的凭证。
- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关已响应，但此客户端在获得正常 operator 访问前仍需要配对 / 批准。
- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍尝试了已配置的 / loopback 直连目标。
- `multiple reachable gateways detected` → 超过一个目标有响应。通常这意味着有意的多 Gateway 网关部署，或存在陈旧 / 重复监听器。
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详细 RPC 受作用域限制；请配对设备身份或使用带有 `operator.read` 的凭证。
- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关已响应，但此客户端在获得正常 operator 访问前仍需完成配对 / 批准。
- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 在此命令路径中，失败目标所需的认证材料不可用。
相关内容：
@ -269,9 +326,9 @@ openclaw gateway probe --ssh user@gateway-host
- [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)
- [/gateway/remote](/zh-CN/gateway/remote)
## 渠道已连接但消息不流转
## 渠道已连接但消息未流动
如果渠道状态显示已连接，但消息流转中断，请重点检查策略、权限和渠道特定的投递规则。
如果渠道状态显示已连接，但消息流已中断，请重点检查策略、权限和渠道特定的投递规则。
```bash
openclaw channels status --probe
@ -285,11 +342,11 @@ openclaw config get channels
- 私信策略（`pairing`、`allowlist`、`open`、`disabled`）。
- 群组 allowlist 和提及要求。
- 缺失的渠道 API 权限 / 作用域。
- 缺失的渠道 API 权限 / scopes。
常见特征：
- `mention required` → 消息因群组提及策略而被忽略。
- `mention required` → 消息被群组提及策略忽略。
- `pairing` / 待批准痕迹 → 发送者尚未获批。
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → 渠道认证 / 权限问题。
@ -300,9 +357,9 @@ openclaw config get channels
- [/channels/telegram](/zh-CN/channels/telegram)
- [/channels/discord](/zh-CN/channels/discord)
## Cron 和心跳投递
## Cron 和 heartbeat 投递
如果 Cron 或心跳未运行，或运行了但未送达，请先验证调度器状态，再检查投递目标。
如果 cron 或 heartbeat 未运行或未成功投递，请先验证调度器状态，再检查投递目标。
```bash
openclaw cron status
@ -316,17 +373,17 @@ openclaw logs --follow
- Cron 已启用，且存在下一次唤醒时间。
- 任务运行历史状态（`ok`、`skipped`、`error`）。
- 心跳跳过原因（`quiet-hours`、`requests-in-flight`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。
- Heartbeat 跳过原因（`quiet-hours`、`requests-in-flight`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。
常见特征：
- `cron: scheduler disabled; jobs will not run automatically` → Cron 已禁用。
- `cron: timer tick failed` → 调度器 tick 失败；检查文件 / 日志 / 运行时错误。
- `heartbeat skipped` 且 `reason=quiet-hours` → 当前处于活跃时间窗口之外。
- `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空行 / Markdown 标题，因此 OpenClaw 会跳过模型调用。
- `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但本次 tick 没有任何任务到期。
- `heartbeat: unknown accountId` → 心跳投递目标使用了无效的 account id。
- `heartbeat skipped` 且 `reason=dm-blocked` → 心跳目标被解析为私信式目标，而 `agents.defaults.heartbeat.directPolicy`（或每个智能体的覆盖项）设置为 `block`。
- `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。
- `cron: timer tick failed` → 调度器 tick 失败；请检查文件 / 日志 / 运行时错误。
- `heartbeat skipped` 且 `reason=quiet-hours` → 当前不在活跃时间窗口内。
- `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空行 / markdown 标题，因此 OpenClaw 会跳过模型调用。
- `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但在本次 tick 中没有任何任务到期。
- `heartbeat: unknown accountId` → heartbeat 投递目标的账号 id 无效。
- `heartbeat skipped` 且 `reason=dm-blocked` → heartbeat 目标被解析为私信式目的地，而 `agents.defaults.heartbeat.directPolicy`（或每个智能体的覆盖设置）被设置为 `block`。
相关内容：
@ -336,7 +393,7 @@ openclaw logs --follow
## 已配对节点的工具失败
如果节点已配对但工具失败，请分别排查前台状态、权限和批准状态。
如果节点已配对，但工具调用失败，请分别排查前台状态、权限和批准状态。
```bash
openclaw nodes status
@ -348,9 +405,9 @@ openclaw status
检查以下内容：
- 节点在线，并具有预期能力。
- 摄像头 / 麦克风 / 位置 / 屏幕的操作系统权限授权。
- exec 批准和 allowlist 状态。
- 节点在线，并具备预期能力。
- 相机 / 麦克风 / 位置 / 屏幕的操作系统权限已授予。
- Exec 批准和 allowlist 状态。
常见特征：
@ -367,7 +424,7 @@ openclaw status
## 浏览器工具失败
当浏览器工具操作失败，但 Gateway 网关本身健康时，使用本节。
当浏览器工具操作失败，但 Gateway 网关本身是健康的时，使用本节。
```bash
openclaw browser status
@ -381,37 +438,37 @@ openclaw doctor
- 是否设置了 `plugins.allow`，且其中包含 `browser`。
- 浏览器可执行文件路径是否有效。
- CDP profile 是否可达。
- 对于 `existing-session` / `user` profiles，本地 Chrome 是否可用。
- CDP 配置文件是否可达。
- `existing-session` / `user` 配置文件所需的本地 Chrome 是否可用。
常见特征：
- `unknown command "browser"` 或 `unknown command 'browser'` → 内置 browser 插件被 `plugins.allow` 排除了。
- 浏览器工具缺失 / 不可用，而 `browser.enabled=true` → `plugins.allow` 排除了 `browser`，因此插件从未加载。
- `unknown command "browser"` 或 `unknown command 'browser'` → 内置 browser 插件被 `plugins.allow` 排除。
- 在 `browser.enabled=true` 时浏览器工具缺失 / 不可用 → `plugins.allow` 排除了 `browser`，因此插件根本没有加载。
- `Failed to start Chrome CDP on port` → 浏览器进程启动失败。
- `browser.executablePath not found` → 配置的路径无效。
- `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的 scheme，例如 `file:` 或 `ftp:`。
- `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口无效或超出范围。
- `No Chrome tabs found for profile="user"` → Chrome MCP 附加 profile 没有打开的本地 Chrome 标签页。
- `Remote CDP for profile "<name>" is not reachable` → 配置的远程 CDP 端点从 Gateway 网关主机不可达。
- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only profile 没有可达目标，或者 HTTP 端点虽然有响应，但 CDP WebSocket 仍无法打开。
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → 当前 Gateway 网关安装不包含完整的 Playwright 包；ARIA 快照和基础页面截图仍然可用，但导航、AI 快照、基于 CSS 选择器的元素截图和 PDF 导出仍不可用。
- `fullPage is not supported for element screenshots` → 截图请求将 `--full-page` 与 `--ref` 或 `--element` 混用。
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` 的截图调用必须使用页面捕获或快照 `--ref`，不能使用 CSS `--element`。
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 上传钩子需要快照引用，不能使用 CSS 选择器。
- `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP profiles 中，每次调用只发送一个上传文件。
- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP profiles 中的对话框钩子不支持超时覆盖。
- `response body is not supported for existing-session profiles yet.` → `responsebody` 目前仍需要托管浏览器或原始 CDP profile。
- attach-only 或远程 CDP profiles 中存在陈旧的 viewport / dark-mode / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile <name>` 关闭当前控制会话并释放 Playwright / CDP 模拟状态，而无需重启整个 Gateway 网关。
- `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的协议，例如 `file:` 或 `ftp:`。
- `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口错误或超出范围。
- `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有找到已打开的本地 Chrome 标签页。
- `Remote CDP for profile "<name>" is not reachable` → 从 Gateway 网关主机无法访问配置的远程 CDP 端点。
- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only 配置文件没有可达目标，或者 HTTP 端点有响应，但 CDP WebSocket 仍无法打开。
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → 当前 Gateway 网关安装不包含完整的 Playwright 包；ARIA 快照和基本页面截图仍可能可用，但导航、AI 快照、基于 CSS 选择器的元素截图和 PDF 导出仍不可用。
- `fullPage is not supported for element screenshots` → 截图请求同时使用了 `--full-page` 和 `--ref` 或 `--element`。
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` 的截图调用必须使用整页捕获或快照 `--ref`，不能使用 CSS `--element`。
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 文件上传钩子需要使用快照引用，而不是 CSS 选择器。
- `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP 配置文件上每次调用只发送一个上传文件。
- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP 配置文件上的对话框处理不支持超时覆盖。
- `response body is not supported for existing-session profiles yet.` → `responsebody` 目前仍需要受管浏览器或原始 CDP 配置文件。
- attach-only 或远程 CDP 配置文件上存在陈旧的 viewport / dark-mode / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile <name>` 以关闭活动控制会话并释放 Playwright / CDP 模拟状态，而无需重启整个 Gateway 网关。
相关内容：
- [/tools/browser-linux-troubleshooting](/zh-CN/tools/browser-linux-troubleshooting)
- [/tools/browser](/zh-CN/tools/browser)
## 如果你升级后突然出问题
## 如果你升级后突然出问题了
大多数升级后的故障都源于配置漂移，或现在开始强制执行更严格的默认值。
大多数升级后的故障都来自配置漂移，或者现在开始强制执行更严格的默认值。
### 1) 认证和 URL 覆盖行为发生了变化
@ -422,10 +479,10 @@ openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
```
要检查的内容：
需要检查：
- 如果 `gateway.mode=remote`，CLI 调用可能会指向远程端，而你的本地服务其实是正常的。
- 显式 `--url` 调用不会回退到已存储凭证。
- 如果 `gateway.mode=remote`，CLI 调用可能正在访问远程目标，而你的本地服务其实是正常的。
- 显式 `--url` 调用不会回退到已存储的凭证。
常见特征：
@ -442,15 +499,15 @@ openclaw gateway status
openclaw logs --follow
```
要检查的内容：
需要检查：
- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享令牌 / 密码认证，或正确配置的非 loopback `trusted-proxy` 部署。
- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享 token / password 认证，或正确配置的非 loopback `trusted-proxy` 部署。
- 像 `gateway.token` 这样的旧键不会替代 `gateway.auth.token`。
常见特征：
- `refusing to bind gateway ... without auth` → 非 loopback 绑定时没有有效的 Gateway 网关认证路径。
- 运行时已启动，但 `Connectivity probe: failed` → Gateway 网关存活，但用当前认证 / URL 无法访问。
- `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径的情况下绑定到非 loopback 地址。
- 运行时已启动但 `Connectivity probe: failed` → Gateway 网关存活，但无法使用当前认证 / URL 访问。
### 3) 配对和设备身份状态发生了变化
@ -461,17 +518,17 @@ openclaw logs --follow
openclaw doctor
```
要检查的内容：
需要检查：
- 仪表板 / 节点是否存在待批准的设备。
- 策略或身份变更后，私信配对是否存在待批准项。
- dashboard / 节点是否有待处理的设备批准。
- 在策略或身份变更后，私信配对批准是否仍待处理。
常见特征：
- `device identity required` → 设备认证未满足。
- `pairing required` → 发送者 / 设备必须先获批。
如果检查后服务配置和运行时仍然不一致，请从相同的 profile / 状态目录重新安装服务元数据：
如果检查后服务配置与运行时仍然不一致，请从同一个 profile / 状态目录重新安装服务元数据：
```bash
openclaw gateway install --force

1996
docs/zh-CN/help/faq.md
View File

File diff suppressed because it is too large Load Diff

136
docs/zh-CN/reference/RELEASING.md
View File

@ -1,141 +1,141 @@
---
read_when:
- 查找公开发布渠道的定义
- 查找公开发布渠道定义
- 查找版本命名和发布节奏
summary: 公开发布渠道、版本命名和发布节奏
title: 发布策略
x-i18n:
generated_at: "2026-04-14T21:23:07Z"
generated_at: "2026-04-20T12:30:01Z"
model: gpt-5.4
provider: openai
source_hash: 88724307269ab783a9fbf8a0540fea198d8a3add68457f4e64d5707114fa518c
source_hash: 1ce04bd255ae5f13ff5088414c87e865fe56a8a0d0bf6ef6d8d84cb07ef65f18
source_path: reference/RELEASING.md
workflow: 15
---
# 发布策略
OpenClaw 有三个公开发布通道：
OpenClaw 有三个公开发布渠道：
- stable：带标签的发布版本，默认发布到 npm `beta`，或在明确指定时发布到 npm `latest`
- stable：带标签的发布版本，默认发布到 npm `beta`，或者在明确指定时发布到 npm `latest`
- beta：预发布标签，发布到 npm `beta`
- dev：`main` 的持续更新头部版本
## 版本命名
- 稳定版发布版本：`YYYY.M.D`
- stable 发布版本：`YYYY.M.D`
- Git 标签：`vYYYY.M.D`
- 稳定版修正版发布版本：`YYYY.M.D-N`
- stable 修正版发布版本：`YYYY.M.D-N`
- Git 标签：`vYYYY.M.D-N`
- Beta 预发布版本：`YYYY.M.D-beta.N`
- beta 预发布版本：`YYYY.M.D-beta.N`
- Git 标签：`vYYYY.M.D-beta.N`
- 月份和日期不要补零
- `latest` 表示当前已提升的稳定 npm 发布版本
- 月份或日期不要补零
- `latest` 表示当前已提升为正式版的 stable npm 发布版本
- `beta` 表示当前 beta 安装目标
- 稳定版和稳定版修正版默认发布到 npm `beta`；发布操作人员可以显式指定为 `latest`，或在后续将经过验证的 beta 构建提升上去
- stable 和 stable 修正版发布默认发布到 npm `beta`；发布操作人员可以明确指定目标为 `latest`，或者之后再提升已验证的 beta 构建版本
- 每个 OpenClaw 发布都会同时交付 npm 包和 macOS 应用
## 发布节奏
- 发布采用 beta 优先的方式推进
- 只有在最新 beta 完成验证后，才会跟进 stable
- 详细的发布流程、审批、凭证和恢复说明仅供维护者查看
- 发布采用 beta 优先流程
- 只有在最新 beta 验证通过后，才会跟进 stable
- 详细发布流程、审批、凭证和恢复说明仅对维护者开放
## 发布前检查
- 在运行 `pnpm release:check` 之前先运行 `pnpm build && pnpm ui:build`，以便为打包验证步骤生成预期的 `dist/*` 发布产物和 Control UI bundle
- 每次带标签发布前都要运行 `pnpm release:check`
- 发布检查现在在单独的手动工作流中运行：
- 在进行发布前检查之前运行 `pnpm check:architecture`，以确保更全面的导入环和架构边界检查在更快的本地 gate 之外也是绿色状态
- 在运行 `pnpm release:check` 之前运行 `pnpm build && pnpm ui:build`，以确保打包验证步骤所需的 `dist/*` 发布产物和 Control UI bundle 已存在
- 每次带标签的发布之前都要运行 `pnpm release:check`
- 发布检查现在在一个独立的手动工作流中运行：
`OpenClaw Release Checks`
- 跨操作系统的安装与升级运行时验证由私有调用方工作流触发：
- 跨操作系统的安装和升级运行时验证由私有调用方工作流分发：
`openclaw/releases-private/.github/workflows/openclaw-cross-os-release-checks.yml`，
它会调用可复用的公开工作流
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- 这种拆分是有意为之：让真正的 npm 发布路径保持简短、可预测且以产物为中心，而较慢的在线检查保留在独立通道中，这样它们不会拖慢或阻塞发布
- 发布检查必须从 `main` 工作流引用触发，以确保工作流逻辑和密钥保持规范一致
- 该工作流接受现有发布标签，或者当前完整的 40 字符 `main` 提交 SHA
- 在提交 SHA 模式下，它只接受当前 `origin/main` 的 HEAD；较旧的发布提交必须使用发布标签
- `OpenClaw NPM Release` 的仅验证预检查也接受当前完整的 40 字符 `main` 提交 SHA，而不要求已推送的标签
- 这种拆分是有意的：让真正的 npm 发布路径保持简短、确定性强且聚焦产物，同时将较慢的实时检查保留在独立渠道中，这样它们不会拖慢或阻塞发布
- 发布检查必须从 `main` 工作流 ref 发起，这样工作流逻辑和 secrets 才能保持为规范来源
- 该工作流接受现有发布标签，或当前完整的 40 字符 `main` commit SHA
- 在 commit SHA 模式下，它只接受当前 `origin/main` HEAD；较早的发布提交请使用发布标签
- `OpenClaw NPM Release` 的仅验证预检查也接受当前完整的 40 字符 `main` commit SHA，而无需已推送的标签
- 该 SHA 路径仅用于验证，不能提升为真实发布
- 在 SHA 模式下，工作流仅为包元数据检查合成 `v<package.json version>`；真实发布仍然需要真实的发布标签
- 两个工作流都将真实发布与提升路径保留在 GitHub 托管 runner 上，而非变更性的验证路径则可以使用更大的 Blacksmith Linux runner
- 两个工作流都会将真实发布和提升路径保留在 GitHub-hosted runners 上，而非变更型验证路径则可以使用更大的 Blacksmith Linux runners
- 该工作流会运行
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
并使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 两个工作流密钥
- npm 发布预检查不再等待独立的发布检查通道完成
- 在审批前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
（或对应的 beta/修正标签）
并使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 两个工作流 secret
- npm 发布前检查不再等待独立的发布检查渠道完成
- 在审批之前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
（或对应的 beta/修正版标签）
- npm 发布后，运行
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
（或对应的 beta/修正版本），以在全新的临时前缀目录中验证已发布注册表安装路径
- 维护者发布自动化现在采用“先预检查再提升”的方式：
- 真实的 npm 发布必须通过成功的 npm `preflight_run_id`
- 稳定版 npm 发布默认使用 `beta`
- 稳定版 npm 发布可以通过工作流输入显式指定为 `latest`
- 基于令牌的 npm dist-tag 变更现在位于
（或对应的 beta/修正版版本），以在全新的临时前缀中验证已发布的 registry 安装路径
- 维护者发布自动化现在使用“先预检查再提升”的流程：
- 真实 npm 发布必须通过成功的 npm `preflight_run_id`
- stable npm 发布默认目标为 `beta`
- stable npm 发布可以通过工作流输入明确指定目标为 `latest`
- 基于 token 的 npm dist-tag 变更现在位于
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
以提升安全性，因为 `npm dist-tag add` 仍然需要 `NPM_TOKEN`，而公开仓库保留仅使用 OIDC 的发布方式
以增强安全性，因为 `npm dist-tag add` 仍然需要 `NPM_TOKEN`，而公开仓库保留仅使用 OIDC 的发布方式
- 公开的 `macOS Release` 仅用于验证
- 真实的私有 mac 发布必须通过成功的私有 mac
`preflight_run_id` 和 `validate_run_id`
- 真实发布路径会提升已准备好的产物，而不是再次重新构建它们
- 对于 `YYYY.M.D-N` 这类稳定版修正版发布，发布后验证器还会检查从 `YYYY.M.D` 升级到 `YYYY.M.D-N` 的同一临时前缀路径，以确保发布修正不会悄悄让较旧的全局安装继续停留在基础稳定版内容上
- npm 发布预检查默认采用失败即关闭的策略，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` 内容，否则不会通过，这样可以避免再次发布一个空的浏览器仪表盘
- `pnpm test:install:smoke` 还会对候选更新 tarball 的 npm pack `unpackedSize` 预算进行强制检查，因此安装器 e2e 可以在发布路径之前捕获意外的打包膨胀
- 如果发布工作涉及 CI 规划、扩展时序清单或扩展测试矩阵，请在审批前重新生成并审查来自 `.github/workflows/ci.yml` 的、由规划器维护的 `checks-node-extensions` 工作流矩阵输出，以免发布说明描述的是过时的 CI 布局
- 稳定版 macOS 发布就绪还包括更新器相关界面：
- 对于像 `YYYY.M.D-N` 这样的 stable 修正版发布，发布后验证器还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的相同临时前缀升级路径，以确保发布修正不会悄悄让旧的全局安装仍停留在基础 stable 载荷上
- npm 发布前检查默认失败关闭，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` 内容，这样我们就不会再次发布一个空的浏览器仪表板
- `pnpm test:install:smoke` 也会对候选更新 tarball 的 npm pack `unpackedSize` 预算进行强制检查，因此安装器 e2e 可以在发布路径之前捕获意外的打包膨胀
- 如果发布工作涉及 CI 规划、扩展时序清单或扩展测试矩阵，请在审批前重新生成并审查来自 `.github/workflows/ci.yml` 的、由 planner 管理的 `checks-node-extensions` 工作流矩阵输出，以免发布说明描述过时的 CI 布局
- stable macOS 发布就绪性还包括更新器相关表面：
- GitHub 发布最终必须包含打包后的 `.zip`、`.dmg` 和 `.dSYM.zip`
- 发布后，`main` 上的 `appcast.xml` 必须指向新的稳定版 zip
- 打包后的应用必须保持非调试 bundle id、非空的 Sparkle feed URL，以及不低于该发布版本规范 Sparkle 构建下限的 `CFBundleVersion`
- 发布后，`main` 上的 `appcast.xml` 必须指向新的 stable zip
- 打包后的应用必须保持非调试 bundle id、非空的 Sparkle feed URL，以及不低于该发布版本规范 Sparkle build floor 的 `CFBundleVersion`
## NPM 工作流输入
`OpenClaw NPM Release` 接受以下由操作人员控制的输入：
- `tag`：必填的发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或
`v2026.4.2-beta.1`；当 `preflight_only=true` 时，也可以是当前
完整的 40 字符 `main` 提交 SHA，用于仅验证的预检查
- `preflight_only`：`true` 表示仅进行验证/构建/打包，`false` 表示
真实发布路径
- `tag`：必填发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或
`v2026.4.2-beta.1`；当 `preflight_only=true` 时，也可以是当前完整的
40 字符 `main` commit SHA，用于仅验证的预检查
- `preflight_only`：`true` 表示仅进行验证/构建/打包，`false` 表示执行真实发布路径
- `preflight_run_id`：在真实发布路径中必填，以便工作流复用成功预检查运行中准备好的 tarball
- `npm_dist_tag`：发布路径的 npm 目标标签；默认为 `beta`
- `npm_dist_tag`：发布路径的 npm 目标标签；默认值为 `beta`
`OpenClaw Release Checks` 接受以下由操作人员控制的输入：
- `ref`：用于验证的现有发布标签，或当前完整的 40 字符 `main` 提交
- `ref`：用于验证的现有发布标签，或当前完整的 40 字符 `main` commit
SHA
规则：
- 稳定版和修正版标签可以发布到 `beta` 或 `latest`
- Beta 预发布标签只能发布到 `beta`
- 仅当 `preflight_only=true` 时才允许使用完整提交 SHA 输入
- 发布检查的提交 SHA 模式还要求必须是当前 `origin/main` 的 HEAD
- Stable 和修正版标签可以发布到 `beta` 或 `latest`
- beta 预发布标签只能发布到 `beta`
- 只有在 `preflight_only=true` 时才允许使用完整 commit SHA 输入
- 发布检查的 commit SHA 模式还要求输入当前 `origin/main` HEAD
- 真实发布路径必须使用与预检查相同的 `npm_dist_tag`；工作流会在继续发布前验证该元数据
## 稳定版 npm 发布顺序
## Stable npm 发布顺序
在发布稳定版 npm 版本时：
在进行 stable npm 发布时：
1. 运行 `OpenClaw NPM Release`，设置 `preflight_only=true`
- 在标签尚不存在之前，你可以使用当前完整的 `main` 提交 SHA 对预检查工作流进行一次仅验证的预演
2. 在正常的 beta 优先流程中选择 `npm_dist_tag=beta`，只有当你明确想直接发布稳定版时才使用 `latest`
3. 单独运行 `OpenClaw Release Checks`，使用相同的标签，或者在你需要在线 prompt cache 覆盖验证时使用当前完整的 `main` 提交 SHA
- 这样刻意分离，是为了让在线覆盖检查在可用的同时，不再把长时间运行或不稳定的检查重新耦合到发布工作流中
1. 运行 `OpenClaw NPM Release`，并设置 `preflight_only=true`
- 在标签尚不存在之前，你可以使用当前完整的 `main` commit SHA，对预检查工作流进行一次仅验证的演练
2. 对于正常的 beta 优先流程，选择 `npm_dist_tag=beta`；只有在你有意直接发布 stable 时才选择 `latest`
3. 单独运行 `OpenClaw Release Checks`，使用相同的标签，或者在你想要实时 prompt cache 覆盖时使用当前完整的 `main` commit SHA
- 这样刻意分离，是为了让实时覆盖保持可用，而不会再次将长时间运行或可能不稳定的检查与发布工作流重新耦合
4. 保存成功的 `preflight_run_id`
5. 再次运行 `OpenClaw NPM Release`，设置 `preflight_only=false`，并使用相同的 `tag`、相同的 `npm_dist_tag` 以及保存的 `preflight_run_id`
6. 如果该发布先落在 `beta`，使用私有
5. 再次运行 `OpenClaw NPM Release`，并设置 `preflight_only=false`，同时使用相同的 `tag`、相同的 `npm_dist_tag` 和已保存的 `preflight_run_id`
6. 如果该发布落在 `beta`，使用私有工作流
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
工作流将该稳定版从 `beta` 提升到 `latest`
7. 如果该发布是有意直接发布到 `latest`，并且 `beta`
也应立即跟进同一个稳定构建，则使用同一个私有工作流将两个 dist-tag 都指向该稳定版本，或者让其计划中的自愈同步稍后再移动 `beta`
将该 stable 版本从 `beta` 提升到 `latest`
7. 如果该发布有意直接发布到 `latest`，并且 `beta`
也应立即跟进同一 stable 构建，请使用同一个私有工作流将两个 dist-tag 都指向该 stable 版本，或者让其计划中的自愈同步稍后再移动 `beta`
dist-tag 变更位于私有仓库中以提升安全性，因为它仍然需要
dist-tag 变更位于私有仓库中以增强安全性，因为它仍然需要
`NPM_TOKEN`，而公开仓库保留仅使用 OIDC 的发布方式。
这样既记录了直接发布路径，也记录了 beta 优先的提升路径，并且两者对操作人员都清晰可见。
这样既让直接发布路径有文档记录，也让 beta 优先的提升路径同样清晰且对操作人员可见。
## 公开参考
## 公开参考资料
- [`.github/workflows/openclaw-npm-release.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-npm-release.yml)
- [`.github/workflows/openclaw-release-checks.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-release-checks.yml)