diff --git a/docs/zh-CN/ci.md b/docs/zh-CN/ci.md index 33de72333..661a6834b 100644 --- a/docs/zh-CN/ci.md +++ b/docs/zh-CN/ci.md @@ -1,56 +1,57 @@ --- read_when: - - 你需要了解某个 CI 作业为何运行或未运行 + - 你需要了解为什么某个 CI 作业会运行或不会运行 - 你正在调试失败的 GitHub Actions 检查 -summary: CI 作业图、作用域门控以及本地命令对应关系 +summary: CI 作业图、作用域门禁，以及本地命令等效项 title: CI 流水线 x-i18n: - generated_at: "2026-04-09T02:58:23Z" + generated_at: "2026-04-10T23:44:34Z" model: gpt-5.4 provider: openai - source_hash: d104f2510fadd674d7952aa08ad73e10f685afebea8d7f19adc1d428e2bdc908 + source_hash: ca7e355b7f73bfe8ea8c6971e78164b8b2e68cbb27966964955e267fed89fce6 source_path: ci.md workflow: 15 --- # CI 流水线 -CI 会在每次推送到 `main` 以及每个拉取请求上运行。它使用智能作用域划分，仅在变更与相关区域有关时才运行高开销作业。 +CI 会在每次推送到 `main` 以及每个拉取请求时运行。它使用智能作用域划分，在仅有不相关区域发生变更时跳过开销较大的作业。 ## 作业概览 -| 作业 | 用途 | 运行时机 | -| ------------------------ | ------------------------------------------------------------------------------------- | -------------------------------- | -| `preflight` | 检测仅文档变更、变更作用域、变更的扩展，并构建 CI 清单 | 所有非草稿的推送和 PR 都会运行 | -| `security-fast` | 私钥检测、通过 `zizmor` 进行工作流审计、生产依赖审计 | 所有非草稿的推送和 PR 都会运行 | -| `build-artifacts` | 构建 `dist/` 和 Control UI 一次，并上传供下游作业复用的制品 | 与 Node 相关的变更 | -| `checks-fast-core` | 快速 Linux 正确性通道，例如 bundled/plugin-contract/protocol 检查 | 与 Node 相关的变更 | -| `checks-fast-extensions` | 在 `checks-fast-extensions-shard` 完成后聚合扩展分片通道 | 与 Node 相关的变更 | -| `extension-fast` | 仅针对已变更的内置插件运行聚焦测试 | 检测到扩展变更时 | -| `check` | CI 中的主要本地门禁：`pnpm check` 加 `pnpm build:strict-smoke` | 与 Node 相关的变更 | -| `check-additional` | 架构、边界、导入循环防护，以及 Gateway 网关 watch 回归测试工具 | 与 Node 相关的变更 | -| `build-smoke` | 已构建 CLI 的 smoke 测试和启动内存 smoke 测试 | 与 Node 相关的变更 | -| `checks` | 更重的 Linux Node 通道：完整测试、渠道测试，以及仅在 push 时运行的 Node 22 兼容性测试 | 与 Node 相关的变更 | -| `check-docs` | 文档格式、lint 和失效链接检查 | 文档发生变更时 | -| `skills-python` | 面向 Python 支持的 Skills 的 Ruff + pytest | 与 Python Skills 相关的变更 | -| `checks-windows` | Windows 特定测试通道 | 与 Windows 相关的变更 | -| `macos-node` | 使用共享构建制品的 macOS TypeScript 测试通道 | 与 macOS 相关的变更 | -| `macos-swift` | macOS 应用的 Swift lint、构建和测试 | 与 macOS 相关的变更 | -| `android` | Android 构建和测试矩阵 | 与 Android 相关的变更 | +| 作业 | 目的 | 运行时机 | +| ------------------------ | ------------------------------------------------------------------------------------ | ----------------------------------- | +| `preflight` | 检测仅文档变更、变更作用域、变更的扩展，并构建 CI 清单 | 在所有非草稿推送和 PR 上始终运行 | +| `security-fast` | 私钥检测、通过 `zizmor` 进行工作流审计、生产依赖审计 | 在所有非草稿推送和 PR 上始终运行 | +| `build-artifacts` | 构建 `dist/` 和 Control UI 一次，并上传可供下游作业复用的制品 | 与 Node 相关的变更 | +| `checks-fast-core` | 快速 Linux 正确性通道，例如 bundled/plugin-contract/protocol 检查 | 与 Node 相关的变更 | +| `checks-node-extensions` | 跨整个扩展套件的完整 bundled-plugin 测试分片 | 与 Node 相关的变更 | +| `checks-node-core-test` | 核心 Node 测试分片，不包括渠道、bundled、contract 和扩展通道 | 与 Node 相关的变更 | +| `extension-fast` | 仅针对已变更 bundled 插件的聚焦测试 | 检测到扩展变更时 | +| `check` | CI 中的主要本地门禁：`pnpm check` 加 `pnpm build:strict-smoke` | 与 Node 相关的变更 | +| `check-additional` | 架构、边界、导入循环防护，以及 Gateway 网关 watch 回归测试 harness | 与 Node 相关的变更 | +| `build-smoke` | 已构建 CLI 的冒烟测试和启动内存冒烟测试 | 与 Node 相关的变更 | +| `checks` | 剩余的 Linux Node 通道：渠道测试以及仅在推送时运行的 Node 22 兼容性检查 | 与 Node 相关的变更 | +| `check-docs` | 文档格式、lint 和损坏链接检查 | 文档发生变更时 | +| `skills-python` | 面向 Python 支持的 Skills 的 Ruff + pytest | 与 Python Skills 相关的变更 | +| `checks-windows` | Windows 特定测试通道 | 与 Windows 相关的变更 | +| `macos-node` | 使用共享构建制品的 macOS TypeScript 测试通道 | 与 macOS 相关的变更 | +| `macos-swift` | macOS 应用的 Swift lint、构建和测试 | 与 macOS 相关的变更 | +| `android` | Android 构建和测试矩阵 | 与 Android 相关的变更 | ## 快速失败顺序 -作业的排序方式是让低成本检查先失败，避免高成本作业继续运行： +作业的排列顺序经过设计，以便让廉价检查先失败，避免昂贵作业过早运行： -1. `preflight` 决定哪些通道实际存在。`docs-scope` 和 `changed-scope` 逻辑是该作业中的步骤，而不是独立作业。 -2. `security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，不必等待更重的制品和平台矩阵作业。 -3. `build-artifacts` 会与快速 Linux 通道并行运行，这样下游使用方可以在共享构建准备好后立即启动。 -4. 然后更重的平台和运行时通道会展开：`checks-fast-core`、`checks-fast-extensions`、`extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。 +1. `preflight` 决定哪些通道实际存在。`docs-scope` 和 `changed-scope` 逻辑是这个作业内部的步骤，不是独立作业。 +2. `security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，而不会等待更重的制品和平台矩阵作业。 +3. `build-artifacts` 会与快速 Linux 通道并行运行，这样下游使用方一旦共享构建准备好就可以立即开始。 +4. 更重的平台和运行时通道会在此之后展开：`checks-fast-core`、`checks-node-extensions`、`checks-node-core-test`、`extension-fast`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。 -作用域逻辑位于 `scripts/ci-changed-scope.mjs`，其单元测试位于 `src/scripts/ci-changed-scope.test.ts`。 -独立的 `install-smoke` 工作流也会通过它自己的 `preflight` 作业复用同一个作用域脚本。它会根据更窄的 changed-smoke 信号计算 `run_install_smoke`，因此 Docker/安装 smoke 只会在与安装、打包和容器相关的变更时运行。 +作用域逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。 +单独的 `install-smoke` 工作流会通过它自己的 `preflight` 作业复用同一个作用域脚本。它会基于更窄的 changed-smoke 信号计算 `run_install_smoke`，因此 Docker/安装冒烟测试只会在与安装、打包和容器相关的变更时运行。 -在 push 上，`checks` 矩阵会增加仅限 push 的 `compat-node22` 通道。在拉取请求上，该通道会被跳过，矩阵将继续专注于常规测试/渠道通道。 +在推送时，`checks` 矩阵会增加仅推送时运行的 `compat-node22` 通道。在拉取请求中，该通道会被跳过，矩阵会继续聚焦于常规测试/渠道通道。 ## 运行器 @@ -60,7 +61,7 @@ CI 会在每次推送到 `main` 以及每个拉取请求上运行。它使用智 | `blacksmith-32vcpu-windows-2025` | `checks-windows` | | `macos-latest` | `macos-node`、`macos-swift` | -## 本地对应命令 +## 本地等效项 ```bash pnpm check # 类型检查 + lint + 格式检查 @@ -69,6 +70,6 @@ pnpm check:import-cycles pnpm test:gateway:watch-regression pnpm test # vitest 测试 pnpm test:channels -pnpm check:docs # 文档格式 + lint + 失效链接检查 -pnpm build # 当 CI 制品/build-smoke 通道相关时构建 dist +pnpm check:docs # 文档格式 + lint + 损坏链接检查 +pnpm build # 当 CI 的 artifact/build-smoke 通道相关时，构建 dist ``` diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 97370318f..4dcdd8649 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -1,70 +1,70 @@ --- read_when: - 你需要精确到字段级别的配置语义或默认值 - - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值以及指向各专用子系统参考文档的链接 + - 你正在验证渠道、模型、Gateway 网关或工具配置块】【。 +summary: Gateway 网关配置参考，涵盖 OpenClaw 核心键名、默认值以及指向各专用子系统参考文档的链接 title: 配置参考 x-i18n: - generated_at: "2026-04-10T21:58:12Z" + generated_at: "2026-04-10T23:44:38Z" model: gpt-5.4 provider: openai - source_hash: a6ea88aeec8b9d5bcf9dd94844de4fa0d4981349452b61a0296417b8ee5840a0 + source_hash: 32acb82e756e4740d13ef12277842081f4c90df7b67850c34f8a76701fcd37d0 source_path: gateway/configuration-reference.md workflow: 15 --- # 配置参考 -`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参阅 [Configuration](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。若需按任务组织的概览，请参见 [Configuration](/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 表面验证配置文档基线哈希 +- `openclaw config schema` 会输出用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据 +- `config.schema.lookup` 会返回一个按路径限定范围的 schema 节点，供下钻工具使用 +- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面对配置文档基线哈希进行校验 -专用深入参考： +专用深度参考： - [Memory configuration reference](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 -- [Slash Commands](/zh-CN/tools/slash-commands)，适用于当前内置 + 内置插件命令目录 -- 对应渠道/插件页面，适用于渠道特定的命令表面 +- [Slash Commands](/zh-CN/tools/slash-commands)，查看当前内置 + 内置插件命令目录 +- 各自所属的渠道/插件页面，用于查看特定渠道的命令面 -配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的 —— OpenClaw 在省略时会使用安全默认值。 +配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全默认值。 --- ## 渠道 -每个渠道在其配置节存在时都会自动启动（除非设置了 `enabled: false`）。 +每个渠道在其配置段存在时都会自动启动（除非设置了 `enabled: false`）。 ### 私信和群组访问 所有渠道都支持私信策略和群组策略： -| 私信策略 | 行为 | -| ------------------- | ---- | +| 私信策略 | 行为 | +| ------------------- | -------------------------------------------- | | `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | | `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对允许存储中的发送者） | -| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有传入私信 | +| `open` | 允许所有入站私信（需要 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有入站私信 | -| 群组策略 | 行为 | -| --------------------- | ---- | -| `allowlist`（默认） | 仅允许与配置的允许列表匹配的群组 | -| `open` | 绕过群组允许列表（仍会应用提及门控） | -| `disabled` | 阻止所有群组/房间消息 | +| 群组策略 | 行为 | +| --------------------- | ---------------------------------------------- | +| `allowlist`（默认） | 仅允许与已配置允许列表匹配的群组 | +| `open` | 绕过群组允许列表（但仍会应用提及门控） | +| `disabled` | 阻止所有群组/房间消息 | -`channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时设定默认值。 +`channels.defaults.groupPolicy` 会在某个提供商的 `groupPolicy` 未设置时作为默认值。 配对码会在 1 小时后过期。待处理的私信配对请求每个渠道最多 **3 个**。 -如果某个提供商配置块完全缺失（`channels.` 不存在），运行时群组策略会回退为 `allowlist`（默认拒绝），并在启动时发出警告。 +如果某个提供商配置块完全缺失（即不存在 `channels.`），运行时群组策略会回退为 `allowlist`（默认拒绝，失败关闭），并在启动时发出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值可接受 `provider/model` 或已配置的模型别名。当某个会话尚未已有模型覆盖时（例如通过 `/model` 设置），会应用渠道映射。 +使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值可接受 `provider/model` 或已配置的模型别名。当某个会话尚未拥有模型覆盖时（例如通过 `/model` 设置），会应用该渠道映射。 ```json5 { @@ -105,15 +105,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时使用的回退群组策略。 -- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。按渠道覆盖：`channels..contextVisibility`。 -- `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。 +- `channels.defaults.groupPolicy`：当提供商级别的 `groupPolicy` 未设置时使用的回退群组策略。 +- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。可选值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。按渠道覆盖：`channels..contextVisibility`。 +- `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康的渠道状态。 - `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 - `channels.defaults.heartbeat.useIndicator`：以紧凑的指示器样式渲染心跳输出。 ### WhatsApp -WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已链接会话时会自动启动。 +WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在已链接会话时，它会自动启动。 ```json5 { @@ -164,8 +164,8 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 出站命令默认使用账号 `default`（如果存在）；否则使用第一个已配置的账号 ID（按排序结果）。 -- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖该回退默认账号选择。 +- 出站命令默认使用 `default` 账号（如果存在）；否则使用第一个已配置的账号 id（按排序顺序）。 +- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配某个已配置账号 id 时，覆盖上述默认账号选择回退逻辑。 - 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 - 按账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -202,7 +202,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress（默认：off；需显式启用以避免预览编辑速率限制） + streaming: "partial", // off | partial | block | progress（默认：off；建议显式启用，以避免预览编辑速率限制） actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -225,12 +225,12 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅允许常规文件；拒绝符号链接），并以 `TELEGRAM_BOT_TOKEN` 作为默认账号的回退值。 -- 可选的 `channels.telegram.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 -- 在多账号设置中（2 个或更多账号 ID），请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`），以避免回退路由；当该项缺失或无效时，`openclaw doctor` 会发出警告。 +- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅允许普通文件；拒绝符号链接），默认账号还可回退为 `TELEGRAM_BOT_TOKEN`。 +- 可选的 `channels.telegram.defaultAccount` 会在其匹配某个已配置账号 id 时覆盖默认账号选择。 +- 在多账号配置（2 个及以上账号 id）中，请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；如果缺失或无效，`openclaw doctor` 会发出警告。 - `configWrites: false` 会阻止由 Telegram 发起的配置写入（supergroup ID 迁移、`/config set|unset`）。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目会为论坛主题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享定义。 -- Telegram 流式预览使用 `sendMessage` + `editMessageText`（在私聊和群聊中均可工作）。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目用于为 forum topics 配置持久化 ACP 绑定（在 `match.peer.id` 中使用规范形式 `chatId:topic:topicId`）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中一致。 +- Telegram 流式预览使用 `sendMessage` + `editMessageText`（在私聊和群聊中均可用）。 - 重试策略：参见 [Retry policy](/zh-CN/concepts/retry)。 ### Discord @@ -286,7 +286,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress（在 Discord 上 progress 会映射为 partial） + streaming: "off", // off | partial | block | progress（在 Discord 上，progress 会映射为 partial） maxLinesPerMessage: 17, ui: { components: { @@ -297,7 +297,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // 为 sessions_spawn({ thread: true }) 显式启用 + spawnSubagentSessions: false, // 对 `sessions_spawn({ thread: true })` 的显式启用 }, voice: { enabled: true, @@ -333,36 +333,36 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- Token：`channels.discord.token`，并以 `DISCORD_BOT_TOKEN` 作为默认账号的回退值。 -- 提供显式 Discord `token` 的直接出站调用会使用该 token 完成调用；账号重试/策略设置仍来自活动运行时快照中选定的账号。 -- 可选的 `channels.discord.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 -- 使用 `user:`（私信）或 `channel:`（服务器渠道）作为投递目标；裸数字 ID 会被拒绝。 -- 服务器 slug 为小写，空格替换为 `-`；渠道键使用 slug 化名称（不含 `#`）。优先使用服务器 ID。 -- 默认会忽略由机器人发布的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 则只接受提及该机器人的机器人消息（机器人自己的消息仍会被过滤）。 -- `channels.discord.guilds..ignoreOtherMentions`（以及渠道级覆盖）会丢弃提及了其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。 -- `maxLinesPerMessage`（默认 17）会拆分行数过多的消息，即使其未超过 2000 个字符。 +- Token：`channels.discord.token`，默认账号还可回退为 `DISCORD_BOT_TOKEN`。 +- 对于直接出站调用，如果显式提供了 Discord `token`，该次调用会使用该 token；但账号重试/策略设置仍来自活动运行时快照中所选账号。 +- 可选的 `channels.discord.defaultAccount` 会在其匹配某个已配置账号 id 时覆盖默认账号选择。 +- 投递目标请使用 `user:`（私信）或 `channel:`（guild 渠道）；裸数字 ID 会被拒绝。 +- Guild slug 使用小写，并将空格替换为 `-`；渠道键使用 slug 化后的名称（不带 `#`）。优先使用 guild ID。 +- 默认会忽略由 bot 自己创作的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 则只接受提及该 bot 的 bot 消息（自身消息仍会被过滤）。 +- `channels.discord.guilds..ignoreOtherMentions`（以及渠道级覆盖）会丢弃那些提及了其他用户或角色、但未提及该 bot 的消息（不包括 @everyone/@here）。 +- `maxLinesPerMessage`（默认 17）会拆分过高的消息，即使其长度未超过 2000 个字符。 - `channels.discord.threadBindings` 控制 Discord 线程绑定路由： - - `enabled`：线程绑定会话功能的 Discord 覆盖项（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由） - - `idleHours`：按小时计的 Discord 非活动自动取消聚焦覆盖项（`0` 表示禁用） - - `maxAgeHours`：按小时计的 Discord 硬性最大时长覆盖项（`0` 表示禁用） + - `enabled`：Discord 对线程绑定会话功能的覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及绑定投递/路由） + - `idleHours`：Discord 对按小时计算的无活动自动取消聚焦的覆盖（`0` 表示禁用） + - `maxAgeHours`：Discord 对按小时计算的硬性最大时长的覆盖（`0` 表示禁用） - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程的显式启用开关 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目会为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 ID）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享定义。 -- `channels.discord.ui.components.accentColor` 为 Discord components v2 容器设置强调色。 -- `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入 + TTS 覆盖项。 -- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传到 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 -- OpenClaw 还会在重复解密失败后通过离开/重新加入语音会话来尝试恢复语音接收。 -- `channels.discord.streaming` 是规范的流式传输模式键。旧版 `streamMode` 和布尔型 `streaming` 值会被自动迁移。 -- `channels.discord.autoPresence` 将运行时可用性映射为机器人在线状态（健康 => online，降级 => idle，资源耗尽 => dnd），并允许可选的状态文本覆盖。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目用于为渠道和线程配置持久化 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 id）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中一致。 +- `channels.discord.ui.components.accentColor` 用于设置 Discord components v2 容器的强调色。 +- `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入 + TTS 覆盖。 +- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 +- OpenClaw 还会在重复解密失败后，通过离开并重新加入语音会话来尝试恢复语音接收。 +- `channels.discord.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔型 `streaming` 值会被自动迁移。 +- `channels.discord.autoPresence` 会将运行时可用性映射到 bot 在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 - `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（破窗兼容模式）。 -- `channels.discord.execApprovals`：Discord 原生 exec 审批投递和审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。 - - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时会回退到 `commands.ownerAllowFrom`。 +- `channels.discord.execApprovals`：Discord 原生的 exec 审批投递和审批人授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。 + - `approvers`：允许审批 exec 请求的 Discord 用户 ID。省略时回退为 `commands.ownerAllowFrom`。 - `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的审批。 - - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：审批提示的发送位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到发起渠道，`"both"` 两者都发送。当目标包含 `"channel"` 时，按钮仅对已解析出的审批人可用。 - - `cleanupAfterResolve`：为 `true` 时，在批准、拒绝或超时后删除审批私信。 + - `sessionFilter`：可选的会话键模式（子字符串或正则表达式）。 + - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到发起渠道，`"both"` 两处都发。若 target 包含 `"channel"`，按钮仅对已解析出的审批人可用。 + - `cleanupAfterResolve`：设为 `true` 时，在批准、拒绝或超时后删除审批私信。 -**Reaction notification modes：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（`guilds..users` 中用户发送的所有消息）。 +**Reaction notification 模式：** `off`（无）、`own`（bot 自己的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users`，应用于所有消息）。 ### Google Chat @@ -393,11 +393,11 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 服务账号 JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 +- 服务账号 JSON：支持内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 - 也支持服务账号 SecretRef（`serviceAccountRef`）。 -- 环境变量回退值：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 使用 `spaces/` 或 `users/` 作为投递目标。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变邮箱主体匹配（破窗兼容模式）。 +- 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 +- 投递目标请使用 `spaces/` 或 `users/`。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变 email principal 匹配（破窗兼容模式）。 ### Slack @@ -449,7 +449,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // 当 mode=partial 时使用 Slack 原生流式传输 API + nativeTransport: true, // 当 mode=partial 时使用 Slack 原生流式 API }, mediaMaxMb: 20, execApprovals: { @@ -464,30 +464,30 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号的环境变量回退值为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP mode** 需要 `botToken` 加 `signingSecret`（可位于根级或账号级）。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 可接受明文字符串或 SecretRef 对象。 -- Slack 账号快照会暴露按凭证划分的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 下的 `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef 进行配置，但当前命令/运行时路径无法解析该 secret 值。 +- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号的环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP mode** 需要 `botToken` 加 `signingSecret`（可位于根级或按账号设置）。 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。 +- Slack 账号快照会暴露按凭据划分的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef 配置，但当前命令/运行时路径无法解析该 secret 值。 - `configWrites: false` 会阻止由 Slack 发起的配置写入。 -- 可选的 `channels.slack.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 -- `channels.slack.streaming.mode` 是规范的 Slack 流式传输模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输协议。旧版 `streamMode`、布尔型 `streaming` 和 `nativeStreaming` 值会被自动迁移。 -- 使用 `user:`（私信）或 `channel:` 作为投递目标。 +- 可选的 `channels.slack.defaultAccount` 会在其匹配某个已配置账号 id 时覆盖默认账号选择。 +- `channels.slack.streaming.mode` 是规范的 Slack 流模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版 `streamMode`、布尔型 `streaming` 和 `nativeStreaming` 值会被自动迁移。 +- 投递目标请使用 `user:`（私信）或 `channel:`。 -**Reaction notification modes：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**Reaction notification 模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 可设为每线程（默认）或全渠道共享。`thread.inheritParent` 会将父渠道的对话记录复制到新线程中。 +**线程会话隔离：** `thread.historyScope` 为按线程隔离（默认）或在整个渠道中共享。`thread.inheritParent` 会将父渠道的转录复制到新线程。 -- Slack 原生流式传输加上 Slack 助手样式的“正在输入...”线程状态需要以回复线程为目标。顶层私信默认保持无线程，因此会使用 `typingReaction` 或正常投递，而不是线程样式预览。 -- `typingReaction` 会在回复运行期间向传入的 Slack 消息添加临时 reaction，并在完成后移除。请使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 -- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批人授权。schema 与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 +- Slack 原生流式传输加上 Slack 助手风格的 “is typing...” 线程状态，需要一个回复线程目标。顶层私信默认保持非线程模式，因此会使用 `typingReaction` 或普通投递，而不是线程式预览。 +- `typingReaction` 会在回复运行期间向入站 Slack 消息添加一个临时 reaction，并在完成后移除。请使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 +- `channels.slack.execApprovals`：Slack 原生的 exec 审批投递和审批人授权。与 Discord 使用相同 schema：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 -| 操作组 | 默认值 | 说明 | -| ------------ | ------- | ---------------------- | -| reactions | 启用 | 添加 reaction + 列出 reactions | -| messages | 启用 | 读取/发送/编辑/删除 | -| pins | 启用 | 置顶/取消置顶/列出 | -| memberInfo | 启用 | 成员信息 | -| emojiList | 启用 | 自定义 emoji 列表 | +| 操作组 | 默认值 | 说明 | +| ------------ | -------- | -------------------- | +| reactions | 已启用 | 添加 reaction + 列出 reactions | +| messages | 已启用 | 读取/发送/编辑/删除 | +| pins | 已启用 | 固定/取消固定/列出 | +| memberInfo | 已启用 | 成员信息 | +| emojiList | 已启用 | 自定义 emoji 列表 | ### Mattermost @@ -511,7 +511,7 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos native: true, // 显式启用 nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // 面向反向代理/公共部署的可选显式 URL + // 面向反向代理/公网部署的可选显式 URL callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -521,18 +521,18 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos } ``` -聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（响应以触发前缀开头的消息）。 +聊天模式：`oncall`（在 @ 提及时回复，默认）、`onmessage`（每条消息都回复）、`onchar`（以触发前缀开头的消息）。 启用 Mattermost 原生命令时： - `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 -- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器可以访问。 -- 原生斜杠命令回调使用 Mattermost 在注册斜杠命令期间返回的按命令划分 token 进行认证。如果注册失败或没有已激活命令，OpenClaw 会以 `Unauthorized: invalid command token.` 拒绝回调。 -- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。请使用主机/域名值，而不是完整 URL。 +- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器能够访问。 +- 原生 slash 回调使用 Mattermost 在注册 slash 命令期间返回的逐命令 token 进行认证。如果注册失败或没有激活任何命令，OpenClaw 会以 `Unauthorized: invalid command token.` 拒绝回调。 +- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机/域名。请使用主机/域名值，而不是完整 URL。 - `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。 - `channels.mattermost.requireMention`：在渠道中回复前要求 `@mention`。 -- `channels.mattermost.groups..requireMention`：按渠道设置的提及门控覆盖（`"*"` 表示默认值）。 -- 可选的 `channels.mattermost.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 +- `channels.mattermost.groups..requireMention`：按渠道覆盖提及门控（`"*"` 表示默认值）。 +- 可选的 `channels.mattermost.defaultAccount` 会在其匹配某个已配置账号 id 时覆盖默认账号选择。 ### Signal @@ -553,15 +553,15 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos } ``` -**Reaction notification modes：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**Reaction notification 模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -- `channels.signal.account`：将渠道启动固定到特定的 Signal 账号标识。 +- `channels.signal.account`：将渠道启动固定到特定的 Signal 账号身份。 - `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。 -- 可选的 `channels.signal.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 +- 可选的 `channels.signal.defaultAccount` 会在其匹配某个已配置账号 id 时覆盖默认账号选择。 ### BlueBubbles -BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `channels.bluebubbles` 下）。 +BlueBubbles 是推荐的 iMessage 路径（插件支持，配置位于 `channels.bluebubbles` 下）。 ```json5 { @@ -577,13 +577,13 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `chann ``` - 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 可选的 `channels.bluebubbles.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目可将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 可选的 `channels.bluebubbles.defaultAccount` 会在其匹配某个已配置账号 id 时覆盖默认账号选择。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可以将 BlueBubbles 会话绑定到持久化 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或 target 字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 - 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。 ### iMessage -OpenClaw 会生成 `imsg rpc`（基于 stdio 的 JSON-RPC）。不需要守护进程或端口。 +OpenClaw 会生成 `imsg rpc`（基于 stdio 的 JSON-RPC）。无需守护进程或端口。 ```json5 { @@ -607,17 +607,17 @@ OpenClaw 会生成 `imsg rpc`（基于 stdio 的 JSON-RPC）。不需要守护 } ``` -- 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 +- 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账号 id 时覆盖默认账号选择。 -- 需要对 Messages 数据库授予完全磁盘访问权限。 +- 需要对 Messages 数据库授予 Full Disk Access。 - 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可指向 SSH 包装脚本；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。 -- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制传入附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 -- SCP 使用严格的主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 +- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以便通过 SCP 获取附件。 +- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制入站附件路径（默认值：`/Users/*/Library/Messages/Attachments`）。 +- SCP 使用严格的 host-key 检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 - `channels.imessage.configWrites`：允许或拒绝由 iMessage 发起的配置写入。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目可将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用标准化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可以将 iMessage 会话绑定到持久化 ACP 会话。在 `match.peer.id` 中使用规范化后的 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 - + ```bash #!/usr/bin/env bash @@ -628,7 +628,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix 由扩展提供支持，并配置在 `channels.matrix` 下。 +Matrix 由扩展支持，配置位于 `channels.matrix` 下。 ```json5 { @@ -660,23 +660,23 @@ Matrix 由扩展提供支持，并配置在 `channels.matrix` 下。 - Token 认证使用 `accessToken`；密码认证使用 `userId` + `password`。 - `channels.matrix.proxy` 会通过显式 HTTP(S) 代理转发 Matrix HTTP 流量。命名账号可通过 `channels.matrix.accounts..proxy` 覆盖它。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 与该网络显式启用项是相互独立的控制项。 -- `channels.matrix.defaultAccount` 在多账号设置中选择首选账号。 -- `channels.matrix.autoJoin` 默认为 `off`，因此被邀请的房间和新的私信式邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。 -- `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递和审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。 - - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 与此网络显式启用项是相互独立的控制项。 +- `channels.matrix.defaultAccount` 在多账号配置中选择首选账号。 +- `channels.matrix.autoJoin` 默认为 `off`，因此在你设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，或设置 `autoJoin: "always"` 之前，受邀房间和新的私信式邀请都会被忽略。 +- `channels.matrix.execApprovals`：Matrix 原生的 exec 审批投递和审批人授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。 + - `approvers`：允许审批 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的审批。 - - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：审批提示的发送位置。`"dm"`（默认）、`"channel"`（发起房间）或 `"both"`。 + - `sessionFilter`：可选的会话键模式（子字符串或正则表达式）。 + - `target`：发送审批提示的位置。`"dm"`（默认）、`"channel"`（发起房间）或 `"both"`。 - 按账号覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组为会话：`per-user`（默认）按路由对端共享，而 `per-room` 会隔离每个私信房间。 -- Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 +- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归组到会话中：`per-user`（默认）按路由对端共享，而 `per-room` 会隔离每个私信房间。 +- Matrix 状态探测和在线目录查找与运行时流量使用相同的代理策略。 - 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 ### Microsoft Teams -Microsoft Teams 由扩展提供支持，并配置在 `channels.msteams` 下。 +Microsoft Teams 由扩展支持，配置位于 `channels.msteams` 下。 ```json5 { @@ -692,11 +692,11 @@ Microsoft Teams 由扩展提供支持，并配置在 `channels.msteams` 下。 ``` - 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 -- 完整的 Teams 配置（凭证、webhook、私信/群组策略、按团队/按渠道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 +- 完整的 Teams 配置（凭据、webhook、私信/群组策略、按团队/按渠道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 ### IRC -IRC 由扩展提供支持，并配置在 `channels.irc` 下。 +IRC 由扩展支持，配置位于 `channels.irc` 下。 ```json5 { @@ -718,8 +718,8 @@ IRC 由扩展提供支持，并配置在 `channels.irc` 下。 ``` - 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可选的 `channels.irc.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 -- 完整的 IRC 渠道配置（主机/端口/TLS/渠道/允许列表/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 +- 可选的 `channels.irc.defaultAccount` 会在其匹配某个已配置账号 id 时覆盖默认账号选择。 +- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/mention gating）记录在 [IRC](/zh-CN/channels/irc) 中。 ### 多账号（所有渠道） @@ -744,28 +744,28 @@ IRC 由扩展提供支持，并配置在 `channels.irc` 下。 } ``` -- 当省略 `accountId` 时，将使用 `default`（CLI + 路由）。 +- 当省略 `accountId` 时，会使用 `default`（CLI + 路由）。 - 环境变量 token 仅适用于 **default** 账号。 -- 基础渠道设置会应用到所有账号，除非在账号级别覆盖。 -- 使用 `bindings[].match.accountId` 将每个账号路由到不同的智能体。 -- 如果你在仍为单账号顶层渠道配置的情况下，通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，OpenClaw 会先将具备账号作用域的顶层单账号值提升到该渠道的账号映射中，以便原账号继续正常工作。大多数渠道会将它们移到 `channels..accounts.default`；Matrix 则可保留已有的匹配命名/默认目标。 -- 现有仅渠道级的绑定（无 `accountId`）将继续匹配默认账号；账号级绑定仍然是可选的。 -- `openclaw doctor --fix` 也会通过将具备账号作用域的顶层单账号值移动到为该渠道选择的提升后账号中，来修复混合形状。大多数渠道使用 `accounts.default`；Matrix 则可保留已有的匹配命名/默认目标。 +- 基础渠道设置会应用于所有账号，除非按账号覆盖。 +- 使用 `bindings[].match.accountId` 可将每个账号路由到不同的智能体。 +- 如果你在仍处于单账号顶层渠道配置时，通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，OpenClaw 会先将按账号作用域的顶层单账号值提升到该渠道账号映射中，以便原账号继续工作。大多数渠道会将其移动到 `channels..accounts.default`；而 Matrix 则可以改为保留现有匹配的命名/default 目标。 +- 现有仅渠道级的绑定（无 `accountId`）仍会匹配 default 账号；按账号作用域的绑定仍然是可选的。 +- `openclaw doctor --fix` 也会通过将按账号作用域的顶层单账号值移动到为该渠道选定的提升后账号中，来修复混合形态。大多数渠道使用 `accounts.default`；Matrix 则可以改为保留现有匹配的命名/default 目标。 ### 其他扩展渠道 -许多扩展渠道都配置为 `channels.`，并记录在各自专用的渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 -请参阅完整渠道索引： [Channels](/zh-CN/channels)。 +许多扩展渠道都配置为 `channels.`，并在各自专用的渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 +请参见完整渠道索引： [Channels](/zh-CN/channels)。 ### 群聊提及门控 -群组消息默认 **需要提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 +群组消息默认**要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 **提及类型：** - **元数据提及**：原生平台 @ 提及。在 WhatsApp self-chat 模式下会被忽略。 - **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 仅在能够检测提及的情况下（原生提及或至少一个模式）才会强制执行提及门控。 +- 仅当能够检测提及时（原生提及或至少一个模式）才会强制执行提及门控。 ```json5 { @@ -778,9 +778,9 @@ IRC 由扩展提供支持，并配置在 `channels.irc` 下。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号）覆盖。设为 `0` 可禁用。 +`messages.groupChat.historyLimit` 用于设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号）覆盖。设为 `0` 可禁用。 -#### 私信历史记录限制 +#### 私信历史限制 ```json5 { @@ -801,7 +801,7 @@ IRC 由扩展提供支持，并配置在 `channels.irc` 下。 #### self-chat 模式 -在 `allowFrom` 中包含你自己的号码即可启用 self-chat 模式（忽略原生 @ 提及，仅响应文本模式）： +将你自己的号码加入 `allowFrom` 以启用 self-chat 模式（忽略原生 @ 提及，仅响应文本模式）： ```json5 { @@ -822,14 +822,14 @@ IRC 由扩展提供支持，并配置在 `channels.irc` 下。 } ``` -### 命令（聊天命令处理） +### Commands（聊天命令处理） ```json5 { commands: { native: "auto", // 在支持时注册原生命令 nativeSkills: "auto", // 在支持时注册原生 Skills 命令 - text: true, // 在聊天消息中解析 /commands + text: true, // 解析聊天消息中的 /commands bash: false, // 允许 !（别名：/bash） bashForegroundMs: 2000, config: false, // 允许 /config @@ -851,32 +851,32 @@ IRC 由扩展提供支持，并配置在 `channels.irc` 下。 -- 此配置块用于配置命令表面。当前内置 + 内置插件命令目录请参阅 [Slash Commands](/zh-CN/tools/slash-commands)。 -- 本页是**配置键**参考，不是完整命令目录。由渠道/插件拥有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、device-pair `/pair`、memory `/dreaming`、phone-control `/phone` 和 Talk `/voice`，记录在各自的渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。 +- 此配置块用于设置命令面。当前内置 + 内置插件命令目录请参见 [Slash Commands](/zh-CN/tools/slash-commands)。 +- 本页是**配置键参考**，不是完整命令目录。诸如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、device-pair `/pair`、memory `/dreaming`、phone-control `/phone` 和 Talk `/voice` 等渠道/插件自有命令，记录在其各自的渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。 - 文本命令必须是带前导 `/` 的**独立**消息。 -- `native: "auto"` 会为 Discord/Telegram 启用原生命令，Slack 保持关闭。 -- `nativeSkills: "auto"` 会为 Discord/Telegram 启用原生 Skills 命令，Slack 保持关闭。 -- 可按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前已注册的命令。 -- 使用 `channels..commands.nativeSkills` 按渠道覆盖原生 Skills 命令注册。 -- `channels.telegram.customCommands` 会添加额外的 Telegram 机器人菜单项。 -- `bash: true` 会为主机 shell 启用 `! `。要求 `tools.elevated.enabled` 已启用，且发送者位于 `tools.elevated.allowFrom.` 中。 -- `config: true` 会启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化的 `/config set|unset` 写入还需要 `operator.admin`；只读的 `/config show` 对普通写入作用域的 operator 客户端仍然可用。 -- `mcp: true` 会为 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。 -- `plugins: true` 会为插件发现、安装以及启用/禁用控制启用 `/plugins`。 +- `native: "auto"` 会为 Discord/Telegram 启用原生命令，对 Slack 则保持关闭。 +- `nativeSkills: "auto"` 会为 Discord/Telegram 启用原生 Skills 命令，对 Slack 则保持关闭。 +- 可按渠道覆盖：`channels.discord.commands.native`（bool 或 `"auto"`）。`false` 会清除先前已注册的命令。 +- 可通过 `channels..commands.nativeSkills` 按渠道覆盖原生技能命令注册。 +- `channels.telegram.customCommands` 会添加额外的 Telegram bot 菜单项。 +- `bash: true` 会为主机 shell 启用 `! `。需要 `tools.elevated.enabled`，且发送者位于 `tools.elevated.allowFrom.` 中。 +- `config: true` 会启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化 `/config set|unset` 写入还需要 `operator.admin`；只读的 `/config show` 对普通写作用域 operator 客户端仍然可用。 +- `mcp: true` 会为位于 `mcp.servers` 下、由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。 +- `plugins: true` 会启用 `/plugins`，用于插件发现、安装以及启用/禁用控制。 - `channels..configWrites` 按渠道控制配置变更（默认：true）。 -- 对于多账号渠道，`channels..accounts..configWrites` 也会控制以该账号为目标的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 +- 对于多账号渠道，`channels..accounts..configWrites` 也会控制针对该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 - `restart: false` 会禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。 -- `ownerAllowFrom` 是 owner 专用命令/工具的显式 owner 允许列表。它与 `allowFrom` 分离。 -- `ownerDisplay: "hash"` 会在系统提示中对 owner ID 进行哈希。设置 `ownerDisplaySecret` 可控制哈希方式。 -- `allowFrom` 是按提供商设置的。设置后，它将成为**唯一**的授权来源（渠道允许列表/配对以及 `useAccessGroups` 会被忽略）。 +- `ownerAllowFrom` 是 owner-only 命令/工具的显式 owner 允许列表。它独立于 `allowFrom`。 +- `ownerDisplay: "hash"` 会在系统提示中对 owner id 进行哈希。设置 `ownerDisplaySecret` 可控制哈希。 +- `allowFrom` 是按提供商划分的。设置后，它将成为**唯一**授权来源（会忽略渠道 allowlist/pairing 和 `useAccessGroups`）。 - `useAccessGroups: false` 会在未设置 `allowFrom` 时允许命令绕过访问组策略。 - 命令文档映射： - - 内置 + 内置插件目录：[Slash Commands](/zh-CN/tools/slash-commands) - - 渠道特定命令表面：[Channels](/zh-CN/channels) - - QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot) - - 配对命令：[Pairing](/zh-CN/channels/pairing) - - LINE card 命令：[LINE](/zh-CN/channels/line) - - memory dreaming：[Dreaming](/zh-CN/concepts/dreaming) + - 内置 + 内置插件目录： [Slash Commands](/zh-CN/tools/slash-commands) + - 渠道专用命令面： [Channels](/zh-CN/channels) + - QQ Bot 命令： [QQ Bot](/zh-CN/channels/qqbot) + - 配对命令： [Pairing](/zh-CN/channels/pairing) + - LINE card 命令： [LINE](/zh-CN/channels/line) + - memory dreaming： [Dreaming](/zh-CN/concepts/dreaming) @@ -896,7 +896,7 @@ IRC 由扩展提供支持，并配置在 `channels.irc` 下。 ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示的 Runtime 行中。若未设置，OpenClaw 会从 workspace 向上遍历自动检测。 +可选的仓库根目录，会显示在系统提示的 Runtime 行中。如果未设置，OpenClaw 会从 workspace 开始向上遍历自动检测。 ```json5 { @@ -906,7 +906,7 @@ IRC 由扩展提供支持，并配置在 `channels.irc` 下。 ### `agents.defaults.skills` -为未设置 `agents.list[].skills` 的智能体提供可选的默认 Skills 允许列表。 +为未设置 `agents.list[].skills` 的智能体提供可选的默认技能 allowlist。 ```json5 { @@ -921,10 +921,10 @@ IRC 由扩展提供支持，并配置在 `channels.irc` 下。 } ``` -- 省略 `agents.defaults.skills` 表示默认 Skills 不受限制。 +- 省略 `agents.defaults.skills` 表示默认不限制 Skills。 - 省略 `agents.list[].skills` 表示继承默认值。 - 设置 `agents.list[].skills: []` 表示不启用任何 Skills。 -- 非空的 `agents.list[].skills` 列表是该智能体的最终集合；它不会与默认值合并。 +- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。 ### `agents.defaults.skipBootstrap` @@ -940,7 +940,7 @@ IRC 由扩展提供支持，并配置在 `channels.irc` 下。 控制何时将 workspace bootstrap 文件注入系统提示。默认值：`"always"`。 -- `"continuation-skip"`：安全续接轮次（在 assistant 完成响应之后）会跳过重新注入 workspace bootstrap，从而减少提示大小。heartbeat 运行和压缩后重试仍会重建上下文。 +- `"continuation-skip"`：安全续接回合（在 assistant 完成响应之后）会跳过 workspace bootstrap 的重新注入，从而减少提示大小。Heartbeat 运行和压缩后的重试仍会重建上下文。 ```json5 { @@ -950,7 +950,7 @@ IRC 由扩展提供支持，并配置在 `channels.irc` 下。 ### `agents.defaults.bootstrapMaxChars` -每个 workspace bootstrap 文件在截断前允许的最大字符数。默认值：`20000`。 +单个 workspace bootstrap 文件在截断前允许的最大字符数。默认值：`20000`。 ```json5 { @@ -970,11 +970,11 @@ IRC 由扩展提供支持，并配置在 `channels.irc` 下。 ### `agents.defaults.bootstrapPromptTruncationWarning` -控制在 bootstrap 上下文被截断时，向智能体可见的警告文本。默认值：`"once"`。 +控制在 bootstrap 上下文被截断时，对智能体可见的警告文本。默认值：`"once"`。 -- `"off"`：绝不将警告文本注入系统提示。 -- `"once"`：每个唯一的截断签名仅注入一次警告（推荐）。 -- `"always"`：只要存在截断，就在每次运行时注入警告。 +- `"off"`：绝不向系统提示注入警告文本。 +- `"once"`：每个唯一截断签名仅注入一次警告（推荐）。 +- `"always"`：只要存在截断，就在每次运行时都注入警告。 ```json5 { @@ -984,10 +984,10 @@ IRC 由扩展提供支持，并配置在 `channels.irc` 下。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，对 transcript/tool 图像块中图像最长边允许的最大像素尺寸。 +在调用提供商之前，转录/工具图像块中图像最长边允许的最大像素尺寸。 默认值：`1200`。 -较低的值通常会减少 vision token 使用量和以截图为主的运行中的请求负载大小。 +较低的值通常会降低 vision token 使用量以及以截图为主的运行请求负载大小。 较高的值则会保留更多视觉细节。 ```json5 @@ -998,7 +998,7 @@ IRC 由扩展提供支持，并配置在 `channels.irc` 下。 ### `agents.defaults.userTimezone` -用于系统提示上下文的时区（不影响消息时间戳）。会回退到主机时区。 +用于系统提示上下文的时区（不影响消息时间戳）。未设置时会回退为主机时区。 ```json5 { @@ -1008,7 +1008,7 @@ IRC 由扩展提供支持，并配置在 `channels.irc` 下。 ### `agents.defaults.timeFormat` -系统提示中的时间格式。默认值：`auto`（操作系统偏好）。 +系统提示中的时间格式。默认值：`auto`（OS 偏好）。 ```json5 { @@ -1065,47 +1065,47 @@ IRC 由扩展提供支持，并配置在 `channels.irc` 下。 } ``` -- `model`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 +- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 字符串形式仅设置主模型。 - - 对象形式设置主模型以及按顺序排列的故障转移模型。 -- `imageModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 作为 `image` 工具路径的视觉模型配置使用。 - - 当选定/默认模型无法接受图像输入时，也用作回退路由。 -- `imageGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于共享的图像生成能力，以及任何未来会生成图像的工具/插件表面。 - - 典型值：`google/gemini-3.1-flash-image-preview`（Gemini 原生图像生成）、`fal/fal-ai/flux/dev`（fal），或 `openai/gpt-image-1`（OpenAI Images）。 - - 如果你直接选择某个提供商/模型，也要配置对应的提供商认证/API key（例如 `google/*` 对应 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 对应 `OPENAI_API_KEY`，`fal/*` 对应 `FAL_KEY`）。 - - 如果省略，`image_generate` 仍可推断出带认证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。 -- `musicGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于共享的音乐生成能力和内置 `music_generate` 工具。 - - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview`，或 `minimax/music-2.5+`。 - - 如果省略，`music_generate` 仍可推断出带认证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。 - - 如果你直接选择某个提供商/模型，也要配置对应的提供商认证/API key。 -- `videoGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于共享的视频生成能力和内置 `video_generate` 工具。 - - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash`，或 `qwen/wan2.7-r2v`。 - - 如果省略，`video_generate` 仍可推断出带认证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。 - - 如果你直接选择某个提供商/模型，也要配置对应的提供商认证/API key。 - - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 -- `pdfModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于 `pdf` 工具的模型路由。 - - 如果省略，PDF 工具会先回退到 `imageModel`，再回退到已解析的会话/默认模型。 -- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具使用的默认 PDF 大小限制。 -- `pdfMaxPages`：`pdf` 工具在提取回退模式下考虑的默认最大页数。 -- `verboseDefault`：智能体的默认详细程度。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 -- `elevatedDefault`：智能体的默认 elevated-output 级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 -- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 ID 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此更推荐显式使用 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露一个过时的、已移除提供商默认值。 -- `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 -- `params`：应用于所有模型的全局默认提供商参数。设置于 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 -- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配的智能体 ID）再按键覆盖。详情请参阅 [Prompt Caching](/zh-CN/reference/prompt-caching)。 -- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。使用 `runtime: "auto"` 让已注册的插件 harness 认领其支持的模型，使用 `runtime: "pi"` 强制使用内置 PI harness，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 PI 回退。 -- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及添加/移除回退模型的命令）会保存为规范对象形式，并在可能时保留现有回退列表。 -- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话本身仍会串行化）。默认值：4。 + - 对象形式设置主模型以及有序故障转移模型。 +- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由 `image` 工具路径作为其视觉模型配置使用。 + - 当已选/默认模型无法接受图像输入时，也会作为回退路由使用。 +- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由共享图像生成功能以及任何未来会生成图像的工具/插件面使用。 + - 典型值：`google/gemini-3.1-flash-image-preview`（用于原生 Gemini 图像生成）、`fal/fal-ai/flux/dev`（用于 fal）或 `openai/gpt-image-1`（用于 OpenAI Images）。 + - 如果你直接选择提供商/模型，也请配置匹配的提供商凭证/API key（例如 `google/*` 对应 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 对应 `OPENAI_API_KEY`，`fal/*` 对应 `FAL_KEY`）。 + - 如果省略，`image_generate` 仍可推断出有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的图像生成提供商。 +- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由共享音乐生成功能和内置 `music_generate` 工具使用。 + - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 + - 如果省略，`music_generate` 仍可推断出有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的音乐生成提供商。 + - 如果你直接选择提供商/模型，也请配置匹配的提供商凭证/API key。 +- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由共享视频生成功能和内置 `video_generate` 工具使用。 + - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 + - 如果省略，`video_generate` 仍可推断出有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的视频生成提供商。 + - 如果你直接选择提供商/模型，也请配置匹配的提供商凭证/API key。 + - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 +- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由 `pdf` 工具用于模型路由。 + - 如果省略，PDF 工具会依次回退到 `imageModel`，再回退到已解析的会话/默认模型。 +- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。 +- `pdfMaxPages`：`pdf` 工具在提取回退模式下默认考虑的最大页数。 +- `verboseDefault`：智能体的默认详细级别。可选值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 +- `elevatedDefault`：智能体的默认 elevated-output 级别。可选值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 +- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试精确匹配该模型 id 的唯一已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此更推荐显式写成 `provider/model`）。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是继续暴露一个陈旧、已移除提供商的默认值。 +- `models`：为 `/model` 配置的模型目录和 allowlist。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商专用，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 +- `params`：应用于所有模型的全局默认提供商参数。设置位置为 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 +- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配的智能体 id）再按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 +- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。使用 `runtime: "auto"` 可让已注册插件 harness 接管其支持的模型，使用 `runtime: "pi"` 可强制使用内置 PI harness，或使用已注册 harness id，如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 PI 回退。 +- 会变更这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退项添加/删除命令）会保存规范对象形式，并在可能时保留现有回退列表。 +- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍然串行）。默认值：4。 ### `agents.defaults.embeddedHarness` -`embeddedHarness` 控制哪个底层执行器运行嵌入式智能体轮次。 -大多数部署应保留默认值 `{ runtime: "auto", fallback: "pi" }`。 +`embeddedHarness` 用于控制哪个底层执行器运行嵌入式智能体回合。 +大多数部署应保持默认值 `{ runtime: "auto", fallback: "pi" }`。 当受信任的插件提供原生 harness 时使用它，例如内置的 Codex app-server harness。 @@ -1123,34 +1123,34 @@ Codex app-server harness。 } ``` -- `runtime`：`"auto"`、`"pi"`，或已注册的插件 harness id。内置 Codex 插件会注册 `codex`。 -- `fallback`：`"pi"` 或 `"none"`。`"pi"` 会保留内置 PI harness 作为兼容性回退。`"none"` 会在插件 harness 缺失或不支持时直接失败，而不是静默使用 PI。 +- `runtime`：`"auto"`、`"pi"` 或已注册插件 harness id。内置的 Codex 插件会注册 `codex`。 +- `fallback`：`"pi"` 或 `"none"`。`"pi"` 会保留内置 PI harness 作为兼容回退。`"none"` 则会在插件 harness 选择缺失或不受支持时直接失败，而不是静默使用 PI。 - 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=none` 会为该进程禁用 PI 回退。 -- 对于仅 Codex 的部署，请设置 `model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。 -- 这仅控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。 +- 对于仅使用 Codex 的部署，请设置 `model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。 +- 这只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用它们各自的提供商/模型设置。 -**内置 alias 简写**（仅当模型位于 `agents.defaults.models` 中时适用）： +**内置 alias 简写**（仅在模型位于 `agents.defaults.models` 中时适用）： -| Alias | 模型 | -| ------------------- | ---- | -| `opus` | `anthropic/claude-opus-4-6` | -| `sonnet` | `anthropic/claude-sonnet-4-6` | -| `gpt` | `openai/gpt-5.4` | -| `gpt-mini` | `openai/gpt-5.4-mini` | -| `gpt-nano` | `openai/gpt-5.4-nano` | -| `gemini` | `google/gemini-3.1-pro-preview` | -| `gemini-flash` | `google/gemini-3-flash-preview` | +| Alias | 模型 | +| ------------------- | -------------------------------------- | +| `opus` | `anthropic/claude-opus-4-6` | +| `sonnet` | `anthropic/claude-sonnet-4-6` | +| `gpt` | `openai/gpt-5.4` | +| `gpt-mini` | `openai/gpt-5.4-mini` | +| `gpt-nano` | `openai/gpt-5.4-nano` | +| `gemini` | `google/gemini-3.1-pro-preview` | +| `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -你配置的 alias 始终优先于默认值。 +你配置的 alias 总是优先于默认值。 Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/"].params.thinking`。 -Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设置为 `false` 可禁用它。 -当未设置显式 thinking 级别时，Anthropic Claude 4.6 模型默认使用 `adaptive` thinking。 +Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用它。 +Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 `adaptive` thinking。 ### `agents.defaults.cliBackends` -可选的 CLI 后端，用于纯文本回退运行（无工具调用）。当 API 提供商失败时可作为备用方案。 +用于纯文本回退运行（无工具调用）的可选 CLI 后端。适合作为 API 提供商失败时的备用方案。 ```json5 { @@ -1178,13 +1178,13 @@ Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `a } ``` -- CLI 后端以文本为主；工具始终被禁用。 +- CLI 后端以文本为主；工具始终禁用。 - 设置了 `sessionArg` 时支持会话。 - 当 `imageArg` 接受文件路径时，支持图像透传。 ### `agents.defaults.systemPromptOverride` -用固定字符串替换由 OpenClaw 组装的整个系统提示。可设置在默认级别（`agents.defaults.systemPromptOverride`）或按智能体设置（`agents.list[].systemPromptOverride`）。按智能体设置的值优先；空值或仅包含空白字符的值会被忽略。适用于受控提示实验。 +用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体设置（`agents.list[].systemPromptOverride`）。按智能体设置的值优先；空值或仅空白字符的值会被忽略。适用于受控提示实验。 ```json5 { @@ -1198,7 +1198,7 @@ Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `a ### `agents.defaults.heartbeat` -周期性 heartbeat 运行。 +周期性 Heartbeat 运行。 ```json5 { @@ -1208,16 +1208,17 @@ Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `a every: "30m", // 0m 表示禁用 model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // 默认：true；false 会从系统提示中省略 Heartbeat 部分 - lightContext: false, // 默认：false；true 只保留 workspace bootstrap 文件中的 HEARTBEAT.md - isolatedSession: false, // 默认：false；true 会让每次 heartbeat 在全新会话中运行（无对话历史） + includeSystemPromptSection: true, // 默认：true；false 会从系统提示中省略 Heartbeat 段 + lightContext: false, // 默认：false；true 仅保留 workspace bootstrap 文件中的 HEARTBEAT.md + isolatedSession: false, // 默认：false；true 会在全新会话中运行每次 Heartbeat（无会话历史） session: "main", to: "+15555550123", - directPolicy: "allow", // allow（默认）| block + directPolicy: "allow", // allow（默认） | block target: "none", // 默认：none | 可选值：last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, + timeoutSeconds: 45, }, }, }, @@ -1225,13 +1226,14 @@ Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `a ``` - `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 -- `includeSystemPromptSection`：为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。 -- `suppressToolErrorWarnings`：为 true 时，会在 heartbeat 运行期间抑制工具错误警告负载。 -- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并发出 `reason=dm-blocked`。 -- `lightContext`：为 true 时，heartbeat 运行会使用轻量 bootstrap 上下文，并且只保留 workspace bootstrap 文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次 heartbeat 都会在全新会话中运行，没有任何先前对话历史。隔离模式与 cron `sessionTarget: "isolated"` 相同。可将每次 heartbeat 的 token 成本从约 100K 降至约 2-5K。 -- 按智能体设置：使用 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 heartbeat。 -- Heartbeat 会运行完整的智能体轮次 —— 更短的间隔会消耗更多 token。 +- `includeSystemPromptSection`：设为 false 时，会从系统提示中省略 Heartbeat 段，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。 +- `suppressToolErrorWarnings`：设为 true 时，会在 Heartbeat 运行期间抑制工具错误警告负载。 +- `timeoutSeconds`：Heartbeat 智能体回合在被中止前允许的最长秒数。若不设置，则使用 `agents.defaults.timeoutSeconds`。 +- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会阻止直接目标投递，并输出 `reason=dm-blocked`。 +- `lightContext`：设为 true 时，Heartbeat 运行会使用轻量 bootstrap 上下文，并且只保留 workspace bootstrap 文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：设为 true 时，每次 Heartbeat 都会在一个没有先前会话历史的全新会话中运行。其隔离模式与 cron `sessionTarget: "isolated"` 相同。可将每次 Heartbeat 的 token 成本从约 100K 降低到约 2-5K。 +- 按智能体设置：使用 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 Heartbeat。 +- Heartbeat 会运行完整的智能体回合——更短的间隔会消耗更多 token。 ### `agents.defaults.compaction` @@ -1247,13 +1249,13 @@ Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `a identifierPolicy: "strict", // strict | off | custom identifierInstructions: "精确保留部署 ID、工单 ID 和 host:port 对。", // 当 identifierPolicy=custom 时使用 postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入 - model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于 compaction 的模型覆盖 - notifyUser: true, // compaction 开始时发送简短通知（默认：false） + model: "openrouter/anthropic/claude-sonnet-4-6", // 仅用于 compaction 的可选模型覆盖 + notifyUser: true, // 在 compaction 开始时发送简短通知（默认：false） memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "会话即将 compaction。现在请存储持久记忆。", - prompt: "将任何持久性笔记写入 memory/YYYY-MM-DD.md；如果没有内容需要存储，请精确回复静默 token NO_REPLY。", + systemPrompt: "会话即将执行 compaction。现在存储持久记忆。", + prompt: "将任何持久笔记写入 memory/YYYY-MM-DD.md；如果没有要存储的内容，请回复精确的静默 token NO_REPLY。", }, }, }, @@ -1262,18 +1264,18 @@ Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `a ``` - `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `provider`：已注册 compaction 提供商插件的 id。设置后，将调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置方式。设置提供商会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 在中止单次 compaction 操作前允许的最大秒数。默认值：`900`。 -- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要时预置内置的不透明标识符保留指导。 -- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 -- `postCompactionSections`：compaction 后要重新注入的可选 `AGENTS.md` H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。当未设置，或显式设置为这对默认值时，也会接受旧版 `Every Session`/`Safety` 标题作为兼容性回退。 -- `model`：可选的 `provider/model-id` 覆盖项，仅用于 compaction 摘要。当主会话需要保留一个模型、但 compaction 摘要应运行在另一个模型上时使用；未设置时，compaction 使用会话的主模型。 -- `notifyUser`：为 `true` 时，在 compaction 开始时向用户发送简短通知（例如“正在压缩上下文...”）。默认禁用，以保持 compaction 静默。 -- `memoryFlush`：自动 compaction 前的静默智能体轮次，用于存储持久记忆。当 workspace 为只读时会跳过。 +- `provider`：已注册 compaction 提供商插件的 id。设置后，会调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置方式。设置提供商会强制启用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最长秒数。默认值：`900`。 +- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内建的不透明标识符保留指导。 +- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留说明文本。 +- `postCompactionSections`：在 compaction 后重新注入的可选 AGENTS.md H2/H3 段落名。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。未设置或显式设为该默认对时，也会接受旧版 `Every Session`/`Safety` 标题作为兼容回退。 +- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当主会话需要保留某个模型，但希望 compaction 摘要改用另一个模型时使用；未设置时，compaction 会使用会话的主模型。 +- `notifyUser`：为 `true` 时，在 compaction 开始时向用户发送简短通知（例如 “正在压缩上下文...”）。默认禁用，以保持 compaction 静默。 +- `memoryFlush`：在自动 compaction 前执行静默的智能体回合，以存储持久记忆。当 workspace 为只读时会跳过。 ### `agents.defaults.contextPruning` -在发送给 LLM 之前，从内存上下文中修剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 +在发送给 LLM 之前，从内存上下文中裁剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -1287,7 +1289,7 @@ Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `a hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[旧的工具结果内容已清除]" }, + hardClear: { enabled: true, placeholder: "[旧工具结果内容已清除]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1297,23 +1299,23 @@ Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `a -- `mode: "cache-ttl"` 启用修剪过程。 -- `ttl` 控制再次运行修剪前需要等待多久（从上次缓存接触后开始计算）。 -- 修剪会先对过大的工具结果执行软裁剪，如有需要，再对较旧的工具结果执行硬清除。 +- `mode: "cache-ttl"` 会启用裁剪过程。 +- `ttl` 控制何时允许再次运行裁剪（自上次缓存触碰之后）。 +- 如有需要，裁剪会先对过大的工具结果执行软裁剪，然后再对较旧的工具结果执行硬清除。 -**软裁剪**会保留开头和结尾，并在中间插入 `...`。 +**软裁剪** 会保留开头 + 结尾，并在中间插入 `...`。 -**硬清除**会用占位文本替换整个工具结果。 +**硬清除** 会用占位符替换整个工具结果。 -注意： +说明： - 图像块永远不会被裁剪/清除。 -- 比例基于字符数（近似），不是精确 token 数。 -- 如果 assistant 消息数量少于 `keepLastAssistants`，则会跳过修剪。 +- 比例基于字符数（近似值），不是精确 token 数。 +- 如果 assistant 消息少于 `keepLastAssistants` 条，则会跳过裁剪。 -行为细节请参阅 [Session Pruning](/zh-CN/concepts/session-pruning)。 +行为详情参见 [Session Pruning](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -1332,10 +1334,10 @@ Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `a ``` - 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。 -- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 +- 渠道级覆盖：`channels..blockStreamingCoalesce`（以及按账号变体）。Signal/Slack/Discord/Google Chat 默认使用 `minChars: 1500`。 - `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。 -行为和分块细节请参阅 [Streaming](/zh-CN/concepts/streaming)。 +行为和分块细节参见 [Streaming](/zh-CN/concepts/streaming)。 ### 输入中指示器 @@ -1350,16 +1352,16 @@ Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `a } ``` -- 默认值：私聊/提及时为 `instant`，未提及的群聊为 `message`。 +- 默认值：私聊/被提及时为 `instant`，未被提及的群聊为 `message`。 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 -参阅 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 +参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南请参阅 [Sandboxing](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南参见 [Sandboxing](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -1459,45 +1461,45 @@ Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `a **后端：** - `docker`：本地 Docker 运行时（默认） -- `ssh`：通用 SSH 支持的远程运行时 +- `ssh`：通用的 SSH 支持远程运行时 - `openshell`：OpenShell 运行时 -当选择 `backend: "openshell"` 时，运行时特定设置会移动到 +选择 `backend: "openshell"` 时，运行时专用设置会移到 `plugins.entries.openshell.config`。 **SSH 后端配置：** -- `target`：采用 `user@host[:port]` 形式的 SSH 目标 +- `target`：`user@host[:port]` 形式的 SSH 目标 - `command`：SSH 客户端命令（默认：`ssh`） - `workspaceRoot`：用于按作用域 workspace 的远程绝对根目录 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 -- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在运行时物化为临时文件的内联内容或 SecretRef -- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略控制项 +- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件 +- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH host-key 策略选项 **SSH 认证优先级：** - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从活动 secrets 运行时快照中解析 +- 由 SecretRef 支持的 `*Data` 值会在沙箱会话开始前从活动 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重新创建后仅初始化一次远程 workspace -- 然后保持远程 SSH workspace 作为规范状态 +- 在创建或重建后对远程 workspace 执行一次初始化 +- 随后保持远程 SSH workspace 为规范副本 - 通过 SSH 路由 `exec`、文件工具和媒体路径 -- 不会自动将远程更改同步回主机 +- 不会自动将远程变更同步回主机 - 不支持沙箱浏览器容器 **Workspace 访问：** -- `none`：位于 `~/.openclaw/sandboxes` 下、按作用域划分的沙箱 workspace +- `none`：在 `~/.openclaw/sandboxes` 下为每个作用域创建沙箱 workspace - `ro`：沙箱 workspace 位于 `/workspace`，智能体 workspace 以只读方式挂载到 `/agent` - `rw`：智能体 workspace 以读写方式挂载到 `/workspace` **作用域：** -- `session`：按会话划分的容器 + workspace +- `session`：每会话一个容器 + workspace - `agent`：每个智能体一个容器 + workspace（默认） - `shared`：共享容器和 workspace（无跨会话隔离） @@ -1516,7 +1518,7 @@ Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `a remoteAgentWorkspaceDir: "/agent", gateway: "lab", // 可选 gatewayEndpoint: "https://lab.example", // 可选 - policy: "strict", // 可选 OpenShell 策略 id + policy: "strict", // 可选 OpenShell policy id providers: ["openai"], // 可选 autoProviders: true, timeoutSeconds: 120, @@ -1529,29 +1531,29 @@ Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `a **OpenShell 模式：** -- `mirror`：在执行前从本地初始化远程，执行后同步回本地；本地 workspace 保持为规范状态 -- `remote`：在创建沙箱时仅初始化一次远程，然后保持远程 workspace 作为规范状态 +- `mirror`：执行前从本地初始化到远程，执行后再同步回本地；本地 workspace 保持为规范副本 +- `remote`：仅在创建沙箱时向远程初始化一次，随后保持远程 workspace 为规范副本 -在 `remote` 模式下，于 OpenClaw 外部在主机本地进行的编辑，在初始化步骤之后不会自动同步到沙箱中。 -传输方式是通过 SSH 进入 OpenShell 沙箱，但插件拥有沙箱生命周期和可选的 mirror 同步。 +在 `remote` 模式下，初始化之后，在 OpenClaw 外部对主机本地所做的编辑不会自动同步到沙箱中。 +传输方式是通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的镜像同步。 -**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 +**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统以及 root 用户。 -**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设为 `"bridge"`（或自定义 bridge 网络）。 +**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 默认会阻止 `"host"`。默认也会阻止 `"container:"`，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（破窗开关）。 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（破窗模式）。 -**传入附件** 会被暂存到活动 workspace 中的 `media/inbound/*`。 +**入站附件** 会被暂存到活动 workspace 中的 `media/inbound/*`。 -**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的绑定会合并。 +**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 binds 会被合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行的 Chromium + CDP。noVNC URL 会注入到系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。 -noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短期有效的 token URL（而不是在共享 URL 中暴露密码）。 +**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入系统提示。无需在 `openclaw.json` 中启用 `browser.enabled`。 +noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出短时有效的 token URL（而不是在共享 URL 中暴露密码）。 -- `allowHostControl: false`（默认）会阻止沙箱隔离会话将主机浏览器作为目标。 -- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。仅当你明确需要全局 bridge 连通性时才设为 `bridge`。 -- `cdpSourceRange` 可选地将容器边界上的 CDP 入站限制为某个 CIDR 范围（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱隔离浏览器容器中。设置后（包括 `[]`），它会为浏览器容器替换 `docker.binds`。 +- `allowHostControl: false`（默认）会阻止沙箱隔离会话将目标指向主机浏览器。 +- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。只有在你明确需要全局 bridge 连通性时才设置为 `bridge`。 +- `cdpSourceRange` 可选地将容器边界处的 CDP 入站限制为某个 CIDR 范围（例如 `172.21.0.1/32`）。 +- `sandbox.browser.binds` 仅会为沙箱隔离浏览器容器挂载额外的主机目录。设置后（包括 `[]`）它会替代浏览器容器上的 `docker.binds`。 - 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` @@ -1570,11 +1572,11 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短期有 - `--no-zygote` - `--metrics-recording-only` - `--disable-extensions`（默认启用） - - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` 默认启用；如果 WebGL/3D 使用需要，可通过设置 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 来禁用这些标志。 + - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` 默认启用；如果 WebGL/3D 使用需要它们，可通过设置 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 来禁用这些标志。 - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展，如果你的工作流依赖它们。 - - `--renderer-process-limit=2` 可通过 `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 可使用 Chromium 的默认进程限制。 - - 另外，当启用 `noSandbox` 时，还会附加 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - - 这些默认值是容器镜像基线；如需更改容器默认值，请使用带自定义入口点的自定义浏览器镜像。 + - `--renderer-process-limit=2` 可通过 `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 则使用 Chromium 的默认进程限制。 + - 另外，当启用 `noSandbox` 时，还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。 + - 这些默认值是容器镜像的基线；如需修改容器默认行为，请使用自定义浏览器镜像和自定义入口点。 @@ -1604,8 +1606,8 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 reasoningDefault: "on", // 按智能体覆盖 reasoning 可见性 fastModeDefault: false, // 按智能体覆盖 fast mode embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params - skills: ["docs-search"], // 设置时会替换 agents.defaults.skills + params: { cacheRetention: "none" }, // 按键覆盖匹配 defaults.models params + skills: ["docs-search"], // 设置后会替代 agents.defaults.skills identity: { name: "Samantha", theme: "helpful sloth", @@ -1636,21 +1638,21 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 } ``` -- `id`：稳定的智能体 ID（必填）。 -- `default`：设置多个时，以第一个为准（会记录警告）。如果一个都未设置，则列表第一项为默认值。 -- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖两者（`[]` 会禁用全局回退模型）。仅覆盖 `primary` 的 cron 任务仍会继承默认回退模型，除非你设置 `fallbacks: []`。 -- `params`：按智能体设置的流参数，会合并到 `agents.defaults.models` 中选定模型条目之上。用于设置智能体特定覆盖，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。 -- `skills`：可选的按智能体 Skills 允许列表。若省略，则在设置了 `agents.defaults.skills` 时继承该默认值；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。 -- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。当未设置按消息或按会话覆盖时，会覆盖此智能体的 `agents.defaults.thinkingDefault`。 -- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当未设置按消息或按会话的 reasoning 覆盖时适用。 -- `fastModeDefault`：可选的按智能体 fast mode 默认值（`true | false`）。当未设置按消息或按会话的 fast-mode 覆盖时适用。 -- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex", fallback: "none" }` 可使某个智能体仅使用 Codex，而其他智能体保留默认的 PI 回退。 -- `runtime`：可选的按智能体运行时描述符。当智能体默认应使用 ACP harness 会话时，使用 `type: "acp"` 并配合 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 +- `id`：稳定的智能体 id（必填）。 +- `default`：如果设置了多个，以第一个为准（会记录警告）。如果一个都没设置，则列表第一项为默认值。 +- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖两者（`[]` 会禁用全局回退）。仅覆盖 `primary` 的 cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。 +- `params`：按智能体的流参数，会合并覆盖到 `agents.defaults.models` 中所选模型条目之上。适合用于 `cacheRetention`、`temperature` 或 `maxTokens` 这类按智能体覆盖，而无需复制整个模型目录。 +- `skills`：可选的按智能体 Skills allowlist。若省略，在设置了 `agents.defaults.skills` 时会继承它；显式列表会替代默认值而不是合并，`[]` 表示不启用任何 Skills。 +- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。当未设置按消息或按会话覆盖时，它会覆盖该智能体的 `agents.defaults.thinkingDefault`。 +- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当未设置按消息或按会话 reasoning 覆盖时应用。 +- `fastModeDefault`：可选的按智能体默认 fast mode（`true | false`）。当未设置按消息或按会话 fast mode 覆盖时应用。 +- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex", fallback: "none" }` 可让某个智能体仅使用 Codex，而其他智能体保留默认的 PI 回退。 +- `runtime`：可选的按智能体运行时描述符。当某个智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 和 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 - `identity.avatar`：相对于 workspace 的路径、`http(s)` URL 或 `data:` URI。 - `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。 -- `subagents.allowAgents`：用于 `sessions_spawn` 的智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝会导致目标以非沙箱方式运行的请求。 -- `subagents.requireAgentId`：为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。 +- `subagents.allowAgents`：`sessions_spawn` 允许的智能体 id 列表（`["*"]` = 任意；默认：仅限相同智能体）。 +- 沙箱继承防护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝运行目标为非沙箱隔离的情况。 +- `subagents.requireAgentId`：设为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。 --- @@ -1675,12 +1677,12 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 绑定匹配字段 -- `type`（可选）：普通路由使用 `route`（缺失时默认也是 route），持久 ACP 对话绑定使用 `acp` +- `type`（可选）：`route` 用于普通路由（缺失时默认是 route），`acp` 用于持久化 ACP 会话绑定。 - `match.channel`（必填） - `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号） - `match.peer`（可选；`{ kind: direct|group|channel, id }`） -- `match.guildId` / `match.teamId`（可选；渠道特定） -- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }` +- `match.guildId` / `match.teamId`（可选；渠道专用） +- `acp`（可选；仅适用于 `type: "acp"`）：`{ mode, label, cwd, backend }` **确定性匹配顺序：** @@ -1688,14 +1690,14 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 2. `match.guildId` 3. `match.teamId` 4. `match.accountId`（精确匹配，无 peer/guild/team） -5. `match.accountId: "*"`（渠道级） +5. `match.accountId: "*"`（整个渠道范围） 6. 默认智能体 -在每一层级中，首个匹配的 `bindings` 条目胜出。 +在每一层级内，第一个匹配的 `bindings` 条目获胜。 -对于 `type: "acp"` 条目，OpenClaw 会按精确对话标识（`match.channel` + 账号 + `match.peer.id`）进行解析，不使用上述 route 绑定层级顺序。 +对于 `type: "acp"` 条目，OpenClaw 会按精确会话身份（`match.channel` + 账号 + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。 -### 按智能体访问配置 +### 按智能体划分的访问配置 @@ -1744,7 +1746,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - + ```json5 { @@ -1790,7 +1792,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 -优先级细节请参阅 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 +优先级细节参见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1816,7 +1818,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 超过此 token 数时跳过父线程 fork（0 表示禁用） + parentForkMaxTokens: 100000, // 超过该 token 数时跳过父线程 fork（0 表示禁用） maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1828,10 +1830,10 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, threadBindings: { enabled: true, - idleHours: 24, // 默认按小时计的非活动自动取消聚焦（`0` 表示禁用） - maxAgeHours: 0, // 默认按小时计的硬性最大时长（`0` 表示禁用） + idleHours: 24, // 默认按小时计算的无活动自动取消聚焦（`0` 表示禁用） + maxAgeHours: 0, // 默认按小时计算的硬性最大时长（`0` 表示禁用） }, - mainKey: "main", // 旧版字段（运行时始终使用 "main"） + mainKey: "main", // 旧版（运行时始终使用 "main"） agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1843,35 +1845,35 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 -- **`scope`**：用于群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：每个发送者在渠道上下文中获得独立会话。 - - `global`：渠道上下文中的所有参与者共享同一个会话（仅在确实需要共享上下文时使用）。 +- **`scope`**：群聊上下文的基础会话分组策略。 + - `per-sender`（默认）：在某个渠道上下文中，每个发送者拥有独立会话。 + - `global`：某个渠道上下文中的所有参与者共享一个会话（仅在你明确需要共享上下文时使用）。 - **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - - `per-peer`：按发送者 ID 跨渠道隔离。 + - `per-peer`：按发送者 id 跨渠道隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 -- **`identityLinks`**：将规范 ID 映射到带提供商前缀的对端标识，用于跨渠道共享会话。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。当两者都已配置时，以先到期者为准。 -- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建 fork 线程会话时允许的父会话 `totalTokens` 最大值（默认 `100000`）。 - - 如果父会话 `totalTokens` 高于该值，OpenClaw 会启动新的线程会话，而不是继承父级 transcript 历史。 - - 设为 `0` 可禁用此保护，并始终允许父级 fork。 +- **`identityLinks`**：将规范 id 映射到带提供商前缀的对端，以实现跨渠道会话共享。 +- **`reset`**：主要重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。当两者都已配置时，以先到期者为准。 +- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名使用。 +- **`parentForkMaxTokens`**：创建 fork 线程会话时，允许的父会话 `totalTokens` 最大值（默认 `100000`）。 + - 如果父会话的 `totalTokens` 高于此值，OpenClaw 会启动一个全新的线程会话，而不是继承父转录历史。 + - 设为 `0` 可禁用此防护，并始终允许从父会话 fork。 - **`mainKey`**：旧版字段。运行时始终对主私聊桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体之间交互时，智能体间来回回复的最大轮次数（整数，范围：`0`–`5`）。`0` 表示禁用 ping-pong 链。 -- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 进行匹配。首个拒绝规则优先。 +- **`agentToAgent.maxPingPongTurns`**：智能体之间交换消息时，允许的最大来回回复轮数（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链式回复。 +- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 也可作为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 规则优先。 - **`maintenance`**：会话存储清理 + 保留控制。 - `mode`：`warn` 仅发出警告；`enforce` 会实际执行清理。 - - `pruneAfter`：陈旧条目的过期时间阈值（默认 `30d`）。 - - `maxEntries`：`sessions.json` 中允许的最大条目数（默认 `500`）。 - - `rotateBytes`：当 `sessions.json` 超过此大小时进行轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` transcript 归档的保留时长。默认等于 `pruneAfter`；设为 `false` 可禁用。 - - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的工件/会话。 + - `pruneAfter`：陈旧条目的年龄截止值（默认 `30d`）。 + - `maxEntries`：`sessions.json` 中条目的最大数量（默认 `500`）。 + - `rotateBytes`：当 `sessions.json` 超过该大小时进行轮转（默认 `10mb`）。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留期。默认继承 `pruneAfter`；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的制品/会话。 - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认按小时计的非活动自动取消聚焦时长（`0` 表示禁用；提供商可覆盖） - - `maxAgeHours`：默认按小时计的硬性最大时长（`0` 表示禁用；提供商可覆盖） + - `idleHours`：按小时计算的默认无活动自动取消聚焦时间（`0` 表示禁用；提供商可覆盖） + - `maxAgeHours`：按小时计算的默认硬性最大时长（`0` 表示禁用；提供商可覆盖） @@ -1915,13 +1917,13 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 **模板变量：** -| 变量 | 描述 | 示例 | -| ----------------- | ---------------------- | --------------------------- | -| `{model}` | 短模型名 | `claude-opus-4-6` | -| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | -| `{provider}` | 提供商名称 | `anthropic` | -| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| 变量 | 说明 | 示例 | +| ----------------- | ---------------- | --------------------------- | +| `{model}` | 短模型名 | `claude-opus-4-6` | +| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | +| `{provider}` | 提供商名称 | `anthropic` | +| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | +| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 @@ -1930,17 +1932,17 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 - 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 - 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。 -- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，于回复后移除确认 reaction。 +- 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上于回复后移除确认 reaction。 - `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态 reactions。 - 在 Slack 和 Discord 上，未设置时会在确认 reaction 处于活动状态时保持状态 reactions 启用。 - 在 Telegram 上，需要显式设为 `true` 才会启用生命周期状态 reactions。 + 在 Slack 和 Discord 上，未设置时，如果确认 reactions 处于启用状态，则状态 reactions 保持启用。 + 在 Telegram 上，需显式设为 `true` 才会启用生命周期状态 reactions。 ### 入站防抖 -将来自同一发送者的快速纯文本消息批处理为单个智能体轮次。媒体/附件会立即冲刷。控制命令会绕过防抖。 +将同一发送者的快速纯文本消息合并为单个智能体回合。媒体/附件会立即刷新。控制命令会绕过防抖。 -### TTS（文本转语音） +### TTS（text-to-speech） ```json5 { @@ -1981,12 +1983,12 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 } ``` -- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示生效状态。 -- `summaryModel` 会覆盖自动摘要所用的 `agents.defaults.model.primary`。 +- `auto` 用于控制默认的自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示生效状态。 +- `summaryModel` 会覆盖自动摘要所使用的 `agents.defaults.model.primary`。 - `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需显式启用）。 - API key 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 -- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为：配置 → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`。 -- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容 TTS 服务器，并放宽模型/语音验证。 +- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置值，然后 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。 +- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型/语音校验。 --- @@ -2016,13 +2018,13 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- `talk.provider` 在配置了多个 Talk 提供商时，必须匹配 `talk.providers` 中的某个键。 +- 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 - 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.`。 - Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 -- `providers.*.apiKey` 可接受明文字符串或 SecretRef 对象。 -- 仅当未配置 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。 +- `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。 +- 仅当未配置 Talk API key 时，才会应用 `ELEVENLABS_API_KEY` 回退。 - `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 -- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久才发送 transcript。未设置时将保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- `silenceTimeoutMs` 控制 Talk 模式在用户静默后等待多长时间再发送转录。未设置时会保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- @@ -2030,37 +2032,37 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### 工具配置 -`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置基础允许列表： +`tools.profile` 会在应用 `tools.allow`/`tools.deny` 之前设置基础 allowlist： -本地新手引导会在未设置时，将新的本地配置默认设为 `tools.profile: "coding"`（已有的显式配置会保留）。 +本地新手引导会在未设置时，将新的本地配置默认设为 `tools.profile: "coding"`（已存在的显式配置不会被更改）。 -| 配置 | 包含 | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | 仅 `session_status` | -| `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | -| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | -| `full` | 无限制（与未设置相同） | +| 配置 | 包含内容 | +| ------------ | ------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | 仅 `session_status` | +| `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | +| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | +| `full` | 无限制（与未设置相同） | ### 工具组 -| 组 | 工具 | +| 组 | 工具 | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | -| `group:fs` | `read`、`write`、`edit`、`apply_patch` | +| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名使用） | +| `group:fs` | `read`、`write`、`edit`、`apply_patch` | | `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | -| `group:memory` | `memory_search`、`memory_get` | -| `group:web` | `web_search`、`x_search`、`web_fetch` | -| `group:ui` | `browser`、`canvas` | -| `group:automation` | `cron`、`gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | -| `group:openclaw` | 所有内置工具（不含 provider 插件） | +| `group:memory` | `memory_search`、`memory_get` | +| `group:web` | `web_search`、`x_search`、`web_fetch` | +| `group:ui` | `browser`、`canvas` | +| `group:automation` | `cron`、`gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | +| `group:openclaw` | 所有内置工具（不包括提供商插件） | ### `tools.allow` / `tools.deny` -全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱已关闭，也会应用。 +全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱隔离关闭时也会应用。 ```json5 { @@ -2070,7 +2072,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.byProvider` -进一步限制特定提供商或模型的工具。顺序：基础配置 → 提供商配置 → allow/deny。 +进一步限制特定提供商或模型的工具。顺序为：基础配置 → 提供商配置 → allow/deny。 ```json5 { @@ -2086,7 +2088,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.elevated` -控制沙箱外的 elevated exec 访问： +控制沙箱外部的 elevated exec 访问： ```json5 { @@ -2103,8 +2105,8 @@ Talk 模式的默认值（macOS/iOS/Android）。 ``` - 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。 -- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅对单条消息生效。 -- Elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认为 `gateway`，或当 exec 目标为 `node` 时使用 `node`）。 +- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅作用于单条消息。 +- elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，若 exec 目标是 `node` 则使用 `node`）。 ### `tools.exec` @@ -2128,8 +2130,8 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.loopDetection` -工具循环安全检查**默认禁用**。设置 `enabled: true` 可启用检测。 -设置可在全局 `tools.loopDetection` 中定义，也可在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 +工具循环安全检查默认**禁用**。设置 `enabled: true` 以启用检测。 +可在 `tools.loopDetection` 中定义全局设置，并在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 ```json5 { @@ -2150,10 +2152,10 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- `historySize`：为循环分析保留的最大工具调用历史。 +- `historySize`：用于循环分析保留的最大工具调用历史。 - `warningThreshold`：重复无进展模式触发警告的阈值。 -- `criticalThreshold`：用于阻止严重循环的更高重复阈值。 -- `globalCircuitBreakerThreshold`：任何无进展运行的硬性停止阈值。 +- `criticalThreshold`：阻止严重循环的更高重复阈值。 +- `globalCircuitBreakerThreshold`：任意无进展运行的硬停止阈值。 - `detectors.genericRepeat`：对重复的同工具/同参数调用发出警告。 - `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。 - `detectors.pingPong`：对交替出现的无进展成对模式发出警告/阻止。 @@ -2174,7 +2176,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 }, fetch: { enabled: true, - provider: "firecrawl", // 可选；省略则自动检测 + provider: "firecrawl", // 可选；省略时自动检测 maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2229,7 +2231,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 - `provider`：API 提供商 id（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） - `model`：模型 id 覆盖 -- `profile` / `preferredProfile`：`auth-profiles.json` 配置文件选择 +- `profile` / `preferredProfile`：`auth-profiles.json` 配置选择 **CLI 条目**（`type: "cli"`）： @@ -2238,7 +2240,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 **通用字段：** -- `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai`/`anthropic`/`minimax` → 图像，`google` → 图像 + 音频 + 视频，`groq` → 音频。 +- `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai`/`anthropic`/`minimax` → image，`google` → image+audio+video，`groq` → audio。 - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：按条目覆盖。 - 失败时会回退到下一个条目。 @@ -2246,9 +2248,9 @@ Talk 模式的默认值（macOS/iOS/Android）。 **异步完成字段：** -- `asyncCompletion.directSend`：为 `true` 时，已完成的异步 `music_generate` - 和 `video_generate` 任务会优先尝试直接渠道投递。默认值：`false` - （旧版请求者会话唤醒/模型投递路径）。 +- `asyncCompletion.directSend`：设为 `true` 时，已完成的异步 `music_generate` + 和 `video_generate` 任务会先尝试直接投递到渠道。默认值：`false` + （保留旧版请求方会话唤醒/模型投递路径）。 @@ -2267,9 +2269,9 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.sessions` -控制 session 工具（`sessions_list`、`sessions_history`、`sessions_send`）可以以哪些会话为目标。 +控制 session 工具（`sessions_list`、`sessions_history`、`sessions_send`）可以面向哪些会话。 -默认值：`tree`（当前会话 + 由其派生的会话，例如子智能体）。 +默认值：`tree`（当前会话 + 由其生成的会话，例如 subagents）。 ```json5 { @@ -2282,13 +2284,13 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -注意： +说明： - `self`：仅当前会话键。 -- `tree`：当前会话 + 由当前会话派生的会话（子智能体）。 -- `agent`：属于当前智能体 id 的任意会话（如果你在同一智能体 id 下按发送者运行会话，则可能包含其他用户）。 +- `tree`：当前会话 + 由当前会话生成的会话（subagents）。 +- `agent`：属于当前智能体 id 的任意会话（如果你在同一智能体 id 下运行按发送者划分的会话，则可能包含其他用户）。 - `all`：任意会话。跨智能体定向仍需要 `tools.agentToAgent`。 -- 沙箱限制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 +- 沙箱限制：当当前会话处于沙箱隔离中且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 ### `tools.sessions_spawn` @@ -2300,7 +2302,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 sessions_spawn: { attachments: { enabled: false, // 显式启用：设为 true 以允许内联文件附件 - maxTotalBytes: 5242880, // 所有文件总计 5 MB + maxTotalBytes: 5242880, // 所有文件合计 5 MB maxFiles: 50, maxFileBytes: 1048576, // 每个文件 1 MB retainOnSessionKeep: false, // 当 cleanup="keep" 时保留附件 @@ -2310,18 +2312,18 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -注意： +说明： -- 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 -- 文件会被物化到子 workspace 的 `.openclaw/attachments//` 中，并附带一个 `.manifest.json`。 -- 附件内容会自动从 transcript 持久化中脱敏。 -- Base64 输入会通过严格的字母表/填充检查以及解码前大小保护进行验证。 -- 目录权限为 `0700`，文件权限为 `0600`。 -- 清理遵循 `cleanup` 策略：`delete` 总会移除附件；只有当 `retainOnSessionKeep: true` 时，`keep` 才会保留它们。 +- 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝它们。 +- 文件会实体化到子 workspace 的 `.openclaw/attachments//` 中，并附带一个 `.manifest.json`。 +- 附件内容会自动从转录持久化中脱敏。 +- Base64 输入会使用严格的字母表/填充校验以及解码前大小防护进行验证。 +- 文件权限为目录 `0700`、文件 `0600`。 +- 清理由 `cleanup` 策略控制：`delete` 总会删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留它们。 ### `tools.experimental` -实验性内置工具标志。默认关闭，除非严格 agentic GPT-5 自动启用规则适用。 +实验性内置工具开关。默认关闭，除非严格智能体式 GPT-5 自动启用规则适用。 ```json5 { @@ -2333,11 +2335,11 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -注意： +说明： -- `planTool`：为非简单多步骤工作跟踪启用结构化 `update_plan` 工具。 -- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或按智能体覆盖）被设置为 OpenAI 或 OpenAI Codex GPT-5 系列运行的 `"strict-agentic"`。设为 `true` 可在该范围外强制启用此工具，设为 `false` 则即使是 strict-agentic GPT-5 运行也保持关闭。 -- 启用后，系统提示还会添加使用说明，以便模型仅在实质性工作中使用它，并始终保持最多一个步骤处于 `in_progress`。 +- `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 +- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或按智能体覆盖）对 OpenAI 或 OpenAI Codex GPT-5 系列运行设置为 `"strict-agentic"`。设为 `true` 可在该范围外强制启用该工具，设为 `false` 则即使在 strict-agentic GPT-5 运行中也保持关闭。 +- 启用后，系统提示还会加入使用指导，使模型仅在实质性工作中使用它，并始终最多只保留一个 `in_progress` 步骤。 ### `agents.defaults.subagents` @@ -2357,21 +2359,21 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- `model`：派生子智能体的默认模型。若省略，子智能体将继承调用方的模型。 -- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 目标智能体 id 的默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- `model`：生成的子智能体默认模型。若省略，子智能体会继承调用方模型。 +- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 目标智能体 id 的默认 allowlist（`["*"]` = 任意；默认：仅同一智能体）。 - `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时时间（秒）。`0` 表示无超时。 -- 按子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 +- 按子智能体的工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- ## 自定义提供商和 base URL -OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 +OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 ```json5 { models: { - mode: "merge", // merge（默认）| replace + mode: "merge", // merge（默认） | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2395,42 +2397,42 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -- 使用 `authHeader: true` + `headers` 以满足自定义认证需求。 -- 使用 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 -- 对匹配提供商 ID 的合并优先级： +- 对于自定义认证需求，请使用 `authHeader: true` + `headers`。 +- 使用 `OPENCLAW_AGENT_DIR` 覆盖智能体配置根目录（或使用旧版环境变量别名 `PI_CODING_AGENT_DIR`）。 +- 对于匹配的提供商 ID，合并优先级如下： - 非空的智能体 `models.json` `baseUrl` 值优先。 - - 非空的智能体 `apiKey` 值仅在该提供商在当前配置/auth-profile 上下文中不是由 SecretRef 管理时优先。 - - 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的 secret。 - - 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。 - - 为空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 - - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值和隐式目录值之间取较高者。 - - 匹配模型的 `contextTokens` 在存在时会保留显式运行时上限；使用它可限制生效上下文，而无需更改模型原生元数据。 - - 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。 - - 标记持久化以源为准：标记会从活动源配置快照（解析前）写入，而不是从已解析的运行时 secret 值写入。 + - 非空的智能体 `apiKey` 值仅在该提供商在当前配置/auth-profile 上下文中不是 SecretRef 管理时优先。 + - 由 SecretRef 管理的提供商 `apiKey` 值会从来源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`），而不是持久化已解析的 secret。 + - 由 SecretRef 管理的提供商 header 值会从来源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`）。 + - 空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 + - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值与隐式目录值之间取较高者。 + - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；可用它在不更改原生模型元数据的情况下限制有效上下文。 + - 当你希望配置完全重写 `models.json` 时，请使用 `models.mode: "replace"`。 + - 标记持久化遵循来源权威：标记来自活动来源配置快照（解析前）写入，而不是来自已解析的运行时 secret 值。 ### 提供商字段详情 - `models.mode`：提供商目录行为（`merge` 或 `replace`）。 - `models.providers`：以提供商 id 为键的自定义提供商映射。 - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。 -- `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef/环境变量替换）。 +- `models.providers.*.apiKey`：提供商凭证（推荐使用 SecretRef/环境变量替换）。 - `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 -- `models.providers.*.injectNumCtxForOpenAICompat`：用于 Ollama + `openai-completions` 时，将 `options.num_ctx` 注入请求中（默认：`true`）。 -- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` 头传输凭证。 +- `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，向请求中注入 `options.num_ctx`（默认：`true`）。 +- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭证。 - `models.providers.*.baseUrl`：上游 API base URL。 - `models.providers.*.headers`：用于代理/租户路由的额外静态 headers。 -- `models.providers.*.request`：模型提供商 HTTP 请求的传输层覆盖。 - - `request.headers`：额外 headers（会与提供商默认值合并）。值支持 SecretRef。 - - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value` 和可选的 `prefix`）。 - - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。这两种模式都接受可选的 `tls` 子对象。 - - `request.tls`：直连的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（均支持 SecretRef）、`serverName`、`insecureSkipVerify`。 - - `request.allowPrivateNetwork`：为 `true` 时，当 DNS 将 `baseUrl` 解析到私有、CGNAT 或类似网段时，允许通过提供商 HTTP fetch 防护访问 HTTPS `baseUrl`（这是针对受信任的自托管 OpenAI 兼容端点的操作员显式启用项）。WebSocket 对 headers/TLS 使用相同的 `request`，但不使用该 fetch SSRF 防护。默认值 `false`。 -- `models.providers.*.models`：显式提供商模型目录条目。 -- `models.providers.*.models.*.contextWindow`：模型原生上下文窗口元数据。 -- `models.providers.*.models.*.contextTokens`：可选运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用此项。 -- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 为非空、非原生值（主机不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空的/省略的 `baseUrl` 会保留默认的 OpenAI 行为。 -- `models.providers.*.models.*.compat.requiresStringContent`：适用于仅支持字符串的 OpenAI 兼容聊天端点的可选兼容性提示。为 `true` 时，OpenClaw 会在发送请求前将纯文本 `messages[].content` 数组展平为纯字符串。 -- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根节点。 +- `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖。 + - `request.headers`：额外 headers（与提供商默认值合并）。值支持 SecretRef。 + - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`，可选 `prefix`）。 + - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。 + - `request.tls`：直连时的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（均支持 SecretRef）、`serverName`、`insecureSkipVerify`。 + - `request.allowPrivateNetwork`：设为 `true` 时，当 DNS 解析到私有、CGNAT 或类似地址范围时，允许通过提供商 HTTP 获取防护访问 `baseUrl` 的 HTTPS（这是针对受信任、自托管、兼容 OpenAI 端点的 operator 显式启用项）。WebSocket 也会使用同一个 `request` 来处理 headers/TLS，但不会使用该 fetch SSRF 防护。默认值 `false`。 +- `models.providers.*.models`：显式的提供商模型目录条目。 +- `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。 +- `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用它。 +- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 为非空、非原生值（host 不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空或省略 `baseUrl` 时保留默认 OpenAI 行为。 +- `models.providers.*.models.*.compat.requiresStringContent`：适用于仅支持字符串的兼容 OpenAI 聊天端点的可选兼容性提示。设为 `true` 时，OpenClaw 会在发送请求前，将纯文本 `messages[].content` 数组压平为普通字符串。 +- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根路径。 - `plugins.entries.amazon-bedrock.config.discovery.enabled`：开启/关闭隐式发现。 - `plugins.entries.amazon-bedrock.config.discovery.region`：用于发现的 AWS 区域。 - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用于定向发现的可选 provider-id 过滤器。 @@ -2452,8 +2454,8 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ fallbacks: ["cerebras/zai-glm-4.6"], }, models: { - "cerebras/zai-glm-4.7": { alias: "GLM 4.7（Cerebras）" }, - "cerebras/zai-glm-4.6": { alias: "GLM 4.6（Cerebras）" }, + "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" }, + "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (Cerebras)" }, }, }, }, @@ -2465,8 +2467,8 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ apiKey: "${CEREBRAS_API_KEY}", api: "openai-completions", models: [ - { id: "zai-glm-4.7", name: "GLM 4.7（Cerebras）" }, - { id: "zai-glm-4.6", name: "GLM 4.6（Cerebras）" }, + { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" }, + { id: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" }, ], }, }, @@ -2474,7 +2476,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 +对于 Cerebras，请使用 `cerebras/zai-glm-4.7`；对于 Z.AI 直连，请使用 `zai/glm-4.7`。 @@ -2491,7 +2493,7 @@ Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 } ``` -设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。Zen 目录使用 `opencode/...` 引用，Go 目录使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 +设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。对 Zen 目录使用 `opencode/...` 引用，对 Go 目录使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 @@ -2511,8 +2513,8 @@ Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 - 通用端点：`https://api.z.ai/api/paas/v4` -- Coding 端点（默认）：`https://api.z.ai/api/coding/paas/v4` -- 若使用通用端点，请定义一个带 base URL 覆盖的自定义提供商。 +- 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` +- 若要使用通用端点，请定义带 base URL 覆盖的自定义提供商。 @@ -2551,11 +2553,11 @@ Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 } ``` -中国区端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 +对于中国端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 -原生 Moonshot 端点会在共享 -`openai-completions` 传输层上声明流式传输兼容性，而 OpenClaw 会基于端点能力 -而不是仅基于内置提供商 id 来做判断。 +原生 Moonshot 端点会在共享的 +`openai-completions` 传输上声明流式传输使用兼容性，而 OpenClaw 会依据端点能力 +而不仅仅是内置提供商 id 本身来处理这一点。 @@ -2573,11 +2575,11 @@ Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 } ``` -Anthropic 兼容，内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 +兼容 Anthropic 的内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 - + ```json5 { @@ -2656,16 +2658,15 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会追加它）。快捷方式 `openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。 模型目录默认仅包含 M2.7。 -在 Anthropic 兼容的流式传输路径上，OpenClaw 默认会禁用 MiniMax thinking， -除非你显式设置 `thinking`。`/fast on` 或 -`params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 +在兼容 Anthropic 的流式传输路径上，除非你显式设置 `thinking`，否则 OpenClaw 默认会禁用 MiniMax thinking。 +`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 -参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在高性能硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 +参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在性能足够的硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 @@ -2696,12 +2697,13 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会追加它）。快捷方式 } ``` -- `allowBundled`：仅针对内置 Skills 的可选允许列表（不影响托管/workspace Skills）。 -- `load.extraDirs`：额外的共享 Skills 根目录（优先级最低）。 -- `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 的可选 allowlist（托管/workspace Skills 不受影响）。 +- `load.extraDirs`：额外的共享 skill 根目录（优先级最低）。 +- `install.preferBrew`：设为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，然后才回退到其他安装器类型。 +- `install.nodeManager`：`metadata.openclaw.install` + 规范所使用的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使某个 skill 已内置/已安装，也会将其禁用。 +- `entries..apiKey`：为声明了主环境变量的 skill 提供便捷设置（明文字符串或 SecretRef 对象）。 --- @@ -2732,38 +2734,38 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会追加它）。快捷方式 - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 - 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 - **配置变更需要重启 Gateway 网关。** -- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 -- `plugins.entries..apiKey`：插件级 API key 便捷字段（在插件支持时）。 +- `allow`：可选 allowlist（仅加载列出的插件）。`deny` 优先。 +- `plugins.entries..apiKey`：插件级 API key 便捷字段（当插件支持时）。 - `plugins.entries..env`：插件作用域环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks 以及受支持的 bundle 提供的 hook 目录。 -- `plugins.entries..subagent.allowModelOverride`：显式信任该插件可为后台子智能体运行请求按次的 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖的可选规范 `provider/model` 目标允许列表。仅当你有意允许任意模型时才使用 `"*"`。 -- `plugins.entries..config`：由插件定义的配置对象（在可用时通过原生 OpenClaw 插件 schema 验证）。 -- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch 提供商设置。 - - `apiKey`：Firecrawl API key（支持 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks 以及受支持的 bundle 提供 hook 目录。 +- `plugins.entries..subagent.allowModelOverride`：显式信任此插件在后台子智能体运行中请求按次运行的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖所允许的规范 `provider/model` 目标的可选 allowlist。仅在你明确希望允许任意模型时才使用 `"*"`。 +- `plugins.entries..config`：由插件定义的配置对象（在可用时由原生 OpenClaw 插件 schema 验证）。 +- `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 base URL（默认：`https://api.firecrawl.dev`）。 - - `onlyMainContent`：仅提取页面主内容（默认：`true`）。 - - `maxAgeMs`：最大缓存时长（毫秒）（默认：`172800000` / 2 天）。 - - `timeoutSeconds`：抓取请求超时时间（秒）（默认：`60`）。 + - `onlyMainContent`：仅提取页面主要内容（默认：`true`）。 + - `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`：memory dreaming（实验性）设置。阶段和阈值请参阅 [Dreaming](/zh-CN/concepts/dreaming)。 +- `plugins.entries.memory-core.config.dreaming`：memory dreaming（实验性）设置。各阶段和阈值请参见 [Dreaming](/zh-CN/concepts/dreaming)。 - `enabled`：dreaming 主开关（默认 `false`）。 - `frequency`：每次完整 dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。 - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 -- 完整 memory 配置位于 [Memory configuration reference](/zh-CN/reference/memory-config)： +- 完整的 memory 配置位于 [Memory configuration reference](/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`：选择活动 memory 插件 id，或设为 `"none"` 以禁用 memory 插件。 -- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 +- 已启用的 Claude bundle 插件也可从 `settings.json` 贡献嵌入式 Pi 默认值；OpenClaw 会将这些值作为已清洗的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。 +- `plugins.slots.memory`：选择活动的 memory 插件 id，或设为 `"none"` 以禁用 memory 插件。 +- `plugins.slots.contextEngine`：选择活动的上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 - `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 - 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - - 请将 `plugins.installs.*` 视为受管状态；优先使用 CLI 命令而不是手动编辑。 + - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 参见 [Plugins](/zh-CN/tools/plugin)。 @@ -2778,7 +2780,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会追加它）。快捷方式 evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // 仅对受信任的私有网络访问显式启用 + // dangerouslyAllowPrivateNetwork: true, // 仅在受信任的私有网络访问中显式启用 // allowPrivateNetwork: true, // 旧版别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2806,24 +2808,25 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会追加它）。快捷方式 ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 为禁用状态，因此浏览器导航默认保持严格模式。 -- 仅当你有意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP 配置端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的私有网络阻止。 +- 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 为禁用，因此默认会对浏览器导航保持严格限制。 +- 仅当你明确受信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 +- 在严格模式下，远程 CDP 配置目标（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到同样的私有网络阻止。 - `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 -- 在严格模式下，可使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 作为显式例外。 -- 远程配置为仅附加模式（启动/停止/重置已禁用）。 +- 在严格模式下，请使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 进行显式例外配置。 +- 远程配置为仅附加模式（禁用 start/stop/reset）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)； - 当提供商直接给出 DevTools WebSocket URL 时使用 WS(S)。 -- `existing-session` 配置仅限主机使用，并通过 Chrome MCP 而不是 CDP 工作。 -- `existing-session` 配置可以设置 `userDataDir`，以定向特定的 - Chromium 系浏览器配置，例如 Brave 或 Edge。 -- `existing-session` 配置保留当前 Chrome MCP 路由限制： - 使用 snapshot/ref 驱动的操作，而不是基于 CSS 选择器的定向， - 单文件上传 hooks，不支持对话框超时覆盖，不支持 `wait --load networkidle`， - 也不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地受管 `openclaw` 配置会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 情况下才需显式设置 `cdpUrl`。 -- 自动检测顺序：默认浏览器（如果是 Chromium 系）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 + 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)； + 当你的提供商直接给出 DevTools WebSocket URL 时，请使用 WS(S)。 +- `existing-session` 配置仅适用于主机，并使用 Chrome MCP 而不是 CDP。 +- `existing-session` 配置可设置 `userDataDir`，以指向特定 + 基于 Chromium 的浏览器配置，例如 Brave 或 Edge。 +- `existing-session` 配置保留当前 Chrome MCP 路线限制： + 使用 snapshot/ref 驱动的操作而不是基于 CSS selector 的目标定位、单文件上传 + hooks、无对话框超时覆盖、无 `wait --load networkidle`，且无 + `responsebody`、PDF 导出、下载拦截或批量操作。 +- 本地托管的 `openclaw` 配置会自动分配 `cdpPort` 和 `cdpUrl`；只有 + 远程 CDP 才需要显式设置 `cdpUrl`。 +- 自动检测顺序：默认浏览器（如果基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 - 控制服务：仅 loopback（端口由 `gateway.port` 推导，默认 `18791`）。 - `extraArgs` 会向本地 Chromium 启动追加额外标志（例如 `--disable-gpu`、窗口尺寸或调试标志）。 @@ -2844,8 +2847,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会追加它）。快捷方式 } ``` -- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡着色等）。 -- `assistant`：Control UI 身份覆盖。会回退到活动智能体身份。 +- `seamColor`：原生应用 UI 外观的强调色（Talk Mode 气泡着色等）。 +- `assistant`：Control UI 身份覆盖。未设置时回退为当前活动智能体身份。 --- @@ -2879,7 +2882,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会追加它）。快捷方式 basePath: "/openclaw", // root: "dist/control-ui", // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必填 - // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host header origin 回退模式 + // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的基于 Host header 的来源回退模式 // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2893,7 +2896,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会追加它）。快捷方式 // 可选。默认 false。 allowRealIpFallback: false, tools: { - // 额外的 /tools/invoke HTTP 拒绝项 + // 对 /tools/invoke HTTP 的额外拒绝项 deny: ["browser"], // 从默认 HTTP 拒绝列表中移除工具 allow: ["gateway"], @@ -2915,46 +2918,46 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会追加它）。快捷方式 - `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`。 -- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 注意事项**：默认的 `loopback` 绑定会在容器内监听 `127.0.0.1`。在 Docker bridge 网络（`-p 18789:18789`）下，流量会到达 `eth0`，因此 Gateway 网关无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以监听所有接口。 -- **认证**：默认必需。非 loopback 绑定需要 Gateway 网关认证。实际中这意味着使用共享 token/password，或使用带 `gateway.auth.mode: "trusted-proxy"` 的身份感知型反向代理。新手引导向导默认会生成 token。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式将 `gateway.auth.mode` 设为 `token` 或 `password`。若两者都已配置但未设置 mode，启动以及服务安装/修复流程都会失败。 -- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 设置；新手引导提示中不会提供此选项。 -- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知型反向代理，并信任来自 `gateway.trustedProxies` 的身份 headers（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。该模式要求**非 loopback** 的代理来源；同主机 loopback 反向代理不满足 trusted-proxy 认证要求。 -- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份 headers 可满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale header 认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。该无 token 流程假定 Gateway 网关主机可信。当 `tailscale.mode = "serve"` 时默认值为 `true`。 +- **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），而不是主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 +- **Docker 注意事项**：默认的 `loopback` bind 会在容器内部监听 `127.0.0.1`。在 Docker bridge 网络（`-p 18789:18789`）下，流量会到达 `eth0`，因此 Gateway 网关不可达。请使用 `--network host`，或设置 `bind: "lan"`（或使用 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以监听所有接口。 +- **认证**：默认必需。非 loopback 绑定必须启用 Gateway 网关认证。实际这意味着使用共享 token/password，或使用带 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成 token。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式设置 `gateway.auth.mode` 为 `token` 或 `password`。若两者都已配置但 mode 未设置，启动和服务安装/修复流程都会失败。 +- `gateway.auth.mode: "none"`：显式无认证模式。仅适用于受信任的本地 local loopback 配置；新手引导提示中不会提供此选项。 +- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份 headers（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 代理来源；同主机 loopback 反向代理不满足 trusted-proxy 认证要求。 +- `gateway.auth.allowTailscale`：设为 `true` 时，Tailscale Serve 身份 headers 可用于满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale header 认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。该无 token 流程假定 Gateway 网关主机是可信的。当 `tailscale.mode = "serve"` 时默认值为 `true`。 - `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域生效（共享密钥和设备 token 会分别跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 - - 在异步的 Tailscale Serve Control UI 路径上，相同 `{scope, clientIp}` 的失败尝试会在写入失败记录前被串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限流，而不是两个都作为普通不匹配直接通过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；当你有意也要对 localhost 流量做限流时（例如测试环境或严格代理部署），可设为 `false`。 -- 来自浏览器源的 WS 认证尝试始终会在关闭 loopback 豁免的情况下被限流（作为针对基于浏览器的 localhost 暴力尝试的纵深防御）。 + - 在异步 Tailscale Serve Control UI 路径上，相同 `{scope, clientIp}` 的失败尝试会在写入失败记录前串行化。因此，同一客户端的并发错误尝试，可能会在第二个请求时触发限流，而不是两个都竞争通过并仅作为普通不匹配处理。 + - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；如果你明确希望 localhost 流量也被限流（例如测试环境或严格代理部署），请设为 `false`。 +- 来自浏览器源的 WS 认证尝试始终会在禁用 loopback 豁免的情况下进行限流（作为对基于浏览器的 localhost 暴力尝试的纵深防御）。 - 在 loopback 上，这些来自浏览器源的锁定会按规范化后的 `Origin` - 值彼此隔离，因此某个 localhost origin 的重复失败 - 不会自动锁定另一个 origin。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback 绑定）或 `funnel`（公开访问，需要认证）。 -- `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器源允许列表。当预期浏览器客户端来自非 loopback 源时必须设置。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host header origin 策略的部署启用 Host header origin 回退。 + 值隔离，因此来自某个 localhost origin 的重复失败不会自动 + 锁定另一个 origin。 +- `tailscale.mode`：`serve`（仅 tailnet，loopback 绑定）或 `funnel`（公网，要求认证）。 +- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器源 allowlist。当预期浏览器客户端来自非 loopback 源时为必填。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为刻意依赖 Host header 源策略的部署启用基于 Host header 的源回退。 - `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧破窗覆盖，允许对受信任的私有网络 IP 使用明文 `ws://`；默认仍只允许对 loopback 使用明文。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧的破窗覆盖，允许对受信任私有网络 IP 使用明文 `ws://`；默认情况下，明文连接仍仅限 local loopback。 - `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 -- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在向 Gateway 网关发布基于 relay 的注册后，Gateway 网关用于外部 APNs relay 的基础 HTTPS URL。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。 -- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时（毫秒）。默认值：`10000`。 -- 基于 relay 的注册会委派给特定 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并向 Gateway 网关转发一个基于注册作用域的发送授权。其他 Gateway 网关无法复用该已存储注册。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：针对上述 relay 配置的临时环境变量覆盖。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅供开发使用的逃逸开关，允许 loopback HTTP relay URL。生产环境 relay URL 应保持为 HTTPS。 +- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在将基于 relay 的注册发布到 Gateway 网关之后，供其使用的外部 APNs relay 的基础 HTTPS URL。该 URL 必须与编译进 iOS 构建的 relay URL 匹配。 +- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间（毫秒）。默认值为 `10000`。 +- 基于 relay 的注册会被委托给特定 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将一个以注册为作用域的发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用该已存储注册。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：对上述 relay 配置的临时环境变量覆盖。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发的逃生开关，允许使用 loopback HTTP relay URL。生产 relay URL 应保持为 HTTPS。 - `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设为 `0` 可全局禁用健康监控重启。默认值：`5`。 -- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。应保持大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 +- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 - `gateway.channelMaxRestartsPerHour`：滚动一小时内每个渠道/账号允许的最大健康监控重启次数。默认值：`10`。 -- `channels..healthMonitor.enabled`：按渠道选择退出健康监控重启，同时保留全局监控启用。 -- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。设置后其优先级高于渠道级覆盖。 -- 本地 Gateway 网关调用路径仅在 `gateway.auth.*` 未设置时，才可使用 `gateway.remote.*` 作为回退。 -- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但未能解析，则解析会默认拒绝关闭（不会被远程回退掩盖）。 -- `trustedProxies`：负责终止 TLS 或注入转发客户端 headers 的反向代理 IP。仅列出你可控的代理。对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理），loopback 条目仍然有效，但它们**不会**让 loopback 请求具备 `gateway.auth.mode: "trusted-proxy"` 的资格。 -- `allowRealIpFallback`：为 `true` 时，在缺少 `X-Forwarded-For` 时 Gateway 网关会接受 `X-Real-IP`。默认 `false`，采用默认拒绝关闭行为。 -- `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 额外阻止的工具名（扩展默认拒绝列表）。 +- `channels..healthMonitor.enabled`：在保持全局监控启用的同时，按渠道选择退出健康监控重启。 +- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。设置后，其优先级高于渠道级覆盖。 +- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可将 `gateway.remote.*` 用作回退。 +- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但未解析，则解析会以失败关闭方式处理（不会由远程回退掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端 headers 的反向代理 IP。仅列出你控制的代理。loopback 条目对于同主机代理/本地检测配置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**让 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的条件。 +- `allowRealIpFallback`：设为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值 `false`，以保持失败关闭行为。 +- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名（在默认拒绝列表基础上扩展）。 - `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名。 -### OpenAI 兼容端点 +### 兼容 OpenAI 的端点 - Chat Completions：默认禁用。使用 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 - Responses API：`gateway.http.endpoints.responses.enabled`。 @@ -2962,14 +2965,14 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会追加它）。快捷方式 - `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 抓取。 + 空 allowlist 会被视为未设置；请使用 `gateway.http.endpoints.responses.files.allowUrl=false` + 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 获取。 - 可选响应加固 header： - - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你可控的 HTTPS 源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） + - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 -在同一台主机上运行多个 Gateway 网关实例，并使用唯一端口和状态目录： +在一台主机上运行多个 Gateway 网关，并为其分配不同端口和状态目录： ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -2998,9 +3001,9 @@ openclaw gateway --port 19001 ``` - `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS/WSS）（默认：`false`）。 -- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书/密钥对；仅供本地/开发使用。 +- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书/密钥对；仅适用于本地/开发用途。 - `certPath`：TLS 证书文件的文件系统路径。 -- `keyPath`：TLS 私钥文件的文件系统路径；应保持权限受限。 +- `keyPath`：TLS 私钥文件的文件系统路径；应限制访问权限。 - `caPath`：用于客户端验证或自定义信任链的可选 CA bundle 路径。 ### `gateway.reload` @@ -3017,11 +3020,11 @@ openclaw gateway --port 19001 } ``` -- `mode`：控制运行时如何应用配置编辑。 +- `mode`：控制如何在运行时应用配置编辑。 - `"off"`：忽略实时编辑；变更需要显式重启。 - `"restart"`：配置变更时始终重启 Gateway 网关进程。 - `"hot"`：在进程内应用变更而不重启。 - - `"hybrid"`（默认）：先尝试热重载；如有需要则回退为重启。 + - `"hybrid"`（默认）：先尝试热重载；如有需要再回退到重启。 - `debounceMs`：应用配置变更前的防抖窗口（毫秒）（非负整数）。 - `deferralTimeoutMs`：在强制重启前等待进行中操作完成的最长时间（毫秒）（默认：`300000` = 5 分钟）。 @@ -3050,7 +3053,7 @@ openclaw gateway --port 19001 wakeMode: "now", name: "Gmail", sessionKey: "hook:gmail:{{messages[0].id}}", - messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}", + messageTemplate: "发件人：{{messages[0].from}}\n主题：{{messages[0].subject}}\n{{messages[0].snippet}}", deliver: true, channel: "last", model: "openai/gpt-5.4-mini", @@ -3061,11 +3064,11 @@ openclaw gateway --port 19001 ``` 认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 -会拒绝查询字符串中的 hook token。 +拒绝使用查询字符串传递 hook token。 -验证和安全说明： +验证与安全说明： -- `hooks.enabled=true` 需要非空的 `hooks.token`。 +- `hooks.enabled=true` 要求提供非空的 `hooks.token`。 - `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关 token 会被拒绝。 - `hooks.path` 不能为 `/`；请使用专用子路径，例如 `/hooks`。 - 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 @@ -3074,7 +3077,7 @@ openclaw gateway --port 19001 - `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` 解析 @@ -3082,15 +3085,15 @@ openclaw gateway --port 19001 - `match.path` 会匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 - `match.source` 会匹配通用路径中的某个负载字段。 - 像 `{{messages[0].subject}}` 这样的模板会从负载中读取。 -- `transform` 可指向返回 hook 操作的 JS/TS 模块。 - - `transform.module` 必须是相对路径，并保持在 `hooks.transformsDir` 内（绝对路径和路径穿越都会被拒绝）。 +- `transform` 可以指向返回 hook action 的 JS/TS 模块。 + - `transform.module` 必须是相对路径，并且保持在 `hooks.transformsDir` 内（绝对路径和路径穿越都会被拒绝）。 - `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。 -- `allowedAgentIds`：限制显式路由（`*` 或省略 = 全部允许，`[]` = 全部拒绝）。 -- `defaultSessionKey`：可选的固定会话键，用于未显式提供 `sessionKey` 的 hook 智能体运行。 +- `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。 +- `defaultSessionKey`：对于没有显式 `sessionKey` 的 hook 智能体运行，可选的固定会话键。 - `allowRequestSessionKey`：允许 `/hooks/agent` 调用方设置 `sessionKey`（默认：`false`）。 -- `allowedSessionKeyPrefixes`：针对显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。 -- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。 -- `model` 会为本次 hook 运行覆盖 LLM（如果设置了模型目录，则该模型必须被允许）。 +- `allowedSessionKeyPrefixes`：针对显式 `sessionKey` 值（请求 + 映射）的可选前缀 allowlist，例如 `["hook:"]`。 +- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认值为 `last`。 +- `model` 会覆盖此次 hook 运行所用的 LLM（若设置了模型目录，则该模型必须被允许）。 @@ -3118,7 +3121,7 @@ openclaw gateway --port 19001 ``` - 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。 -- 不要在 Gateway 网关旁边单独运行另一个 `gog gmail watch serve`。 +- 不要在 Gateway 网关旁边单独运行 `gog gmail watch serve`。 --- @@ -3134,18 +3137,18 @@ 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 网关认证（token/password/trusted-proxy），与其他 Gateway 网关 HTTP 表面相同。 -- Node WebViews 通常不会发送认证 headers；在 node 完成配对并连接后，Gateway 网关会通告面向 node 作用域的能力 URL，用于访问 canvas/A2UI。 -- 能力 URL 绑定到活动的 node WS 会话，并且会很快过期。不使用基于 IP 的回退。 -- 会将实时重载客户端注入到已提供的 HTML 中。 -- 为空时会自动创建初始 `index.html`。 +- 非 loopback 绑定：canvas 路由与其他 Gateway 网关 HTTP 面相同，需要 Gateway 网关认证（token/password/trusted-proxy）。 +- Node WebView 通常不会发送认证 headers；在某个 node 完成配对并连接后，Gateway 网关会为其广播 node 作用域的 capability URL，用于访问 canvas/A2UI。 +- Capability URL 绑定到当前活动的 node WS 会话，并且会很快过期。不使用基于 IP 的回退。 +- 会向提供的 HTML 注入 live-reload 客户端。 +- 当目录为空时，会自动创建起始 `index.html`。 - 也会在 `/__openclaw__/a2ui/` 提供 A2UI。 - 变更需要重启 Gateway 网关。 -- 对于大型目录或出现 `EMFILE` 错误时，请禁用实时重载。 +- 对于大目录或出现 `EMFILE` 错误时，请禁用 live reload。 --- @@ -3167,7 +3170,7 @@ openclaw gateway --port 19001 - `full`：包含 `cliPath` + `sshPort`。 - 主机名默认为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 -### 广域网（DNS-SD） +### 广域（DNS-SD） ```json5 { @@ -3177,7 +3180,7 @@ openclaw gateway --port 19001 } ``` -会在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。对于跨网络设备发现，请配合 DNS 服务器（推荐 CoreDNS）+ Tailscale 分离 DNS 一起使用。 +会在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。若要实现跨网络设备发现，请配合 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS 一起使用。 设置：`openclaw dns setup --apply`。 @@ -3202,14 +3205,14 @@ openclaw gateway --port 19001 } ``` -- 内联环境变量仅在进程环境中缺少该键时才会应用。 +- 仅当进程环境中缺少该键时，才会应用内联环境变量。 - `.env` 文件：当前工作目录 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 - `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。 - 完整优先级请参见 [Environment](/zh-CN/help/environment)。 ### 环境变量替换 -可在任意配置字符串中通过 `${VAR_NAME}` 引用环境变量： +可以在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -3220,37 +3223,37 @@ openclaw gateway --port 19001 ``` - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失/为空的变量会在配置加载时抛出错误。 -- 使用 `$${VAR}` 转义为字面量 `${VAR}`。 +- 缺失/为空的变量会在加载配置时抛出错误。 +- 使用 `$${VAR}` 可转义为字面量 `${VAR}`。 - 适用于 `$include`。 --- ## Secrets -SecretRef 是增量能力：明文值仍然可用。 +SecretRef 是增量能力：明文值依然可用。 ### `SecretRef` -使用如下对象结构： +使用以下对象形态： ```json5 { 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"` 的 id 不能包含 `.` 或 `..` 形式的斜杠分隔路径段（例如 `a/../b` 会被拒绝） -### 支持的凭证表面 +### 支持的凭证面 -- 规范矩阵：[SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) -- `secrets apply` 会面向受支持的 `openclaw.json` 凭证路径。 -- `auth-profiles.json` 引用已纳入运行时解析和审计覆盖范围。 +- 规范矩阵： [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) +- `secrets apply` 会针对受支持的 `openclaw.json` 凭证路径执行。 +- `auth-profiles.json` 引用也会纳入运行时解析和审计覆盖范围。 ### Secret 提供商配置 @@ -3280,15 +3283,15 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -注意： +说明： - `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 - `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin/stdout 使用协议负载。 -- 默认会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可在验证解析后目标路径的同时允许符号链接路径。 +- 默认会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时验证其解析后的目标路径。 - 如果配置了 `trustedDirs`，则受信任目录检查会应用到解析后的目标路径。 -- 默认情况下，`exec` 子进程环境是最小化的；请通过 `passEnv` 显式传递所需变量。 -- Secret 引用会在激活时解析为内存快照，之后请求路径仅从该快照读取。 -- 激活期间会应用活动表面过滤：已启用表面上的未解析引用会导致启动/重载失败，而非活动表面会被跳过并附带诊断信息。 +- `exec` 子进程环境默认最小化；请使用 `passEnv` 显式传递所需变量。 +- Secret 引用会在激活时解析为内存快照，随后请求路径只读取该快照。 +- 激活期间会应用活动面过滤：已启用面的未解析引用会导致启动/重载失败，而非活动面则会跳过并附带诊断信息。 --- @@ -3311,12 +3314,12 @@ SecretRef 是增量能力：明文值仍然可用。 ``` - 按智能体配置文件存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 支持静态凭证模式的值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- `auth-profiles.json` 支持静态凭证模式的值级引用（`api_key` 对应 `keyRef`，`token` 对应 `tokenRef`）。 - OAuth 模式配置文件（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 -- 静态运行时凭证来自已解析的内存快照；发现旧版静态 `auth.json` 条目时会将其清理。 -- 旧版 OAuth 会从 `~/.openclaw/credentials/oauth.json` 导入。 +- 静态运行时凭证来自已解析的内存快照；发现旧版静态 `auth.json` 条目时会进行清理。 +- 旧版 OAuth 从 `~/.openclaw/credentials/oauth.json` 导入。 - 参见 [OAuth](/zh-CN/concepts/oauth)。 -- secrets 运行时行为以及 `audit/configure/apply` 工具：参见 [Secrets Management](/zh-CN/gateway/secrets)。 +- Secrets 运行时行为以及 `audit/configure/apply` 工具： [Secrets Management](/zh-CN/gateway/secrets)。 ### `auth.cooldowns` @@ -3338,20 +3341,21 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- `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`：对于 overloaded 错误，在切换到模型回退前，同一提供商 auth-profile 允许的最大轮换次数（默认：`1`）。例如 `ModelNotReadyException` 这类提供商繁忙形态会落入此类。 -- `overloadedBackoffMs`：重试 overloaded 提供商/profile 轮换前的固定延迟（毫秒）（默认：`0`）。 -- `rateLimitedProfileRotations`：对于 rate-limit 错误，在切换到模型回退前，同一提供商 auth-profile 允许的最大轮换次数（默认：`1`）。该 rate-limit 桶还包括诸如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted` 之类具有提供商特征的文本。 +- `billingBackoffHours`：当某个配置文件因真实 + 计费/余额不足错误而失败时的基础回退时间（小时）（默认：`5`）。显式计费文本 + 即使出现在 `401`/`403` 响应中，仍可能落到这里，但提供商专属文本 + 匹配器会保持限定在其所属提供商范围内（例如 OpenRouter + 的 `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或 + organization/workspace 支出上限消息则仍会落在 `rate_limit` 路径 + 中。 +- `billingBackoffHoursByProvider`：可选的按提供商覆盖计费回退小时数。 +- `billingMaxHours`：计费回退指数增长的上限小时数（默认：`24`）。 +- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础回退时间（分钟）（默认：`10`）。 +- `authPermanentMaxMinutes`：`auth_permanent` 回退增长的上限分钟数（默认：`60`）。 +- `failureWindowHours`：用于回退计数器的滚动窗口（小时）（默认：`24`）。 +- `overloadedProfileRotations`：在切换到模型回退之前，对于 overloaded 错误允许的同提供商 auth-profile 轮换最大次数（默认：`1`）。像 `ModelNotReadyException` 这类提供商繁忙形态会归入这里。 +- `overloadedBackoffMs`：在重试 overloaded 提供商/配置文件轮换前的固定延迟（默认：`0`）。 +- `rateLimitedProfileRotations`：在切换到模型回退之前，对于 rate-limit 错误允许的同提供商 auth-profile 轮换最大次数（默认：`1`）。该 rate-limit 桶也包括诸如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted` 等提供商形态文本。 --- @@ -3373,7 +3377,7 @@ SecretRef 是增量能力：明文值仍然可用。 - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 - 设置 `logging.file` 可使用固定路径。 - 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 -- `maxFileBytes`：写入被抑制前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 +- `maxFileBytes`：日志文件在停止写入前允许的最大大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 --- @@ -3410,20 +3414,20 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- `enabled`：instrumentation 输出的总开关（默认：`true`）。 -- `flags`：用于启用定向日志输出的标志字符串数组（支持诸如 `"telegram.*"` 或 `"*"` 的通配符）。 -- `stuckSessionWarnMs`：当会话仍处于处理状态时，发出卡住会话警告的时长阈值（毫秒）。 -- `otel.enabled`：启用 OpenTelemetry 导出管道（默认：`false`）。 +- `enabled`：检测输出的主开关（默认：`true`）。 +- `flags`：用于启用定向日志输出的标志字符串数组（支持如 `"telegram.*"` 或 `"*"` 这样的通配符）。 +- `stuckSessionWarnMs`：当某个会话持续处于处理状态时，用于发出卡住会话警告的年龄阈值（毫秒）。 +- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。 - `otel.endpoint`：OTel 导出的采集器 URL。 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 -- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据 headers。 -- `otel.serviceName`：资源属性的服务名称。 +- `otel.headers`：随 OTel 导出请求一起发送的额外 HTTP/gRPC 元数据 headers。 +- `otel.serviceName`：资源属性中的服务名称。 - `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。 -- `otel.sampleRate`：trace 采样率，范围 `0`–`1`。 +- `otel.sampleRate`：`0`–`1` 的 trace 采样率。 - `otel.flushIntervalMs`：周期性 telemetry 刷新间隔（毫秒）。 -- `cacheTrace.enabled`：为嵌入式运行记录缓存追踪快照（默认：`false`）。 -- `cacheTrace.filePath`：缓存追踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存追踪输出中包含的内容（默认均为 `true`）。 +- `cacheTrace.enabled`：为嵌入式运行记录缓存跟踪快照（默认：`false`）。 +- `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含哪些内容（默认均为 `true`）。 --- @@ -3445,12 +3449,12 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- `channel`：npm/git 安装的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。 -- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认：`true`）。 +- `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`）。 +- `auto.stableDelayHours`：stable 渠道自动应用前的最小延迟小时数（默认：`6`；最大：`168`）。 +- `auto.stableJitterHours`：stable 渠道额外的发布扩散窗口小时数（默认：`12`；最大：`168`）。 +- `auto.betaCheckIntervalHours`：beta 渠道检查运行的间隔小时数（默认：`1`；最大：`24`）。 --- @@ -3483,22 +3487,22 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- `enabled`：ACP 功能的全局开关（默认：`false`）。 -- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 -- `backend`：默认 ACP 运行时后端 id（必须匹配某个已注册 ACP 运行时插件）。 -- `defaultAgent`：当派生会话未指定显式目标时，ACP 目标智能体 id 的回退值。 -- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；空列表表示无额外限制。 -- `maxConcurrentSessions`：最大并发活动 ACP 会话数。 -- `stream.coalesceIdleMs`：流式文本的空闲合并窗口（毫秒）。 -- `stream.maxChunkChars`：拆分流式块投影前允许的最大块大小。 -- `stream.repeatSuppression`：按轮次抑制重复的状态/工具行（默认：`true`）。 -- `stream.deliveryMode`：`"live"` 逐步流式传输；`"final_only"` 会缓冲到轮次终结事件后再输出。 +- `enabled`：全局 ACP 功能门控（默认：`false`）。 +- `dispatch.enabled`：ACP 会话回合分发的独立门控（默认：`true`）。设为 `false` 时，可保留 ACP 命令可用，但阻止执行。 +- `backend`：默认 ACP 运行时后端 id（必须匹配某个已注册的 ACP 运行时插件）。 +- `defaultAgent`：当生成时未指定显式目标时，使用的回退 ACP 目标智能体 id。 +- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id allowlist；为空表示无额外限制。 +- `maxConcurrentSessions`：并发活跃 ACP 会话的最大数量。 +- `stream.coalesceIdleMs`：流式文本的空闲刷新窗口（毫秒）。 +- `stream.maxChunkChars`：在拆分流式分块投影前允许的最大分块大小。 +- `stream.repeatSuppression`：按回合抑制重复状态/工具行（默认：`true`）。 +- `stream.deliveryMode`：`"live"` 会增量流式传输；`"final_only"` 会缓冲到回合终止事件后再发送。 - `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前的分隔符（默认：`"paragraph"`）。 -- `stream.maxOutputChars`：每个 ACP 轮次投影的 assistant 输出最大字符数。 +- `stream.maxOutputChars`：每个 ACP 回合允许投影的 assistant 输出最大字符数。 - `stream.maxSessionUpdateChars`：投影 ACP 状态/更新行的最大字符数。 -- `stream.tagVisibility`：标签名称到布尔可见性覆盖的映射记录，用于流式事件。 -- `runtime.ttlMinutes`：ACP 会话 worker 在进入可清理状态前的空闲 TTL（分钟）。 -- `runtime.installCommand`：在引导 ACP 运行时环境时执行的可选安装命令。 +- `stream.tagVisibility`：流式事件中标签名称到布尔可见性覆盖的记录。 +- `runtime.ttlMinutes`：ACP 会话 worker 在可被清理前的空闲 TTL（分钟）。 +- `runtime.installCommand`：在引导 ACP 运行时环境时运行的可选安装命令。 --- @@ -3514,11 +3518,11 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- `cli.banner.taglineMode` 控制横幅标语样式： +- `cli.banner.taglineMode` 控制 banner 标语风格： - `"random"`（默认）：轮换的有趣/季节性标语。 - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 - - `"off"`：不显示标语文本（横幅标题/版本仍会显示）。 -- 若要隐藏整个横幅（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 + - `"off"`：不显示标语文本（仍显示 banner 标题/版本）。 +- 若要隐藏整个 banner（而不仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- @@ -3542,13 +3546,13 @@ SecretRef 是增量能力：明文值仍然可用。 ## 身份 -请参阅 [Agent defaults](#agent-defaults) 下 `agents.list` 的身份字段。 +请参见 [Agent defaults](#agent-defaults) 下 `agents.list` 的身份字段。 --- -## Bridge protocol（旧版节点，历史参考）（旧版，已移除） +## Bridge protocol（旧版节点，历史参考，已移除） -当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可移除未知键）。 +当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前，验证会失败；`openclaw doctor --fix` 可去除未知键）。 @@ -3577,8 +3581,8 @@ SecretRef 是增量能力：明文值仍然可用。 cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // 已弃用，供已存储且 notify:true 的任务使用的回退值 - webhookToken: "replace-with-dedicated-token", // 可选的 outbound webhook 认证 bearer token + webhook: "https://example.invalid/legacy", // 已弃用：存量 notify:true 作业的回退 + webhookToken: "replace-with-dedicated-token", // 出站 webhook 认证的可选 bearer token sessionRetention: "24h", // 时长字符串或 false runLog: { maxBytes: "2mb", // 默认 2_000_000 字节 @@ -3588,11 +3592,11 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- `sessionRetention`：在从 `sessions.json` 修剪前，保留已完成的隔离 cron 运行会话的时长。也控制已归档且被删除的 cron transcript 的清理。默认值：`24h`；设为 `false` 可禁用。 -- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在触发修剪前允许的最大大小。默认值：`2_000_000` 字节。 -- `runLog.keepLines`：触发运行日志修剪时保留的最新行数。默认值：`2000`。 -- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略，则不发送认证 header。 -- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍保留 `notify: true` 的已存储任务。 +- `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；若省略则不会发送认证 header。 +- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍保留 `notify: true` 的存量作业。 ### `cron.retry` @@ -3608,11 +3612,11 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- `maxAttempts`：单次任务在瞬时错误下允许的最大重试次数（默认：`3`；范围：`0`–`10`）。 -- `backoffMs`：每次重试尝试使用的退避延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。 -- `retryOn`：触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时会重试所有瞬时错误类型。 +- `maxAttempts`：一次性作业在瞬态错误下的最大重试次数（默认：`3`；范围：`0`–`10`）。 +- `backoffMs`：每次重试尝试对应的回退延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。 +- `retryOn`：会触发重试的错误类型——`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时会重试所有瞬态类型。 -仅适用于单次 cron 任务。周期性任务使用独立的失败处理机制。 +仅适用于一次性 cron 作业。周期性作业使用独立的失败处理逻辑。 ### `cron.failureAlert` @@ -3630,10 +3634,10 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- `enabled`：启用 cron 任务失败告警（默认：`false`）。 +- `enabled`：启用 cron 作业失败告警（默认：`false`）。 - `after`：连续失败达到多少次后触发告警（正整数，最小值：`1`）。 -- `cooldownMs`：同一任务重复告警之间的最小间隔（毫秒）（非负整数）。 -- `mode`：投递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 通过已配置 webhook POST 发送。 +- `cooldownMs`：同一作业重复告警之间的最小间隔（毫秒）（非负整数）。 +- `mode`：投递模式——`"announce"` 通过渠道消息发送；`"webhook"` 向已配置的 webhook 发送 `POST`。 - `accountId`：用于限定告警投递范围的可选账号或渠道 id。 ### `cron.failureDestination` @@ -3651,14 +3655,14 @@ SecretRef 是增量能力：明文值仍然可用。 } ``` -- 所有任务通用的 cron 失败通知默认目标。 -- `mode`：`"announce"` 或 `"webhook"`；当存在足够目标数据时，默认值为 `"announce"`。 -- `channel`：announce 投递的渠道覆盖。`"last"` 会复用上次已知的投递渠道。 -- `to`：显式的 announce 目标或 webhook URL。在 webhook 模式下为必填。 +- 所有作业共享的默认 cron 失败通知目标。 +- `mode`：`"announce"` 或 `"webhook"`；当存在足够目标数据时，默认使用 `"announce"`。 +- `channel`：用于 announce 投递的渠道覆盖。`"last"` 会复用最近一次已知投递渠道。 +- `to`：显式的 announce 目标或 webhook URL。webhook 模式下为必填。 - `accountId`：可选的投递账号覆盖。 -- 按任务的 `delivery.failureDestination` 会覆盖此全局默认值。 -- 当全局和按任务的失败目标都未设置时，已通过 `announce` 投递的任务在失败时会回退到其主 announce 目标。 -- 除非任务的主 `delivery.mode` 为 `"webhook"`，否则 `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的任务。 +- 按作业的 `delivery.failureDestination` 会覆盖该全局默认值。 +- 当全局和按作业失败目标都未设置时，已经通过 `announce` 投递的作业在失败时会回退到该主 announce 目标。 +- 除非作业的主 `delivery.mode` 为 `"webhook"`，否则 `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的作业。 参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [background tasks](/zh-CN/automation/tasks) 进行跟踪。 @@ -3668,34 +3672,34 @@ SecretRef 是增量能力：明文值仍然可用。 在 `tools.media.models[].args` 中展开的模板占位符： -| 变量 | 描述 | -| ------------------ | ------------------------------------------------- | -| `{{Body}}` | 完整的入站消息正文 | -| `{{RawBody}}` | 原始正文（无历史/发送者包装） | -| `{{BodyStripped}}` | 去除了群组提及的正文 | -| `{{From}}` | 发送者标识符 | -| `{{To}}` | 目标标识符 | -| `{{MessageSid}}` | 渠道消息 id | -| `{{SessionId}}` | 当前会话 UUID | -| `{{IsNewSession}}` | 新会话创建时为 `"true"` | -| `{{MediaUrl}}` | 入站媒体伪 URL | -| `{{MediaPath}}` | 本地媒体路径 | -| `{{MediaType}}` | 媒体类型（image/audio/document/…） | -| `{{Transcript}}` | 音频 transcript | -| `{{Prompt}}` | 为 CLI 条目解析后的媒体提示 | -| `{{MaxChars}}` | 为 CLI 条目解析后的最大输出字符数 | -| `{{ChatType}}` | `"direct"` 或 `"group"` | -| `{{GroupSubject}}` | 群组主题（尽力提供） | -| `{{GroupMembers}}` | 群组成员预览（尽力提供） | -| `{{SenderName}}` | 发送者显示名称（尽力提供） | -| `{{SenderE164}}` | 发送者电话号码（尽力提供） | +| 变量 | 说明 | +| ------------------ | ------------------------------------- | +| `{{Body}}` | 完整入站消息正文 | +| `{{RawBody}}` | 原始正文（无历史/发送者包装） | +| `{{BodyStripped}}` | 去除了群组提及的正文 | +| `{{From}}` | 发送者标识符 | +| `{{To}}` | 目标标识符 | +| `{{MessageSid}}` | 渠道消息 id | +| `{{SessionId}}` | 当前会话 UUID | +| `{{IsNewSession}}` | 当新会话已创建时为 `"true"` | +| `{{MediaUrl}}` | 入站媒体伪 URL | +| `{{MediaPath}}` | 本地媒体路径 | +| `{{MediaType}}` | 媒体类型（image/audio/document/…） | +| `{{Transcript}}` | 音频转录 | +| `{{Prompt}}` | 为 CLI 条目解析出的媒体提示 | +| `{{MaxChars}}` | 为 CLI 条目解析出的最大输出字符数 | +| `{{ChatType}}` | `"direct"` 或 `"group"` | +| `{{GroupSubject}}` | 群组主题（尽力而为） | +| `{{GroupMembers}}` | 群组成员预览（尽力而为） | +| `{{SenderName}}` | 发送者显示名（尽力而为） | +| `{{SenderE164}}` | 发送者电话号码（尽力而为） | | `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | --- -## 配置 include（`$include`） +## 配置包含（`$include`） -将配置拆分到多个文件中： +将配置拆分为多个文件： ```json5 // ~/.openclaw/openclaw.json @@ -3710,13 +3714,13 @@ SecretRef 是增量能力：明文值仍然可用。 **合并行为：** -- 单个文件：替换所在的对象。 -- 文件数组：按顺序进行深度合并（后者覆盖前者）。 -- 同级键：会在 includes 之后合并（覆盖被 include 的值）。 -- 嵌套 includes：最多支持 10 层深度。 -- 路径：相对于发起 include 的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）之内。仅当最终仍解析到该边界内时，才允许绝对路径/`../` 形式。 -- 错误：对缺失文件、解析错误和循环 include 都会给出清晰消息。 +- 单文件：替换其所在的包含对象。 +- 文件数组：按顺序深度合并（后者覆盖前者）。 +- 同级键：在 includes 之后合并（覆盖被包含的值）。 +- 嵌套 includes：最多 10 层。 +- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）之内。仅当绝对路径/`../` 形式最终仍解析到该边界内时才允许。 +- 错误：会为缺失文件、解析错误和循环包含提供清晰消息。 --- -_相关内容：[Configuration](/zh-CN/gateway/configuration) · [Configuration Examples](/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)_ diff --git a/docs/zh-CN/gateway/heartbeat.md b/docs/zh-CN/gateway/heartbeat.md index 509c6fcfe..4e54aa54c 100644 --- a/docs/zh-CN/gateway/heartbeat.md +++ b/docs/zh-CN/gateway/heartbeat.md @@ -1,40 +1,40 @@ --- read_when: - - 调整心跳频率或消息传递方式 + - 调整心跳频率或消息内容 - 决定在计划任务中使用心跳还是 cron summary: 心跳轮询消息和通知规则 title: 心跳 x-i18n: - generated_at: "2026-04-07T23:54:15Z" + generated_at: "2026-04-10T23:44:34Z" model: gpt-5.4 provider: openai - source_hash: a8021d747637060eacb91ec5f75904368a08790c19f4fca32acda8c8c0a25e41 + source_hash: e4485072148753076d909867a623696829bf4a82dcd0479b95d5d0cae43100b0 source_path: gateway/heartbeat.md workflow: 15 --- -# 心跳 (Gateway 网关) +# 心跳（Gateway 网关） -> **心跳 vs Cron？** 参见 [Automation & Tasks](/zh-CN/automation)，了解何时使用它们各自更合适。 +> **心跳还是 Cron？** 关于何时使用两者，请参阅 [自动化与任务](/zh-CN/automation)。 -心跳会在主会话中运行**周期性的智能体轮次**，让模型能够提示任何需要关注的事项，同时不会对你造成刷屏。 +心跳会在主会话中运行**周期性的智能体轮次**，这样模型就能提示任何需要注意的事项，而不会不停打扰你。 -心跳是一个计划执行的主会话轮次——它**不会**创建[后台任务](/zh-CN/automation/tasks)记录。 -任务记录用于脱离式工作（ACP 运行、子智能体、隔离的 cron 作业）。 +心跳是一次计划执行的主会话轮次——它**不会**创建[后台任务](/zh-CN/automation/tasks)记录。 +任务记录用于脱离主会话的工作（ACP 运行、子智能体、隔离的 cron 作业）。 -故障排除：[Scheduled Tasks](/zh-CN/automation/cron-jobs#troubleshooting) +故障排除：[计划任务](/zh-CN/automation/cron-jobs#troubleshooting) -## 快速开始（初学者） +## 快速开始（适合初学者） -1. 保持心跳启用状态（默认是 `30m`，对于 Anthropic OAuth/token 认证，包括 Claude CLI 复用，则为 `1h`），或者设置你自己的频率。 -2. 在智能体工作区中创建一个简短的 `HEARTBEAT.md` 清单或 `tasks:` 块（可选但推荐）。 -3. 决定心跳消息应发送到哪里（默认是 `target: "none"`；设置 `target: "last"` 可路由到最近联系对象）。 -4. 可选：启用心跳推理传递以提高透明度。 +1. 保持心跳启用状态（默认是 `30m`，如果使用 Anthropic OAuth/令牌凭证认证，包括复用 Claude CLI，则默认是 `1h`），或者设置你自己的频率。 +2. 在智能体工作区中创建一个很小的 `HEARTBEAT.md` 检查清单或 `tasks:` 块（可选但推荐）。 +3. 决定心跳消息应该发送到哪里（默认是 `target: "none"`；设置 `target: "last"` 可路由到最近一次联系对象）。 +4. 可选：启用心跳推理内容投递，以提升透明度。 5. 可选：如果心跳运行只需要 `HEARTBEAT.md`，可使用轻量级引导上下文。 -6. 可选：启用隔离会话，以避免每次心跳都发送完整的对话历史。 +6. 可选：启用隔离会话，避免每次心跳都发送完整会话历史。 7. 可选：将心跳限制在活跃时段内（本地时间）。 -示例配置： +配置示例： ```json5 { @@ -42,12 +42,12 @@ x-i18n: defaults: { heartbeat: { every: "30m", - target: "last", // 显式发送到最近联系对象（默认是 "none"） + target: "last", // 显式投递到最近一次联系对象（默认是 "none"） directPolicy: "allow", // 默认：允许直接/私信目标；设为 "block" 可抑制发送 - lightContext: true, // 可选：只从引导文件中注入 HEARTBEAT.md - isolatedSession: true, // 可选：每次运行都使用全新会话（无对话历史） + lightContext: true, // 可选：仅从引导文件中注入 HEARTBEAT.md + isolatedSession: true, // 可选：每次运行都使用新会话（无会话历史） // activeHours: { start: "08:00", end: "24:00" }, - // includeReasoning: true, // 可选：同时发送单独的 `Reasoning:` 消息 + // includeReasoning: true, // 可选：也发送单独的 `Reasoning:` 消息 }, }, }, @@ -56,33 +56,33 @@ x-i18n: ## 默认值 -- 间隔：`30m`（或者在检测到的认证模式为 Anthropic OAuth/token 认证时为 `1h`，包括 Claude CLI 复用）。设置 `agents.defaults.heartbeat.every` 或针对每个智能体设置 `agents.list[].heartbeat.every`；使用 `0m` 可禁用。 +- 间隔：`30m`（如果检测到的认证模式是 Anthropic OAuth/令牌凭证认证，包括复用 Claude CLI，则为 `1h`）。设置 `agents.defaults.heartbeat.every` 或按智能体设置 `agents.list[].heartbeat.every`；使用 `0m` 可禁用。 - 提示词正文（可通过 `agents.defaults.heartbeat.prompt` 配置）： `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.` -- 心跳提示词会**原样**作为用户消息发送。只有当默认智能体启用了心跳，并且该运行在内部被标记后，系统提示词才会包含一个“Heartbeat”部分。 -- 当使用 `0m` 禁用心跳时，普通运行也会从引导上下文中省略 `HEARTBEAT.md`，这样模型就不会看到仅供心跳使用的说明。 -- 活跃时段（`heartbeat.activeHours`）会在配置的时区中进行检查。 - 在该时间窗口之外，心跳会被跳过，直到窗口内的下一个 tick。 +- 心跳提示词会作为用户消息**原样**发送。系统提示词仅在默认智能体启用了心跳且本次运行在内部被标记为心跳时，才会包含一个“Heartbeat”部分。 +- 当心跳通过 `0m` 禁用时，普通运行也会从引导上下文中省略 `HEARTBEAT.md`，这样模型就不会看到仅供心跳使用的指令。 +- 活跃时段（`heartbeat.activeHours`）会按照已配置的时区进行检查。 + 在窗口之外，心跳会被跳过，直到下一个落在窗口内的时钟周期。 ## 心跳提示词的用途 -默认提示词刻意保持宽泛： +默认提示词是有意保持宽泛的： -- **后台任务**：“Consider outstanding tasks” 会推动智能体审查待跟进事项（收件箱、日历、提醒、排队工作），并提示任何紧急内容。 -- **人工检查**：“Checkup sometimes on your human during day time” 会推动偶尔发送轻量级的“你有什么需要吗？”消息，但会根据你配置的本地时区避免夜间刷屏（参见 [/concepts/timezone](/zh-CN/concepts/timezone)）。 +- **后台任务**：“Consider outstanding tasks” 会推动智能体检查待处理事项（收件箱、日历、提醒、排队工作），并提示任何紧急内容。 +- **人工检查**：“Checkup sometimes on your human during day time” 会推动偶尔发送轻量级的“你需要什么帮助吗？”消息，但会通过你配置的本地时区避免夜间打扰（见 [/concepts/timezone](/zh-CN/concepts/timezone)）。 心跳可以对已完成的[后台任务](/zh-CN/automation/tasks)作出反应，但心跳运行本身不会创建任务记录。 -如果你希望心跳执行非常具体的事情（例如“检查 Gmail PubSub 统计信息”或“验证 Gateway 网关健康状态”），请将 `agents.defaults.heartbeat.prompt`（或 `agents.list[].heartbeat.prompt`）设置为自定义正文（原样发送）。 +如果你希望心跳执行非常具体的事情（例如“检查 Gmail PubSub 统计”或“验证 Gateway 网关健康状态”），请将 `agents.defaults.heartbeat.prompt`（或 `agents.list[].heartbeat.prompt`）设置为自定义正文（会原样发送）。 ## 响应约定 -- 如果没有任何事项需要关注，请回复 **`HEARTBEAT_OK`**。 -- 在心跳运行期间，如果 `HEARTBEAT_OK` 出现在回复的**开头或结尾**，OpenClaw 会将其视为确认。该标记会被移除；如果剩余内容**≤ `ackMaxChars`**（默认：300），则整条回复会被丢弃。 +- 如果没有任何需要关注的内容，请回复 **`HEARTBEAT_OK`**。 +- 在心跳运行期间，如果 `HEARTBEAT_OK` 出现在回复的**开头或结尾**，OpenClaw 会将其视为确认信号。当剩余内容**≤ `ackMaxChars`**（默认：300）时，该标记会被移除，并且整条回复会被丢弃。 - 如果 `HEARTBEAT_OK` 出现在回复的**中间**，则不会被特殊处理。 - 对于提醒消息，**不要**包含 `HEARTBEAT_OK`；只返回提醒文本。 -在心跳之外，如果消息开头或结尾意外出现 `HEARTBEAT_OK`，它会被移除并记录日志；如果消息只有 `HEARTBEAT_OK`，则该消息会被丢弃。 +在非心跳场景下，如果消息开头或结尾意外出现 `HEARTBEAT_OK`，它会被移除并记录日志；如果整条消息只有 `HEARTBEAT_OK`，则会被丢弃。 ## 配置 @@ -91,35 +91,34 @@ x-i18n: agents: { defaults: { heartbeat: { - every: "30m", // 默认：30m（0m 禁用） + every: "30m", // 默认：30m（0m 表示禁用） model: "anthropic/claude-opus-4-6", - includeReasoning: false, // 默认：false（可用时发送单独的 Reasoning: 消息） + includeReasoning: false, // 默认：false（可用时投递单独的 Reasoning: 消息） lightContext: false, // 默认：false；true 时仅保留工作区引导文件中的 HEARTBEAT.md - isolatedSession: false, // 默认：false；true 时每次心跳都在全新会话中运行（无对话历史） - target: "last", // 默认：none | 可选值：last | none | （核心或插件，例如 "bluebubbles"） - to: "+15551234567", // 可选的特定渠道覆盖 - accountId: "ops-bot", // 可选的多账号渠道 id + isolatedSession: false, // 默认：false；true 时每次心跳都在新会话中运行（无会话历史） + target: "last", // 默认：none | 可选：last | none | （核心或插件，例如 "bluebubbles"） + to: "+15551234567", // 可选：按渠道覆盖目标收件人 + accountId: "ops-bot", // 可选：多账号渠道 id prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.", - ackMaxChars: 300, // HEARTBEAT_OK 之后允许的最大字符数 + ackMaxChars: 300, // HEARTBEAT_OK 后允许的最大字符数 }, }, }, } ``` -### 作用范围和优先级 +### 范围与优先级 - `agents.defaults.heartbeat` 设置全局心跳行为。 -- `agents.list[].heartbeat` 会在其之上合并；如果任何智能体有 `heartbeat` 块，则**只有这些智能体**会运行心跳。 +- `agents.list[].heartbeat` 会在其基础上合并；如果任何智能体具有 `heartbeat` 块，则**只有这些智能体**会运行心跳。 - `channels.defaults.heartbeat` 设置所有渠道的可见性默认值。 -- `channels..heartbeat` 覆盖渠道默认值。 -- `channels..accounts..heartbeat`（多账号渠道）按渠道内账号进行覆盖。 +- `channels..heartbeat` 会覆盖渠道默认值。 +- `channels..accounts..heartbeat`（多账号渠道）会按渠道内账号进一步覆盖设置。 -### 每个智能体的心跳 +### 按智能体设置心跳 -如果任意 `agents.list[]` 条目包含 `heartbeat` 块，则**只有这些智能体** -会运行心跳。每个智能体的块会在 `agents.defaults.heartbeat` -之上合并（因此你可以先设置共享默认值，再按智能体覆盖）。 +如果任何 `agents.list[]` 条目包含 `heartbeat` 块，则**只有这些智能体**会运行心跳。 +按智能体的块会在 `agents.defaults.heartbeat` 之上合并（因此你可以先设置共享默认值，再按智能体覆盖）。 示例：两个智能体，只有第二个智能体运行心跳。 @@ -129,7 +128,7 @@ x-i18n: defaults: { heartbeat: { every: "30m", - target: "last", // 显式发送到最近联系对象（默认是 "none"） + target: "last", // 显式投递到最近一次联系对象（默认是 "none"） }, }, list: [ @@ -140,6 +139,7 @@ x-i18n: every: "1h", target: "whatsapp", to: "+15551234567", + timeoutSeconds: 45, prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.", }, }, @@ -150,7 +150,7 @@ x-i18n: ### 活跃时段示例 -将心跳限制在某个特定时区的工作时段内： +将心跳限制在特定时区的工作时间内： ```json5 { @@ -158,11 +158,11 @@ x-i18n: defaults: { heartbeat: { every: "30m", - target: "last", // 显式发送到最近联系对象（默认是 "none"） + target: "last", // 显式投递到最近一次联系对象（默认是 "none"） activeHours: { start: "09:00", end: "22:00", - timezone: "America/New_York", // 可选；如果已设置则使用你的 userTimezone，否则使用主机时区 + timezone: "America/New_York", // 可选；如果设置了 userTimezone 则使用它，否则使用主机时区 }, }, }, @@ -170,21 +170,21 @@ x-i18n: } ``` -在这个时间窗口之外（美东时间上午 9 点前或晚上 10 点后），心跳会被跳过。窗口内的下一次计划 tick 会正常运行。 +在这个时间窗口之外（美国东部时间上午 9 点前或晚上 10 点后），心跳会被跳过。下一个位于窗口内的计划周期将正常运行。 ### 24/7 配置 -如果你希望心跳全天运行，可以使用以下模式之一： +如果你希望心跳全天运行，可使用以下任一模式： -- 完全省略 `activeHours`（无时间窗口限制；这是默认行为）。 +- 完全省略 `activeHours`（不限制时间窗口；这是默认行为）。 - 设置全天窗口：`activeHours: { start: "00:00", end: "24:00" }`。 不要将 `start` 和 `end` 设置为相同时间（例如 `08:00` 到 `08:00`）。 -这会被视为零宽度窗口，因此心跳会始终被跳过。 +这会被视为零宽度窗口，因此心跳将始终被跳过。 ### 多账号示例 -使用 `accountId` 将消息发送到 Telegram 等多账号渠道中的特定账号： +使用 `accountId` 将消息定向到 Telegram 等多账号渠道上的特定账号： ```json5 { @@ -195,7 +195,7 @@ x-i18n: heartbeat: { every: "1h", target: "telegram", - to: "12345678:topic:42", // 可选：路由到特定 topic/thread + to: "12345678:topic:42", // 可选：路由到特定话题/线程 accountId: "ops-bot", }, }, @@ -213,56 +213,50 @@ x-i18n: ### 字段说明 -- `every`：心跳间隔（时长字符串；默认单位 = 分钟）。 +- `every`：心跳间隔（时长字符串；默认单位为分钟）。 - `model`：心跳运行时可选的模型覆盖（`provider/model`）。 -- `includeReasoning`：启用后，在可用时也会发送单独的 `Reasoning:` 消息（形式与 `/reasoning on` 相同）。 +- `includeReasoning`：启用后，在可用时也会投递单独的 `Reasoning:` 消息（形式与 `/reasoning on` 相同）。 - `lightContext`：为 true 时，心跳运行会使用轻量级引导上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次心跳都会在无先前对话历史的全新会话中运行。使用与 cron `sessionTarget: "isolated"` 相同的隔离模式。可显著降低每次心跳的 token 成本。与 `lightContext: true` 结合使用可获得最大节省。消息传递路由仍使用主会话上下文。 +- `isolatedSession`：为 true 时，每次心跳都在没有先前会话历史的新会话中运行。使用与 cron `sessionTarget: "isolated"` 相同的隔离模式。可显著降低每次心跳的 token 成本。与 `lightContext: true` 组合可获得最大节省。投递路由仍使用主会话上下文。 - `session`：心跳运行的可选会话键。 - `main`（默认）：智能体主会话。 - - 显式会话键（从 `openclaw sessions --json` 或 [sessions CLI](/cli/sessions) 复制）。 - - 会话键格式：参见 [Sessions](/zh-CN/concepts/session) 和 [Groups](/zh-CN/channels/groups)。 + - 显式会话键（可从 `openclaw sessions --json` 或 [sessions CLI](/cli/sessions) 复制）。 + - 会话键格式：见 [会话](/zh-CN/concepts/session) 和 [群组](/zh-CN/channels/groups)。 - `target`： - - `last`：发送到最近使用的外部渠道。 - - 显式渠道：任意已配置的渠道或插件 id，例如 `discord`、`matrix`、`telegram` 或 `whatsapp`。 - - `none`（默认）：运行心跳，但**不向外部发送**。 -- `directPolicy`：控制直接/私信传递行为： - - `allow`（默认）：允许直接/私信心跳传递。 - - `block`：抑制直接/私信传递（`reason=dm-blocked`）。 -- `to`：可选的接收者覆盖（渠道特定 id，例如 WhatsApp 的 E.164 或 Telegram chat id）。对于 Telegram topic/thread，使用 `:topic:`。 -- `accountId`：多账号渠道的可选账号 id。当 `target: "last"` 时，如果解析出的最近渠道支持账号，则该账号 id 会应用于该渠道；否则会被忽略。如果该账号 id 与解析出的渠道中已配置账号不匹配，则会跳过传递。 -- `prompt`：覆盖默认提示词正文（不做合并）。 -- `ackMaxChars`：`HEARTBEAT_OK` 之后允许的最大字符数，超过则会发送。 -- `suppressToolErrorWarnings`：为 true 时，在心跳运行期间抑制工具错误警告载荷。 -- `activeHours`：将心跳运行限制在某个时间窗口内。对象包含 `start`（HH:MM，含边界；一天开始请使用 `00:00`）、`end`（HH:MM，不含边界；一天结束可使用 `24:00`）以及可选的 `timezone`。 - - 省略或设为 `"user"`：如果已设置，则使用你的 `agents.defaults.userTimezone`，否则回退到主机系统时区。 + - `last`：投递到最近一次使用的外部渠道。 + - 显式渠道：任何已配置的渠道或插件 id，例如 `discord`、`matrix`、`telegram` 或 `whatsapp`。 + - `none`（默认）：运行心跳，但**不进行**外部投递。 +- `directPolicy`：控制直接/私信投递行为： + - `allow`（默认）：允许直接/私信心跳投递。 + - `block`：抑制直接/私信投递（`reason=dm-blocked`）。 +- `to`：可选的收件人覆盖（按渠道定义的 id，例如 WhatsApp 的 E.164 或 Telegram chat id）。对于 Telegram 话题/线程，使用 `:topic:`。 +- `accountId`：多账号渠道的可选账号 id。当 `target: "last"` 时，如果解析出的最近渠道支持账号，则会应用该账号 id；否则会被忽略。如果该账号 id 与解析出的渠道中已配置的账号不匹配，则会跳过投递。 +- `prompt`：覆盖默认提示词正文（不会合并）。 +- `ackMaxChars`：`HEARTBEAT_OK` 后允许的最大字符数，超出则继续投递。 +- `suppressToolErrorWarnings`：为 true 时，会在心跳运行期间抑制工具错误警告负载。 +- `activeHours`：将心跳运行限制在一个时间窗口内。该对象包含 `start`（HH:MM，含边界；当天开始请使用 `00:00`）、`end`（HH:MM，不含边界；一天结束可用 `24:00`）以及可选的 `timezone`。 + - 省略或设为 `"user"`：如果设置了你的 `agents.defaults.userTimezone` 则使用它，否则回退到主机系统时区。 - `"local"`：始终使用主机系统时区。 - - 任意 IANA 标识符（例如 `America/New_York`）：直接使用；如果无效，则回退到上面的 `"user"` 行为。 - - 对于活跃窗口，`start` 和 `end` 不得相等；相等会被视为零宽度（始终在窗口外）。 - - 在活跃窗口之外，心跳会被跳过，直到窗口内的下一个 tick。 + - 任何 IANA 标识符（例如 `America/New_York`）：直接使用；如果无效，则回退到上面的 `"user"` 行为。 + - `start` 和 `end` 不能相等；相等会被视为零宽度窗口（始终处于窗口外）。 + - 在活跃窗口之外，心跳会被跳过，直到下一个位于窗口内的计划周期。 -## 传递行为 +## 投递行为 -- 默认情况下，心跳在智能体的主会话中运行（`agent::`）， - 或者当 `session.scope = "global"` 时使用 `global`。设置 `session` 可覆盖为某个 - 特定渠道会话（Discord/WhatsApp 等）。 -- `session` 只影响运行上下文；消息传递由 `target` 和 `to` 控制。 -- 若要发送到特定渠道/接收者，请设置 `target` + `to`。当 - `target: "last"` 时，传递会使用该会话最近的外部渠道。 -- 默认情况下，心跳传递允许直接/私信目标。设置 `directPolicy: "block"` 可在仍然运行心跳轮次的同时抑制向直接目标发送。 -- 如果主队列繁忙，心跳会被跳过，并在稍后重试。 -- 如果 `target` 解析后没有外部目的地，运行仍会发生，但不会 - 发送外发消息。 -- 如果 `showOk`、`showAlerts` 和 `useIndicator` 全部被禁用，则该运行会在前期被跳过，并标记为 `reason=alerts-disabled`。 -- 如果仅禁用了提醒传递，OpenClaw 仍可运行心跳、更新时间已到任务的时间戳、恢复会话空闲时间戳，并抑制向外发送的提醒载荷。 -- 仅心跳的回复**不会**保持会话活跃；最后的 `updatedAt` - 会被恢复，因此空闲过期行为保持正常。 -- 脱离式[后台任务](/zh-CN/automation/tasks)可以加入一个系统事件队列并唤醒心跳，以便主会话更快注意到某些事情。这种唤醒不会使心跳运行成为后台任务。 +- 心跳默认在智能体的主会话中运行（`agent::`），当 `session.scope = "global"` 时则运行在 `global` 中。设置 `session` 可将其覆盖为特定的渠道会话（Discord/WhatsApp 等）。 +- `session` 只影响运行上下文；投递由 `target` 和 `to` 控制。 +- 要投递到特定渠道/收件人，请设置 `target` + `to`。当使用 `target: "last"` 时，投递会使用该会话最近一次使用的外部渠道。 +- 默认情况下，心跳投递允许直接/私信目标。设置 `directPolicy: "block"` 可在仍运行心跳轮次的同时抑制直接目标发送。 +- 如果主队列繁忙，心跳会被跳过，并在之后重试。 +- 如果 `target` 未解析到任何外部目标，运行仍会发生，但不会发送出站消息。 +- 如果 `showOk`、`showAlerts` 和 `useIndicator` 全部被禁用，则该次运行会在开始前被跳过，并记为 `reason=alerts-disabled`。 +- 如果仅禁用了提醒投递，OpenClaw 仍可以运行心跳、更新时间已到任务的时间戳、恢复会话空闲时间戳，并抑制对外提醒负载。 +- 仅包含心跳内容的回复**不会**保持会话活跃；最后的 `updatedAt` 会被恢复，因此空闲过期仍按正常方式生效。 +- 脱离主会话的[后台任务](/zh-CN/automation/tasks)可以将系统事件加入队列，并唤醒心跳，以便主会话尽快注意到某些事情。这种唤醒不会让心跳运行变成后台任务。 ## 可见性控制 -默认情况下，`HEARTBEAT_OK` 确认会被抑制，而提醒内容会 -正常发送。你可以按渠道或按账号进行调整： +默认情况下，`HEARTBEAT_OK` 确认消息会被抑制，而提醒内容会正常投递。你可以按渠道或按账号进行调整： ```yaml channels: @@ -278,20 +272,20 @@ channels: accounts: work: heartbeat: - showAlerts: false # 为该账号抑制提醒发送 + showAlerts: false # 为此账号抑制提醒投递 ``` -优先级：每账号 → 每渠道 → 渠道默认值 → 内置默认值。 +优先级：按账号 → 按渠道 → 渠道默认值 → 内置默认值。 -### 每个标志的作用 +### 各标志的作用 -- `showOk`：当模型返回仅包含 OK 的回复时，发送 `HEARTBEAT_OK` 确认。 +- `showOk`：当模型返回仅含 OK 的回复时，发送 `HEARTBEAT_OK` 确认消息。 - `showAlerts`：当模型返回非 OK 回复时，发送提醒内容。 - `useIndicator`：为 UI 状态界面发出指示器事件。 -如果**三者都**为 false，OpenClaw 会完全跳过心跳运行（不调用模型）。 +如果**这三项全部**为 false，OpenClaw 会完全跳过心跳运行（不会调用模型）。 -### 每渠道与每账号示例 +### 按渠道与按账号示例 ```yaml channels: @@ -315,31 +309,26 @@ channels: ### 常见模式 | 目标 | 配置 | -| ---------------------------------------- | ---------------------------------------------------------------------------------------- | +| --- | --- | | 默认行为（静默 OK，提醒开启） | _(无需配置)_ | -| 完全静默（无消息，无指示器） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | -| 仅指示器（无消息） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` | -| 仅在一个渠道中显示 OK | `channels.telegram.heartbeat: { showOk: true }` | +| 完全静默（无消息、无指示器） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | +| 仅指示器（无消息） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` | +| 仅在一个渠道中显示 OK | `channels.telegram.heartbeat: { showOk: true }` | -## HEARTBEAT.md（可选） +## `HEARTBEAT.md`（可选） -如果工作区中存在 `HEARTBEAT.md` 文件，默认提示词会告诉 -智能体读取它。你可以将其视为你的“心跳检查清单”：内容要小而稳定， -并且适合每 30 分钟都包含一次。 +如果工作区中存在 `HEARTBEAT.md` 文件，默认提示词会告诉智能体去读取它。你可以把它看作你的“心跳检查清单”：小巧、稳定，并且适合每 30 分钟包含一次。 -在普通运行中，只有当默认智能体启用了心跳指引时， -`HEARTBEAT.md` 才会被注入。如果使用 `0m` 禁用心跳频率，或 -设置 `includeSystemPromptSection: false`，它就会从普通引导 -上下文中省略。 +在普通运行中，只有当默认智能体启用了心跳指引时，才会注入 `HEARTBEAT.md`。 +如果将心跳频率通过 `0m` 禁用，或设置 `includeSystemPromptSection: false`，则会在普通引导上下文中省略它。 -如果 `HEARTBEAT.md` 存在但实际上为空（只有空行和 markdown -标题，例如 `# Heading`），OpenClaw 会跳过心跳运行以节省 API 调用。 -这种跳过会报告为 `reason=empty-heartbeat-file`。 +如果 `HEARTBEAT.md` 存在但实际上为空（只有空行和 Markdown 标题，例如 `# Heading`），OpenClaw 会跳过该次心跳运行以节省 API 调用。 +该跳过会记为 `reason=empty-heartbeat-file`。 如果文件不存在，心跳仍会运行，并由模型决定该做什么。 -请保持它很小（简短清单或提醒），以避免提示词膨胀。 +请保持它足够小巧（简短的检查清单或提醒），以避免提示词膨胀。 -示例 `HEARTBEAT.md`： +`HEARTBEAT.md` 示例： ```md # Heartbeat checklist @@ -351,8 +340,7 @@ channels: ### `tasks:` 块 -`HEARTBEAT.md` 还支持一个小型结构化 `tasks:` 块， -用于在心跳内部执行基于间隔的检查。 +`HEARTBEAT.md` 还支持一个小型结构化 `tasks:` 块，用于在心跳内部执行基于间隔的检查。 示例： @@ -372,73 +360,66 @@ tasks: - If nothing needs attention after all due tasks, reply HEARTBEAT_OK. ``` -行为： +行为如下： -- OpenClaw 会解析 `tasks:` 块，并根据各任务自己的 `interval` 检查每个任务。 -- 只有**到期**任务会被包含在该次 tick 的心跳提示词中。 -- 如果没有任务到期，心跳会被完全跳过（`reason=no-tasks-due`），以避免浪费一次模型调用。 -- `HEARTBEAT.md` 中的非任务内容会被保留，并作为附加上下文追加在到期任务列表之后。 -- 任务上次运行时间戳存储在会话状态中（`heartbeatTaskState`），因此这些间隔在正常重启后仍会保留。 -- 只有在心跳运行完成其正常回复路径后，任务时间戳才会推进。被跳过的 `empty-heartbeat-file` / `no-tasks-due` 运行不会将任务标记为已完成。 +- OpenClaw 会解析 `tasks:` 块，并根据每个任务自己的 `interval` 进行检查。 +- 只有**到期**的任务才会被包含到该次时钟周期的心跳提示词中。 +- 如果没有任务到期，则会完全跳过该次心跳（`reason=no-tasks-due`），以避免浪费一次模型调用。 +- `HEARTBEAT.md` 中的非任务内容会被保留，并在到期任务列表之后作为附加上下文追加。 +- 任务的上次运行时间戳会存储在会话状态（`heartbeatTaskState`）中，因此这些间隔信息在正常重启后依然保留。 +- 只有在一次心跳运行完成其正常回复路径之后，任务时间戳才会前进。被跳过的 `empty-heartbeat-file` / `no-tasks-due` 运行不会将任务标记为已完成。 -当你希望一个心跳文件容纳多个周期性检查，同时又不想每次 tick 都为全部检查付费时，任务模式就很有用。 +当你希望一个心跳文件容纳多个周期性检查，但又不想在每次时钟周期中都为所有检查付费时，任务模式会很有用。 -### 智能体可以更新 HEARTBEAT.md 吗？ +### 智能体可以更新 `HEARTBEAT.md` 吗？ -可以——如果你要求它这么做。 +可以——如果你要求它这样做。 -`HEARTBEAT.md` 只是智能体工作区中的一个普通文件，因此你可以在 -普通聊天中对智能体说： +`HEARTBEAT.md` 只是智能体工作区中的一个普通文件，因此你可以在普通聊天中告诉智能体类似这样的话： -- “更新 `HEARTBEAT.md`，加入每日历检查。” -- “重写 `HEARTBEAT.md`，让它更短，并专注于收件箱跟进事项。” +- “更新 `HEARTBEAT.md`，加入每日检查日历的内容。” +- “重写 `HEARTBEAT.md`，让它更短，并聚焦于收件箱跟进事项。” -如果你希望它主动这样做，也可以在 -心跳提示词中加入一行明确说明，例如：“如果清单已经过时，请更新 HEARTBEAT.md -并替换为更好的版本。” +如果你希望这件事主动发生，也可以在心跳提示词中加入一行明确说明，比如：“如果检查清单变陈旧了，就用更好的版本更新 HEARTBEAT.md。” -安全说明：不要把密钥（API keys、电话号码、私有 token）放进 -`HEARTBEAT.md`——它会成为提示词上下文的一部分。 +安全提示：不要把秘密信息（API 密钥、电话号码、私有令牌）放进 `HEARTBEAT.md`——它会成为提示词上下文的一部分。 ## 手动唤醒（按需） -你可以通过以下命令将系统事件加入队列并立即触发心跳： +你可以通过以下命令将系统事件加入队列，并立即触发一次心跳： ```bash openclaw system event --text "Check for urgent follow-ups" --mode now ``` -如果多个智能体配置了 `heartbeat`，手动唤醒会立即运行其中每个 -智能体的心跳。 +如果多个智能体都配置了 `heartbeat`，手动唤醒会立即运行每一个此类智能体的心跳。 -使用 `--mode next-heartbeat` 可等待下一次计划 tick。 +使用 `--mode next-heartbeat` 可等待下一个计划时钟周期。 -## 推理传递（可选） +## 推理内容投递（可选） -默认情况下，心跳只传递最终的“answer”载荷。 +默认情况下，心跳只会投递最终的“answer”负载。 如果你希望提高透明度，请启用： - `agents.defaults.heartbeat.includeReasoning: true` -启用后，心跳还会传递一条单独的消息，前缀为 -`Reasoning:`（形式与 `/reasoning on` 相同）。当智能体 -正在管理多个会话/codexes，而你希望看到它为何决定提醒 -你时，这会很有帮助——但它也可能泄露比你想要的更多内部细节。建议在群聊中保持关闭。 +启用后，心跳还会投递一条单独的消息，前缀为 +`Reasoning:`（形式与 `/reasoning on` 相同）。当智能体正在管理多个会话 / codexes，而你希望看到它为什么决定提醒你时，这会很有帮助——但它也可能泄露比你想要更多的内部细节。建议在群聊中保持关闭。 ## 成本意识 -心跳会运行完整的智能体轮次。更短的间隔会消耗更多 token。要降低成本： +心跳会运行完整的智能体轮次。更短的间隔会消耗更多 token。为了降低成本： -- 使用 `isolatedSession: true` 以避免发送完整对话历史（每次运行约从 ~100K tokens 降至 ~2-5K）。 -- 使用 `lightContext: true` 将引导文件限制为只有 `HEARTBEAT.md`。 +- 使用 `isolatedSession: true` 来避免发送完整会话历史（每次运行大约可从 ~100K token 降到 ~2-5K）。 +- 使用 `lightContext: true` 将引导文件限制为仅 `HEARTBEAT.md`。 - 设置更便宜的 `model`（例如 `ollama/llama3.2:1b`）。 -- 保持 `HEARTBEAT.md` 小巧。 -- 如果你只想要内部状态更新，请使用 `target: "none"`。 +- 保持 `HEARTBEAT.md` 足够小。 +- 如果你只想更新内部状态，请使用 `target: "none"`。 ## 相关内容 -- [Automation & Tasks](/zh-CN/automation) — 所有自动化机制概览 -- [Background Tasks](/zh-CN/automation/tasks) — 脱离式工作如何被跟踪 -- [Timezone](/zh-CN/concepts/timezone) — 时区如何影响心跳调度 -- [Troubleshooting](/zh-CN/automation/cron-jobs#troubleshooting) — 自动化问题调试 +- [自动化与任务](/zh-CN/automation) —— 所有自动化机制一览 +- [后台任务](/zh-CN/automation/tasks) —— 脱离主会话的工作如何被跟踪 +- [时区](/zh-CN/concepts/timezone) —— 时区如何影响心跳调度 +- [故障排除](/zh-CN/automation/cron-jobs#troubleshooting) —— 调试自动化问题 diff --git a/docs/zh-CN/reference/RELEASING.md b/docs/zh-CN/reference/RELEASING.md index fa47cde4d..c31f12b94 100644 --- a/docs/zh-CN/reference/RELEASING.md +++ b/docs/zh-CN/reference/RELEASING.md @@ -1,128 +1,107 @@ --- read_when: - - 查找公开发布通道定义 - - 查找版本命名和发布节奏 -summary: 公开发布通道、版本命名和发布节奏 + - 正在查找公开发布渠道的定义 + - 正在查找版本命名和发布节奏 +summary: 公开发布渠道、版本命名和发布节奏 title: 发布策略 x-i18n: - generated_at: "2026-04-05T10:07:37Z" + generated_at: "2026-04-10T23:44:34Z" model: gpt-5.4 provider: openai - source_hash: bb52a13264c802395aa55404c6baeec5c7b2a6820562e7a684057e70cc85668f + source_hash: ca613d094c93670c012f0b79720fad0d5d85be802f54b0acb7a8f22aca5bde12 source_path: reference/RELEASING.md workflow: 15 --- # 发布策略 -OpenClaw 有三条公开发布通道： +OpenClaw 有三条公开发布渠道： -- stable：带标签的发布版本，默认发布到 npm `beta`，或在显式指定时发布到 npm `latest` +- stable：带标签的发布版本，默认发布到 npm `beta`，或在明确要求时发布到 npm `latest` - beta：预发布标签，发布到 npm `beta` -- dev：`main` 的滚动最新头部版本 +- dev：`main` 的持续更新头部版本 ## 版本命名 -- 稳定版发布版本：`YYYY.M.D` +- Stable 发布版本：`YYYY.M.D` - Git 标签：`vYYYY.M.D` -- 稳定版修正版发布版本：`YYYY.M.D-N` +- Stable 修正版发布版本：`YYYY.M.D-N` - Git 标签：`vYYYY.M.D-N` - Beta 预发布版本：`YYYY.M.D-beta.N` - Git 标签：`vYYYY.M.D-beta.N` -- 月和日不要补零 -- `latest` 表示当前已晋升的稳定 npm 发布版本 +- 月份和日期不要补零 +- `latest` 表示当前已提升为正式版的 stable npm 发布版本 - `beta` 表示当前 beta 安装目标 -- 稳定版和稳定版修正版默认发布到 npm `beta`；发布操作员可以显式指定发布到 `latest`，或在之后将已验证的 beta 构建晋升 -- 每个 OpenClaw 发布都会同时发布 npm 包和 macOS 应用 +- Stable 和 stable 修正版发布默认发布到 npm `beta`；发布操作人员也可以显式指定发布到 `latest`，或者稍后再将已验证的 beta 构建提升过去 +- 每个 OpenClaw 发布都会同时交付 npm 包和 macOS 应用 ## 发布节奏 - 发布先走 beta -- 只有在最新 beta 验证通过后，才会跟进 stable -- 详细的发布流程、审批、凭证和恢复说明仅供维护者使用 +- 只有在最新 beta 完成验证后，才会进入 stable +- 详细的发布流程、审批、凭证和恢复说明仅限维护者查看 ## 发布前检查 -- 在运行 `pnpm release:check` 之前先运行 `pnpm build && pnpm ui:build`，以便打包验证步骤所需的 `dist/*` 发布产物和 Control UI bundle 已存在 -- 在每次带标签发布前运行 `pnpm release:check` -- `main` 分支的 npm 发布前检查还会在打包 tarball 之前运行 - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`， - 并使用工作流密钥 `OPENAI_API_KEY` 和 - `ANTHROPIC_API_KEY` -- 在审批前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` - （或对应的 beta/修正版标签） -- npm 发布后，运行 - `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` - （或对应的 beta/修正版版本），在一个全新的临时前缀中验证已发布注册表的安装路径 -- 维护者发布自动化现在使用“先预检再晋升”流程： - - 实际 npm 发布必须通过成功的 npm `preflight_run_id` - - 稳定 npm 发布默认使用 `beta` - - 稳定 npm 发布可通过工作流输入显式指定目标为 `latest` - - 稳定 npm 从 `beta` 晋升到 `latest` 仍然作为可信 `OpenClaw NPM Release` 工作流中的显式手动模式提供 - - 该晋升模式仍需要 `npm-release` 环境中有效的 `NPM_TOKEN`，因为 npm `dist-tag` 管理独立于可信发布 +- 在运行 `pnpm release:check` 之前，先运行 `pnpm build && pnpm ui:build`，这样 pack 校验步骤所需的 `dist/*` 发布产物和 Control UI bundle 才会存在 +- 每次带标签发布前都要运行 `pnpm release:check` +- `main` 分支上的 npm 发布前检查还会在打包 tarball 之前运行 `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`，并使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 这两个工作流密钥 +- 在批准前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`（或对应的 beta / 修正版标签） +- npm 发布后，运行 `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（或对应的 beta / 修正版版本），以在一个全新的临时前缀中验证已发布注册表安装路径 +- 维护者发布自动化现在使用“先预检，再提升”的流程： + - 真正的 npm 发布必须依赖一次成功的 npm `preflight_run_id` + - stable npm 发布默认目标为 `beta` + - stable npm 发布可以通过工作流输入显式指定目标为 `latest` + - 也仍然支持在受信任的 `OpenClaw NPM Release` 工作流中，以显式手动模式将 stable 从 `beta` 提升到 `latest` + - 该提升模式仍然需要 `npm-release` 环境中存在有效的 `NPM_TOKEN`，因为 npm `dist-tag` 管理与受信任发布是分开的 - 公开的 `macOS Release` 仅用于验证 - - 实际的私有 mac 发布必须通过成功的私有 mac - `preflight_run_id` 和 `validate_run_id` - - 实际发布路径会晋升已准备好的产物，而不是再次重新构建 -- 对于像 `YYYY.M.D-N` 这样的稳定版修正版发布，发布后验证器还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的同一临时前缀升级路径，因此发布修正不能悄悄让旧的全局安装仍停留在基础稳定版负载上 -- npm 发布前检查会以失败关闭，除非 tarball 同时包含 - `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` 负载， - 以避免再次发布一个空的浏览器仪表板 -- 如果发布工作涉及 CI 规划、扩展时序清单或快速测试矩阵，请在审批前从 `.github/workflows/ci.yml` - 重新生成并审查由规划器负责的 `checks-fast-extensions` - 工作流矩阵输出，以免发布说明描述过时的 CI 布局 -- 稳定版 macOS 发布就绪还包括更新器相关接口： - - GitHub 发布最终必须包含打包后的 `.zip`、`.dmg` 和 `.dSYM.zip` - - 发布后，`main` 上的 `appcast.xml` 必须指向新的稳定版 zip - - 打包后的应用必须保持非调试 bundle id、非空的 Sparkle feed - URL，以及不低于该发布版本规范 Sparkle 构建下限的 `CFBundleVersion` + - 真正的私有 mac 发布必须依赖成功的私有 mac `preflight_run_id` 和 `validate_run_id` + - 真正的发布路径会提升已准备好的产物，而不是再次重新构建它们 +- 对于像 `YYYY.M.D-N` 这样的 stable 修正版发布，发布后验证器还会检查从 `YYYY.M.D` 升级到 `YYYY.M.D-N` 的同一临时前缀升级路径，这样修正版发布就不能在无声无息中让旧的全局安装仍停留在基础 stable 负载上 +- npm 发布前检查默认采用失败即关闭的策略，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` 内容，否则检查不会通过，以避免再次发布一个空的浏览器仪表盘 +- 如果发布工作涉及 CI 规划、扩展时序清单或扩展测试矩阵，请在批准前重新生成并审查来自 `.github/workflows/ci.yml` 的规划器维护的 `checks-node-extensions` 工作流矩阵输出，以免发布说明描述过时的 CI 布局 +- Stable macOS 发布就绪检查还包括更新器相关表面： + - GitHub release 最终必须包含打包后的 `.zip`、`.dmg` 和 `.dSYM.zip` + - 发布后，`main` 上的 `appcast.xml` 必须指向新的 stable zip + - 打包后的应用必须保持非调试 bundle id、非空的 Sparkle feed URL，以及不低于该发布版本规范 Sparkle 构建底线的 `CFBundleVersion` ## NPM 工作流输入 -`OpenClaw NPM Release` 接受以下由操作员控制的输入： +`OpenClaw NPM Release` 接受以下由操作人员控制的输入： -- `tag`：必填发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或 - `v2026.4.2-beta.1` -- `preflight_only`：若仅执行验证/构建/打包则为 `true`，若执行实际发布路径则为 `false` -- `preflight_run_id`：在实际发布路径中为必填，这样工作流会复用成功预检运行中准备好的 tarball -- `npm_dist_tag`：发布路径的 npm 目标标签；默认值为 `beta` -- `promote_beta_to_latest`：若为 `true`，则跳过发布，并将已发布的稳定版 `beta` 构建移动到 `latest` +- `tag`：必填发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或 `v2026.4.2-beta.1` +- `preflight_only`：`true` 表示仅执行验证 / 构建 / 打包，`false` 表示执行真实发布路径 +- `preflight_run_id`：真实发布路径中必填，这样工作流可以复用成功预检运行中准备好的 tarball +- `npm_dist_tag`：发布路径的 npm 目标标签；默认是 `beta` +- `promote_beta_to_latest`：`true` 表示跳过发布，并将一个已经发布的 stable `beta` 构建移动到 `latest` 规则： -- 稳定版和修正版标签可以发布到 `beta` 或 `latest` -- beta 预发布标签只能发布到 `beta` -- 实际发布路径必须使用与预检时相同的 `npm_dist_tag`；工作流会在继续发布前验证该元数据 -- 晋升模式必须使用稳定版或修正版标签、`preflight_only=false`、 - 空的 `preflight_run_id`，以及 `npm_dist_tag=beta` -- 晋升模式还要求 `npm-release` - 环境中存在有效的 `NPM_TOKEN`，因为 `npm dist-tag add` 仍然需要常规 npm 认证 +- Stable 和修正版标签可以发布到 `beta` 或 `latest` +- Beta 预发布标签只能发布到 `beta` +- 真实发布路径必须使用与预检时相同的 `npm_dist_tag`；工作流会在继续发布前校验该元数据 +- 提升模式必须使用 stable 或修正版标签、`preflight_only=false`、空的 `preflight_run_id`，以及 `npm_dist_tag=beta` +- 提升模式还要求 `npm-release` 环境中存在有效的 `NPM_TOKEN`，因为 `npm dist-tag add` 仍然需要常规 npm 认证 -## 稳定版 npm 发布顺序 +## Stable npm 发布顺序 -在发布稳定版 npm 时： +在发布 stable npm 版本时： -1. 使用 `preflight_only=true` 运行 `OpenClaw NPM Release` -2. 在常规的先 beta 流程中选择 `npm_dist_tag=beta`，或者仅当你有意直接发布稳定版时才选择 `latest` +1. 以 `preflight_only=true` 运行 `OpenClaw NPM Release` +2. 正常的先 beta 后 stable 流程请选择 `npm_dist_tag=beta`；只有在你明确想直接发布 stable 时才选择 `latest` 3. 保存成功的 `preflight_run_id` -4. 再次运行 `OpenClaw NPM Release`，设置 `preflight_only=false`，并使用相同的 - `tag`、相同的 `npm_dist_tag` 和保存的 `preflight_run_id` -5. 如果该发布已落到 `beta`，则在之后运行 `OpenClaw NPM Release`， - 使用相同的稳定版 `tag`、`promote_beta_to_latest=true`、`preflight_only=false`、 - 空的 `preflight_run_id` 和 `npm_dist_tag=beta`，以便在你想把该已发布构建移动到 `latest` 时执行晋升 +4. 再次运行 `OpenClaw NPM Release`，这次使用 `preflight_only=false`，并传入相同的 `tag`、相同的 `npm_dist_tag`，以及上一步保存的 `preflight_run_id` +5. 如果该发布先落在 `beta`，之后当你想把该已发布构建移动到 `latest` 时，再用相同的 stable `tag`、`promote_beta_to_latest=true`、`preflight_only=false`、空的 `preflight_run_id` 和 `npm_dist_tag=beta` 运行 `OpenClaw NPM Release` -晋升模式仍然需要 `npm-release` 环境审批，以及该环境中有效的 -`NPM_TOKEN`。 +提升模式仍然需要 `npm-release` 环境审批以及该环境中的有效 `NPM_TOKEN`。 -这样既保留了直接发布路径，也保留了先 beta 再晋升路径，并且二者都清晰记录、对操作员可见。 +这样一来，直接发布路径和先 beta 后提升路径都会被记录下来，并且对操作人员清晰可见。 -## 公开参考资料 +## 公开参考 - [`.github/workflows/openclaw-npm-release.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-npm-release.yml) - [`scripts/openclaw-npm-release-check.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/openclaw-npm-release-check.ts) - [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh) - [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh) -维护者在 -[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) -中使用私有发布文档作为实际操作手册。 +维护者会使用私有发布文档 [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) 作为实际操作手册。