diff --git a/docs/zh-CN/cli/config.md b/docs/zh-CN/cli/config.md index 75bbb7e97..990ce257c 100644 --- a/docs/zh-CN/cli/config.md +++ b/docs/zh-CN/cli/config.md @@ -2,23 +2,23 @@ read_when: - 你想以非交互方式读取或编辑配置 sidebarTitle: Config -summary: 用于 `openclaw config` 的 CLI 参考（get/set/patch/unset/file/schema/validate） +summary: '`openclaw config` 的 CLI 参考（get/set/patch/unset/file/schema/validate）' title: 配置 x-i18n: - generated_at: "2026-04-29T21:05:38Z" + generated_at: "2026-05-03T17:10:53Z" model: gpt-5.5 provider: openai - source_hash: f1f55c4b932d469cb9112d9f55b66f0ff88dbe066250651df7a0a753060a223d + source_hash: 7be6a2ff8474fe78deb1d32dd822a4cf8a2b420dfb45306be5d7c5a1d54f0b4d source_path: cli/config.md workflow: 16 --- -配置辅助工具用于在 `openclaw.json` 中进行非交互式编辑：按路径 get/set/patch/unset/file/schema/validate 值，并打印当前活动的配置文件。不带子命令运行会打开配置向导（等同于 `openclaw configure`）。 +用于对 `openclaw.json` 进行非交互式编辑的配置辅助命令：按路径获取、设置、修补、取消设置、查看文件、查看 schema、验证值，并打印活动配置文件。不带子命令运行时会打开配置向导（等同于 `openclaw configure`）。 ## 根选项 - 当你不带子命令运行 `openclaw config` 时，可重复使用的引导式设置分区过滤器。 + 当你不带子命令运行 `openclaw config` 时，可重复使用的引导式设置分区筛选器。 支持的引导式分区：`workspace`、`model`、`web`、`gateway`、`daemon`、`channels`、`plugins`、`skills`、`health`。 @@ -50,17 +50,17 @@ openclaw config validate --json 将为 `openclaw.json` 生成的 JSON schema 以 JSON 形式打印到 stdout。 - - - 当前根配置 schema，加上用于编辑器工具的根 `$schema` 字符串字段。 + + - 当前根配置 schema，并附带用于编辑器工具的根 `$schema` 字符串字段。 - Control UI 使用的字段 `title` 和 `description` 文档元数据。 - - 当存在匹配的字段文档时，嵌套对象、通配符（`*`）和数组项（`[]`）节点会继承相同的 `title` / `description` 元数据。 - - 当存在匹配的字段文档时，`anyOf` / `oneOf` / `allOf` 分支也会继承相同的文档元数据。 - - 当可以加载运行时 manifest 时，尽力提供实时插件 + 渠道 schema 元数据。 - - 即使当前配置无效，也会提供干净的回退 schema。 + - 嵌套对象、通配符（`*`）和数组项（`[]`）节点在存在匹配字段文档时，会继承相同的 `title` / `description` 元数据。 + - `anyOf` / `oneOf` / `allOf` 分支在存在匹配字段文档时，也会继承相同的文档元数据。 + - 在能够加载运行时清单时，提供尽力而为的实时插件 + 渠道 schema 元数据。 + - 即使当前配置无效，也会提供一个干净的回退 schema。 - - `config.schema.lookup` 返回一个规范化配置路径，包含一个浅层 schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界）、匹配的 UI 提示元数据，以及直接子项摘要。可在 Control UI 或自定义客户端中用于按路径深入查看。 + + `config.schema.lookup` 返回一个规范化配置路径，并带有浅层 schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界）、匹配的 UI 提示元数据，以及直接子项摘要。可将它用于 Control UI 或自定义客户端中的按路径钻取。 @@ -68,7 +68,7 @@ openclaw config validate --json openclaw config schema ``` -当你想用其他工具检查或验证它时，可以通过管道写入文件： +当你想用其他工具检查或验证它时，可以将其管道输出到文件： ```bash openclaw config schema > openclaw.schema.json @@ -76,7 +76,7 @@ openclaw config schema > openclaw.schema.json ### 路径 -路径使用点号或括号表示法： +路径使用点号或方括号表示法： ```bash openclaw config get agents.defaults.workspace @@ -92,7 +92,7 @@ openclaw config set agents.list[1].tools.exec.node "node-id-or-name" ## 值 -值会尽可能按 JSON5 解析；否则会被视为字符串。使用 `--strict-json` 要求必须按 JSON5 解析。`--json` 仍作为旧版别名受支持。 +值会在可能时按 JSON5 解析；否则会被视为字符串。使用 `--strict-json` 要求必须按 JSON5 解析。`--json` 仍作为旧版别名受到支持。 ```bash openclaw config set agents.defaults.heartbeat.every "0m" @@ -100,10 +100,10 @@ openclaw config set gateway.port 19001 --strict-json openclaw config set channels.whatsapp.groups '["*"]' --strict-json ``` -`config get --json` 会将原始值以 JSON 打印，而不是打印终端格式化文本。 +`config get --json` 会以 JSON 打印原始值，而不是终端格式化文本。 -默认情况下，对象赋值会替换目标路径。常用于保存用户新增条目的受保护 map/list 路径，例如 `agents.defaults.models`、`models.providers`、`models.providers..models`、`plugins.entries` 和 `auth.profiles`，会拒绝可能移除现有条目的替换，除非你传入 `--replace`。 +默认情况下，对象赋值会替换目标路径。常用于保存用户添加条目的受保护映射/列表路径，例如 `agents.defaults.models`、`models.providers`、`models.providers..models`、`plugins.entries` 和 `auth.profiles`，会拒绝移除现有条目的替换，除非你传入 `--replace`。 向这些映射添加条目时使用 `--merge`： @@ -113,19 +113,19 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge ``` -只有当你明确希望提供的值成为完整目标值时，才使用 `--replace`。 +仅在你有意让提供的值成为完整目标值时，才使用 `--replace`。 ## `config set` 模式 -`openclaw config set` 支持四种赋值方式： +`openclaw config set` 支持四种赋值样式： - + ```bash openclaw config set ``` - + ```bash openclaw config set channels.discord.token \ --ref-provider default \ @@ -133,7 +133,7 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll --ref-id DISCORD_BOT_TOKEN ``` - + 提供商构建器模式仅面向 `secrets.providers.` 路径： ```bash @@ -146,7 +146,7 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll ``` - + ```bash openclaw config set --batch-json '[ { @@ -168,28 +168,28 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll -SecretRef 赋值会在不支持运行时可变的表面上被拒绝（例如 `hooks.token`、`commands.ownerDisplaySecret`、Discord 线程绑定 webhook 令牌，以及 WhatsApp 凭证 JSON）。参见 [SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface)。 +SecretRef 赋值会在不支持的运行时可变表面上被拒绝（例如 `hooks.token`、`commands.ownerDisplaySecret`、Discord 线程绑定 webhook token，以及 WhatsApp 凭证 JSON）。请参阅 [SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface)。 -批量解析始终使用批量载荷（`--batch-json`/`--batch-file`）作为事实来源。`--strict-json` / `--json` 不会改变批量解析行为。 +批处理解析始终以批处理载荷（`--batch-json`/`--batch-file`）为事实来源。`--strict-json` / `--json` 不会改变批处理解析行为。 ## `config patch` -当你想粘贴或通过管道传入一个配置形状的补丁，而不是运行许多基于路径的 `config set` 命令时，使用 `config patch`。输入是一个 JSON5 对象。对象会递归合并，数组和标量值会替换目标值，`null` 会删除目标路径。 +当你想粘贴或管道传入配置形状的补丁，而不是运行许多基于路径的 `config set` 命令时，请使用 `config patch`。输入是一个 JSON5 对象。对象会递归合并，数组和标量值会替换目标值，而 `null` 会删除目标路径。 ```bash openclaw config patch --file ./openclaw.patch.json5 --dry-run openclaw config patch --file ./openclaw.patch.json5 ``` -你也可以通过 stdin 传入补丁，这对远程设置脚本很有用： +你也可以通过 stdin 管道传入补丁，这对远程设置脚本很有用： ```bash ssh openclaw-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5 ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5 ``` -示例补丁： +补丁示例： ```json5 { @@ -221,15 +221,15 @@ ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5 } ``` -当某个对象或数组必须精确变为提供的值，而不是被递归补丁处理时，使用 `--replace-path `： +当某个对象或数组必须精确变成提供的值，而不是被递归修补时，使用 `--replace-path `： ```bash openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels' ``` -`--dry-run` 会在不写入的情况下运行 schema 和 SecretRef 可解析性检查。默认情况下，dry-run 期间会跳过基于 exec 的 SecretRefs；当你明确希望 dry-run 执行提供商命令时，添加 `--allow-exec`。 +`--dry-run` 会运行 schema 和 SecretRef 可解析性检查，而不写入。默认情况下，dry-run 期间会跳过 exec 支持的 SecretRef；当你有意让 dry-run 执行提供商命令时，添加 `--allow-exec`。 -JSON 路径/值模式仍然同时支持 SecretRefs 和提供商： +JSON 路径/值模式仍同时支持 SecretRef 和提供商： ```bash openclaw config set channels.discord.token \ @@ -246,24 +246,24 @@ openclaw config set secrets.providers.vaultfile \ 提供商构建器目标必须使用 `secrets.providers.` 作为路径。 - + - `--provider-source ` - `--provider-timeout-ms `（`file`、`exec`） - + - `--provider-allowlist `（可重复） - - - `--provider-path `（必需） + + - `--provider-path `（必填） - `--provider-mode ` - `--provider-max-bytes ` - `--provider-allow-insecure-path` - - - `--provider-command `（必需） + + - `--provider-command `（必填） - `--provider-arg `（可重复） - `--provider-no-output-timeout-ms ` - `--provider-max-output-bytes ` @@ -277,7 +277,7 @@ openclaw config set secrets.providers.vaultfile \ -加固的 exec 提供商示例： +加固后的 exec 提供商示例： ```bash openclaw config set secrets.providers.vault \ @@ -293,7 +293,7 @@ openclaw config set secrets.providers.vault \ ## Dry run -使用 `--dry-run` 在不写入 `openclaw.json` 的情况下验证更改。 +使用 `--dry-run` 验证更改，而不写入 `openclaw.json`。 ```bash openclaw config set channels.discord.token \ @@ -318,22 +318,22 @@ openclaw config set channels.discord.token \ ``` - - - 构建器模式：对已更改的 refs/providers 运行 SecretRef 可解析性检查。 - - JSON 模式（`--strict-json`、`--json` 或批量模式）：运行 schema 验证以及 SecretRef 可解析性检查。 + + - 构建器模式：对已更改的 ref/提供商运行 SecretRef 可解析性检查。 + - JSON 模式（`--strict-json`、`--json` 或批处理模式）：运行 schema 验证以及 SecretRef 可解析性检查。 - 策略验证也会针对已知不支持的 SecretRef 目标表面运行。 - - 策略检查会评估完整的更改后配置，因此父对象写入（例如将 `hooks` 设置为对象）无法绕过不支持表面的验证。 - - dry-run 期间默认跳过 exec SecretRef 检查，以避免命令副作用。 - - 将 `--allow-exec` 与 `--dry-run` 一起使用可选择启用 exec SecretRef 检查（这可能会执行提供商命令）。 - - `--allow-exec` 仅用于 dry-run；如果不与 `--dry-run` 一起使用会报错。 + - 策略检查会评估完整的变更后配置，因此父对象写入（例如将 `hooks` 设置为对象）无法绕过不支持表面的验证。 + - 默认情况下，dry-run 期间会跳过 exec SecretRef 检查，以避免命令副作用。 + - 将 `--allow-exec` 与 `--dry-run` 搭配使用，以选择启用 exec SecretRef 检查（这可能会执行提供商命令）。 + - `--allow-exec` 仅适用于 dry-run；如果不带 `--dry-run` 使用会报错。 - - `--dry-run --json` 会打印机器可读报告： + + `--dry-run --json` 会打印一份机器可读报告： - `ok`：dry-run 是否通过 - `operations`：已评估的赋值数量 - - `checks`：是否运行了 schema/可解析性检查 + - `checks`：schema/可解析性检查是否已运行 - `checks.resolvabilityComplete`：可解析性检查是否运行完成（跳过 exec refs 时为 false） - `refsChecked`：dry-run 期间实际解析的 refs 数量 - `skippedExecRefs`：由于未设置 `--allow-exec` 而跳过的 exec refs 数量 @@ -413,11 +413,11 @@ openclaw config set channels.discord.token \ - - `config schema validation failed`：变更后的配置结构无效；修正路径/值或提供商/ref 对象结构。 - - `Config policy validation failed: unsupported SecretRef usage`：将该凭证移回明文/字符串输入，并仅在受支持的表面使用 SecretRefs。 - - `SecretRef assignment(s) could not be resolved`：当前无法解析引用的提供商/ref（缺少环境变量、文件指针无效、exec 提供商失败，或提供商/来源不匹配）。 - - `Dry run note: skipped exec SecretRef resolvability check(s)`：dry-run 跳过了 exec 引用；如果你需要 exec 可解析性验证，请使用 `--allow-exec` 重新运行。 - - 对于批处理模式，请修复失败条目，并在写入前重新运行 `--dry-run`。 + - `config schema validation failed`：你的变更后配置形状无效；请修正路径/值或提供商/ref 对象形状。 + - `Config policy validation failed: unsupported SecretRef usage`：将该凭证移回明文/字符串输入，并只在受支持的表面使用 SecretRefs。 + - `SecretRef assignment(s) could not be resolved`：当前无法解析引用的提供商/ref（缺少环境变量、文件指针无效、exec 提供商失败，或提供商/source 不匹配）。 + - `Dry run note: skipped exec SecretRef resolvability check(s)`：dry-run 跳过了 exec refs；如果你需要 exec 可解析性验证，请使用 `--allow-exec` 重新运行。 + - 对于批处理模式，请修正失败条目，并在写入前重新运行 `--dry-run`。 @@ -430,7 +430,7 @@ openclaw config set channels.discord.token \ 活动配置路径必须是普通文件。写入不支持符号链接的 `openclaw.json` 布局；请改用 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。 -小幅编辑优先使用 CLI 写入： +小改动优先使用 CLI 写入： ```bash openclaw config set gateway.reload.mode hybrid --dry-run @@ -438,7 +438,7 @@ openclaw config set gateway.reload.mode hybrid openclaw config validate ``` -如果写入被拒绝，请检查保存的载荷并修复完整配置结构： +如果写入被拒绝，请检查保存的载荷并修正完整配置形状： ```bash CONFIG="$(openclaw config file)" @@ -446,9 +446,9 @@ ls -lt "$CONFIG".rejected.* 2>/dev/null | head openclaw config validate ``` -仍然允许直接用编辑器写入，但运行中的 Gateway 网关会在它们通过验证前将其视为不可信。无效的直接编辑可能会在启动或热重载期间从最后已知良好的备份恢复。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。 +仍然允许直接用编辑器写入，但运行中的 Gateway 网关会在它们通过验证之前将其视为不可信。无效的直接编辑会导致启动失败，或被热重载跳过；Gateway 网关不会重写 `openclaw.json`。运行 `openclaw doctor --fix` 来修复带前缀/被覆盖的配置，或恢复最后一次已知可用的副本。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-rejected-invalid-config)。 -整文件恢复仅用于全局损坏的配置，例如解析错误、根级 schema 失败、旧版迁移失败，或插件与根配置同时失败。如果验证仅在 `plugins.entries....` 下失败，OpenClaw 会保留活动的 `openclaw.json`，并报告插件本地问题，而不是恢复 `.last-good`。这可以防止插件 schema 变更或 `minHostVersion` 偏差回滚无关的用户设置，例如模型、提供商、认证配置文件、渠道、Gateway 网关暴露、工具、内存、浏览器或 cron 配置。 +整文件恢复仅保留给 Doctor 修复。插件 schema 变更或 `minHostVersion` 偏差会保持显式报错，而不是回滚不相关的用户设置，例如模型、提供商、认证配置文件、渠道、Gateway 网关暴露、工具、记忆、浏览器或 cron 配置。 ## 子命令 @@ -458,14 +458,14 @@ openclaw config validate ## 验证 -在不启动 Gateway 网关的情况下，根据活动 schema 验证当前配置。 +在不启动 Gateway 网关的情况下，针对活动 schema 验证当前配置。 ```bash openclaw config validate openclaw config validate --json ``` -`openclaw config validate` 通过后，你可以使用本地 TUI，让嵌入式智能体在同一个终端中验证每项变更时，对照文档比较活动配置： +`openclaw config validate` 通过后，你可以使用本地 TUI，让嵌入式智能体在你从同一个终端验证每项更改时，将活动配置与文档进行比较： 如果验证已经失败，请从 `openclaw configure` 或 `openclaw doctor --fix` 开始。`openclaw chat` 不会绕过无效配置保护。 @@ -475,7 +475,7 @@ openclaw config validate --json openclaw chat ``` -然后在 TUI 中： +然后在 TUI 内： ```text !openclaw config file @@ -494,10 +494,10 @@ openclaw chat 使用 `openclaw config set` 或 `openclaw configure` 应用定向编辑。 - 每次变更后重新运行 `openclaw config validate`。 + 每次更改后重新运行 `openclaw config validate`。 - - 如果验证通过但运行时仍不健康，请运行 `openclaw doctor` 或 `openclaw doctor --fix` 获取迁移与修复帮助。 + + 如果验证通过但运行时仍不健康，请运行 `openclaw doctor` 或 `openclaw doctor --fix` 获取迁移和修复帮助。 diff --git a/docs/zh-CN/cli/plugins.md b/docs/zh-CN/cli/plugins.md index 7945b1ef0..6fae48b73 100644 --- a/docs/zh-CN/cli/plugins.md +++ b/docs/zh-CN/cli/plugins.md @@ -1,20 +1,20 @@ --- read_when: - - 你想安装或管理 Gateway 网关插件或兼容包 - - 你想调试插件加载失败 + - 你想安装或管理 Gateway 网关插件或兼容捆绑包 + - 你想调试插件加载失败问题 sidebarTitle: Plugins -summary: 适用于 `openclaw plugins` 的 CLI 参考（list、install、marketplace、uninstall、enable/disable、doctor） +summary: '`openclaw plugins` 的 CLI 参考（list、install、marketplace、uninstall、enable/disable、doctor）' title: 插件 x-i18n: - generated_at: "2026-05-02T21:57:47Z" + generated_at: "2026-05-03T17:11:00Z" model: gpt-5.5 provider: openai - source_hash: 3b077ab0739e2453ccba434aa3b02b1d441bab792b7b131216221a8048d551cd + source_hash: f6ae613e39535ea20f9cf3dd451f110ae1b14de4586bdbe3d55d06d8e7cfd2cf source_path: cli/plugins.md workflow: 16 --- -管理 Gateway 网关插件、钩子包和兼容包。 +管理 Gateway 网关插件、钩子包和兼容捆绑包。 @@ -23,13 +23,13 @@ x-i18n: 安装、列出、更新、卸载和发布的快速示例。 - - 包兼容性模型。 + + 捆绑包兼容性模型。 清单字段和配置架构。 - + 插件安装的安全加固。 @@ -62,14 +62,16 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -如需调查安装、检查、卸载或注册表刷新速度慢的问题，请使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 运行该命令。跟踪会将阶段耗时写入 stderr，并保持 JSON 输出可解析。参见 [调试](/zh-CN/help/debugging#plugin-lifecycle-trace)。 +如果要排查安装、检查、卸载或注册表刷新缓慢的问题，请使用 +`OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 运行该命令。跟踪信息会将阶段耗时写入 +stderr，并保持 JSON 输出可解析。参见[调试](/zh-CN/help/debugging#plugin-lifecycle-trace)。 -内置插件随 OpenClaw 一起发布。有些默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）；其他插件需要 `plugins enable`。 +内置插件随 OpenClaw 一起提供。其中一些默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）；其他插件需要使用 `plugins enable`。 -原生 OpenClaw 插件必须随附 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空）。兼容包改用它们自己的包清单。 +原生 OpenClaw 插件必须随附 `openclaw.plugin.json`，并包含内联 JSON Schema（`configSchema`，即使为空）。兼容捆绑包则使用自己的捆绑包清单。 -`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细列表/info 输出还会显示包子类型（`codex`、`claude` 或 `cursor`）以及检测到的包能力。 +`plugins list` 会显示 `Format: openclaw` 或 `Format: bundle`。详细列表/info 输出还会显示捆绑包子类型（`codex`、`claude` 或 `cursor`）以及检测到的捆绑包能力。 ### 安装 @@ -91,100 +93,108 @@ openclaw plugins install --marketplace https://github.com// -在发布切换期间，裸包名默认从 npm 安装。对 ClawHub 使用 `clawhub:`。请像运行代码一样对待插件安装。优先使用固定版本。 +在发布切换期间，裸包名默认从 npm 安装。ClawHub 请使用 `clawhub:`。请像运行代码一样对待插件安装。优先使用固定版本。 -`plugins search` 会查询 ClawHub 中可安装的插件包，并打印可直接安装的包名。它搜索代码插件和包插件包，而不是 Skills。使用 `openclaw skills search` 搜索 ClawHub Skills。 +`plugins search` 会查询 ClawHub 中可安装的插件包，并打印 +可直接用于安装的包名。它会搜索代码插件和捆绑包插件包， +不搜索 Skills。对于 ClawHub Skills，请使用 `openclaw skills search`。 -ClawHub 是大多数插件的主要分发和设备发现界面。Npm 仍是受支持的回退和直接安装路径。OpenClaw 拥有的 `@openclaw/*` 插件包已再次发布到 npm；请在 [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) 或 [插件清单](/zh-CN/plugins/plugin-inventory) 查看当前列表。稳定安装使用 `latest`。Beta 渠道安装和更新会优先使用 npm `beta` dist-tag（如果该标签可用），然后回退到 `latest`。 +ClawHub 是大多数插件的主要分发和发现入口。Npm +仍然是受支持的回退和直接安装路径。OpenClaw 拥有的 +`@openclaw/*` 插件包已重新发布到 npm；请在 +[npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) 或 +[插件清单](/zh-CN/plugins/plugin-inventory)查看当前列表。稳定安装使用 `latest`。 +Beta 渠道安装和更新在 npm `beta` dist-tag 可用时会优先使用该标签， +然后回退到 `latest`。 - - 如果你的 `plugins` 部分由单文件 `$include` 支持，`plugins install/update/enable/disable/uninstall` 会写入该包含文件，并保持 `openclaw.json` 不变。根 include、include 数组以及带有同级覆盖的 include 会失败关闭，而不是被扁平化。有关支持的形状，请参见 [配置 include](/zh-CN/gateway/configuration)。 + + 如果你的 `plugins` 部分由单文件 `$include` 支持，`plugins install/update/enable/disable/uninstall` 会写入该包含文件，并保持 `openclaw.json` 不变。根 include、include 数组以及带有同级覆盖项的 include 会关闭失败，而不是被展平。有关支持的形状，请参见[配置 include](/zh-CN/gateway/configuration)。 - 如果安装期间配置无效，`plugins install` 通常会失败关闭，并提示你先运行 `openclaw doctor --fix`。在 Gateway 网关启动期间，单个插件的无效配置会隔离到该插件，因此其他渠道和插件可以继续运行；`openclaw doctor --fix` 可以隔离无效插件条目。唯一有文档记录的安装时例外，是面向显式选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件的窄范围内置插件恢复路径。 + 如果安装期间配置无效，`plugins install` 通常会关闭失败，并提示你先运行 `openclaw doctor --fix`。在 Gateway 网关启动和热重载期间，无效插件配置会像任何其他无效配置一样关闭失败；`openclaw doctor --fix` 可以隔离无效的插件条目。唯一记录在案的安装时例外，是一个范围很窄的内置插件恢复路径，仅适用于显式选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。 - - `--force` 会复用现有安装目标，并原地覆盖已安装的插件或钩子包。当你有意从新的本地路径、归档、ClawHub 包或 npm 构件重新安装同一 id 时使用它。对于已跟踪 npm 插件的常规升级，优先使用 `openclaw plugins update `。 + + `--force` 会复用现有安装目标，并就地覆盖已安装的插件或钩子包。当你有意从新的本地路径、归档、ClawHub 包或 npm 构件重新安装同一 id 时使用它。对于已跟踪的 npm 插件的常规升级，请优先使用 `openclaw plugins update `。 - 如果你对已安装的插件 id 运行 `plugins install`，OpenClaw 会停止并指引你使用 `plugins update ` 进行正常升级，或者在确实想从不同来源覆盖当前安装时使用 `plugins install --force`。 + 如果你对已经安装的插件 id 运行 `plugins install`，OpenClaw 会停止并引导你使用 `plugins update ` 进行正常升级，或者在你确实想从不同来源覆盖当前安装时使用 `plugins install --force`。 - - `--pin` 仅适用于 npm 安装。它不支持 `git:` 安装；当你想要固定来源时，请使用显式 git ref，例如 `git:github.com/acme/plugin@v1.2.3`。它不支持 `--marketplace`，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。 + + `--pin` 仅适用于 npm 安装。它不支持 `git:` 安装；如果你想固定来源，请使用显式 git ref，例如 `git:github.com/acme/plugin@v1.2.3`。它不支持 `--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 网关支持的 skill 依赖安装使用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是单独的 ClawHub skill 下载/安装流程。 - 如果你发布到 ClawHub 的插件被注册表扫描阻止，请使用 [ClawHub](/zh-CN/tools/clawhub) 中的发布者步骤。 + 如果你在 ClawHub 上发布的插件被注册表扫描阻止，请使用 [ClawHub](/zh-CN/tools/clawhub) 中的发布者步骤。 - - `plugins install` 也是安装在 `package.json` 中暴露 `openclaw.hooks` 的钩子包的入口。使用 `openclaw hooks` 查看筛选后的钩子可见性并启用单个钩子，而不是安装包。 + + `plugins install` 也是安装钩子包的入口，这些钩子包会在 `package.json` 中暴露 `openclaw.hooks`。请使用 `openclaw hooks` 查看筛选后的钩子可见性并启用单个钩子，而不是用于包安装。 - Npm specs **仅限注册表**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file specs 和 semver 范围会被拒绝。依赖安装以项目本地方式运行，并出于安全原因使用 `--ignore-scripts`，即使你的 shell 配有全局 npm 安装设置也是如此。 + Npm spec **仅限注册表**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围会被拒绝。为了安全，即使你的 shell 设置了全局 npm 安装设置，依赖安装也会在项目本地使用 `--ignore-scripts` 运行。 - 当你想明确使用 npm 解析时，请使用 `npm:`。在发布切换期间，裸包 specs 也会直接从 npm 安装。 + 当你想明确使用 npm 解析时，请使用 `npm:`。在发布切换期间，裸包 spec 也会直接从 npm 安装。 - 裸 specs 和 `@latest` 会保持在稳定轨道上。如果 npm 将其中任一解析为预发布版，OpenClaw 会停止并要求你使用预发布标签（例如 `@beta`/`@rc`）或精确预发布版本（例如 `@1.2.3-beta.4`）显式选择加入。 + 裸 spec 和 `@latest` 会保持在稳定轨道。如果 npm 将其中任何一个解析为预发布版本，OpenClaw 会停止并要求你使用预发布标签（例如 `@beta`/`@rc`）或精确预发布版本（例如 `@1.2.3-beta.4`）显式选择加入。 - 如果裸安装 spec 匹配官方插件 id（例如 `diffs`），OpenClaw 会直接安装目录条目。要安装同名 npm 包，请使用显式 scoped spec（例如 `@scope/diffs`）。 + 如果裸安装 spec 匹配官方插件 id（例如 `diffs`），OpenClaw 会直接安装目录条目。若要安装同名 npm 包，请使用显式 scoped spec（例如 `@scope/diffs`）。 - 使用 `git:` 直接从 git 仓库安装。支持的形式包括 `git:github.com/owner/repo`、`git:owner/repo`、完整 `https://`、`ssh://`、`git://`、`file://` 以及 `git@host:owner/repo.git` 克隆 URL。添加 `@` 或 `#` 可在安装前检出分支、标签或提交。 + 使用 `git:` 可直接从 git 仓库安装。支持的形式包括 `git:github.com/owner/repo`、`git:owner/repo`、完整的 `https://`、`ssh://`、`git://`、`file://` 以及 `git@host:owner/repo.git` 克隆 URL。添加 `@` 或 `#` 可在安装前检出分支、标签或提交。 - Git 安装会克隆到临时目录，在存在请求的 ref 时检出它，然后使用正常的插件目录安装器。这意味着清单验证、危险代码扫描、包管理器安装工作和安装记录的行为都类似 npm 安装。记录的 git 安装会包含来源 URL/ref 以及解析后的提交，因此 `openclaw plugins update` 稍后可以重新解析来源。 + Git 安装会克隆到临时目录，在存在请求的 ref 时检出它，然后使用正常的插件目录安装器。这意味着清单验证、危险代码扫描、包管理器安装工作和安装记录的行为都与 npm 安装类似。记录的 git 安装包含来源 URL/ref 以及解析后的提交，因此 `openclaw plugins update` 以后可以重新解析该来源。 - 从 git 安装后，使用 `openclaw plugins inspect --runtime --json` 验证运行时注册项，例如 gateway 方法和 CLI 命令。如果插件使用 `api.registerCli` 注册了 CLI 根命令，请直接通过 OpenClaw 根 CLI 执行该命令，例如 `openclaw demo-plugin ping`。 + 从 git 安装后，请使用 `openclaw plugins inspect --runtime --json` 验证运行时注册项，例如 gateway 方法和 CLI 命令。如果插件使用 `api.registerCli` 注册了 CLI 根命令，请直接通过 OpenClaw 根 CLI 执行该命令，例如 `openclaw demo-plugin ping`。 支持的归档：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw 插件归档必须在解压后的插件根目录包含有效的 `openclaw.plugin.json`；只包含 `package.json` 的归档会在 OpenClaw 写入安装记录前被拒绝。 - Claude marketplace 安装也受支持。 + 也支持 Claude marketplace 安装。 -ClawHub 安装使用显式 `clawhub:` 定位器： +ClawHub 安装使用显式 `clawhub:` 定位符： ```bash openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -在发布切换期间，裸 npm 安全插件 specs 默认从 npm 安装： +在发布切换期间，裸 npm 安全插件 spec 默认从 npm 安装： ```bash openclaw plugins install openclaw-codex-app-server ``` -使用 `npm:` 明确仅使用 npm 解析： +使用 `npm:` 以明确仅使用 npm 解析： ```bash openclaw plugins install npm:openclaw-codex-app-server openclaw plugins install npm:@scope/plugin-name@1.0.1 ``` -OpenClaw 会在安装前检查宣告的插件 API / 最低 gateway 兼容性。当选定的 ClawHub 版本发布 ClawPack 构件时，OpenClaw 会下载带版本的 npm-pack `.tgz`，验证 ClawHub 摘要标头和构件摘要，然后通过正常归档路径安装。没有 ClawPack 元数据的较旧 ClawHub 版本仍会通过旧版包归档验证路径安装。记录的安装会保留其 ClawHub 来源元数据、构件类型、npm integrity、npm shasum、tarball 名称和 ClawPack 摘要信息，以便后续更新。 -未指定版本的 ClawHub 安装会保留未指定版本的记录 spec，因此 `openclaw plugins update` 可以跟随后续 ClawHub 版本；显式版本或标签选择器（例如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）仍固定到该选择器。 +OpenClaw 会在安装前检查声明的插件 API / 最低 gateway 兼容性。当选定的 ClawHub 版本发布了 ClawPack 构件时，OpenClaw 会下载带版本的 npm-pack `.tgz`，验证 ClawHub 摘要标头和构件摘要，然后通过正常归档路径安装它。没有 ClawPack 元数据的旧版 ClawHub 版本仍会通过旧版包归档验证路径安装。记录的安装会保留其 ClawHub 来源元数据、构件类型、npm integrity、npm shasum、tarball 名称和 ClawPack 摘要事实，以供后续更新使用。 +未指定版本的 ClawHub 安装会保留未指定版本的记录 spec，以便 `openclaw plugins update` 可以跟随后续的 ClawHub 版本；显式版本或标签选择器（例如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）仍会固定到该选择器。 #### Marketplace 简写 -当 marketplace 名称存在于 Claude 位于 `~/.claude/plugins/known_marketplaces.json` 的本地注册表缓存中时，使用 `plugin@marketplace` 简写： +当 Claude 的本地注册表缓存在 `~/.claude/plugins/known_marketplaces.json` 中存在 marketplace 名称时，使用 `plugin@marketplace` 简写： ```bash openclaw plugins marketplace list openclaw plugins install @ ``` -当你想显式传递 marketplace 来源时，使用 `--marketplace`： +当你想显式传入 marketplace 来源时，请使用 `--marketplace`： ```bash openclaw plugins install --marketplace @@ -194,31 +204,31 @@ openclaw plugins install --marketplace ./my-marketplace ``` - - - `~/.claude/plugins/known_marketplaces.json` 中 Claude 已知的 marketplace 名称 + + - 来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称 - 本地 marketplace 根目录或 `marketplace.json` 路径 - - GitHub 仓库简写，例如 `owner/repo` - - GitHub 仓库 URL，例如 `https://github.com/owner/repo` + - GitHub repo 简写，例如 `owner/repo` + - GitHub repo URL，例如 `https://github.com/owner/repo` - git URL - - 对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保留在克隆的 marketplace 仓库内。OpenClaw 接受来自该仓库的相对路径来源，并拒绝远程清单中的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径插件来源。 + + 对于从 GitHub 或 git 加载的远程 marketplace，插件条目必须保留在克隆的 marketplace repo 内。OpenClaw 接受来自该 repo 的相对路径源，并拒绝远程清单中的 HTTP(S)、绝对路径、git、GitHub 和其他非路径插件源。 对于本地路径和归档文件，OpenClaw 会自动检测： - 原生 OpenClaw 插件（`openclaw.plugin.json`） -- 兼容 Codex 的 bundle（`.codex-plugin/plugin.json`） -- 兼容 Claude 的 bundle（`.claude-plugin/plugin.json` 或默认 Claude 组件布局） -- 兼容 Cursor 的 bundle（`.cursor-plugin/plugin.json`） +- Codex 兼容包（`.codex-plugin/plugin.json`） +- Claude 兼容包（`.claude-plugin/plugin.json` 或默认 Claude 组件布局） +- Cursor 兼容包（`.cursor-plugin/plugin.json`） -兼容 bundle 会安装到普通插件根目录，并参与相同的列表/信息/启用/禁用流程。目前支持 bundle Skills、Claude 命令 Skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor 命令 Skills，以及兼容的 Codex hook 目录；其他检测到的 bundle 能力会显示在诊断/信息中，但尚未接入运行时执行。 +兼容包会安装到常规插件根目录，并参与相同的列表/信息/启用/禁用流程。目前支持包 Skills、Claude 命令 Skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor 命令 Skills，以及兼容的 Codex 钩子目录；其他检测到的包能力会显示在诊断/信息中，但尚未接入运行时执行。 -### 列出 +### 列表 ```bash openclaw plugins list @@ -234,46 +244,56 @@ openclaw plugins search --json 仅显示已启用的插件。 - 从表格视图切换为按插件显示的详情行，包含来源/origin/版本/激活元数据。 + 从表格视图切换为每个插件一行的详细信息，包含源/来源/版本/激活元数据。 机器可读的清单，以及注册表诊断和包依赖安装状态。 -`plugins list` 会先读取持久化的本地插件注册表；当注册表缺失或无效时，会回退到仅从清单派生的结果。它适合用于检查插件是否已安装、已启用，并且对冷启动规划可见，但它不是对已运行 Gateway 网关进程的实时运行时探测。更改插件代码、启用状态、hook 策略或 `plugins.load.paths` 后，需要重启为该渠道提供服务的 Gateway 网关，之后新的 `register(api)` 代码或 hook 才会运行。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不仅是包装器进程。 +`plugins list` 会先读取持久化的本地插件注册表；当注册表缺失或无效时，会回退到仅由清单派生的结果。它适合用来检查某个插件是否已安装、已启用，并且对冷启动规划可见，但它不是对已运行 Gateway 网关进程的实时运行时探测。修改插件代码、启用状态、钩子策略或 `plugins.load.paths` 后，请重启服务于该渠道的 Gateway 网关，再预期新的 `register(api)` 代码或钩子会运行。对于远程/容器部署，请确认你重启的是实际的 `openclaw gateway run` 子进程，而不只是包装器进程。 `plugins list --json` 包含每个插件来自 `package.json` -`dependencies` 和 `optionalDependencies` 的 `dependencyStatus`。OpenClaw 会检查这些包名是否存在于插件正常的 Node `node_modules` 查找路径中；它不会导入插件运行时代码、运行包管理器，也不会修复缺失的依赖。 +`dependencies` 和 `optionalDependencies` 的 `dependencyStatus`。OpenClaw 会检查这些包 +名称是否存在于插件常规 Node `node_modules` 查找路径上；它 +不会导入插件运行时代码、运行包管理器，或修复缺失的 +依赖。 -`plugins search` 是远程 ClawHub 目录查询。它不会检查本地状态、修改配置、安装包或加载插件运行时代码。搜索结果包含 ClawHub 包名、族、渠道、版本、摘要，以及类似 `openclaw plugins install clawhub:` 的安装提示。 +`plugins search` 是远程 ClawHub 目录查询。它不会检查本地 +状态、修改配置、安装包，或加载插件运行时代码。搜索 +结果包含 ClawHub 包名、系列、渠道、版本、摘要，以及 +安装提示，例如 `openclaw plugins install clawhub:`。 -在打包的 Docker 镜像内处理内置插件时，将插件源码目录绑定挂载到匹配的打包源码路径上，例如 `/app/extensions/synology-chat`。OpenClaw 会先发现这个已挂载的源码覆盖层，再发现 `/app/dist/extensions/synology-chat`；单纯复制的源码目录保持不生效，因此普通打包安装仍会使用已编译的 dist。 +在打包 Docker 镜像内处理内置插件时，将插件 +源目录 bind-mount 到匹配的打包源路径上，例如 +`/app/extensions/synology-chat`。OpenClaw 会先于 `/app/dist/extensions/synology-chat` 发现该挂载的源 +覆盖层；普通复制的源 +目录仍然不会生效，因此常规打包安装仍会使用已编译的 dist。 -对于运行时 hook 调试： +用于运行时钩子调试： -- `openclaw plugins inspect --runtime --json` 会显示一次已加载模块检查过程中注册的 hook 和诊断。运行时检查绝不会安装依赖；请使用 `openclaw doctor --fix` 清理旧版依赖状态，或安装缺失的已配置可下载插件。 -- `openclaw gateway status --deep --require-rpc` 会确认可达的 Gateway 网关、服务/进程提示、配置路径和 RPC 健康状态。 -- 非内置会话 hook（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）需要 `plugins.entries..hooks.allowConversationAccess=true`。 +- `openclaw plugins inspect --runtime --json` 会显示一次模块加载检查过程中注册的钩子和诊断。运行时检查绝不会安装依赖；使用 `openclaw doctor --fix` 清理旧版依赖状态，或安装缺失的已配置可下载插件。 +- `openclaw gateway status --deep --require-rpc` 确认可达的 Gateway 网关、服务/进程提示、配置路径和 RPC 健康状态。 +- 非内置会话钩子（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）需要 `plugins.entries..hooks.allowConversationAccess=true`。 -使用 `--link` 以避免复制本地目录（会添加到 `plugins.load.paths`）： +使用 `--link` 避免复制本地目录（会添加到 `plugins.load.paths`）： ```bash openclaw plugins install -l ./my-plugin ``` -`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源码路径，而不是覆盖托管安装目标。 +`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是复制覆盖托管安装目标。 -在 npm 安装中使用 `--pin`，可将解析后的精确 spec（`name@version`）保存到托管插件索引中，同时保持默认行为不固定版本。 +在 npm 安装中使用 `--pin`，可将解析后的精确规格（`name@version`）保存到托管插件索引中，同时默认行为仍保持不固定。 ### 插件索引 -插件安装元数据是机器管理的状态，而不是用户配置。安装和更新会把它写入活跃 OpenClaw 状态目录下的 `plugins/installs.json`。其顶层 `installRecords` 映射是安装元数据的持久来源，包括清单损坏或缺失的插件记录。`plugins` 数组是从清单派生的冷注册表缓存。该文件包含请勿编辑警告，并被 `openclaw plugins update`、卸载、诊断和冷插件注册表使用。 +插件安装元数据是机器管理的状态，不是用户配置。安装和更新会把它写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。它的顶层 `installRecords` 映射是安装元数据的持久来源，包括损坏或缺失插件清单的记录。`plugins` 数组是由清单派生的冷注册表缓存。该文件包含“请勿编辑”警告，并由 `openclaw plugins update`、卸载、诊断和冷插件注册表使用。 -当 OpenClaw 在配置中看到随版本交付的旧版 `plugins.installs` 记录时，会将它们迁移到插件索引并删除该配置键；如果任一写入失败，则会保留配置记录，以免安装元数据丢失。 +当 OpenClaw 在配置中看到已发布的旧版 `plugins.installs` 记录时，会将其移动到插件索引并移除该配置键；如果任一写入失败，会保留配置记录，以免安装元数据丢失。 ### 卸载 @@ -283,10 +303,10 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` 会从 `plugins.entries`、持久化插件索引、插件允许/拒绝列表条目，以及适用时链接的 `plugins.load.paths` 条目中删除插件记录。除非设置了 `--keep-files`，否则卸载还会删除被跟踪的托管安装目录，前提是它位于 OpenClaw 的插件 extensions 根目录内。对于主动记忆插件，记忆槽位会重置为 `memory-core`。 +`uninstall` 会在适用时从 `plugins.entries`、持久化插件索引、插件允许/拒绝列表条目，以及已链接的 `plugins.load.paths` 条目中移除插件记录。除非设置了 `--keep-files`，卸载还会移除被跟踪的托管安装目录，前提是它位于 OpenClaw 的插件扩展根目录内。对于主动记忆插件，记忆插槽会重置为 `memory-core`。 -`--keep-config` 作为 `--keep-files` 的已弃用别名受支持。 +`--keep-config` 作为 `--keep-files` 的已弃用别名仍受支持。 ### 更新 @@ -299,29 +319,29 @@ openclaw plugins update @openclaw/voice-call openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` -更新会应用到托管插件索引中被跟踪的插件安装，以及 `hooks.internal.installs` 中被跟踪的 hook-pack 安装。 +更新适用于托管插件索引中被跟踪的插件安装，以及 `hooks.internal.installs` 中被跟踪的 hook-pack 安装。 - - 当你传入插件 ID 时，OpenClaw 会复用该插件记录的安装 spec。这意味着之前存储的 dist-tag（例如 `@beta`）和精确固定版本，会在后续 `update ` 运行中继续使用。 + + 当你传入插件 id 时，OpenClaw 会复用该插件记录的安装规格。这意味着先前存储的 dist-tag（例如 `@beta`）和精确固定版本，会在之后的 `update ` 运行中继续使用。 - 对于 npm 安装，你也可以传入带 dist-tag 或精确版本的显式 npm 包 spec。OpenClaw 会将该包名解析回被跟踪的插件记录，更新该已安装插件，并记录新的 npm spec 供未来基于 ID 的更新使用。 + 对于 npm 安装，你也可以传入带 dist-tag 或精确版本的显式 npm 包规格。OpenClaw 会将该包名解析回被跟踪的插件记录，更新该已安装插件，并记录新的 npm 规格，供后续基于 id 的更新使用。 - 传入不带版本或 tag 的 npm 包名也会解析回被跟踪的插件记录。当某个插件固定到了精确版本，而你希望将其移回注册表的默认发布线时，请使用这种方式。 + 传入不带版本或标签的 npm 包名也会解析回被跟踪的插件记录。当某个插件被固定到精确版本，而你想将其移回注册表默认发布线时，请使用这种方式。 - - 除非你传入新的 spec，否则 `openclaw plugins update` 会复用被跟踪的插件 spec。`openclaw update` 还知道当前活跃的 OpenClaw 更新渠道：在 beta 渠道上，默认线 npm 和 ClawHub 插件记录会先尝试 `@beta`，如果不存在插件 beta 版本，再回退到记录的 default/latest spec。精确版本和显式 tag 会继续固定到该选择器。 + + `openclaw plugins update` 会复用被跟踪的插件规格，除非你传入新规格。`openclaw update` 还知道当前激活的 OpenClaw 更新渠道：在 beta 渠道上，默认线 npm 和 ClawHub 插件记录会先尝试 `@beta`，如果不存在插件 beta 版本，再回退到记录的默认/latest 规格。精确版本和显式标签会保持固定到该选择器。 - - 在执行实时 npm 更新之前，OpenClaw 会根据 npm 注册表元数据检查已安装的包版本。如果已安装版本和记录的工件身份已经与解析出的目标匹配，则会跳过更新，不下载、不重新安装，也不重写 `openclaw.json`。 + + 在实时 npm 更新之前，OpenClaw 会根据 npm 注册表元数据检查已安装包版本。如果已安装版本和记录的构件身份已经与解析出的目标匹配，则会跳过更新，不会下载、重新安装或重写 `openclaw.json`。 - 当存在已存储的完整性哈希且获取到的工件哈希发生变化时，OpenClaw 会将其视为 npm 工件漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。非交互式更新助手会默认失败关闭，除非调用方提供显式继续策略。 + 当存在已存储的完整性哈希且获取到的构件哈希发生变化时，OpenClaw 会将其视为 npm 构件漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续之前请求确认。非交互式更新助手默认关闭失败，除非调用方提供显式的继续策略。 - - `--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的应急覆盖开关。它仍然不会绕过插件 `before_install` 策略阻断或扫描失败阻断，并且只适用于插件更新，不适用于 hook-pack 更新。 + + `--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的紧急覆盖。它仍然不会绕过插件 `before_install` 策略阻断或扫描失败阻断，并且只适用于插件更新，不适用于 hook-pack 更新。 @@ -333,21 +353,21 @@ openclaw plugins inspect --runtime openclaw plugins inspect --json ``` -默认情况下，Inspect 会显示身份、加载状态、来源、清单能力、策略标志、诊断、安装元数据、bundle 能力，以及任何检测到的 MCP 或 LSP 服务器支持，而不导入插件运行时。添加 `--runtime` 会加载插件模块，并包含已注册的 hook、工具、命令、服务、gateway 方法和 HTTP 路由。运行时检查会直接报告缺失的插件依赖；安装和修复仍由 `openclaw plugins install`、`openclaw plugins update` 和 `openclaw doctor --fix` 处理。 +默认情况下，检查会在不导入插件运行时的情况下，显示身份、加载状态、来源、清单能力、策略标志、诊断、安装元数据、包能力，以及任何检测到的 MCP 或 LSP 服务器支持。添加 `--runtime` 会加载插件模块，并包含已注册的钩子、工具、命令、服务、gateway 方法和 HTTP 路由。运行时检查会直接报告缺失的插件依赖；安装和修复仍在 `openclaw plugins install`、`openclaw plugins update` 和 `openclaw doctor --fix` 中处理。 -插件拥有的 CLI 命令会作为根 `openclaw` 命令组安装。`inspect --runtime` 在 `cliCommands` 下显示命令后，将其作为 `openclaw ...` 运行；例如，注册了 `demo-git` 的插件可以用 `openclaw demo-git ping` 验证。 +插件自有 CLI 命令会作为根 `openclaw` 命令组安装。`inspect --runtime` 在 `cliCommands` 下显示命令后，请以 `openclaw ...` 形式运行；例如，注册 `demo-git` 的插件可以用 `openclaw demo-git ping` 验证。 -每个插件会根据其在运行时实际注册的内容分类： +每个插件都会根据其在运行时实际注册的内容分类： -- **plain-capability** — 一种能力类型（例如仅提供商插件） +- **plain-capability** — 一种能力类型（例如仅 provider 的插件） - **hybrid-capability** — 多种能力类型（例如文本 + 语音 + 图像） -- **hook-only** — 只有 hook，没有能力或表面 +- **hook-only** — 只有钩子，没有能力或 surface - **non-capability** — 有工具/命令/服务，但没有能力 -关于能力模型的更多信息，请参阅 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。 +有关能力模型的更多信息，请参见 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。 -`--json` 标志会输出适合脚本处理和审计的机器可读报告。`inspect --all` 会呈现全局表格，包含形态、能力种类、兼容性提示、bundle 能力和 hook 摘要列。`info` 是 `inspect` 的别名。 +`--json` 标志会输出适合脚本和审计的机器可读报告。`inspect --all` 会渲染一个全量表格，包含形态、能力种类、兼容性通知、包能力和钩子摘要列。`info` 是 `inspect` 的别名。 ### Doctor @@ -356,9 +376,9 @@ openclaw plugins inspect --json openclaw plugins doctor ``` -`doctor` 会报告插件加载错误、清单/发现诊断和兼容性提示。当一切正常时，它会打印 `No plugin issues detected.` +`doctor` 会报告插件加载错误、清单/发现诊断，以及兼容性通知。当一切正常时，它会打印 `No plugin issues detected.` -对于缺少 `register`/`activate` 导出等模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以在诊断输出中包含紧凑的导出形态摘要。 +对于缺失 `register`/`activate` 导出等模块形态失败，请用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以便在诊断输出中包含紧凑的导出形态摘要。 ### 注册表 @@ -368,22 +388,22 @@ openclaw plugins registry --refresh openclaw plugins registry --json ``` -本地插件注册表是 OpenClaw 对已安装插件身份、启用状态、来源元数据和贡献归属的持久化冷读模型。普通启动、提供商 owner 查找、渠道设置分类和插件清单可以读取它，而无需导入插件运行时模块。 +本地插件注册表是 OpenClaw 为已安装插件身份、启用状态、来源元数据和贡献归属持久化的冷读模型。常规启动、提供商所有者查找、渠道设置分类和插件清单都可以读取它，而无需导入插件运行时模块。 -使用 `plugins registry` 检查持久化注册表是否存在、是否当前有效或是否陈旧。使用 `--refresh` 可基于持久化插件索引、配置策略和清单/包元数据重建它。这是修复路径，不是运行时激活路径。 +使用 `plugins registry` 检查持久化注册表是否存在、是否当前有效或是否过期。使用 `--refresh` 可根据持久化插件索引、配置策略和清单/包元数据重建它。这是修复路径，不是运行时激活路径。 -`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是一个已弃用的紧急兼容开关，用于插件注册表读取失败。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；环境变量回退仅用于迁移逐步推出期间的紧急启动恢复。 +`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是一个已弃用的紧急兼容性开关，用于处理注册表读取失败。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；环境变量回退仅用于迁移逐步推出期间的紧急启动恢复。 -### 市场 +### 插件市场 ```bash openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -市场列表接受本地市场路径、`marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。`--json` 会打印解析后的来源标签，以及解析出的市场清单和插件条目。 +插件市场列表接受本地市场路径、`marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL 或 git URL。`--json` 会打印解析后的来源标签，以及解析后的市场清单和插件条目。 ## 相关内容 diff --git a/docs/zh-CN/concepts/mantis.md b/docs/zh-CN/concepts/mantis.md index 3b0db3724..f1933efb3 100644 --- a/docs/zh-CN/concepts/mantis.md +++ b/docs/zh-CN/concepts/mantis.md @@ -1,65 +1,65 @@ --- read_when: - - 针对 OpenClaw 缺陷构建或运行实时视觉 QA + - 为 OpenClaw 缺陷构建或运行实时视觉质量检查 - 为拉取请求添加前后验证 - 添加 Discord、Slack、WhatsApp 或其他实时传输场景 - 调试需要截图、浏览器自动化或 VNC 访问的 QA 运行 -summary: Mantis 是用于在实时传输协议上复现 OpenClaw 缺陷、捕获前后证据，并将工件附加到拉取请求的可视化端到端验证系统。 +summary: Mantis 是一个可视化端到端验证系统，用于在实时传输通道上复现 OpenClaw 缺陷、捕获修复前后的证据，并将工件附加到拉取请求中。 title: Mantis x-i18n: - generated_at: "2026-05-03T16:48:53Z" + generated_at: "2026-05-03T17:11:15Z" model: gpt-5.5 provider: openai - source_hash: 5b58934ec88a640745f7430c875c377e898f87f1b3d4a9ef03115395084664f5 + source_hash: 2a038872d2754b380a0983d81869de247d66c41b49746e1608dca215ab2096a7 source_path: concepts/mantis.md workflow: 16 --- -Mantis 是 OpenClaw 的端到端验证系统，适用于需要真实运行时、真实传输协议和可见证明的缺陷。它会针对已知有问题的 ref 运行一个场景并捕获证据，再针对候选 ref 运行相同场景，然后将对比结果发布为构件，维护者可以从 PR 或本地命令中检查这些构件。 +Mantis 是 OpenClaw 端到端验证系统，用于需要真实运行时、真实传输协议和可见证据的 bug。它会在一个已知有问题的 ref 上运行场景，捕获证据，再在候选 ref 上运行同一场景，并将对比结果发布为构件，维护者可以从 PR 或本地命令中检查这些构件。 -Mantis 从 Discord 开始，因为 Discord 为我们提供了一条高价值的首个通道：真实机器人凭证、真实公会渠道、回应、线程、原生命令，以及人类可以直观确认传输协议展示内容的浏览器 UI。 +Mantis 从 Discord 开始，因为 Discord 为我们提供了一条高价值的第一条验证通道：真实 bot 凭证、真实 guild 渠道、回应、线程、原生命令，以及一个浏览器 UI，便于人工直观看到传输协议展示的内容。 ## 目标 -- 使用用户看到的相同传输形态，从 GitHub 问题或 PR 中复现缺陷。 -- 在应用修复之前，在基线 ref 上捕获一个 **before** 构件。 -- 在应用修复之后，在候选 ref 上捕获一个 **after** 构件。 -- 尽可能使用确定性的判定器，例如 Discord REST 回应读取或渠道转录检查。 -- 当缺陷有可见 UI 表面时捕获截图。 +- 使用用户看到的同一种传输协议形态，从 GitHub issue 或 PR 中复现 bug。 +- 在应用修复前，在基线 ref 上捕获一个 **before** 构件。 +- 在应用修复后，在候选 ref 上捕获一个 **after** 构件。 +- 尽可能使用确定性的判定器，例如 Discord REST 反应读取或渠道转录检查。 +- 当 bug 有可见 UI 表面时捕获截图。 - 从智能体控制的 CLI 在本地运行，并从 GitHub 远程运行。 -- 当登录、浏览器自动化或提供商凭证卡住时，保留足够的机器状态以便 VNC 救援。 -- 当运行被阻塞、需要手动 VNC 帮助或完成时，向操作员 Discord 渠道发布简洁状态。 +- 当登录、浏览器自动化或提供商凭证卡住时，保留足够的机器状态用于 VNC 救援。 +- 当运行被阻塞、需要手动 VNC 协助或完成时，向操作员 Discord 渠道发布简短状态。 ## 非目标 -- Mantis 不是单元测试的替代品。理解修复后，Mantis 运行通常应该转化为更小的回归测试。 -- Mantis 不是常规的快速 CI 门禁。它更慢、使用实时凭证，并且只保留给实时环境重要的缺陷。 -- Mantis 的正常运行不应该需要人类介入。手动 VNC 是救援路径，不是理想路径。 +- Mantis 不是单元测试的替代品。理解修复后，Mantis 运行通常应转化为更小的回归测试。 +- Mantis 不是常规的快速 CI 门禁。它更慢，使用实时凭证，并且只用于实时环境很重要的 bug。 +- Mantis 不应在正常运行中需要人工介入。手动 VNC 是救援路径，而不是理想路径。 - Mantis 不会在构件、日志、截图、Markdown 报告或 PR 评论中存储原始密钥。 -## 所有权 +## 归属 Mantis 位于 OpenClaw QA 栈中。 -- OpenClaw 拥有场景运行时、传输协议适配器、证据 schema，以及 `pnpm openclaw qa mantis` 下的本地 CLI。 -- QA Lab 拥有实时传输协议 harness 组件、浏览器捕获辅助工具和构件写入器。 +- OpenClaw 拥有 `pnpm openclaw qa mantis` 下的场景运行时、传输协议适配器、证据 schema 和本地 CLI。 +- QA Lab 拥有实时传输协议 harness 组件、浏览器捕获助手和构件写入器。 - 需要远程 VM 时，Crabbox 拥有预热的 Linux 机器。 - GitHub Actions 拥有远程工作流入口点和构件保留。 -- ClawSweeper 拥有 GitHub 评论路由：解析维护者命令、调度工作流，以及发布最终 PR 评论。 +- ClawSweeper 拥有 GitHub 评论路由：解析维护者命令、分派工作流并发布最终 PR 评论。 - 当场景需要智能体式设置、调试或卡住状态报告时，OpenClaw 智能体通过 Codex 驱动 Mantis。 -这个边界将传输协议知识保留在 OpenClaw 中，将机器调度保留在 Crabbox 中，并将维护者工作流粘合逻辑保留在 ClawSweeper 中。 +这个边界将传输协议知识保留在 OpenClaw 中，将机器调度保留在 Crabbox 中，并将维护者工作流胶水保留在 ClawSweeper 中。 -## 命令形态 +## 命令形式 -第一个本地命令会验证 Discord 机器人、公会、渠道、消息发送、回应发送和构件路径： +第一个本地命令会验证 Discord bot、guild、渠道、消息发送、反应发送和构件路径： ```bash pnpm openclaw qa mantis discord-smoke \ --output-dir .artifacts/qa-e2e/mantis/discord-smoke ``` -后续的前后对比运行器应该接受这种形态： +后续 before 和 after 运行器应接受这种形式： ```bash pnpm openclaw qa mantis run \ @@ -70,12 +70,12 @@ pnpm openclaw qa mantis run \ --output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions ``` -GitHub 冒烟工作流是 `Mantis Discord Smoke`。第一个真实场景的前后对比 GitHub 工作流是 `Mantis Discord Status Reactions`。它接受： +GitHub smoke 工作流是 `Mantis Discord Smoke`。第一个真实场景的 before 和 after GitHub 工作流是 `Mantis Discord Status Reactions`。它接受： - `baseline_ref`：预期会复现仅 queued 行为的 ref。 - `candidate_ref`：预期会显示 `queued -> thinking -> done` 的 ref。 -它会检出工作流 harness ref，构建独立的基线和候选 worktree，分别针对每个 worktree 运行 `discord-status-reactions-tool-only`，并将 `baseline/`、`candidate/`、`comparison.json` 和 `mantis-report.md` 作为 Actions 构件上传。 +它会检出工作流 harness ref，构建独立的基线和候选工作树，分别对每个工作树运行 `discord-status-reactions-tool-only`，并将 `baseline/`、`candidate/`、`comparison.json` 和 `mantis-report.md` 作为 Actions 构件上传。 ClawSweeper 命令示例： @@ -84,42 +84,42 @@ ClawSweeper 命令示例： @clawsweeper verify e2e discord ``` -第一个命令明确且聚焦于场景。第二个命令之后可以根据标签、变更文件和 ClawSweeper 审查发现，将 PR 或问题映射到推荐的 Mantis 场景。 +第一个命令是显式且聚焦场景的。第二个命令后续可以根据标签、变更文件和 ClawSweeper 评审发现，将 PR 或 issue 映射到推荐的 Mantis 场景。 ## 运行生命周期 1. 获取凭证。 2. 分配或复用 VM。 -3. 为基线 ref 准备一个干净检出。 -4. 安装依赖，并只构建场景需要的内容。 -5. 使用隔离的状态目录启动一个子 OpenClaw Gateway 网关。 +3. 为基线 ref 准备干净的检出。 +4. 安装依赖，并且只构建场景所需内容。 +5. 使用隔离状态目录启动子 OpenClaw Gateway 网关。 6. 配置实时传输协议、提供商、模型和浏览器配置文件。 7. 运行场景并捕获基线证据。 8. 停止 Gateway 网关并保留日志。 -9. 在同一个 VM 中准备候选 ref。 -10. 运行相同场景并捕获候选证据。 +9. 在同一 VM 中准备候选 ref。 +10. 运行同一场景并捕获候选证据。 11. 比较判定器结果和视觉证据。 12. 写入 Markdown、JSON、日志、截图和可选 trace 构件。 13. 上传 GitHub Actions 构件。 -14. 发布简洁的 PR 或 Discord 状态消息。 +14. 发布简短的 PR 或 Discord 状态消息。 -场景应该能够以两种不同方式失败： +场景应能以两种不同方式失败： -- **已复现缺陷**：基线以预期方式失败。 -- **Harness 失败**：环境设置、凭证、Discord API、浏览器或提供商在缺陷判定器有意义之前失败。 +- **已复现 bug**：基线以预期方式失败。 +- **Harness 失败**：环境设置、凭证、Discord API、浏览器或提供商在 bug 判定器有意义前失败。 -最终报告必须区分这些情况，确保维护者不会把不稳定的环境与产品行为混淆。 +最终报告必须区分这些情况，这样维护者不会把不稳定环境与产品行为混淆。 ## Discord MVP -第一个场景应该针对公会渠道中的 Discord 状态回应，其中源回复投递模式为 `message_tool_only`。 +第一个场景应针对 guild 渠道中的 Discord 状态反应，其中源回复投递模式为 `message_tool_only`。 -它适合作为 Mantis 起点的原因： +它是一个好的 Mantis 种子，原因如下： -- 它在 Discord 中表现为触发消息上的回应，具有可见性。 -- 它通过 Discord 消息回应状态提供强 REST 判定器。 -- 它会覆盖真实的 OpenClaw Gateway 网关、Discord 机器人凭证、消息分发、源回复投递模式、状态回应状态和模型轮次生命周期。 -- 它足够窄，可以让第一个实现保持诚实。 +- 它在 Discord 中以触发消息上的反应形式可见。 +- 它通过 Discord 消息反应状态提供强 REST 判定器。 +- 它会覆盖真实的 OpenClaw Gateway 网关、Discord bot 凭证、消息分派、源回复投递模式、状态反应状态和模型轮次生命周期。 +- 它足够窄，能让第一个实现保持可靠。 预期场景形态： @@ -152,9 +152,9 @@ evidence: screenshotMessageRow: true ``` -基线证据应该显示 queued 确认回应，但在仅工具模式下没有生命周期转换。候选证据应该显示当 `messages.statusReactions.enabled` 被显式设为 true 时，生命周期状态回应会运行。 +基线证据应显示 queued 确认反应，但在 tool-only 模式下没有生命周期转换。候选证据应显示当 `messages.statusReactions.enabled` 显式为 true 时，生命周期状态反应会运行。 -可执行的第一个切片是选择启用的 Discord 实时 QA 场景： +第一个可执行切片是可选启用的 Discord 实时 QA 场景： ```bash pnpm openclaw qa discord \ @@ -166,20 +166,19 @@ pnpm openclaw qa discord \ --output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate ``` -它会为 SUT 配置始终开启的公会处理、`visibleReplies: -"message_tool"`、`ackReaction: "👀"` 和显式状态回应。判定器会轮询真实的 Discord 触发消息，并预期观察到序列 `👀 -> 🤔 -> 👍`。构件包括 `discord-qa-reaction-timelines.json`、`discord-status-reactions-tool-only-timeline.html` 和 `discord-status-reactions-tool-only-timeline.png`。 +它会为 SUT 配置始终开启的 guild 处理、`visibleReplies: "message_tool"`、`ackReaction: "👀"` 和显式状态反应。判定器会轮询真实的 Discord 触发消息，并预期观察到序列 `👀 -> 🤔 -> 👍`。构件包括 `discord-qa-reaction-timelines.json`、`discord-status-reactions-tool-only-timeline.html` 和 `discord-status-reactions-tool-only-timeline.png`。 ## 现有 QA 组件 -Mantis 应该构建在现有私有 QA 栈之上，而不是从零开始： +Mantis 应基于现有的私有 QA 栈构建，而不是从零开始： -- `pnpm openclaw qa discord` 已经运行一条带 driver 和 SUT 机器人的实时 Discord 通道。 -- 实时传输协议运行器已经在 `.artifacts/qa-e2e/` 下写入报告和观测消息构件。 +- `pnpm openclaw qa discord` 已经运行带 driver 和 SUT bot 的实时 Discord 通道。 +- 实时传输协议运行器已经会在 `.artifacts/qa-e2e/` 下写入报告和已观察消息构件。 - Convex 凭证租约已经提供对共享实时传输协议凭证的独占访问。 - 浏览器控制服务已经支持截图、快照、无头托管配置文件和远程 CDP 配置文件。 -- QA Lab 已经拥有用于传输协议形态测试的调试器 UI 和总线。 +- QA Lab 已经有用于传输协议形态测试的调试器 UI 和总线。 -第一个 Mantis 实现可以是在这些组件之上的一层很薄的前后对比运行器，再加上一层视觉证据。 +第一个 Mantis 实现可以是在这些组件之上构建的轻量 before/after 运行器，再加上一层视觉证据。 ## 证据模型 @@ -203,65 +202,65 @@ Mantis 应该构建在现有私有 QA 栈之上，而不是从零开始： run.log ``` -`mantis-summary.json` 应该是机器可读的事实来源。Markdown 报告用于 PR 评论和人工审查。 +`mantis-summary.json` 应是机器可读的事实来源。Markdown 报告用于 PR 评论和人工评审。 -摘要必须包括： +摘要必须包含： -- 测试的 ref 和 SHA -- 传输协议和场景 ID -- 机器提供商以及机器 ID 或租约 ID +- 已测试的 refs 和 SHA +- 传输协议和场景 id +- 机器提供商以及机器 id 或租约 id - 不含密钥值的凭证来源 - 基线结果 - 候选结果 -- 缺陷是否在基线上复现 +- bug 是否在基线上复现 - 候选是否修复了它 - 构件路径 - 已清理的设置或清理问题 -截图是证据，不是密钥。它们仍然需要遵守脱敏纪律：私有渠道名称、用户名或消息内容可能会出现。对于公开 PR，在脱敏方案更成熟之前，优先使用 GitHub Actions 构件链接，而不是内联图片。 +截图是证据，不是密钥。它们仍然需要遵守脱敏纪律：私有渠道名称、用户名或消息内容可能会出现。对于公开 PR，在脱敏方案更完善之前，优先使用 GitHub Actions 构件链接，而不是内联图片。 ## 浏览器和 VNC 浏览器通道有两种模式： - **无头自动化**：CI 的默认模式。Chrome 启用 CDP 运行，Playwright 或 OpenClaw 浏览器控制会捕获截图。 -- **VNC 救援**：当登录、MFA、Discord 反自动化或视觉调试需要人类介入时，在同一个 VM 上启用。 +- **VNC 救援**：当登录、MFA、Discord 反自动化或视觉调试需要人工时，在同一 VM 上启用。 -Discord 观察者浏览器配置文件应该足够持久，以避免每次运行都登录，但要与个人浏览器状态隔离。配置文件属于 Mantis 机器池，而不是开发者笔记本电脑。 +Discord 观察者浏览器配置文件应足够持久，避免每次运行都登录，但要与个人浏览器状态隔离。配置文件属于 Mantis 机器池，而不是开发者笔记本电脑。 -当 Mantis 卡住时，它会发布一条 Discord 状态消息，其中包含： +当 Mantis 卡住时，它会发布一条 Discord 状态消息，包含： -- 运行 ID -- 场景 ID +- 运行 id +- 场景 id - 机器提供商 - 构件目录 - VNC 或 noVNC 连接说明（如果可用） -- 简短阻塞原因文本 +- 简短阻塞说明 第一个私有部署可以将这些消息发布到现有操作员渠道，之后再迁移到专用 Mantis 渠道。 ## 机器 -第一个远程实现中，Mantis 应优先通过 Crabbox 使用 AWS。Crabbox 为我们提供预热机器、租约跟踪、环境补水、日志、结果和清理。如果 AWS 容量太慢或不可用，就在相同机器接口后添加 Hetzner 提供商。 +第一个远程实现中，Mantis 应优先通过 Crabbox 使用 AWS。Crabbox 提供预热机器、租约跟踪、hydration、日志、结果和清理。如果 AWS 容量太慢或不可用，则在同一机器接口后添加 Hetzner 提供商。 最低 VM 要求： -- Linux，安装了具备桌面能力的 Chrome 或 Chromium +- Linux，安装可用于桌面的 Chrome 或 Chromium - 用于浏览器自动化的 CDP 访问 - 用于救援的 VNC 或 noVNC - Node 22 和 pnpm - OpenClaw 检出和依赖缓存 - 使用 Playwright 时的 Playwright Chromium 浏览器缓存 - 足够运行一个 OpenClaw Gateway 网关、一个浏览器和一次模型运行的 CPU 与内存 -- 对 Discord、GitHub、模型提供商和凭证代理的出站访问 +- 对 Discord、GitHub、模型提供商和凭证 broker 的出站访问 -VM 不应在预期凭证或浏览器配置文件存储之外保留长期存在的原始密钥。 +VM 不应在预期的凭证或浏览器配置文件存储之外保留长期存在的原始密钥。 ## 密钥 -远程运行的密钥位于 GitHub 组织或仓库密钥中，本地运行的密钥位于本地操作员控制的密钥文件中。 +远程运行的密钥存放在 GitHub 组织或仓库密钥中，本地运行的密钥存放在本地操作员控制的密钥文件中。 -推荐的密钥名称： +推荐密钥名称： - `OPENCLAW_QA_DISCORD_MANTIS_BOT_TOKEN` - `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN` @@ -269,30 +268,32 @@ VM 不应在预期凭证或浏览器配置文件存储之外保留长期存在 - `OPENCLAW_QA_DISCORD_GUILD_ID` - `OPENCLAW_QA_DISCORD_CHANNEL_ID` - `OPENCLAW_QA_DISCORD_NOTIFY_CHANNEL_ID` -- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1`，用于公开 GitHub 构件上传 +- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` 用于公开 GitHub 构件上传 - `OPENCLAW_QA_CONVEX_SITE_URL` - `OPENCLAW_QA_CONVEX_SECRET_CI` -长期来看，Convex 凭证池应继续作为实时传输协议凭证的常规来源。GitHub 密钥用于引导代理和回退通道。 +长期来看，Convex 凭证池应继续作为实时传输协议凭证的常规来源。GitHub 密钥用于引导 broker 和后备通道。 Mantis 运行器绝不能打印： -- Discord 机器人 token +- Discord bot token - 提供商 API key - 浏览器 cookie - 凭证配置文件内容 - VNC 密码 -- 原始凭证载荷 +- 原始凭证 payload -公开构件上传还应脱敏 Discord 目标元数据，例如机器人、公会、渠道和消息 ID。GitHub 冒烟工作流因此启用了 `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1`。 +公开构件上传还应脱敏 Discord 目标元数据，例如 bot、guild、渠道和消息 id。GitHub smoke 工作流因此启用了 `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1`。 -如果 token 被意外粘贴到问题、PR、聊天或日志中，请在新密钥存储后轮换它。 +如果 token 被意外粘贴到 issue、PR、聊天或日志中，请在存储新密钥后轮换它。 ## GitHub 构件和 PR 评论 -Mantis 工作流应将完整证据包作为短期 Actions 工件上传。当工作流针对错误报告或修复 PR 运行时，它还应将已脱敏的 PNG 截图发布到 `qa-artifacts` 分支，并在该错误或修复 PR 上插入或更新一条评论，内联展示修复前/修复后的截图。不要只把主要证明发布在通用 QA 自动化 PR 上。原始日志、观测到的消息和其他体量较大的证据保留在 Actions 工件中。 +Mantis 工作流应将完整证据包上传为短期 Actions 工件。当工作流针对错误报告或修复 PR 运行时，它还应将已脱敏的 PNG 截图发布到 `qa-artifacts` 分支，并在该错误或修复 PR 上更新或插入一条评论，内联展示修复前/后的截图。不要只把主要证明发布到通用 QA 自动化 PR 上。原始日志、观测到的消息以及其他体积较大的证据应保留在 Actions 工件中。 -PR 评论应简短且偏视觉化： +生产工作流应使用 Mantis GitHub App 发布这些评论，而不是使用 `github-actions[bot]`。将应用 id 和私钥存储为 `MANTIS_GITHUB_APP_ID` 和 `MANTIS_GITHUB_APP_PRIVATE_KEY` GitHub Actions 密钥。如果缺少这些密钥，工作流可以在本地启动阶段回退到 `github-actions[bot]`，但这不是期望的长期身份。 + +PR 评论应简短且以视觉为主： ```md Mantis Discord Status Reactions QA @@ -312,60 +313,60 @@ candidate showed the expected queued -> thinking -> done sequence. | | | ``` -当运行失败是因为 harness 失败时，评论必须说明这一点，而不是暗示候选修复失败。 +当运行因 harness 失败而失败时，评论必须说明这一点，而不是暗示候选修复失败。 ## 私有部署说明 -私有部署可能已经有一个 Mantis Discord 应用。当该应用具备正确的机器人权限并且可以安全轮换时，复用该应用，而不是再创建一个应用。 +私有部署可能已经有一个 Mantis Discord 应用。如果该应用具备正确的 bot 权限并且可以安全轮换，请复用该应用，而不是再创建一个应用。 -通过密钥或部署配置设置初始操作员通知渠道。它可以先指向现有的维护者或运维渠道，然后在专用 Mantis 渠道存在后再迁移过去。 +通过密钥或部署配置设置初始操作员通知渠道。它可以先指向现有维护者或运维渠道，等专用 Mantis 渠道存在后再迁移过去。 -不要将服务器 ID、渠道 ID、机器人令牌、浏览器 Cookie 或 VNC 密码放入本文档。请将它们存储在 GitHub 密钥、凭证代理或操作员的本地密钥存储中。 +不要把 guild id、channel id、bot token、浏览器 cookie 或 VNC 密码放入本文档。将它们存储在 GitHub 密钥、凭证代理或操作员的本地密钥存储中。 ## 添加场景 Mantis 场景应声明： -- ID 和标题 +- id 和标题 - 传输协议 - 所需凭证 - 基线 ref 策略 - 候选 ref 策略 - OpenClaw 配置补丁 - 设置步骤 -- 触发输入 -- 预期基线判定依据 -- 预期候选判定依据 +- 刺激 +- 预期基线判定器 +- 预期候选判定器 - 视觉捕获目标 - 超时预算 - 清理步骤 -场景应优先使用小型、类型化的判定依据： +场景应优先使用小型、带类型的判定器： -- 用于回应错误的 Discord 回应状态 -- 用于话题串错误的 Discord 消息引用 -- 用于 Slack 错误的 Slack 线程 ts 和回应 API 状态 -- 用于邮件错误的电子邮件消息 ID 和标头 -- 当 UI 是唯一可靠的可观测对象时，使用浏览器截图 +- 用于表情回应错误的 Discord 表情回应状态 +- 用于串联错误的 Discord 消息引用 +- 用于 Slack 错误的 Slack thread ts 和表情回应 API 状态 +- 用于电子邮件错误的电子邮件消息 id 和标头 +- 当 UI 是唯一可靠可观测对象时使用浏览器截图 -视觉检查应作为补充。如果平台 API 可以证明错误，就使用 API 作为通过/失败判定依据，并保留截图以增强人工信心。 +视觉检查应作为补充。如果平台 API 可以证明该错误，请使用 API 作为通过/失败判定器，并保留截图用于增强人工信心。 ## 提供商扩展 -在 Discord 之后，同一个 runner 可以添加： +在 Discord 之后，同一个运行器可以添加： -- Slack：回应、线程、应用提及、模态框、文件上传。 -- 电子邮件：在连接器不足时，使用 `gog` 进行 Gmail 凭证和消息话题串处理。 -- WhatsApp：二维码登录、重新识别、消息送达、媒体、回应。 -- Telegram：群组提及门控、命令、可用时的回应。 -- Matrix：加密房间、线程或回复关系、重启后恢复。 +- Slack：表情回应、线程、应用提及、模态框、文件上传。 +- 电子邮件：在连接器不足时，使用 `gog` 进行 Gmail 认证和消息串联。 +- WhatsApp：二维码登录、重新识别、消息投递、媒体、表情回应。 +- Telegram：群组提及门控、命令、可用时的表情回应。 +- Matrix：加密房间、线程或回复关系、重启恢复。 -每种传输协议都应有一个低成本冒烟场景，以及一个或多个错误类别场景。昂贵的视觉场景应保持为可选启用。 +每种传输协议都应有一个低成本 smoke 场景，以及一个或多个错误类别场景。昂贵的视觉场景应保持为选择性启用。 -## 待解问题 +## 未决问题 -- 当复用现有 Mantis 机器人时，哪个 Discord 机器人应作为驱动方，哪个应作为 SUT？ -- 第一阶段的观察者浏览器登录应使用真人 Discord 账号、测试账号，还是只使用机器人可读的 REST 证据？ +- 复用现有 Mantis bot 时，哪个 Discord bot 应作为驱动方，哪个应作为 SUT？ +- 第一阶段中，观察者浏览器登录应使用真人 Discord 账号、测试账号，还是只使用 bot 可读的 REST 证据？ - GitHub 应为 PR 保留 Mantis 工件多长时间？ -- ClawSweeper 何时应自动推荐 Mantis，而不是等待维护者命令？ -- 公开 PR 上传前，截图是否应脱敏或裁剪？ +- ClawSweeper 应在什么时候自动推荐 Mantis，而不是等待维护者命令？ +- 面向公开 PR 上传前，截图是否应进行脱敏或裁剪？ diff --git a/docs/zh-CN/gateway/configuration.md b/docs/zh-CN/gateway/configuration.md index fea77423a..94e5dd60f 100644 --- a/docs/zh-CN/gateway/configuration.md +++ b/docs/zh-CN/gateway/configuration.md @@ -2,38 +2,38 @@ read_when: - 首次设置 OpenClaw - 正在查找常见配置模式 - - 导航到特定配置章节 -summary: 配置概览：常见任务、快速设置，以及完整参考链接 + - 跳转到特定配置章节 +summary: 配置概览：常见任务、快速设置，以及完整参考的链接 title: 配置 x-i18n: - generated_at: "2026-05-03T12:47:59Z" + generated_at: "2026-05-03T17:11:02Z" model: gpt-5.5 provider: openai - source_hash: b17a72368bb8d178174ccd3ff401657c67911096efd5960e5a1aa8cf0d303c81 + source_hash: e27ef442d6375d8c22715f20194fb9ce50130204377c9ba4652c2949de28967c source_path: gateway/configuration.md workflow: 16 --- OpenClaw 从 `~/.openclaw/openclaw.json` 读取可选的 **JSON5** 配置。 -活动配置路径必须是普通文件。对于 OpenClaw 拥有的写入，不支持符号链接的 `openclaw.json` -布局；原子写入可能会替换该路径，而不是保留符号链接。如果你将配置保存在 -默认状态目录之外，请将 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。 +活动配置路径必须是常规文件。符号链接的 `openclaw.json` +布局不支持 OpenClaw 拥有的写入；原子写入可能会替换 +该路径，而不是保留符号链接。如果你将配置保存在默认状态目录 +之外，请将 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。 如果文件缺失，OpenClaw 会使用安全默认值。添加配置的常见原因： -- 连接渠道并控制谁可以给机器人发消息 -- 设置模型、工具、沙箱隔离或自动化（cron、hooks） +- 连接渠道并控制谁可以给 bot 发送消息 +- 设置模型、工具、沙箱隔离或自动化（cron、钩子） - 调整会话、媒体、网络或 UI -查看[完整参考](/zh-CN/gateway/configuration-reference)，了解每个可用字段。 +查看[完整参考](/zh-CN/gateway/configuration-reference)了解每个可用字段。 -智能体和自动化在编辑配置前，应使用 `config.schema.lookup` 获取精确到字段级别的 -文档。将本页用于面向任务的指导，并将 -[配置参考](/zh-CN/gateway/configuration-reference)用于更完整的 -字段映射和默认值。 +智能体和自动化在编辑配置前，应使用 `config.schema.lookup` 获取精确的字段级 +文档。此页面提供面向任务的指导；[配置参考](/zh-CN/gateway/configuration-reference) +提供更完整的字段映射和默认值。 -**刚开始配置？** 从 `openclaw onboard` 开始进行交互式设置，或查看 [Configuration Examples](/zh-CN/gateway/configuration-examples) 指南，获取完整的可复制粘贴配置。 +**刚开始使用配置？** 从 `openclaw onboard` 开始进行交互式设置，或查看 [Configuration Examples](/zh-CN/gateway/configuration-examples) 指南获取完整的可复制粘贴配置。 ## 最小配置 @@ -64,53 +64,49 @@ OpenClaw 从 `~/.openclaw/openclaw.json` 读取可选的 打开 [http://127.0.0.1:18789](http://127.0.0.1:18789)，并使用 **配置** 标签页。 - 控制 UI 会根据实时配置架构渲染表单，包括字段 - `title` / `description` 文档元数据，以及可用时的插件和渠道架构， - 并提供 **Raw JSON** 编辑器作为逃生通道。对于下钻 - UI 和其他工具，Gateway 网关还暴露 `config.schema.lookup`，用于 - 获取一个路径限定的架构节点及其直接子项摘要。 + 控制 UI 会基于实时配置 schema 渲染表单，包括字段 + `title` / `description` 文档元数据，以及可用时的插件和渠道 schema， + 并提供 **原始 JSON** 编辑器作为逃生口。对于下钻 + UI 和其他工具，Gateway 网关还暴露 `config.schema.lookup`， + 用于获取一个路径作用域的 schema 节点及其直接子项摘要。 - 直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。 + 直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监听该文件并自动应用更改（见[热重载](#config-hot-reload)）。 -## 严格验证 +## 严格校验 -OpenClaw 只接受完全匹配架构的配置。未知键、格式错误的类型或无效值会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器可以附加 JSON Schema 元数据。 +OpenClaw 只接受完全匹配 schema 的配置。未知键、格式错误的类型或无效值会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器可以附加 JSON Schema 元数据。 -`openclaw config schema` 会打印控制 UI -和验证使用的规范 JSON Schema。`config.schema.lookup` 会获取单个路径限定的节点及其 -子项摘要，供下钻工具使用。字段 `title`/`description` 文档元数据 -会贯穿嵌套对象、通配符（`*`）、数组项（`[]`）以及 `anyOf`/ -`oneOf`/`allOf` 分支。清单注册表加载后，会合并运行时插件和渠道架构。 +`openclaw config schema` 会打印控制 UI 和校验使用的规范 JSON Schema。 +`config.schema.lookup` 会获取单个路径作用域节点及其子项摘要，用于下钻工具。 +字段 `title`/`description` 文档元数据会贯穿嵌套对象、通配符（`*`）、 +数组项（`[]`）以及 `anyOf`/`oneOf`/`allOf` 分支。加载清单注册表后， +运行时插件和渠道 schema 会合并进来。 -验证失败时： +校验失败时： - Gateway 网关不会启动 - 只有诊断命令可用（`openclaw doctor`、`openclaw logs`、`openclaw health`、`openclaw status`） -- 运行 `openclaw doctor` 查看确切问题 +- 运行 `openclaw doctor` 查看精确问题 - 运行 `openclaw doctor --fix`（或 `--yes`）应用修复 -Gateway 网关会在每次成功启动后保留一份可信的最后已知良好副本。 -如果 `openclaw.json` 后续验证失败（或移除了 `gateway.mode`、大幅缩小， -或前面被意外添加了一行日志），OpenClaw 会将损坏文件保留为 -`.clobbered.*`，恢复最后已知良好副本，并记录恢复 -原因。下一轮智能体交互还会收到一个系统事件警告，避免主 -智能体盲目重写已恢复的配置。当候选配置包含 `***` 等经过遮盖的密钥占位符时， -会跳过将其提升为最后已知良好副本。 -当每个验证问题都限定在 `plugins.entries....` 范围内时，OpenClaw -不会执行整文件恢复。它会保持当前配置活动，并 -浮现插件本地失败，这样插件架构或主机版本不匹配 -就不会回滚无关的用户设置。 +Gateway 网关在每次成功启动后都会保留一份可信的最近一次可用副本， +但启动和热重载不会自动恢复它。如果 `openclaw.json` +校验失败（包括插件本地校验），Gateway 网关启动会失败，或 +重载会被跳过，当前运行时保留最后一次被接受的配置。 +运行 `openclaw doctor --fix`（或 `--yes`）来修复带前缀/被覆盖的配置，或 +恢复最近一次可用副本。当候选配置包含已脱敏的密钥占位符（如 `***`）时， +会跳过提升为最近一次可用副本。 ## 常见任务 - 每个渠道在 `channels.` 下都有自己的配置区段。查看专用渠道页面了解设置步骤： + 每个渠道在 `channels.` 下都有自己的配置段。设置步骤请查看对应的渠道页面： - [WhatsApp](/zh-CN/channels/whatsapp) — `channels.whatsapp` - [Telegram](/zh-CN/channels/telegram) — `channels.telegram` @@ -141,7 +137,7 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 - 设置主模型和可选回退模型： + 设置主模型和可选回退项： ```json5 { @@ -160,31 +156,31 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 } ``` - - `agents.defaults.models` 定义模型目录，并作为 `/model` 的 allowlist。 - - 使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加 allowlist 条目，而不会移除现有模型。除非传入 `--replace`，否则会移除条目的普通替换会被拒绝。 + - `agents.defaults.models` 定义模型目录，并作为 `/model` 的允许列表。 + - 使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加允许列表条目，而不移除现有模型。除非传入 `--replace`，否则会移除条目的普通替换会被拒绝。 - 模型引用使用 `provider/model` 格式（例如 `anthropic/claude-opus-4-6`）。 - - `agents.defaults.imageMaxDimensionPx` 控制 transcript/工具图像缩小（默认 `1200`）；较低的值通常会减少截图密集型运行中的视觉 token 用量。 - - 查看 [Models CLI](/zh-CN/concepts/models) 了解如何在聊天中切换模型，并查看 [Model Failover](/zh-CN/concepts/model-failover) 了解认证轮换和回退行为。 + - `agents.defaults.imageMaxDimensionPx` 控制 transcript/工具图片缩小（默认 `1200`）；较低的值通常会在截图密集的运行中减少视觉 token 用量。 + - 参见 [Models CLI](/zh-CN/concepts/models) 了解如何在聊天中切换模型，并参见 [Model Failover](/zh-CN/concepts/model-failover) 了解鉴权轮换和回退行为。 - 对于自定义/自托管提供商，请参见参考中的[自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。 - - 私信访问通过每个渠道的 `dmPolicy` 控制： + + 私信访问通过 `dmPolicy` 按渠道控制： - - `"pairing"`（默认）：未知发送者会获得一次性配对码用于批准 - - `"allowlist"`：仅允许 `allowFrom` 中的发送者（或已配对的允许存储） - - `"open"`：允许所有传入私信（需要 `allowFrom: ["*"]`） + - `"pairing"`（默认）：未知发送者会收到一次性配对码以进行批准 + - `"allowlist"`：仅允许 `allowFrom` 中的发送者（或已配对允许存储中的发送者） + - `"open"`：允许所有入站私信（需要 `allowFrom: ["*"]`） - `"disabled"`：忽略所有私信 - 对于群组，使用 `groupPolicy` + `groupAllowFrom` 或渠道特定的 allowlist。 + 对于群组，请使用 `groupPolicy` + `groupAllowFrom` 或渠道专用允许列表。 - 查看[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)，了解每个渠道的详细信息。 + 按渠道的详细信息请参见[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)。 - 群组消息默认**需要提及**。为每个智能体配置触发模式，并将可见房间回复保留在默认的消息工具路径上，除非你有意使用旧版自动最终回复： + 群组消息默认**需要提及**。按智能体配置触发模式，并将可见房间回复保持在默认的消息工具路径，除非你有意使用旧版自动最终回复： ```json5 { @@ -215,12 +211,12 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 - **元数据提及**：原生 @ 提及（WhatsApp 点按提及、Telegram @bot 等） - **文本模式**：`mentionPatterns` 中的安全正则模式 - **可见回复**：`messages.visibleReplies` 可以全局要求通过消息工具发送；`messages.groupChat.visibleReplies` 会为群组/渠道覆盖该设置。 - - 查看[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)，了解可见回复模式、每渠道覆盖以及自聊模式。 + - 查看[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)，了解可见回复模式、按渠道覆盖和自聊模式。 - 使用 `agents.defaults.skills` 作为共享基线，然后通过 + 使用 `agents.defaults.skills` 作为共享基线，然后用 `agents.list[].skills` 覆盖特定智能体： ```json5 @@ -238,16 +234,16 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 } ``` - - 省略 `agents.defaults.skills`，默认不限制 Skills。 - - 省略 `agents.list[].skills` 以继承默认值。 - - 设置 `agents.list[].skills: []` 表示没有 Skills。 - - 查看 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和 + - 省略 `agents.defaults.skills` 时，默认不限制 Skills。 + - 省略 `agents.list[].skills` 时继承默认值。 + - 将 `agents.list[].skills` 设为 `[]` 表示没有 Skills。 + - 参见 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config)，以及 [配置参考](/zh-CN/gateway/config-agents#agents-defaults-skills)。 - 控制 Gateway 网关对看起来停滞的渠道进行重启的积极程度： + 控制 Gateway 网关对看起来停滞的渠道进行重启的激进程度： ```json5 { @@ -269,15 +265,15 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 } ``` - - 设置 `gateway.channelHealthCheckMinutes: 0` 可全局禁用健康监控重启。 + - 将 `gateway.channelHealthCheckMinutes: 0` 设为全局禁用健康监控重启。 - `channelStaleEventThresholdMinutes` 应大于或等于检查间隔。 - - 使用 `channels..healthMonitor.enabled` 或 `channels..accounts..healthMonitor.enabled` 可为单个渠道或账号禁用自动重启，而不禁用全局监控器。 - - 查看 [Health Checks](/zh-CN/gateway/health) 了解运维调试，并查看[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。 + - 使用 `channels..healthMonitor.enabled` 或 `channels..accounts..healthMonitor.enabled` 可为某个渠道或账号禁用自动重启，而不禁用全局监控。 + - 参见 [Health Checks](/zh-CN/gateway/health) 进行运维调试，并参见[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。 - 在负载较高或性能较低的主机上，给本地客户端更多时间来完成认证前 WebSocket 握手： + 在负载较高或性能较低的主机上，给本地客户端更多时间完成鉴权前 WebSocket 握手： ```json5 { @@ -288,8 +284,8 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 ``` - 默认值为 `15000` 毫秒。 - - 对于一次性的服务或 shell 覆盖，`OPENCLAW_HANDSHAKE_TIMEOUT_MS` 仍然优先。 - - 优先修复启动/事件循环停顿；这个旋钮适用于健康但在预热期间较慢的主机。 + - `OPENCLAW_HANDSHAKE_TIMEOUT_MS` 对一次性服务或 shell 覆盖仍然优先。 + - 优先修复启动/事件循环停顿；此旋钮用于健康但预热期间较慢的主机。 @@ -314,10 +310,10 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 } ``` - - `dmScope`: `main`（共享）| `per-peer` | `per-channel-peer` | `per-account-channel-peer` + - `dmScope`：`main`（共享）| `per-peer` | `per-channel-peer` | `per-account-channel-peer` - `threadBindings`：线程绑定会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。 - - 请参阅[会话管理](/zh-CN/concepts/session)，了解作用域、身份链接和发送策略。 - - 请参阅[完整参考](/zh-CN/gateway/config-agents#session)，了解所有字段。 + - 参见 [Session Management](/zh-CN/concepts/session) 了解作用域、身份链接和发送策略。 + - 参见[完整参考](/zh-CN/gateway/config-agents#session)了解所有字段。 @@ -337,14 +333,14 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 } ``` - 请先构建镜像——如果使用源码检出，运行 `scripts/sandbox-setup.sh`；如果使用 npm 安装，请参阅[沙箱隔离 § 镜像和设置](/zh-CN/gateway/sandboxing#images-and-setup)中的内联 `docker build` 命令。 + 先构建镜像 — 如果是源码 checkout，请运行 `scripts/sandbox-setup.sh`；如果是 npm 安装，请参阅 [沙箱隔离 § 镜像和设置](/zh-CN/gateway/sandboxing#images-and-setup)中的内联 `docker build` 命令。 - 请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)获取完整指南，并参阅[完整参考](/zh-CN/gateway/config-agents#agentsdefaultssandbox)了解所有选项。 + 请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)了解完整指南，并参阅[完整参考](/zh-CN/gateway/config-agents#agentsdefaultssandbox)了解所有选项。 - - 中继支持的推送在 `openclaw.json` 中配置。 + + relay-backed push 在 `openclaw.json` 中配置。 在 Gateway 网关配置中设置： @@ -364,7 +360,7 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 } ``` - 等效的 CLI 命令： + CLI 等效命令： ```bash openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com @@ -373,34 +369,34 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 这会执行以下操作： - 让 Gateway 网关通过外部中继发送 `push.test`、唤醒提示和重连唤醒。 - - 使用由已配对 iOS 应用转发的、注册作用域内的发送授权。Gateway 网关不需要部署范围的中继令牌。 - - 将每个中继支持的注册绑定到 iOS 应用配对的 Gateway 网关身份，因此另一个 Gateway 网关无法复用已存储的注册。 - - 让本地/手动 iOS 构建继续使用直连 APNs。中继支持的发送仅适用于通过中继注册的官方分发构建。 - - 必须与官方/TestFlight iOS 构建中内置的中继基础 URL 匹配，以便注册和发送流量到达同一个中继部署。 + - 使用由已配对 iOS 应用转发的、限定在注册范围内的发送授权。Gateway 网关不需要部署级中继 token。 + - 将每个 relay-backed 注册绑定到 iOS 应用配对的 Gateway 网关身份，因此其他 Gateway 网关无法复用已存储的注册。 + - 让本地/手动 iOS 构建继续使用直接 APNs。relay-backed 发送仅适用于通过中继注册的官方分发构建。 + - 必须匹配内置到官方/TestFlight iOS 构建中的中继基础 URL，以便注册和发送流量到达同一个中继部署。 端到端流程： 1. 安装使用相同中继基础 URL 编译的官方/TestFlight iOS 构建。 2. 在 Gateway 网关上配置 `gateway.push.apns.relay.baseUrl`。 - 3. 将 iOS 应用与 Gateway 网关配对，并让节点和操作员会话都完成连接。 - 4. iOS 应用获取 Gateway 网关身份，使用 App Attest 和应用收据向中继注册，然后将中继支持的 `push.apns.register` 负载发布到已配对的 Gateway 网关。 - 5. Gateway 网关存储中继句柄和发送授权，然后将它们用于 `push.test`、唤醒提示和重连唤醒。 + 3. 将 iOS 应用与 Gateway 网关配对，并让节点会话和操作者会话都连接。 + 4. iOS 应用获取 Gateway 网关身份，使用 App Attest 加应用收据向中继注册，然后将 relay-backed `push.apns.register` 载荷发布到已配对的 Gateway 网关。 + 5. Gateway 网关存储中继 handle 和发送授权，然后将它们用于 `push.test`、唤醒提示和重连唤醒。 运维说明： - - 如果你将 iOS 应用切换到不同的 Gateway 网关，请重新连接应用，以便它发布绑定到该 Gateway 网关的新中继注册。 - - 如果你发布了指向不同中继部署的新 iOS 构建，应用会刷新其缓存的中继注册，而不是复用旧的中继来源。 + - 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接应用，使其能够发布绑定到该 Gateway 网关的新中继注册。 + - 如果你发布的新 iOS 构建指向不同的中继部署，应用会刷新其缓存的中继注册，而不是复用旧的中继来源。 兼容性说明： - - `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可作为临时环境变量覆盖使用。 - - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍是仅限 loopback 的开发应急开关；不要在配置中持久化 HTTP 中继 URL。 + - `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可作为临时环境变量覆盖项使用。 + - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍是仅限 local loopback 的开发逃生口；不要在配置中持久保存 HTTP 中继 URL。 - 请参阅 [iOS 应用](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)了解端到端流程，并参阅[认证和信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)了解中继安全模型。 + 请参阅 [iOS 应用](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)了解端到端流程，并参阅[身份验证和信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)了解中继安全模型。 - + ```json5 { agents: { @@ -414,10 +410,10 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 } ``` - - `every`：持续时间字符串（`30m`、`2h`）。设置为 `0m` 可禁用。 + - `every`：时长字符串（`30m`、`2h`）。设置为 `0m` 可禁用。 - `target`：`last` | `none` | ``（例如 `discord`、`matrix`、`telegram` 或 `whatsapp`） - - `directPolicy`：对于私信风格的 Heartbeat 目标，使用 `allow`（默认）或 `block` - - 请参阅 [Heartbeat](/zh-CN/gateway/heartbeat) 获取完整指南。 + - `directPolicy`：对于私信样式的 Heartbeat 目标，使用 `allow`（默认）或 `block` + - 请参阅 [Heartbeat](/zh-CN/gateway/heartbeat)了解完整指南。 @@ -442,7 +438,7 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 - + 在 Gateway 网关上启用 HTTP webhook 端点： ```json5 @@ -467,15 +463,15 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 ``` 安全说明： - - 将所有 hook/webhook 负载内容视为不受信任的输入。 - - 使用专用的 `hooks.token`；不要复用共享的 Gateway 网关令牌。 - - Hook 认证仅支持标头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串令牌会被拒绝。 - - `hooks.path` 不能是 `/`；请将 webhook 入口保留在专用子路径上，例如 `/hooks`。 - - 除非进行严格限定范围的调试，否则请保持禁用不安全内容绕过标志（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`）。 - - 如果你启用 `hooks.allowRequestSessionKey`，也请设置 `hooks.allowedSessionKeyPrefixes` 来限制调用方选择的会话键。 - - 对于由 hook 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如仅消息传递，并在可行时配合沙箱隔离）。 + - 将所有 hook/webhook 载荷内容视为不受信任的输入。 + - 使用专用的 `hooks.token`；不要复用共享 Gateway 网关 token。 + - Hook 认证仅支持 header（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串 token 会被拒绝。 + - `hooks.path` 不能是 `/`；将 webhook 入口保留在专用子路径上，例如 `/hooks`。 + - 除非进行严格限定范围的调试，否则保持不安全内容绕过标志禁用（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`）。 + - 如果启用 `hooks.allowRequestSessionKey`，也要设置 `hooks.allowedSessionKeyPrefixes`，以约束调用方选择的会话键。 + - 对于 hook 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如仅消息传递，并尽可能使用沙箱隔离）。 - 请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)，了解所有映射选项和 Gmail 集成。 + 请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)了解所有映射选项和 Gmail 集成。 @@ -497,11 +493,11 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 } ``` - 请参阅[多智能体](/zh-CN/concepts/multi-agent)和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)，了解绑定规则和按智能体划分的访问配置文件。 + 请参阅 [Multi-Agent](/zh-CN/concepts/multi-agent) 和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)，了解绑定规则和每智能体访问配置文件。 - + 使用 `$include` 组织大型配置： ```json5 @@ -517,35 +513,33 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 - **单个文件**：替换包含它的对象 - **文件数组**：按顺序深度合并（后者优先） - - **同级键**：在 include 之后合并（覆盖被 include 的值） - - **嵌套 include**：最多支持 10 层深度 - - **相对路径**：相对于执行 include 的文件解析 - - **OpenClaw 所有的写入**：当写入只更改一个由单文件 include 支持的顶层区段时，例如 `plugins: { $include: "./plugins.json5" }`，OpenClaw 会更新该 include 的文件，并保持 `openclaw.json` 不变 - - **不支持的透传写入**：对于 OpenClaw 所有的写入，根 include、include 数组以及带同级覆盖的 include 会以失败关闭方式处理，而不是将配置扁平化 - - **限制范围**：`$include` 路径必须解析到包含 `openclaw.json` 的目录之下。要在机器或用户之间共享一棵目录树，请将 `OPENCLAW_INCLUDE_ROOTS` 设置为额外目录的路径列表（POSIX 上为 `:`，Windows 上为 `;`），include 可以引用这些目录。符号链接会被解析并重新检查，因此即使某个路径在词法上位于配置目录中，但其真实目标逃出了每个允许的根，也仍会被拒绝。 - - **错误处理**：针对缺失文件、解析错误和循环 include 提供清晰错误 + - **同级键**：在 include 之后合并（覆盖已 include 的值） + - **嵌套 include**：支持最多 10 层深度 + - **相对路径**：相对于包含它的文件解析 + - **OpenClaw 所有的写入**：当一次写入只更改一个顶级 section，且该 section 由单文件 include 支持，例如 `plugins: { $include: "./plugins.json5" }`，OpenClaw 会更新该被 include 的文件，并保持 `openclaw.json` 不变 + - **不支持的写穿透**：root include、include 数组，以及带有同级覆盖的 include，在 OpenClaw 所有的写入中会失败关闭，而不是展平配置 + - **限制范围**：`$include` 路径必须解析到保存 `openclaw.json` 的目录下。若要跨机器或用户共享一棵目录树，请将 `OPENCLAW_INCLUDE_ROOTS` 设置为路径列表（POSIX 上为 `:`，Windows 上为 `;`），其中包含 include 可引用的其他目录。符号链接会被解析并重新检查，因此即使某个路径在字面上位于配置目录中，但其真实目标逃逸出每个允许的 root，仍会被拒绝。 + - **错误处理**：对缺失文件、解析错误和循环 include 提供清晰错误 ## 配置热重载 -Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改——大多数设置无需手动重启。 +Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改 — 大多数设置无需手动重启。 -直接文件编辑在通过验证前会被视为不受信任。监视器会等待编辑器的临时写入/重命名抖动稳定下来，读取最终文件，并通过恢复最后一次已知良好的配置来拒绝无效的外部编辑。OpenClaw 所有的配置写入在写入前使用同一个 schema 门禁；会拒绝破坏性覆盖，例如删除 `gateway.mode` 或将文件缩小超过一半，并保存为 `.rejected.*` 以供检查。 +直接文件编辑在通过验证前会被视为不受信任。监视器会等待编辑器临时写入/重命名抖动稳定，读取最终文件，并在不重写 `openclaw.json` 的情况下拒绝无效外部编辑。OpenClaw 所有的配置写入在写入前使用同一个 schema gate；破坏性覆盖（例如删除 `gateway.mode` 或将文件缩小超过一半）会被拒绝，并保存为 `.rejected.*` 以供检查。 -插件本地验证失败是例外：如果所有问题都位于 `plugins.entries....` 下，重载会保留当前配置并报告插件问题，而不是恢复 `.last-good`。 - -如果你在日志中看到 `Config auto-restored from last-known-good` 或 `config reload restored last-known-good config`，请检查 `openclaw.json` 旁边匹配的 `.clobbered.*` 文件，修复被拒绝的负载，然后运行 `openclaw config validate`。请参阅 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)获取恢复检查清单。 +如果看到 `config reload skipped (invalid config)`，或启动时报出 `Invalid config`，请检查配置，运行 `openclaw config validate`，然后运行 `openclaw doctor --fix` 进行修复。请参阅 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-rejected-invalid-config)查看检查清单。 ### 重载模式 | 模式 | 行为 | | ---------------------- | --------------------------------------------------------------------------------------- | | **`hybrid`**（默认） | 立即热应用安全更改。对关键更改自动重启。 | -| **`hot`** | 仅热应用安全更改。当需要重启时记录警告——由你处理。 | -| **`restart`** | 任何配置更改都会重启 Gateway 网关，无论是否安全。 | -| **`off`** | 禁用文件监视。更改会在下一次手动重启时生效。 | +| **`hot`** | 仅热应用安全更改。需要重启时记录警告 — 由你处理。 | +| **`restart`** | 对任何配置更改都重启 Gateway 网关，无论是否安全。 | +| **`off`** | 禁用文件监视。更改会在下次手动重启时生效。 | ```json5 { @@ -557,18 +551,18 @@ Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改—— ### 哪些会热应用，哪些需要重启 -大多数字段都可以在不停机的情况下热应用。在 `hybrid` 模式下，需要重启的更改会自动处理。 +大多数字段可以无停机热应用。在 `hybrid` 模式下，需要重启的更改会被自动处理。 -| 类别 | 字段 | 是否需要重启？ | +| 类别 | 字段 | 需要重启？ | | ------------------- | ----------------------------------------------------------------- | --------------- | -| 渠道 | `channels.*`, `web` (WhatsApp) — 所有内置和插件渠道 | 否 | -| 智能体与模型 | `agent`, `agents`, `models`, `routing` | 否 | -| 自动化 | `hooks`, `cron`, `agent.heartbeat` | 否 | -| 会话与消息 | `session`, `messages` | 否 | -| 工具与媒体 | `tools`, `browser`, `skills`, `mcp`, `audio`, `talk` | 否 | -| UI 与其他 | `ui`, `logging`, `identity`, `bindings` | 否 | +| 渠道 | `channels.*`、`web`（WhatsApp）— 所有内置和插件渠道 | 否 | +| 智能体和模型 | `agent`、`agents`、`models`、`routing` | 否 | +| 自动化 | `hooks`、`cron`、`agent.heartbeat` | 否 | +| 会话和消息 | `session`、`messages` | 否 | +| 工具和媒体 | `tools`、`browser`、`skills`、`mcp`、`audio`、`talk` | 否 | +| UI 和其他 | `ui`、`logging`、`identity`、`bindings` | 否 | | Gateway 网关服务器 | `gateway.*`（端口、绑定、认证、tailscale、TLS、HTTP） | **是** | -| 基础设施 | `discovery`, `canvasHost`, `plugins` | **是** | +| 基础设施 | `discovery`、`canvasHost`、`plugins` | **是** | `gateway.reload` 和 `gateway.remote` 是例外 — 更改它们**不会**触发重启。 @@ -576,29 +570,23 @@ Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改—— ### 重载规划 -当你编辑通过 `$include` 引用的源文件时，OpenClaw 会从源文件编写时的布局规划重载，而不是从扁平化的内存视图规划。 -这样即使单个顶级部分位于自己的包含文件中，例如 -`plugins: { $include: "./plugins.json5" }`，热重载决策（热应用或重启）也能保持可预测。 -如果源布局存在歧义，重载规划会保守失败。 +当你编辑通过 `$include` 引用的源文件时，OpenClaw 会从源作者编写的布局规划重新加载，而不是从扁平化的内存视图规划。这样即使单个顶层部分位于自己的 include 文件中，例如 `plugins: { $include: "./plugins.json5" }`，也能让热重载决策（热应用还是重启）保持可预测。如果源布局存在歧义，重新加载规划会以关闭方式失败。 ## 配置 RPC（程序化更新） -对于通过 Gateway 网关 API 写入配置的工具，优先使用此流程： +对于通过 Gateway 网关 API 写入配置的工具，建议使用以下流程： -- 使用 `config.schema.lookup` 检查一个子树（浅层 schema 节点 + 子级摘要） -- 使用 `config.get` 获取当前快照以及 `hash` -- 使用 `config.patch` 进行局部更新（JSON 合并补丁：对象会合并，`null` 会删除，数组会替换） -- 仅在你打算替换整个配置时使用 `config.apply` -- 使用 `update.run` 显式执行自更新并重启；如果重启后的会话应运行一次后续回合，请包含 `continuationMessage` -- 使用 `update.status` 检查最新的更新重启哨兵，并在重启后验证正在运行的版本 +- `config.schema.lookup` 用于检查一个子树（浅层 schema 节点 + 子项摘要） +- `config.get` 用于获取当前快照以及 `hash` +- `config.patch` 用于局部更新（JSON merge patch：对象合并，`null` 删除，数组替换） +- 仅当你打算替换整个配置时才使用 `config.apply` +- `update.run` 用于显式自更新并重启；当重启后的会话应运行一个后续轮次时，请包含 `continuationMessage` +- `update.status` 用于检查最新的更新重启哨兵，并在重启后验证正在运行的版本 -智能体应将 `config.schema.lookup` 作为获取精确字段级文档和约束的第一站。 -当它们需要更宽泛的配置映射、默认值或指向专用子系统参考的链接时，请使用[配置参考](/zh-CN/gateway/configuration-reference)。 +智能体应将 `config.schema.lookup` 视为获取精确字段级文档和约束的第一站。当需要更广泛的配置映射、默认值或专用子系统参考链接时，请使用 [配置参考](/zh-CN/gateway/configuration-reference)。 -控制平面写入（`config.apply`、`config.patch`、`update.run`）会按每个 `deviceId+clientIp` 每 60 秒 3 个请求进行限流。 -重启请求会合并，然后在重启周期之间强制执行 30 秒冷却时间。 -`update.status` 是只读的，但限定为管理员作用域，因为重启哨兵可能包含更新步骤摘要和命令输出尾部。 +控制平面写入（`config.apply`、`config.patch`、`update.run`）按每个 `deviceId+clientIp` 每 60 秒 3 个请求进行速率限制。重启请求会合并，然后在重启周期之间强制执行 30 秒冷却时间。`update.status` 是只读的，但属于管理员作用域，因为重启哨兵可能包含更新步骤摘要和命令输出尾部。 局部补丁示例： @@ -611,17 +599,16 @@ openclaw gateway call config.patch --params '{ }' ``` -`config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、`note` 和 `restartDelayMs`。 -当配置已存在时，这两个方法都需要 `baseHash`。 +`config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、`note` 和 `restartDelayMs`。当配置已经存在时，这两个方法都要求提供 `baseHash`。 ## 环境变量 -OpenClaw 会从父进程以及以下位置读取环境变量： +OpenClaw 会从父进程读取环境变量，并额外读取： - 当前工作目录中的 `.env`（如果存在） - `~/.openclaw/.env`（全局回退） -这两个文件都不会覆盖现有环境变量。你也可以在配置中设置内联环境变量： +两个文件都不会覆盖现有环境变量。你也可以在配置中设置内联环境变量： ```json5 { @@ -632,8 +619,8 @@ OpenClaw 会从父进程以及以下位置读取环境变量： } ``` - - 如果启用且预期键名未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键： + + 如果启用且预期键名未设置，OpenClaw 会运行你的登录 shell，并只导入缺失的键： ```json5 { @@ -643,11 +630,11 @@ OpenClaw 会从父进程以及以下位置读取环境变量： } ``` -等效的环境变量：`OPENCLAW_LOAD_SHELL_ENV=1` +环境变量等价项：`OPENCLAW_LOAD_SHELL_ENV=1` - - 使用 `${VAR_NAME}` 在任意配置字符串值中引用环境变量： + + 在任何配置字符串值中使用 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -661,12 +648,12 @@ OpenClaw 会从父进程以及以下位置读取环境变量： - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*` - 缺失或为空的变量会在加载时抛出错误 - 使用 `$${VAR}` 转义以输出字面量 -- 可在 `$include` 文件中使用 +- 可在 `$include` 文件内工作 - 内联替换：`"${BASE}/v1"` → `"https://api.example.com/v1"` - + 对于支持 SecretRef 对象的字段，你可以使用： ```json5 @@ -699,22 +686,21 @@ OpenClaw 会从父进程以及以下位置读取环境变量： } ``` -SecretRef 详情（包括用于 `env`/`file`/`exec` 的 `secrets.providers`）位于[密钥管理](/zh-CN/gateway/secrets)。 -支持的凭据路径列在 [SecretRef 凭据表面](/zh-CN/reference/secretref-credential-surface)中。 +SecretRef 详情（包括用于 `env`/`file`/`exec` 的 `secrets.providers`）见 [Secrets Management](/zh-CN/gateway/secrets)。支持的凭证路径列在 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) 中。 -完整的优先级和来源见[环境](/zh-CN/help/environment)。 +完整优先级和来源请参阅 [Environment](/zh-CN/help/environment)。 ## 完整参考 -如需完整的逐字段参考，请参阅**[配置参考](/zh-CN/gateway/configuration-reference)**。 +如需完整的逐字段参考，请参阅 **[配置参考](/zh-CN/gateway/configuration-reference)**。 --- -_相关：[配置示例](/zh-CN/gateway/configuration-examples) · [配置参考](/zh-CN/gateway/configuration-reference) · [Doctor](/zh-CN/gateway/doctor)_ +_相关：[Configuration Examples](/zh-CN/gateway/configuration-examples) · [配置参考](/zh-CN/gateway/configuration-reference) · [Doctor](/zh-CN/gateway/doctor)_ ## 相关 - [配置参考](/zh-CN/gateway/configuration-reference) -- [配置示例](/zh-CN/gateway/configuration-examples) +- [Configuration examples](/zh-CN/gateway/configuration-examples) - [Gateway 网关运行手册](/zh-CN/gateway) diff --git a/docs/zh-CN/gateway/troubleshooting.md b/docs/zh-CN/gateway/troubleshooting.md index 66343461d..b86742ed4 100644 --- a/docs/zh-CN/gateway/troubleshooting.md +++ b/docs/zh-CN/gateway/troubleshooting.md @@ -1,24 +1,24 @@ --- read_when: - - 故障排除中心将你引导到这里，以便进行更深入的诊断 - - 你需要稳定的、基于症状的运行手册章节，并附上精确命令 + - 故障排除中心将你指引到这里，以便进行更深入的诊断 + - 你需要基于稳定症状、包含精确命令的运行手册章节 sidebarTitle: Troubleshooting -summary: Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除操作手册 +summary: Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除运行手册 title: 故障排除 x-i18n: - generated_at: "2026-05-01T20:37:47Z" + generated_at: "2026-05-03T17:11:05Z" model: gpt-5.5 provider: openai - source_hash: 815fbbca4d12b4b9c65b1172e07606d0eaf4c64df7fd6ca23a8f8d104b78c2a9 + source_hash: 19422615706ca09124b19dd3e21b2c13391d6daf2b1807e01b4ce2047d02e522 source_path: gateway/troubleshooting.md workflow: 16 --- -此页面是深入运行手册。如果你想先使用快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。 +本页是深入运行手册。如果你想先使用快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。 -## 命令阶梯 +## 命令排查顺序 -先按此顺序运行这些命令： +请先按以下顺序运行这些命令： ```bash openclaw status @@ -31,14 +31,14 @@ openclaw channels status --probe 预期的健康信号： - `openclaw gateway status` 显示 `Runtime: running`、`Connectivity probe: ok`，以及一行 `Capability: ...`。 -- `openclaw doctor` 未报告阻塞性的配置/服务问题。 -- `openclaw channels status --probe` 显示每个账号的实时传输协议状态，并在支持的地方显示探测/审计结果，例如 `works` 或 `audit ok`。 +- `openclaw doctor` 报告没有阻塞性的配置/服务问题。 +- `openclaw channels status --probe` 显示逐账号的实时传输状态，并在支持的位置显示探测/审计结果，例如 `works` 或 `audit ok`。 -## 安装分裂和新版配置保护 +## 脑裂安装与较新配置保护 -当 Gateway 网关服务在更新后意外停止，或者日志显示某个 `openclaw` 二进制文件早于最后写入 `openclaw.json` 的版本时，使用此部分。 +当 Gateway 网关服务在更新后意外停止，或日志显示某个 `openclaw` 二进制文件早于最后写入 `openclaw.json` 的版本时，使用本节。 -OpenClaw 会用 `meta.lastTouchedVersion` 标记配置写入。只读命令仍可检查由更新版 OpenClaw 写入的配置，但来自旧版二进制文件的进程和服务变更会拒绝继续。被阻止的操作包括 Gateway 网关服务启动、停止、重启、卸载、强制服务重装、服务模式 Gateway 网关启动，以及 `gateway --force` 端口清理。 +OpenClaw 会用 `meta.lastTouchedVersion` 标记配置写入。只读命令仍可检查由较新版 OpenClaw 写入的配置，但进程和服务变更操作会拒绝从较旧的二进制文件继续。被阻止的操作包括 Gateway 网关服务启动、停止、重启、卸载、强制服务重装、服务模式 Gateway 网关启动，以及 `gateway --force` 端口清理。 ```bash which openclaw @@ -52,7 +52,7 @@ openclaw config get meta.lastTouchedVersion 修复 `PATH`，让 `openclaw` 解析到较新的安装，然后重新运行该操作。 - 从较新的安装中重新安装预期的 Gateway 网关服务： + 从较新的安装重新安装目标 Gateway 网关服务： ```bash openclaw gateway install --force @@ -60,18 +60,18 @@ openclaw config get meta.lastTouchedVersion ``` - - 移除仍指向旧 `openclaw` 二进制文件的过时系统包或旧包装器条目。 + + 移除仍指向旧 `openclaw` 二进制文件的过期系统包或旧包装器条目。 -仅在有意降级或紧急恢复时，为单个命令设置 `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1`。正常操作时不要设置它。 +仅在有意降级或紧急恢复时，为单条命令设置 `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1`。正常操作时保持未设置。 -## Anthropic 429 长上下文需要额外用量资格 +## Anthropic 429 长上下文需要额外用量 -当日志/错误包含以下内容时使用：`HTTP 429: rate_limit_error: Extra usage is required for long context requests`。 +当日志/错误包含以下内容时使用本节：`HTTP 429: rate_limit_error: Extra usage is required for long context requests`。 ```bash openclaw logs --follow @@ -79,10 +79,10 @@ openclaw models status openclaw config get agents.defaults.models ``` -查看： +检查以下情况： -- 选中的 Anthropic Opus/Sonnet 模型具有 `params.context1m: true`。 -- 当前 Anthropic 凭证不符合长上下文使用资格。 +- 所选的 Anthropic Opus/Sonnet 模型设置了 `params.context1m: true`。 +- 当前 Anthropic 凭证不符合长上下文使用条件。 - 请求只在需要 1M beta 路径的长会话/模型运行中失败。 修复选项： @@ -91,26 +91,26 @@ openclaw config get agents.defaults.models 为该模型禁用 `context1m`，以回退到普通上下文窗口。 - - 使用符合长上下文请求资格的 Anthropic 凭证，或切换到 Anthropic API key。 + + 使用符合长上下文请求条件的 Anthropic 凭证，或切换到 Anthropic API 密钥。 - 配置回退模型，让运行在 Anthropic 长上下文请求被拒绝时继续进行。 + 配置回退模型，以便在 Anthropic 长上下文请求被拒绝时运行仍能继续。 相关： - [Anthropic](/zh-CN/providers/anthropic) -- [令牌使用和成本](/zh-CN/reference/token-use) +- [令牌使用量和成本](/zh-CN/reference/token-use) - [为什么我会看到来自 Anthropic 的 HTTP 429？](/zh-CN/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) -## 本地 OpenAI 兼容后端通过直接探测，但智能体运行失败 +## 本地 OpenAI 兼容后端能通过直接探测，但智能体运行失败 -在以下情况下使用： +当出现以下情况时使用本节： -- `curl ... /v1/models` 正常工作 -- 很小的直接 `/v1/chat/completions` 调用正常工作 +- `curl ... /v1/models` 可用 +- 微型直接 `/v1/chat/completions` 调用可用 - OpenClaw 模型运行只在普通智能体轮次中失败 ```bash @@ -122,29 +122,29 @@ openclaw infer model run --model --prompt "hi" --json openclaw logs --follow ``` -查看： +检查以下情况： -- 直接的小请求成功，但 OpenClaw 运行只在较大提示词上失败 -- 出现 `model_not_found` 或 404 错误，即使直接 `/v1/chat/completions` - 可使用同一个裸模型 ID 正常工作 -- 关于 `messages[].content` 预期为字符串的后端错误 +- 直接微型调用成功，但 OpenClaw 运行只在较大的提示词上失败 +- 即使直接 `/v1/chat/completions` + 使用同一个裸模型 ID 可用，也出现 `model_not_found` 或 404 错误 +- 后端错误提示 `messages[].content` 期望字符串 - 使用 OpenAI 兼容本地后端时，间歇出现 `incomplete turn detected ... stopReason=stop payloads=0` 警告 -- 只在较大的提示词令牌数或完整智能体运行时提示词下出现的后端崩溃 +- 只在更大的提示词令牌数量或完整智能体运行时提示词下出现的后端崩溃 - - 本地 MLX/vLLM 风格服务器出现 `model_not_found` → 验证 `baseUrl` 包含 `/v1`，对于 `/v1/chat/completions` 后端，`api` 是 `"openai-completions"`，并且 `models.providers..models[].id` 是裸的提供商本地 ID。选择它时加一次提供商前缀，例如 `mlx/mlx-community/Qwen3-30B-A3B-6bit`；将目录条目保持为 `mlx-community/Qwen3-30B-A3B-6bit`。 + - 本地 MLX/vLLM 风格服务器出现 `model_not_found` → 验证 `baseUrl` 包含 `/v1`，对于 `/v1/chat/completions` 后端，`api` 是 `"openai-completions"`，并且 `models.providers..models[].id` 是裸提供商本地 ID。选择时加一次提供商前缀，例如 `mlx/mlx-community/Qwen3-30B-A3B-6bit`；目录条目保持为 `mlx-community/Qwen3-30B-A3B-6bit`。 - `messages[...].content: invalid type: sequence, expected a string` → 后端拒绝结构化 Chat Completions 内容部分。修复：设置 `models.providers..models[].compat.requiresStringContent: true`。 - - `incomplete turn detected ... stopReason=stop payloads=0` → 后端完成了 Chat Completions 请求，但未为该轮次返回用户可见的助手文本。OpenClaw 会对可安全重放的空 OpenAI 兼容轮次重试一次；持续失败通常意味着后端正在发出空内容/非文本内容，或抑制最终回答文本。 - - 直接的小请求成功，但 OpenClaw 智能体运行因后端/模型崩溃而失败（例如某些 `inferrs` 构建上的 Gemma）→ OpenClaw 传输协议很可能已经正确；后端在更大的智能体运行时提示词形态上失败。 - - 禁用工具后失败减少但未消失 → 工具 schema 是压力的一部分，但剩余问题仍是上游模型/服务器容量或后端 bug。 + - `incomplete turn detected ... stopReason=stop payloads=0` → 后端完成了 Chat Completions 请求，但没有为该轮次返回用户可见的助手文本。OpenClaw 会对可安全重放的空 OpenAI 兼容轮次重试一次；持续失败通常意味着后端正在发出空内容/非文本内容，或抑制最终答案文本。 + - 直接微型请求成功，但 OpenClaw 智能体运行因后端/模型崩溃而失败（例如某些 `inferrs` 构建上的 Gemma）→ OpenClaw 传输层很可能已经正确；失败发生在后端处理更大的智能体运行时提示词形状时。 + - 禁用工具后失败减少但没有消失 → 工具模式是压力来源的一部分，但剩余问题仍是上游模型/服务器容量或后端错误。 - 1. 对仅支持字符串的 Chat Completions 后端设置 `compat.requiresStringContent: true`。 - 2. 对无法可靠处理 OpenClaw 工具 schema 表面的模型/后端设置 `compat.supportsTools: false`。 - 3. 尽可能降低提示词压力：更小的工作区启动内容、更短的会话历史、更轻量的本地模型，或具有更强长上下文支持的后端。 - 4. 如果很小的直接请求持续通过，而 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器/模型限制，并用已接受的 payload 形态向上游提交复现。 + 1. 为仅支持字符串的 Chat Completions 后端设置 `compat.requiresStringContent: true`。 + 2. 对无法可靠处理 OpenClaw 工具模式接口面的模型/后端设置 `compat.supportsTools: false`。 + 3. 在可行时降低提示词压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或具备更强长上下文支持的后端。 + 4. 如果微型直接请求持续通过，但 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器/模型限制，并向该项目提交一个包含已接受载荷形状的复现。 @@ -154,9 +154,9 @@ openclaw logs --follow - [本地模型](/zh-CN/gateway/local-models) - [OpenAI 兼容端点](/zh-CN/gateway/configuration-reference#openai-compatible-endpoints) -## 没有回复 +## 无回复 -如果渠道已启动但没有任何响应，请先检查路由和策略，再重新连接任何内容。 +如果渠道已启动但没有任何回复，请先检查路由和策略，再重新连接任何内容。 ```bash openclaw status @@ -166,17 +166,17 @@ openclaw config get channels openclaw logs --follow ``` -查看： +检查以下情况： -- 私信发送者的配对待处理。 +- 私信发送者有待处理的配对。 - 群组提及门控（`requireMention`、`mentionPatterns`）。 -- 渠道/群组 allowlist 不匹配。 +- 渠道/群组允许列表不匹配。 常见特征： - `drop guild message (mention required` → 群组消息会被忽略，直到被提及。 - `pairing request` → 发送者需要批准。 -- `blocked` / `allowlist` → 发送者/渠道已被策略过滤。 +- `blocked` / `allowlist` → 发送者/渠道被策略过滤。 相关： @@ -184,9 +184,9 @@ openclaw logs --follow - [群组](/zh-CN/channels/groups) - [配对](/zh-CN/channels/pairing) -## Dashboard 控制 UI 连接 +## 仪表板控制 UI 连接性 -当 dashboard/control UI 无法连接时，请验证 URL、认证模式和安全上下文假设。 +当仪表板/控制 UI 无法连接时，请验证 URL、认证模式和安全上下文假设。 ```bash openclaw gateway status @@ -196,45 +196,45 @@ openclaw doctor openclaw gateway status --json ``` -查看： +检查以下情况： -- 正确的探测 URL 和 dashboard URL。 +- 正确的探测 URL 和仪表板 URL。 - 客户端与 Gateway 网关之间的认证模式/令牌不匹配。 -- 在需要设备身份的地方使用 HTTP。 +- 在需要设备身份的位置使用了 HTTP。 - `device identity required` → 非安全上下文或缺少设备认证。 - - `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正在从非 loopback 浏览器源连接，但没有显式 allowlist）。 - - `device nonce required` / `device nonce mismatch` → 客户端未完成基于挑战的设备认证流程（`connect.challenge` + `device.nonce`）。 - - `device signature invalid` / `device signature expired` → 客户端为当前握手签名了错误 payload（或时间戳过期）。 - - `AUTH_TOKEN_MISMATCH` 且带有 `canRetryWithDeviceToken=true` → 客户端可以用缓存的设备令牌执行一次受信重试。 - - 该缓存令牌重试会复用与已配对设备令牌一起存储的缓存 scope 集。显式 `deviceToken` / 显式 `scopes` 调用方会保留其请求的 scope 集。 - - 在该重试路径之外，连接认证优先级是先显式共享令牌/密码，然后是显式 `deviceToken`，再是已存储设备令牌，最后是 bootstrap token。 - - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, ip}` 的失败尝试会在限流器记录失败之前被串行化。因此，同一客户端的两个并发错误重试可能会让第二次尝试显示 `retry later`，而不是两个普通不匹配。 - - 浏览器源 loopback 客户端出现 `too many failed authentication attempts (retry later)` → 来自同一规范化 `Origin` 的重复失败会被暂时锁定；另一个 localhost 源使用单独的桶。 + - `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正从没有显式允许列表的非 loopback 浏览器源连接）。 + - `device nonce required` / `device nonce mismatch` → 客户端未完成基于质询的设备认证流程（`connect.challenge` + `device.nonce`）。 + - `device signature invalid` / `device signature expired` → 客户端为当前握手签名了错误的载荷（或过期时间戳）。 + - `AUTH_TOKEN_MISMATCH` 且带有 `canRetryWithDeviceToken=true` → 客户端可以使用缓存的设备令牌做一次受信任重试。 + - 该缓存令牌重试会复用与已配对设备令牌一起存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则保留其请求的作用域集合。 + - 在该重试路径之外，connect 认证优先级是：显式共享令牌/密码优先，然后是显式 `deviceToken`，再是已存储设备令牌，最后是引导令牌。 + - 在异步 Tailscale Serve 控制 UI 路径上，同一 `{scope, ip}` 的失败尝试会在限流器记录失败前被串行化。因此，来自同一客户端的两个错误并发重试可能会在第二次尝试时显示 `retry later`，而不是两个普通的不匹配。 + - 来自浏览器源 loopback 客户端的 `too many failed authentication attempts (retry later)` → 来自同一个规范化 `Origin` 的重复失败会被临时锁定；另一个 localhost 源使用单独的桶。 - 该重试后仍反复出现 `unauthorized` → 共享令牌/设备令牌漂移；刷新令牌配置，并在需要时重新批准/轮换设备令牌。 - - `gateway connect failed:` → host/port/url 目标错误。 + - `gateway connect failed:` → 主机/端口/URL 目标错误。 -### 认证详情代码快速映射 +### 认证详情代码速查表 使用失败 `connect` 响应中的 `error.details.code` 来选择下一步操作： -| 详情代码 | 含义 | 建议操作 | +| 详细代码 | 含义 | 推荐操作 | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | 客户端未发送必需的共享令牌。 | 在客户端粘贴/设置令牌并重试。对于仪表板路径：`openclaw config get gateway.auth.token`，然后粘贴到控制 UI 设置中。 | -| `AUTH_TOKEN_MISMATCH` | 共享令牌与 Gateway 网关认证令牌不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次受信任重试。缓存令牌重试会复用已存储的已批准作用域；显式 `deviceToken` / `scopes` 调用方会保留请求的作用域。如果仍然失败，请运行[令牌漂移恢复检查清单](/zh-CN/cli/devices#token-drift-recovery-checklist)。 | -| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的每设备令牌已过期或被撤销。 | 使用[设备 CLI](/zh-CN/cli/devices) 轮换/重新批准设备令牌，然后重新连接。 | -| `PAIRING_REQUIRED` | 设备身份需要批准。检查 `error.details.reason` 是否为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。 | 批准待处理请求：`openclaw devices list`，然后执行 `openclaw devices approve `。作用域/角色升级在你审查请求的访问权限后使用同一流程。 | +| `AUTH_TOKEN_MISSING` | 客户端没有发送必需的共享令牌。 | 在客户端粘贴/设置令牌，然后重试。对于控制台路径：先运行 `openclaw config get gateway.auth.token`，然后粘贴到控制 UI 设置中。 | +| `AUTH_TOKEN_MISMATCH` | 共享令牌与 Gateway 网关身份验证令牌不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次受信任重试。缓存令牌重试会复用已存储的已批准作用域；显式 `deviceToken` / `scopes` 调用方会保留请求的作用域。如果仍然失败，请运行[令牌漂移恢复清单](/zh-CN/cli/devices#token-drift-recovery-checklist)。 | +| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的按设备令牌已过期或已被撤销。 | 使用[设备 CLI](/zh-CN/cli/devices) 轮换/重新批准设备令牌，然后重新连接。 | +| `PAIRING_REQUIRED` | 设备身份需要批准。检查 `error.details.reason` 是否为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。 | 批准待处理请求：先运行 `openclaw devices list`，再运行 `openclaw devices approve `。作用域/角色升级在你审查请求的访问权限后使用相同流程。 | -使用共享 Gateway 网关令牌/密码认证的直接 loopback 后端 RPC 不应依赖 CLI 的已配对设备作用域基线。如果子智能体或其他内部调用仍然因 `scope-upgrade` 失败，请确认调用方使用的是 `client.id: "gateway-client"` 和 `client.mode: "backend"`，且没有强制使用显式 `deviceIdentity` 或设备令牌。 +使用共享 Gateway 网关令牌/密码进行身份验证的直接环回后端 RPC 不应依赖 CLI 的已配对设备作用域基线。如果 subagent 或其他内部调用仍因 `scope-upgrade` 失败，请确认调用方正在使用 `client.id: "gateway-client"` 和 `client.mode: "backend"`，并且没有强制使用显式 `deviceIdentity` 或设备令牌。 -设备认证 v2 迁移检查： +设备身份验证 v2 迁移检查： ```bash openclaw --version @@ -245,33 +245,33 @@ openclaw gateway status 如果日志显示 nonce/签名错误，请更新连接客户端并验证它： - - 客户端等待 Gateway 网关签发的 `connect.challenge`。 + + 客户端等待 Gateway 网关发出的 `connect.challenge`。 - - 客户端签署与 challenge 绑定的载荷。 + + 客户端对绑定挑战的载荷进行签名。 - - 客户端发送 `connect.params.device.nonce`，并使用相同的 challenge nonce。 + + 客户端发送带有相同挑战 nonce 的 `connect.params.device.nonce`。 如果 `openclaw devices rotate` / `revoke` / `remove` 意外被拒绝： -- 已配对设备令牌会话只能管理**自己的**设备，除非调用方也具有 `operator.admin` -- `openclaw devices rotate --scope ...` 只能请求调用方会话已持有的 operator 作用域 +- 已配对设备令牌会话只能管理**自己的**设备，除非调用方还拥有 `operator.admin` +- `openclaw devices rotate --scope ...` 只能请求调用方会话已经持有的操作员作用域 相关： -- [配置](/zh-CN/gateway/configuration)（Gateway 网关认证模式） +- [配置](/zh-CN/gateway/configuration)（Gateway 网关身份验证模式） - [控制 UI](/zh-CN/web/control-ui) - [设备](/zh-CN/cli/devices) - [远程访问](/zh-CN/gateway/remote) -- [受信任代理认证](/zh-CN/gateway/trusted-proxy-auth) +- [受信任代理身份验证](/zh-CN/gateway/trusted-proxy-auth) ## Gateway 网关服务未运行 -当服务已安装但进程无法保持运行时使用此项。 +在服务已安装但进程无法保持运行时使用此项。 ```bash openclaw gateway status @@ -283,33 +283,34 @@ openclaw gateway status --deep # also scan system-level services 查找： -- `Runtime: stopped` 以及退出提示。 +- 带有退出提示的 `Runtime: stopped`。 - 服务配置不匹配（`Config (cli)` 与 `Config (service)`）。 - 端口/监听器冲突。 - 使用 `--deep` 时出现额外的 launchd/systemd/schtasks 安装。 - `Other gateway-like services detected (best effort)` 清理提示。 - - - `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 本地 Gateway 网关模式未启用，或配置文件被覆盖并丢失了 `gateway.mode`。修复：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup` 以重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。 - - `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径（令牌/密码，或已配置的受信任代理）的情况下绑定到非 loopback 地址。 + + - `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 本地 Gateway 网关模式未启用，或者配置文件被覆盖并丢失了 `gateway.mode`。修复：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup` 来重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。 + - `refusing to bind gateway ... without auth` → 没有有效 Gateway 网关身份验证路径（令牌/密码，或已配置的受信任代理）时绑定到了非环回地址。 - `another gateway instance is already listening` / `EADDRINUSE` → 端口冲突。 - - `Other gateway-like services detected (best effort)` → 存在陈旧或并行的 launchd/systemd/schtasks 单元。大多数设置应在每台机器上保留一个 Gateway 网关；如果确实需要多个，请隔离端口 + 配置/状态/工作区。参见 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。 - - 来自 Doctor 的 `System-level OpenClaw gateway service detected` → 存在一个 systemd 系统单元，而用户级服务缺失。在允许 Doctor 安装用户服务之前移除或禁用重复项，或者如果系统单元是预期的监督器，请设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。 - - `Gateway service port does not match current gateway config` → 已安装的监督器仍然固定旧的 `--port`。运行 `openclaw doctor --fix` 或 `openclaw gateway install --force`，然后重启 Gateway 网关服务。 + - `Other gateway-like services detected (best effort)` → 存在陈旧或并行的 launchd/systemd/schtasks 单元。多数设置应在每台机器上只保留一个 Gateway 网关；如果确实需要多个，请隔离端口 + 配置/状态/工作区。请参阅 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。 + - Doctor 输出的 `System-level OpenClaw gateway service detected` → 存在 systemd 系统单元，而用户级服务缺失。在允许 Doctor 安装用户服务之前，移除或禁用重复项；如果该系统单元是预期的监督器，请设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。 + - `Gateway service port does not match current gateway config` → 已安装的监督器仍固定旧的 `--port`。运行 `openclaw doctor --fix` 或 `openclaw gateway install --force`，然后重启 Gateway 网关服务。 相关： -- [后台执行和进程工具](/zh-CN/gateway/background-process) +- [后台 exec 和进程工具](/zh-CN/gateway/background-process) - [配置](/zh-CN/gateway/configuration) - [Doctor](/zh-CN/gateway/doctor) -## Gateway 网关恢复了最后已知良好配置 +## Gateway 网关拒绝了无效配置 -当 Gateway 网关启动，但日志显示它恢复了 `openclaw.json` 时使用此项。 +在 Gateway 网关启动因 `Invalid config` 失败，或热重载日志提示 +它跳过了无效编辑时使用此项。 ```bash openclaw logs --follow @@ -320,22 +321,22 @@ openclaw doctor 查找： -- `Config auto-restored from last-known-good` -- `gateway: invalid config was restored from last-known-good backup` -- `config reload restored last-known-good config after invalid-config` -- 活动配置旁带时间戳的 `openclaw.json.clobbered.*` 文件 -- 以 `Config recovery warning` 开头的主智能体系统事件 +- `Invalid config at ...` +- `config reload skipped (invalid config): ...` +- `Config write rejected: ...` +- 活动配置旁带时间戳的 `openclaw.json.rejected.*` 文件 +- 如果 `doctor --fix` 修复了损坏的直接编辑，则会有带时间戳的 `openclaw.json.clobbered.*` 文件 - - - 被拒绝的配置在启动或热重载期间未通过验证。 - - OpenClaw 将被拒绝的载荷保留为 `.clobbered.*`。 - - 活动配置已从最后一次验证通过的最后已知良好副本恢复。 - - 下一个主智能体轮次会收到警告，不要盲目重写被拒绝的配置。 - - 如果所有验证问题都位于 `plugins.entries....` 下，OpenClaw 不会恢复整个文件。插件本地故障会保持显眼，而不相关的用户设置仍保留在活动配置中。 + + - 配置在启动、热重载或 OpenClaw 拥有的写入期间未通过验证。 + - Gateway 网关启动会失败关闭，而不是重写 `openclaw.json`。 + - 热重载会跳过无效的外部编辑，并保持当前运行时配置处于活动状态。 + - OpenClaw 拥有的写入会在提交前拒绝无效/破坏性载荷，并保存 `.rejected.*`。 + - `openclaw doctor --fix` 负责修复。它可以移除非 JSON 前缀，或恢复最后已知良好副本，同时将被拒绝的载荷保留为 `.clobbered.*`。 - + ```bash CONFIG="$(openclaw config file)" ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head @@ -344,20 +345,21 @@ openclaw doctor openclaw doctor ``` - - - `.clobbered.*` 存在 → 外部直接编辑或启动读取已被恢复。 - - `.rejected.*` 存在 → OpenClaw 拥有的配置写入在提交前未通过 schema 或覆盖检查。 - - `Config write rejected:` → 写入试图丢弃必需结构、让文件大幅缩小，或持久化无效配置。 - - `Rejected validation details:` → 恢复日志或主智能体通知包含导致恢复的 schema 路径，例如 `agents.defaults.execution` 或 `gateway.auth.password.source`。 - - `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good` 或 `size-drop-vs-last-good:*` → 启动时将当前文件视为被覆盖，因为与最后已知良好备份相比，它丢失了字段或大小减少。 - - `Config last-known-good promotion skipped` → 候选项包含经过脱敏的密钥占位符，例如 `***`。 + + - 存在 `.clobbered.*` → Doctor 在修复活动配置时保留了损坏的外部编辑。 + - 存在 `.rejected.*` → OpenClaw 拥有的配置写入在提交前未通过 schema 或覆盖检查。 + - `Config write rejected:` → 写入尝试丢弃必需结构、大幅缩小文件，或持久化无效配置。 + - `config reload skipped (invalid config):` → 直接编辑未通过验证，并被正在运行的 Gateway 网关忽略。 + - `Invalid config at ...` → 启动在 Gateway 网关服务启动前失败。 + - `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good` 或 `size-drop-vs-last-good:*` → OpenClaw 拥有的写入被拒绝，因为相比最后已知良好备份，它丢失了字段或大小。 + - `Config last-known-good promotion skipped` → 候选内容包含已遮盖的密钥占位符，例如 `***`。 - - 1. 如果恢复后的活动配置正确，请保留它。 - 2. 仅从 `.clobbered.*` 或 `.rejected.*` 复制预期键，然后使用 `openclaw config set` 或 `config.patch` 应用它们。 + + 1. 运行 `openclaw doctor --fix`，让 Doctor 修复带前缀/被覆盖的配置，或恢复最后已知良好配置。 + 2. 仅从 `.clobbered.*` 或 `.rejected.*` 复制预期键名，然后使用 `openclaw config set` 或 `config.patch` 应用它们。 3. 在重启前运行 `openclaw config validate`。 - 4. 如果手动编辑，请保留完整 JSON5 配置，而不只是你想更改的局部对象。 + 4. 如果你手动编辑，请保留完整 JSON5 配置，而不只是你想修改的部分对象。 @@ -370,7 +372,7 @@ openclaw doctor ## Gateway 网关探测警告 -当 `openclaw gateway probe` 能够到达某个对象，但仍打印警告块时使用此项。 +在 `openclaw gateway probe` 访问到某个目标，但仍打印警告块时使用此项。 ```bash openclaw gateway probe @@ -381,16 +383,16 @@ openclaw gateway probe --ssh user@gateway-host 查找： - JSON 输出中的 `warnings[].code` 和 `primaryTargetId`。 -- 警告是否与 SSH 回退、多个 Gateway 网关、缺失作用域或未解析的认证引用有关。 +- 警告是否与 SSH 回退、多个 Gateway 网关、缺失作用域或未解析的身份验证引用有关。 常见特征： -- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍然尝试了直接配置目标/loopback 目标。 -- `multiple reachable gateways detected` → 多个目标有响应。通常这表示有意的多 Gateway 网关设置，或陈旧/重复的监听器。 -- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详情 RPC 受作用域限制；请配对设备身份，或使用带有 `operator.read` 的凭据。 -- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → 连接成功，但完整诊断 RPC 集超时或失败。将其视为可到达但诊断降级的 Gateway 网关；在 `--json` 输出中比较 `connect.ok` 和 `connect.rpcOk`。 -- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关有响应，但此客户端在正常 operator 访问前仍需要配对/批准。 -- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 此命令路径中，失败目标的认证材料不可用。 +- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但该命令仍尝试了直接配置/环回目标。 +- `multiple reachable gateways detected` → 有多个目标响应。通常这意味着有意的多 Gateway 网关设置，或陈旧/重复的监听器。 +- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详细 RPC 受作用域限制；请配对设备身份，或使用具有 `operator.read` 的凭据。 +- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → 连接成功，但完整诊断 RPC 集超时或失败。将其视为可达但诊断能力降级的 Gateway 网关；比较 `--json` 输出中的 `connect.ok` 和 `connect.rpcOk`。 +- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关已响应，但此客户端仍需要配对/批准后才能获得正常操作员访问权限。 +- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 失败目标在此命令路径中无法使用身份验证材料。 相关： @@ -398,9 +400,9 @@ openclaw gateway probe --ssh user@gateway-host - [同一主机上的多个 Gateway 网关](/zh-CN/gateway#multiple-gateways-same-host) - [远程访问](/zh-CN/gateway/remote) -## 渠道已连接，但消息未流动 +## 渠道已连接，但消息没有流动 -如果渠道状态为已连接但消息流已停止，请关注策略、权限和渠道特定的投递规则。 +如果渠道状态为已连接但消息流已中断，请重点检查策略、权限和特定渠道的投递规则。 ```bash openclaw channels status --probe @@ -413,13 +415,13 @@ openclaw config get channels 查找： - 私信策略（`pairing`、`allowlist`、`open`、`disabled`）。 -- 群组 allowlist 和提及要求。 +- 群组允许列表和提及要求。 - 缺少渠道 API 权限/作用域。 常见特征： -- `mention required` → 消息被群组提及策略忽略。 -- `pairing` / 待批准跟踪信息 → 发送者未获批准。 +- `mention required` → 消息因群组提及策略被忽略。 +- `pairing` / 待批准跟踪 → 发送者未获批准。 - `missing_scope`、`not_in_channel`、`Forbidden`、`401/403` → 渠道认证/权限问题。 相关： @@ -431,7 +433,7 @@ openclaw config get channels ## Cron 和 Heartbeat 投递 -如果 cron 或 Heartbeat 未运行或未投递，请先验证调度器状态，再验证投递目标。 +如果 cron 或 Heartbeat 没有运行或没有投递，请先验证调度器状态，再验证投递目标。 ```bash openclaw cron status @@ -441,21 +443,21 @@ openclaw system heartbeat last openclaw logs --follow ``` -检查： +查找： -- Cron 已启用，并且存在下一次唤醒。 +- Cron 已启用，并且存在下一次唤醒时间。 - 作业运行历史状态（`ok`、`skipped`、`error`）。 - Heartbeat 跳过原因（`quiet-hours`、`requests-in-flight`、`cron-in-progress`、`lanes-busy`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。 - + - `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。 - `cron: timer tick failed` → 调度器 tick 失败；检查文件/日志/运行时错误。 - - `heartbeat skipped` 且 `reason=quiet-hours` → 不在活跃时间窗口内。 + - `heartbeat skipped` 且 `reason=quiet-hours` → 当前不在活动时间窗口内。 - `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空行 / markdown 标题，因此 OpenClaw 会跳过模型调用。 - - `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但此 tick 没有到期任务。 + - `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但本次 tick 没有任何任务到期。 - `heartbeat: unknown accountId` → Heartbeat 投递目标的账号 ID 无效。 - - `heartbeat skipped` 且 `reason=dm-blocked` → Heartbeat 目标解析为私信式目的地，而 `agents.defaults.heartbeat.directPolicy`（或按智能体覆盖项）设置为 `block`。 + - `heartbeat skipped` 且 `reason=dm-blocked` → Heartbeat 目标解析为私信式目的地，而 `agents.defaults.heartbeat.directPolicy`（或单智能体覆盖项）设置为 `block`。 @@ -478,18 +480,18 @@ openclaw logs --follow openclaw status ``` -检查： +查找： - 节点在线，并具备预期能力。 -- 摄像头/麦克风/位置/屏幕的操作系统权限授权。 -- Exec 批准和 allowlist 状态。 +- 摄像头/麦克风/定位/屏幕的操作系统权限授予。 +- Exec 批准和允许列表状态。 常见特征： - `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须位于前台。 - `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → 缺少操作系统权限。 - `SYSTEM_RUN_DENIED: approval required` → exec 批准待处理。 -- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被 allowlist 阻止。 +- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被允许列表阻止。 相关： @@ -499,7 +501,7 @@ openclaw status ## 浏览器工具失败 -当浏览器工具操作失败但 Gateway 网关本身健康时，使用此部分。 +当浏览器工具操作失败但 Gateway 网关本身健康时使用此项。 ```bash openclaw browser status @@ -509,41 +511,41 @@ openclaw logs --follow openclaw doctor ``` -检查： +查找： -- 是否设置了 `plugins.allow`，并且包含 `browser`。 +- `plugins.allow` 是否已设置并包含 `browser`。 - 有效的浏览器可执行文件路径。 -- CDP 配置文件可达性。 -- `existing-session` / `user` 配置文件的本地 Chrome 可用性。 +- CDP 配置可达性。 +- `existing-session` / `user` 配置的本地 Chrome 可用性。 - + - `unknown command "browser"` 或 `unknown command 'browser'` → 内置浏览器插件被 `plugins.allow` 排除。 - - 浏览器工具缺失 / 不可用，而 `browser.enabled=true` → `plugins.allow` 排除了 `browser`，因此插件从未加载。 + - 浏览器工具缺失 / 不可用，而 `browser.enabled=true` → `plugins.allow` 排除了 `browser`，因此该插件从未加载。 - `Failed to start Chrome CDP on port` → 浏览器进程启动失败。 - `browser.executablePath not found` → 配置的路径无效。 - - `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的方案，例如 `file:` 或 `ftp:`。 + - `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不支持的协议，例如 `file:` 或 `ftp:`。 - `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口错误或超出范围。 - - `Playwright is not available in this gateway build; '' is unsupported.` → 当前 Gateway 网关安装缺少核心浏览器运行时依赖；重新安装或更新 OpenClaw，然后重启 Gateway 网关。ARIA 快照和基础页面截图仍可工作，但导航、AI 快照、CSS 选择器元素截图和 PDF 导出仍不可用。 + - `Playwright is not available in this gateway build; '' is unsupported.` → 当前 Gateway 网关安装缺少核心浏览器运行时依赖；重新安装或更新 OpenClaw，然后重启 Gateway 网关。ARIA 快照和基础页面截图仍然可用，但导航、AI 快照、CSS 选择器元素截图以及 PDF 导出仍不可用。 - - - `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session 还无法附加到所选浏览器数据目录。打开浏览器检查页面，启用远程调试，保持浏览器打开，批准第一次附加提示，然后重试。如果不需要已登录状态，优先使用托管的 `openclaw` 配置文件。 - - `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。 + + - `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session 尚无法附加到所选浏览器数据目录。打开浏览器检查页面，启用远程调试，保持浏览器打开，批准首次附加提示，然后重试。如果不需要登录状态，优先使用托管的 `openclaw` 配置。 + - `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置没有打开的本地 Chrome 标签页。 - `Remote CDP for profile "" is not reachable` → 配置的远程 CDP 端点无法从 Gateway 网关主机访问。 - - `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可达目标，或者 HTTP 端点已响应但 CDP WebSocket 仍无法打开。 + - `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置没有可达目标，或 HTTP 端点有响应，但 CDP WebSocket 仍无法打开。 - + - `fullPage is not supported for element screenshots` → 截图请求将 `--full-page` 与 `--ref` 或 `--element` 混用。 - `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` 截图调用必须使用页面捕获或快照 `--ref`，不能使用 CSS `--element`。 - - `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 上传钩子需要快照引用，而不是 CSS 选择器。 - - `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP 配置文件上，每次调用发送一个上传。 - - `existing-session dialog handling does not support timeoutMs.` → Chrome MCP 配置文件上的对话框钩子不支持超时覆盖。 - - `existing-session type does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置文件上的 `act:type` 省略 `timeoutMs`，或者在需要自定义超时时使用托管/CDP 浏览器配置文件。 - - `existing-session evaluate does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置文件上的 `act:evaluate` 省略 `timeoutMs`，或者在需要自定义超时时使用托管/CDP 浏览器配置文件。 - - `response body is not supported for existing-session profiles yet.` → `responsebody` 仍需要托管浏览器或原始 CDP 配置文件。 - - 附加专用或远程 CDP 配置文件上的过期视口 / 深色模式 / 区域设置 / 离线覆盖 → 运行 `openclaw browser stop --browser-profile ` 以关闭活跃控制会话并释放 Playwright/CDP 仿真状态，而无需重启整个 Gateway 网关。 + - `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 上传钩子需要快照 ref，而不是 CSS 选择器。 + - `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP 配置上，每次调用发送一个上传文件。 + - `existing-session dialog handling does not support timeoutMs.` → Chrome MCP 配置上的对话框钩子不支持超时覆盖。 + - `existing-session type does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置上的 `act:type` 省略 `timeoutMs`，或在需要自定义超时时使用托管/CDP 浏览器配置。 + - `existing-session evaluate does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置上的 `act:evaluate` 省略 `timeoutMs`，或在需要自定义超时时使用托管/CDP 浏览器配置。 + - `response body is not supported for existing-session profiles yet.` → `responsebody` 仍需要托管浏览器或原始 CDP 配置。 + - 仅附加或远程 CDP 配置上的过期视口 / 深色模式 / 区域设置 / 离线覆盖项 → 运行 `openclaw browser stop --browser-profile ` 关闭活动控制会话并释放 Playwright/CDP 模拟状态，无需重启整个 Gateway 网关。 @@ -553,12 +555,12 @@ openclaw doctor - [浏览器（OpenClaw 托管）](/zh-CN/tools/browser) - [浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting) -## 如果你升级后某些内容突然损坏 +## 如果你升级后某些内容突然坏了 -大多数升级后的故障来自配置漂移，或现在开始执行的更严格默认值。 +大多数升级后故障都是配置漂移，或现在开始强制执行更严格的默认值。 - + ```bash openclaw gateway status openclaw config get gateway.mode @@ -566,10 +568,10 @@ openclaw doctor openclaw config get gateway.auth.mode ``` - 要检查的内容： + 检查内容： - 如果 `gateway.mode=remote`，CLI 调用可能会指向远程，而你的本地服务是正常的。 - - 显式 `--url` 调用不会回退到已存储的凭据。 + - 显式 `--url` 调用不会回退到已存储凭证。 常见特征： @@ -577,7 +579,7 @@ openclaw doctor - `unauthorized` → 端点可达，但认证错误。 - + ```bash openclaw config get gateway.bind openclaw config get gateway.auth.mode @@ -586,18 +588,18 @@ openclaw doctor openclaw logs --follow ``` - 要检查的内容： + 检查内容： - - 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享令牌/密码认证，或配置正确的非 loopback `trusted-proxy` 部署。 - - 像 `gateway.token` 这样的旧键不会替代 `gateway.auth.token`。 + - 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享 token/密码认证，或配置正确的非 loopback `trusted-proxy` 部署。 + - `gateway.token` 等旧键不能替代 `gateway.auth.token`。 常见特征： - - `refusing to bind gateway ... without auth` → 非 loopback 绑定没有有效的 Gateway 网关认证路径。 + - `refusing to bind gateway ... without auth` → 非 loopback 绑定缺少有效的 Gateway 网关认证路径。 - `Connectivity probe: failed`，但运行时正在运行 → Gateway 网关存活，但使用当前认证/url 无法访问。 - + ```bash openclaw devices list openclaw pairing list --channel [--account ] @@ -605,20 +607,20 @@ openclaw doctor openclaw doctor ``` - 要检查的内容： + 检查内容： - - dashboard/节点的设备批准待处理。 - - 策略或身份更改后的私信配对批准待处理。 + - 仪表板/节点存在待处理设备批准。 + - 策略或身份变更后存在待处理私信配对批准。 常见特征： - `device identity required` → 设备认证未满足。 - - `pairing required` → 发送者/设备必须获批准。 + - `pairing required` → 发送者/设备必须获批。 -如果检查后服务配置和运行时仍不一致，请从同一配置文件/状态目录重新安装服务元数据： +如果检查后服务配置和运行时仍不一致，请从同一个配置/状态目录重新安装服务元数据： ```bash openclaw gateway install --force diff --git a/docs/zh-CN/help/faq.md b/docs/zh-CN/help/faq.md index eb5d566a9..87923bbbc 100644 --- a/docs/zh-CN/help/faq.md +++ b/docs/zh-CN/help/faq.md @@ -1,37 +1,37 @@ --- read_when: - 解答常见的设置、安装、新手引导或运行时支持问题 - - 在深入调试之前先分诊用户报告的问题 + - 在深入调试前对用户报告的问题进行分流排查 summary: 关于 OpenClaw 设置、配置和使用的常见问题 title: 常见问题 x-i18n: - generated_at: "2026-05-02T20:49:20Z" + generated_at: "2026-05-03T17:10:57Z" model: gpt-5.5 provider: openai - source_hash: 1437a84d7da0e4111edd46297b2a486e2da4f6e4a6cff0d69d6a372e85608130 + source_hash: 372220d62f872db1427b2836662bc8cc74e07d2cdfb651c105d3df25131855dd source_path: help/faq.md workflow: 16 --- -快速解答，以及面向真实部署（本地开发、VPS、多智能体、OAuth/API keys、模型故障转移）的深入故障排除。运行时诊断请参见[故障排除](/zh-CN/gateway/troubleshooting)。完整配置参考请参见[配置](/zh-CN/gateway/configuration)。 +快速答案，以及面向真实设置（本地开发、VPS、多智能体、OAuth/API key、模型故障转移）的更深入故障排除。运行时诊断请参见[故障排除](/zh-CN/gateway/troubleshooting)。完整配置参考请参见[配置](/zh-CN/gateway/configuration)。 ## 最初的六十秒：如果出现故障 -1. **快速状态（首次检查）** +1. **快速状态（首项检查）** ```bash openclaw status ``` - 快速本地摘要：OS + 更新、Gateway 网关/服务可达性、智能体/会话、提供商配置 + 运行时问题（当 Gateway 网关可达时）。 + 快速本地摘要：OS + 更新、gateway/服务可达性、智能体/会话、提供商配置 + 运行时问题（当 gateway 可达时）。 -2. **可粘贴的报告（可安全分享）** +2. **可粘贴报告（可安全共享）** ```bash openclaw status --all ``` - 只读诊断，包含日志尾部（token 已脱敏）。 + 只读诊断，包含日志尾部（令牌已脱敏）。 3. **守护进程 + 端口状态** @@ -48,7 +48,7 @@ x-i18n: ``` 运行实时 Gateway 网关健康探测，包括受支持时的渠道探测 - （需要可达的 Gateway 网关）。参见[健康检查](/zh-CN/gateway/health)。 + （需要可达的 Gateway 网关）。参见[健康](/zh-CN/gateway/health)。 5. **跟踪最新日志** @@ -56,7 +56,7 @@ x-i18n: openclaw logs --follow ``` - 如果 RPC 已停用，请回退到： + 如果 RPC 不可用，回退到： ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" @@ -79,83 +79,83 @@ x-i18n: openclaw health --verbose # shows the target URL + config path on errors ``` - 向正在运行的 Gateway 网关请求完整快照（仅 WS）。参见[健康检查](/zh-CN/gateway/health)。 + 向正在运行的 Gateway 网关请求完整快照（仅 WS）。参见[健康](/zh-CN/gateway/health)。 ## 快速开始和首次运行设置 -首次运行问答 —— 安装、新手引导、认证路径、订阅、初始故障 —— +首次运行问答 —— 安装、新手引导、凭证路由、订阅、初始失败 —— 位于[首次运行常见问题](/zh-CN/help/faq-first-run)。 ## 什么是 OpenClaw？ - OpenClaw 是一个在你自己的设备上运行的个人 AI 助手。它会在你已经使用的消息界面上回复（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat，以及 QQ Bot 等内置渠道插件），并且在受支持的平台上还可以使用语音 + 实时 Canvas。**Gateway 网关**是始终在线的控制平面；助手才是产品。 + OpenClaw 是你在自己设备上运行的个人 AI 助手。它会在你已经使用的消息界面上回复（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat，以及 QQ Bot 等内置渠道插件），还可以在受支持平台上提供语音 + 实时 Canvas。**Gateway 网关**是始终在线的控制平面；助手才是产品本身。 - OpenClaw 不“只是 Claude 包装器”。它是一个**本地优先的控制平面**，让你可以在**自己的硬件**上运行 - 能力完整的助手，从你已经使用的聊天应用访问它，具备 - 有状态会话、记忆和工具，而不必把工作流控制权交给托管式 + OpenClaw 不是“只是一个 Claude 包装器”。它是一个**本地优先的控制平面**，让你可以在**自己的硬件**上运行一个 + 能力强的助手，并从你已经使用的聊天应用访问它，具备 + 有状态会话、记忆和工具，而无需把你的工作流控制权交给托管 SaaS。 亮点： - - **你的设备，你的数据：** 在任何你想要的位置运行 Gateway 网关（Mac、Linux、VPS），并将 + - **你的设备，你的数据：**在任意位置运行 Gateway 网关（Mac、Linux、VPS），并将 工作区 + 会话历史保留在本地。 - - **真实渠道，而不是 Web 沙箱：** WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等， + - **真实渠道，而不是 Web 沙箱：**WhatsApp/Telegram/Slack/Discord/Signal/iMessage/等， 以及受支持平台上的移动语音和 Canvas。 - - **模型无关：** 使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按智能体路由 + - **模型无关：**使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按智能体路由 和故障转移。 - - **仅本地选项：** 运行本地模型，因此如果你愿意，**所有数据都可以留在你的设备上**。 - - **多智能体路由：** 按渠道、账号或任务拆分智能体，每个智能体都有自己的 + - **仅本地选项：**运行本地模型，因此如果你愿意，**所有数据都可以留在你的设备上**。 + - **多智能体路由：**按渠道、账号或任务分离智能体，每个智能体都有自己的 工作区和默认设置。 - - **开源且可定制：** 检查、扩展并自托管，没有供应商锁定。 + - **开源且易于改造：**无需供应商锁定，即可审查、扩展和自托管。 文档：[Gateway 网关](/zh-CN/gateway)、[渠道](/zh-CN/channels)、[多智能体](/zh-CN/concepts/multi-agent)、 [记忆](/zh-CN/concepts/memory)。 - - 适合作为起步的项目： + + 适合先做的项目： - - 构建一个网站（WordPress、Shopify，或简单静态站点）。 - - 原型化一个移动应用（大纲、界面、API 计划）。 - - 整理文件和文件夹（清理、命名、打标签）。 - - 连接 Gmail，并自动化摘要或跟进事项。 + - 构建一个网站（WordPress、Shopify 或简单静态站点）。 + - 原型设计一个移动应用（大纲、屏幕、API 计划）。 + - 整理文件和文件夹（清理、命名、标记）。 + - 连接 Gmail，并自动生成摘要或跟进事项。 - 它可以处理大型任务，但当你把任务拆成阶段并 - 使用子智能体并行处理时，效果最好。 + 它可以处理大型任务，但当你把任务拆分成多个阶段，并 + 使用子智能体并行工作时效果最好。 日常收益通常包括： - - **个人简报：** 汇总你关心的收件箱、日历和新闻。 - - **研究和起草：** 快速研究、摘要，以及邮件或文档初稿。 - - **提醒和跟进事项：** 由 cron 或 Heartbeat 驱动的提醒和检查清单。 - - **浏览器自动化：** 填写表单、收集数据，以及重复执行 Web 任务。 - - **跨设备协作：** 从你的手机发送任务，让 Gateway 网关在服务器上运行它，并在聊天中取回结果。 + - **个人简报：**汇总你关心的收件箱、日历和新闻。 + - **研究和起草：**快速研究、摘要，以及邮件或文档的初稿。 + - **提醒和跟进：**由 cron 或 Heartbeat 驱动的提醒和检查清单。 + - **浏览器自动化：**填写表单、收集数据，并重复执行 Web 任务。 + - **跨设备协作：**从手机发送任务，让 Gateway 网关在服务器上运行它，并在聊天中取回结果。 - - 可以，用于**调研、资质筛选和起草**。它可以扫描站点、构建候选名单、 - 总结潜在客户，并撰写外联或广告文案草稿。 + + 可以，用于**研究、资格筛选和起草**。它可以扫描网站、建立候选名单、 + 总结潜在客户，并起草外联内容或广告文案。 - 对于**外联或广告投放**，请保留人工审核。避免垃圾信息，遵守当地法律和 - 平台政策，并在发送前审查所有内容。最安全的模式是让 - OpenClaw 起草，然后由你批准。 + 对于**外联或广告投放**，请保留人工参与。避免垃圾信息，遵守当地法律和 + 平台政策，并在发送前审核所有内容。最安全的模式是让 + OpenClaw 起草，由你批准。 文档：[安全](/zh-CN/gateway/security)。 - - OpenClaw 是一个**个人助手**和协调层，不是 IDE 的替代品。需要在 repo 内进行最快的直接编码循环时，请使用 - Claude Code 或 Codex。需要持久记忆、跨设备访问和工具编排时，请使用 OpenClaw。 + + OpenClaw 是一个**个人助手**和协调层，而不是 IDE 的替代品。在代码仓库中进行最快的直接编码循环时，请使用 + Claude Code 或 Codex。当你需要持久记忆、跨设备访问和工具编排时，请使用 OpenClaw。 优势： @@ -173,69 +173,69 @@ x-i18n: ## Skills 和自动化 - - 使用托管覆盖，而不是编辑 repo 副本。将你的更改放在 `~/.openclaw/skills//SKILL.md` 中（或通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加文件夹）。优先级为 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`，因此托管覆盖仍会优先于内置 Skills，且无需触碰 git。如果你需要全局安装该 Skill，但只对部分智能体可见，请将共享副本保留在 `~/.openclaw/skills` 中，并用 `agents.defaults.skills` 和 `agents.list[].skills` 控制可见性。只有值得上游合并的编辑才应放在 repo 中并通过 PR 提交。 + + 使用受管覆盖，而不是编辑代码仓库副本。将你的更改放在 `~/.openclaw/skills//SKILL.md` 中（或通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加文件夹）。优先级是 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`，因此受管覆盖仍会优先于内置 Skills，而无需触碰 git。如果你需要全局安装该 Skill，但只对某些智能体可见，请将共享副本保留在 `~/.openclaw/skills` 中，并使用 `agents.defaults.skills` 和 `agents.list[].skills` 控制可见性。只有值得上游合入的编辑才应放在代码仓库中并以 PR 形式提交。 - 可以。通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加额外目录（最低优先级）。默认优先级为 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`。`clawhub` 默认安装到 `./skills`，OpenClaw 会在下一个会话中将其视为 `/skills`。如果该 Skill 只应对特定智能体可见，请搭配 `agents.defaults.skills` 或 `agents.list[].skills` 使用。 + 可以。通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加额外目录（最低优先级）。默认优先级是 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`。`clawhub` 默认安装到 `./skills`，OpenClaw 会在下一个会话中将其视为 `/skills`。如果该 Skill 只应对某些智能体可见，请搭配使用 `agents.defaults.skills` 或 `agents.list[].skills`。 当前支持的模式包括： - - **Cron 任务**：隔离任务可以为每个任务设置 `model` 覆盖。 + - **Cron 任务**：隔离任务可以按任务设置 `model` 覆盖。 - **子智能体**：将任务路由到具有不同默认模型的独立智能体。 - **按需切换**：随时使用 `/model` 切换当前会话模型。 - 参见 [Cron 任务](/zh-CN/automation/cron-jobs)、[多智能体路由](/zh-CN/concepts/multi-agent) 和 [Slash 命令](/zh-CN/tools/slash-commands)。 + 请参阅 [Cron 任务](/zh-CN/automation/cron-jobs)、[多智能体路由](/zh-CN/concepts/multi-agent) 和 [Slash 命令](/zh-CN/tools/slash-commands)。 - - 对长任务或并行任务使用**子智能体**。子智能体在自己的会话中运行、 - 返回摘要，并保持你的主聊天响应流畅。 + + 对长任务或并行任务使用**子智能体**。子智能体在自己的会话中运行， + 返回摘要，并保持你的主聊天响应及时。 - 让你的 bot “为此任务生成一个子智能体”，或使用 `/subagents`。 - 在聊天中使用 `/status` 查看 Gateway 网关当前正在做什么（以及它是否忙碌）。 + 让你的机器人“为此任务生成一个子智能体”，或使用 `/subagents`。 + 在聊天中使用 `/status` 查看 Gateway 网关当前正在执行什么（以及它是否繁忙）。 - Token 提示：长任务和子智能体都会消耗 token。如果在意成本，请通过 `agents.defaults.subagents.model` - 为子智能体设置更便宜的模型。 + Token 提示：长任务和子智能体都会消耗 Token。如果担心成本，请通过 + `agents.defaults.subagents.model` 为子智能体设置更便宜的模型。 文档：[子智能体](/zh-CN/tools/subagents)、[后台任务](/zh-CN/automation/tasks)。 - + 使用线程绑定。你可以将 Discord 线程绑定到子智能体或会话目标，这样该线程中的后续消息会保留在绑定的会话上。 基本流程： - - 使用带 `thread: true` 的 `sessions_spawn` 生成（也可以为持久后续跟进添加 `mode: "session"`）。 + - 使用 `sessions_spawn` 和 `thread: true` 生成（也可选择使用 `mode: "session"` 进行持久后续跟进）。 - 或使用 `/focus ` 手动绑定。 - 使用 `/agents` 检查绑定状态。 - 使用 `/session idle ` 和 `/session max-age ` 控制自动取消聚焦。 - - 使用 `/unfocus` 解除线程绑定。 + - 使用 `/unfocus` 分离线程。 必需配置： - 全局默认值：`session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours`。 - Discord 覆盖：`channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours`。 - - 生成时自动绑定：`channels.discord.threadBindings.spawnSessions` 默认为 `true`；将其设为 `false` 可禁用绑定到线程的会话生成。 + - 生成时自动绑定：`channels.discord.threadBindings.spawnSessions` 默认为 `true`；将其设为 `false` 可禁用线程绑定会话生成。 文档：[子智能体](/zh-CN/tools/subagents)、[Discord](/zh-CN/channels/discord)、[配置参考](/zh-CN/gateway/configuration-reference)、[Slash 命令](/zh-CN/tools/slash-commands)。 - - 先检查解析后的请求者路由： + + 先检查解析后的请求方路由： - - 完成模式的子智能体投递会优先使用任何已绑定线程或对话路由（如果存在）。 - - 如果完成来源只携带渠道，OpenClaw 会回退到请求者会话存储的路由（`lastChannel` / `lastTo` / `lastAccountId`），因此直接投递仍可成功。 - - 如果既没有绑定路由，也没有可用的存储路由，直接投递可能失败，结果会回退到排队会话投递，而不是立即发布到聊天。 - - 无效或过期目标仍可能强制回退到队列或导致最终投递失败。 - - 如果子项最后一条可见助手回复是精确的静默 token `NO_REPLY` / `no_reply`，或精确为 `ANNOUNCE_SKIP`，OpenClaw 会有意抑制公告，而不是发布过期的早期进度。 - - 如果子项在仅执行工具调用后超时，公告可以将其折叠成简短的部分进度摘要，而不是重放原始工具输出。 + - 完成模式子智能体交付会优先使用任何已绑定线程或会话路由（如果存在）。 + - 如果完成来源只携带一个渠道，OpenClaw 会回退到请求方会话存储的路由（`lastChannel` / `lastTo` / `lastAccountId`），这样直接交付仍可成功。 + - 如果既没有绑定路由，也没有可用的已存储路由，直接交付可能失败，结果会回退到排队的会话交付，而不是立即发布到聊天。 + - 无效或过期的目标仍可能强制回退到队列，或导致最终交付失败。 + - 如果子会话最后一条可见的助手回复正好是静默 Token `NO_REPLY` / `no_reply`，或正好是 `ANNOUNCE_SKIP`，OpenClaw 会有意抑制通知，而不是发布过期的较早进度。 + - 如果子会话在只有工具调用后超时，通知可以将其压缩为简短的部分进度摘要，而不是重放原始工具输出。 调试： @@ -248,13 +248,13 @@ x-i18n: - Cron 在 Gateway 网关进程内部运行。如果 Gateway 网关没有持续运行， + Cron 在 Gateway 网关进程内运行。如果 Gateway 网关没有持续运行， 定时任务就不会运行。 检查清单： - - 确认 cron 已启用（`cron.enabled`），且未设置 `OPENCLAW_SKIP_CRON`。 - - 检查 Gateway 网关是否 24/7 运行（无睡眠/重启）。 + - 确认 Cron 已启用（`cron.enabled`），并且未设置 `OPENCLAW_SKIP_CRON`。 + - 检查 Gateway 网关是否 24/7 运行（没有休眠/重启）。 - 验证该任务的时区设置（`--tz` 与主机时区）。 调试： @@ -264,21 +264,21 @@ x-i18n: openclaw cron runs --id --limit 50 ``` - 文档：[Cron 任务](/zh-CN/automation/cron-jobs)、[自动化与任务](/zh-CN/automation)。 + 文档：[Cron 任务](/zh-CN/automation/cron-jobs)、[自动化和任务](/zh-CN/automation)。 - - 请先检查投递模式： + + 先检查投递模式： - - `--no-deliver` / `delivery.mode: "none"` 表示预期不会发送运行器回退消息。 - - 缺少或无效的公告目标（`channel` / `to`）表示运行器跳过了出站投递。 - - 渠道认证失败（`unauthorized`、`Forbidden`）表示运行器尝试投递，但凭证阻止了它。 - - 静默的隔离结果（仅 `NO_REPLY` / `no_reply`）会被视为有意不可投递，因此运行器也会抑制排队的回退投递。 + - `--no-deliver` / `delivery.mode: "none"` 表示不会有预期的 runner 兜底发送。 + - 缺失或无效的公告目标（`channel` / `to`）表示 runner 已跳过出站投递。 + - 渠道认证失败（`unauthorized`、`Forbidden`）表示 runner 曾尝试投递，但凭证阻止了它。 + - 静默隔离结果（仅 `NO_REPLY` / `no_reply`）会被视为有意不可投递，因此 runner 也会抑制排队的兜底投递。 - 对于隔离的 cron 作业，当聊天路由可用时，智能体仍然可以使用 `message` - 工具直接发送。`--announce` 只控制运行器 - 回退路径，用于智能体尚未发送的最终文本。 + 对于隔离 cron 作业，只要有聊天路由可用，智能体仍可通过 `message` + 工具直接发送。`--announce` 只控制 runner + 兜底路径，用于智能体尚未发送的最终文本。 调试： @@ -291,13 +291,12 @@ x-i18n: - + 这通常是实时模型切换路径，而不是重复调度。 - 隔离的 cron 可以在活动 - 运行抛出 `LiveSessionModelSwitchError` 时持久化运行时模型交接并重试。重试会保留切换后的 + 隔离 cron 可以在活动运行抛出 `LiveSessionModelSwitchError` 时持久化运行时模型交接并重试。重试会保留切换后的 提供商/模型；如果切换携带了新的认证配置文件覆盖，cron - 也会在重试前将其持久化。 + 也会在重试前持久化该覆盖。 相关选择规则： @@ -306,7 +305,7 @@ x-i18n: - 然后是任何已存储的 cron 会话模型覆盖。 - 然后是正常的智能体/默认模型选择。 - 重试循环是有界的。在初始尝试加 2 次切换重试之后， + 重试循环有边界。初始尝试加上 2 次切换重试后， cron 会中止，而不是永久循环。 调试： @@ -338,33 +337,33 @@ x-i18n: 原生 `openclaw skills install` 会写入活动工作区的 `skills/` 目录。只有在你想发布或同步自己的 Skills 时，才需要安装单独的 `clawhub` CLI。 若要在多个智能体之间共享安装，请将 Skill 放在 - `~/.openclaw/skills` 下，并在需要限制哪些智能体可见时使用 + `~/.openclaw/skills` 下；如果想收窄哪些智能体能看到它，请使用 `agents.defaults.skills` 或 `agents.list[].skills`。 - + 可以。使用 Gateway 网关调度器： - **Cron 作业**用于计划任务或周期性任务（重启后仍会保留）。 - **Heartbeat** 用于“主会话”周期检查。 - - **隔离作业**用于发布摘要或投递到聊天的自治智能体。 + - **隔离作业**用于自主智能体发布摘要或投递到聊天。 文档：[Cron 作业](/zh-CN/automation/cron-jobs)、[自动化与任务](/zh-CN/automation)、 [Heartbeat](/zh-CN/gateway/heartbeat)。 - - 不能直接运行。macOS Skills 受 `metadata.openclaw.os` 加所需二进制文件约束，并且 Skills 只有在 **Gateway 网关主机**上符合条件时才会出现在系统提示中。在 Linux 上，除非你覆盖该限制，否则仅限 `darwin` 的 Skills（如 `apple-notes`、`apple-reminders`、`things-mac`）不会加载。 + + 不能直接运行。macOS Skills 受 `metadata.openclaw.os` 加上必需二进制文件约束，并且 Skills 只有在 **Gateway 网关主机**上符合条件时才会出现在系统提示中。在 Linux 上，仅限 `darwin` 的 Skills（如 `apple-notes`、`apple-reminders`、`things-mac`）不会加载，除非你覆盖该门控。 - 你有三种受支持的模式： + 有三种受支持的模式： **选项 A - 在 Mac 上运行 Gateway 网关（最简单）。** - 在存在 macOS 二进制文件的位置运行 Gateway 网关，然后从 Linux 通过[远程模式](#gateway-ports-already-running-and-remote-mode)或 Tailscale 连接。由于 Gateway 网关主机是 macOS，Skills 会正常加载。 + 在存在 macOS 二进制文件的地方运行 Gateway 网关，然后从 Linux 以[远程模式](#gateway-ports-already-running-and-remote-mode)或通过 Tailscale 连接。由于 Gateway 网关主机是 macOS，Skills 会正常加载。 - **选项 B - 使用 macOS 节点（无需 SSH）。** - 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并在 Mac 上将 **Node Run Commands** 设置为 “Always Ask” 或 “Always Allow”。当节点上存在所需二进制文件时，OpenClaw 可以将仅限 macOS 的 Skills 视为符合条件。智能体会通过 `nodes` 工具运行这些 Skills。如果你选择 “Always Ask”，在提示中批准 “Always Allow” 会将该命令加入允许列表。 + **选项 B - 使用 macOS 节点（无 SSH）。** + 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并在 Mac 上将 **Node Run Commands** 设为 "Always Ask" 或 "Always Allow"。当节点上存在所需二进制文件时，OpenClaw 可以将仅限 macOS 的 Skills 视为符合条件。智能体会通过 `nodes` 工具运行这些 Skills。如果你选择 "Always Ask"，在提示中批准 "Always Allow" 会将该命令加入允许列表。 **选项 C - 通过 SSH 代理 macOS 二进制文件（高级）。** 将 Gateway 网关保留在 Linux 上，但让所需 CLI 二进制文件解析为在 Mac 上运行的 SSH 包装器。然后覆盖 Skill 以允许 Linux，使其保持符合条件。 @@ -377,7 +376,7 @@ x-i18n: exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` - 2. 将包装器放到 Linux 主机的 `PATH` 上（例如 `~/bin/memo`）。 + 2. 将包装器放到 Linux 主机的 `PATH` 中（例如 `~/bin/memo`）。 3. 覆盖 Skill 元数据（工作区或 `~/.openclaw/skills`）以允许 Linux： ```markdown @@ -388,24 +387,24 @@ x-i18n: --- ``` - 4. 启动一个新会话，以便刷新 Skills 快照。 + 4. 启动新会话，让 Skills 快照刷新。 - 目前没有内置。 + 今天还没有内置。 选项： - - **自定义 Skill / 插件：** 最适合可靠的 API 访问（Notion/HeyGen 都有 API）。 - - **浏览器自动化：** 无需代码也可工作，但速度较慢且更脆弱。 + - **自定义 Skill / 插件：**最适合可靠的 API 访问（Notion/HeyGen 都有 API）。 + - **浏览器自动化：**无需代码即可工作，但更慢也更脆弱。 如果你想按客户保留上下文（代理机构工作流），一个简单模式是： - - 每个客户一个 Notion 页面（上下文 + 偏好 + 活动工作）。 + - 每个客户一个 Notion 页面（上下文 + 偏好 + 活跃工作）。 - 要求智能体在会话开始时获取该页面。 - 如果你想要原生集成，请提交功能请求，或构建一个面向这些 API 的 Skill。 + 如果你想要原生集成，请打开功能请求，或构建一个面向这些 API 的 Skill。 安装 Skills： @@ -414,11 +413,11 @@ x-i18n: openclaw skills update --all ``` - 原生安装会落在活动工作区的 `skills/` 目录中。对于跨智能体共享的 Skills，请将它们放在 `~/.openclaw/skills//SKILL.md`。如果只有部分智能体应该看到共享安装，请配置 `agents.defaults.skills` 或 `agents.list[].skills`。某些 Skills 预期通过 Homebrew 安装二进制文件；在 Linux 上，这意味着 Linuxbrew（请参阅上方的 Homebrew Linux 常见问题条目）。请参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和 [ClawHub](/zh-CN/tools/clawhub)。 + 原生安装会落到活动工作区的 `skills/` 目录。若要在智能体之间共享 Skills，请将它们放在 `~/.openclaw/skills//SKILL.md`。如果只有部分智能体应该看到共享安装，请配置 `agents.defaults.skills` 或 `agents.list[].skills`。一些 Skills 预期通过 Homebrew 安装二进制文件；在 Linux 上这意味着 Linuxbrew（见上方 Homebrew Linux 常见问题条目）。参见 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和 [ClawHub](/zh-CN/tools/clawhub)。 - + 使用内置的 `user` 浏览器配置文件，它会通过 Chrome DevTools MCP 附加： ```bash @@ -426,20 +425,20 @@ x-i18n: openclaw browser --browser-profile user snapshot ``` - 如果你想使用自定义名称，请创建显式 MCP 配置文件： + 如果你想使用自定义名称，请创建一个显式 MCP 配置文件： ```bash openclaw browser create-profile --name chrome-live --driver existing-session openclaw browser --browser-profile chrome-live tabs ``` - 此路径可以使用本地主机浏览器或已连接的浏览器节点。如果 Gateway 网关在别处运行，请在浏览器所在机器上运行节点主机，或改用远程 CDP。 + 此路径可以使用本地主机浏览器或已连接的浏览器节点。如果 Gateway 网关在其他位置运行，请在浏览器机器上运行节点主机，或改用远程 CDP。 - `existing-session` / `user` 当前限制： + `existing-session` / `user` 的当前限制： - - 操作基于 ref，而不是基于 CSS 选择器 - - 上传需要 `ref` / `inputRef`，且当前一次支持一个文件 - - `responsebody`、PDF 导出、下载拦截和批量操作仍然需要托管浏览器或原始 CDP 配置文件 + - 操作由 ref 驱动，不由 CSS 选择器驱动 + - 上传需要 `ref` / `inputRef`，并且目前一次支持一个文件 + - `responsebody`、PDF 导出、下载拦截和批量操作仍需要托管浏览器或原始 CDP 配置文件 @@ -448,40 +447,40 @@ x-i18n: - 有。请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)。有关 Docker 专属设置（Docker 中的完整 Gateway 网关或沙箱镜像），请参阅 [Docker](/zh-CN/install/docker)。 + 有。参见[沙箱隔离](/zh-CN/gateway/sandboxing)。对于 Docker 专用设置（Docker 中的完整 Gateway 网关或沙箱镜像），参见 [Docker](/zh-CN/install/docker)。 - 默认镜像以安全优先，并以 `node` 用户运行，因此不 - 包含系统包、Homebrew 或内置浏览器。若要获得更完整的设置： + 默认镜像以安全优先，并以 `node` 用户运行，因此它不 + 包含系统包、Homebrew 或内置浏览器。若要更完整的设置： - - 使用 `OPENCLAW_HOME_VOLUME` 持久化 `/home/node`，以便缓存保留下来。 + - 使用 `OPENCLAW_HOME_VOLUME` 持久化 `/home/node`，让缓存保留下来。 - 使用 `OPENCLAW_DOCKER_APT_PACKAGES` 将系统依赖烘焙进镜像。 - 通过内置 CLI 安装 Playwright 浏览器： `node /app/node_modules/playwright-core/cli.js install chromium` - - 设置 `PLAYWRIGHT_BROWSERS_PATH`，并确保该路径被持久化。 + - 设置 `PLAYWRIGHT_BROWSERS_PATH`，并确保该路径已持久化。 文档：[Docker](/zh-CN/install/docker)、[浏览器](/zh-CN/tools/browser)。 - - 可以，前提是你的私有流量是**私信**，公开流量是**群组**。 + + 可以，前提是你的私有流量是 **私信**，公共流量是**群组**。 - 使用 `agents.defaults.sandbox.mode: "non-main"`，让群组/渠道会话（非主键）在配置的沙箱后端中运行，而主私信会话保留在主机上。如果你未选择后端，Docker 是默认后端。然后通过 `tools.sandbox.tools` 限制沙箱隔离会话中可用的工具。 + 使用 `agents.defaults.sandbox.mode: "non-main"`，使群组/渠道会话（非主键）在配置的沙箱后端中运行，而主私信会话保留在主机上。如果你未选择后端，Docker 是默认后端。然后通过 `tools.sandbox.tools` 限制沙箱隔离会话中可用的工具。 - 设置演练 + 示例配置：[群组：个人私信 + 公开群组](/zh-CN/channels/groups#pattern-personal-dms-public-groups-single-agent) + 设置演练 + 示例配置：[群组：个人私信 + 公共群组](/zh-CN/channels/groups#pattern-personal-dms-public-groups-single-agent) 关键配置参考：[Gateway 网关配置](/zh-CN/gateway/config-agents#agentsdefaultssandbox) - - 将 `agents.defaults.sandbox.docker.binds` 设置为 `["host:path:mode"]`（例如 `"/home/user/src:/src:ro"`）。全局绑定和按智能体绑定会合并；当 `scope: "shared"` 时，按智能体绑定会被忽略。对任何敏感内容使用 `:ro`，并记住绑定会绕过沙箱文件系统墙。 + + 将 `agents.defaults.sandbox.docker.binds` 设为 `["host:path:mode"]`（例如 `"/home/user/src:/src:ro"`）。全局绑定和每智能体绑定会合并；当 `scope: "shared"` 时，会忽略每智能体绑定。对任何敏感内容使用 `:ro`，并记住绑定会绕过沙箱文件系统边界。 - OpenClaw 会根据规范化路径以及通过最深层已存在祖先解析得到的规范路径来验证绑定源。这意味着即使最后一个路径段尚不存在，符号链接父级逃逸仍会默认失败关闭，并且允许根检查在符号链接解析后仍会应用。 + OpenClaw 会同时依据规范化路径和通过最深已存在祖先解析出的规范路径来验证绑定源。这意味着即使最后一个路径段尚不存在，符号链接父级逃逸仍会默认失败，并且符号链接解析后仍会应用允许根检查。 - 请参阅[沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts)和[沙箱 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)，查看示例和安全说明。 + 示例和安全说明见[沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts)以及[沙箱 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)。 @@ -489,20 +488,20 @@ x-i18n: OpenClaw 记忆只是智能体工作区中的 Markdown 文件： - `memory/YYYY-MM-DD.md` 中的每日笔记 - - `MEMORY.md` 中的精选长期笔记（仅主/私有会话） + - `MEMORY.md` 中经过整理的长期笔记（仅主/私有会话） - OpenClaw 还会运行**静默的压缩前记忆刷新**，以提醒模型 - 在自动压缩前写入持久笔记。这只会在工作区可写时运行 - （只读沙箱会跳过）。请参阅[记忆](/zh-CN/concepts/memory)。 + OpenClaw 还会运行一次**静默的压缩前记忆刷新**，以提醒模型 + 在自动压缩前写入持久笔记。它只会在工作区 + 可写时运行（只读沙箱会跳过）。参见[记忆](/zh-CN/concepts/memory)。 - - 要求机器人**将事实写入记忆**。长期笔记应放在 `MEMORY.md`， - 短期上下文放入 `memory/YYYY-MM-DD.md`。 + + 要求机器人**把事实写入记忆**。长期笔记应放在 `MEMORY.md`， + 短期上下文放进 `memory/YYYY-MM-DD.md`。 - 这仍是我们正在改进的领域。提醒模型存储记忆会有所帮助； - 它会知道怎么做。如果它持续忘记，请验证 Gateway 网关每次运行都使用同一个 + 这仍是我们正在改进的领域。提醒模型存储记忆会有帮助； + 它会知道该怎么做。如果它持续忘记，请验证 Gateway 网关每次运行都使用同一个 工作区。 文档：[记忆](/zh-CN/concepts/memory)、[Agent 工作区](/zh-CN/concepts/agent-workspace)。 @@ -510,65 +509,66 @@ x-i18n: - 记忆文件位于磁盘上，并会持续存在，直到你删除它们。限制来自你的 - 存储空间，而不是模型。**会话上下文**仍然受模型 - 上下文窗口限制，因此长对话可能会被压缩或截断。这就是 - 记忆搜索存在的原因，它只会把相关部分拉回上下文。 + 记忆文件存在磁盘上，并会一直保留，直到你删除它们。限制来自你的 + 存储，而不是模型。**会话上下文**仍受模型 + 上下文窗口限制，因此长对话可能被压缩或截断。这就是 + 记忆搜索存在的原因：它只把相关部分拉回上下文。 文档：[记忆](/zh-CN/concepts/memory)、[上下文](/zh-CN/concepts/context)。 - 仅当你使用 **OpenAI 嵌入**时才需要。Codex OAuth 涵盖聊天/补全，并且 - **不**授予嵌入访问权限，因此**使用 Codex 登录（OAuth 或 - Codex CLI 登录）**对语义记忆搜索没有帮助。OpenAI 嵌入 - 仍然需要真实的 API key（`OPENAI_API_KEY` 或 `models.providers.openai.apiKey`）。 + 仅当你使用 **OpenAI embeddings** 时需要。Codex OAuth 覆盖聊天/补全， + 但**不会**授予 embeddings 访问权限，因此**使用 Codex 登录（OAuth 或 + Codex CLI 登录）**对语义记忆搜索没有帮助。OpenAI embeddings + 仍然需要真正的 API key（`OPENAI_API_KEY` 或 `models.providers.openai.apiKey`）。 - 如果你没有显式设置提供商，OpenClaw 会在能够解析 API key（认证配置文件、`models.providers.*.apiKey` 或环境变量）时自动选择提供商。 - 如果能解析 OpenAI key，它会优先使用 OpenAI；否则如果能解析 Gemini key， - 则使用 Gemini，然后是 Voyage，再然后是 Mistral。如果没有可用的远程 key，记忆 - 搜索会保持禁用，直到你完成配置。如果你已经配置并存在本地模型路径，OpenClaw - 会优先使用 `local`。当你显式设置 - `memorySearch.provider = "ollama"` 时，支持 Ollama。 + 如果你没有显式设置提供商，OpenClaw 会在能够解析出 API key（认证配置文件、 + `models.providers.*.apiKey` 或环境变量）时自动选择提供商。 + 如果解析到 OpenAI key，它会优先选择 OpenAI；否则如果解析到 Gemini key， + 则选择 Gemini；然后是 Voyage，再然后是 Mistral。如果没有可用的远程 key， + 记忆搜索会保持禁用，直到你完成配置。如果你已配置并提供了本地模型路径， + OpenClaw 会优先选择 `local`。当你显式设置 + `memorySearch.provider = "ollama"` 时支持 Ollama。 - 如果你更想保持本地运行，请设置 `memorySearch.provider = "local"`（并可选设置 - `memorySearch.fallback = "none"`）。如果你想使用 Gemini 嵌入，请设置 + 如果你更想保持本地运行，请设置 `memorySearch.provider = "local"`（也可选择设置 + `memorySearch.fallback = "none"`）。如果你想使用 Gemini embeddings，请设置 `memorySearch.provider = "gemini"` 并提供 `GEMINI_API_KEY`（或 - `memorySearch.remote.apiKey`）。我们支持 **OpenAI、Gemini、Voyage、Mistral、Ollama 或本地**嵌入 - 模型 - 设置详情请参见 [Memory](/zh-CN/concepts/memory)。 + `memorySearch.remote.apiKey`）。我们支持 **OpenAI、Gemini、Voyage、Mistral、Ollama 或本地** embedding + 模型 - 设置详情请参阅 [记忆](/zh-CN/concepts/memory)。 -## 内容在磁盘上的位置 +## 文件在磁盘上的位置 - 不会 - **OpenClaw 的状态是本地的**，但**外部服务仍然会看到你发送给它们的内容**。 + 不会 - **OpenClaw 的状态是本地的**，但**外部服务仍会看到你发送给它们的内容**。 - - **默认本地：** 会话、记忆文件、配置和工作区位于 Gateway 网关主机上 + - **默认本地：** 会话、记忆文件、配置和工作区位于 Gateway 网关主机 （`~/.openclaw` + 你的工作区目录）。 - **必要时远程：** 你发送给模型提供商（Anthropic/OpenAI 等）的消息会进入 - 它们的 API，而聊天平台（WhatsApp/Telegram/Slack 等）会在它们的 - 服务器上存储消息数据。 - - **你控制覆盖范围：** 使用本地模型会让提示词保留在你的机器上，但渠道 + 它们的 API，聊天平台（WhatsApp/Telegram/Slack 等）会把消息数据存储在它们的 + 服务器上。 + - **你控制数据足迹：** 使用本地模型会让提示词留在你的机器上，但渠道 流量仍会经过该渠道的服务器。 - 相关：[Agent 工作区](/zh-CN/concepts/agent-workspace)、[Memory](/zh-CN/concepts/memory)。 + 相关：[Agent 工作区](/zh-CN/concepts/agent-workspace)、[记忆](/zh-CN/concepts/memory)。 - 所有内容都位于 `$OPENCLAW_STATE_DIR` 下（默认值：`~/.openclaw`）： + 所有内容都位于 `$OPENCLAW_STATE_DIR` 下（默认：`~/.openclaw`）： | 路径 | 用途 | | --------------------------------------------------------------- | ------------------------------------------------------------------ | | `$OPENCLAW_STATE_DIR/openclaw.json` | 主配置（JSON5） | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 旧版 OAuth 导入（首次使用时复制到认证配置文件中） | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | 认证配置文件（OAuth、API key，以及可选的 `keyRef`/`tokenRef`） | - | `$OPENCLAW_STATE_DIR/secrets.json` | `file` SecretRef 提供商的可选文件后端密钥载荷 | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | 旧版兼容文件（静态 `api_key` 条目会被清除） | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 旧版 OAuth 导入（首次使用时复制到认证配置文件） | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | 认证配置文件（OAuth、API keys，以及可选的 `keyRef`/`tokenRef`） | + | `$OPENCLAW_STATE_DIR/secrets.json` | 面向 `file` SecretRef 提供商的可选文件后端密钥载荷 | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | 旧版兼容文件（静态 `api_key` 条目会被清理） | | `$OPENCLAW_STATE_DIR/credentials/` | 提供商状态（例如 `whatsapp//creds.json`） | | `$OPENCLAW_STATE_DIR/agents/` | 每个智能体的状态（agentDir + 会话） | | `$OPENCLAW_STATE_DIR/agents//sessions/` | 对话历史和状态（按智能体） | @@ -576,17 +576,17 @@ x-i18n: 旧版单智能体路径：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移）。 - 你的**工作区**（AGENTS.md、记忆文件、Skills 等）是独立的，并通过 `agents.defaults.workspace` 配置（默认值：`~/.openclaw/workspace`）。 + 你的 **工作区**（AGENTS.md、记忆文件、Skills 等）是独立的，并通过 `agents.defaults.workspace` 配置（默认：`~/.openclaw/workspace`）。 这些文件位于 **Agent 工作区**，而不是 `~/.openclaw`。 - - **工作区（每个智能体）**：`AGENTS.md`、`SOUL.md`、`IDENTITY.md`、`USER.md`、 + - **工作区（按智能体）**：`AGENTS.md`、`SOUL.md`、`IDENTITY.md`、`USER.md`、 `MEMORY.md`、`memory/YYYY-MM-DD.md`，以及可选的 `HEARTBEAT.md`。 - 小写根文件 `memory.md` 仅作为旧版修复输入；当两个文件同时存在时，`openclaw doctor --fix` - 可以将它合并到 `MEMORY.md` 中。 + 小写的根级 `memory.md` 仅作为旧版修复输入；当两个文件都存在时，`openclaw doctor --fix` + 可以将它合并到 `MEMORY.md`。 - **状态目录（`~/.openclaw`）**：配置、渠道/提供商状态、认证配置文件、会话、日志， 以及共享 Skills（`~/.openclaw/skills`）。 @@ -598,23 +598,23 @@ x-i18n: } ``` - 如果机器人重启后“忘记”了，请确认 Gateway 网关每次启动时使用的是同一个 - 工作区（并记住：远程模式使用的是 **Gateway 网关主机的** - 工作区，而不是你的本地笔记本）。 + 如果机器人在重启后“忘记”了内容，请确认 Gateway 网关在每次启动时都使用相同的 + 工作区（并记住：远程模式使用的是 **gateway 主机的** + 工作区，而不是你本地笔记本电脑上的工作区）。 - 提示：如果你希望某种行为或偏好持久保存，请让机器人**将它写入 + 提示：如果你想保留持久的行为或偏好，请让机器人**把它写入 AGENTS.md 或 MEMORY.md**，而不是依赖聊天历史。 - 参见 [Agent 工作区](/zh-CN/concepts/agent-workspace) 和 [Memory](/zh-CN/concepts/memory)。 + 请参阅 [Agent 工作区](/zh-CN/concepts/agent-workspace) 和 [记忆](/zh-CN/concepts/memory)。 - 将你的 **Agent 工作区**放入**私有** git 仓库，并备份到某个 - 私有位置（例如 GitHub 私有仓库）。这会捕获记忆 + AGENTS/SOUL/USER - 文件，并让你以后恢复助手的“心智”。 + 将你的 **Agent 工作区** 放入一个**私有** git 仓库，并备份到某个 + 私有位置（例如 GitHub private）。这会捕获记忆 + AGENTS/SOUL/USER + 文件，并允许你稍后恢复助手的“心智”。 - **不要**提交 `~/.openclaw` 下的任何内容（凭证、会话、令牌或加密密钥载荷）。 + **不要**提交 `~/.openclaw` 下的任何内容（凭据、会话、令牌或加密密钥载荷）。 如果你需要完整恢复，请分别备份工作区和状态目录 （参见上面的迁移问题）。 @@ -623,19 +623,19 @@ x-i18n: - 参见专门指南：[卸载](/zh-CN/install/uninstall)。 + 请参阅专门指南：[卸载](/zh-CN/install/uninstall)。 - 可以。工作区是**默认 cwd** 和记忆锚点，而不是强制沙箱。 + 可以。工作区是**默认 cwd** 和记忆锚点，不是硬性沙箱。 相对路径会在工作区内解析，但除非启用沙箱隔离，否则绝对路径可以访问其他 主机位置。如果你需要隔离，请使用 - [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing) 或每个智能体的沙箱设置。如果你 - 希望某个仓库成为默认工作目录，请将该智能体的 + [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing) 或按智能体设置沙箱。如果你 + 想让某个仓库成为默认工作目录，请将该智能体的 `workspace` 指向仓库根目录。OpenClaw 仓库只是源代码；除非你有意让智能体在其中工作， 否则请将工作区分开。 - 示例（仓库作为默认 cwd）： + 示例（将仓库作为默认 cwd）： ```json5 { @@ -650,7 +650,7 @@ x-i18n: - 会话状态由 **Gateway 网关主机**拥有。如果你处于远程模式，你关心的会话存储位于远程机器上，而不是你的本地笔记本。参见[会话管理](/zh-CN/concepts/session)。 + 会话状态归 **gateway 主机**所有。如果你处于远程模式，你关心的会话存储位于远程机器上，而不是本地笔记本电脑上。请参阅 [会话管理](/zh-CN/concepts/session)。 @@ -658,7 +658,7 @@ x-i18n: - OpenClaw 会从 `$OPENCLAW_CONFIG_PATH` 读取可选的 **JSON5** 配置（默认值：`~/.openclaw/openclaw.json`）： + OpenClaw 从 `$OPENCLAW_CONFIG_PATH` 读取可选的 **JSON5** 配置（默认：`~/.openclaw/openclaw.json`）： ``` $OPENCLAW_CONFIG_PATH @@ -668,11 +668,11 @@ x-i18n: - - 非 loopback 绑定**需要有效的 Gateway 网关认证路径**。实践中这意味着： + + 非 loopback 绑定**需要有效的 gateway 认证路径**。实际中这意味着： - 共享密钥认证：令牌或密码 - - `gateway.auth.mode: "trusted-proxy"`，位于正确配置的身份感知反向代理之后 + - `gateway.auth.mode: "trusted-proxy"`，位于已正确配置的身份感知反向代理之后 ```json5 { @@ -686,19 +686,19 @@ x-i18n: } ``` - 注意： + 说明： - - `gateway.remote.token` / `.password` **不会**单独启用本地 Gateway 网关认证。 - - 只有当 `gateway.auth.*` 未设置时，本地调用路径才可以将 `gateway.remote.*` 用作回退。 - - 对于密码认证，请改为设置 `gateway.auth.mode: "password"` 以及 `gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 - - 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但未解析，解析会失败关闭（不会用远程回退掩盖）。 - - 共享密钥 Control UI 设置通过 `connect.params.auth.token` 或 `connect.params.auth.password`（存储在应用/UI 设置中）进行认证。Tailscale Serve 或 `trusted-proxy` 等带身份的模式则使用请求头。避免将共享密钥放入 URL。 + - `gateway.remote.token` / `.password` 本身**不会**启用本地 gateway 认证。 + - 仅当未设置 `gateway.auth.*` 时，本地调用路径才能使用 `gateway.remote.*` 作为回退。 + - 对于密码认证，请改为设置 `gateway.auth.mode: "password"` 加 `gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 + - 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但无法解析，解析会失败关闭（不会用远程回退掩盖）。 + - 共享密钥 Control UI 设置通过 `connect.params.auth.token` 或 `connect.params.auth.password`（存储在应用/UI 设置中）进行认证。Tailscale Serve 或 `trusted-proxy` 等带身份的模式则使用请求头。避免把共享密钥放进 URL。 - 使用 `gateway.auth.mode: "trusted-proxy"` 时，同主机 loopback 反向代理需要显式设置 `gateway.auth.trustedProxy.allowLoopback = true`，并在 `gateway.trustedProxies` 中加入 loopback 条目。 - - OpenClaw 默认强制执行 Gateway 网关认证，包括 loopback。在正常默认路径中，这意味着令牌认证：如果没有配置显式认证路径，Gateway 网关启动会解析为令牌模式并自动生成一个令牌，将它保存到 `gateway.auth.token`，因此**本地 WS 客户端必须认证**。这会阻止其他本地进程调用 Gateway 网关。 + + OpenClaw 默认强制执行 gateway 认证，包括 loopback。在普通默认路径中，这意味着令牌认证：如果未配置显式认证路径，gateway 启动会解析为令牌模式并自动生成一个令牌，保存到 `gateway.auth.token`，因此**本地 WS 客户端必须认证**。这会阻止其他本地进程调用 Gateway 网关。 如果你更喜欢其他认证路径，可以显式选择密码模式（或者，对于身份感知反向代理，选择 `trusted-proxy`）。如果你**确实**想开放 loopback，请在配置中显式设置 `gateway.auth.mode: "none"`。Doctor 可以随时为你生成令牌：`openclaw doctor --generate-gateway-token`。 @@ -707,7 +707,7 @@ x-i18n: Gateway 网关会监视配置并支持热重载： - - `gateway.reload.mode: "hybrid"`（默认）：热应用安全变更，关键变更则重启 + - `gateway.reload.mode: "hybrid"`（默认）：安全变更热应用，关键变更重启 - 也支持 `hot`、`restart`、`off` @@ -727,7 +727,7 @@ x-i18n: - `off`：隐藏标语文本，但保留横幅标题/版本行。 - `default`：每次都使用 `All your chats, one OpenClaw.`。 - - `random`：轮换的有趣/季节性标语（默认行为）。 + - `random`：轮换有趣/季节性标语（默认行为）。 - 如果你完全不想显示横幅，请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 @@ -736,24 +736,24 @@ x-i18n: `web_fetch` 无需 API key 即可工作。`web_search` 取决于你选择的 提供商： - - Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily 等 API 后端提供商需要其常规 API key 设置。 - - Ollama Web 搜索不需要 key，但它使用你配置的 Ollama 主机，并且需要 `ollama signin`。 - - DuckDuckGo 不需要 key，但它是非官方的基于 HTML 的集成。 - - SearXNG 不需要 key/可自托管；配置 `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`。 + - Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily 等 API 后端提供商需要它们的常规 API key 设置。 + - Ollama Web 搜索无需 key，但它会使用你配置的 Ollama 主机，并且需要 `ollama signin`。 + - DuckDuckGo 无需 key，但它是非官方的基于 HTML 的集成。 + - SearXNG 无需 key/可自托管；配置 `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`。 - **推荐：**运行 `openclaw configure --section web` 并选择一个提供商。 + **推荐：** 运行 `openclaw configure --section web` 并选择一个提供商。 环境变量替代项： - - Brave：`BRAVE_API_KEY` - - Exa：`EXA_API_KEY` - - Firecrawl：`FIRECRAWL_API_KEY` - - Gemini：`GEMINI_API_KEY` - - Grok：`XAI_API_KEY` - - Kimi：`KIMI_API_KEY` 或 `MOONSHOT_API_KEY` - - MiniMax Search：`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY` 或 `MINIMAX_API_KEY` - - Perplexity：`PERPLEXITY_API_KEY` 或 `OPENROUTER_API_KEY` - - SearXNG：`SEARXNG_BASE_URL` - - Tavily：`TAVILY_API_KEY` + - Brave: `BRAVE_API_KEY` + - Exa: `EXA_API_KEY` + - Firecrawl: `FIRECRAWL_API_KEY` + - Gemini: `GEMINI_API_KEY` + - Grok: `XAI_API_KEY` + - Kimi: `KIMI_API_KEY` 或 `MOONSHOT_API_KEY` + - MiniMax Search: `MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY` 或 `MINIMAX_API_KEY` + - Perplexity: `PERPLEXITY_API_KEY` 或 `OPENROUTER_API_KEY` + - SearXNG: `SEARXNG_BASE_URL` + - Tavily: `TAVILY_API_KEY` ```json5 { @@ -785,14 +785,14 @@ x-i18n: ``` 提供商专用的 Web 搜索配置现在位于 `plugins.entries..config.webSearch.*` 下。 - 旧版 `tools.web.search.*` 提供商路径仍会临时加载以保持兼容，但不应在新配置中使用。 - Firecrawl Web 获取回退配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下。 + 旧版 `tools.web.search.*` 提供商路径仍会暂时加载以保持兼容，但不应再用于新配置。 + Firecrawl Web 抓取回退配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下。 注意： - 如果你使用允许列表，请添加 `web_search`/`web_fetch`/`x_search` 或 `group:web`。 - `web_fetch` 默认启用（除非显式禁用）。 - - 如果省略 `tools.web.fetch.provider`，OpenClaw 会从可用凭证中自动检测第一个就绪的获取回退提供商。目前内置提供商是 Firecrawl。 + - 如果省略 `tools.web.fetch.provider`，OpenClaw 会从可用凭证中自动检测第一个就绪的抓取回退提供商。目前内置提供商是 Firecrawl。 - 守护进程从 `~/.openclaw/.env`（或服务环境）读取环境变量。 文档：[Web 工具](/zh-CN/tools/web)。 @@ -800,45 +800,46 @@ x-i18n: - `config.apply` 会替换**整个配置**。如果你发送的是部分对象，其他所有内容都会被移除。 + `config.apply` 会替换**整个配置**。如果你发送部分对象，其他所有内容 + 都会被移除。 - 当前 OpenClaw 会防护许多意外覆盖： + 当前 OpenClaw 会防止许多意外覆盖： - OpenClaw 拥有的配置写入会在写入前验证变更后的完整配置。 - - 无效或具有破坏性的 OpenClaw 拥有写入会被拒绝，并保存为 `openclaw.json.rejected.*`。 - - 如果直接编辑导致启动或热重载失败，Gateway 网关会恢复最后已知可用配置，并将被拒绝的文件保存为 `openclaw.json.clobbered.*`。 - - 恢复后，主智能体会收到启动警告，避免它再次盲目写入错误配置。 + - 无效或破坏性的 OpenClaw 拥有的写入会被拒绝，并保存为 `openclaw.json.rejected.*`。 + - 如果直接编辑导致启动或热重载失败，Gateway 网关会故障关闭或跳过重载；它不会重写 `openclaw.json`。 + - `openclaw doctor --fix` 负责修复，可以恢复到最后一个已知良好的配置，同时将被拒绝的文件保存为 `openclaw.json.clobbered.*`。 恢复： - - 检查 `openclaw logs --follow` 中的 `Config auto-restored from last-known-good`、`Config write rejected:` 或 `config reload restored last-known-good config`。 - - 查看活动配置旁边最新的 `openclaw.json.clobbered.*` 或 `openclaw.json.rejected.*`。 - - 如果活动的已恢复配置可用，请保留它，然后只用 `openclaw config set` 或 `config.patch` 复制回预期键名。 - - 运行 `openclaw config validate` 和 `openclaw doctor`。 - - 如果你没有最后已知可用配置或被拒绝的载荷，请从备份恢复，或重新运行 `openclaw doctor` 并重新配置渠道/模型。 - - 如果这是意外情况，请提交 bug，并包含你最后已知的配置或任何备份。 - - 本地编码智能体通常可以从日志或历史记录中重建可用配置。 + - 检查 `openclaw logs --follow` 中是否有 `Invalid config at`、`Config write rejected:` 或 `config reload skipped (invalid config)`。 + - 检查活动配置旁最新的 `openclaw.json.clobbered.*` 或 `openclaw.json.rejected.*`。 + - 运行 `openclaw config validate` 和 `openclaw doctor --fix`。 + - 只用 `openclaw config set` 或 `config.patch` 把预期键名复制回去。 + - 如果你没有最后一个已知良好的配置或被拒绝的载荷，请从备份恢复，或重新运行 `openclaw doctor` 并重新配置渠道/模型。 + - 如果这不是预期行为，请提交 bug，并包含你最后已知的配置或任何备份。 + - 本地编码智能体通常可以根据日志或历史记录重建可用配置。 - 避免： + 避免方式： - - 小改动使用 `openclaw config set`。 - - 交互式编辑使用 `openclaw configure`。 - - 如果不确定确切路径或字段形状，请先使用 `config.schema.lookup`；它会返回浅层 schema 节点以及用于下钻的直接子项摘要。 - - 部分 RPC 编辑使用 `config.patch`；`config.apply` 仅用于完整配置替换。 - - 如果你在智能体运行中使用仅限所有者的 `gateway` 工具，它仍会拒绝写入 `tools.exec.ask` / `tools.exec.security`（包括会规范化到相同受保护 exec 路径的旧版 `tools.bash.*` 别名）。 + - 对小改动使用 `openclaw config set`。 + - 对交互式编辑使用 `openclaw configure`。 + - 如果不确定确切路径或字段形状，请先使用 `config.schema.lookup`；它会返回一个浅层 schema 节点以及用于下钻的直接子项摘要。 + - 对部分 RPC 编辑使用 `config.patch`；仅将 `config.apply` 用于完整配置替换。 + - 如果你在一次智能体运行中使用仅所有者可用的 `gateway` 工具，它仍会拒绝写入 `tools.exec.ask` / `tools.exec.security`（包括会规范化到相同受保护 exec 路径的旧版 `tools.bash.*` 别名）。 - 文档：[配置](/zh-CN/cli/config)、[配置](/zh-CN/cli/configure)、[Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)、[Doctor](/zh-CN/gateway/doctor)。 + 文档：[配置](/zh-CN/cli/config)、[配置向导](/zh-CN/cli/configure)、[Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-rejected-invalid-config)、[Doctor](/zh-CN/gateway/doctor)。 - + 常见模式是**一个 Gateway 网关**（例如 Raspberry Pi）加上**节点**和**智能体**： - - **Gateway 网关（中央）：** 拥有渠道（Signal/WhatsApp）、路由和会话。 - - **节点（设备）：** Mac/iOS/Android 作为外围设备连接，并暴露本地工具（`system.run`、`canvas`、`camera`）。 - - **智能体（工作器）：** 用于特殊角色的独立大脑/工作区（例如“Hetzner 运维”、“个人数据”）。 - - **子智能体：** 当你需要并行处理时，从主智能体生成后台工作。 - - **TUI：** 连接到 Gateway 网关并切换智能体/会话。 + - **Gateway 网关（中央）：**拥有渠道（Signal/WhatsApp）、路由和会话。 + - **节点（设备）：**Mac/iOS/Android 作为外设连接，并暴露本地工具（`system.run`、`canvas`、`camera`）。 + - **智能体（worker）：**面向特殊角色的独立大脑/工作区（例如“Hetzner 运维”、“个人数据”）。 + - **子智能体：**当你需要并行处理时，从主智能体派生后台工作。 + - **TUI：**连接到 Gateway 网关并切换智能体/会话。 文档：[节点](/zh-CN/nodes)、[远程访问](/zh-CN/gateway/remote)、[多智能体路由](/zh-CN/concepts/multi-agent)、[子智能体](/zh-CN/tools/subagents)、[TUI](/zh-CN/web/tui)。 @@ -858,19 +859,19 @@ x-i18n: } ``` - 默认值是 `false`（有头）。无头模式在某些网站上更可能触发反机器人检查。请参阅[浏览器](/zh-CN/tools/browser)。 + 默认值是 `false`（有头）。无头模式在某些站点上更容易触发反机器人检查。请参阅[浏览器](/zh-CN/tools/browser)。 - 无头模式使用**相同的 Chromium 引擎**，适用于大多数自动化（表单、点击、抓取、登录）。主要区别： + 无头模式使用**相同的 Chromium 引擎**，适用于大多数自动化任务（表单、点击、抓取、登录）。主要区别是： - - 没有可见的浏览器窗口（如果需要视觉内容，请使用截图）。 - - 有些网站对无头模式下的自动化更严格（CAPTCHA、反机器人）。 - 例如，X/Twitter 经常阻止无头会话。 + - 没有可见浏览器窗口（如果需要可视信息，请使用截图）。 + - 一些站点对无头模式下的自动化更严格（CAPTCHA、反机器人）。 + 例如，X/Twitter 经常会阻止无头会话。 将 `browser.executablePath` 设置为你的 Brave 二进制文件（或任何基于 Chromium 的浏览器），然后重启 Gateway 网关。 - 请参阅[浏览器](/zh-CN/tools/browser#use-brave-or-another-chromium-based-browser)中的完整配置示例。 + 请查看[浏览器](/zh-CN/tools/browser#use-brave-or-another-chromium-based-browser)中的完整配置示例。 @@ -878,25 +879,27 @@ x-i18n: - Telegram 消息由 **Gateway 网关**处理。Gateway 网关运行智能体，然后仅在需要节点工具时才通过 **Gateway 网关 WebSocket** 调用节点： + Telegram 消息由 **Gateway 网关**处理。Gateway 网关运行智能体， + 只有在需要节点工具时，才会通过 **Gateway 网关 WebSocket** 调用节点： Telegram → Gateway 网关 → 智能体 → `node.*` → 节点 → Gateway 网关 → Telegram - 节点看不到入站提供商流量；它们只接收节点 RPC 调用。 + 节点看不到传入的提供商流量；它们只接收节点 RPC 调用。 - - 简短答案：**将你的电脑配对为节点**。Gateway 网关在其他地方运行，但它可以通过 Gateway 网关 WebSocket 在你的本地机器上调用 `node.*` 工具（屏幕、摄像头、系统）。 + + 简短答案：**将你的电脑配对为节点**。Gateway 网关在其他地方运行，但它可以 + 通过 Gateway 网关 WebSocket 调用你本地机器上的 `node.*` 工具（屏幕、相机、系统）。 典型设置： 1. 在常开主机（VPS/家用服务器）上运行 Gateway 网关。 2. 将 Gateway 网关主机和你的电脑放在同一个 tailnet 中。 3. 确保 Gateway 网关 WS 可访问（tailnet 绑定或 SSH 隧道）。 - 4. 在本地打开 macOS 应用，并以 **通过 SSH 远程**模式（或直接 tailnet）连接， - 让它可以注册为节点。 - 5. 在 Gateway 网关上批准该节点： + 4. 在本地打开 macOS 应用，并以 **Remote over SSH** 模式（或直接 tailnet） + 连接，以便它可以注册为节点。 + 5. 在 Gateway 网关上批准节点： ```bash openclaw devices list @@ -905,13 +908,14 @@ x-i18n: 不需要单独的 TCP 桥接；节点通过 Gateway 网关 WebSocket 连接。 - 安全提醒：配对 macOS 节点允许在该机器上使用 `system.run`。只配对你信任的设备，并查看[安全](/zh-CN/gateway/security)。 + 安全提醒：配对 macOS 节点会允许在该机器上执行 `system.run`。只配对 + 你信任的设备，并查看[安全](/zh-CN/gateway/security)。 文档：[节点](/zh-CN/nodes)、[Gateway 网关协议](/zh-CN/gateway/protocol)、[macOS 远程模式](/zh-CN/platforms/mac/remote)、[安全](/zh-CN/gateway/security)。 - + 检查基础项： - Gateway 网关正在运行：`openclaw gateway status` @@ -921,22 +925,24 @@ x-i18n: 然后验证认证和路由： - 如果你使用 Tailscale Serve，请确保 `gateway.auth.allowTailscale` 设置正确。 - - 如果你通过 SSH 隧道连接，请确认本地隧道已启动并指向正确端口。 + - 如果通过 SSH 隧道连接，请确认本地隧道已启动，并指向正确端口。 - 确认你的允许列表（私信或群组）包含你的账号。 文档：[Tailscale](/zh-CN/gateway/tailscale)、[远程访问](/zh-CN/gateway/remote)、[渠道](/zh-CN/channels)。 - - 可以。没有内置的“bot 到 bot”桥接，但你可以用几种可靠方式连接起来： + + 可以。没有内置的“机器人到机器人”桥接，但你可以用几种 + 可靠方式把它们连接起来： - **最简单：** 使用两个机器人都能访问的普通聊天渠道（Telegram/Slack/WhatsApp）。 - 让 Bot A 向 Bot B 发送消息，然后让 Bot B 像平常一样回复。 + **最简单：**使用两个机器人都能访问的普通聊天渠道（Telegram/Slack/WhatsApp）。 + 让机器人 A 给机器人 B 发送消息，然后让机器人 B 像平常一样回复。 - **CLI 桥接（通用）：** 运行一个脚本，使用 `openclaw agent --message ... --deliver` 调用另一个 Gateway 网关， - 目标是另一个机器人监听的聊天。如果一个机器人在远程 VPS 上，请通过 SSH/Tailscale 将你的 CLI 指向该远程 Gateway 网关 - （请参阅[远程访问](/zh-CN/gateway/remote)）。 + **CLI 桥接（通用）：**运行一个脚本，用 + `openclaw agent --message ... --deliver` 调用另一个 Gateway 网关，目标是另一个机器人 + 监听的聊天。如果其中一个机器人在远程 VPS 上，请通过 SSH/Tailscale 将你的 CLI 指向该远程 Gateway 网关 + （参见[远程访问](/zh-CN/gateway/remote)）。 示例模式（从可以访问目标 Gateway 网关的机器运行）： @@ -944,49 +950,58 @@ x-i18n: openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - 提示：添加防护规则，避免两个机器人无限循环（仅提及时响应、渠道允许列表，或“不回复机器人消息”规则）。 + 提示：添加防护，避免两个机器人无限循环（仅提及时、渠道 + 允许列表，或“不要回复机器人消息”规则）。 文档：[远程访问](/zh-CN/gateway/remote)、[智能体 CLI](/zh-CN/cli/agent)、[智能体发送](/zh-CN/tools/agent-send)。 - 不需要。一个 Gateway 网关可以托管多个智能体，每个智能体都有自己的工作区、模型默认值和路由。这是常规设置，比每个智能体运行一个 VPS 更便宜也更简单。 + 不需要。一个 Gateway 网关可以托管多个智能体，每个都有自己的工作区、模型默认值 + 和路由。这是正常设置，而且比每个智能体运行一个 VPS 便宜且简单得多。 - 只有当你需要硬隔离（安全边界）或非常不同且不想共享的配置时，才使用单独的 VPS。否则，请保留一个 Gateway 网关，并使用多个智能体或子智能体。 + 只有在你需要强隔离（安全边界）或非常 + 不同且不想共享的配置时，才使用单独 VPS。否则，保持一个 Gateway 网关，并 + 使用多个智能体或子智能体。 - - 有，节点是从远程 Gateway 网关访问你的笔记本的第一等方式，并且解锁的不只是 shell 访问。Gateway 网关运行在 macOS/Linux（Windows 可通过 WSL2）上，并且很轻量（小型 VPS 或 Raspberry Pi 级别的机器即可；4 GB RAM 足够），所以常见设置是一个常开主机加上你的笔记本作为节点。 + + 有，节点是从远程 Gateway 网关访问你笔记本的一等方式，并且 + 解锁的不只是 shell 访问。Gateway 网关运行在 macOS/Linux（Windows 通过 WSL2）上，并且 + 很轻量（小型 VPS 或 Raspberry Pi 级别的盒子即可；4 GB RAM 已足够），因此常见 + 设置是一个常开主机加上作为节点的笔记本。 - - **不需要入站 SSH。** 节点主动连接到 Gateway 网关 WebSocket，并使用设备配对。 - - **更安全的执行控制。** `system.run` 受该笔记本上的节点允许列表/批准控制。 - - **更多设备工具。** 节点除了 `system.run` 之外，还暴露 `canvas`、`camera` 和 `screen`。 - - **本地浏览器自动化。** 将 Gateway 网关保留在 VPS 上，但通过笔记本上的节点主机在本地运行 Chrome，或通过 Chrome MCP 附加到主机上的本地 Chrome。 + - **不需要入站 SSH。**节点会向外连接到 Gateway 网关 WebSocket，并使用设备配对。 + - **更安全的执行控制。**`system.run` 受该笔记本上的节点允许列表/批准控制。 + - **更多设备工具。**除了 `system.run`，节点还暴露 `canvas`、`camera` 和 `screen`。 + - **本地浏览器自动化。**将 Gateway 网关保留在 VPS 上，但通过笔记本上的节点主机在本地运行 Chrome，或通过 Chrome MCP 附加到主机上的本地 Chrome。 - SSH 适合临时 shell 访问，但对于持续的智能体工作流和设备自动化，节点更简单。 + SSH 适合临时 shell 访问，但对于持续的智能体工作流和 + 设备自动化，节点更简单。 文档：[节点](/zh-CN/nodes)、[节点 CLI](/zh-CN/cli/nodes)、[浏览器](/zh-CN/tools/browser)。 - 不会。除非你有意运行隔离配置文件（请参阅[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)），否则每台主机只应运行**一个 Gateway 网关**。节点是连接到 Gateway 网关的外围设备（iOS/Android 节点，或 macOS 菜单栏应用中的“节点模式”）。对于无头节点 + 不会。除非你有意运行隔离配置文件（参见[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)），否则每台主机只应运行**一个 Gateway 网关**。节点是连接 + 到 Gateway 网关的外设（iOS/Android 节点，或菜单栏应用中的 macOS“节点模式”）。对于无头节点 主机和 CLI 控制，请参阅[节点主机 CLI](/zh-CN/cli/node)。 - `gateway`、`discovery` 和 `canvasHost` 变更需要完整重启。 + 对 `gateway`、`discovery` 和 `canvasHost` 的更改需要完整重启。 - + 有。 - `config.schema.lookup`：在写入前检查一个配置子树，包括其浅层 schema 节点、匹配的 UI 提示和直接子项摘要 - `config.get`：获取当前快照 + 哈希 - - `config.patch`：安全的部分更新（大多数 RPC 编辑的首选）；可能时热重载，需要时重启 - - `config.apply`：验证并替换完整配置；可能时热重载，需要时重启 - - 仅限所有者的 `gateway` 运行时工具仍拒绝重写 `tools.exec.ask` / `tools.exec.security`；旧版 `tools.bash.*` 别名会规范化到相同的受保护 exec 路径 + - `config.patch`：安全的部分更新（多数 RPC 编辑的首选）；可行时热重载，需要时重启 + - `config.apply`：验证 + 替换完整配置；可行时热重载，需要时重启 + - 仅所有者可用的 `gateway` 运行时工具仍会拒绝重写 `tools.exec.ask` / `tools.exec.security`；旧版 `tools.bash.*` 别名会规范化到相同的受保护 exec 路径 @@ -998,11 +1013,11 @@ x-i18n: } ``` - 这会设置你的工作区，并限制谁可以触发该机器人。 + 这会设置你的工作区，并限制谁可以触发机器人。 - + 最小步骤： 1. **在 VPS 上安装并登录** @@ -1013,32 +1028,32 @@ x-i18n: ``` 2. **在你的 Mac 上安装并登录** - - 使用 Tailscale 应用，并登录同一个 tailnet。 + - 使用 Tailscale 应用，并登录到同一个 tailnet。 3. **启用 MagicDNS（推荐）** - - 在 Tailscale 管理控制台中启用 MagicDNS，这样 VPS 就会有一个稳定名称。 + - 在 Tailscale 管理控制台中启用 MagicDNS，让 VPS 拥有稳定名称。 4. **使用 tailnet 主机名** - SSH：`ssh user@your-vps.tailnet-xxxx.ts.net` - Gateway 网关 WS：`ws://your-vps.tailnet-xxxx.ts.net:18789` - 如果你想在不使用 SSH 的情况下访问 Control UI，请在 VPS 上使用 Tailscale Serve： + 如果你想在不使用 SSH 的情况下访问控制 UI，请在 VPS 上使用 Tailscale Serve： ```bash openclaw gateway --tailscale serve ``` - 这会让 gateway 绑定到 loopback，并通过 Tailscale 暴露 HTTPS。参见 [Tailscale](/zh-CN/gateway/tailscale)。 + 这会让 Gateway 网关绑定到 loopback，并通过 Tailscale 暴露 HTTPS。参见 [Tailscale](/zh-CN/gateway/tailscale)。 - Serve 会暴露 **Gateway 网关 Control UI + WS**。节点通过同一个 Gateway 网关 WS 端点连接。 + Serve 会暴露 **Gateway 网关控制 UI + WS**。节点通过同一个 Gateway 网关 WS 端点连接。 推荐设置： 1. **确保 VPS + Mac 位于同一个 tailnet**。 2. **在远程模式下使用 macOS 应用**（SSH 目标可以是 tailnet 主机名）。 该应用会隧道转发 Gateway 网关端口，并作为节点连接。 - 3. **在 gateway 上批准该节点**： + 3. **在 Gateway 网关上批准节点**： ```bash openclaw devices list @@ -1049,10 +1064,10 @@ x-i18n: - - 如果你只需要在第二台笔记本上使用**本地工具**（屏幕/摄像头/exec），请将其添加为 - **节点**。这样可以保留单个 Gateway 网关，并避免重复配置。本地节点工具 - 目前仅支持 macOS，但我们计划将其扩展到其他操作系统。 + + 如果你只需要第二台笔记本电脑上的**本地工具**（屏幕/相机/执行），请将它添加为 + **节点**。这样会保留单个 Gateway 网关，并避免重复配置。本地节点工具 + 目前仅支持 macOS，但我们计划将它们扩展到其他操作系统。 只有在需要**强隔离**或两个完全独立的机器人时，才安装第二个 Gateway 网关。 @@ -1068,9 +1083,9 @@ x-i18n: OpenClaw 会从父进程（shell、launchd/systemd、CI 等）读取环境变量，并额外加载： - 当前工作目录中的 `.env` - - 来自 `~/.openclaw/.env`（也就是 `$OPENCLAW_STATE_DIR/.env`）的全局后备 `.env` + - 来自 `~/.openclaw/.env` 的全局回退 `.env`（也就是 `$OPENCLAW_STATE_DIR/.env`） - 两个 `.env` 文件都不会覆盖现有环境变量。 + 这两个 `.env` 文件都不会覆盖已有的环境变量。 你也可以在配置中定义内联环境变量（仅在进程环境中缺失时应用）： @@ -1083,15 +1098,15 @@ x-i18n: } ``` - 完整优先级和来源请参见 [/environment](/zh-CN/help/environment)。 + 参见 [/environment](/zh-CN/help/environment) 了解完整优先级和来源。 - - 两个常见修复方法： + + 两种常见修复方法： - 1. 将缺失的键放入 `~/.openclaw/.env`，这样即使服务没有继承你的 shell 环境，也能被读取。 - 2. 启用 shell 导入（可选便利功能）： + 1. 将缺失的键放入 `~/.openclaw/.env`，这样即使服务没有继承你的 shell 环境，也能读取到它们。 + 2. 启用 shell 导入（选择加入的便捷功能）： ```json5 { @@ -1104,18 +1119,18 @@ x-i18n: } ``` - 这会运行你的登录 shell，并且只导入缺失的预期键名（永不覆盖）。环境变量等价项： + 这会运行你的登录 shell，并且只导入缺失的预期键名（绝不覆盖）。环境变量等价项： `OPENCLAW_LOAD_SHELL_ENV=1`、`OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`。 - - `openclaw models status` 报告的是是否启用了 **shell env import**。“Shell env: off” - **不**表示你的环境变量缺失，它只表示 OpenClaw 不会自动加载 + + `openclaw models status` 报告的是是否启用了 **shell 环境导入**。“Shell env: off” + **不**表示你的环境变量缺失，只表示 OpenClaw 不会自动加载 你的登录 shell。 - 如果 Gateway 网关作为服务运行（launchd/systemd），它不会继承你的 shell - 环境。可通过以下任一方式修复： + 如果 Gateway 网关作为服务（launchd/systemd）运行，它不会继承你的 shell + 环境。用以下任一方式修复： 1. 将令牌放入 `~/.openclaw/.env`： @@ -1124,15 +1139,15 @@ x-i18n: ``` 2. 或启用 shell 导入（`env.shellEnv.enabled: true`）。 - 3. 或将其添加到你的配置 `env` 块（仅在缺失时应用）。 + 3. 或将其添加到你的配置 `env` 块中（仅在缺失时应用）。 - 然后重启 gateway 并重新检查： + 然后重启 Gateway 网关并重新检查： ```bash openclaw models status ``` - Copilot 令牌会从 `COPILOT_GITHUB_TOKEN`（也包括 `GH_TOKEN` / `GITHUB_TOKEN`）读取。 + Copilot 令牌从 `COPILOT_GITHUB_TOKEN` 读取（也包括 `GH_TOKEN` / `GITHUB_TOKEN`）。 参见 [/concepts/model-providers](/zh-CN/concepts/model-providers) 和 [/environment](/zh-CN/help/environment)。 @@ -1141,15 +1156,15 @@ x-i18n: ## 会话和多个聊天 - - 发送独立消息 `/new` 或 `/reset`。参见[会话管理](/zh-CN/concepts/session)。 + + 将 `/new` 或 `/reset` 作为独立消息发送。参见[会话管理](/zh-CN/concepts/session)。 - 会话可以在 `session.idleMinutes` 后过期，但这项功能**默认禁用**（默认值为 **0**）。 + 会话可以在 `session.idleMinutes` 之后过期，但这项功能**默认禁用**（默认值为 **0**）。 将其设置为正值即可启用空闲过期。启用后，空闲期之后的**下一条** 消息会为该聊天键启动一个新的会话 ID。 - 这不会删除转录记录，只是启动一个新的会话。 + 这不会删除转录记录，只是启动一个新会话。 ```json5 { @@ -1161,33 +1176,33 @@ x-i18n: - - 可以，通过**多智能体路由**和**子智能体**实现。你可以创建一个协调器 + + 可以，通过**多智能体路由**和**子智能体**实现。你可以创建一个协调 智能体，以及多个拥有各自工作区和模型的工作智能体。 - 也就是说，最好把它视为一个**有趣的实验**。它会消耗大量 token，而且通常 - 不如使用一个带有独立会话的机器人高效。我们设想的典型模型是一个与你对话的机器人， - 并使用不同会话处理并行工作。该机器人也可以在需要时派生子智能体。 + 话虽如此，这最好被视为一个**有趣实验**。它消耗大量令牌，而且通常 + 不如使用一个带有独立会话的机器人高效。我们设想的典型模型是一个你与之对话的机器人，并为并行工作使用不同会话。该 + 机器人也可以在需要时生成子智能体。 文档：[多智能体路由](/zh-CN/concepts/multi-agent)、[子智能体](/zh-CN/tools/subagents)、[智能体 CLI](/zh-CN/cli/agents)。 - - 会话上下文受模型窗口限制。长聊天、大量工具输出，或许多 + + 会话上下文受模型窗口限制。长聊天、大型工具输出或大量 文件都可能触发压缩或截断。 有帮助的做法： - 让机器人总结当前状态并写入文件。 - 在长任务前使用 `/compact`，切换主题时使用 `/new`。 - - 将重要上下文保存在工作区中，并让机器人读回。 + - 将重要上下文保存在工作区中，并让机器人回读。 - 对长时间或并行工作使用子智能体，让主聊天保持更小。 - - 如果经常发生这种情况，选择上下文窗口更大的模型。 + - 如果经常发生这种情况，请选择上下文窗口更大的模型。 - + 使用重置命令： ```bash @@ -1208,16 +1223,16 @@ x-i18n: 注意： - - 如果新手引导发现已有配置，也会提供**重置**选项。参见[新手引导（CLI）](/zh-CN/start/wizard)。 - - 如果你使用了配置文件（`--profile` / `OPENCLAW_PROFILE`），请重置每个状态目录（默认值为 `~/.openclaw-`）。 - - 开发重置：`openclaw gateway --dev --reset`（仅限开发；会清除开发配置 + 凭证 + 会话 + 工作区）。 + - 如果新手引导发现已有配置，也会提供**重置**。参见[新手引导（CLI）](/zh-CN/start/wizard)。 + - 如果你使用了配置档（`--profile` / `OPENCLAW_PROFILE`），请重置每个状态目录（默认是 `~/.openclaw-`）。 + - 开发重置：`openclaw gateway --dev --reset`（仅开发用途；会清除开发配置 + 凭证 + 会话 + 工作区）。 - + 使用以下任一方式： - - **压缩**（保留对话，但总结较旧的轮次）： + - **压缩**（保留对话，但总结较早轮次）： ``` /compact @@ -1225,7 +1240,7 @@ x-i18n: 或使用 `/compact ` 来指导总结。 - - **重置**（为同一个聊天键创建新的会话 ID）： + - **重置**（为同一聊天键创建新会话 ID）： ``` /new @@ -1234,24 +1249,24 @@ x-i18n: 如果持续发生： - - 启用或调整**会话剪枝**（`agents.defaults.contextPruning`），以裁剪旧工具输出。 + - 启用或调整**会话裁剪**（`agents.defaults.contextPruning`）以裁剪旧工具输出。 - 使用上下文窗口更大的模型。 - 文档：[压缩](/zh-CN/concepts/compaction)、[会话剪枝](/zh-CN/concepts/session-pruning)、[会话管理](/zh-CN/concepts/session)。 + 文档：[压缩](/zh-CN/concepts/compaction)、[会话裁剪](/zh-CN/concepts/session-pruning)、[会话管理](/zh-CN/concepts/session)。 - - 这是提供商验证错误：模型发出了一个缺少必需 - `input` 的 `tool_use` 块。它通常表示会话历史已过时或损坏（常见于长线程 + + 这是一个提供商验证错误：模型发出了缺少必需 + `input` 的 `tool_use` 块。它通常表示会话历史陈旧或损坏（常见于长线程 或工具/架构变更之后）。 - 修复：使用 `/new`（独立消息）开始一个新会话。 + 修复：使用 `/new`（独立消息）启动新会话。 - - Heartbeat 默认每 **30m** 运行一次（使用 OAuth 认证时为 **1h**）。可以调整或禁用： + + Heartbeat 默认每 **30m** 运行一次（使用 OAuth 认证时为 **1h**）。调整或禁用它们： ```json5 { @@ -1265,11 +1280,11 @@ x-i18n: } ``` - 如果 `HEARTBEAT.md` 存在但实际上为空（只有空行和类似 - `# Heading` 的 markdown 标题），OpenClaw 会跳过 heartbeat 运行以节省 API 调用。 - 如果文件缺失，heartbeat 仍会运行，并由模型决定要做什么。 + 如果 `HEARTBEAT.md` 存在但实际上为空（只有空行和 markdown + 标题，例如 `# Heading`），OpenClaw 会跳过 heartbeat 运行以节省 API 调用。 + 如果该文件缺失，heartbeat 仍会运行，由模型决定要做什么。 - 每个智能体的覆盖项使用 `agents.list[].heartbeat`。文档：[Heartbeat](/zh-CN/gateway/heartbeat)。 + 每个智能体覆盖使用 `agents.list[].heartbeat`。文档：[Heartbeat](/zh-CN/gateway/heartbeat)。 @@ -1302,7 +1317,7 @@ x-i18n: 查找以 `@g.us` 结尾的 `chatId`（或 `from`），例如： `1234567890-1234567890@g.us`。 - 选项 2（如果已配置/加入允许列表）：从配置列出群组： + 选项 2（如果已配置/加入 allowlist）：从配置列出群组： ```bash openclaw directory groups list --channel whatsapp @@ -1312,40 +1327,40 @@ x-i18n: - + 两个常见原因： - - 提及门控已开启（默认）。你必须 @提及该机器人（或匹配 `mentionPatterns`）。 - - 你配置了 `channels.whatsapp.groups` 但没有包含 `"*"`，并且该群组未加入允许列表。 + - 提及门控已开启（默认）。你必须 @提及机器人（或匹配 `mentionPatterns`）。 + - 你配置了 `channels.whatsapp.groups`，但没有配置 `"*"`，并且该群组未加入 allowlist。 参见[群组](/zh-CN/channels/groups)和[群组消息](/zh-CN/channels/group-messages)。 - 默认情况下，直接聊天会折叠到主会话。群组/渠道有自己的会话键，而 Telegram 话题 / Discord 线程是独立会话。参见[群组](/zh-CN/channels/groups)和[群组消息](/zh-CN/channels/group-messages)。 + 默认情况下，直接聊天会折叠到主会话。群组/渠道有自己的会话键，Telegram 话题 / Discord 线程是独立会话。参见[群组](/zh-CN/channels/groups)和[群组消息](/zh-CN/channels/group-messages)。 - 没有硬性限制。几十个（甚至几百个）也可以，但要注意： + 没有硬性限制。几十个（甚至几百个）都可以，但要注意： - - **磁盘增长：**会话 + 转录记录位于 `~/.openclaw/agents//sessions/` 下。 - - **Token 成本：**更多智能体意味着更多并发模型使用。 - - **运维开销：**每个智能体的认证配置文件、工作区和渠道路由。 + - **磁盘增长：** 会话 + 转录记录位于 `~/.openclaw/agents//sessions/` 下。 + - **令牌成本：** 更多智能体意味着更多并发模型使用。 + - **运维开销：** 每个智能体的认证配置档、工作区和渠道路由。 提示： - 每个智能体保留一个**活跃**工作区（`agents.defaults.workspace`）。 - - 如果磁盘增长，剪枝旧会话（删除 JSONL 或存储条目）。 - - 使用 `openclaw doctor` 发现孤立工作区和配置文件不匹配。 + - 如果磁盘增长，请裁剪旧会话（删除 JSONL 或存储条目）。 + - 使用 `openclaw doctor` 发现零散工作区和配置档不匹配。 - 可以。使用 **多智能体路由** 来运行多个隔离的智能体，并按 - 渠道/账号/对端路由入站消息。Slack 作为渠道受支持，并且可以绑定到特定智能体。 + 可以。使用 **多智能体路由** 运行多个隔离智能体，并按 + 渠道/账户/对等方路由传入消息。Slack 支持作为渠道，并可绑定到特定智能体。 - 浏览器访问能力很强，但并不是“人能做什么它就能做什么”——反机器人、CAPTCHA 和 MFA 仍然可能 + 浏览器访问能力很强，但并不是“人能做什么它就能做什么”——反机器人机制、CAPTCHA 和 MFA 仍可能 阻止自动化。若要获得最可靠的浏览器控制，请在主机上使用本地 Chrome MCP， 或在实际运行浏览器的机器上使用 CDP。 @@ -1362,16 +1377,16 @@ x-i18n: -## Models、故障转移和身份验证配置档案 +## 模型、故障转移和认证配置 -Models 问答——默认值、选择、别名、切换、故障转移、身份验证配置档案—— -位于 [Models 常见问题](/zh-CN/help/faq-models)。 +模型问答 —— 默认值、选择、别名、切换、故障转移、认证配置 —— +见 [Models 常见问题](/zh-CN/help/faq-models)。 ## Gateway 网关：端口、“已在运行”和远程模式 - `gateway.port` 控制 WebSocket + HTTP（Control UI、钩子等）的单个多路复用端口。 + `gateway.port` 控制用于 WebSocket + HTTP（Control UI、钩子等）的单个复用端口。 优先级： @@ -1381,19 +1396,19 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 - - 因为“running”是**监督器**的视角（launchd/systemd/schtasks）。连通性探测是 CLI 实际连接到 gateway WebSocket。 + + 因为 "running" 是**监督进程**视角（launchd/systemd/schtasks）。连接探测是 CLI 实际连接到 Gateway 网关 WebSocket。 使用 `openclaw gateway status`，并信任这些行： - `Probe target:`（探测实际使用的 URL） - `Listening:`（端口上实际绑定的内容） - - `Last gateway error:`（进程仍然存活但端口未监听时的常见根因） + - `Last gateway error:`（进程存活但端口未监听时的常见根因） - - 你正在编辑一个配置文件，而服务正在运行另一个配置文件（通常是 `--profile` / `OPENCLAW_STATE_DIR` 不匹配）。 + + 你正在编辑一个配置文件，而服务运行的是另一个配置文件（通常是 `--profile` / `OPENCLAW_STATE_DIR` 不匹配）。 修复： @@ -1401,19 +1416,19 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 openclaw gateway install --force ``` - 从你希望服务使用的同一个 `--profile` / 环境运行该命令。 + 请在希望服务使用的同一个 `--profile` / 环境中运行该命令。 - - OpenClaw 会在启动时立即绑定 WebSocket 监听器（默认 `ws://127.0.0.1:18789`）来强制执行运行时锁。如果绑定因 `EADDRINUSE` 失败，它会抛出 `GatewayLockError`，表示另一个实例已在监听。 + + OpenClaw 会在启动时立即绑定 WebSocket 监听器来强制执行运行时锁（默认 `ws://127.0.0.1:18789`）。如果绑定因 `EADDRINUSE` 失败，它会抛出 `GatewayLockError`，表示另一个实例已在监听。 修复：停止另一个实例、释放端口，或使用 `openclaw gateway --port ` 运行。 - 设置 `gateway.mode: "remote"`，并指向远程 WebSocket URL，可选使用共享密钥远程凭证： + 设置 `gateway.mode: "remote"` 并指向远程 WebSocket URL，可选地使用共享密钥远程凭证： ```json5 { @@ -1430,76 +1445,76 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 注意： - - 只有当 `gateway.mode` 为 `local` 时（或你传入覆盖标志时），`openclaw gateway` 才会启动。 + - `openclaw gateway` 仅在 `gateway.mode` 为 `local` 时启动（或你传入覆盖标志时）。 - macOS 应用会监视配置文件，并在这些值变化时实时切换模式。 - - `gateway.remote.token` / `.password` 只是客户端侧远程凭证；它们本身不会启用本地 gateway 身份验证。 + - `gateway.remote.token` / `.password` 只是客户端侧远程凭证；它们本身不会启用本地 Gateway 网关认证。 - - 你的 gateway 身份验证路径与 UI 的身份验证方法不匹配。 + + 你的 Gateway 网关认证路径和 UI 的认证方式不匹配。 事实（来自代码）： - - Control UI 会把令牌保存在当前浏览器标签页会话和所选 gateway URL 的 `sessionStorage` 中，因此同一标签页刷新仍可继续工作，而不会恢复长期存在的 localStorage 令牌持久化。 - - 遇到 `AUTH_TOKEN_MISMATCH` 时，如果 gateway 返回重试提示（`canRetryWithDeviceToken=true`、`recommendedNextStep=retry_with_device_token`），受信任客户端可以尝试使用缓存的设备令牌进行一次有界重试。 - - 该缓存令牌重试现在会复用与设备令牌一起存储的已批准缓存作用域。显式 `deviceToken` / 显式 `scopes` 调用方仍会保留其请求的作用域集合，而不是继承缓存作用域。 - - 在该重试路径之外，连接身份验证优先级为：显式共享令牌/密码优先，其次是显式 `deviceToken`，然后是已存储设备令牌，最后是引导令牌。 - - 引导令牌作用域检查带有角色前缀。内置引导操作员 allowlist 只满足操作员请求；节点或其他非操作员角色仍需要其自身角色前缀下的作用域。 + - Control UI 会把当前浏览器标签页会话和所选 Gateway 网关 URL 的令牌保存在 `sessionStorage` 中，因此同一标签页刷新仍可继续工作，而无需恢复长期 localStorage 令牌持久化。 + - 遇到 `AUTH_TOKEN_MISMATCH` 时，当 Gateway 网关返回重试提示（`canRetryWithDeviceToken=true`、`recommendedNextStep=retry_with_device_token`）时，受信任客户端可以尝试一次有界重试，并使用缓存的设备令牌。 + - 该缓存令牌重试现在会复用与设备令牌一起存储的缓存已批准作用域。显式 `deviceToken` / 显式 `scopes` 调用方仍会保留其请求的作用域集合，而不是继承缓存作用域。 + - 在该重试路径之外，连接认证优先级是：显式共享令牌/密码优先，然后是显式 `deviceToken`，然后是已存储的设备令牌，最后是引导令牌。 + - 引导令牌作用域检查带有角色前缀。内置引导操作员允许列表只满足操作员请求；节点或其他非操作员角色仍需要其自身角色前缀下的作用域。 修复： - - 最快：`openclaw dashboard`（打印并复制 dashboard URL，尝试打开；如果是无头环境则显示 SSH 提示）。 + - 最快方式：`openclaw dashboard`（打印并复制仪表板 URL，尝试打开；若为无头环境则显示 SSH 提示）。 - 如果你还没有令牌：`openclaw doctor --generate-gateway-token`。 - - 如果是远程，先建隧道：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。 + - 如果是远程，先建立隧道：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。 - 共享密钥模式：设置 `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` 或 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`，然后在 Control UI 设置中粘贴匹配的密钥。 - - Tailscale Serve 模式：确保 `gateway.auth.allowTailscale` 已启用，并且你打开的是 Serve URL，而不是会绕过 Tailscale 身份标头的原始 loopback/tailnet URL。 - - 受信任代理模式：确保你是通过已配置的感知身份代理进入，而不是通过原始 gateway URL。同主机 loopback 代理还需要 `gateway.auth.trustedProxy.allowLoopback = true`。 - - 如果一次重试后仍不匹配，请轮换/重新批准已配对的设备令牌： + - Tailscale Serve 模式：确保已启用 `gateway.auth.allowTailscale`，且你打开的是 Serve URL，而不是绕过 Tailscale 身份标头的原始 loopback/tailnet URL。 + - 受信任代理模式：确保你是通过已配置的身份感知代理访问，而不是使用原始 Gateway 网关 URL。同主机 loopback 代理还需要 `gateway.auth.trustedProxy.allowLoopback = true`。 + - 如果一次重试后仍不匹配，请轮换/重新批准已配对设备令牌： - `openclaw devices list` - `openclaw devices rotate --device --role operator` - - 如果该轮换调用提示被拒绝，请检查两点： - - 已配对设备会话只能轮换其**自己的**设备，除非它们还拥有 `operator.admin` - - 显式 `--scope` 值不能超过调用方当前的操作员作用域 - - 仍然卡住？运行 `openclaw status --all` 并按照[故障排除](/zh-CN/gateway/troubleshooting)操作。身份验证详情见 [Dashboard](/zh-CN/web/dashboard)。 + - 如果该轮换调用显示被拒绝，请检查两点： + - 已配对设备会话只能轮换其**自己的**设备，除非它们也拥有 `operator.admin` + - 显式 `--scope` 值不能超出调用方当前的操作员作用域 + - 仍然卡住？运行 `openclaw status --all` 并按照[故障排除](/zh-CN/gateway/troubleshooting)操作。认证详情见[仪表板](/zh-CN/web/dashboard)。 - - `tailnet` 绑定会从你的网络接口中选择一个 Tailscale IP（100.64.0.0/10）。如果机器不在 Tailscale 上（或接口已关闭），就没有可绑定的地址。 + + `tailnet` 绑定会从你的网络接口中选择一个 Tailscale IP（100.64.0.0/10）。如果该机器不在 Tailscale 上（或接口已关闭），就没有可绑定的内容。 修复： - 在该主机上启动 Tailscale（使其拥有 100.x 地址），或 - 切换到 `gateway.bind: "loopback"` / `"lan"`。 - 注意：`tailnet` 是显式设置。`auto` 会优先选择 loopback；如果你想要仅 tailnet 绑定，请使用 `gateway.bind: "tailnet"`。 + 注意：`tailnet` 是显式的。`auto` 偏好 loopback；当你需要仅 tailnet 绑定时，请使用 `gateway.bind: "tailnet"`。 - 通常不可以——一个 Gateway 网关可以运行多个消息渠道和智能体。只有在需要冗余（例如：救援机器人）或强隔离时，才使用多个 Gateway 网关。 + 通常不需要——一个 Gateway 网关可以运行多个消息渠道和智能体。只有在需要冗余（例如：救援机器人）或强隔离时，才使用多个 Gateway 网关。 - 可以，但你必须隔离： + 可以，但必须隔离： - - `OPENCLAW_CONFIG_PATH`（每实例配置） - - `OPENCLAW_STATE_DIR`（每实例状态） + - `OPENCLAW_CONFIG_PATH`（每个实例的配置） + - `OPENCLAW_STATE_DIR`（每个实例的状态） - `agents.defaults.workspace`（工作区隔离） - `gateway.port`（唯一端口） 快速设置（推荐）： - 每个实例使用 `openclaw --profile ...`（自动创建 `~/.openclaw-`）。 - - 在每个配置档案配置中设置唯一的 `gateway.port`（或手动运行时传入 `--port`）。 - - 安装每个配置档案对应的服务：`openclaw --profile gateway install`。 + - 在每个 profile 配置中设置唯一的 `gateway.port`（或为手动运行传入 `--port`）。 + - 安装每个 profile 的服务：`openclaw --profile gateway install`。 - 配置档案还会为服务名称添加后缀（`ai.openclaw.`；旧版 `com.openclaw.*`、`openclaw-gateway-.service`、`OpenClaw Gateway ()`）。 - 完整指南：[多个 gateway](/zh-CN/gateway/multiple-gateways)。 + Profiles 还会为服务名添加后缀（`ai.openclaw.`；旧版 `com.openclaw.*`、`openclaw-gateway-.service`、`OpenClaw Gateway ()`）。 + 完整指南：[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 - - Gateway 网关是一个 **WebSocket 服务器**，它期望第一条消息就是 + + Gateway 网关是一个 **WebSocket 服务器**，它期望第一条消息是 `connect` 帧。如果收到其他任何内容，它会以 **代码 1008**（策略违规） 关闭连接。 @@ -1507,15 +1522,15 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 - 你在浏览器中打开了 **HTTP** URL（`http://...`），而不是使用 WS 客户端。 - 你使用了错误的端口或路径。 - - 代理或隧道剥离了身份验证标头，或发送了非 Gateway 网关请求。 + - 代理或隧道剥离了认证标头，或发送了非 Gateway 网关请求。 快速修复： - 1. 使用 WS URL：`ws://:18789`（如果是 HTTPS，则用 `wss://...`）。 + 1. 使用 WS URL：`ws://:18789`（如果是 HTTPS，则使用 `wss://...`）。 2. 不要在普通浏览器标签页中打开 WS 端口。 - 3. 如果启用了身份验证，请在 `connect` 帧中包含令牌/密码。 + 3. 如果已启用认证，请在 `connect` 帧中包含令牌/密码。 - 如果你使用 CLI 或 TUI，URL 应类似于： + 如果你使用 CLI 或 TUI，URL 应如下所示： ``` openclaw tui --url ws://:18789 --token @@ -1526,7 +1541,7 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 -## 日志记录和调试 +## 日志和调试 @@ -1538,31 +1553,31 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 你可以通过 `logging.file` 设置稳定路径。文件日志级别由 `logging.level` 控制。控制台详细程度由 `--verbose` 和 `logging.consoleLevel` 控制。 - 最快查看日志尾部： + 最快跟踪日志： ```bash openclaw logs --follow ``` - 服务/监督器日志（当 gateway 通过 launchd/systemd 运行时）： + 服务/监督进程日志（当 Gateway 网关通过 launchd/systemd 运行时）： - - macOS：`$OPENCLAW_STATE_DIR/logs/gateway.log` 和 `gateway.err.log`（默认：`~/.openclaw/logs/...`；配置档案使用 `~/.openclaw-/logs/...`） + - macOS：`$OPENCLAW_STATE_DIR/logs/gateway.log` 和 `gateway.err.log`（默认：`~/.openclaw/logs/...`；profiles 使用 `~/.openclaw-/logs/...`） - Linux：`journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` - Windows：`schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` - 更多信息见[故障排除](/zh-CN/gateway/troubleshooting)。 + 更多内容见[故障排除](/zh-CN/gateway/troubleshooting)。 - 使用 gateway 辅助命令： + 使用 Gateway 网关辅助命令： ```bash openclaw gateway status openclaw gateway restart ``` - 如果你手动运行 gateway，`openclaw gateway --force` 可以收回端口。见 [Gateway 网关](/zh-CN/gateway)。 + 如果你手动运行 Gateway 网关，`openclaw gateway --force` 可以收回端口。见 [Gateway 网关](/zh-CN/gateway)。 @@ -1579,7 +1594,7 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 openclaw gateway restart ``` - 如果你从未安装服务，请在前台启动： + 如果你从未安装服务，请在前台启动它： ```bash openclaw gateway run @@ -1594,7 +1609,7 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 openclaw gateway restart ``` - 如果你手动运行它（没有服务），请使用： + 如果你手动运行它（无服务），请使用： ```powershell openclaw gateway run @@ -1604,8 +1619,8 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 - - 先做一次快速健康检查： + + 从快速健康检查开始： ```bash openclaw status @@ -1616,24 +1631,24 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 常见原因： - - 模型身份验证未加载到 **gateway 主机**上（检查 `models status`）。 - - 渠道配对/allowlist 阻止回复（检查渠道配置 + 日志）。 - - WebChat/Dashboard 已打开，但没有正确令牌。 + - 模型认证未加载到 **Gateway 网关主机**上（检查 `models status`）。 + - 渠道配对/允许列表阻止回复（检查渠道配置和日志）。 + - WebChat/Dashboard 已打开，但没有正确的令牌。 - 如果你是远程连接，请确认隧道/Tailscale 连接已启动，并且 + 如果你是远程访问，请确认隧道/Tailscale 连接已建立，且 Gateway 网关 WebSocket 可访问。 文档：[渠道](/zh-CN/channels)、[故障排除](/zh-CN/gateway/troubleshooting)、[远程访问](/zh-CN/gateway/remote)。 - + 这通常表示 UI 失去了 WebSocket 连接。请检查： 1. Gateway 网关是否正在运行？`openclaw gateway status` 2. Gateway 网关是否健康？`openclaw status` 3. UI 是否有正确的令牌？`openclaw dashboard` - 4. 如果是远程环境，隧道/Tailscale 链接是否已连通？ + 4. 如果是远程访问，隧道/Tailscale 链接是否已连通？ 然后跟踪日志： @@ -1641,7 +1656,7 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 openclaw logs --follow ``` - 文档：[仪表板](/zh-CN/web/dashboard)、[远程访问](/zh-CN/gateway/remote)、[故障排除](/zh-CN/gateway/troubleshooting)。 + 文档：[Dashboard](/zh-CN/web/dashboard)、[远程访问](/zh-CN/gateway/remote)、[故障排除](/zh-CN/gateway/troubleshooting)。 @@ -1655,10 +1670,10 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 然后匹配错误： - - `BOT_COMMANDS_TOO_MUCH`：Telegram 菜单条目过多。OpenClaw 已经会裁剪到 Telegram 限制并用更少命令重试，但仍需要丢弃一些菜单条目。减少插件/skill/自定义命令，或者如果不需要菜单，请禁用 `channels.telegram.commands.native`。 - - `TypeError: fetch failed`、`Network request for 'setMyCommands' failed!` 或类似网络错误：如果你在 VPS 上或位于代理后方，请确认允许出站 HTTPS，并且 DNS 可解析 `api.telegram.org`。 + - `BOT_COMMANDS_TOO_MUCH`：Telegram 菜单条目过多。OpenClaw 已经会裁剪到 Telegram 限制并用更少的命令重试，但仍需要删除一些菜单条目。减少插件/skill/自定义命令，或者如果你不需要菜单，请禁用 `channels.telegram.commands.native`。 + - `TypeError: fetch failed`、`Network request for 'setMyCommands' failed!` 或类似网络错误：如果你在 VPS 上或位于代理后面，请确认允许出站 HTTPS，并且 DNS 能够解析 `api.telegram.org`。 - 如果 Gateway 网关是远程的，请确保你查看的是 Gateway 网关主机上的日志。 + 如果 Gateway 网关在远程主机上，请确保你查看的是 Gateway 网关主机上的日志。 文档：[Telegram](/zh-CN/channels/telegram)、[渠道故障排除](/zh-CN/channels/troubleshooting)。 @@ -1680,7 +1695,7 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 - + 如果你安装了服务： ```bash @@ -1688,10 +1703,10 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 openclaw gateway start ``` - 这会停止/启动**受监督的服务**（macOS 上的 launchd，Linux 上的 systemd）。 - 当 Gateway 网关作为守护进程在后台运行时，请使用这个方式。 + 这会停止/启动**受管服务**（macOS 上的 launchd，Linux 上的 systemd）。 + 当 Gateway 网关作为守护进程在后台运行时，请使用这种方式。 - 如果你在前台运行，请用 Ctrl-C 停止，然后运行： + 如果你在前台运行，请用 Ctrl-C 停止，然后执行： ```bash openclaw gateway run @@ -1701,17 +1716,17 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 - + - `openclaw gateway restart`：重启**后台服务**（launchd/systemd）。 - - `openclaw gateway`：为当前终端会话在**前台**运行 Gateway 网关。 + - `openclaw gateway`：在此终端会话中**前台**运行 Gateway 网关。 - 如果你安装了服务，请使用 Gateway 网关命令。当你想进行一次性的前台运行时， + 如果你安装了服务，请使用 gateway 命令。当你想进行一次性的前台运行时， 使用 `openclaw gateway`。 - - 使用 `--verbose` 启动 Gateway 网关，以获得更多控制台细节。然后检查日志文件中的渠道凭证、模型路由和 RPC 错误。 + + 使用 `--verbose` 启动 Gateway 网关，以获得更多控制台细节。然后检查日志文件中的渠道认证、模型路由和 RPC 错误。 @@ -1719,7 +1734,7 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 - 智能体发出的出站附件必须包含一行 `MEDIA:`（单独一行）。请参见 [OpenClaw 助手设置](/zh-CN/start/openclaw)和[智能体发送](/zh-CN/tools/agent-send)。 + 智能体发出的出站附件必须包含一行 `MEDIA:`（单独成行）。请参阅 [OpenClaw assistant 设置](/zh-CN/start/openclaw)和[智能体发送](/zh-CN/tools/agent-send)。 CLI 发送： @@ -1727,14 +1742,14 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png ``` - 另请检查： + 还要检查： - - 目标渠道支持出站媒体，并且未被 allowlist 阻止。 - - 文件在提供商的大小限制内（图片会调整到最大 2048px）。 - - `tools.fs.workspaceOnly=true` 会把本地路径发送限制在工作区、临时/媒体存储，以及通过沙箱验证的文件中。 - - `tools.fs.workspaceOnly=false` 允许 `MEDIA:` 发送智能体已经可以读取的主机本地文件，但仅限媒体以及安全的文档类型（图片、音频、视频、PDF 和 Office 文档）。纯文本和类似密钥的文件仍会被阻止。 + - 目标渠道支持出站媒体，并且未被允许列表阻止。 + - 文件在提供商的大小限制内（图片会被缩放到最大 2048px）。 + - `tools.fs.workspaceOnly=true` 会将本地路径发送限制在工作区、临时/媒体存储以及通过沙箱验证的文件内。 + - `tools.fs.workspaceOnly=false` 允许 `MEDIA:` 发送智能体已经能读取的主机本地文件，但仅限媒体和安全文档类型（图片、音频、视频、PDF 和 Office 文档）。纯文本和类似密钥的文件仍会被阻止。 - 请参见[图片](/zh-CN/nodes/images)。 + 参见[图片](/zh-CN/nodes/images)。 @@ -1742,46 +1757,46 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 ## 安全和访问控制 - + 将入站私信视为不受信任的输入。默认设置旨在降低风险： - 支持私信的渠道上的默认行为是**配对**： - 未知发送者会收到配对码；机器人不会处理他们的消息。 - 使用以下命令批准：`openclaw pairing approve --channel [--account ] ` - 待处理请求上限为**每个渠道 3 个**；如果没有收到代码，请检查 `openclaw pairing list --channel [--account ]`。 - - 公开开放私信需要显式选择启用（`dmPolicy: "open"` 和 allowlist `"*"`）。 + - 公开开放私信需要明确选择加入（`dmPolicy: "open"` 和允许列表 `"*"`）。 - 运行 `openclaw doctor` 以显示有风险的私信策略。 + 运行 `openclaw doctor` 以暴露有风险的私信策略。 - 不是。提示注入关乎**不受信任的内容**，而不仅仅是谁可以给机器人发私信。 - 如果你的助手读取外部内容（Web 搜索/抓取、浏览器页面、电子邮件、 + 不是。提示注入关乎**不受信任的内容**，而不只是“谁可以私信机器人”。 + 如果你的 assistant 读取外部内容（Web 搜索/获取、浏览器页面、电子邮件、 文档、附件、粘贴的日志），这些内容可能包含试图劫持模型的指令。 - 即使**你是唯一发送者**，这也可能发生。 + 即使**你是唯一的发送者**，这种情况也可能发生。 - 最大风险出现在启用了工具时：模型可能被诱导代表你 - 泄露上下文或调用工具。通过以下方式降低影响范围： + 最大的风险出现在启用工具时：模型可能被诱导 + 泄露上下文或代表你调用工具。通过以下方式降低影响范围： - 使用只读或禁用工具的“reader”智能体来总结不受信任的内容 - 对启用工具的智能体关闭 `web_search` / `web_fetch` / `browser` - 也将解码后的文件/文档文本视为不受信任：OpenResponses - `input_file` 和媒体附件提取都会把提取文本包裹在 - 明确的外部内容边界标记中，而不是传递原始文件文本 - - 使用沙箱隔离和严格的工具 allowlist + `input_file` 和媒体附件提取都会用 + 明确的外部内容边界标记包裹提取文本，而不是传递原始文件文本 + - 沙箱隔离和严格的工具允许列表 详情：[安全](/zh-CN/gateway/security)。 - - 是的，对大多数设置来说应该如此。用单独账号和电话号码隔离机器人 - 可以在出问题时降低影响范围。这也让你更容易轮换 - 凭证或撤销访问权限，而不影响你的个人账号。 + + 是的，对于大多数设置都应该这样做。用单独账号和电话号码隔离机器人， + 可以在出现问题时降低影响范围。这也让你更容易轮换 + 凭证或撤销访问权限，而不会影响你的个人账号。 - 从小范围开始。只授予实际需要的工具和账号访问权限，并在 - 以后需要时再扩展。 + 从小范围开始。只授予你实际需要的工具和账号访问权限，并在 + 需要时再扩展。 文档：[安全](/zh-CN/gateway/security)、[配对](/zh-CN/channels/pairing)。 @@ -1790,24 +1805,24 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 我们**不**建议让它完全自主处理你的个人消息。最安全的模式是： - - 将私信保持在**配对模式**或严格 allowlist 中。 - - 如果你希望它代表你发送消息，请使用**单独的号码或账号**。 - - 让它起草，然后在**发送前批准**。 + - 将私信保持在**配对模式**或严格的允许列表中。 + - 如果你希望它代表你发消息，请使用**单独的号码或账号**。 + - 让它先起草，然后**发送前批准**。 - 如果你想实验，请在专用账号上进行，并保持隔离。请参见 + 如果你想实验，请在专用账号上进行并保持隔离。参见 [安全](/zh-CN/gateway/security)。 - - 可以，**前提是**智能体仅用于聊天且输入可信。较小档位 - 更容易受到指令劫持，因此应避免把它们用于启用工具的智能体， - 或用于读取不受信任内容。如果必须使用较小模型，请锁定 - 工具并在沙箱中运行。请参见[安全](/zh-CN/gateway/security)。 + + 可以，**前提是**该智能体仅用于聊天，并且输入可信。较小层级的模型 + 更容易受到指令劫持，因此避免将它们用于启用工具的智能体 + 或读取不受信任内容的场景。如果必须使用较小模型，请锁定 + 工具并在沙箱中运行。参见[安全](/zh-CN/gateway/security)。 - 只有当未知发送者给机器人发消息且 + 只有当未知发送者向机器人发送消息，并且 `dmPolicy: "pairing"` 已启用时，才会发送配对码。`/start` 本身不会生成代码。 检查待处理请求： @@ -1816,12 +1831,12 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 openclaw pairing list telegram ``` - 如果你想立即访问，请将你的发送者 ID 加入 allowlist，或为该账号设置 `dmPolicy: "open"`。 + 如果你想立即访问，请将你的发送者 ID 加入允许列表，或为该账号设置 `dmPolicy: "open"`。 - 不会。默认 WhatsApp 私信策略是**配对**。未知发送者只会收到配对码，其消息**不会被处理**。OpenClaw 只会回复它收到的聊天，或回复你显式触发的发送。 + 不会。默认 WhatsApp 私信策略是**配对**。未知发送者只会获得配对码，其消息**不会被处理**。OpenClaw 只会回复它收到的聊天，或回复你显式触发的发送。 使用以下命令批准配对： @@ -1835,16 +1850,16 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 openclaw pairing list whatsapp ``` - 向导电话号码提示：它用于设置你的 **allowlist/owner**，以允许你自己的私信。它不会用于自动发送。如果你在个人 WhatsApp 号码上运行，请使用该号码并启用 `channels.whatsapp.selfChatMode`。 + 向导电话号码提示：它用于设置你的**允许列表/所有者**，这样你的个人私信会被允许。它不会用于自动发送。如果你在个人 WhatsApp 号码上运行，请使用该号码并启用 `channels.whatsapp.selfChatMode`。 -## 聊天命令、中止任务和“它停不下来” +## 聊天命令、中止任务，以及“它停不下来” - 大多数内部消息或工具消息只有在该会话启用 **verbose**、**trace** 或 **reasoning** 时才会出现。 + 大多数内部消息或工具消息只会在该会话启用**详细**、**跟踪**或**推理**时出现。 在你看到它的聊天中修复： @@ -1854,11 +1869,11 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 /reasoning off ``` - 如果仍然很嘈杂，请在 Control UI 中检查会话设置，并将 verbose - 设置为**继承**。还要确认你没有使用在配置中将 `verboseDefault` 设置为 - `on` 的机器人配置文件。 + 如果仍然很吵，请在 Control UI 中检查会话设置，并将详细模式设置为 + **继承**。还要确认你没有使用在配置中将 `verboseDefault` 设置 + 为 `on` 的机器人资料。 - 文档：[Thinking 和 verbose](/zh-CN/tools/thinking)、[安全](/zh-CN/gateway/security/index#reasoning-and-verbose-output-in-groups)。 + 文档：[思考与详细模式](/zh-CN/tools/thinking)、[安全](/zh-CN/gateway/security/index#reasoning-and-verbose-output-in-groups)。 @@ -1889,19 +1904,19 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 这些是中止触发词（不是斜杠命令）。 - 对于后台进程（来自 exec 工具），你可以要求智能体运行： + 对于后台进程（来自 exec 工具），你可以让智能体运行： ``` process action:kill sessionId:XXX ``` - 斜杠命令概览：请参见[斜杠命令](/zh-CN/tools/slash-commands)。 + 斜杠命令概览：参见[斜杠命令](/zh-CN/tools/slash-commands)。 - 大多数命令必须作为以 `/` 开头的**独立**消息发送，但少数快捷命令（如 `/status`）也可供 allowlist 中的发送者内联使用。 + 大多数命令必须作为以 `/` 开头的**独立**消息发送，但少数快捷方式（如 `/status`）也可供允许列表中的发送者在行内使用。 - + OpenClaw 默认阻止**跨提供商**消息传递。如果工具调用绑定到 Telegram，除非你显式允许，否则它不会发送到 Discord。 @@ -1924,35 +1939,35 @@ Models 问答——默认值、选择、别名、切换、故障转移、身份 - - 队列模式控制新消息如何与进行中的运行交互。使用 `/queue` 更改模式： + + 队列模式控制新消息如何与正在进行的运行交互。使用 `/queue` 更改模式： - - `steer` - 将所有待处理 steering 排队到当前运行中的下一个模型边界 - - `queue` - 旧版一次一个的 steering - - `followup` - 一次运行一条消息 + - `steer` - 将所有待处理 Steering 排入当前运行中的下一个模型边界 + - `queue` - 旧版逐条 Steering + - `followup` - 逐条运行消息 - `collect` - 批处理消息并只回复一次 - `steer-backlog` - 立即 steer，然后处理积压消息 - `interrupt` - 中止当前运行并重新开始 - 默认模式是 `steer`。你可以为 followup 模式添加类似 `debounce:0.5s cap:25 drop:summarize` 的选项。请参见[命令队列](/zh-CN/concepts/queue)和[Steering queue](/zh-CN/concepts/queue-steering)。 + 默认模式是 `steer`。你可以为 followup 模式添加 `debounce:0.5s cap:25 drop:summarize` 等选项。参见[命令队列](/zh-CN/concepts/queue)和[Steering queue](/zh-CN/concepts/queue-steering)。 -## 其他 +## 杂项 - - 在 OpenClaw 中，凭证和模型选择是分开的。设置 `ANTHROPIC_API_KEY`（或在 auth profiles 中存储 Anthropic API key）会启用身份验证，但实际的默认模型是你在 `agents.defaults.model.primary` 中配置的任何模型（例如 `anthropic/claude-sonnet-4-6` 或 `anthropic/claude-opus-4-6`）。如果你看到 `No credentials found for profile "anthropic:default"`，这表示 Gateway 网关无法在正在运行的智能体的预期 `auth-profiles.json` 中找到 Anthropic 凭证。 + + 在 OpenClaw 中，凭据和模型选择是分开的。设置 `ANTHROPIC_API_KEY`（或在认证配置文件中存储 Anthropic API key）会启用身份认证，但实际的默认模型取决于你在 `agents.defaults.model.primary` 中配置的内容（例如 `anthropic/claude-sonnet-4-6` 或 `anthropic/claude-opus-4-6`）。如果你看到 `No credentials found for profile "anthropic:default"`，这表示 Gateway 网关无法在当前运行的智能体预期的 `auth-profiles.json` 中找到 Anthropic 凭据。 --- -仍然卡住？请在 [Discord](https://discord.com/invite/clawd) 中提问，或打开一个 [GitHub 讨论](https://github.com/openclaw/openclaw/discussions)。 +仍然卡住？在 [Discord](https://discord.com/invite/clawd) 提问，或发起 [GitHub 讨论](https://github.com/openclaw/openclaw/discussions)。 -## 相关 +## 相关内容 -- [首次运行常见问题](/zh-CN/help/faq-first-run) — 安装、新手引导、身份验证、订阅、早期故障 -- [Models 常见问题](/zh-CN/help/faq-models) — 模型选择、故障转移、auth profiles +- [首次运行常见问题](/zh-CN/help/faq-first-run) — 安装、新手引导、身份认证、订阅、早期故障 +- [Models 常见问题](/zh-CN/help/faq-models) — 模型选择、故障转移、认证配置文件 - [故障排除](/zh-CN/help/troubleshooting) — 按症状优先的分诊 diff --git a/docs/zh-CN/tools/plugin.md b/docs/zh-CN/tools/plugin.md index 6c5a68e12..8daef6026 100644 --- a/docs/zh-CN/tools/plugin.md +++ b/docs/zh-CN/tools/plugin.md @@ -1,28 +1,29 @@ --- read_when: - 安装或配置插件 - - 了解插件发现和加载规则 + - 了解插件发现与加载规则 - 使用与 Codex/Claude 兼容的插件包 sidebarTitle: Install and Configure summary: 安装、配置和管理 OpenClaw 插件 title: 插件 x-i18n: - generated_at: "2026-05-03T15:53:26Z" + generated_at: "2026-05-03T17:11:02Z" model: gpt-5.5 provider: openai - source_hash: 937623bf3bfd7832680264b28deaef58970b35fdae7cfa0e5731c097eccc38e6 + source_hash: 30e3cffc15c5c52dd539e21103c207c9e38955f9fd3acd561a52964eefafb8f0 source_path: tools/plugin.md workflow: 16 --- -插件为 OpenClaw 扩展新能力：渠道、模型提供商、智能体执行框架、工具、Skills、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是**核心**插件（随 OpenClaw 一起提供），另一些是**外部**插件。大多数外部插件通过 [ClawHub](/zh-CN/tools/clawhub) 发布和发现。在迁移完成之前，npm 仍支持直接安装，也会临时承载一组 OpenClaw 拥有的插件包。 +插件为 OpenClaw 扩展新能力：渠道、模型提供商、智能体运行框架、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。一些插件是 **核心**（随 OpenClaw 分发），另一些是 **外部**。大多数外部插件通过 [ClawHub](/zh-CN/tools/clawhub) 发布和发现。在该迁移完成之前，npm 仍支持直接安装，以及一组临时的 OpenClaw 自有插件包。 ## 快速开始 -如需可直接复制粘贴的安装、列表查看、卸载、更新和发布示例，请参阅[管理插件](/zh-CN/plugins/manage-plugins)。 +如需可直接复制粘贴的安装、列出、卸载、更新和发布示例，请参阅 +[管理插件](/zh-CN/plugins/manage-plugins)。 - + ```bash openclaw plugins list ``` @@ -58,9 +59,10 @@ x-i18n: - - 在运行中的 Gateway 网关里，仅限所有者使用的 `/plugins enable` 和 `/plugins disable` - 会触发 Gateway 网关配置重新加载器。Gateway 网关会在进程内重新加载插件运行时表面，新的智能体轮次会从刷新后的注册表重建工具列表。`/plugins install` 会更改插件源代码，因此 Gateway 网关会请求重启，而不是假装当前进程可以安全地重新加载已经导入的模块。 + + 在运行中的 Gateway 网关中，仅所有者可用的 `/plugins enable` 和 `/plugins disable` + 会触发 Gateway 网关配置重新加载器。Gateway 网关会在进程内重新加载插件运行时接口面，新的智能体轮次会从刷新后的注册表重建工具列表。`/plugins install` + 会更改插件源代码，因此 Gateway 网关会请求重启，而不是假定当前进程可以安全地重新加载已经导入的模块。 @@ -72,12 +74,12 @@ x-i18n: openclaw --help ``` - 当你需要证明已注册的工具、服务、gateway 方法、钩子或插件拥有的 CLI 命令时，请使用 `--runtime`。普通 `inspect` 是冷态清单/注册表检查，并且有意避免导入插件运行时。 + 当你需要证明已注册的工具、服务、Gateway 网关方法、钩子或插件拥有的 CLI 命令时，请使用 `--runtime`。普通 `inspect` 是一次冷态的清单/注册表检查，并且有意避免导入插件运行时。 -如果你偏好聊天原生控制，请启用 `commands.plugins: true` 并使用： +如果你更偏好聊天内原生控制，请启用 `commands.plugins: true` 并使用： ```text /plugin install clawhub: @@ -85,40 +87,49 @@ x-i18n: /plugin enable ``` -安装路径使用与 CLI 相同的解析器：本地路径/归档、显式 `clawhub:`、显式 `npm:`、显式 `git:`，或通过 npm 解析的裸包规范。 +安装路径使用与 CLI 相同的解析器：本地路径/归档、显式 +`clawhub:`、显式 `npm:`、显式 `git:`，或通过 npm 解析的无前缀包规格。 -如果配置无效，安装通常会失败关闭，并指引你使用 `openclaw doctor --fix`。唯一的恢复例外是一条狭窄的内置插件重装路径，仅适用于选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。 -在 Gateway 网关启动期间，某个插件的无效配置会被隔离到该插件：启动会记录 `plugins.entries..config` 问题，加载时跳过该插件，并保持其他插件和渠道在线。运行 `openclaw doctor --fix` 可通过禁用该插件条目并移除其无效配置负载来隔离错误插件配置；正常的配置备份会保留此前的值。 -当渠道配置引用了一个不再可发现的插件，但同一个过期插件 ID 仍保留在插件配置或安装记录中时，Gateway 网关启动会记录警告并跳过该渠道，而不是阻塞所有其他渠道。运行 `openclaw doctor --fix` 可移除过期的渠道/插件条目；没有过期插件证据的未知渠道键仍会验证失败，以便拼写错误保持可见。 -如果设置了 `plugins.enabled: false`，过期插件引用会被视为非活动：Gateway 网关启动会跳过插件发现/加载工作，`openclaw doctor` 会保留已禁用的插件配置，而不是自动移除它。若你想移除过期插件 ID，请先重新启用插件再运行 doctor 清理。 +如果配置无效，安装通常会拒绝继续，并提示你运行 +`openclaw doctor --fix`。唯一的恢复例外是一个范围很窄的内置插件重装路径，适用于选择启用 +`openclaw.install.allowInvalidConfigRecovery` 的插件。 +在 Gateway 网关启动期间，无效的插件配置会像任何其他无效配置一样导致启动拒绝继续。运行 `openclaw doctor --fix` 可隔离有问题的插件配置，方法是禁用该插件条目并移除其无效配置载荷；常规配置备份会保留先前值。 +当某个渠道配置引用了一个不再可发现的插件，但同一个过期插件 ID 仍保留在插件配置或安装记录中时，Gateway 网关启动会记录警告并跳过该渠道，而不是阻塞所有其他渠道。 +运行 `openclaw doctor --fix` 可移除过期的渠道/插件条目；没有过期插件证据的未知渠道键仍会验证失败，以便拼写错误保持可见。 +如果设置了 `plugins.enabled: false`，过期插件引用会被视为惰性：Gateway 网关启动会跳过插件发现/加载工作，`openclaw doctor` 会保留已禁用的插件配置，而不是自动移除它。如果你希望移除过期插件 ID，请先重新启用插件再运行 Doctor 清理。 -插件依赖安装只会在显式安装/更新或 doctor 修复流程中发生。Gateway 网关启动、配置重新加载和运行时检查不会运行包管理器，也不会修复依赖树。本地插件必须已经安装其依赖，而 npm、git 和 ClawHub 插件会安装到 OpenClaw 的托管插件根目录下。npm 依赖可能会在 OpenClaw 的托管 npm 根目录内提升；安装/更新会先扫描该托管根目录，再进行信任判断，卸载会通过 npm 移除 npm 托管的包。外部插件和自定义加载路径仍必须通过 `openclaw plugins install` 安装。 -使用 `openclaw plugins list --json` 可以查看每个可见插件的静态 `dependencyStatus`，无需导入运行时代码或修复依赖。 -有关安装时生命周期，请参阅[插件依赖解析](/zh-CN/plugins/dependency-resolution)。 +插件依赖安装只会在显式安装/更新或 Doctor 修复流程中发生。Gateway 网关启动、配置重新加载和运行时检查不会运行包管理器，也不会修复依赖树。本地插件必须已经安装好依赖，而 npm、git 和 ClawHub 插件会安装到 OpenClaw 的托管插件根目录下。npm 依赖可能会在 OpenClaw 的托管 npm 根目录内提升；安装/更新会先扫描该托管根目录再信任它，卸载会通过 npm 移除由 npm 管理的包。外部插件和自定义加载路径仍必须通过 `openclaw plugins install` 安装。 +使用 `openclaw plugins list --json` 可以查看每个可见插件的静态 `dependencyStatus`，而无需导入运行时代码或修复依赖。 +有关安装时生命周期，请参阅 [插件依赖解析](/zh-CN/plugins/dependency-resolution)。 -对于 npm 安装，`latest` 或 dist-tag 等可变选择器会在安装前解析，然后固定到 OpenClaw 托管 npm 根目录中的精确已验证版本。npm 完成后，OpenClaw 会验证已安装的 `package-lock.json` 条目仍与解析出的版本和完整性匹配。如果 npm 写入了不同的包元数据，安装会失败，并回滚托管包，而不是接受不同的插件工件。 +对于 npm 安装，`latest` 或分发标签等可变选择器会在安装前解析，然后固定到 OpenClaw 托管 npm 根目录中经过精确验证的版本。npm 完成后，OpenClaw 会验证已安装的 +`package-lock.json` 条目仍然匹配解析出的版本和完整性。如果 npm 写入了不同的包元数据，安装会失败并回滚托管包，而不是接受不同的插件制品。 -源码检出是 pnpm 工作区。如果你克隆 OpenClaw 来修改内置插件，请运行 `pnpm install`；随后 OpenClaw 会从 `extensions/` 加载内置插件，因此编辑内容和包本地依赖会被直接使用。普通 npm 根目录安装适用于打包版 OpenClaw，而不是源码检出开发。 +源码检出是 pnpm 工作区。如果你克隆 OpenClaw 来修改内置插件，请运行 `pnpm install`；随后 OpenClaw 会从 +`extensions/` 加载内置插件，以便直接使用编辑内容和包本地依赖。 +普通的 npm 根目录安装适用于打包版 OpenClaw，而不是源码检出开发。 ## 插件类型 OpenClaw 识别两种插件格式： -| 格式 | 工作方式 | 示例 | +| 格式 | 工作方式 | 示例 | | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ | -| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 | -| **Bundle** | Codex/Claude/Cursor 兼容布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` | +| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 | +| **包** | 兼容 Codex/Claude/Cursor 的布局；映射为 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` | -两者都会显示在 `openclaw plugins list` 下。有关 Bundle 详情，请参阅[插件 Bundle](/zh-CN/plugins/bundles)。 +两者都会显示在 `openclaw plugins list` 中。有关插件包的详细信息，请参阅 [插件包](/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 包必须在 `package.json` 中声明 `openclaw.extensions`。每个条目都必须保留在包目录内部，并解析为可读取的运行时文件，或解析为一个 TypeScript 源文件，其内推的已构建 JavaScript 对等文件例如从 `src/index.ts` 到 `dist/index.js`。 -打包安装必须随包提供该 JavaScript 运行时输出。TypeScript 源码回退用于源码检出和本地开发路径，而不是用于安装到 OpenClaw 托管插件根目录中的 npm 包。 +原生插件 npm 包必须在 `package.json` 中声明 `openclaw.extensions`。 +每个条目都必须位于包目录内，并解析为可读取的运行时文件，或解析为一个 TypeScript 源文件，且能够推断出对应的已构建 JavaScript 对等文件，例如从 `src/index.ts` 到 `dist/index.js`。 +打包安装必须随附该 JavaScript 运行时输出。TypeScript 源码回退用于源码检出和本地开发路径，不适用于安装到 OpenClaw 托管插件根目录中的 npm 包。 -当发布的运行时文件与源条目不在相同路径时，请使用 `openclaw.runtimeExtensions`。存在时，`runtimeExtensions` 必须为每个 `extensions` 条目包含且仅包含一个条目。列表不匹配会导致安装和插件发现失败，而不是静默回退到源码路径。如果你也发布 `openclaw.setupEntry`，请为其已构建 JavaScript 对等文件使用 `openclaw.runtimeSetupEntry`；声明时该文件是必需的。 +当发布的运行时文件与源码条目不在相同路径时，请使用 `openclaw.runtimeExtensions`。存在时，`runtimeExtensions` 必须为每个 `extensions` 条目精确包含一个条目。列表不匹配会导致安装和插件发现失败，而不会静默回退到源码路径。如果你也发布 `openclaw.setupEntry`，请为它的已构建 JavaScript 对等文件使用 `openclaw.runtimeSetupEntry`；声明后该文件必须存在。 ```json { @@ -132,13 +143,13 @@ OpenClaw 识别两种插件格式： ## 官方插件 -### 迁移期间 OpenClaw 拥有的 npm 包 +### 迁移期间 OpenClaw 自有的 npm 包 -ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版本已经内置许多官方插件，因此在常规设置中不需要单独进行 npm 安装。在每个 OpenClaw 拥有的插件都迁移到 ClawHub 之前，OpenClaw 仍会在 npm 上发布一些 `@openclaw/*` 插件包，用于较旧/自定义安装和直接 npm 工作流。 +ClawHub 是大多数插件的主要分发路径。当前打包版 OpenClaw 发行版已经内置许多官方插件，因此在普通设置中它们不需要单独的 npm 安装。在每个 OpenClaw 自有插件都迁移到 ClawHub 之前，OpenClaw 仍会在 npm 上发布一些 `@openclaw/*` 插件包，用于旧版/自定义安装和直接 npm 工作流。 -如果 npm 报告某个 `@openclaw/*` 插件包已弃用，则该包版本来自较旧的外部包发布线。请使用当前 OpenClaw 中的内置插件或本地检出，直到更新的 npm 包发布。 +如果 npm 报告某个 `@openclaw/*` 插件包已弃用，该包版本来自较旧的外部包发布序列。在更新的 npm 包发布之前，请使用当前 OpenClaw 中的内置插件或本地检出。 -| 插件 | 包 | 文档 | +| 插件 | 包 | 文档 | | --------------- | -------------------------- | ------------------------------------------ | | BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/zh-CN/channels/bluebubbles) | | Discord | `@openclaw/discord` | [Discord](/zh-CN/channels/discord) | @@ -154,7 +165,7 @@ ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版 | Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) | | Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) | -### 核心（随 OpenClaw 一起提供） +### 核心（随 OpenClaw 分发） @@ -166,10 +177,10 @@ ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版 - - `memory-core` — 内置记忆搜索（默认通过 `plugins.slots.memory` 使用） - - `memory-lancedb` — 基于 LanceDB 的长期记忆，支持自动召回/捕获（设置 `plugins.slots.memory = "memory-lancedb"`） + - `memory-core` — 内置记忆搜索（默认通过 `plugins.slots.memory` 启用） + - `memory-lancedb` — 由 LanceDB 支持的长期记忆，带自动召回/捕获（设置 `plugins.slots.memory = "memory-lancedb"`） - 有关 OpenAI 兼容的嵌入设置、Ollama 示例、召回限制和故障排除，请参阅 [Memory LanceDB](/zh-CN/plugins/memory-lancedb)。 + 有关兼容 OpenAI 的嵌入设置、Ollama 示例、召回限制和故障排除，请参阅 [Memory LanceDB](/zh-CN/plugins/memory-lancedb)。 @@ -178,13 +189,13 @@ ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版 - - `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` gateway 方法、浏览器运行时和默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用） + - `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时和默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用） - `copilot-proxy` — VS Code Copilot Proxy 桥接（默认禁用） -在找第三方插件？请参阅[社区插件](/zh-CN/plugins/community)。 +在寻找第三方插件？请参阅 [社区插件](/zh-CN/plugins/community)。 ## 配置 @@ -202,35 +213,49 @@ ClawHub 是大多数插件的主要分发路径。当前打包的 OpenClaw 版 } ``` -| 字段 | 描述 | +| 字段 | 说明 | | ---------------- | --------------------------------------------------------- | -| `enabled` | 总开关（默认：`true`） | -| `allow` | 插件允许列表（可选） | -| `deny` | 插件拒绝列表（可选；拒绝优先） | -| `load.paths` | 额外插件文件/目录 | -| `slots` | 独占槽选择器（例如 `memory`、`contextEngine`） | -| `entries.\` | 单个插件的开关 + 配置 | +| `enabled` | 总开关（默认值：`true`） | +| `allow` | 插件允许列表（可选） | +| `deny` | 插件拒绝列表（可选；拒绝优先） | +| `load.paths` | 额外插件文件/目录 | +| `slots` | 独占槽位选择器（例如 `memory`、`contextEngine`） | +| `entries.\` | 每个插件的开关 + 配置 | -`plugins.allow` 是独占的。当它非空时，只有列出的插件可以加载或暴露工具，即使 `tools.allow` 包含 `"*"` 或特定插件拥有的工具名称。如果某个工具允许列表引用了插件工具，请把拥有这些工具的插件 id 添加到 `plugins.allow`，或移除 `plugins.allow`；`openclaw doctor` 会对这种形态发出警告。 +`plugins.allow` 是排他的。当它非空时，只有列出的插件可以加载 +或暴露工具，即使 `tools.allow` 包含 `"*"` 或某个插件拥有的 +具体工具名称。如果某个工具允许列表引用插件工具，请将所属插件 ID +添加到 `plugins.allow`，或移除 `plugins.allow`；`openclaw doctor` 会对此 +形态发出警告。 -通过 `/plugins enable` 或 `/plugins disable` 做出的配置更改会触发进程内 Gateway 网关插件重新加载。新的智能体轮次会从刷新后的插件注册表重建其工具列表。安装、更新和卸载等更改源代码的操作仍会重启 Gateway 网关进程，因为已经导入的插件模块无法安全地就地替换。 +通过 `/plugins enable` 或 `/plugins disable` 做出的配置更改会触发 +进程内的 Gateway 网关插件重新加载。新的智能体轮次会从刷新后的插件注册表 +重新构建其工具列表。安装、更新和卸载等会改变源的操作仍会重启 +Gateway 网关进程，因为已经导入的插件模块无法安全地原地替换。 -`openclaw plugins list` 是本地插件注册表/配置快照。其中显示为 `enabled` 的插件表示持久化注册表和当前配置允许该插件参与运行。它并不能证明一个已经运行的远程 Gateway 网关已经重新加载或重启到相同的插件代码。在使用包装进程的 VPS/容器设置中，请把重启或触发重新加载的写入发送到实际的 `openclaw gateway run` 进程，或者在重新加载报告失败时，对正在运行的 Gateway 网关使用 `openclaw gateway restart`。 +`openclaw plugins list` 是本地插件注册表/配置快照。其中显示为 +`enabled` 的插件表示持久化注册表和当前配置允许该插件参与运行。 +这并不证明一个已在运行的远程 Gateway 网关已经重新加载或重启到 +同一份插件代码。在带有包装器进程的 VPS/容器设置中，请将重启或 +触发重新加载的写入发送到实际的 `openclaw gateway run` 进程，或者在 +重新加载报告失败时，对正在运行的 Gateway 网关使用 `openclaw gateway restart`。 - + - **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。 - - **缺失**：配置引用了设备发现未找到的插件 id。 - - **无效**：插件存在，但其配置不符合声明的 schema。Gateway 网关启动时只会跳过该插件；`openclaw doctor --fix` 可以通过禁用它并移除其配置负载来隔离这个无效条目。 + - **缺失**：配置引用了设备发现未找到的插件 ID。 + - **无效**：插件存在，但其配置与声明的架构不匹配。Gateway 网关启动时只跳过该插件；`openclaw doctor --fix` 可以通过禁用该插件并移除其配置载荷来隔离无效条目。 ## 设备发现和优先级 -OpenClaw 按以下顺序扫描插件（第一个匹配项优先）： +OpenClaw 按以下顺序扫描插件（第一个匹配项生效）： - `plugins.load.paths` — 显式文件或目录路径。指回 OpenClaw 自身打包的内置插件目录的路径会被忽略；运行 `openclaw doctor --fix` 可移除这些过时别名。 + `plugins.load.paths` — 显式文件或目录路径。指回 + OpenClaw 自身打包的内置插件目录的路径会被忽略； + 运行 `openclaw doctor --fix` 可移除这些过时别名。 @@ -242,37 +267,62 @@ OpenClaw 按以下顺序扫描插件（第一个匹配项优先）： - 随 OpenClaw 一起发布。许多默认启用（模型提供商、语音）。其他插件需要显式启用。 + 随 OpenClaw 一起发布。许多默认启用（模型提供商、语音）。 + 其他插件需要显式启用。 -打包安装和 Docker 镜像通常会从编译后的 `dist/extensions` 树解析内置插件。如果一个内置插件源目录被绑定挂载到匹配的打包源路径上，例如 `/app/extensions/synology-chat`，OpenClaw 会将该挂载的源目录视为内置源覆盖，并在打包的 `/app/dist/extensions/synology-chat` bundle 之前发现它。这样可以让维护者容器循环继续工作，而不必把每个内置插件都切回 TypeScript 源码。设置 `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` 可强制使用打包后的 dist bundle，即使存在源覆盖挂载也是如此。 +打包安装和 Docker 镜像通常会从编译后的 `dist/extensions` 树解析内置插件。 +如果某个内置插件源目录被绑定挂载到匹配的打包源路径上，例如 +`/app/extensions/synology-chat`，OpenClaw 会将该挂载的源目录 +视为内置源覆盖，并在打包的 +`/app/dist/extensions/synology-chat` 包之前发现它。这样可以让维护者容器 +循环继续工作，而无需将每个内置插件都切回 TypeScript 源码。 +设置 `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` 可强制使用打包的 dist 包， +即使存在源覆盖挂载也是如此。 ### 启用规则 -- `plugins.enabled: false` 会禁用所有插件，并跳过插件设备发现/加载工作 +- `plugins.enabled: false` 会禁用所有插件，并跳过插件发现/加载工作 - `plugins.deny` 始终优先于 allow - `plugins.entries.\.enabled: false` 会禁用该插件 - 工作区来源的插件**默认禁用**（必须显式启用） -- 内置插件遵循内置的默认启用集合，除非被覆盖 -- 独占槽可以强制启用该槽所选的插件 -- 当配置命名了插件拥有的表面时，某些内置的选择加入插件会自动启用，例如提供商模型引用、渠道配置或 harness 运行时 -- 当 `plugins.enabled: false` 处于激活状态时，过时插件配置会被保留；如果你想移除过时 id，请先重新启用插件再运行 Doctor 清理 -- OpenAI 家族 Codex 路由会保持独立的插件边界：`openai-codex/*` 属于 OpenAI 插件，而内置 Codex 应用服务器插件由 `agentRuntime.id: "codex"` 或旧版 `codex/*` 模型引用选择 +- 内置插件遵循内建的默认启用集合，除非被覆盖 +- 独占槽位可以强制启用该槽位选中的插件 +- 当配置命名了插件拥有的表面时，一些内置的选择性启用插件会自动启用， + 例如提供商模型引用、渠道配置或 harness 运行时 +- 当 `plugins.enabled: false` 处于活动状态时，过时插件配置会被保留； + 如果你希望移除过时 ID，请先重新启用插件，再运行 Doctor 清理 +- OpenAI 系列 Codex 路由保持独立的插件边界： + `openai-codex/*` 属于 OpenAI 插件，而内置 Codex + app-server 插件由 `agentRuntime.id: "codex"` 或旧版 + `codex/*` 模型引用选择 -## 故障排除运行时钩子 +## 排查运行时钩子问题 -如果某个插件出现在 `plugins list` 中，但 `register(api)` 副作用或钩子没有在实时聊天流量中运行，请先检查以下内容： +如果某个插件出现在 `plugins list` 中，但 `register(api)` 副作用或钩子 +没有在实时聊天流量中运行，请先检查这些项： -- 运行 `openclaw gateway status --deep --require-rpc`，确认活动 Gateway 网关 URL、profile、配置路径和进程就是你正在编辑的那些。 -- 在插件安装/配置/代码更改后重启实时 Gateway 网关。在包装容器中，PID 1 可能只是 supervisor；请重启或向子 `openclaw gateway run` 进程发送信号。 -- 使用 `openclaw plugins inspect --runtime --json` 确认钩子注册和诊断。非内置会话钩子，例如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`，需要 `plugins.entries..hooks.allowConversationAccess=true`。 -- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型解析之前运行；`llm_output` 只会在一次模型尝试产生助手输出之后运行。 -- 如需证明有效会话模型，请使用 `openclaw sessions` 或 Gateway 网关会话/status 表面；调试提供商负载时，请使用 `--raw-stream --raw-stream-path ` 启动 Gateway 网关。 +- 运行 `openclaw gateway status --deep --require-rpc`，并确认活动的 + Gateway 网关 URL、配置文件、配置路径和进程就是你正在编辑的那些。 +- 在插件安装/配置/代码变更后重启实时 Gateway 网关。在包装器 + 容器中，PID 1 可能只是一个监督进程；请重启或向子 + `openclaw gateway run` 进程发送信号。 +- 使用 `openclaw plugins inspect --runtime --json` 确认钩子注册和 + 诊断信息。非内置对话钩子，例如 `llm_input`、 + `llm_output`、`before_agent_finalize` 和 `agent_end`，需要 + `plugins.entries..hooks.allowConversationAccess=true`。 +- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的 + 模型解析之前运行；`llm_output` 只会在一次模型尝试 + 产生助手输出后运行。 +- 要证明有效会话模型，请使用 `openclaw sessions` 或 + Gateway 网关会话/状态表面；在调试提供商载荷时，使用 + `--raw-stream --raw-stream-path ` 启动 Gateway 网关。 ### 插件工具设置缓慢 -如果智能体轮次在准备工具时看起来停滞，请启用 trace 日志记录，并检查插件工具工厂计时行： +如果智能体轮次看起来在准备工具时卡住，请启用 trace 日志并 +检查插件工具工厂计时行： ```bash openclaw config set logging.level trace @@ -285,17 +335,24 @@ openclaw logs --follow [trace:plugin-tools] factory timings ... ``` -摘要会列出总工厂时间和最慢的插件工具工厂，包括插件 id、声明的工具名称、结果形态，以及该工具是否可选。当单个工厂耗时至少 1 秒或总插件工具工厂准备耗时至少 5 秒时，慢速行会提升为警告。 +摘要会列出总工厂耗时和最慢的插件工具工厂， +包括插件 ID、声明的工具名称、结果形态，以及该工具是否 +可选。当单个工厂耗时至少 1 秒，或插件工具工厂准备总耗时至少 5 秒时， +慢速行会提升为警告。 -OpenClaw 会缓存使用相同有效请求上下文重复解析时成功的插件工具工厂结果。缓存键包含有效运行时配置、工作区、智能体/会话 id、沙箱策略、浏览器设置、交付上下文、请求者身份和所有权状态，因此依赖这些可信字段的工厂会在上下文变化时重新运行。 +OpenClaw 会为相同有效请求上下文下的重复解析缓存成功的插件工具工厂结果。 +缓存键包含有效运行时配置、工作区、智能体/会话 ID、沙箱策略、浏览器设置、 +交付上下文、请求者身份和所有权状态，因此依赖这些可信字段的工厂会在 +上下文变化时重新运行。 -如果某个插件占用了大部分时间，请检查其运行时注册： +如果某个插件占用了主要耗时，请检查其运行时注册： ```bash openclaw plugins inspect --runtime --json ``` -然后更新、重新安装或禁用该插件。插件作者应将昂贵的依赖加载移到工具执行路径之后，而不是在工具工厂中执行。 +然后更新、重新安装或禁用该插件。插件作者应将昂贵的依赖加载 +移动到工具执行路径之后，而不是在工具工厂内执行。 ### 重复的渠道或工具所有权 @@ -305,24 +362,35 @@ openclaw plugins inspect --runtime --json - `channel setup already registered: ()` - `plugin tool name conflict (): ` -这些表示有多个已启用插件试图拥有同一个渠道、设置流程或工具名称。最常见原因是在现在提供相同渠道 id 的内置插件旁边安装了外部渠道插件。 +这些表示有多个已启用插件正在尝试拥有同一个渠道、 +设置流程或工具名称。最常见的原因是一个外部渠道插件 +安装在某个现在提供相同渠道 ID 的内置插件旁边。 调试步骤： -- 运行 `openclaw plugins list --enabled --verbose` 查看每个已启用插件及其来源。 -- 对每个可疑插件运行 `openclaw plugins inspect --runtime --json`，并比较 `channels`、`channelConfigs`、`tools` 和诊断。 -- 安装或移除插件包后，运行 `openclaw plugins registry --refresh`，以便持久化元数据反映当前安装。 +- 运行 `openclaw plugins list --enabled --verbose` 查看每个已启用插件 + 及其来源。 +- 对每个可疑插件运行 `openclaw plugins inspect --runtime --json`， + 并比较 `channels`、`channelConfigs`、`tools` 和诊断信息。 +- 在安装或移除插件包后运行 `openclaw plugins registry --refresh`， + 让持久化元数据反映当前安装。 - 在安装、注册表或配置更改后重启 Gateway 网关。 修复选项： -- 如果一个插件有意替换另一个具有相同渠道 id 的插件，则首选插件应声明 `channelConfigs..preferOver`，并填写优先级较低的插件 id。参见 [/plugins/manifest#replacing-another-channel-plugin](/zh-CN/plugins/manifest#replacing-another-channel-plugin)。 -- 如果重复是意外产生的，请使用 `plugins.entries..enabled: false` 禁用一方，或移除过时的插件安装。 -- 如果你显式启用了两个插件，OpenClaw 会保留该请求并报告冲突。请为该渠道选择一个所有者，或重命名插件拥有的工具，使运行时表面保持明确。 +- 如果一个插件有意替换另一个同渠道 ID 的插件，首选插件应声明 + `channelConfigs..preferOver`，并指向优先级较低的 + 插件 ID。参见 [/plugins/manifest#replacing-another-channel-plugin](/zh-CN/plugins/manifest#replacing-another-channel-plugin)。 +- 如果重复是意外造成的，请使用 + `plugins.entries..enabled: false` 禁用其中一方，或移除过时的插件 + 安装。 +- 如果你显式启用了两个插件，OpenClaw 会保留该请求并 + 报告冲突。请为该渠道选择一个所有者，或重命名插件拥有的 + 工具，使运行时表面没有歧义。 -## 插件槽（独占类别） +## 插件槽位（独占类别） -某些类别是独占的（同一时间只能有一个处于活动状态）： +某些类别是独占的（一次只能有一个活动项）： ```json5 { @@ -335,10 +403,10 @@ openclaw plugins inspect --runtime --json } ``` -| 槽 | 控制内容 | 默认值 | -| --------------- | ---------------- | ------------------- | -| `memory` | 主动记忆插件 | `memory-core` | -| `contextEngine` | 活动上下文引擎 | `legacy`（内置） | +| 槽位 | 控制内容 | 默认值 | +| --------------- | --------------------- | ------------------- | +| `memory` | 活动记忆插件 | `memory-core` | +| `contextEngine` | 活动上下文引擎 | `legacy`（内置） | ## CLI 参考 @@ -388,35 +456,35 @@ openclaw plugins enable openclaw plugins disable ``` -内置插件随 OpenClaw 一起发布。许多插件默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）。其他内置插件仍需要 `openclaw plugins enable `。 +OpenClaw 随附内置插件。许多插件默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）。其他内置插件仍需要 `openclaw plugins enable `。 -`--force` 会原地覆盖现有已安装的插件或钩子包。对于已跟踪的 npm 插件的常规升级，请使用 `openclaw plugins update `。它不支持与 `--link` 一起使用，因为 `--link` 会复用源路径，而不是复制到托管安装目标上。 +`--force` 会就地覆盖现有已安装的插件或钩子包。使用 `openclaw plugins update ` 对受跟踪的 npm 插件进行常规升级。它不支持与 `--link` 一起使用，因为 `--link` 会复用源路径，而不是复制到托管安装目标上。 -当 `plugins.allow` 已设置时，`openclaw plugins install` 会在启用已安装插件之前，将该插件 ID 添加到该允许列表。如果同一个插件 ID 存在于 `plugins.deny` 中，安装会移除这个过时的 deny 条目，以便显式安装在重启后立即可加载。 +当 `plugins.allow` 已设置时，`openclaw plugins install` 会先把已安装的插件 ID 添加到该允许列表，然后再启用它。如果同一个插件 ID 存在于 `plugins.deny` 中，安装会移除这条过时的拒绝项，使显式安装的插件在重启后可以立即加载。 -OpenClaw 会保留一个持久化的本地插件注册表，作为插件清单、贡献归属和启动规划的冷读模型。安装、更新、卸载、启用和停用流程会在更改插件状态后刷新该注册表。同一个 `plugins/installs.json` 文件会在顶层 `installRecords` 中保留持久安装元数据，并在 `plugins` 中保留可重建的清单元数据。如果注册表缺失、过时或无效，`openclaw plugins registry --refresh` 会从安装记录、配置策略以及清单/包元数据中重建其清单视图，而无需加载插件运行时模块。 -`openclaw plugins update ` 适用于已跟踪的安装。传入带有 dist-tag 或精确版本的 npm 包规范时，会将包名解析回已跟踪的插件记录，并记录新规范以供后续更新。传入不带版本的包名时，会把精确固定的安装切回注册表的默认发布线。如果已安装的 npm 插件已经匹配解析后的版本和记录的构件身份，OpenClaw 会跳过更新，不下载、不重新安装，也不重写配置。 +OpenClaw 会保留一个持久化的本地插件注册表，作为插件清单、贡献归属和启动规划的冷读取模型。安装、更新、卸载、启用和禁用流程会在更改插件状态后刷新该注册表。同一个 `plugins/installs.json` 文件会把持久安装元数据保存在顶层 `installRecords` 中，并把可重建的清单元数据保存在 `plugins` 中。如果注册表缺失、过时或无效，`openclaw plugins registry --refresh` 会从安装记录、配置策略以及清单/包元数据重建其清单视图，而不加载插件运行时模块。 +`openclaw plugins update ` 适用于受跟踪的安装。传入带有 dist-tag 或精确版本的 npm 包规范时，会把包名解析回受跟踪的插件记录，并记录新的规范以供未来更新。传入不带版本的包名时，会把精确固定版本的安装移回注册表的默认发布线。如果已安装的 npm 插件已经与解析出的版本和记录的构件身份一致，OpenClaw 会跳过更新，不下载、不重新安装，也不重写配置。 当 `openclaw update` 在 beta 渠道上运行时，默认线 npm 和 ClawHub 插件记录会先尝试 `@beta`，并在不存在插件 beta 版本时回退到默认/latest。精确版本和显式标签会保持固定。 -`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm 规范。 +`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 源元数据，而不是 npm 规范。 -`--dangerously-force-unsafe-install` 是针对内置危险代码扫描器误报的破窗式覆盖开关。它允许插件安装和插件更新在内置 `critical` 发现项之后继续执行，但仍不会绕过插件 `before_install` 策略阻断或扫描失败阻断。安装扫描会忽略常见测试文件和目录，例如 `tests/`、`__tests__/`、`*.test.*` 和 `*.spec.*`，以避免阻断打包的测试 mock；声明的插件运行时入口点即使使用这些名称之一，仍会被扫描。 +`--dangerously-force-unsafe-install` 是一个应急覆盖开关，用于处理内置危险代码扫描器的误报。它允许插件安装和插件更新在内置 `critical` 发现项后继续执行，但仍不会绕过插件 `before_install` 策略阻止或扫描失败阻止。安装扫描会忽略常见测试文件和目录，例如 `tests/`、`__tests__/`、`*.test.*` 和 `*.spec.*`，以避免阻止打包的测试 mock；声明的插件运行时入口点即使使用这些名称之一，仍会被扫描。 -此 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的 Skill 依赖安装改用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍是单独的 ClawHub Skill 下载/安装流程。 +此 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的技能依赖安装改用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍是单独的 ClawHub 技能下载/安装流程。 -如果你在 ClawHub 上发布的插件因扫描而被隐藏或阻断，请打开 ClawHub 控制台，或运行 `clawhub package rescan ` 来请求 ClawHub 再次检查它。`--dangerously-force-unsafe-install` 只影响你自己机器上的安装；它不会请求 ClawHub 重新扫描插件，也不会让被阻断的版本公开。 +如果你发布到 ClawHub 的插件被扫描隐藏或阻止，请打开 ClawHub 仪表板，或运行 `clawhub package rescan ` 请求 ClawHub 再次检查它。`--dangerously-force-unsafe-install` 只影响你自己机器上的安装；它不会请求 ClawHub 重新扫描该插件，也不会让被阻止的发布变为公开。 -兼容包参与同一套插件列表/检查/启用/停用流程。当前运行时支持包括包内 Skills、Claude 命令 Skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor 命令 Skills，以及兼容的 Codex 钩子目录。 +兼容包会参与同一个插件列表/检查/启用/禁用流程。当前运行时支持包括包内 Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex 钩子目录。 `openclaw plugins inspect ` 还会报告检测到的包能力，以及由包支持的插件中受支持或不受支持的 MCP 和 LSP 服务器条目。 -Marketplace 来源可以是 `~/.claude/plugins/known_marketplaces.json` 中的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须留在克隆的 marketplace 仓库内，并且只能使用相对路径来源。 +Marketplace 源可以是来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保留在克隆的 marketplace 仓库内，并且只能使用相对路径源。 -了解详情请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。 +请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins) 了解详情。 ## 插件 API 概览 -原生插件会导出一个暴露 `register(api)` 的入口对象。较旧的插件可能仍将 `activate(api)` 用作旧版别名，但新插件应使用 `register`。 +原生插件会导出一个入口对象，该对象暴露 `register(api)`。较旧的插件可能仍使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。 ```typescript export default definePluginEntry({ @@ -436,21 +504,21 @@ export default definePluginEntry({ }); ``` -OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为较旧的插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公开契约。 +OpenClaw 会在插件激活期间加载入口对象并调用 `register(api)`。加载器仍会为较旧插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公共契约。 -`api.registrationMode` 会告诉插件其入口为何被加载： +`api.registrationMode` 会告诉插件其入口为什么被加载： | 模式 | 含义 | | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `full` | 运行时激活。注册工具、钩子、服务、命令、路由和其他实时副作用。 | -| `discovery` | 只读能力发现。注册提供商和元数据；可信插件入口代码可能会加载，但跳过实时副作用。 | -| `setup-only` | 通过轻量设置入口加载渠道设置元数据。 | +| `full` | 运行时激活。注册工具、钩子、服务、命令、路由以及其他实时副作用。 | +| `discovery` | 只读能力发现。注册提供商和元数据；受信任的插件入口代码可以加载，但应跳过实时副作用。 | +| `setup-only` | 通过轻量级设置入口加载渠道设置元数据。 | | `setup-runtime` | 还需要运行时入口的渠道设置加载。 | | `cli-metadata` | 仅收集 CLI 命令元数据。 | -会打开套接字、数据库、后台 worker 或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 保护这些副作用。发现加载会与激活加载分开缓存，并且不会替换正在运行的 Gateway 网关注册表。发现是非激活的，但并非免导入：OpenClaw 可能会执行可信插件入口或渠道插件模块来构建快照。保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移动到完整运行时路径之后。 +会打开套接字、数据库、后台 worker 或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 保护这些副作用。发现加载会与激活加载分开缓存，并且不会替换正在运行的 Gateway 网关注册表。发现是非激活式的，但并非免导入：OpenClaw 可能会求值受信任的插件入口或渠道插件模块以构建快照。保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移到完整运行时路径后面。 -常用注册方法： +常见注册方法： | 方法 | 注册内容 | | --------------------------------------- | --------------------------- | @@ -465,7 +533,7 @@ OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)` | `registerImageGenerationProvider` | 图像生成 | | `registerMusicGenerationProvider` | 音乐生成 | | `registerVideoGenerationProvider` | 视频生成 | -| `registerWebFetchProvider` | Web 获取 / 抓取提供商 | +| `registerWebFetchProvider` | Web 抓取 / 抓取提供商 | | `registerWebSearchProvider` | Web 搜索 | | `registerHttpRoute` | HTTP 端点 | | `registerCommand` / `registerCli` | CLI 命令 | @@ -474,22 +542,22 @@ OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)` 类型化生命周期钩子的钩子保护行为： -- `before_tool_call`：`{ block: true }` 是终止性的；低优先级处理器会被跳过。 -- `before_tool_call`：`{ block: false }` 是无操作，不会清除先前的阻断。 -- `before_install`：`{ block: true }` 是终止性的；低优先级处理器会被跳过。 -- `before_install`：`{ block: false }` 是无操作，不会清除先前的阻断。 -- `message_sending`：`{ cancel: true }` 是终止性的；低优先级处理器会被跳过。 -- `message_sending`：`{ cancel: false }` 是无操作，不会清除先前的取消。 +- `before_tool_call`：`{ block: true }` 是终止性的；较低优先级的处理程序会被跳过。 +- `before_tool_call`：`{ block: false }` 是无操作，并且不会清除先前的阻止。 +- `before_install`：`{ block: true }` 是终止性的；较低优先级的处理程序会被跳过。 +- `before_install`：`{ block: false }` 是无操作，并且不会清除先前的阻止。 +- `message_sending`：`{ cancel: true }` 是终止性的；较低优先级的处理程序会被跳过。 +- `message_sending`：`{ cancel: false }` 是无操作，并且不会清除先前的取消。 -原生 Codex 应用服务器会把 Codex 原生工具事件桥接回这个钩子表面。插件可以通过 `before_tool_call` 阻断原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 审批。该桥接目前尚不会重写 Codex 原生工具参数。确切的 Codex 运行时支持边界位于 [Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract)。 +原生 Codex app-server 会把 Codex 原生工具事件桥接回这个钩子表面。插件可以通过 `before_tool_call` 阻止原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 审批。该桥接目前还不会重写 Codex 原生工具参数。确切的 Codex 运行时支持边界位于 [Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract)。 -完整的类型化钩子行为，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。 +完整的类型化钩子行为请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。 -## 相关内容 +## 相关 - [构建插件](/zh-CN/plugins/building-plugins) — 创建你自己的插件 - [插件包](/zh-CN/plugins/bundles) — Codex/Claude/Cursor 包兼容性 - [插件清单](/zh-CN/plugins/manifest) — 清单 schema - [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具 -- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载流水线 +- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载管线 - [社区插件](/zh-CN/plugins/community) — 第三方列表