chore(i18n): refresh zh-CN translations

docs/zh-CN/gateway/doctor.md

@@ -5,17 +5,17 @@ read_when:
 summary: Doctor 命令：健康检查、配置迁移和修复步骤
 title: Doctor
 x-i18n:
-    generated_at: "2026-04-20T06:08:04Z"
+    generated_at: "2026-04-20T16:49:57Z"
     model: gpt-5.4
     provider: openai
-    source_hash: 61a5e01a306058c49be6095f7c8082d779a55d63cf3b5f4c4096173943faf51b
+    source_hash: 6460fe657e7cf0d938bfbb77e1cc0355c1b67830327d441878e48375de52a46f
     source_path: gateway/doctor.md
     workflow: 15
 ---
 
 # Doctor
 
-`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过期的配置/状态、检查健康状况，并提供可执行的修复步骤。
+`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过期的配置/状态、执行健康检查，并提供可操作的修复步骤。
 
 ## 快速开始
 
@@ -23,7 +23,7 @@ x-i18n:
 openclaw doctor
 ```
 
-### 无头 / 自动化
+### 无头模式 / 自动化
 
 ```bash
 openclaw doctor --yes
@@ -35,7 +35,7 @@ openclaw doctor --yes
 openclaw doctor --repair
 ```
 
-应用建议的修复而不提示（在安全情况下执行修复 + 重启）。
+应用推荐的修复而不提示（在安全的情况下执行修复 + 重启）。
 
 ```bash
 openclaw doctor --repair --force
@@ -47,16 +47,16 @@ openclaw doctor --repair --force
 openclaw doctor --non-interactive
 ```
 
-无提示运行，并且只应用安全迁移（配置规范化 + 磁盘状态移动）。会跳过需要人工确认的重启/服务/沙箱操作。
-检测到旧状态迁移时，会自动运行。
+在无提示的情况下运行，并且只应用安全迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启/服务/沙箱操作。
+检测到旧状态迁移时会自动运行。
 
 ```bash
 openclaw doctor --deep
 ```
 
-扫描系统服务以查找额外的 Gateway 网关安装（`launchd/systemd/schtasks`）。
+扫描系统服务以查找额外的 Gateway 网关安装（`launchd`/`systemd`/`schtasks`）。
 
-如果你想在写入前先查看变更，先打开配置文件：
+如果你想在写入之前先查看变更，请先打开配置文件：
 
 ```bash
 cat ~/.openclaw/openclaw.json
@@ -64,57 +64,57 @@ cat ~/.openclaw/openclaw.json
 
 ## 它会做什么（摘要）
 
-- 可选的 git 安装预检更新（仅交互式）。
+- 针对 git 安装的可选飞行前更新（仅交互模式）。
 - UI 协议新鲜度检查（当协议 schema 更新时重建 Control UI）。
 - 健康检查 + 重启提示。
-- Skills 状态摘要（可用/缺失/受阻）和插件状态。
+- Skills 状态摘要（可用/缺失/阻止）和插件状态。
 - 对旧值执行配置规范化。
-- 将旧版扁平 `talk.*` 字段迁移为 `talk.provider` + `talk.providers.<provider>` 的 Talk 配置迁移。
-- 针对旧版 Chrome 扩展配置和 Chrome MCP 就绪状态的浏览器迁移检查。
+- 将旧版扁平 `talk.*` 字段迁移到 `talk.provider` + `talk.providers.<provider>` 的 Talk 配置迁移。
+- 针对旧版 Chrome 扩展配置和 Chrome MCP 就绪情况的浏览器迁移检查。
 - OpenCode 提供商覆盖警告（`models.providers.opencode` / `models.providers.opencode-go`）。
 - Codex OAuth 遮蔽警告（`models.providers.openai-codex`）。
 - OpenAI Codex OAuth 配置文件的 OAuth TLS 前置条件检查。
-- 旧版磁盘状态迁移（会话/智能体目录/WhatsApp 凭证）。
-- 旧版插件 manifest contract 键迁移（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。
-- 旧版 cron 存储迁移（`jobId`、`schedule.cron`、顶层 delivery/payload 字段、payload `provider`、简单的 `notify: true` webhook 回退任务）。
+- 旧版磁盘状态迁移（会话/智能体目录/WhatsApp 身份验证）。
+- 旧版插件清单契约键迁移（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。
+- 旧版 cron 存储迁移（`jobId`、`schedule.cron`、顶层 `delivery`/`payload` 字段、`payload provider`、简单的 `notify: true` webhook 回退作业）。
 - 会话锁文件检查和过期锁清理。
 - 状态完整性和权限检查（会话、转录、状态目录）。
-- 本地运行时检查配置文件权限（`chmod 600`）。
-- 模型凭证健康状况：检查 OAuth 过期状态，可刷新即将过期的令牌，并报告 auth-profile 冷却/禁用状态。
+- 本地运行时的配置文件权限检查（`chmod 600`）。
+- 模型身份验证健康状态：检查 OAuth 过期情况、可刷新即将过期的令牌，并报告 auth-profile 冷却/禁用状态。
 - 检测额外的工作区目录（`~/openclaw`）。
 - 在启用沙箱隔离时修复沙箱镜像。
 - 旧版服务迁移和额外 Gateway 网关检测。
 - Matrix 渠道旧状态迁移（在 `--fix` / `--repair` 模式下）。
-- Gateway 网关运行时检查（服务已安装但未运行；缓存的 launchd 标签）。
-- 渠道状态警告（从运行中的 Gateway 网关探测）。
-- Supervisor 配置审计（`launchd/systemd/schtasks`）并可选择修复。
-- Gateway 网关运行时最佳实践检查（Node vs Bun、版本管理器路径）。
+- Gateway 网关运行时检查（已安装服务但未运行；缓存的 `launchd` 标签）。
+- 渠道状态警告（从正在运行的 Gateway 网关探测）。
+- supervisor 配置审计（`launchd`/`systemd`/`schtasks`）以及可选修复。
+- Gateway 网关运行时最佳实践检查（Node 与 Bun、版本管理器路径）。
 - Gateway 网关端口冲突诊断（默认 `18789`）。
-- 面向开放私信策略的安全警告。
-- 本地令牌模式下的 Gateway 网关凭证检查（在不存在令牌来源时提供令牌生成功能；不会覆盖令牌 `SecretRef` 配置）。
-- 设备配对问题检测（首次配对请求待处理、角色/作用域升级待处理、过期的本地设备令牌缓存漂移，以及已配对记录的凭证漂移）。
-- Linux 上的 systemd linger 检查。
-- 工作区 bootstrap 文件大小检查（针对上下文文件的截断/接近上限警告）。
-- Shell 补全状态检查以及自动安装/升级。
-- Memory 搜索嵌入提供商就绪状态检查（本地模型、远程 API key 或 QMD 二进制文件）。
-- 源码安装检查（pnpm 工作区不匹配、缺失 UI 资源、缺失 tsx 二进制文件）。
+- 针对开放 私信 策略的安全警告。
+- 针对本地令牌模式的 Gateway 网关身份验证检查（当不存在令牌来源时提供生成令牌；不会覆盖令牌 `SecretRef` 配置）。
+- 设备配对故障检测（首次配对请求待处理、角色/作用域升级待处理、过期的本地设备令牌缓存漂移，以及已配对记录的身份验证漂移）。
+- Linux 上的 `systemd linger` 检查。
+- 工作区引导文件大小检查（上下文文件的截断/接近限制警告）。
+- Shell 补全状态检查和自动安装/升级。
+- Memory 搜索嵌入提供商就绪情况检查（本地模型、远程 API 密钥或 QMD 二进制文件）。
+- 源码安装检查（`pnpm` 工作区不匹配、缺失 UI 资源、缺失 `tsx` 二进制文件）。
 - 写入更新后的配置 + 向导元数据。
 
 ## Dreams UI 回填和重置
 
-Control UI 的 Dreams 场景为 grounded dreaming 工作流包含 **Backfill**、**Reset** 和 **Clear Grounded** 操作。这些操作使用 Gateway 网关风格的 doctor RPC 方法，但它们**不是** `openclaw doctor` CLI 修复/迁移的一部分。
+Control UI 的 Dreams 场景包含针对 grounded dreaming 工作流的 **Backfill**、**Reset** 和 **Clear Grounded** 操作。这些操作使用 Gateway 网关风格的 doctor RPC 方法，但它们**不是** `openclaw doctor` CLI 修复/迁移的一部分。
 
 它们的作用：
 
-- **Backfill** 会扫描当前工作区中的历史 `memory/YYYY-MM-DD.md` 文件，运行 grounded REM 日记流程，并将可逆的回填条目写入 `DREAMS.md`。
-- **Reset** 只会从 `DREAMS.md` 中删除那些已标记的回填日记条目。
-- **Clear Grounded** 只会删除来自历史回放、且尚未积累实时召回或每日支持的 staged grounded-only 短期条目。
+- **Backfill** 会扫描当前工作区中的历史 `memory/YYYY-MM-DD.md` 文件，运行 grounded REM diary 处理，并将可逆的回填条目写入 `DREAMS.md`。
+- **Reset** 只会从 `DREAMS.md` 中移除那些已标记的回填 diary 条目。
+- **Clear Grounded** 只会移除那些来自历史回放、且尚未积累实时回忆或每日支持的 staged grounded-only 短期条目。
 
 它们**不会**自行执行的事情：
 
 - 不会编辑 `MEMORY.md`
-- 不会运行完整的 doctor 迁移
-- 不会自动将 grounded 候选项暂存到实时短期提升存储中，除非你先显式运行 staged CLI 路径
+- 不会运行完整的 Doctor 迁移
+- 不会自动将 grounded 候选项暂存到实时短期提升存储中，除非你先明确运行 staged CLI 路径
 
 如果你希望 grounded 历史回放影响正常的深度提升通道，请改用 CLI 流程：
 
@@ -122,31 +122,31 @@ Control UI 的 Dreams 场景为 grounded dreaming 工作流包含 **Backfill**
 openclaw memory rem-backfill --path ./memory --stage-short-term
 ```
 
-这会将 grounded durable 候选项暂存到短期 dreaming 存储中，同时保留 `DREAMS.md` 作为审核界面。
+这样会将 grounded 持久候选项暂存到短期 dreaming 存储中，同时保留 `DREAMS.md` 作为审查界面。
 
-## 详细行为和原理
+## 详细行为与原因说明
 
-### 0) 可选更新（git 安装）
+### 0）可选更新（git 安装）
 
-如果这是一个 git checkout，且 doctor 正在交互式运行，它会先提供在运行 doctor 之前进行更新（fetch/rebase/build）。
+如果这是一个 git 检出，并且 doctor 正在以交互方式运行，它会在运行 doctor 之前提供更新选项（`fetch`/`rebase`/`build`）。
 
-### 1) 配置规范化
+### 1）配置规范化
 
-如果配置中包含旧版值结构（例如没有特定渠道覆盖的 `messages.ackReaction`），doctor 会将其规范化为当前 schema。
+如果配置中包含旧版值形状（例如没有渠道专属覆盖的 `messages.ackReaction`），doctor 会将其规范化为当前 schema。
 
-这也包括旧版 Talk 扁平字段。当前公开的 Talk 配置是 `talk.provider` + `talk.providers.<provider>`。Doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 结构重写到 provider 映射中。
+这也包括旧版 Talk 扁平字段。当前公开的 Talk 配置是 `talk.provider` + `talk.providers.<provider>`。Doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形状重写到提供商映射中。
 
-### 2) 旧版配置键迁移
+### 2）旧版配置键迁移
 
-当配置中包含已弃用键时，其他命令会拒绝运行，并要求你执行 `openclaw doctor`。
+当配置中包含已弃用的键时，其他命令会拒绝运行，并要求你运行 `openclaw doctor`。
 
-Doctor 会：
+Doctor 将会：
 
-- 说明找到了哪些旧版键。
+- 解释找到了哪些旧版键。
 - 显示它应用的迁移。
-- 用更新后的 schema 重写 `~/.openclaw/openclaw.json`。
+- 使用更新后的 schema 重写 `~/.openclaw/openclaw.json`。
 
-当 Gateway 网关在启动时检测到旧版配置格式，也会自动运行 doctor 迁移，因此过期配置无需人工干预即可修复。
+Gateway 网关在检测到旧版配置格式时，也会在启动时自动运行 doctor 迁移，因此过期配置无需手动干预即可修复。
 Cron 作业存储迁移由 `openclaw doctor --fix` 处理。
 
 当前迁移包括：
@@ -171,269 +171,269 @@ Cron 作业存储迁移由 `openclaw doctor --fix` 处理。
 - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold`
   → `plugins.entries.voice-call.config.streaming.providers.openai.*`
 - `bindings[].match.accountID` → `bindings[].match.accountId`
-- 对于配置了具名 `accounts` 但仍保留单账户顶层渠道值的渠道，将这些账户级值移动到该渠道所选中的提升账户中（大多数渠道使用 `accounts.default`；Matrix 可以保留现有匹配的具名/默认目标）
+- 对于配置了命名 `accounts` 但仍残留单账户顶层渠道值的渠道，将这些账户作用域的值移动到该渠道选定的提升账户中（大多数渠道使用 `accounts.default`；Matrix 可以保留现有匹配的命名/默认目标）
 - `identity` → `agents.list[].identity`
-- `agent.*` → `agents.defaults` + `tools.*`（tools/elevated/exec/sandbox/subagents）
+- `agent.*` → `agents.defaults` + `tools.*`（`tools`/`elevated`/`exec`/`sandbox`/`subagents`）
 - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
   → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
 - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
 - `browser.profiles.*.driver: "extension"` → `"existing-session"`
-- 删除 `browser.relayBindHost`（旧版扩展 relay 设置）
+- 移除 `browser.relayBindHost`（旧版扩展 relay 设置）
 
-Doctor 警告还包括多账户渠道的账户默认值指引：
+Doctor 警告还包括多账户渠道的默认账户指引：
 
-- 如果配置了两个或更多 `channels.<channel>.accounts` 条目，但没有设置 `channels.<channel>.defaultAccount` 或 `accounts.default`，doctor 会警告回退路由可能会选择非预期账户。
-- 如果 `channels.<channel>.defaultAccount` 设置为未知账户 ID，doctor 会发出警告并列出已配置的账户 ID。
+- 如果配置了两个或更多 `channels.<channel>.accounts` 条目，但没有 `channels.<channel>.defaultAccount` 或 `accounts.default`，doctor 会警告回退路由可能会选择意外的账户。
+- 如果 `channels.<channel>.defaultAccount` 被设置为未知账户 ID，doctor 会发出警告并列出已配置的账户 ID。
 
-### 2b) OpenCode 提供商覆盖
+### 2b）OpenCode 提供商覆盖
 
 如果你手动添加了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它会覆盖来自 `@mariozechner/pi-ai` 的内置 OpenCode 目录。
-这可能会把模型强制路由到错误的 API，或把成本清零。Doctor 会发出警告，这样你就可以移除覆盖并恢复按模型路由 API + 成本。
 
-### 2c) 浏览器迁移和 Chrome MCP 就绪状态
+这可能会强制模型使用错误的 API，或将成本清零。Doctor 会发出警告，以便你移除该覆盖并恢复按模型的 API 路由 + 成本。
 
-如果你的浏览器配置仍指向已移除的 Chrome 扩展路径，doctor 会将其规范化为当前的主机本地 Chrome MCP 附加模型：
+### 2c）浏览器迁移和 Chrome MCP 就绪情况
 
-- `browser.profiles.*.driver: "extension"` 会变成 `"existing-session"`
+如果你的浏览器配置仍然指向已移除的 Chrome 扩展路径，doctor 会将其规范化为当前基于主机本地的 Chrome MCP 附加模型：
+
+- `browser.profiles.*.driver: "extension"` 会变为 `"existing-session"`
 - `browser.relayBindHost` 会被移除
 
-当你使用 `defaultProfile: "user"` 或配置了 `existing-session` 配置文件时，doctor 还会审计主机本地 Chrome MCP 路径：
+当你使用 `defaultProfile: "user"` 或已配置的 `existing-session` 配置文件时，doctor 还会审计基于主机本地的 Chrome MCP 路径：
 
-- 检查默认自动连接配置文件是否在同一主机上安装了 Google Chrome
-- 检查检测到的 Chrome 版本，并在低于 Chrome 144 时发出警告
+- 检查同一主机上是否已安装 Google Chrome，以支持默认自动连接配置文件
+- 检查检测到的 Chrome 版本，并在其低于 Chrome 144 时发出警告
 - 提醒你在浏览器 inspect 页面中启用远程调试（例如 `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging` 或 `edge://inspect/#remote-debugging`）
 
-Doctor 不能替你启用 Chrome 侧设置。主机本地 Chrome MCP 仍然要求：
+Doctor 无法替你启用 Chrome 侧设置。主机本地 Chrome MCP 仍然需要：
 
-- Gateway 网关/节点主机上有 144+ 的 Chromium 内核浏览器
+- Gateway 网关/节点主机上安装 Chromium 系浏览器 144+
 - 浏览器在本地运行
 - 在该浏览器中启用远程调试
 - 在浏览器中批准首次附加的同意提示
 
-这里的就绪状态仅指本地附加前置条件。`existing-session` 仍保留当前 Chrome MCP 路由限制；像 `responsebody`、PDF 导出、下载拦截和批量操作这样的高级路由，仍然需要受管浏览器或原始 CDP 配置文件。
+这里的就绪情况仅与本地附加前置条件有关。`existing-session` 会保留当前 Chrome MCP 路由限制；像 `responsebody`、PDF 导出、下载拦截和批量操作这样的高级路由，仍然需要托管浏览器或原始 CDP 配置文件。
 
-此检查**不**适用于 Docker、沙箱、remote-browser 或其他无头流程。那些流程会继续使用原始 CDP。
+此检查**不**适用于 Docker、沙箱、remote-browser 或其他无头流程。那些流程仍继续使用原始 CDP。
 
-### 2d) OAuth TLS 前置条件
+### 2d）OAuth TLS 前置条件
 
-当配置了 OpenAI Codex OAuth 配置文件时，doctor 会探测 OpenAI 授权端点，以验证本地 Node/OpenSSL TLS 栈能否校验证书链。如果探测因证书错误失败（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书已过期或自签名证书），doctor 会输出按平台划分的修复指引。在 macOS 上使用 Homebrew Node 时，修复方式通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 Gateway 网关健康，此探测也会运行。
+当配置了 OpenAI Codex OAuth 配置文件时，doctor 会探测 OpenAI 授权端点，以验证本地 Node/OpenSSL TLS 堆栈是否能够验证证书链。如果探测因证书错误而失败（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书过期或自签名证书），doctor 会打印特定平台的修复指引。在使用 Homebrew Node 的 macOS 上，修复通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 Gateway 网关是健康的，也会运行此探测。
 
-### 2c) Codex OAuth 提供商覆盖
+### 2c）Codex OAuth 提供商覆盖
 
-如果你此前在 `models.providers.openai-codex` 下添加过旧版 OpenAI 传输设置，它们可能会遮蔽较新版本自动使用的内置 Codex OAuth 提供商路径。Doctor 在检测到这些旧传输设置与 Codex OAuth 并存时会发出警告，这样你就可以删除或重写过期的传输覆盖，并恢复内置的路由/回退行为。自定义代理和仅头部覆盖仍然受支持，并且不会触发此警告。
+如果你之前在 `models.providers.openai-codex` 下添加过旧版 OpenAI 传输设置，它们可能会遮蔽较新版本自动使用的内置 Codex OAuth 提供商路径。当 Doctor 发现这些旧传输设置与 Codex OAuth 同时存在时，会发出警告，以便你移除或重写过期的传输覆盖，并恢复内置的路由/回退行为。自定义代理和仅标头覆盖仍受支持，并且不会触发此警告。
 
-### 3) 旧版状态迁移（磁盘布局）
+### 3）旧版状态迁移（磁盘布局）
 
-Doctor 可以将旧版磁盘布局迁移到当前结构：
+Doctor 可以将较旧的磁盘布局迁移到当前结构：
 
 - 会话存储 + 转录：
-  - 从 `~/.openclaw/sessions/` 到 `~/.openclaw/agents/<agentId>/sessions/`
-- 智能体目录：
-  - 从 `~/.openclaw/agent/` 到 `~/.openclaw/agents/<agentId>/agent/`
-- WhatsApp 凭证状态（Baileys）：
+  - 从 `~/.openclaw/sessions/` 迁移到 `~/.openclaw/agents/<agentId>/sessions/`
+- 智能体 目录：
+  - 从 `~/.openclaw/agent/` 迁移到 `~/.openclaw/agents/<agentId>/agent/`
+- WhatsApp 身份验证状态（Baileys）：
   - 从旧版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外）
-  - 到 `~/.openclaw/credentials/whatsapp/<accountId>/...`（默认账户 ID：`default`）
+  - 迁移到 `~/.openclaw/credentials/whatsapp/<accountId>/...`（默认账户 ID：`default`）
 
-这些迁移会尽力执行，并且是幂等的；如果保留了任何旧版文件夹作为备份，doctor 会发出警告。Gateway 网关/CLI 也会在启动时自动迁移旧版会话 + 智能体目录，因此历史记录/凭证/模型会落到按智能体划分的路径中，而无需手动运行 doctor。WhatsApp 凭证则有意只通过 `openclaw doctor` 迁移。Talk provider/provider-map 规范化现在按结构相等进行比较，因此仅键顺序不同的差异不再触发重复的无操作 `doctor --fix` 变更。
+这些迁移会尽力而为，并且是幂等的；当保留任何旧版文件夹作为备份时，doctor 会发出警告。Gateway 网关/CLI 也会在启动时自动迁移旧版会话 + 智能体 目录，因此历史记录/身份验证/模型会进入按智能体划分的路径，而无需手动运行 doctor。WhatsApp 身份验证则有意仅通过 `openclaw doctor` 迁移。Talk 提供商/提供商映射规范化现在按结构相等性进行比较，因此仅键顺序不同的差异不再触发重复的无操作 `doctor --fix` 变更。
 
-### 3a) 旧版插件 manifest 迁移
+### 3a）旧版插件清单迁移
 
-Doctor 会扫描所有已安装插件的 manifest，查找已弃用的顶层 capability 键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。发现后，它会提供将它们移动到 `contracts` 对象中的选项，并原地重写 manifest 文件。此迁移是幂等的；如果 `contracts` 键中已经有相同的值，则会移除旧版键，而不会重复数据。
+Doctor 会扫描所有已安装插件的清单，以查找已弃用的顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。找到后，它会提供将它们移动到 `contracts` 对象中的选项，并原地重写清单文件。此迁移是幂等的；如果 `contracts` 键中已经有相同的值，则会移除旧版键，而不会重复数据。
 
-### 3b) 旧版 cron 存储迁移
+### 3b）旧版 cron 存储迁移
 
-Doctor 还会检查 cron 作业存储（默认为 `~/.openclaw/cron/jobs.json`，或在覆盖时使用 `cron.store`）中调度器仍为兼容性而接受的旧版作业结构。
+Doctor 还会检查 cron 作业存储（默认是 `~/.openclaw/cron/jobs.json`，或在被覆盖时使用 `cron.store`），查找调度器仍为兼容性而接受的旧作业结构。
 
-当前的 cron 清理包括：
+当前 cron 清理包括：
 
 - `jobId` → `id`
 - `schedule.cron` → `schedule.expr`
 - 顶层 payload 字段（`message`、`model`、`thinking`、...）→ `payload`
-- 顶层 delivery 字段（`deliver`、`channel`、`to`、`provider`、...）→ `delivery`
-- payload `provider` delivery 别名 → 显式 `delivery.channel`
+- 顶层 `delivery` 字段（`deliver`、`channel`、`to`、`provider`、...）→ `delivery`
+- payload 中 `provider` 的传递别名 → 显式 `delivery.channel`
 - 简单的旧版 `notify: true` webhook 回退作业 → 显式 `delivery.mode="webhook"`，并设置 `delivery.to=cron.webhook`
 
-Doctor 只会在能够不改变行为的前提下自动迁移 `notify: true` 作业。如果某个作业将旧版通知回退与现有的非 webhook delivery 模式组合使用，doctor 会发出警告，并将该作业留给你手动审查。
+Doctor 仅会在能够不改变行为的情况下自动迁移 `notify: true` 作业。如果某个作业将旧版通知回退与现有的非 webhook 传递模式组合使用，doctor 会发出警告，并将该作业留给你手动审查。
 
-### 3c) 会话锁清理
+### 3c）会话锁清理
 
-Doctor 会扫描每个智能体会话目录中的过期写锁文件——这些文件通常是在会话异常退出时遗留的。对于找到的每个锁文件，它会报告：
-路径、PID、该 PID 是否仍存活、锁的年龄，以及它是否被视为过期（PID 已死或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动删除过期锁文件；否则会输出提示，并指示你使用 `--fix` 重新运行。
+Doctor 会扫描每个智能体会话目录，查找过期的写锁文件——即会话异常退出后遗留的文件。对于找到的每个锁文件，它会报告：
+路径、PID、该 PID 是否仍然存活、锁年龄，以及它是否被视为过期（PID 已死或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动移除过期锁文件；否则会打印说明，并指示你使用 `--fix` 重新运行。
 
-### 4) 状态完整性检查（会话持久化、路由和安全）
+### 4）状态完整性检查（会话持久化、路由和安全性）
 
-状态目录是运行中的核心中枢。如果它消失了，你会丢失会话、凭证、日志和配置（除非你在别处有备份）。
+状态目录是运行中的中枢神经。如果它消失了，你会丢失会话、凭证、日志和配置（除非你在其他地方有备份）。
 
 Doctor 会检查：
 
-- **状态目录缺失**：警告灾难性的状态丢失，提示重新创建该目录，并提醒你它无法恢复缺失数据。
-- **状态目录权限**：验证可写性；提供修复权限的选项（并在检测到所有者/组不匹配时给出 `chown` 提示）。
-- **macOS 云同步状态目录**：当状态解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 下时发出警告，因为基于同步的路径可能导致更慢的 I/O，以及锁/同步竞争。
-- **Linux SD 或 eMMC 状态目录**：当状态解析到 `mmcblk*` 挂载源时发出警告，因为基于 SD 或 eMMC 的随机 I/O 在会话和凭证写入下可能更慢，且磨损更快。
+- **状态目录缺失**：警告灾难性的状态丢失，提示重新创建目录，并提醒你它无法恢复丢失的数据。
+- **状态目录权限**：验证是否可写；提供修复权限的选项（并在检测到所有者/组不匹配时给出 `chown` 提示）。
+- **macOS 云同步状态目录**：当状态路径解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 下时发出警告，因为基于同步的路径可能导致较慢的 I/O 以及锁/同步竞争。
+- **Linux SD 或 eMMC 状态目录**：当状态路径解析到 `mmcblk*` 挂载源时发出警告，因为基于 SD 卡或 eMMC 的随机 I/O 在会话和凭证写入场景下可能更慢且磨损更快。
 - **会话目录缺失**：`sessions/` 和会话存储目录是持久化历史记录并避免 `ENOENT` 崩溃所必需的。
 - **转录不匹配**：当最近的会话条目缺少转录文件时发出警告。
-- **主会话“单行 JSONL”**：当主转录只有一行时发出标记（历史记录没有持续累积）。
-- **多个状态目录**：当多个 `~/.openclaw` 文件夹存在于不同主目录中，或者 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史记录可能会在不同安装之间分裂）。
+- **主会话“单行 JSONL”**：当主转录只有一行时进行标记（历史记录未持续累积）。
+- **多个状态目录**：当不同主目录下存在多个 `~/.openclaw` 文件夹，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史记录可能在不同安装之间分裂）。
 - **远程模式提醒**：如果 `gateway.mode=remote`，doctor 会提醒你在远程主机上运行它（状态存储在那里）。
-- **配置文件权限**：如果 `~/.openclaw/openclaw.json` 对组/全体用户可读，会发出警告，并提供将权限收紧到 `600` 的选项。
+- **配置文件权限**：如果 `~/.openclaw/openclaw.json` 对组/所有人可读，则会发出警告，并提供收紧到 `600` 的选项。
 
-### 5) 模型凭证健康状况（OAuth 过期）
+### 5）模型身份验证健康状态（OAuth 过期）
 
-Doctor 会检查凭证存储中的 OAuth 配置文件，在令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic OAuth/令牌配置文件已过期，它会建议使用 Anthropic API key 或 Anthropic setup-token 路径。
-只有在交互式（TTY）运行时才会出现刷新提示；`--non-interactive` 会跳过刷新尝试。
+Doctor 会检查身份验证存储中的 OAuth 配置文件，在令牌即将过期/已过期时发出警告，并在安全情况下进行刷新。如果 Anthropic OAuth/令牌配置文件已过期，它会建议使用 Anthropic API 密钥或 Anthropic setup-token 路径。
+只有在交互模式（TTY）下运行时才会出现刷新提示；`--non-interactive` 会跳过刷新尝试。
 
-当 OAuth 刷新永久失败时（例如 `refresh_token_reused`、`invalid_grant`，或提供商提示你需要重新登录），doctor 会报告需要重新鉴权，并打印要运行的精确 `openclaw models auth login --provider ...` 命令。
+当 OAuth 刷新永久失败时（例如 `refresh_token_reused`、`invalid_grant`，或提供商提示你重新登录），doctor 会报告需要重新认证，并打印确切的 `openclaw models auth login --provider ...` 命令供你运行。
 
-Doctor 还会报告由于以下原因而暂时不可用的 auth-profile：
+Doctor 还会报告因以下原因而暂时不可用的 auth profile：
 
-- 短期冷却（速率限制/超时/鉴权失败）
+- 短期冷却（速率限制/超时/身份验证失败）
 - 较长时间禁用（计费/额度失败）
 
-### 6) Hooks 模型校验
+### 6）Hooks 模型验证
 
-如果设置了 `hooks.gmail.model`，doctor 会根据目录和 allowlist 校验模型引用，并在其无法解析或不被允许时发出警告。
+如果设置了 `hooks.gmail.model`，doctor 会根据目录和允许列表验证该模型引用，并在它无法解析或不被允许时发出警告。
 
-### 7) 沙箱镜像修复
+### 7）沙箱镜像修复
 
-当启用沙箱隔离时，doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧版名称的选项。
+启用沙箱隔离时，doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧版名称的选项。
 
-### 7b) 内置插件运行时依赖
+### 7b）内置插件运行时依赖
 
-Doctor 会验证内置插件运行时依赖（例如 Discord 插件运行时包）是否存在于 OpenClaw 安装根目录中。
-如果缺少任何依赖，doctor 会报告这些包，并在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式下安装它们。
+Doctor 仅验证在当前配置中处于活动状态，或因其内置清单默认值而启用的内置插件的运行时依赖，例如 `plugins.entries.discord.enabled: true`、旧版 `channels.discord.enabled: true`，或默认启用的内置提供商。如果缺少任何依赖，doctor 会报告相应的软件包，并在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式下安装它们。外部插件仍然使用 `openclaw plugins install` / `openclaw plugins update`；doctor 不会为任意插件路径安装依赖。
 
-### 8) Gateway 网关服务迁移和清理提示
+### 8）Gateway 网关服务迁移和清理提示
 
-Doctor 会检测旧版 Gateway 网关服务（`launchd/systemd/schtasks`），并提供移除它们、同时使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的类似 Gateway 网关的服务并打印清理提示。带 profile 名称的 OpenClaw Gateway 网关服务被视为一等公民，不会被标记为“额外”。
+Doctor 会检测旧版 Gateway 网关服务（`launchd`/`systemd`/`schtasks`），并提供移除它们并使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的类 Gateway 网关服务并打印清理提示。带 profile 名称的 OpenClaw Gateway 网关服务被视为一等公民，不会被标记为“额外”。
 
-### 8b) 启动时 Matrix 迁移
+### 8b）启动 Matrix 迁移
 
-当某个 Matrix 渠道账户存在待处理或可执行的旧版状态迁移时，doctor（在 `--fix` / `--repair` 模式下）会先创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都不是致命的；错误会被记录，启动会继续进行。在只读模式（不带 `--fix` 的 `openclaw doctor`）下，此检查会被完全跳过。
+当某个 Matrix 渠道账户存在待处理或可执行的旧版状态迁移时，doctor（在 `--fix` / `--repair` 模式下）会先创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都不是致命的；错误会被记录，启动会继续进行。在只读模式下（不带 `--fix` 的 `openclaw doctor`），此检查会被完全跳过。
 
-### 8c) 设备配对和凭证漂移
+### 8c）设备配对和身份验证漂移
 
-Doctor 现在会将设备配对状态纳入常规健康检查的一部分。
+Doctor 现在会将设备配对状态检查纳入常规健康检查流程。
 
-它会报告的内容：
+它会报告：
 
 - 待处理的首次配对请求
-- 已配对设备的待处理角色升级
-- 已配对设备的待处理作用域升级
-- 公钥不匹配修复：设备 ID 仍然匹配，但设备身份已不再与已批准记录匹配
-- 已配对记录中缺少已批准角色的有效令牌
-- 已配对令牌的作用域漂移到已批准配对基线之外
-- 当前机器上的本地缓存设备令牌条目，早于 Gateway 网关侧令牌轮换，或携带过期的作用域元数据
+- 已配对设备待处理的角色升级
+- 已配对设备待处理的作用域升级
+- 公钥不匹配修复：设备 ID 仍匹配，但设备身份已不再匹配已批准记录
+- 已批准角色缺少活动令牌的已配对记录
+- 作用域漂移到已批准配对基线之外的已配对令牌
+- 当前机器的本地缓存设备令牌条目，这些条目早于 Gateway 网关端令牌轮换，或携带过期的作用域元数据
 
-Doctor 不会自动批准配对请求，也不会自动轮换设备令牌。它会直接打印精确的下一步操作：
+Doctor 不会自动批准配对请求，也不会自动轮换设备令牌。它会直接打印下一步操作：
 
-- 使用 `openclaw devices list` 检查待处理请求
-- 使用 `openclaw devices approve <requestId>` 批准精确请求
-- 使用 `openclaw devices rotate --device <deviceId> --role <role>` 轮换新令牌
-- 使用 `openclaw devices remove <deviceId>` 删除并重新批准过期记录
+- 使用 `openclaw devices list` 查看待处理请求
+- 使用 `openclaw devices approve <requestId>` 批准确切请求
+- 使用 `openclaw devices rotate --device <deviceId> --role <role>` 轮换出新的令牌
+- 使用 `openclaw devices remove <deviceId>` 移除过期记录并重新批准
 
-这解决了常见的“明明已配对却仍提示需要配对”的问题：doctor 现在可以区分首次配对、待处理角色/作用域升级，以及过期令牌/设备身份漂移。
+这填补了常见的“已经配对但仍然提示需要配对”的漏洞：doctor 现在可以区分首次配对、待处理角色/作用域升级，以及过期令牌/设备身份漂移。
 
-### 9) 安全警告
+### 9）安全警告
 
-当某个提供商对私信开放但没有 allowlist，或某项策略以危险方式配置时，doctor 会发出警告。
+当某个提供商对 私信 开放但没有允许列表，或某项策略以危险方式配置时，doctor 会发出警告。
 
-### 10) systemd linger（Linux）
+### 10）`systemd linger`（Linux）
 
-如果以 systemd 用户服务运行，doctor 会确保已启用 lingering，以便 gateway 在注销后仍保持运行。
+如果以 `systemd` 用户服务运行，doctor 会确保已启用 lingering，以便 Gateway 网关在注销后仍保持运行。
 
-### 11) 工作区状态（Skills、插件和旧版目录）
+### 11）工作区状态（Skills、插件和旧版目录）
 
 Doctor 会打印默认智能体的工作区状态摘要：
 
-- **Skills 状态**：统计可用、缺少要求和被 allowlist 阻止的 Skills 数量。
+- **Skills 状态**：统计可用、缺少依赖和被允许列表阻止的 Skills 数量。
 - **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录与当前工作区并存时发出警告。
 - **插件状态**：统计已加载/已禁用/出错的插件数量；列出所有出错插件的插件 ID；报告内置插件能力。
 - **插件兼容性警告**：标记与当前运行时存在兼容性问题的插件。
 - **插件诊断**：显示插件注册表在加载时发出的任何警告或错误。
 
-### 11b) bootstrap 文件大小
+### 11b）引导文件大小
 
-Doctor 会检查工作区 bootstrap 文件（例如 `AGENTS.md`、`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过配置的字符预算。它会按文件报告原始字符数与注入后字符数、截断百分比、截断原因（`max/file` 或 `max/total`），以及注入总字符数占总预算的比例。当文件被截断或接近限制时，doctor 会打印关于调整 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 的提示。
+Doctor 会检查工作区引导文件（例如 `AGENTS.md`、`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过配置的字符预算。它会按文件报告原始字符数与注入字符数、截断百分比、截断原因（`max/file` 或 `max/total`），以及总注入字符数占总预算的比例。当文件被截断或接近限制时，doctor 会打印关于调整 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 的建议。
 
-### 11c) Shell 补全
+### 11c）Shell 补全
 
-Doctor 会检查当前 shell（zsh、bash、fish 或 PowerShell）是否已安装 Tab 补全：
+Doctor 会检查当前 shell（`zsh`、`bash`、`fish` 或 PowerShell）是否已安装 Tab 补全：
 
-- 如果 shell 配置文件使用了较慢的动态补全模式（`source <(openclaw completion ...)`），doctor 会将其升级为更快的缓存文件变体。
+- 如果 shell 配置文件使用了较慢的动态补全模式（`source <(openclaw completion ...)`），doctor 会将其升级为更快的缓存文件版本。
 - 如果补全已在配置文件中设置，但缓存文件缺失，doctor 会自动重新生成缓存。
-- 如果完全未配置补全，doctor 会提示你安装它（仅交互模式；`--non-interactive` 时跳过）。
+- 如果完全没有配置补全，doctor 会提示进行安装（仅限交互模式；`--non-interactive` 时跳过）。
 
-运行 `openclaw completion --write-state` 可以手动重新生成缓存。
+运行 `openclaw completion --write-state` 可手动重新生成缓存。
 
-### 12) Gateway 网关凭证检查（本地令牌）
+### 12）Gateway 网关身份验证检查（本地令牌）
 
-Doctor 会检查本地 Gateway 网关令牌鉴权的就绪状态。
+Doctor 会检查本地 Gateway 网关令牌身份验证的就绪情况。
 
-- 如果令牌模式需要令牌而且不存在令牌来源，doctor 会提供生成令牌的选项。
-- 如果 `gateway.auth.token` 由 `SecretRef` 管理但不可用，doctor 会发出警告，并且不会用明文覆盖它。
-- `openclaw doctor --generate-gateway-token` 只会在未配置令牌 `SecretRef` 时强制生成。
+- 如果令牌模式需要令牌且不存在令牌来源，doctor 会提供生成令牌的选项。
+- 如果 `gateway.auth.token` 由 `SecretRef` 管理但当前不可用，doctor 会发出警告，并且不会用明文覆盖它。
+- `openclaw doctor --generate-gateway-token` 仅会在未配置令牌 `SecretRef` 时强制生成令牌。
 
-### 12b) 只读的 SecretRef 感知修复
+### 12b）只读且感知 `SecretRef` 的修复
 
 某些修复流程需要检查已配置的凭证，同时又不能削弱运行时快速失败行为。
 
-- `openclaw doctor --fix` 现在对有针对性的配置修复使用与 status 系列命令相同的只读 `SecretRef` 摘要模型。
-- 示例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修复会在可用时尝试使用已配置的 bot 凭证。
-- 如果 Telegram bot token 通过 `SecretRef` 配置，但在当前命令路径中不可用，doctor 会报告该凭证为“已配置但不可用”，并跳过自动解析，而不是崩溃或错误地将该 token 报告为缺失。
+- `openclaw doctor --fix` 现在使用与 status 系列命令相同的只读 `SecretRef` 摘要模型来执行定向配置修复。
+- 示例：Telegram 的 `allowFrom` / `groupAllowFrom` `@username` 修复会在可用时尝试使用已配置的 bot 凭证。
+- 如果 Telegram bot 令牌是通过 `SecretRef` 配置的，但在当前命令路径中不可用，doctor 会报告该凭证“已配置但不可用”，并跳过自动解析，而不是崩溃或错误地将令牌报告为缺失。
 
-### 13) Gateway 网关健康检查 + 重启
+### 13）Gateway 网关健康检查 + 重启
 
 Doctor 会运行健康检查，并在 Gateway 网关看起来不健康时提供重启选项。
 
-### 13b) Memory 搜索就绪状态
+### 13b）Memory 搜索就绪情况
 
-Doctor 会检查为默认智能体配置的 Memory 搜索嵌入提供商是否已就绪。具体行为取决于所配置的后端和提供商：
+Doctor 会检查为默认智能体配置的 Memory 搜索嵌入提供商是否已就绪。具体行为取决于配置的后端和提供商：
 
 - **QMD 后端**：探测 `qmd` 二进制文件是否可用且可启动。
   如果不可用，会打印修复指引，包括 npm 包和手动二进制路径选项。
-- **显式本地提供商**：检查本地模型文件或已识别的远程/可下载模型 URL。
+- **显式本地提供商**：检查本地模型文件或可识别的远程/可下载模型 URL。
   如果缺失，会建议切换到远程提供商。
-- **显式远程提供商**（`openai`、`voyage` 等）：验证环境变量或凭证存储中是否存在 API key。若缺失，会打印可执行的修复提示。
-- **自动提供商**：先检查本地模型可用性，然后按自动选择顺序尝试各个远程提供商。
+- **显式远程提供商**（`openai`、`voyage` 等）：验证环境中或身份验证存储中是否存在 API 密钥。如果缺失，会打印可操作的修复提示。
+- **自动提供商**：先检查本地模型可用性，然后按照自动选择顺序尝试每个远程提供商。
 
-当 Gateway 网关探测结果可用时（即检查时 Gateway 网关健康），doctor 会将其结果与 CLI 可见配置进行交叉比对，并注明任何差异。
+当 Gateway 网关探测结果可用时（即检查时 Gateway 网关健康），doctor 会将其结果与 CLI 可见配置进行交叉比对，并指出任何差异。
 
-使用 `openclaw memory status --deep` 可在运行时验证嵌入就绪状态。
+使用 `openclaw memory status --deep` 可在运行时验证嵌入就绪情况。
 
-### 14) 渠道状态警告
+### 14）渠道状态警告
 
-如果 Gateway 网关健康，doctor 会运行渠道状态探测，并报告带有建议修复方案的警告。
+如果 Gateway 网关健康，doctor 会运行渠道状态探测，并报告带有建议修复方法的警告。
 
-### 15) Supervisor 配置审计 + 修复
+### 15）supervisor 配置审计 + 修复
 
-Doctor 会检查已安装的 supervisor 配置（`launchd/systemd/schtasks`）中是否缺少默认值或默认值已过期（例如 systemd 的 network-online 依赖和重启延迟）。当发现不匹配时，它会建议更新，并可将服务文件/任务重写为当前默认值。
+Doctor 会检查已安装的 supervisor 配置（`launchd`/`systemd`/`schtasks`）中是否缺少或使用了过期默认值（例如 `systemd network-online` 依赖和重启延迟）。当发现不匹配时，它会建议更新，并可将服务文件/任务重写为当前默认值。
 
 说明：
 
-- `openclaw doctor` 会在重写 supervisor 配置前提示你确认。
+- `openclaw doctor` 会在重写 supervisor 配置前提示确认。
 - `openclaw doctor --yes` 会接受默认修复提示。
-- `openclaw doctor --repair` 会在无提示的情况下应用建议修复。
+- `openclaw doctor --repair` 会在无提示的情况下应用推荐修复。
 - `openclaw doctor --repair --force` 会覆盖自定义 supervisor 配置。
-- 如果令牌鉴权需要 token，且 `gateway.auth.token` 由 `SecretRef` 管理，doctor 在服务安装/修复时会校验 `SecretRef`，但不会将解析出的明文 token 值持久化到 supervisor 服务环境元数据中。
-- 如果令牌鉴权需要 token，但配置的 token `SecretRef` 无法解析，doctor 会阻止安装/修复路径，并提供可执行的指引。
-- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，但未设置 `gateway.auth.mode`，doctor 会阻止安装/修复，直到显式设置 mode。
-- 对于 Linux 用户级 systemd 单元，doctor 的 token 漂移检查现在在比较服务鉴权元数据时会同时包含 `Environment=` 和 `EnvironmentFile=` 来源。
+- 如果令牌身份验证需要令牌，并且 `gateway.auth.token` 由 `SecretRef` 管理，doctor 在服务安装/修复时会验证该 `SecretRef`，但不会将解析出的明文令牌值持久化到 supervisor 服务环境元数据中。
+- 如果令牌身份验证需要令牌，而已配置的令牌 `SecretRef` 无法解析，doctor 会阻止安装/修复流程，并给出可操作的指引。
+- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，但未设置 `gateway.auth.mode`，doctor 会阻止安装/修复，直到显式设置模式。
+- 对于 Linux 用户级 `systemd` 单元，doctor 的令牌漂移检查现在会在比较服务身份验证元数据时同时包含 `Environment=` 和 `EnvironmentFile=` 来源。
 - 你始终可以通过 `openclaw gateway install --force` 强制执行完整重写。
 
-### 16) Gateway 网关运行时 + 端口诊断
+### 16）Gateway 网关运行时 + 端口诊断
 
-Doctor 会检查服务运行时（PID、最近退出状态），并在服务已安装但实际未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。
+Doctor 会检查服务运行时（PID、上次退出状态），并在服务已安装但实际上未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。
 
-### 17) Gateway 网关运行时最佳实践
+### 17）Gateway 网关运行时最佳实践
 
-当 Gateway 网关服务运行在 Bun 或版本管理器管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上时，doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，而版本管理器路径在升级后可能失效，因为服务不会加载你的 shell 初始化。Doctor 会在可用时提供迁移到系统 Node 安装的选项（Homebrew/apt/choco）。
+当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上时，doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，而版本管理器路径在升级后可能失效，因为服务不会加载你的 shell 初始化。Doctor 会在可用时提供迁移到系统级 Node 安装的选项（Homebrew/`apt`/`choco`）。
 
-### 18) 配置写入 + 向导元数据
+### 18）配置写入 + 向导元数据
 
-Doctor 会持久化所有配置变更，并写入向导元数据以记录此次 doctor 运行。
+Doctor 会持久化任何配置变更，并写入向导元数据以记录此次 doctor 运行。
 
-### 19) 工作区提示（备份 + Memory 系统）
+### 19）工作区提示（备份 + 记忆系统）
 
-当工作区缺少 Memory 系统时，doctor 会给出建议；如果工作区尚未纳入 git，它还会打印备份提示。
+如果缺少工作区记忆系统，Doctor 会给出建议；如果工作区尚未纳入 git，它还会打印备份提示。
 
-有关工作区结构和 git 备份（推荐使用私有 GitHub 或 GitLab）的完整指南，请参阅 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)。
+有关工作区结构和 git 备份（推荐使用私有 GitHub 或 GitLab）的完整指南，请参见 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)。

docs/zh-CN/plugins/sdk-setup.md

@@ -4,28 +4,30 @@ read_when:
     - 你需要理解 `setup-entry.ts` 与 `index.ts` 的区别
     - 你正在定义插件配置模式或 `package.json` 中的 OpenClaw 元数据
 sidebarTitle: Setup and Config
-summary: 设置向导、setup-entry.ts、配置模式以及 package.json 元数据
+summary: 设置向导、setup-entry.ts、配置模式和 package.json 元数据
 title: 插件设置和配置
 x-i18n:
-    generated_at: "2026-04-15T16:36:52Z"
+    generated_at: "2026-04-20T16:50:01Z"
     model: gpt-5.4
     provider: openai
-    source_hash: ddf28e25e381a4a38ac478e531586f59612e1a278732597375f87c2eeefc521b
+    source_hash: 5de51b55c04b4f05947bc2d4de9c34e24a26e4ca8b3ff9b1711288a8e5b63273
     source_path: plugins/sdk-setup.md
     workflow: 15
 ---
 
 # 插件设置和配置
 
-插件打包（`package.json` 元数据）、清单（`openclaw.plugin.json`）、设置入口和配置模式的参考文档。
+关于插件打包（`package.json` 元数据）、清单（`openclaw.plugin.json`）、设置入口和配置模式的参考。
 
 <Tip>
-  **想看操作演练？** 操作指南会在上下文中介绍打包方式： [渠道插件](/zh-CN/plugins/sdk-channel-plugins#step-1-package-and-manifest) 和 [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-1-package-and-manifest)。
+  **在找操作指南吗？** 操作指南会结合上下文介绍打包流程：
+  [渠道插件](/zh-CN/plugins/sdk-channel-plugins#step-1-package-and-manifest) 和
+  [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-1-package-and-manifest)。
 </Tip>
 
 ## 包元数据
 
-你的 `package.json` 需要有一个 `openclaw` 字段，用来告诉插件系统你的插件提供了什么：
+你的 `package.json` 需要包含一个 `openclaw` 字段，用来告诉插件系统你的插件提供了什么：
 
 **渠道插件：**
 
@@ -40,7 +42,7 @@ x-i18n:
     "channel": {
       "id": "my-channel",
       "label": "My Channel",
-      "blurb": "渠道的简短说明。"
+      "blurb": "Short description of the channel."
     }
   }
 }
@@ -67,44 +69,46 @@ x-i18n:
 }
 ```
 
-如果你要在 ClawHub 上对外发布插件，这些 `compat` 和 `build` 字段是必需的。规范的发布代码片段位于 `docs/snippets/plugin-publish/`。
+如果你要在 ClawHub 上对外发布该插件，这些 `compat` 和 `build`
+字段是必需的。规范的发布代码片段位于
+`docs/snippets/plugin-publish/`。
 
 ### `openclaw` 字段
 
-| 字段 | 类型 | 说明 |
-| ------------ | ---------- | ------------------------------------------------------------------------------------------------------ |
-| `extensions` | `string[]` | 入口点文件（相对于包根目录） |
-| `setupEntry` | `string`   | 仅用于设置的轻量级入口（可选） |
-| `channel`    | `object`   | 用于设置、选择器、快速开始和状态界面的渠道目录元数据 |
-| `providers`  | `string[]` | 此插件注册的提供商 id |
+| 字段         | 类型       | 说明                                                                 |
+| ------------ | ---------- | -------------------------------------------------------------------- |
+| `extensions` | `string[]` | 入口点文件（相对于包根目录）                                         |
+| `setupEntry` | `string`   | 仅用于设置的轻量入口（可选）                                         |
+| `channel`    | `object`   | 用于设置、选择器、快速开始和状态界面的渠道目录元数据                 |
+| `providers`  | `string[]` | 该插件注册的提供商 id                                                |
 | `install`    | `object`   | 安装提示：`npmSpec`、`localPath`、`defaultChoice`、`minHostVersion`、`allowInvalidConfigRecovery` |
-| `startup`    | `object`   | 启动行为标志 |
+| `startup`    | `object`   | 启动行为标志                                                         |
 
 ### `openclaw.channel`
 
-`openclaw.channel` 是轻量级包元数据，用于在运行时加载之前进行渠道发现和展示设置界面。
+`openclaw.channel` 是低成本的包元数据，用于在运行时加载之前支持渠道发现和设置界面。
 
-| 字段 | 类型 | 含义 |
-| -------------------------------------- | ---------- | ----------------------------------------------------------------------------- |
-| `id`                                   | `string`   | 规范的渠道 id。 |
-| `label`                                | `string`   | 主渠道标签。 |
-| `selectionLabel`                       | `string`   | 当需要与 `label` 不同时，在选择器/设置中显示的标签。 |
-| `detailLabel`                          | `string`   | 用于更丰富的渠道目录和状态界面的次级详情标签。 |
-| `docsPath`                             | `string`   | 用于设置和选择链接的文档路径。 |
-| `docsLabel`                            | `string`   | 当文档链接标签需要与渠道 id 不同时，使用的覆盖标签。 |
-| `blurb`                                | `string`   | 简短的新手引导/目录说明。 |
-| `order`                                | `number`   | 在渠道目录中的排序顺序。 |
-| `aliases`                              | `string[]` | 用于渠道选择的额外查找别名。 |
-| `preferOver`                           | `string[]` | 此渠道应优先于的较低优先级插件/渠道 id。 |
-| `systemImage`                          | `string`   | 可选的图标/system-image 名称，用于渠道 UI 目录。 |
-| `selectionDocsPrefix`                  | `string`   | 在选择界面中位于文档链接前的前缀文本。 |
+| 字段                                   | 类型       | 含义                                                  |
+| -------------------------------------- | ---------- | ----------------------------------------------------- |
+| `id`                                   | `string`   | 规范的渠道 id。                                       |
+| `label`                                | `string`   | 主要渠道标签。                                        |
+| `selectionLabel`                       | `string`   | 当需要与 `label` 不同时，在选择器 / 设置中显示的标签。 |
+| `detailLabel`                          | `string`   | 用于更丰富渠道目录和状态界面的次级详情标签。          |
+| `docsPath`                             | `string`   | 用于设置和选择链接的文档路径。                        |
+| `docsLabel`                            | `string`   | 当需要与渠道 id 不同时，用作文档链接标签的覆盖值。    |
+| `blurb`                                | `string`   | 简短的新手引导 / 目录描述。                           |
+| `order`                                | `number`   | 在渠道目录中的排序顺序。                              |
+| `aliases`                              | `string[]` | 用于渠道选择的额外查找别名。                          |
+| `preferOver`                           | `string[]` | 该渠道应优先于的较低优先级插件 / 渠道 id。            |
+| `systemImage`                          | `string`   | 渠道 UI 目录中可选的图标 / system-image 名称。        |
+| `selectionDocsPrefix`                  | `string`   | 在选择界面中文档链接前显示的前缀文本。                |
 | `selectionDocsOmitLabel`               | `boolean`  | 在选择文案中直接显示文档路径，而不是带标签的文档链接。 |
-| `selectionExtras`                      | `string[]` | 附加到选择文案中的额外短文本。 |
-| `markdownCapable`                      | `boolean`  | 将渠道标记为支持 Markdown，以用于出站格式决策。 |
-| `exposure`                             | `object`   | 针对设置、已配置列表和文档界面的渠道可见性控制。 |
-| `quickstartAllowFrom`                  | `boolean`  | 让此渠道加入标准快速开始 `allowFrom` 设置流程。 |
-| `forceAccountBinding`                  | `boolean`  | 即使只有一个账号，也要求显式账号绑定。 |
-| `preferSessionLookupForAnnounceTarget` | `boolean`  | 为此渠道解析公告目标时，优先使用会话查找。 |
+| `selectionExtras`                      | `string[]` | 附加在选择文案中的额外短文本。                        |
+| `markdownCapable`                      | `boolean`  | 将该渠道标记为支持 Markdown，用于出站格式决策。       |
+| `exposure`                             | `object`   | 渠道在设置、已配置列表和文档界面中的可见性控制。      |
+| `quickstartAllowFrom`                  | `boolean`  | 让该渠道加入标准快速开始 `allowFrom` 设置流程。       |
+| `forceAccountBinding`                  | `boolean`  | 即使只有一个账户存在，也要求显式账户绑定。            |
+| `preferSessionLookupForAnnounceTarget` | `boolean`  | 为该渠道解析公告目标时，优先使用会话查找。            |
 
 示例：
 
@@ -118,11 +122,11 @@ x-i18n:
       "detailLabel": "My Channel Bot",
       "docsPath": "/channels/my-channel",
       "docsLabel": "my-channel",
-      "blurb": "基于 Webhook 的自托管聊天集成。",
+      "blurb": "Webhook-based self-hosted chat integration.",
       "order": 80,
       "aliases": ["mc"],
       "preferOver": ["my-channel-legacy"],
-      "selectionDocsPrefix": "指南：",
+      "selectionDocsPrefix": "Guide:",
       "selectionExtras": ["Markdown"],
       "markdownCapable": true,
       "exposure": {
@@ -138,31 +142,34 @@ x-i18n:
 
 `exposure` 支持：
 
-- `configured`：在已配置/状态类列表界面中包含该渠道
-- `setup`：在交互式设置/配置选择器中包含该渠道
-- `docs`：在文档/导航界面中将该渠道标记为面向公开
+- `configured`：在已配置 / 状态类列表界面中包含该渠道
+- `setup`：在交互式设置 / 配置选择器中包含该渠道
+- `docs`：将该渠道标记为面向公开的文档 / 导航界面内容
 
-`showConfigured` 和 `showInSetup` 仍然作为旧版别名受支持。优先使用 `exposure`。
+`showConfigured` 和 `showInSetup` 仍然作为旧别名受支持。优先使用
+`exposure`。
 
 ### `openclaw.install`
 
 `openclaw.install` 是包元数据，不是清单元数据。
 
-| 字段 | 类型 | 含义 |
+| 字段                         | 类型                 | 含义                                                                             |
 | ---------------------------- | -------------------- | -------------------------------------------------------------------------------- |
-| `npmSpec`                    | `string`             | 用于安装/更新流程的规范 npm spec。 |
-| `localPath`                  | `string`             | 本地开发或内置安装路径。 |
-| `defaultChoice`              | `"npm"` \| `"local"` | 当两者都可用时，优先使用的安装来源。 |
-| `minHostVersion`             | `string`             | 支持的最低 OpenClaw 版本，格式为 `>=x.y.z`。 |
-| `allowInvalidConfigRecovery` | `boolean`            | 允许内置插件重装流程从特定的陈旧配置故障中恢复。 |
+| `npmSpec`                    | `string`             | 用于安装 / 更新流程的规范 npm spec。                                             |
+| `localPath`                  | `string`             | 本地开发或内置安装路径。                                                         |
+| `defaultChoice`              | `"npm"` \| `"local"` | 当两者都可用时，优先使用的安装来源。                                             |
+| `minHostVersion`             | `string`             | 支持的最低 OpenClaw 版本，格式为 `>=x.y.z`。                                     |
+| `allowInvalidConfigRecovery` | `boolean`            | 允许内置插件重装流程从特定的过期配置失败中恢复。                                 |
 
-如果设置了 `minHostVersion`，安装和清单注册表加载都会强制执行它。较旧的宿主会跳过该插件；无效的版本字符串会被拒绝。
+如果设置了 `minHostVersion`，安装和清单注册表加载都会强制执行它。
+较旧的宿主会跳过该插件；无效的版本字符串会被拒绝。
 
-`allowInvalidConfigRecovery` 不是对损坏配置的通用绕过。它仅用于较窄范围的内置插件恢复，以便重装/设置能够修复已知的升级遗留问题，例如缺失的内置插件路径，或该插件对应的陈旧 `channels.<id>` 条目。如果配置因无关原因损坏，安装仍会以安全关闭的方式失败，并提示操作员运行 `openclaw doctor --fix`。
+`allowInvalidConfigRecovery` 不是针对损坏配置的通用绕过方式。它仅用于内置插件的狭义恢复场景，使重装 / 设置可以修复已知的升级遗留问题，例如缺失的内置插件路径，或该插件对应的过期 `channels.<id>`
+条目。如果配置因无关原因损坏，安装仍会以关闭方式失败，并提示操作员运行 `openclaw doctor --fix`。
 
 ### 延迟完整加载
 
-渠道插件可以通过以下方式启用延迟加载：
+渠道插件可以通过以下方式选择启用延迟加载：
 
 ```json
 {
@@ -176,30 +183,32 @@ x-i18n:
 }
 ```
 
-启用后，即使渠道已经配置，OpenClaw 在监听前的启动阶段也只会加载 `setupEntry`。完整入口会在 Gateway 网关开始监听后再加载。
+启用后，OpenClaw 在监听前的启动阶段只会加载 `setupEntry`，即使对于已配置的渠道也是如此。完整入口会在 Gateway 网关开始监听后再加载。
 
 <Warning>
-  仅当你的 `setupEntry` 注册了 Gateway 网关在开始监听前所需的全部内容时，才启用延迟加载（渠道注册、HTTP 路由、Gateway 网关方法）。如果完整入口拥有必需的启动能力，请保持默认行为。
+  仅当你的 `setupEntry` 注册了 Gateway 网关在开始监听前所需的一切内容时，才应启用延迟加载（渠道注册、HTTP 路由、Gateway 网关方法）。如果完整入口拥有必需的启动能力，请保持默认行为。
 </Warning>
 
-如果你的设置/完整入口会注册 Gateway 网关 RPC 方法，请将它们保留在插件专用前缀下。保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍由核心拥有，并始终解析到 `operator.admin`。
+如果你的设置 / 完整入口会注册 Gateway 网关 RPC 方法，请保持使用插件专属前缀。保留的核心管理命名空间（`config.*`、
+`exec.approvals.*`、`wizard.*`、`update.*`）仍由核心拥有，并始终解析到 `operator.admin`。
 
 ## 插件清单
 
-每个原生插件都必须在包根目录中提供一个 `openclaw.plugin.json`。OpenClaw 使用它在不执行插件代码的情况下验证配置。
+每个原生插件都必须在包根目录提供一个 `openclaw.plugin.json`。
+OpenClaw 使用它在不执行插件代码的情况下验证配置。
 
 ```json
 {
   "id": "my-plugin",
   "name": "My Plugin",
-  "description": "为 OpenClaw 添加 My Plugin 功能",
+  "description": "Adds My Plugin capabilities to OpenClaw",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
     "properties": {
       "webhookSecret": {
         "type": "string",
-        "description": "Webhook 验证密钥"
+        "description": "Webhook verification secret"
       }
     }
   }
@@ -233,7 +242,7 @@ x-i18n:
 }
 ```
 
-完整模式参考见 [插件清单](/zh-CN/plugins/manifest)。
+完整模式参考请见 [插件清单](/zh-CN/plugins/manifest)。
 
 ## ClawHub 发布
 
@@ -244,11 +253,11 @@ clawhub package publish your-org/your-plugin --dry-run
 clawhub package publish your-org/your-plugin
 ```
 
-旧版仅适用于 Skills 的发布别名是给 Skills 用的。插件包应始终使用 `clawhub package publish`。
+旧版仅适用于 skill 的发布别名是给 Skills 使用的。插件包应始终使用 `clawhub package publish`。
 
 ## 设置入口
 
-`setup-entry.ts` 文件是 `index.ts` 的轻量级替代方案，当 OpenClaw 只需要设置界面时（新手引导、配置修复、已禁用渠道检查），会加载它。
+`setup-entry.ts` 文件是 `index.ts` 的轻量替代方案，当 OpenClaw 只需要设置界面时（新手引导、配置修复、禁用渠道检查），会加载它。
 
 ```typescript
 // setup-entry.ts
@@ -258,13 +267,16 @@ import { myChannelPlugin } from "./src/channel.js";
 export default defineSetupPluginEntry(myChannelPlugin);
 ```
 
-这可以避免在设置流程中加载沉重的运行时代码（加密库、CLI 注册、后台服务）。
+这可以避免在设置流程中加载重量级运行时代码（加密库、CLI 注册、后台服务）。
 
-对于将设置安全导出保存在 sidecar 模块中的内置工作区渠道，可以使用 `openclaw/plugin-sdk/channel-entry-contract` 中的 `defineBundledChannelSetupEntry(...)`，而不是 `defineSetupPluginEntry(...)`。该内置契约还支持可选的 `runtime` 导出，以便让设置时的运行时接线保持轻量且明确。
+对于将设置安全导出保存在 sidecar 模块中的内置工作区渠道，可以使用
+`openclaw/plugin-sdk/channel-entry-contract` 中的
+`defineBundledChannelSetupEntry(...)`，而不是
+`defineSetupPluginEntry(...)`。该内置契约还支持可选的 `runtime` 导出，从而让设置阶段的运行时接线保持轻量且明确。
 
 **OpenClaw 在以下情况下会使用 `setupEntry` 而不是完整入口：**
 
-- 渠道已禁用，但需要设置/新手引导界面
+- 渠道已禁用，但仍需要设置 / 新手引导界面
 - 渠道已启用，但尚未配置
 - 已启用延迟加载（`deferConfiguredChannelFullLoadUntilAfterListen`）
 
@@ -280,38 +292,45 @@ export default defineSetupPluginEntry(myChannelPlugin);
 
 - CLI 注册
 - 后台服务
-- 沉重的运行时导入（加密库、SDK）
+- 重量级运行时导入（加密库、SDK）
 - 仅在启动后才需要的 Gateway 网关方法
 
-### 窄范围设置辅助导入
+### 窄化设置辅助导入
 
-对于仅设置的热点路径，如果你只需要部分设置能力，优先使用窄范围的设置辅助接缝，而不是更宽泛的 `plugin-sdk/setup` 总入口：
+对于仅设置的热点路径，如果你只需要设置界面的一部分，优先使用窄化的设置辅助接缝，而不是更宽泛的 `plugin-sdk/setup` 总入口：
 
-| 导入路径 | 适用场景 | 关键导出 |
+| 导入路径                           | 适用场景                                                                                  | 关键导出                                                                                                                                                                                                                                                                                     |
 | ---------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `plugin-sdk/setup-runtime`         | 在 `setupEntry` / 延迟渠道启动中仍可用的设置时运行时辅助工具 | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
-| `plugin-sdk/setup-adapter-runtime` | 具备环境感知能力的账号设置适配器 | `createEnvPatchedAccountSetupAdapter` |
-| `plugin-sdk/setup-tools`           | 设置/安装 CLI、归档、文档辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
+| `plugin-sdk/setup-runtime`         | 在 `setupEntry` / 延迟渠道启动中仍可用的设置期运行时辅助工具                              | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
+| `plugin-sdk/setup-adapter-runtime` | 感知环境的账户设置适配器                                                                  | `createEnvPatchedAccountSetupAdapter`                                                                                                                                                                                                                                                        |
+| `plugin-sdk/setup-tools`           | 设置 / 安装 CLI / 归档 / 文档辅助工具                                                     | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`                                                                                                                                                                               |
 
-当你需要完整的共享设置工具箱时，请使用更宽泛的 `plugin-sdk/setup` 接缝，其中包括配置补丁辅助工具，例如 `moveSingleAccountChannelSectionToDefaultAccount(...)`。
+当你需要完整的共享设置工具箱时，请使用更宽泛的 `plugin-sdk/setup`
+接缝，其中包括配置补丁辅助工具，例如
+`moveSingleAccountChannelSectionToDefaultAccount(...)`。
 
-这些设置补丁适配器在导入时仍然适合热点路径使用。它们对内置单账号提升契约面的查找是惰性的，因此导入 `plugin-sdk/setup-runtime` 不会在适配器真正使用前急切加载内置契约面发现逻辑。
+这些设置补丁适配器在导入时仍然对热点路径安全。它们对内置单账户提升契约界面的查找是惰性的，因此导入
+`plugin-sdk/setup-runtime` 不会在实际使用适配器之前急切加载内置契约界面发现逻辑。
 
-### 渠道自有的单账号提升
+### 渠道自有的单账户提升
 
-当某个渠道从单账号顶层配置升级到 `channels.<id>.accounts.*` 时，默认的共享行为是将被提升的账号作用域值移动到 `accounts.default` 中。
+当一个渠道从单账户顶层配置升级到
+`channels.<id>.accounts.*` 时，默认的共享行为会将被提升的账户作用域值移动到
+`accounts.default` 中。
 
-内置渠道可以通过其设置契约面缩小或覆盖该提升行为：
+内置渠道可以通过其设置契约界面缩小或覆盖该提升行为：
 
-- `singleAccountKeysToMove`：应移动到提升后账号中的额外顶层键
-- `namedAccountPromotionKeys`：当已存在命名账号时，只有这些键会移动到提升后的账号中；共享的策略/投递键会保留在渠道根级别
-- `resolveSingleAccountPromotionTarget(...)`：选择由哪个现有账号接收提升后的值
+- `singleAccountKeysToMove`：应移动到被提升账户中的额外顶层键
+- `namedAccountPromotionKeys`：当已存在命名账户时，只有这些键会移动到被提升账户中；共享的策略 / 投递键会保留在渠道根级别
+- `resolveSingleAccountPromotionTarget(...)`：选择哪个现有账户接收被提升的值
 
-Matrix 是当前的内置示例。如果已经恰好存在一个命名的 Matrix 账号，或者 `defaultAccount` 指向现有的非规范键（例如 `Ops`），提升过程会保留该账号，而不是新建一个 `accounts.default` 条目。
+Matrix 是当前的内置示例。如果恰好已经存在一个命名的 Matrix 账户，或者
+`defaultAccount` 指向一个现有的非规范键（例如 `Ops`），提升过程会保留该账户，而不是创建新的
+`accounts.default` 条目。
 
 ## 配置模式
 
-插件配置会根据你在清单中定义的 JSON Schema 进行验证。用户通过以下方式配置插件：
+插件配置会根据清单中的 JSON Schema 进行验证。用户通过以下方式配置插件：
 
 ```json5
 {
@@ -327,9 +346,9 @@ Matrix 是当前的内置示例。如果已经恰好存在一个命名的 Matrix
 }
 ```
 
-在注册期间，你的插件会通过 `api.pluginConfig` 接收到这份配置。
+你的插件会在注册期间通过 `api.pluginConfig` 接收这份配置。
 
-对于渠道专用配置，请改用渠道配置部分：
+对于特定渠道的配置，请改用渠道配置区段：
 
 ```json5
 {
@@ -344,7 +363,8 @@ Matrix 是当前的内置示例。如果已经恰好存在一个命名的 Matrix
 
 ### 构建渠道配置模式
 
-使用 `openclaw/plugin-sdk/core` 中的 `buildChannelConfigSchema`，将 Zod 模式转换为 OpenClaw 用于验证的 `ChannelConfigSchema` 包装器：
+使用 `openclaw/plugin-sdk/core` 中的 `buildChannelConfigSchema` 将一个
+Zod 模式转换为 OpenClaw 用于验证的 `ChannelConfigSchema` 包装器：
 
 ```typescript
 import { z } from "zod";
@@ -362,7 +382,8 @@ const configSchema = buildChannelConfigSchema(accountSchema);
 
 ## 设置向导
 
-渠道插件可以为 `openclaw onboard` 提供交互式设置向导。该向导是 `ChannelPlugin` 上的一个 `ChannelSetupWizard` 对象：
+渠道插件可以为 `openclaw onboard` 提供交互式设置向导。
+该向导是 `ChannelPlugin` 上的一个 `ChannelSetupWizard` 对象：
 
 ```typescript
 import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";
@@ -370,19 +391,19 @@ import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";
 const setupWizard: ChannelSetupWizard = {
   channel: "my-channel",
   status: {
-    configuredLabel: "已连接",
-    unconfiguredLabel: "未配置",
+    configuredLabel: "Connected",
+    unconfiguredLabel: "Not configured",
     resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),
   },
   credentials: [
     {
       inputKey: "token",
       providerHint: "my-channel",
-      credentialLabel: "机器人令牌",
+      credentialLabel: "Bot token",
       preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",
-      envPrompt: "使用环境中的 MY_CHANNEL_BOT_TOKEN 吗？",
-      keepPrompt: "保留当前令牌吗？",
-      inputPrompt: "输入你的机器人令牌：",
+      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",
+      keepPrompt: "Keep current token?",
+      inputPrompt: "Enter your bot token:",
       inspect: ({ cfg, accountId }) => {
         const token = (cfg.channels as any)?.["my-channel"]?.token;
         return {
@@ -395,13 +416,26 @@ const setupWizard: ChannelSetupWizard = {
 };
 ```
 
-`ChannelSetupWizard` 类型支持 `credentials`、`textInputs`、`dmPolicy`、`allowFrom`、`groupAccess`、`prepare`、`finalize` 等等。完整示例请参见内置插件包（例如 Discord 插件的 `src/channel.setup.ts`）。
+`ChannelSetupWizard` 类型支持 `credentials`、`textInputs`、
+`dmPolicy`、`allowFrom`、`groupAccess`、`prepare`、`finalize`
+等。完整示例请参阅内置插件包（例如 Discord 插件中的 `src/channel.setup.ts`）。
 
-对于只需要标准 `note -> prompt -> parse -> merge -> patch` 流程的私信白名单提示，优先使用 `openclaw/plugin-sdk/setup` 中的共享设置辅助工具：`createPromptParsedAllowFromForAccount(...)`、`createTopLevelChannelParsedAllowFromPrompt(...)` 和 `createNestedChannelParsedAllowFromPrompt(...)`。
+对于只需要标准
+`note -> prompt -> parse -> merge -> patch`
+流程的私信 allowlist 提示，优先使用
+`openclaw/plugin-sdk/setup` 中的共享设置辅助工具：
+`createPromptParsedAllowFromForAccount(...)`、
+`createTopLevelChannelParsedAllowFromPrompt(...)` 和
+`createNestedChannelParsedAllowFromPrompt(...)`。
 
-对于只在标签、分数和可选额外行上有所不同的渠道设置状态块，优先使用 `openclaw/plugin-sdk/setup` 中的 `createStandardChannelSetupStatus(...)`，而不是在每个插件中手写相同的 `status` 对象。
+对于仅在标签、分数和可选附加行上有所不同的渠道设置状态块，优先使用
+`openclaw/plugin-sdk/setup` 中的
+`createStandardChannelSetupStatus(...)`，而不是在每个插件中手动重复构建相同的
+`status` 对象。
 
-对于只应在特定上下文中出现的可选设置界面，请使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface`：
+对于只应在特定上下文中显示的可选设置界面，使用
+`openclaw/plugin-sdk/channel-setup` 中的
+`createOptionalChannelSetupSurface`：
 
 ```typescript
 import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup";
@@ -412,19 +446,28 @@ const setupSurface = createOptionalChannelSetupSurface({
   npmSpec: "@myorg/openclaw-my-channel",
   docsPath: "/channels/my-channel",
 });
-// 返回 { setupAdapter, setupWizard }
+// Returns { setupAdapter, setupWizard }
 ```
 
-`plugin-sdk/channel-setup` 还公开了更底层的 `createOptionalChannelSetupAdapter(...)` 和 `createOptionalChannelSetupWizard(...)` 构建器，适用于你只需要这个可选安装界面其中一半能力的情况。
+`plugin-sdk/channel-setup` 还暴露了更底层的
+`createOptionalChannelSetupAdapter(...)` 和
+`createOptionalChannelSetupWizard(...)` 构建器，用于你只需要该可选安装界面其中一半的情况。
 
-生成的可选适配器/向导在真正写入配置时会以安全关闭方式失败。它们会在 `validateInput`、`applyAccountConfig` 和 `finalize` 之间复用同一条“需要安装”的消息，并在设置了 `docsPath` 时附加一个文档链接。
+生成的可选适配器 / 向导在真正写入配置时会以关闭方式失败。它们会在
+`validateInput`、`applyAccountConfig` 和 `finalize`
+之间复用同一条“需要安装”的消息，并在设置了 `docsPath`
+时附加一个文档链接。
 
-对于基于二进制程序的设置 UI，优先使用共享的委托辅助工具，而不是把相同的二进制/状态胶水代码复制到每个渠道中：
+对于基于二进制文件的设置 UI，优先使用共享的委托辅助工具，而不是在每个渠道中复制相同的二进制 / 状态粘合逻辑：
 
-- `createDetectedBinaryStatus(...)`：用于仅在标签、提示、分数和二进制检测上有所不同的状态块
+- `createDetectedBinaryStatus(...)`：用于仅在标签、提示、分数和二进制检测上变化的状态块
 - `createCliPathTextInput(...)`：用于基于路径的文本输入
-- `createDelegatedSetupWizardStatusResolvers(...)`、`createDelegatedPrepare(...)`、`createDelegatedFinalize(...)` 和 `createDelegatedResolveConfigured(...)`：适用于当 `setupEntry` 需要惰性转发到更重的完整向导时
-- `createDelegatedTextInputShouldPrompt(...)`：适用于当 `setupEntry` 只需要委托 `textInputs[*].shouldPrompt` 判断时
+- `createDelegatedSetupWizardStatusResolvers(...)`、
+  `createDelegatedPrepare(...)`、`createDelegatedFinalize(...)` 和
+  `createDelegatedResolveConfigured(...)`：用于当 `setupEntry`
+  需要惰性转发到更重量级的完整向导时
+- `createDelegatedTextInputShouldPrompt(...)`：用于当 `setupEntry`
+  只需要委托一个 `textInputs[*].shouldPrompt` 判断时
 
 ## 发布和安装
 
@@ -434,10 +477,10 @@ const setupSurface = createOptionalChannelSetupSurface({
 openclaw plugins install @myorg/openclaw-my-plugin
 ```
 
-OpenClaw 会先尝试 ClawHub，然后自动回退到 npm。你也可以显式强制使用 ClawHub：
+OpenClaw 会先尝试 ClawHub，并在失败后自动回退到 npm。你也可以显式强制使用 ClawHub：
 
 ```bash
-openclaw plugins install clawhub:@myorg/openclaw-my-plugin   # 仅 ClawHub
+openclaw plugins install clawhub:@myorg/openclaw-my-plugin   # ClawHub only
 ```
 
 没有对应的 `npm:` 覆盖方式。当你希望在 ClawHub 回退后走 npm 路径时，请使用普通的 npm 包 spec：
@@ -446,7 +489,7 @@ openclaw plugins install clawhub:@myorg/openclaw-my-plugin   # 仅 ClawHub
 openclaw plugins install @myorg/openclaw-my-plugin
 ```
 
-**仓库内插件：** 放在内置插件工作区树下，构建期间会自动发现。
+**仓库内插件：** 放在内置插件工作区目录树下，它们会在构建期间自动被发现。
 
 **用户可以安装：**
 
@@ -455,11 +498,14 @@ openclaw plugins install <package-name>
 ```
 
 <Info>
-  对于来自 npm 的安装，`openclaw plugins install` 会运行 `npm install --ignore-scripts`（不执行生命周期脚本）。请保持插件依赖树为纯 JS/TS，并避免使用需要 `postinstall` 构建的包。
+  对于来源于 npm 的安装，`openclaw plugins install` 会运行
+  `npm install --ignore-scripts`（不执行生命周期脚本）。请保持插件依赖树为纯 JS/TS，并避免使用需要 `postinstall` 构建的包。
 </Info>
 
+内置的 OpenClaw 自有插件是唯一的启动修复例外：当打包安装检测到某个插件因插件配置、旧版渠道配置或其内置默认启用清单而处于启用状态时，启动过程会在导入前为该插件安装缺失的运行时依赖。第三方插件不应依赖启动时安装；请继续使用显式的插件安装器。
+
 ## 相关内容
 
-- [SDK 概览](/zh-CN/plugins/sdk-entrypoints) -- `definePluginEntry` 和 `defineChannelPluginEntry`
-- [插件清单](/zh-CN/plugins/manifest) -- 完整的清单模式参考
-- [构建插件](/zh-CN/plugins/building-plugins) -- 分步式入门指南
+- [SDK 入口点](/zh-CN/plugins/sdk-entrypoints) -- `definePluginEntry` 和 `defineChannelPluginEntry`
+- [插件清单](/zh-CN/plugins/manifest) -- 完整清单模式参考
+- [构建插件](/zh-CN/plugins/building-plugins) -- 分步入门指南

docs/zh-CN/tools/plugin.md

@@ -1,23 +1,23 @@
 ---
 read_when:
     - 安装或配置插件
-    - 了解插件设备发现和加载规则
-    - 使用兼容 Codex / Claude 的插件 bundles
+    - 了解插件发现和加载规则
+    - 使用与 Codex/Claude 兼容的插件包
 sidebarTitle: Install and Configure
 summary: 安装、配置和管理 OpenClaw 插件
 title: 插件
 x-i18n:
-    generated_at: "2026-04-06T00:53:21Z"
+    generated_at: "2026-04-20T16:49:57Z"
     model: gpt-5.4
     provider: openai
-    source_hash: 9e2472a3023f3c1c6ee05b0cdc228f6b713cc226a08695b327de8a3ad6973c83
+    source_hash: a34995fe8a27b7c96fb2abd9ef55bea38ea7ba2ff4e867977683e09f799e9e8f
     source_path: tools/plugin.md
     workflow: 15
 ---
 
 # 插件
 
-插件可为 OpenClaw 扩展新能力：渠道、模型提供商、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是**核心**插件（随 OpenClaw 一起提供），其他则是**外部**插件（由社区发布到 npm）。
+插件可为 OpenClaw 扩展新能力：渠道、模型提供商、工具、Skills、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是**核心**插件（随 OpenClaw 一起提供），另一些是**外部**插件（由社区发布到 npm）。
 
 ## 快速开始
 
@@ -30,10 +30,10 @@ x-i18n:
 
   <Step title="安装插件">
     ```bash
-    # 从 npm
+    # 来自 npm
     openclaw plugins install @openclaw/voice-call
 
-    # 从本地目录或归档文件
+    # 来自本地目录或归档文件
     openclaw plugins install ./my-plugin
     openclaw plugins install ./my-plugin.tgz
     ```
@@ -50,7 +50,7 @@ x-i18n:
   </Step>
 </Steps>
 
-如果你更喜欢原生聊天控制，请启用 `commands.plugins: true` 并使用：
+如果你更喜欢使用聊天原生控制方式，请启用 `commands.plugins: true`，然后使用：
 
 ```text
 /plugin install clawhub:@openclaw/voice-call
@@ -58,35 +58,42 @@ x-i18n:
 /plugin enable voice-call
 ```
 
-安装路径使用与 CLI 相同的解析器：本地路径 / 归档文件、显式 `clawhub:<pkg>`，或裸包规范（先 ClawHub，再回退到 npm）。
+安装路径使用与 CLI 相同的解析器：本地路径/归档文件、显式 `clawhub:<pkg>`，或裸包规范（优先 ClawHub，然后回退到 npm）。
 
-如果配置无效，安装通常会以关闭失败的方式终止，并提示你使用 `openclaw doctor --fix`。唯一的恢复例外是为选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件提供的一条范围很窄的内置插件重装路径。
+如果配置无效，安装通常会以失败关闭的方式结束，并提示你使用
+`openclaw doctor --fix`。唯一的恢复例外，是针对选择启用
+`openclaw.install.allowInvalidConfigRecovery` 的插件所提供的一条受限的内置插件重装路径。
+
+打包分发的 OpenClaw 安装不会急切安装每个内置插件的全部运行时依赖树。
+当某个由 OpenClaw 拥有的内置插件因插件配置、旧版渠道配置或默认启用的清单而处于激活状态时，启动过程只会在导入该插件之前修复它所声明的运行时依赖。外部插件和自定义加载路径仍然必须通过
+`openclaw plugins install` 安装。
 
 ## 插件类型
 
 OpenClaw 可识别两种插件格式：
 
-| 格式       | 工作方式                                                         | 示例                                                   |
-| ---------- | ---------------------------------------------------------------- | ------------------------------------------------------ |
-| **原生**   | `openclaw.plugin.json` + 运行时模块；在进程内执行                | 官方插件、社区 npm 包                                  |
-| **Bundle** | 兼容 Codex / Claude / Cursor 的布局；映射到 OpenClaw 功能        | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
+| 格式 | 工作方式 | 示例 |
+| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
+| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
+| **Bundle** | 与 Codex/Claude/Cursor 兼容的布局；映射到 OpenClaw 功能 | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
 
-两者都会显示在 `openclaw plugins list` 中。有关 bundle 详情，请参见 [插件 Bundles](/zh-CN/plugins/bundles)。
+两者都会显示在 `openclaw plugins list` 中。有关 Bundle 的详细信息，请参阅 [插件包](/zh-CN/plugins/bundles)。
 
-如果你正在编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins) 和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。
+如果你正在编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins)
+和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。
 
 ## 官方插件
 
 ### 可安装（npm）
 
-| 插件             | 包                     | 文档                                 |
-| ---------------- | ---------------------- | ------------------------------------ |
-| Matrix           | `@openclaw/matrix`     | [Matrix](/zh-CN/channels/matrix)           |
-| Microsoft Teams  | `@openclaw/msteams`    | [Microsoft Teams](/zh-CN/channels/msteams) |
-| Nostr            | `@openclaw/nostr`      | [Nostr](/zh-CN/channels/nostr)             |
-| Voice Call       | `@openclaw/voice-call` | [Voice Call](/zh-CN/plugins/voice-call)    |
-| Zalo             | `@openclaw/zalo`       | [Zalo](/zh-CN/channels/zalo)               |
-| Zalo Personal    | `@openclaw/zalouser`   | [Zalo Personal](/zh-CN/plugins/zalouser)   |
+| 插件 | 包名 | 文档 |
+| --------------- | ---------------------- | ------------------------------------ |
+| Matrix          | `@openclaw/matrix`     | [Matrix](/zh-CN/channels/matrix)           |
+| Microsoft Teams | `@openclaw/msteams`    | [Microsoft Teams](/zh-CN/channels/msteams) |
+| Nostr           | `@openclaw/nostr`      | [Nostr](/zh-CN/channels/nostr)             |
+| Voice Call      | `@openclaw/voice-call` | [Voice Call](/zh-CN/plugins/voice-call)    |
+| Zalo            | `@openclaw/zalo`       | [Zalo](/zh-CN/channels/zalo)               |
+| Zalo Personal   | `@openclaw/zalouser`   | [Zalo Personal](/zh-CN/plugins/zalouser)   |
 
 ### 核心（随 OpenClaw 一起提供）
 
@@ -100,8 +107,8 @@ OpenClaw 可识别两种插件格式：
   </Accordion>
 
   <Accordion title="Memory 插件">
-    - `memory-core` — 内置内存搜索（默认通过 `plugins.slots.memory`）
-    - `memory-lancedb` — 按需安装的长期记忆，带自动召回 / 捕获（设置 `plugins.slots.memory = "memory-lancedb"`）
+    - `memory-core` — 内置的 Memory 搜索（默认通过 `plugins.slots.memory` 使用）
+    - `memory-lancedb` — 按需安装的长期 Memory，支持自动召回/捕获（设置 `plugins.slots.memory = "memory-lancedb"`）
   </Accordion>
 
   <Accordion title="语音提供商（默认启用）">
@@ -109,12 +116,12 @@ OpenClaw 可识别两种插件格式：
   </Accordion>
 
   <Accordion title="其他">
-    - `browser` — 用于 browser 工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、browser 运行时和默认 browser 控制服务的内置 browser 插件（默认启用；替换前请先禁用）
+    - `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时以及默认浏览器控制服务的内置浏览器插件（默认启用；在替换它之前请先禁用）
     - `copilot-proxy` — VS Code Copilot Proxy 桥接（默认禁用）
   </Accordion>
 </AccordionGroup>
 
-想找第三方插件？请参见 [社区插件](/zh-CN/plugins/community)。
+在找第三方插件？请参阅 [社区插件](/zh-CN/plugins/community)。
 
 ## 配置
 
@@ -132,26 +139,26 @@ OpenClaw 可识别两种插件格式：
 }
 ```
 
-| 字段             | 说明                                                      |
+| 字段 | 说明 |
 | ---------------- | --------------------------------------------------------- |
-| `enabled`        | 主开关（默认：`true`）                                    |
-| `allow`          | 插件允许列表（可选）                                      |
-| `deny`           | 插件拒绝列表（可选；拒绝优先）                            |
-| `load.paths`     | 额外的插件文件 / 目录                                     |
-| `slots`          | 独占槽位选择器（例如 `memory`、`contextEngine`）          |
-| `entries.\<id\>` | 每个插件的开关 + 配置                                     |
+| `enabled`        | 总开关（默认：`true`） |
+| `allow`          | 插件允许列表（可选） |
+| `deny`           | 插件拒绝列表（可选；拒绝优先） |
+| `load.paths`     | 额外的插件文件/目录 |
+| `slots`          | 独占插槽选择器（例如 `memory`、`contextEngine`） |
+| `entries.\<id\>` | 每个插件的开关 + 配置 |
 
-配置更改**需要重启 Gateway 网关**。如果 Gateway 网关以启用配置监视 + 进程内重启的方式运行（默认的 `openclaw gateway` 路径），则通常会在配置写入完成后稍等片刻自动执行该重启。
+配置变更**需要重启 Gateway 网关**。如果 Gateway 网关正在以启用了配置监听和进程内重启的方式运行（默认的 `openclaw gateway` 路径），那么配置写入落盘后，通常会在稍后自动执行该重启。
 
 <Accordion title="插件状态：已禁用 vs 缺失 vs 无效">
   - **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。
-  - **缺失**：配置引用了一个设备发现未找到的插件 id。
-  - **无效**：插件存在，但其配置不符合声明的 schema。
+  - **缺失**：配置引用了某个插件 id，但发现流程没有找到它。
+  - **无效**：插件存在，但其配置与声明的 schema 不匹配。
 </Accordion>
 
-## 设备发现与优先级
+## 发现与优先级
 
-OpenClaw 按以下顺序扫描插件（先匹配者优先）：
+OpenClaw 会按以下顺序扫描插件（先匹配到的优先）：
 
 <Steps>
   <Step title="配置路径">
@@ -167,23 +174,23 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）：
   </Step>
 
   <Step title="内置插件">
-    随 OpenClaw 一起提供。许多默认启用（模型提供商、语音等）。
-    其他则需要显式启用。
+    随 OpenClaw 一起提供。许多插件默认启用（模型提供商、语音）。
+    其他插件则需要显式启用。
   </Step>
 </Steps>
 
 ### 启用规则
 
 - `plugins.enabled: false` 会禁用所有插件
-- `plugins.deny` 总是优先于 allow
+- `plugins.deny` 始终优先于 allow
 - `plugins.entries.\<id\>.enabled: false` 会禁用该插件
-- 来源于工作区的插件**默认禁用**（必须显式启用）
+- 来自工作区的插件**默认禁用**（必须显式启用）
 - 内置插件遵循内建的默认启用集合，除非被覆盖
-- 独占槽位可强制启用该槽位中选定的插件
+- 独占插槽可以强制启用该插槽所选中的插件
 
-## 插件槽位（独占类别）
+## 插件插槽（独占类别）
 
-有些类别是独占的（同一时间只能激活一个）：
+某些类别是独占的（同一时间只能激活一个）：
 
 ```json5
 {
@@ -196,25 +203,25 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）：
 }
 ```
 
-| 槽位            | 控制内容         | 默认值              |
-| --------------- | ---------------- | ------------------- |
-| `memory`        | 活动 memory 插件 | `memory-core`       |
-| `contextEngine` | 活动上下文引擎   | `legacy`（内建）    |
+| 插槽 | 控制内容 | 默认值 |
+| --------------- | --------------------- | ------------------- |
+| `memory`        | 当前激活的 Memory 插件 | `memory-core`       |
+| `contextEngine` | 当前激活的上下文引擎 | `legacy`（内建） |
 
 ## CLI 参考
 
 ```bash
 openclaw plugins list                       # 紧凑清单
 openclaw plugins list --enabled            # 仅显示已加载插件
-openclaw plugins list --verbose            # 每个插件的详细行
+openclaw plugins list --verbose            # 每个插件的详细信息行
 openclaw plugins list --json               # 机器可读清单
 openclaw plugins inspect <id>              # 深度详情
 openclaw plugins inspect <id> --json       # 机器可读
-openclaw plugins inspect --all             # 全局表格
-openclaw plugins info <id>                 # inspect 别名
+openclaw plugins inspect --all             # 全量表格
+openclaw plugins info <id>                 # inspect 的别名
 openclaw plugins doctor                    # 诊断
 
-openclaw plugins install <package>         # 安装（先 ClawHub，再 npm）
+openclaw plugins install <package>         # 安装（优先 ClawHub，然后 npm）
 openclaw plugins install clawhub:<pkg>     # 仅从 ClawHub 安装
 openclaw plugins install <spec> --force    # 覆盖现有安装
 openclaw plugins install <path>            # 从本地路径安装
@@ -226,7 +233,7 @@ openclaw plugins install <spec> --dangerously-force-unsafe-install
 openclaw plugins update <id>             # 更新单个插件
 openclaw plugins update <id> --dangerously-force-unsafe-install
 openclaw plugins update --all            # 更新全部
-openclaw plugins uninstall <id>          # 删除配置 / 安装记录
+openclaw plugins uninstall <id>          # 删除配置/安装记录
 openclaw plugins uninstall <id> --keep-files
 openclaw plugins marketplace list <source>
 openclaw plugins marketplace list <source> --json
@@ -235,28 +242,31 @@ openclaw plugins enable <id>
 openclaw plugins disable <id>
 ```
 
-内置插件随 OpenClaw 一起提供。许多默认启用（例如内置模型提供商、内置语音提供商和内置 browser 插件）。其他内置插件仍然需要 `openclaw plugins enable <id>`。
+内置插件随 OpenClaw 一起提供。许多插件默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）。其他内置插件仍然需要执行 `openclaw plugins enable <id>`。
 
-`--force` 会就地覆盖现有已安装插件或 hook pack。
-它不支持与 `--link` 一起使用，因为 `--link` 会复用源路径，而不是复制到受管理的安装目标。
+`--force` 会原地覆盖已安装的现有插件或 hook 包。
+它不支持与 `--link` 一起使用，因为 `--link` 会复用源路径，而不是复制到受管安装目标中。
 
-`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。
+`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为
+marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。
 
-`--dangerously-force-unsafe-install` 是针对内置危险代码扫描器误报的紧急覆盖开关。它允许插件安装和插件更新在遇到内置 `critical` 发现后继续进行，但仍不会绕过插件 `before_install` 策略阻止或扫描失败阻止。
+`--dangerously-force-unsafe-install` 是一个应急覆盖选项，用于处理内置危险代码扫描器的误报。它允许插件安装和插件更新在遇到内置 `critical` 发现后继续进行，但它仍然不会绕过插件 `before_install` 策略阻止或扫描失败拦截。
 
-这个 CLI 标志仅适用于插件安装 / 更新流程。由 Gateway 网关驱动的 skill 依赖安装则使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是独立的 ClawHub skill 下载 / 安装流程。
+这个 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关驱动的 Skills 依赖安装则会改用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖参数，而 `openclaw skills install` 仍然是独立的 ClawHub Skills 下载/安装流程。
 
-兼容 bundles 会参与相同的插件列表 / 检查 / 启用 / 禁用流程。当前运行时支持包括 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。
+兼容的 Bundle 参与相同的插件 list/inspect/enable/disable 流程。当前运行时支持包括 Bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。
 
-`openclaw plugins inspect <id>` 还会报告检测到的 bundle 能力，以及由 bundle 支持或不支持的 MCP 和 LSP server 条目。
+`openclaw plugins inspect <id>` 还会报告已检测到的 Bundle 能力，以及由 Bundle 支持或不支持的 MCP 和 LSP server 条目。
 
-Marketplace 来源可以是来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、形如 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplaces，插件条目必须保留在克隆的 marketplace 仓库内，并且只能使用相对路径来源。
+Marketplace 来源可以是来自
+`~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或
+`marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保留在克隆得到的 marketplace 仓库内，并且只能使用相对路径来源。
 
-完整详情请参见 [`openclaw plugins` CLI 参考](/cli/plugins)。
+完整详情请参阅 [`openclaw plugins` CLI 参考](/cli/plugins)。
 
 ## 插件 API 概览
 
-原生插件会导出一个暴露 `register(api)` 的入口对象。较旧的插件仍可能使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。
+原生插件会导出一个入口对象，该对象暴露 `register(api)`。旧版插件仍可能继续使用 `activate(api)` 作为旧别名，但新插件应使用 `register`。
 
 ```typescript
 export default definePluginEntry({
@@ -276,45 +286,45 @@ export default definePluginEntry({
 });
 ```
 
-OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为较旧插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公共契约。
+OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为旧版插件回退到 `activate(api)`，但内置 Bundle 插件和新的外部插件都应将 `register` 视为公开契约。
 
-常见注册方法：
+常见的注册方法：
 
-| 方法                                    | 注册内容                    |
+| 方法 | 注册内容 |
 | --------------------------------------- | --------------------------- |
-| `registerProvider`                      | 模型提供商（LLM）           |
-| `registerChannel`                       | 聊天渠道                    |
-| `registerTool`                          | 智能体工具                  |
-| `registerHook` / `on(...)`              | 生命周期 hooks              |
-| `registerSpeechProvider`                | 文本转语音 / STT            |
-| `registerRealtimeTranscriptionProvider` | 流式 STT                    |
-| `registerRealtimeVoiceProvider`         | 双工实时语音                |
-| `registerMediaUnderstandingProvider`    | 图像 / 音频分析             |
-| `registerImageGenerationProvider`       | 图像生成                    |
-| `registerMusicGenerationProvider`       | 音乐生成                    |
-| `registerVideoGenerationProvider`       | 视频生成                    |
-| `registerWebFetchProvider`              | 网页抓取 / scrape 提供商    |
-| `registerWebSearchProvider`             | Web 搜索                    |
-| `registerHttpRoute`                     | HTTP 端点                   |
-| `registerCommand` / `registerCli`       | CLI 命令                    |
-| `registerContextEngine`                 | 上下文引擎                  |
-| `registerService`                       | 后台服务                    |
+| `registerProvider`                      | 模型提供商（LLM） |
+| `registerChannel`                       | 聊天渠道 |
+| `registerTool`                          | 智能体工具 |
+| `registerHook` / `on(...)`              | 生命周期 hook |
+| `registerSpeechProvider`                | 文本转语音 / STT |
+| `registerRealtimeTranscriptionProvider` | 流式 STT |
+| `registerRealtimeVoiceProvider`         | 双向实时语音 |
+| `registerMediaUnderstandingProvider`    | 图像/音频分析 |
+| `registerImageGenerationProvider`       | 图像生成 |
+| `registerMusicGenerationProvider`       | 音乐生成 |
+| `registerVideoGenerationProvider`       | 视频生成 |
+| `registerWebFetchProvider`              | 网页抓取 / 抓取提供商 |
+| `registerWebSearchProvider`             | 网页搜索 |
+| `registerHttpRoute`                     | HTTP 端点 |
+| `registerCommand` / `registerCli`       | CLI 命令 |
+| `registerContextEngine`                 | 上下文引擎 |
+| `registerService`                       | 后台服务 |
 
-类型化生命周期 hooks 的 hook 守卫行为：
+类型化生命周期 hook 的守卫行为：
 
-- `before_tool_call`：`{ block: true }` 是终止性的；较低优先级处理器会被跳过。
+- `before_tool_call`：`{ block: true }` 是终止性的；优先级更低的处理器会被跳过。
 - `before_tool_call`：`{ block: false }` 是空操作，不会清除更早的 block。
-- `before_install`：`{ block: true }` 是终止性的；较低优先级处理器会被跳过。
+- `before_install`：`{ block: true }` 是终止性的；优先级更低的处理器会被跳过。
 - `before_install`：`{ block: false }` 是空操作，不会清除更早的 block。
-- `message_sending`：`{ cancel: true }` 是终止性的；较低优先级处理器会被跳过。
+- `message_sending`：`{ cancel: true }` 是终止性的；优先级更低的处理器会被跳过。
 - `message_sending`：`{ cancel: false }` 是空操作，不会清除更早的 cancel。
 
-完整的类型化 hook 行为，请参见 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
+有关完整的类型化 hook 行为，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
 
 ## 相关内容
 
 - [构建插件](/zh-CN/plugins/building-plugins) — 创建你自己的插件
-- [插件 Bundles](/zh-CN/plugins/bundles) — Codex / Claude / Cursor bundle 兼容性
+- [插件包](/zh-CN/plugins/bundles) — Codex/Claude/Cursor Bundle 兼容性
 - [插件清单](/zh-CN/plugins/manifest) — 清单 schema
 - [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具
 - [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载流水线