From 86cf0e4bedc2774717eb1a5b252dc87bd95f65bf Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 2 May 2026 03:34:03 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/cli/doctor.md | 57 +++++++++++++------------ docs/zh-CN/install/migrating.md | 76 ++++++++++++++++++--------------- 2 files changed, 71 insertions(+), 62 deletions(-) diff --git a/docs/zh-CN/cli/doctor.md b/docs/zh-CN/cli/doctor.md index d069b677b..f055a1640 100644 --- a/docs/zh-CN/cli/doctor.md +++ b/docs/zh-CN/cli/doctor.md @@ -1,21 +1,21 @@ --- read_when: - - 你遇到连接或身份验证问题，并想要引导式修复 - - 你已更新并想做一次完整性检查 + - 你遇到连接/凭证问题，并想要引导式修复 + - 你更新后想做一次完整性检查 summary: '`openclaw doctor` 的 CLI 参考（健康检查 + 引导式修复）' title: Doctor x-i18n: - generated_at: "2026-05-01T21:49:48Z" + generated_at: "2026-05-02T03:33:33Z" model: gpt-5.5 provider: openai - source_hash: 8b15e5e5d062ae3e6f236775567b098d57ea6518171c0d45c78cab5b985e215e + source_hash: e861fa105737088eafa55815faa1a37ccd61e154e8dbe811cf4b988bc1c571e5 source_path: cli/doctor.md workflow: 16 --- # `openclaw doctor` -针对 Gateway 网关和渠道的健康检查 + 快速修复。 +用于 Gateway 网关和渠道的健康检查 + 快速修复。 相关： @@ -39,37 +39,38 @@ openclaw doctor --generate-gateway-token - `--repair`：不提示，应用推荐的非服务修复；Gateway 网关服务安装和重写仍需要交互式确认或显式 Gateway 网关命令 - `--fix`：`--repair` 的别名 - `--force`：应用激进修复，包括在需要时覆盖自定义服务配置 -- `--non-interactive`：不显示提示运行；仅执行安全迁移和非服务修复 +- `--non-interactive`：无提示运行；仅执行安全迁移和非服务修复 - `--generate-gateway-token`：生成并配置 Gateway 网关令牌 - `--deep`：扫描系统服务，查找额外的 Gateway 网关安装 -说明： +注意事项： -- 交互式提示（如钥匙串/OAuth 修复）只会在 stdin 是 TTY 且**未**设置 `--non-interactive` 时运行。无头运行（cron、Telegram、无终端）会跳过提示。 -- 性能：非交互式 `doctor` 运行会跳过预先加载插件，因此无头健康检查保持快速。交互式会话在检查需要插件参与时仍会完整加载插件。 +- 交互式提示（例如钥匙串/OAuth 修复）仅在 stdin 是 TTY 且**未**设置 `--non-interactive` 时运行。无头运行（cron、Telegram、无终端）会跳过提示。 +- 性能：非交互式 `doctor` 运行会跳过预先加载插件，因此无头健康检查能保持快速。交互式会话在检查需要插件贡献时仍会完整加载插件。 - `--fix`（`--repair` 的别名）会将备份写入 `~/.openclaw/openclaw.json.bak`，并删除未知配置键名，同时列出每一项删除。 -- `doctor --fix --non-interactive` 会报告缺失或过期的 Gateway 网关服务定义，但不会在更新修复模式之外安装或重写它们。服务缺失时运行 `openclaw gateway install`；如果你明确想替换启动器，则运行 `openclaw gateway install --force`。 -- 状态完整性检查现在会检测会话目录中的孤立转录文件。将它们归档为 `.deleted.` 需要交互式确认；`--fix`、`--yes` 和无头运行会将它们保留在原处。 -- Doctor 还会扫描 `~/.openclaw/cron/jobs.json`（或 `cron.store`）中的旧版 cron 任务形态，并可在调度器必须在运行时自动规范化它们之前原地重写。 -- 在 Linux 上，当用户的 crontab 仍运行旧版 `~/.openclaw/bin/ensure-whatsapp.sh` 时，Doctor 会发出警告；该脚本已不再维护，并且当 cron 缺少 systemd 用户总线环境时，可能记录错误的 WhatsApp Gateway 网关宕机。 -- Doctor 会清理旧版 OpenClaw 创建的旧版插件依赖暂存状态。当注册表能够解析已配置但缺失的可下载插件时，它也会修复这些插件。 -- Doctor 会通过从 `plugins.allow`/`plugins.entries` 中移除缺失的插件 ID 来修复过期的插件配置，并在插件发现健康时一并移除匹配的悬空渠道配置、Heartbeat 目标和渠道模型覆盖。 -- Doctor 会通过禁用受影响的 `plugins.entries.` 条目并移除其无效的 `config` 负载，来隔离无效插件配置。Gateway 网关启动时已经只会跳过该损坏插件，因此其他插件和渠道可以继续运行。 -- 当另一个监督器负责 Gateway 网关生命周期时，设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。Doctor 仍会报告 Gateway 网关/服务健康状态并应用非服务修复，但会跳过服务安装/启动/重启/引导以及旧版服务清理。 -- 在 Linux 上，Doctor 会忽略未激活的额外 Gateway 网关类 systemd 单元，并且在修复期间不会为正在运行的 systemd Gateway 网关服务重写命令/入口点元数据。如果你明确想替换活动启动器，请先停止服务，或使用 `openclaw gateway install --force`。 +- `doctor --fix --non-interactive` 会报告缺失或过期的 Gateway 网关服务定义，但不会在更新修复模式之外安装或重写它们。缺少服务时运行 `openclaw gateway install`；当你有意要替换启动器时，运行 `openclaw gateway install --force`。 +- 状态完整性检查现在会检测会话目录中的孤立转录文件。将它们归档为 `.deleted.` 需要交互式确认；`--fix`、`--yes` 和无头运行会让它们保留原位。 +- Doctor 还会扫描 `~/.openclaw/cron/jobs.json`（或 `cron.store`）中的旧版 cron 作业结构，并且可以在调度器必须在运行时自动规范化它们之前就地重写。 +- 在 Linux 上，当用户的 crontab 仍运行旧版 `~/.openclaw/bin/ensure-whatsapp.sh` 时，Doctor 会发出警告；该脚本已不再维护，并且当 cron 缺少 systemd 用户总线环境时，可能记录虚假的 WhatsApp Gateway 网关中断。 +- Doctor 会清理旧版 OpenClaw 创建的旧版插件依赖暂存状态。它还会在注册表能够解析已配置的可下载插件时，修复缺失的插件。 +- 当插件设备发现状态正常时，Doctor 会通过从 `plugins.allow`/`plugins.entries` 中移除缺失的插件 ID，并移除匹配的悬空渠道配置、Heartbeat 目标和渠道模型覆盖，来修复过期插件配置。 +- Doctor 会通过禁用受影响的 `plugins.entries.` 条目并移除其无效的 `config` 载荷，来隔离无效插件配置。Gateway 网关启动时本来就只会跳过这个坏插件，因此其他插件和渠道可以继续运行。 +- 当另一个 supervisor 拥有 Gateway 网关生命周期时，设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。Doctor 仍会报告 Gateway 网关/服务健康状况并应用非服务修复，但会跳过服务安装/启动/重启/bootstrap 和旧版服务清理。 +- 在 Linux 上，Doctor 会忽略非活动的额外类 Gateway 网关 systemd 单元，并且在修复期间不会重写正在运行的 systemd Gateway 网关服务的命令/入口点元数据。当你有意要替换活动启动器时，请先停止服务，或使用 `openclaw gateway install --force`。 - Doctor 会将旧版扁平 Talk 配置（`talk.voiceId`、`talk.modelId` 及相关项）自动迁移到 `talk.provider` + `talk.providers.`。 -- 重复运行 `doctor --fix` 时，如果唯一差异是对象键顺序，将不再报告/应用 Talk 规范化。 -- Doctor 包含记忆搜索就绪检查，并可在缺少嵌入凭证时建议运行 `openclaw configure --section model`。 -- 未配置命令所有者时，Doctor 会发出警告。命令所有者是获准运行仅所有者命令并批准危险操作的人类操作员账号。私信配对只允许某人与机器人对话；如果你在首次所有者引导存在之前批准过某个发送者，请显式设置 `commands.ownerAllowFrom`。 -- 当配置了 Codex 模式智能体，且操作员的 Codex 主目录中存在个人 Codex CLI 资产时，Doctor 会发出警告。本地 Codex 应用服务器启动使用隔离的逐智能体主目录，因此请使用 `openclaw migrate codex --dry-run` 清点应有意提升的资产。 -- 如果沙箱模式已启用但 Docker 不可用，Doctor 会报告高信号警告及修复方法（`install Docker` 或 `openclaw config set agents.defaults.sandbox.mode off`）。 -- 如果 `gateway.auth.token`/`gateway.auth.password` 由 SecretRef 管理且在当前命令路径中不可用，Doctor 会报告只读警告，并且不会写入明文回退凭证。 -- 如果在修复路径中检查渠道 SecretRef 失败，Doctor 会继续并报告警告，而不是提前退出。 -- Telegram `allowFrom` 用户名自动解析（`doctor --fix`）需要当前命令路径中有可解析的 Telegram 令牌。如果令牌检查不可用，Doctor 会报告警告，并在该次运行中跳过自动解析。 +- 当唯一差异是对象键顺序时，重复运行 `doctor --fix` 不再报告/应用 Talk 规范化。 +- Doctor 包含记忆搜索就绪性检查，并且可以在缺少嵌入凭证时建议运行 `openclaw configure --section model`。 +- 当未配置命令所有者时，Doctor 会发出警告。命令所有者是被允许运行仅限所有者命令并批准危险操作的人类操作员账号。私信配对只允许某人与机器人对话；如果你在首个所有者 bootstrap 存在之前批准过某个发送者，请显式设置 `commands.ownerAllowFrom`。 +- 当配置了 Codex 模式智能体，并且操作员的 Codex home 中存在个人 Codex CLI 资产时，Doctor 会发出警告。本地 Codex 应用服务器启动使用隔离的每智能体 home，因此请使用 `openclaw migrate codex --dry-run` 来清点应有意提升的资产。 +- 如果启用了沙箱模式但 Docker 不可用，Doctor 会报告带有修复建议（`install Docker` 或 `openclaw config set agents.defaults.sandbox.mode off`）的高信号警告。 +- 如果 `gateway.auth.token`/`gateway.auth.password` 由 SecretRef 管理，并且在当前命令路径中不可用，Doctor 会报告只读警告，并且不会写入明文回退凭证。 +- 如果在修复路径中检查渠道 SecretRef 失败，Doctor 会继续运行并报告警告，而不是提前退出。 +- 状态目录迁移后，当已启用的默认 Telegram 或 Discord 账号依赖环境回退，且 `TELEGRAM_BOT_TOKEN` 或 `DISCORD_BOT_TOKEN` 对 Doctor 进程不可用时，Doctor 会发出警告。 +- Telegram `allowFrom` 用户名自动解析（`doctor --fix`）需要当前命令路径中有可解析的 Telegram 令牌。如果令牌检查不可用，Doctor 会报告警告并跳过该轮自动解析。 ## macOS：`launchctl` 环境变量覆盖 -如果你之前运行过 `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（或 `...PASSWORD`），该值会覆盖你的配置文件，并可能导致持续的“unauthorized”错误。 +如果你之前运行过 `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（或 `...PASSWORD`），该值会覆盖你的配置文件，并可能导致持续的“未授权”错误。 ```bash launchctl getenv OPENCLAW_GATEWAY_TOKEN @@ -82,4 +83,4 @@ launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD ## 相关 - [CLI 参考](/zh-CN/cli) -- [Gateway 网关 Doctor](/zh-CN/gateway/doctor) +- [Gateway 网关 doctor](/zh-CN/gateway/doctor) diff --git a/docs/zh-CN/install/migrating.md b/docs/zh-CN/install/migrating.md index 8f8ea73df..c7ad9334a 100644 --- a/docs/zh-CN/install/migrating.md +++ b/docs/zh-CN/install/migrating.md @@ -1,55 +1,55 @@ --- read_when: - 你正在将 OpenClaw 迁移到新的笔记本电脑或服务器 - - 你正从另一个智能体系统迁移过来，并希望保留状态 - - 你正在升级一个就地安装的插件 + - 你来自另一个智能体系统，并希望保留状态 + - 你正在升级一个就地插件 summary: 迁移中心：跨系统导入、机器到机器迁移和插件升级 title: 迁移指南 x-i18n: - generated_at: "2026-04-27T10:59:33Z" - model: gpt-5.4 + generated_at: "2026-05-02T03:33:37Z" + model: gpt-5.5 provider: openai - source_hash: e2a1dc86ed367a0b92cdc0d5189123bb045d327be944516f564dac723f324c97 + source_hash: e447e38cf0086603a7b30ee5204e63cc8227ebc7a56add26d06ac2798a23e26f source_path: install/migrating.md - workflow: 15 + workflow: 16 --- -OpenClaw 支持三种迁移路径：从另一个智能体系统导入、将现有安装迁移到新机器，以及就地升级插件。 +OpenClaw 支持三种迁移路径：从另一个智能体系统导入、将现有安装移到新机器，以及就地升级插件。 ## 从另一个智能体系统导入 -使用内置迁移提供商将指令、MCP 服务器、Skills、模型配置以及（可选启用的）API 密钥导入到 OpenClaw。所有更改前都会先预览计划，报告中的敏感信息会被打码，应用操作则有经过验证的备份作为保障。 +使用内置迁移提供商将指令、MCP 服务器、Skills、模型配置和（可选）API 密钥导入 OpenClaw。任何更改前都会先预览计划，报告中会遮蔽密钥，应用更改时会有经过验证的备份作为支撑。 导入 Claude Code 和 Claude Desktop 状态，包括 `CLAUDE.md`、MCP 服务器、Skills 和项目命令。 - 导入 Hermes 配置、提供商、MCP 服务器、Memory、Skills 和受支持的 `.env` 键。 + 导入 Hermes 配置、提供商、MCP 服务器、记忆、Skills 和受支持的 `.env` 键。 -CLI 入口点是 [`openclaw migrate`](/zh-CN/cli/migrate)。当新手引导检测到已知来源时，也可以提供迁移选项（`openclaw onboard --flow import`）。 +CLI 入口点是 [`openclaw migrate`](/zh-CN/cli/migrate)。当新手引导检测到已知来源时，也可以提供迁移（`openclaw onboard --flow import`）。 -## 将 OpenClaw 迁移到新机器 +## 将 OpenClaw 移到新机器 -复制**状态目录**（默认为 `~/.openclaw/`）和你的**工作区**，以保留： +复制**状态目录**（默认是 `~/.openclaw/`）和你的**工作区**，以保留： - **配置** — `openclaw.json` 和所有 Gateway 网关设置。 -- **认证** — 每个智能体的 `auth-profiles.json`（API 密钥加 OAuth），以及 `credentials/` 下的所有渠道或提供商状态。 +- **凭证** — 每个智能体的 `auth-profiles.json`（API 密钥和 OAuth），以及 `credentials/` 下的任何渠道或提供商状态。 - **会话** — 对话历史和智能体状态。 -- **渠道状态** — WhatsApp 登录、Telegram 会话等。 +- **渠道状态** — WhatsApp 登录、Telegram 会话，以及类似内容。 - **工作区文件** — `MEMORY.md`、`USER.md`、Skills 和提示词。 -在旧机器上运行 `openclaw status` 以确认你的状态目录路径。自定义 profile 使用 `~/.openclaw-/`，或使用通过 `OPENCLAW_STATE_DIR` 设置的路径。 +在旧机器上运行 `openclaw status`，确认你的状态目录路径。自定义配置使用 `~/.openclaw-/`，或使用通过 `OPENCLAW_STATE_DIR` 设置的路径。 ### 迁移步骤 - 在**旧**机器上，停止 Gateway 网关，避免复制过程中文件发生变化，然后进行归档： + 在**旧**机器上停止 Gateway 网关，避免文件在复制过程中发生变化，然后归档： ```bash openclaw gateway stop @@ -57,28 +57,28 @@ CLI 入口点是 [`openclaw migrate`](/zh-CN/cli/migrate)。当新手引导检 tar -czf openclaw-state.tgz .openclaw ``` - 如果你使用多个 profile（例如 `~/.openclaw-work`），请分别归档每一个。 + 如果你使用多个配置（例如 `~/.openclaw-work`），请分别归档每一个。 - 在新机器上[安装](/zh-CN/install) CLI（如有需要也安装 Node）。即使新手引导创建了一个新的 `~/.openclaw/` 也没关系。下一步你会覆盖它。 + 在新机器上[安装](/zh-CN/install) CLI（如有需要也安装 Node）。如果新手引导创建了新的 `~/.openclaw/`，也没有问题。下一步会覆盖它。 - 通过 `scp`、`rsync -a` 或外部硬盘传输归档文件，然后解压： + 通过 `scp`、`rsync -a` 或外部硬盘传输归档，然后解压： ```bash cd ~ tar -xzf openclaw-state.tgz ``` - 确保已包含隐藏目录，并且文件所有权与将要运行 Gateway 网关的用户一致。 + 确保隐藏目录已包含在内，并且文件所有权与将运行 Gateway 网关的用户一致。 - 在新机器上，运行 [Doctor](/zh-CN/gateway/doctor) 以应用配置迁移并修复服务： + 在新机器上运行 [Doctor](/zh-CN/gateway/doctor)，应用配置迁移并修复服务： ```bash openclaw doctor @@ -89,48 +89,56 @@ CLI 入口点是 [`openclaw migrate`](/zh-CN/cli/migrate)。当新手引导检 +如果 Telegram 或 Discord 使用默认环境变量回退（`TELEGRAM_BOT_TOKEN` 或 `DISCORD_BOT_TOKEN`），请验证迁移后的状态目录 `.env` 是否包含这些键，同时不要打印密钥值： + +```bash +awk -F= '/^(TELEGRAM_BOT_TOKEN|DISCORD_BOT_TOKEN)=/ { print $1 "=present" }' ~/.openclaw/.env +``` + +当已启用的默认 Telegram 或 Discord 账号没有配置令牌，并且 Doctor 进程无法使用匹配的环境变量时，`openclaw doctor` 也会发出警告。 + ### 常见陷阱 - - 如果旧 Gateway 网关使用了 `--profile` 或 `OPENCLAW_STATE_DIR`，而新机器没有使用，那么渠道看起来会像是已登出，会话也会为空。请使用你迁移过来的**相同** profile 或状态目录启动 Gateway 网关，然后重新运行 `openclaw doctor`。 + + 如果旧 Gateway 网关使用了 `--profile` 或 `OPENCLAW_STATE_DIR`，而新的没有使用，渠道会显示为已登出，会话也会为空。用你迁移的**同一个**配置或状态目录启动 Gateway 网关，然后重新运行 `openclaw doctor`。 - 仅有配置文件是不够的。模型认证配置文件位于 `agents//agent/auth-profiles.json`，而渠道和提供商状态位于 `credentials/` 下。始终迁移**整个**状态目录。 + 仅配置文件还不够。模型凭证配置文件位于 `agents//agent/auth-profiles.json` 下，渠道和提供商状态位于 `credentials/` 下。请始终迁移**整个**状态目录。 - 如果你以 root 身份复制，或切换了用户，Gateway 网关可能无法读取凭证。请确保状态目录和工作区归运行 Gateway 网关的用户所有。 + 如果你以 root 身份复制，或切换了用户，Gateway 网关可能无法读取凭证。确保状态目录和工作区归运行 Gateway 网关的用户所有。 - 如果你的 UI 指向的是**远程** Gateway 网关，那么会话和工作区都由远程主机持有。你应迁移 Gateway 网关主机本身，而不是本地笔记本。参见 [常见问题](/zh-CN/help/faq#where-things-live-on-disk)。 + 如果你的 UI 指向**远程** Gateway 网关，会话和工作区归远程主机所有。迁移 Gateway 网关主机本身，而不是你的本地笔记本电脑。参见[常见问题](/zh-CN/help/faq#where-things-live-on-disk)。 - - 状态目录包含认证配置文件、渠道凭证和其他提供商状态。请使用加密方式存储备份，避免通过不安全的传输渠道传送；如果你怀疑发生泄露，请轮换密钥。 + + 状态目录包含凭证配置文件、渠道凭证和其他提供商状态。请加密存储备份，避免使用不安全的传输渠道；如果你怀疑发生暴露，请轮换密钥。 ### 验证清单 -在新机器上，确认： +在新机器上确认： - [ ] `openclaw status` 显示 Gateway 网关正在运行。 - [ ] 渠道仍保持连接（无需重新配对）。 -- [ ] 仪表板能够打开并显示现有会话。 -- [ ] 工作区文件（Memory、配置）都存在。 +- [ ] 仪表盘可以打开，并显示现有会话。 +- [ ] 工作区文件（记忆、配置）存在。 ## 就地升级插件 -就地插件升级会保留相同的插件 id 和配置键，但可能会将磁盘上的状态迁移到当前布局。插件专属升级指南与其对应渠道文档放在一起： +就地插件升级会保留相同的插件 ID 和配置键，但可能会把磁盘上的状态移入当前布局。插件专属升级指南与其渠道放在一起： - [Matrix 迁移](/zh-CN/channels/matrix-migration)：加密状态恢复限制、自动快照行为和手动恢复命令。 ## 相关内容 - [`openclaw migrate`](/zh-CN/cli/migrate)：跨系统导入的 CLI 参考。 -- [安装概览](/zh-CN/install)：所有安装方式。 +- [安装概览](/zh-CN/install)：所有安装方法。 - [Doctor](/zh-CN/gateway/doctor)：迁移后的健康检查。 -- [卸载](/zh-CN/install/uninstall)：干净移除 OpenClaw。 +- [卸载](/zh-CN/install/uninstall)：干净地移除 OpenClaw。