diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index fd00e561e..33b68abb2 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -2,62 +2,73 @@ read_when: - 你需要精确的字段级配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向专用子系统参考文档的链接 +summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向专用子系统参考的链接 title: 配置参考 x-i18n: - generated_at: "2026-05-03T18:19:02Z" + generated_at: "2026-05-04T22:54:29Z" model: gpt-5.5 provider: openai - source_hash: 52fa15e85a41ed5ed39102fb641bd33f0aec2e8f244c9d7b3d12b3a1b6dc62a9 + source_hash: 82164a3ea7592f667573b643ee9e0ec840b9b622c9d86c382a3feaf192e75684 source_path: gateway/configuration-reference.md workflow: 16 --- -核心配置参考，适用于 `~/.openclaw/openclaw.json`。如需面向任务的概览，请参阅[配置](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。对于面向任务的概览，请参阅 [配置](/zh-CN/gateway/configuration)。 -覆盖主要的 OpenClaw 配置表面；当某个子系统有自己的更深入参考时，会链接到对应页面。渠道和插件拥有的命令目录，以及深层记忆/QMD 调节项，位于各自页面，而不在本页。 +涵盖主要的 OpenClaw 配置界面；当某个子系统有自己的更深入参考时，会链接到对应页面。渠道和插件拥有的命令目录，以及深层 memory/QMD 调节项，位于各自页面，而不在本页。 -代码事实来源： +代码依据： - `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema；可用时会合并内置/插件/渠道元数据 -- `config.schema.lookup` 返回一个按路径限定的 schema 节点，供下钻工具使用 -- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面验证配置文档基线哈希 +- `config.schema.lookup` 会为下钻工具返回一个按路径限定的 schema 节点 +- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 界面验证配置文档基线哈希 -智能体查找路径：编辑前，使用 `gateway` 工具动作 `config.schema.lookup` 获取精确的字段级文档和约束。使用[配置](/zh-CN/gateway/configuration)获取面向任务的指导；使用本页了解更广的字段映射、默认值，以及到子系统参考的链接。 +智能体查找路径：编辑前，使用 `gateway` 工具操作 `config.schema.lookup` +获取精确到字段级别的文档和约束。使用 +[配置](/zh-CN/gateway/configuration) 获取面向任务的指导，使用本页 +查看更广泛的字段映射、默认值以及指向子系统参考的链接。 -专用深层参考： +专门的深层参考： -- [记忆配置参考](/zh-CN/reference/memory-config)，涵盖 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 -- [斜杠命令](/zh-CN/tools/slash-commands)，涵盖当前内置 + 捆绑命令目录 -- 拥有对应渠道特定命令表面的渠道/插件页面 +- [记忆配置参考](/zh-CN/reference/memory-config)，用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 Dreaming 配置 +- [斜杠命令](/zh-CN/tools/slash-commands)，用于当前内置 + 捆绑命令目录 +- 拥有对应渠道特定命令界面的渠道/插件页面 -配置格式是 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的，省略时 OpenClaw 会使用安全默认值。 +配置格式是 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的 — 省略时 OpenClaw 会使用安全默认值。 --- ## 渠道 -每个渠道的配置键已移至专用页面，请参阅[配置 — 渠道](/zh-CN/gateway/config-channels)了解 `channels.*`，包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage，以及其他内置渠道（认证、访问控制、多账号、提及门控）。 +每个渠道的配置键已移至专用页面 — 请参阅 +[配置 — 渠道](/zh-CN/gateway/config-channels)，了解 `channels.*`， +包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 以及其他 +内置渠道（认证、访问控制、多账号、提及门控）。 ## 智能体默认值、多智能体、会话和消息 -已移至专用页面，请参阅[配置 — 智能体](/zh-CN/gateway/config-agents)，了解： +已移至专用页面 — 请参阅 +[配置 — 智能体](/zh-CN/gateway/config-agents)，了解： -- `agents.defaults.*`（工作区、模型、思考、Heartbeat、记忆、媒体、Skills、沙箱） +- `agents.defaults.*`（工作区、模型、thinking、heartbeat、记忆、媒体、Skills、沙箱） - `multiAgent.*`（多智能体路由和绑定） - `session.*`（会话生命周期、压缩、修剪） -- `messages.*`（消息投递、TTS、markdown 渲染） +- `messages.*`（消息投递、TTS、Markdown 渲染） - `talk.*`（Talk 模式） - - `talk.speechLocale`：可选的 BCP 47 区域设置 ID，用于 iOS/macOS 上的 Talk 语音识别 - - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录文本前保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`） + - `talk.speechLocale`：iOS/macOS 上 Talk 语音识别的可选 BCP 47 区域设置 ID + - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录文本前保留平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`） ## 工具和自定义提供商 -工具策略、实验性开关、提供商支持的工具配置，以及自定义提供商/base-URL 设置已移至专用页面，请参阅[配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools)。 +工具策略、实验性开关、提供商支持的工具配置，以及自定义 +提供商 / base-URL 设置已移至专用页面 — 请参阅 +[配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools)。 ## Models -提供商定义、模型允许列表和自定义提供商设置位于[配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。`models` 根节点还负责全局模型目录行为。 +提供商定义、模型允许列表和自定义提供商设置位于 +[配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。 +`models` 根节点也拥有全局模型目录行为。 ```json5 { @@ -69,12 +80,17 @@ x-i18n: ``` - `models.mode`：提供商目录行为（`merge` 或 `replace`）。 -- `models.providers`：按提供商 ID 建索引的自定义提供商映射。 -- `models.pricing.enabled`：控制后台定价引导流程，该流程会在 sidecar 和渠道到达 Gateway 网关就绪路径后启动。为 `false` 时，Gateway 网关会跳过 OpenRouter 和 LiteLLM 定价目录抓取；已配置的 `models.providers.*.models[].cost` 值仍可用于本地成本估算。 +- `models.providers`：按提供商 ID 键控的自定义提供商映射。 +- `models.pricing.enabled`：控制后台价格引导；该引导会在 sidecar 和渠道到达 Gateway 网关 ready 路径后启动。当为 `false` 时， + Gateway 网关会跳过 OpenRouter 和 LiteLLM 价格目录拉取；已配置的 + `models.providers.*.models[].cost` 值仍可用于本地成本估算。 ## MCP -OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，由嵌入式 Pi 和其他运行时适配器使用。`openclaw mcp list`、`show`、`set` 和 `unset` 命令会管理此块，并且在编辑配置期间不会连接到目标服务器。 +OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由 +嵌入式 Pi 和其他运行时适配器使用。`openclaw mcp list`、 +`show`、`set` 和 `unset` 命令会管理此块，且在配置编辑期间不会连接到 +目标服务器。 ```json5 { @@ -98,11 +114,18 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，由嵌入式 Pi } ``` -- `mcp.servers`：命名的 stdio 或远程 MCP 服务器定义，供暴露已配置 MCP 工具的运行时使用。远程条目使用 `transport: "streamable-http"` 或 `transport: "sse"`；`type: "http"` 是 CLI 原生别名，`openclaw mcp set` 和 `openclaw doctor --fix` 会将其规范化为标准 `transport` 字段。 -- `mcp.sessionIdleTtlMs`：会话作用域内置 MCP 运行时的空闲 TTL。一次性嵌入式运行会请求运行结束清理；此 TTL 是长生命周期会话和未来调用方的兜底机制。 -- `mcp.*` 下的变更会通过释放缓存的会话 MCP 运行时来热应用。下一次工具发现/使用会从新配置重新创建它们，因此被移除的 `mcp.servers` 条目会立即清理，而不是等待空闲 TTL。 +- `mcp.servers`：命名的 stdio 或远程 MCP 服务器定义，供公开已配置 MCP 工具的运行时使用。 + 远程条目使用 `transport: "streamable-http"` 或 `transport: "sse"`； + `type: "http"` 是 CLI 原生别名，`openclaw mcp set` 和 + `openclaw doctor --fix` 会将其规范化为标准 `transport` 字段。 +- `mcp.sessionIdleTtlMs`：会话作用域的内置 MCP 运行时的空闲 TTL。 + 一次性嵌入式运行会请求运行结束清理；此 TTL 是长生命周期会话和未来调用方的兜底。 +- `mcp.*` 下的更改会通过释放缓存的会话 MCP 运行时来热应用。 + 下一次工具发现/使用会从新配置重新创建它们，因此移除的 + `mcp.servers` 条目会立即被回收，而不是等待空闲 TTL。 -请参阅 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 [CLI 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays)了解运行时行为。 +请参阅 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 +[CLI 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays) 了解运行时行为。 ## Skills @@ -129,12 +152,13 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，由嵌入式 Pi } ``` -- `allowBundled`：可选允许列表，仅适用于内置 Skills（不影响托管/工作区 Skills）。 -- `load.extraDirs`：额外共享技能根目录（最低优先级）。 -- `install.preferBrew`：为 true 时，如果 `brew` 可用，会优先使用 Homebrew 安装器，再回退到其他安装器类型。 -- `install.nodeManager`：`metadata.openclaw.install` 规格的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false` 会禁用某个 skill，即使它已内置/安装。 -- `entries..apiKey`：为声明主环境变量的 Skills 提供的便捷项（明文字符串或 SecretRef 对象）。 +- `allowBundled`：仅用于内置 Skills 的可选允许列表（不影响托管/工作区 Skills）。 +- `load.extraDirs`：额外的共享 Skills 根目录（最低优先级）。 +- `install.preferBrew`：为 true 时，如果 `brew` 可用，会优先使用 Homebrew 安装器，然后再回退到其他安装器类型。 +- `install.nodeManager`：用于 `metadata.openclaw.install` + 规范的节点安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false` 会禁用某个 Skill，即使它是内置/已安装的。 +- `entries..apiKey`：用于声明主环境变量的 Skills 的便捷配置（明文字符串或 SecretRef 对象）。 --- @@ -145,6 +169,7 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，由嵌入式 Pi plugins: { enabled: true, allow: ["voice-call"], + bundledDiscovery: "allowlist", deny: [], load: { paths: ["~/Projects/oss/voice-call-plugin"], @@ -162,54 +187,58 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，由嵌入式 Pi } ``` -- 从 `~/.openclaw/extensions`、`/.openclaw/extensions`，以及 `plugins.load.paths` 加载。 -- 设备发现会接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括没有清单的 Claude 默认布局 bundle。 -- **配置变更需要重启 Gateway 网关。** +- 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 +- 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex 包和 Claude 包，包括无清单的 Claude 默认布局包。 +- **配置更改需要重启 Gateway 网关。** - `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 +- `bundledDiscovery`：新配置默认值为 `"allowlist"`，因此非空的 + `plugins.allow` 也会门控内置提供商插件，包括 Web 搜索 + 运行时提供商。Doctor 会为迁移的旧版允许列表配置写入 `"compat"`， + 以便在你选择加入前保留现有的内置提供商行为。 - `plugins.entries..apiKey`：插件级 API key 便捷字段（当插件支持时）。 -- `plugins.entries..env`：插件作用域环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会改变提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子，以及受支持的 bundle 提供的钩子目录。 -- `plugins.entries..hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可以从类型化钩子读取原始对话内容，例如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`。 -- `plugins.entries..subagent.allowModelOverride`：明确信任此插件为后台 subagent 运行请求每次运行的 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任 subagent 覆盖的标准 `provider/model` 目标可选允许列表。仅在你有意允许任意模型时使用 `"*"`。 +- `plugins.entries..env`：插件作用域的环境变量映射。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子和受支持的包提供钩子目录。 +- `plugins.entries..hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可以从类型化钩子（如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end`）读取原始对话内容。 +- `plugins.entries..subagent.allowModelOverride`：显式信任此插件，使其可为后台子智能体运行请求每次运行的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖的规范 `provider/model` 目标的可选允许列表。只有在你有意允许任意模型时才使用 `"*"`。 - `plugins.entries..config`：插件定义的配置对象（可用时由原生 OpenClaw 插件 schema 验证）。 -- 渠道插件账号/运行时设置位于 `channels.` 下，应由所属插件清单的 `channelConfigs` 元数据描述，而不是由中央 OpenClaw 选项注册表描述。 -- `plugins.entries.firecrawl.config.webFetch`：Firecrawl 网页抓取提供商设置。 - - `apiKey`：Firecrawl API key（接受 SecretRef）。回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey`，或 `FIRECRAWL_API_KEY` 环境变量。 +- 渠道插件账号/运行时设置位于 `channels.` 下，应由拥有该渠道的插件清单 `channelConfigs` 元数据描述，而不是由中央 OpenClaw 选项注册表描述。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl Web 抓取提供商设置。 + - `apiKey`：Firecrawl API key（接受 SecretRef）。回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 - `baseUrl`：Firecrawl API 基础 URL（默认：`https://api.firecrawl.dev`；自托管覆盖必须指向私有/内部端点）。 - `onlyMainContent`：仅提取页面主内容（默认：`true`）。 - - `maxAgeMs`：最大缓存年龄，单位为毫秒（默认：`172800000` / 2 天）。 + - `maxAgeMs`：最大缓存时长，单位为毫秒（默认：`172800000` / 2 天）。 - `timeoutSeconds`：抓取请求超时，单位为秒（默认：`60`）。 - `plugins.entries.xai.config.xSearch`：xAI X Search（Grok Web 搜索）设置。 - `enabled`：启用 X Search 提供商。 - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`：记忆 dreaming 设置。有关阶段和阈值，请参阅 [Dreaming](/zh-CN/concepts/dreaming)。 - - `enabled`：主 dreaming 开关（默认 `false`）。 - - `frequency`：每次完整 dreaming 扫描的 cron 节奏（默认为 `"0 3 * * *"`）。 - - `model`：可选的 Dream Diary subagent 模型覆盖。需要 `plugins.entries.memory-core.subagent.allowModelOverride: true`；与 `allowedModels` 搭配可限制目标。模型不可用错误会使用会话默认模型重试一次；信任或允许列表失败不会静默回退。 +- `plugins.entries.memory-core.config.dreaming`：记忆 Dreaming 设置。请参阅 [Dreaming](/zh-CN/concepts/dreaming) 了解阶段和阈值。 + - `enabled`：主 Dreaming 开关（默认 `false`）。 + - `frequency`：每次完整 Dreaming 扫描的 cron 频率（默认为 `"0 3 * * *"`）。 + - `model`：可选的 Dream Diary 子智能体模型覆盖。需要 `plugins.entries.memory-core.subagent.allowModelOverride: true`；与 `allowedModels` 搭配使用以限制目标。模型不可用错误会使用会话默认模型重试一次；信任或允许列表失败不会静默回退。 - 阶段策略和阈值是实现细节（不是面向用户的配置键）。 -- 完整记忆配置位于[记忆配置参考](/zh-CN/reference/memory-config)： +- 完整记忆配置位于 [记忆配置参考](/zh-CN/reference/memory-config)： - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 已启用的 Claude bundle 插件也可以从 `settings.json` 贡献嵌入式 Pi 默认值；OpenClaw 会将这些值作为经过清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 -- `plugins.slots.memory`：选择活跃的记忆插件 ID，或使用 `"none"` 禁用记忆插件。 -- `plugins.slots.contextEngine`：选择活跃的上下文引擎插件 ID；除非你安装并选择另一个引擎，否则默认是 `"legacy"`。 +- 已启用的 Claude 包插件还可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将这些值作为经过清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。 +- `plugins.slots.memory`：选择活动记忆插件 ID，或使用 `"none"` 禁用记忆插件。 +- `plugins.slots.contextEngine`：选择活动上下文引擎插件 ID；默认为 `"legacy"`，除非你安装并选择了另一个引擎。 -请参阅[插件](/zh-CN/tools/plugin)。 +请参阅 [插件](/zh-CN/tools/plugin)。 --- ## 跟进承诺 -`commitments` 控制推断出的后续跟进记忆：OpenClaw 可以从对话轮次中检测 check-in，并通过 Heartbeat 运行投递它们。 +`commitments` 控制推断式跟进记忆：OpenClaw 可以从对话轮次中检测 check-in，并通过 heartbeat 运行投递它们。 -- `commitments.enabled`：启用隐藏 LLM 提取、存储，以及通过 Heartbeat 投递推断式跟进承诺。默认值：`false`。 -- `commitments.maxPerDay`：滚动一天内，每个智能体会话最多投递的推断式跟进承诺数量。默认值：`3`。 +- `commitments.enabled`：为推断式跟进承诺启用隐藏 LLM 提取、存储和 heartbeat 投递。默认值：`false`。 +- `commitments.maxPerDay`：每个智能体会话在滚动一天内投递的最大推断式跟进承诺数量。默认值：`3`。 -请参阅[推断式跟进承诺](/zh-CN/concepts/commitments)。 +请参阅 [推断式跟进承诺](/zh-CN/concepts/commitments)。 --- @@ -260,30 +289,30 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，由嵌入式 Pi ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- `tabCleanup` 会在空闲时间过后，或会话超过上限时，回收已跟踪的主智能体标签页。设置 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 可禁用对应的单项清理模式。 -- 未设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork` 时它处于禁用状态，因此浏览器导航默认保持严格。 -- 只有在你有意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP profile 端点（`profiles.*.cdpUrl`）在可达性和发现检查期间也会受到同样的私有网络阻止限制。 +- `tabCleanup` 会在空闲时间后，或当某个会话超过上限时，回收已跟踪的主智能体标签页。设置 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 可禁用对应的单项清理模式。 +- 未设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork` 时它会被禁用，因此浏览器导航默认保持严格。 +- 只有在你明确信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 +- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到相同的私有网络阻止限制。 - `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 - 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 配置显式例外。 -- 远程 profile 仅支持附加（禁用启动/停止/重置）。 -- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)；当你的提供商给你直接的 DevTools WebSocket URL 时使用 WS(S)。 -- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程和 `attachOnly` CDP 可达性，以及标签页打开请求。托管的 loopback profile 保留本地 CDP 默认值。 -- 如果外部托管的 CDP 服务可通过 loopback 访问，请将该 profile 的 `attachOnly: true` 设为 true；否则 OpenClaw 会把该 loopback 端口视为本地托管的浏览器 profile，并可能报告本地端口所有权错误。 -- `existing-session` profile 使用 Chrome MCP 而不是 CDP，并且可以在选定主机上或通过已连接的浏览器节点附加。 -- `existing-session` profile 可以设置 `userDataDir` 来定位特定的基于 Chromium 的浏览器 profile，例如 Brave 或 Edge。 -- `existing-session` profile 保留当前 Chrome MCP 路由限制：基于快照/引用驱动的操作，而不是 CSS 选择器目标定位；单文件上传钩子；没有对话框超时覆盖；没有 `wait --load networkidle`；也没有 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地托管的 `openclaw` profile 会自动分配 `cdpPort` 和 `cdpUrl`；只应为远程 CDP 显式设置 `cdpUrl`。 -- 本地托管的 profile 可以设置 `executablePath`，以便为该 profile 覆盖全局 `browser.executablePath`。用它可以让一个 profile 运行在 Chrome 中，另一个运行在 Brave 中。 -- 本地托管的 profile 在进程启动后，会使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP 发现，并使用 `browser.localCdpReadyTimeoutMs` 等待启动后的 CDP websocket 就绪。在较慢的主机上，如果 Chrome 能成功启动但就绪检查与启动过程发生竞态，请调高这些值。两个值都必须是最大为 `120000` 毫秒的正整数；无效配置值会被拒绝。 +- 远程配置文件仅支持附加（禁用启动/停止/重置）。 +- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)；当你的提供商提供直接的 DevTools WebSocket URL 时使用 WS(S)。 +- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程和 `attachOnly` CDP 可达性以及打开标签页请求。托管的 loopback 配置文件保留本地 CDP 默认值。 +- 如果外部托管的 CDP 服务可通过 loopback 访问，请将该配置文件的 `attachOnly: true`；否则 OpenClaw 会把该 loopback 端口视为本地托管浏览器配置文件，并可能报告本地端口所有权错误。 +- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以在所选主机上附加，或通过已连接的浏览器节点附加。 +- `existing-session` 配置文件可以设置 `userDataDir`，以定位特定的基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。 +- `existing-session` 配置文件保留当前 Chrome MCP 路由限制：使用基于 snapshot/ref 的操作而不是 CSS 选择器定位、单文件上传钩子、无对话框超时覆盖、无 `wait --load networkidle`，并且无 `responsebody`、PDF 导出、下载拦截或批处理操作。 +- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；只有远程 CDP 才需要显式设置 `cdpUrl`。 +- 本地托管配置文件可以设置 `executablePath`，以覆盖该配置文件的全局 `browser.executablePath`。可用它让一个配置文件运行在 Chrome 中，另一个运行在 Brave 中。 +- 本地托管配置文件在进程启动后使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP 发现，并使用 `browser.localCdpReadyTimeoutMs` 等待启动后的 CDP websocket 就绪。在较慢主机上，如果 Chrome 启动成功但就绪检查与启动过程竞争，请调高这些值。两个值都必须是最大为 `120000` 毫秒的正整数；无效配置值会被拒绝。 - 自动检测顺序：默认浏览器（如果基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 -- `browser.executablePath` 和 `browser.profiles..executablePath` 在 Chromium 启动前，都接受用 `~` 和 `~/...` 表示你的操作系统主目录。`existing-session` profile 中按 profile 配置的 `userDataDir` 也会展开波浪号。 -- 控制服务：仅 loopback（端口派生自 `gateway.port`，默认为 `18791`）。 +- `browser.executablePath` 和 `browser.profiles..executablePath` 都接受 `~` 和 `~/...`，并会在 Chromium 启动前解析为你的操作系统主目录。`existing-session` 配置文件中的按配置文件 `userDataDir` 也会展开波浪号。 +- 控制服务：仅 loopback（端口派生自 `gateway.port`，默认值为 `18791`）。 - `extraArgs` 会向本地 Chromium 启动追加额外启动标志（例如 `--disable-gpu`、窗口尺寸或调试标志）。 --- -## 界面 +## UI ```json5 { @@ -297,7 +326,7 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，由嵌入式 Pi } ``` -- `seamColor`：原生应用 UI 外观的强调色（Talk Mode 气泡色调等）。 +- `seamColor`：原生应用 UI chrome 的强调色（Talk Mode 气泡色调等）。 - `assistant`：Control UI 身份覆盖。回退到活跃智能体身份。 --- @@ -376,52 +405,52 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，由嵌入式 Pi -- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关拒绝启动。 -- `port`：WS + HTTP 的单个多路复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 +- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。 +- `port`：用于 WS + HTTP 的单个多路复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。 - **旧版绑定别名**：在 `gateway.bind` 中使用绑定模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 注意事项**：默认的 `loopback` 绑定会监听容器内的 `127.0.0.1`。使用 Docker 桥接网络（`-p 18789:18789`）时，流量从 `eth0` 到达，因此 Gateway 网关无法访问。使用 `--network host`，或设置 `bind: "lan"`（或设置 `bind: "custom"` 并使用 `customBindHost: "0.0.0.0"`）以监听所有接口。 -- **认证**：默认必需。非 loopback 绑定需要 Gateway 网关认证。实践中，这意味着使用共享 token/密码，或使用带身份感知能力的反向代理并设置 `gateway.auth.mode: "trusted-proxy"`。新手引导向导默认会生成 token。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRefs），请将 `gateway.auth.mode` 显式设置为 `token` 或 `password`。当两者都已配置且未设置模式时，启动以及服务安装/修复流程会失败。 -- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的 local loopback 设置；新手引导提示会有意不提供此选项。 +- **Docker 注意事项**：默认 `loopback` 绑定会在容器内监听 `127.0.0.1`。使用 Docker 桥接网络（`-p 18789:18789`）时，流量会从 `eth0` 到达，因此 Gateway 网关无法访问。使用 `--network host`，或设置 `bind: "lan"`（或使用 `bind: "custom"` 并设置 `customBindHost: "0.0.0.0"`）以监听所有接口。 +- **认证**：默认必需。非 loopback 绑定需要 Gateway 网关认证。实践中，这意味着需要共享令牌/密码，或使用带身份感知能力的反向代理并设置 `gateway.auth.mode: "trusted-proxy"`。新手引导向导默认会生成令牌。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRefs），请将 `gateway.auth.mode` 显式设置为 `token` 或 `password`。两者都已配置而模式未设置时，启动以及服务安装/修复流程会失败。 +- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的 local loopback 设置；新手引导提示有意不提供此选项。 - `gateway.auth.mode: "trusted-proxy"`：将浏览器/用户认证委托给带身份感知能力的反向代理，并信任来自 `gateway.trustedProxies` 的身份标头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式默认预期代理来源为**非 loopback**；同主机 loopback 反向代理需要显式设置 `gateway.auth.trustedProxy.allowLoopback = true`。内部同主机调用方可以使用 `gateway.auth.password` 作为本地直连回退；`gateway.auth.token` 仍然与 trusted-proxy 模式互斥。 -- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份标头可以满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 标头认证；它们改为遵循 Gateway 网关的普通 HTTP 认证模式。此无 token 流程假定 Gateway 网关主机受信任。当 `tailscale.mode = "serve"` 时默认为 `true`。 -- `gateway.auth.rateLimit`：可选的认证失败限制器。按客户端 IP 和认证作用域应用（shared-secret 和 device-token 会独立跟踪）。被阻止的尝试返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败前串行化。因此，来自同一客户端的并发错误尝试可能会在第二个请求时触发限制器，而不是都作为普通不匹配竞争通过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；当你有意也想对 localhost 流量进行限速时（用于测试设置或严格代理部署），请设置为 `false`。 -- 浏览器来源的 WS 认证尝试始终会被节流，并禁用 loopback 豁免（针对基于浏览器的 localhost 暴力破解提供纵深防御）。 -- 在 loopback 上，这些浏览器来源的锁定会按规范化后的 `Origin` +- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份标头可以满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 标头认证；它们会改用 Gateway 网关的正常 HTTP 认证模式。此无令牌流程假定 Gateway 网关主机是受信任的。当 `tailscale.mode = "serve"` 时默认为 `true`。 +- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域应用（shared-secret 和 device-token 会分别跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 + - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败前被串行化。因此，来自同一客户端的并发错误尝试可能会在第二个请求时触发限流器，而不是两个请求都以普通不匹配的形式竞态通过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；当你有意也希望对 localhost 流量限流时（用于测试设置或严格代理部署），将其设置为 `false`。 +- 浏览器来源的 WS 认证尝试始终会被限流，并禁用 loopback 豁免（纵深防御，防止基于浏览器的 localhost 暴力破解）。 +- 在 loopback 上，这些浏览器来源锁定会按规范化后的 `Origin` 值隔离，因此来自一个 localhost 来源的重复失败不会自动 锁定另一个来源。 - `tailscale.mode`：`serve`（仅 tailnet，loopback 绑定）或 `funnel`（公开，需要认证）。 - `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当预期浏览器客户端来自非 loopback 来源时必需。 -- `controlUi.chatMessageMaxWidth`：分组 Control UI 聊天消息的可选最大宽度。接受受约束的 CSS 宽度值，例如 `960px`、`82%`、`min(1280px, 82%)` 和 `calc(100% - 2rem)`。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 标头来源策略的部署启用 Host 标头来源回退。 +- `controlUi.chatMessageMaxWidth`：分组 Control UI 聊天消息的可选最大宽度。接受受限 CSS 宽度值，例如 `960px`、`82%`、`min(1280px, 82%)` 和 `calc(100% - 2rem)`。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，会为有意依赖 Host 标头来源策略的部署启用 Host 标头来源回退。 - `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境的 - break-glass 覆盖，允许明文 `ws://` 连接到受信任的私有网络 - IP；默认明文仍仅限 loopback。没有对应的 `openclaw.json` +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境中的 + break-glass 覆盖项，允许明文 `ws://` 连接到受信任的私有网络 + IP；默认仍然仅允许明文连接到 loopback。没有等效的 `openclaw.json` 配置，并且 `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - 等浏览器私有网络配置不会影响 Gateway 网关 - WebSocket 客户端。 -- `gateway.remote.token` / `.password` 是远程客户端凭据字段。它们本身不会配置 Gateway 网关认证。 -- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在向 Gateway 网关发布 relay-backed registrations 后使用的外部 APNs 中继的基础 HTTPS URL。此 URL 必须与编译进 iOS 构建的中继 URL 匹配。 -- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到中继的发送超时，单位为毫秒。默认为 `10000`。 -- relay-backed registrations 会委托给特定的 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在中继注册中包含该身份，并向 Gateway 网关转发一个注册作用域的发送授权。另一个 Gateway 网关无法复用该已存储的注册。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上面中继配置的临时环境变量覆盖。 + 等浏览器私有网络配置不会影响 Gateway 网关 WebSocket + 客户端。 +- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 +- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在向 Gateway 网关发布基于中继的注册后所使用的外部 APNs 中继的基础 HTTPS URL。此 URL 必须匹配编译进 iOS 构建的中继 URL。 +- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到中继的发送超时，单位为毫秒。默认值为 `10000`。 +- 基于中继的注册会委托给特定 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在中继注册中包含该身份，并将注册作用域的发送授权转发给 Gateway 网关。另一个 Gateway 网关无法复用该已存储注册。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述中继配置的临时环境变量覆盖项。 - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅限开发使用的逃生口，用于 loopback HTTP 中继 URL。生产中继 URL 应保持使用 HTTPS。 -- `gateway.handshakeTimeoutMs`：认证前 Gateway 网关 WebSocket 握手超时，单位为毫秒。默认：`15000`。设置后，`OPENCLAW_HANDSHAKE_TIMEOUT_MS` 优先。对于负载较高或低功耗的主机，如果本地客户端能连接但启动预热仍在稳定中，请增大此值。 -- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔，单位为分钟。设置为 `0` 可全局禁用健康监控重启。默认：`5`。 -- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值，单位为分钟。保持此值大于或等于 `gateway.channelHealthCheckMinutes`。默认：`30`。 -- `gateway.channelMaxRestartsPerHour`：每个渠道/账户在滚动一小时内的最大健康监控重启次数。默认：`10`。 -- `channels..healthMonitor.enabled`：按渠道选择退出健康监控重启，同时保持全局监控启用。 -- `channels..accounts..healthMonitor.enabled`：多账户渠道的按账户覆盖。设置后，它优先于渠道级覆盖。 -- 只有在未设置 `gateway.auth.*` 时，本地 Gateway 网关调用路径才能使用 `gateway.remote.*` 作为回退。 -- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 且未解析，解析会以关闭方式失败（不会用远程回退掩盖）。 -- `trustedProxies`：终止 TLS 或注入转发客户端标头的反向代理 IP。只列出你控制的代理。loopback 条目对于同主机代理/本地检测设置仍然有效（例如 Tailscale Serve 或本地反向代理），但它们**不会**让 loopback 请求有资格使用 `gateway.auth.mode: "trusted-proxy"`。 -- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认 `false` 以实现失败关闭行为。 -- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR/IP 允许列表，用于自动批准首次节点设备配对且无请求作用域的情况。未设置时禁用。这不会自动批准 operator/browser/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。 -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和平台允许列表评估之后，对已声明节点命令进行全局允许/拒绝塑形。使用 `allowCommands` 选择启用危险节点命令，例如 `camera.snap`、`camera.clip` 和 `screen.record`；即使平台默认值或显式允许本来会包含某个命令，`denyCommands` 也会移除它。节点更改其声明的命令列表后，请拒绝并重新批准该设备配对，以便 Gateway 网关存储更新后的命令快照。 +- `gateway.handshakeTimeoutMs`：认证前 Gateway 网关 WebSocket 握手超时，单位为毫秒。默认值：`15000`。设置后，`OPENCLAW_HANDSHAKE_TIMEOUT_MS` 优先级更高。对于负载较高或低功耗主机，本地客户端可能在启动预热尚未稳定时连接，可增大此值。 +- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔，单位为分钟。设置为 `0` 可全局禁用健康监控重启。默认值：`5`。 +- `gateway.channelStaleEventThresholdMinutes`：陈旧套接字阈值，单位为分钟。保持该值大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 +- `gateway.channelMaxRestartsPerHour`：每个渠道/账号在滚动一小时内的最大健康监控重启次数。默认值：`10`。 +- `channels..healthMonitor.enabled`：每个渠道的健康监控重启退出开关，同时保持全局监控启用。 +- `channels..accounts..healthMonitor.enabled`：多账号渠道的每账号覆盖项。设置后，其优先级高于渠道级覆盖项。 +- 只有在未设置 `gateway.auth.*` 时，本地 Gateway 网关调用路径才可以使用 `gateway.remote.*` 作为回退。 +- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 且未解析，解析会失败关闭（不会被远程回退掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端标头的反向代理 IP。只列出你控制的代理。loopback 条目对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**让 loopback 请求具备使用 `gateway.auth.mode: "trusted-proxy"` 的资格。 +- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，用于失败关闭行为。 +- `gateway.nodes.pairing.autoApproveCidrs`：可选 CIDR/IP 允许列表，用于自动批准没有请求作用域的首次节点设备配对。未设置时禁用。它不会自动批准操作员/浏览器/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。 +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：配对和平台允许列表评估后，对已声明节点命令进行全局允许/拒绝塑形。使用 `allowCommands` 来选择启用危险节点命令，例如 `camera.snap`、`camera.clip` 和 `screen.record`；即使平台默认值或显式允许本会包含某个命令，`denyCommands` 也会移除该命令。节点更改其已声明命令列表后，请拒绝并重新批准该设备配对，以便 Gateway 网关存储更新后的命令快照。 - `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 阻止的额外工具名称（扩展默认拒绝列表）。 - `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。 @@ -431,14 +460,14 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，由嵌入式 Pi - Chat Completions：默认禁用。使用 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 - Responses API：`gateway.http.endpoints.responses.enabled`。 -- Responses URL 输入加固： +- Responses URL 输入强化： - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` 空允许列表会被视为未设置；使用 `gateway.http.endpoints.responses.files.allowUrl=false` - 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 禁用 URL 获取。 -- 可选响应加固标头： - - `gateway.http.securityHeaders.strictTransportSecurity`（仅为你控制的 HTTPS 来源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） + 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 可禁用 URL 获取。 +- 可选响应强化标头： + - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 来源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 @@ -452,7 +481,7 @@ openclaw gateway --port 19001 便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile `（使用 `~/.openclaw-`）。 -参见 [Multiple Gateways](/zh-CN/gateway/multiple-gateways)。 +参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 ### `gateway.tls` @@ -470,11 +499,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS/WSS）（默认：`false`）。 -- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书/密钥对；仅用于本地/开发。 +- `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS/WSS）（默认值：`false`）。 +- `autoGenerate`：未配置显式文件时，自动生成本地自签名证书/密钥对；仅用于本地/开发。 - `certPath`：TLS 证书文件的文件系统路径。 - `keyPath`：TLS 私钥文件的文件系统路径；请保持权限受限。 -- `caPath`：用于客户端验证或自定义信任链的可选 CA bundle 路径。 +- `caPath`：用于客户端验证或自定义信任链的可选 CA 捆绑包路径。 ### `gateway.reload` @@ -490,13 +519,13 @@ openclaw gateway --port 19001 } ``` -- `mode`：控制配置编辑如何在运行时应用。 +- `mode`：控制运行时如何应用配置编辑。 - `"off"`：忽略实时编辑；更改需要显式重启。 - `"restart"`：配置更改时始终重启 Gateway 网关进程。 - - `"hot"`：在进程内应用更改，无需重启。 - - `"hybrid"`（默认）：先尝试热重载；如有必要则回退到重启。 -- `debounceMs`：应用配置更改前的防抖窗口，单位为 ms（非负整数）。 -- `deferralTimeoutMs`：可选的最大等待时间，单位为 ms，用于在强制重启前等待进行中的操作。省略时使用默认有界等待（`300000`）；设置为 `0` 表示无限期等待，并定期记录仍有待处理操作的警告。 + - `"hot"`：在进程内应用更改而不重启。 + - `"hybrid"`（默认）：先尝试热重载；如有需要则回退到重启。 +- `debounceMs`：应用配置更改前的防抖窗口，单位为毫秒（非负整数）。 +- `deferralTimeoutMs`：在强制重启前等待进行中操作的可选最大时间，单位为毫秒。省略时使用默认有界等待（`300000`）；设置为 `0` 表示无限等待并定期记录仍有待处理的警告。 --- @@ -534,47 +563,47 @@ openclaw gateway --port 19001 ``` 认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 -查询字符串中的 hook 令牌会被拒绝。 +查询字符串中的钩子令牌会被拒绝。 验证和安全注意事项： - `hooks.enabled=true` 需要非空的 `hooks.token`。 -- `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关令牌会被拒绝。 +- `hooks.token` 必须与 `gateway.auth.token` **不同**；重复使用 Gateway 网关令牌会被拒绝。 - `hooks.path` 不能是 `/`；请使用专用子路径，例如 `/hooks`。 -- 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 -- 如果映射或预设使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该选择启用。 +- 如果 `hooks.allowRequestSessionKey=true`，请限制 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 +- 如果映射或预设使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该选择加入。 **端点：** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - 只有当 `hooks.allowRequestSessionKey=true`（默认值：`false`）时，才接受请求载荷中的 `sessionKey`。 + - 只有当 `hooks.allowRequestSessionKey=true`（默认值：`false`）时，才接受请求负载中的 `sessionKey`。 - `POST /hooks/` → 通过 `hooks.mappings` 解析 - - 模板渲染得到的映射 `sessionKey` 值会被视为外部提供，也需要 `hooks.allowRequestSessionKey=true`。 + - 模板渲染的映射 `sessionKey` 值会被视为外部提供，也需要 `hooks.allowRequestSessionKey=true`。 -- `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 -- `match.source` 为通用路径匹配载荷字段。 -- 像 `{{messages[0].subject}}` 这样的模板会从载荷读取。 -- `transform` 可以指向一个返回 hook 操作的 JS/TS 模块。 - - `transform.module` 必须是相对路径，并且保留在 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。 - - 将 `hooks.transformsDir` 保持在 `~/.openclaw/hooks/transforms` 下；工作区 Skills 目录会被拒绝。如果 `openclaw doctor` 报告此路径无效，请将 transform 模块移入 hooks transforms 目录，或移除 `hooks.transformsDir`。 +- `match.path` 匹配 `/hooks` 后的子路径（例如 `/hooks/gmail` → `gmail`）。 +- `match.source` 匹配通用路径的负载字段。 +- 类似 `{{messages[0].subject}}` 的模板会从负载读取。 +- `transform` 可以指向返回钩子动作的 JS/TS 模块。 + - `transform.module` 必须是相对路径，并且保留在 `hooks.transformsDir` 内（绝对路径和目录遍历会被拒绝）。 + - 将 `hooks.transformsDir` 保持在 `~/.openclaw/hooks/transforms` 下；工作区 Skills 目录会被拒绝。如果 `openclaw doctor` 报告此路径无效，请将转换模块移动到钩子转换目录中，或移除 `hooks.transformsDir`。 - `agentId` 路由到特定智能体；未知 ID 会回退到默认值。 -- `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。 -- `defaultSessionKey`：没有显式 `sessionKey` 的 hook 智能体运行使用的可选固定会话键。 +- `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 拒绝全部）。 +- `defaultSessionKey`：用于没有显式 `sessionKey` 的钩子智能体运行的可选固定会话键。 - `allowRequestSessionKey`：允许 `/hooks/agent` 调用方和模板驱动的映射会话键设置 `sessionKey`（默认值：`false`）。 -- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或预设使用模板化的 `sessionKey` 时，它会成为必需项。 -- `deliver: true` 将最终回复发送到渠道；`channel` 默认为 `last`。 -- `model` 会覆盖此次 hook 运行的 LLM（如果设置了模型目录，则必须被允许）。 +- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或预设使用模板化的 `sessionKey` 时，它会变为必需。 +- `deliver: true` 会将最终回复发送到渠道；`channel` 默认值为 `last`。 +- `model` 会为此次钩子运行覆盖 LLM（如果设置了模型目录，则必须被允许）。 ### Gmail 集成 - 内置 Gmail 预设使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 -- 如果保留这种按消息路由，请设置 `hooks.allowRequestSessionKey: true`，并约束 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 -- 如果需要 `hooks.allowRequestSessionKey: false`，请使用静态 `sessionKey` 覆盖该预设，而不是使用模板化默认值。 +- 如果保留这种按消息路由，请设置 `hooks.allowRequestSessionKey: true`，并限制 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 +- 如果需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖预设，而不是使用模板化默认值。 ```json5 { @@ -602,7 +631,7 @@ openclaw gateway --port 19001 --- -## Canvas host +## Canvas 主机 ```json5 { @@ -614,13 +643,13 @@ openclaw gateway --port 19001 } ``` -- 在 Gateway 网关端口下通过 HTTP 提供智能体可编辑的 HTML/CSS/JS 和 A2UI： +- 通过 Gateway 网关端口下的 HTTP 提供智能体可编辑的 HTML/CSS/JS 和 A2UI： - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- 仅本地：保持 `gateway.bind: "loopback"`（默认值）。 -- 非 loopback 绑定：canvas 路由需要 Gateway 网关认证（令牌/密码/可信代理），与其他 Gateway 网关 HTTP 表面相同。 -- Node WebViews 通常不会发送认证标头；节点配对并连接后，Gateway 网关会公布节点作用域的能力 URL，用于访问 canvas/A2UI。 -- 能力 URL 绑定到活跃节点 WS 会话，并会很快过期。不使用基于 IP 的回退。 +- 仅限本地：保持 `gateway.bind: "loopback"`（默认值）。 +- 非 loopback 绑定：canvas 路由需要 Gateway 网关认证（令牌/密码/受信任代理），与其他 Gateway 网关 HTTP 表面相同。 +- Node WebViews 通常不会发送认证标头；节点配对并连接后，Gateway 网关会为 canvas/A2UI 访问通告节点作用域的能力 URL。 +- 能力 URL 绑定到活动节点 WS 会话，并且很快过期。不使用基于 IP 的回退。 - 向提供的 HTML 注入实时重载客户端。 - 为空时自动创建起始 `index.html`。 - 还会在 `/__openclaw__/a2ui/` 提供 A2UI。 @@ -631,7 +660,7 @@ openclaw gateway --port 19001 ## 设备发现 -### mDNS（Bonjour） +### mDNS (Bonjour) ```json5 { @@ -644,12 +673,12 @@ openclaw gateway --port 19001 ``` - `minimal`（启用内置 `bonjour` 插件时的默认值）：从 TXT 记录中省略 `cliPath` + `sshPort`。 -- `full`：包含 `cliPath` + `sshPort`；LAN 多播广播仍要求启用内置 `bonjour` 插件。 -- `off`：在不更改插件启用状态的情况下禁止 LAN 多播广播。 -- 内置 `bonjour` 插件会在 macOS 主机上自动启动，并且在 Linux、Windows 和容器化 Gateway 网关部署上需要选择启用。 -- 当系统主机名是有效 DNS 标签时，主机名默认使用系统主机名，否则回退到 `openclaw`。可用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 +- `full`：包含 `cliPath` + `sshPort`；LAN 组播通告仍然要求启用内置 `bonjour` 插件。 +- `off`：在不更改插件启用状态的情况下抑制 LAN 组播通告。 +- 内置 `bonjour` 插件会在 macOS 主机上自动启动，并在 Linux、Windows 和容器化 Gateway 网关部署中选择加入。 +- 当系统主机名是有效 DNS 标签时，主机名默认使用系统主机名，否则回退到 `openclaw`。可使用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 -### 广域（DNS-SD） +### 广域 (DNS-SD) ```json5 { @@ -685,13 +714,13 @@ openclaw gateway --port 19001 ``` - 仅当进程环境中缺少对应键时，才会应用内联环境变量。 -- `.env` 文件：CWD `.env` + `~/.openclaw/.env`（二者都不会覆盖现有变量）。 +- `.env` 文件：CWD `.env` + `~/.openclaw/.env`（两者都不会覆盖已有变量）。 - `shellEnv`：从你的登录 shell 配置文件导入缺失的预期键名。 - 完整优先级见[环境](/zh-CN/help/environment)。 ### 环境变量替换 -在任意配置字符串中用 `${VAR_NAME}` 引用环境变量： +在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -703,14 +732,14 @@ openclaw gateway --port 19001 - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 - 缺失或为空的变量会在配置加载时抛出错误。 -- 使用 `$${VAR}` 转义为字面量 `${VAR}`。 -- 可与 `$include` 一起使用。 +- 使用 `$${VAR}` 转义，表示字面量 `${VAR}`。 +- 可与 `$include` 配合使用。 --- ## 密钥 -密钥引用是增量式的：明文值仍然可用。 +密钥引用是增量能力：明文值仍然可用。 ### `SecretRef` @@ -720,18 +749,18 @@ openclaw gateway --port 19001 { source: "env" | "file" | "exec", provider: "default", id: "..." } ``` -验证： +校验： - `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$` - `source: "env"` id 模式：`^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` id：绝对 JSON pointer（例如 `"/providers/openai/apiKey"`） +- `source: "file"` id：绝对 JSON 指针（例如 `"/providers/openai/apiKey"`） - `source: "exec"` id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `source: "exec"` id 不得包含 `.` 或 `..` 这类以斜杠分隔的路径段（例如 `a/../b` 会被拒绝） +- `source: "exec"` ids 不得包含以斜杠分隔的 `.` 或 `..` 路径段（例如 `a/../b` 会被拒绝） -### 支持的凭证表面 +### 支持的凭据作用面 -- 规范矩阵：[SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface) -- `secrets apply` 以受支持的 `openclaw.json` 凭证路径为目标。 +- 规范矩阵：[SecretRef 凭据作用面](/zh-CN/reference/secretref-credential-surface) +- `secrets apply` 目标支持的 `openclaw.json` 凭据路径。 - `auth-profiles.json` 引用包含在运行时解析和审计覆盖范围内。 ### 密钥提供商配置 @@ -765,13 +794,13 @@ openclaw gateway --port 19001 注意： - `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须是 `"value"`）。 -- 当 Windows ACL 验证不可用时，文件和 exec 提供商路径会失败关闭。仅对无法验证但可信的路径设置 `allowInsecurePath: true`。 -- `exec` 提供商要求 `command` 是绝对路径，并通过 stdin/stdout 使用协议载荷。 -- 默认情况下会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时验证解析后的目标路径。 -- 如果配置了 `trustedDirs`，受信任目录检查会应用于解析后的目标路径。 -- `exec` 子环境默认是最小环境；请用 `passEnv` 显式传入所需变量。 -- 密钥引用会在激活时解析到内存快照中，之后请求路径只读取该快照。 -- 激活期间会应用活动表面过滤：已启用表面上的未解析引用会导致启动或重载失败，而非活动表面会被跳过并给出诊断信息。 +- 当 Windows ACL 校验不可用时，文件和 exec 提供商路径会失败关闭。仅对无法校验的可信路径设置 `allowInsecurePath: true`。 +- `exec` 提供商要求绝对 `command` 路径，并通过 stdin/stdout 使用协议载荷。 +- 默认情况下，会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时校验解析后的目标路径。 +- 如果配置了 `trustedDirs`，可信目录检查会应用于解析后的目标路径。 +- 默认情况下，`exec` 子进程环境是最小化的；请使用 `passEnv` 显式传入所需变量。 +- 密钥引用会在激活时解析为内存快照，随后请求路径只读取该快照。 +- 激活期间会应用活动作用面过滤：已启用作用面上的未解析引用会导致启动/重载失败，而非活动作用面会跳过并输出诊断信息。 --- @@ -793,11 +822,11 @@ openclaw gateway --port 19001 } ``` -- 每个智能体的 profile 存储在 `/auth-profiles.json`。 -- 对于静态凭证模式，`auth-profiles.json` 支持值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 -- 旧版扁平 `auth-profiles.json` 映射（例如 `{ "provider": { "apiKey": "..." } }`）不是运行时格式；`openclaw doctor --fix` 会将它们重写为规范的 `provider:default` API-key profile，并生成 `.legacy-flat.*.bak` 备份。 -- OAuth 模式的 profile（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 -- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会将其清理。 +- 每个智能体的配置文件存储在 `/auth-profiles.json`。 +- `auth-profiles.json` 支持静态凭据模式的值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- 旧版扁平 `auth-profiles.json` 映射（例如 `{ "provider": { "apiKey": "..." } }`）不是运行时格式；`openclaw doctor --fix` 会将它们重写为规范的 `provider:default` API-key 配置文件，并创建 `.legacy-flat.*.bak` 备份。 +- OAuth 模式配置文件（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭据。 +- 静态运行时凭据来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会将其清理。 - 旧版 OAuth 从 `~/.openclaw/credentials/oauth.json` 导入。 - 见 [OAuth](/zh-CN/concepts/oauth)。 - 密钥运行时行为和 `audit/configure/apply` 工具：[密钥管理](/zh-CN/gateway/secrets)。 @@ -822,15 +851,15 @@ openclaw gateway --port 19001 } ``` -- `billingBackoffHours`：当某个 profile 因真实的账单/余额不足错误失败时，以小时为单位的基础退避时间（默认值：`5`）。即使在 `401`/`403` 响应中，明确的账单文本仍可能归入这里，但特定于提供商的文本匹配器仍限定在拥有它们的提供商范围内（例如 OpenRouter 的 `Key limit exceeded`）。可重试的 HTTP `402` 用量窗口或组织/工作区支出限制消息则仍归入 `rate_limit` 路径。 +- `billingBackoffHours`：当配置文件因真正的账单/额度不足错误失败时，以小时为单位的基础退避时间（默认：`5`）。明确的账单文本即使出现在 `401`/`403` 响应中，仍可能归入这里，但特定提供商的文本匹配器会限定在拥有它们的提供商范围内（例如 OpenRouter 的 `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或组织/工作区支出限制消息则继续走 `rate_limit` 路径。 - `billingBackoffHoursByProvider`：可选的按提供商覆盖账单退避小时数。 -- `billingMaxHours`：账单退避指数增长的小时上限（默认值：`24`）。 -- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避分钟数（默认值：`10`）。 -- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的分钟上限（默认值：`60`）。 -- `failureWindowHours`：用于退避计数器的滚动窗口小时数（默认值：`24`）。 -- `overloadedProfileRotations`：在切换到模型 fallback 之前，针对过载错误允许的最大同一提供商 auth-profile 轮换次数（默认值：`1`）。诸如 `ModelNotReadyException` 这类提供商繁忙形态会归入这里。 -- `overloadedBackoffMs`：重试过载提供商/profile 轮换前的固定延迟（默认值：`0`）。 -- `rateLimitedProfileRotations`：在切换到模型 fallback 之前，针对速率限制错误允许的最大同一提供商 auth-profile 轮换次数（默认值：`1`）。该速率限制桶包含提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 +- `billingMaxHours`：账单退避指数增长的小时数上限（默认：`24`）。 +- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避分钟数（默认：`10`）。 +- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的分钟数上限（默认：`60`）。 +- `failureWindowHours`：用于退避计数器的滚动窗口小时数（默认：`24`）。 +- `overloadedProfileRotations`：在切换到模型回退之前，过载错误允许的同一提供商认证配置文件轮换最大次数（默认：`1`）。诸如 `ModelNotReadyException` 之类的提供商繁忙形态会归入这里。 +- `overloadedBackoffMs`：在重试过载的提供商/配置文件轮换之前的固定延迟（默认：`0`）。 +- `rateLimitedProfileRotations`：在切换到模型回退之前，限流错误允许的同一提供商认证配置文件轮换最大次数（默认：`1`）。该限流桶包括提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 --- @@ -851,9 +880,9 @@ openclaw gateway --port 19001 - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 - 设置 `logging.file` 可使用稳定路径。 -- 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 -- `maxFileBytes`：轮换前活动日志文件的最大字节数（正整数；默认值：`104857600` = 100 MB）。OpenClaw 会在活动文件旁保留最多五个编号归档文件。 -- `redactSensitive` / `redactPatterns`：对控制台输出、文件日志、OTLP 日志记录和持久化会话转录文本进行尽力而为的遮蔽。`redactSensitive: "off"` 只会禁用这个通用日志/转录策略；UI/工具/诊断安全界面仍会在发出前遮蔽密钥。 +- 使用 `--verbose` 时，`consoleLevel` 会提升到 `debug`。 +- `maxFileBytes`：轮换前活动日志文件的最大字节数（正整数；默认：`104857600` = 100 MB）。OpenClaw 会在活动文件旁保留最多五个编号归档文件。 +- `redactSensitive` / `redactPatterns`：对控制台输出、文件日志、OTLP 日志记录以及持久化的会话转录文本进行尽力而为的遮蔽。`redactSensitive: "off"` 只会禁用这项通用日志/转录策略；UI/工具/诊断安全表面仍会在发出前遮蔽密钥。 --- @@ -901,25 +930,25 @@ openclaw gateway --port 19001 } ``` -- `enabled`：仪表化输出的总开关（默认值：`true`）。 -- `flags`：用于启用定向日志输出的标志字符串数组（支持类似 `"telegram.*"` 或 `"*"` 的通配符）。 -- `stuckSessionWarnMs`：用于将长时间运行的处理会话分类为 `session.long_running`、`session.stalled` 或 `session.stuck` 的无进展时长阈值，单位为 ms。回复、工具、Status、分块和 ACP 进度会重置计时器；重复的 `session.stuck` 诊断会在状态未变化时退避。 -- `otel.enabled`：启用 OpenTelemetry 导出管线（默认值：`false`）。完整配置、信号目录和隐私模型请参见 [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。 -- `otel.endpoint`：OTel 导出的采集器 URL。 -- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`：可选的特定信号 OTLP 端点。设置后，它们只会覆盖该信号的 `otel.endpoint`。 +- `enabled`：仪表输出的总开关（默认：`true`）。 +- `flags`：启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 这类通配符）。 +- `stuckSessionWarnMs`：用于将长时间运行的处理会话分类为 `session.long_running`、`session.stalled` 或 `session.stuck` 的无进展时间阈值，单位为 ms。回复、工具、状态、分块和 ACP 进度会重置计时器；重复的 `session.stuck` 诊断会在未变化时退避。 +- `otel.enabled`：启用 OpenTelemetry 导出流水线（默认：`false`）。完整配置、信号目录和隐私模型见 [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。 +- `otel.endpoint`：用于 OTel 导出的收集器 URL。 +- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`：可选的特定信号 OTLP 端点。设置后，它们只会覆盖对应信号的 `otel.endpoint`。 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 - `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据标头。 - `otel.serviceName`：资源属性的服务名称。 -- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。 -- `otel.sampleRate`：trace 采样率 `0`–`1`。 +- `otel.traces` / `otel.metrics` / `otel.logs`：启用跟踪、指标或日志导出。 +- `otel.sampleRate`：跟踪采样率 `0`–`1`。 - `otel.flushIntervalMs`：周期性遥测刷新间隔，单位为 ms。 -- `otel.captureContent`：选择加入的 OTEL span 属性原始内容捕获。默认关闭。布尔值 `true` 会捕获非系统消息/工具内容；对象形式允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。 -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：用于最新实验性 GenAI span 提供商属性的环境开关。默认情况下，span 会保留旧版 `gen_ai.system` 属性以保持兼容；GenAI metrics 使用有界语义属性。 -- `OPENCLAW_OTEL_PRELOADED=1`：用于已注册全局 OpenTelemetry SDK 的宿主的环境开关。随后 OpenClaw 会跳过插件自有的 SDK 启动/关闭，同时保持诊断监听器处于活动状态。 +- `otel.captureContent`：选择性启用 OTEL span 属性的原始内容捕获。默认关闭。布尔值 `true` 会捕获非系统消息/工具内容；对象形式允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。 +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：用于最新实验性 GenAI span 提供商属性的环境开关。默认情况下，span 会保留旧版 `gen_ai.system` 属性以保持兼容；GenAI 指标使用有界语义属性。 +- `OPENCLAW_OTEL_PRELOADED=1`：适用于已经注册全局 OpenTelemetry SDK 的宿主的环境开关。随后 OpenClaw 会跳过插件拥有的 SDK 启动/关闭，同时保持诊断监听器处于活动状态。 - `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`、`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` 和 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`：当匹配的配置键未设置时使用的特定信号端点环境变量。 -- `cacheTrace.enabled`：为嵌入式运行记录缓存 trace 快照（默认值：`false`）。 -- `cacheTrace.filePath`：缓存 trace JSONL 的输出路径（默认值：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存 trace 输出中包含的内容（全部默认值：`true`）。 +- `cacheTrace.enabled`：为嵌入式运行记录缓存跟踪快照（默认：`false`）。 +- `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含的内容（全部默认：`true`）。 --- @@ -941,12 +970,12 @@ openclaw gateway --port 19001 } ``` -- `channel`：npm/git 安装的发布渠道 — `"stable"`、`"beta"` 或 `"dev"`。 -- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认值：`true`）。 -- `auto.enabled`：为包安装启用后台自动更新（默认值：`false`）。 -- `auto.stableDelayHours`：stable 渠道自动应用前的最小延迟小时数（默认值：`6`；最大值：`168`）。 -- `auto.stableJitterHours`：stable 渠道发布扩散窗口的额外小时数（默认值：`12`；最大值：`168`）。 -- `auto.betaCheckIntervalHours`：beta 渠道检查运行频率，单位为小时（默认值：`1`；最大值：`24`）。 +- `channel`：npm/git 安装的发布渠道，取值为 `"stable"`、`"beta"` 或 `"dev"`。 +- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认：`true`）。 +- `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。 +- `auto.stableDelayHours`：稳定渠道自动应用前的最小延迟小时数（默认：`6`；最大值：`168`）。 +- `auto.stableJitterHours`：稳定渠道发布扩散的额外小时窗口（默认：`12`；最大值：`168`）。 +- `auto.betaCheckIntervalHours`：Beta 渠道检查运行的频率，单位为小时（默认：`1`；最大值：`24`）。 --- @@ -979,22 +1008,23 @@ openclaw gateway --port 19001 } ``` -- `enabled`：全局 ACP 功能门控（默认值：`true`；设置为 `false` 可隐藏 ACP dispatch 和 spawn 入口）。 -- `dispatch.enabled`：ACP 会话轮次 dispatch 的独立门控（默认值：`true`）。设置为 `false` 可在保留 ACP 命令可用的同时阻止执行。 -- `backend`：默认 ACP 运行时后端 id（必须匹配已注册的 ACP 运行时插件）。先安装后端插件；如果设置了 `plugins.allow`，请包含后端插件 id（例如 `acpx`），否则 ACP 后端不会加载。 -- `defaultAgent`：当 spawn 未指定显式目标时使用的 fallback ACP 目标智能体 id。 +- `enabled`：全局 ACP 功能门控（默认：`true`；设为 `false` 可隐藏 ACP 分发和生成入口）。 +- `dispatch.enabled`：ACP 会话轮次分发的独立门控（默认：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 +- `backend`：默认 ACP 运行时后端 id（必须匹配已注册的 ACP 运行时插件）。 + 先安装后端插件；如果设置了 `plugins.allow`，请包含后端插件 id（例如 `acpx`），否则 ACP 后端不会加载。 +- `defaultAgent`：当生成未指定显式目标时使用的后备 ACP 目标智能体 id。 - `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；为空表示没有额外限制。 -- `maxConcurrentSessions`：同时处于活动状态的 ACP 会话最大数量。 +- `maxConcurrentSessions`：并发活动 ACP 会话的最大数量。 - `stream.coalesceIdleMs`：流式文本的空闲刷新窗口，单位为 ms。 -- `stream.maxChunkChars`：拆分流式 block 投影前的最大 chunk 大小。 -- `stream.repeatSuppression`：按轮次抑制重复的 Status/工具行（默认值：`true`）。 +- `stream.maxChunkChars`：拆分流式分块投影前的最大分块大小。 +- `stream.repeatSuppression`：抑制每轮中的重复状态/工具行（默认：`true`）。 - `stream.deliveryMode`：`"live"` 会增量流式传输；`"final_only"` 会缓冲到轮次终止事件。 -- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前的分隔符（默认值：`"paragraph"`）。 +- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前的分隔符（默认：`"paragraph"`）。 - `stream.maxOutputChars`：每个 ACP 轮次投影的最大助手输出字符数。 -- `stream.maxSessionUpdateChars`：投影的 ACP Status/更新行的最大字符数。 -- `stream.tagVisibility`：标签名称到流式事件布尔可见性覆盖的记录。 -- `runtime.ttlMinutes`：ACP 会话 worker 在符合清理条件前的空闲 TTL，单位为分钟。 -- `runtime.installCommand`：引导 ACP 运行时环境时要运行的可选安装命令。 +- `stream.maxSessionUpdateChars`：投影的 ACP 状态/更新行的最大字符数。 +- `stream.tagVisibility`：标签名称到布尔可见性覆盖项的记录，用于流式事件。 +- `runtime.ttlMinutes`：ACP 会话 worker 符合清理条件前的空闲 TTL，单位为分钟。 +- `runtime.installCommand`：引导 ACP 运行时环境时可运行的可选安装命令。 --- @@ -1010,17 +1040,17 @@ openclaw gateway --port 19001 } ``` -- `cli.banner.taglineMode` 控制 banner 标语样式： +- `cli.banner.taglineMode` 控制横幅标语样式： - `"random"`（默认）：轮换的趣味/季节性标语。 - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 - - `"off"`：无标语文本（仍显示 banner 标题/版本）。 -- 若要隐藏整个 banner（不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 + - `"off"`：无标语文本（仍显示横幅标题/版本）。 +- 要隐藏整个横幅（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- ## 向导 -CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数据： +由 CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数据： ```json5 { @@ -1038,15 +1068,15 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 ## 身份 -请参见 [智能体默认值](/zh-CN/gateway/config-agents#agent-defaults) 下的 `agents.list` 身份字段。 +参见 [智能体默认值](/zh-CN/gateway/config-agents#agent-defaults) 下的 `agents.list` 身份字段。 --- -## Bridge（旧版，已移除） +## 桥接（旧版，已移除） -当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键不再属于配置架构（在移除前验证会失败；`openclaw doctor --fix` 可以剥离未知键）。 +当前构建不再包含 TCP 桥接。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键不再属于配置 schema（在移除之前验证会失败；`openclaw doctor --fix` 可以清理未知键）。 - + ```json { @@ -1066,7 +1096,7 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 --- -## Cron +## 定时任务 ```json5 { @@ -1084,11 +1114,11 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 } ``` -- `sessionRetention`：在从 `sessions.json` 中修剪之前，保留已完成的隔离 cron 运行会话的时长。也会控制已归档的已删除 cron 转录的清理。默认值：`24h`；设置为 `false` 可禁用。 -- `runLog.maxBytes`：修剪前每个运行日志文件（`cron/runs/.jsonl`）的最大大小。默认值：`2_000_000` 字节。 -- `runLog.keepLines`：触发运行日志修剪时保留的最新行数。默认值：`2000`。 -- `webhookToken`：用于 cron webhook POST 交付（`delivery.mode = "webhook"`）的 bearer token；若省略，则不发送 auth header。 -- `webhook`：已弃用的旧版 fallback webhook URL（http/https），仅用于仍带有 `notify: true` 的已存储任务。 +- `sessionRetention`：已完成的隔离定时任务运行会话在从 `sessions.json` 裁剪前保留多久。也控制已归档的已删除定时任务转录文本的清理。默认：`24h`；设为 `false` 可禁用。 +- `runLog.maxBytes`：裁剪前每个运行日志文件（`cron/runs/.jsonl`）的最大大小。默认：`2_000_000` 字节。 +- `runLog.keepLines`：触发运行日志裁剪时保留的最新行数。默认：`2000`。 +- `webhookToken`：用于定时任务 webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；如果省略，则不会发送认证标头。 +- `webhook`：已弃用的旧版后备 webhook URL（http/https），仅用于仍带有 `notify: true` 的已存储作业。 ### `cron.retry` @@ -1104,9 +1134,9 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 } ``` -- `maxAttempts`：一次性作业在暂时性错误上的最大重试次数（默认值：`3`；范围：`0`–`10`）。 -- `backoffMs`：每次重试尝试的退避延迟数组，单位为毫秒（默认值：`[30000, 60000, 300000]`；1–10 项）。 -- `retryOn`：触发重试的错误类型 — `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时重试所有暂时性类型。 +- `maxAttempts`：一次性作业在瞬时错误上的最大重试次数（默认值：`3`；范围：`0`–`10`）。 +- `backoffMs`：每次重试尝试的退避延迟数组，单位为 ms（默认值：`[30000, 60000, 300000]`；1–10 个条目）。 +- `retryOn`：触发重试的错误类型 — `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时重试所有瞬时类型。 仅适用于一次性 cron 作业。周期性作业使用单独的失败处理。 @@ -1127,12 +1157,12 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 } ``` -- `enabled`：为 cron 作业启用失败告警（默认值：`false`）。 -- `after`：触发告警前的连续失败次数（正整数，最小值：`1`）。 -- `cooldownMs`：同一作业重复告警之间的最小毫秒数（非负整数）。 -- `includeSkipped`：将连续跳过的运行计入告警阈值（默认值：`false`）。跳过的运行会单独跟踪，不影响执行错误退避。 -- `mode`：递送模式 — `"announce"` 通过渠道消息发送；`"webhook"` 发送到已配置的 webhook。 -- `accountId`：可选的账号或渠道 ID，用于限定告警递送范围。 +- `enabled`：为 cron 作业启用失败警报（默认值：`false`）。 +- `after`：警报触发前的连续失败次数（正整数，最小值：`1`）。 +- `cooldownMs`：同一作业重复警报之间的最小毫秒数（非负整数）。 +- `includeSkipped`：将连续跳过的运行计入警报阈值（默认值：`false`）。跳过的运行会单独跟踪，并且不会影响执行错误退避。 +- `mode`：投递模式 — `"announce"` 通过渠道消息发送；`"webhook"` 发布到配置的 webhook。 +- `accountId`：用于限定警报投递范围的可选账号或渠道 ID。 ### `cron.failureDestination` @@ -1149,16 +1179,16 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 } ``` -- 所有作业的 cron 失败通知默认目标。 +- 所有作业的 cron 失败通知默认目的地。 - `mode`：`"announce"` 或 `"webhook"`；当存在足够目标数据时，默认值为 `"announce"`。 -- `channel`：用于 announce 递送的渠道覆盖项。`"last"` 会复用上次已知的递送渠道。 -- `to`：显式 announce 目标或 webhook URL。webhook 模式必需。 -- `accountId`：可选的递送账号覆盖项。 -- 每个作业的 `delivery.failureDestination` 会覆盖此全局默认值。 -- 当既未设置全局失败目标，也未设置每个作业的失败目标时，已通过 `announce` 递送的作业会在失败时回退到该主要 announce 目标。 -- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 作业，除非该作业的主要 `delivery.mode` 为 `"webhook"`。 +- `channel`：announce 投递的渠道覆盖项。`"last"` 会复用最后已知的投递渠道。 +- `to`：显式 announce 目标或 webhook URL。webhook 模式必填。 +- `accountId`：可选的投递账号覆盖项。 +- 每个作业的 `delivery.failureDestination` 会覆盖这个全局默认值。 +- 当既未设置全局失败目的地，也未设置每个作业的失败目的地时，已经通过 `announce` 投递的作业会在失败时回退到该主要 announce 目标。 +- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 作业，除非该作业的主要 `delivery.mode` 是 `"webhook"`。 -参见 [Cron 作业](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)跟踪。 +参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 --- @@ -1169,10 +1199,10 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 | 变量 | 描述 | | ------------------ | ------------------------------------------------- | | `{{Body}}` | 完整的入站消息正文 | -| `{{RawBody}}` | 原始正文（无历史/发送者包装） | -| `{{BodyStripped}}` | 移除群组提及后的正文 | +| `{{RawBody}}` | 原始正文（无历史记录/发送者包装） | +| `{{BodyStripped}}` | 移除了群组提及的正文 | | `{{From}}` | 发送者标识符 | -| `{{To}}` | 目标标识符 | +| `{{To}}` | 目的地标识符 | | `{{MessageSid}}` | 渠道消息 ID | | `{{SessionId}}` | 当前会话 UUID | | `{{IsNewSession}}` | 创建新会话时为 `"true"` | @@ -1180,8 +1210,8 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 | `{{MediaPath}}` | 本地媒体路径 | | `{{MediaType}}` | 媒体类型（图像/音频/文档/…） | | `{{Transcript}}` | 音频转录文本 | -| `{{Prompt}}` | 为 CLI 条目解析后的媒体提示词 | -| `{{MaxChars}}` | 为 CLI 条目解析后的最大输出字符数 | +| `{{Prompt}}` | CLI 条目的已解析媒体提示词 | +| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 | | `{{ChatType}}` | `"direct"` 或 `"group"` | | `{{GroupSubject}}` | 群组主题（尽力获取） | | `{{GroupMembers}}` | 群组成员预览（尽力获取） | @@ -1193,7 +1223,7 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 ## 配置包含（`$include`） -将配置拆分到多个文件： +将配置拆分为多个文件： ```json5 // ~/.openclaw/openclaw.json @@ -1209,19 +1239,19 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数 **合并行为：** - 单个文件：替换包含它的对象。 -- 文件数组：按顺序深度合并（后者覆盖前者）。 -- 同级键：在包含后合并（覆盖被包含的值）。 +- 文件数组：按顺序深度合并（后面的覆盖前面的）。 +- 同级键：在包含之后合并（覆盖已包含的值）。 - 嵌套包含：最多 10 层深。 -- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录内（`openclaw.json` 的 `dirname`）。只有当绝对路径/`../` 形式仍解析到该边界内时才允许使用。 -- OpenClaw 拥有的写入如果只更改单个文件包含支持的一个顶层区段，会透传写入到该被包含文件。例如，`plugins install` 会在 `plugins.json5` 中更新 `plugins: { $include: "./plugins.json5" }`，并保持 `openclaw.json` 不变。 -- 根包含、包含数组以及带同级覆盖项的包含对于 OpenClaw 拥有的写入是只读的；这些写入会失败关闭，而不是扁平化配置。 +- 路径：相对于包含它的文件解析，但必须保留在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径/`../` 形式仍解析在该边界内时才允许使用。 +- OpenClaw 拥有的写入如果只更改由单文件包含支持的一个顶层部分，会写入该被包含文件。例如，`plugins install` 会在 `plugins.json5` 中更新 `plugins: { $include: "./plugins.json5" }`，并保持 `openclaw.json` 不变。 +- 根包含、包含数组以及带有同级覆盖项的包含，对于 OpenClaw 拥有的写入是只读的；这些写入会失败关闭，而不是扁平化配置。 - 错误：针对缺失文件、解析错误和循环包含提供清晰消息。 --- -_相关：[配置](/zh-CN/gateway/configuration) · [配置示例](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_ +_相关：[Configuration](/zh-CN/gateway/configuration) · [Configuration Examples](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_ ## 相关 -- [配置](/zh-CN/gateway/configuration) -- [配置示例](/zh-CN/gateway/configuration-examples) +- [Configuration](/zh-CN/gateway/configuration) +- [Configuration examples](/zh-CN/gateway/configuration-examples) diff --git a/docs/zh-CN/gateway/doctor.md b/docs/zh-CN/gateway/doctor.md index 274084833..7b94e31c1 100644 --- a/docs/zh-CN/gateway/doctor.md +++ b/docs/zh-CN/gateway/doctor.md @@ -6,15 +6,15 @@ sidebarTitle: Doctor summary: Doctor 命令：健康检查、配置迁移和修复步骤 title: Doctor x-i18n: - generated_at: "2026-05-04T19:04:50Z" + generated_at: "2026-05-04T22:54:31Z" model: gpt-5.5 provider: openai - source_hash: e6b18967c4a352290057afc2da95f1d6a1389f46f9d1e49ad4864baf7b77d343 + source_hash: 86d862ccc56c0d979c2a957272b2e2f5c5fc7bb1ae8142748630ede0003891de source_path: gateway/doctor.md workflow: 16 --- -`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过时的配置/状态、检查健康状况，并提供可操作的修复步骤。 +`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过期的配置/状态、检查健康状况，并提供可执行的修复步骤。 ## 快速开始 @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - 不提示并接受默认值（适用时包括重启/服务/沙箱修复步骤）。 + 不提示，直接接受默认值（适用时包括重启/服务/沙箱修复步骤）。 @@ -38,7 +38,7 @@ openclaw doctor openclaw doctor --repair ``` - 不提示并应用推荐修复（在安全的情况下执行修复 + 重启）。 + 不提示，应用推荐的修复（在安全的情况下执行修复 + 重启）。 @@ -46,7 +46,7 @@ openclaw doctor openclaw doctor --repair --force ``` - 同时应用激进修复（会覆盖自定义 supervisor 配置）。 + 同时应用更激进的修复（会覆盖自定义 supervisor 配置）。 @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - 无提示运行，并且只应用安全迁移（配置规范化 + 磁盘上的状态移动）。跳过需要人工确认的重启/服务/沙箱操作。检测到旧版状态迁移时会自动运行。 + 不显示提示运行，并且只应用安全迁移（配置规范化 + 磁盘上的状态移动）。跳过需要人工确认的重启/服务/沙箱操作。检测到旧版状态迁移时会自动运行。 @@ -62,12 +62,12 @@ openclaw doctor openclaw doctor --deep ``` - 扫描系统服务以查找额外的 Gateway 网关安装（launchd/systemd/schtasks）。 + 扫描系统服务，查找额外的 Gateway 网关安装（launchd/systemd/schtasks）。 -如果你想在写入前查看变更，请先打开配置文件： +如果你想在写入前查看更改，请先打开配置文件： ```bash cat ~/.openclaw/openclaw.json @@ -76,63 +76,63 @@ cat ~/.openclaw/openclaw.json ## 它会做什么（摘要） - - - 针对 git 安装的可选预检更新（仅交互模式）。 + + - 对 git 安装执行可选的预检更新（仅交互模式）。 - UI 协议新鲜度检查（当协议 schema 更新时重建 Control UI）。 - 健康检查 + 重启提示。 - - Skills 状态摘要（符合条件/缺失/被阻止）和插件状态。 + - Skills 状态摘要（可用/缺失/阻塞）和插件状态。 - - 旧版值的配置规范化。 - - 将旧版扁平 `talk.*` 字段迁移到 `talk.provider` + `talk.providers.` 的 Talk 配置迁移。 - - 检查旧版 Chrome 扩展配置和 Chrome MCP 就绪状态的浏览器迁移。 + - 针对旧版值的配置规范化。 + - 将旧版扁平 `talk.*` 字段迁移到 `talk.provider` + `talk.providers.`。 + - 针对旧版 Chrome 扩展配置和 Chrome MCP 就绪状态的浏览器迁移检查。 - OpenCode 提供商覆盖警告（`models.providers.opencode` / `models.providers.opencode-go`）。 - - Codex OAuth shadowing 警告（`models.providers.openai-codex`）。 + - Codex OAuth 遮蔽警告（`models.providers.openai-codex`）。 - OpenAI Codex OAuth 配置文件的 OAuth TLS 前置条件检查。 - - 当 `plugins.allow` 具有限制性但工具策略仍要求通配符或插件自有工具时，发出插件/工具 allowlist 警告。 - - 旧版磁盘状态迁移（会话/智能体目录/WhatsApp 凭证）。 + - 当 `plugins.allow` 是限制性的，但工具策略仍要求通配符或插件自有工具时，发出插件/工具允许列表警告。 + - 旧版磁盘状态迁移（会话/agent 目录/WhatsApp 凭证）。 - 旧版插件清单契约键迁移（`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`）。 - - 旧版 cron 存储迁移（`jobId`, `schedule.cron`, 顶层 delivery/payload 字段、payload `provider`、简单 `notify: true` webhook fallback 作业）。 - - 旧版智能体运行时策略迁移到 `agents.defaults.agentRuntime` 和 `agents.list[].agentRuntime`。 - - 启用插件时清理过时的插件配置；当 `plugins.enabled=false` 时，过时的插件引用会被视为惰性隔离配置并被保留。 + - 旧版 cron 存储迁移（`jobId`, `schedule.cron`, 顶层 delivery/payload 字段、payload `provider`、简单的 `notify: true` webhook 兜底任务）。 + - 旧版 agent 运行时策略迁移到 `agents.defaults.agentRuntime` 和 `agents.list[].agentRuntime`。 + - 启用插件时清理过期插件配置；当 `plugins.enabled=false` 时，过期插件引用会被视为惰性隔离配置并保留。 - - 检查会话锁文件并清理过时锁。 - - 修复受影响的 2026.4.24 构建创建的重复 prompt-rewrite 分支的会话转录。 - - 检测卡住的子智能体重启恢复 tombstone，并支持用 `--fix` 清理过时的已中止恢复标志，避免启动时继续把子进程视为 restart-aborted。 - - 状态完整性和权限检查（会话、转录、状态目录）。 + - 会话锁文件检查和过期锁清理。 + - 修复受影响的 2026.4.24 构建创建的重复 prompt-rewrite 分支会话 transcript。 + - 检测卡住的 subagent 重启恢复 tombstone，并通过 `--fix` 支持清除过期的 aborted recovery 标志，避免启动时继续将子进程视为 restart-aborted。 + - 状态完整性和权限检查（会话、transcript、状态目录）。 - 本地运行时检查配置文件权限（chmod 600）。 - - 模型认证健康状况：检查 OAuth 过期时间，可刷新即将过期的令牌，并报告 auth-profile 冷却/禁用状态。 - - 额外工作区目录检测（`~/openclaw`）。 + - 模型认证健康状况：检查 OAuth 到期时间，可以刷新即将到期的 token，并报告 auth-profile 的冷却/禁用状态。 + - 检测额外工作区目录（`~/openclaw`）。 - 启用沙箱隔离时修复沙箱镜像。 - 旧版服务迁移和额外 Gateway 网关检测。 - - Matrix 渠道旧版状态迁移（在 `--fix` / `--repair` 模式中）。 + - Matrix 渠道旧版状态迁移（在 `--fix` / `--repair` 模式下）。 - Gateway 网关运行时检查（服务已安装但未运行；缓存的 launchd 标签）。 - - 渠道状态警告（从运行中的 Gateway 网关探测）。 - - Supervisor 配置审计（launchd/systemd/schtasks），可选择修复。 - - 清理安装或更新期间捕获 shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 值的 Gateway 网关服务的嵌入式代理环境。 + - 渠道状态警告（从正在运行的 Gateway 网关探测）。 + - 带可选修复的 supervisor 配置审计（launchd/systemd/schtasks）。 + - 清理 Gateway 网关服务的嵌入式代理环境，这些服务在安装或更新期间捕获了 shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 值。 - Gateway 网关运行时最佳实践检查（Node vs Bun、版本管理器路径）。 - Gateway 网关端口冲突诊断（默认 `18789`）。 - - 开放私信策略的安全警告。 - - 本地令牌模式的 Gateway 网关认证检查（无令牌来源时提供令牌生成；不会覆盖令牌 SecretRef 配置）。 - - 设备配对问题检测（待处理的首次配对请求、待处理的角色/作用域升级、过时的本地设备令牌缓存漂移，以及 paired-record 认证漂移）。 + - 针对开放私信策略的安全警告。 + - 本地 token 模式的 Gateway 网关认证检查（当不存在 token 来源时提供 token 生成；不会覆盖 token SecretRef 配置）。 + - 设备配对问题检测（待处理的首次配对请求、待处理的角色/范围升级、过期的本地设备 token 缓存漂移，以及配对记录认证漂移）。 - Linux 上的 systemd linger 检查。 - - 工作区 bootstrap 文件大小检查（上下文文件的截断/接近限制警告）。 - - 默认智能体的 Skills 就绪状态检查；报告缺少二进制文件、环境、配置或 OS 要求的允许 Skills，并且 `--fix` 可以在 `skills.entries` 中禁用不可用 Skills。 + - 工作区 bootstrap 文件大小检查（针对上下文文件的截断/接近限制警告）。 + - 默认 agent 的 Skills 就绪状态检查；报告允许但缺少 bin、环境变量、配置或 OS 要求的技能，并且 `--fix` 可以在 `skills.entries` 中禁用不可用技能。 - Shell 补全状态检查和自动安装/升级。 - - 记忆搜索 embedding 提供商就绪状态检查（本地模型、远程 API key 或 QMD 二进制文件）。 - - 源码安装检查（pnpm workspace 不匹配、缺少 UI 资产、缺少 tsx 二进制文件）。 + - 记忆搜索 embedding 提供商就绪状态检查（本地模型、远程 API key 或 QMD 二进制）。 + - 源码安装检查（pnpm workspace 不匹配、缺少 UI assets、缺少 tsx 二进制）。 - 写入更新后的配置 + 向导元数据。 @@ -140,52 +140,52 @@ cat ~/.openclaw/openclaw.json ## Dreams UI 回填和重置 -Control UI 的 Dreams 场景包含用于 grounded dreaming 工作流的 **回填**、**重置** 和 **清除 Grounded** 操作。这些操作使用 Gateway 网关 doctor 风格的 RPC 方法，但它们**不是** `openclaw doctor` CLI 修复/迁移的一部分。 +Control UI Dreams 场景包含用于 grounded dreaming 工作流的 **回填**、**重置** 和 **清除 Grounded** 操作。这些操作使用 Gateway 网关 doctor 风格的 RPC 方法，但它们**不是** `openclaw doctor` CLI 修复/迁移的一部分。 它们会做什么： -- **回填** 会扫描当前工作区中的历史 `memory/YYYY-MM-DD.md` 文件，运行 grounded REM diary pass，并将可逆的回填条目写入 `DREAMS.md`。 -- **重置** 只会从 `DREAMS.md` 中移除那些已标记的回填日记条目。 -- **清除 Grounded** 只会移除来自历史回放、且尚未积累实时 recall 或 daily support 的暂存 grounded-only 短期条目。 +- **回填** 会扫描活动工作区中的历史 `memory/YYYY-MM-DD.md` 文件，运行 grounded REM 日记步骤，并将可逆的回填条目写入 `DREAMS.md`。 +- **重置** 只会从 `DREAMS.md` 中移除这些带标记的回填日记条目。 +- **清除 Grounded** 只会移除来自历史重放、且尚未积累 live recall 或每日支持的暂存 grounded-only 短期条目。 它们本身**不会**做什么： - 它们不会编辑 `MEMORY.md` - 它们不会运行完整的 doctor 迁移 -- 除非你先显式运行 staged CLI 路径，否则它们不会自动把 grounded candidates 暂存到实时短期 promotion store 中 +- 除非你先显式运行暂存 CLI 路径，否则它们不会自动将 grounded 候选项暂存到 live 短期提升存储中 -如果你希望 grounded 历史回放影响常规 deep promotion lane，请改用 CLI 流程： +如果你希望 grounded 历史重放影响正常的深度提升通道，请改用 CLI 流程： ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -这会将 grounded durable candidates 暂存到短期 dreaming store 中，同时让 `DREAMS.md` 保持为审阅界面。 +这会将 grounded durable 候选项暂存到短期 dreaming 存储，同时保持 `DREAMS.md` 作为审阅界面。 -## 详细行为和原因 +## 详细行为和原理 - 如果这是一个 git checkout，并且 doctor 正在交互式运行，它会在运行 doctor 前提供更新选项（fetch/rebase/build）。 + 如果这是一个 git checkout，并且 doctor 正在交互式运行，它会在运行 doctor 前提供更新（fetch/rebase/build）选项。 - 如果配置包含旧版值形状（例如没有渠道专属覆盖的 `messages.ackReaction`），doctor 会将它们规范化为当前 schema。 + 如果配置包含旧版值形状（例如没有渠道特定覆盖的 `messages.ackReaction`），doctor 会将它们规范化为当前 schema。 - 这包括旧版 Talk 扁平字段。当前公开 Talk 配置是 `talk.provider` + `talk.providers.`。Doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形状重写到提供商映射中。 + 这包括旧版 Talk 扁平字段。当前公共 Talk 配置是 `talk.provider` + `talk.providers.`。Doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形状重写到提供商映射中。 - 当 `plugins.allow` 非空且工具策略使用通配符或插件自有工具条目时，Doctor 也会发出警告。`tools.allow: ["*"]` 只匹配来自实际加载的插件的工具；它不会绕过独占插件 allowlist。 + 当 `plugins.allow` 非空且工具策略使用通配符或插件自有工具条目时，Doctor 也会发出警告。`tools.allow: ["*"]` 只匹配实际加载的插件中的工具；它不会绕过独占插件允许列表。Doctor 会为迁移后的旧版允许列表配置写入 `plugins.bundledDiscovery: "compat"`，以保留现有的内置提供商行为，然后指向更严格的 `"allowlist"` 设置。 - 当配置包含已弃用键时，其他命令会拒绝运行，并要求你运行 `openclaw doctor`。 + 当配置包含已弃用的键时，其他命令会拒绝运行，并要求你运行 `openclaw doctor`。 - Doctor 将会： + Doctor 会： - 说明发现了哪些旧版键。 - 显示它应用的迁移。 - 使用更新后的 schema 重写 `~/.openclaw/openclaw.json`。 - Gateway 网关在启动时如果检测到旧版配置格式，也会自动运行 doctor 迁移，因此过时配置无需人工干预即可修复。Cron 作业存储迁移由 `openclaw doctor --fix` 处理。 + Gateway 网关在启动时如果检测到旧版配置格式，也会自动运行 doctor 迁移，因此过期配置无需手动干预即可修复。Cron 任务存储迁移由 `openclaw doctor --fix` 处理。 当前迁移： @@ -212,284 +212,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.*`（工具/提升权限/执行/沙箱/subagents） - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - - 移除 `agents.defaults.llm`；对较慢的提供商/模型超时，请使用 `models.providers..timeoutSeconds` + - 移除 `agents.defaults.llm`；对速度较慢的提供商/模型超时，使用 `models.providers..timeoutSeconds` - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - - 移除 `browser.relayBindHost`（旧版扩展中继设置） - - 旧版 `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 网关启动时也会跳过 `api` 设置为未来或未知枚举值的提供商，而不是失败关闭） + - 移除 `browser.relayBindHost`（旧版插件中继设置） + - 旧版 `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 网关启动时也会跳过 `api` 设为未来或未知枚举值的提供商，而不是封闭失败） - Doctor 警告还包含多账户渠道的账户默认值指南： + Doctor 警告还包括多账号渠道的账号默认值指导： - - 如果配置了两个或更多 `channels..accounts` 条目，但没有配置 `channels..defaultAccount` 或 `accounts.default`，Doctor 会警告后备路由可能会选择意外账户。 - - 如果 `channels..defaultAccount` 设置为未知账户 ID，Doctor 会发出警告并列出已配置的账户 ID。 + - 如果配置了两个或更多 `channels..accounts` 条目，但没有配置 `channels..defaultAccount` 或 `accounts.default`，Doctor 会警告后备路由可能选择意外账号。 + - 如果 `channels..defaultAccount` 被设为未知账号 ID，Doctor 会警告并列出已配置的账号 ID。 - - 如果你手动添加了 `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 路由 + 成本。 - - 如果你的浏览器配置仍指向已移除的 Chrome 扩展路径，Doctor 会将其规范化为当前的主机本地 Chrome MCP 附加模型： + + 如果你的浏览器配置仍指向已移除的 Chrome 插件路径，Doctor 会将其规范化为当前的主机本地 Chrome MCP 附加模型： - - `browser.profiles.*.driver: "extension"` 变为 `"existing-session"` + - `browser.profiles.*.driver: "extension"` 会变为 `"existing-session"` - `browser.relayBindHost` 会被移除 当你使用 `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。 + 此检查**不**适用于 Docker、沙箱、远程浏览器或其他无头流程。那些流程会继续使用原始 CDP。 - - 配置 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 网关健康，也会运行该探测。 - - 如果你之前在 `models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会遮蔽较新版本自动使用的内置 Codex OAuth 提供商路径。当 Doctor 发现这些旧传输设置与 Codex OAuth 同时存在时会发出警告，以便你移除或重写过时的传输覆盖，并恢复内置路由/后备行为。仍然支持自定义代理和仅标头覆盖，并且它们不会触发此警告。 + + 如果你之前在 `models.providers.openai-codex` 下添加过旧版 OpenAI 传输设置，它们可能会遮蔽新版发布自动使用的内置 Codex OAuth 提供商路径。Doctor 在看到这些旧传输设置与 Codex OAuth 并存时会发出警告，以便你移除或改写陈旧的传输覆盖，并恢复内置路由/后备行为。自定义代理和仅标头覆盖仍受支持，并且不会触发此警告。 - - 启用内置 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 应用服务器 harness 混淆。Doctor 会发出警告，并指向显式应用服务器形态：`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 应用服务器运行嵌入式回合。” + - `/codex ...` 表示“从聊天中控制或绑定原生 Codex 对话。” + - `/acp ...` 或 `runtime: "acp"` 表示“使用外部 ACP/acpx 适配器。” - 如果出现警告，请选择你预期的路由并手动编辑配置。当 PI Codex OAuth 是有意配置时，请保持该警告不变。 + 如果出现该警告，请选择你原本想要的路由并手动编辑配置。当 PI Codex OAuth 是有意配置时，请保持该警告原样。 - + Doctor 可以将较旧的磁盘布局迁移到当前结构： - - 会话存储 + 文字记录： + - 会话存储 + 转录： - 从 `~/.openclaw/sessions/` 到 `~/.openclaw/agents//sessions/` - - 智能体目录： + - Agent 目录： - 从 `~/.openclaw/agent/` 到 `~/.openclaw/agents//agent/` - WhatsApp 凭证状态（Baileys）： - - 从旧版 `~/.openclaw/credentials/*.json`（不包括 `oauth.json`） - - 到 `~/.openclaw/credentials/whatsapp//...`（默认账户 ID：`default`） + - 从旧版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外） + - 到 `~/.openclaw/credentials/whatsapp//...`（默认账号 ID：`default`） - 这些迁移是尽力而为且幂等的；当 Doctor 留下任何旧版文件夹作为备份时，会发出警告。Gateway 网关/CLI 也会在启动时自动迁移旧版会话和智能体目录，因此历史记录/凭证/模型会进入按智能体划分的路径，而无需手动运行 Doctor。WhatsApp 凭证有意仅通过 `openclaw doctor` 迁移。Talk 提供商/提供商映射规范化现在按结构相等性比较，因此仅键顺序不同的差异不再触发重复的空操作 `doctor --fix` 变更。 + 这些迁移是尽力而为且幂等的；当 Doctor 将任何旧版文件夹作为备份留下时，会发出警告。Gateway 网关/CLI 也会在启动时自动迁移旧版会话 + Agent 目录，使历史记录/凭证/模型落入逐 Agent 路径，而无需手动运行 Doctor。WhatsApp 凭证有意只通过 `openclaw doctor` 迁移。Talk 提供商/提供商映射规范化现在按结构相等比较，因此仅键顺序不同的差异不再触发重复的空操作 `doctor --fix` 变更。 - - Doctor 会扫描所有已安装插件清单中的已弃用顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。发现后，它会提议将它们移动到 `contracts` 对象中，并就地重写清单文件。此迁移是幂等的；如果 `contracts` 键已经具有相同值，则会移除旧版键而不会复制数据。 + + Doctor 会扫描所有已安装插件清单，查找已弃用的顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。发现后，它会提供将它们移动到 `contracts` 对象并就地重写清单文件的选项。此迁移是幂等的；如果 `contracts` 键已经有相同值，则会移除旧版键而不重复数据。 - - Doctor 还会检查 cron 作业存储（默认是 `~/.openclaw/cron/jobs.json`，或在覆盖时使用 `cron.store`），查找调度器仍为兼容性而接受的旧作业形态。 + + Doctor 还会检查 cron 作业存储（默认是 `~/.openclaw/cron/jobs.json`，或覆盖时的 `cron.store`），查找调度器为了兼容性仍接受的旧作业形态。 当前 cron 清理包括： - `jobId` → `id` - `schedule.cron` → `schedule.expr` - - 顶层载荷字段（`message`、`model`、`thinking`、...）→ `payload` - - 顶层投递字段（`deliver`、`channel`、`to`、`provider`、...）→ `delivery` - - 载荷 `provider` 投递别名 → 显式 `delivery.channel` - - 简单旧版 `notify: true` webhook 后备作业 → 显式 `delivery.mode="webhook"`，并带有 `delivery.to=cron.webhook` + - 顶层 payload 字段（`message`、`model`、`thinking`、...）→ `payload` + - 顶层 delivery 字段（`deliver`、`channel`、`to`、`provider`、...）→ `delivery` + - payload `provider` 递送别名 → 显式 `delivery.channel` + - 简单旧版 `notify: true` webhook 后备作业 → 显式 `delivery.mode="webhook"`，并设置 `delivery.to=cron.webhook` - Doctor 只有在可以不改变行为的情况下，才会自动迁移 `notify: true` 作业。如果某个作业将旧版通知后备与现有非 webhook 投递模式结合使用，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`。 - Doctor 会扫描每个智能体会话目录，查找陈旧的写锁文件——这些文件是在会话异常退出后遗留下来的。对于找到的每个锁文件，它会报告：路径、PID、该 PID 是否仍然存活、锁的存在时间，以及它是否被视为陈旧（PID 已死亡或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动移除陈旧的锁文件；否则会打印一条说明，并提示你使用 `--fix` 重新运行。 + Doctor 会扫描每个智能体会话目录，查找陈旧的写入锁文件，即会话异常退出后留下的文件。对于找到的每个锁文件，它会报告：路径、PID、PID 是否仍然存活、锁年龄，以及它是否被视为陈旧（PID 已死或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动移除陈旧锁文件；否则会打印一条说明，并指示你使用 `--fix` 重新运行。 - Doctor 会扫描智能体会话 JSONL 文件，查找由 2026.4.24 提示词转录重写错误创建的重复分支形态：一个被废弃的用户轮次，其中包含 OpenClaw 内部运行时上下文，另有一个活跃的同级分支包含相同的可见用户提示词。在 `--fix` / `--repair` 模式下，doctor 会在原文件旁备份每个受影响文件，并将转录重写为活跃分支，这样 Gateway 网关历史和记忆读取器就不会再看到重复轮次。 + Doctor 会扫描智能体会话 JSONL 文件，查找由 2026.4.24 提示词转录重写缺陷创建的重复分支形态：一个被遗弃的用户轮次，包含 OpenClaw 内部运行时上下文，以及一个包含相同可见用户提示词的活跃兄弟分支。在 `--fix` / `--repair` 模式下，Doctor 会在原文件旁备份每个受影响文件，并将转录重写到活跃分支，这样 Gateway 网关历史记录和记忆读取器就不再看到重复轮次。 - 状态目录是运行中的中枢。如果它消失，你会丢失会话、凭证、日志和配置（除非你在其他位置有备份）。 + 状态目录是运行层面的脑干。如果它消失，你会丢失会话、凭证、日志和配置（除非你在其他位置有备份）。 - Doctor 会检查： + 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` 崩溃所必需的。 + - **状态目录缺失**：警告灾难性状态丢失，提示重新创建目录，并提醒你它无法恢复缺失的数据。 + - **状态目录权限**：验证可写性；提供修复权限的选项（并在检测到所有者/组不匹配时发出 `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 会提醒你在远程主机上运行它（状态存放在那里）。 + - **主会话“1 行 JSONL”**：当主转录只有一行时标记（历史记录没有累积）。 + - **多个状态目录**：当多个 home 目录中存在多个 `~/.openclaw` 文件夹，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史记录可能在安装之间分裂）。 + - **远程模式提醒**：如果 `gateway.mode=remote`，Doctor 会提醒你在远程主机上运行它（状态位于那里）。 - **配置文件权限**：如果 `~/.openclaw/openclaw.json` 可被组/所有人读取，则发出警告，并提供收紧到 `600` 的选项。 - - Doctor 会检查认证存储中的 OAuth 配置文件，在令牌即将过期或已过期时发出警告，并在安全时刷新它们。如果 Anthropic OAuth/令牌配置文件已陈旧，它会建议使用 Anthropic API key 或 Anthropic setup-token 路径。刷新提示只会在交互式运行（TTY）时出现；`--non-interactive` 会跳过刷新尝试。 + + Doctor 会检查凭证存储中的 OAuth 配置文件，在令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic OAuth/令牌配置文件已陈旧，它会建议使用 Anthropic API key 或 Anthropic 设置令牌路径。刷新提示只会在交互式运行（TTY）时出现；`--non-interactive` 会跳过刷新尝试。 - 当 OAuth 刷新永久失败时（例如 `refresh_token_reused`、`invalid_grant`，或提供商要求你重新登录），doctor 会报告需要重新认证，并打印要运行的确切 `openclaw models auth login --provider ...` 命令。 + 当 OAuth 刷新永久失败时（例如 `refresh_token_reused`、`invalid_grant`，或提供商要求你重新登录），Doctor 会报告需要重新认证，并打印要运行的确切 `openclaw models auth login --provider ...` 命令。 - Doctor 还会报告由于以下原因而暂时不可用的认证配置文件： + Doctor 还会报告由于以下原因暂时不可用的凭证配置文件： - - 短暂冷却（速率限制/超时/认证失败） - - 更长时间的禁用（计费/额度失败） + - 短暂冷却（速率限制/超时/凭证失败） + - 较长禁用（账单/额度失败） - 如果设置了 `hooks.gmail.model`，doctor 会根据目录和允许列表验证模型引用，并在它无法解析或被禁止时发出警告。 + 如果设置了 `hooks.gmail.model`，Doctor 会根据目录和允许列表验证模型引用，并在它无法解析或被禁止时发出警告。 - 启用沙箱隔离时，doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧名称的选项。 + 启用沙箱隔离时，Doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧名称的选项。 - 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/install/update 工作。 + 当配置引用了可下载插件，但本地插件注册表找不到它们时，Doctor 也可以重新安装已配置的可下载插件。对于 2026.5.2 内置插件外部化，Doctor 会自动安装现有配置已经使用的可下载插件，然后依赖 `meta.lastTouchedVersion` 让该发布处理只运行一次。Gateway 网关启动和配置重载不会运行包管理器；插件安装仍然是显式的 Doctor/安装/更新工作。 - 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`。 - 当 Matrix 渠道账号存在待处理或可执行的旧版状态迁移时，doctor（在 `--fix` / `--repair` 模式下）会创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都是非致命的；错误会被记录，启动会继续。在只读模式（不带 `--fix` 的 `openclaw doctor`）下，此检查会被完全跳过。 + 当 Matrix 渠道账号有待处理或可操作的旧版状态迁移时，Doctor（在 `--fix` / `--repair` 模式下）会创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都是非致命的；错误会被记录，启动会继续。在只读模式（不带 `--fix` 的 `openclaw doctor`）下，此检查会被完全跳过。 - - Doctor 现在会将设备配对状态作为常规健康检查的一部分进行检查。 + + Doctor 现在会将设备配对状态作为正常健康检查的一部分进行检查。 - 它会报告： + 它报告的内容： - 待处理的首次配对请求 - 已配对设备的待处理角色升级 - - 已配对设备的待处理作用域升级 - - 公钥不匹配修复：设备 ID 仍然匹配，但设备身份已不再匹配已批准记录 - - 已配对记录缺少已批准角色的活动令牌 - - 已配对令牌的作用域偏离已批准的配对基线 - - 当前机器的本地缓存设备令牌条目早于 Gateway 网关侧令牌轮换，或携带过时的作用域元数据 + - 已配对设备的待处理范围升级 + - 公钥不匹配修复，其中设备 ID 仍然匹配，但设备身份不再匹配已批准记录 + - 已配对记录缺少已批准角色的活跃令牌 + - 范围漂移到已批准配对基线之外的已配对令牌 + - 当前机器上的本地缓存设备令牌条目早于 Gateway 网关侧令牌轮换，或携带陈旧的范围元数据 Doctor 不会自动批准配对请求或自动轮换设备令牌。它会改为打印确切的后续步骤： - 使用 `openclaw devices list` 检查待处理请求 - 使用 `openclaw devices approve ` 批准确切请求 - 使用 `openclaw devices rotate --device --role ` 轮换新令牌 - - 使用 `openclaw devices remove ` 移除并重新批准过时记录 + - 使用 `openclaw devices remove ` 移除并重新批准陈旧记录 - 这堵住了常见的“已经配对但仍然收到需要配对提示”缺口：Doctor 现在会区分首次配对、待处理的角色/作用域升级，以及过时令牌/设备身份漂移。 + 这弥合了常见的“已配对但仍收到需要配对”漏洞：Doctor 现在会区分首次配对、待处理角色/范围升级，以及陈旧令牌/设备身份漂移。 - 当提供商在没有 allowlist 的情况下对私信开放，或策略以危险方式配置时，Doctor 会发出警告。 + 当提供商对私信开放但没有允许列表，或策略以危险方式配置时，Doctor 会发出警告。 - - 如果作为 systemd 用户服务运行，Doctor 会确保已启用 linger，以便 Gateway 网关在注销后保持运行。 + + 如果作为 systemd 用户服务运行，Doctor 会确保已启用 linger，使 Gateway 网关在注销后保持存活。 - + Doctor 会打印默认智能体的工作区状态摘要： - - **Skills 状态**：统计符合条件、缺少要求以及被 allowlist 阻止的 Skills。 - - **旧工作区目录**：当 `~/openclaw` 或其他旧工作区目录与当前工作区同时存在时发出警告。 - - **插件状态**：统计已启用/已禁用/出错的插件；列出任何错误对应的插件 ID；报告内置插件能力。 + - **Skills 状态**：统计符合条件、缺少要求和被允许列表阻止的 Skills。 + - **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录与当前工作区并存时发出警告。 + - **插件状态**：统计已启用/已禁用/出错的插件；列出所有错误的插件 ID；报告内置插件能力。 - **插件兼容性警告**：标记与当前运行时存在兼容性问题的插件。 - **插件诊断**：显示插件注册表在加载时发出的任何警告或错误。 - Doctor 会检查工作区引导文件（例如 `AGENTS.md`、`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过配置的字符预算。它会按文件报告原始字符数与注入字符数、截断百分比、截断原因（`max/file` 或 `max/total`），以及总注入字符数占总预算的比例。当文件被截断或接近限制时，Doctor 会打印用于调整 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 的提示。 + Doctor 会检查工作区引导文件（例如 `AGENTS.md`、`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过配置的字符预算。它会按文件报告原始字符数与注入字符数、截断百分比、截断原因（`max/file` 或 `max/total`），以及总注入字符数占总预算的比例。当文件被截断或接近限制时，Doctor 会打印调优 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 的提示。 - - 当 `openclaw doctor --fix` 移除缺失的渠道插件时，它还会移除引用该插件的悬空渠道作用域配置：`channels.` 条目、命名该渠道的 heartbeat 目标，以及 `agents.*.models["/*"]` 覆盖项。这会防止渠道运行时已消失但配置仍要求 Gateway 网关绑定到它而导致的 Gateway 网关启动循环。 + + 当 `openclaw doctor --fix` 移除缺失的渠道插件时，它还会移除引用该插件的悬空渠道范围配置：`channels.` 条目、命名该渠道的 Heartbeat 目标，以及 `agents.*.models["/*"]` 覆盖项。这可以防止渠道运行时已经不存在但配置仍要求 Gateway 网关绑定到它的 Gateway 网关启动循环。 Doctor 会检查当前 shell（zsh、bash、fish 或 PowerShell）是否已安装 Tab 补全： - - 如果 shell 配置文件使用较慢的动态补全模式（`source <(openclaw completion ...)`），Doctor 会将其升级为更快的缓存文件变体。 + - 如果 shell 配置文件使用慢速动态补全模式（`source <(openclaw completion ...)`），Doctor 会将其升级为更快的缓存文件变体。 - 如果补全已在配置文件中配置但缓存文件缺失，Doctor 会自动重新生成缓存。 - 如果完全没有配置补全，Doctor 会提示安装它（仅交互模式；使用 `--non-interactive` 时跳过）。 运行 `openclaw completion --write-state` 可手动重新生成缓存。 - - Doctor 会检查本地 Gateway 网关令牌身份验证是否就绪。 + + Doctor 会检查本地 Gateway 网关令牌凭证就绪状态。 - - 如果令牌模式需要令牌但不存在令牌来源，Doctor 会提议生成一个。 + - 如果令牌模式需要令牌但不存在令牌源，Doctor 会提供生成令牌的选项。 - 如果 `gateway.auth.token` 由 SecretRef 管理但不可用，Doctor 会发出警告，并且不会用明文覆盖它。 - - `openclaw doctor --generate-gateway-token` 仅在未配置令牌 SecretRef 时强制生成。 + - `openclaw doctor --generate-gateway-token` 只有在没有配置令牌 SecretRef 时才会强制生成。 - - 某些修复流程需要在不削弱运行时快速失败行为的前提下检查已配置的凭据。 + + 某些修复流程需要检查已配置凭证，同时不削弱运行时快速失败行为。 - - `openclaw doctor --fix` 现在会对定向配置修复使用与 status 系列命令相同的只读 SecretRef 摘要模型。 - - 示例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修复会在可用时尝试使用已配置的机器人凭据。 - - 如果 Telegram 机器人令牌通过 SecretRef 配置，但在当前命令路径中不可用，Doctor 会报告该凭据已配置但不可用，并跳过自动解析，而不是崩溃或误报令牌缺失。 + - `openclaw doctor --fix` 现在会使用与状态类命令相同的只读 SecretRef 摘要模型，用于定向配置修复。 + - 示例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修复会在可用时尝试使用已配置的机器人凭证。 + - 如果 Telegram 机器人令牌通过 SecretRef 配置但在当前命令路径中不可用，Doctor 会报告该凭证已配置但不可用，并跳过自动解析，而不是崩溃或误报令牌缺失。 Doctor 会运行健康检查，并在 Gateway 网关看起来不健康时提供重启选项。 - Doctor 会检查已配置的记忆搜索嵌入提供商是否已为默认智能体准备就绪。该行为取决于已配置的后端和提供商： + Doctor 会检查已配置的记忆搜索嵌入提供商是否已为默认智能体就绪。行为取决于已配置的后端和提供商： - - **QMD 后端**：探测 `qmd` 二进制文件是否可用且可启动。如果不可用，会打印修复指引，包括 npm 包和手动二进制路径选项。 - - **显式本地提供商**：检查本地模型文件，或可识别的远程/可下载模型 URL。如果缺失，建议切换到远程提供商。 + - **QMD 后端**：探测 `qmd` 二进制文件是否可用且可启动。如果不可用，会打印修复指南，包括 npm 包和手动二进制路径选项。 + - **显式本地提供商**：检查是否存在本地模型文件或可识别的远程/可下载模型 URL。如果缺失，建议切换到远程提供商。 - **显式远程提供商**（`openai`、`voyage` 等）：验证环境或认证存储中是否存在 API key。如果缺失，会打印可操作的修复提示。 - **自动提供商**：先检查本地模型可用性，然后按自动选择顺序尝试每个远程提供商。 - 当缓存的 Gateway 网关探测结果可用时（检查时 Gateway 网关处于健康状态），Doctor 会将其结果与 CLI 可见配置交叉比对，并指出任何差异。Doctor 不会在默认路径上启动新的嵌入 ping；当你需要实时提供商检查时，请使用深度记忆 Status 命令。 + 当存在缓存的 Gateway 网关探测结果时（检查时 Gateway 网关健康），Doctor 会将其结果与 CLI 可见的配置交叉比对，并标注任何差异。Doctor 不会在默认路径上启动新的嵌入 ping；如果你需要实时提供商检查，请使用深度记忆状态命令。 使用 `openclaw memory status --deep` 在运行时验证嵌入就绪状态。 - - 如果 Gateway 网关健康，Doctor 会运行渠道 Status 探测，并报告警告和建议的修复方式。 + + 如果 Gateway 网关健康，Doctor 会运行渠道状态探测，并报告警告及建议修复方式。 - - Doctor 会检查已安装的监督器配置（launchd/systemd/schtasks），查找缺失或过时的默认值（例如 systemd network-online 依赖项和重启延迟）。当发现不匹配时，它会建议更新，并可以将服务文件/任务重写为当前默认值。 + + Doctor 会检查已安装的 supervisor 配置（launchd/systemd/schtasks）是否缺少默认值或默认值已过期（例如 systemd network-online 依赖项和重启延迟）。发现不匹配时，它会建议更新，并可以将服务文件/任务重写为当前默认值。 - 注意： + 备注： - - `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 doctor` 会在重写 supervisor 配置前提示。 + - `openclaw doctor --yes` 接受默认修复提示。 + - `openclaw doctor --repair` 无需提示即可应用建议修复。 + - `openclaw doctor --repair --force` 会覆盖自定义 supervisor 配置。 + - `OPENCLAW_SERVICE_REPAIR_POLICY=external` 会让 Doctor 对 Gateway 网关服务生命周期保持只读。它仍会报告服务健康状况并运行非服务修复，但会跳过服务安装/启动/重启/bootstrap、supervisor 配置重写，以及旧版服务清理，因为该生命周期由外部 supervisor 拥有。 + - 在 Linux 上，当匹配的 systemd Gateway 网关 unit 处于活动状态时，Doctor 不会重写命令/入口点元数据。它还会在重复服务扫描期间忽略处于非活动状态的非旧版额外 Gateway 网关类似 unit，因此配套服务文件不会产生清理噪声。 + - 如果令牌认证需要令牌，且 `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 user-systemd unit，Doctor 令牌漂移检查现在会在比较服务认证元数据时同时包含 `Environment=` 和 `EnvironmentFile=` 来源。 + - 当配置最后由较新版本写入时，Doctor 服务修复会拒绝使用较旧的 OpenClaw 二进制文件重写、停止或重启 Gateway 网关服务。请参阅 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)。 - 你始终可以通过 `openclaw gateway install --force` 强制完整重写。 - Doctor 会检查服务运行时（PID、最后退出 Status），并在服务已安装但实际上未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。 + Doctor 会检查服务运行时（PID、最后退出状态），并在服务已安装但实际未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。 - 当 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 init。Doctor 会在系统 Node 安装可用时（Homebrew/apt/choco）提供迁移选项。 - 新安装或修复的 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`）和稳定的 user-bin 目录，但猜测出的版本管理器备用目录只有在这些目录实际存在于磁盘上时，才会写入服务 PATH。 - Doctor 会持久保存任何配置更改，并标记向导元数据以记录这次 Doctor 运行。 + Doctor 会持久化所有配置变更，并为向导元数据打标以记录本次 Doctor 运行。 - 当缺少工作区记忆系统时，Doctor 会建议添加；如果工作区尚未纳入 git 管理，则会打印备份提示。 + Doctor 会在缺少工作区记忆系统时建议添加，并在工作区尚未纳入 git 管理时打印备份提示。 - 请参阅 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)，了解工作区结构和 git 备份的完整指南（推荐使用私有 GitHub 或 GitLab）。 + 有关工作区结构和 git 备份（推荐使用私有 GitHub 或 GitLab）的完整指南，请参阅 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)。 diff --git a/docs/zh-CN/tools/plugin.md b/docs/zh-CN/tools/plugin.md index 8daef6026..e7a956e1e 100644 --- a/docs/zh-CN/tools/plugin.md +++ b/docs/zh-CN/tools/plugin.md @@ -1,26 +1,25 @@ --- read_when: - 安装或配置插件 - - 了解插件发现与加载规则 + - 了解插件发现和加载规则 - 使用与 Codex/Claude 兼容的插件包 sidebarTitle: Install and Configure summary: 安装、配置和管理 OpenClaw 插件 title: 插件 x-i18n: - generated_at: "2026-05-03T17:11:02Z" + generated_at: "2026-05-04T22:54:34Z" model: gpt-5.5 provider: openai - source_hash: 30e3cffc15c5c52dd539e21103c207c9e38955f9fd3acd561a52964eefafb8f0 + source_hash: 1de640f7766a6b312a2385075ae1abdb19f5c2afcb0e7063eba0d3edde697004 source_path: tools/plugin.md workflow: 16 --- -插件为 OpenClaw 扩展新能力：渠道、模型提供商、智能体运行框架、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。一些插件是 **核心**（随 OpenClaw 分发），另一些是 **外部**。大多数外部插件通过 [ClawHub](/zh-CN/tools/clawhub) 发布和发现。在该迁移完成之前，npm 仍支持直接安装，以及一组临时的 OpenClaw 自有插件包。 +插件通过新能力扩展 OpenClaw：渠道、模型提供商、agent harnesses、工具、Skills、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、Web 获取、Web 搜索等。一些插件是 **核心** 插件（随 OpenClaw 一起提供），另一些是 **外部** 插件。大多数外部插件通过 [ClawHub](/zh-CN/tools/clawhub) 发布和发现。npm 仍然支持直接安装，也支持 OpenClaw 自有插件包的临时集合，直到该迁移完成。 ## 快速开始 -如需可直接复制粘贴的安装、列出、卸载、更新和发布示例，请参阅 -[管理插件](/zh-CN/plugins/manage-plugins)。 +有关可复制粘贴的安装、列出、卸载、更新和发布示例，请参阅[管理插件](/zh-CN/plugins/manage-plugins)。 @@ -55,14 +54,15 @@ x-i18n: openclaw gateway restart ``` - 然后在你的配置文件中的 `plugins.entries.\.config` 下进行配置。 + 然后在你的配置文件中的 `plugins.entries.\.config` 下配置。 - + 在运行中的 Gateway 网关中，仅所有者可用的 `/plugins enable` 和 `/plugins disable` - 会触发 Gateway 网关配置重新加载器。Gateway 网关会在进程内重新加载插件运行时接口面，新的智能体轮次会从刷新后的注册表重建工具列表。`/plugins install` - 会更改插件源代码，因此 Gateway 网关会请求重启，而不是假定当前进程可以安全地重新加载已经导入的模块。 + 会触发 Gateway 网关配置重载器。Gateway 网关会在进程内重新加载插件运行时 + 表面，新的 agent 轮次会从刷新后的注册表重建其工具列表。`/plugins install` 会更改插件源代码，因此 Gateway 网关会请求重启，而不是假装当前进程可以 + 安全地重新加载已经导入的模块。 @@ -74,12 +74,13 @@ x-i18n: openclaw --help ``` - 当你需要证明已注册的工具、服务、Gateway 网关方法、钩子或插件拥有的 CLI 命令时，请使用 `--runtime`。普通 `inspect` 是一次冷态的清单/注册表检查，并且有意避免导入插件运行时。 + 当你需要证明已注册的工具、服务、Gateway 网关方法、钩子或插件拥有的 CLI 命令时，请使用 `--runtime`。普通 `inspect` 是冷态的 + 清单/注册表检查，并且会有意避免导入插件运行时。 -如果你更偏好聊天内原生控制，请启用 `commands.plugins: true` 并使用： +如果你更偏好聊天原生控制，请启用 `commands.plugins: true` 并使用： ```text /plugin install clawhub: @@ -88,26 +89,48 @@ x-i18n: ``` 安装路径使用与 CLI 相同的解析器：本地路径/归档、显式 -`clawhub:`、显式 `npm:`、显式 `git:`，或通过 npm 解析的无前缀包规格。 +`clawhub:`、显式 `npm:`、显式 `git:`，或通过 npm 的裸包 +规格。 -如果配置无效，安装通常会拒绝继续，并提示你运行 -`openclaw doctor --fix`。唯一的恢复例外是一个范围很窄的内置插件重装路径，适用于选择启用 +如果配置无效，安装通常会失败关闭并指向 +`openclaw doctor --fix`。唯一的恢复例外是一个狭窄的内置插件 +重装路径，仅适用于选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。 -在 Gateway 网关启动期间，无效的插件配置会像任何其他无效配置一样导致启动拒绝继续。运行 `openclaw doctor --fix` 可隔离有问题的插件配置，方法是禁用该插件条目并移除其无效配置载荷；常规配置备份会保留先前值。 -当某个渠道配置引用了一个不再可发现的插件，但同一个过期插件 ID 仍保留在插件配置或安装记录中时，Gateway 网关启动会记录警告并跳过该渠道，而不是阻塞所有其他渠道。 -运行 `openclaw doctor --fix` 可移除过期的渠道/插件条目；没有过期插件证据的未知渠道键仍会验证失败，以便拼写错误保持可见。 -如果设置了 `plugins.enabled: false`，过期插件引用会被视为惰性：Gateway 网关启动会跳过插件发现/加载工作，`openclaw doctor` 会保留已禁用的插件配置，而不是自动移除它。如果你希望移除过期插件 ID，请先重新启用插件再运行 Doctor 清理。 +在 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` 或分发标签等可变选择器会在安装前解析，然后固定到 OpenClaw 托管 npm 根目录中经过精确验证的版本。npm 完成后，OpenClaw 会验证已安装的 -`package-lock.json` 条目仍然匹配解析出的版本和完整性。如果 npm 写入了不同的包元数据，安装会失败并回滚托管包，而不是接受不同的插件制品。 +对于 npm 安装，`latest` 或 dist-tag 等可变选择器会在安装前解析， +然后固定到 OpenClaw 的托管 npm 根目录中经过验证的确切版本。npm 完成后，OpenClaw 会验证已安装的 +`package-lock.json` 条目是否仍与解析出的版本和完整性匹配。如果 +npm 写入不同的包元数据，安装会失败，并且托管包 +会回滚，而不是接受不同的插件制品。 -源码检出是 pnpm 工作区。如果你克隆 OpenClaw 来修改内置插件，请运行 `pnpm install`；随后 OpenClaw 会从 -`extensions/` 加载内置插件，以便直接使用编辑内容和包本地依赖。 -普通的 npm 根目录安装适用于打包版 OpenClaw，而不是源码检出开发。 +源码检出是 pnpm 工作区。如果你克隆 OpenClaw 来修改内置 +插件，请运行 `pnpm install`；随后 OpenClaw 会从 +`extensions/` 加载内置插件，因此会直接使用你的编辑和包本地依赖。 +普通 npm 根目录安装用于打包版 OpenClaw，而不是源码检出 +开发。 ## 插件类型 @@ -115,21 +138,29 @@ OpenClaw 识别两种插件格式： | 格式 | 工作方式 | 示例 | | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ | -| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 | -| **包** | 兼容 Codex/Claude/Cursor 的布局；映射为 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` | +| **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 | +| **Bundle** | 与 Codex/Claude/Cursor 兼容的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` | -两者都会显示在 `openclaw plugins list` 中。有关插件包的详细信息，请参阅 [插件包](/zh-CN/plugins/bundles)。 +两者都会显示在 `openclaw plugins list` 下。有关 Bundle 详情，请参阅[插件 Bundle](/zh-CN/plugins/bundles)。 -如果你正在编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins) -和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。 +如果你正在编写原生插件，请从[构建插件](/zh-CN/plugins/building-plugins) +和[插件 SDK 概览](/zh-CN/plugins/sdk-overview)开始。 ## 包入口点 原生插件 npm 包必须在 `package.json` 中声明 `openclaw.extensions`。 -每个条目都必须位于包目录内，并解析为可读取的运行时文件，或解析为一个 TypeScript 源文件，且能够推断出对应的已构建 JavaScript 对等文件，例如从 `src/index.ts` 到 `dist/index.js`。 -打包安装必须随附该 JavaScript 运行时输出。TypeScript 源码回退用于源码检出和本地开发路径，不适用于安装到 OpenClaw 托管插件根目录中的 npm 包。 +每个条目都必须位于包目录内，并解析为可读的 +运行时文件，或解析为带有推断出的已构建 JavaScript +对等文件的 TypeScript 源文件，例如从 `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 { @@ -145,11 +176,17 @@ OpenClaw 识别两种插件格式： ### 迁移期间 OpenClaw 自有的 npm 包 -ClawHub 是大多数插件的主要分发路径。当前打包版 OpenClaw 发行版已经内置许多官方插件，因此在普通设置中它们不需要单独的 npm 安装。在每个 OpenClaw 自有插件都迁移到 ClawHub 之前，OpenClaw 仍会在 npm 上发布一些 `@openclaw/*` 插件包，用于旧版/自定义安装和直接 npm 工作流。 +ClawHub 是大多数插件的主要分发路径。当前打包版 +OpenClaw 版本已经内置许多官方插件，因此在常规设置中不需要 +单独 npm 安装。在每个 OpenClaw 自有插件都 +迁移到 ClawHub 之前，OpenClaw 仍会在 npm 上发布一些 `@openclaw/*` 插件包， +用于较旧/自定义安装和直接 npm 工作流。 -如果 npm 报告某个 `@openclaw/*` 插件包已弃用，该包版本来自较旧的外部包发布序列。在更新的 npm 包发布之前，请使用当前 OpenClaw 中的内置插件或本地检出。 +如果 npm 报告某个 `@openclaw/*` 插件包已弃用，则该包 +版本来自较旧的外部包发布线。请使用 +当前 OpenClaw 中的内置插件或本地检出，直到发布更新的 npm 包。 -| 插件 | 包 | 文档 | +| 插件 | 包 | 文档 | | --------------- | -------------------------- | ------------------------------------------ | | BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/zh-CN/channels/bluebubbles) | | Discord | `@openclaw/discord` | [Discord](/zh-CN/channels/discord) | @@ -165,7 +202,7 @@ ClawHub 是大多数插件的主要分发路径。当前打包版 OpenClaw 发 | Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) | | Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) | -### 核心（随 OpenClaw 分发） +### 核心（随 OpenClaw 一起提供） @@ -177,10 +214,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)。 @@ -190,12 +227,12 @@ ClawHub 是大多数插件的主要分发路径。当前打包版 OpenClaw 发 - `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时和默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用） - - `copilot-proxy` — VS Code Copilot Proxy 桥接（默认禁用） + - `copilot-proxy` — VS Code Copilot Proxy 桥接器（默认禁用） -在寻找第三方插件？请参阅 [社区插件](/zh-CN/plugins/community)。 +正在寻找第三方插件？请参阅[社区插件](/zh-CN/plugins/community)。 ## 配置 @@ -213,49 +250,38 @@ ClawHub 是大多数插件的主要分发路径。当前打包版 OpenClaw 发 } ``` -| 字段 | 说明 | -| ---------------- | --------------------------------------------------------- | -| `enabled` | 总开关（默认值：`true`） | -| `allow` | 插件允许列表（可选） | -| `deny` | 插件拒绝列表（可选；拒绝优先） | -| `load.paths` | 额外插件文件/目录 | -| `slots` | 独占槽位选择器（例如 `memory`、`contextEngine`） | -| `entries.\` | 每个插件的开关 + 配置 | +| 字段 | 说明 | +| ------------------ | -------------------------------------------------------- | +| `enabled` | 主开关（默认：`true`） | +| `allow` | 插件允许列表（可选） | +| `bundledDiscovery` | 内置插件发现模式（默认：`allowlist`） | +| `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.bundledDiscovery` 默认是 `"allowlist"`，因此限制性的 `plugins.allow` 清单也会阻止未列出的内置提供商插件，包括运行时 Web 搜索提供商发现。Doctor 会在迁移期间为较旧的限制性允许列表配置标记 `"compat"`，这样升级会保留旧版内置提供商行为，直到操作者选择启用更严格的模式。空的 `plugins.allow` 仍会被视为未设置/开放。 -`openclaw plugins list` 是本地插件注册表/配置快照。其中显示为 -`enabled` 的插件表示持久化注册表和当前配置允许该插件参与运行。 -这并不证明一个已在运行的远程 Gateway 网关已经重新加载或重启到 -同一份插件代码。在带有包装器进程的 VPS/容器设置中，请将重启或 -触发重新加载的写入发送到实际的 `openclaw gateway run` 进程，或者在 -重新加载报告失败时，对正在运行的 Gateway 网关使用 `openclaw gateway restart`。 +通过 `/plugins enable` 或 `/plugins disable` 进行的配置更改会触发进程内 Gateway 网关插件重新加载。新的智能体轮次会从刷新后的插件注册表重建其工具列表。安装、更新和卸载等更改来源的操作仍会重启 Gateway 网关进程，因为已导入的插件模块无法安全地就地替换。 + +`openclaw plugins list` 是本地插件注册表/配置快照。其中显示为 `enabled` 的插件表示持久化注册表和当前配置允许该插件参与运行。这并不证明已经运行的远程 Gateway 网关已重新加载或重启到同一份插件代码。在使用包装进程的 VPS/容器设置中，请向实际的 `openclaw gateway run` 进程发送重启或触发重新加载的写入，或者在重新加载报告失败时，对正在运行的 Gateway 网关使用 `openclaw gateway restart`。 - - **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。 - - **缺失**：配置引用了设备发现未找到的插件 ID。 - - **无效**：插件存在，但其配置与声明的架构不匹配。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` 可移除这些过时别名。 @@ -267,62 +293,37 @@ OpenClaw 按以下顺序扫描插件（第一个匹配项生效）： - 随 OpenClaw 一起发布。许多默认启用（模型提供商、语音）。 - 其他插件需要显式启用。 + 随 OpenClaw 一起发布。许多插件默认启用（模型提供商、语音）。其他插件需要显式启用。 -打包安装和 Docker 镜像通常会从编译后的 `dist/extensions` 树解析内置插件。 -如果某个内置插件源目录被绑定挂载到匹配的打包源路径上，例如 -`/app/extensions/synology-chat`，OpenClaw 会将该挂载的源目录 -视为内置源覆盖，并在打包的 -`/app/dist/extensions/synology-chat` 包之前发现它。这样可以让维护者容器 -循环继续工作，而无需将每个内置插件都切回 TypeScript 源码。 -设置 `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` 可强制使用打包的 dist 包， -即使存在源覆盖挂载也是如此。 +打包安装和 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.deny` 始终优先于 allow +- `plugins.deny` 始终优先于允许 - `plugins.entries.\.enabled: false` 会禁用该插件 - 工作区来源的插件**默认禁用**（必须显式启用） -- 内置插件遵循内建的默认启用集合，除非被覆盖 -- 独占槽位可以强制启用该槽位选中的插件 -- 当配置命名了插件拥有的表面时，一些内置的选择性启用插件会自动启用， - 例如提供商模型引用、渠道配置或 harness 运行时 -- 当 `plugins.enabled: false` 处于活动状态时，过时插件配置会被保留； - 如果你希望移除过时 ID，请先重新启用插件，再运行 Doctor 清理 -- OpenAI 系列 Codex 路由保持独立的插件边界： - `openai-codex/*` 属于 OpenAI 插件，而内置 Codex - app-server 插件由 `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、配置文件、配置路径和进程就是你正在编辑的那些。 -- 在插件安装/配置/代码变更后重启实时 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 网关。 +- 运行 `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 网关。 ### 插件工具设置缓慢 -如果智能体轮次看起来在准备工具时卡住，请启用 trace 日志并 -检查插件工具工厂计时行： +如果智能体轮次在准备工具时似乎卡住，请启用 trace 日志，并检查插件工具工厂耗时行： ```bash openclaw config set logging.level trace @@ -335,24 +336,17 @@ openclaw logs --follow [trace:plugin-tools] factory timings ... ``` -摘要会列出总工厂耗时和最慢的插件工具工厂， -包括插件 ID、声明的工具名称、结果形态，以及该工具是否 -可选。当单个工厂耗时至少 1 秒，或插件工具工厂准备总耗时至少 5 秒时， -慢速行会提升为警告。 +摘要会列出总工厂耗时和最慢的插件工具工厂，包括插件 ID、声明的工具名称、结果形态，以及工具是否可选。当单个工厂耗时至少 1 秒，或插件工具工厂准备总耗时至少 5 秒时，慢速行会提升为警告。 -OpenClaw 会为相同有效请求上下文下的重复解析缓存成功的插件工具工厂结果。 -缓存键包含有效运行时配置、工作区、智能体/会话 ID、沙箱策略、浏览器设置、 -交付上下文、请求者身份和所有权状态，因此依赖这些可信字段的工厂会在 -上下文变化时重新运行。 +OpenClaw 会为使用相同有效请求上下文的重复解析缓存成功的插件工具工厂结果。缓存键包含有效运行时配置、工作区、智能体/会话 ID、沙箱策略、浏览器设置、交付上下文、请求者身份和所有权状态，因此依赖这些可信字段的工厂会在上下文变化时重新运行。 -如果某个插件占用了主要耗时，请检查其运行时注册： +如果某个插件占据了主要耗时，请检查其运行时注册： ```bash openclaw plugins inspect --runtime --json ``` -然后更新、重新安装或禁用该插件。插件作者应将昂贵的依赖加载 -移动到工具执行路径之后，而不是在工具工厂内执行。 +然后更新、重新安装或禁用该插件。插件作者应将昂贵的依赖加载移到工具执行路径之后，而不是在工具工厂内部完成。 ### 重复的渠道或工具所有权 @@ -362,35 +356,24 @@ 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 { @@ -403,10 +386,10 @@ openclaw plugins inspect --runtime --json } ``` -| 槽位 | 控制内容 | 默认值 | -| --------------- | --------------------- | ------------------- | -| `memory` | 活动记忆插件 | `memory-core` | -| `contextEngine` | 活动上下文引擎 | `legacy`（内置） | +| 槽位 | 控制内容 | 默认值 | +| --------------- | -------------- | ------------------- | +| `memory` | 活动记忆插件 | `memory-core` | +| `contextEngine` | 活动上下文引擎 | `legacy`（内置） | ## CLI 参考 @@ -456,35 +439,33 @@ openclaw plugins enable openclaw plugins disable ``` -OpenClaw 随附内置插件。许多插件默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）。其他内置插件仍需要 `openclaw plugins enable `。 +内置插件随 OpenClaw 一起发布。许多插件默认启用（例如内置模型提供商、内置语音提供商和内置浏览器插件）。其他内置插件仍需要运行 `openclaw plugins enable `。 -`--force` 会就地覆盖现有已安装的插件或钩子包。使用 `openclaw plugins update ` 对受跟踪的 npm 插件进行常规升级。它不支持与 `--link` 一起使用，因为 `--link` 会复用源路径，而不是复制到托管安装目标上。 +`--force` 会原位覆盖现有已安装插件或钩子包。对于已跟踪 npm 插件的常规升级，请使用 `openclaw plugins update `。它不支持与 `--link` 一起使用，因为 `--link` 会复用源路径，而不是复制到受管理的安装目标上。 -当 `plugins.allow` 已设置时，`openclaw plugins install` 会先把已安装的插件 ID 添加到该允许列表，然后再启用它。如果同一个插件 ID 存在于 `plugins.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 update` 在 beta 渠道上运行时，默认线 npm 和 ClawHub 插件记录会先尝试 `@beta`，并在不存在插件 beta 版本时回退到默认/latest。精确版本和显式标签会保持固定。 +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 网关支持的技能依赖安装改用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍是单独的 ClawHub 技能下载/安装流程。 +此 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的 Skills 依赖安装使用匹配的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍是单独的 ClawHub Skills 下载/安装流程。 -如果你发布到 ClawHub 的插件被扫描隐藏或阻止，请打开 ClawHub 仪表板，或运行 `clawhub package rescan ` 请求 ClawHub 再次检查它。`--dangerously-force-unsafe-install` 只影响你自己机器上的安装；它不会请求 ClawHub 重新扫描该插件，也不会让被阻止的发布变为公开。 +如果你在 ClawHub 发布的插件被扫描隐藏或阻断，请打开 ClawHub 仪表板，或运行 `clawhub package rescan ` 请求 ClawHub 重新检查。`--dangerously-force-unsafe-install` 只影响你自己机器上的安装；它不会请求 ClawHub 重新扫描插件，也不会让被阻断的版本公开。 -兼容包会参与同一个插件列表/检查/启用/禁用流程。当前运行时支持包括包内 Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex 钩子目录。 +兼容包参与同一套插件 list/inspect/enable/disable 流程。当前运行时支持包括包内 Skills、Claude 命令型 Skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor 命令型 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({ @@ -504,19 +485,19 @@ export default definePluginEntry({ }); ``` -OpenClaw 会在插件激活期间加载入口对象并调用 `register(api)`。加载器仍会为较旧插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公共契约。 +OpenClaw 会在插件激活期间加载入口对象并调用 `register(api)`。加载器仍会为旧版插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公共契约。 -`api.registrationMode` 会告诉插件其入口为什么被加载： +`api.registrationMode` 会告诉插件其入口为何被加载： | 模式 | 含义 | | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `full` | 运行时激活。注册工具、钩子、服务、命令、路由以及其他实时副作用。 | +| `full` | 运行时激活。注册工具、钩子、服务、命令、路由和其他实时副作用。 | | `discovery` | 只读能力发现。注册提供商和元数据；受信任的插件入口代码可以加载，但应跳过实时副作用。 | -| `setup-only` | 通过轻量级设置入口加载渠道设置元数据。 | +| `setup-only` | 通过轻量设置入口加载渠道设置元数据。 | | `setup-runtime` | 还需要运行时入口的渠道设置加载。 | | `cli-metadata` | 仅收集 CLI 命令元数据。 | -会打开套接字、数据库、后台 worker 或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 保护这些副作用。发现加载会与激活加载分开缓存，并且不会替换正在运行的 Gateway 网关注册表。发现是非激活式的，但并非免导入：OpenClaw 可能会求值受信任的插件入口或渠道插件模块以构建快照。保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移到完整运行时路径后面。 +会打开套接字、数据库、后台 worker 或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 保护这些副作用。发现加载会与激活加载分开缓存，并且不会替换正在运行的 Gateway 网关注册表。发现是非激活式的，但并非免导入：OpenClaw 可能会执行受信任的插件入口或渠道插件模块来构建快照。保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移到完整运行时路径之后。 常见注册方法： @@ -524,7 +505,7 @@ OpenClaw 会在插件激活期间加载入口对象并调用 `register(api)`。 | --------------------------------------- | --------------------------- | | `registerProvider` | 模型提供商（LLM） | | `registerChannel` | 聊天渠道 | -| `registerTool` | 智能体工具 | +| `registerTool` | Agent 工具 | | `registerHook` / `on(...)` | 生命周期钩子 | | `registerSpeechProvider` | 文本转语音 / STT | | `registerRealtimeTranscriptionProvider` | 流式 STT | @@ -533,31 +514,31 @@ OpenClaw 会在插件激活期间加载入口对象并调用 `register(api)`。 | `registerImageGenerationProvider` | 图像生成 | | `registerMusicGenerationProvider` | 音乐生成 | | `registerVideoGenerationProvider` | 视频生成 | -| `registerWebFetchProvider` | Web 抓取 / 抓取提供商 | +| `registerWebFetchProvider` | Web 抓取 / 爬取提供商 | | `registerWebSearchProvider` | Web 搜索 | | `registerHttpRoute` | HTTP 端点 | | `registerCommand` / `registerCli` | CLI 命令 | | `registerContextEngine` | 上下文引擎 | | `registerService` | 后台服务 | -类型化生命周期钩子的钩子保护行为： +类型化生命周期钩子的保护行为： -- `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 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)。 +原生 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)。 -## 相关 +## 相关内容 - [构建插件](/zh-CN/plugins/building-plugins) — 创建你自己的插件 - [插件包](/zh-CN/plugins/bundles) — Codex/Claude/Cursor 包兼容性 -- [插件清单](/zh-CN/plugins/manifest) — 清单 schema +- [插件清单](/zh-CN/plugins/manifest) — 清单架构 - [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具 -- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载管线 +- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载流程 - [社区插件](/zh-CN/plugins/community) — 第三方列表