diff --git a/docs/zh-CN/gateway/configuration.md b/docs/zh-CN/gateway/configuration.md index a3c245ad4..ca3c2c847 100644 --- a/docs/zh-CN/gateway/configuration.md +++ b/docs/zh-CN/gateway/configuration.md @@ -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` 读取一个可选的 **JSON5** 配置。 +OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 **JSON5** 配置。 -如果该文件缺失，OpenClaw 会使用安全的默认值。常见的添加配置原因包括： +如果该文件缺失，OpenClaw 会使用安全的默认值。添加配置的常见原因包括： -- 连接渠道并控制谁可以给机器人发送消息 +- 连接渠道并控制谁可以向机器人发送消息 - 设置模型、工具、沙箱隔离或自动化（cron、hooks） - 调整会话、媒体、网络或 UI -请参阅[完整参考](/zh-CN/gateway/configuration-reference)以了解每个可用字段。 +查看[完整参考](/zh-CN/gateway/configuration-reference)以了解每个可用字段。 -**刚开始接触配置？** 从 `openclaw onboard` 开始进行交互式设置，或查看[配置示例](/zh-CN/gateway/configuration-examples)指南以获取可直接复制粘贴的完整配置。 +**刚开始接触配置？** 先运行 `openclaw onboard` 进行交互式设置，或查看[配置示例](/zh-CN/gateway/configuration-examples)指南，获取可直接复制粘贴的完整配置。 ## 最小配置 @@ -45,8 +45,8 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 ```bash - openclaw onboard # full onboarding flow - openclaw configure # config wizard + openclaw onboard # 完整的新手引导流程 + openclaw configure # 配置向导 ``` @@ -57,57 +57,67 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 - 打开 [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 节点及其直接子项摘要。 - 直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。 + 直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关 会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。 ## 严格校验 -OpenClaw 仅接受与 schema 完全匹配的配置。未知键名、格式错误的类型或无效值都会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器就可以附加 JSON Schema 元数据。 +OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的类型或无效值都会导致 Gateway 网关 **拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器就可以附加 JSON Schema 元数据。 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 值，则会跳过提升。 ## 常见任务 - - 每个渠道在 `channels.` 下都有自己的配置区段。请查看对应渠道页面了解设置步骤： + + 每个渠道在 `channels.` 下都有自己的配置部分。设置步骤请参阅对应的专用渠道页面： - [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)。 - - 私信访问通过每个渠道的 `dmPolicy` 进行控制： + + 私信访问通过每个渠道的 `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)以了解每个渠道的详细信息。 - 群组消息默认是**需要提及**。可按智能体配置模式： + 群消息默认 **需要提及**。可按智能体配置模式： ```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)。 - 使用 `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)。 - - 控制 Gateway 网关对看起来已停滞渠道的重启激进程度： + + 控制 Gateway 网关 对看起来已失活的渠道进行重启的激进程度： ```json5 { @@ -258,10 +268,10 @@ Schema 工具说明： } ``` - - 将 `gateway.channelHealthCheckMinutes: 0` 设为全局禁用健康监控重启。 + - 设置 `gateway.channelHealthCheckMinutes: 0` 以全局禁用健康监控重启。 - `channelStaleEventThresholdMinutes` 应大于或等于检查间隔。 - - 使用 `channels..healthMonitor.enabled` 或 `channels..accounts..healthMonitor.enabled` 可为单个渠道或账户禁用自动重启，而无需禁用全局监控。 - - 请参阅[健康检查](/zh-CN/gateway/health)了解运维调试信息，并参阅[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。 + - 使用 `channels..healthMonitor.enabled` 或 `channels..accounts..healthMonitor.enabled`，可为单个渠道或账户禁用自动重启，而无需禁用全局监控。 + - 参见[健康检查](/zh-CN/gateway/health)了解运维调试信息，参见[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。 @@ -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)了解所有字段。 @@ -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)了解所有选项。 基于 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 安全模型。 @@ -386,10 +396,10 @@ Schema 工具说明： } ``` - - `every`：时长字符串（`30m`、`2h`）。设为 `0m` 可禁用。 + - `every`：时长字符串（`30m`、`2h`）。设置为 `0m` 可禁用。 - `target`：`last` | `none` | ``（例如 `discord`、`matrix`、`telegram` 或 `whatsapp`） - - `directPolicy`：用于私信式心跳目标的 `allow`（默认）或 `block` - - 请参阅[心跳](/zh-CN/gateway/heartbeat)了解完整指南。 + - `directPolicy`：对于私信式心跳目标，可设为 `allow`（默认）或 `block` + - 完整指南参见[心跳](/zh-CN/gateway/heartbeat)。 @@ -408,14 +418,14 @@ Schema 工具说明： } ``` - - `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设为 `false` 可禁用）。 + - `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设置为 `false` 可禁用）。 - `runLog`：按大小和保留行数清理 `cron/runs/.jsonl`。 - - 请参阅 [Cron jobs](/zh-CN/automation/cron-jobs) 了解功能概览和 CLI 示例。 + - 功能概览和 CLI 示例参见 [Cron jobs](/zh-CN/automation/cron-jobs)。 - 在 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 集成。 - 使用单独的工作区和会话运行多个隔离智能体： + 运行多个彼此隔离的智能体，并使用各自独立的工作区和会话： ```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)了解绑定规则和每个智能体的访问配置文件。 @@ -489,26 +499,38 @@ Schema 工具说明： - **单个文件**：替换包含它的对象 - **文件数组**：按顺序深度合并（后者优先） - - **同级键**：在 include 之后合并（覆盖 include 中的值） - - **嵌套 include**：支持，最多 10 层 + - **同级键名**：在 include 之后合并（覆盖被包含的值） + - **嵌套 include**：最多支持 10 层嵌套 - **相对路径**：相对于包含它的文件解析 - - **错误处理**：对缺失文件、解析错误和循环 include 提供清晰错误信息 + - **错误处理**：对于缺失文件、解析错误和循环 include，都会提供清晰错误信息 ## 配置热重载 -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` | **是** | -`gateway.reload` 和 `gateway.remote` 是例外——更改它们**不会**触发重启。 +`gateway.reload` 和 `gateway.remote` 是例外——更改它们 **不会** 触发重启。 ## 配置 RPC（程序化更新） -控制平面写入 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`。 -安全/默认流程： +安全 / 默认流程： -- `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`。 - 在一步内校验并写入完整配置，同时重启 Gateway 网关。 + 校验 + 写入完整配置，并在一步中重启 Gateway 网关。 - `config.apply` 会替换**整个配置**。部分更新请使用 `config.patch`，单个键请使用 `openclaw config set`。 + `config.apply` 会替换**整个配置**。部分更新请使用 `config.patch`，单个键名请使用 `openclaw config set`。 参数： - `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` 并自动应用更改—— 将部分更新合并到现有配置中（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 会从父进程读取环境变量，另外还会读取： } ``` - - 如果启用且预期键名尚未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键名： + + 如果已启用，并且预期键名尚未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键名： ```json5 { @@ -638,11 +660,11 @@ OpenClaw 会从父进程读取环境变量，另外还会读取： } ``` -环境变量等价形式：`OPENCLAW_LOAD_SHELL_ENV=1` +环境变量等效项：`OPENCLAW_LOAD_SHELL_ENV=1` - 你可以在任意配置字符串值中使用 `${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) 中。 -请参阅[环境](/zh-CN/help/environment)了解完整的优先级和来源。 +完整优先级和来源请参见[环境](/zh-CN/help/environment)。 ## 完整参考 -如需完整的逐字段参考，请参阅 **[配置参考](/zh-CN/gateway/configuration-reference)**。 +如需逐字段的完整参考，请参见 **[配置参考](/zh-CN/gateway/configuration-reference)**。 --- diff --git a/docs/zh-CN/gateway/troubleshooting.md b/docs/zh-CN/gateway/troubleshooting.md index add6fd001..428ebbad0 100644 --- a/docs/zh-CN/gateway/troubleshooting.md +++ b/docs/zh-CN/gateway/troubleshooting.md @@ -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..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 `。作用域 / 角色升级在你审查所请求的访问权限后也使用相同流程。 | +| 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 `。在你审核所请求的访问权限后，作用域 / 角色升级也使用相同流程。 | 设备认证 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 "" 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; '' 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 ` 关闭当前控制会话并释放 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 "" 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; '' 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 ` 以关闭活动控制会话并释放 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 diff --git a/docs/zh-CN/help/faq.md b/docs/zh-CN/help/faq.md index f0e43fa69..e11988ccd 100644 --- a/docs/zh-CN/help/faq.md +++ b/docs/zh-CN/help/faq.md @@ -1,31 +1,31 @@ --- read_when: - 解答常见的设置、安装、新手引导或运行时支持问题 - - 在深入调试之前，对用户报告的问题进行初步分诊 + - 在进行更深入的调试之前，对用户报告的问题进行初步分类和判断 summary: 关于 OpenClaw 设置、配置和使用的常见问题 title: 常见问题 x-i18n: - generated_at: "2026-04-20T06:31:00Z" + generated_at: "2026-04-20T12:30:04Z" model: gpt-5.4 provider: openai - source_hash: ae8efda399e34f59f22f6ea8ce218eaf7b872e4117d8596ec19c09891d70813b + source_hash: b9441a569bade4b862b115df0537183473b457470218e9b3e18539d503318f13 source_path: help/faq.md workflow: 15 --- # 常见问题 -针对真实环境设置的快速解答和更深入的故障排除（本地开发、VPS、多智能体、OAuth/API 密钥、模型故障切换）。如需运行时诊断，请参阅 [故障排除](/zh-CN/gateway/troubleshooting)。如需完整的配置参考，请参阅 [Configuration](/zh-CN/gateway/configuration)。 +为真实世界的部署提供快速解答，并深入介绍故障排除（本地开发、VPS、多智能体、OAuth/API 密钥、模型故障切换）。如需运行时诊断，请参阅 [故障排除](/zh-CN/gateway/troubleshooting)。如需完整的配置参考，请参阅 [Configuration](/zh-CN/gateway/configuration)。 -## 如果出现问题，最初的六十秒 +## 最初的六十秒：如果有东西坏了 -1. **快速状态（首次检查）** +1. **快速状态（第一项检查）** ```bash openclaw status ``` - 快速的本地摘要：操作系统 + 更新、Gateway 网关 / 服务可达性、智能体 / 会话、提供商配置 + 运行时问题（当 Gateway 网关 可达时）。 + 快速本地摘要：操作系统 + 更新、Gateway 网关/服务可达性、智能体/会话、提供商配置 + 运行时问题（当 Gateway 网关可达时）。 2. **可粘贴的报告（可安全分享）** @@ -33,7 +33,7 @@ x-i18n: openclaw status --all ``` - 只读诊断，附带日志尾部（令牌已脱敏）。 + 只读诊断，包含日志尾部（令牌已脱敏）。 3. **守护进程 + 端口状态** @@ -49,16 +49,16 @@ x-i18n: openclaw status --deep ``` - 运行实时的 Gateway 网关 健康探测，包括支持时的渠道探测 - （需要 Gateway 网关 可达）。请参阅 [Health](/zh-CN/gateway/health)。 + 运行实时 Gateway 网关健康探测，在支持时也包括渠道探测 + （需要可访问的 Gateway 网关）。请参阅 [Health](/zh-CN/gateway/health)。 -5. **跟踪最新日志** +5. **查看最新日志尾部** ```bash openclaw logs --follow ``` - 如果 RPC 不可用，则退回到： + 如果 RPC 不可用，则回退到： ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" @@ -72,48 +72,47 @@ x-i18n: openclaw doctor ``` - 修复 / 迁移配置与状态 + 运行健康检查。请参阅 [Doctor](/zh-CN/gateway/doctor)。 + 修复/迁移配置和状态 + 运行健康检查。请参阅 [Doctor](/zh-CN/gateway/doctor)。 -7. **Gateway 网关 快照** +7. **Gateway 网关快照** ```bash openclaw health --json openclaw health --verbose # shows the target URL + config path on errors ``` - 向正在运行的 Gateway 网关 请求完整快照（仅 WS）。请参阅 [Health](/zh-CN/gateway/health)。 + 向正在运行的 Gateway 网关请求完整快照（仅 WS）。请参阅 [Health](/zh-CN/gateway/health)。 ## 快速开始和首次运行设置 - + 使用一个能够**看到你的机器**的本地 AI 智能体。这比在 Discord 里提问有效得多， - 因为大多数“我卡住了”的情况其实都是**本地配置或环境问题**， + 因为大多数“我卡住了”的情况都是**本地配置或环境问题**， 远程协助者无法直接检查。 - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) - 这些工具可以读取仓库、运行命令、检查日志，并帮助修复你机器级别的 - 设置问题（PATH、服务、权限、认证文件）。通过可修改的（git）安装方式， - 把**完整的源代码检出**提供给它们： + 这些工具可以读取仓库、运行命令、检查日志，并帮助修复你的机器级设置 + （PATH、服务、权限、凭证文件）。通过可修改的（git）安装方式向它们提供**完整源码检出**： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - 这会**从一个 git 检出版本**安装 OpenClaw，因此智能体可以读取代码 + 文档， - 并基于你正在运行的确切版本进行推理。之后你随时都可以通过不带 - `--install-method git` 重新运行安装器，切换回稳定版。 + 这会**从 git 检出**安装 OpenClaw，因此智能体可以读取代码 + 文档，并 + 针对你当前运行的精确版本进行推理。你之后随时可以通过重新运行安装器并去掉 `--install-method git` + 切回稳定版。 - 提示：让智能体先**规划并监督**修复过程（逐步进行），然后只执行 - 必要的命令。这样改动会更少，也更容易审计。 + 提示：让智能体先**规划并监督**修复过程（分步进行），然后只执行 + 必要的命令。这样可以让变更保持较小，也更容易审计。 如果你发现了真实的 bug 或修复，请提交 GitHub issue 或发送 PR： [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) - 先从这些命令开始（在寻求帮助时分享输出）： + 从这些命令开始（在请求帮助时分享输出）： ```bash openclaw status @@ -123,14 +122,14 @@ x-i18n: 它们的作用： - - `openclaw status`：快速查看 Gateway 网关 / 智能体健康状态 + 基本配置。 - - `openclaw models status`：检查提供商认证 + 模型可用性。 - - `openclaw doctor`：验证并修复常见的配置 / 状态问题。 + - `openclaw status`：快速查看 Gateway 网关/智能体健康状态 + 基本配置。 + - `openclaw models status`：检查提供商凭证 + 模型可用性。 + - `openclaw doctor`：验证并修复常见的配置/状态问题。 其他有用的 CLI 检查：`openclaw status --all`、`openclaw logs --follow`、 `openclaw gateway status`、`openclaw health --verbose`。 - 快速调试循环：[如果出现问题，最初的六十秒](#first-60-seconds-if-something-is-broken)。 + 快速调试循环：[最初的六十秒：如果有东西坏了](#最初的六十秒如果有东西坏了)。 安装文档：[Install](/zh-CN/install)、[Installer flags](/zh-CN/install/installer)、[Updating](/zh-CN/install/updating)。 @@ -138,29 +137,29 @@ x-i18n: 常见的 Heartbeat 跳过原因： - - `quiet-hours`：不在已配置的 active-hours 时间窗口内 - - `empty-heartbeat-file`：`HEARTBEAT.md` 存在，但只包含空白 / 仅标题的脚手架内容 - - `no-tasks-due`：`HEARTBEAT.md` 任务模式已启用，但还没有任何任务间隔到期 + - `quiet-hours`：不在已配置的活跃时间窗口内 + - `empty-heartbeat-file`：`HEARTBEAT.md` 存在，但只包含空白/仅标题的脚手架内容 + - `no-tasks-due`：`HEARTBEAT.md` 任务模式已启用，但尚未到任何任务间隔的执行时间 - `alerts-disabled`：所有 Heartbeat 可见性都已禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭） - 在任务模式下，只有在真正的 Heartbeat 运行 - 完成后，才会推进到期时间戳。被跳过的运行不会将任务标记为已完成。 + 在任务模式下，只有在真实的 Heartbeat 运行 + 完成后，待执行时间戳才会推进。被跳过的运行不会将任务标记为已完成。 文档：[Heartbeat](/zh-CN/gateway/heartbeat)、[Automation & Tasks](/zh-CN/automation)。 - 仓库建议从源码运行，并使用新手引导： + 仓库推荐从源码运行，并使用新手引导： ```bash curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard --install-daemon ``` - 向导也可以自动构建 UI 资源。完成新手引导后，你通常会在 **18789** 端口运行 Gateway 网关。 + 该向导还可以自动构建 UI 资源。完成新手引导后，你通常会在 **18789** 端口运行 Gateway 网关。 - 从源码开始（贡献者 / 开发者）： + 从源码运行（贡献者/开发者）： ```bash git clone https://github.com/openclaw/openclaw.git @@ -175,28 +174,28 @@ x-i18n: - - 向导会在新手引导完成后立即用浏览器打开一个干净的（不带令牌的）仪表板 URL，并且也会在摘要中打印该链接。请保持该标签页打开；如果没有自动启动，就在同一台机器上复制 / 粘贴打印出来的 URL。 + + 向导会在新手引导结束后立即用浏览器打开一个干净的（不带令牌的）仪表板 URL，并且也会在摘要中打印该链接。请保持该标签页打开；如果没有自动启动，请在同一台机器上复制/粘贴打印出的 URL。 - - **Localhost（同一台机器）：** + + **localhost（同一台机器）：** - 打开 `http://127.0.0.1:18789/`。 - - 如果它要求 shared-secret 认证，请把已配置的令牌或密码粘贴到 Control UI 设置中。 - - 令牌来源：`gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）。 + - 如果它要求 shared-secret 身份验证，请将已配置的 token 或密码粘贴到 Control UI 设置中。 + - token 来源：`gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）。 - 密码来源：`gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 - - 如果还没有配置 shared secret，请使用 `openclaw doctor --generate-gateway-token` 生成令牌。 + - 如果还没有配置 shared secret，可使用 `openclaw doctor --generate-gateway-token` 生成一个 token。 - **不在 localhost 上：** + **不在 localhost：** - - **Tailscale Serve**（推荐）：保持 bind loopback，运行 `openclaw gateway --tailscale serve`，打开 `https:///`。如果 `gateway.auth.allowTailscale` 为 `true`，身份标头会满足 Control UI/WebSocket 认证（无需粘贴 shared secret，前提是假定 Gateway 网关 主机可信）；HTTP API 仍然需要 shared-secret 认证，除非你有意使用 private-ingress `none` 或 trusted-proxy HTTP 认证。 - 来自同一客户端的错误并发 Serve 认证尝试，会在失败认证限流器记录之前被串行化，因此第二次错误重试就可能已经显示 `retry later`。 - - **Tailnet 绑定**：运行 `openclaw gateway --bind tailnet --token ""`（或配置密码认证），打开 `http://:18789/`，然后在仪表板设置中粘贴匹配的 shared secret。 - - **支持身份感知的反向代理**：将 Gateway 网关 保持在非 loopback 的 trusted proxy 后面，配置 `gateway.auth.mode: "trusted-proxy"`，然后打开代理 URL。 - - **SSH 隧道**：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。shared-secret 认证在隧道上仍然适用；如果出现提示，请粘贴已配置的令牌或密码。 + - **Tailscale Serve**（推荐）：保持绑定到 loopback，运行 `openclaw gateway --tailscale serve`，打开 `https:///`。如果 `gateway.auth.allowTailscale` 为 `true`，身份标头可以满足 Control UI/WebSocket 身份验证（无需粘贴 shared secret，假定 Gateway 网关主机可信）；HTTP API 仍然需要 shared-secret 身份验证，除非你明确使用 private-ingress `none` 或 trusted-proxy HTTP 身份验证。 + 来自同一客户端的错误并发 Serve 身份验证尝试会在 failed-auth limiter 记录之前被串行化，因此第二次错误重试可能已经显示 `retry later`。 + - **Tailnet bind**：运行 `openclaw gateway --bind tailnet --token ""`（或配置密码身份验证），打开 `http://:18789/`，然后在仪表板设置中粘贴匹配的 shared secret。 + - **支持身份感知的反向代理**：将 Gateway 网关放在非 loopback 的 trusted proxy 后面，配置 `gateway.auth.mode: "trusted-proxy"`，然后打开该代理 URL。 + - **SSH 隧道**：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。即使通过隧道，shared-secret 身份验证仍然适用；如果出现提示，请粘贴已配置的 token 或密码。 - 有关 bind 模式和认证细节，请参阅 [Dashboard](/web/dashboard) 和 [Web surfaces](/web)。 + 有关绑定模式和身份验证详情，请参阅 [Dashboard](/web/dashboard) 和 [Web surfaces](/web)。 @@ -206,55 +205,55 @@ x-i18n: - `approvals.exec`：将审批提示转发到聊天目标 - `channels..execApprovals`：让该渠道作为 exec 审批的原生审批客户端 - 主机的 exec 策略仍然是真正的审批门控。聊天配置只控制审批提示出现在哪里， - 以及人们如何进行回应。 + 主机 exec 策略仍然是真正的审批关卡。聊天配置只控制审批 + 提示出现在哪里，以及人们如何进行回应。 - 在大多数设置中，你**不需要**同时启用两者： + 在大多数部署中，你**不**需要同时使用这两者： - - 如果聊天已经支持命令和回复，那么同一聊天中的 `/approve` 会通过共享路径工作。 - - 如果受支持的原生渠道能够安全地推断审批人，OpenClaw 现在会在 `channels..execApprovals.enabled` 未设置或为 `"auto"` 时，自动启用私信优先的原生审批。 - - 当原生审批卡片 / 按钮可用时，该原生 UI 是主要路径；只有在工具结果说明聊天审批不可用，或手动审批是唯一途径时，智能体才应包含手动 `/approve` 命令。 - - 仅当提示还必须被转发到其他聊天或明确的运维房间时，才使用 `approvals.exec`。 - - 仅当你明确希望将审批提示也发回发起来源的房间 / 话题时，才使用 `channels..execApprovals.target: "channel"` 或 `"both"`。 - - 插件审批则是另一套机制：默认使用同一聊天中的 `/approve`，可选使用 `approvals.plugin` 转发，并且只有部分原生渠道会额外保留原生插件审批处理。 + - 如果聊天已支持命令和回复，同一聊天中的 `/approve` 会通过共享路径生效。 + - 如果受支持的原生渠道能够安全推断审批人，当 `channels..execApprovals.enabled` 未设置或为 `"auto"` 时，OpenClaw 现在会自动启用私信优先的原生审批。 + - 当原生审批卡片/按钮可用时，该原生 UI 是主要路径；只有当工具结果表明聊天审批不可用，或手动审批是唯一方式时，智能体才应包含手动 `/approve` 命令。 + - 只有当提示还必须转发到其他聊天或明确的运维房间时，才使用 `approvals.exec`。 + - 只有当你明确希望将审批提示发回原始房间/话题时，才使用 `channels..execApprovals.target: "channel"` 或 `"both"`。 + - 插件审批则是另一个独立体系：默认使用同一聊天中的 `/approve`，可选 `approvals.plugin` 转发，并且只有部分原生渠道会在此基础上继续提供原生插件审批处理。 - 简而言之：转发用于路由，原生客户端配置用于更丰富的渠道特定 UX。 + 简而言之：转发用于路由，原生客户端配置用于提供更丰富的特定渠道 UX。 请参阅 [Exec Approvals](/zh-CN/tools/exec-approvals)。 - 需要 Node **>= 22**。推荐使用 `pnpm`。Gateway 网关 **不推荐**使用 Bun。 + 需要 Node **>= 22**。推荐使用 `pnpm`。**不推荐**将 Bun 用于 Gateway 网关。 - 可以。Gateway 网关 很轻量——文档中说明个人使用时，**512MB-1GB RAM**、**1 个核心**以及大约 **500MB** - 磁盘空间就足够了，并指出 **Raspberry Pi 4 可以运行它**。 + 可以。Gateway 网关很轻量——文档中写明个人使用只需 **512MB-1GB RAM**、**1 个核心** 和大约 **500MB** + 磁盘空间，并说明 **Raspberry Pi 4 可以运行它**。 - 如果你想保留更多余量（日志、媒体、其他服务），**推荐 2GB**，但这 - 不是硬性最低要求。 + 如果你希望留出更多余量（日志、媒体、其他服务），推荐使用 **2GB**， + 但这不是硬性最低要求。 - 提示：小型 Pi/VPS 可以托管 Gateway 网关，而你可以在笔记本电脑 / 手机上配对**节点**，用于 - 本地屏幕 / 摄像头 / 画布或命令执行。请参阅 [Nodes](/zh-CN/nodes)。 + 提示：一台小型 Pi/VPS 可以托管 Gateway 网关，而你可以在笔记本电脑/手机上配对**节点**，以获得 + 本地屏幕/摄像头/canvas 或命令执行能力。请参阅 [Nodes](/zh-CN/nodes)。 - - 简短回答：它可以运行，但要预期会有一些棘手边角问题。 + + 简短回答：可以运行，但预计会遇到一些粗糙边缘。 - - 使用 **64 位**操作系统，并保持 Node >= 22。 + - 使用 **64 位** 操作系统，并保持 Node >= 22。 - 优先使用**可修改的（git）安装方式**，这样你可以查看日志并快速更新。 - - 先不要启用渠道 / Skills，然后一个一个地添加。 - - 如果你遇到奇怪的二进制问题，通常都是 **ARM 兼容性**问题。 + - 先不要启用渠道/Skills，然后逐个添加。 + - 如果你遇到奇怪的二进制问题，通常都是 **ARM 兼容性** 问题。 文档：[Linux](/zh-CN/platforms/linux)、[Install](/zh-CN/install)。 - 这个界面依赖于 Gateway 网关 可达并且已认证。TUI 也会在首次 hatch 时自动发送 - “Wake up, my friend!”。如果你看到这行内容但**没有回复**， - 且令牌始终为 0，就表示智能体根本没有运行。 + 该界面依赖 Gateway 网关可达且已通过身份验证。TUI 还会在首次 hatch 时自动发送 + “Wake up, my friend!”。如果你看到这行文字却**没有回复**， + 并且 token 仍为 0，说明智能体根本没有运行。 1. 重启 Gateway 网关： @@ -262,7 +261,7 @@ x-i18n: openclaw gateway restart ``` - 2. 检查状态 + 认证： + 2. 检查状态 + 身份验证： ```bash openclaw status @@ -276,31 +275,31 @@ x-i18n: openclaw doctor ``` - 如果 Gateway 网关 是远程的，请确保隧道 / Tailscale 连接正常，并且 UI - 指向了正确的 Gateway 网关。请参阅 [Remote access](/zh-CN/gateway/remote)。 + 如果 Gateway 网关位于远程，请确保隧道/Tailscale 连接已建立，并且 UI + 指向的是正确的 Gateway 网关。请参阅 [Remote access](/zh-CN/gateway/remote)。 - + 可以。复制**状态目录**和**工作区**，然后运行一次 Doctor。这样 - 就能让你的机器人“完全保持不变”（记忆、会话历史、认证和渠道 + 可以让你的机器人“完全保持不变”（memory、会话历史、凭证和渠道 状态），前提是你复制了**这两个**位置： 1. 在新机器上安装 OpenClaw。 2. 从旧机器复制 `$OPENCLAW_STATE_DIR`（默认：`~/.openclaw`）。 3. 复制你的工作区（默认：`~/.openclaw/workspace`）。 - 4. 运行 `openclaw doctor` 并重启 Gateway 网关 服务。 + 4. 运行 `openclaw doctor` 并重启 Gateway 网关服务。 - 这会保留配置、认证配置文件、WhatsApp 凭证、会话和记忆。如果你处于 - 远程模式，请记住会话存储和工作区归 Gateway 网关 主机所有。 + 这会保留配置、凭证配置文件、WhatsApp 凭证、会话和 memory。如果你处于 + 远程模式，请记住会话存储和工作区归 Gateway 网关主机所有。 - **重要：**如果你只是将工作区提交 / 推送到 GitHub，你备份的是 - **记忆 + bootstrap 文件**，但**不会**备份会话历史或认证。它们位于 + **重要：**如果你只将工作区提交/推送到 GitHub，你备份的 + 是**memory + 引导文件**，**不是**会话历史或凭证。那些内容位于 `~/.openclaw/` 下（例如 `~/.openclaw/agents//sessions/`）。 - 相关内容：[Migrating](/zh-CN/install/migrating)、[磁盘上的内容位置](#where-things-live-on-disk)、 + 相关内容：[Migrating](/zh-CN/install/migrating)、[磁盘上的文件位置](#where-things-live-on-disk)、 [智能体工作区](/zh-CN/concepts/agent-workspace)、[Doctor](/zh-CN/gateway/doctor)、 - [Remote mode](/zh-CN/gateway/remote)。 + [远程模式](/zh-CN/gateway/remote)。 @@ -308,16 +307,16 @@ x-i18n: 查看 GitHub 更新日志： [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - 最新条目位于最上方。如果顶部部分标记为 **Unreleased**，那么下一个带日期的 - 部分就是最近发布的版本。条目按 **Highlights**、**Changes** 和 - **Fixes** 分组（如有需要，还会有文档 / 其他部分）。 + 最新条目位于顶部。如果顶部章节标记为 **Unreleased**，那么下一个带日期的 + 章节就是最近发布的版本。条目按 **Highlights**、**Changes** 和 + **Fixes** 分组（如有需要，还会包含 docs/其他章节）。 - 一些 Comcast/Xfinity 连接会因为 Xfinity - Advanced Security 而错误地拦截 `docs.openclaw.ai`。请禁用它，或将 `docs.openclaw.ai` 加入允许列表，然后重试。 - 也请通过这里的链接帮助我们解除拦截：[https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status)。 + 某些 Comcast/Xfinity 连接会因 Xfinity + Advanced Security 而错误地屏蔽 `docs.openclaw.ai`。请禁用它或将 `docs.openclaw.ai` 加入允许列表，然后重试。 + 也请通过这里帮助我们解除屏蔽：[https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status)。 如果你仍然无法访问该站点，文档在 GitHub 上也有镜像： [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) @@ -325,28 +324,28 @@ x-i18n: - **Stable** 和 **beta** 是 **npm dist-tag**，而不是独立的代码分支： + **Stable** 和 **beta** 是 **npm dist-tags**，不是不同的代码线： - `latest` = stable - `beta` = 用于测试的早期构建 - 通常，稳定版本会先发布到 **beta**，然后再通过一个明确的 - 提升步骤将同一版本移动到 `latest`。维护者也可以在需要时 - 直接发布到 `latest`。这就是为什么 beta 和 stable 在提升之后可能会 + 通常，一个 stable 版本会先发布到 **beta**，然后再通过一个明确的 + 提升步骤将同一版本移到 `latest`。维护者在需要时也可以 + 直接发布到 `latest`。这就是为什么 beta 和 stable 在提升之后可能 指向**同一个版本**。 查看变更内容： [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - 关于安装一行命令以及 beta 和 dev 的区别，请参阅下方的折叠项。 + 有关安装单行命令以及 beta 和 dev 之间区别，请参阅下面的折叠项。 - **Beta** 是 npm dist-tag `beta`（提升后可能与 `latest` 一致）。 - **Dev** 是不断移动的 `main` 头部（git）；发布时使用 npm dist-tag `dev`。 + **Beta** 是 npm dist-tag `beta`（在提升后可能与 `latest` 相同）。 + **Dev** 是 `main` 的移动头部（git）；发布时，它使用 npm dist-tag `dev`。 - 一行命令（macOS/Linux）： + 单行命令（macOS/Linux）： ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta @@ -364,7 +363,7 @@ x-i18n: - 有两种方式： + 有两种选择： 1. **Dev 渠道（git 检出）：** @@ -374,7 +373,7 @@ x-i18n: 这会切换到 `main` 分支并从源码更新。 - 2. **可修改安装（通过安装站点）：** + 2. **可修改安装（来自安装站点）：** ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git @@ -382,7 +381,7 @@ x-i18n: 这会给你一个可本地编辑的仓库，然后你可以通过 git 更新。 - 如果你更喜欢手动进行干净的克隆，请使用： + 如果你更喜欢手动使用干净克隆，请使用： ```bash git clone https://github.com/openclaw/openclaw.git @@ -400,21 +399,21 @@ x-i18n: 大致参考： - **安装：**2-5 分钟 - - **新手引导：**5-15 分钟，取决于你配置了多少渠道 / 模型 + - **新手引导：**5-15 分钟，取决于你配置了多少渠道/模型 - 如果卡住了，请使用 [安装器卡住了](#quick-start-and-first-run-setup) - 以及 [我卡住了](#quick-start-and-first-run-setup) 中的快速调试循环。 + 如果卡住了，请参阅 [安装器卡住了](#quick-start-and-first-run-setup) + 和 [我卡住了](#quick-start-and-first-run-setup) 中的快速调试循环。 - 使用**详细输出**重新运行安装器： + 重新运行安装器并启用**详细输出**： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` - 使用详细输出安装 beta： + 带详细输出的 beta 安装： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose @@ -439,17 +438,17 @@ x-i18n: - + 两个常见的 Windows 问题： - **1）npm 错误 spawn git / git not found** + **1) npm 错误 spawn git / git not found** - - 安装 **Git for Windows**，并确保 `git` 在你的 PATH 中。 + - 安装 **Git for Windows**，并确保 `git` 已加入你的 PATH。 - 关闭并重新打开 PowerShell，然后重新运行安装器。 - **2）安装后 openclaw is not recognized** + **2) 安装后 openclaw is not recognized** - - 你的 npm 全局 bin 目录不在 PATH 中。 + - 你的 npm 全局 bin 文件夹不在 PATH 中。 - 检查路径： ```powershell @@ -459,18 +458,18 @@ x-i18n: - 将该目录添加到你的用户 PATH 中（Windows 上不需要 `\bin` 后缀；在大多数系统上它是 `%AppData%\npm`）。 - 更新 PATH 后，关闭并重新打开 PowerShell。 - 如果你想获得最顺滑的 Windows 设置体验，请使用 **WSL2**，而不是原生 Windows。 + 如果你想要最顺畅的 Windows 设置，请使用 **WSL2**，而不是原生 Windows。 文档：[Windows](/zh-CN/platforms/windows)。 - + 这通常是原生 Windows shell 中控制台代码页不匹配导致的。 症状： - - `system.run`/`exec` 输出中的中文显示为乱码 - - 同一命令在另一个终端配置中显示正常 + - `system.run`/`exec` 输出将中文显示为乱码 + - 同一条命令在另一个终端配置中显示正常 在 PowerShell 中的快速解决方法： @@ -481,21 +480,21 @@ x-i18n: $OutputEncoding = [System.Text.UTF8Encoding]::new($false) ``` - 然后重启 Gateway 网关 并重试你的命令： + 然后重启 Gateway 网关并重试你的命令： ```powershell openclaw gateway restart ``` - 如果你在最新的 OpenClaw 上仍然能复现这个问题，请在这里跟踪 / 报告： + 如果你在最新版本 OpenClaw 上仍能复现此问题，请在这里跟踪/报告： - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - - 使用**可修改的（git）安装方式**，这样你就能在本地拥有完整的源代码和文档，然后 - 在_该目录中_询问你的机器人（或 Claude/Codex），这样它就可以读取仓库并给出准确答案。 + + 使用**可修改的（git）安装方式**，这样你就能在本地拥有完整源码和文档，然后 + 在_该目录中_询问你的机器人（或 Claude/Codex），这样它就能读取仓库并给出精确回答。 ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git @@ -515,28 +514,28 @@ x-i18n: - 任何 Linux VPS 都可以。在服务器上安装，然后使用 SSH/Tailscale 访问 Gateway 网关。 + 任何 Linux VPS 都可以。安装到服务器上，然后使用 SSH/Tailscale 访问 Gateway 网关。 指南：[exe.dev](/zh-CN/install/exe-dev)、[Hetzner](/zh-CN/install/hetzner)、[Fly.io](/zh-CN/install/fly)。 远程访问：[Gateway remote](/zh-CN/gateway/remote)。 - + 我们维护了一个**托管中心**，汇总常见提供商。选择一个并按照指南操作： - - [VPS hosting](/zh-CN/vps)（所有提供商集中在一处） + - [VPS hosting](/zh-CN/vps)（所有提供商集中在一个地方） - [Fly.io](/zh-CN/install/fly) - [Hetzner](/zh-CN/install/hetzner) - [exe.dev](/zh-CN/install/exe-dev) - 它在云中的工作方式是：**Gateway 网关 运行在服务器上**，而你通过 - Control UI（或 Tailscale/SSH）从笔记本电脑 / 手机上访问它。你的状态和工作区 - 都位于服务器上，因此请将该主机视为真实数据源并做好备份。 + 在云端的工作方式是：**Gateway 网关运行在服务器上**，而你通过 + Control UI（或 Tailscale/SSH）从笔记本电脑/手机访问它。你的状态 + 工作区 + 位于服务器上，因此请将该主机视为事实来源并做好备份。 - 你可以将**节点**（Mac/iOS/Android/无头环境）配对到这个云端 Gateway 网关，以访问 - 本地屏幕 / 摄像头 / 画布，或在你的笔记本电脑上运行命令，同时保持 - Gateway 网关 在云中运行。 + 你可以将**节点**（Mac/iOS/Android/headless）配对到该云端 Gateway 网关，以访问 + 本地屏幕/摄像头/canvas，或在你的笔记本电脑上运行命令，同时保持 + Gateway 网关位于云端。 中心页：[Platforms](/zh-CN/platforms)。远程访问：[Gateway remote](/zh-CN/gateway/remote)。 节点：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)。 @@ -545,8 +544,8 @@ x-i18n: 简短回答：**可以，但不推荐**。更新流程可能会重启 - Gateway 网关（这会中断当前会话），可能需要一个干净的 git 检出，并且 - 可能要求确认。更安全的做法是：由操作员在 shell 中执行更新。 + Gateway 网关（这会断开当前会话），可能需要干净的 git 检出，并且 + 可能提示确认。更安全的方式是：由操作员在 shell 中运行更新。 使用 CLI： @@ -558,7 +557,7 @@ x-i18n: openclaw update --no-restart ``` - 如果你必须从智能体中自动化执行： + 如果你必须从智能体自动化执行： ```bash openclaw update --yes --no-restart @@ -570,34 +569,34 @@ x-i18n: - `openclaw onboard` 是推荐的设置方式。在**本地模式**下，它会引导你完成： + `openclaw onboard` 是推荐的设置路径。在**本地模式**下，它会引导你完成： - - **模型 / 认证设置**（提供商 OAuth、API 密钥、Anthropic setup-token，以及 LM Studio 等本地模型选项） - - **工作区**位置 + bootstrap 文件 - - **Gateway 网关 设置**（bind/port/auth/tailscale） + - **模型/凭证设置**（提供商 OAuth、API 密钥、Anthropic setup-token，以及 LM Studio 等本地模型选项） + - **工作区**位置 + 引导文件 + - **Gateway 网关设置**（bind/port/auth/tailscale） - **渠道**（WhatsApp、Telegram、Discord、Mattermost、Signal、iMessage，以及像 QQ Bot 这样的内置渠道插件） - - **守护进程安装**（macOS 上为 LaunchAgent；Linux/WSL2 上为 systemd 用户单元） - - **健康检查**和 **Skills** 选择 + - **守护进程安装**（macOS 上的 LaunchAgent；Linux/WSL2 上的 systemd 用户单元） + - **健康检查** 和 **Skills** 选择 - 如果你配置的模型未知或缺少认证，它也会发出警告。 + 如果你配置的模型未知或缺少凭证，它还会发出警告。 - - 不需要。你可以通过 **API 密钥**（Anthropic/OpenAI/其他）运行 OpenClaw，或者使用 - **纯本地模型**，这样你的数据就会保留在设备上。订阅（Claude - Pro/Max 或 OpenAI Codex）只是认证这些提供商的可选方式。 + + 不需要。你可以通过**API 密钥**（Anthropic/OpenAI/其他）运行 OpenClaw，或者使用 + **纯本地模型**，这样你的数据会保留在你的设备上。订阅（Claude + Pro/Max 或 OpenAI Codex）是这些提供商的可选身份验证方式。 - 对于 OpenClaw 中的 Anthropic，实际上的区分是： + 对于 OpenClaw 中的 Anthropic，实际区分如下： - - **Anthropic API key**：正常的 Anthropic API 计费 - - **Claude CLI / OpenClaw 中的 Claude 订阅认证**：Anthropic 员工 - 告诉我们这种用法再次被允许，OpenClaw 当前将 `claude -p` - 的使用视为此集成的认可方式，除非 Anthropic 发布新的 + - **Anthropic API key**：普通 Anthropic API 计费 + - **OpenClaw 中的 Claude CLI / Claude 订阅身份验证**：Anthropic 员工 + 告诉我们这种用法再次被允许，OpenClaw 将 `claude -p` + 的使用视为该集成的已认可方式，除非 Anthropic 发布新的 政策 - 对于长期运行的 Gateway 网关 主机，Anthropic API 密钥仍然是 - 更可预测的设置方式。OpenAI Codex OAuth 已明确支持像 OpenClaw 这样的外部 + 对于长期运行的 Gateway 网关主机，Anthropic API 密钥仍然是更 + 可预测的配置方式。OpenAI Codex OAuth 已明确支持像 OpenClaw 这样的外部 工具。 OpenClaw 还支持其他托管式订阅选项，包括 @@ -611,27 +610,25 @@ x-i18n: - + 可以。 Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 - 除非 Anthropic 发布新的政策，否则 OpenClaw 会将 Claude 订阅认证和 `claude -p` 的使用视为 - 该集成下被认可的方式。如果你想要 - 最可预测的服务端设置，请改用 Anthropic API key。 + 除非 Anthropic 发布新的政策，否则 OpenClaw 会将 Claude 订阅凭证和 `claude -p` 的使用 + 视为此集成的已认可方式。如果你想要最可预测的服务器端部署，请改用 Anthropic API 密钥。 - + 支持。 - Anthropic 员工告诉我们，这种用法再次被允许，因此 OpenClaw 将 - Claude CLI 复用和 `claude -p` 的使用视为该集成下被认可的方式， - 除非 Anthropic 发布新的政策。 + Anthropic 员工告诉我们这种用法再次被允许，因此除非 Anthropic 发布新的政策， + 否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 的使用视为此集成的已认可方式。 - Anthropic setup-token 仍然是 OpenClaw 支持的令牌路径，但在可用时，OpenClaw 现在更偏好 Claude CLI 复用和 `claude -p`。 - 对于生产环境或多用户工作负载，Anthropic API key 认证仍然是 - 更安全、更可预测的选择。如果你想在 OpenClaw 中使用其他订阅式托管 - 选项，请参阅 [OpenAI](/zh-CN/providers/openai)、[Qwen / Model + Anthropic setup-token 仍然可作为 OpenClaw 支持的 token 路径，但 OpenClaw 现在在可用时更倾向于使用 Claude CLI 复用和 `claude -p`。 + 对于生产环境或多用户工作负载，Anthropic API 密钥凭证仍然是 + 更安全、更可预测的选择。如果你想在 OpenClaw 中使用其他托管式订阅选项， + 请参阅 [OpenAI](/zh-CN/providers/openai)、[Qwen / Model Cloud](/zh-CN/providers/qwen)、[MiniMax](/zh-CN/providers/minimax) 和 [GLM Models](/zh-CN/providers/glm)。 @@ -639,29 +636,29 @@ x-i18n: -这表示你当前时间窗口中的 **Anthropic 配额 / 速率限制** 已耗尽。如果你 -使用 **Claude CLI**，请等待时间窗口重置或升级你的套餐。如果你 +这意味着你在当前窗口中的 **Anthropic 配额/速率限制** 已耗尽。如果你 +使用 **Claude CLI**，请等待窗口重置或升级你的套餐。如果你 使用 **Anthropic API key**，请检查 Anthropic Console -中的用量 / 计费，并根据需要提高限额。 +中的使用量/计费情况，并根据需要提高限制。 如果消息明确是： - `Extra usage is required for long context requests`，则说明该请求正在尝试使用 + `Extra usage is required for long context requests`，则说明该请求正尝试使用 Anthropic 的 1M 上下文 beta（`context1m: true`）。这仅在你的 - 凭证符合长上下文计费条件时才可用（API key 计费，或者 + 凭证符合长上下文计费资格时才可用（API key 计费，或 启用了 Extra Usage 的 OpenClaw Claude 登录路径）。 - 提示：设置一个**回退模型**，这样当某个提供商受到速率限制时，OpenClaw 仍然可以继续回复。 + 提示：设置一个**后备模型**，这样在某个提供商受到速率限制时，OpenClaw 仍可继续回复。 请参阅 [Models](/cli/models)、[OAuth](/zh-CN/concepts/oauth) 和 [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/zh-CN/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context)。 - 支持。OpenClaw 内置了 **Amazon Bedrock（Converse）** 提供商。存在 AWS 环境标记时，OpenClaw 可以自动发现支持流式 / 文本的 Bedrock 目录，并将其作为隐式 `amazon-bedrock` 提供商合并；否则你也可以显式启用 `plugins.entries.amazon-bedrock.config.discovery.enabled` 或添加手动提供商条目。请参阅 [Amazon Bedrock](/zh-CN/providers/bedrock) 和 [Model providers](/zh-CN/providers/models)。如果你更偏好托管密钥流程，在 Bedrock 前面使用 OpenAI 兼容代理仍然是有效选项。 + 支持。OpenClaw 内置了 **Amazon Bedrock（Converse）** 提供商。在存在 AWS 环境标记时，OpenClaw 可以自动发现支持流式传输/文本的 Bedrock 目录，并将其合并为隐式的 `amazon-bedrock` 提供商；否则你也可以显式启用 `plugins.entries.amazon-bedrock.config.discovery.enabled` 或添加手动提供商条目。请参阅 [Amazon Bedrock](/zh-CN/providers/bedrock) 和 [模型提供商](/zh-CN/providers/models)。如果你更喜欢托管式密钥流程，在 Bedrock 前面放置一个兼容 OpenAI 的代理仍然是有效选项。 - - OpenClaw 通过 OAuth（ChatGPT 登录）支持 **OpenAI Code（Codex）**。新手引导可以运行 OAuth 流程，并会在适当时将默认模型设置为 `openai-codex/gpt-5.4`。请参阅 [Model providers](/zh-CN/concepts/model-providers) 和 [新手引导（CLI）](/zh-CN/start/wizard)。 + + OpenClaw 通过 OAuth（ChatGPT 登录）支持 **OpenAI Code（Codex）**。新手引导可以运行 OAuth 流程，并会在适当时将默认模型设置为 `openai-codex/gpt-5.4`。请参阅 [模型提供商](/zh-CN/concepts/model-providers) 和 [设置向导（CLI）](/zh-CN/start/wizard)。 @@ -670,92 +667,92 @@ x-i18n: - `openai-codex/gpt-5.4` = ChatGPT/Codex OAuth - `openai/gpt-5.4` = 直接 OpenAI Platform API - 在 OpenClaw 中，ChatGPT/Codex 登录接入的是 `openai-codex/*` 路径， + 在 OpenClaw 中，ChatGPT/Codex 登录连接的是 `openai-codex/*` 路径， 而不是直接的 `openai/*` 路径。如果你想在 OpenClaw 中使用直接 API 路径，请设置 `OPENAI_API_KEY`（或等效的 OpenAI 提供商配置）。 如果你想在 OpenClaw 中使用 ChatGPT/Codex 登录，请使用 `openai-codex/*`。 - - `openai-codex/*` 使用 Codex OAuth 路径，而它可用的配额窗口由 - OpenAI 管理，并取决于你的套餐。实际上，这些限制可能与 - ChatGPT 网站 / 应用的体验不同，即使二者绑定的是同一个账户。 + + `openai-codex/*` 使用 Codex OAuth 路径，其可用配额窗口 + 由 OpenAI 管理，并取决于套餐。实际上，这些限制可能与 + ChatGPT 网站/应用中的体验不同，即使两者绑定的是同一个账户。 OpenClaw 可以在 - `openclaw models status` 中显示当前可见的提供商用量 / 配额窗口，但它不会凭空生成或将 ChatGPT 网页版的 - 权益规范化为直接 API 访问。如果你想使用直接的 OpenAI Platform - 计费 / 限额路径，请配合 API key 使用 `openai/*`。 + `openclaw models status` 中显示当前可见的提供商使用量/配额窗口，但不会臆造或标准化 ChatGPT 网页版的 + 权益，使其变成直接 API 访问。如果你想使用直接 OpenAI Platform + 计费/限额路径，请配合 API 密钥使用 `openai/*`。 - - 支持。OpenClaw 完全支持 **OpenAI Code（Codex）订阅 OAuth**。 - OpenAI 明确允许在像 OpenClaw 这样的外部工具 / 工作流中 - 使用订阅 OAuth。新手引导可以为你运行该 OAuth 流程。 + + 支持。OpenClaw 完整支持 **OpenAI Code（Codex）订阅 OAuth**。 + OpenAI 明确允许在像 OpenClaw 这样的外部工具/工作流中 + 使用订阅 OAuth。新手引导可以为你运行 OAuth 流程。 - 请参阅 [OAuth](/zh-CN/concepts/oauth)、[Model providers](/zh-CN/concepts/model-providers) 和 [新手引导（CLI）](/zh-CN/start/wizard)。 + 请参阅 [OAuth](/zh-CN/concepts/oauth)、[模型提供商](/zh-CN/concepts/model-providers) 和 [设置向导（CLI）](/zh-CN/start/wizard)。 - Gemini CLI 使用的是**插件认证流程**，而不是在 `openclaw.json` 中配置 client id 或 secret。 + Gemini CLI 使用的是**插件凭证流程**，而不是在 `openclaw.json` 中配置 client id 或 secret。 步骤： - 1. 在本地安装 Gemini CLI，使 `gemini` 位于 `PATH` 中 + 1. 在本地安装 Gemini CLI，确保 `gemini` 已在 `PATH` 中 - Homebrew：`brew install gemini-cli` - npm：`npm install -g @google/gemini-cli` 2. 启用插件：`openclaw plugins enable google` 3. 登录：`openclaw models auth login --provider google-gemini-cli --set-default` 4. 登录后的默认模型：`google-gemini-cli/gemini-3-flash-preview` - 5. 如果请求失败，请在 Gateway 网关 主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID` + 5. 如果请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID` - 这会将 OAuth 令牌存储在 Gateway 网关 主机上的认证配置文件中。详情请参阅：[Model providers](/zh-CN/concepts/model-providers)。 + 这会将 OAuth token 存储在 Gateway 网关主机上的凭证配置文件中。详情请参阅：[模型提供商](/zh-CN/concepts/model-providers)。 - 通常不适合。OpenClaw 需要大上下文 + 强安全性；小模型会截断并泄漏。如果你确实要用，请在本地运行你能承载的**最大**模型构建（LM Studio），并查看 [/gateway/local-models](/zh-CN/gateway/local-models)。更小 / 量化的模型会增加提示注入风险——请参阅 [Security](/zh-CN/gateway/security)。 + 通常不适合。OpenClaw 需要较大的上下文 + 强安全性；小显存卡会截断并泄露内容。如果你必须这么做，请在本地运行你能使用的**最大**模型构建版本（LM Studio），并参阅 [/gateway/local-models](/zh-CN/gateway/local-models)。更小/量化的模型会增加 prompt injection 风险——请参阅 [Security](/zh-CN/gateway/security)。 - - 选择区域固定的端点。OpenRouter 为 MiniMax、Kimi 和 GLM 提供了美国托管选项；选择美国托管变体即可让数据保留在该区域内。你仍然可以通过使用 `models.mode: "merge"` 将 Anthropic/OpenAI 与这些选项一并列出，这样既能保持回退可用，又能遵循你选择的区域化提供商。 + + 选择固定区域的端点。OpenRouter 为 MiniMax、Kimi 和 GLM 提供了美国托管选项；选择美国托管变体即可将数据保留在该区域。你仍然可以通过使用 `models.mode: "merge"` 将 Anthropic/OpenAI 与这些选项一起列出，这样在遵守所选区域提供商约束的同时，后备模型仍然可用。 - - 不需要。OpenClaw 可以运行在 macOS 或 Linux 上（Windows 通过 WSL2）。Mac mini 是可选的——有些人 - 会买一台作为常开主机，但小型 VPS、家用服务器或 Raspberry Pi 级别的机器也可以。 + + 不需要。OpenClaw 可运行在 macOS 或 Linux 上（Windows 通过 WSL2）。Mac mini 是可选的——有些人 + 会买一台作为始终在线的主机，但小型 VPS、家用服务器或 Raspberry Pi 级别的设备也可以。 - 只有在你需要**仅限 macOS 的工具**时才需要 Mac。对于 iMessage，请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)（推荐）——BlueBubbles 服务器可以运行在任何 Mac 上，而 Gateway 网关 可以运行在 Linux 或其他地方。如果你想使用其他仅限 macOS 的工具，请在 Mac 上运行 Gateway 网关 或配对一个 macOS 节点。 + 只有在你需要**仅限 macOS 的工具**时才需要 Mac。对于 iMessage，请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)（推荐）——BlueBubbles 服务器可运行在任何 Mac 上，而 Gateway 网关可以运行在 Linux 或其他地方。如果你想使用其他仅限 macOS 的工具，请在 Mac 上运行 Gateway 网关或配对一个 macOS 节点。 文档：[BlueBubbles](/zh-CN/channels/bluebubbles)、[Nodes](/zh-CN/nodes)、[Mac remote mode](/zh-CN/platforms/mac/remote)。 - - 你需要**某台已登录 Messages 的 macOS 设备**。它**不一定**必须是 Mac mini—— - 任何 Mac 都可以。对于 iMessage，**请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)**（推荐）——BlueBubbles 服务器运行在 macOS 上，而 Gateway 网关 可以运行在 Linux 或其他地方。 + + 你需要**某种已登录 Messages 的 macOS 设备**。它**不一定**是 Mac mini—— + 任何 Mac 都可以。对于 iMessage，**请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)**（推荐）——BlueBubbles 服务器运行在 macOS 上，而 Gateway 网关可以运行在 Linux 或其他地方。 - 常见设置： + 常见部署： - - 在 Linux/VPS 上运行 Gateway 网关，并在任意已登录 Messages 的 Mac 上运行 BlueBubbles 服务器。 - - 如果你想要最简单的单机设置，也可以把所有内容都运行在那台 Mac 上。 + - 在 Linux/VPS 上运行 Gateway 网关，并在任何已登录 Messages 的 Mac 上运行 BlueBubbles 服务器。 + - 如果你想要最简单的单机部署，也可以将所有内容都运行在这台 Mac 上。 文档：[BlueBubbles](/zh-CN/channels/bluebubbles)、[Nodes](/zh-CN/nodes)、 [Mac remote mode](/zh-CN/platforms/mac/remote)。 - + 可以。**Mac mini 可以运行 Gateway 网关**，而你的 MacBook Pro 可以作为 - **节点**（配套设备）连接。节点不运行 Gateway 网关——它们提供额外的 - 能力，例如该设备上的屏幕 / 摄像头 / 画布以及 `system.run`。 + **节点**（配套设备）连接。节点本身不运行 Gateway 网关——它们提供额外 + 能力，例如该设备上的屏幕/摄像头/canvas 和 `system.run`。 常见模式： - - Gateway 网关 运行在 Mac mini 上（始终在线）。 - - MacBook Pro 运行 macOS 应用或节点主机，并与 Gateway 网关 配对。 + - Gateway 网关运行在 Mac mini 上（始终在线）。 + - MacBook Pro 运行 macOS 应用或节点主机，并与 Gateway 网关配对。 - 使用 `openclaw nodes status` / `openclaw nodes list` 查看它。 文档：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)。 @@ -764,43 +761,43 @@ x-i18n: **不推荐**使用 Bun。我们观察到运行时 bug，尤其是在 WhatsApp 和 Telegram 上。 - 对于稳定的 Gateway 网关，请使用 **Node**。 + 若要获得稳定的 Gateway 网关，请使用 **Node**。 - 如果你仍想尝试 Bun，请在不用于生产的 Gateway 网关 上进行， + 如果你仍想尝试 Bun，请仅在非生产 Gateway 网关上进行， 并且不要启用 WhatsApp/Telegram。 - `channels.telegram.allowFrom` 填的是**人工发送者的 Telegram 用户 ID**（数字），不是机器人用户名。 + `channels.telegram.allowFrom` 填的是**人工发送者的 Telegram 用户 ID**（数字）。它不是 bot 用户名。 - 设置流程只接受数字用户 ID。如果你的配置中已经有遗留的 `@username` 条目，`openclaw doctor --fix` 可以尝试解析它们。 + 设置过程中只会要求输入数字用户 ID。如果你的配置中已经有旧版 `@username` 条目，`openclaw doctor --fix` 可以尝试解析它们。 - 更安全的方式（无需第三方机器人）： + 更安全的方式（不使用第三方 bot）： - - 私信你的机器人，然后运行 `openclaw logs --follow`，读取 `from.id`。 + - 给你的 bot 发送私信，然后运行 `openclaw logs --follow` 并读取 `from.id`。 官方 Bot API： - - 私信你的机器人，然后调用 `https://api.telegram.org/bot/getUpdates`，读取 `message.from.id`。 + - 给你的 bot 发送私信，然后调用 `https://api.telegram.org/bot/getUpdates` 并读取 `message.from.id`。 第三方方式（隐私性较差）： - - 私信 `@userinfobot` 或 `@getidsbot`。 + - 给 `@userinfobot` 或 `@getidsbot` 发送私信。 请参阅 [/channels/telegram](/zh-CN/channels/telegram#access-control-and-activation)。 - - 可以，通过**多智能体路由**实现。将每个发送者的 WhatsApp **私信**（peer `kind: "direct"`，发送者 E.164 格式如 `+15551234567`）绑定到不同的 `agentId`，这样每个人都会有自己的工作区和会话存储。回复仍然来自**同一个 WhatsApp 账户**，而私信访问控制（`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`）对每个 WhatsApp 账户都是全局的。请参阅 [Multi-Agent Routing](/zh-CN/concepts/multi-agent) 和 [WhatsApp](/zh-CN/channels/whatsapp)。 + + 可以，通过**多智能体路由**实现。将每个发送者的 WhatsApp **私信**（peer `kind: "direct"`，发送者 E.164 格式如 `+15551234567`）绑定到不同的 `agentId`，这样每个人都会拥有自己的工作区和会话存储。回复仍然来自**同一个 WhatsApp 账号**，而私信访问控制（`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`）对每个 WhatsApp 账号来说是全局的。请参阅 [多智能体路由](/zh-CN/concepts/multi-agent) 和 [WhatsApp](/zh-CN/channels/whatsapp)。 - - 可以。使用多智能体路由：给每个智能体设置各自的默认模型，然后将入站路由（提供商账户或特定 peer）绑定到对应智能体。示例配置见 [Multi-Agent Routing](/zh-CN/concepts/multi-agent)。另请参阅 [Models](/zh-CN/concepts/models) 和 [Configuration](/zh-CN/gateway/configuration)。 + + 可以。使用多智能体路由：为每个智能体设置各自的默认模型，然后将入站路由（提供商账户或特定 peer）绑定到各个智能体。示例配置见 [多智能体路由](/zh-CN/concepts/multi-agent)。另请参阅 [Models](/zh-CN/concepts/models) 和 [Configuration](/zh-CN/gateway/configuration)。 - + 可以。Homebrew 支持 Linux（Linuxbrew）。快速设置： ```bash @@ -810,25 +807,25 @@ x-i18n: brew install ``` - 如果你通过 systemd 运行 OpenClaw，请确保服务的 PATH 包含 `/home/linuxbrew/.linuxbrew/bin`（或你的 brew 前缀），这样通过 `brew` 安装的工具才能在非登录 shell 中被解析。 - 较新的构建也会在 Linux systemd 服务中预置常见用户 bin 目录（例如 `~/.local/bin`、`~/.npm-global/bin`、`~/.local/share/pnpm`、`~/.bun/bin`），并在已设置时遵循 `PNPM_HOME`、`NPM_CONFIG_PREFIX`、`BUN_INSTALL`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`NVM_DIR` 和 `FNM_DIR`。 + 如果你通过 systemd 运行 OpenClaw，请确保服务的 PATH 包含 `/home/linuxbrew/.linuxbrew/bin`（或你的 brew 前缀），这样通过 `brew` 安装的工具才能在非登录 shell 中解析。 + 最近的构建还会在 Linux systemd 服务中预置常见的用户 bin 目录（例如 `~/.local/bin`、`~/.npm-global/bin`、`~/.local/share/pnpm`、`~/.bun/bin`），并在设置时遵循 `PNPM_HOME`、`NPM_CONFIG_PREFIX`、`BUN_INSTALL`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`NVM_DIR` 和 `FNM_DIR`。 - - **可修改的（git）安装：**完整的源码检出，可编辑，最适合贡献者。 - 你可以在本地运行构建并修改代码 / 文档。 - - **npm install：**全局 CLI 安装，不带仓库，最适合“直接运行”。 - 更新来自 npm dist-tag。 + - **可修改的（git）安装：**完整源码检出、可编辑，最适合贡献者。 + 你可以在本地运行构建，并修改代码/文档。 + - **npm install：**全局 CLI 安装，不包含仓库，最适合“直接运行”。 + 更新来自 npm dist-tags。 文档：[入门指南](/zh-CN/start/getting-started)、[Updating](/zh-CN/install/updating)。 - 可以。安装另一种方式，然后运行 Doctor，让 Gateway 网关 服务指向新的入口点。 - 这**不会删除你的数据**——它只会更改 OpenClaw 的代码安装方式。你的状态 - （`~/.openclaw`）和工作区（`~/.openclaw/workspace`）都会保持不变。 + 可以。安装另一种形式后，运行 Doctor，让 Gateway 网关服务指向新的入口点。 + 这**不会删除你的数据**——它只会更改 OpenClaw 代码安装。你的状态 + （`~/.openclaw`）和工作区（`~/.openclaw/workspace`）都不会被触碰。 从 npm 切换到 git： @@ -849,68 +846,68 @@ x-i18n: openclaw gateway restart ``` - Doctor 会检测 Gateway 网关 服务入口点不匹配的问题，并提供重写服务配置以匹配当前安装的选项（在自动化中使用 `--repair`）。 + Doctor 会检测 Gateway 网关服务入口点不匹配的问题，并提供将服务配置重写为与当前安装一致的选项（在自动化中使用 `--repair`）。 - 备份建议：请参阅 [备份策略](#where-things-live-on-disk)。 + 备份提示：请参阅 [备份策略](#where-things-live-on-disk)。 - + 简短回答：**如果你想要 24/7 的可靠性，就用 VPS**。如果你想要 - 最低的使用门槛，并且能接受睡眠 / 重启带来的影响，那就在本地运行。 + 最低摩擦，并且能接受休眠/重启带来的影响，就在本地运行。 **笔记本电脑（本地 Gateway 网关）** - - **优点：**没有服务器成本，可直接访问本地文件，有可见的实时浏览器窗口。 - - **缺点：**睡眠 / 网络中断 = 连接断开，操作系统更新 / 重启会打断运行，必须保持唤醒状态。 + - **优点：**没有服务器成本，可直接访问本地文件，可见的实时浏览器窗口。 + - **缺点：**休眠/网络断开 = 连接中断，操作系统更新/重启会打断运行，机器必须保持唤醒。 **VPS / 云端** - - **优点：**始终在线，网络稳定，没有笔记本睡眠问题，更容易保持持续运行。 - - **缺点：**通常以无头方式运行（使用截图），只能远程访问文件，更新时你必须通过 SSH 操作。 + - **优点：**始终在线、网络稳定、不会受到笔记本休眠影响、更容易持续运行。 + - **缺点：**通常以 headless 方式运行（使用截图），只能远程访问文件，更新时你必须通过 SSH 操作。 - **OpenClaw 特定说明：**WhatsApp/Telegram/Slack/Mattermost/Discord 在 VPS 上都能正常工作。唯一真正的权衡是**无头浏览器**与可见窗口之间的区别。请参阅 [Browser](/zh-CN/tools/browser)。 + **OpenClaw 特有说明：**WhatsApp/Telegram/Slack/Mattermost/Discord 在 VPS 上都能很好运行。唯一真正的权衡是 **headless 浏览器** 与可见窗口之间的差异。请参阅 [Browser](/zh-CN/tools/browser)。 - **推荐默认方案：**如果你之前遇到过 Gateway 网关 断开连接的问题，就用 VPS。本地运行非常适合你正在积极使用 Mac，并且想要访问本地文件或通过可见浏览器执行 UI 自动化的时候。 + **推荐默认方案：**如果你之前遇到过 Gateway 网关断连问题，请选 VPS。本地运行非常适合你正在积极使用 Mac，并且希望访问本地文件或通过可见浏览器进行 UI 自动化的场景。 - - 不是必须，但**出于可靠性和隔离考虑，推荐这样做**。 + + 不是必需的，但**为了可靠性和隔离性，推荐这样做**。 - - **专用主机（VPS/Mac mini/Pi）：**始终在线，更少受到睡眠 / 重启中断影响，权限更清晰，更容易保持持续运行。 - - **共享笔记本 / 台式机：**用于测试和活跃使用完全没问题，但机器进入睡眠或更新时，预期会出现暂停。 + - **专用主机（VPS/Mac mini/Pi）：**始终在线，较少受到休眠/重启打断，权限更清晰，更容易持续运行。 + - **共享笔记本/台式机：**用于测试和主动使用完全没问题，但当机器休眠或更新时，预计会出现暂停。 - 如果你想两者兼得，可以将 Gateway 网关 放在专用主机上运行，并将你的笔记本配对为一个**节点**，用于本地屏幕 / 摄像头 / exec 工具。请参阅 [Nodes](/zh-CN/nodes)。 - 有关安全建议，请阅读 [Security](/zh-CN/gateway/security)。 + 如果你想兼顾两者的优点，可以把 Gateway 网关放在专用主机上，再将笔记本配对为一个**节点**，用于本地屏幕/摄像头/exec 工具。请参阅 [Nodes](/zh-CN/nodes)。 + 如需安全指导，请阅读 [Security](/zh-CN/gateway/security)。 - - OpenClaw 很轻量。对于基础的 Gateway 网关 + 一个聊天渠道： + + OpenClaw 很轻量。对于基础 Gateway 网关 + 一个聊天渠道： - - **绝对最低配置：**1 vCPU、1GB RAM、约 500MB 磁盘。 - - **推荐配置：**1-2 vCPU、2GB RAM 或更多余量（日志、媒体、多个渠道）。节点工具和浏览器自动化可能比较吃资源。 + - **绝对最低要求：**1 vCPU、1GB RAM、约 500MB 磁盘空间。 + - **推荐配置：**1-2 vCPU、2GB RAM 或更多余量（日志、媒体、多个渠道）。Node 工具和浏览器自动化可能比较吃资源。 - 操作系统：使用 **Ubuntu LTS**（或任何现代 Debian/Ubuntu）。Linux 安装路径在这些系统上测试最充分。 + 操作系统：使用 **Ubuntu LTS**（或任何现代 Debian/Ubuntu）。Linux 安装路径在这些环境中测试最充分。 文档：[Linux](/zh-CN/platforms/linux)、[VPS hosting](/zh-CN/vps)。 - 可以。将虚拟机视作 VPS 即可：它需要始终在线、可访问，并且有足够的 - RAM 来运行 Gateway 网关 以及你启用的所有渠道。 + 可以。将虚拟机视为 VPS 即可：它需要始终在线、可访问，并且有足够的 + RAM 供 Gateway 网关和你启用的任何渠道使用。 - 基本建议： + 基础建议： - - **绝对最低配置：**1 vCPU、1GB RAM。 - - **推荐配置：**如果你运行多个渠道、浏览器自动化或媒体工具，建议使用 2GB RAM 或更多。 + - **绝对最低要求：**1 vCPU、1GB RAM。 + - **推荐配置：**如果你运行多个渠道、浏览器自动化或媒体工具，建议 2GB RAM 或更多。 - **操作系统：**Ubuntu LTS 或其他现代 Debian/Ubuntu。 - 如果你使用的是 Windows，**WSL2 是最简单的类虚拟机设置方式**，并且拥有最佳的工具 - 兼容性。请参阅 [Windows](/zh-CN/platforms/windows)、[VPS hosting](/zh-CN/vps)。 - 如果你是在虚拟机中运行 macOS，请参阅 [macOS VM](/zh-CN/install/macos-vm)。 + 如果你使用 Windows，**WSL2 是最简单的类虚拟机部署方式**，并且拥有最好的工具兼容性。 + 请参阅 [Windows](/zh-CN/platforms/windows)、[VPS hosting](/zh-CN/vps)。 + 如果你在虚拟机中运行 macOS，请参阅 [macOS VM](/zh-CN/install/macos-vm)。 @@ -918,81 +915,81 @@ x-i18n: ## OpenClaw 是什么？ - - OpenClaw 是一个运行在你自己设备上的个人 AI 助手。它会在你已经使用的消息界面上回复你（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat，以及像 QQ Bot 这样的内置渠道插件），并且在受支持的平台上还可以提供语音 + 实时 Canvas。**Gateway 网关**是始终在线的控制平面；而这个助手本身才是产品。 + + OpenClaw 是一个运行在你自己设备上的个人 AI 助手。它会在你已经使用的消息界面中回复你（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat，以及像 QQ Bot 这样的内置渠道插件），并且在受支持的平台上还可以提供语音 + 实时 Canvas。**Gateway 网关**是始终在线的控制平面；助手才是产品本身。 - OpenClaw 并不只是“Claude 的一层封装”。它是一个**本地优先的控制平面**，让你能够在**自己的硬件上** - 运行一个功能强大的助手，并通过你已经在使用的聊天应用访问它，同时具备 - 有状态会话、记忆和工具能力——而无需将你的工作流控制权交给托管式 + OpenClaw 不是“只是一个 Claude 包装器”。它是一个**本地优先的控制平面**，让你能够在**自己的硬件**上运行一个功能强大的助手，并通过你已经使用的聊天应用访问它，同时具备 + 有状态会话、memory 和工具——而无需把你的工作流控制权交给托管式 SaaS。 亮点： - - **你的设备，你的数据：**你可以将 Gateway 网关 运行在任何你想要的地方（Mac、Linux、VPS），并将 + - **你的设备，你的数据：**在你想要的地方运行 Gateway 网关（Mac、Linux、VPS），并将 工作区 + 会话历史保留在本地。 - **真实渠道，而不是 Web 沙箱：**WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等， - 并且在受支持平台上还提供移动端语音和 Canvas。 - - **与模型无关：**可以使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按智能体路由 + 以及在受支持平台上的移动语音和 Canvas。 + - **模型无关：**使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，支持按智能体路由 和故障切换。 - - **纯本地选项：**运行本地模型，这样**所有数据都可以保留在你的设备上**，如果你愿意的话。 + - **纯本地选项：**运行本地模型，这样**所有数据都可以保留在你的设备上**。 - **多智能体路由：**按渠道、账户或任务拆分不同智能体，每个智能体都有自己的 工作区和默认设置。 - - **开源且可修改：**可以检查、扩展和自托管，无需被供应商锁定。 + - **开源且可修改：**可检查、可扩展、可自托管，无供应商锁定。 - 文档：[Gateway 网关](/zh-CN/gateway)、[Channels](/zh-CN/channels)、[多智能体](/zh-CN/concepts/multi-agent)、 + 文档：[Gateway 网关](/zh-CN/gateway)、[渠道](/zh-CN/channels)、[多智能体](/zh-CN/concepts/multi-agent)、 [Memory](/zh-CN/concepts/memory)。 - - 很适合作为起步的项目包括： + + 很适合作为起点的项目包括： - - 搭建网站（WordPress、Shopify 或简单的静态站点）。 - - 制作移动应用原型（大纲、界面、API 计划）。 + - 搭建网站（WordPress、Shopify 或简单静态站点）。 + - 制作移动应用原型（大纲、界面、API 规划）。 - 整理文件和文件夹（清理、命名、打标签）。 - - 连接 Gmail，并自动化生成摘要或后续跟进。 + - 连接 Gmail 并自动生成摘要或后续跟进。 - 它可以处理大型任务，但当你将任务拆分成多个阶段并 - 使用子智能体并行处理时，效果通常最好。 + 它可以处理大型任务，但当你把任务拆分为多个阶段，并 + 使用子智能体进行并行工作时，效果最好。 - + 日常收益通常体现在这些方面： - - **个人简报：**对收件箱、日历和你关心的新闻进行摘要。 - - **研究与起草：**快速研究、摘要，以及邮件或文档的初稿。 - - **提醒与跟进：**由 cron 或 Heartbeat 驱动的提示和清单。 - - **浏览器自动化：**填写表单、采集数据、重复执行网页任务。 - - **跨设备协同：**在手机上发送任务，让 Gateway 网关 在服务器上执行，然后把结果返回到聊天中。 + - **个人简报：**汇总你关心的收件箱、日历和新闻。 + - **研究和起草：**快速研究、摘要，以及邮件或文档的初稿。 + - **提醒和跟进：**由 cron 或 Heartbeat 驱动的提示和检查清单。 + - **浏览器自动化：**填写表单、收集数据、重复执行 Web 任务。 + - **跨设备协作：**从手机发送任务，让 Gateway 网关在服务器上执行，并在聊天中返回结果。 - - 可以，用于**研究、筛选和起草**。它可以扫描网站、建立候选清单、 + + 对于**研究、筛选和起草**，可以。它可以扫描网站、建立候选名单、 汇总潜在客户信息，并撰写外联或广告文案草稿。 - 对于**外联或广告投放**，请始终保留人工参与。避免垃圾信息，遵守当地法律和 - 平台政策，并在发送前审查所有内容。最安全的模式是让 - OpenClaw 起草，由你审批。 + 对于**外联或广告投放**，请让人工参与审核。避免垃圾信息，遵守当地法律和 + 平台政策，并在发送前审核所有内容。最安全的模式是让 + OpenClaw 起草，然后由你审批。 文档：[Security](/zh-CN/gateway/security)。 - OpenClaw 是一个**个人助手**和协调层，而不是 IDE 替代品。想要在仓库中获得最快的直接编码循环， - 请使用 Claude Code 或 Codex。想要持久记忆、跨设备访问和工具编排时，再使用 OpenClaw。 + OpenClaw 是一个**个人助手**和协作编排层，不是 IDE 替代品。若想在仓库中获得 + 最快的直接编码循环，请使用 Claude Code 或 Codex。若你需要 + 持久 memory、跨设备访问和工具编排，请使用 OpenClaw。 优势： - - **持久记忆 + 工作区**，跨会话保留 + - **跨会话的持久 memory + 工作区** - **多平台访问**（WhatsApp、Telegram、TUI、WebChat） - **工具编排**（浏览器、文件、调度、hooks） - - **始终在线的 Gateway 网关**（可运行在 VPS 上，随时随地交互） - - 用于本地浏览器 / 屏幕 / 摄像头 / exec 的 **Nodes** + - **始终在线的 Gateway 网关**（运行在 VPS 上，随时随地交互） + - 用于本地浏览器/屏幕/摄像头/exec 的 **节点** 展示页：[https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -1002,47 +999,47 @@ x-i18n: ## Skills 和自动化 - - 使用受管覆盖，而不是直接编辑仓库副本。把你的改动放到 `~/.openclaw/skills//SKILL.md`（或通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加文件夹）。优先级顺序是 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`，因此受管覆盖仍然会在不触碰 git 的情况下覆盖内置 Skills。如果你需要全局安装某个 skill，但只让部分智能体可见，请将共享副本保存在 `~/.openclaw/skills` 中，并通过 `agents.defaults.skills` 和 `agents.list[].skills` 控制可见性。只有值得上游合并的修改才应保留在仓库中，并通过 PR 提交。 + + 使用托管覆盖，而不是编辑仓库副本。将你的改动放到 `~/.openclaw/skills//SKILL.md` 中（或者通过 `~/.openclaw/openclaw.json` 里的 `skills.load.extraDirs` 添加文件夹）。优先级顺序是 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`，因此托管覆盖仍然会在不触碰 git 的情况下覆盖内置 Skills。如果你需要让 Skill 全局安装，但只对部分智能体可见，请将共享副本放在 `~/.openclaw/skills` 中，并通过 `agents.defaults.skills` 和 `agents.list[].skills` 控制可见性。只有值得上游合并的修改才应该保存在仓库中，并以 PR 形式提交。 - 可以。通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加额外目录（最低优先级）。默认优先级是 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`。`clawhub` 默认安装到 `./skills`，OpenClaw 会在下一个会话中将其视为 `/skills`。如果该 skill 只应对特定智能体可见，请结合 `agents.defaults.skills` 或 `agents.list[].skills` 使用。 + 可以。通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加额外目录（最低优先级）。默认优先级是 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`。`clawhub` 默认安装到 `./skills`，OpenClaw 会在下一次会话中将其视为 `/skills`。如果该 Skill 只应对某些智能体可见，请将其与 `agents.defaults.skills` 或 `agents.list[].skills` 配合使用。 - - 当前支持的模式有： + + 目前支持的模式有： - - **Cron 作业**：隔离的作业可以为每个作业设置 `model` 覆盖。 + - **Cron jobs**：隔离作业可以为每个作业设置 `model` 覆盖。 - **子智能体**：将任务路由到默认模型不同的独立智能体。 - - **按需切换**：使用 `/model` 随时切换当前会话模型。 + - **按需切换**：随时使用 `/model` 切换当前会话模型。 - 请参阅 [Cron jobs](/zh-CN/automation/cron-jobs)、[Multi-Agent Routing](/zh-CN/concepts/multi-agent) 和 [Slash commands](/zh-CN/tools/slash-commands)。 + 请参阅 [Cron jobs](/zh-CN/automation/cron-jobs)、[多智能体路由](/zh-CN/concepts/multi-agent) 和 [Slash commands](/zh-CN/tools/slash-commands)。 - - 对于长时间运行或并行任务，请使用**子智能体**。子智能体会在自己的会话中运行、 - 返回摘要，并让你的主聊天保持响应。 + + 对于长时间运行或并行任务，请使用**子智能体**。子智能体会在自己的会话中运行， + 返回摘要，并保持主聊天响应流畅。 - 你可以让机器人“为这个任务启动一个子智能体”，或者使用 `/subagents`。 - 使用聊天中的 `/status` 可以查看 Gateway 网关 当前正在做什么（以及它是否正忙）。 + 让你的机器人“为此任务生成一个子智能体”，或使用 `/subagents`。 + 在聊天中使用 `/status` 查看 Gateway 网关当前正在做什么（以及它是否繁忙）。 - 令牌提示：长任务和子智能体都会消耗令牌。如果你关心成本，可以通过 `agents.defaults.subagents.model` 为子智能体设置一个 - 更便宜的模型。 + token 提示：长任务和子智能体都会消耗 token。如果你担心成本，请通过 `agents.defaults.subagents.model` + 为子智能体设置一个更便宜的模型。 - 文档：[Sub-agents](/zh-CN/tools/subagents)、[Background Tasks](/zh-CN/automation/tasks)。 + 文档：[子智能体](/zh-CN/tools/subagents)、[后台任务](/zh-CN/automation/tasks)。 - - 使用线程绑定。你可以把一个 Discord 线程绑定到某个子智能体或会话目标，这样该线程中的后续消息就会持续停留在那个绑定的会话上。 + + 使用线程绑定。你可以将 Discord 线程绑定到子智能体或会话目标，这样该线程中的后续消息就会持续发送到绑定的会话。 基本流程： - - 使用 `sessions_spawn` 并设置 `thread: true` 启动（如需持久跟进，也可额外设置 `mode: "session"`）。 - - 或者通过 `/focus ` 手动绑定。 - - 使用 `/agents` 查看绑定状态。 + - 使用 `sessions_spawn` 并设置 `thread: true` 生成（也可以选择 `mode: "session"` 用于持久后续交互）。 + - 或者手动使用 `/focus ` 进行绑定。 + - 使用 `/agents` 检查绑定状态。 - 使用 `/session idle ` 和 `/session max-age ` 控制自动取消聚焦。 - 使用 `/unfocus` 解除线程绑定。 @@ -1050,21 +1047,21 @@ x-i18n: - 全局默认值：`session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours`。 - Discord 覆盖项：`channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours`。 - - 启动时自动绑定：设置 `channels.discord.threadBindings.spawnSubagentSessions: true`。 + - 在生成时自动绑定：设置 `channels.discord.threadBindings.spawnSubagentSessions: true`。 - 文档：[Sub-agents](/zh-CN/tools/subagents)、[Discord](/zh-CN/channels/discord)、[Configuration Reference](/zh-CN/gateway/configuration-reference)、[Slash commands](/zh-CN/tools/slash-commands)。 + 文档：[子智能体](/zh-CN/tools/subagents)、[Discord](/zh-CN/channels/discord)、[Configuration Reference](/zh-CN/gateway/configuration-reference)、[Slash commands](/zh-CN/tools/slash-commands)。 - + 先检查解析后的请求者路由： - - 完成模式的子智能体投递会在存在绑定线程或会话路由时优先使用它们。 - - 如果完成来源只携带一个渠道，OpenClaw 会回退到请求者会话中存储的路由（`lastChannel` / `lastTo` / `lastAccountId`），这样直接投递仍然可能成功。 - - 如果既没有绑定路由，也没有可用的存储路由，直接投递可能失败，结果会回退为排队的会话投递，而不是立即发到聊天中。 + - 完成模式的子智能体投递会优先使用任何已绑定的线程或会话路由（如果存在）。 + - 如果完成来源只携带渠道，OpenClaw 会回退到请求者会话中存储的路由（`lastChannel` / `lastTo` / `lastAccountId`），这样仍然可以成功直接投递。 + - 如果既没有绑定路由，也没有可用的存储路由，直接投递可能会失败，结果会回退为排队的会话投递，而不是立即发送到聊天中。 - 无效或过期的目标仍然可能强制回退到队列，或导致最终投递失败。 - - 如果子会话最后一条可见的助手回复恰好是静默令牌 `NO_REPLY` / `no_reply`，或恰好是 `ANNOUNCE_SKIP`，OpenClaw 会有意抑制公告，而不是发布过时的更早进度。 - - 如果子会话在只有工具调用后超时，公告可能会将其折叠成一条简短的部分进度摘要，而不是重放原始工具输出。 + - 如果子任务最后一条可见的助手回复正好是静默 token `NO_REPLY` / `no_reply`，或者正好是 `ANNOUNCE_SKIP`，OpenClaw 会有意抑制公告，而不是发送较早的过时进度。 + - 如果子任务在只进行工具调用后超时，公告可能会将其折叠为一个简短的部分进度摘要，而不是重放原始工具输出。 调试： @@ -1072,19 +1069,19 @@ x-i18n: openclaw tasks show ``` - 文档：[Sub-agents](/zh-CN/tools/subagents)、[Background Tasks](/zh-CN/automation/tasks)、[Session Tools](/zh-CN/concepts/session-tool)。 + 文档：[子智能体](/zh-CN/tools/subagents)、[后台任务](/zh-CN/automation/tasks)、[会话工具](/zh-CN/concepts/session-tool)。 - Cron 在 Gateway 网关 进程内部运行。如果 Gateway 网关 没有持续运行， + Cron 在 Gateway 网关进程内部运行。如果 Gateway 网关没有持续运行， 定时作业就不会执行。 检查清单： - - 确认 cron 已启用（`cron.enabled`），并且没有设置 `OPENCLAW_SKIP_CRON`。 - - 检查 Gateway 网关 是否在 24/7 持续运行（没有睡眠 / 重启）。 - - 验证作业的时区设置（`--tz` 与主机时区是否一致）。 + - 确认 cron 已启用（`cron.enabled`），并且未设置 `OPENCLAW_SKIP_CRON`。 + - 检查 Gateway 网关是否在 24/7 持续运行（没有休眠/重启）。 + - 验证作业的时区设置（`--tz` 与主机时区）。 调试： @@ -1097,17 +1094,17 @@ x-i18n: - + 先检查投递模式： - - `--no-deliver` / `delivery.mode: "none"` 表示不期望有任何外部消息。 + - `--no-deliver` / `delivery.mode: "none"` 表示不预期有外部消息。 - 缺少或无效的公告目标（`channel` / `to`）意味着运行器跳过了出站投递。 - - 渠道认证失败（`unauthorized`、`Forbidden`）意味着运行器尝试了投递，但被凭证阻止。 - - 静默的隔离结果（仅有 `NO_REPLY` / `no_reply`）会被视为有意不投递，因此运行器也会抑制排队的回退投递。 + - 渠道凭证失败（`unauthorized`、`Forbidden`）意味着运行器尝试投递了，但被凭证拦截。 + - 静默的隔离结果（仅有 `NO_REPLY` / `no_reply`）会被视为有意不投递，因此运行器也会抑制排队回退投递。 - 对于隔离的 cron 作业，运行器负责最终投递。智能体应当 - 返回一段纯文本摘要，供运行器发送。`--no-deliver` 会让 - 结果保持内部可见；它并不会让智能体改为通过 + 对于隔离的 cron 作业，运行器负责最终投递。系统期望 + 智能体返回一个纯文本摘要供运行器发送。`--no-deliver` 会将 + 该结果保留在内部；它并不会允许智能体改用 message 工具直接发送。 调试： @@ -1117,26 +1114,26 @@ x-i18n: openclaw tasks show ``` - 文档：[Cron jobs](/zh-CN/automation/cron-jobs)、[Background Tasks](/zh-CN/automation/tasks)。 + 文档：[Cron jobs](/zh-CN/automation/cron-jobs)、[后台任务](/zh-CN/automation/tasks)。 - + 这通常是实时模型切换路径，而不是重复调度。 - 隔离的 cron 可以在活动运行抛出 `LiveSessionModelSwitchError` 时， - 持久化运行时模型切换并重试。重试会保留切换后的 - 提供商 / 模型；如果切换还携带了新的认证配置文件覆盖，cron + 隔离 cron 可以在活动运行抛出 `LiveSessionModelSwitchError` 时持久化 + 一次运行时模型切换并重试。重试会保留切换后的 + 提供商/模型；如果切换携带了新的凭证配置文件覆盖，cron 也会在重试前将其持久化。 相关选择规则： - - 如果适用，Gmail hook 模型覆盖优先级最高。 + - 在适用时，Gmail hook 模型覆盖优先级最高。 - 然后是每个作业的 `model`。 - 然后是任何已存储的 cron 会话模型覆盖。 - - 最后是正常的智能体 / 默认模型选择。 + - 最后是正常的智能体/默认模型选择。 - 重试循环是有上限的。在初始尝试加上 2 次切换重试之后， + 重试循环是有界的。在初始尝试加上 2 次切换重试之后， cron 会中止，而不是无限循环。 调试： @@ -1152,7 +1149,7 @@ x-i18n: 使用原生 `openclaw skills` 命令，或将 Skills 放入你的工作区。macOS 的 Skills UI 在 Linux 上不可用。 - 你可以在 [https://clawhub.ai](https://clawhub.ai) 浏览 Skills。 + 可在 [https://clawhub.ai](https://clawhub.ai) 浏览 Skills。 ```bash openclaw skills search "calendar" @@ -1165,41 +1162,41 @@ x-i18n: openclaw skills check ``` - 原生 `openclaw skills install` 会写入当前活动工作区的 `skills/` - 目录。只有当你想发布或 - 同步自己的 Skills 时，才需要单独安装 `clawhub` CLI。对于跨智能体共享安装，请将 skill 放在 - `~/.openclaw/skills` 下，并在你想限制哪些智能体可见时使用 `agents.defaults.skills` 或 + 原生 `openclaw skills install` 会写入当前工作区的 `skills/` + 目录。只有在你想发布或 + 同步自己的 Skills 时，才需要单独安装 `clawhub` CLI。对于跨智能体共享安装，请将 Skill 放在 + `~/.openclaw/skills` 下，并在你想限制可见智能体时使用 `agents.defaults.skills` 或 `agents.list[].skills`。 - - 可以。使用 Gateway 网关 调度器： + + 可以。使用 Gateway 网关调度器： - - **Cron jobs**：用于定时或周期性任务（重启后依然保留）。 + - **Cron jobs**：用于计划任务或重复任务（重启后仍会保留）。 - **Heartbeat**：用于“主会话”的周期性检查。 - - **隔离作业**：用于能够发布摘要或投递到聊天中的自治智能体。 + - **隔离作业**：用于可自主运行、发送摘要或投递到聊天中的智能体。 文档：[Cron jobs](/zh-CN/automation/cron-jobs)、[Automation & Tasks](/zh-CN/automation)、 [Heartbeat](/zh-CN/gateway/heartbeat)。 - - 不能直接运行。macOS Skills 受 `metadata.openclaw.os` 和所需二进制文件共同控制，并且只有在 **Gateway 网关 主机**上符合条件时，Skills 才会出现在系统提示中。在 Linux 上，`darwin` 专用 Skills（如 `apple-notes`、`apple-reminders`、`things-mac`）默认不会加载，除非你覆盖这层限制。 + + 不能直接运行。macOS Skills 受 `metadata.openclaw.os` 和所需二进制文件控制，且只有在 **Gateway 网关主机** 上符合条件时，这些 Skills 才会出现在系统提示中。在 Linux 上，`darwin` 专用的 Skills（如 `apple-notes`、`apple-reminders`、`things-mac`）不会加载，除非你覆盖此限制。 - 你有三种受支持的方式： + 你有三种受支持的模式： - **方案 A - 在 Mac 上运行 Gateway 网关（最简单）。** - 在存在 macOS 二进制文件的地方运行 Gateway 网关，然后通过 [远程模式](#gateway-ports-already-running-and-remote-mode) 或 Tailscale 从 Linux 连接。由于 Gateway 网关 主机是 macOS，这些 Skills 会正常加载。 + **选项 A - 在 Mac 上运行 Gateway 网关（最简单）。** + 在存在 macOS 二进制文件的地方运行 Gateway 网关，然后通过 [远程模式](#gateway-ports-already-running-and-remote-mode) 或 Tailscale 从 Linux 连接。由于 Gateway 网关主机是 macOS，这些 Skills 会正常加载。 - **方案 B - 使用 macOS 节点（无需 SSH）。** - 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并将 Mac 上的**节点运行命令**设为“Always Ask”或“Always Allow”。当节点上存在所需二进制文件时，OpenClaw 可以将仅限 macOS 的 Skills 视为符合条件。智能体会通过 `nodes` 工具运行这些 Skills。如果你选择“Always Ask”，在提示中批准“Always Allow”会将该命令加入允许列表。 + **选项 B - 使用 macOS 节点（无需 SSH）。** + 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并在 Mac 上将**节点运行命令**设置为“始终询问”或“始终允许”。当节点上存在所需二进制文件时，OpenClaw 可以将这些仅限 macOS 的 Skills 视为符合条件。智能体会通过 `nodes` 工具运行这些 Skills。如果你选择“始终询问”，在提示中批准“始终允许”会将该命令添加到允许列表中。 - **方案 C - 通过 SSH 代理 macOS 二进制文件（高级）。** - 将 Gateway 网关 保留在 Linux 上，但让所需的 CLI 二进制文件解析为在 Mac 上运行的 SSH 包装器。然后覆盖该 skill，使其允许 Linux，从而保持可用。 + **选项 C - 通过 SSH 代理 macOS 二进制文件（高级）。** + 将 Gateway 网关保留在 Linux 上，但让所需的 CLI 二进制文件解析为在 Mac 上运行的 SSH 包装器。然后覆盖 Skill，使其允许 Linux，这样它就会保持可用。 - 1. 为该二进制文件创建 SSH 包装器（示例：Apple Notes 的 `memo`）： + 1. 为该二进制文件创建一个 SSH 包装器（示例：Apple Notes 的 `memo`）： ```bash #!/usr/bin/env bash @@ -1207,8 +1204,8 @@ x-i18n: exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` - 2. 将该包装器放入 Linux 主机的 `PATH` 中（例如 `~/bin/memo`）。 - 3. 覆盖该 skill 的元数据（工作区或 `~/.openclaw/skills`）以允许 Linux： + 2. 将该包装器放到 Linux 主机的 `PATH` 中（例如 `~/bin/memo`）。 + 3. 覆盖 Skill 元数据（工作区或 `~/.openclaw/skills`）以允许 Linux： ```markdown --- @@ -1225,18 +1222,18 @@ x-i18n: 目前没有内置。 - 可选方式： + 可选方案： - - **自定义 skill / 插件：**最适合可靠的 API 访问（Notion/HeyGen 都有 API）。 - - **浏览器自动化：**无需编写代码即可工作，但更慢，也更脆弱。 + - **自定义 Skill / 插件：**最适合稳定的 API 访问（Notion/HeyGen 都提供 API）。 + - **浏览器自动化：**无需编写代码即可使用，但速度较慢，也更脆弱。 如果你想为每个客户保留上下文（代理机构工作流），一种简单模式是： - 每个客户一个 Notion 页面（上下文 + 偏好 + 当前工作）。 - 让智能体在会话开始时获取该页面。 - 如果你想要原生集成，请提交功能请求，或构建一个 - 面向这些 API 的 skill。 + 如果你想要原生集成，请提交功能请求或构建一个 + 面向这些 API 的 Skill。 安装 Skills： @@ -1245,181 +1242,180 @@ x-i18n: openclaw skills update --all ``` - 原生安装会落到当前活动工作区的 `skills/` 目录中。对于跨智能体共享的 Skills，请将它们放在 `~/.openclaw/skills//SKILL.md`。如果只希望部分智能体看到共享安装，请配置 `agents.defaults.skills` 或 `agents.list[].skills`。有些 Skills 依赖通过 Homebrew 安装的二进制文件；在 Linux 上这意味着 Linuxbrew（请参阅上面的 Homebrew Linux 常见问题条目）。请参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和 [ClawHub](/zh-CN/tools/clawhub)。 + 原生安装会落在当前工作区的 `skills/` 目录中。对于跨智能体共享的 Skills，请将它们放在 `~/.openclaw/skills//SKILL.md`。如果只应让部分智能体看到共享安装，请配置 `agents.defaults.skills` 或 `agents.list[].skills`。某些 Skills 依赖通过 Homebrew 安装的二进制文件；在 Linux 上这意味着 Linuxbrew（请参阅上面的 Homebrew Linux 常见问题条目）。请参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和 [ClawHub](/zh-CN/tools/clawhub)。 - - 使用内置的 `user` 浏览器配置文件，它会通过 Chrome DevTools MCP 进行连接： + + 使用内置的 `user` 浏览器配置文件，它通过 Chrome DevTools MCP 进行连接： ```bash openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot ``` - 如果你想使用自定义名称，请创建一个显式 MCP 配置文件： + 如果你想自定义名称，请创建一个显式的 MCP 配置文件： ```bash openclaw browser create-profile --name chrome-live --driver existing-session openclaw browser --browser-profile chrome-live tabs ``` - 这种方式可以使用本地主机浏览器，也可以使用已连接的浏览器节点。如果 Gateway 网关 运行在其他地方，请在浏览器所在机器上运行节点主机，或改用远程 CDP。 + 该路径可以使用本地主机浏览器或已连接的浏览器节点。如果 Gateway 网关运行在其他地方，请在浏览器所在机器上运行一个节点主机，或改用远程 CDP。 - 当前 `existing-session` / `user` 的限制： + `existing-session` / `user` 当前的限制： - 操作基于 ref，而不是基于 CSS 选择器 - - 上传需要 `ref` / `inputRef`，并且当前一次只支持一个文件 - - `responsebody`、PDF 导出、下载拦截和批量操作仍然需要受管浏览器或原始 CDP 配置文件 + - 上传要求提供 `ref` / `inputRef`，并且当前一次只支持一个文件 + - `responsebody`、PDF 导出、下载拦截和批量操作仍然需要托管浏览器或原始 CDP 配置文件 -## 沙箱隔离和记忆 +## 沙箱隔离和 memory - - 有。请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing)。如需 Docker 专用设置（Docker 中的完整 Gateway 网关 或沙箱镜像），请参阅 [Docker](/zh-CN/install/docker)。 + + 有。请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing)。对于 Docker 专用设置（Docker 中的完整 Gateway 网关或沙箱镜像），请参阅 [Docker](/zh-CN/install/docker)。 - - 默认镜像以安全优先为原则，并以 `node` 用户身份运行，因此它 - 不包含系统包、Homebrew 或内置浏览器。要获得更完整的设置： + + 默认镜像以安全优先，并以 `node` 用户身份运行，因此它不 + 包含系统软件包、Homebrew 或内置浏览器。若要获得更完整的设置： - - 持久化 `/home/node`，使用 `OPENCLAW_HOME_VOLUME`，这样缓存就能保留下来。 - - 通过 `OPENCLAW_DOCKER_APT_PACKAGES` 将系统依赖烘焙进镜像。 + - 持久化 `/home/node`，并设置 `OPENCLAW_HOME_VOLUME`，这样缓存才能保留。 + - 使用 `OPENCLAW_DOCKER_APT_PACKAGES` 将系统依赖烘焙进镜像。 - 通过内置 CLI 安装 Playwright 浏览器： `node /app/node_modules/playwright-core/cli.js install chromium` - - 设置 `PLAYWRIGHT_BROWSERS_PATH`，并确保该路径被持久化。 + - 设置 `PLAYWRIGHT_BROWSERS_PATH`，并确保该路径是持久化的。 文档：[Docker](/zh-CN/install/docker)、[Browser](/zh-CN/tools/browser)。 - - 可以——前提是你的私密流量是**私信**，而公开流量是**群组**。 + + 可以——前提是你的私有流量是**私信**，而公开流量是**群组**。 - 使用 `agents.defaults.sandbox.mode: "non-main"`，这样群组 / 渠道会话（非主键）会在 Docker 中运行，而主私信会话仍留在主机上。然后通过 `tools.sandbox.tools` 限制沙箱隔离会话中可用的工具。 + 使用 `agents.defaults.sandbox.mode: "non-main"`，这样群组/渠道会话（非主键）会在 Docker 中运行，而主私信会话仍保留在主机上。然后通过 `tools.sandbox.tools` 限制沙箱隔离会话中可用的工具。 设置演练 + 示例配置：[群组：个人私信 + 公开群组](/zh-CN/channels/groups#pattern-personal-dms-public-groups-single-agent) - 关键配置参考：[Gateway 网关 配置](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox) + 关键配置参考：[Gateway 网关配置](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox) - - 设置 `agents.defaults.sandbox.docker.binds` 为 `["host:path:mode"]`（例如 `"/home/user/src:/src:ro"`）。全局和每智能体绑定会合并；当 `scope: "shared"` 时，每智能体绑定会被忽略。对任何敏感内容都使用 `:ro`，并记住绑定会绕过沙箱文件系统边界。 + + 将 `agents.defaults.sandbox.docker.binds` 设置为 `["host:path:mode"]`（例如 `"/home/user/src:/src:ro"`）。全局绑定和每个智能体的绑定会合并；当 `scope: "shared"` 时，每个智能体的绑定会被忽略。对任何敏感内容都请使用 `:ro`，并记住绑定会绕过沙箱文件系统边界。 - OpenClaw 会根据规范化路径以及通过最深已存在祖先解析得到的规范路径，同时校验绑定源。也就是说，即使最后一个路径段尚不存在，通过符号链接父目录逃逸的情况也仍会以失败关闭的方式被阻止，并且允许根目录检查在符号链接解析后依然适用。 + OpenClaw 会同时根据规范化路径，以及通过最深已存在祖先解析出的规范路径来验证绑定源。这意味着即使最后一个路径段尚不存在，通过符号链接父目录逃逸的情况也仍会以失败关闭方式被拦截，并且在符号链接解析后，允许根目录检查仍然适用。 - 示例和安全说明请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts) 和 [Sandbox vs Tool Policy vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)。 + 示例和安全说明请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts) 和 [沙箱 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)。 - - OpenClaw 的记忆其实就是智能体工作区中的 Markdown 文件： + + OpenClaw 的 memory 就是智能体工作区中的 Markdown 文件： - `memory/YYYY-MM-DD.md` 中的每日笔记 - - `MEMORY.md` 中整理过的长期笔记（仅主 / 私密会话） + - `MEMORY.md` 中整理过的长期笔记（仅主/私密会话） - OpenClaw 还会运行一个**静默的预压缩记忆刷新**，以提醒模型 - 在自动压缩前写入持久笔记。它仅在工作区 + OpenClaw 还会运行一个**静默的预压缩 memory 刷新**，提醒模型 + 在自动压缩前写下持久笔记。它只会在工作区 可写时运行（只读沙箱会跳过）。请参阅 [Memory](/zh-CN/concepts/memory)。 - - 让机器人**把该事实写入记忆**。长期笔记应写入 `MEMORY.md`， - 短期上下文则写入 `memory/YYYY-MM-DD.md`。 + + 让机器人**把这个事实写入 memory**。长期笔记应放入 `MEMORY.md`， + 短期上下文应放入 `memory/YYYY-MM-DD.md`。 - 这是我们仍在持续改进的领域。提醒模型存储记忆会有帮助； - 它会知道该怎么做。如果它还是总忘，请确认 Gateway 网关 每次运行时使用的都是同一个 + 这仍然是我们正在改进的领域。提醒模型去存储记忆会有帮助； + 它会知道该怎么做。如果它还是总忘记，请确认 Gateway 网关每次运行时使用的都是同一个 工作区。 文档：[Memory](/zh-CN/concepts/memory)、[智能体工作区](/zh-CN/concepts/agent-workspace)。 - - 记忆文件保存在磁盘上，会一直保留，直到你删除它们。限制来自你的 - 存储空间，而不是模型。**会话上下文**仍然受模型 - 上下文窗口限制，因此长对话可能会被压缩或截断。这就是为什么 - 存在记忆搜索——它只会将相关部分重新拉回上下文中。 + + memory 文件保存在磁盘上，除非你删除，否则会一直存在。限制来自你的 + 存储空间，而不是模型。**会话上下文** 仍然受限于模型的 + 上下文窗口，因此长对话可能会被压缩或截断。这就是 + memory 搜索存在的原因——它只会将相关部分重新拉回上下文中。 文档：[Memory](/zh-CN/concepts/memory)、[Context](/zh-CN/concepts/context)。 - - 只有当你使用 **OpenAI embeddings** 时才需要。Codex OAuth 仅覆盖聊天 / 补全， - **不**授予 embeddings 访问权限，因此**使用 Codex 登录（OAuth 或 - Codex CLI 登录）**并不能帮助进行语义记忆搜索。OpenAI embeddings - 仍然需要真实的 API key（`OPENAI_API_KEY` 或 `models.providers.openai.apiKey`）。 + + 只有当你使用 **OpenAI embeddings** 时才需要。Codex OAuth 仅覆盖聊天/补全， + **不**提供 embeddings 访问权限，因此**使用 Codex 登录（OAuth 或 + Codex CLI 登录）**对语义 memory 搜索没有帮助。OpenAI embeddings + 仍然需要真实的 API 密钥（`OPENAI_API_KEY` 或 `models.providers.openai.apiKey`）。 - 如果你没有显式设置提供商，只要 OpenClaw 能解析到 API key，它就会自动选择提供商 - （认证配置文件、`models.providers.*.apiKey` 或环境变量）。 - 如果能解析到 OpenAI key，它会优先选择 OpenAI；否则如果能解析到 Gemini key， - 就选择 Gemini；然后是 Voyage，再然后是 Mistral。如果没有可用的远程 key， - 记忆搜索会保持禁用，直到你完成配置。如果你已经配置了本地模型路径 - 且该路径存在，OpenClaw - 会优先选择 `local`。在你显式设置 + 如果你没有显式设置提供商，OpenClaw 会在能够解析 API 密钥时 + 自动选择一个提供商（凭证配置文件、`models.providers.*.apiKey` 或环境变量）。 + 如果能解析到 OpenAI 密钥，它会优先使用 OpenAI；否则如果能解析到 Gemini 密钥， + 就使用 Gemini；然后是 Voyage，再然后是 Mistral。如果没有可用的远程密钥，memory + 搜索会保持禁用状态，直到你完成配置。如果你配置并存在本地模型路径，OpenClaw + 会优先使用 `local`。当你显式设置 `memorySearch.provider = "ollama"` 时，也支持 Ollama。 - 如果你更希望保持本地化，请设置 `memorySearch.provider = "local"`（并可选设置 + 如果你更希望保持本地化，请设置 `memorySearch.provider = "local"`（也可以选择 `memorySearch.fallback = "none"`）。如果你想使用 Gemini embeddings，请设置 `memorySearch.provider = "gemini"` 并提供 `GEMINI_API_KEY`（或 - `memorySearch.remote.apiKey`）。我们支持 **OpenAI、Gemini、Voyage、Mistral、Ollama 或 local** embedding - 模型——具体设置详情请参阅 [Memory](/zh-CN/concepts/memory)。 + `memorySearch.remote.apiKey`）。我们支持 **OpenAI、Gemini、Voyage、Mistral、Ollama 或本地** + embedding 模型——设置详情请参阅 [Memory](/zh-CN/concepts/memory)。 -## 磁盘上的内容位置 +## 磁盘上的文件位置 - + 不会——**OpenClaw 的状态是本地的**，但**外部服务仍然会看到你发送给它们的内容**。 - - **默认本地：**会话、记忆文件、配置和工作区都位于 Gateway 网关 主机上 + - **默认本地：**会话、memory 文件、配置和工作区都位于 Gateway 网关主机上 （`~/.openclaw` + 你的工作区目录）。 - - **因需求而远程：**你发送给模型提供商（Anthropic/OpenAI 等）的消息会发送到 - 它们的 API，而聊天平台（WhatsApp/Telegram/Slack 等）会将消息数据存储在 - 它们的服务器上。 + - **因需要而远程：**你发送给模型提供商（Anthropic/OpenAI 等）的消息会发往 + 它们的 API，而聊天平台（WhatsApp/Telegram/Slack 等）会将消息数据存储在它们自己的 + 服务器上。 - **足迹由你控制：**使用本地模型可让提示保留在你的机器上，但渠道 - 流量仍然会经过对应渠道的服务器。 + 流量仍会经过对应渠道的服务器。 相关内容：[智能体工作区](/zh-CN/concepts/agent-workspace)、[Memory](/zh-CN/concepts/memory)。 - + 所有内容都位于 `$OPENCLAW_STATE_DIR` 下（默认：`~/.openclaw`）： | Path | 用途 | | --------------------------------------------------------------- | ------------------------------------------------------------------ | | `$OPENCLAW_STATE_DIR/openclaw.json` | 主配置（JSON5） | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 旧版 OAuth 导入（首次使用时复制到 auth profiles） | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles（OAuth、API keys，以及可选的 `keyRef`/`tokenRef`） | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 旧版 OAuth 导入（首次使用时复制到凭证配置文件中） | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | 凭证配置文件（OAuth、API 密钥以及可选的 `keyRef`/`tokenRef`） | | `$OPENCLAW_STATE_DIR/secrets.json` | `file` SecretRef 提供商的可选文件后备 secret 负载 | | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | 旧版兼容文件（静态 `api_key` 条目已清理） | | `$OPENCLAW_STATE_DIR/credentials/` | 提供商状态（例如 `whatsapp//creds.json`） | - | `$OPENCLAW_STATE_DIR/agents/` | 每智能体状态（agentDir + sessions） | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | 对话历史和状态（按智能体） | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | 会话元数据（按智能体） | + | `$OPENCLAW_STATE_DIR/agents/` | 每个智能体的状态（agentDir + sessions） | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | 对话历史和状态（按智能体划分） | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | 会话元数据（按智能体划分） | 旧版单智能体路径：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移）。 - 你的**工作区**（AGENTS.md、记忆文件、Skills 等）是分开的，并通过 `agents.defaults.workspace` 配置（默认：`~/.openclaw/workspace`）。 + 你的**工作区**（AGENTS.md、memory 文件、Skills 等）是分开的，通过 `agents.defaults.workspace` 配置（默认：`~/.openclaw/workspace`）。 这些文件位于**智能体工作区**中，而不是 `~/.openclaw`。 - - **工作区（每智能体）**：`AGENTS.md`、`SOUL.md`、`IDENTITY.md`、`USER.md`、 - `MEMORY.md`（如果不存在 `MEMORY.md`，则使用旧版回退 `memory.md`）， - `memory/YYYY-MM-DD.md`、可选的 `HEARTBEAT.md`。 - - **状态目录（`~/.openclaw`）**：配置、渠道 / 提供商状态、auth profiles、会话、日志， + - **工作区（按智能体划分）：**`AGENTS.md`、`SOUL.md`、`IDENTITY.md`、`USER.md`、 + `MEMORY.md`（若 `MEMORY.md` 不存在，则回退为旧版 `memory.md`）， + `memory/YYYY-MM-DD.md`，以及可选的 `HEARTBEAT.md`。 + - **状态目录（`~/.openclaw`）：**配置、渠道/提供商状态、凭证配置文件、会话、日志， 以及共享 Skills（`~/.openclaw/skills`）。 默认工作区是 `~/.openclaw/workspace`，可通过以下方式配置： @@ -1430,11 +1426,11 @@ x-i18n: } ``` - 如果机器人在重启后“忘记了”内容，请确认 Gateway 网关 每次启动时使用的都是同一个 - 工作区（并记住：远程模式使用的是**Gateway 网关 主机的** - 工作区，而不是你本地笔记本上的工作区）。 + 如果机器人在重启后“遗忘”，请确认 Gateway 网关每次启动时都使用的是同一个 + 工作区（并且请记住：远程模式使用的是**Gateway 网关主机的** + 工作区，而不是你本地笔记本电脑的工作区）。 - 提示：如果你想要一种持久的行为或偏好，请让机器人**将其写入 + 提示：如果你想保存一个持久行为或偏好，请让机器人**把它写入 AGENTS.md 或 MEMORY.md**，而不是依赖聊天历史。 请参阅 [智能体工作区](/zh-CN/concepts/agent-workspace) 和 [Memory](/zh-CN/concepts/memory)。 @@ -1442,11 +1438,11 @@ x-i18n: - 将你的**智能体工作区**放入一个**私有** git 仓库，并备份到某个 - 私有位置（例如 GitHub 私有仓库）。这样可以捕获记忆 + AGENTS/SOUL/USER - 文件，并让你日后可以恢复这个助手的“心智”。 + 将你的**智能体工作区**放进一个**私有** git 仓库，并将其备份到某个 + 私有位置（例如 GitHub 私有仓库）。这样可以保存 memory + AGENTS/SOUL/USER + 文件，并让你以后能够恢复助手的“心智”。 - **不要**提交 `~/.openclaw` 下的任何内容（凭证、会话、令牌或加密后的 secret 负载）。 + **不要**提交 `~/.openclaw` 下的任何内容（凭证、会话、令牌或加密的 secret 负载）。 如果你需要完整恢复，请分别备份工作区和状态目录 （请参阅上面的迁移问题）。 @@ -1455,17 +1451,17 @@ x-i18n: - 请参阅专门指南：[Uninstall](/zh-CN/install/uninstall)。 + 请参阅专门的指南：[Uninstall](/zh-CN/install/uninstall)。 - 可以。工作区是**默认 cwd** 和记忆锚点，而不是硬性的沙箱。 - 相对路径会在工作区内解析，但绝对路径仍然可以访问主机上的其他 - 位置，除非启用了沙箱隔离。如果你需要隔离，请使用 - [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing) 或每智能体沙箱设置。如果你 + 可以。工作区是默认的 **cwd** 和 memory 锚点，不是硬性沙箱。 + 相对路径会解析到工作区内，但绝对路径可以访问其他 + 主机位置，除非启用了沙箱隔离。如果你需要隔离，请使用 + [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing) 或每个智能体的沙箱设置。如果你 想让某个仓库成为默认工作目录，请将该智能体的 - `workspace` 指向仓库根目录。OpenClaw 仓库本身只是源代码；除非你有意让 - 智能体在其中工作，否则请将工作区与其分开。 + `workspace` 指向仓库根目录。OpenClaw 仓库本身只是源代码；请将 + 工作区与其分开，除非你明确希望智能体在其中工作。 示例（将仓库作为默认 cwd）： @@ -1482,14 +1478,14 @@ x-i18n: - 会话状态归**Gateway 网关 主机**所有。如果你处于远程模式，你需要关注的会话存储位于远程机器上，而不是本地笔记本。请参阅 [会话管理](/zh-CN/concepts/session)。 + 会话状态归**Gateway 网关主机**所有。如果你处于远程模式，你关心的会话存储位于远程机器上，而不是本地笔记本电脑上。请参阅 [会话管理](/zh-CN/concepts/session)。 ## 配置基础 - + OpenClaw 会从 `$OPENCLAW_CONFIG_PATH` 读取可选的 **JSON5** 配置（默认：`~/.openclaw/openclaw.json`）： ``` @@ -1501,10 +1497,10 @@ x-i18n: - 非 loopback 绑定**要求存在有效的 Gateway 网关 认证路径**。实际通常意味着： + 非 loopback 绑定**需要有效的 Gateway 网关凭证路径**。实际来说，这意味着： - - shared-secret 认证：令牌或密码 - - 位于正确配置的非 loopback 身份感知反向代理之后的 `gateway.auth.mode: "trusted-proxy"` + - shared-secret 身份验证：token 或密码 + - 位于已正确配置的非 loopback 身份感知反向代理之后的 `gateway.auth.mode: "trusted-proxy"` ```json5 { @@ -1520,24 +1516,24 @@ x-i18n: 说明： - - `gateway.remote.token` / `.password` **不会**单独启用本地 Gateway 网关 认证。 - - 只有在 `gateway.auth.*` 未设置时，本地调用路径才可以把 `gateway.remote.*` 用作回退。 - - 对于密码认证，请改为设置 `gateway.auth.mode: "password"` 加 `gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 - - 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但无法解析，则解析会以失败关闭方式处理（不会用远程回退掩盖问题）。 - - shared-secret 的 Control UI 设置通过 `connect.params.auth.token` 或 `connect.params.auth.password` 进行认证（存储在应用 / UI 设置中）。像 Tailscale Serve 或 `trusted-proxy` 这类带身份的模式则改用请求标头。避免把 shared secrets 放进 URL。 - - 当使用 `gateway.auth.mode: "trusted-proxy"` 时，同主机的 loopback 反向代理**仍然不能**满足 trusted-proxy 认证。trusted proxy 必须是一个已配置的非 loopback 来源。 + - `gateway.remote.token` / `.password` **不会**单独启用本地 Gateway 网关身份验证。 + - 只有在 `gateway.auth.*` 未设置时，本地调用路径才可以将 `gateway.remote.*` 用作回退。 + - 对于密码身份验证，请改为设置 `gateway.auth.mode: "password"` 加 `gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 + - 如果 `gateway.auth.token` / `gateway.auth.password` 是通过 SecretRef 显式配置且未解析的，解析将以失败关闭方式结束（不会由远程回退来掩盖）。 + - shared-secret Control UI 设置通过 `connect.params.auth.token` 或 `connect.params.auth.password` 进行身份验证（存储在应用/UI 设置中）。像 Tailscale Serve 或 `trusted-proxy` 这样的携带身份信息的模式则使用请求标头。避免将 shared secret 放入 URL。 + - 使用 `gateway.auth.mode: "trusted-proxy"` 时，同主机 loopback 反向代理仍然**不能**满足 trusted-proxy 身份验证要求。trusted proxy 必须是一个已配置的非 loopback 来源。 - - OpenClaw 默认强制启用 Gateway 网关 认证，包括 loopback。在正常默认路径下，这意味着令牌认证：如果没有显式配置认证路径，Gateway 网关 启动时会解析为令牌模式并自动生成一个令牌，将其保存到 `gateway.auth.token`，因此**本地 WS 客户端必须进行认证**。这样可以阻止其他本地进程调用 Gateway 网关。 + + OpenClaw 默认强制启用 Gateway 网关身份验证，包括 loopback。在正常默认路径下，这意味着 token 身份验证：如果没有配置显式的身份验证路径，Gateway 网关启动时会解析为 token 模式并自动生成一个 token，将其保存到 `gateway.auth.token`，因此**本地 WS 客户端也必须进行身份验证**。这样可以阻止其他本地进程调用 Gateway 网关。 - 如果你更喜欢其他认证方式，可以显式选择密码模式（或者对于非 loopback 的身份感知反向代理，选择 `trusted-proxy`）。如果你**确实**想要开放的 loopback，请在配置中显式设置 `gateway.auth.mode: "none"`。Doctor 随时都可以为你生成令牌：`openclaw doctor --generate-gateway-token`。 + 如果你更喜欢其他身份验证路径，可以显式选择密码模式（或者，对于非 loopback 身份感知反向代理，选择 `trusted-proxy`）。如果你**确实**想要开放的 loopback，请在配置中显式设置 `gateway.auth.mode: "none"`。Doctor 可以随时为你生成 token：`openclaw doctor --generate-gateway-token`。 - - Gateway 网关 会监视配置，并支持热重载： + + Gateway 网关会监视配置，并支持热重载： - `gateway.reload.mode: "hybrid"`（默认）：安全变更热应用，关键变更则重启 - 也支持 `hot`、`restart`、`off` @@ -1557,24 +1553,24 @@ x-i18n: } ``` - - `off`：隐藏标语文本，但保留横幅标题 / 版本行。 - - `default`：每次都使用 `All your chats, one OpenClaw.`。 - - `random`：轮换显示有趣的 / 季节性标语（默认行为）。 - - 如果你想完全不显示横幅，请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 + - `off`：隐藏标语文本，但保留横幅标题/版本行。 + - `default`：始终使用 `All your chats, one OpenClaw.`。 + - `random`：轮换显示有趣/季节性标语（默认行为）。 + - 如果你完全不想显示横幅，请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 - - `web_fetch` 无需 API key 即可使用。`web_search` 取决于你选择的 + + `web_fetch` 无需 API 密钥即可使用。`web_search` 取决于你选择的 提供商： - - Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily 等基于 API 的提供商需要它们各自的常规 API key 配置。 - - Ollama Web 搜索不需要 key，但它使用你已配置的 Ollama 主机，并要求执行 `ollama signin`。 - - DuckDuckGo 不需要 key，但它是一个非官方、基于 HTML 的集成。 - - SearXNG 不需要 key / 可自托管；配置 `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`。 + - Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily 等基于 API 的提供商需要按常规方式配置 API 密钥。 + - Ollama Web 搜索不需要密钥，但它会使用你配置的 Ollama 主机，并要求执行 `ollama signin`。 + - DuckDuckGo 不需要密钥，但它是一个非官方的基于 HTML 的集成。 + - SearXNG 不需要密钥/可自托管；请配置 `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`。 - **推荐做法：**运行 `openclaw configure --section web` 并选择一个提供商。 - 环境变量替代方式： + **推荐：**运行 `openclaw configure --section web` 并选择一个提供商。 + 环境变量替代方案： - Brave：`BRAVE_API_KEY` - Exa：`EXA_API_KEY` @@ -1617,58 +1613,68 @@ x-i18n: ``` 提供商特定的 Web 搜索配置现在位于 `plugins.entries..config.webSearch.*` 下。 - 出于兼容性考虑，旧版 `tools.web.search.*` 提供商路径目前仍可加载，但不应再用于新配置。 - Firecrawl 的 web-fetch 回退配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下。 + 旧版 `tools.web.search.*` 提供商路径目前仍会为了兼容性而加载，但不应再用于新配置。 + Firecrawl Web 抓取回退配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下。 - 说明： + 注意： - 如果你使用允许列表，请添加 `web_search`/`web_fetch`/`x_search` 或 `group:web`。 - - `web_fetch` 默认启用（除非显式禁用）。 - - 如果省略 `tools.web.fetch.provider`，OpenClaw 会从可用凭证中自动检测第一个可用的 fetch 回退提供商。当前内置提供商是 Firecrawl。 + - `web_fetch` 默认启用（除非被显式禁用）。 + - 如果省略 `tools.web.fetch.provider`，OpenClaw 会根据可用凭证自动检测第一个可用的抓取回退提供商。目前内置提供商是 Firecrawl。 - 守护进程会从 `~/.openclaw/.env`（或服务环境）读取环境变量。 - 文档：[Web tools](/zh-CN/tools/web)。 + 文档：[Web 工具](/zh-CN/tools/web)。 - `config.apply` 会替换**整个配置**。如果你传入的是部分对象，其他所有内容 + `config.apply` 会替换**整个配置**。如果你发送的是部分对象，其余所有内容 都会被移除。 - 恢复方式： + 当前 OpenClaw 会保护你免受许多意外覆盖： - - 从备份恢复（git 或复制出来的 `~/.openclaw/openclaw.json`）。 - - 如果你没有备份，请重新运行 `openclaw doctor` 并重新配置渠道 / 模型。 - - 如果这不是你预期的行为，请提交 bug，并附上你最后已知的配置或任何备份。 - - 本地编码智能体通常可以根据日志或历史记录重建出一个可工作的配置。 + - OpenClaw 自有的配置写入会在写入前验证变更后的完整配置。 + - 无效或具有破坏性的 OpenClaw 自有写入会被拒绝，并保存为 `openclaw.json.rejected.*`。 + - 如果直接编辑破坏了启动或热重载，Gateway 网关会恢复最后已知正常配置，并将被拒绝的文件保存为 `openclaw.json.clobbered.*`。 + - 恢复后，主智能体会收到启动警告，因此它不会再次盲目写入错误配置。 - 避免方式： + 恢复方法： - - 小改动请使用 `openclaw config set`。 - - 交互式编辑请使用 `openclaw configure`。 - - 当你不确定精确路径或字段结构时，先使用 `config.schema.lookup`；它会返回浅层 schema 节点以及直接子节点摘要，便于逐级深入。 - - 对于部分 RPC 编辑，请使用 `config.patch`；仅在需要完整替换配置时使用 `config.apply`。 - - 如果你是在智能体运行中使用仅限所有者的 `gateway` 工具，它仍会拒绝对 `tools.exec.ask` / `tools.exec.security` 的写入（包括会规范化到同一受保护 exec 路径的旧版 `tools.bash.*` 别名）。 + - 检查 `openclaw logs --follow` 中是否有 `Config auto-restored from last-known-good`、`Config write rejected:` 或 `config reload restored last-known-good config`。 + - 查看活动配置旁边最新的 `openclaw.json.clobbered.*` 或 `openclaw.json.rejected.*`。 + - 如果当前恢复后的活动配置可用，就保留它，然后只用 `openclaw config set` 或 `config.patch` 把你本来想修改的键复制回来。 + - 运行 `openclaw config validate` 和 `openclaw doctor`。 + - 如果你没有 last-known-good 或被拒绝的负载，请从备份恢复，或重新运行 `openclaw doctor` 并重新配置渠道/模型。 + - 如果这是意料之外的行为，请提交 bug，并附上你最后已知的配置或任何备份。 + - 本地编码智能体通常可以根据日志或历史重建一个可用配置。 - 文档：[Config](/cli/config)、[Configure](/cli/configure)、[Doctor](/zh-CN/gateway/doctor)。 + 预防方法： + + - 小改动使用 `openclaw config set`。 + - 交互式编辑使用 `openclaw configure`。 + - 当你不确定精确路径或字段形状时，先使用 `config.schema.lookup`；它会返回一个浅层 schema 节点和直接子项摘要，便于逐步深入。 + - 部分 RPC 编辑请使用 `config.patch`；仅在确实需要整体替换配置时才使用 `config.apply`。 + - 如果你在智能体运行中使用仅限 owner 的 `gateway` 工具，它仍然会拒绝写入 `tools.exec.ask` / `tools.exec.security`（包括会标准化到相同受保护 exec 路径的旧版 `tools.bash.*` 别名）。 + + 文档：[Config](/cli/config)、[Configure](/cli/configure)、[Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)、[Doctor](/zh-CN/gateway/doctor)。 - + 常见模式是**一个 Gateway 网关**（例如 Raspberry Pi）加上**节点**和**智能体**： - - **Gateway 网关（中心）：**负责渠道（Signal/WhatsApp）、路由和会话。 - - **节点（设备）：**Mac、iOS、Android 作为外设连接，并暴露本地工具（`system.run`、`canvas`、`camera`）。 - - **智能体（worker）：**拥有不同角色的独立“大脑” / 工作区（例如“Hetzner 运维”、“个人数据”）。 - - **子智能体：**当你需要并行处理时，从主智能体中启动后台工作。 - - **TUI：**连接到 Gateway 网关，并切换智能体 / 会话。 + - **Gateway 网关（中心）：**拥有渠道（Signal/WhatsApp）、路由和会话。 + - **节点（设备）：**Mac/iOS/Android 作为外围设备连接，并暴露本地工具（`system.run`、`canvas`、`camera`）。 + - **智能体（工作节点）：**用于特殊角色的独立大脑/工作区（例如“Hetzner 运维”“个人数据”）。 + - **子智能体：**当你需要并行处理时，从主智能体中生成后台工作。 + - **TUI：**连接到 Gateway 网关并切换智能体/会话。 - 文档：[Nodes](/zh-CN/nodes)、[Remote access](/zh-CN/gateway/remote)、[Multi-Agent Routing](/zh-CN/concepts/multi-agent)、[Sub-agents](/zh-CN/tools/subagents)、[TUI](/web/tui)。 + 文档：[Nodes](/zh-CN/nodes)、[远程访问](/zh-CN/gateway/remote)、[多智能体路由](/zh-CN/concepts/multi-agent)、[子智能体](/zh-CN/tools/subagents)、[TUI](/web/tui)。 - - 可以。这是一个配置项： + + 可以。这是一个配置选项： ```json5 { @@ -1681,13 +1687,13 @@ x-i18n: } ``` - 默认值为 `false`（有头模式）。在某些网站上，无头模式更容易触发反机器人检测。请参阅 [Browser](/zh-CN/tools/browser)。 + 默认值为 `false`（有界面）。某些网站在 headless 模式下更容易触发反机器人检测。请参阅 [Browser](/zh-CN/tools/browser)。 - 无头模式使用**相同的 Chromium 引擎**，适用于大多数自动化任务（表单、点击、抓取、登录）。主要区别是： + Headless 使用的是**同一个 Chromium 引擎**，适用于大多数自动化操作（表单、点击、抓取、登录）。主要区别： - - 没有可见的浏览器窗口（如果你需要视觉效果，请使用截图）。 - - 某些网站在无头模式下对自动化更严格（CAPTCHA、反机器人）。 - 例如，X/Twitter 经常会阻止无头会话。 + - 没有可见的浏览器窗口（如果你需要视觉信息，请使用截图）。 + - 某些网站在 headless 模式下对自动化更严格（CAPTCHA、反机器人）。 + 例如，X/Twitter 经常会阻止 headless 会话。 @@ -1697,11 +1703,11 @@ x-i18n: -## 远程 Gateway 网关 和节点 +## 远程 Gateway 网关和节点 - - Telegram 消息由**Gateway 网关**处理。Gateway 网关 会先运行智能体， + + Telegram 消息由 **Gateway 网关** 处理。Gateway 网关运行智能体， 然后仅在需要节点工具时，才通过 **Gateway WebSocket** 调用节点： Telegram → Gateway 网关 → 智能体 → `node.*` → 节点 → Gateway 网关 → Telegram @@ -1710,18 +1716,18 @@ x-i18n: - - 简短回答：**把你的电脑配对为一个节点**。Gateway 网关 运行在其他地方，但它可以 - 通过 Gateway WebSocket 调用你本地机器上的 `node.*` 工具（屏幕、摄像头、系统）。 + + 简短回答：**把你的电脑配对成一个节点**。Gateway 网关运行在别处，但它可以 + 通过 Gateway WebSocket 调用你本地机器上的 `node.*` 工具（屏幕、摄像头、system）。 - 典型设置： + 典型部署： - 1. 在始终在线的主机（VPS / 家用服务器）上运行 Gateway 网关。 - 2. 将 Gateway 网关 主机和你的电脑放到同一个 tailnet 中。 - 3. 确保 Gateway WS 可达（tailnet 绑定或 SSH 隧道）。 - 4. 在本地打开 macOS 应用，并以**Remote over SSH** 模式（或直接 tailnet） - 连接，以便它注册为节点。 - 5. 在 Gateway 网关 上批准该节点： + 1. 在始终在线的主机（VPS/家用服务器）上运行 Gateway 网关。 + 2. 将 Gateway 网关主机和你的电脑放到同一个 tailnet 中。 + 3. 确保 Gateway 网关 WS 可访问（tailnet bind 或 SSH 隧道）。 + 4. 在本地打开 macOS 应用，并以**通过 SSH 远程连接**模式（或直接 tailnet） + 连接，这样它就可以注册为一个节点。 + 5. 在 Gateway 网关上批准该节点： ```bash openclaw devices list @@ -1730,101 +1736,101 @@ x-i18n: 不需要单独的 TCP bridge；节点通过 Gateway WebSocket 连接。 - 安全提醒：配对一个 macOS 节点将允许在该机器上执行 `system.run`。请只 + 安全提醒：配对一个 macOS 节点会允许在那台机器上执行 `system.run`。只 配对你信任的设备，并查看 [Security](/zh-CN/gateway/security)。 - 文档：[Nodes](/zh-CN/nodes)、[Gateway protocol](/zh-CN/gateway/protocol)、[macOS remote mode](/zh-CN/platforms/mac/remote)、[Security](/zh-CN/gateway/security)。 + 文档：[Nodes](/zh-CN/nodes)、[Gateway protocol](/zh-CN/gateway/protocol)、[macOS 远程模式](/zh-CN/platforms/mac/remote)、[Security](/zh-CN/gateway/security)。 先检查基础项： - - Gateway 网关 正在运行：`openclaw gateway status` - - Gateway 网关 健康状态：`openclaw status` + - Gateway 网关正在运行：`openclaw gateway status` + - Gateway 网关健康状态：`openclaw status` - 渠道健康状态：`openclaw channels status` - 然后验证认证和路由： + 然后验证身份验证和路由： - - 如果你使用 Tailscale Serve，请确认 `gateway.auth.allowTailscale` 设置正确。 - - 如果你通过 SSH 隧道连接，请确认本地隧道已启动，并且指向正确端口。 - - 确认你的允许列表（私信或群组）包含你的账户。 + - 如果你使用 Tailscale Serve，请确保 `gateway.auth.allowTailscale` 设置正确。 + - 如果你通过 SSH 隧道连接，请确认本地隧道已建立并指向正确端口。 + - 确认你的允许列表（私信或群组）包含你的账号。 - 文档：[Tailscale](/zh-CN/gateway/tailscale)、[Remote access](/zh-CN/gateway/remote)、[Channels](/zh-CN/channels)。 + 文档：[Tailscale](/zh-CN/gateway/tailscale)、[远程访问](/zh-CN/gateway/remote)、[渠道](/zh-CN/channels)。 - 可以。虽然没有内置的“bot 对 bot”桥接，但你可以通过几种 - 可靠方式来实现： + 可以。没有内置的“bot 对 bot”桥接，但你可以通过几种 + 可靠方式把它连起来： - **最简单：**使用两个机器人都能访问的普通聊天渠道（Telegram/Slack/WhatsApp）。 - 让机器人 A 给机器人 B 发送消息，然后让机器人 B 像平常一样回复。 + **最简单的方式：**使用两个机器人都能访问的普通聊天渠道（Telegram/Slack/WhatsApp）。 + 让 Bot A 给 Bot B 发消息，然后让 Bot B 像平常一样回复。 - **CLI 桥接（通用）：**运行一个脚本，通过 + **CLI 桥接（通用）：**运行一个脚本，使用 `openclaw agent --message ... --deliver` 调用另一个 Gateway 网关，目标是另一个机器人 - 正在监听的聊天。如果其中一个机器人位于远程 VPS 上，请让你的 CLI 指向那个远程 Gateway 网关， - 可通过 SSH/Tailscale 连接（请参阅 [Remote access](/zh-CN/gateway/remote)）。 + 正在监听的聊天。如果其中一个机器人在远程 VPS 上，请将你的 CLI 指向那个远程 Gateway 网关， + 可通过 SSH/Tailscale 实现（请参阅 [远程访问](/zh-CN/gateway/remote)）。 - 示例模式（在能够访问目标 Gateway 网关 的机器上运行）： + 示例模式（从能访问目标 Gateway 网关的机器上运行）： ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - 提示：请加上一条防护规则，避免两个机器人无限循环回复（仅响应提及、渠道 + 提示：添加一个防护措施，避免两个机器人无限循环（仅响应提及、渠道 允许列表，或“不要回复机器人消息”的规则）。 - 文档：[Remote access](/zh-CN/gateway/remote)、[Agent CLI](/cli/agent)、[Agent send](/zh-CN/tools/agent-send)。 + 文档：[远程访问](/zh-CN/gateway/remote)、[Agent CLI](/cli/agent)、[智能体发送](/zh-CN/tools/agent-send)。 - - 不需要。一个 Gateway 网关 就可以托管多个智能体，每个智能体都有自己的工作区、默认模型 - 和路由。这是正常设置，而且比每个智能体都运行 - 一个 VPS 更便宜也更简单。 + + 不需要。一个 Gateway 网关可以托管多个智能体，每个智能体都有自己的工作区、默认模型 + 和路由。这是常规部署方式，也比为每个智能体 + 单独运行一个 VPS 更便宜、更简单。 - 只有当你需要硬隔离（安全边界）或非常 - 不同、且不想共享的配置时，才需要分开使用多个 VPS。否则，保留一个 Gateway 网关，并 - 使用多个智能体或子智能体即可。 + 只有在你需要硬隔离（安全边界）或完全不同且不想共享的 + 配置时，才需要单独的 VPS。否则，保持一个 Gateway 网关， + 并使用多个智能体或子智能体。 - - 有——节点是从远程 Gateway 网关 访问你笔记本电脑的一等方式，而且它们 - 提供的不仅仅是 shell 访问。Gateway 网关 运行在 macOS/Linux 上（Windows 通过 WSL2），并且 - 很轻量（小型 VPS 或 Raspberry Pi 级别的机器就足够；4 GB RAM 很充裕），因此一种常见 - 设置是始终在线的主机加上你的笔记本作为节点。 + + 有——节点是从远程 Gateway 网关访问你笔记本电脑的一等方式，而且它们 + 解锁的不只是 shell 访问。Gateway 网关运行在 macOS/Linux 上（Windows 通过 WSL2），并且 + 很轻量（小型 VPS 或 Raspberry Pi 级别的设备就足够；4 GB RAM 已经很充裕），因此一种常见的 + 部署方式是始终在线的主机加上你的笔记本电脑作为节点。 - - **不需要入站 SSH。**节点会主动连出到 Gateway WebSocket，并使用设备配对。 - - **更安全的执行控制。**`system.run` 在那台笔记本上受节点允许列表 / 审批控制。 - - **更多设备工具。**节点除了 `system.run` 外，还会暴露 `canvas`、`camera` 和 `screen`。 - - **本地浏览器自动化。**将 Gateway 网关 放在 VPS 上，但通过笔记本上的节点主机在本地运行 Chrome，或者通过 Chrome MCP 连接到主机上的本地 Chrome。 + - **不需要入站 SSH。** 节点会主动连接到 Gateway WebSocket，并使用设备配对。 + - **更安全的执行控制。** `system.run` 在该笔记本电脑上受节点允许列表/审批控制。 + - **更多设备工具。** 节点除了 `system.run` 外，还会暴露 `canvas`、`camera` 和 `screen`。 + - **本地浏览器自动化。** 保持 Gateway 网关运行在 VPS 上，但通过笔记本电脑上的节点主机在本地运行 Chrome，或者通过 Chrome MCP 附加到主机上的本地 Chrome。 - SSH 适合临时的 shell 访问，但对于持续性的智能体工作流和 - 设备自动化，节点更简单。 + 对于临时的 shell 访问，SSH 也可以，但对于持续的智能体工作流和 + 设备自动化来说，节点更简单。 文档：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)、[Browser](/zh-CN/tools/browser)。 - - 不会。除非你有意运行隔离配置文件（请参阅 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)），否则每台主机上应该只运行**一个 Gateway 网关**。节点是连接到 - Gateway 网关 的外设（iOS/Android 节点，或菜单栏应用中的 macOS“节点模式”）。有关无头节点 + + 不会。每台主机上通常只应运行**一个 Gateway 网关**，除非你有意运行隔离的 profile（参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)）。节点是连接 + 到 Gateway 网关的外围设备（iOS/Android 节点，或菜单栏应用中的 macOS“节点模式”）。有关无头节点 主机和 CLI 控制，请参阅 [Node host CLI](/cli/node)。 - 对 `gateway`、`discovery` 和 `canvasHost` 的更改需要完整重启。 + 对 `gateway`、`discovery` 和 `canvasHost` 的更改需要执行完整重启。 - + 有。 - - `config.schema.lookup`：在写入前检查某个配置子树，包括其浅层 schema 节点、匹配的 UI 提示和直接子节点摘要 - - `config.get`：获取当前快照 + 哈希 - - `config.patch`：安全的部分更新（大多数 RPC 编辑的首选）；在可能时热重载，必要时重启 - - `config.apply`：验证并替换完整配置；在可能时热重载，必要时重启 - - 仅限所有者的 `gateway` 运行时工具仍然拒绝重写 `tools.exec.ask` / `tools.exec.security`；旧版 `tools.bash.*` 别名会规范化到相同的受保护 exec 路径 + - `config.schema.lookup`：在写入前检查某个配置子树及其浅层 schema 节点、匹配的 UI 提示和直接子项摘要 + - `config.get`：获取当前快照 + hash + - `config.patch`：安全的部分更新（大多数 RPC 编辑的首选）；在可能时热重载，在需要时重启 + - `config.apply`：验证并替换完整配置；在可能时热重载，在需要时重启 + - 仅限 owner 的 `gateway` 运行时工具仍然拒绝重写 `tools.exec.ask` / `tools.exec.security`；旧版 `tools.bash.*` 别名会标准化到同一组受保护的 exec 路径 @@ -1836,7 +1842,7 @@ x-i18n: } ``` - 这会设置你的工作区，并限制哪些人可以触发机器人。 + 这会设置你的工作区，并限制谁可以触发机器人。 @@ -1853,44 +1859,44 @@ x-i18n: 2. **在你的 Mac 上安装并登录** - 使用 Tailscale 应用，并登录到同一个 tailnet。 3. **启用 MagicDNS（推荐）** - - 在 Tailscale 管理控制台中启用 MagicDNS，这样 VPS 就会有一个稳定的名称。 + - 在 Tailscale 管理控制台中启用 MagicDNS，这样 VPS 就会有一个稳定名称。 4. **使用 tailnet 主机名** - SSH：`ssh user@your-vps.tailnet-xxxx.ts.net` - - Gateway WS：`ws://your-vps.tailnet-xxxx.ts.net:18789` + - Gateway 网关 WS：`ws://your-vps.tailnet-xxxx.ts.net:18789` - 如果你想在不使用 SSH 的情况下使用 Control UI，请在 VPS 上使用 Tailscale Serve： + 如果你希望在不使用 SSH 的情况下访问 Control UI，请在 VPS 上使用 Tailscale Serve： ```bash openclaw gateway --tailscale serve ``` - 这会让 Gateway 网关 保持绑定到 loopback，并通过 Tailscale 暴露 HTTPS。请参阅 [Tailscale](/zh-CN/gateway/tailscale)。 + 这会让 Gateway 网关保持绑定到 loopback，并通过 Tailscale 暴露 HTTPS。请参阅 [Tailscale](/zh-CN/gateway/tailscale)。 - Serve 暴露的是**Gateway 网关 Control UI + WS**。节点通过同一个 Gateway WS 端点连接。 + Serve 会暴露 **Gateway 网关 Control UI + WS**。节点通过同一个 Gateway 网关 WS 端点连接。 - 推荐设置： + 推荐部署： 1. **确保 VPS 和 Mac 位于同一个 tailnet 中**。 2. **在远程模式下使用 macOS 应用**（SSH 目标可以是 tailnet 主机名）。 - 应用会隧道转发 Gateway 端口，并作为节点连接。 - 3. **在 Gateway 网关 上批准该节点**： + 应用会为 Gateway 网关端口建立隧道，并作为节点进行连接。 + 3. **在 Gateway 网关上批准该节点**： ```bash openclaw devices list openclaw devices approve ``` - 文档：[Gateway protocol](/zh-CN/gateway/protocol)、[设备发现](/zh-CN/gateway/discovery)、[macOS remote mode](/zh-CN/platforms/mac/remote)。 + 文档：[Gateway protocol](/zh-CN/gateway/protocol)、[设备发现](/zh-CN/gateway/discovery)、[macOS 远程模式](/zh-CN/platforms/mac/remote)。 - - 如果你只需要在第二台笔记本上使用**本地工具**（屏幕 / 摄像头 / exec），就把它添加为 - **节点**。这样可以保留单个 Gateway 网关，并避免重复配置。当前本地节点工具 - 仅支持 macOS，但我们计划将其扩展到其他操作系统。 + + 如果你只需要第二台笔记本电脑上的**本地工具**（屏幕/摄像头/exec），就把它添加为 + **节点**。这样可以保持单个 Gateway 网关，并避免重复配置。本地节点工具 + 目前仅支持 macOS，但我们计划将其扩展到其他操作系统。 只有在你需要**硬隔离**或两个完全独立的机器人时，才安装第二个 Gateway 网关。 @@ -1899,14 +1905,14 @@ x-i18n: -## 环境变量和 .env 加载 +## 环境变量和 `.env` 加载 - OpenClaw 会从父进程（shell、launchd/systemd、CI 等）读取环境变量，并另外加载： + OpenClaw 会从父进程（shell、launchd/systemd、CI 等）读取环境变量，并额外加载： - 当前工作目录中的 `.env` - - `~/.openclaw/.env`（即 `$OPENCLAW_STATE_DIR/.env`）中的全局回退 `.env` + - 来自 `~/.openclaw/.env`（也就是 `$OPENCLAW_STATE_DIR/.env`）的全局回退 `.env` 这两个 `.env` 文件都不会覆盖现有环境变量。 @@ -1925,11 +1931,11 @@ x-i18n: - + 两个常见修复方式： - 1. 把缺失的 key 放进 `~/.openclaw/.env`，这样即使服务没有继承你的 shell 环境，也能被读取。 - 2. 启用 shell 导入（自选的便利功能）： + 1. 将缺失的键放到 `~/.openclaw/.env` 中，这样即使服务没有继承你的 shell 环境，也能读取到它们。 + 2. 启用 shell 导入（选择性启用的便捷功能）： ```json5 { @@ -1942,35 +1948,35 @@ x-i18n: } ``` - 这会运行你的登录 shell，并仅导入缺失的预期键名（永不覆盖）。对应环境变量： + 这会运行你的登录 shell，并且只导入缺失的预期键名（永不覆盖）。对应环境变量： `OPENCLAW_LOAD_SHELL_ENV=1`、`OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`。 - - `openclaw models status` 报告的是是否启用了**shell 环境导入**。“Shell env: off” - **并不**意味着你的环境变量缺失——它只是表示 OpenClaw 不会自动加载 + + `openclaw models status` 报告的是**shell 环境导入**是否已启用。“Shell env: off” + **不**表示你的环境变量缺失——它只是表示 OpenClaw 不会自动加载 你的登录 shell。 - 如果 Gateway 网关 作为服务运行（launchd/systemd），它不会继承你的 shell - 环境。可用以下方式修复： + 如果 Gateway 网关作为服务运行（launchd/systemd），它不会继承你的 shell + 环境。可通过以下任一方式修复： - 1. 将令牌放入 `~/.openclaw/.env`： + 1. 将 token 放入 `~/.openclaw/.env`： ``` COPILOT_GITHUB_TOKEN=... ``` 2. 或启用 shell 导入（`env.shellEnv.enabled: true`）。 - 3. 或把它添加到配置中的 `env` 块（仅在缺失时应用）。 + 3. 或将其添加到配置的 `env` 块中（仅在缺失时应用）。 - 然后重启 Gateway 网关 并重新检查： + 然后重启 Gateway 网关并重新检查： ```bash openclaw models status ``` - Copilot 令牌会从 `COPILOT_GITHUB_TOKEN` 读取（也支持 `GH_TOKEN` / `GITHUB_TOKEN`）。 + Copilot token 会从 `COPILOT_GITHUB_TOKEN` 读取（也支持 `GH_TOKEN` / `GITHUB_TOKEN`）。 请参阅 [/concepts/model-providers](/zh-CN/concepts/model-providers) 和 [/environment](/zh-CN/help/environment)。 @@ -1980,14 +1986,14 @@ x-i18n: - 发送单独的一条 `/new` 或 `/reset` 消息。请参阅 [会话管理](/zh-CN/concepts/session)。 + 发送 `/new` 或 `/reset` 作为独立消息。请参阅 [会话管理](/zh-CN/concepts/session)。 - - 会话可以在 `session.idleMinutes` 后过期，但这**默认是关闭的**（默认值为 **0**）。 - 将其设置为正数即可启用空闲过期。启用后，空闲期后的**下一条** + + 会话可以在 `session.idleMinutes` 之后过期，但这**默认是禁用的**（默认值为 **0**）。 + 将其设置为正值即可启用空闲过期。启用后，空闲期后的**下一条** 消息会为该聊天键启动一个新的会话 ID。 - 这不会删除转录内容——它只是开始一个新会话。 + 这不会删除转录——它只是开始一个新会话。 ```json5 { @@ -1999,34 +2005,34 @@ x-i18n: - + 可以，通过**多智能体路由**和**子智能体**。你可以创建一个协调者 - 智能体和若干个拥有各自工作区和模型的工作智能体。 + 智能体，再创建多个拥有各自工作区和模型的工作智能体。 - 不过，最好把这看作是一个**有趣的实验**。它非常耗费令牌，而且通常 - 不如使用一个机器人配合多个独立会话来得高效。我们更典型设想的模型是： - 你与一个机器人对话，用不同会话来处理并行工作。该 - 机器人也可以在需要时启动子智能体。 + 也就是说，最好把这看作一种**有趣的实验**。它会消耗大量 token，而且通常 + 不如使用一个机器人配合多个独立会话高效。我们更典型设想的模式是： + 你与一个机器人交流，并用不同会话并行完成工作。这个 + 机器人也可以在需要时生成子智能体。 - 文档：[多智能体路由](/zh-CN/concepts/multi-agent)、[Sub-agents](/zh-CN/tools/subagents)、[Agents CLI](/cli/agents)。 + 文档：[多智能体路由](/zh-CN/concepts/multi-agent)、[子智能体](/zh-CN/tools/subagents)、[Agents CLI](/cli/agents)。 - - 会话上下文受模型窗口限制。长聊天、大量工具输出或过多 + + 会话上下文受模型上下文窗口限制。长聊天、大量工具输出或许多 文件都可能触发压缩或截断。 - 有帮助的做法： + 有帮助的方法： - - 让机器人总结当前状态并写入文件。 - - 在长任务前使用 `/compact`，在切换主题时使用 `/new`。 + - 让机器人总结当前状态并将其写入文件。 + - 在长任务前使用 `/compact`，切换话题时使用 `/new`。 - 将重要上下文保存在工作区中，并让机器人重新读取。 - - 对于长时间或并行任务使用子智能体，这样主聊天会保持更小。 - - 如果这种情况经常发生，请选择具有更大上下文窗口的模型。 + - 对于长任务或并行任务，使用子智能体，这样主聊天会保持更小。 + - 如果这种情况经常发生，请选择上下文窗口更大的模型。 - + 使用 reset 命令： ```bash @@ -2047,24 +2053,24 @@ x-i18n: 说明： - - 如果检测到现有配置，新手引导也会提供**重置**选项。请参阅 [新手引导（CLI）](/zh-CN/start/wizard)。 - - 如果你使用了 profiles（`--profile` / `OPENCLAW_PROFILE`），请重置每个状态目录（默认是 `~/.openclaw-`）。 - - 开发重置：`openclaw gateway --dev --reset`（仅开发模式；会清除开发配置 + 凭证 + 会话 + 工作区）。 + - 如果新手引导检测到现有配置，也会提供**重置**选项。请参阅 [设置向导（CLI）](/zh-CN/start/wizard)。 + - 如果你使用了 profile（`--profile` / `OPENCLAW_PROFILE`），请重置每个状态目录（默认是 `~/.openclaw-`）。 + - 开发重置：`openclaw gateway --dev --reset`（仅限开发；会清空开发配置 + 凭证 + 会话 + 工作区）。 - - 使用以下任一方法： + + 使用以下任一方式： - - **压缩**（保留对话，但总结较早的轮次）： + - **压缩**（保留对话，但总结较早轮次）： ``` /compact ``` - 或使用 `/compact ` 来指导总结内容。 + 或使用 `/compact ` 来指导摘要内容。 - - **重置**（为相同聊天键创建全新的会话 ID）： + - **重置**（为相同聊天键生成新的会话 ID）： ``` /new @@ -2073,24 +2079,24 @@ x-i18n: 如果这种情况持续发生： - - 启用或调整**会话修剪**（`agents.defaults.contextPruning`）以裁剪旧工具输出。 - - 使用具有更大上下文窗口的模型。 + - 启用或调整**会话修剪**（`agents.defaults.contextPruning`）以裁剪旧的工具输出。 + - 使用上下文窗口更大的模型。 - 文档：[Compaction](/zh-CN/concepts/compaction)、[Session pruning](/zh-CN/concepts/session-pruning)、[会话管理](/zh-CN/concepts/session)。 + 文档：[压缩](/zh-CN/concepts/compaction)、[会话修剪](/zh-CN/concepts/session-pruning)、[会话管理](/zh-CN/concepts/session)。 - 这是一个提供商校验错误：模型发出了一个 `tool_use` 块，但缺少必需的 - `input`。这通常意味着会话历史已过时或损坏（常见于长线程 - 或工具 / schema 更改之后）。 + 这是一个提供商验证错误：模型发出了一个缺少必需 + `input` 的 `tool_use` 块。通常这意味着会话历史已过时或已损坏（常见于长线程 + 或工具/schema 变更之后）。 - 修复方法：使用 `/new` 开始一个新会话（单独发送一条消息）。 + 修复方法：使用 `/new`（独立消息）开始一个新会话。 - - Heartbeat 默认每 **30m** 运行一次（使用 OAuth 认证时为 **1h**）。你可以调整或禁用它们： + + Heartbeat 默认每 **30m** 运行一次（使用 OAuth 凭证时为 **1h**）。可进行调整或禁用： ```json5 { @@ -2104,17 +2110,17 @@ x-i18n: } ``` - 如果 `HEARTBEAT.md` 存在但实际上是空的（只有空行和 Markdown - 标题，例如 `# Heading`），OpenClaw 会跳过 Heartbeat 运行以节省 API 调用。 - 如果文件不存在，Heartbeat 仍会运行，并由模型决定要做什么。 + 如果 `HEARTBEAT.md` 存在，但实际上为空（只有空行和 markdown + 标题，如 `# Heading`），OpenClaw 会跳过 Heartbeat 运行以节省 API 调用。 + 如果该文件不存在，Heartbeat 仍会运行，并由模型决定执行什么操作。 - 每智能体覆盖使用 `agents.list[].heartbeat`。文档：[Heartbeat](/zh-CN/gateway/heartbeat)。 + 每个智能体的覆盖项使用 `agents.list[].heartbeat`。文档：[Heartbeat](/zh-CN/gateway/heartbeat)。 - - 不需要。OpenClaw 运行在**你自己的账号**上，所以如果你在群组里，OpenClaw 就能看到它。 - 默认情况下，在你允许发送者之前，群组回复会被阻止（`groupPolicy: "allowlist"`）。 + + 不需要。OpenClaw 运行在**你自己的账号**上，所以只要你在群组里，OpenClaw 就能看到它。 + 默认情况下，群组回复会被阻止，直到你允许发送者（`groupPolicy: "allowlist"`）。 如果你只想让**你自己**能够触发群组回复： @@ -2132,7 +2138,7 @@ x-i18n: - 方式 1（最快）：跟踪日志，并在群组里发送一条测试消息： + 方式 1（最快）：查看日志尾部，并在群组里发送一条测试消息： ```bash openclaw logs --follow --json @@ -2141,7 +2147,7 @@ x-i18n: 查找以 `@g.us` 结尾的 `chatId`（或 `from`），例如： `1234567890-1234567890@g.us`。 - 方式 2（如果已配置 / 已加入允许列表）：从配置中列出群组： + 方式 2（如果已经配置/加入允许列表）：从配置中列出群组： ```bash openclaw directory groups list --channel whatsapp @@ -2151,47 +2157,47 @@ x-i18n: - + 两个常见原因： - - 提及门控是开启的（默认）。你必须 @ 提及机器人（或匹配 `mentionPatterns`）。 - - 你配置了 `channels.whatsapp.groups`，但没有包含 `"*"`，且该群组不在允许列表中。 + - 提及门控已开启（默认）。你必须 @ 提及机器人（或匹配 `mentionPatterns`）。 + - 你配置了 `channels.whatsapp.groups`，但没有包含 `"*"`，并且该群组不在允许列表中。 - 请参阅 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 + 请参阅 [Groups](/zh-CN/channels/groups) 和 [群组消息](/zh-CN/channels/group-messages)。 - - 直接聊天默认会折叠到主会话。群组 / 渠道拥有各自的会话键，而 Telegram 话题 / Discord 线程则是独立会话。请参阅 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 + + 直接聊天默认会折叠到主会话。群组/渠道有它们自己的会话键，而 Telegram 话题 / Discord 线程则是独立会话。请参阅 [Groups](/zh-CN/channels/groups) 和 [群组消息](/zh-CN/channels/group-messages)。 - 没有硬性限制。几十个（甚至上百个）都没问题，但要注意： + 没有硬性限制。几十个（甚至几百个）都没问题，但要注意： - **磁盘增长：**会话 + 转录内容位于 `~/.openclaw/agents//sessions/` 下。 - - **令牌成本：**智能体越多，并发模型使用就越多。 - - **运维开销：**每智能体的 auth profiles、工作区和渠道路由。 + - **token 成本：**更多智能体意味着更多并发模型使用。 + - **运维开销：**每个智能体的凭证配置文件、工作区和渠道路由。 提示： - 每个智能体保留一个**活动**工作区（`agents.defaults.workspace`）。 - - 如果磁盘增长过快，清理旧会话（删除 JSONL 或存储条目）。 - - 使用 `openclaw doctor` 发现散落的工作区和 profile 不匹配问题。 + - 如果磁盘增长，修剪旧会话（删除 JSONL 或存储条目）。 + - 使用 `openclaw doctor` 发现零散工作区和 profile 不匹配问题。 - - 可以。使用**多智能体路由**来运行多个相互隔离的智能体，并按 - 渠道 / 账户 / peer 路由入站消息。Slack 作为渠道受支持，也可以绑定到特定智能体。 + + 可以。使用**多智能体路由**运行多个隔离的智能体，并按 + 渠道/账号/peer 路由入站消息。Slack 作为渠道受支持，也可以绑定到特定智能体。 - 浏览器访问功能很强，但并不等于“能做到人类能做的一切”——反机器人机制、CAPTCHA 和 MFA - 仍然可能阻止自动化。要获得最可靠的浏览器控制，请在主机上使用本地 Chrome MCP， + 浏览器访问能力很强，但并不等于“做人类能做的所有事情”——反机器人机制、CAPTCHA 和 MFA + 仍然可能阻止自动化。若要获得最可靠的浏览器控制，请在主机上使用本地 Chrome MCP， 或在实际运行浏览器的机器上使用 CDP。 - 最佳实践设置： + 最佳实践部署： - - 始终在线的 Gateway 网关 主机（VPS / Mac mini）。 - - 每个角色一个智能体（绑定）。 + - 始终在线的 Gateway 网关主机（VPS/Mac mini）。 + - 每个角色一个智能体（bindings）。 - 将 Slack 渠道绑定到这些智能体。 - 在需要时通过 Chrome MCP 或节点使用本地浏览器。 @@ -2205,91 +2211,90 @@ x-i18n: - OpenClaw 的默认模型就是你设置在这里的内容： + OpenClaw 的默认模型就是你设置在这里的值： ``` agents.defaults.model.primary ``` - 模型使用 `provider/model` 的形式引用（例如：`openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 id 唯一匹配的已配置提供商，最后才会退回到已配置默认提供商这一已弃用的兼容路径。如果该提供商不再暴露已配置的默认模型，OpenClaw 会退回到第一个已配置的提供商 / 模型，而不是继续使用一个陈旧、已移除提供商的默认值。你仍然应该**显式**设置 `provider/model`。 + 模型使用 `provider/model` 形式引用（例如：`openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 id 匹配的唯一已配置提供商，只有在这之后才会回退到已配置的默认提供商这一已弃用的兼容路径。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是继续使用过时的已移除提供商默认值。你仍然应该**显式**设置 `provider/model`。 - - **推荐默认值：**使用你提供商栈中可用的最强、最新一代模型。 - **对于启用了工具或接收不可信输入的智能体：**优先考虑模型能力，而不是成本。 - **对于日常 / 低风险聊天：**使用更便宜的回退模型，并按智能体角色进行路由。 + + **推荐默认值：**使用你当前提供商栈中最新一代、能力最强的模型。 + **对于启用了工具或会接收不可信输入的智能体：**优先考虑模型能力，而不是成本。 + **对于日常/低风险聊天：**使用更便宜的后备模型，并按智能体角色进行路由。 - MiniMax 有单独文档：[MiniMax](/zh-CN/providers/minimax) 和 + MiniMax 有自己的文档：[MiniMax](/zh-CN/providers/minimax) 和 [Local models](/zh-CN/gateway/local-models)。 - 经验法则：对于高风险工作，使用你**负担得起的最佳模型**；对于日常 - 聊天或摘要，使用更便宜的模型。你可以按智能体路由模型，并使用子智能体来 - 并行处理长任务（每个子智能体都会消耗令牌）。请参阅 [Models](/zh-CN/concepts/models) 和 - [Sub-agents](/zh-CN/tools/subagents)。 + 经验法则：对于高风险工作，使用你**负担得起的最佳模型**；对于常规聊天或摘要， + 使用更便宜的模型。你可以按智能体路由模型，并使用子智能体来 + 并行处理长任务（每个子智能体都会消耗 token）。请参阅 [Models](/zh-CN/concepts/models) 和 + [子智能体](/zh-CN/tools/subagents)。 - 强烈警告：较弱或过度量化的模型更容易受到提示 - 注入和不安全行为的影响。请参阅 [Security](/zh-CN/gateway/security)。 + 强烈警告：较弱/过度量化的模型更容易受到 prompt + injection 和不安全行为的影响。请参阅 [Security](/zh-CN/gateway/security)。 - 更多背景：[Models](/zh-CN/concepts/models)。 + 更多背景信息：[Models](/zh-CN/concepts/models)。 - 使用**模型命令**，或仅编辑**模型**字段。避免完整替换配置。 + 使用**模型命令**，或者只编辑**模型**字段。避免整份配置替换。 - 安全的选项： + 安全选项： - - 在聊天中使用 `/model`（快速，按会话） + - 在聊天中使用 `/model`（快速、按会话） - `openclaw models set ...`（只更新模型配置） - `openclaw configure --section model`（交互式） - 编辑 `~/.openclaw/openclaw.json` 中的 `agents.defaults.model` - 除非你确实打算替换整个配置，否则避免对部分对象使用 `config.apply`。 - 对于 RPC 编辑，先用 `config.schema.lookup` 检查，并优先使用 `config.patch`。 - lookup 载荷会给你规范化路径、浅层 schema 文档 / 约束以及直接子节点摘要， - 便于进行部分更新。 + 除非你确实打算替换整个配置，否则请避免用部分对象调用 `config.apply`。 + 对于 RPC 编辑，请先用 `config.schema.lookup` 检查，并优先使用 `config.patch`。lookup 负载会提供规范化路径、浅层 schema 文档/约束以及直接子项摘要， + 以便进行部分更新。 如果你确实覆盖了配置，请从备份恢复，或重新运行 `openclaw doctor` 进行修复。 文档：[Models](/zh-CN/concepts/models)、[Configure](/cli/configure)、[Config](/cli/config)、[Doctor](/zh-CN/gateway/doctor)。 - - 可以。Ollama 是使用本地模型最简单的方式。 + + 可以。Ollama 是使用本地模型的最简单路径。 最快设置方式： 1. 从 `https://ollama.com/download` 安装 Ollama 2. 拉取一个本地模型，例如 `ollama pull gemma4` - 3. 如果你还想使用云模型，运行 `ollama signin` + 3. 如果你还想使用云端模型，请运行 `ollama signin` 4. 运行 `openclaw onboard` 并选择 `Ollama` 5. 选择 `Local` 或 `Cloud + Local` 说明： - - `Cloud + Local` 会同时提供云模型和你的本地 Ollama 模型 - - 像 `kimi-k2.5:cloud` 这样的云模型不需要本地拉取 - - 若要手动切换，请使用 `openclaw models list` 和 `openclaw models set ollama/` + - `Cloud + Local` 会同时提供云端模型和你的本地 Ollama 模型 + - `kimi-k2.5:cloud` 这样的云端模型不需要本地拉取 + - 如需手动切换，使用 `openclaw models list` 和 `openclaw models set ollama/` - 安全提示：较小或高度量化的模型更容易受到提示 - 注入影响。对于任何可以使用工具的机器人，我们强烈建议使用**大模型**。 - 如果你仍然想使用小模型，请启用沙箱隔离并使用严格的工具允许列表。 + 安全说明：较小或高度量化的模型更容易受到 prompt + injection 的影响。对于任何可以使用工具的机器人，我们强烈建议使用**大型模型**。 + 如果你仍然想使用小模型，请启用沙箱隔离和严格的工具允许列表。 文档：[Ollama](/zh-CN/providers/ollama)、[Local models](/zh-CN/gateway/local-models)、 - [Model providers](/zh-CN/concepts/model-providers)、[Security](/zh-CN/gateway/security)、 + [模型提供商](/zh-CN/concepts/model-providers)、[Security](/zh-CN/gateway/security)、 [沙箱隔离](/zh-CN/gateway/sandboxing)。 - - 这些部署可能不同，也可能随时间变化；没有固定的提供商推荐。 - - 使用 `openclaw models status` 检查每个 Gateway 网关 上当前的运行时设置。 - - 对于安全敏感 / 启用工具的智能体，请使用可用的最强、最新一代模型。 + - 这些部署可能不同，并且会随时间变化；没有固定的提供商推荐。 + - 请在每个 Gateway 网关上使用 `openclaw models status` 检查当前运行时设置。 + - 对于安全敏感/启用了工具的智能体，请使用当前可用的最新一代最强模型。 - - 使用 `/model` 命令，作为单独的一条消息发送： + + 将 `/model` 命令作为独立消息发送： ``` /model sonnet @@ -2301,56 +2306,56 @@ x-i18n: /model gemini-flash-lite ``` - 这些是内置别名。你也可以通过 `agents.defaults.models` 添加自定义别名。 + 这些是内置别名。可通过 `agents.defaults.models` 添加自定义别名。 你可以使用 `/model`、`/model list` 或 `/model status` 列出可用模型。 - `/model`（以及 `/model list`）会显示一个紧凑的编号选择器。通过数字选择： + `/model`（以及 `/model list`）会显示一个紧凑的编号选择器。按编号选择： ``` /model 3 ``` - 你还可以为提供商强制指定一个特定的认证配置文件（按会话）： + 你还可以为该提供商强制指定特定凭证配置文件（按会话）： ``` /model opus@anthropic:default /model opus@anthropic:work ``` - 提示：`/model status` 会显示当前活动的是哪个智能体、正在使用哪个 `auth-profiles.json` 文件，以及接下来会尝试哪个认证配置文件。 - 如果可用，它还会显示已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。 + 提示：`/model status` 会显示当前激活的是哪个智能体、正在使用哪个 `auth-profiles.json` 文件，以及下一步将尝试哪个凭证配置文件。 + 它还会在可用时显示已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。 - **如何取消固定我用 @profile 设置的 profile？** + **如何取消固定我用 `@profile` 设置的 profile？** - 重新运行 `/model`，**不要**带 `@profile` 后缀： + 重新运行 `/model`，但**不要**带 `@profile` 后缀： ``` /model anthropic/claude-opus-4-6 ``` - 如果你想回到默认值，就从 `/model` 中选择默认项（或发送 `/model `）。 - 使用 `/model status` 确认当前活动的是哪个认证配置文件。 + 如果你想恢复默认值，请从 `/model` 中选择它（或发送 `/model `）。 + 使用 `/model status` 确认当前激活的是哪个凭证配置文件。 - 可以。设置一个为默认值，并在需要时切换： + 可以。将一个设为默认值，并在需要时切换： - - **快速切换（按会话）：**日常任务使用 `/model gpt-5.4`，使用 Codex OAuth 编码时切换到 `/model openai-codex/gpt-5.4`。 + - **快速切换（按会话）：**日常任务使用 `/model gpt-5.4`，编码时使用 `/model openai-codex/gpt-5.4` 并通过 Codex OAuth。 - **默认值 + 切换：**将 `agents.defaults.model.primary` 设置为 `openai/gpt-5.4`，然后在编码时切换到 `openai-codex/gpt-5.4`（或者反过来）。 - - **子智能体：**将编码任务路由到使用不同默认模型的子智能体。 + - **子智能体：**将编码任务路由到默认模型不同的子智能体。 请参阅 [Models](/zh-CN/concepts/models) 和 [Slash commands](/zh-CN/tools/slash-commands)。 - 你可以使用会话级切换，或配置默认值： + 可使用会话切换或配置默认值： - **按会话：**当会话正在使用 `openai/gpt-5.4` 或 `openai-codex/gpt-5.4` 时，发送 `/fast on`。 - - **按模型默认值：**将 `agents.defaults.models["openai/gpt-5.4"].params.fastMode` 设为 `true`。 - - **Codex OAuth 同样适用：**如果你也使用 `openai-codex/gpt-5.4`，请在那里设置相同标志。 + - **按模型默认值：**将 `agents.defaults.models["openai/gpt-5.4"].params.fastMode` 设置为 `true`。 + - **Codex OAuth 也一样：**如果你还使用 `openai-codex/gpt-5.4`，也请为它设置相同标志。 示例： @@ -2375,39 +2380,39 @@ x-i18n: } ``` - 对于 OpenAI，fast mode 会在受支持的原生 Responses 请求中映射为 `service_tier = "priority"`。会话级 `/fast` 覆盖优先于配置默认值。 + 对于 OpenAI，fast mode 会在受支持的原生 Responses 请求上映射为 `service_tier = "priority"`。会话中的 `/fast` 覆盖优先于配置默认值。 请参阅 [Thinking and fast mode](/zh-CN/tools/thinking) 和 [OpenAI fast mode](/zh-CN/providers/openai#openai-fast-mode)。 - - 如果设置了 `agents.defaults.models`，它就会成为 `/model` 和任何 - 会话覆盖的**允许列表**。选择一个不在该列表中的模型会返回： + + 如果设置了 `agents.defaults.models`，它就会成为 `/model` 以及任何 + 会话覆盖的**允许列表**。选择不在该列表中的模型会返回： ``` Model "provider/model" is not allowed. Use /model to list available models. ``` - 该错误会**替代**正常回复返回。修复方式：将该模型加入 - `agents.defaults.models`，删除该允许列表，或从 `/model list` 中选择一个模型。 + 该错误会**替代**正常回复返回。修复方法：将该模型添加到 + `agents.defaults.models`、移除允许列表，或从 `/model list` 中选择一个模型。 - 这意味着**提供商未配置**（未找到 MiniMax 提供商配置或认证 - 配置文件），因此无法解析该模型。 + 这意味着**提供商未配置**（找不到 MiniMax 提供商配置或凭证 + 配置文件），所以无法解析该模型。 修复清单： - 1. 升级到当前 OpenClaw 版本（或从源码 `main` 运行），然后重启 Gateway 网关。 - 2. 确保已配置 MiniMax（通过向导或 JSON），或者存在 MiniMax 认证， - 位于环境变量 / 认证配置文件中，以便注入匹配的提供商 + 1. 升级到当前的 OpenClaw 版本（或直接从源码 `main` 运行），然后重启 Gateway 网关。 + 2. 确保已配置 MiniMax（通过向导或 JSON），或者环境变量/凭证配置文件中存在 MiniMax 凭证， + 这样才能注入匹配的提供商 （`minimax` 使用 `MINIMAX_API_KEY`，`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或已存储的 MiniMax OAuth）。 - 3. 对你的认证路径使用精确的模型 id（区分大小写）： - API key 设置使用 `minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`， - OAuth 设置使用 `minimax-portal/MiniMax-M2.7` / + 3. 针对你的凭证路径使用精确的模型 id（区分大小写）： + API 密钥方式使用 `minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`， + OAuth 方式使用 `minimax-portal/MiniMax-M2.7` / `minimax-portal/MiniMax-M2.7-highspeed`。 4. 运行： @@ -2415,17 +2420,17 @@ x-i18n: openclaw models list ``` - 并从列表中选择一个（或在聊天中使用 `/model list`）。 + 并从列表中选择（或在聊天中使用 `/model list`）。 请参阅 [MiniMax](/zh-CN/providers/minimax) 和 [Models](/zh-CN/concepts/models)。 - + 可以。将 **MiniMax 设为默认值**，并在需要时**按会话**切换模型。 - 回退适用于**错误**，而不是“困难任务”，所以请使用 `/model` 或单独的智能体。 + 后备仅用于**错误**，而不是“困难任务”，因此请使用 `/model` 或单独的智能体。 - **方案 A：按会话切换** + **选项 A：按会话切换** ```json5 { @@ -2448,18 +2453,18 @@ x-i18n: /model gpt ``` - **方案 B：分离智能体** + **选项 B：拆分为不同智能体** - 智能体 A 默认：MiniMax - 智能体 B 默认：OpenAI - 按智能体路由，或使用 `/agent` 切换 - 文档：[Models](/zh-CN/concepts/models)、[Multi-Agent Routing](/zh-CN/concepts/multi-agent)、[MiniMax](/zh-CN/providers/minimax)、[OpenAI](/zh-CN/providers/openai)。 + 文档：[Models](/zh-CN/concepts/models)、[多智能体路由](/zh-CN/concepts/multi-agent)、[MiniMax](/zh-CN/providers/minimax)、[OpenAI](/zh-CN/providers/openai)。 - 是。OpenClaw 内置了一些默认简写（仅当模型存在于 `agents.defaults.models` 中时才会生效）： + 是的。OpenClaw 自带一些默认简写（仅当模型存在于 `agents.defaults.models` 中时才会应用）： - `opus` → `anthropic/claude-opus-4-6` - `sonnet` → `anthropic/claude-sonnet-4-6` @@ -2470,11 +2475,11 @@ x-i18n: - `gemini-flash` → `google/gemini-3-flash-preview` - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` - 如果你使用了同名自定义别名，则以你的值为准。 + 如果你设置了同名自定义别名，则以你的值为准。 - + 别名来自 `agents.defaults.models..alias`。示例： ```json5 @@ -2492,12 +2497,12 @@ x-i18n: } ``` - 然后 `/model sonnet`（或在支持时使用 `/`）就会解析到对应模型 ID。 + 然后 `/model sonnet`（或在支持时使用 `/`）就会解析到该模型 ID。 - - OpenRouter（按令牌付费；模型众多）： + + OpenRouter（按 token 计费；支持许多模型）： ```json5 { @@ -2525,22 +2530,23 @@ x-i18n: } ``` - 如果你引用了某个提供商 / 模型，但缺少所需的提供商 key，就会收到运行时认证错误（例如 `No API key found for provider "zai"`）。 + 如果你引用了某个提供商/模型，但缺少所需的提供商密钥，就会收到运行时凭证错误（例如 `No API key found for provider "zai"`）。 - **添加新智能体后显示 No API key found for provider** + **添加新智能体后提示 No API key found for provider** - 这通常表示这个**新智能体**的认证存储是空的。认证是按智能体划分的，并存储在： + 这通常意味着**新智能体**的凭证存储是空的。凭证是按智能体存储的， + 路径为： ``` ~/.openclaw/agents//agent/auth-profiles.json ``` - 修复方式： + 修复方法： - - 运行 `openclaw agents add `，并在向导中配置认证。 - - 或者将主智能体 `agentDir` 中的 `auth-profiles.json` 复制到新智能体的 `agentDir`。 + - 运行 `openclaw agents add `，并在向导中配置凭证。 + - 或者将主智能体 `agentDir` 中的 `auth-profiles.json` 复制到新智能体的 `agentDir` 中。 - **不要**在多个智能体之间复用 `agentDir`；这会导致认证 / 会话冲突。 + **不要**在多个智能体之间复用 `agentDir`；这会导致凭证/会话冲突。 @@ -2551,105 +2557,104 @@ x-i18n: 故障切换分两个阶段进行： - 1. 同一提供商内的**认证配置文件轮换**。 - 2. **模型回退**到 `agents.defaults.model.fallbacks` 中的下一个模型。 + 1. 同一提供商内的**凭证配置文件轮换**。 + 2. **模型后备**到 `agents.defaults.model.fallbacks` 中的下一个模型。 - 对失败的配置文件会应用冷却期（指数退避），因此即使某个提供商受到速率限制或暂时失败，OpenClaw 也能继续回复。 + 失败的配置文件会应用冷却时间（指数退避），因此即使某个提供商受到速率限制或暂时故障，OpenClaw 仍可继续响应。 - 速率限制桶不仅包括普通的 `429` 响应。OpenClaw - 还会将诸如 `Too many concurrent requests`、 + 速率限制桶包含的不只是普通 `429` 响应。OpenClaw + 也会将诸如 `Too many concurrent requests`、 `ThrottlingException`、`concurrency limit reached`、 - `workers_ai ... quota limit exceeded`、`resource exhausted` 以及周期性的 - 用量窗口限制（`weekly/monthly limit reached`）等消息视为值得进行故障切换的 + `workers_ai ... quota limit exceeded`、`resource exhausted` 以及周期性 + 使用窗口限制（`weekly/monthly limit reached`）等消息视为值得触发故障切换的 速率限制。 某些看起来像计费问题的响应并不是 `402`，而某些 HTTP `402` 响应也仍会留在该瞬时故障桶中。如果提供商在 `401` 或 `403` 上返回 - 明确的计费文本，OpenClaw 仍可以把它归入 - 计费通道，但提供商特定的文本匹配器仍会限制在其 - 所属提供商内（例如 OpenRouter 的 `Key limit exceeded`）。如果某条 `402` - 消息看起来反而像一个可重试的用量窗口，或 - 组织 / 工作区支出限制（`daily limit reached, resets tomorrow`、 + 明确的计费文本，OpenClaw 仍然可以将其保留在 + 计费通道中，但提供商特定的文本匹配器仍只限定在拥有它们的 + 提供商范围内（例如 OpenRouter 的 `Key limit exceeded`）。如果某个 `402` + 消息看起来像可重试的使用窗口问题，或者是 + 组织/工作区支出上限（`daily limit reached, resets tomorrow`、 `organization spending limit exceeded`），OpenClaw 会将其视为 `rate_limit`，而不是长期计费禁用。 - 上下文溢出错误则不同：像 + 上下文溢出错误则不同：类似 `request_too_large`、`input exceeds the maximum number of tokens`、 `input token count exceeds the maximum number of input tokens`、 `input is too long for the model` 或 `ollama error: context length - exceeded` 这类特征，会继续走压缩 / 重试路径，而不是推进到模型 - 回退。 + exceeded` 这类特征，会保留在压缩/重试路径上，而不会推进模型 + 后备。 - 通用服务器错误文本的匹配范围刻意比“任何包含 - unknown/error 的内容”更窄。OpenClaw 确实会将提供商范围内的瞬时错误形态 - 视为值得故障切换的超时 / 过载信号，例如 Anthropic 的裸 `An unknown error occurred`、OpenRouter 的裸 - `Provider returned error`、停止原因错误如 `Unhandled stop reason: - error`、带有瞬时服务器错误文本的 JSON `api_error` 负载 + 通用服务器错误文本的匹配范围有意比“任何包含 + unknown/error 的内容”更窄。OpenClaw 确实会将提供商范围内的瞬时形态 + 视为值得故障切换的超时/过载信号，例如 Anthropic 的裸 `An unknown error occurred`、OpenRouter 的裸 + `Provider returned error`、类似 `Unhandled stop reason: + error` 的停止原因错误、带有瞬时服务器文本的 JSON `api_error` 负载 （`internal server error`、`unknown error, 520`、`upstream error`、`backend - error`），以及像 `ModelNotReadyException` 这样的提供商忙碌错误，前提是提供商上下文 - 匹配。 + error`），以及诸如 `ModelNotReadyException` 的提供商繁忙错误，只要提供商上下文匹配即可。 像 `LLM request failed with an unknown - error.` 这样的通用内部回退文本则保持保守，不会仅凭自身触发模型回退。 + error.` 这样的通用内部后备文本则保持保守，不会单独触发模型后备。 - 这表示系统尝试使用认证配置文件 ID `anthropic:default`，但无法在预期的认证存储中找到对应凭证。 + 这表示系统尝试使用凭证配置文件 ID `anthropic:default`，但在预期的凭证存储中找不到对应凭证。 **修复清单：** - - **确认 auth profiles 的存放位置**（新路径与旧路径） - - 当前：`~/.openclaw/agents//agent/auth-profiles.json` - - 旧版：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移） - - **确认 Gateway 网关 已加载你的环境变量** - - 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但 Gateway 网关 是通过 systemd/launchd 运行的，它可能不会继承该变量。请将其放入 `~/.openclaw/.env`，或启用 `env.shellEnv`。 - - **确认你正在编辑正确的智能体** - - 多智能体设置意味着可能存在多个 `auth-profiles.json` 文件。 - - **对模型 / 认证状态做基本检查** - - 使用 `openclaw models status` 查看已配置模型，以及提供商是否已认证。 + - **确认凭证配置文件的位置**（新路径与旧路径） + - 当前路径：`~/.openclaw/agents//agent/auth-profiles.json` + - 旧路径：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移） + - **确认 Gateway 网关已加载你的环境变量** + - 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但通过 systemd/launchd 运行 Gateway 网关，它可能不会继承它。请将其放入 `~/.openclaw/.env` 或启用 `env.shellEnv`。 + - **确保你编辑的是正确的智能体** + - 多智能体部署意味着可能存在多个 `auth-profiles.json` 文件。 + - **进行模型/凭证状态检查** + - 使用 `openclaw models status` 查看已配置模型以及提供商是否已通过身份验证。 - **针对 “No credentials found for profile anthropic” 的修复清单** + **关于 “No credentials found for profile anthropic” 的修复清单** - 这表示当前运行被固定到了某个 Anthropic 认证配置文件，但 Gateway 网关 - 无法在其认证存储中找到它。 + 这表示当前运行被固定到某个 Anthropic 凭证配置文件，但 Gateway 网关 + 无法在其凭证存储中找到它。 - **使用 Claude CLI** - - 在 Gateway 网关 主机上运行 `openclaw models auth login --provider anthropic --method cli --set-default`。 - - **如果你想改用 API key** - - 将 `ANTHROPIC_API_KEY` 放到**Gateway 网关 主机**上的 `~/.openclaw/.env` 中。 - - 清除任何会强制使用缺失配置文件的固定顺序： + - 在 Gateway 网关主机上运行 `openclaw models auth login --provider anthropic --method cli --set-default`。 + - **如果你想改用 API 密钥** + - 将 `ANTHROPIC_API_KEY` 放入**Gateway 网关主机**上的 `~/.openclaw/.env`。 + - 清除任何强制缺失配置文件的固定顺序： ```bash openclaw models auth order clear --provider anthropic ``` - - **确认你是在 Gateway 网关 主机上运行命令** - - 在远程模式下，auth profiles 位于 Gateway 网关 机器上，而不是你的笔记本上。 + - **确认你是在 Gateway 网关主机上运行命令** + - 在远程模式下，凭证配置文件位于 Gateway 网关机器上，而不是你的笔记本电脑上。 - - 如果你的模型配置中把 Google Gemini 作为回退项（或者你切换到了 Gemini 简写），OpenClaw 就会在模型回退时尝试它。如果你没有配置 Google 凭证，就会看到 `No API key found for provider "google"`。 + + 如果你的模型配置将 Google Gemini 包含为后备（或者你切换到了 Gemini 简写），OpenClaw 就会在模型后备时尝试它。如果你没有配置 Google 凭证，就会看到 `No API key found for provider "google"`。 - 修复方法：要么提供 Google 认证，要么从 `agents.defaults.model.fallbacks` / aliases 中移除或避免使用 Google 模型，这样回退就不会路由到那里。 + 修复方法：要么提供 Google 凭证，要么从 `agents.defaults.model.fallbacks` / 别名中移除或避免使用 Google 模型，以免后备路由到它。 **LLM request rejected: thinking signature required（Google Antigravity）** 原因：会话历史中包含**没有签名的 thinking 块**（通常来自 - 已中止 / 部分流式输出）。Google Antigravity 要求 thinking 块带有签名。 + 已中止/部分流式传输）。Google Antigravity 要求 thinking 块必须带有签名。 - 修复方法：OpenClaw 现在会为 Google Antigravity Claude 去除无签名的 thinking 块。如果仍然出现，请开始一个**新会话**，或为该智能体设置 `/thinking off`。 + 修复方法：OpenClaw 现在会为 Google Antigravity Claude 去除未签名的 thinking 块。如果仍然出现，请开始一个**新会话**，或为该智能体设置 `/thinking off`。 -## Auth profiles：它们是什么，以及如何管理 +## 凭证配置文件：它们是什么，以及如何管理 -相关内容：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流程、令牌存储、多账户模式） +相关内容：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流程、token 存储、多账户模式） - - auth profile 是一个绑定到提供商的具名凭证记录（OAuth 或 API key）。profiles 位于： + + 凭证配置文件是一个与提供商绑定的命名凭证记录（OAuth 或 API 密钥）。配置文件位于： ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2657,64 +2662,64 @@ x-i18n: - + OpenClaw 使用带提供商前缀的 ID，例如： - - `anthropic:default`（没有电子邮件身份时很常见） + - `anthropic:default`（在没有邮箱身份时较常见） - `anthropic:` 用于 OAuth 身份 - 你自己选择的自定义 ID（例如 `anthropic:work`） - - 可以。配置支持 profiles 的可选元数据，以及每个提供商的顺序设置（`auth.order.`）。这**不会**存储 secrets；它只会把 ID 映射到 provider/mode，并设置轮换顺序。 + + 可以。配置支持配置文件的可选元数据，以及按提供商排序（`auth.order.`）。这**不会**存储 secrets；它只是将 ID 映射到 provider/mode，并设置轮换顺序。 - 如果某个 profile 处于短期**冷却**状态（速率限制 / 超时 / 认证失败）或较长期的**禁用**状态（计费 / 额度不足），OpenClaw 可能会暂时跳过它。要检查这一点，请运行 `openclaw models status --json` 并查看 `auth.unusableProfiles`。调优项：`auth.cooldowns.billingBackoffHours*`。 + 如果某个配置文件处于短暂**冷却**状态（速率限制/超时/凭证失败）或更长时间的**禁用**状态（计费/额度不足），OpenClaw 可能会暂时跳过它。要检查这一点，请运行 `openclaw models status --json` 并查看 `auth.unusableProfiles`。调优项：`auth.cooldowns.billingBackoffHours*`。 - 速率限制冷却可以按模型划分。某个 profile 对某个模型处于冷却状态时， - 对同一提供商下的兄弟模型仍可能可用， - 而计费 / 禁用窗口仍会阻止整个 profile。 + 速率限制冷却可以是按模型范围生效的。某个配置文件 + 对一个模型处于冷却中时，仍然可能对同一提供商下的兄弟模型可用， + 而计费/禁用窗口仍会阻止整个配置文件。 - 你还可以通过 CLI 设置**每智能体**顺序覆盖（存储在该智能体的 `auth-state.json` 中）： + 你也可以通过 CLI 设置**按智能体**的顺序覆盖（存储在该智能体的 `auth-state.json` 中）： ```bash - # 默认为已配置的默认智能体（省略 --agent） + # 默认针对已配置的默认智能体（省略 --agent） openclaw models auth order get --provider anthropic - # 将轮换锁定到单个 profile（只尝试这一个） + # 将轮换锁定为单一配置文件（只尝试这一个） openclaw models auth order set --provider anthropic anthropic:default - # 或设置显式顺序（提供商内回退） + # 或设置显式顺序（提供商内部后备） openclaw models auth order set --provider anthropic anthropic:work anthropic:default - # 清除覆盖（回退到 config auth.order / round-robin） + # 清除覆盖（回退到配置 auth.order / round-robin） openclaw models auth order clear --provider anthropic ``` - 如需指定某个特定智能体： + 要针对特定智能体： ```bash openclaw models auth order set --provider anthropic --agent main anthropic:default ``` - 如需验证实际会尝试什么，请使用： + 要验证实际会尝试什么，请使用： ```bash openclaw models status --probe ``` - 如果某个已存储的 profile 被排除在显式顺序之外，probe 会为该 profile 报告 - `excluded_by_auth_order`，而不是默默尝试它。 + 如果某个已存储的配置文件未包含在显式顺序中，探测会为该配置文件报告 + `excluded_by_auth_order`，而不是悄悄尝试它。 - + OpenClaw 两者都支持： - - **OAuth** 通常会利用订阅访问权限（如适用）。 - - **API keys** 使用按令牌付费的计费方式。 + - **OAuth** 通常会利用订阅访问权限（在适用时）。 + - **API keys** 使用按 token 计费。 - 向导明确支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API keys。 + 该向导明确支持 Anthropic Claude CLI、OpenAI Codex OAuth 以及 API 密钥。 @@ -2722,8 +2727,8 @@ x-i18n: ## Gateway 网关：端口、“已在运行”和远程模式 - - `gateway.port` 控制单一的复用端口，用于 WebSocket + HTTP（Control UI、hooks 等）。 + + `gateway.port` 控制 WebSocket + HTTP（Control UI、hooks 等）共用的单一复用端口。 优先级： @@ -2733,21 +2738,21 @@ x-i18n: - - 因为 “running” 是 **supervisor** 的视角（launchd/systemd/schtasks）。而 connectivity probe 表示 CLI 实际尝试连接 Gateway 网关 WebSocket 的结果。 + + 因为 “running” 是 **supervisor** 的视角（launchd/systemd/schtasks）。而 connectivity probe 是 CLI 实际去连接 Gateway 网关 WebSocket。 - 使用 `openclaw gateway status`，并重点关注这些行： + 使用 `openclaw gateway status`，并重点查看这些行： - `Probe target:`（探测实际使用的 URL） - `Listening:`（端口上实际绑定的内容） - - `Last gateway error:`（当进程活着但端口未监听时，这通常是常见根因） + - `Last gateway error:`（当进程仍存活但端口未监听时，常见的根本原因） - - 你正在编辑一个配置文件，而服务运行的是另一个配置文件（通常是 `--profile` / `OPENCLAW_STATE_DIR` 不匹配）。 + + 你编辑的是一个配置文件，而服务运行的是另一个配置文件（通常是 `--profile` / `OPENCLAW_STATE_DIR` 不匹配）。 - 修复方式： + 修复方法： ```bash openclaw gateway install --force @@ -2758,14 +2763,14 @@ x-i18n: - OpenClaw 通过在启动时立即绑定 WebSocket 监听器来强制执行运行时锁（默认是 `ws://127.0.0.1:18789`）。如果绑定因 `EADDRINUSE` 失败，它会抛出 `GatewayLockError`，表示另一个实例已经在监听。 + OpenClaw 通过在启动时立即绑定 WebSocket 监听器来强制执行运行时锁（默认 `ws://127.0.0.1:18789`）。如果绑定因 `EADDRINUSE` 失败，它会抛出 `GatewayLockError`，表示已有另一个实例正在监听。 - 修复方式：停止另一个实例，释放端口，或使用 `openclaw gateway --port ` 运行。 + 修复方法：停止另一个实例、释放端口，或者使用 `openclaw gateway --port ` 运行。 - - 设置 `gateway.mode: "remote"` 并指向远程 WebSocket URL，可选再加上 shared-secret 远程凭证： + + 设置 `gateway.mode: "remote"`，并指向远程 WebSocket URL；也可以选择附带 shared-secret 远程凭证： ```json5 { @@ -2784,53 +2789,53 @@ x-i18n: - 只有当 `gateway.mode` 为 `local` 时，`openclaw gateway` 才会启动（除非你传入覆盖标志）。 - macOS 应用会监视配置文件，并在这些值发生变化时实时切换模式。 - - `gateway.remote.token` / `.password` 仅用于客户端侧远程凭证；它们本身不会启用本地 Gateway 网关 认证。 + - `gateway.remote.token` / `.password` 只是客户端侧的远程凭证；它们本身不会启用本地 Gateway 网关身份验证。 - - 你的 Gateway 网关 认证路径与 UI 的认证方式不匹配。 + + 你的 Gateway 网关身份验证路径与 UI 的身份验证方式不匹配。 - 事实说明（来自代码）： + 事实（来自代码）： - - Control UI 会将令牌保存在 `sessionStorage` 中，作用范围是当前浏览器标签页会话和所选 Gateway 网关 URL，因此同一标签页刷新后仍能继续使用，而无需恢复长期的 localStorage 令牌持久化。 - - 当出现 `AUTH_TOKEN_MISMATCH` 时，如果 Gateway 网关 返回重试提示（`canRetryWithDeviceToken=true`、`recommendedNextStep=retry_with_device_token`），受信任客户端可以尝试使用缓存的设备令牌进行一次有界重试。 - - 该缓存令牌重试现在会复用与设备令牌一同存储的已批准 scopes。显式 `deviceToken` / 显式 `scopes` 的调用方仍会保留它们请求的 scope 集，而不会继承缓存 scopes。 - - 在该重试路径之外，连接认证优先级依次为：显式 shared token / password，然后是显式 `deviceToken`，然后是已存储设备令牌，最后是 bootstrap 令牌。 - - Bootstrap 令牌的 scope 检查带有角色前缀。内置的 bootstrap operator allowlist 只满足 operator 请求；node 或其他非 operator 角色仍需要各自角色前缀下的 scopes。 + - Control UI 会将 token 保存在当前浏览器标签页会话和所选 Gateway 网关 URL 对应的 `sessionStorage` 中，因此同一标签页刷新后仍可正常工作，而无需恢复长久的 `localStorage` token 持久化。 + - 当出现 `AUTH_TOKEN_MISMATCH` 时，受信任客户端可以在 Gateway 网关返回重试提示（`canRetryWithDeviceToken=true`、`recommendedNextStep=retry_with_device_token`）时，使用缓存的设备 token 进行一次有界重试。 + - 该缓存 token 重试现在会复用随设备 token 一起存储的已批准 scopes。显式传入 `deviceToken` / 显式 `scopes` 的调用方仍会保留自己请求的作用域集，而不会继承缓存 scopes。 + - 在该重试路径之外，connect 身份验证优先级依次是显式 shared token/password、显式 `deviceToken`、已存储设备 token，最后才是 bootstrap token。 + - Bootstrap token 的作用域检查采用角色前缀。内置的 bootstrap operator 允许列表只能满足 operator 请求；节点或其他非 operator 角色仍然需要其各自角色前缀下的 scopes。 - 修复方式： + 修复方法： - - 最快方式：`openclaw dashboard`（打印并复制仪表板 URL，尝试打开；无头环境下会显示 SSH 提示）。 - - 如果你还没有令牌：`openclaw doctor --generate-gateway-token`。 - - 如果是远程环境，先建立隧道：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。 - - shared-secret 模式：设置 `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` 或 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`，然后在 Control UI 设置中粘贴匹配的 secret。 - - Tailscale Serve 模式：确认已启用 `gateway.auth.allowTailscale`，并且你打开的是 Serve URL，而不是绕过 Tailscale 身份标头的原始 loopback / tailnet URL。 - - trusted-proxy 模式：确认你是通过已配置的非 loopback 身份感知代理访问的，而不是通过同主机 loopback 代理或原始 Gateway 网关 URL。 - - 如果一次重试后仍然不匹配，请轮换 / 重新批准已配对的设备令牌： + - 最快方式：`openclaw dashboard`（会打印并复制仪表板 URL，尝试打开；如果是 headless，会显示 SSH 提示）。 + - 如果你还没有 token：`openclaw doctor --generate-gateway-token`。 + - 如果是远程连接，先建立隧道：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。 + - Shared-secret 模式：设置 `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` 或 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`，然后在 Control UI 设置中粘贴对应的 secret。 + - Tailscale Serve 模式：确保 `gateway.auth.allowTailscale` 已启用，并且你打开的是 Serve URL，而不是绕过 Tailscale 身份标头的原始 loopback/tailnet URL。 + - Trusted-proxy 模式：确保你是通过已配置的非 loopback 身份感知代理访问，而不是通过同主机 loopback 代理或原始 Gateway 网关 URL 访问。 + - 如果一次重试后仍不匹配，请轮换/重新批准已配对的设备 token： - `openclaw devices list` - `openclaw devices rotate --device --role operator` - - 如果该 rotate 调用提示被拒绝，请检查两点： - - 配对设备会话只能轮换**它们自己的**设备，除非它们同时具有 `operator.admin` - - 显式 `--scope` 值不能超出调用方当前的 operator scopes - - 如果仍卡住？运行 `openclaw status --all`，并参考 [故障排除](/zh-CN/gateway/troubleshooting)。认证细节请参阅 [Dashboard](/web/dashboard)。 + - 如果该轮换调用提示被拒绝，请检查两点： + - 已配对设备会话只能轮换其**自己的**设备，除非它们同时拥有 `operator.admin` + - 显式 `--scope` 值不能超过调用者当前的 operator scopes + - 还是卡住？运行 `openclaw status --all`，并按照 [故障排除](/zh-CN/gateway/troubleshooting) 进行操作。身份验证详情请参阅 [Dashboard](/web/dashboard)。 - - `tailnet` 绑定会从你的网络接口中选择一个 Tailscale IP（100.64.0.0/10）。如果机器没有接入 Tailscale（或接口已断开），就没有可绑定的地址。 + + `tailnet` 绑定会从你的网络接口中选择一个 Tailscale IP（100.64.0.0/10）。如果机器未接入 Tailscale（或接口已关闭），就没有可绑定的地址。 - 修复方式： + 修复方法： - - 在该主机上启动 Tailscale（让它获得一个 100.x 地址），或者 + - 在该主机上启动 Tailscale（使其获得一个 100.x 地址），或者 - 切换到 `gateway.bind: "loopback"` / `"lan"`。 - 说明：`tailnet` 是显式模式。`auto` 会优先使用 loopback；如果你想只绑定 tailnet，请使用 `gateway.bind: "tailnet"`。 + 注意：`tailnet` 是显式选项。`auto` 会优先使用 loopback；如果你想只绑定到 tailnet，请使用 `gateway.bind: "tailnet"`。 - - 通常不需要——一个 Gateway 网关 就可以运行多个消息渠道和智能体。只有在你需要冗余（例如应急机器人）或硬隔离时，才使用多个 Gateway 网关。 + + 通常不需要——一个 Gateway 网关就可以运行多个消息渠道和智能体。只有在你需要冗余（例如救援机器人）或硬隔离时，才使用多个 Gateway 网关。 可以，但你必须隔离以下内容： @@ -2842,38 +2847,38 @@ x-i18n: 快速设置（推荐）： - 每个实例使用 `openclaw --profile ...`（会自动创建 `~/.openclaw-`）。 - - 在每个 profile 配置中设置唯一的 `gateway.port`（或在手动运行时传入 `--port`）。 - - 安装每个 profile 对应的服务：`openclaw --profile gateway install`。 + - 在每个 profile 配置中设置唯一的 `gateway.port`（或为手动运行传入 `--port`）。 + - 安装每个 profile 的服务：`openclaw --profile gateway install`。 - Profiles 还会为服务名添加后缀（`ai.openclaw.`；旧版为 `com.openclaw.*`、`openclaw-gateway-.service`、`OpenClaw Gateway ()`）。 + Profiles 也会为服务名添加后缀（`ai.openclaw.`；旧版为 `com.openclaw.*`、`openclaw-gateway-.service`、`OpenClaw Gateway ()`）。 完整指南：[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 - Gateway 网关 是一个**WebSocket 服务器**，并且它期望收到的第一条消息 - 是一个 `connect` 帧。如果收到其他内容，它就会关闭连接， - 并返回 **code 1008**（策略违规）。 + Gateway 网关是一个 **WebSocket 服务器**，它期望收到的第一条消息 + 是一个 `connect` 帧。如果收到其他内容，它就会以 + **code 1008**（策略违规）关闭连接。 常见原因： - 你在浏览器中打开了 **HTTP** URL（`http://...`），而不是使用 WS 客户端。 - - 你用了错误的端口或路径。 - - 某个代理或隧道剥离了认证标头，或发送了非 Gateway 网关 请求。 + - 你使用了错误的端口或路径。 + - 某个代理或隧道剥离了身份验证标头，或发送了非 Gateway 网关请求。 快速修复： - 1. 使用 WS URL：`ws://:18789`（如果是 HTTPS，则使用 `wss://...`）。 + 1. 使用 WS URL：`ws://:18789`（如果是 HTTPS，则用 `wss://...`）。 2. 不要在普通浏览器标签页中打开 WS 端口。 - 3. 如果启用了认证，请在 `connect` 帧中包含令牌 / 密码。 + 3. 如果启用了身份验证，请在 `connect` 帧中包含 token/password。 - 如果你使用的是 CLI 或 TUI，URL 应该类似这样： + 如果你使用 CLI 或 TUI，URL 应如下所示： ``` openclaw tui --url ws://:18789 --token ``` - 协议细节：[Gateway protocol](/zh-CN/gateway/protocol)。 + 协议详情：[Gateway protocol](/zh-CN/gateway/protocol)。 @@ -2888,15 +2893,15 @@ x-i18n: /tmp/openclaw/openclaw-YYYY-MM-DD.log ``` - 你可以通过 `logging.file` 设置一个稳定路径。文件日志级别由 `logging.level` 控制。控制台详细程度由 `--verbose` 和 `logging.consoleLevel` 控制。 + 你可以通过 `logging.file` 设置稳定路径。文件日志级别由 `logging.level` 控制。控制台详细程度由 `--verbose` 和 `logging.consoleLevel` 控制。 - 最快查看日志尾部的方式： + 查看日志尾部的最快方式： ```bash openclaw logs --follow ``` - 服务 / supervisor 日志（当 Gateway 网关 通过 launchd/systemd 运行时）： + 服务/supervisor 日志（当 Gateway 网关通过 launchd/systemd 运行时）： - macOS：`$OPENCLAW_STATE_DIR/logs/gateway.log` 和 `gateway.err.log`（默认：`~/.openclaw/logs/...`；profiles 使用 `~/.openclaw-/logs/...`） - Linux：`journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` @@ -2906,22 +2911,22 @@ x-i18n: - - 使用 Gateway 网关 辅助命令： + + 使用 Gateway 网关辅助命令： ```bash openclaw gateway status openclaw gateway restart ``` - 如果你是手动运行 Gateway 网关，`openclaw gateway --force` 可以回收端口。请参阅 [Gateway 网关](/zh-CN/gateway)。 + 如果你是手动运行 Gateway 网关，`openclaw gateway --force` 可以重新夺回端口。请参阅 [Gateway 网关](/zh-CN/gateway)。 Windows 有**两种安装模式**： - **1）WSL2（推荐）：**Gateway 网关 运行在 Linux 内部。 + **1) WSL2（推荐）：**Gateway 网关运行在 Linux 内部。 打开 PowerShell，进入 WSL，然后重启： @@ -2931,13 +2936,13 @@ x-i18n: openclaw gateway restart ``` - 如果你从未安装服务，就在前台启动它： + 如果你从未安装服务，请在前台启动它： ```bash openclaw gateway run ``` - **2）原生 Windows（不推荐）：**Gateway 网关 直接运行在 Windows 中。 + **2) 原生 Windows（不推荐）：**Gateway 网关直接运行在 Windows 中。 打开 PowerShell 并运行： @@ -2946,18 +2951,18 @@ x-i18n: openclaw gateway restart ``` - 如果你是手动运行它（没有服务），请使用： + 如果你是手动运行它（无服务），请使用： ```powershell openclaw gateway run ``` - 文档：[Windows（WSL2）](/zh-CN/platforms/windows)、[Gateway 网关 服务运行手册](/zh-CN/gateway)。 + 文档：[Windows（WSL2）](/zh-CN/platforms/windows)、[Gateway 网关服务运行手册](/zh-CN/gateway)。 - - 先进行一轮快速健康检查： + + 先做一轮快速健康检查： ```bash openclaw status @@ -2968,24 +2973,24 @@ x-i18n: 常见原因： - - 模型认证未在**Gateway 网关 主机**上加载（检查 `models status`）。 - - 渠道配对 / 允许列表阻止了回复（检查渠道配置 + 日志）。 - - WebChat / Dashboard 已打开，但使用的令牌不正确。 + - 模型凭证未在**Gateway 网关主机**上加载（检查 `models status`）。 + - 渠道配对/允许列表阻止了回复（检查渠道配置 + 日志）。 + - WebChat/Dashboard 打开时没有使用正确的 token。 - 如果你处于远程模式，请确认隧道 / Tailscale 连接正常，并且 - Gateway WebSocket 可达。 + 如果你是远程连接，请确认隧道/Tailscale 连接正常，并且 + Gateway 网关 WebSocket 可达。 - 文档：[Channels](/zh-CN/channels)、[故障排除](/zh-CN/gateway/troubleshooting)、[Remote access](/zh-CN/gateway/remote)。 + 文档：[渠道](/zh-CN/channels)、[故障排除](/zh-CN/gateway/troubleshooting)、[远程访问](/zh-CN/gateway/remote)。 这通常表示 UI 丢失了 WebSocket 连接。请检查： - 1. Gateway 网关 是否正在运行？`openclaw gateway status` - 2. Gateway 网关 是否健康？`openclaw status` - 3. UI 是否使用了正确的令牌？`openclaw dashboard` - 4. 如果是远程环境，隧道 / Tailscale 链路是否正常？ + 1. Gateway 网关是否正在运行？`openclaw gateway status` + 2. Gateway 网关是否健康？`openclaw status` + 3. UI 是否拥有正确的 token？`openclaw dashboard` + 4. 如果是远程连接，隧道/Tailscale 链路是否正常？ 然后查看日志尾部： @@ -2993,31 +2998,31 @@ x-i18n: openclaw logs --follow ``` - 文档：[Dashboard](/web/dashboard)、[Remote access](/zh-CN/gateway/remote)、[故障排除](/zh-CN/gateway/troubleshooting)。 + 文档：[Dashboard](/web/dashboard)、[远程访问](/zh-CN/gateway/remote)、[故障排除](/zh-CN/gateway/troubleshooting)。 - - 先查看日志和渠道状态： + + 先从日志和渠道状态开始： ```bash openclaw channels status openclaw channels logs --channel telegram ``` - 然后根据错误进行匹配： + 然后根据错误类型进行匹配： - - `BOT_COMMANDS_TOO_MUCH`：Telegram 菜单条目过多。OpenClaw 已经会裁剪到 Telegram 限制并用更少的命令重试，但某些菜单条目仍然需要去掉。请减少插件 / skill / 自定义命令，或在不需要菜单时禁用 `channels.telegram.commands.native`。 - - `TypeError: fetch failed`、`Network request for 'setMyCommands' failed!` 或类似网络错误：如果你在 VPS 上或位于代理之后，请确认允许出站 HTTPS，并且 `api.telegram.org` 的 DNS 正常。 + - `BOT_COMMANDS_TOO_MUCH`：Telegram 菜单条目过多。OpenClaw 已经会裁剪到 Telegram 的限制并使用更少的命令重试，但某些菜单条目仍然需要删除。请减少插件/Skill/自定义命令，或者如果你不需要该菜单，则禁用 `channels.telegram.commands.native`。 + - `TypeError: fetch failed`、`Network request for 'setMyCommands' failed!` 或类似网络错误：如果你在 VPS 上运行或位于代理之后，请确认允许出站 HTTPS，并且 `api.telegram.org` 的 DNS 解析正常。 - 如果 Gateway 网关 是远程的，请确认你查看的是 Gateway 网关 主机上的日志。 + 如果 Gateway 网关是远程的，请确保你查看的是 Gateway 网关主机上的日志。 文档：[Telegram](/zh-CN/channels/telegram)、[渠道故障排除](/zh-CN/channels/troubleshooting)。 - - 先确认 Gateway 网关 可达，并且智能体能够运行： + + 先确认 Gateway 网关可达，并且智能体可以运行： ```bash openclaw status @@ -3025,14 +3030,14 @@ x-i18n: openclaw logs --follow ``` - 在 TUI 中，使用 `/status` 查看当前状态。如果你希望回复出现在某个聊天 - 渠道中，请确认已启用投递（`/deliver on`）。 + 在 TUI 中，使用 `/status` 查看当前状态。如果你希望在某个聊天 + 渠道中收到回复，请确保已启用投递（`/deliver on`）。 文档：[TUI](/web/tui)、[Slash commands](/zh-CN/tools/slash-commands)。 - + 如果你安装了服务： ```bash @@ -3040,40 +3045,40 @@ x-i18n: openclaw gateway start ``` - 这会停止 / 启动**受监管的服务**（macOS 上是 launchd，Linux 上是 systemd）。 - 当 Gateway 网关 作为后台守护进程运行时，请使用这种方式。 + 这会停止/启动**受监管服务**（macOS 上是 launchd，Linux 上是 systemd）。 + 当 Gateway 网关作为后台守护进程运行时，请使用这个方式。 - 如果你是在前台运行，请按 Ctrl-C 停止，然后： + 如果你是在前台运行，请用 Ctrl-C 停止，然后执行： ```bash openclaw gateway run ``` - 文档：[Gateway 网关 服务运行手册](/zh-CN/gateway)。 + 文档：[Gateway 网关服务运行手册](/zh-CN/gateway)。 - + - `openclaw gateway restart`：重启**后台服务**（launchd/systemd）。 - `openclaw gateway`：在当前终端会话中**前台运行** Gateway 网关。 - 如果你已经安装了服务，请使用 Gateway 网关 命令。只有在 - 你想进行一次性的前台运行时，才使用 `openclaw gateway`。 + 如果你安装了服务，请使用 gateway 相关命令。使用 `openclaw gateway` 的场景是： + 你想进行一次性的前台运行。 - - 使用 `--verbose` 启动 Gateway 网关，以获得更详细的控制台输出。然后检查日志文件，查看渠道认证、模型路由和 RPC 错误。 + + 使用 `--verbose` 启动 Gateway 网关，以获得更详细的控制台输出。然后检查日志文件，查看渠道凭证、模型路由和 RPC 错误。 ## 媒体和附件 - - 智能体发出的附件必须包含一行 `MEDIA:`（单独占一行）。请参阅 [OpenClaw assistant setup](/zh-CN/start/openclaw) 和 [Agent send](/zh-CN/tools/agent-send)。 + + 来自智能体的出站附件必须包含一行 `MEDIA:`（单独占一行）。请参阅 [OpenClaw 助手设置](/zh-CN/start/openclaw) 和 [智能体发送](/zh-CN/tools/agent-send)。 - CLI 发送方式： + CLI 发送： ```bash openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png @@ -3081,10 +3086,10 @@ x-i18n: 还请检查： - - 目标渠道支持出站媒体，并且没有被允许列表阻止。 + - 目标渠道支持发送媒体，并且未被允许列表阻止。 - 文件未超过提供商的大小限制（图片会被缩放到最大 2048px）。 - - `tools.fs.workspaceOnly=true` 会将本地路径发送限制在工作区、temp/media-store 和通过沙箱校验的文件内。 - - `tools.fs.workspaceOnly=false` 允许 `MEDIA:` 发送智能体已可读取的主机本地文件，但仅限媒体和安全文档类型（图片、音频、视频、PDF 和 Office 文档）。纯文本和类似 secret 的文件仍然会被阻止。 + - `tools.fs.workspaceOnly=true` 会将本地路径发送限制在工作区、temp/media-store 以及通过沙箱验证的文件内。 + - `tools.fs.workspaceOnly=false` 允许 `MEDIA:` 发送智能体本来就能读取的主机本地文件，但仅限媒体和安全文档类型（图片、音频、视频、PDF 和 Office 文档）。纯文本和类似 secret 的文件仍会被阻止。 请参阅 [Images](/zh-CN/nodes/images)。 @@ -3094,73 +3099,73 @@ x-i18n: ## 安全和访问控制 - - 请将入站私信视为不可信输入。默认设置的设计目标是降低风险： + + 请将入站私信视为不可信输入。默认设置旨在降低风险： - - 在支持私信的渠道上，默认行为是**配对**： + - 支持私信的渠道上的默认行为是**配对**： - 未知发送者会收到一个配对码；机器人不会处理他们的消息。 - - 使用以下命令批准：`openclaw pairing approve --channel [--account ] ` - - 待处理请求每个渠道最多 **3 个**；如果配对码没有送达，请检查 `openclaw pairing list --channel [--account ]` - - 公开开放私信需要显式选择加入（`dmPolicy: "open"` 且 allowlist 为 `"*"`）。 + - 批准方式：`openclaw pairing approve --channel [--account ] ` + - 待处理请求每个渠道最多 **3 个**；如果没有收到代码，请检查 `openclaw pairing list --channel [--account ]`。 + - 公开开放私信需要显式选择启用（`dmPolicy: "open"` 和允许列表 `"*"`）。 - 运行 `openclaw doctor` 可以发现风险较高的私信策略。 + 运行 `openclaw doctor` 以发现风险较高的私信策略。 - - 不是。提示注入针对的是**不可信内容**，而不只是“谁可以给机器人发私信”。 - 如果你的助手会读取外部内容（Web 搜索 / 获取、浏览器页面、邮件、 - 文档、附件、粘贴的日志），这些内容都可能包含试图 - 劫持模型的指令。即使**只有你自己是发送者**，也可能发生这种情况。 + + 不是。prompt injection 关乎的是**不可信内容**，而不仅仅是谁可以给机器人发私信。 + 如果你的助手会读取外部内容（Web 搜索/抓取、浏览器页面、邮件、 + 文档、附件、粘贴的日志），这些内容就可能包含试图 + 劫持模型的指令。即使**你是唯一的发送者**，这种情况也会发生。 - 最大的风险出现在启用了工具时：模型可能被诱导去 - 窃取上下文，或代表你调用工具。可通过以下方式降低影响范围： + 最大的风险出现在启用工具时：模型可能会被诱导去 + 窃取上下文，或者代表你调用工具。降低影响范围的方法包括： - - 使用只读或禁用工具的“阅读器”智能体来总结不可信内容 + - 使用一个只读或禁用工具的“阅读器”智能体来总结不可信内容 - 对启用了工具的智能体关闭 `web_search` / `web_fetch` / `browser` - - 同样将解码后的文件 / 文档文本视为不可信：OpenResponses + - 也将解码后的文件/文档文本视为不可信：OpenResponses `input_file` 和媒体附件提取都会将提取出的文本包裹在 明确的外部内容边界标记中，而不是直接传递原始文件文本 - - 使用沙箱隔离和严格的工具允许列表 + - 启用沙箱隔离并使用严格的工具允许列表 - 详情请参阅 [Security](/zh-CN/gateway/security)。 + 详情请参阅：[Security](/zh-CN/gateway/security)。 - - 对大多数设置来说，是的。使用单独的账户和手机号来隔离机器人， - 可以在出问题时降低影响范围。这也使得轮换 - 凭证或撤销访问更容易，而不会影响你的个人账户。 + + 对大多数部署来说，是的。使用独立的账号和电话号码隔离机器人， + 可以在出问题时缩小影响范围。这也让你更容易轮换 + 凭证或撤销访问权限，而不会影响你的个人账号。 - 从小规模开始。只授予它你实际需要的工具和账户访问权限，然后在确有需要时 - 再逐步扩展。 + 从小规模开始。只赋予它你实际需要的工具和账号访问权限， + 如有需要再逐步扩展。 - 文档：[Security](/zh-CN/gateway/security)、[Pairing](/zh-CN/channels/pairing)。 + 文档：[Security](/zh-CN/gateway/security)、[配对](/zh-CN/channels/pairing)。 - 我们**不建议**让它完全自主处理你的个人消息。最安全的模式是： + 我们**不**推荐让它完全自主处理你的个人消息。最安全的模式是： - 将私信保持在**配对模式**或严格的允许列表中。 - - 如果你想让它代表你发送消息，请使用**单独的号码或账户**。 - - 让它起草，然后在发送前**由你批准**。 + - 如果你希望它代表你发消息，请使用**单独的号码或账号**。 + - 让它先起草，然后**发送前审批**。 - 如果你确实想尝试，请在专用账户上进行，并保持隔离。请参阅 + 如果你想尝试，请在专用账号上进行，并保持隔离。请参阅 [Security](/zh-CN/gateway/security)。 - - 可以，**前提是**该智能体仅用于聊天，并且输入是可信的。较小档位 - 更容易受到指令劫持，因此不要将它们用于启用了工具的智能体， - 或用于读取不可信内容的场景。如果你必须使用较小模型，请锁紧 - 工具，并在沙箱中运行。请参阅 [Security](/zh-CN/gateway/security)。 + + 可以，**前提是**该智能体仅用于聊天，且输入是可信的。更小档位的模型 + 更容易受到指令劫持影响，因此在启用了工具的智能体上， + 或在读取不可信内容时，应避免使用它们。如果你必须使用更小的模型，请锁定 + 工具并在沙箱中运行。请参阅 [Security](/zh-CN/gateway/security)。 - 只有在未知发送者给机器人发消息且 - `dmPolicy: "pairing"` 已启用时，才会发送配对码。单独发送 `/start` 不会生成配对码。 + 只有当未知发送者给机器人发消息，且 + `dmPolicy: "pairing"` 已启用时，才会发送配对码。单独的 `/start` 不会生成代码。 检查待处理请求： @@ -3168,14 +3173,14 @@ x-i18n: openclaw pairing list telegram ``` - 如果你想立即获得访问权限，请将你的 sender id 加入允许列表，或为该账户设置 `dmPolicy: "open"`。 + 如果你想立即访问，请将你的 sender id 加入允许列表，或为该账号设置 `dmPolicy: "open"`。 - 不会。WhatsApp 私信的默认策略是**配对**。未知发送者只会收到一个配对码，而且他们的消息**不会被处理**。OpenClaw 只会回复它收到的聊天，或你显式触发的发送操作。 + 不会。默认的 WhatsApp 私信策略是**配对**。未知发送者只会收到一个配对码，他们的消息**不会被处理**。OpenClaw 只会回复它收到的聊天，或你显式触发的发送。 - 使用以下命令批准配对： + 批准配对： ```bash openclaw pairing approve whatsapp @@ -3187,18 +3192,19 @@ x-i18n: openclaw pairing list whatsapp ``` - 向导中的手机号提示用于设置你的**允许列表 / 所有者**，以便允许你自己的私信。它不会用于自动发送。如果你是在个人 WhatsApp 号码上运行，请使用该号码，并启用 `channels.whatsapp.selfChatMode`。 + 向导中的电话号码提示用于设置你的**允许列表/所有者**，以便允许你自己的私信。它不会用于自动发送。如果你是在自己的 WhatsApp 号码上运行，请使用该号码并启用 `channels.whatsapp.selfChatMode`。 -## 聊天命令、终止任务，以及“它就是不停” +## 聊天命令、中止任务，以及“它停不下来” - 大多数内部或工具消息只会在该会话启用了 **verbose**、**trace** 或 **reasoning** 时出现。 + 大多数内部或工具消息只有在该会话启用了 **verbose**、**trace** 或 **reasoning** 时 + 才会出现。 - 在你看到这些消息的聊天中这样修复： + 在你看到这些内容的聊天中这样修复： ``` /verbose off @@ -3207,15 +3213,15 @@ x-i18n: ``` 如果仍然很吵，请检查 Control UI 中的会话设置，并将 verbose - 设为 **inherit**。同时确认你没有使用在配置中将 `verboseDefault` 设为 - `on` 的机器人配置文件。 + 设为 **inherit**。同时确认你没有使用一个在配置中将 `verboseDefault` 设为 + `on` 的机器人 profile。 - 文档：[Thinking and verbose](/zh-CN/tools/thinking)、[Security](/zh-CN/gateway/security#reasoning-verbose-output-in-groups)。 + 文档：[Thinking and fast mode](/zh-CN/tools/thinking)、[Security](/zh-CN/gateway/security#reasoning-verbose-output-in-groups)。 - - 发送以下任意内容，**作为单独的一条消息发送**（不要加斜杠）： + + 将以下任意内容**作为独立消息发送**（不要加斜杠）： ``` stop @@ -3239,7 +3245,7 @@ x-i18n: interrupt ``` - 这些是中止触发词（不是斜杠命令）。 + 这些都是中止触发词（不是斜杠命令）。 对于后台进程（来自 exec 工具），你可以让智能体运行： @@ -3249,13 +3255,13 @@ x-i18n: 斜杠命令概览：请参阅 [Slash commands](/zh-CN/tools/slash-commands)。 - 大多数命令都必须作为**单独的一条**、以 `/` 开头的消息发送，但少数快捷方式（例如 `/status`）也可以对允许列表中的发送者以内联方式生效。 + 大多数命令都必须作为**独立**消息发送，并且以 `/` 开头，但少数快捷命令（如 `/status`）对允许列表中的发送者也支持内联使用。 - OpenClaw 默认会阻止**跨提供商**消息传递。如果某次工具调用绑定到了 - Telegram，它就不会发送到 Discord，除非你显式允许。 + OpenClaw 默认会阻止**跨提供商**消息传递。如果某个工具调用绑定 + 到 Telegram，它就不会发送到 Discord，除非你显式允许。 为该智能体启用跨提供商消息传递： @@ -3276,16 +3282,16 @@ x-i18n: - - 队列模式决定了新消息如何与正在进行中的运行交互。使用 `/queue` 修改模式： + + 队列模式控制新消息如何与正在进行的运行交互。使用 `/queue` 更改模式： - `steer` - 新消息会重定向当前任务 - - `followup` - 逐条处理消息 - - `collect` - 批量收集消息并回复一次（默认） - - `steer-backlog` - 先转向当前任务，然后处理积压 + - `followup` - 消息逐个运行 + - `collect` - 批量收集消息并统一回复（默认） + - `steer-backlog` - 先重定向当前任务，再处理积压消息 - `interrupt` - 中止当前运行并重新开始 - 你还可以为 followup 模式添加选项，例如 `debounce:2s cap:25 drop:summarize`。 + 对于 followup 模式，你还可以添加 `debounce:2s cap:25 drop:summarize` 之类的选项。 @@ -3293,11 +3299,11 @@ x-i18n: ## 其他 - - 在 OpenClaw 中，凭证和模型选择是分开的。设置 `ANTHROPIC_API_KEY`（或在 auth profiles 中存储 Anthropic API key）会启用认证，但实际默认模型仍然取决于你在 `agents.defaults.model.primary` 中的配置（例如 `anthropic/claude-sonnet-4-6` 或 `anthropic/claude-opus-4-6`）。如果你看到 `No credentials found for profile "anthropic:default"`，说明 Gateway 网关 无法在当前运行智能体的预期 `auth-profiles.json` 中找到 Anthropic 凭证。 + + 在 OpenClaw 中，凭证和模型选择是分开的。设置 `ANTHROPIC_API_KEY`（或在凭证配置文件中存储 Anthropic API 密钥）会启用身份验证，但实际默认模型取决于你在 `agents.defaults.model.primary` 中配置的内容（例如 `anthropic/claude-sonnet-4-6` 或 `anthropic/claude-opus-4-6`）。如果你看到 `No credentials found for profile "anthropic:default"`，这表示 Gateway 网关无法在当前运行智能体对应的 `auth-profiles.json` 中找到 Anthropic 凭证。 --- -如果你还是卡住了，请到 [Discord](https://discord.com/invite/clawd) 提问，或创建一个 [GitHub discussion](https://github.com/openclaw/openclaw/discussions)。 +还是卡住了？欢迎到 [Discord](https://discord.com/invite/clawd) 提问，或发起一个 [GitHub discussion](https://github.com/openclaw/openclaw/discussions)。 diff --git a/docs/zh-CN/reference/RELEASING.md b/docs/zh-CN/reference/RELEASING.md index 52db86e74..c4d6c4ebc 100644 --- a/docs/zh-CN/reference/RELEASING.md +++ b/docs/zh-CN/reference/RELEASING.md @@ -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`；真实发布仍然需要真实的发布标签 -- 两个工作流都将真实发布与提升路径保留在 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)