openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-04 09:24:27 +00:00
parent da7db2d0e9
commit 02f0ad9d6f
3 changed files with 414 additions and 408 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

184
docs/zh-CN/cli/plugins.md
View File

@ -1,15 +1,15 @@
---
read_when:
- 你想安装或管理 Gateway 网关插件或兼容捆绑包
- 你想调试插件加载失败
- 你想安装或管理 Gateway 网关插件或兼容包
- 你想调试插件加载失败问题
sidebarTitle: Plugins
summary: '`openclaw plugins` 的 CLI 参考（list、install、marketplace、uninstall、enable/disable、doctor）'
title: 插件
x-i18n:
generated_at: "2026-05-04T08:21:20Z"
generated_at: "2026-05-04T09:22:18Z"
model: gpt-5.5
provider: openai
source_hash: d3f0ac9412e24f3598e9bab6389f770b3d0d26268d9907891697919d9371f1c1
source_hash: f561ce098181b07f25db3520b1726162863469ac05fb4a3e786915257d97c9a4
source_path: cli/plugins.md
workflow: 16
---
@ -18,7 +18,7 @@ x-i18n:
<CardGroup cols={2}>
<Card title="插件系统" href="/zh-CN/tools/plugin">
面向最终用户的插件安装、启用和故障排除指南。
用于安装、启用插件以及排查插件问题的最终用户指南。
</Card>
<Card title="管理插件" href="/zh-CN/plugins/manage-plugins">
安装、列出、更新、卸载和发布的快速示例。
@ -62,14 +62,14 @@ openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
排查安装、检查、卸载或 registry 刷新较慢的问题时，请使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 运行该命令。跟踪会将阶段耗时写入 stderr，并保持 JSON 输出可解析。请参阅 [调试](/zh-CN/help/debugging#plugin-lifecycle-trace)。
如需调查缓慢的安装、检查、卸载或注册表刷新，请使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 运行该命令。trace 会将阶段耗时写入 stderr，并保持 JSON 输出可解析。请参阅[调试](/zh-CN/help/debugging#plugin-lifecycle-trace)。
<Note>
内置插件随 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`。详细的 list/info 输出还会显示包子类型（`codex`、`claude` 或 `cursor`）以及检测到的包能力。
</Note>
### 安装
@ -91,61 +91,61 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
```
<Warning>
在发布切换期间，裸包名默认从 npm 安装。对 ClawHub 请使用 `clawhub:<package>`。把安装插件视同运行代码。优先使用固定版本。
在发布切换期间，裸包名默认从 npm 安装。对 ClawHub 使用 `clawhub:<package>`。应像运行代码一样看待插件安装。优先使用固定版本。
</Warning>
`plugins search` 会查询 ClawHub 中可安装的插件包，并打印可直接安装的包名。它搜索代码插件和包插件，不搜索 Skills。请使用 `openclaw skills search` 搜索 ClawHub Skills。
`plugins search` 会查询 ClawHub 中可安装的插件包，并打印可直接用于安装的包名。它搜索代码插件和包插件的软件包，而不是 Skills。使用 `openclaw skills search` 搜索 ClawHub Skills。
<Note>
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`。当 npm `beta` dist-tag 可用时，Beta 频道的安装和更新优先使用该标签，然后回退到 `latest`。
</Note>
<AccordionGroup>
<Accordion title="Config include 和无效配置修复">
如果你的 `plugins` 部分由单文件 `$include` 支持，`plugins install/update/enable/disable/uninstall` 会写入该被包含文件，并保持 `openclaw.json` 不变。根 include、include 数组以及带同级覆盖项的 include 会失败关闭，而不是展开合并。受支持的形状见 [配置 include](/zh-CN/gateway/configuration)。
<Accordion title="配置 include 和无效配置修复">
如果你的 `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` 的插件的窄范围内置插件恢复路径。
</Accordion>
<Accordion title="--force 与重新安装和更新">
`--force` 会复用现有安装目标，并在原位覆盖已安装的插件或钩子包。当你有意从新的本地路径、归档、ClawHub 包或 npm artifact 重新安装同一 id 时使用它。对于已跟踪 npm 插件的常规升级，优先使用 `openclaw plugins update <id-or-npm-spec>`。
<Accordion title="--force 和重新安装与更新">
`--force` 会复用现有安装目标，并就地覆盖已经安装的插件或钩子包。当你有意从新的本地路径、归档、ClawHub 包或 npm 构件重新安装同一 id 时使用它。对于已跟踪的 npm 插件的常规升级，优先使用 `openclaw plugins update <id-or-npm-spec>`。
如果你对已安装插件 id 运行 `plugins install`，OpenClaw 会停止，并提示你使用 `plugins update <id-or-npm-spec>` 进行正常升级，或在你确实想从不同来源覆盖当前安装时使用 `plugins install <package> --force`。
如果你对已安装的插件 id 运行 `plugins install`，OpenClaw 会停止，并指向 `plugins update <id-or-npm-spec>` 以进行正常升级；如果你确实想从不同来源覆盖当前安装，则指向 `plugins install <package> --force`。
</Accordion>
<Accordion title="--pin 作用范围">
`--pin` 仅适用于 npm 安装。它不支持 `git:` 安装；当你想固定来源时，请使用显式 git ref，例如 `git:github.com/acme/plugin@v1.2.3`。它不支持 `--marketplace`，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。
<Accordion title="--pin 范围">
`--pin` 仅适用于 npm 安装。它不支持 `git:` 安装；当你需要固定来源时，请使用显式 git ref，例如 `git:github.com/acme/plugin@v1.2.3`。它不支持 `--marketplace`，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。
</Accordion>
<Accordion title="--dangerously-force-unsafe-install">
`--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 上的插件被 registry 扫描阻止，请使用 [ClawHub](/zh-CN/tools/clawhub) 中的发布者步骤。
如果你发布在 ClawHub 上的插件被注册表扫描阻断，请使用 [ClawHub](/zh-CN/tools/clawhub) 中的发布者步骤。
</Accordion>
<Accordion title="钩子包和 npm spec">
`plugins install` 也是安装在 `package.json` 中暴露 `openclaw.hooks` 的钩子包的入口。请使用 `openclaw hooks` 查看经过筛选的钩子可见性和逐钩子启用状态，而不是用于安装包。
<Accordion title="钩子包和 npm specs">
`plugins install` 也是安装在 `package.json` 中暴露 `openclaw.hooks` 的钩子包的入口。使用 `openclaw hooks` 查看经过过滤的钩子可见性和逐钩子启用，不用于软件包安装。
Npm spec **仅限 registry**（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file spec 和 semver 范围会被拒绝。为了安全，即使你的 shell 有全局 npm 安装设置，依赖安装也会以项目本地方式运行，并带 `--ignore-scripts`。
Npm specs 是**仅注册表**形式（包名 + 可选的**精确版本**或 **dist-tag**）。Git/URL/file specs 和 semver 范围会被拒绝。为安全起见，依赖安装会以项目本地方式配合 `--ignore-scripts` 运行，即使你的 shell 设置了全局 npm 安装设置也是如此。
当你想显式使用 npm 解析时，请使用 `npm:<package>`。在发布切换期间，裸包 spec 也会直接从 npm 安装。
当你想明确使用 npm 解析时，请使用 `npm:<package>`。在发布切换期间，裸包 specs 也会直接从 npm 安装。
裸 spec 和 `@latest` 保持在稳定轨道上。OpenClaw 带日期戳的修正版，例如 `2026.5.3-1`，在此检查中属于稳定版本。如果 npm 将二者之一解析为预发布版，OpenClaw 会停止，并要求你通过预发布标签（例如 `@beta`/`@rc`）或精确预发布版本（例如 `@1.2.3-beta.4`）显式选择加入。
裸 specs 和 `@latest` 会停留在稳定轨道。OpenClaw 日期戳修正版（例如 `2026.5.3-1`）在此检查中属于稳定版本。如果 npm 将其中任一解析为预发布版本，OpenClaw 会停止，并要求你使用预发布标签（例如 `@beta`/`@rc`）或精确的预发布版本（例如 `@1.2.3-beta.4`）显式选择加入。
如果裸安装 spec 匹配官方插件 id（例如 `diffs`），OpenClaw 会直接安装目录条目。要安装同名 npm 包，请使用显式 scoped spec（例如 `@scope/diffs`）。
如果裸安装 spec 匹配官方插件 id（例如 `diffs`），OpenClaw 会直接安装目录条目。若要安装同名 npm 包，请使用显式作用域 spec（例如 `@scope/diffs`）。
</Accordion>
<Accordion title="Git 仓库">
使用 `git:<repo>` 直接从 git 仓库安装。支持的形式包括 `git:github.com/owner/repo`、`git:owner/repo`、完整 `https://`、`ssh://`、`git://`、`file://` 和 `git@host:owner/repo.git` clone URL。添加 `@<ref>` 或 `#<ref>` 可在安装前检出分支、标签或提交。
使用 `git:<repo>` 可直接从 git 仓库安装。受支持的形式包括 `git:github.com/owner/repo`、`git:owner/repo`、完整的 `https://`、`ssh://`、`git://`、`file://` 以及 `git@host:owner/repo.git` clone URL。添加 `@<ref>` 或 `#<ref>` 可在安装前检出分支、标签或提交。
Git 安装会克隆到临时目录，在存在请求 ref 时检出该 ref，然后使用普通插件目录安装器。这意味着清单验证、危险代码扫描、包管理器安装工作和安装记录的行为都像 npm 安装一样。记录的 git 安装包含来源 URL/ref 以及解析后的提交，因此 `openclaw plugins update` 之后可以重新解析该来源。
Git 安装会克隆到临时目录，在存在请求的 ref 时检出它，然后使用正常的插件目录安装器。这意味着清单验证、危险代码扫描、包管理器安装工作和安装记录的行为都类似 npm 安装。记录的 git 安装包含来源 URL/ref 以及解析后的提交，因此 `openclaw plugins update` 之后可以重新解析来源。
从 git 安装后，使用 `openclaw plugins inspect <id> --runtime --json` 验证运行时注册，例如 gateway 方法和 CLI 命令。如果插件通过 `api.registerCli` 注册了 CLI 根命令，请直接通过 OpenClaw 根 CLI 执行该命令，例如 `openclaw demo-plugin ping`。
</Accordion>
<Accordion title="归档">
支持的归档：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw 插件归档必须在解压后的插件根目录包含有效的 `openclaw.plugin.json`；只包含 `package.json` 的归档会在 OpenClaw 写入安装记录前被拒绝。
支持的归档：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw 插件归档必须在解压后的插件根目录包含有效的 `openclaw.plugin.json`；仅包含 `package.json` 的归档会在 OpenClaw 写入安装记录之前被拒绝。
也支持 Claude marketplace 安装。
@ -159,32 +159,32 @@ openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
在发布切换期间，裸 npm 安全插件 spec 默认从 npm 安装：
在发布切换期间，npm 安全的裸插件 specs 默认从 npm 安装：
```bash
openclaw plugins install openclaw-codex-app-server
```
使用 `npm:` 让 npm-only 解析显式化：
使用 `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 artifact 时，OpenClaw 会下载带版本的 npm-pack `.tgz`，验证 ClawHub digest header 和 artifact digest，然后通过普通归档路径安装它。没有 ClawPack 元数据的旧版 ClawHub 版本仍会通过旧版包归档验证路径安装。记录的安装会保留其 ClawHub 来源元数据、artifact 类型、npm integrity、npm shasum、tarball 名称和 ClawPack digest 事实，以供之后更新。
未指定版本的 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 的本地 registry 缓存 `~/.claude/plugins/known_marketplaces.json` 中时，使用 `plugin@marketplace` 简写：
当 marketplace 名称存在于 Claude 位于 `~/.claude/plugins/known_marketplaces.json` 的本地注册表缓存中时，请使用 `plugin@marketplace` 简写：
```bash
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```
当你想显式传入 marketplace 来源时，使用 `--marketplace`：
当你想显式传递 marketplace 来源时，请使用 `--marketplace`：
```bash
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
@ -195,19 +195,19 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
<Tabs>
<Tab title="市场源">
- `~/.claude/plugins/known_marketplaces.json` 中的 Claude 已知市场名称
- 来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知市场名称
- 本地市场根目录或 `marketplace.json` 路径
- `owner/repo` 这样的 GitHub 仓库简写
- `https://github.com/owner/repo` 这样的 GitHub 仓库 URL
- GitHub 仓库简写，例如 `owner/repo`
- GitHub 仓库 URL，例如 `https://github.com/owner/repo`
- git URL
</Tab>
<Tab title="远程市场规则">
对于从 GitHub 或 git 加载的远程市场，插件条目必须保留在克隆的市场仓库内。OpenClaw 接受来自该仓库的相对路径源，并拒绝远程清单中的 HTTP(S)、绝对路径、git、GitHub 和其他非路径插件源。
对于从 GitHub 或 git 加载的远程市场，插件条目必须保留在克隆的市场仓库内。OpenClaw 接受来自该仓库的相对路径源，并拒绝来自远程清单的 HTTP(S)、绝对路径、git、GitHub 以及其他非路径插件源。
</Tab>
</Tabs>
对于本地路径和归档文件，OpenClaw 会自动检测：
对于本地路径和归档，OpenClaw 会自动检测：
- 原生 OpenClaw 插件（`openclaw.plugin.json`）
- Codex 兼容包（`.codex-plugin/plugin.json`）
@ -215,10 +215,10 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
- Cursor 兼容包（`.cursor-plugin/plugin.json`）
<Note>
兼容包会安装到普通插件根目录，并参与相同的 list/info/enable/disable 流程。当前支持包 Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex 钩子目录；其他检测到的包能力会显示在 diagnostics/info 中，但尚未接入运行时执行。
兼容包会安装到常规插件根目录，并参与同一套列表/信息/启用/禁用流程。目前支持包 Skills、Claude 命令 Skills、Claude `settings.json` 默认值、Claude `.lsp.json` / 清单声明的 `lspServers` 默认值、Cursor 命令 Skills，以及兼容的 Codex 钩子目录；其他检测到的包能力会显示在诊断/信息中，但尚未接入运行时执行。
</Note>
### 列出
### 列表
```bash
openclaw plugins list
@ -234,56 +234,56 @@ openclaw plugins search <query> --json
仅显示已启用的插件。
</ParamField>
<ParamField path="--verbose" type="boolean">
从表格视图切换为逐插件详情行，包含 source/origin/version/activation 元数据。
从表格视图切换为每个插件的详细行，包含源/来源/版本/激活元数据。
</ParamField>
<ParamField path="--json" type="boolean">
机器可读的清单，加上注册表诊断信息和软件包依赖安装状态。
机器可读的清单，以及注册表诊断和包依赖安装状态。
</ParamField>
<Note>
`plugins list` 会先读取持久化的本地插件注册表；当注册表缺失或无效时，会使用仅从清单派生的回退结果。它适合用来检查插件是否已安装、已启用并且对冷启动规划可见，但它不是对已运行 Gateway 网关进程的实时运行时探测。更改插件代码、启用状态、钩子策略或 `plugins.load.paths` 后，应重启为该渠道提供服务的 Gateway 网关，然后再期待新的 `register(api)` 代码或钩子运行。对于远程/容器部署，请确认你重启的是实际的 `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` 查找路径中；它
`plugins list --json` 会包含每个插件来自 `package.json`
`dependencies` 和 `optionalDependencies` 的 `dependencyStatus`。OpenClaw 会检查这些包
名称是否存在于该插件正常的 Node `node_modules` 查找路径上；它
不会导入插件运行时代码、运行包管理器或修复缺失的
依赖。
</Note>
`plugins search` 是远程 ClawHub 目录查询。它不会检查本地
状态、修改配置、安装软件包或加载插件运行时代码。搜索
结果包括 ClawHub 软件包名称、系列、渠道、版本、摘要，以及
安装提示，例如 `openclaw plugins install clawhub:<package>`。
状态、变更配置、安装包或加载插件运行时代码。搜索
结果包含 ClawHub 包名称、系列、渠道、版本、摘要，以及
类似 `openclaw plugins install clawhub:<package>` 的安装提示。
对于打包 Docker 镜像中的内置插件工作，请将插件
对于打包 Docker 镜像内的内置插件工作，请将插件
源目录绑定挂载到匹配的打包源路径上，例如
`/app/extensions/synology-chat`。OpenClaw 会先于 `/app/dist/extensions/synology-chat` 发现该挂载的源
覆盖层；普通复制的源
目录仍保持惰性，因此正常打包安装仍会使用编译后的 dist。
`/app/extensions/synology-chat`。OpenClaw 会先发现该挂载的源
覆盖层，再发现 `/app/dist/extensions/synology-chat`；普通复制的源
目录会保持惰性，因此正常的打包安装仍会使用编译后的 dist。
对于运行时钩子调试：
- `openclaw plugins inspect <id> --runtime --json` 会显示来自模块加载检查过程的已注册钩子和诊断信息。运行时检查绝不会安装依赖；请使用 `openclaw doctor --fix` 清理旧版依赖状态或安装缺失的已配置可下载插件。
- `openclaw plugins inspect <id> --runtime --json` 会显示来自模块加载检查过程的已注册钩子和诊断。运行时检查绝不会安装依赖；使用 `openclaw doctor --fix` 清理旧版依赖状态，或安装缺失的已配置可下载插件。
- `openclaw gateway status --deep --require-rpc` 会确认可访问的 Gateway 网关、服务/进程提示、配置路径和 RPC 健康状态。
- 非内置会话钩子（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
- 非内置对话钩子（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
使用 `--link` 可避免复制本地目录（会添加到 `plugins.load.paths`）：
使用 `--link` 可以避免复制本地目录（会添加到 `plugins.load.paths`）：
```bash
openclaw plugins install -l ./my-plugin
```
<Note>
`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是覆盖托管安装目标。
`--force` 不支持与 `--link` 一起使用，因为链接安装会复用源路径，而不是复制覆盖托管安装目标。
在 npm 安装上使用 `--pin`，可将解析得到的精确规格（`name@version`）保存到托管插件索引中，同时保持默认行为为未固定。
在 npm 安装时使用 `--pin`，可将解析出的精确规格（`name@version`）保存到托管插件索引中，同时保持默认行为不固定版本。
</Note>
### 插件索引
插件安装元数据是由机器管理的状态，而不是用户配置。安装和更新会将其写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。其顶层 `installRecords` 映射是安装元数据的持久来源，包括损坏或缺失插件清单的记录。`plugins` 数组是从清单派生的冷注册表缓存。该文件包含请勿编辑警告，并由 `openclaw plugins update`、卸载、诊断以及冷插件注册表使用。
插件安装元数据是机器管理的状态，而不是用户配置。安装和更新会将其写入活动 OpenClaw 状态目录下的 `plugins/installs.json`。其顶层 `installRecords` 映射是安装元数据的持久来源，包括损坏或缺失插件清单的记录。`plugins` 数组是由清单派生的冷注册表缓存。该文件包含不要编辑的警告，并由 `openclaw plugins update`、卸载、诊断以及冷插件注册表使用。
当 OpenClaw 在配置中看到已发布的旧版 `plugins.installs` 记录时，它会将这些记录移动到插件索引并移除该配置键；如果任一写入失败，则保留配置记录，确保安装元数据不会丢失。
当 OpenClaw 在配置中看到已发布的旧版 `plugins.installs` 记录时，会将它们移动到插件索引中并移除该配置键；如果任一写入失败，配置记录会被保留，以免安装元数据丢失。
### 卸载
@ -293,10 +293,10 @@ openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` 会从 `plugins.entries`、持久化插件索引、插件允许/拒绝列表条目，以及适用时链接的 `plugins.load.paths` 条目中移除插件记录。除非设置了 `--keep-files`，否则当受跟踪的托管安装目录位于 OpenClaw 插件扩展根目录内时，卸载也会移除该目录。对于主动记忆插件，记忆槽会重置为 `memory-core`。
`uninstall` 会从 `plugins.entries`、持久化插件索引、插件允许/拒绝列表条目，以及适用时的已链接 `plugins.load.paths` 条目中移除插件记录。除非设置了 `--keep-files`，卸载还会在跟踪的托管安装目录位于 OpenClaw 插件扩展根目录内时将其移除。对于主动记忆插件，记忆槽会重置为 `memory-core`。
<Note>
`--keep-config` 作为 `--keep-files` 的弃用别名受到支持。
`--keep-config` 作为 `--keep-files` 的已弃用别名仍受支持。
</Note>
### 更新
@ -309,29 +309,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` 中跟踪的钩子包安装。
<AccordionGroup>
<Accordion title="解析插件 id 与 npm 规格">
当你传入插件 id 时，OpenClaw 会复用为该插件记录的安装规格。这意味着之前存储的 dist-tag（例如 `@beta`）和精确固定版本会在后续 `update <id>` 运行中继续使用。
当你传入插件 id 时，OpenClaw 会复用该插件记录的安装规格。这意味着之前存储的 dist-tag（例如 `@beta`）和精确固定版本会在之后运行 `update <id>` 时继续使用。
对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 软件包规格。OpenClaw 会将该软件包名称解析回受跟踪的插件记录，更新该已安装插件，并记录新的 npm 规格以供将来基于 id 的更新使用。
对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 包规格。OpenClaw 会将该包名解析回已跟踪的插件记录，更新该已安装插件，并记录新的 npm 规格以供未来基于 id 的更新使用。
传入不带版本或标签的 npm 软件包名称也会解析回受跟踪的插件记录。当插件已固定到精确版本，而你想将其移回注册表默认发布线时，请使用这种方式。
传入不带版本或标签的 npm 包名，也会解析回已跟踪的插件记录。当插件已固定到精确版本，而你想将它移回注册表默认发布线时，请使用这种方式。
</Accordion>
<Accordion title="Beta 渠道更新">
`openclaw plugins update` 会复用受跟踪的插件规格，除非你传入新规格。`openclaw update` 还知道活动的 OpenClaw 更新渠道：在 beta 渠道上，默认线 npm 和 ClawHub 插件记录会先尝试 `@beta`，如果不存在插件 beta 版本，则回退到记录的 default/latest 规格。精确版本和显式标签会继续固定到该选择器。
`openclaw plugins update` 会复用已跟踪的插件规格，除非你传入新的规格。`openclaw update` 还知道活动的 OpenClaw 更新渠道：在 beta 渠道上，默认线 npm 和 ClawHub 插件记录会先尝试 `@beta`，如果没有插件 beta 版本，再回退到记录的默认/latest 规格。精确版本和显式标签会继续固定到该选择器。
</Accordion>
<Accordion title="版本检查和完整性漂移">
在实时 npm 更新前，OpenClaw 会根据 npm 注册表元数据检查已安装的软件包版本。如果已安装版本和记录的工件身份已经与解析目标匹配，则会跳过更新，不下载、不重新安装，也不重写 `openclaw.json`。
在实时 npm 更新之前，OpenClaw 会根据 npm 注册表元数据检查已安装的包版本。如果已安装版本和记录的构件标识已经与解析目标匹配，则会跳过更新，不下载、不重新安装，也不重写 `openclaw.json`。
当存在已存储的完整性哈希且获取到的工件哈希发生变化时，OpenClaw 会将其视为 npm 工件漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。非交互式更新助手会默认关闭并失败，除非调用方提供显式的继续策略。
当存在已存储的完整性哈希，且获取到的构件哈希发生变化时，OpenClaw 会将其视为 npm 构件漂移。交互式 `openclaw plugins update` 命令会打印预期哈希和实际哈希，并在继续前请求确认。非交互式更新辅助工具会默认关闭失败，除非调用方提供显式的继续策略。
</Accordion>
<Accordion title="更新时的 --dangerously-force-unsafe-install">
`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的破窗覆盖选项。它仍不会绕过插件 `before_install` 策略阻止或扫描失败阻止，并且只适用于插件更新，不适用于 hook-pack 更新。
<Accordion title="更新时使用 --dangerously-force-unsafe-install">
`--dangerously-force-unsafe-install` 也可用于 `plugins update`，作为插件更新期间内置危险代码扫描误报的破窗覆盖项。它仍然不会绕过插件 `before_install` 策略阻断或扫描失败阻断，并且只适用于插件更新，不适用于钩子包更新。
</Accordion>
</AccordionGroup>
@ -343,21 +343,21 @@ openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
```
默认情况下，inspect 会显示身份、加载状态、来源、清单能力、策略标志、诊断信息、安装元数据、包能力，以及任何检测到的 MCP 或 LSP 服务器支持，而不会导入插件运行时。添加 `--runtime` 可加载插件模块，并包含已注册的钩子、工具、命令、服务、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 <command> ...` 运行；例如，注册了 `demo-git` 的插件可以通过 `openclaw demo-git ping` 验证。
插件拥有的 CLI 命令会安装为根 `openclaw` 命令组。在 `inspect --runtime` 于 `cliCommands` 下显示某个命令后，请以 `openclaw <command> ...` 运行它；例如，注册了 `demo-git` 的插件可以用 `openclaw demo-git ping` 验证。
每个插件会根据其在运行时实际注册的内容进行分类：
每个插件都会按其在运行时实际注册的内容分类：
- **plain-capability** — 一种能力类型（例如仅提供商插件）
- **hybrid-capability** — 多种能力类型（例如文本 + 语音 + 图像）
- **hook-only** — 仅钩子，无能力或表面
- **non-capability** — 工具/命令/服务，但无能力
- **hook-only** — 仅钩子，没有能力或表面
- **non-capability** — 工具/命令/服务，但没有能力
有关能力模型的更多信息，请参阅 [插件形态](/zh-CN/plugins/architecture#plugin-shapes)。
<Note>
`--json` 标志会输出适合脚本和审计的机器可读报告。`inspect --all` 会渲染全量插件表格，包含形态、能力种类、兼容性通知、包能力和钩子摘要列。`info` 是 `inspect` 的别名。
`--json` 标志会输出适合脚本和审计使用的机器可读报告。`inspect --all` 会呈现覆盖整个插件群的表格，包含形态、能力种类、兼容性通知、包能力和钩子摘要列。`info` 是 `inspect` 的别名。
</Note>
### Doctor
@ -366,11 +366,11 @@ openclaw plugins inspect <id> --json
openclaw plugins doctor
```
`doctor` 会报告插件加载错误、清单/发现诊断信息和兼容性通知。当一切正常时，它会打印 `No plugin issues detected.`
`doctor` 会报告插件加载错误、清单/发现诊断和兼容性通知。当一切正常时，它会打印 `No plugin issues detected.`
如果已配置插件存在于磁盘上，但被加载器的路径安全检查阻止，配置验证会保留插件条目并将其报告为 `present but blocked`。请修复前面的被阻止插件诊断，例如路径所有权或全局可写权限，而不是移除 `plugins.entries.<id>` 或 `plugins.allow` 配置。
如果已配置的插件存在于磁盘上，但被加载器的路径安全检查阻止，配置验证会保留该插件条目，并将其报告为 `present but blocked`。请修复前面的被阻止插件诊断，例如路径所有权或全局可写权限，而不是移除 `plugins.entries.<id>` 或 `plugins.allow` 配置。
对于缺少 `register`/`activate` 导出等模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以便在诊断输出中包含紧凑的导出形态摘要。
对于缺少 `register`/`activate` 导出等模块形态失败，请使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新运行，以在诊断输出中包含紧凑的导出形态摘要。
### 注册表
@ -380,26 +380,26 @@ openclaw plugins registry --refresh
openclaw plugins registry --json
```
本地插件注册表是 OpenClaw 针对已安装插件身份、启用状态、来源元数据和贡献所有权的持久化冷读取模型。正常启动、提供商所有者查找、渠道设置分类和插件清单都可以读取它，而无需导入插件运行时模块。
本地插件注册表是 OpenClaw 对已安装插件身份、启用状态、源元数据和贡献所有权持久化的冷读取模型。正常启动、提供商所有者查找、渠道设置分类和插件清单都可以读取它，而无需导入插件运行时模块。
使用 `plugins registry` 检查持久化注册表是否存在、是否为当前版本或是否已过期。使用 `--refresh` 可基于持久化插件索引、配置策略和插件清单/包元数据重新构建它。这是修复路径，不是运行时激活路径。
使用 `plugins registry` 检查持久化注册表是否存在、是否为当前版本或是否已过期。使用 `--refresh` 可根据持久化插件索引、配置策略以及清单/包元数据重建它。这是修复路径，不是运行时激活路径。
`openclaw doctor --fix` 也会修复与注册表相关的托管 npm 漂移：如果托管插件 npm 根目录下某个孤立的 `@openclaw/*` 包遮蔽了内置插件，doctor 会移除该过期包并重新构建注册表，让启动过程根据内置清单进行验证。
`openclaw doctor --fix` 还会修复注册表相邻的托管 npm 漂移：如果托管插件 npm 根目录下某个孤立或恢复的 `@openclaw/*` 包遮蔽了内置插件，Doctor 会移除该过期包并重建注册表，使启动时根据内置清单进行验证。
<Warning>
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是一个已弃用的应急兼容性开关，用于处理注册表读取失败。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；环境变量回退仅用于迁移推出期间的紧急启动恢复。
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是一个已弃用的应急兼容开关，用于处理注册表读取失败。优先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；环境变量回退机制仅用于迁移推出期间的紧急启动恢复。
</Warning>
### 市场
### 插件市场
```bash
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
市场列表接受本地市场路径、`marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。`--json` 会打印解析后的来源标签，以及解析后的市场清单和插件条目。
插件市场列表接受本地市场路径、`marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL 或 git URL。`--json` 会打印解析后的来源标签，以及解析后的市场清单和插件条目。
## 相关
## 相关内容
- [构建插件](/zh-CN/plugins/building-plugins)
- [CLI 参考](/zh-CN/cli)

357
docs/zh-CN/gateway/doctor.md
View File

@ -6,15 +6,15 @@ sidebarTitle: Doctor
summary: Doctor 命令：健康检查、配置迁移和修复步骤
title: Doctor
x-i18n:
generated_at: "2026-05-04T08:21:17Z"
generated_at: "2026-05-04T09:22:10Z"
model: gpt-5.5
provider: openai
source_hash: 00124eb5d85445080439d2603c65b78e85b0a2fded1cff121f21c330464f42cf
source_hash: 1bc8615f5e49e8c20785a9dc9779c447fd0d5794c80663d2396b0a20b4187798
source_path: gateway/doctor.md
workflow: 16
---
`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过时的配置/状态，检查健康状况，并提供可执行的修复步骤。
`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过期配置/状态、检查健康状况，并提供可执行的修复步骤。
## 快速开始
@ -22,7 +22,7 @@ x-i18n:
openclaw doctor
```
### 无界面和自动化模式
### 无头和自动化模式
<Tabs>
<Tab title="--yes">
@ -30,7 +30,7 @@ openclaw doctor
openclaw doctor --yes
```
不提示，直接接受默认值（在适用时包括重启/服务/沙箱修复步骤）。
不提示并接受默认值（适用时包括重启/服务/沙箱修复步骤）。
</Tab>
<Tab title="--repair">
@ -38,7 +38,7 @@ openclaw doctor
openclaw doctor --repair
```
不提示，应用推荐修复（在安全时执行修复 + 重启）。
不提示并应用推荐修复（在安全时执行修复 + 重启）。
</Tab>
<Tab title="--repair --force">
@ -54,7 +54,7 @@ openclaw doctor
openclaw doctor --non-interactive
```
无提示运行，并且只应用安全迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启/服务/沙箱操作。检测到旧版状态迁移时会自动运行。
不提示运行，并且只应用安全迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启/服务/沙箱操作。检测到旧版状态迁移时会自动运行。
</Tab>
<Tab title="--deep">
@ -62,12 +62,12 @@ openclaw doctor
openclaw doctor --deep
```
扫描系统服务，查找额外的 Gateway 网关安装（launchd/systemd/schtasks）。
扫描系统服务以查找额外的 Gateway 网关安装（launchd/systemd/schtasks）。
</Tab>
</Tabs>
如果你想在写入前审查变更，请先打开配置文件：
如果你想在写入前查看变更，请先打开配置文件：
```bash
cat ~/.openclaw/openclaw.json
@ -76,63 +76,63 @@ cat ~/.openclaw/openclaw.json
## 它会做什么（摘要）
<AccordionGroup>
<Accordion title="健康状况、界面和更新">
- 对 git 安装执行可选的预检更新（仅交互模式）。
- 界面协议新鲜度检查（当协议 schema 更新时重建 Control UI）。
<Accordion title="健康状况、UI 和更新">
- 针对 git 安装的可选预检更新（仅交互模式）。
- UI 协议新鲜度检查（当协议架构更新时重建 Control UI）。
- 健康检查 + 重启提示。
- Skills 状态摘要（符合条件/缺失/被阻止）和插件状态。
</Accordion>
<Accordion title="配置和迁移">
- 对旧版值进行配置规范化。
- 针对旧版值的配置规范化。
- 将旧版扁平 `talk.*` 字段中的 Talk 配置迁移到 `talk.provider` + `talk.providers.<provider>`。
- 检查旧版 Chrome 扩展配置的浏览器迁移和 Chrome MCP 就绪状态。
- 旧版 Chrome 扩展配置和 Chrome MCP 就绪状态的浏览器迁移检查。
- OpenCode 提供商覆盖警告（`models.providers.opencode` / `models.providers.opencode-go`）。
- Codex OAuth 遮蔽警告（`models.providers.openai-codex`）。
- OpenAI Codex OAuth 配置文件的 OAuth TLS 前置条件检查。
- 当 `plugins.allow` 限制严格但工具策略仍请求通配符或插件拥有的工具时，给出插件/工具 allowlist 警告。
- 旧版磁盘状态迁移（会话/智能体目录/WhatsApp 认证）。
- 旧版插件清单契约键迁移（`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`）。
- 旧版 cron 存储迁移（`jobId`, `schedule.cron`, 顶层 delivery/payload 字段，payload `provider`，简单 `notify: true` webhook 回退任务）。
- 当 `plugins.allow` 具有限制性但工具策略仍要求通配符或插件拥有的工具时，发出插件/工具允许列表警告。
- 旧版磁盘状态迁移（会话/智能体目录/WhatsApp 凭证）。
- 旧版插件清单合约键迁移（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。
- 旧版 cron 存储迁移（`jobId`、`schedule.cron`、顶层 delivery/payload 字段、payload `provider`、简单的 `notify: true` webhook 兜底作业）。
- 旧版智能体运行时策略迁移到 `agents.defaults.agentRuntime` 和 `agents.list[].agentRuntime`。
- 插件启用时清理过时的插件配置；当 `plugins.enabled=false` 时，过时的插件引用会被视为惰性的隔离配置并保留。
- 插件启用时清理过期插件配置；当 `plugins.enabled=false` 时，过期插件引用会被视为惰性的隔离配置并保留。
</Accordion>
<Accordion title="状态和完整性">
- 检查会话锁文件并清理过时锁。
- 修复受影响的 2026.4.24 构建创建的重复提示词重写分支对应的会话 transcript。
- 检测卡住的子智能体重启恢复 tombstone，并支持通过 `--fix` 清除过时的已中止恢复标志，避免启动时持续将子项视为重启已中止。
- 状态完整性和权限检查（会话、transcript、状态目录）。
- 会话锁文件检查和过期锁清理。
- 修复受影响的 2026.4.24 构建创建的重复 prompt-rewrite 分支会话转录。
- 检测卡住的子智能体重启恢复 tombstone，并支持使用 `--fix` 清除过期的已中止恢复标记，避免启动时继续将子智能体视为重启已中止。
- 状态完整性和权限检查（会话、转录、状态目录）。
- 本地运行时检查配置文件权限（chmod 600）。
- 模型认证健康状况：检查 OAuth 过期情况，可刷新即将过期的令牌，并报告认证配置文件的冷却/禁用状态。
- 检测额外工作区目录（`~/openclaw`）。
- 模型凭证健康：检查 OAuth 过期情况，可以刷新即将过期的 token，并报告 auth-profile 冷却/禁用状态。
- 额外工作区目录检测（`~/openclaw`）。
</Accordion>
<Accordion title="Gateway 网关、服务和 supervisor">
<Accordion title="Gateway 网关、服务和 supervisors">
- 启用沙箱隔离时修复沙箱镜像。
- 旧版服务迁移和额外 Gateway 网关检测。
- Matrix 渠道旧版状态迁移（在 `--fix` / `--repair` 模式下）。
- Gateway 网关运行时检查（服务已安装但未运行；缓存的 launchd 标签）。
- Gateway 网关运行时检查（服务已安装但未运行；缓存的 launchd label）。
- 渠道状态警告（从正在运行的 Gateway 网关探测）。
- supervisor 配置审计（launchd/systemd/schtasks），可选择修复。
- 清理 Gateway 网关服务的嵌入式代理环境，这些服务在安装或更新时捕获了 shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 值。
- Gateway 网关运行时最佳实践检查（Node vs Bun，版本管理器路径）。
- Supervisor 配置审计（launchd/systemd/schtasks）并支持可选修复。
- 清理 Gateway 网关服务的嵌入式代理环境，这些服务在安装或更新期间捕获了 shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 值。
- Gateway 网关运行时最佳实践检查（Node vs Bun、版本管理器路径）。
- Gateway 网关端口冲突诊断（默认 `18789`）。
</Accordion>
<Accordion title="认证、安全和配对">
<Accordion title="凭证、安全和配对">
- 开放私信策略的安全警告。
- 本地令牌模式的 Gateway 网关认证检查（没有令牌来源时提供令牌生成；不会覆盖令牌 SecretRef 配置）。
- 设备配对问题检测（待处理的首次配对请求、待处理的角色/范围升级、过时的本地设备令牌缓存漂移，以及已配对记录认证漂移）。
- 本地 token 模式的 Gateway 网关凭证检查（没有 token 来源时提供 token 生成；不会覆盖 token SecretRef 配置）。
- 设备配对问题检测（待处理的首次配对请求、待处理的角色/作用域升级、过期的本地 device-token 缓存漂移，以及 paired-record 凭证漂移）。
</Accordion>
<Accordion title="工作区和 shell">
- Linux 上的 systemd linger 检查。
- 工作区 bootstrap 文件大小检查（上下文文件截断/接近限制警告）。
- 默认智能体的 Skills 就绪检查；报告缺少二进制、环境变量、配置或 OS 要求的已允许 Skills，并且 `--fix` 可以在 `skills.entries` 中禁用不可用 Skills。
- shell 补全状态检查和自动安装/升级。
- Memory 搜索嵌入提供商就绪检查（本地模型、远程 API key 或 QMD 二进制）。
- 源码安装检查（pnpm 工作区不匹配、缺少 UI 资产、缺少 tsx 二进制）。
- 工作区 bootstrap 文件大小检查（上下文文件的截断/接近限制警告）。
- 默认智能体的 Skills 就绪检查；报告缺少 bin、环境变量、配置或 OS 要求的已允许 Skills，并且 `--fix` 可以在 `skills.entries` 中禁用不可用的 Skills。
- Shell 补全状态检查和自动安装/升级。
- 记忆搜索 embedding 提供商就绪检查（本地模型、远程 API key 或 QMD binary）。
- 源码安装检查（pnpm 工作区不匹配、缺少 UI 资源、缺少 tsx binary）。
- 写入更新后的配置 + 向导元数据。
</Accordion>
@ -140,19 +140,19 @@ cat ~/.openclaw/openclaw.json
## Dreams UI 回填和重置
Control UI Dreams 场景包含用于 grounded dreaming 工作流的 **回填**、**重置** 和 **清除 Grounded** 操作。这些操作使用 Gateway 网关 doctor 风格的 RPC 方法，但它们**不是** `openclaw doctor` CLI 修复/迁移的一部分。
Control UI 的 Dreams 场景为 grounded dreaming 工作流包含 **Backfill**、**Reset** 和 **Clear Grounded** 操作。这些操作使用 Gateway 网关 Doctor 风格的 RPC 方法，但它们**不**属于 `openclaw doctor` CLI 修复/迁移。
它们会做什么：
- **回填** 会扫描当前工作区中的历史 `memory/YYYY-MM-DD.md` 文件，运行 grounded REM 日记 pass，并将可逆的回填条目写入 `DREAMS.md`。
- **重置** 只会从 `DREAMS.md` 中移除那些标记过的回填日记条目。
- **清除 Grounded** 只会移除来自历史重放、且尚未积累实时召回或每日支持的暂存 grounded-only 短期条目。
- **Backfill** 扫描活动工作区中的历史 `memory/YYYY-MM-DD.md` 文件，运行 grounded REM diary pass，并将可逆回填条目写入 `DREAMS.md`。
- **Reset** 只从 `DREAMS.md` 中移除这些已标记的回填 diary 条目。
- **Clear Grounded** 只移除来自历史重放、且尚未累积实时召回或每日支持的暂存 grounded-only 短期条目。
它们本身**不会**做什么：
- 它们不会编辑 `MEMORY.md`
- 它们不会运行完整 doctor 迁移
- 除非你先显式运行暂存 CLI 路径，否则它们不会自动把 grounded 候选暂存到实时短期提升存储中
- 它们不会运行完整 Doctor 迁移
- 除非你先显式运行暂存 CLI 路径，否则它们不会自动把 grounded 候选项暂存到实时短期提升存储中
如果你想让 grounded 历史重放影响正常的深度提升通道，请改用 CLI 流程：
@ -160,32 +160,35 @@ Control UI Dreams 场景包含用于 grounded dreaming 工作流的 **回填**
openclaw memory rem-backfill --path ./memory --stage-short-term
```
这会把 grounded 持久候选暂存到短期 dreaming 存储中，同时让 `DREAMS.md` 保持为审查界面。
这会将 grounded durable 候选项暂存到短期 dreaming 存储，同时保留 `DREAMS.md` 作为审查界面。
## 详细行为和原理
<AccordionGroup>
<Accordion title="0. 可选更新（git 安装）">
如果这是一个 git checkout，并且 doctor 以交互模式运行，它会先提出更新（fetch/rebase/build），再运行 doctor。
如果这是 git checkout，并且 Doctor 以交互方式运行，它会在运行 Doctor 前提供更新（fetch/rebase/build）选项。
</Accordion>
<Accordion title="1. 配置规范化">
如果配置包含旧版值形态（例如没有渠道特定覆盖的 `messages.ackReaction`），doctor 会将它们规范化为当前 schema。
如果配置包含旧版值形状（例如没有渠道专用覆盖的 `messages.ackReaction`），Doctor 会将它们规范化为当前架构。
这包括旧版 Talk 扁平字段。当前公开的 Talk 配置是 `talk.provider` + `talk.providers.<provider>`。Doctor 会把旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形态重写到提供商 map 中。
这包括旧版 Talk 扁平字段。当前公开 Talk 配置是 `talk.provider` + `talk.providers.<provider>`。Doctor 会把旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形状重写到提供商映射中。
当 `plugins.allow` 非空且工具策略使用通配符或插件拥有的工具条目时，Doctor 也会发出警告。`tools.allow: ["*"]` 只匹配来自实际加载插件的工具；它不会绕过排他性的插件 allowlist。
当 `plugins.allow` 非空且工具策略使用
通配符或插件拥有的工具条目时，Doctor 也会发出警告。`tools.allow: ["*"]` 只匹配
实际加载的插件中的工具；它不会绕过排他性的插件
允许列表。
</Accordion>
<Accordion title="2. 旧版配置键迁移">
当配置包含已弃用的键时，其他命令会拒绝运行，并要求你运行 `openclaw doctor`。
当配置包含已弃用键时，其他命令会拒绝运行，并要求你运行 `openclaw doctor`。
Doctor 会：
Doctor 将会：
- 说明发现了哪些旧版键。
- 展示已应用的迁移。
- 使用更新后的 schema 重写 `~/.openclaw/openclaw.json`。
- 显示它应用的迁移。
- 使用更新后的架构重写 `~/.openclaw/openclaw.json`。
Gateway 网关在启动时如果检测到旧版配置格式，也会自动运行 doctor 迁移，因此过时配置无需人工干预就能修复。Cron 任务存储迁移由 `openclaw doctor --fix` 处理。
当 Gateway 网关在启动时检测到旧版配置格式，也会自动运行 Doctor 迁移，因此过期配置无需人工干预即可修复。Cron 作业存储迁移由 `openclaw doctor --fix` 处理。
当前迁移：
@ -211,284 +214,284 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
- `bindings[].match.accountID` → `bindings[].match.accountId`
- 对于具有命名 `accounts` 但仍保留单账号顶层渠道值的渠道，将这些账号范围值移动到为该渠道选择的提升账号中（大多数渠道为 `accounts.default`；Matrix 可以保留现有匹配的命名/默认目标）
- 对于带有命名 `accounts` 但仍残留单账号顶层渠道值的渠道，将这些账号作用域的值移动到为该渠道选择的提升账号中（大多数渠道为 `accounts.default`；Matrix 可以保留现有的匹配命名/默认目标）
- `identity` → `agents.list[].identity`
- `agent.*` → `agents.defaults` + `tools.*`（tools/elevated/exec/sandbox/subagents）
- `agent.*` → `agents.defaults` + `tools.*`（工具/提权/exec/沙箱/子智能体）
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
- 移除 `agents.defaults.llm`；对慢速提供商/模型超时使用 `models.providers.<id>.timeoutSeconds`
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- 移除 `browser.relayBindHost`（旧版扩展中继设置）
- 旧版 `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 网关启动时也会跳过 `api` 设为未来或未知枚举值的提供商，而不是关闭失败）
- 旧版 `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 网关启动时也会跳过 `api` 设置为未来或未知枚举值的提供商，而不是失败关闭）
Doctor 警告还包括多账号渠道的账号默认值指导：
- 如果配置了两个或更多 `channels.<channel>.accounts` 条目，却没有配置 `channels.<channel>.defaultAccount` 或 `accounts.default`，Doctor 会警告回退路由可能会选择意外的账号。
- 如果 `channels.<channel>.defaultAccount` 设为未知账号 ID，Doctor 会发出警告并列出已配置的账号 ID。
- 如果配置了两个或更多 `channels.<channel>.accounts` 条目，但没有配置 `channels.<channel>.defaultAccount` 或 `accounts.default`，Doctor 会警告回退路由可能选择意外账号。
- 如果 `channels.<channel>.defaultAccount` 设置为未知账号 ID，Doctor 会警告并列出已配置的账号 ID。
</Accordion>
<Accordion title="2b. OpenCode 提供商覆盖">
如果你手动添加了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它会覆盖来自 `@mariozechner/pi-ai` 的内置 OpenCode 目录。这可能会强制模型使用错误的 API，或将成本清零。Doctor 会发出警告，方便你移除覆盖并恢复按模型的 API 路由和成本。
如果你手动添加了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它会覆盖来自 `@mariozechner/pi-ai` 的内置 OpenCode 目录。这可能会强制模型使用错误的 API，或将成本清零。Doctor 会发出警告，这样你就可以移除覆盖并恢复按模型配置的 API 路由和成本。
</Accordion>
<Accordion title="2c. 浏览器迁移和 Chrome MCP 就绪状态">
如果你的浏览器配置仍指向已移除的 Chrome 扩展路径，Doctor 会将它规范化为当前的主机本地 Chrome MCP 附加模型：
如果你的浏览器配置仍指向已移除的 Chrome 扩展路径，Doctor 会将其规范化为当前主机本地的 Chrome MCP 附加模型：
- `browser.profiles.*.driver: "extension"` 变为 `"existing-session"`
- `browser.relayBindHost` 会被移除
当你使用 `defaultProfile: "user"` 或已配置的 `existing-session` 配置文件时，Doctor 还会审计主机本地 Chrome MCP 路径：
当你使用 `defaultProfile: "user"` 或已配置的 `existing-session` 配置文件时，Doctor 还会审核主机本地 Chrome MCP 路径：
- 检查默认自动连接配置文件所在的同一主机上是否安装了 Google Chrome
- 检查默认自动连接配置文件是否在同一主机上安装了 Google Chrome
- 检查检测到的 Chrome 版本，并在低于 Chrome 144 时发出警告
- 提醒你在浏览器检查页面启用远程调试（例如 `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging` 或 `edge://inspect/#remote-debugging`）
Doctor 无法替你启用 Chrome 端设置。主机本地 Chrome MCP 仍需要：
Doctor 无法替你启用 Chrome 侧的设置。主机本地 Chrome MCP 仍需要：
- Gateway 网关/节点主机上有基于 Chromium 的浏览器 144+
- Gateway 网关/节点主机上有基于 Chromium 的 144+ 浏览器
- 浏览器在本地运行
- 在该浏览器中启用远程调试
- 在浏览器中批准首次附加同意提示
- 该浏览器已启用远程调试
- 在浏览器中批准第一次附加同意提示
这里的就绪状态只涉及本地附加前置条件。Existing-session 会保留当前 Chrome MCP 路由限制；`responsebody`、PDF 导出、下载拦截和批量操作等高级路由仍需要托管浏览器或原始 CDP 配置文件。
这里的就绪状态只涉及本地附加前置条件。Existing-session 会保留当前的 Chrome MCP 路由限制；`responsebody`、PDF 导出、下载拦截和批量操作等高级路由仍需要托管浏览器或原始 CDP 配置文件。
此检查**不**适用于 Docker、沙箱、远程浏览器或其他无头流程。这些流程会继续使用原始 CDP。
</Accordion>
<Accordion title="2d. OAuth TLS 前置条件">
配置 OpenAI Codex OAuth 配置文件时，Doctor 会探测 OpenAI 授权端点，以验证本地 Node/OpenSSL TLS 栈是否能验证证书链。如果探测因证书错误而失败（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书过期或自签名证书），Doctor 会输出特定平台的修复指导。在使用 Homebrew Node 的 macOS 上，修复通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 Gateway 网关健康，也会运行该探测。
配置 OpenAI Codex OAuth 配置文件后，Doctor 会探测 OpenAI 授权端点，以验证本地 Node/OpenSSL TLS 栈能否验证证书链。如果探测因证书错误失败（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书过期或自签名证书），Doctor 会打印特定平台的修复指导。在使用 Homebrew Node 的 macOS 上，修复通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 Gateway 网关健康，也会运行该探测。
</Accordion>
<Accordion title="2e. Codex OAuth 提供商覆盖">
如果你之前在 `models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会遮蔽新版发布自动使用的内置 Codex OAuth 提供商路径。Doctor 在看到这些旧传输设置与 Codex OAuth 同时存在时会发出警告，方便你移除或重写过期的传输覆盖，并恢复内置路由/回退行为。仍然支持自定义代理和仅标头覆盖，并且不会触发此警告。
如果你之前在 `models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会遮蔽新版本自动使用的内置 Codex OAuth 提供商路径。Doctor 在看到这些旧传输设置与 Codex OAuth 同时存在时会发出警告，这样你就可以移除或重写过时的传输覆盖，并恢复内置路由/回退行为。仍支持自定义代理和仅标头覆盖，并且不会触发此警告。
</Accordion>
<Accordion title="2f. Codex 插件路由警告">
启用内置 Codex 插件时，Doctor 还会检查 `openai-codex/*` 主模型引用是否仍通过默认 PI 运行器解析。当你希望通过 PI 使用 Codex OAuth/订阅凭证时，这种组合是有效的，但很容易与原生 Codex 应用服务器 harness 混淆。Doctor 会发出警告并指向显式应用服务器形态：`openai/*` 加 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。
启用内置 Codex 插件后，Doctor 还会检查 `openai-codex/*` 主模型引用是否仍通过默认 PI runner 解析。当你想通过 PI 使用 Codex OAuth/订阅凭证时，此组合是有效的，但它很容易与原生 Codex app-server harness 混淆。Doctor 会发出警告并指向显式 app-server 形态：`openai/*` 加 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。
Doctor 不会自动修复这一点，因为两条路由都有效：
Doctor 不会自动修复此项，因为两条路由都是有效的：
- `openai-codex/*` + PI 表示“通过普通 OpenClaw 运行器使用 Codex OAuth/订阅凭证”。
- `openai/*` + `agentRuntime.id: "codex"` 表示“通过原生 Codex 应用服务器运行嵌入式回合”。
- `/codex ...` 表示“从聊天中控制或绑定原生 Codex 对话”。
- `/acp ...` 或 `runtime: "acp"` 表示“使用外部 ACP/acpx 适配器”。
- `openai-codex/*` + PI 表示“通过普通 OpenClaw runner 使用 Codex OAuth/订阅凭证。”
- `openai/*` + `agentRuntime.id: "codex"` 表示“通过原生 Codex app-server 运行嵌入式回合。”
- `/codex ...` 表示“从聊天中控制或绑定原生 Codex 对话。”
- `/acp ...` 或 `runtime: "acp"` 表示“使用外部 ACP/acpx 适配器。”
如果出现该警告，请选择你本来想要的路由并手动编辑配置。当 PI Codex OAuth 是有意配置时，保持该警告不变。
如果出现该警告，请选择你预期的路由并手动编辑配置。当 PI Codex OAuth 是有意配置时，请保持警告原样。
</Accordion>
<Accordion title="3. 旧版状态迁移（磁盘布局）">
Doctor 可以将较旧的磁盘布局迁移到当前结构：
- 会话存储 + transcripts：
- 会话存储 + 转录：
- 从 `~/.openclaw/sessions/` 到 `~/.openclaw/agents/<agentId>/sessions/`
- Agent 目录：
- 智能体目录：
- 从 `~/.openclaw/agent/` 到 `~/.openclaw/agents/<agentId>/agent/`
- WhatsApp 凭证状态（Baileys）：
- 从旧版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外）
- 从旧版 `~/.openclaw/credentials/*.json`（不含 `oauth.json`）
- 到 `~/.openclaw/credentials/whatsapp/<accountId>/...`（默认账号 ID：`default`）
这些迁移是尽力而为且幂等的；当 Doctor 将任何旧版文件夹保留为备份时，会发出警告。Gateway 网关/CLI 在启动时也会自动迁移旧版会话和 Agent 目录，让历史记录/凭证/模型落在按 Agent 划分的路径中，而无需手动运行 Doctor。WhatsApp 凭证有意只通过 `openclaw doctor` 迁移。Talk 提供商/提供商映射规范化现在按结构相等进行比较，因此仅键顺序不同的差异不再触发重复的无操作 `doctor --fix` 更改。
这些迁移是尽力而为且幂等的；当 Doctor 将任何旧版文件夹作为备份留下时，会发出警告。Gateway 网关/CLI 也会在启动时自动迁移旧版会话和智能体目录，因此历史记录/凭证/模型无需手动运行 Doctor 就会落到按智能体划分的路径中。WhatsApp 凭证有意只通过 `openclaw doctor` 迁移。Talk 提供商/提供商映射规范化现在会按结构相等性进行比较，因此仅键顺序不同的差异不再触发重复的空操作 `doctor --fix` 变更。
</Accordion>
<Accordion title="3a. 旧版插件清单迁移">
Doctor 会扫描所有已安装插件清单，查找已弃用的顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。找到后，它会提供将这些键移动到 `contracts` 对象并就地重写清单文件的选项。此迁移是幂等的；如果 `contracts` 键已有相同的值，会移除旧版键而不重复数据。
Doctor 会扫描所有已安装插件清单，查找已弃用的顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。找到后，它会提供将它们移动到 `contracts` 对象并就地重写清单文件的操作。此迁移是幂等的；如果 `contracts` 键已有相同值，则会移除旧版键，而不会重复数据。
</Accordion>
<Accordion title="3b. 旧版 cron 存储迁移">
Doctor 还会检查 cron 作业存储（默认为 `~/.openclaw/cron/jobs.json`，或在覆盖时使用 `cron.store`），查找调度器仍为兼容性而接受的旧作业形态。
Doctor 还会检查 cron 作业存储（默认是 `~/.openclaw/cron/jobs.json`，或覆盖后的 `cron.store`），查找调度器仍出于兼容性接受的旧作业形态。
当前 cron 清理包括：
- `jobId` → `id`
- `schedule.cron` → `schedule.expr`
- 顶层 payload 字段（`message`、`model`、`thinking`、...）→ `payload`
- 顶层 delivery 字段（`deliver`、`channel`、`to`、`provider`、...）→ `delivery`
- payload `provider` delivery 别名 → 显式 `delivery.channel`
- 简单的旧版 `notify: true` webhook 回退作业 → 显式 `delivery.mode="webhook"`，并带有 `delivery.to=cron.webhook`
- 顶层载荷字段（`message`、`model`、`thinking`、...）→ `payload`
- 顶层投递字段（`deliver`、`channel`、`to`、`provider`、...）→ `delivery`
- 载荷 `provider` 投递别名 → 显式 `delivery.channel`
- 简单旧版 `notify: true` webhook 回退作业 → 显式 `delivery.mode="webhook"`，并设置 `delivery.to=cron.webhook`
Doctor 只会在不改变行为的情况下自动迁移 `notify: true` 作业。如果某个作业将旧版通知回退与现有的非 webhook delivery 模式组合在一起，Doctor 会发出警告，并将该作业留待手动审查。
Doctor 只会在不改变行为的情况下自动迁移 `notify: true` 作业。如果某个作业将旧版 notify 回退与现有非 webhook 投递模式组合使用，Doctor 会发出警告并将该作业留待手动审查。
在 Linux 上，当用户的 crontab 仍调用旧版 `~/.openclaw/bin/ensure-whatsapp.sh` 时，Doctor 也会发出警告。当前 OpenClaw 不维护这个主机本地脚本，并且当 cron 无法访问 systemd 用户总线时，它可能会向 `~/.openclaw/logs/whatsapp-health.log` 写入错误的 `Gateway inactive` 消息。使用 `crontab -e` 移除过期的 crontab 条目；使用 `openclaw channels status --probe`、`openclaw doctor` 和 `openclaw gateway status` 进行当前健康检查。
在 Linux 上，如果用户的 crontab 仍调用旧版 `~/.openclaw/bin/ensure-whatsapp.sh`，Doctor 也会发出警告。当前 OpenClaw 不维护该主机本地脚本，并且当 cron 无法访问 systemd 用户总线时，它可能会向 `~/.openclaw/logs/whatsapp-health.log` 写入错误的 `Gateway inactive` 消息。使用 `crontab -e` 移除过时的 crontab 条目；使用 `openclaw channels status --probe`、`openclaw doctor` 和 `openclaw gateway status` 进行当前健康检查。
</Accordion>
<Accordion title="3c. 会话锁清理">
Doctor 会扫描每个智能体会话目录，查找陈旧的写入锁文件，即会话异常退出时遗留的文件。对于找到的每个锁文件，它会报告：路径、PID、PID 是否仍然存活、锁龄，以及是否被视为陈旧（PID 已死或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动移除陈旧的锁文件；否则，它会打印一条提示，并指导你使用 `--fix` 重新运行。
Doctor 会扫描每个智能体会话目录，查找过时的写入锁文件，即会话异常退出后遗留的文件。对于发现的每个锁文件，它会报告：路径、PID、PID 是否仍然存活、锁存在时长，以及是否被视为过时（PID 已死亡或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动移除过时的锁文件；否则会打印一条说明，并指示你使用 `--fix` 重新运行。
</Accordion>
<Accordion title="3d. 会话转录分支修复">
Doctor 会扫描智能体会话 JSONL 文件，查找由 2026.4.24 prompt 转录重写 bug 创建的重复分支形态：一个包含 OpenClaw 内部运行时上下文的已废弃用户轮次，以及一个包含相同可见用户 prompt 的活动同级分支。在 `--fix` / `--repair` 模式下，Doctor 会在原文件旁边备份每个受影响文件，并将转录重写到活动分支，这样 Gateway 网关历史和记忆读取器就不会再看到重复轮次。
<Accordion title="3d. 会话记录分支修复">
Doctor 会扫描智能体会话 JSONL 文件，查找由 2026.4.24 提示词记录重写 bug 创建的重复分支形态：一个被放弃的用户轮次，其中包含 OpenClaw 内部运行时上下文，外加一个包含相同可见用户提示词的活跃同级分支。在 `--fix` / `--repair` 模式下，Doctor 会在每个受影响文件的原文件旁边创建备份，并将记录重写到活跃分支，这样 Gateway 网关历史和记忆读取器就不会再看到重复轮次。
</Accordion>
<Accordion title="4. 状态完整性检查（会话持久化、路由和安全）">
状态目录是运行中的核心枢纽。如果它消失，你会丢失会话、凭证、日志和配置（除非你在其他地方有备份）。
状态目录是运行时的中枢。如果它消失，你会丢失会话、凭证、日志和配置（除非你在其他位置有备份）。
Doctor 会检查：
- **状态目录缺失**：警告灾难性状态丢失，提示重新创建目录，并提醒你它无法恢复缺失的数据。
- **状态目录权限**：验证可写性；提供修复权限的选项（检测到所有者/组不匹配时会发出 `chown` 提示）。
- **macOS 云同步状态目录**：当状态解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 下时发出警告，因为同步支持的路径可能导致更慢的 I/O 以及锁/同步竞态。
- **Linux SD 或 eMMC 状态目录**：当状态解析到 `mmcblk*` 挂载源时发出警告，因为 SD 或 eMMC 支持的随机 I/O 在会话和凭证写入下可能更慢且磨损更快。
- **会话目录缺失**：`sessions/` 和会话存储目录是持久化历史并避免 `ENOENT` 崩溃所必需的。
- **转录不匹配**：当最近的会话条目缺少转录文件时发出警告。
- **主会话 “1 行 JSONL”**：当主转录只有一行时标记（历史没有累积）。
- **多个状态目录**：当多个主目录中存在多个 `~/.openclaw` 文件夹，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史可能在安装之间分裂）。
- **远程模式提醒**：如果 `gateway.mode=remote`，Doctor 会提醒你在远程主机上运行它（状态位于那里）。
- **配置文件权限**：如果 `~/.openclaw/openclaw.json` 对组/所有人可读则发出警告，并提供收紧到 `600` 的选项。
- **状态目录权限**：验证可写性；提供修复权限的选项（当检测到所有者/组不匹配时，会发出 `chown` 提示）。
- **macOS 云同步状态目录**：当状态解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 下时发出警告，因为同步支持的路径可能导致更慢的 I/O 以及锁/同步竞争。
- **Linux SD 或 eMMC 状态目录**：当状态解析到 `mmcblk*` 挂载源时发出警告，因为基于 SD 或 eMMC 的随机 I/O 在会话和凭证写入时可能更慢且磨损更快。
- **会话目录缺失**：需要 `sessions/` 和会话存储目录来持久化历史并避免 `ENOENT` 崩溃。
- **记录不匹配**：当最近的会话条目缺少记录文件时发出警告。
- **主会话“单行 JSONL”**：当主记录只有一行时标记（历史没有累积）。
- **多个状态目录**：当多个主目录中存在多个 `~/.openclaw` 文件夹，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史可能在不同安装之间拆分）。
- **远程模式提醒**：如果 `gateway.mode=remote`，Doctor 会提醒你在远程主机上运行它（状态存放在那里）。
- **配置文件权限**：如果 `~/.openclaw/openclaw.json` 对组/所有人可读，则发出警告，并提供收紧到 `600` 的选项。
</Accordion>
<Accordion title="5. 模型凭证健康状况（OAuth 过期）">
Doctor 会检查凭证存储中的 OAuth 配置文件，在令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic OAuth/令牌配置文件已陈旧，它会建议使用 Anthropic API key 或 Anthropic 设置令牌路径。刷新提示只会在交互式运行（TTY）时出现；`--non-interactive` 会跳过刷新尝试。
<Accordion title="5. 模型认证健康状况（OAuth 过期）">
Doctor 会检查认证存储中的 OAuth 配置文件，在令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic OAuth/令牌配置文件已过时，它会建议使用 Anthropic API key 或 Anthropic 设置令牌路径。刷新提示只会在交互式运行（TTY）时出现；`--non-interactive` 会跳过刷新尝试。
当 OAuth 刷新永久失败时（例如 `refresh_token_reused`、`invalid_grant`，或提供商要求你重新登录），Doctor 会报告需要重新认证，并打印要运行的确切 `openclaw models auth login --provider ...` 命令。
Doctor 还会报告因以下原因暂时不可用的凭证配置文件：
Doctor 还会报告因以下原因暂时不可用的认证配置文件：
- 短暂冷却（速率限制/超时/凭证失败）
- 较长时间禁用（账单/额度失败）
- 短暂冷却（速率限制/超时/认证失败）
- 较长时间禁用（计费/额度失败）
</Accordion>
<Accordion title="6. 钩子模型验证">
如果设置了 `hooks.gmail.model`，Doctor 会根据目录和允许列表验证模型引用，并在其无法解析或被禁止时发出警告。
如果设置了 `hooks.gmail.model`，Doctor 会根据目录和允许列表验证模型引用，并在无法解析或不被允许时发出警告。
</Accordion>
<Accordion title="7. 沙箱镜像修复">
启用沙箱隔离时，Doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧版名称的选项。
启用沙箱隔离时，Doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧名称的选项。
</Accordion>
<Accordion title="7b. 插件安装清理">
Doctor 会在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式下移除旧版 OpenClaw 生成的插件依赖暂存状态。这涵盖陈旧的生成依赖根目录、旧安装阶段目录、早期内置插件依赖修复代码留下的包本地残留，以及孤立的托管 npm 副本，这些内置 `@openclaw/*` 插件可能遮蔽当前内置清单。
Doctor 会在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式下移除旧版 OpenClaw 生成的插件依赖暂存状态。这涵盖过时的生成依赖根目录、旧安装阶段目录、早期内置插件依赖修复代码留下的包本地碎片，以及可能遮蔽当前内置清单的孤立或已恢复的托管 npm 版内置 `@openclaw/*` 插件副本。
当配置引用了可下载插件但本地插件注册表找不到它们时，Doctor 也可以重新安装这些插件。对于 2026.5.2 的内置插件外部化，Doctor 会自动安装现有配置已经使用的可下载插件，然后依赖 `meta.lastTouchedVersion` 让该发布迁移只运行一次。Gateway 网关启动和配置重新加载不会运行包管理器；插件安装仍然是显式的 Doctor/安装/更新工作。
当配置引用可下载插件但本地插件注册表找不到它们时，Doctor 也可以重新安装已配置的可下载插件。对于 2026.5.2 的内置插件外部化，Doctor 会自动安装现有配置已经使用的可下载插件，然后依赖 `meta.lastTouchedVersion` 确保该发布轮次只运行一次。Gateway 网关启动和配置重新加载不会运行包管理器；插件安装仍然是显式的 Doctor/安装/更新工作。
</Accordion>
<Accordion title="8. Gateway 网关服务迁移和清理提示">
Doctor 会检测旧版 Gateway 网关服务（launchd/systemd/schtasks），并提供移除它们以及使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的类似 Gateway 网关的服务并打印清理提示。带配置文件名称的 OpenClaw Gateway 网关服务被视为一等服务，不会被标记为“额外”。
Doctor 会检测旧版 Gateway 网关服务（launchd/systemd/schtasks），并提供移除它们以及使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的类似 Gateway 网关的服务，并打印清理提示。带配置文件名称的 OpenClaw Gateway 网关服务被视为一等服务，不会被标记为“额外”。
在 Linux 上，如果缺少用户级 Gateway 网关服务，但存在系统级 OpenClaw Gateway 网关服务，Doctor 不会自动安装第二个用户级服务。使用 `openclaw gateway status --deep` 或 `openclaw doctor --deep` 检查，然后移除重复项，或在系统监督器拥有 Gateway 网关生命周期时设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。
在 Linux 上，如果缺少用户级 Gateway 网关服务，但存在系统级 OpenClaw Gateway 网关服务，Doctor 不会自动安装第二个用户级服务。使用 `openclaw gateway status --deep` 或 `openclaw doctor --deep` 检查，然后移除重复服务；如果 Gateway 网关生命周期由系统监管器负责，则设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。
</Accordion>
<Accordion title="8b. 启动 Matrix 迁移">
当 Matrix 渠道账号存在待处理或可操作的旧版状态迁移时，Doctor（在 `--fix` / `--repair` 模式下）会创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。两个步骤都是非致命的；错误会被记录，启动会继续。在只读模式（不带 `--fix` 的 `openclaw doctor`）下，此检查会被完全跳过。
当 Matrix 渠道账号存在待处理或可执行的旧状态迁移时，Doctor（在 `--fix` / `--repair` 模式下）会创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都是非致命的；错误会被记录，启动会继续。在只读模式（不带 `--fix` 的 `openclaw doctor`）下，此检查会被完全跳过。
</Accordion>
<Accordion title="8c. 设备配对和凭证漂移">
Doctor 现在会将设备配对状态作为正常健康检查的一部分进行检查。
<Accordion title="8c. 设备配对和认证漂移">
Doctor 现在会在正常健康检查过程中检查设备配对状态。
它会报告：
- 待处理的首次配对请求
- 已配对设备的待处理角色升级
- 已配对设备的待处理范围升级
- 设备 id 仍然匹配但设备身份不再匹配已批准记录的公钥不匹配修复
- 缺少已批准角色的活动令牌的配对记录
- 范围漂移到已批准配对基线之外的配对令牌
- 当前机器的本地缓存设备令牌条目早于 Gateway 网关侧令牌轮换，或携带陈旧范围元数据
- 已配对设备的待处理作用域升级
- 设备 id 仍然匹配、但设备身份不再匹配已批准记录的公钥不匹配修复
- 缺少已批准角色的活动令牌的已配对记录
- 作用域偏离已批准配对基线的已配对令牌
- 当前机器上的本地缓存设备令牌条目，这些条目早于 Gateway 网关侧令牌轮换，或携带过期的作用域元数据
Doctor 不会自动批准配对请求或自动轮换设备令牌。它会改为打印确切的后续步骤：
Doctor 不会自动批准配对请求，也不会自动轮换设备令牌。它会改为打印确切的后续步骤：
- 使用 `openclaw devices list` 检查待处理请求
- 使用 `openclaw devices approve <requestId>` 批准确切请求
- 使用 `openclaw devices rotate --device <deviceId> --role <role>` 轮换新令牌
- 使用 `openclaw devices remove <deviceId>` 移除并重新批准陈旧记录
- 使用 `openclaw devices remove <deviceId>` 移除并重新批准过期记录
这修复了常见的“已经配对但仍然提示需要配对”缺口：Doctor 现在会区分首次配对、待处理的角色/范围升级，以及陈旧令牌/设备身份漂移。
这补上了常见的“已经配对但仍然提示需要配对”漏洞：doctor 现在会区分首次配对、待处理的角色/作用域升级，以及过期令牌/设备身份漂移。
</Accordion>
<Accordion title="9. 安全警告">
当提供商对私信开放但没有允许列表，或策略以危险方式配置时，Doctor 会发出警告。
当某个提供商在没有允许列表的情况下对私信开放，或策略以危险方式配置时，Doctor 会发出警告。
</Accordion>
<Accordion title="10. systemd linger（Linux）">
如果作为 systemd 用户服务运行，Doctor 会确保已启用 linger，以便 Gateway 网关在注销后保持运行。
如果作为 systemd 用户服务运行，doctor 会确保已启用 linger，让 Gateway 网关在登出后继续保持运行。
</Accordion>
<Accordion title="11. 工作区状态（Skills、插件和旧版目录）">
Doctor 会打印默认智能体的工作区状态摘要：
- **Skills 状态**：统计符合条件、缺少要求和被允许列表阻止的 Skills。
- **Skills 状态**：统计符合条件、缺少要求以及被允许列表阻止的 skills。
- **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录与当前工作区并存时发出警告。
- **插件状态**：统计已启用/已禁用/出错的插件；列出所有错误的插件 ID；报告内置插件能力。
- **插件状态**：统计已启用/已禁用/出错的插件；列出所有错误对应的插件 ID；报告内置插件能力。
- **插件兼容性警告**：标记与当前运行时存在兼容性问题的插件。
- **插件诊断**：显示插件注册表在加载时发出的任何警告或错误。
</Accordion>
<Accordion title="11b. Bootstrap 文件大小">
Doctor 会检查工作区 bootstrap 文件（例如 `AGENTS.md`、`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过配置的字符预算。它会报告每个文件的原始字符数与注入字符数、截断百分比、截断原因（`max/file` 或 `max/total`），以及总注入字符数占总预算的比例。当文件被截断或接近限制时，Doctor 会打印调优 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 的提示。
<Accordion title="11b. 引导文件大小">
Doctor 会检查工作区引导文件（例如 `AGENTS.md`、`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过配置的字符预算。它会报告每个文件的原始字符数与注入字符数、截断百分比、截断原因（`max/file` 或 `max/total`），以及总注入字符数占总预算的比例。当文件被截断或接近限制时，doctor 会打印用于调优 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 的提示。
</Accordion>
<Accordion title="11d. 陈旧渠道插件清理">
当 `openclaw doctor --fix` 移除缺失的渠道插件时，它也会移除引用该插件的悬空渠道作用域配置：`channels.<id>` 条目、命名该渠道的 Heartbeat 目标，以及 `agents.*.models["<channel>/*"]` 覆盖项。这可以防止渠道运行时已不存在但配置仍要求 Gateway 网关绑定到它时产生 Gateway 网关启动循环。
<Accordion title="11d. 过期渠道插件清理">
当 `openclaw doctor --fix` 移除缺失的渠道插件时，它也会移除引用该插件的悬空渠道级配置：`channels.<id>` 条目、命名该渠道的 heartbeat 目标，以及 `agents.*.models["<channel>/*"]` 覆盖项。这可以防止渠道运行时已消失、但配置仍要求 Gateway 网关绑定到它而导致的 Gateway 网关启动循环。
</Accordion>
<Accordion title="11c. Shell 补全">
Doctor 会检查当前 shell（zsh、bash、fish 或 PowerShell）是否已安装 tab 补全：
Doctor 会检查当前 shell（zsh、bash、fish 或 PowerShell）是否已安装 Tab 补全：
- 如果 shell 配置文件使用较慢的动态补全模式（`source <(openclaw completion ...)`），Doctor 会将其升级为更快的缓存文件变体。
- 如果补全已在配置文件中配置但缓存文件缺失，Doctor 会自动重新生成缓存。
- 如果完全没有配置补全，Doctor 会提示安装它（仅交互模式；使用 `--non-interactive` 时跳过）。
- 如果 shell 配置文件使用较慢的动态补全模式（`source <(openclaw completion ...)`），doctor 会将其升级为更快的缓存文件变体。
- 如果补全已在配置文件中配置，但缓存文件缺失，doctor 会自动重新生成缓存。
- 如果完全没有配置补全，doctor 会提示安装（仅限交互模式；使用 `--non-interactive` 时跳过）。
运行 `openclaw completion --write-state` 可手动重新生成缓存。
</Accordion>
<Accordion title="12. Gateway 网关凭证检查（本地令牌）">
Doctor 会检查本地 Gateway 网关令牌凭证就绪状态。
<Accordion title="12. Gateway 网关认证检查（本地令牌）">
Doctor 会检查本地 Gateway 网关令牌认证就绪状态。
- 如果令牌模式需要令牌但不存在令牌来源，Doctor 会提供生成一个令牌的选项。
- 如果 `gateway.auth.token` 由 SecretRef 管理但不可用，Doctor 会发出警告，并且不会用明文覆盖它。
- `openclaw doctor --generate-gateway-token` 仅在没有配置令牌 SecretRef 时强制生成。
- 如果令牌模式需要令牌且不存在令牌来源，doctor 会提示生成一个。
- 如果 `gateway.auth.token` 由 SecretRef 管理但不可用，doctor 会发出警告，并且不会用明文覆盖它。
- `openclaw doctor --generate-gateway-token` 仅在未配置令牌 SecretRef 时强制生成。
</Accordion>
<Accordion title="12b. 感知 SecretRef 的只读修复">
某些修复流程需要检查已配置凭证，同时不削弱运行时快速失败行为。
一些修复流程需要检查已配置的凭证，同时不削弱运行时快速失败行为。
- `openclaw doctor --fix` 现在使用与 status 系列命令相同的只读 SecretRef 摘要模型来执行有针对性的配置修复。
- 示例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修复会在可用时尝试使用已配置的 bot 凭证。
- 如果 Telegram bot 令牌通过 SecretRef 配置，但在当前命令路径中不可用，Doctor 会报告该凭证已配置但不可用，并跳过自动解析，而不是崩溃或误报令牌缺失。
- `openclaw doctor --fix` 现在会使用与 status 系列命令相同的只读 SecretRef 摘要模型来执行定向配置修复。
- 示例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修复会在可用时尝试使用已配置的机器人凭证。
- 如果 Telegram 机器人令牌通过 SecretRef 配置，但在当前命令路径中不可用，doctor 会报告该凭证已配置但不可用，并跳过自动解析，而不是崩溃或误报令牌缺失。
</Accordion>
<Accordion title="13. Gateway 网关健康检查 + 重启">
Doctor 会运行健康检查，并在 Gateway 网关看起来不健康时提供重启选项。
Doctor 会运行健康检查，并在 Gateway 网关看起来不健康时提示重启。
</Accordion>
<Accordion title="13b. 内存搜索就绪状态">
Doctor 会检查已配置的内存搜索嵌入提供商是否已为默认智能体就绪。具体行为取决于已配置的后端和提供商：
<Accordion title="13b. 记忆搜索就绪状态">
Doctor 会检查已配置的记忆搜索嵌入提供商是否已为默认智能体准备就绪。行为取决于配置的后端和提供商：
- **QMD 后端**：探测 `qmd` 二进制文件是否可用且可启动。如果不可用，会打印修复指导，包括 npm 包和手动二进制路径选项。
- **QMD 后端**：探测 `qmd` 二进制文件是否可用且可启动。如果不可用，会打印修复指引，包括 npm 包和手动二进制路径选项。
- **显式本地提供商**：检查本地模型文件或可识别的远程/可下载模型 URL。如果缺失，建议切换到远程提供商。
- **显式远程提供商**（`openai`、`voyage` 等）：验证环境或凭证存储中是否存在 API key。如果缺失，会打印可操作的修复提示。
- **显式远程提供商**（`openai`、`voyage` 等）：验证环境或身份验证存储中是否存在 API key。如果缺失，会打印可操作的修复提示。
- **自动提供商**：先检查本地模型可用性，然后按自动选择顺序尝试每个远程提供商。
当缓存的 Gateway 网关探测结果可用时（检查时 Gateway 网关处于健康状态），Doctor 会将其结果与 CLI 可见配置交叉参照，并标注任何差异。Doctor 不会在默认路径上启动新的嵌入 ping；如果你想要实时提供商检查，请使用深度内存 Status 命令。
当缓存的 Gateway 网关探测结果可用时（检查时 Gateway 网关处于健康状态），Doctor 会将其结果与 CLI 可见配置交叉引用，并指出任何差异。Doctor 不会在默认路径上启动新的嵌入 ping；如果你想进行实时提供商检查，请使用深度记忆状态命令。
使用 `openclaw memory status --deep` 在运行时验证嵌入就绪状态。
</Accordion>
<Accordion title="14. 渠道 Status 警告">
如果 Gateway 网关健康，Doctor 会运行渠道 Status 探测，并报告带建议修复措施的警告。
<Accordion title="14. 渠道状态警告">
如果 Gateway 网关健康，Doctor 会运行渠道状态探测，并报告带有建议修复方案的警告。
</Accordion>
<Accordion title="15. Supervisor 配置审计 + 修复">
Doctor 会检查已安装的 supervisor 配置（launchd/systemd/schtasks）是否缺少默认值或默认值过时（例如 systemd network-online 依赖项和重启延迟）。发现不匹配时，它会建议更新，并可将服务文件/任务重写为当前默认值。
<Accordion title="15. 监督程序配置审计 + 修复">
Doctor 会检查已安装的监督程序配置（launchd/systemd/schtasks）是否缺少默认值或默认值已过期（例如 systemd network-online 依赖项和重启延迟）。当发现不匹配时，它会建议更新，并可以将服务文件/任务重写为当前默认值。
注意：
注意事项：
- `openclaw doctor` 会在重写 supervisor 配置前提示。
- `openclaw doctor --yes` 会接受默认修复提示。
- `openclaw doctor --repair` 会在不提示的情况下应用建议修复。
- `openclaw doctor --repair --force` 会覆盖自定义 supervisor 配置。
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` 会让 Doctor 对 Gateway 网关服务生命周期保持只读。它仍会报告服务健康状况并运行非服务修复，但会跳过服务安装/启动/重启/引导、supervisor 配置重写和旧版服务清理，因为该生命周期由外部 supervisor 拥有。
- 在 Linux 上，当匹配的 systemd Gateway 网关单元处于活动状态时，Doctor 不会重写命令/入口点元数据。它还会在重复服务扫描期间忽略非活动的非旧版额外类 Gateway 网关单元，因此配套服务文件不会产生清理噪声。
- 如果令牌认证需要令牌且 `gateway.auth.token` 由 SecretRef 管理，Doctor 服务安装/修复会验证 SecretRef，但不会把解析后的明文令牌值持久化到 supervisor 服务环境元数据中。
- Doctor 会检测旧版 LaunchAgent、systemd 或 Windows Scheduled Task 安装中以内联方式嵌入的托管 `.env`/SecretRef 支持的服务环境值，并重写服务元数据，使这些值从运行时来源加载，而不是从 supervisor 定义加载。
- Doctor 会检测服务命令在 `gateway.port` 变更后是否仍固定旧的 `--port`，并将服务元数据重写为当前端口。
- 如果令牌认证需要令牌且已配置的令牌 SecretRef 未解析，Doctor 会阻止安装/修复路径，并提供可操作的指导。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，Doctor 会阻止安装/修复，直到显式设置 mode。
- 对于 Linux 用户 systemd 单元，Doctor 令牌漂移检查现在会在比较服务认证元数据时同时包含 `Environment=` 和 `EnvironmentFile=` 来源。
- 当配置最后由较新版本写入时，Doctor 服务修复会拒绝使用旧版 OpenClaw 二进制文件重写、停止或重启 Gateway 网关服务。请参阅 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)。
- 你始终可以通过 `openclaw gateway install --force` 强制完整重写。
- `openclaw doctor` 会在重写监督程序配置前提示。
- `openclaw doctor --yes` 接受默认修复提示。
- `openclaw doctor --repair` 会在不提示的情况下应用建议的修复。
- `openclaw doctor --repair --force` 会覆盖自定义监督程序配置。
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` 会让 Doctor 对 Gateway 网关服务生命周期保持只读。它仍会报告服务健康状态并运行非服务修复，但会跳过服务安装/启动/重启/引导、监督程序配置重写和旧版服务清理，因为外部监督程序拥有该生命周期。
- 在 Linux 上，当匹配的 systemd Gateway 网关单元处于活动状态时，Doctor 不会重写命令/入口点元数据。它还会在重复服务扫描期间忽略非活动的非旧版额外类似 Gateway 网关的单元，因此配套服务文件不会制造清理噪声。
- 如果令牌身份验证需要令牌，并且 `gateway.auth.token` 由 SecretRef 管理，Doctor 服务安装/修复会验证 SecretRef，但不会将解析后的明文令牌值持久化到监督程序服务环境元数据中。
- Doctor 会检测较旧的 LaunchAgent、systemd 或 Windows Scheduled Task 安装中以内联方式嵌入的托管 `.env`/SecretRef 支持的服务环境值，并重写服务元数据，使这些值从运行时源加载，而不是从监督程序定义加载。
- Doctor 会检测服务命令是否在 `gateway.port` 更改后仍固定旧的 `--port`，并将服务元数据重写为当前端口。
- 如果令牌身份验证需要令牌，并且配置的令牌 SecretRef 无法解析，Doctor 会阻止安装/修复路径，并给出可操作的指引。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，Doctor 会阻止安装/修复，直到显式设置模式。
- 对于 Linux 用户 systemd 单元，Doctor 令牌漂移检查现在会在比较服务身份验证元数据时同时包含 `Environment=` 和 `EnvironmentFile=` 源。
- 当配置最后由较新版本写入时，Doctor 服务修复会拒绝从较旧的 OpenClaw 二进制文件重写、停止或重启 Gateway 网关服务。请参阅 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)。
- 你始终可以通过 `openclaw gateway install --force` 强制完全重写。
</Accordion>
<Accordion title="16. Gateway 网关运行时 + 端口诊断">
Doctor 会检查服务运行时（PID、上次退出状态），并在服务已安装但未实际运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。
Doctor 会检查服务运行时（PID、上次退出状态），并在服务已安装但实际未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。
</Accordion>
<Accordion title="17. Gateway 网关运行时最佳实践">
当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上时，Doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，而版本管理器路径在升级后可能中断，因为服务不会加载你的 shell 初始化。Doctor 会在可用时提供迁移到系统 Node 安装的选项（Homebrew/apt/choco）。
当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上时，Doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，而版本管理器路径可能会在升级后失效，因为服务不会加载你的 shell 初始化。Doctor 会在系统 Node 安装可用时（Homebrew/apt/choco）提示迁移到系统 Node 安装。
新安装或修复的 macOS LaunchAgent 使用规范的系统 PATH（`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`），而不是复制交互式 shell PATH，因此 Volta、asdf、fnm、pnpm 和其他版本管理器目录不会改变 Node 子进程解析的位置。Linux 服务仍会保留显式环境根目录（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）和稳定的用户 bin 目录，但猜测的版本管理器回退目录只会在这些目录存在于磁盘上时写入服务 PATH。
新安装或修复的 macOS LaunchAgent 使用规范的系统 PATH（`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`），而不是复制交互式 shell PATH，因此 Volta、asdf、fnm、pnpm 和其他版本管理器目录不会改变 Node 子进程的解析位置。Linux 服务仍会保留显式环境根目录（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）和稳定的用户 bin 目录，但猜测出的版本管理器回退目录只有在这些目录实际存在于磁盘上时，才会写入服务 PATH。
</Accordion>
<Accordion title="18. 配置写入 + 向导元数据">
Doctor 会持久化任何配置更改，并标记向导元数据以记录本次 Doctor 运行。
Doctor 会持久化任何配置更改，并标记向导元数据以记录 Doctor 运行。
</Accordion>
<Accordion title="19. 工作区提示（备份 + 内存系统）">
当缺少工作区内存系统时，Doctor 会建议添加；如果工作区尚未纳入 git，它会打印备份提示。
<Accordion title="19. 工作区提示（备份 + 记忆系统）">
当缺少工作区记忆系统时，Doctor 会建议添加；如果工作区尚未置于 git 下，它会打印备份提示。
请参阅 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)，获取关于工作区结构和 git 备份的完整指南（推荐使用私有 GitHub 或 GitLab）。
请参阅 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)，了解工作区结构和 git 备份的完整指南（推荐使用私有 GitHub 或 GitLab）。
</Accordion>
</AccordionGroup>

281
docs/zh-CN/web/control-ui.md
View File

@ -3,46 +3,46 @@ read_when:
- 你想从浏览器操作 Gateway 网关
- 你想要在不使用 SSH 隧道的情况下访问 Tailnet
sidebarTitle: Control UI
summary: Gateway 网关的浏览器端控制界面（聊天、节点、配置）
summary: 基于浏览器的 Gateway 网关控制界面（聊天、节点、配置）
title: 控制界面
x-i18n:
generated_at: "2026-05-04T07:09:03Z"
generated_at: "2026-05-04T09:22:11Z"
model: gpt-5.5
provider: openai
source_hash: 896c75116d7a396571017ac6e6db7ff6ce328617e44470c303fd41af58aa2bd7
source_hash: 4b68b5203b369de6a3354a7e7442ee38ee790875b2d7054b0c8ec997098fd9de
source_path: web/control-ui.md
workflow: 16
---
Control UI 是一个由 Gateway 网关提供服务的小型 **Vite + Lit** 单页应用：
控制界面是一个由 Gateway 网关提供服务的小型 **Vite + Lit** 单页应用：
- 默认：`http://<host>:18789/`
- 可选前缀：设置 `gateway.controlUi.basePath`（例如 `/openclaw`）
它会在同一端口上**直接连接 Gateway 网关 WebSocket**。
它会在同一端口上**直接与 Gateway 网关 WebSocket** 通信。
## 快速打开（本地）
如果 Gateway 网关正在同一台计算机上运行，请打开：
如果 Gateway 网关在同一台电脑上运行，请打开：
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/)（或 [http://localhost:18789/](http://localhost:18789/)）
如果页面加载失败，请先启动 Gateway 网关：`openclaw gateway`。
身份验证会在 WebSocket 握手期间通过以下方式提供：
认证会在 WebSocket 握手期间通过以下方式提供：
- `connect.params.auth.token`
- `connect.params.auth.password`
- 当 `gateway.auth.allowTailscale: true` 时使用 Tailscale Serve 身份标头
- 当 `gateway.auth.mode: "trusted-proxy"` 时使用受信任代理身份标头
- 当 `gateway.auth.allowTailscale: true` 时的 Tailscale Serve 身份标头
- 当 `gateway.auth.mode: "trusted-proxy"` 时的可信代理身份标头
仪表盘设置面板会为当前浏览器标签页会话和所选 Gateway 网关 URL 保留一个令牌；密码不会被持久化。新手引导通常会在首次连接时为共享密钥身份验证生成一个 Gateway 网关令牌，但当 `gateway.auth.mode` 为 `"password"` 时，也可以使用密码身份验证。
仪表盘设置面板会为当前浏览器标签页会话和选中的 Gateway 网关 URL 保留一个令牌；密码不会持久保存。新手引导通常会在首次连接时为共享密钥认证生成一个 Gateway 网关令牌，但当 `gateway.auth.mode` 为 `"password"` 时，密码认证也可用。
## 设备配对（首次连接）
当你从新的浏览器或设备连接到 Control UI 时，Gateway 网关通常需要**一次性配对批准**。这是一项安全措施，用于防止未经授权的访问。
当你从新的浏览器或设备连接到控制界面时，Gateway 网关通常需要**一次性配对批准**。这是一项安全措施，用于防止未授权访问。
**你会看到：**“已断开连接 (1008)：需要配对”
**你会看到：** “disconnected (1008): pairing required”
<Steps>
<Step title="列出待处理请求">
@ -57,97 +57,97 @@ Control UI 是一个由 Gateway 网关提供服务的小型 **Vite + Lit** 单
</Step>
</Steps>
如果浏览器用已更改的身份验证详情（角色/作用域/公钥）重试配对，先前的待处理请求会被取代，并创建新的 `requestId`。批准前请重新运行 `openclaw devices list`。
如果浏览器使用已更改的认证详情（角色/作用域/公钥）重试配对，之前的待处理请求会被取代，并创建新的 `requestId`。批准前请重新运行 `openclaw devices list`。
如果浏览器已经配对，而你将它从读取访问改为写入/管理员访问，这会被视为批准升级，而不是静默重新连接。OpenClaw 会保持旧批准有效，阻止更大权限范围的重新连接，并要求你明确批准新的作用域集合。
如果浏览器已经配对，而你将它从读取访问改为写入/管理员访问，这会被视为一次批准升级，而不是静默重连。OpenClaw 会保持旧批准有效，阻止范围更大的重连，并要求你显式批准新的作用域集合。
批准后，设备会被记住，不会再次要求批准，除非你使用 `openclaw devices revoke --device <id> --role <role>` 撤销它。请参阅 [设备 CLI](/zh-CN/cli/devices) 了解令牌轮换和撤销。
批准后，设备会被记住，除非你使用 `openclaw devices revoke --device <id> --role <role>` 撤销它，否则无需重新批准。令牌轮换和撤销请参阅[设备 CLI](/zh-CN/cli/devices)。
<Note>
- 直接 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会自动批准。
- 当 `gateway.auth.allowTailscale: true`、Tailscale 身份验证通过，并且浏览器提供其设备身份时，Tailscale Serve 可以为 Control UI 操作员会话跳过配对往返。
- 直接 Tailnet 绑定、局域网浏览器连接，以及没有设备身份的浏览器配置文件仍然需要明确批准。
- 直接的 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会自动批准。
- 当 `gateway.auth.allowTailscale: true`、Tailscale 身份验证通过，并且浏览器提供其设备身份时，Tailscale Serve 可以为控制界面操作员会话跳过配对往返。
- 直接 Tailnet 绑定、局域网浏览器连接，以及没有设备身份的浏览器配置文件仍然需要显式批准。
- 每个浏览器配置文件都会生成唯一的设备 ID，因此切换浏览器或清除浏览器数据将需要重新配对。
</Note>
## 个人身份（浏览器本地）
Control UI 支持按浏览器设置个人身份（显示名称和头像），并将其附加到外发消息上，用于在共享会话中标明归属。它存放在浏览器存储中，作用域限定为当前浏览器配置文件，不会同步到其他设备，也不会在服务端持久化，除了你实际发送的消息上的常规转录作者元数据。清除站点数据或切换浏览器会将其重置为空。
控制界面支持按浏览器设置个人身份（显示名称和头像），并将其附加到传出消息上，用于在共享会话中标明归属。它存储在浏览器存储中，作用域限定为当前浏览器配置文件，不会同步到其他设备，也不会在服务器端持久保存，除了你实际发送的消息上正常的转录作者身份元数据。清除站点数据或切换浏览器会将其重置为空。
同样的浏览器本地模式也适用于助手头像覆盖。上传的助手头像只会在本地浏览器中覆盖 Gateway 网关解析出的身份，绝不会通过 `config.patch` 往返传输。共享的 `ui.assistant.avatar` 配置字段仍可供直接写入该字段的非 UI 客户端使用（例如脚本化 Gateway 网关或自定义仪表盘）。
## 运行时配置端点
Control UI 会从 `/__openclaw/control-ui-config.json` 获取其运行时设置。该端点受与其余 HTTP 表面相同的 Gateway 网关身份验证保护：未经身份验证的浏览器无法获取它，成功获取需要已有有效的 Gateway 网关令牌/密码、Tailscale Serve 身份，或受信任代理身份。
控制界面从 `/__openclaw/control-ui-config.json` 获取其运行时设置。该端点与其余 HTTP 表面受同一 Gateway 网关认证保护：未经认证的浏览器无法获取它，成功获取需要已有有效的 Gateway 网关令牌/密码、Tailscale Serve 身份，或可信代理身份。
## 语言支持
Control UI 可以在首次加载时根据你的浏览器语言环境进行本地化。若要稍后覆盖它，请打开 **概览 -> Gateway 网关访问 -> 语言**。语言环境选择器位于 Gateway 网关访问卡片中，而不是外观下。
控制界面可以在首次加载时根据你的浏览器区域设置进行本地化。若要稍后覆盖它，请打开**概览 -> Gateway 网关访问 -> 语言**。区域设置选择器位于 Gateway 网关访问卡片中，而不是外观下。
- 支持的语言环境：`en`、`zh-CN`、`zh-TW`、`pt-BR`、`de`、`es`、`ja-JP`、`ko`、`fr`、`ar`、`it`、`tr`、`uk`、`id`、`pl`、`th`、`vi`、`nl`、`fa`
- 支持的区域设置：`en`、`zh-CN`、`zh-TW`、`pt-BR`、`de`、`es`、`ja-JP`、`ko`、`fr`、`ar`、`it`、`tr`、`uk`、`id`、`pl`、`th`、`vi`、`nl`、`fa`
- 非英语翻译会在浏览器中延迟加载。
- 所选语言环境会保存在浏览器存储中，并在后续访问时复用。
- 选中的区域设置会保存在浏览器存储中，并在以后访问时复用。
- 缺失的翻译键会回退到英语。
文档翻译会为同一组非英语语言环境生成，但文档站点内置的 Mintlify 语言选择器仅限于 Mintlify 接受的语言环境代码。泰语（`th`）和波斯语（`fa`）文档仍会在发布仓库中生成；在 Mintlify 支持这些代码之前，它们可能不会出现在该选择器中。
文档翻译会针对同一组非英语区域设置生成，但文档站点内置的 Mintlify 语言选择器仅限于 Mintlify 接受的区域设置代码。泰语（`th`）和波斯语（`fa`）文档仍会在发布仓库中生成；在 Mintlify 支持这些代码之前，它们可能不会出现在该选择器中。
## 外观主题
外观面板保留内置的 Claw、Knot 和 Dash 主题，外加一个浏览器本地 tweakcn 导入槽位。若要导入主题，请打开 [tweakcn 编辑器](https://tweakcn.com/editor/theme)，选择或创建一个主题，点击 **分享**，然后将复制的主题链接粘贴到外观中。导入器还接受 `https://tweakcn.com/r/themes/<id>` 注册表 URL、类似 `https://tweakcn.com/editor/theme?theme=amethyst-haze` 的编辑器 URL、相对 `/themes/<id>` 路径、原始主题 ID，以及默认主题名称，例如 `amethyst-haze`。
外观面板保留内置的 Claw、Knot 和 Dash 主题，外加一个浏览器本地的 tweakcn 导入槽。若要导入主题，请打开 [tweakcn 编辑器](https://tweakcn.com/editor/theme)，选择或创建一个主题，点击**分享**，然后将复制的主题链接粘贴到外观中。导入器也接受 `https://tweakcn.com/r/themes/<id>` 注册表 URL、类似 `https://tweakcn.com/editor/theme?theme=amethyst-haze` 的编辑器 URL、相对 `/themes/<id>` 路径、原始主题 ID，以及默认主题名称，例如 `amethyst-haze`。
导入的主题只会存储在当前浏览器配置文件中。它们不会写入 Gateway 网关配置，也不会跨设备同步。替换导入的主题会更新这一个本地槽位；如果当前选中的是导入主题，清除它会将活动主题切回 Claw。
导入的主题只存储在当前浏览器配置文件中。它们不会写入 Gateway 网关配置，也不会跨设备同步。替换导入的主题会更新这一个本地槽；如果当前选中了导入主题，清除它会将活动主题切回 Claw。
## 它当前能做什么
## 它现在能做什么
<AccordionGroup>
<Accordion title="聊天和语音交谈">
<Accordion title="聊天和语音">
- 通过 Gateway 网关 WS 与模型聊天（`chat.history`、`chat.send`、`chat.abort`、`chat.inject`）。
- 通过浏览器实时会话进行语音交谈。OpenAI 使用直接 WebRTC，Google Live 通过 WebSocket 使用受限的一次性浏览器令牌，而仅后端实时语音插件使用 Gateway 网关中继传输。中继会将提供商凭证保留在 Gateway 网关上，同时浏览器通过 `talk.realtime.relay*` RPC 流式传输麦克风 PCM，并通过 `chat.send` 将 `openclaw_agent_consult` 工具调用发回给已配置的更大 OpenClaw 模型。
- 在聊天中流式传输工具调用和实时工具输出卡片（智能体事件）。
- 通过浏览器实时会话进行语音对话。OpenAI 使用直接 WebRTC，Google Live 使用通过 WebSocket 传递的受限一次性浏览器令牌，而仅后端实时语音插件使用 Gateway 网关中继传输。中继会将提供商凭据保留在 Gateway 网关上，同时浏览器通过 `talk.realtime.relay*` RPC 流式传输麦克风 PCM，并通过 `chat.send` 将 `openclaw_agent_consult` 工具调用发回给配置的更大 OpenClaw 模型。
- 在聊天中流式传输工具调用 + 实时工具输出卡片（智能体事件）。
</Accordion>
<Accordion title="渠道、实例、会话、Dreaming">
- 渠道：内置渠道以及内置/外部插件渠道状态、二维码登录和按渠道配置（`channels.status`、`web.login.*`、`config.patch`）。
<Accordion title="渠道、实例、会话、梦境">
- 渠道：内置以及内置/外部插件渠道的状态、二维码登录和按渠道配置（`channels.status`、`web.login.*`、`config.patch`）。
- 实例：在线列表 + 刷新（`system-presence`）。
- 会话：列表 + 按会话设置模型/思考/快速/详细/跟踪/推理覆盖（`sessions.list`、`sessions.patch`）。
- Dreams：Dreaming 状态、启用/禁用开关，以及 Dream Diary 阅读器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。
- 会话：列表 + 按会话设置模型/思考/快速/详细/跟踪/推理覆盖项（`sessions.list`、`sessions.patch`）。
- 梦境：Dreaming 状态、启用/禁用切换，以及 Dream Diary 阅读器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。
</Accordion>
<Accordion title="Cron、Skills、节点、exec 批准">
<Accordion title="Cron、Skills、节点、执行批准">
- Cron 作业：列出/添加/编辑/运行/启用/禁用 + 运行历史（`cron.*`）。
- Skills：状态、启用/禁用、安装、API key 更新（`skills.*`）。
- Skills：状态、启用/禁用、安装、API 密钥更新（`skills.*`）。
- 节点：列表 + 能力（`node.list`）。
- Exec 批准：为 `exec host=gateway/node` 编辑 Gateway 网关或节点 allowlist + 询问策略（`exec.approvals.*`）。
- 执行批准：编辑 Gateway 网关或节点允许列表 + `exec host=gateway/node` 的询问策略（`exec.approvals.*`）。
</Accordion>
<Accordion title="配置">
- 查看/编辑 `~/.openclaw/openclaw.json`（`config.get`、`config.set`）。
- 应用 + 带验证重启（`config.apply`），并唤醒最后一个活跃会话。
- 写入包含 base-hash 保护，以防覆盖并发编辑。
- 写入（`config.set`/`config.apply`/`config.patch`）会为提交的配置载荷中的引用预检活动 SecretRef 解析；未解析的活动已提交引用会在写入前被拒绝。
- Schema + 表单渲染（`config.schema` / `config.schema.lookup`，包括字段 `title` / `description`、匹配的 UI 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点上的文档元数据，以及可用时的插件 + 渠道 schema）；只有在快照具有安全的原始往返能力时，Raw JSON 编辑器才可用。
- 如果快照无法安全地往返原始文本，Control UI 会强制使用表单模式，并为该快照禁用原始模式。
- Raw JSON 编辑器的“重置为已保存”会保留原始编写的形状（格式、注释、`$include` 布局），而不是重新渲染扁平化快照，因此当快照可以安全往返时，外部编辑会在重置后保留下来。
- 结构化 SecretRef 对象值在表单文本输入中以只读方式渲染，以防意外发生对象到字符串的损坏。
- 通过验证应用 + 重启（`config.apply`），并唤醒最后一个活跃会话。
- 写入包含基础哈希保护，以防覆盖并发编辑。
- 写入（`config.set`/`config.apply`/`config.patch`）会对提交的配置载荷中的引用预检活动 SecretRef 解析；未解析的活动提交引用会在写入前被拒绝。
- Schema + 表单渲染（`config.schema` / `config.schema.lookup`，包括字段 `title` / `description`、匹配的 UI 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点上的文档元数据，以及可用时的插件 + 渠道 schema）；仅当快照具备安全的原始往返能力时，Raw JSON 编辑器才可用。
- 如果快照无法安全往返原始文本，控制界面会对该快照强制使用表单模式并禁用原始模式。
- Raw JSON 编辑器的“重置为已保存”会保留原始编辑形态（格式、注释、`$include` 布局），而不是重新渲染一个扁平化快照，因此当快照可以安全往返时，外部编辑会在重置后保留下来。
- 结构化 SecretRef 对象值会在表单文本输入中以只读方式呈现，以防意外的对象到字符串损坏。
</Accordion>
<Accordion title="调试、日志、更新">
- 调试：状态/健康/模型快照 + 事件日志 + 手动 RPC 调用（`status`、`health`、`models.list`）。
- 事件日志包含 Control UI 刷新/RPC 计时，以及当浏览器暴露这些 PerformanceObserver 条目类型时的长动画帧或长任务浏览器响应性条目。
- 日志：带过滤/导出的 Gateway 网关文件日志实时 tail（`logs.tail`）。
- 更新：运行包/git 更新 + 重启（`update.run`），附带重启报告，然后在重新连接后轮询 `update.status` 以验证正在运行的 Gateway 网关版本。
- 事件日志包含控制界面刷新/RPC 计时，以及当浏览器公开这些 PerformanceObserver 条目类型时的长动画帧或长任务浏览器响应性条目。
- 日志：带过滤/导出的 Gateway 网关文件日志实时尾随（`logs.tail`）。
- 更新：运行包/git 更新 + 重启（`update.run`）并生成重启报告，然后在重连后轮询 `update.status` 以验证正在运行的 Gateway 网关版本。
</Accordion>
<Accordion title="Cron 作业面板说明">
- 对于隔离作业，投递默认会公告摘要。如果你希望仅内部运行，可以切换为无。
- 对于隔离作业，交付默认设置为公告摘要。如果你想要仅内部运行，可以切换为无。
- 选择公告时会显示渠道/目标字段。
- Webhook 模式使用 `delivery.mode = "webhook"`，并将 `delivery.to` 设置为有效的 HTTP(S) webhook URL。
- 对于主会话作业，可以使用 webhook 和无投递模式。
- 高级编辑控件包括运行后删除、清除智能体覆盖、cron 精确/错峰选项、智能体模型/思考覆盖，以及尽力而为投递开关。
- 对于主会话作业，webhook 和无交付模式均可用。
- 高级编辑控件包括运行后删除、清除智能体覆盖、cron 精确/错峰选项、智能体模型/思考覆盖，以及尽力交付切换。
- 表单验证以内联方式显示字段级错误；无效值会禁用保存按钮，直到修复为止。
- 设置 `cron.webhookToken` 可发送专用 bearer 令牌；如果省略，webhook 会在没有身份验证标头的情况下发送。
- 已弃用的回退：存储的旧版作业如果带有 `notify: true`，在迁移前仍可使用 `cron.webhook`。
- 设置 `cron.webhookToken` 可发送专用 bearer 令牌；如果省略，webhook 会在没有认证标头的情况下发送。
- 已弃用的回退：存储的旧版作业若带有 `notify: true`，在迁移前仍可使用 `cron.webhook`。
</Accordion>
</AccordionGroup>
@ -158,52 +158,55 @@ Control UI 可以在首次加载时根据你的浏览器语言环境进行本地
<Accordion title="发送和历史语义">
- `chat.send` 是**非阻塞**的：它会立即以 `{ runId, status: "started" }` 确认，响应通过 `chat` 事件流式传输。
- 聊天上传接受图片和非视频文件。图片保留原生图片路径；其他文件会作为托管媒体存储，并在历史记录中显示为附件链接。
- 使用相同的 `idempotencyKey` 重新发送时，运行期间会返回 `{ status: "in_flight" }`，完成后会返回 `{ status: "ok" }`。
- 出于 UI 安全考虑，`chat.history` 响应有大小限制。当转录条目过大时，Gateway 网关可能会截断长文本字段，省略较重的元数据块，并用占位符（`[chat.history omitted: message too large]`）替换超大的消息。
- 助手/生成的图片会持久化为托管媒体引用，并通过经过身份验证的 Gateway 网关媒体 URL 返回，因此重新加载不依赖原始 base64 图片载荷继续保留在聊天历史响应中。
- `chat.history` 还会从可见助手文本中移除仅用于显示的内联指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 载荷（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 和被截断的工具调用块）以及泄漏的 ASCII/全角模型控制令牌，并省略整段可见文本仅为精确静默令牌 `NO_REPLY` / `no_reply` 的助手条目。
- 在一次发送处于活动状态以及最终历史刷新期间，如果 `chat.history` 短暂返回较旧的快照，聊天视图会保持本地乐观用户/助手消息可见；一旦 Gateway 网关历史记录追上，规范转录会替换这些本地消息。
- 实时 `chat` 事件是投递状态，而 `chat.history` 会从持久会话转录中重建。在工具最终事件之后，控制 UI 会重新加载历史记录，并且只合并一个很小的乐观尾部；转录边界记录在 [WebChat](/zh-CN/web/webchat) 中。
- `chat.inject` 会向会话转录追加一条助手备注，并广播一个 `chat` 事件用于仅 UI 更新（无智能体运行，无渠道投递）。
- 聊天标题中的模型和思考选择器会通过 `sessions.patch` 立即修补活动会话；它们是持久的会话覆盖，而不是仅限一轮的发送选项。
- 在控制 UI 中输入 `/new` 会创建并切换到与 New Chat 相同的全新仪表板会话。输入 `/reset` 会保留 Gateway 网关对当前会话的显式就地重置。
- 聊天模型选择器会请求 Gateway 网关配置的模型视图。如果存在 `agents.defaults.models`，该允许列表会驱动选择器。否则，选择器会显示显式的 `models.providers.*.models` 条目以及具有可用凭证的提供商。完整目录仍可通过调试 `models.list` RPC 和 `view: "all"` 使用。
- 当新的 Gateway 网关会话用量报告显示上下文压力较高时，聊天编辑区会显示上下文提示；在推荐的压缩级别下，还会显示一个压缩按钮，用于运行正常的会话压缩路径。陈旧的令牌快照会被隐藏，直到 Gateway 网关再次报告新的用量。
- 使用相同的 `idempotencyKey` 重新发送时，运行中会返回 `{ status: "in_flight" }`，完成后会返回 `{ status: "ok" }`。
- `chat.history` 响应会限制大小以保障 UI 安全。当转录条目过大时，Gateway 网关可能会截断长文本字段，省略较大的元数据块，并用占位符（`[chat.history omitted: message too large]`）替换过大的消息。
- 助手/生成的图片会作为托管媒体引用持久化，并通过已认证的 Gateway 网关媒体 URL 返回，因此重新加载不依赖原始 base64 图片载荷继续保留在聊天历史响应中。
- `chat.history` 还会从可见助手文本中移除仅用于显示的内联指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 载荷（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 以及被截断的工具调用块）和泄漏的 ASCII/全角模型控制令牌，并省略整个可见文本仅为精确静默令牌 `NO_REPLY` / `no_reply` 的助手条目。
- 在活跃发送期间和最终历史刷新时，如果 `chat.history` 短暂返回较旧的快照，聊天视图会继续显示本地乐观用户/助手消息；一旦 Gateway 网关历史追上，规范转录就会替换这些本地消息。
- 实时 `chat` 事件表示投递状态，而 `chat.history` 会从持久会话转录重建。在工具最终事件之后，Control UI 会重新加载历史并仅合并一小段乐观尾部；转录边界记录在 [WebChat](/zh-CN/web/webchat) 中。
- `chat.inject` 会向会话转录追加一条助手备注，并广播一个 `chat` 事件用于仅限 UI 的更新（不运行智能体，不进行渠道投递）。
- 聊天标题栏会在会话选择器之前显示智能体筛选器，并且会话选择器按所选智能体限定范围。切换智能体时，只显示与该智能体关联的会话；如果它还没有保存的仪表板会话，则回退到该智能体的主会话。
- 在桌面宽度下，聊天控件会保持在一行紧凑布局中，并在向下滚动转录时折叠；向上滚动、回到顶部或到达底部时会恢复控件。
- 连续重复的纯文本消息会渲染为一个气泡，并带有计数徽章。带有图片、附件、工具输出或 canvas 预览的消息不会折叠。
- 聊天标题栏中的模型和思考选择器会立即通过 `sessions.patch` 修补活跃会话；它们是持久的会话覆盖项，而不是仅限单轮的发送选项。
- 在 Control UI 中输入 `/new` 会创建并切换到与 New Chat 相同的全新仪表板会话。输入 `/reset` 会保留 Gateway 网关对当前会话的显式就地重置。
- 聊天模型选择器会请求 Gateway 网关配置的模型视图。如果存在 `agents.defaults.models`，该允许列表会驱动选择器。否则，选择器会显示显式的 `models.providers.*.models` 条目，以及具有可用认证的提供商。完整目录仍可通过调试用 `models.list` RPC 使用 `view: "all"` 获取。
- 当新的 Gateway 网关会话用量报告显示上下文压力较高时，聊天编写区会显示上下文提示；在建议的压缩级别下，还会显示一个紧凑按钮，用于运行正常的会话压缩路径。在 Gateway 网关再次报告新鲜用量之前，过期令牌快照会被隐藏。
</Accordion>
<Accordion title="对话模式（浏览器实时）">
对话模式使用已注册的实时语音提供商。使用 `talk.provider: "openai"` 加 `talk.providers.openai.apiKey` 配置 OpenAI，或使用 `talk.provider: "google"` 加 `talk.providers.google.apiKey` 配置 Google；Voice Call 实时提供商配置仍可作为回退复用。浏览器永远不会收到标准提供商 API key。OpenAI 会收到用于 WebRTC 的临时 Realtime 客户端密钥。Google Live 会收到用于浏览器 WebSocket 会话的一次性受限 Live API 身份验证令牌，其中指令和工具声明由 Gateway 网关锁定到令牌中。仅公开后端实时桥接的提供商会通过 Gateway 网关中继传输运行，因此凭据和供应商套接字保留在服务器端，而浏览器音频则通过经过身份验证的 Gateway 网关 RPC 传输。Realtime 会话提示由 Gateway 网关组装；`talk.realtime.session` 不接受调用方提供的指令覆盖。
<Accordion title="通话模式（浏览器实时）">
通话模式使用已注册的实时语音提供商。配置 OpenAI 时使用 `talk.provider: "openai"` 加 `talk.providers.openai.apiKey`，或配置 Google 时使用 `talk.provider: "google"` 加 `talk.providers.google.apiKey`；Voice Call 实时提供商配置仍可作为回退复用。浏览器永远不会收到标准提供商 API key。OpenAI 会收到用于 WebRTC 的临时 Realtime 客户端密钥。Google Live 会收到用于浏览器 WebSocket 会话的一次性受限 Live API 认证令牌，指令和工具声明由 Gateway 网关锁定到该令牌中。仅公开后端实时桥接的提供商会通过 Gateway 网关中继传输运行，因此凭据和厂商 socket 会保留在服务器端，而浏览器音频会通过已认证的 Gateway 网关 RPC 传输。Realtime 会话提示由 Gateway 网关组装；`talk.realtime.session` 不接受调用方提供的指令覆盖。
在聊天编辑器中，Talk 控件是麦克风听写按钮旁边的波形按钮。Talk 启动时，编辑器状态行会显示 `Connecting Talk...`，音频连接后显示 `Talk live`，或者当实时工具调用正在通过 `chat.send` 咨询配置的更大模型时显示 `Asking OpenClaw...`。
在聊天编写器中，Talk 控件是麦克风听写按钮旁边的波形按钮。Talk 启动时，编写器状态行会显示 `Connecting Talk...`，随后在音频已连接时显示 `Talk live`，或在实时工具调用通过 `chat.send` 咨询已配置的更大模型时显示 `Asking OpenClaw...`。
维护者实时冒烟测试：`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 会验证 OpenAI 浏览器 WebRTC SDP 交换、Google Live 受限令牌浏览器 WebSocket 设置，以及使用模拟麦克风媒体的 Gateway 网关中继浏览器适配器。该命令只打印提供商状态，不记录密钥。
维护者实时冒烟测试：`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 会验证 OpenAI 浏览器 WebRTC SDP 交换、Google Live 受限令牌浏览器 WebSocket 设置，以及使用假麦克风媒体的 Gateway 网关中继浏览器适配器。该命令只打印提供商状态，不记录密钥。
</Accordion>
<Accordion title="停止和中止">
- 点击**停止**（调用 `chat.abort`）。
- 运行处于活动状态时，普通后续消息会排队。点击排队消息上的 **Steer**，可将该后续消息注入正在运行的轮次中。
- 输入 `/stop`（或独立中止短语，如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）以带外中止。
- `chat.abort` 支持 `{ sessionKey }`（无 `runId`），用于中止该会话的所有活动运行。
- 点击 **Stop**（调用 `chat.abort`）。
- 运行处于活跃状态时，普通后续消息会排队。点击排队消息上的 **Steer**，可将该后续消息注入正在运行的轮次。
- 输入 `/stop`（或独立的中止短语，例如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）以带外中止。
- `chat.abort` 支持 `{ sessionKey }`（无 `runId`）来中止该会话的所有活跃运行。
</Accordion>
<Accordion title="中止部分内容保留">
- 当运行被中止时，部分助手文本仍可显示在 UI 中。
<Accordion title="中止部分保留">
- 运行被中止时，部分助手文本仍可显示在 UI 中。
- 当存在已缓冲输出时，Gateway 网关会将已中止的部分助手文本持久化到转录历史中。
- 持久化条目包含中止元数据，因此转录消费者可以区分中止部分内容和正常完成输出。
- 持久化条目包含中止元数据，因此转录消费者可以区分中止片段和正常完成输出。
</Accordion>
</AccordionGroup>
## PWA 安装和 Web Push 推送
## PWA 安装和 Web 推送
控制 UI 附带 `manifest.webmanifest` 和 service worker，因此现代浏览器可以将其安装为独立 PWA。Web Push 推送让 Gateway 网关即使在标签页或浏览器窗口未打开时，也可以通过通知唤醒已安装的 PWA。
Control UI 附带 `manifest.webmanifest` 和 service worker，因此现代浏览器可以将其安装为独立 PWA。Web Push 允许 Gateway 网关通过通知唤醒已安装的 PWA，即使标签页或浏览器窗口未打开。
| 表面 | 作用 |
| ----------------------------------------------------- | ------------------------------------------------------------------ |
| `ui/public/manifest.webmanifest` | PWA 清单。浏览器在可访问后会提供“安装应用”。 |
| `ui/public/manifest.webmanifest` | PWA 清单。浏览器在可访问后会提供 “Install app”。 |
| `ui/public/sw.js` | 处理 `push` 事件和通知点击的 service worker。 |
| `push/vapid-keys.json`（位于 OpenClaw 状态目录下） | 自动生成的 VAPID 密钥对，用于签名 Web Push 推送载荷。 |
| `push/web-push-subscriptions.json` | 持久化的浏览器订阅端点。 |
| `push/vapid-keys.json`（位于 OpenClaw 状态目录下） | 自动生成的 VAPID 密钥对，用于签名 Web Push 载荷。 |
| `push/web-push-subscriptions.json` | 持久化的浏览器订阅端点。 |
当你想固定密钥（用于多主机部署、密钥轮换或测试）时，可通过 Gateway 网关进程上的环境变量覆盖 VAPID 密钥对：
@ -211,30 +214,30 @@ Control UI 可以在首次加载时根据你的浏览器语言环境进行本地
- `OPENCLAW_VAPID_PRIVATE_KEY`
- `OPENCLAW_VAPID_SUBJECT`（默认为 `mailto:openclaw@localhost`）
控制 UI 使用这些按作用域限制的 Gateway 网关方法来注册和测试浏览器订阅：
Control UI 使用这些按作用域限定的 Gateway 网关方法来注册和测试浏览器订阅：
- `push.web.vapidPublicKey` — 获取活动的 VAPID 公钥。
- `push.web.vapidPublicKey` — 获取活跃的 VAPID 公钥。
- `push.web.subscribe` — 注册一个 `endpoint` 以及 `keys.p256dh`/`keys.auth`。
- `push.web.unsubscribe` — 移除已注册的端点。
- `push.web.test` — 向调用方的订阅发送测试通知。
<Note>
Web Push 推送独立于 iOS APNS 中继路径（有关中继支持的推送，请参阅[配置](/zh-CN/gateway/configuration)）和现有 `push.test` 方法；后两者面向原生移动端配对。
Web Push 独立于 iOS APNS 中继路径（有关中继支持的推送，请参阅[配置](/zh-CN/gateway/configuration)）和现有的 `push.test` 方法，后者面向原生移动端配对。
</Note>
## 托管嵌入
助手消息可以使用 `[embed ...]` 短代码以内联方式渲染托管 Web 内容。iframe 沙箱策略由 `gateway.controlUi.embedSandbox` 控制：
助手消息可以使用 `[embed ...]` 短代码内联渲染托管 Web 内容。iframe 沙箱策略由 `gateway.controlUi.embedSandbox` 控制：
<Tabs>
<Tab title="strict">
禁用托管嵌入内的脚本执行。
禁用托管嵌入中的脚本执行。
</Tab>
<Tab title="scripts（默认）">
允许交互式嵌入，同时保持来源隔离；这是默认值，通常足以用于自包含浏览器游戏/小组件。
在保持源隔离的同时允许交互式嵌入；这是默认值，通常足以用于自包含的浏览器游戏/小组件。
</Tab>
<Tab title="trusted">
在 `allow-scripts` 之上添加 `allow-same-origin`，用于有意需要更强权限的同站点文档。
在 `allow-scripts` 之上为有意需要更强权限的同站点文档添加 `allow-same-origin`。
</Tab>
</Tabs>
@ -251,10 +254,10 @@ Web Push 推送独立于 iOS APNS 中继路径（有关中继支持的推送，
```
<Warning>
仅当嵌入文档确实需要同源行为时才使用 `trusted`。对于大多数智能体生成的游戏和交互式画布，`scripts` 是更安全的选择。
只有当嵌入文档确实需要同源行为时，才使用 `trusted`。对于大多数智能体生成的游戏和交互式 canvas，`scripts` 是更安全的选择。
</Warning>
默认情况下，绝对外部 `http(s)` 嵌入 URL 仍会被阻止。如果你有意让 `[embed url="https://..."]` 加载第三方页面，请设置 `gateway.controlUi.allowExternalEmbedUrls: true`。
默认情况下，绝对外部 `http(s)` 嵌入 URL 仍会被阻止。如果你有意希望 `[embed url="https://..."]` 加载第三方页面，请设置 `gateway.controlUi.allowExternalEmbedUrls: true`。
## 聊天消息宽度
@ -270,13 +273,13 @@ Web Push 推送独立于 iOS APNS 中继路径（有关中继支持的推送，
}
```
该值会在到达浏览器前被验证。支持的值包括普通长度和百分比，例如 `960px` 或 `82%`，以及受限的 `min(...)`、`max(...)`、`clamp(...)`、`calc(...)` 和 `fit-content(...)` 宽度表达式。
该值会在到达浏览器之前进行验证。支持的值包括普通长度和百分比，例如 `960px` 或 `82%`，以及受限的 `min(...)`、`max(...)`、`clamp(...)`、`calc(...)` 和 `fit-content(...)` 宽度表达式。
## Tailnet 访问（推荐）
<Tabs>
<Tab title="集成 Tailscale Serve（首选）">
将 Gateway 网关保持在 loopback 上，并让 Tailscale Serve 通过 HTTPS 代理它：
<Tab title="集成式 Tailscale Serve（首选）">
将 Gateway 网关保留在 loopback 上，并让 Tailscale Serve 通过 HTTPS 代理它：
```bash
openclaw gateway --tailscale serve
@ -286,16 +289,16 @@ Web Push 推送独立于 iOS APNS 中继路径（有关中继支持的推送，
- `https://<magicdns>/`（或你配置的 `gateway.controlUi.basePath`）
默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，控制 UI/WebSocket Serve 请求可以通过 Tailscale 身份标头（`tailscale-user-login`）进行身份验证。OpenClaw 会使用 `tailscale whois` 解析 `x-forwarded-for` 地址并将其与标头匹配，从而验证身份，并且仅在请求命中 loopback 且带有 Tailscale 的 `x-forwarded-*` 标头时接受这些请求。对于带有浏览器设备身份的控制 UI 操作者会话，此经过验证的 Serve 路径还会跳过设备配对往返；无设备浏览器和节点角色连接仍会遵循正常设备检查。如果你即使对 Serve 流量也想要求显式共享密钥凭据，请设置 `gateway.auth.allowTailscale: false`。然后使用 `gateway.auth.mode: "token"` 或 `"password"`。
默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Control UI/WebSocket Serve 请求可以通过 Tailscale 身份标头（`tailscale-user-login`）进行认证。OpenClaw 会通过使用 `tailscale whois` 解析 `x-forwarded-for` 地址并将其与标头匹配来验证身份，并且只在请求命中 loopback 且带有 Tailscale 的 `x-forwarded-*` 标头时接受这些身份。对于带浏览器设备身份的 Control UI 操作者会话，这条已验证的 Serve 路径还会跳过设备配对往返；无设备浏览器和节点角色连接仍会遵循正常的设备检查。如果你希望即使对 Serve 流量也要求显式共享密钥凭据，请设置 `gateway.auth.allowTailscale: false`。然后使用 `gateway.auth.mode: "token"` 或 `"password"`。
对于该异步 Serve 身份路径，同一客户端 IP 和身份验证作用域的失败身份验证尝试会在写入速率限制之前被串行化。因此，来自同一浏览器的并发错误重试可能会在第二个请求上显示 `retry later`，而不是两个普通不匹配并行竞争。
对于该异步 Serve 身份路径，同一客户端 IP 和认证作用域的失败认证尝试会在写入速率限制之前被串行化。因此，来自同一浏览器的并发错误重试可能会在第二个请求上显示 `retry later`，而不是两个普通不匹配并行竞争。
<Warning>
无令牌 Serve 身份验证假设 Gateway 网关主机可信。如果不受信任的本地代码可能在该主机上运行，请要求 token/password 身份验证。
无令牌 Serve 认证假定 Gateway 网关主机可信。如果不受信任的本地代码可能在该主机上运行，请要求 token/password 认证。
</Warning>
</Tab>
<Tab title="绑定到 tailnet + 令牌">
<Tab title="绑定到 tailnet + token">
```bash
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
```
@ -304,28 +307,28 @@ Web Push 推送独立于 iOS APNS 中继路径（有关中继支持的推送，
- `http://<tailscale-ip>:18789/`（或你配置的 `gateway.controlUi.basePath`）
将匹配的共享密钥粘贴到 UI 设置中（以 `connect.params.auth.token` 或 `connect.params.auth.password` 形式发送）。
将匹配的共享密钥粘贴到 UI 设置中（作为 `connect.params.auth.token` 或 `connect.params.auth.password` 发送）。
</Tab>
</Tabs>
## 不安全 HTTP
## 不安全的 HTTP
如果你通过纯 HTTP（`http://<lan-ip>` 或 `http://<tailscale-ip>`）打开仪表板，浏览器会在**非安全上下文**中运行并阻止 WebCrypto。默认情况下，OpenClaw 会**阻止**没有设备身份的控制 UI 连接。
如果你通过纯 HTTP（`http://<lan-ip>` 或 `http://<tailscale-ip>`）打开仪表盘，浏览器会在**非安全上下文**中运行并阻止 WebCrypto。默认情况下，OpenClaw 会**阻止**没有设备身份的 Control UI 连接。
已记录的例外：
已记录的例外情况：
- 仅 localhost 的不安全 HTTP 兼容性，使用 `gateway.controlUi.allowInsecureAuth=true`
- 通过 `gateway.auth.mode: "trusted-proxy"` 成功完成的操作者控制 UI 身份验证
- 紧急开关 `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
- 使用 `gateway.controlUi.allowInsecureAuth=true` 的仅 localhost 不安全 HTTP 兼容性
- 通过 `gateway.auth.mode: "trusted-proxy"` 成功完成操作员 Control UI 凭证
- 紧急破窗选项 `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
**建议修复：** 使用 HTTPS（Tailscale Serve）或在本地打开 UI：
**推荐修复：**使用 HTTPS（Tailscale Serve）或在本地打开 UI：
- `https://<magicdns>/`（Serve）
- `http://127.0.0.1:18789/`（在 Gateway 网关主机上）
<AccordionGroup>
<Accordion title="不安全认证开关行为">
<Accordion title="不安全凭证开关行为">
```json5
{
gateway: {
@ -343,7 +346,7 @@ Web Push 推送独立于 iOS APNS 中继路径（有关中继支持的推送，
- 它不会放宽远程（非 localhost）设备身份要求。
</Accordion>
<Accordion title="仅用于紧急破窗">
<Accordion title="仅限紧急破窗">
```json5
{
gateway: {
@ -355,52 +358,52 @@ Web Push 推送独立于 iOS APNS 中继路径（有关中继支持的推送，
```
<Warning>
`dangerouslyDisableDeviceAuth` 会禁用 Control UI 设备身份检查，是严重的安全降级。紧急使用后请尽快还原。
`dangerouslyDisableDeviceAuth` 会禁用 Control UI 设备身份检查，属于严重的安全降级。紧急使用后请尽快还原。
</Warning>
</Accordion>
<Accordion title="受信代理说明">
- 成功的受信代理认证可以允许没有设备身份的 **operator** Control UI 会话进入。
- 这**不**适用于 node-role Control UI 会话。
- 同主机 local loopback 反向代理仍然不满足受信代理认证；请参阅[受信代理认证](/zh-CN/gateway/trusted-proxy-auth)。
- 成功的 trusted-proxy 凭证可以允许没有设备身份的**操作员** Control UI 会话进入。
- 这**不**适用于节点角色的 Control UI 会话。
- 同主机回环反向代理仍然不满足 trusted-proxy 凭证；请参阅[受信代理凭证](/zh-CN/gateway/trusted-proxy-auth)。
</Accordion>
</AccordionGroup>
请参阅 [Tailscale](/zh-CN/gateway/tailscale) 获取 HTTPS 设置指导。
有关 HTTPS 设置指导，请参阅 [Tailscale](/zh-CN/gateway/tailscale)。
## 内容安全策略
Control UI 附带严格的 `img-src` 策略：只允许**同源**资源、`data:` URL，以及本地生成的 `blob:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，并且不会发起网络请求。
Control UI 附带严格的 `img-src` 策略：只允许**同源**资源、`data:` URL 和本地生成的 `blob:` URL。浏览器会拒绝远程 `http(s)` 和协议相对图片 URL，且不会发起网络获取。
实际含义如下：
- 通过相对路径提供的头像和图片（例如 `/avatars/<id>`）仍会渲染，包括 UI 获取并转换为本地 `blob:` URL 的已认证头像路由。
- 内联 `data:image/...` URL 仍会渲染（对协议内载荷很有用）。
- Control UI 创建的本地 `blob:` URL 仍会渲染。
- 渠道元数据发出的远程头像 URL 会在 Control UI 的头像辅助逻辑中被移除，并替换为内置 logo/badge，因此受攻陷或恶意渠道无法强制操作员浏览器获取任意远程图片。
- 渠道元数据发出的远程头像 URL 会在 Control UI 的头像辅助函数处被剥离，并替换为内置徽标/徽章，因此被入侵或恶意的渠道无法强制操作员浏览器发起任意远程图片获取。
你无需做任何更改即可获得此行为，它始终启用且不可配置。
你无需更改任何内容即可获得此行为——它始终启用且不可配置。
## 头像路由认证
## 头像路由凭证
配置 Gateway 网关认证后，Control UI 头像端点需要与 API 其余部分相同的 Gateway 网关令牌：
配置 Gateway 网关凭证后，Control UI 头像端点需要与 API 其余部分相同的 Gateway 网关令牌：
- `GET /avatar/<agentId>` 只向已认证调用方返回头像图片。`GET /avatar/<agentId>?meta=1` 在相同规则下返回头像元数据。
- 对任一路由的未认证请求都会被拒绝（与同级 assistant-media 路由一致）。这可以防止头像路由在原本受保护的主机上泄露智能体身份。
- Control UI 本身会在获取头像时以 bearer 标头转发 Gateway 网关令牌，并使用已认证的 blob URL，因此图片仍会在仪表盘中渲染。
- `GET /avatar/<agentId>` 仅向已认证调用方返回头像图片。`GET /avatar/<agentId>?meta=1` 按相同规则返回头像元数据。
- 对任一路由的未认证请求都会被拒绝（与同级 assistant-media 路由一致）。这可以防止头像路由在其他方面受保护的主机上泄露智能体身份。
- Control UI 自身在获取头像时会将 Gateway 网关令牌作为 bearer 标头转发，并使用已认证的 blob URL，因此图片仍会在仪表盘中渲染。
如果你禁用 Gateway 网关认证（不建议在共享主机上这样做），头像路由也会变为未认证，与 Gateway 网关其余部分保持一致。
如果你禁用 Gateway 网关凭证（不建议在共享主机上这样做），头像路由也会与 Gateway 网关的其余部分一样变为未认证。
## Assistant media 路由认证
## 助手媒体路由凭证
配置 Gateway 网关认证后，assistant 本地媒体预览会使用两步路由：
配置 Gateway 网关凭证后，助手本地媒体预览会使用两步路由：
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` 需要普通的 Control UI operator 认证。浏览器在检查可用性时会将 Gateway 网关令牌作为 bearer 标头发送。
- 成功的元数据响应会包含一个短期有效的 `mediaTicket`，其作用域限定为该精确源路径。
- 浏览器渲染的图片、音频、视频和文档 URL 使用 `mediaTicket=<ticket>`，而不是活动 Gateway 网关令牌或密码。该票据会快速过期，且无法授权不同的源。
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` 需要普通的 Control UI 操作员凭证。浏览器在检查可用性时会将 Gateway 网关令牌作为 bearer 标头发送。
- 成功的元数据响应包含一个短期有效的 `mediaTicket`，其作用域限定为该确切源路径。
- 浏览器渲染的图片、音频、视频和文档 URL 使用 `mediaTicket=<ticket>`，而不是活动的 Gateway 网关令牌或密码。票据会快速过期，且不能授权不同的来源。
这能让普通媒体渲染兼容浏览器原生媒体元素，同时不会把可复用的 Gateway 网关凭据放进可见媒体 URL 中。
这能让普通媒体渲染与浏览器原生媒体元素保持兼容，同时不会把可复用的 Gateway 网关凭据放进可见媒体 URL 中。
## 构建 UI
@ -410,13 +413,13 @@ Gateway 网关从 `dist/control-ui` 提供静态文件。使用以下命令构
pnpm ui:build
```
可选的绝对 base（当你需要固定资源 URL 时）：
可选的绝对基础路径（当你需要固定资源 URL 时）：
```bash
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
```
用于本地开发（单独的开发服务器）：
本地开发（单独的开发服务器）：
```bash
pnpm ui:dev
@ -426,7 +429,7 @@ pnpm ui:dev
## 调试/测试：开发服务器 + 远程 Gateway 网关
Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 HTTP 源。当你想在本地使用 Vite 开发服务器，而 Gateway 网关在其他位置运行时，这很方便。
Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 HTTP 来源。当你想在本地使用 Vite 开发服务器，而 Gateway 网关在其他位置运行时，这很有用。
<Steps>
<Step title="启动 UI 开发服务器">
@ -439,7 +442,7 @@ Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 H
http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
```
可选的一次性认证（如需要）：
可选的一次性凭证（如果需要）：
```text
http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
@ -452,15 +455,15 @@ Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 H
<Accordion title="说明">
- `gatewayUrl` 会在加载后存储到 localStorage，并从 URL 中移除。
- 如果你通过 `gatewayUrl` 传入完整的 `ws://` 或 `wss://` 端点，请对 `gatewayUrl` 值进行 URL 编码，以便浏览器正确解析查询字符串。
- 应尽可能通过 URL 片段（`#token=...`）传递 `token`。片段不会发送到服务器，这可以避免请求日志和 Referer 泄露。旧版 `?token=` 查询参数仍会为了兼容性导入一次，但仅作为回退，并会在 bootstrap 后立即移除。
- `password` 只保留在内存中。
- 设置 `gatewayUrl` 后，UI 不会回退到配置或环境凭据。请显式提供 `token`（或 `password`）。缺少显式凭据会报错。
- 当 Gateway 网关位于 TLS 后面时（Tailscale Serve、HTTPS 代理等），请使用 `wss://`。
- `gatewayUrl` 只在顶层窗口中被接受（不能嵌入），以防止点击劫持。
- 非 loopback Control UI 部署必须显式设置 `gateway.controlUi.allowedOrigins`（完整源）。这包括远程开发设置。
- Gateway 网关启动时可能会从有效的运行时绑定和端口中填充本地源，例如 `http://localhost:<port>` 和 `http://127.0.0.1:<port>`，但远程浏览器源仍需要显式条目。
- 除了严格受控的本地测试外，不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允许任意浏览器源，而不是“匹配我正在使用的任何主机”。
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 标头源回退模式，但这是危险的安全模式。
- 应尽可能通过 URL 片段（`#token=...`）传入 `token`。片段不会发送到服务器，因此可以避免请求日志和 Referer 泄露。旧版 `?token=` 查询参数仍会为了兼容性导入一次，但仅作为回退，并会在启动后立即剥离。
- `password` 仅保存在内存中。
- 设置 `gatewayUrl` 后，UI 不会回退到配置或环境凭据。请显式提供 `token`（或 `password`）。缺少显式凭据是一个错误。
- 当 Gateway 网关位于 TLS 后方（Tailscale Serve、HTTPS 代理等）时，请使用 `wss://`。
- `gatewayUrl` 仅在顶层窗口中接受（不可嵌入），以防止点击劫持。
- 非回环的 Control UI 部署必须显式设置 `gateway.controlUi.allowedOrigins`（完整来源）。这包括远程开发设置。
- Gateway 网关启动时可能会根据有效的运行时绑定和端口播种本地来源，例如 `http://localhost:<port>` 和 `http://127.0.0.1:<port>`，但远程浏览器来源仍需要显式条目。
- 除了严格受控的本地测试，不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允许任何浏览器来源，而不是“匹配我正在使用的任何主机”。
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 标头来源回退模式，但这是危险的安全模式。
</Accordion>
</AccordionGroup>
@ -479,7 +482,7 @@ Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 H
远程访问设置详情：[远程访问](/zh-CN/gateway/remote)。
## 相关
## 相关内容
- [仪表盘](/zh-CN/web/dashboard) — Gateway 网关仪表盘
- [健康检查](/zh-CN/gateway/health) — Gateway 网关健康监控