chore(i18n): refresh zh-CN translations

docs/zh-CN/concepts/model-failover.md

@@ -1,51 +1,49 @@
 ---
 read_when:
-    - 诊断凭证配置文件轮换、冷却时间或模型回退行为
-    - 更新凭证配置文件或模型的故障切换规则
-    - 了解会话模型覆盖如何与回退重试交互
-summary: OpenClaw 如何轮换凭证配置文件，并在模型之间执行回退
-title: 模型故障切换
+    - 诊断凭证配置文件轮换、冷却时间或模型故障回退行为
+    - 更新凭证配置文件或模型的故障回退规则
+    - 了解会话模型覆盖如何与故障回退重试交互
+summary: OpenClaw 如何轮换凭证配置文件并在不同模型之间回退
+title: 模型故障回退
 x-i18n:
-    generated_at: "2026-04-06T15:28:05Z"
+    generated_at: "2026-04-23T02:36:31Z"
     model: gpt-5.4
     provider: openai
-    source_hash: d88821e229610f236bdab3f798d5e8c173f61a77c01017cc87431126bf465e32
+    source_hash: 6c1f06d5371379cc59998e1cd6f52d250e8c4eba4e7dbfef776a090899b8d3c4
     source_path: concepts/model-failover.md
     workflow: 15
 ---
 
-# 模型故障切换
+# 模型故障回退
 
-OpenClaw 分两个阶段处理失败：
+OpenClaw 分两个阶段处理故障：
 
 1. 当前提供商内的**凭证配置文件轮换**。
-2. 回退到 `agents.defaults.model.fallbacks` 中的下一个模型，即**模型回退**。
+2. 故障回退到 `agents.defaults.model.fallbacks` 中的下一个**模型**。
 
-本文档说明支撑这些行为的运行时规则和数据。
+本文档解释运行时规则及其背后的数据。
 
 ## 运行时流程
 
 对于一次普通的文本运行，OpenClaw 会按以下顺序评估候选项：
 
-1. 当前选中的会话模型。
+1. 当前选定的会话模型。
 2. 按顺序配置的 `agents.defaults.model.fallbacks`。
-3. 如果本次运行起始于某个覆盖设置，则最后再使用已配置的主模型。
+3. 如果这次运行是从某个覆盖项开始的，则最后使用配置的主模型。
 
-在每个候选项内部，OpenClaw 会先尝试凭证配置文件故障切换，再进入
-下一个模型候选项。
+在每个候选项内部，OpenClaw 会先尝试凭证配置文件故障回退，然后才推进到下一个模型候选项。
 
-高级别流程如下：
+高层级顺序如下：
 
-1. 解析当前激活的会话模型和凭证配置文件偏好。
+1. 解析当前活跃的会话模型和凭证配置文件偏好。
 2. 构建模型候选链。
-3. 按照凭证配置文件轮换 / 冷却规则尝试当前提供商。
-4. 如果该提供商因值得故障切换的错误而耗尽可用项，则移动到下一个
-   模型候选项。
-5. 在重试开始前持久化选中的回退覆盖，这样其他会话读取方会看到运行器即将使用的同一提供商 / 模型。
-6. 如果回退候选项失败，则仅回滚那些由回退拥有的会话覆盖字段，并且仅当它们仍匹配该失败候选项时才回滚。
-7. 如果所有候选项都失败，则抛出带有每次尝试详情及最早冷却到期时间（如果已知）的 `FallbackSummaryError`。
+3. 使用凭证配置文件轮换/冷却规则尝试当前提供商。
+4. 如果该提供商因值得进行故障回退的错误而耗尽，则移动到下一个模型候选项。
+5. 在重试开始前持久化选中的故障回退覆盖项，以便其他会话读取方看到运行器即将使用的同一提供商/模型。
+6. 如果故障回退候选项失败，仅当会话中的故障回退所属覆盖字段仍匹配该失败候选项时，才回滚这些字段。
+7. 如果所有候选项都失败，则抛出一个 `FallbackSummaryError`，其中包含每次尝试的详细信息，以及已知情况下最早的冷却到期时间。
 
-这刻意比“保存并恢复整个会话”更窄。回复运行器只会持久化它为回退所拥有的模型选择字段：
+这刻意比“保存并恢复整个会话”更窄。回复运行器只会持久化它为故障回退所拥有的模型选择字段：
 
 - `providerOverride`
 - `modelOverride`
@@ -53,101 +51,88 @@ OpenClaw 分两个阶段处理失败：
 - `authProfileOverrideSource`
 - `authProfileOverrideCompactionCount`
 
-这样可以防止一次失败的回退重试覆盖更新较新的、无关的会话变更，
-例如手动 `/model` 更改或在尝试运行期间发生的会话轮换更新。
+这样可以防止一次失败的故障回退重试覆盖掉较新的、无关的会话变更，例如在尝试运行期间发生的手动 `/model` 变更或会话轮换更新。
 
 ## 凭证存储（密钥 + OAuth）
 
 OpenClaw 对 API 密钥和 OAuth 令牌都使用**凭证配置文件**。
 
-- 密钥存储在 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（旧版：`~/.openclaw/agent/auth-profiles.json`）。
-- 运行时凭证路由状态存储在 `~/.openclaw/agents/<agentId>/agent/auth-state.json`。
-- 配置 `auth.profiles` / `auth.order` **仅用于元数据 + 路由**（不存储密钥）。
-- 仅用于旧版导入的 OAuth 文件：`~/.openclaw/credentials/oauth.json`（首次使用时会导入到 `auth-profiles.json`）。
+- 密钥存放在 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` 中（旧版路径：`~/.openclaw/agent/auth-profiles.json`）。
+- 运行时凭证路由状态存放在 `~/.openclaw/agents/<agentId>/agent/auth-state.json` 中。
+- 配置 `auth.profiles` / `auth.order` **仅包含元数据 + 路由信息**（不包含密钥）。
+- 旧版仅导入用 OAuth 文件：`~/.openclaw/credentials/oauth.json`（首次使用时导入到 `auth-profiles.json`）。
 
 更多细节：[/concepts/oauth](/zh-CN/concepts/oauth)
 
 凭证类型：
 
 - `type: "api_key"` → `{ provider, key }`
-- `type: "oauth"` → `{ provider, access, refresh, expires, email? }`（某些提供商还会包含 `projectId` / `enterpriseUrl`）
+- `type: "oauth"` → `{ provider, access, refresh, expires, email? }`（某些提供商还包含 `projectId`/`enterpriseUrl`）
 
 ## 配置文件 ID
 
-OAuth 登录会创建不同的配置文件，以便多个账户可以共存。
+OAuth 登录会创建不同的配置文件，以便多个账户共存。
 
-- 默认值：当没有可用邮箱时为 `provider:default`。
+- 默认：当没有可用邮箱时使用 `provider:default`。
 - 带邮箱的 OAuth：`provider:<email>`（例如 `google-antigravity:user@gmail.com`）。
 
-配置文件位于 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` 的 `profiles` 下。
+配置文件存放在 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` 的 `profiles` 下。
 
 ## 轮换顺序
 
-当一个提供商有多个配置文件时，OpenClaw 会按如下方式决定顺序：
+当某个提供商有多个配置文件时，OpenClaw 会按以下方式选择顺序：
 
 1. **显式配置**：`auth.order[provider]`（如果已设置）。
 2. **已配置的配置文件**：按提供商过滤后的 `auth.profiles`。
-3. **已存储的配置文件**：`auth-profiles.json` 中该提供商对应的条目。
+3. **已存储的配置文件**：`auth-profiles.json` 中该提供商的条目。
 
-如果没有配置显式顺序，OpenClaw 会使用轮询顺序：
+如果未配置显式顺序，OpenClaw 会使用轮询顺序：
 
-- **主排序键：** 配置文件类型（**OAuth 优先于 API 密钥**）。
-- **次排序键：** `usageStats.lastUsed`（越久未使用越靠前，同类型内排序）。
-- **处于冷却 / 已禁用的配置文件** 会被移到末尾，并按最早到期时间排序。
+- **主键：**配置文件类型（**OAuth 优先于 API 密钥**）。
+- **次键：**`usageStats.lastUsed`（越早使用的越先尝试，同一类型内如此）。
+- **冷却中/已禁用的配置文件**会被移到末尾，并按最早到期时间排序。
 
-### 会话粘性（对缓存更友好）
+### 会话粘性（有利于缓存）
 
-OpenClaw 会**为每个会话固定所选的凭证配置文件**，以保持提供商缓存处于预热状态。
-它**不会**在每次请求时轮换。固定的配置文件会被重复使用，直到：
+OpenClaw 会**按会话固定选定的凭证配置文件**，以保持提供商缓存处于预热状态。
+它**不会**在每个请求上都轮换。固定的配置文件会持续复用，直到出现以下情况：
 
 - 会话被重置（`/new` / `/reset`）
-- 一次压缩完成（压缩计数增加）
-- 该配置文件处于冷却 / 已禁用状态
+- 一次压缩完成（压缩计数递增）
+- 配置文件处于冷却中/已禁用
 
-通过 `/model …@<profileId>` 进行手动选择会为该会话设置一个**用户覆盖**，
-在新会话开始前不会自动轮换。
+通过 `/model …@<profileId>` 手动选择会为该会话设置一个**用户覆盖项**，在新会话开始前不会自动轮换。
 
-自动固定的配置文件（由会话路由器选中）被视为一种**偏好**：
-它们会被优先尝试，但 OpenClaw 可能会在遇到速率限制 / 超时时轮换到其他配置文件。
-用户固定的配置文件会保持锁定在该配置文件；如果它失败且已配置模型回退，
-OpenClaw 会移动到下一个模型，而不是切换配置文件。
+自动固定的配置文件（由会话路由器选择）被视为一种**偏好**：
+它们会被优先尝试，但 OpenClaw 可能会在遇到速率限制/超时时轮换到其他配置文件。
+用户固定的配置文件会保持锁定在该配置文件上；如果它失败且已配置模型故障回退，OpenClaw 会移动到下一个模型，而不是切换配置文件。
 
-### 为什么 OAuth 可能“看起来丢了”
+### 为什么 OAuth 可能“看起来丢失了”
 
-如果你对同一个提供商同时拥有一个 OAuth 配置文件和一个 API 密钥配置文件，在未固定时，轮询可能会在不同消息之间切换它们。若要强制使用单一配置文件：
+如果同一个提供商同时有一个 OAuth 配置文件和一个 API 密钥配置文件，在未固定的情况下，轮询可能会在不同消息之间切换它们。若要强制使用单一配置文件：
 
 - 使用 `auth.order[provider] = ["provider:profileId"]` 固定，或
-- 通过 `/model …` 使用带配置文件覆盖的按会话覆盖（当你的 UI / 聊天界面支持时）。
+- 使用带配置文件覆盖项的 `/model …` 设置每会话覆盖项（当你的 UI/聊天界面支持时）。
 
 ## 冷却时间
 
-当某个配置文件因凭证 / 速率限制错误（或看起来像速率限制的超时）
-而失败时，OpenClaw 会将其标记为冷却中，并切换到下一个配置文件。
-这个速率限制分类比单纯的 `429` 更宽：它还包括提供商消息，
-例如 `Too many concurrent requests`、`ThrottlingException`、
-`concurrency limit reached`、`workers_ai ... quota limit exceeded`、
-`throttled`、`resource exhausted`，以及周期性使用窗口限制，
-例如 `weekly/monthly limit reached`。
-格式 / 无效请求错误（例如 Cloud Code Assist 工具调用 ID
-校验失败）也会被视为值得故障切换，并使用相同的冷却时间。
-OpenAI 兼容的停止原因错误，例如 `Unhandled stop reason: error`、
-`stop reason: error` 和 `reason: error`，会被归类为超时 / 故障切换
-信号。
-当来源匹配已知瞬态模式时，提供商范围的通用服务器文本也会归入该超时分类。
-例如，Anthropic 的裸文本
-`An unknown error occurred` 以及带有瞬态服务器文本的 JSON `api_error`
-载荷，例如 `internal server error`、`unknown error, 520`、`upstream error`
-或 `backend error`，都会被视为值得故障切换的超时。
-OpenRouter 特有的通用上游文本，例如裸文本 `Provider returned error`，
-只有在提供商上下文确实是 OpenRouter 时才会被视为超时。
-通用的内部回退文本，例如 `LLM request failed with an unknown error.`，
-则保持保守，不会单独触发故障切换。
+当某个配置文件因凭证/速率限制错误（或看起来像速率限制的超时）而失败时，OpenClaw 会将其标记为冷却中，并切换到下一个配置文件。
+该速率限制桶不仅包含普通的 `429`：还包括提供商消息，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`、`throttled`、`resource exhausted`，以及诸如 `weekly/monthly limit reached` 之类的周期性用量窗口限制。
+格式错误/无效请求错误（例如 Cloud Code Assist 工具调用 ID 校验失败）会被视为值得故障回退的错误，并使用相同的冷却机制。
+OpenAI 兼容的停止原因错误，例如 `Unhandled stop reason: error`、`stop reason: error` 和 `reason: error`，会被归类为超时/故障回退信号。
+当来源匹配已知的瞬时模式时，提供商范围的通用服务器文本也可能归入该超时桶。例如，Anthropic 的裸文本 `An unknown error occurred` 以及带有瞬时服务器文本的 JSON `api_error` 负载，例如 `internal server error`、`unknown error, 520`、`upstream error` 或 `backend error`，都会被视为值得故障回退的超时。
+OpenRouter 特有的通用上游文本，例如裸文本 `Provider returned error`，只有在提供商上下文确实是 OpenRouter 时才会被视为超时。
+通用内部回退文本，例如 `LLM request failed with an unknown error.`，会保持保守策略，不会单独触发故障回退。
 
-速率限制冷却也可以按模型划分范围：
+某些提供商 SDK 可能会在将控制权返回给 OpenClaw 之前，先休眠一个很长的 `Retry-After` 时间窗口。
+对于基于 Stainless 的 SDK，例如 Anthropic 和 OpenAI，OpenClaw 默认会将 SDK 内部的 `retry-after-ms` / `retry-after` 等待时间限制在 60 秒以内，并立即暴露更长的可重试响应，以便运行这条故障回退路径。
+可通过 `OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS` 调整或禁用该限制；参见 [/concepts/retry](/zh-CN/concepts/retry)。
+
+速率限制冷却也可以是模型范围的：
 
 - 当已知失败的模型 ID 时，OpenClaw 会为速率限制失败记录 `cooldownModel`。
-- 当冷却限定在不同模型上时，同一提供商上的兄弟模型仍可被尝试。
-- 计费 / 已禁用窗口仍会在所有模型上阻止整个配置文件。
+- 同一提供商下的同级模型仍可在冷却范围限定为其他模型时继续尝试。
+- 计费/禁用窗口仍会在不同模型之间阻止整个配置文件。
 
 冷却时间使用指数退避：
 
@@ -172,13 +157,13 @@ OpenRouter 特有的通用上游文本，例如裸文本 `Provider returned erro
 
 ## 计费禁用
 
-计费 / 额度失败（例如“insufficient credits” / “credit balance too low”）会被视为值得故障切换，但它们通常不是瞬态错误。OpenClaw 不会设置短暂冷却，而是会将该配置文件标记为**已禁用**（使用更长的退避时间），并轮换到下一个配置文件 / 提供商。
+计费/额度失败（例如“insufficient credits” / “credit balance too low”）会被视为值得故障回退的错误，但它们通常不是瞬时性的。
+OpenClaw 不会设置一个短冷却时间，而是会将该配置文件标记为**已禁用**（使用更长的退避时间），并轮换到下一个配置文件/提供商。
 
-并非每个看起来像计费问题的响应都是 `402`，也并非每个 HTTP `402`
-都会归入这里。即使提供商返回的是 `401` 或 `403`，OpenClaw 仍会将明确的计费文本保留在计费分类中，但提供商特定匹配器仍仅限于拥有它们的提供商（例如 OpenRouter 的 `403 Key limit exceeded`）。
-与此同时，临时性的 `402` 使用窗口和组织 / 工作区支出限制错误，如果消息看起来可重试（例如 `weekly usage limit exhausted`、`daily limit reached, resets tomorrow` 或 `organization spending limit exceeded`），则会被归类为 `rate_limit`。
-这些情况会继续走短冷却 / 故障切换路径，而不是长时间的
-计费禁用途径。
+并非每个看起来像计费问题的响应都是 `402`，也并非每个 HTTP `402` 都会进入这里。
+即使某个提供商返回的是 `401` 或 `403`，OpenClaw 仍会将显式计费文本保留在计费通道中，但提供商特定匹配器会保持限定在拥有它们的提供商范围内（例如 OpenRouter 的 `403 Key limit exceeded`）。
+与此同时，临时性的 `402` 用量窗口和组织/工作区支出限制错误，如果消息看起来可重试（例如 `weekly usage limit exhausted`、`daily limit reached, resets tomorrow` 或 `organization spending limit exceeded`），则会被归类为 `rate_limit`。
+这些情况会继续走短冷却/故障回退路径，而不是长时间的计费禁用路径。
 
 状态存储在 `auth-state.json` 中：
 
@@ -195,54 +180,51 @@ OpenRouter 特有的通用上游文本，例如裸文本 `Provider returned erro
 
 默认值：
 
-- 计费退避从 **5 小时**开始，每次计费失败后翻倍，并在 **24 小时**封顶。
-- 如果配置文件在 **24 小时**内未再失败，退避计数器会重置（可配置）。
-- 过载重试在模型回退前允许进行 **1 次同提供商配置文件轮换**。
-- 过载重试默认使用 **0 毫秒退避**。
+- 计费退避从**5 小时**开始，每次计费失败翻倍，并在 **24 小时**封顶。
+- 如果某个配置文件在 **24 小时**内未失败，退避计数器会重置（可配置）。
+- 过载重试在模型故障回退之前，允许**1 次同提供商配置文件轮换**。
+- 过载重试默认使用 **0 毫秒**退避。
 
-## 模型回退
+## 模型故障回退
 
-如果某个提供商的所有配置文件都失败，OpenClaw 会移动到
-`agents.defaults.model.fallbacks` 中的下一个模型。这适用于凭证失败、速率限制，以及耗尽配置文件轮换后的超时（其他错误不会推进回退）。
+如果某个提供商的所有配置文件都失败了，OpenClaw 会移动到 `agents.defaults.model.fallbacks` 中的下一个模型。
+这适用于凭证失败、速率限制，以及已经耗尽配置文件轮换的超时（其他错误不会推进故障回退）。
 
-过载和速率限制错误的处理比计费冷却更激进。默认情况下，
-OpenClaw 允许一次同提供商凭证配置文件重试，然后立即切换到下一个已配置的模型回退，无需等待。
-提供商繁忙信号，例如 `ModelNotReadyException`，会归入该过载分类。
-你可以使用 `auth.cooldowns.overloadedProfileRotations`、
-`auth.cooldowns.overloadedBackoffMs` 和
-`auth.cooldowns.rateLimitedProfileRotations` 进行调整。
+与计费冷却相比，过载和速率限制错误会采用更激进的处理方式。
+默认情况下，OpenClaw 允许一次同提供商凭证配置文件重试，然后不等待，直接切换到下一个已配置的模型故障回退。
+诸如 `ModelNotReadyException` 之类的提供商繁忙信号会归入该过载桶。
+可通过 `auth.cooldowns.overloadedProfileRotations`、`auth.cooldowns.overloadedBackoffMs` 和 `auth.cooldowns.rateLimitedProfileRotations` 进行调整。
 
-当一次运行以模型覆盖开始时（hooks 或 CLI），在尝试完任何已配置回退后，
-回退仍会以 `agents.defaults.model.primary` 结束。
+当一次运行以模型覆盖项开始时（hooks 或 CLI），故障回退在尝试完所有已配置回退项后，仍会以 `agents.defaults.model.primary` 结束。
 
 ### 候选链规则
 
-OpenClaw 会根据当前请求的 `provider/model` 与已配置回退构建候选列表。
+OpenClaw 会根据当前请求的 `provider/model` 和已配置的故障回退构建候选列表。
 
 规则：
 
 - 请求的模型始终排在第一位。
-- 显式配置的回退会去重，但不会按模型允许列表过滤。它们被视为运维方的显式意图。
-- 如果当前运行已经在同一提供商家族中的某个已配置回退上，OpenClaw 会继续使用完整的已配置链。
-- 如果当前运行所在的提供商与配置不同，并且该当前模型尚未包含在已配置回退链中，OpenClaw 不会附加来自其他提供商的无关已配置回退。
-- 当运行起始于某个覆盖设置时，已配置的主模型会附加到末尾，这样在较早候选项耗尽后，候选链可以回到正常默认值。
+- 显式配置的故障回退会去重，但不会按模型允许列表进行过滤。它们被视为明确的运维意图。
+- 如果当前运行已经位于同一提供商家族中的某个已配置故障回退上，OpenClaw 会继续使用完整的已配置链。
+- 如果当前运行使用的提供商与配置不同，且当前模型并不属于已配置的故障回退链，OpenClaw 不会附加来自其他提供商的无关已配置故障回退。
+- 当运行是从某个覆盖项开始时，配置的主模型会被追加到末尾，以便在前面的候选项耗尽后，候选链可以重新回到正常的默认值。
 
-### 哪些错误会推进回退
+### 哪些错误会推进故障回退
 
-模型回退会在以下情况继续：
+模型故障回退会在以下情况继续：
 
 - 凭证失败
 - 速率限制和冷却耗尽
-- 过载 / 提供商繁忙错误
-- 类超时的故障切换错误
+- 过载/提供商繁忙错误
+- 具有超时特征的故障回退错误
 - 计费禁用
-- `LiveSessionModelSwitchError`，它会被规范化为故障切换路径，这样过时的持久化模型就不会形成外层重试循环
-- 当仍有剩余候选项时，其他无法识别的错误
+- `LiveSessionModelSwitchError`，它会被规范化为故障回退路径，以避免陈旧的持久化模型造成外层重试循环
+- 当仍有剩余候选项时，其他未识别错误
 
-模型回退不会在以下情况继续：
+模型故障回退不会在以下情况继续：
 
-- 不属于超时 / 故障切换形态的显式中止
-- 应保留在压缩 / 重试逻辑内部的上下文溢出错误
+- 明确的中止，且不具备超时/故障回退特征
+- 应保留在压缩/重试逻辑内部处理的上下文溢出错误
   （例如 `request_too_large`、`INVALID_ARGUMENT: input exceeds the maximum
 number of tokens`、`input token count exceeds the maximum number of input
 tokens`、`The input is too long for the model` 或 `ollama error: context
@@ -251,56 +233,55 @@ length exceeded`）
 
 ### 冷却跳过与探测行为
 
-当某个提供商的所有凭证配置文件都已经处于冷却中时，OpenClaw 不会自动永久跳过该提供商。它会针对每个候选项单独决策：
+当某个提供商的所有凭证配置文件都已处于冷却中时，OpenClaw 不会自动永久跳过该提供商。它会按每个候选项逐一做出决定：
 
-- 持续性的凭证失败会立即跳过整个提供商。
-- 计费禁用通常会跳过，但主候选项仍可能在节流条件下被探测，以便无需重启也能恢复。
-- 在接近冷却到期时，主候选项可能会被探测，并带有按提供商区分的节流限制。
-- 即使存在冷却，同提供商的回退兄弟项在失败看起来是瞬态时（`rate_limit`、`overloaded` 或未知）仍可被尝试。当速率限制是模型范围时，而兄弟模型可能仍可立即恢复，这一点尤其重要。
-- 瞬态冷却探测在每次回退运行中每个提供商最多仅允许一次，因此单个提供商不会拖慢跨提供商回退。
+- 持久性凭证失败会立即跳过整个提供商。
+- 计费禁用通常会被跳过，但主候选项仍可按节流策略进行探测，这样无需重启也能恢复。
+- 主候选项可能会在接近冷却到期时被探测，并带有每个提供商的节流限制。
+- 即使处于冷却中，同一提供商下的故障回退同级模型仍然可以尝试，前提是该失败看起来是瞬时性的（`rate_limit`、`overloaded` 或未知）。当速率限制是模型范围的，而同级模型仍可能立即恢复时，这一点尤其重要。
+- 瞬时冷却探测在每次故障回退运行中，每个提供商最多只允许一次，以避免单个提供商拖慢跨提供商故障回退。
 
-## 会话覆盖与实时模型切换
+## 会话覆盖项与实时模型切换
 
-会话模型更改属于共享状态。活动运行器、`/model` 命令、
-压缩 / 会话更新，以及实时会话协调逻辑都会读取或写入同一个会话条目的不同部分。
+会话模型变更属于共享状态。活跃运行器、`/model` 命令、压缩/会话更新以及实时会话协调，都会读取或写入同一个会话条目的不同部分。
 
-这意味着回退重试必须与实时模型切换协调：
+这意味着故障回退重试必须与实时模型切换进行协调：
 
-- 只有显式的用户驱动模型更改才会标记待处理的实时切换。这包括 `/model`、`session_status(model=...)` 和 `sessions.patch`。
-- 由系统驱动的模型更改，例如回退轮换、心跳覆盖或压缩，不会自行标记待处理的实时切换。
-- 在回退重试开始前，回复运行器会将选中的回退覆盖字段持久化到会话条目中。
-- 实时会话协调会优先使用持久化的会话覆盖，而不是过时的运行时模型字段。
-- 如果回退尝试失败，运行器只会回滚它写入的覆盖字段，并且仅当这些字段仍匹配该失败候选项时才会回滚。
+- 只有明确由用户驱动的模型变更才会标记待处理的实时切换。这包括 `/model`、`session_status(model=...)` 和 `sessions.patch`。
+- 由系统驱动的模型变更，例如故障回退轮换、心跳覆盖项或压缩，本身不会标记待处理的实时切换。
+- 在故障回退重试开始之前，回复运行器会将选中的故障回退覆盖字段持久化到会话条目中。
+- 实时会话协调会优先采用持久化的会话覆盖项，而不是过时的运行时模型字段。
+- 如果故障回退尝试失败，运行器只会回滚它写入的覆盖字段，并且仅当这些字段仍与失败候选项匹配时才会回滚。
 
-这可以防止经典竞争条件：
+这可以防止经典竞争情况：
 
 1. 主模型失败。
-2. 回退候选项在内存中被选中。
-3. 会话存储仍显示旧的主模型。
-4. 实时会话协调读取了过时的会话状态。
-5. 在回退尝试开始前，重试又被拉回旧模型。
+2. 在内存中选中了故障回退候选项。
+3. 会话存储中仍然记录的是旧的主模型。
+4. 实时会话协调读取到了过时的会话状态。
+5. 在故障回退尝试开始前，重试被拉回到旧模型。
 
-持久化的回退覆盖封住了这个窗口，而范围收窄的回滚则能保持更新的手动或运行时会话更改不受影响。
+持久化的故障回退覆盖项关闭了这个时间窗口，而范围收窄的回滚则能保持较新的手动或运行时会话变更不受影响。
 
 ## 可观测性与失败摘要
 
-`runWithModelFallback(...)` 会记录每次尝试的详细信息，以供日志记录和面向用户的冷却消息使用：
+`runWithModelFallback(...)` 会记录每次尝试的详细信息，用于日志和面向用户的冷却消息：
 
-- 尝试过的提供商 / 模型
-- 原因（`rate_limit`、`overloaded`、`billing`、`auth`、`model_not_found` 以及类似的故障切换原因）
-- 可选的状态 / 代码
+- 尝试过的提供商/模型
+- 原因（`rate_limit`、`overloaded`、`billing`、`auth`、`model_not_found` 以及类似的故障回退原因）
+- 可选的状态/代码
 - 人类可读的错误摘要
 
-当所有候选项都失败时，OpenClaw 会抛出 `FallbackSummaryError`。外层回复运行器可以据此构建更具体的消息，例如“所有模型当前都受到临时速率限制”，并在已知时包含最早的冷却到期时间。
+当所有候选项都失败时，OpenClaw 会抛出 `FallbackSummaryError`。外层回复运行器可以用它来构建更具体的消息，例如“所有模型都暂时受到速率限制”，并在已知情况下包含最早的冷却到期时间。
 
-该冷却摘要是模型感知的：
+该冷却摘要具有模型感知能力：
 
-- 对于已尝试的提供商 / 模型链，无关的模型范围速率限制会被忽略
-- 如果剩余阻塞是匹配的模型范围速率限制，OpenClaw 会报告仍阻止该模型的最后一个匹配到期时间
+- 与已尝试的提供商/模型链无关的模型范围速率限制会被忽略
+- 如果剩余阻塞项是匹配的模型范围速率限制，OpenClaw 会报告仍然阻止该模型的最后一个匹配到期时间
 
 ## 相关配置
 
-有关以下内容，请参见 [Gateway 网关配置](/zh-CN/gateway/configuration)：
+有关以下内容，请参见[Gateway 网关配置](/zh-CN/gateway/configuration)：
 
 - `auth.profiles` / `auth.order`
 - `auth.cooldowns.billingBackoffHours` / `auth.cooldowns.billingBackoffHoursByProvider`
@@ -310,4 +291,4 @@ length exceeded`）
 - `agents.defaults.model.primary` / `agents.defaults.model.fallbacks`
 - `agents.defaults.imageModel` 路由
 
-有关更广泛的模型选择与回退概览，请参见 [模型](/zh-CN/concepts/models)。
+有关更广泛的模型选择和故障回退概览，请参见[模型](/zh-CN/concepts/models)。

docs/zh-CN/concepts/retry.md

@@ -1,51 +1,58 @@
 ---
 read_when:
-  - 更新提供商重试行为或默认值
-  - 调试提供商发送错误或速率限制
+    - 更新提供商重试行为或默认值
+    - 调试提供商发送错误或速率限制
 summary: 出站提供商调用的重试策略
 title: 重试策略
 x-i18n:
-  generated_at: "2026-02-01T20:23:37Z"
-  model: claude-opus-4-6
-  provider: pi
-  source_hash: 55bb261ff567f46ce447be9c0ee0c5b5e6d2776287d7662762656c14108dd607
-  source_path: concepts/retry.md
-  workflow: 14
+    generated_at: "2026-04-23T02:36:27Z"
+    model: gpt-5.4
+    provider: openai
+    source_hash: aa16219d197492be15925dfd49359cfbed20e53ecdaa5309bbe122d4fe611e75
+    source_path: concepts/retry.md
+    workflow: 15
 ---
 
 # 重试策略
 
 ## 目标
 
-- 按 HTTP 请求重试，而非按多步骤流程重试。
-- 通过仅重试当前步骤来保持顺序。
+- 按每个 HTTP 请求重试，而不是按多步骤流程重试。
+- 仅重试当前步骤，以保留顺序。
 - 避免重复执行非幂等操作。
 
 ## 默认值
 
 - 尝试次数：3
-- 最大延迟上限：30000 毫秒
+- 最大延迟上限：30000 ms
 - 抖动：0.1（10%）
 - 提供商默认值：
-  - Telegram 最小延迟：400 毫秒
-  - Discord 最小延迟：500 毫秒
+  - Telegram 最小延迟：400 ms
+  - Discord 最小延迟：500 ms
 
 ## 行为
 
+### 模型提供商
+
+- OpenClaw 让 provider SDK 处理常规的短时重试。
+- 对于基于 Stainless 的 SDK，例如 Anthropic 和 OpenAI，可重试响应（`408`、`409`、`429` 和 `5xx`）可以包含 `retry-after-ms` 或 `retry-after`。当该等待时间长于 60 秒时，OpenClaw 会注入 `x-should-retry: false`，使 SDK 立即暴露错误，并让模型故障切换轮换到另一个认证配置文件或回退模型。
+- 使用 `OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS=<seconds>` 覆盖该上限。
+  将其设置为 `0`、`false`、`off`、`none` 或 `disabled`，即可让 SDK 在内部遵循较长的 `Retry-After` 睡眠等待。
+
 ### Discord
 
 - 仅在速率限制错误（HTTP 429）时重试。
-- 可用时使用 Discord `retry_after`，否则使用指数退避。
+- 在可用时使用 Discord 的 `retry_after`，否则使用指数退避。
 
 ### Telegram
 
 - 在瞬态错误时重试（429、超时、连接/重置/关闭、暂时不可用）。
-- 可用时使用 `retry_after`，否则使用指数退避。
-- Markdown 解析错误不会重试；会回退为纯文本。
+- 在可用时使用 `retry_after`，否则使用指数退避。
+- Markdown 解析错误不会重试；它们会回退为纯文本。
 
 ## 配置
 
-在 `~/.openclaw/openclaw.json` 中按提供商设置重试策略：
+在 `~/.openclaw/openclaw.json` 中为每个提供商设置重试策略：
 
 ```json5
 {
@@ -70,7 +77,7 @@ x-i18n:
 }
 ```
 
-## 注意事项
+## 说明
 
-- 重试按请求应用（消息发送、媒体上传、表情回应、投票、贴纸）。
-- 组合流程不会重试已完成的步骤。
+- 重试按每个请求生效（消息发送、媒体上传、表情回应、投票、贴纸）。
+- 复合流程不会重试已完成的步骤。

docs/zh-CN/reference/wizard.md

@@ -4,13 +4,13 @@ read_when:
     - 使用非交互模式自动化新手引导
     - 调试新手引导行为
 sidebarTitle: Onboarding Reference
-summary: CLI 新手引导的完整参考：每一步、每个标志和每个配置字段
+summary: CLI 新手引导的完整参考：每个步骤、标志和配置字段
 title: 新手引导参考
 x-i18n:
-    generated_at: "2026-04-15T13:38:05Z"
+    generated_at: "2026-04-23T02:36:29Z"
     model: gpt-5.4
     provider: openai
-    source_hash: 1db3ff789422617634e6624f9d12c18b6a6c573721226b9c0fa6f6b7956ef33d
+    source_hash: 51405f5d9ba3d9553662fd0a03254a709d5eb4b27339c5edfe1da1111629d0dd
     source_path: reference/wizard.md
     workflow: 15
 ---
@@ -20,34 +20,35 @@ x-i18n:
 这是 `openclaw onboard` 的完整参考。
 如需高层概览，请参阅 [设置向导（CLI）](/zh-CN/start/wizard)。
 
-## 流程细节（本地模式）
+## 流程详情（本地模式）
 
 <Steps>
   <Step title="现有配置检测">
-    - 如果 `~/.openclaw/openclaw.json` 已存在，选择 **保留 / 修改 / 重置**。
+    - 如果 `~/.openclaw/openclaw.json` 存在，选择 **保留 / 修改 / 重置**。
     - 重新运行新手引导**不会**清除任何内容，除非你明确选择 **重置**
       （或传入 `--reset`）。
     - CLI `--reset` 默认作用于 `config+creds+sessions`；使用 `--reset-scope full`
-      还会移除工作区。
-    - 如果配置无效或包含旧版键名，向导会停止并要求
-      你先运行 `openclaw doctor`，然后再继续。
+      可额外删除工作区。
+    - 如果配置无效或包含旧版键名，向导会停止，并要求
+      你在继续之前运行 `openclaw doctor`。
     - 重置使用 `trash`（绝不使用 `rm`），并提供以下范围：
       - 仅配置
       - 配置 + 凭证 + 会话
-      - 完全重置（还会移除工作区）
+      - 完全重置（也会删除工作区）
   </Step>
   <Step title="模型/凭证">
-    - **Anthropic API 密钥**：如果存在 `ANTHROPIC_API_KEY` 就使用它，否则提示输入密钥，然后保存以供守护进程使用。
-    - **Anthropic API 密钥**：是新手引导/配置中首选的 Anthropic 助手选项。
-    - **Anthropic setup-token**：在新手引导/配置中仍可用，不过当可用时，OpenClaw 现在更倾向于复用 Claude CLI。
-    - **OpenAI Code（Codex）订阅（Codex CLI）**：如果 `~/.codex/auth.json` 存在，新手引导可以复用它。被复用的 Codex CLI 凭证仍由 Codex CLI 管理；过期时，OpenClaw 会先重新读取该来源，并且当提供商可以刷新它时，会把刷新的凭证写回 Codex 存储，而不是自行接管。
+    - **Anthropic API 密钥**：如果存在则使用 `ANTHROPIC_API_KEY`，否则提示你输入密钥，然后保存以供守护进程使用。
+    - **Anthropic API 密钥**：在新手引导/配置中是 Anthropic 助手的首选项。
+    - **Anthropic setup-token**：在新手引导/配置中仍然可用，不过 OpenClaw 现在在可用时更倾向于复用 Claude CLI。
     - **OpenAI Code（Codex）订阅（OAuth）**：浏览器流程；粘贴 `code#state`。
-      - 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设为 `openai-codex/gpt-5.4`。
-    - **OpenAI API 密钥**：如果存在 `OPENAI_API_KEY` 就使用它，否则提示输入密钥，然后将其存储到凭证配置中。
-      - 当模型未设置、为 `openai/*` 或 `openai-codex/*` 时，将 `agents.defaults.model` 设为 `openai/gpt-5.4`。
+      - 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.4`。
+    - **OpenAI Code（Codex）订阅（设备配对）**：使用短时效设备代码的浏览器配对流程。
+      - 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.4`。
+    - **OpenAI API 密钥**：如果存在则使用 `OPENAI_API_KEY`，否则提示你输入密钥，然后将其存储到凭证配置文件中。
+      - 当模型未设置、为 `openai/*` 或 `openai-codex/*` 时，将 `agents.defaults.model` 设置为 `openai/gpt-5.4`。
     - **xAI（Grok）API 密钥**：提示输入 `XAI_API_KEY`，并将 xAI 配置为模型提供商。
-    - **OpenCode**：提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`，可在 https://opencode.ai/auth 获取），并让你选择 Zen 或 Go 目录。
-    - **Ollama**：首先提供 **Cloud + Local**、**仅 Cloud** 或 **仅 Local**。`仅 Cloud` 会提示输入 `OLLAMA_API_KEY` 并使用 `https://ollama.com`；依赖主机的模式会提示输入 Ollama 基础 URL、发现可用模型，并在需要时自动拉取所选本地模型；`Cloud + Local` 还会检查该 Ollama 主机是否已登录以访问云端。
+    - **OpenCode**：提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`，可在 https://opencode.ai/auth 获取），并允许你选择 Zen 或 Go 目录。
+    - **Ollama**：首先提供 **Cloud + Local**、**仅 Cloud** 或 **仅 Local**。`仅 Cloud` 会提示输入 `OLLAMA_API_KEY` 并使用 `https://ollama.com`；依赖主机的模式会提示输入 Ollama 基础 URL、发现可用模型，并在需要时自动拉取所选本地模型；`Cloud + Local` 还会检查该 Ollama 主机是否已登录以使用云访问。
     - 更多详情：[Ollama](/zh-CN/providers/ollama)
     - **API 密钥**：会为你存储该密钥。
     - **Vercel AI Gateway（多模型代理）**：提示输入 `AI_GATEWAY_API_KEY`。
@@ -58,7 +59,7 @@ x-i18n:
       API 密钥设置使用 `minimax/...`，OAuth 设置使用
       `minimax-portal/...`。
     - 更多详情：[MiniMax](/zh-CN/providers/minimax)
-    - **StepFun**：会为中国区或全球端点上的 StepFun standard 或 Step Plan 自动写入配置。
+    - **StepFun**：会为中国或全球端点上的 StepFun standard 或 Step Plan 自动写入配置。
     - Standard 当前包含 `step-3.5-flash`，Step Plan 还包含 `step-3.5-flash-2603`。
     - 更多详情：[StepFun](/zh-CN/providers/stepfun)
     - **Synthetic（兼容 Anthropic）**：提示输入 `SYNTHETIC_API_KEY`。
@@ -67,89 +68,89 @@ x-i18n:
     - **Kimi Coding**：会自动写入配置。
     - 更多详情：[Moonshot AI（Kimi + Kimi Coding）](/zh-CN/providers/moonshot)
     - **跳过**：暂不配置凭证。
-    - 从检测到的选项中选择默认模型（或手动输入 provider/model）。为了获得最佳质量并降低提示注入风险，请选择你当前提供商栈中可用的最强最新一代模型。
-    - 新手引导会运行模型检查，并在配置的模型未知或缺少凭证时发出警告。
-    - API 密钥存储模式默认使用明文凭证配置值。使用 `--secret-input-mode ref` 可改为存储基于环境变量的引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`）。
-    - 凭证配置位于 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（API 密钥 + OAuth）。`~/.openclaw/credentials/oauth.json` 仅用于导入旧版数据。
+    - 从检测到的选项中选择一个默认模型（或手动输入 provider/model）。为获得最佳质量并降低提示注入风险，请选择你的提供商栈中可用的最新一代最强模型。
+    - 新手引导会执行模型检查；如果配置的模型未知或缺少凭证，会发出警告。
+    - API 密钥存储模式默认使用明文 auth-profile 值。使用 `--secret-input-mode ref` 可改为存储基于环境变量的引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`）。
+    - 凭证配置文件位于 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（API 密钥 + OAuth）。`~/.openclaw/credentials/oauth.json` 仅用于导入旧版数据。
     - 更多详情：[/concepts/oauth](/zh-CN/concepts/oauth)
     <Note>
     无头/服务器提示：先在有浏览器的机器上完成 OAuth，然后复制
     该智能体的 `auth-profiles.json`（例如
     `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`，或对应的
     `$OPENCLAW_STATE_DIR/...` 路径）到 Gateway 网关主机。`credentials/oauth.json`
-    仅是旧版导入来源。
+    只是旧版导入来源。
     </Note>
   </Step>
   <Step title="工作区">
-    - 默认是 `~/.openclaw/workspace`（可配置）。
-    - 初始化智能体引导仪式所需的工作区文件。
-    - 完整工作区布局 + 备份指南：[智能体工作区](/zh-CN/concepts/agent-workspace)
+    - 默认为 `~/.openclaw/workspace`（可配置）。
+    - 会初始化智能体引导仪式所需的工作区文件。
+    - 完整工作区布局和备份指南：[智能体工作区](/zh-CN/concepts/agent-workspace)
   </Step>
   <Step title="Gateway 网关">
     - 端口、绑定、认证模式、Tailscale 暴露。
-    - 认证建议：即使是 loopback，也请保持 **Token**，这样本地 WS 客户端也必须认证。
+    - 认证建议：即使是 loopback，也保留 **Token**，这样本地 WS 客户端也必须进行认证。
     - 在 token 模式下，交互式设置提供：
       - **生成/存储明文 token**（默认）
       - **使用 SecretRef**（可选启用）
-      - 快速开始会复用现有的 `gateway.auth.token` SecretRef，包括 `env`、`file` 和 `exec` 提供商，用于新手引导探测/仪表板引导。
-      - 如果已配置该 SecretRef 但无法解析，新手引导会尽早失败并给出明确修复信息，而不是静默降低运行时认证。
-    - 在密码模式下，交互式设置也支持明文或 SecretRef 存储。
-    - 非交互 token SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
-      - 要求新手引导进程环境中存在一个非空环境变量。
-      - 不能与 `--gateway-token` 组合使用。
-    - 仅当你完全信任每一个本地进程时才禁用认证。
-    - 非 loopback 绑定仍然需要认证。
+      - 快速开始会在新手引导探测/仪表板引导中，复用 `env`、`file` 和 `exec` 提供商上现有的 `gateway.auth.token` SecretRef。
+      - 如果该 SecretRef 已配置但无法解析，新手引导会尽早失败，并给出清晰的修复信息，而不是静默降级运行时认证。
+    - 在 password 模式下，交互式设置同样支持明文或 SecretRef 存储。
+    - 非交互式 token SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
+      - 要求在新手引导进程环境中存在非空环境变量。
+      - 不能与 `--gateway-token` 同时使用。
+    - 只有在你完全信任每个本地进程时才禁用认证。
+    - 非 loopback 绑定仍然要求认证。
   </Step>
   <Step title="渠道">
-    - [WhatsApp](/zh-CN/channels/whatsapp)：可选 QR 登录。
+    - [WhatsApp](/zh-CN/channels/whatsapp)：可选二维码登录。
     - [Telegram](/zh-CN/channels/telegram)：机器人 token。
     - [Discord](/zh-CN/channels/discord)：机器人 token。
     - [Google Chat](/zh-CN/channels/googlechat)：服务账号 JSON + webhook audience。
     - [Mattermost](/zh-CN/channels/mattermost)（插件）：机器人 token + 基础 URL。
-    - [Signal](/zh-CN/channels/signal)：可选 `signal-cli` 安装 + 账号配置。
+    - [Signal](/zh-CN/channels/signal)：可选安装 `signal-cli` + 账号配置。
     - [BlueBubbles](/zh-CN/channels/bluebubbles)：**推荐用于 iMessage**；服务器 URL + 密码 + webhook。
     - [iMessage](/zh-CN/channels/imessage)：旧版 `imsg` CLI 路径 + DB 访问。
-    - 私信安全：默认采用配对。首次私信会发送一个代码；通过 `openclaw pairing approve <channel> <code>` 批准，或使用允许列表。
+    - 私信安全：默认启用配对。首次私信会发送验证码；通过 `openclaw pairing approve <channel> <code>` 批准，或使用允许列表。
   </Step>
   <Step title="Web 搜索">
     - 选择一个受支持的提供商，例如 Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Ollama Web 搜索、Perplexity、SearXNG 或 Tavily（或跳过）。
-    - 基于 API 的提供商可使用环境变量或现有配置进行快速设置；无密钥提供商则使用各自提供商特定的前置条件。
+    - 基于 API 的提供商可使用环境变量或现有配置进行快速设置；无密钥提供商则使用其特定前置条件。
     - 使用 `--skip-search` 跳过。
-    - 之后再配置：`openclaw configure --section web`。
+    - 稍后配置：`openclaw configure --section web`。
   </Step>
-  <Step title="安装守护进程">
+  <Step title="守护进程安装">
     - macOS：LaunchAgent
-      - 需要已登录的用户会话；对于无头环境，请使用自定义 LaunchDaemon（未内置提供）。
+      - 需要已登录的用户会话；对于无头环境，请使用自定义 LaunchDaemon（未随附）。
     - Linux（以及通过 WSL2 的 Windows）：systemd 用户单元
-      - 新手引导会尝试启用 lingering：`loginctl enable-linger <user>`，以便 Gateway 网关在注销后继续运行。
-      - 可能会提示 sudo（会写入 `/var/lib/systemd/linger`）；它会先尝试不使用 sudo。
-    - **运行时选择：** Node（推荐；WhatsApp/Telegram 必需）。**不推荐** Bun。
-    - 如果 token 认证需要 token 且 `gateway.auth.token` 由 SecretRef 管理，守护进程安装会验证它，但不会将解析后的明文 token 值持久化到 supervisor 服务环境元数据中。
-    - 如果 token 认证需要 token 且已配置的 token SecretRef 无法解析，守护进程安装会被阻止，并给出可执行的指引。
-    - 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，但未设置 `gateway.auth.mode`，则守护进程安装会被阻止，直到显式设置 mode。
+      - 新手引导会尝试通过 `loginctl enable-linger <user>` 启用 lingering，这样 Gateway 网关会在注销后继续运行。
+      - 可能会提示输入 sudo（会写入 `/var/lib/systemd/linger`）；它会先尝试不使用 sudo。
+    - **运行时选择：** Node（推荐；WhatsApp/Telegram 必需）。Bun **不推荐**。
+    - 如果 token 认证需要 token，且 `gateway.auth.token` 由 SecretRef 管理，守护进程安装会验证它，但不会将解析后的明文 token 值持久化到监督服务环境元数据中。
+    - 如果 token 认证需要 token，而已配置的 token SecretRef 未解析，守护进程安装会被阻止，并提供可执行的指导。
+    - 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，但未设置 `gateway.auth.mode`，守护进程安装会被阻止，直到显式设置模式。
   </Step>
   <Step title="健康检查">
-    - 启动 Gateway 网关（如有需要），然后运行 `openclaw health`。
-    - 提示：`openclaw status --deep` 会在状态输出中加入实时 Gateway 网关健康探测，包括支持时的渠道探测（需要 Gateway 网关可达）。
+    - 启动 Gateway 网关（如有需要）并运行 `openclaw health`。
+    - 提示：`openclaw status --deep` 会将实时 Gateway 网关健康探测添加到状态输出中，包括在支持时的渠道探测（需要 Gateway 网关可访问）。
   </Step>
   <Step title="Skills（推荐）">
     - 读取可用的 Skills 并检查要求。
-    - 让你选择一个 node 管理器：**npm / pnpm**（不推荐 bun）。
-    - 安装可选依赖（其中一些在 macOS 上使用 Homebrew）。
+    - 让你选择一个节点管理器：**npm / pnpm**（bun 不推荐）。
+    - 安装可选依赖项（其中一些在 macOS 上使用 Homebrew）。
   </Step>
   <Step title="完成">
-    - 摘要 + 后续步骤，包括 iOS/Android/macOS 应用以获得额外功能。
+    - 摘要 + 后续步骤，包括提供更多功能的 iOS/Android/macOS 应用。
   </Step>
 </Steps>
 
 <Note>
 如果未检测到 GUI，新手引导会打印用于 Control UI 的 SSH 端口转发说明，而不是打开浏览器。
-如果缺少 Control UI 资源，新手引导会尝试构建它们；回退命令为 `pnpm ui:build`（会自动安装 UI 依赖）。
+如果缺少 Control UI 资源，新手引导会尝试构建它们；回退命令是 `pnpm ui:build`（会自动安装 UI 依赖）。
 </Note>
 
 ## 非交互模式
 
-使用 `--non-interactive` 来自动化或脚本化新手引导：
+使用 `--non-interactive` 来自动化或编写新手引导脚本：
 
 ```bash
 openclaw onboard --non-interactive \
@@ -163,9 +164,9 @@ openclaw onboard --non-interactive \
   --skip-skills
 ```
 
-添加 `--json` 可获得机器可读的摘要。
+添加 `--json` 可获得机器可读摘要。
 
-非交互模式中的 Gateway 网关 token SecretRef：
+在非交互模式下使用 Gateway 网关 token SecretRef：
 
 ```bash
 export OPENCLAW_GATEWAY_TOKEN="your-token"
@@ -176,13 +177,13 @@ openclaw onboard --non-interactive \
   --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN
 ```
 
-`--gateway-token` 和 `--gateway-token-ref-env` 互斥。
+`--gateway-token` 与 `--gateway-token-ref-env` 互斥。
 
 <Note>
 `--json` **不**意味着非交互模式。脚本中请使用 `--non-interactive`（以及 `--workspace`）。
 </Note>
 
-提供商专用命令示例位于 [CLI 自动化](/zh-CN/start/wizard-cli-automation#provider-specific-examples)。
+各提供商的命令示例见 [CLI 自动化](/zh-CN/start/wizard-cli-automation#provider-specific-examples)。
 本参考页用于说明标志语义和步骤顺序。
 
 ### 添加智能体（非交互）
@@ -203,29 +204,29 @@ Gateway 网关通过 RPC 暴露新手引导流程（`wizard.start`、`wizard.nex
 
 ## Signal 设置（signal-cli）
 
-新手引导可以从 GitHub releases 安装 `signal-cli`：
+新手引导可以从 GitHub Releases 安装 `signal-cli`：
 
-- 下载适当的发布资源。
-- 将其存储在 `~/.openclaw/tools/signal-cli/<version>/` 下。
+- 下载相应的发布资源。
+- 将其存储到 `~/.openclaw/tools/signal-cli/<version>/` 下。
 - 将 `channels.signal.cliPath` 写入你的配置。
 
-注意：
+说明：
 
 - JVM 构建需要 **Java 21**。
-- 若可用，则使用原生构建。
-- Windows 使用 WSL2；`signal-cli` 安装会在 WSL 内按照 Linux 流程进行。
+- 在可用时会使用原生构建。
+- Windows 使用 WSL2；`signal-cli` 安装会在 WSL 内按 Linux 流程执行。
 
-## 向导会写入什么内容
+## 向导会写入什么
 
 `~/.openclaw/openclaw.json` 中的典型字段：
 
 - `agents.defaults.workspace`
 - `agents.defaults.model` / `models.providers`（如果选择了 MiniMax）
 - `tools.profile`（本地新手引导在未设置时默认使用 `"coding"`；现有的显式值会被保留）
-- `gateway.*`（mode、bind、auth、tailscale）
-- `session.dmScope`（行为细节：[CLI 设置参考](/zh-CN/start/wizard-cli-reference#outputs-and-internals)）
+- `gateway.*`（模式、绑定、认证、Tailscale）
+- `session.dmScope`（行为详情：[CLI 设置参考](/zh-CN/start/wizard-cli-reference#outputs-and-internals)）
 - `channels.telegram.botToken`、`channels.discord.token`、`channels.matrix.*`、`channels.signal.*`、`channels.imessage.*`
-- 当你在提示中选择启用时，会写入渠道允许列表（Slack/Discord/Matrix/Microsoft Teams）（名称会在可能时解析为 ID）。
+- 如果你在提示中选择启用，还会写入渠道允许列表（Slack/Discord/Matrix/Microsoft Teams）；在可能的情况下，名称会解析为 ID。
 - `skills.install.nodeManager`
   - `setup --node-manager` 接受 `npm`、`pnpm` 或 `bun`。
   - 手动配置仍可通过直接设置 `skills.install.nodeManager` 来使用 `yarn`。
@@ -237,10 +238,10 @@ Gateway 网关通过 RPC 暴露新手引导流程（`wizard.start`、`wizard.nex
 
 `openclaw agents add` 会写入 `agents.list[]` 和可选的 `bindings`。
 
-WhatsApp 凭证存放在 `~/.openclaw/credentials/whatsapp/<accountId>/` 下。
+WhatsApp 凭证存储在 `~/.openclaw/credentials/whatsapp/<accountId>/` 下。
 会话存储在 `~/.openclaw/agents/<agentId>/sessions/` 下。
 
-某些渠道以插件形式提供。当你在设置过程中选择其中一个时，新手引导
+某些渠道以插件形式提供。当你在设置期间选择其中之一时，新手引导
 会先提示安装它（npm 或本地路径），然后才能进行配置。
 
 ## 相关文档

docs/zh-CN/start/wizard-cli-reference.md

@@ -1,15 +1,15 @@
 ---
 read_when:
-    - 你需要 `openclaw onboard` 的详细行为说明
-    - 你正在调试新手引导结果或集成新手引导客户端
+    - 你需要了解 `openclaw onboard` 的详细行为
+    - 你正在调试新手引导结果，或集成新手引导客户端
 sidebarTitle: CLI reference
-summary: CLI 设置流程、凭证/模型设置、输出和内部机制的完整参考
+summary: CLI 设置流程、凭证 / 模型设置、输出和内部机制的完整参考
 title: CLI 设置参考
 x-i18n:
-    generated_at: "2026-04-15T13:39:08Z"
+    generated_at: "2026-04-23T02:36:28Z"
     model: gpt-5.4
     provider: openai
-    source_hash: 61ca679caca3b43fa02388294007f89db22d343e49e10b61d8d118cd8fbb7369
+    source_hash: 60b47a3cd7eaa6e10b5e7108ba4eb331afddffa55a321eac98243611fd7e721b
     source_path: start/wizard-cli-reference.md
     workflow: 15
 ---
@@ -17,7 +17,7 @@ x-i18n:
 # CLI 设置参考
 
 本页是 `openclaw onboard` 的完整参考。
-如需简短指南，请参阅 [新手引导（CLI）](/zh-CN/start/wizard)。
+简短指南见 [设置向导（CLI）](/zh-CN/start/wizard)。
 
 ## 向导的作用
 
@@ -25,48 +25,48 @@ x-i18n:
 
 - 模型和凭证设置（OpenAI Code 订阅 OAuth、Anthropic Claude CLI 或 API 密钥，以及 MiniMax、GLM、Ollama、Moonshot、StepFun 和 AI Gateway 选项）
 - 工作区位置和引导文件
-- Gateway 网关设置（端口、绑定、认证、Tailscale）
+- Gateway 网关设置（端口、绑定、凭证、Tailscale）
 - 渠道和提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost、Signal、BlueBubbles，以及其他内置渠道插件）
 - 守护进程安装（LaunchAgent、systemd 用户单元，或原生 Windows Scheduled Task，并在失败时回退到 Startup 文件夹）
 - 健康检查
 - Skills 设置
 
-远程模式会将此机器配置为连接到其他地方的 Gateway 网关。
+远程模式会将这台机器配置为连接到其他位置的 Gateway 网关。
 它不会在远程主机上安装或修改任何内容。
 
 ## 本地流程详情
 
 <Steps>
   <Step title="现有配置检测">
-    - 如果 `~/.openclaw/openclaw.json` 已存在，可选择保留、修改或重置。
-    - 重新运行向导不会清除任何内容，除非你明确选择“重置”（或传入 `--reset`）。
-    - CLI `--reset` 默认是 `config+creds+sessions`；使用 `--reset-scope full` 还会移除工作区。
-    - 如果配置无效或包含旧版键名，向导会停止并要求你先运行 `openclaw doctor` 再继续。
+    - 如果存在 `~/.openclaw/openclaw.json`，可选择保留、修改或重置。
+    - 重新运行向导不会清除任何内容，除非你明确选择重置（或传入 `--reset`）。
+    - CLI `--reset` 默认作用于 `config+creds+sessions`；使用 `--reset-scope full` 还会移除工作区。
+    - 如果配置无效或包含旧版键名，向导会停止，并要求你先运行 `openclaw doctor` 后再继续。
     - 重置使用 `trash`，并提供以下范围：
       - 仅配置
       - 配置 + 凭证 + 会话
-      - 完全重置（还会移除工作区）
+      - 完整重置（同时移除工作区）
   </Step>
   <Step title="模型和凭证">
     - 完整选项矩阵见 [凭证和模型选项](#auth-and-model-options)。
   </Step>
   <Step title="工作区">
-    - 默认 `~/.openclaw/workspace`（可配置）。
-    - 生成首次运行引导流程所需的工作区文件。
-    - 工作区布局： [智能体工作区](/zh-CN/concepts/agent-workspace)。
+    - 默认值为 `~/.openclaw/workspace`（可配置）。
+    - 会写入首次运行引导仪式所需的工作区文件。
+    - 工作区布局见：[智能体工作区](/zh-CN/concepts/agent-workspace)。
   </Step>
   <Step title="Gateway 网关">
-    - 提示设置端口、绑定、认证模式和 Tailscale 暴露方式。
-    - 推荐：即使只绑定到 loopback，也保持启用令牌认证，这样本地 WS 客户端仍必须进行认证。
+    - 会提示你设置端口、绑定、凭证模式和 Tailscale 暴露方式。
+    - 推荐：即使仅用于 loopback，也保持启用令牌凭证，这样本地 WS 客户端也必须进行认证。
     - 在令牌模式下，交互式设置提供：
-      - **生成/存储明文令牌**（默认）
-      - **使用 SecretRef**（可选）
+      - **生成 / 存储明文令牌**（默认）
+      - **使用 SecretRef**（可选启用）
     - 在密码模式下，交互式设置也支持明文或 SecretRef 存储。
     - 非交互式令牌 SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
-      - 要求新手引导进程环境中存在一个非空环境变量。
+      - 要求新手引导进程环境中存在非空环境变量。
       - 不能与 `--gateway-token` 同时使用。
-    - 仅当你完全信任每个本地进程时才禁用认证。
-    - 非 loopback 绑定仍然需要认证。
+    - 仅当你完全信任每个本地进程时，才禁用凭证。
+    - 非 loopback 绑定仍然需要凭证。
   </Step>
   <Step title="渠道">
     - [WhatsApp](/zh-CN/channels/whatsapp)：可选 QR 登录
@@ -77,19 +77,19 @@ x-i18n:
     - [Signal](/zh-CN/channels/signal)：可选 `signal-cli` 安装 + 账号配置
     - [BlueBubbles](/zh-CN/channels/bluebubbles)：推荐用于 iMessage；服务器 URL + 密码 + webhook
     - [iMessage](/zh-CN/channels/imessage)：旧版 `imsg` CLI 路径 + DB 访问
-    - 私信安全：默认使用配对。首次私信会发送一个代码；通过
+    - 私信安全：默认为配对。首次私信会发送一个代码；可通过
       `openclaw pairing approve <channel> <code>` 批准，或使用 allowlist。
   </Step>
   <Step title="守护进程安装">
     - macOS：LaunchAgent
-      - 需要已登录的用户会话；对于无头环境，请使用自定义 LaunchDaemon（未随附）。
+      - 需要已登录的用户会话；对于无头环境，请使用自定义 LaunchDaemon（未随产品提供）。
     - Linux 和通过 WSL2 的 Windows：systemd 用户单元
-      - 向导会尝试执行 `loginctl enable-linger <user>`，使 Gateway 网关在注销后仍保持运行。
-      - 可能会提示 sudo（写入 `/var/lib/systemd/linger`）；它会先尝试不使用 sudo。
+      - 向导会尝试执行 `loginctl enable-linger <user>`，以便 Gateway 网关在注销后继续运行。
+      - 可能会提示 sudo（写入 `/var/lib/systemd/linger`）；它会先尝试无 sudo 方式。
     - 原生 Windows：优先使用 Scheduled Task
-      - 如果任务创建被拒绝，OpenClaw 会回退到按用户设置的 Startup 文件夹登录项，并立即启动 Gateway 网关。
-      - 仍然优先推荐 Scheduled Task，因为它们提供更好的监督状态。
-    - 运行时选择：Node（推荐；WhatsApp 和 Telegram 必需）。不推荐 Bun。
+      - 如果任务创建被拒绝，OpenClaw 会回退到每用户 Startup 文件夹登录项，并立即启动 Gateway 网关。
+      - 仍优先推荐 Scheduled Task，因为它们提供更好的主管理器状态信息。
+    - 运行时选择：Node（推荐；WhatsApp 和 Telegram 需要）。不推荐使用 Bun。
   </Step>
   <Step title="健康检查">
     - 启动 Gateway 网关（如有需要）并运行 `openclaw health`。
@@ -107,12 +107,12 @@ x-i18n:
 
 <Note>
 如果未检测到 GUI，向导会打印用于 Control UI 的 SSH 端口转发说明，而不是打开浏览器。
-如果缺少 Control UI 资源，向导会尝试构建它们；回退命令是 `pnpm ui:build`（会自动安装 UI 依赖）。
+如果缺少 Control UI 资源，向导会尝试构建它们；回退命令为 `pnpm ui:build`（会自动安装 UI 依赖）。
 </Note>
 
 ## 远程模式详情
 
-远程模式会将此机器配置为连接到其他地方的 Gateway 网关。
+远程模式会将这台机器配置为连接到其他位置的 Gateway 网关。
 
 <Info>
 远程模式不会在远程主机上安装或修改任何内容。
@@ -121,11 +121,11 @@ x-i18n:
 你需要设置：
 
 - 远程 Gateway 网关 URL（`ws://...`）
-- 如果远程 Gateway 网关需要认证，则设置令牌（推荐）
+- 如果远程 Gateway 网关需要凭证，则设置令牌（推荐）
 
 <Note>
-- 如果 Gateway 网关仅限 loopback，请使用 SSH 隧道或 tailnet。
-- 设备发现提示：
+- 如果 Gateway 网关仅绑定到 loopback，请使用 SSH 隧道或 tailnet。
+- 发现提示：
   - macOS：Bonjour（`dns-sd`）
   - Linux：Avahi（`avahi-browse`）
 </Note>
@@ -134,28 +134,28 @@ x-i18n:
 
 <AccordionGroup>
   <Accordion title="Anthropic API 密钥">
-    如果存在 `ANTHROPIC_API_KEY` 则使用它，否则提示你输入密钥，然后将其保存供守护进程使用。
-  </Accordion>
-  <Accordion title="OpenAI Code 订阅（复用 Codex CLI）">
-    如果 `~/.codex/auth.json` 存在，向导可以复用它。
-    复用的 Codex CLI 凭证仍由 Codex CLI 管理；过期时，OpenClaw
-    会先重新读取该来源，并且在提供商支持刷新的情况下，将
-    刷新后的凭证写回 Codex 存储，而不是自行接管其管理。
+    如果存在 `ANTHROPIC_API_KEY` 则使用它，否则提示输入密钥，然后保存供守护进程使用。
   </Accordion>
   <Accordion title="OpenAI Code 订阅（OAuth）">
     浏览器流程；粘贴 `code#state`。
 
     当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.4`。
 
+  </Accordion>
+  <Accordion title="OpenAI Code 订阅（设备配对）">
+    浏览器配对流程，使用短时有效的设备代码。
+
+    当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.4`。
+
   </Accordion>
   <Accordion title="OpenAI API 密钥">
-    如果存在 `OPENAI_API_KEY` 则使用它，否则提示你输入密钥，然后将凭证存储到凭证配置文件中。
+    如果存在 `OPENAI_API_KEY` 则使用它，否则提示输入密钥，然后将该凭证存储到凭证配置文件中。
 
     当模型未设置、为 `openai/*` 或 `openai-codex/*` 时，将 `agents.defaults.model` 设置为 `openai/gpt-5.4`。
 
   </Accordion>
   <Accordion title="xAI（Grok）API 密钥">
-    提示输入 `XAI_API_KEY` 并将 xAI 配置为模型提供商。
+    提示输入 `XAI_API_KEY`，并将 xAI 配置为模型提供商。
   </Accordion>
   <Accordion title="OpenCode">
     提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`），并让你选择 Zen 或 Go 目录。
@@ -166,45 +166,45 @@ x-i18n:
   </Accordion>
   <Accordion title="Vercel AI Gateway">
     提示输入 `AI_GATEWAY_API_KEY`。
-    更多细节： [Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway)。
+    更多详情见：[Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway)。
   </Accordion>
   <Accordion title="Cloudflare AI Gateway">
     提示输入账号 ID、Gateway 网关 ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。
-    更多细节： [Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway)。
+    更多详情见：[Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway)。
   </Accordion>
   <Accordion title="MiniMax">
-    配置会自动写入。托管默认值是 `MiniMax-M2.7`；API 密钥设置使用
+    配置会自动写入。托管默认值为 `MiniMax-M2.7`；API 密钥设置使用
     `minimax/...`，OAuth 设置使用 `minimax-portal/...`。
-    更多细节： [MiniMax](/zh-CN/providers/minimax)。
+    更多详情见：[MiniMax](/zh-CN/providers/minimax)。
   </Accordion>
   <Accordion title="StepFun">
-    会为中国区或全球端点上的 StepFun standard 或 Step Plan 自动写入配置。
-    Standard 当前包含 `step-3.5-flash`，Step Plan 还包含 `step-3.5-flash-2603`。
-    更多细节： [StepFun](/zh-CN/providers/stepfun)。
+    配置会针对中国或全球端点的 StepFun standard 或 Step Plan 自动写入。
+    Standard 当前包括 `step-3.5-flash`，Step Plan 还包括 `step-3.5-flash-2603`。
+    更多详情见：[StepFun](/zh-CN/providers/stepfun)。
   </Accordion>
   <Accordion title="Synthetic（兼容 Anthropic）">
     提示输入 `SYNTHETIC_API_KEY`。
-    更多细节： [Synthetic](/zh-CN/providers/synthetic)。
+    更多详情见：[Synthetic](/zh-CN/providers/synthetic)。
   </Accordion>
   <Accordion title="Ollama（云端和本地开放模型）">
-    首先提示你选择 `Cloud + Local`、`Cloud only` 或 `Local only`。
+    会先提示选择 `Cloud + Local`、`Cloud only` 或 `Local only`。
     `Cloud only` 使用 `OLLAMA_API_KEY` 和 `https://ollama.com`。
-    基于主机的模式会提示输入基础 URL（默认 `http://127.0.0.1:11434`）、发现可用模型并建议默认值。
+    基于主机的模式会提示输入基础 URL（默认 `http://127.0.0.1:11434`），发现可用模型，并建议默认值。
     `Cloud + Local` 还会检查该 Ollama 主机是否已登录以访问云端。
-    更多细节： [Ollama](/zh-CN/providers/ollama)。
+    更多详情见：[Ollama](/zh-CN/providers/ollama)。
   </Accordion>
   <Accordion title="Moonshot 和 Kimi Coding">
     Moonshot（Kimi K2）和 Kimi Coding 配置会自动写入。
-    更多细节： [Moonshot AI（Kimi + Kimi Coding）](/zh-CN/providers/moonshot)。
+    更多详情见：[Moonshot AI（Kimi + Kimi Coding）](/zh-CN/providers/moonshot)。
   </Accordion>
   <Accordion title="自定义提供商">
     适用于兼容 OpenAI 和兼容 Anthropic 的端点。
 
     交互式新手引导支持与其他提供商 API 密钥流程相同的 API 密钥存储选项：
     - **立即粘贴 API 密钥**（明文）
-    - **使用 secret reference**（环境变量引用或已配置的提供商引用，并带有预检校验）
+    - **使用 secret reference**（环境变量引用或已配置的提供商引用，带预检校验）
 
-    非交互式参数：
+    非交互式标志：
     - `--auth-choice custom-api-key`
     - `--custom-base-url`
     - `--custom-model-id`
@@ -214,20 +214,20 @@ x-i18n:
 
   </Accordion>
   <Accordion title="跳过">
-    保持凭证未配置状态。
+    保持凭证未配置。
   </Accordion>
 </AccordionGroup>
 
 模型行为：
 
 - 从检测到的选项中选择默认模型，或手动输入提供商和模型。
-- 当新手引导从某个提供商凭证选项开始时，模型选择器会自动优先显示
-  该提供商。对于 Volcengine 和 BytePlus，这种优先级
+- 当新手引导从某个提供商凭证选项开始时，模型选择器会自动优先
+  该提供商。对于 Volcengine 和 BytePlus，此优先级
   也会匹配它们的 coding-plan 变体（`volcengine-plan/*`、
   `byteplus-plan/*`）。
-- 如果该首选提供商筛选结果为空，选择器会回退到
+- 如果该优先提供商过滤后为空，选择器会回退到
   完整目录，而不是显示没有模型。
-- 向导会执行模型检查，并在配置的模型未知或缺少凭证时发出警告。
+- 向导会运行模型检查，并在配置的模型未知或缺少凭证时发出警告。
 
 凭证和配置文件路径：
 
@@ -236,28 +236,28 @@ x-i18n:
 
 凭证存储模式：
 
-- 默认的新手引导行为会将 API 密钥作为明文值持久化到凭证配置文件中。
+- 默认新手引导行为会将 API 密钥作为明文值持久化到凭证配置文件中。
 - `--secret-input-mode ref` 会启用引用模式，而不是明文密钥存储。
   在交互式设置中，你可以选择以下任一方式：
   - 环境变量引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`）
   - 已配置的提供商引用（`file` 或 `exec`），包含提供商别名 + id
-- 交互式引用模式会在保存前执行快速预检校验。
-  - 环境变量引用：校验变量名以及当前新手引导环境中的非空值。
+- 交互式引用模式在保存前会执行快速预检校验。
+  - 环境变量引用：校验变量名，以及当前新手引导环境中的非空值。
   - 提供商引用：校验提供商配置并解析请求的 id。
   - 如果预检失败，新手引导会显示错误并允许你重试。
 - 在非交互式模式下，`--secret-input-mode ref` 仅支持基于环境变量。
   - 在新手引导进程环境中设置提供商环境变量。
-  - 内联密钥参数（例如 `--openai-api-key`）要求必须设置该环境变量；否则新手引导会快速失败。
+  - 内联密钥标志（例如 `--openai-api-key`）要求该环境变量已设置；否则新手引导会快速失败。
   - 对于自定义提供商，非交互式 `ref` 模式会将 `models.providers.<id>.apiKey` 存储为 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`。
   - 在该自定义提供商场景中，`--custom-api-key` 要求必须设置 `CUSTOM_API_KEY`；否则新手引导会快速失败。
-- Gateway 网关认证凭证在交互式设置中支持明文和 SecretRef 选项：
-  - 令牌模式：**生成/存储明文令牌**（默认）或 **使用 SecretRef**。
+- Gateway 网关凭证凭据在交互式设置中支持明文和 SecretRef 选项：
+  - 令牌模式：**生成 / 存储明文令牌**（默认）或 **使用 SecretRef**。
   - 密码模式：明文或 SecretRef。
 - 非交互式令牌 SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
-- 现有的明文设置将继续保持不变并正常工作。
+- 现有的明文设置会继续保持不变并正常工作。
 
 <Note>
-无头环境和服务器提示：在有浏览器的机器上完成 OAuth，然后复制
+无头环境和服务器提示：先在有浏览器的机器上完成 OAuth，然后复制
 该智能体的 `auth-profiles.json`（例如
 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`，或对应的
 `$OPENCLAW_STATE_DIR/...` 路径）到 Gateway 网关主机。`credentials/oauth.json`
@@ -270,14 +270,14 @@ x-i18n:
 
 - `agents.defaults.workspace`
 - `agents.defaults.model` / `models.providers`（如果选择了 MiniMax）
-- `tools.profile`（本地新手引导在未设置时默认使用 `"coding"`；现有的显式值会被保留）
-- `gateway.*`（模式、绑定、认证、Tailscale）
-- `session.dmScope`（本地新手引导在未设置时默认将其设为 `per-channel-peer`；现有的显式值会被保留）
+- `tools.profile`（本地新手引导在未设置时默认使用 `"coding"`；现有显式值会被保留）
+- `gateway.*`（模式、绑定、凭证、Tailscale）
+- `session.dmScope`（本地新手引导在未设置时默认将其设为 `per-channel-peer`；现有显式值会被保留）
 - `channels.telegram.botToken`、`channels.discord.token`、`channels.matrix.*`、`channels.signal.*`、`channels.imessage.*`
-- 当你在提示中选择启用时的渠道 allowlist（Slack、Discord、Matrix、Microsoft Teams）（名称会在可能时解析为 ID）
+- 当你在提示中选择启用时的渠道 allowlist（Slack、Discord、Matrix、Microsoft Teams）（如果可能，名称会解析为 ID）
 - `skills.install.nodeManager`
-  - `setup --node-manager` 参数接受 `npm`、`pnpm` 或 `bun`。
-  - 后续手动配置仍可将 `skills.install.nodeManager: "yarn"` 设为 `"yarn"`。
+  - `setup --node-manager` 标志接受 `npm`、`pnpm` 或 `bun`。
+  - 稍后手动配置仍可将 `skills.install.nodeManager: "yarn"`` 设置为该值。
 - `wizard.lastRunAt`
 - `wizard.lastRunVersion`
 - `wizard.lastRunCommit`
@@ -286,11 +286,11 @@ x-i18n:
 
 `openclaw agents add` 会写入 `agents.list[]` 和可选的 `bindings`。
 
-WhatsApp 凭证位于 `~/.openclaw/credentials/whatsapp/<accountId>/`。
+WhatsApp 凭证位于 `~/.openclaw/credentials/whatsapp/<accountId>/` 下。
 会话存储在 `~/.openclaw/agents/<agentId>/sessions/` 下。
 
 <Note>
-某些渠道以插件形式提供。在设置期间选择这些渠道时，向导会先提示你安装该插件（npm 或本地路径），然后再进行渠道配置。
+某些渠道以插件形式提供。在设置期间选择它们时，向导会先提示你安装插件（npm 或本地路径），然后再进行渠道配置。
 </Note>
 
 Gateway 网关向导 RPC：
@@ -300,19 +300,19 @@ Gateway 网关向导 RPC：
 - `wizard.cancel`
 - `wizard.status`
 
-客户端（macOS 应用和 Control UI）可以渲染这些步骤，而无需重新实现新手引导逻辑。
+客户端（macOS 应用和 Control UI）可以渲染步骤，而无需重新实现新手引导逻辑。
 
 Signal 设置行为：
 
-- 下载对应的发布资源
-- 将其存储到 `~/.openclaw/tools/signal-cli/<version>/`
+- 下载合适的发布资源
+- 将其存储在 `~/.openclaw/tools/signal-cli/<version>/` 下
 - 在配置中写入 `channels.signal.cliPath`
 - JVM 构建需要 Java 21
-- 可用时使用原生构建
+- 可用时会使用原生构建
 - Windows 使用 WSL2，并在 WSL 内遵循 Linux 的 `signal-cli` 流程
 
 ## 相关文档
 
-- 新手引导中心：[新手引导（CLI）](/zh-CN/start/wizard)
-- 自动化和脚本：[CLI 自动化](/zh-CN/start/wizard-cli-automation)
+- 新手引导中心：[设置向导（CLI）](/start/wizard)
+- 自动化和脚本：[CLI 自动化](/start/wizard-cli-automation)
 - 命令参考：[`openclaw onboard`](/cli/onboard)