From 8b0f41c6137d6d67da81d8bd537301a22a669ca2 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 22 Apr 2026 22:34:24 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/concepts/models.md | 143 +- docs/zh-CN/gateway/configuration-reference.md | 1449 ++++++++--------- docs/zh-CN/gateway/configuration.md | 308 ++-- 3 files changed, 955 insertions(+), 945 deletions(-) diff --git a/docs/zh-CN/concepts/models.md b/docs/zh-CN/concepts/models.md index d951a56d1..2db12bc6a 100644 --- a/docs/zh-CN/concepts/models.md +++ b/docs/zh-CN/concepts/models.md @@ -1,47 +1,47 @@ --- read_when: - 添加或修改模型 CLI（`models list/set/scan/aliases/fallbacks`） - - 更改模型回退行为或选择 UX + - 更改模型回退行为或选择体验 - 更新模型扫描探测项（工具/图像） summary: 模型 CLI：列出、设置、别名、回退、扫描、状态 title: 模型 CLI x-i18n: - generated_at: "2026-04-22T19:54:32Z" + generated_at: "2026-04-22T22:26:04Z" model: gpt-5.4 provider: openai - source_hash: 99174b625d265fe4743f4e0ca7ea3897bb446a485dde0841e101fe136a08558a + source_hash: 18d915f3f761aaff5efc3bf752f5abddeb625e1a386ab3d701f46fd92244f20e source_path: concepts/models.md workflow: 15 --- # 模型 CLI -关于凭证配置文件轮换、冷却时间及其与回退机制的交互方式，请参阅 [/concepts/model-failover](/zh-CN/concepts/model-failover)。 -提供商快速概览与示例：[/concepts/model-providers](/zh-CN/concepts/model-providers)。 +有关凭证配置文件轮换、冷却时间及其与回退如何交互的信息，请参阅 [/concepts/model-failover](/zh-CN/concepts/model-failover)。 +快速提供商概览 + 示例：[/concepts/model-providers](/zh-CN/concepts/model-providers)。 ## 模型选择的工作方式 OpenClaw 按以下顺序选择模型： 1. **主** 模型（`agents.defaults.model.primary` 或 `agents.defaults.model`）。 -2. `agents.defaults.model.fallbacks` 中的 **回退模型**（按顺序）。 -3. **提供商凭证回退** 会在切换到下一个模型之前，于提供商内部发生。 +2. `agents.defaults.model.fallbacks` 中的**回退**模型（按顺序）。 +3. **提供商凭证故障切换**会先在提供商内部发生，然后才会切换到下一个模型。 相关项： -- `agents.defaults.models` 是 OpenClaw 可使用模型的允许列表/目录（也包含别名）。 -- `agents.defaults.imageModel` **仅在** 主模型无法接受图像时使用。 +- `agents.defaults.models` 是 OpenClaw 可使用模型的允许列表/目录（以及别名）。 +- `agents.defaults.imageModel` **仅在**主模型无法接受图像时使用。 - `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会依次回退到 `agents.defaults.imageModel`，然后是已解析的会话/默认模型。 -- `agents.defaults.imageGenerationModel` 用于共享的图像生成功能。如果省略，`image_generate` 仍可推断出一个带凭证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。如果你设置了特定的提供商/模型，也要同时配置该提供商的凭证/API 密钥。 -- `agents.defaults.musicGenerationModel` 用于共享的音乐生成功能。如果省略，`music_generate` 仍可推断出一个带凭证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定的提供商/模型，也要同时配置该提供商的凭证/API 密钥。 -- `agents.defaults.videoGenerationModel` 用于共享的视频生成功能。如果省略，`video_generate` 仍可推断出一个带凭证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。如果你设置了特定的提供商/模型，也要同时配置该提供商的凭证/API 密钥。 -- 每个智能体的默认值可通过 `agents.list[].model` 及其绑定覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/zh-CN/concepts/multi-agent)）。 +- `agents.defaults.imageGenerationModel` 用于共享的图像生成功能。如果省略，`image_generate` 仍可推断出一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。 +- `agents.defaults.musicGenerationModel` 用于共享的音乐生成功能。如果省略，`music_generate` 仍可推断出一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。 +- `agents.defaults.videoGenerationModel` 用于共享的视频生成功能。如果省略，`video_generate` 仍可推断出一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。 +- 每个智能体的默认值可以通过 `agents.list[].model` 加上绑定覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/zh-CN/concepts/multi-agent)）。 ## 快速模型策略 -- 将你的主模型设为你可用的、最新一代中能力最强的模型。 +- 将你的主模型设为你可用的最新一代中能力最强的模型。 - 对成本/延迟敏感的任务和风险较低的聊天，使用回退模型。 -- 对启用了工具的智能体或不可信输入，避免使用较旧/较弱的模型层级。 +- 对启用了工具的智能体或不受信任的输入，避免使用较旧/较弱档位的模型。 ## 新手引导（推荐） @@ -51,7 +51,8 @@ OpenClaw 按以下顺序选择模型： openclaw onboard ``` -它可以为常见提供商设置模型 + 凭证，包括 **OpenAI Code（Codex）订阅**（OAuth）和 **Anthropic**（API 密钥或 Claude CLI）。 +它可以为常见提供商设置模型 + 凭证，包括 **OpenAI Code (Codex) +subscription**（OAuth）和 **Anthropic**（API 密钥或 Claude CLI）。 ## 配置键名（概览） @@ -63,23 +64,36 @@ openclaw onboard - `agents.defaults.models`（允许列表 + 别名 + 提供商参数） - `models.providers`（写入 `models.json` 的自定义提供商） -模型引用会被规范化为小写。像 `z.ai/*` 这样的提供商别名会规范化为 `zai/*`。 +模型引用会被标准化为小写。像 `z.ai/*` 这样的提供商别名会标准化为 +`zai/*`。 提供商配置示例（包括 OpenCode）位于 [/providers/opencode](/zh-CN/providers/opencode)。 +### 安全地编辑允许列表 + +手动更新 `agents.defaults.models` 时，请使用追加式写入： + +```bash +openclaw config set agents.defaults.models '{"openai-codex/gpt-5.4":{}}' --strict-json --merge +``` + +`openclaw config set` 会保护模型/提供商映射，避免被意外覆盖。当对 `agents.defaults.models`、`models.providers` 或 `models.providers..models` 进行普通对象赋值且会移除现有条目时，该操作会被拒绝。对追加式更改使用 `--merge`；仅当提供的值应成为完整目标值时才使用 `--replace`。 + +交互式提供商设置和 `openclaw configure --section model` 也会将按提供商范围选择的内容合并到现有允许列表中，因此添加 Codex、Ollama 或其他提供商时，不会丢失无关的模型条目。 + ## “Model is not allowed”（以及为什么回复会停止） -如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的**允许列表**。当用户选择的模型不在该允许列表中时，OpenClaw 会返回： +如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的**允许列表**。当用户选择了不在该允许列表中的模型时，OpenClaw 会返回： ``` Model "provider/model" is not allowed. Use /model to list available models. ``` -这会发生在生成正常回复**之前**，因此消息看起来会像是“没有响应”。修复方法是以下之一： +这会在正常回复生成**之前**发生，因此消息会让人感觉它“没有响应”。修复方法是以下之一： -- 将该模型添加到 `agents.defaults.models`，或者 -- 清除允许列表（移除 `agents.defaults.models`），或者 +- 将该模型添加到 `agents.defaults.models`，或 +- 清除允许列表（移除 `agents.defaults.models`），或 - 从 `/model list` 中选择一个模型。 允许列表示例配置： @@ -98,9 +112,9 @@ Model "provider/model" is not allowed. Use /model to list available models. ## 在聊天中切换模型（`/model`） -你可以为当前会话切换模型，而无需重启： +你可以在不重启的情况下为当前会话切换模型： -```text +``` /model /model list /model 3 @@ -110,26 +124,26 @@ Model "provider/model" is not allowed. Use /model to list available models. 说明： -- `/model`（以及 `/model list`）是紧凑的编号选择器（模型家族 + 可用提供商）。 -- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，带有提供商和模型下拉菜单，以及一个提交步骤。 +- `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型家族 + 可用提供商）。 +- 在 Discord 中，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个“提交”步骤。 - `/models add` 默认可用，可通过 `commands.modelsWrite=false` 禁用。 -- 启用后，`/models add ` 是最快路径；仅输入 `/models add` 时，会在支持的情况下启动一个从提供商开始的引导式流程。 -- 执行 `/models add` 后，无需重启 Gateway 网关，新模型就会在 `/models` 和 `/model` 中可用。 -- `/model <#>` 会从该选择器中选择。 +- 启用后，`/models add ` 是最快路径；仅输入 `/models add` 会在支持的情况下启动一个“先选提供商”的引导流程。 +- 在执行 `/models add` 后，新模型会立即在 `/models` 和 `/model` 中可用，无需重启 Gateway 网关。 +- `/model <#>` 会从该选择器中进行选择。 - `/model` 会立即持久化新的会话选择。 -- 如果智能体处于空闲状态，下一次运行会立即使用新模型。 -- 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只会在一个干净的重试点重启到新模型。 -- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到后续某个重试机会或下一次用户轮次。 -- `/model status` 是详细视图（凭证候选项，以及在已配置时提供商端点 `baseUrl` + `api` 模式）。 -- 模型引用通过按**第一个** `/` 分割来解析。输入 `/model ` 时请使用 `provider/model`。 +- 如果智能体处于空闲状态，下次运行会立即使用新模型。 +- 如果某次运行已在进行中，OpenClaw 会将实时切换标记为待处理，并只会在一个干净的重试点重启到新模型。 +- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到稍后的重试机会或下一个用户轮次。 +- `/model status` 是详细视图（凭证候选项，以及在已配置时显示的提供商端点 `baseUrl` + `api` 模式）。 +- 模型引用通过按**第一个** `/` 进行拆分来解析。输入 `/model ` 时请使用 `provider/model`。 - 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（示例：`/model openrouter/moonshotai/kimi-k2`）。 -- 如果你省略了提供商，OpenClaw 会按以下顺序解析输入： +- 如果你省略提供商，OpenClaw 会按以下顺序解析输入： 1. 别名匹配 2. 对该精确无前缀模型 ID 的唯一已配置提供商匹配 - 3. 已弃用的回退：使用已配置的默认提供商 - 如果该提供商不再暴露已配置的默认模型，OpenClaw 会改为回退到第一个已配置的提供商/模型，以避免暴露一个陈旧的、已移除提供商默认值。 + 3. 已弃用的回退：使用已配置的默认提供商 + 如果该提供商已不再公开配置中的默认模型，OpenClaw 会改为回退到第一个已配置的提供商/模型，以避免暴露陈旧且已移除提供商的默认值。 -完整命令行为/配置：[/tools/slash-commands](/zh-CN/tools/slash-commands)。 +完整命令行为/配置： [斜杠命令](/zh-CN/tools/slash-commands)。 示例： @@ -166,7 +180,7 @@ openclaw models image-fallbacks clear ### `models list` -默认显示已配置的模型。常用标志： +默认显示已配置模型。有用的标志： - `--all`：完整目录 - `--local`：仅本地提供商 @@ -174,16 +188,16 @@ openclaw models image-fallbacks clear - `--plain`：每行一个模型 - `--json`：机器可读输出 -`--all` 会在配置凭证之前，先包含由内置提供商拥有的静态目录条目，因此仅用于发现的视图也可以显示那些在你添加匹配提供商凭证之前不可用的模型。 +`--all` 会在配置凭证之前包含内置的、由提供商拥有的静态目录条目，因此仅发现视图可以显示那些在你添加匹配提供商凭证之前不可用的模型。 ### `models status` -显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示凭证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内发出警告）。`--plain` 仅打印已解析的主模型。 -OAuth 状态始终会显示（也会包含在 `--json` 输出中）。如果某个已配置的提供商没有凭证，`models status` 会打印一个 **Missing auth** 小节。 -JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的生效凭证，包括由环境变量提供的凭证）。`auth.oauth` 仅表示凭证存储中的配置文件健康状态；仅使用环境变量的提供商不会出现在其中。 -自动化场景请使用 `--check`（缺失/过期时退出码为 `1`，即将过期时为 `2`）。 -使用 `--probe` 可进行实时凭证检查；探测行可以来自凭证配置文件、环境变量凭证或 `models.json`。 -如果显式的 `auth.order.` 省略了一个已存储的配置文件，探测会报告 `excluded_by_auth_order`，而不是尝试它。如果凭证存在，但无法为该提供商解析出可探测的模型，则探测会报告 `status: no_model`。 +显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示在凭证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内到期时发出警告）。`--plain` 仅打印已解析的主模型。 +OAuth 状态始终会显示（也会包含在 `--json` 输出中）。如果某个已配置提供商没有凭证，`models status` 会打印一个 **缺少凭证** 部分。JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的生效凭证，包括由环境变量支持的凭证）。`auth.oauth` 仅表示凭证存储配置文件的健康状态；仅使用环境变量的提供商不会出现在其中。 +自动化场景请使用 `--check`（缺失/已过期时退出码为 `1`，即将过期时为 `2`）。 +使用 `--probe` 可执行实时凭证检查；探测行可来自凭证配置文件、环境变量凭证或 `models.json`。 +如果显式 `auth.order.` 省略了一个已存储配置文件，探测会报告 +`excluded_by_auth_order`，而不是尝试它。如果凭证存在，但无法为该提供商解析出可探测模型，则探测会报告 `status: no_model`。 凭证选择取决于提供商/账户。对于始终在线的 Gateway 网关主机，API 密钥通常是最可预测的；也支持复用 Claude CLI，以及现有的 Anthropic OAuth/token 配置文件。 @@ -196,7 +210,7 @@ openclaw models status ## 扫描（OpenRouter 免费模型） -`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并可选择探测模型是否支持工具和图像。 +`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并可选择探测模型对工具和图像的支持情况。 关键标志： @@ -205,12 +219,13 @@ openclaw models status - `--max-age-days `：跳过较旧模型 - `--provider `：提供商前缀筛选 - `--max-candidates `：回退列表大小 -- `--set-default`：将 `agents.defaults.model.primary` 设为第一个选中项 -- `--set-image`：将 `agents.defaults.imageModel.primary` 设为第一个图像选中项 +- `--set-default`：将 `agents.defaults.model.primary` 设为第一个选择项 +- `--set-image`：将 `agents.defaults.imageModel.primary` 设为第一个图像选择项 -探测需要 OpenRouter API 密钥（来自凭证配置文件或 `OPENROUTER_API_KEY`）。如果没有密钥，请使用 `--no-probe` 仅列出候选项。 +探测需要 OpenRouter API 密钥（来自凭证配置文件或 +`OPENROUTER_API_KEY`）。没有密钥时，请使用 `--no-probe` 仅列出候选项。 -扫描结果按以下顺序排序： +扫描结果按以下条件排序： 1. 图像支持 2. 工具延迟 @@ -228,25 +243,25 @@ openclaw models status ## 模型注册表（`models.json`） -`models.providers` 中的自定义提供商会写入智能体目录下的 `models.json`（默认路径为 `~/.openclaw/agents//agent/models.json`）。默认会合并该文件，除非 `models.mode` 设为 `replace`。 +`models.providers` 中的自定义提供商会写入智能体目录下的 `models.json`（默认是 `~/.openclaw/agents//agent/models.json`）。默认情况下，此文件会被合并，除非 `models.mode` 设为 `replace`。 -对于匹配的提供商 ID，合并模式优先级如下： +匹配提供商 ID 的合并模式优先级： - 智能体 `models.json` 中已存在的非空 `baseUrl` 优先。 -- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商在当前配置/凭证配置文件上下文中**不是** SecretRef 管理时才优先。 -- 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。 +- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商在当前配置/凭证配置文件上下文中**不是**由 SecretRef 管理时优先。 +- 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的秘密值。 - 由 SecretRef 管理的提供商请求头值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。 -- 智能体中为空或缺失的 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 -- 其他提供商字段会从配置和已规范化的目录数据中刷新。 +- 空的或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 +- 其他提供商字段会从配置和标准化目录数据中刷新。 -标记持久化以源为准：OpenClaw 会从活动源配置快照（解析前）写入标记，而不是从已解析的运行时密钥值写入。 -只要 OpenClaw 重新生成 `models.json`，这一规则都会适用，包括 `openclaw agent` 这样的命令驱动路径。 +标记持久化以源为准：OpenClaw 会根据当前源配置快照（预解析）写入标记，而不是根据运行时已解析的秘密值写入。 +这适用于 OpenClaw 重新生成 `models.json` 的任何情况，包括像 `openclaw agent` 这样的命令驱动路径。 ## 相关内容 -- [模型提供商](/zh-CN/concepts/model-providers) — 提供商路由与凭证 -- [模型回退](/zh-CN/concepts/model-failover) — 回退链 -- [图像生成](/zh-CN/tools/image-generation) — 图像模型配置 -- [音乐生成](/zh-CN/tools/music-generation) — 音乐模型配置 -- [视频生成](/zh-CN/tools/video-generation) — 视频模型配置 -- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键名 +- [Model Providers](/zh-CN/concepts/model-providers) — 提供商路由和凭证 +- [Model Failover](/zh-CN/concepts/model-failover) — 回退链 +- [Image Generation](/zh-CN/tools/image-generation) — 图像模型配置 +- [Music Generation](/zh-CN/tools/music-generation) — 音乐模型配置 +- [Video Generation](/zh-CN/tools/video-generation) — 视频模型配置 +- [Configuration Reference](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键名 diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 6a87cc49e..f5bbd03b0 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -2,69 +2,69 @@ read_when: - 你需要精确到字段级别的配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: 用于核心 OpenClaw 键名、默认值以及指向专用子系统参考文档链接的 Gateway 网关配置参考 +summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向专用子系统参考文档的链接 title: 配置参考 x-i18n: - generated_at: "2026-04-22T05:35:09Z" + generated_at: "2026-04-22T22:25:43Z" model: gpt-5.4 provider: openai - source_hash: f0d6fc076f54e84bef5beefbcc42d8f172cc79792c716f76103894303e3042ac + source_hash: f602f43fe750e99d5fed261634ce569c0034415cd1769e501e98d0ebe0ad1c19 source_path: gateway/configuration-reference.md workflow: 15 --- # 配置参考 -`~/.openclaw/openclaw.json` 的核心配置参考。若需按任务组织的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。若想查看面向任务的概览，请参见 [配置](/zh-CN/gateway/configuration)。 -本页介绍 OpenClaw 的主要配置面，并在某个子系统有更深入的独立参考时提供跳转链接。它**不会**尝试在同一页内联展示每个由渠道/插件拥有的命令目录，或每个深层 memory/QMD 调节项。 +本页涵盖 OpenClaw 的主要配置面，并在某个子系统拥有更深入的独立参考时提供外链。它**不会**尝试在一页内联展示每个渠道/插件自有的命令目录，也不会包含 memory/QMD 的每个深层旋钮。 -代码事实来源： +代码中的真实来源： - `openclaw config schema` 会输出用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据 -- `config.schema.lookup` 会返回一个按路径作用域限定的 schema 节点，供钻取工具使用 -- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 面验证配置文档基线哈希 +- `config.schema.lookup` 返回一个按路径范围划分的 schema 节点，供下钻工具使用 +- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面验证配置文档基线哈希 专用深度参考： -- [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)，适用于当前内置 + 内置插件的命令目录 -- 对应渠道/插件页面，适用于特定渠道的命令面 +- [Memory 配置参考](/zh-CN/reference/memory-config)，用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 Dreaming 配置 +- [斜杠命令](/zh-CN/tools/slash-commands)，用于当前内置 + 内置插件命令目录 +- 对应渠道/插件页面，用于渠道特定命令表面 -配置格式是 **JSON5**（允许注释和尾随逗号）。所有字段均为可选 —— OpenClaw 在省略时会使用安全默认值。 +配置格式是 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的 —— 省略时，OpenClaw 会使用安全默认值。 --- ## 渠道 -每个渠道在其配置段存在时都会自动启动（除非设置了 `enabled: false`）。 +只要某个渠道的配置段存在，它就会自动启动（除非设置了 `enabled: false`）。 ### 私信和群组访问 所有渠道都支持私信策略和群组策略： -| 私信策略 | 行为 | -| ------------------- | --------------------------------------------------------------- | -| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | -| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对的允许列表存储） | -| `open` | 允许所有入站私信（需要 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有入站私信 | +| 私信策略 | 行为 | +| ------------------- | ---- | +| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | +| `allowlist` | 只允许 `allowFrom` 中的发送者（或已配对的允许存储） | +| `open` | 允许所有入站私信（需要 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有入站私信 | -| 群组策略 | 行为 | -| --------------------- | ------------------------------------------------------ | -| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 | -| `open` | 绕过群组允许列表（仍会应用提及门控） | -| `disabled` | 阻止所有群组/房间消息 | +| 群组策略 | 行为 | +| --------------------- | ---- | +| `allowlist`（默认） | 只允许匹配已配置允许列表的群组 | +| `open` | 绕过群组允许列表（仍会应用提及门控） | +| `disabled` | 屏蔽所有群组/房间消息 | -当提供商的 `groupPolicy` 未设置时，`channels.defaults.groupPolicy` 会设置默认值。 +`channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时作为默认值。 配对码会在 1 小时后过期。待处理的私信配对请求上限为**每个渠道 3 个**。 -如果整个提供商块缺失（即不存在 `channels.`），运行时群组策略会回退为 `allowlist`（默认拒绝，fail-closed），并在启动时发出警告。 +如果提供商配置块完全缺失（`channels.` 不存在），运行时群组策略会回退为 `allowlist`（默认拒绝），并在启动时发出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。取值接受 `provider/model` 或已配置的模型别名。当某个会话尚未有模型覆盖时（例如通过 `/model` 设置），就会应用该渠道映射。 +使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值可接受 `provider/model` 或已配置的模型别名。当某个会话尚未有模型覆盖时（例如通过 `/model` 设置），就会应用该渠道映射。 ```json5 { @@ -87,7 +87,7 @@ x-i18n: ### 渠道默认值和心跳 -使用 `channels.defaults` 为各提供商共享群组策略和心跳行为： +使用 `channels.defaults` 在各提供商之间共享群组策略和心跳行为： ```json5 { @@ -106,14 +106,14 @@ x-i18n: ``` - `channels.defaults.groupPolicy`：当提供商级别的 `groupPolicy` 未设置时使用的回退群组策略。 -- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。按渠道覆盖：`channels..contextVisibility`。 +- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（只包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。按渠道覆盖：`channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。 - `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 -- `channels.defaults.heartbeat.useIndicator`：以紧凑的指示器样式渲染心跳输出。 +- `channels.defaults.heartbeat.useIndicator`：渲染紧凑的指示器式心跳输出。 ### WhatsApp -WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已链接会话时会自动启动。 +WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在已关联会话时，它会自动启动。 ```json5 { @@ -124,7 +124,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // 蓝色对勾（自聊模式下为 false） + sendReadReceipts: true, // 蓝色对勾（在自聊模式下为 false） groups: { "*": { requireMention: true }, }, @@ -164,9 +164,9 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 出站命令默认使用账号 `default`；如果不存在，则使用第一个已配置的账号 ID（按排序）。 -- 可选的 `channels.whatsapp.defaultAccount` 可在其匹配某个已配置账号 ID 时覆盖该回退默认账号选择。 -- 旧版单账号 Baileys auth 目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 +- 出站命令默认使用账号 `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,13 +225,13 @@ 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 发起的配置写入（超级群组 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`（在私聊和群聊中都可用）。 -- 重试策略：参见 [Retry policy](/zh-CN/concepts/retry)。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目用于为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义共享于 [ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- Telegram 流式预览使用 `sendMessage` + `editMessageText`（可用于私聊和群聊）。 +- 重试策略：参见 [重试策略](/zh-CN/concepts/retry)。 ### Discord @@ -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。 +- 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 个字符。 +- 默认会忽略由机器人撰写的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 则只接受提及机器人的机器人消息（机器人自己的消息仍会被过滤）。 +- `channels.discord.guilds..ignoreOtherMentions`（以及频道级覆盖）会丢弃提及其他用户或角色但未提及机器人的消息（不包括 @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` 中使用 channel/thread id）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。 -- `channels.discord.ui.components.accentColor` 为 Discord components v2 容器设置强调色。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目用于为频道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用频道/线程 ID）。字段语义共享于 [ACP 智能体](/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` 会将运行时可用性映射到机器人在线状态（healthy => online、degraded => idle、exhausted => dnd），并允许可选的状态文本覆盖。 -- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变的名称/tag 匹配（应急兼容模式）。 -- `channels.discord.execApprovals`：Discord 原生 exec 批准交付和批准人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出批准人时，会激活 exec 批准。 +- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会直接透传给 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 +- OpenClaw 还会在重复解密失败后，通过离开/重新加入语音会话来尝试恢复语音接收。 +- `channels.discord.streaming` 是规范的流式模式键名。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 +- `channels.discord.autoPresence` 将运行时可用性映射到机器人在线状态（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`。 - - `agentFilter`：可选的智能体 ID 允许列表。省略时会为所有智能体转发批准请求。 + - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：发送批准提示的位置。`"dm"`（默认）发送到批准人的私信，`"channel"` 发送到原始频道，`"both"` 同时发送到两者。当 target 包含 `"channel"` 时，按钮仅可由已解析的批准人使用。 - - `cleanupAfterResolve`：当为 `true` 时，在批准、拒绝或超时后删除批准私信。 + - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到发起频道，`"both"` 两者都发送。当 target 包含 `"channel"` 时，按钮仅可由已解析出的审批人使用。 + - `cleanupAfterResolve`：当为 `true` 时，在批准、拒绝或超时后删除审批私信。 -**反应通知模式：** `off`（无）、`own`（机器人自己的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users` 的所有消息）。 +**反应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users` 的所有消息）。 ### Google Chat @@ -393,11 +393,11 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- Service account JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 -- 也支持 Service account SecretRef（`serviceAccountRef`）。 +- 服务账号 JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 +- 也支持服务账号 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 交付目标请使用 `spaces/` 或 `users/`。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变 email principal 匹配（应急兼容模式）。 +- 投递目标使用 `spaces/` 或 `users/`。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变邮箱主体匹配（紧急兼容模式）。 ### Slack @@ -464,30 +464,26 @@ 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 模式下的 - `signingSecretStatus`。`configured_unavailable` 表示该账号是通过 SecretRef - 配置的，但当前命令/运行时路径无法解析出该 secret 值。 +- **Socket 模式** 需要同时提供 `botToken` 和 `appToken`（默认账号的环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP 模式** 需要 `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:`。 **反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 可以是按线程（默认）或在整个频道内共享。`thread.inheritParent` 会将父频道的会话记录复制到新线程中。 +**线程会话隔离：** `thread.historyScope` 可设为按线程（默认）或在频道内共享。`thread.inheritParent` 会将父频道转录复制到新线程。 -- Slack 原生流式传输加上 Slack 助手样式的 “is typing...” 线程状态需要一个回复线程目标。顶层私信默认保持非线程，因此会使用 `typingReaction` 或普通交付，而不是线程样式预览。 -- `typingReaction` 会在回复进行期间向入站 Slack 消息添加一个临时反应，并在完成时移除。请使用 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 消息添加一个临时反应，并在完成后移除。使用 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"`）。 | 操作组 | 默认值 | 说明 | | ------------ | ------- | ---------------------- | -| reactions | 已启用 | 添加反应 + 列出反应 | +| reactions | 已启用 | 反应 + 列出反应 | | messages | 已启用 | 读取/发送/编辑/删除 | | pins | 已启用 | 置顶/取消置顶/列出 | | memberInfo | 已启用 | 成员信息 | @@ -515,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, @@ -525,21 +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 服务器能够访问。 -- 原生 slash 回调使用 Mattermost 在注册 slash 命令时返回的每命令 token 进行认证。如果注册失败或未激活任何命令，OpenClaw 会拒绝回调，并返回 - `Unauthorized: invalid command token.`。 -- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 - `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。 - 请使用主机/域名值，而不是完整 URL。 +- 原生斜杠回调使用 Mattermost 在斜杠命令注册期间返回的每命令 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.requireMention`：在频道中回复前要求 `@mention`。 +- `channels.mattermost.groups..requireMention`：按频道覆盖提及门控（`"*"` 用作默认值）。 +- 可选的 `channels.mattermost.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 ### Signal @@ -548,7 +541,7 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos channels: { signal: { enabled: true, - account: "+15555550123", // 可选的账号绑定 + account: "+15555550123", // 可选账号绑定 dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -562,13 +555,13 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos **反应通知模式：** `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 { @@ -584,8 +577,8 @@ 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 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings)。 - 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。 ### iMessage @@ -614,17 +607,17 @@ OpenClaw 会启动 `imsg rpc`（基于 stdio 的 JSON-RPC）。无需守护进 } ``` -- 可选的 `channels.imessage.defaultAccount` 可在其匹配某个已配置账号 ID 时覆盖默认账号选择。 +- 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 需要对 Messages DB 拥有完全磁盘访问权限。 +- 需要对 Messages 数据库授予完全磁盘访问权限。 - 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以便通过 SCP 获取附件。 +- `cliPath` 可以指向 SSH 包装脚本；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。 - `attachmentRoots` 和 `remoteAttachmentRoots` 会限制入站附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 -- SCP 使用严格主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 +- SCP 使用严格主机密钥校验，因此请确保中继主机密钥已存在于 `~/.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 智能体](/zh-CN/tools/acp-agents#channel-specific-settings)。 - + ```bash #!/usr/bin/env bash @@ -666,18 +659,18 @@ 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 批准。 +- `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`）。 - - `agentFilter`：可选的智能体 ID 允许列表。省略时会为所有智能体转发批准请求。 + - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：发送批准提示的位置。`"dm"`（默认）、`"channel"`（原始房间）或 `"both"`。 + - `target`：发送审批提示的位置。`"dm"`（默认）、`"channel"`（发起房间）或 `"both"`。 - 按账号覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组到会话中：`per-user`（默认）按路由对端共享，而 `per-room` 会隔离每个私信房间。 +- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归并到会话中：`per-user`（默认）按路由对端共享，而 `per-room` 会隔离每个私信房间。 - Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 - 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 @@ -699,7 +692,7 @@ 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 @@ -725,12 +718,12 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 ``` - 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可选的 `channels.irc.defaultAccount` 可在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/mention gating）记录在 [IRC](/zh-CN/channels/irc) 中。 +- 可选的 `channels.irc.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 +- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 ### 多账号（所有渠道） -为每个渠道运行多个账号（每个账号各自有 `accountId`）： +为每个渠道运行多个账号（每个账号都有自己的 `accountId`）： ```json5 { @@ -751,18 +744,18 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 } ``` -- 当省略 `accountId` 时，使用 `default`（CLI + 路由）。 -- 环境变量 token 仅适用于 **default** 账号。 -- 基础渠道设置会应用到所有账号，除非在账号级别覆盖。 -- 使用 `bindings[].match.accountId` 可将每个账号路由到不同的智能体。 -- 如果你通过 `openclaw channels add`（或渠道新手引导）添加一个非默认账号，而当前仍使用单账号顶层渠道配置，OpenClaw 会先将按账号作用域划分的顶层单账号值提升到渠道账号映射中，以便原账号继续工作。大多数渠道会将它们移动到 `channels..accounts.default`；而 Matrix 则可以改为保留现有匹配的命名/default 目标。 -- 现有仅渠道级绑定（无 `accountId`）仍会匹配默认账号；按账号作用域划分的绑定依然是可选的。 -- `openclaw doctor --fix` 也会通过将按账号作用域划分的顶层单账号值移动到该渠道所选的提升后账号中来修复混合形态。大多数渠道使用 `accounts.default`；Matrix 则可以改为保留现有匹配的命名/default 目标。 +- 当省略 `accountId` 时，会使用 `default`（CLI + 路由）。 +- 环境变量 token 只适用于**默认**账号。 +- 基础渠道设置会应用到所有账号，除非按账号覆盖。 +- 使用 `bindings[].match.accountId` 将每个账号路由到不同的智能体。 +- 如果你在仍处于单账号顶层渠道配置的情况下，通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，OpenClaw 会先将按账号范围的顶层单账号值提升到渠道账号映射中，以便原始账号继续工作。大多数渠道会将它们移到 `channels..accounts.default`；Matrix 则可以改为保留现有匹配的命名/默认目标。 +- 现有仅限渠道的绑定（无 `accountId`）会继续匹配默认账号；按账号范围的绑定仍然是可选的。 +- `openclaw doctor --fix` 也会通过将按账号范围的顶层单账号值移入该渠道选定的提升账号中，来修复混合结构。大多数渠道使用 `accounts.default`；Matrix 则可以改为保留现有匹配的命名/默认目标。 ### 其他渠道插件 -许多渠道插件都配置为 `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)。 ### 群聊提及门控 @@ -772,7 +765,7 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 - **元数据提及**：平台原生 @ 提及。在 WhatsApp 自聊模式下会被忽略。 - **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 仅当能够进行检测时（存在原生提及或至少一个模式），才会执行提及门控。 +- 只有在可检测到提及的情况下（原生提及或至少一个模式），才会强制执行提及门控。 ```json5 { @@ -785,7 +778,7 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号）覆盖。设置为 `0` 可禁用。 +`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号）覆盖。设为 `0` 可禁用。 #### 私信历史限制 @@ -802,13 +795,13 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 } ``` -解析顺序：按私信覆盖 → 提供商默认值 → 不限制（全部保留）。 +解析顺序：按私信覆盖 → 提供商默认值 → 无限制（保留全部）。 支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 #### 自聊模式 -将你自己的号码包含在 `allowFrom` 中即可启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： +在 `allowFrom` 中包含你自己的号码以启用自聊模式（忽略原生 @ 提及，只响应文本模式）： ```json5 { @@ -829,13 +822,13 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 } ``` -### Commands（聊天命令处理） +### 命令（聊天命令处理） ```json5 { commands: { - native: "auto", // 支持时注册原生命令 - nativeSkills: "auto", // 支持时注册原生 Skills 命令 + native: "auto", // 在支持时注册原生命令 + nativeSkills: "auto", // 在支持时注册原生 Skills 命令 text: true, // 解析聊天消息中的 /commands bash: false, // 允许 !（别名：/bash） bashForegroundMs: 2000, @@ -843,7 +836,7 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 mcp: false, // 允许 /mcp plugins: false, // 允许 /plugins debug: false, // 允许 /debug - restart: true, // 允许 /restart + gateway restart 工具 + restart: true, // 允许 /restart + Gateway 网关重启工具 ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -858,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) 中。 -- 文本命令必须是以前导 `/` 开头的**独立**消息。 +- 此配置块用于配置命令表面。当前内置 + 内置插件命令目录请参见 [斜杠命令](/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` 这类由渠道/插件拥有的命令，记录在对应渠道/插件页面以及 [斜杠命令](/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.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 客户端仍然可用。 +- `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）。 +- `plugins: true` 会启用 `/plugins`，用于插件发现、安装和启用/禁用控制。 +- `channels..configWrites` 控制每个渠道的配置变更权限（默认：true）。 - 对于多账号渠道，`channels..accounts..configWrites` 也会控制针对该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 -- `restart: false` 会禁用 `/restart` 和 gateway restart 工具操作。默认值：`true`。 -- `ownerAllowFrom` 是 owner 专用命令/工具的显式 owner 允许列表。它与 `allowFrom` 分开。 -- `ownerDisplay: "hash"` 会在系统提示中对 owner id 做哈希处理。设置 `ownerDisplaySecret` 可控制哈希。 -- `allowFrom` 是按提供商划分的。设置后，它将成为**唯一**的授权来源（渠道允许列表/配对以及 `useAccessGroups` 都会被忽略）。 -- `useAccessGroups: false` 允许在未设置 `allowFrom` 时让命令绕过访问组策略。 +- `restart: false` 会禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。 +- `ownerAllowFrom` 是仅限所有者命令/工具的显式所有者允许列表。它与 `allowFrom` 分开。 +- `ownerDisplay: "hash"` 会在系统提示中对所有者 ID 进行哈希。设置 `ownerDisplaySecret` 可控制哈希行为。 +- `allowFrom` 是按提供商区分的。设置后，它将成为**唯一**的授权来源（渠道允许列表/配对和 `useAccessGroups` 会被忽略）。 +- `useAccessGroups: false` 会在 `allowFrom` 未设置时，允许命令绕过访问组策略。 - 命令文档映射： - - 内置 + 内置插件目录：[Slash Commands](/zh-CN/tools/slash-commands) - - 渠道特定命令面：[Channels](/zh-CN/channels) + - 内置 + 内置插件目录：[斜杠命令](/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) + - 配对命令：[配对](/zh-CN/channels/pairing) + - LINE 卡片命令：[LINE](/zh-CN/channels/line) + - memory Dreaming：[Dreaming](/zh-CN/concepts/dreaming) @@ -903,7 +896,7 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示的 Runtime 行中。如果未设置，OpenClaw 会从 workspace 开始向上遍历自动检测。 +可选的仓库根目录，会显示在系统提示的 Runtime 行中。如果未设置，OpenClaw 会从工作区开始向上遍历自动检测。 ```json5 { @@ -913,8 +906,7 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 ### `agents.defaults.skills` -适用于未设置 -`agents.list[].skills` 的智能体的可选默认 Skills 允许列表。 +对于未设置 `agents.list[].skills` 的智能体，可选的默认 Skills 允许列表。 ```json5 { @@ -923,21 +915,20 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 list: [ { id: "writer" }, // 继承 github、weather { id: "docs", skills: ["docs-search"] }, // 替换默认值 - { id: "locked-down", skills: [] }, // 无 Skills + { id: "locked-down", skills: [] }, // 不使用任何 Skills ], }, } ``` -- 省略 `agents.defaults.skills` 可使默认 Skills 不受限制。 -- 省略 `agents.list[].skills` 可继承默认值。 -- 设置 `agents.list[].skills: []` 表示不启用任何 Skills。 -- 非空的 `agents.list[].skills` 列表是该智能体的最终集合；它 - 不会与默认值合并。 +- 省略 `agents.defaults.skills`，则默认 Skills 不受限制。 +- 省略 `agents.list[].skills`，则继承默认值。 +- 设置 `agents.list[].skills: []` 表示不使用任何 Skills。 +- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。 ### `agents.defaults.skipBootstrap` -禁用自动创建 workspace bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 +禁用自动创建工作区 bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 ```json5 { @@ -947,9 +938,9 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 ### `agents.defaults.contextInjection` -控制何时将 workspace bootstrap 文件注入系统提示。默认值：`"always"`。 +控制何时将工作区 bootstrap 文件注入系统提示。默认值：`"always"`。 -- `"continuation-skip"`：安全续接轮次（在 assistant 完成响应之后）会跳过 workspace bootstrap 的重新注入，从而减少提示大小。心跳运行和压缩后重试仍会重建上下文。 +- `"continuation-skip"`：安全续接轮次（在 assistant 完整响应之后）会跳过工作区 bootstrap 的重新注入，从而减小提示大小。心跳运行和压缩后重试仍会重建上下文。 ```json5 { @@ -959,7 +950,7 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 ### `agents.defaults.bootstrapMaxChars` -单个 workspace bootstrap 文件在截断前的最大字符数。默认值：`12000`。 +每个工作区 bootstrap 文件在截断前允许的最大字符数。默认值：`12000`。 ```json5 { @@ -969,7 +960,7 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 ### `agents.defaults.bootstrapTotalMaxChars` -所有 workspace bootstrap 文件注入的总最大字符数。默认值：`60000`。 +跨所有工作区 bootstrap 文件注入的总字符数上限。默认值：`60000`。 ```json5 { @@ -979,12 +970,12 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 ### `agents.defaults.bootstrapPromptTruncationWarning` -控制在 bootstrap 上下文被截断时，对智能体可见的警告文本。 +控制 bootstrap 上下文被截断时向智能体显示的警告文本。 默认值：`"once"`。 - `"off"`：绝不将警告文本注入系统提示。 -- `"once"`：对每个唯一的截断签名注入一次警告（推荐）。 -- `"always"`：只要存在截断，就在每次运行时都注入警告。 +- `"once"`：对每个唯一的截断签名仅注入一次警告（推荐）。 +- `"always"`：只要存在截断，就在每次运行时注入警告。 ```json5 { @@ -994,33 +985,29 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 ### 上下文预算归属映射 -OpenClaw 有多个高容量提示/上下文预算，并且它们会 -按子系统有意拆分，而不是全部流经同一个通用 -调节项。 +OpenClaw 有多个高容量的提示/上下文预算，它们被有意按子系统拆分，而不是全部通过一个通用旋钮流转。 - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`： - 常规 workspace bootstrap 注入。 + 常规工作区 bootstrap 注入。 - `agents.defaults.startupContext.*`： - 单次 `/new` 和 `/reset` 启动前导内容，包括最近的每日 + 一次性的 `/new` 和 `/reset` 启动前导内容，包括最近的每日 `memory/*.md` 文件。 - `skills.limits.*`： - 注入系统提示的紧凑 Skills 列表。 + 注入系统提示中的紧凑 Skills 列表。 - `agents.defaults.contextLimits.*`： 有界运行时摘录和由运行时拥有的注入块。 - `memory.qmd.limits.*`： - 已索引 memory 搜索片段和注入大小控制。 + 已索引的 memory 搜索片段和注入大小控制。 -仅当某个智能体需要不同的 -预算时，才使用对应的按智能体覆盖： +仅当某个智能体需要不同预算时，才使用对应的按智能体覆盖： - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -控制在裸 `/new` 和 `/reset` -运行时注入的首轮启动前导内容。 +控制在裸 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。 ```json5 { @@ -1041,7 +1028,7 @@ OpenClaw 有多个高容量提示/上下文预算，并且它们会 #### `agents.defaults.contextLimits` -有界运行时上下文面的共享默认值。 +有界运行时上下文表面的共享默认值。 ```json5 { @@ -1058,18 +1045,14 @@ OpenClaw 有多个高容量提示/上下文预算，并且它们会 } ``` -- `memoryGetMaxChars`：默认的 `memory_get` 摘录上限；超过后会添加 - 截断元数据和继续提示。 -- `memoryGetDefaultLines`：省略 `lines` 时默认的 `memory_get` 行窗口。 -- `toolResultMaxChars`：用于持久化结果和 - 溢出恢复的实时工具结果上限。 -- `postCompactionMaxChars`：在压缩后 - 刷新注入期间使用的 AGENTS.md 摘录上限。 +- `memoryGetMaxChars`：`memory_get` 摘录在添加截断元数据和续接提示之前的默认上限。 +- `memoryGetDefaultLines`：当省略 `lines` 时，`memory_get` 的默认行窗口。 +- `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。 +- `postCompactionMaxChars`：压缩后刷新注入期间使用的 AGENTS.md 摘录上限。 #### `agents.list[].contextLimits` -共享 `contextLimits` 调节项的按智能体覆盖。省略的字段会继承 -`agents.defaults.contextLimits`。 +共享 `contextLimits` 旋钮的按智能体覆盖。省略的字段会继承自 `agents.defaults.contextLimits`。 ```json5 { @@ -1095,8 +1078,8 @@ OpenClaw 有多个高容量提示/上下文预算，并且它们会 #### `skills.limits.maxSkillsPromptChars` -注入系统提示的紧凑 Skills 列表的全局上限。此项 -不会影响按需读取 `SKILL.md` 文件。 +注入系统提示中的紧凑 Skills 列表的全局上限。 +这不会影响按需读取 `SKILL.md` 文件。 ```json5 { @@ -1129,11 +1112,11 @@ Skills 提示预算的按智能体覆盖。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，transcript/tool 图像块中图像最长边的最大像素尺寸。 +在调用提供商之前，转录/工具图像块中图像最长边的最大像素尺寸。 默认值：`1200`。 较低的值通常会减少视觉 token 使用量，以及在截图较多的运行中的请求负载大小。 -较高的值会保留更多视觉细节。 +较高的值则会保留更多视觉细节。 ```json5 { @@ -1191,7 +1174,7 @@ Skills 提示预算的按智能体覆盖。 primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // 全局默认提供商参数 + params: { cacheRetention: "long" }, // 全局默认 provider 参数 embeddedHarness: { runtime: "auto", // auto | pi | 已注册的 harness id，例如 codex fallback: "pi", // pi | none @@ -1210,48 +1193,50 @@ Skills 提示预算的按智能体覆盖。 } ``` -- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 字符串形式仅设置主模型。 - - 对象形式设置主模型以及按顺序的故障切换模型。 -- `imageModel`：接受字符串（`"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-2`（用于 OpenAI Images）。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商身份验证/API key（例如 `google/*` 需要 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 需要 `OPENAI_API_KEY`，`fal/*` 需要 `FAL_KEY`）。 - - 如果省略，`image_generate` 仍可推断出一个带身份验证的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的图像生成提供商。 -- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 当所选/默认模型无法接受图像输入时，也用作回退路由。 +- `imageGenerationModel`：既接受字符串（`"provider/model"`），也接受对象（`{ primary, fallbacks }`）。 + - 由共享图像生成能力以及未来任何生成图像的工具/插件表面使用。 + - 典型值：`google/gemini-3.1-flash-image-preview`（用于原生 Gemini 图像生成）、`fal/fal-ai/flux/dev`（用于 fal），或 `openai/gpt-image-2`（用于 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` 仍可推断出一个带身份验证的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的音乐生成提供商。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商身份验证/API key。 -- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 典型值：`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` 仍可推断出一个带身份验证的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的视频生成提供商。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商身份验证/API key。 - - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 -- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 典型值：`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` 工具在提取回退模式下默认考虑的最大页数。 + - 如果省略，PDF 工具会先回退到 `imageModel`，再回退到已解析出的会话/默认模型。 +- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb`，用于 `pdf` 工具的默认 PDF 大小限制。 +- `pdfMaxPages`：`pdf` 工具在提取回退模式下考虑的默认最大页数。 - `verboseDefault`：智能体的默认 verbose 级别。取值：`"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` 以及 fallback add/remove 命令）会保存规范对象形式，并在可能时保留现有 fallback 列表。 -- `maxConcurrent`：跨会话并行运行的最大智能体数（每个会话内部仍会串行化）。默认值：4。 +- `elevatedDefault`：智能体的默认 elevated 输出级别。取值：`"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`）。 + - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非传入 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换操作。 + - 按提供商范围的配置/新手引导流程会将所选提供商模型合并到此映射中，并保留已经配置的无关提供商。 +- `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" }`。 -当受信任插件提供原生 harness 时使用它，例如内置的 +当受信任的插件提供原生 harness 时使用它，例如内置的 Codex app-server harness。 ```json5 @@ -1268,15 +1253,15 @@ Codex app-server harness。 } ``` -- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置 Codex 插件会注册 `codex`。 -- `fallback`：`"pi"` 或 `"none"`。当未选择任何插件 harness 时，`"pi"` 会保留内置 PI harness 作为兼容回退。`"none"` 则会在插件 harness 缺失或不受支持时直接失败，而不是静默使用 PI。所选插件 harness 的失败始终会直接暴露。 +- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness ID。内置的 Codex 插件会注册 `codex`。 +- `fallback`：`"pi"` 或 `"none"`。当未选择任何插件 harness 时，`"pi"` 会保留内置 PI harness 作为兼容性回退。`"none"` 则会让缺失或不受支持的插件 harness 选择直接失败，而不是静默使用 PI。所选插件 harness 的失败始终会直接暴露。 - 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=none` 会为该进程禁用 PI 回退。 -- 对于仅 Codex 的部署，请设置 `model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。 +- 对于仅使用 Codex 的部署，设置 `model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。 - 这只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。 **内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： -| 别名 | 模型 | +| 别名 | 模型 | | ------------------- | -------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -1291,11 +1276,11 @@ Codex app-server harness。 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` 可禁用它。 -Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `adaptive` thinking。 +Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 `adaptive` thinking。 ### `agents.defaults.cliBackends` -适用于纯文本回退运行（无工具调用）的可选 CLI 后端。在 API 提供商失败时可作为备用方案。 +用于纯文本回退运行（无工具调用）的可选 CLI 后端。在 API 提供商失败时，可作为备用方案。 ```json5 { @@ -1329,7 +1314,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad ### `agents.defaults.systemPromptOverride` -用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体（`agents.list[].systemPromptOverride`）设置。按智能体的值优先；空值或仅含空白的值会被忽略。适用于受控提示实验。 +用一个固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别设置（`agents.defaults.systemPromptOverride`），也可按智能体设置（`agents.list[].systemPromptOverride`）。按智能体的值优先；空值或仅包含空白字符的值会被忽略。适用于受控提示实验。 ```json5 { @@ -1354,8 +1339,8 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad 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 会在一个全新会话中运行每次心跳（无会话历史） + lightContext: false, // 默认：false；true 只保留工作区 bootstrap 文件中的 HEARTBEAT.md + isolatedSession: false, // 默认：false；true 会让每次心跳都在全新会话中运行（无会话历史） session: "main", to: "+15555550123", directPolicy: "allow", // allow（默认）| block @@ -1370,15 +1355,15 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad } ``` -- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API-key 身份验证）或 `1h`（OAuth 身份验证）。设置为 `0m` 可禁用。 -- `includeSystemPromptSection`：为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。 -- `suppressToolErrorWarnings`：为 true 时，会在心跳运行期间抑制工具错误警告负载。 -- `timeoutSeconds`：心跳智能体轮次在被中止前允许的最长秒数。留空则使用 `agents.defaults.timeoutSeconds`。 -- `directPolicy`：直达/私信交付策略。`allow`（默认）允许直达目标交付。`block` 会抑制直达目标交付，并输出 `reason=dm-blocked`。 -- `lightContext`：为 true 时，心跳运行使用轻量 bootstrap 上下文，并且仅保留 workspace bootstrap 文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次心跳都会在一个没有先前会话历史的新会话中运行。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次心跳的 token 成本从约 100K 降低到约 2-5K token。 +- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 +- `includeSystemPromptSection`：设为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。 +- `suppressToolErrorWarnings`：设为 true 时，会在心跳运行期间抑制工具错误警告负载。 +- `timeoutSeconds`：在心跳智能体轮次被中止前允许的最长时间（秒）。留空则使用 `agents.defaults.timeoutSeconds`。 +- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并发出 `reason=dm-blocked`。 +- `lightContext`：设为 true 时，心跳运行会使用轻量级 bootstrap 上下文，并且仅保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：设为 true 时，每次心跳都在一个没有先前会话历史的全新会话中运行。隔离模式与 cron `sessionTarget: "isolated"` 相同。可将每次心跳的 token 成本从约 100K 降至约 2-5K token。 - 按智能体设置：使用 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。 -- 心跳运行的是完整智能体轮次 —— 间隔越短，消耗的 token 越多。 +- 心跳会运行完整的智能体轮次 —— 间隔越短，消耗的 token 越多。 ### `agents.defaults.compaction` @@ -1388,19 +1373,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // 已注册的 compaction 提供商插件的 id（可选） + provider: "my-provider", // 已注册 compaction provider 插件的 id（可选） timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom identifierInstructions: "精确保留部署 ID、工单 ID 和 host:port 对。", 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。", }, }, }, @@ -1408,19 +1393,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad } ``` -- `mode`：`default` 或 `safeguard`（针对长历史记录的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `provider`：已注册 compaction 提供商插件的 id。设置后，将调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。在失败时会回退到内置实现。设置提供商会强制启用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 在中止前允许单次 compaction 操作运行的最大秒数。默认值：`900`。 +- `mode`：`default` 或 `safeguard`（对长历史进行分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `provider`：已注册 compaction provider 插件的 id。设置后，将调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。在失败时会回退到内置实现。设置 provider 会强制使用 `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 为只读时会跳过。 +- `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 之前执行的静默智能体轮次，用于存储持久记忆。当工作区为只读时会跳过。 ### `agents.defaults.contextPruning` -在发送给 LLM 之前，从内存上下文中修剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 +在发送给 LLM 之前，从内存上下文中裁剪**旧工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -1444,23 +1429,23 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad -- `mode: "cache-ttl"` 会启用修剪过程。 -- `ttl` 控制再次运行修剪的频率（自上次缓存触达后）。 -- 修剪会先对过大的工具结果进行软修剪，必要时再对更旧的工具结果进行硬清除。 +- `mode: "cache-ttl"` 会启用裁剪轮次。 +- `ttl` 控制再次运行裁剪的频率（自上次缓存触碰后开始计算）。 +- 裁剪会先对过大的工具结果进行软裁剪，然后在需要时对更旧的工具结果执行硬清除。 -**软修剪**会保留开头和结尾，并在中间插入 `...`。 +**软裁剪** 会保留开头和结尾，并在中间插入 `...`。 -**硬清除**会用占位文本替换整个工具结果。 +**硬清除** 会用占位符替换整个工具结果。 -注意： +说明： -- 图像块永远不会被修剪/清除。 -- 比例按字符计算（近似），而不是精确 token 数。 -- 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过修剪。 +- 图像块永远不会被裁剪/清除。 +- 比例基于字符数（近似），不是精确 token 数。 +- 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过裁剪。 -行为细节请参见 [Session Pruning](/zh-CN/concepts/session-pruning)。 +行为细节参见 [会话裁剪](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -1480,9 +1465,9 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad - 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 - 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 -- `humanDelay`：分块回复之间的随机停顿。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。 +- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。 -行为和分块细节请参见 [Streaming](/zh-CN/concepts/streaming)。 +行为和分块细节参见 [流式传输](/zh-CN/concepts/streaming)。 ### 输入中指示器 @@ -1497,16 +1482,16 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad } ``` -- 默认值：在私聊/被提及时使用 `instant`，在未被提及的群聊中使用 `message`。 +- 默认值：私聊/被提及时为 `instant`，未提及的群聊为 `message`。 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 -参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 +参见 [输入中指示器](/zh-CN/concepts/typing-indicators)。 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南请参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -1606,47 +1591,47 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad **后端：** - `docker`：本地 Docker 运行时（默认） -- `ssh`：通用 SSH 支持的远程运行时 +- `ssh`：通用 SSH 远程运行时 - `openshell`：OpenShell 运行时 -当选择 `backend: "openshell"` 时，运行时特定设置将移动到 +当选择 `backend: "openshell"` 时，运行时特定设置会移至 `plugins.entries.openshell.config`。 **SSH 后端配置：** - `target`：`user@host[:port]` 形式的 SSH 目标 - `command`：SSH 客户端命令（默认：`ssh`） -- `workspaceRoot`：用于按作用域 workspace 的远程绝对根路径 +- `workspaceRoot`：用于按 scope 工作区的远程绝对根目录 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 -- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在运行时物化为临时文件的内联内容或 SecretRef -- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略调节项 +- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在运行时物化为临时文件的内联内容或 SecretRefs +- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 -**SSH 身份验证优先级：** +**SSH 认证优先级：** - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前从活动 secrets 运行时快照中解析 +- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从活动 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重建后初始化一次远程 workspace -- 之后保持远程 SSH workspace 为规范版本 +- 在创建或重建后，会先为远程工作区执行一次初始化 +- 随后保持远程 SSH 工作区为规范来源 - 通过 SSH 路由 `exec`、文件工具和媒体路径 - 不会自动将远程变更同步回主机 -- 不支持沙箱 browser 容器 +- 不支持沙箱浏览器容器 -**Workspace 访问：** +**工作区访问：** -- `none`：在 `~/.openclaw/sandboxes` 下为每个作用域创建沙箱 workspace -- `ro`：沙箱 workspace 位于 `/workspace`，智能体 workspace 以只读方式挂载到 `/agent` -- `rw`：智能体 workspace 以读写方式挂载到 `/workspace` +- `none`：位于 `~/.openclaw/sandboxes` 下的按 scope 沙箱工作区 +- `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent` +- `rw`：智能体工作区以读写方式挂载到 `/workspace` -**作用域：** +**Scope：** -- `session`：每个会话一个容器 + workspace -- `agent`：每个智能体一个容器 + workspace（默认） -- `shared`：共享容器和 workspace（无跨会话隔离） +- `session`：按会话划分的容器 + 工作区 +- `agent`：每个智能体一个容器 + 工作区（默认） +- `shared`：共享容器和工作区（无跨会话隔离） **OpenShell 插件配置：** @@ -1663,7 +1648,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad remoteAgentWorkspaceDir: "/agent", gateway: "lab", // 可选 gatewayEndpoint: "https://lab.example", // 可选 - policy: "strict", // 可选的 OpenShell policy id + policy: "strict", // 可选 OpenShell policy id providers: ["openai"], // 可选 autoProviders: true, timeoutSeconds: 120, @@ -1676,30 +1661,30 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时默认使用 `ad **OpenShell 模式：** -- `mirror`：在 `exec` 前从本地初始化远程，`exec` 后再同步回本地；本地 workspace 保持为规范版本 -- `remote`：在创建沙箱时仅初始化一次远程，之后保持远程 workspace 为规范版本 +- `mirror`：在执行前将远程与本地镜像同步，执行后再同步回本地；本地工作区保持为规范来源 +- `remote`：在创建沙箱时仅初始化远程一次，之后保持远程工作区为规范来源 -在 `remote` 模式下，初始化步骤之后，在 OpenClaw 外部对主机本地所做的编辑不会自动同步到沙箱中。 -传输通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的镜像同步。 +在 `remote` 模式下，初始化完成后，在 OpenClaw 外部进行的主机本地编辑不会自动同步进沙箱。 +传输使用 SSH 进入 OpenShell 沙箱，但插件拥有沙箱生命周期和可选的镜像同步。 -**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根目录和 root 用户。 +**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 -**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 -`"host"` 会被阻止。`"container:"` 默认也会被阻止，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（应急开关）。 +**容器默认使用 `network: "none"`** —— 如果智能体需要对外访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 +默认会阻止 `"host"`。默认也会阻止 `"container:"`，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急开关）。 -**入站附件** 会被暂存到活动 workspace 中的 `media/inbound/*`。 +**入站附件** 会被暂存到活动工作区中的 `media/inbound/*`。 -**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的绑定会合并。 +**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 binds 会合并。 -**沙箱隔离 browser**（`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`（默认）会阻止沙箱隔离会话以主机 browser 为目标。 -- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。仅当你明确希望获得全局 bridge 连通性时，才设置为 `bridge`。 -- `cdpSourceRange` 可选地将容器边界上的 CDP 入站访问限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅将额外主机目录挂载到沙箱 browser 容器中。设置后（包括 `[]`），它会替换 browser 容器的 `docker.binds`。 -- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调整： +- `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=` - `--user-data-dir=${HOME}/.chrome` @@ -1717,27 +1702,27 @@ 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`。 - - 这些默认值是容器镜像基线；如需更改容器默认值，请使用带自定义 - entrypoint 的自定义 browser 镜像。 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 可使用 Chromium 的 + 默认进程上限。 + - 此外，当启用 `noSandbox` 时，还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。 + - 默认值是容器镜像基线；如需更改容器默认值，请使用带有自定义 + entrypoint 的自定义浏览器镜像。 -browser 沙箱隔离和 `sandbox.docker.binds` 仅适用于 Docker。 +浏览器沙箱隔离和 `sandbox.docker.binds` 仅支持 Docker。 构建镜像： ```bash scripts/sandbox-setup.sh # 主沙箱镜像 -scripts/sandbox-browser-setup.sh # 可选 browser 镜像 +scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ``` ### `agents.list`（按智能体覆盖） @@ -1753,12 +1738,12 @@ scripts/sandbox-browser-setup.sh # 可选 browser 镜像 workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks } - thinkingDefault: "high", // 按智能体覆盖 thinking 级别 - reasoningDefault: "on", // 按智能体覆盖 reasoning 可见性 - fastModeDefault: false, // 按智能体覆盖 fast mode + thinkingDefault: "high", // 按智能体覆盖的默认 thinking 级别 + reasoningDefault: "on", // 按智能体覆盖的默认 reasoning 可见性 + fastModeDefault: false, // 按智能体覆盖的默认快速模式 embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // 按键覆盖匹配 defaults.models 的参数 - skills: ["docs-search"], // 设置后替换 agents.defaults.skills + params: { cacheRetention: "none" }, // 按键覆盖匹配 defaults.models params + skills: ["docs-search"], // 设置后会替换 agents.defaults.skills identity: { name: "Samantha", theme: "helpful sloth", @@ -1789,27 +1774,27 @@ scripts/sandbox-browser-setup.sh # 可选 browser 镜像 } ``` -- `id`：稳定的智能体 id（必填）。 -- `default`：设置多个时，以第一个为准（会记录警告）。如果都未设置，则列表中的第一个条目为默认值。 -- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖二者（`[]` 会禁用全局 fallbacks）。仅覆盖 `primary` 的 cron 作业仍会继承默认 fallbacks，除非你设置 `fallbacks: []`。 -- `params`：按智能体划分的流参数，会合并到 `agents.defaults.models` 中所选模型条目之上。用于为特定智能体覆盖 `cacheRetention`、`temperature` 或 `maxTokens` 等参数，而无需复制整个模型目录。 -- `skills`：可选的按智能体 Skills 允许列表。如果省略，并且设置了 `agents.defaults.skills`，则智能体会继承该值；显式列表会替换默认值而不是合并，`[]` 表示不启用任何 Skills。 -- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置按消息或按会话覆盖时，它会覆盖此智能体的 `agents.defaults.thinkingDefault`。 +- `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 | max`）。当未设置按消息或按会话覆盖时，会覆盖该智能体的 `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` 会推导默认值：从 `emoji` 推导 `ackReaction`，从 `name`/`emoji` 推导 `mentionPatterns`。 -- `subagents.allowAgents`：`sessions_spawn` 可用的智能体 id 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些将以非沙箱方式运行的目标。 -- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。 +- `fastModeDefault`：可选的按智能体默认快速模式（`true | false`）。当未设置按消息或按会话快速模式覆盖时生效。 +- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex", fallback: "none" }` 可让某个智能体仅使用 Codex，而其他智能体仍保留默认的 PI 回退。 +- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 并设置 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 +- `identity.avatar`：工作区相对路径、`http(s)` URL，或 `data:` URI。 +- `identity` 会派生默认值：`ackReaction` 取自 `emoji`，`mentionPatterns` 取自 `name`/`emoji`。 +- `subagents.allowAgents`：用于 `sessions_spawn` 的智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- 沙箱继承防护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些将以非沙箱模式运行的目标。 +- `subagents.requireAgentId`：为 true 时，阻止未提供 `agentId` 的 `sessions_spawn` 调用（强制显式选择 profile；默认：false）。 --- ## 多智能体路由 -在一个 Gateway 网关内运行多个隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关内运行多个彼此隔离的智能体。参见 [多智能体](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -1828,29 +1813,29 @@ scripts/sandbox-browser-setup.sh # 可选 browser 镜像 ### 绑定匹配字段 -- `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`（可选；特定于渠道） +- `match.guildId` / `match.teamId`（可选；渠道特定） - `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }` -**确定性匹配顺序：** +**确定性的匹配顺序：** 1. `match.peer` 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` + account + `match.peer.id`）解析，不使用上述 route 绑定层级顺序。 ### 按智能体访问配置 - + ```json5 { @@ -1868,7 +1853,7 @@ scripts/sandbox-browser-setup.sh # 可选 browser 镜像 - + ```json5 { @@ -1943,7 +1928,7 @@ scripts/sandbox-browser-setup.sh # 可选 browser 镜像 -优先级细节请参见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 +优先级细节参见 [多智能体沙箱与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1969,7 +1954,7 @@ scripts/sandbox-browser-setup.sh # 可选 browser 镜像 }, 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", @@ -1981,8 +1966,8 @@ scripts/sandbox-browser-setup.sh # 可选 browser 镜像 }, threadBindings: { enabled: true, - idleHours: 24, // 默认按小时的不活动自动取消聚焦（`0` 表示禁用） - maxAgeHours: 0, // 默认按小时的硬性最大时长（`0` 表示禁用） + idleHours: 24, // 默认按非活动时长自动取消焦点，单位小时（`0` 表示禁用） + maxAgeHours: 0, // 默认硬性最大时长，单位小时（`0` 表示禁用） }, mainKey: "main", // 旧版字段（运行时始终使用 "main"） agentToAgent: { maxPingPongTurns: 5 }, @@ -1997,34 +1982,34 @@ scripts/sandbox-browser-setup.sh # 可选 browser 镜像 - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在一个渠道上下文中，每个发送者都有独立会话。 - - `global`：一个渠道上下文中的所有参与者共享同一个会话（仅在确实需要共享上下文时使用）。 + - `per-sender`（默认）：每个发送者在某个渠道上下文中拥有独立会话。 + - `global`：某个渠道上下文中的所有参与者共享一个会话（仅在明确需要共享上下文时使用）。 - **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - - `per-peer`：按发送者 id 跨渠道隔离。 + - `per-peer`：按发送者 ID 跨渠道隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 -- **`identityLinks`**：将规范 id 映射到带提供商前缀的 peer，用于跨渠道会话共享。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在空闲 `idleMinutes` 后重置。当两者都已配置时，以先到期者为准。 +- **`identityLinks`**：将规范 ID 映射到带提供商前缀的对端，用于跨渠道会话共享。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。如果两者都配置，则以先到期者为准。 - **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建分叉线程会话时允许的父会话最大 `totalTokens`（默认 `100000`）。 - - 如果父会话的 `totalTokens` 高于该值，OpenClaw 会启动一个新的线程会话，而不是继承父会话的 transcript 历史。 - - 设置为 `0` 可禁用此保护，并始终允许父会话分叉。 +- **`parentForkMaxTokens`**：创建 fork 线程会话时允许的父会话 `totalTokens` 最大值（默认 `100000`）。 + - 如果父会话的 `totalTokens` 高于该值，OpenClaw 会启动一个新的线程会话，而不是继承父转录历史。 + - 设为 `0` 可禁用此保护，并始终允许父会话 fork。 - **`mainKey`**：旧版字段。运行时始终对主私聊桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体之间交换时，智能体间来回回复的最大轮数（整数，范围：`0`–`5`）。`0` 表示禁用 ping-pong 链式回复。 +- **`agentToAgent.maxPingPongTurns`**：智能体之间交换时，代理间来回回复的最大轮次数（整数，范围：`0`–`5`）。`0` 表示禁用 ping-pong 链式对话。 - **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 生效。 - **`maintenance`**：会话存储清理 + 保留控制。 - `mode`：`warn` 仅发出警告；`enforce` 会执行清理。 - - `pruneAfter`：过期条目的时间阈值（默认 `30d`）。 + - `pruneAfter`：陈旧条目的年龄截止值（默认 `30d`）。 - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。 - `rotateBytes`：当 `sessions.json` 超过该大小时进行轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` transcript 归档的保留时长。默认继承 `pruneAfter`；设置为 `false` 可禁用。 - - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的产物/会话。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留时间。默认使用 `pruneAfter`；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的制品/会话。 - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - - `enabled`：总默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认按小时计算的不活动自动取消聚焦（`0` 表示禁用；提供商可覆盖） - - `maxAgeHours`：默认按小时计算的硬性最大时长（`0` 表示禁用；提供商可覆盖） + - `enabled`：主默认开关（提供商可以覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） + - `idleHours`：按非活动时长自动取消焦点的默认小时数（`0` 表示禁用；提供商可覆盖） + - `maxAgeHours`：硬性最大时长的默认小时数（`0` 表示禁用；提供商可覆盖） @@ -2064,34 +2049,34 @@ scripts/sandbox-browser-setup.sh # 可选 browser 镜像 按渠道/账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会推导为 `[{identity.name}]`。 +解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。 **模板变量：** | 变量 | 说明 | 示例 | | ----------------- | ---------------------- | --------------------------- | -| `{model}` | 简短模型名 | `claude-opus-4-6` | +| `{model}` | 短模型名 | `claude-opus-4-6` | | `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | -| `{provider}` | 提供商名称 | `anthropic` | -| `{thinkingLevel}` | 当前 thinking 级别 | `high`, `low`, `off` | -| `{identity.name}` | 智能体 identity 名称 | （与 `"auto"` 相同） | +| `{provider}` | 提供商名称 | `anthropic` | +| `{thinkingLevel}` | 当前 thinking 级别 | `high`, `low`, `off` | +| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 ### 确认反应 -- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设置 `""` 可禁用。 +- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 - 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 - 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。 -- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上于回复后移除确认反应。 +- 范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除 ack。 - `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 - 在 Slack 和 Discord 上，未设置时会在确认反应处于启用状态时继续启用状态反应。 - 在 Telegram 上，需显式将其设置为 `true` 才会启用生命周期状态反应。 + 在 Slack 和 Discord 上，未设置时会在 ack 反应处于活动状态时保持启用状态反应。 + 在 Telegram 上，必须显式设置为 `true` 才会启用生命周期状态反应。 -### 入站去抖动 +### 入站防抖 -将同一发送者快速发来的纯文本消息批量合并为一次智能体轮次。媒体/附件会立即刷新。控制命令会绕过去抖动。 +将来自同一发送者的快速连续纯文本消息合并为一个智能体轮次。媒体/附件会立即冲刷。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -2134,18 +2119,18 @@ scripts/sandbox-browser-setup.sh # 可选 browser 镜像 } ``` -- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示实际生效状态。 +- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好，`/tts status` 会显示生效状态。 - `summaryModel` 会覆盖用于自动摘要的 `agents.defaults.model.primary`。 -- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需显式启用）。 +- `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 服务器，并放宽对 model/voice 的校验。 +- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置，然后是 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。 +- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容的 TTS 服务器，并放宽模型/voice 验证。 --- ## Talk -Talk 模式（macOS/iOS/Android）的默认值。 +Talk 模式的默认值（macOS/iOS/Android）。 ```json5 { @@ -2169,51 +2154,51 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 -- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.`。 +- `talk.provider` 在配置了多个 Talk 提供商时，必须匹配 `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.*.voiceAliases` 允许 Talk 指令使用友好的名称。 -- `silenceTimeoutMs` 控制 Talk 模式在用户静默后等待多久才发送 transcript。未设置时会保留平台默认停顿窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）。 +- 仅当未配置 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。 +- `providers.*.voiceAliases` 允许 Talk 指令使用易读名称。 +- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久再发送转录。未设置时会保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- ## 工具 -### 工具配置 +### 工具配置文件 `tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置基础允许列表： -本地新手引导会在未设置时将新的本地配置默认设为 `tools.profile: "coding"`（现有的显式配置不会被更改）。 +本地新手引导在未设置时，默认会将新的本地配置设为 `tools.profile: "coding"`（已存在的显式 profile 会被保留）。 -| 配置 | 包含项 | +| 配置文件 | 包含 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | 仅 `session_status` | +| `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` | 不限制（与未设置相同） | +| `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` -全局工具允许/拒绝策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭也会应用。 +全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱隔离处于关闭状态也会应用。 ```json5 { @@ -2223,7 +2208,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.byProvider` -进一步限制特定提供商或模型的工具。顺序：基础配置 → 提供商配置 → allow/deny。 +进一步限制特定提供商或模型可用的工具。顺序：基础 profile → 提供商 profile → allow/deny。 ```json5 { @@ -2256,8 +2241,8 @@ Talk 模式（macOS/iOS/Android）的默认值。 ``` - 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。 -- `/elevated on|off|ask|full` 会按会话保存状态；内联指令仅作用于单条消息。 -- elevated `exec` 会绕过沙箱隔离，并使用已配置的 escape 路径（默认是 `gateway`，当 exec 目标为 `node` 时使用 `node`）。 +- `/elevated on|off|ask|full` 会按会话存储状态；内联指令只作用于单条消息。 +- elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，当 exec 目标为 `node` 时则使用 `node`）。 ### `tools.exec` @@ -2281,8 +2266,8 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.loopDetection` -工具循环安全检查默认**关闭**。设置 `enabled: true` 可启用检测。 -设置可以在全局 `tools.loopDetection` 中定义，并在按智能体的 `agents.list[].tools.loopDetection` 中覆盖。 +工具循环安全检查默认**处于禁用状态**。设置 `enabled: true` 可启用检测。 +可以在 `tools.loopDetection` 中定义全局设置，并在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 ```json5 { @@ -2305,9 +2290,9 @@ Talk 模式（macOS/iOS/Android）的默认值。 - `historySize`：为循环分析保留的最大工具调用历史。 - `warningThreshold`：用于发出警告的重复无进展模式阈值。 -- `criticalThreshold`：用于阻止严重循环的更高重复阈值。 +- `criticalThreshold`：用于阻止关键循环的更高重复阈值。 - `globalCircuitBreakerThreshold`：任何无进展运行的硬停止阈值。 -- `detectors.genericRepeat`：对重复的相同工具/相同参数调用发出警告。 +- `detectors.genericRepeat`：对重复的同工具/同参数调用发出警告。 - `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。 - `detectors.pingPong`：对交替出现的无进展成对模式发出警告/阻止。 - 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证会失败。 @@ -2327,7 +2312,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 }, fetch: { enabled: true, - provider: "firecrawl", // 可选；省略则自动检测 + provider: "firecrawl", // 可选；省略时自动检测 maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2352,7 +2337,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 media: { concurrency: 2, asyncCompletion: { - directSend: false, // 显式启用：将完成的异步音乐/视频直接发送到渠道 + directSend: false, // 显式启用：将已完成的异步音乐/视频直接发送到渠道 }, audio: { enabled: true, @@ -2382,7 +2367,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` profile 选择 **CLI 条目**（`type: "cli"`）： @@ -2395,13 +2380,13 @@ Talk 模式（macOS/iOS/Android）的默认值。 - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：按条目覆盖。 - 失败时会回退到下一个条目。 -提供商身份验证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 +提供商认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 **异步完成字段：** - `asyncCompletion.directSend`：当为 `true` 时，已完成的异步 `music_generate` - 和 `video_generate` 任务会先尝试直接交付到渠道。默认值：`false` - （旧版请求方会话唤醒/模型交付路径）。 + 和 `video_generate` 任务会先尝试直接渠道投递。默认值：`false` + （旧版的请求方会话唤醒/模型投递路径）。 @@ -2420,9 +2405,9 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.sessions` -控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可以面向哪些会话。 +控制 session 工具（`sessions_list`、`sessions_history`、`sessions_send`）可以定位哪些会话。 -默认值：`tree`（当前会话 + 由其派生出的会话，例如子智能体）。 +默认值：`tree`（当前会话 + 由其生成的会话，例如子智能体）。 ```json5 { @@ -2435,13 +2420,13 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -注意： +说明： - `self`：仅当前会话键。 -- `tree`：当前会话 + 由当前会话派生出的会话（子智能体）。 -- `agent`：属于当前智能体 id 的任意会话（如果你在同一智能体 id 下运行按发送者划分的会话，也可能包含其他用户）。 -- `all`：任意会话。跨智能体目标仍需要 `tools.agentToAgent`。 -- 沙箱钳制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 +- `tree`：当前会话 + 由当前会话生成的会话（子智能体）。 +- `agent`：属于当前智能体 ID 的任意会话（如果你在同一个智能体 ID 下运行按发送者划分的会话，也可能包括其他用户）。 +- `all`：任意会话。跨智能体定位仍需要 `tools.agentToAgent`。 +- 沙箱钳制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制设为 `tree`。 ### `tools.sessions_spawn` @@ -2452,7 +2437,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 tools: { sessions_spawn: { attachments: { - enabled: false, // 显式启用：设置为 true 以允许内联文件附件 + enabled: false, // 显式启用：设为 true 以允许内联文件附件 maxTotalBytes: 5242880, // 所有文件总计 5 MB maxFiles: 50, maxFileBytes: 1048576, // 每个文件 1 MB @@ -2463,34 +2448,34 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -注意： +说明： -- 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 -- 文件会被物化到子 workspace 中 `.openclaw/attachments//`，并附带 `.manifest.json`。 -- 附件内容会自动从 transcript 持久化中脱敏。 -- Base64 输入会使用严格的字母表/填充校验以及解码前大小保护进行验证。 -- 文件权限为目录 `0700`、文件 `0600`。 -- 清理由 `cleanup` 策略控制：`delete` 总会移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留附件。 +- 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝它们。 +- 文件会被物化到子工作区的 `.openclaw/attachments//` 中，并附带一个 `.manifest.json`。 +- 附件内容会自动从转录持久化中脱敏。 +- Base64 输入会通过严格的字母表/填充检查和解码前大小保护进行验证。 +- 目录权限为 `0700`，文件权限为 `0600`。 +- 清理由 `cleanup` 策略控制：`delete` 总会删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留附件。 ### `tools.experimental` -实验性内置工具标志。默认关闭，除非适用严格 agentic GPT-5 自动启用规则。 +实验性内置工具标志。默认关闭，除非严格 agentic GPT-5 自动启用规则生效。 ```json5 { tools: { experimental: { - planTool: true, // 启用实验性的 update_plan + planTool: true, // 启用实验性 update_plan }, }, } ``` -注意： +说明： -- `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 -- 默认值：`false`，除非将 `agents.defaults.embeddedPi.executionContract`（或按智能体覆盖）设置为 `"strict-agentic"`，并用于 OpenAI 或 OpenAI Codex GPT-5 家族运行。设置为 `true` 可在该范围之外强制启用该工具，设置为 `false` 则即使在严格 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` @@ -2510,9 +2495,9 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- `model`：派生子智能体的默认模型。省略时，子智能体会继承调用方模型。 -- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 可用的默认目标智能体 id 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时（秒）。`0` 表示无超时。 +- `model`：生成的子智能体的默认模型。如果省略，子智能体会继承调用方的模型。 +- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 目标智能体 ID 的默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时（秒）。`0` 表示无超时。 - 按子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- @@ -2548,42 +2533,43 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -- 对于自定义身份验证需求，使用 `authHeader: true` + `headers`。 -- 使用 `OPENCLAW_AGENT_DIR` 覆盖智能体配置根目录（或使用旧版环境变量别名 `PI_CODING_AGENT_DIR`）。 +- 使用 `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`，文件/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 值。 ### 提供商字段详情 - `models.mode`：提供商目录行为（`merge` 或 `replace`）。 -- `models.providers`：按提供商 id 作为键的自定义提供商映射。 +- `models.providers`：按提供商 id 建立键的自定义提供商映射。 + - 安全编辑：使用 `openclaw config set models.providers. '' --strict-json --merge` 或 `openclaw config set models.providers..models '' --strict-json --merge` 进行增量更新。除非传入 `--replace`，否则 `config set` 会拒绝破坏性替换。 - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。 - `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.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 +- `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，将 `options.num_ctx` 注入请求（默认：`true`）。 - `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭证。 - `models.providers.*.baseUrl`：上游 API base URL。 - `models.providers.*.headers`：用于代理/租户路由的额外静态 header。 - `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖。 - - `request.headers`：额外 header（与提供商默认值合并）。值支持 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 抓取保护访问 HTTPS（这是对受信任自托管 OpenAI 兼容端点的 operator 显式启用项）。WebSocket 也使用相同的 `request` 处理 header/TLS，但不受该抓取 SSRF 门控影响。默认值为 `false`。 -- `models.providers.*.models`：显式的提供商模型目录条目。 + - `request.headers`：额外 header（与提供商默认值合并）。值可接受 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（这是面向受信任自托管 OpenAI 兼容端点的 operator 显式启用项）。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.*.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 过滤器。 @@ -2627,7 +2613,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`。 @@ -2664,8 +2650,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` -- 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` -- 若要使用通用端点，请定义一个带 base URL 覆盖的自定义提供商。 +- Coding 端点（默认）：`https://api.z.ai/api/coding/paas/v4` +- 对于通用端点，请定义一个带 base URL 覆盖的自定义提供商。 @@ -2706,9 +2692,9 @@ 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`。 -原生 Moonshot 端点会在共享 -`openai-completions` 传输上声明流式使用兼容性，OpenClaw 会据此依赖端点能力 -而不是仅依赖内置提供商 id。 +原生 Moonshot 端点会在共享的 +`openai-completions` 传输上声明流式使用兼容性，而 OpenClaw 会基于端点能力 +来决定该行为，而不仅仅依据内置 provider id。 @@ -2726,11 +2712,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 { @@ -2765,7 +2751,7 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 +base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 @@ -2809,8 +2795,8 @@ 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` 或 +在兼容 Anthropic 的流式路径上，除非你显式设置 `thinking`，否则 OpenClaw +默认会禁用 MiniMax thinking。`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 @@ -2818,7 +2804,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 -参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在性能较强的硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已托管模型的合并配置作为回退。 +参见 [本地模型](/zh-CN/gateway/local-models)。简而言之：在高性能硬件上通过 LM Studio Responses API 运行大型本地模型；保留合并后的托管模型作为回退。 @@ -2849,13 +2835,12 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `allowBundled`：仅针对内置 Skills 的可选允许列表（不影响受管/工作区 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`：为声明了主环境变量的技能提供便捷设置（明文字符串或 SecretRef 对象）。 +- `allowBundled`：仅针对内置 Skills 的可选允许列表（托管/工作区 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`：为声明了主环境变量的 skill 提供便捷配置（明文字符串或 SecretRef 对象）。 --- @@ -2884,46 +2869,46 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 设备发现同时接受原生 OpenClaw 插件以及兼容的 Codex bundles 和 Claude bundles，包括无 manifest 的 Claude 默认布局 bundles。 -- **配置更改需要重启 Gateway 网关。** +- 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 +- **配置变更需要重启 Gateway 网关。** - `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 - `plugins.entries..apiKey`：插件级 API key 便捷字段（当插件支持时）。 - `plugins.entries..env`：插件作用域环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hook 和受支持 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` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会变更 prompt 的字段，同时保留旧版 `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` 环境变量。 - `baseUrl`：Firecrawl API base URL（默认：`https://api.firecrawl.dev`）。 - - `onlyMainContent`：仅提取页面主内容（默认：`true`）。 - - `maxAgeMs`：最大缓存时长（毫秒）（默认：`172800000` / 2 天）。 - - `timeoutSeconds`：抓取请求超时秒数（默认：`60`）。 -- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web search）设置。 + - `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)。 - - `enabled`：dreaming 总开关（默认 `false`）。 - - `frequency`：每次完整 dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。 +- `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 配置参考](/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`：选择活动 context engine 插件 id；默认是 `"legacy"`，除非你安装并选择了其他 engine。 - `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 - - 包含 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 + - 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - 将 `plugins.installs.*` 视为受管状态；优先使用 CLI 命令，而不是手动编辑。 -参见 [Plugins](/zh-CN/tools/plugin)。 +参见 [插件](/zh-CN/tools/plugin)。 --- -## Browser +## 浏览器 ```json5 { @@ -2960,28 +2945,28 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用，因此 browser 导航默认保持严格模式。 -- 仅当你明确信任私有网络 browser 导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP 配置端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到相同的私有网络阻止。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 未设置时处于禁用状态，因此浏览器导航默认保持严格模式。 +- 仅当你有意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 +- 在严格模式下，远程 CDP profile 端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的私有网络阻止规则约束。 - `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 -- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 设置显式例外。 -- 远程配置为仅附加模式（禁用 start/stop/reset）。 +- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 进行显式例外配置。 +- 远程 profile 为仅附加模式（禁用 start/stop/reset）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)； - 当提供商直接给你 DevTools WebSocket URL 时，请使用 WS(S)。 -- `existing-session` 配置使用 Chrome MCP 而不是 CDP，并且可以附加到所选主机上 - 或通过已连接的 browser 节点附加。 -- `existing-session` 配置可以设置 `userDataDir`，以指向特定的 - Chromium 系 browser 配置，例如 Brave 或 Edge。 -- `existing-session` 配置保留当前 Chrome MCP 路由限制： - 使用 snapshot/ref 驱动操作而非 CSS 选择器定位、单文件上传 - hook、无对话框超时覆盖、无 `wait --load networkidle`，以及无 + 当你希望 OpenClaw 发现 `/json/version` 时，使用 HTTP(S)； + 当提供商直接给出 DevTools WebSocket URL 时，使用 WS(S)。 +- `existing-session` profile 使用 Chrome MCP 而不是 CDP，并且可以附加到 + 选定主机上，或通过已连接的浏览器节点附加。 +- `existing-session` profile 可以设置 `userDataDir`，以定位特定的 + Chromium 系浏览器 profile，例如 Brave 或 Edge。 +- `existing-session` profile 保留当前 Chrome MCP 路由限制： + 使用 snapshot/ref 驱动的操作而不是 CSS 选择器定位、单文件上传 + hooks、不支持对话框超时覆盖、不支持 `wait --load networkidle`，以及不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地受管的 `openclaw` 配置会自动分配 `cdpPort` 和 `cdpUrl`；仅 - 在远程 CDP 场景下显式设置 `cdpUrl`。 -- 自动检测顺序：默认 browser（若为 Chromium 系）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 -- Control 服务：仅 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 -- `extraArgs` 会向本地 Chromium 启动追加额外标志（例如 +- 本地受管 `openclaw` profile 会自动分配 `cdpPort` 和 `cdpUrl`；只有在远程 CDP 场景下 + 才需要显式设置 `cdpUrl`。 +- 自动检测顺序：默认浏览器（若为 Chromium 系）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 控制服务：仅限 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 +- `extraArgs` 会向本地 Chromium 启动追加额外启动标志（例如 `--disable-gpu`、窗口大小设置或调试标志）。 --- @@ -3000,8 +2985,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `seamColor`：原生应用 UI 外观的强调色（Talk Mode 气泡色调等）。 -- `assistant`：Control UI 的 identity 覆盖。会回退到活动智能体 identity。 +- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡着色等）。 +- `assistant`：Control UI 身份覆盖。未设置时回退到当前活动智能体身份。 --- @@ -3037,7 +3022,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 // embedSandbox: "scripts", // strict | scripts | trusted // allowExternalEmbedUrls: false, // 危险：允许绝对外部 http(s) 嵌入 URL // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必填 - // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host-header origin 回退模式 + // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host header origin 回退模式 // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -3051,9 +3036,9 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 // 可选。默认 false。 allowRealIpFallback: false, tools: { - // 额外的 /tools/invoke HTTP deny + // 额外的 /tools/invoke HTTP 拒绝项 deny: ["browser"], - // 从默认 HTTP deny 列表中移除工具 + // 从默认 HTTP 拒绝列表中移除工具 allow: ["gateway"], }, push: { @@ -3070,64 +3055,64 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 -- `mode`：`local`（运行 gateway）或 `remote`（连接到远程 gateway）。除非为 `local`，否则 Gateway 网关会拒绝启动。 -- `port`：WS + HTTP 共用的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 +- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非是 `local`，否则 Gateway 网关会拒绝启动。 +- `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。 -- **旧版 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"`）以监听所有接口。 -- **Auth**：默认必须启用。非 loopback bind 需要 gateway auth。实际意味着要么使用共享 token/password，要么使用设置了 `gateway.auth.mode: "trusted-proxy"` 的 identity-aware 反向代理。新手引导默认会生成 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"`：将认证委托给 identity-aware 反向代理，并信任来自 `gateway.trustedProxies` 的身份 header（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 的代理来源；同主机的 loopback 反向代理不满足 trusted-proxy auth 要求。 -- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve identity header 可满足 Control UI/WebSocket auth（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale header 认证；它们仍遵循 gateway 的常规 HTTP auth 模式。此无 token 流程假定 gateway 主机是受信任的。当 `tailscale.mode = "serve"` 时默认值为 `true`。 -- `gateway.auth.rateLimit`：可选的认证失败限速器。按客户端 IP 和 auth 作用域生效（共享 secret 和设备 token 会分别跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径上，同一个 `{scope, clientIp}` 的失败尝试会在写入失败记录之前串行化。因此，同一客户端并发的错误尝试，可能会让第二个请求触发限速器，而不是两个请求都作为普通不匹配直接通过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；如果你有意也要对 localhost 流量进行限速（例如测试环境或严格代理部署），请设置为 `false`。 -- 来自 browser 的 WS 认证尝试始终会进行限速，并关闭 loopback 豁免（作为防御加固，防止基于 browser 的 localhost 暴力破解）。 -- 在 loopback 上，这些来自 browser 的锁定会按规范化后的 `Origin` - 值分别隔离，因此来自某个 localhost origin 的重复失败不会自动 +- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用 host 别名（`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 bind 要求 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` 的身份 header（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 的代理来源；同主机 loopback 反向代理不满足 trusted-proxy 认证要求。 +- `gateway.auth.allowTailscale`：当为 `true` 时，Tailscale Serve 身份 header 可以满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale header 认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。该无 token 流程假设 Gateway 网关主机受信任。当 `tailscale.mode = "serve"` 时，默认值为 `true`。 +- `gateway.auth.rateLimit`：可选的认证失败限速器。按客户端 IP 和认证作用域应用（共享 secret 和 device token 会分别跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 + - 在异步 Tailscale Serve Control UI 路径上，对于相同 `{scope, clientIp}` 的失败尝试，会在写入失败记录前被串行化。因此，来自同一客户端的并发错误尝试可能会在第二个请求时触发限速器，而不是两个都作为普通不匹配同时通过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；当你有意也要对 localhost 流量进行限速时（例如测试设置或严格代理部署），可将其设为 `false`。 +- 来自浏览器源的 WS 认证尝试始终会启用限速，且禁用 loopback 豁免（作为对基于浏览器的 localhost 暴力破解的纵深防御）。 +- 在 loopback 上，这些来自浏览器源的锁定会按规范化后的 `Origin` + 值彼此隔离，因此来自某个 localhost origin 的重复失败不会自动 锁定另一个 origin。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公网，需要认证）。 -- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式 browser-origin 允许列表。当预期 browser 客户端来自非 loopback origin 时必须设置。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host-header origin 策略的部署启用 Host-header origin 回退。 +- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开访问，需要认证）。 +- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器源允许列表。当预计浏览器客户端来自非 loopback origin 时，这是必填项。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host header origin 策略的部署启用 Host header origin 回退。 - `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧的应急覆盖，允许连接到受信任私有网络 IP 的明文 `ws://`；默认仍只允许 loopback 使用明文。 -- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 gateway auth。 -- `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 identity。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该 identity，并将某个注册作用域的发送授权转发给 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.channelMaxRestartsPerHour`：每个渠道/账号在滚动一小时内允许的最大健康监控重启次数。默认值：`10`。 -- `channels..healthMonitor.enabled`：按渠道选择退出健康监控重启，同时保留全局监控启用。 -- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。设置后，其优先级高于渠道级覆盖。 -- 本地 gateway 调用路径仅在 `gateway.auth.*` 未设置时，才可以将 `gateway.remote.*` 用作回退。 -- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但未解析，则解析会以关闭方式失败（不会使用远程回退来掩盖）。 -- `trustedProxies`：终止 TLS 或注入 forwarded-client header 的反向代理 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` 额外阻止的工具名称（扩展默认 deny 列表）。 -- `gateway.tools.allow`：从默认 HTTP deny 列表中移除工具名称。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧的紧急开关覆盖，允许明文 `ws://` 连接到受信任的私有网络 IP；默认仍仅允许 loopback 使用明文连接。 +- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 +- `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.channelMaxRestartsPerHour`：滚动一小时内每个渠道/账号允许的最大健康监控重启次数。默认值：`10`。 +- `channels..healthMonitor.enabled`：按渠道选择退出健康监控重启，同时保留全局监控启用状态。 +- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。设置后，它的优先级高于渠道级覆盖。 +- 本地 Gateway 网关调用路径仅会在 `gateway.auth.*` 未设置时，才可将 `gateway.remote.*` 作为回退。 +- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但无法解析，解析会以默认拒绝方式失败（不会被远程回退所掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端 header 的反向代理 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 兼容端点 -- Chat Completions：默认禁用。使用 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 -- Responses API：使用 `gateway.http.endpoints.responses.enabled`。 +- Chat Completions：默认禁用。通过 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 +- Responses API：`gateway.http.endpoints.responses.enabled`。 - Responses URL 输入加固： - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - 空 allowlist 会被视为未设置；使用 `gateway.http.endpoints.responses.files.allowUrl=false` - 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 可禁用 URL 抓取。 + 空允许列表会被视为未设置；使用 `gateway.http.endpoints.responses.files.allowUrl=false` + 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 以禁用 URL 抓取。 - 可选的响应加固 header： - - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS origin 设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） + - `gateway.http.securityHeaders.strictTransportSecurity`（仅为你控制的 HTTPS origin 设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 -在同一主机上运行多个 gateways，并为它们分配唯一端口和状态目录： +在同一主机上通过唯一端口和状态目录运行多个 Gateway 网关： ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3137,7 +3122,7 @@ openclaw gateway --port 19001 便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`），`--profile `（使用 `~/.openclaw-`）。 -参见 [Multiple Gateways](/zh-CN/gateway/multiple-gateways)。 +参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 ### `gateway.tls` @@ -3155,11 +3140,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`：在 gateway 监听器处启用 TLS 终止（HTTPS/WSS）（默认：`false`）。 -- `autoGenerate`：当未配置显式文件时自动生成本地自签名证书/密钥对；仅用于本地/开发环境。 +- `enabled`：在 Gateway 网关监听器处启用 TLS 终止（HTTPS/WSS）（默认：`false`）。 +- `autoGenerate`：当未配置显式文件时自动生成本地自签名证书/密钥对；仅供本地/开发使用。 - `certPath`：TLS 证书文件的文件系统路径。 - `keyPath`：TLS 私钥文件的文件系统路径；应限制权限。 -- `caPath`：用于客户端验证或自定义信任链的可选 CA bundle 路径。 +- `caPath`：可选 CA bundle 路径，用于客户端验证或自定义信任链。 ### `gateway.reload` @@ -3175,13 +3160,13 @@ openclaw gateway --port 19001 } ``` -- `mode`：控制配置编辑在运行时的应用方式。 - - `"off"`：忽略实时编辑；更改需要显式重启。 - - `"restart"`：配置变更时始终重启 gateway 进程。 - - `"hot"`：在进程内应用更改而不重启。 +- `mode`：控制运行时如何应用配置编辑。 + - `"off"`：忽略实时编辑；变更需要显式重启。 + - `"restart"`：配置变更时始终重启 Gateway 网关进程。 + - `"hot"`：在不重启的情况下，在进程内应用变更。 - `"hybrid"`（默认）：先尝试热重载；如有需要则回退到重启。 -- `debounceMs`：应用配置变更前的去抖窗口（毫秒）（非负整数）。 -- `deferralTimeoutMs`：在强制重启前等待正在进行中的操作完成的最长时间（毫秒）（默认：`300000` = 5 分钟）。 +- `debounceMs`：应用配置变更前的防抖窗口，单位毫秒（非负整数）。 +- `deferralTimeoutMs`：在强制重启前，等待进行中的操作完成的最长时间，单位毫秒（默认：`300000` = 5 分钟）。 --- @@ -3208,7 +3193,7 @@ openclaw gateway --port 19001 wakeMode: "now", name: "Gmail", sessionKey: "hook:gmail:{{messages[0].id}}", - messageTemplate: "发件人：{{messages[0].from}}\n主题：{{messages[0].subject}}\n{{messages[0].snippet}}", + messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}", deliver: true, channel: "last", model: "openai/gpt-5.4-mini", @@ -3223,42 +3208,42 @@ openclaw gateway --port 19001 验证和安全说明： -- `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:"]`）。 -- 如果某个映射或预设使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要此显式启用。 +- 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 +- 如果某个 mapping 或 preset 使用模板化 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态 mapping 键不需要这个显式启用项。 **端点：** - `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` 时，才接受请求负载中的 `sessionKey`（默认：`false`）。 - `POST /hooks/` → 通过 `hooks.mappings` 解析 - - 模板渲染后的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。 + - 模板渲染后的 mapping `sessionKey` 值会被视为外部提供，因此也要求 `hooks.allowRequestSessionKey=true`。 -- `match.path`：匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 -- `match.source`：对通用路径匹配某个负载字段。 -- `{{messages[0].subject}}` 之类的模板会从负载中读取。 -- `transform` 可以指向一个返回 hook 操作的 JS/TS 模块。 - - `transform.module` 必须是相对路径，并且始终位于 `hooks.transformsDir` 内（绝对路径和路径遍历都会被拒绝）。 +- `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 +- `match.source` 匹配通用路径中的某个负载字段。 +- 像 `{{messages[0].subject}}` 这样的模板会从负载中读取。 +- `transform` 可以指向一个返回 hook action 的 JS/TS 模块。 + - `transform.module` 必须是相对路径，并且必须保持在 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。 - `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。 - `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。 -- `defaultSessionKey`：用于无显式 `sessionKey` 的 hook 智能体运行的可选固定会话键。 -- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及模板驱动的映射会话键设置 `sessionKey`（默认：`false`）。 -- `allowedSessionKeyPrefixes`：用于显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任意映射或预设使用模板化 `sessionKey` 时，它就变为必需项。 +- `defaultSessionKey`：用于没有显式 `sessionKey` 的 hook 智能体运行的可选固定会话键。 +- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及模板驱动的 mapping session key 设置 `sessionKey`（默认：`false`）。 +- `allowedSessionKeyPrefixes`：对显式 `sessionKey` 值（请求 + mapping）生效的可选前缀允许列表，例如 `["hook:"]`。当任一 mapping 或 preset 使用模板化 `sessionKey` 时，它就变为必填项。 - `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。 -- `model` 会覆盖此次 hook 运行的 LLM（如果设置了模型目录，则该模型必须被允许）。 +- `model` 会覆盖本次 hook 运行所用的 LLM（如果设置了模型目录，则该模型必须被允许）。 ### Gmail 集成 -- 内置 Gmail 预设使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 -- 如果你保留这种按消息路由方式，请设置 `hooks.allowRequestSessionKey: true`，并将 `hooks.allowedSessionKeyPrefixes` 限制为匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 -- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖该预设，而不是使用默认的模板化值。 +- 内置 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 +- 如果你保留这种按消息路由方式，请设置 `hooks.allowRequestSessionKey: true`，并将 `hooks.allowedSessionKeyPrefixes` 约束为匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 +- 如果你需要 `hooks.allowRequestSessionKey: false`，请使用静态 `sessionKey` 覆盖 preset，而不是使用默认的模板化值。 ```json5 { @@ -3281,8 +3266,8 @@ openclaw gateway --port 19001 } ``` -- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。 -- 不要在 Gateway 网关旁边单独运行另一个 `gog gmail watch serve`。 +- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。如需禁用，请设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1`。 +- 不要在 Gateway 网关旁边再单独运行一个 `gog gmail watch serve`。 --- @@ -3298,18 +3283,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 bind：canvas 路由与其他 Gateway 网关 HTTP 面一样，需要 Gateway 网关 auth（token/password/trusted-proxy）。 -- 节点 WebView 通常不会发送 auth header；在节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问公布节点作用域的 capability URL。 -- Capability URL 绑定到当前活动的节点 WS 会话，并且会很快过期。不使用基于 IP 的回退。 -- 会将 live-reload 客户端注入到所提供的 HTML 中。 -- 为空时会自动创建起始 `index.html`。 -- 也会在 `/__openclaw__/a2ui/` 提供 A2UI。 -- 更改需要重启 gateway。 -- 对于大型目录或出现 `EMFILE` 错误时，请禁用 live reload。 +- 非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP 表面一样，需要 Gateway 网关认证（token/password/trusted-proxy）。 +- Node WebView 通常不会发送认证 header；一旦某个节点完成配对并已连接，Gateway 网关就会为 canvas/A2UI 访问发布节点作用域的 capability URL。 +- Capability URL 绑定到活动的节点 WS 会话，并且很快过期。不使用基于 IP 的回退。 +- 会将实时重载客户端注入到所提供的 HTML 中。 +- 当为空时会自动创建初始 `index.html`。 +- 同时还会在 `/__openclaw__/a2ui/` 下提供 A2UI。 +- 变更需要重启 Gateway 网关。 +- 对于大型目录或出现 `EMFILE` 错误时，请禁用实时重载。 --- @@ -3329,7 +3314,7 @@ openclaw gateway --port 19001 - `minimal`（默认）：在 TXT 记录中省略 `cliPath` + `sshPort`。 - `full`：包含 `cliPath` + `sshPort`。 -- 主机名默认为 `openclaw`。使用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 +- 主机名默认为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 ### 广域（DNS-SD） @@ -3341,7 +3326,7 @@ openclaw gateway --port 19001 } ``` -会在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。若需跨网络设备发现，请配合 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS 使用。 +会在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。对于跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS 使用。 设置：`openclaw dns setup --apply`。 @@ -3367,13 +3352,13 @@ openclaw gateway --port 19001 ``` - 仅当进程环境中缺少该键时，才会应用内联环境变量。 -- `.env` 文件：当前工作目录 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 -- `shellEnv`：从你的登录 shell 配置文件导入缺失的预期键名。 -- 完整优先级请参见 [Environment](/zh-CN/help/environment)。 +- `.env` 文件：当前工作目录的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 +- `shellEnv`：从你的登录 shell profile 导入缺失的预期键名。 +- 完整优先级参见 [环境](/zh-CN/help/environment)。 ### 环境变量替换 -可在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量： +可在任何配置字符串中使用 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -3384,7 +3369,7 @@ openclaw gateway --port 19001 ``` - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失/空变量会在配置加载时报错。 +- 缺失/空变量会在配置加载时抛出错误。 - 使用 `$${VAR}` 可转义为字面量 `${VAR}`。 - 可与 `$include` 一起使用。 @@ -3392,11 +3377,11 @@ openclaw gateway --port 19001 ## Secrets -SecretRef 是增量支持的：明文值仍然可用。 +SecretRef 是增量特性：明文值仍然可用。 ### `SecretRef` -使用如下对象形态： +使用以下对象结构之一： ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -3408,21 +3393,21 @@ SecretRef 是增量支持的：明文值仍然可用。 - `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$` - `source: "file"` 的 id：绝对 JSON pointer（例如 `"/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) +- 规范矩阵：[SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface) - `secrets apply` 以受支持的 `openclaw.json` 凭证路径为目标。 -- `auth-profiles.json` 引用也包含在运行时解析和审计覆盖中。 +- `auth-profiles.json` 引用也包含在运行时解析和审计覆盖范围内。 -### Secret 提供商配置 +### Secret providers 配置 ```json5 { secrets: { providers: { - default: { source: "env" }, // 可选的显式 env 提供商 + default: { source: "env" }, // 可选的显式 env provider filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3444,19 +3429,19 @@ SecretRef 是增量支持的：明文值仍然可用。 } ``` -注意： +说明： -- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 -- `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin/stdout 使用协议负载。 -- 默认会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍校验解析后的目标路径。 -- 如果配置了 `trustedDirs`，则受信任目录检查会作用于解析后的目标路径。 -- `exec` 子进程环境默认最小化；请通过 `passEnv` 显式传入所需变量。 -- Secret 引用会在激活时解析到内存快照中，之后请求路径只读取该快照。 -- 激活期间会应用活动面过滤：已启用面上的未解析引用会导致启动/重载失败，而非活动面会被跳过并附带诊断信息。 +- `file` provider 支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须是 `"value"`）。 +- `exec` provider 要求使用绝对 `command` 路径，并通过 stdin/stdout 使用协议负载。 +- 默认会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可在验证解析后目标路径的同时，允许符号链接路径。 +- 如果配置了 `trustedDirs`，受信任目录检查会应用到解析后的目标路径。 +- 默认情况下，`exec` 子进程环境是最小化的；使用 `passEnv` 显式传递所需变量。 +- Secret 引用会在激活时解析为内存快照，之后请求路径只读取该快照。 +- 激活期间会应用活动表面过滤：已启用表面上的未解析引用会导致启动/重载失败，而非活动表面会被跳过并输出诊断信息。 --- -## Auth 存储 +## 认证存储 ```json5 { @@ -3474,11 +3459,11 @@ SecretRef 是增量支持的：明文值仍然可用。 } ``` -- 按智能体的配置文件存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 支持值级别引用（静态凭证模式下，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 -- OAuth 模式的配置文件（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 -- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会进行清理。 -- 旧版 OAuth 导入来自 `~/.openclaw/credentials/oauth.json`。 +- 按智能体 profile 存储在 `/auth-profiles.json`。 +- `auth-profiles.json` 支持值级引用（静态凭证模式下，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- OAuth 模式 profile（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 +- 静态运行时凭证来自内存中已解析的快照；发现旧版静态 `auth.json` 条目时会进行清理。 +- 旧版 OAuth 从 `~/.openclaw/credentials/oauth.json` 导入。 - 参见 [OAuth](/zh-CN/concepts/oauth)。 - Secrets 运行时行为以及 `audit/configure/apply` 工具：参见 [Secrets Management](/zh-CN/gateway/secrets)。 @@ -3502,20 +3487,20 @@ 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 提供商/配置文件轮换之前的固定延迟（毫秒）（默认：`0`）。 -- `rateLimitedProfileRotations`：遇到速率限制错误时，在切换到模型回退之前，同一提供商 auth-profile 的最大轮换次数（默认：`1`）。该 rate-limit 桶包括提供商样式文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 +- `billingBackoffHours`：当某个 profile 因真实的 + 计费/余额不足错误而失败时的基础退避时长（小时）（默认：`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 提供商/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` 之类的提供商风格文本。 --- @@ -3536,8 +3521,8 @@ SecretRef 是增量支持的：明文值仍然可用。 - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 - 设置 `logging.file` 可使用稳定路径。 -- 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 -- `maxFileBytes`：在抑制写入前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 +- 使用 `--verbose` 时，`consoleLevel` 会提升到 `debug`。 +- `maxFileBytes`：在抑制写入之前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 --- @@ -3574,20 +3559,20 @@ SecretRef 是增量支持的：明文值仍然可用。 } ``` -- `enabled`：instrumentation 输出的总开关（默认：`true`）。 -- `flags`：用于启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 之类的通配符）。 -- `stuckSessionWarnMs`：当会话保持在 processing 状态时，用于发出卡住会话警告的时长阈值（毫秒）。 -- `otel.enabled`：启用 OpenTelemetry 导出管道（默认：`false`）。 +- `enabled`：instrumentation 输出的主开关（默认：`true`）。 +- `flags`：用于启用定向日志输出的标志字符串数组（支持通配符，例如 `"telegram.*"` 或 `"*"`）。 +- `stuckSessionWarnMs`：当会话保持在 processing 状态时，发出卡住会话警告的年龄阈值（毫秒）。 +- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。 - `otel.endpoint`：用于 OTel 导出的 collector URL。 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 -- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据 header。 -- `otel.serviceName`：资源属性中的服务名称。 +- `otel.headers`：随 OTel 导出请求一起发送的额外 HTTP/gRPC 元数据 header。 +- `otel.serviceName`：资源属性使用的服务名称。 - `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。 -- `otel.sampleRate`：trace 采样率 `0`–`1`。 -- `otel.flushIntervalMs`：周期性 telemetry 刷新间隔（毫秒）。 +- `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.filePath`：缓存追踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存追踪输出中包含的内容（默认全部为 `true`）。 --- @@ -3609,12 +3594,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`：stable 渠道自动应用前的最小时延（小时）（默认：`6`；最大：`168`）。 -- `auto.stableJitterHours`：stable 渠道额外的发布时间扩散窗口（小时）（默认：`12`；最大：`168`）。 -- `auto.betaCheckIntervalHours`：beta 渠道检查运行频率（小时）（默认：`1`；最大：`24`）。 +- `auto.stableDelayHours`：stable 渠道自动应用前的最短延迟（小时）（默认：`6`；最大：`168`）。 +- `auto.stableJitterHours`：stable 渠道额外的发布扩散窗口（小时）（默认：`12`；最大：`168`）。 +- `auto.betaCheckIntervalHours`：beta 渠道检查运行的间隔（小时）（默认：`1`；最大：`24`）。 --- @@ -3648,21 +3633,21 @@ 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`：在拆分流式分块投影前允许的最大分块大小。 +- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 +- `backend`：默认 ACP 运行时后端 id（必须匹配某个已注册的 ACP 运行时插件）。 +- `defaultAgent`：当 spawn 未指定显式目标时，使用的回退 ACP 目标智能体 id。 +- `allowedAgents`：允许用于 ACP 运行时会话的智能体 ID 允许列表；为空表示不施加额外限制。 +- `maxConcurrentSessions`：同时处于活动状态的 ACP 会话最大数量。 +- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口（毫秒）。 +- `stream.maxChunkChars`：在拆分流式块投影之前允许的最大 chunk 大小。 - `stream.repeatSuppression`：按轮次抑制重复的状态/工具行（默认：`true`）。 -- `stream.deliveryMode`：`"live"` 表示增量流式传输；`"final_only"` 表示缓冲到轮次终止事件后再发送。 -- `stream.hiddenBoundarySeparator`：在隐藏工具事件之后、可见文本之前插入的分隔符（默认：`"paragraph"`）。 -- `stream.maxOutputChars`：每个 ACP 轮次投影的 assistant 输出最大字符数。 -- `stream.maxSessionUpdateChars`：投影 ACP 状态/更新行的最大字符数。 -- `stream.tagVisibility`：从 tag 名称到布尔可见性覆盖的记录，用于流式事件。 -- `runtime.ttlMinutes`：ACP 会话工作器在空闲后可被清理前的 TTL（分钟）。 -- `runtime.installCommand`：在引导 ACP 运行时环境时运行的可选安装命令。 +- `stream.deliveryMode`：`"live"` 递增流式输出；`"final_only"` 会缓冲直到轮次终止事件。 +- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前使用的分隔符（默认：`"paragraph"`）。 +- `stream.maxOutputChars`：每个 ACP 轮次可投影的 assistant 输出最大字符数。 +- `stream.maxSessionUpdateChars`：可投影 ACP 状态/更新行的最大字符数。 +- `stream.tagVisibility`：记录标签名到布尔可见性覆盖的映射，用于流式事件。 +- `runtime.ttlMinutes`：ACP 会话 worker 在可被清理前的空闲 TTL（分钟）。 +- `runtime.installCommand`：在引导 ACP 运行时环境时执行的可选安装命令。 --- @@ -3679,10 +3664,10 @@ SecretRef 是增量支持的：明文值仍然可用。 ``` - `cli.banner.taglineMode` 控制 banner 标语样式： - - `"random"`（默认）：轮换显示有趣/季节性标语。 - - `"default"`：固定中性标语（`All your chats, one OpenClaw.`）。 - - `"off"`：不显示标语文本（仍显示 banner 标题/版本）。 -- 若要隐藏整个 banner（而不仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 + - `"random"`（默认）：轮换的趣味/季节性标语。 + - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 + - `"off"`：不显示标语文本（仍会显示 banner 标题/版本）。 +- 如需隐藏整个 banner（而不仅仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- @@ -3704,15 +3689,15 @@ SecretRef 是增量支持的：明文值仍然可用。 --- -## Identity +## 身份 参见 [智能体默认值](#agent-defaults) 下 `agents.list` 的 identity 字段。 --- -## Bridge protocol（旧版节点，历史参考）（旧版、已移除） +## Bridge protocol（旧版节点，历史参考） -当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema（在移除前验证会失败；`openclaw doctor --fix` 可清除未知键）。 +当前版本已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可以清理未知键）。 @@ -3741,7 +3726,7 @@ SecretRef 是增量支持的：明文值仍然可用。 cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // 已弃用：用于已存储 notify:true 作业的回退 + webhook: "https://example.invalid/legacy", // 已弃用：供已存储 notify:true 作业使用的回退 webhook webhookToken: "replace-with-dedicated-token", // 可选：用于出站 webhook 认证的 bearer token sessionRetention: "24h", // 时长字符串或 false runLog: { @@ -3752,11 +3737,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；省略时不会发送 auth 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` @@ -3772,11 +3757,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` @@ -3794,11 +3779,11 @@ SecretRef 是增量支持的：明文值仍然可用。 } ``` -- `enabled`：启用 cron 作业失败告警（默认：`false`）。 -- `after`：连续失败多少次后触发告警（正整数，最小值：`1`）。 -- `cooldownMs`：同一作业重复告警之间的最小间隔（毫秒）（非负整数）。 -- `mode`：交付模式 —— `"announce"` 通过渠道消息发送；`"webhook"` POST 到已配置的 webhook。 -- `accountId`：用于限定告警交付范围的可选账号或渠道 id。 +- `enabled`：为 cron 作业启用失败警报（默认：`false`）。 +- `after`：在触发警报前允许的连续失败次数（正整数，最小值：`1`）。 +- `cooldownMs`：同一作业重复警报之间的最短间隔（毫秒）（非负整数）。 +- `mode`：投递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 向已配置的 webhook 发送 POST。 +- `accountId`：用于限定警报投递范围的可选账号或渠道 id。 ### `cron.failureDestination` @@ -3815,22 +3800,22 @@ SecretRef 是增量支持的：明文值仍然可用。 } ``` -- 所有作业共享的 cron 失败通知默认目标。 -- `mode`：`"announce"` 或 `"webhook"`；当存在足够目标数据时，默认是 `"announce"`。 -- `channel`：用于 announce 交付的渠道覆盖。`"last"` 会复用最后一次已知交付渠道。 -- `to`：显式的 announce 目标或 webhook URL。webhook 模式下必填。 -- `accountId`：可选的交付账号覆盖。 -- 按作业的 `delivery.failureDestination` 会覆盖此全局默认值。 -- 当既未设置全局失败目标，也未设置按作业失败目标时，已经通过 `announce` 交付的作业在失败时会回退到其主 announce 目标。 -- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的作业，除非该作业的主 `delivery.mode` 为 `"webhook"`。 +- 所有作业共用的 cron 失败通知默认目标。 +- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认值为 `"announce"`。 +- `channel`：announce 投递的渠道覆盖。`"last"` 会复用最近一次已知投递渠道。 +- `to`：显式 announce 目标或 webhook URL。webhook 模式下必填。 +- `accountId`：可选的投递账号覆盖。 +- 按作业的 `delivery.failureDestination` 会覆盖这个全局默认值。 +- 当全局和按作业失败目标都未设置时，那些已经通过 `announce` 投递的作业在失败时会回退到其主 announce 目标。 +- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的作业，除非该作业的主 `delivery.mode` 是 `"webhook"`。 -参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [background tasks](/zh-CN/automation/tasks) 跟踪。 +参见 [Cron 作业](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 --- ## 媒体模型模板变量 -在 `tools.media.models[].args` 中展开的模板占位符： +会在 `tools.media.models[].args` 中展开的模板占位符： | 变量 | 说明 | | ------------------ | ------------------------------------------------- | @@ -3841,13 +3826,13 @@ SecretRef 是增量支持的：明文值仍然可用。 | `{{To}}` | 目标标识符 | | `{{MessageSid}}` | 渠道消息 id | | `{{SessionId}}` | 当前会话 UUID | -| `{{IsNewSession}}` | 新会话创建时为 `"true"` | +| `{{IsNewSession}}` | 新建会话时为 `"true"` | | `{{MediaUrl}}` | 入站媒体伪 URL | | `{{MediaPath}}` | 本地媒体路径 | | `{{MediaType}}` | 媒体类型（image/audio/document/…） | -| `{{Transcript}}` | 音频 transcript | -| `{{Prompt}}` | 用于 CLI 条目的已解析媒体提示 | -| `{{MaxChars}}` | 用于 CLI 条目的已解析最大输出字符数 | +| `{{Transcript}}` | 音频转录 | +| `{{Prompt}}` | 为 CLI 条目解析出的媒体 prompt | +| `{{MaxChars}}` | 为 CLI 条目解析出的最大输出字符数 | | `{{ChatType}}` | `"direct"` 或 `"group"` | | `{{GroupSubject}}` | 群组主题（尽力而为） | | `{{GroupMembers}}` | 群组成员预览（尽力而为） | @@ -3874,13 +3859,13 @@ SecretRef 是增量支持的：明文值仍然可用。 **合并行为：** -- 单个文件：替换包含它的对象。 +- 单个文件：替换其所在的对象。 - 文件数组：按顺序深度合并（后者覆盖前者）。 -- 同级键：在 include 之后合并（覆盖已包含的值）。 -- 嵌套 include：最多 10 层。 -- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径/`../` 形式最终仍解析到该边界内时才允许。 -- 错误：对于缺失文件、解析错误和循环 include，会给出清晰的错误信息。 +- 同级键：会在 includes 之后合并（覆盖 include 中的值）。 +- 嵌套 includes：最多 10 层深。 +- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录内（即 `openclaw.json` 的 `dirname`）。只有在最终解析结果仍位于该边界内时，才允许绝对路径/`../` 形式。 +- 错误：对缺失文件、解析错误和循环 include 提供清晰的报错信息。 --- -_相关内容：[Configuration](/zh-CN/gateway/configuration) · [Configuration Examples](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_ +_相关内容：[配置](/zh-CN/gateway/configuration) · [配置示例](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_ diff --git a/docs/zh-CN/gateway/configuration.md b/docs/zh-CN/gateway/configuration.md index c947915ff..811bb3e11 100644 --- a/docs/zh-CN/gateway/configuration.md +++ b/docs/zh-CN/gateway/configuration.md @@ -2,32 +2,32 @@ read_when: - 首次设置 OpenClaw - 查找常见配置模式 - - 导航到特定配置章节 + - 跳转到特定配置章节 summary: 配置概览：常见任务、快速设置，以及完整参考的链接 title: 配置 x-i18n: - generated_at: "2026-04-22T21:30:52Z" + generated_at: "2026-04-22T22:25:42Z" model: gpt-5.4 provider: openai - source_hash: 36162008b66dcaaac6d51882f20d74aebd9b637bfddde00395cdfbd5721e3d20 + source_hash: 2296617a25a339048cb1df7b895fec35e96b0740851c89add907fc49307e08d1 source_path: gateway/configuration.md workflow: 15 --- # 配置 -OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 **JSON5** 配置。 +OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 **JSON5** 配置文件。 -如果该文件缺失，OpenClaw 会使用安全的默认值。添加配置的常见原因包括： +如果该文件不存在，OpenClaw 会使用安全的默认值。常见的添加配置原因包括： -- 连接渠道并控制谁可以给机器人发消息 +- 连接渠道，并控制谁可以向机器人发送消息 - 设置模型、工具、沙箱隔离或自动化（cron、hooks） - 调整会话、媒体、网络或 UI -有关每个可用字段，请参阅[完整参考](/zh-CN/gateway/configuration-reference)。 +请参阅[完整参考](/zh-CN/gateway/configuration-reference)以查看所有可用字段。 -**刚接触配置？** 从 `openclaw onboard` 开始进行交互式设置，或查看[配置示例](/zh-CN/gateway/configuration-examples)指南，获取可直接复制粘贴的完整配置。 +**刚接触配置？** 可以先从 `openclaw onboard` 开始进行交互式设置，或者查看[配置示例](/zh-CN/gateway/configuration-examples)指南，获取可直接复制粘贴的完整配置。 ## 最小配置 @@ -57,12 +57,12 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 - 打开 [http://127.0.0.1:18789](http://127.0.0.1:18789) 并使用 **配置** 标签页。 - Control UI 会根据实时配置 schema 渲染表单，其中包括字段 - `title` / `description` 文档元数据，以及在可用时的插件和渠道 schema， - 并提供 **原始 JSON** 编辑器作为兜底入口。对于下钻式 UI - 和其他工具，Gateway 网关 还会公开 `config.schema.lookup`，用于 - 获取单个路径范围内的 schema 节点及其直属子节点摘要。 + 打开 [http://127.0.0.1:18789](http://127.0.0.1:18789)，然后使用 **配置** 标签页。 + 控制 UI 会基于实时配置 schema 渲染表单，其中包括字段 + `title` / `description` 文档元数据，以及在可用时加载的插件和渠道 schema， + 同时还提供一个 **原始 JSON** 编辑器作为兜底入口。对于下钻式 + UI 和其他工具，Gateway 网关 还会暴露 `config.schema.lookup`， + 用于获取单个路径范围的 schema 节点及其直接子项摘要。 直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关 会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。 @@ -72,47 +72,56 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 - 每个渠道在 `channels.` 下都有自己的配置章节。设置步骤请参阅对应的专属渠道页面： + 每个渠道在 `channels.` 下都有自己的配置章节。设置步骤请参阅对应的专用渠道页面： - [WhatsApp](/zh-CN/channels/whatsapp) — `channels.whatsapp` - [Telegram](/zh-CN/channels/telegram) — `channels.telegram` @@ -143,7 +152,7 @@ JSON。 - 设置主模型和可选的回退模型： + 设置主模型以及可选的回退模型： ```json5 { @@ -162,11 +171,12 @@ JSON。 } ``` - - `agents.defaults.models` 定义模型目录，并作为 `/model` 的 allowlist。 + - `agents.defaults.models` 定义模型目录，并充当 `/model` 的 allowlist。 + - 使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加 allowlist 条目，而不会移除现有模型。若普通替换会删除条目，则除非你传入 `--replace`，否则会被拒绝。 - 模型引用使用 `provider/model` 格式（例如 `anthropic/claude-opus-4-6`）。 - - `agents.defaults.imageMaxDimensionPx` 控制 transcript/tool 图像缩小尺寸（默认值为 `1200`）；在大量截图的运行中，较低的值通常会减少视觉 token 使用量。 - - 在聊天中切换模型，请参阅[模型 CLI](/zh-CN/concepts/models)；有关凭证轮换和回退行为，请参阅[模型故障切换](/zh-CN/concepts/model-failover)。 - - 对于自定义/自托管提供商，请参阅参考中的[自定义提供商](/zh-CN/gateway/configuration-reference#custom-providers-and-base-urls)。 + - `agents.defaults.imageMaxDimensionPx` 控制 transcript / tool 图像缩放下采样（默认值为 `1200`）；较低的值通常会减少以截图为主的运行中的视觉 token 使用量。 + - 参见[模型 CLI](/zh-CN/concepts/models)，了解如何在聊天中切换模型；参见[模型故障切换](/zh-CN/concepts/model-failover)，了解凭证轮换和回退行为。 + - 对于自定义 / 自托管 provider，请参见参考中的[自定义 providers](/zh-CN/gateway/configuration-reference#custom-providers-and-base-urls)。 @@ -174,18 +184,18 @@ JSON。 私信访问通过每个渠道的 `dmPolicy` 进行控制： - `"pairing"`（默认）：未知发送者会收到一次性配对码以供批准 - - `"allowlist"`：只允许 `allowFrom` 中的发送者（或已配对的允许存储） - - `"open"`：允许所有入站私信（需要 `allowFrom: ["*"]`） + - `"allowlist"`：只有 `allowFrom`（或已配对的 allow 存储）中的发送者才允许访问 + - `"open"`：允许所有传入私信（要求 `allowFrom: ["*"]`） - `"disabled"`：忽略所有私信 - 对于群组，请使用 `groupPolicy` + `groupAllowFrom` 或渠道专用 allowlist。 + 对于群组，请使用 `groupPolicy` + `groupAllowFrom` 或渠道特定的 allowlist。 - 有关每个渠道的详细信息，请参阅[完整参考](/zh-CN/gateway/configuration-reference#dm-and-group-access)。 + 每个渠道的详细信息请参阅[完整参考](/zh-CN/gateway/configuration-reference#dm-and-group-access)。 - 群组消息默认 **需要提及**。可按智能体配置模式： + 群组消息默认**要求提及**。可按智能体配置模式： ```json5 { @@ -207,9 +217,9 @@ JSON。 } ``` - - **元数据提及**：原生 @ 提及（WhatsApp 点按提及、Telegram @bot 等） - - **文本模式**：`mentionPatterns` 中的安全正则表达式模式 - - 有关每个渠道的覆盖项和自聊模式，请参阅[完整参考](/zh-CN/gateway/configuration-reference#group-chat-mention-gating)。 + - **元数据提及**：原生 @ 提及（WhatsApp 点击提及、Telegram @bot 等） + - **文本模式**：`mentionPatterns` 中的安全正则模式 + - 每个渠道的覆盖项和 self-chat 模式请参阅[完整参考](/zh-CN/gateway/configuration-reference#group-chat-mention-gating)。 @@ -224,24 +234,24 @@ JSON。 skills: ["github", "weather"], }, list: [ - { id: "writer" }, // 继承 github、weather - { id: "docs", skills: ["docs-search"] }, // 替换默认值 - { id: "locked-down", skills: [] }, // 不使用任何 Skills + { id: "writer" }, // inherits github, weather + { id: "docs", skills: ["docs-search"] }, // replaces defaults + { id: "locked-down", skills: [] }, // no skills ], }, } ``` - - 省略 `agents.defaults.skills` 可使默认情况下的 Skills 不受限制。 - - 省略 `agents.list[].skills` 将继承默认值。 - - 设置 `agents.list[].skills: []` 表示不使用任何 Skills。 - - 请参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config)，以及 + - 省略 `agents.defaults.skills` 表示默认情况下 Skills 不受限制。 + - 省略 `agents.list[].skills` 表示继承默认值。 + - 设置 `agents.list[].skills: []` 表示不启用任何 Skills。 + - 参见 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config)，以及 [配置参考](/zh-CN/gateway/configuration-reference#agents-defaults-skills)。 - 控制 Gateway 网关 对看起来已陈旧的渠道执行重启的激进程度： + 控制 Gateway 网关 对看起来已停滞的渠道执行重启的激进程度： ```json5 { @@ -265,8 +275,8 @@ JSON。 - 设置 `gateway.channelHealthCheckMinutes: 0` 可全局禁用健康监控重启。 - `channelStaleEventThresholdMinutes` 应大于或等于检查间隔。 - - 使用 `channels..healthMonitor.enabled` 或 `channels..accounts..healthMonitor.enabled`，可仅为某个渠道或账户禁用自动重启，而不必禁用全局监控。 - - 运行调试请参阅[健康检查](/zh-CN/gateway/health)，所有字段请参阅[完整参考](/zh-CN/gateway/configuration-reference#gateway)。 + - 使用 `channels..healthMonitor.enabled` 或 `channels..accounts..healthMonitor.enabled` 可为单个渠道或账户禁用自动重启，而无需禁用全局监控。 + - 参见[健康检查](/zh-CN/gateway/health)了解运维调试内容，并查看[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。 @@ -292,9 +302,9 @@ JSON。 ``` - `dmScope`：`main`（共享）| `per-peer` | `per-channel-peer` | `per-account-channel-peer` - - `threadBindings`：线程绑定会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。 - - 有关作用域、身份关联和发送策略，请参阅[会话管理](/zh-CN/concepts/session)。 - - 所有字段请参阅[完整参考](/zh-CN/gateway/configuration-reference#session)。 + - `threadBindings`：thread-bound 会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。 + - 参见[会话管理](/zh-CN/concepts/session)了解作用域、身份关联和发送策略。 + - 参见[完整参考](/zh-CN/gateway/configuration-reference#session)了解所有字段。 @@ -314,14 +324,14 @@ JSON。 } ``` - 请先构建镜像：`scripts/sandbox-setup.sh` + 先构建镜像：`scripts/sandbox-setup.sh` 完整指南请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)，所有选项请参阅[完整参考](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox)。 - - 基于 relay 的推送在 `openclaw.json` 中配置。 + + relay 支持的推送在 `openclaw.json` 中配置。 在 Gateway 网关 配置中设置： @@ -341,43 +351,43 @@ JSON。 } ``` - 等效 CLI： + 对应的 CLI 命令： ```bash openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com ``` - 作用如下： + 这样做的作用： - - 让 Gateway 网关 通过外部 relay 发送 `push.test`、唤醒提示以及重连唤醒。 - - 使用由已配对 iOS 应用转发的、以注册为作用域的发送授权。Gateway 网关 不需要部署范围的 relay 令牌。 - - 将每个基于 relay 的注册绑定到 iOS 应用所配对的 Gateway 网关 身份，因此其他 Gateway 网关 无法复用已存储的注册信息。 - - 本地/手动 iOS 构建仍使用直接 APNs。基于 relay 的发送仅适用于通过 relay 注册的官方分发构建。 - - 必须与官方/TestFlight iOS 构建中内置的 relay 基础 URL 一致，这样注册和发送流量才能到达同一个 relay 部署。 + - 让 Gateway 网关 能够通过外部 relay 发送 `push.test`、唤醒提示和重连唤醒。 + - 使用由已配对 iOS 应用转发的、作用域限定到注册项的发送授权。Gateway 网关 不需要部署范围的 relay token。 + - 将每个 relay 支持的注册绑定到 iOS 应用所配对的 Gateway 网关 身份，因此另一个 Gateway 网关 无法复用已存储的注册信息。 + - 让本地 / 手动构建的 iOS 版本继续使用直连 APNs。relay 支持的发送仅适用于通过 relay 注册的官方分发构建。 + - 必须与官方 / TestFlight iOS 构建中固化的 relay 基础 URL 匹配，这样注册和发送流量才能到达同一个 relay 部署。 端到端流程： - 1. 安装一个官方/TestFlight iOS 构建，且其编译时使用了相同的 relay 基础 URL。 + 1. 安装一个使用相同 relay 基础 URL 编译的官方 / TestFlight iOS 构建。 2. 在 Gateway 网关 上配置 `gateway.push.apns.relay.baseUrl`。 - 3. 将 iOS 应用与 Gateway 网关 配对，并让节点会话和操作员会话都建立连接。 - 4. iOS 应用获取 Gateway 网关 身份，使用 App Attest 和应用回执向 relay 注册，然后将基于 relay 的 `push.apns.register` 载荷发布到已配对的 Gateway 网关。 - 5. Gateway 网关 存储 relay 句柄和发送授权，然后将它们用于 `push.test`、唤醒提示和重连唤醒。 + 3. 将 iOS 应用与 Gateway 网关 配对，并让节点和操作员会话都连接。 + 4. iOS 应用获取 Gateway 网关 身份，使用 App Attest 加上应用收据向 relay 注册，然后将 relay 支持的 `push.apns.register` 负载发布到已配对的 Gateway 网关。 + 5. Gateway 网关 存储 relay 句柄和发送授权，然后将其用于 `push.test`、唤醒提示和重连唤醒。 - 运行说明： + 运维说明： - - 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接应用，以便它发布一个绑定到该 Gateway 网关 的新 relay 注册。 + - 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接应用，以便它可以发布一个绑定到该 Gateway 网关 的新 relay 注册。 - 如果你发布了一个指向不同 relay 部署的新 iOS 构建，应用会刷新其缓存的 relay 注册，而不是复用旧的 relay 来源。 兼容性说明： - `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可作为临时环境变量覆盖项使用。 - - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍然是仅限 local loopback 的开发逃生口；不要在配置中持久保存 HTTP relay URL。 + - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍然是仅限 local loopback 的开发逃生口；不要在配置中持久化 HTTP relay URL。 - 完整端到端流程请参阅[iOS App](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)，relay 安全模型请参阅[认证与信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)。 + 端到端流程请参阅[iOS App](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)，relay 安全模型请参阅[身份验证与信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)。 - + ```json5 { agents: { @@ -393,8 +403,8 @@ JSON。 - `every`：时长字符串（`30m`、`2h`）。设置为 `0m` 可禁用。 - `target`：`last` | `none` | ``（例如 `discord`、`matrix`、`telegram` 或 `whatsapp`） - - `directPolicy`：用于私信风格 heartbeat 目标的 `allow`（默认）或 `block` - - 完整指南请参阅[Heartbeat](/zh-CN/gateway/heartbeat)。 + - `directPolicy`：对于私信风格的 heartbeat 目标，可设为 `allow`（默认）或 `block` + - 完整指南请参阅 [Heartbeat](/zh-CN/gateway/heartbeat)。 @@ -413,9 +423,9 @@ JSON。 } ``` - - `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认值为 `24h`；设置为 `false` 可禁用）。 + - `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设为 `false` 可禁用）。 - `runLog`：按大小和保留行数清理 `cron/runs/.jsonl`。 - - 功能概览和 CLI 示例请参阅[Cron 作业](/zh-CN/automation/cron-jobs)。 + - 功能概览和 CLI 示例请参阅[cron 作业](/zh-CN/automation/cron-jobs)。 @@ -444,20 +454,20 @@ JSON。 ``` 安全说明： - - 将所有 hook/webhook 载荷内容都视为不受信任输入。 - - 使用专用的 `hooks.token`；不要复用共享的 Gateway 网关 令牌。 - - Hook 认证仅支持请求头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串令牌会被拒绝。 - - `hooks.path` 不能为 `/`；请将 webhook 入口保留在专用子路径上，例如 `/hooks`。 - - 保持不安全内容绕过标志处于禁用状态（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`），除非是在进行严格限定范围的调试。 - - 如果你启用了 `hooks.allowRequestSessionKey`，也请设置 `hooks.allowedSessionKeyPrefixes`，以限制调用方可选择的会话键。 - - 对于由 hook 驱动的智能体，优先选择强大的现代模型层级和严格的工具策略（例如尽可能仅允许消息传递并启用沙箱隔离）。 + - 将所有 hook / webhook 负载内容都视为不受信任的输入。 + - 使用专用的 `hooks.token`；不要复用共享的 Gateway 网关 token。 + - Hook 身份验证仅支持 header（`Authorization: Bearer ...` 或 `x-openclaw-token`）；query string token 会被拒绝。 + - `hooks.path` 不能是 `/`；请将 webhook 入口保留在专用子路径下，例如 `/hooks`。 + - 保持不安全内容绕过标志关闭（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`），除非你是在进行严格限定范围的调试。 + - 如果你启用了 `hooks.allowRequestSessionKey`，也要设置 `hooks.allowedSessionKeyPrefixes`，以限制调用方可选的会话键前缀。 + - 对于由 hook 驱动的智能体，优先选择强力的现代模型层级和严格的工具策略（例如仅消息传递，加上尽可能启用沙箱隔离）。 所有映射选项和 Gmail 集成请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)。 - 运行多个隔离的智能体，并分别使用各自的工作区和会话： + 使用不同的 workspace 和会话运行多个相互隔离的智能体： ```json5 { @@ -474,7 +484,7 @@ JSON。 } ``` - 绑定规则和每个智能体的访问配置文件请参阅[多智能体](/zh-CN/concepts/multi-agent)和[完整参考](/zh-CN/gateway/configuration-reference#multi-agent-routing)。 + 绑定规则和每个智能体的访问配置请参阅[多智能体](/zh-CN/concepts/multi-agent)和[完整参考](/zh-CN/gateway/configuration-reference#multi-agent-routing)。 @@ -492,12 +502,12 @@ JSON。 } ``` - - **单个文件**：替换其所在的对象 - - **文件数组**：按顺序深度合并（后者优先） - - **同级键**：在 include 之后合并（覆盖被 include 的值） - - **嵌套 include**：支持，最多 10 层深 + - **单个文件**：替换所在的整个对象 + - **文件数组**：按顺序深度合并（后者覆盖前者） + - **同级键**：在 include 之后合并（覆盖已包含的值） + - **嵌套 include**：最多支持 10 层嵌套 - **相对路径**：相对于包含它的文件解析 - - **错误处理**：对缺失文件、解析错误和循环 include 提供清晰错误信息 + - **错误处理**：对缺失文件、解析错误和循环 include 提供明确错误 @@ -506,26 +516,26 @@ JSON。 Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改——对于大多数设置，无需手动重启。 -直接编辑文件在通过校验前会被视为不受信任。监视器会等待 -编辑器临时写入/重命名带来的抖动稳定下来，读取最终文件，并通过恢复 -最近一次已知正常配置来拒绝无效的外部编辑。由 OpenClaw 自身发起的 -配置写入在写入前也会经过相同的 schema 检查；像删除 `gateway.mode` -或将文件缩小超过一半这类破坏性覆盖会被拒绝，并保存为 `.rejected.*` -以供检查。 +直接编辑文件会被视为不受信任，直到通过校验。监视器会等待 +编辑器临时写入 / 重命名抖动结束，读取最终文件，并通过恢复 +“上次已知正常”配置来拒绝无效的外部编辑。由 OpenClaw 发起的 +配置写入在落盘前也会经过相同的 schema 闸门；破坏性的覆盖，例如 +删除 `gateway.mode` 或将文件缩小到原来一半以下的情况，会被拒绝 +并另存为 `.rejected.*` 以供检查。 如果你在日志中看到 `Config auto-restored from last-known-good` 或 `config reload restored last-known-good config`，请检查 `openclaw.json` -旁边对应的 `.clobbered.*` 文件，修复被拒绝的载荷，然后运行 +旁边对应的 `.clobbered.*` 文件，修复被拒绝的负载，然后运行 `openclaw config validate`。恢复检查清单请参阅[Gateway 网关 故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。 ### 重载模式 | 模式 | 行为 | | ---------------------- | --------------------------------------------------------------------------------------- | -| **`hybrid`**（默认） | 立即热应用安全更改。对于关键更改会自动重启。 | -| **`hot`** | 仅热应用安全更改。当需要重启时记录警告——由你自行处理。 | +| **`hybrid`**（默认） | 立即热应用安全更改。对关键更改会自动重启。 | +| **`hot`** | 仅热应用安全更改。当需要重启时会记录警告——由你自行处理。 | | **`restart`** | 对任何配置更改都重启 Gateway 网关，无论是否安全。 | -| **`off`** | 禁用文件监视。更改将在下次手动重启时生效。 | +| **`off`** | 禁用文件监视。更改会在下一次手动重启时生效。 | ```json5 { @@ -535,63 +545,63 @@ Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改—— } ``` -### 哪些可热应用，哪些需要重启 +### 哪些可以热应用，哪些需要重启 -大多数字段都可在不停机的情况下热应用。在 `hybrid` 模式下，需要重启的更改会自动处理。 +大多数字段都可以在不停机的情况下热应用。在 `hybrid` 模式下，需要重启的更改会自动处理。 | 类别 | 字段 | 需要重启？ | | ------------------- | ----------------------------------------------------------------- | --------------- | -| 渠道 | `channels.*`、`web`（WhatsApp）——所有内置和插件渠道 | 否 | +| 渠道 | `channels.*`, `web`（WhatsApp）——所有内置和插件渠道 | 否 | | 智能体与模型 | `agent`、`agents`、`models`、`routing` | 否 | | 自动化 | `hooks`、`cron`、`agent.heartbeat` | 否 | | 会话与消息 | `session`、`messages` | 否 | | 工具与媒体 | `tools`、`browser`、`skills`、`audio`、`talk` | 否 | -| UI 与杂项 | `ui`、`logging`、`identity`、`bindings` | 否 | +| UI 与其他 | `ui`、`logging`、`identity`、`bindings` | 否 | | Gateway 网关 服务器 | `gateway.*`（port、bind、auth、tailscale、TLS、HTTP） | **是** | | 基础设施 | `discovery`、`canvasHost`、`plugins` | **是** | -`gateway.reload` 和 `gateway.remote` 是例外——更改它们 **不会** 触发重启。 +`gateway.reload` 和 `gateway.remote` 是例外——更改它们**不会**触发重启。 ## 配置 RPC（程序化更新） -控制平面写入 RPC（`config.apply`、`config.patch`、`update.run`）会按 `deviceId+clientIp` 进行限流：**每 60 秒最多 3 个请求**。达到限制时，RPC 会返回 `UNAVAILABLE` 和 `retryAfterMs`。 +控制平面写入 RPC（`config.apply`、`config.patch`、`update.run`）会按每个 `deviceId+clientIp` 限速为**每 60 秒 3 次请求**。被限流时，RPC 会返回 `UNAVAILABLE` 并附带 `retryAfterMs`。 -安全/默认流程： +安全 / 默认流程： - `config.schema.lookup`：检查单个路径范围的配置子树，返回一个浅层 - schema 节点、匹配的提示元数据以及直属子节点摘要 -- `config.get`：获取当前快照和哈希 -- `config.patch`：推荐的部分更新路径 + schema 节点、匹配的提示元数据，以及直接子项摘要 +- `config.get`：获取当前快照 + 哈希 +- `config.patch`：首选的部分更新路径 - `config.apply`：仅用于完整配置替换 -- `update.run`：显式执行自更新 + 重启 +- `update.run`：显式自更新 + 重启 -当你不是要替换整个配置时，优先使用 `config.schema.lookup` +如果你不是要替换整个配置，优先使用 `config.schema.lookup` 然后再使用 `config.patch`。 - 校验并写入完整配置，然后一步完成 Gateway 网关 重启。 + 在一步内校验并写入完整配置，然后重启 Gateway 网关。 - `config.apply` 会替换**整个配置**。如需部分更新，请使用 `config.patch`；如需更新单个键，请使用 `openclaw config set`。 + `config.apply` 会替换**整个配置**。部分更新请使用 `config.patch`，单个键请使用 `openclaw config set`。 参数： - - `raw`（字符串）— 整个配置的 JSON5 载荷 - - `baseHash`（可选）— 来自 `config.get` 的配置哈希（配置已存在时为必需） + - `raw`（字符串）— 整个配置的 JSON5 负载 + - `baseHash`（可选）— 来自 `config.get` 的配置哈希（配置已存在时为必填） - `sessionKey`（可选）— 重启后唤醒 ping 使用的会话键 - - `note`（可选）— 用于重启哨兵的备注 - - `restartDelayMs`（可选）— 重启前延迟（默认值为 2000） + - `note`（可选）— 写入重启哨兵的说明 + - `restartDelayMs`（可选）— 重启前延迟（默认 2000） - 当已有重启处于待处理/进行中时，重启请求会被合并，并且两次重启周期之间会应用 30 秒冷却时间。 + 当某个重启已在等待中 / 进行中时，重启请求会被合并处理，并且两次重启周期之间会有 30 秒冷却时间。 ```bash - openclaw gateway call config.get --params '{}' # 获取 payload.hash + openclaw gateway call config.get --params '{}' # capture payload.hash openclaw gateway call config.apply --params '{ "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }", "baseHash": "", @@ -605,16 +615,16 @@ Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改—— 将部分更新合并到现有配置中（JSON merge patch 语义）： - 对象递归合并 - - `null` 删除键 - - 数组整体替换 + - `null` 删除一个键 + - 数组会整体替换 参数： - - `raw`（字符串）— 只包含待更改键的 JSON5 - - `baseHash`（必需）— 来自 `config.get` 的配置哈希 + - `raw`（字符串）— 只包含要更改键名的 JSON5 + - `baseHash`（必填）— 来自 `config.get` 的配置哈希 - `sessionKey`、`note`、`restartDelayMs` — 与 `config.apply` 相同 - 重启行为与 `config.apply` 一致：待处理重启会被合并，且两次重启周期之间有 30 秒冷却时间。 + 重启行为与 `config.apply` 一致：会合并待处理的重启请求，并在两次重启周期之间应用 30 秒冷却时间。 ```bash openclaw gateway call config.patch --params '{ @@ -628,12 +638,12 @@ Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改—— ## 环境变量 -OpenClaw 会从父进程读取环境变量，此外还会读取： +OpenClaw 会从父进程读取环境变量，另外还会读取： - 当前工作目录中的 `.env`（如果存在） - `~/.openclaw/.env`（全局回退） -这两个文件都不会覆盖现有环境变量。你也可以在配置中设置内联环境变量： +这两个文件都不会覆盖已有的环境变量。你也可以在配置中设置内联环境变量： ```json5 { @@ -645,7 +655,7 @@ OpenClaw 会从父进程读取环境变量，此外还会读取： ``` - 如果启用且预期键名未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键： + 如果已启用且预期键名未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键名： ```json5 { @@ -655,11 +665,11 @@ OpenClaw 会从父进程读取环境变量，此外还会读取： } ``` -等效环境变量：`OPENCLAW_LOAD_SHELL_ENV=1` +对应的环境变量：`OPENCLAW_LOAD_SHELL_ENV=1` - 可在任意配置字符串值中使用 `${VAR_NAME}` 引用环境变量： + 你可以在任意配置字符串值中通过 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -670,10 +680,10 @@ OpenClaw 会从父进程读取环境变量，此外还会读取： 规则： -- 仅匹配全大写名称：`[A-Z_][A-Z0-9_]*` -- 缺失/为空的变量会在加载时报错 -- 使用 `$${VAR}` 转义以输出字面值 -- 在 `$include` 文件中同样有效 +- 仅匹配大写名称：`[A-Z_][A-Z0-9_]*` +- 缺失 / 为空的变量会在加载时报错 +- 使用 `$${VAR}` 转义，以输出字面值 +- 在 `$include` 文件内同样可用 - 内联替换：`"${BASE}/v1"` → `"https://api.example.com/v1"` @@ -711,15 +721,15 @@ OpenClaw 会从父进程读取环境变量，此外还会读取： } ``` -有关 SecretRef 的详细信息（包括用于 `env` / `file` / `exec` 的 `secrets.providers`），请参阅[密钥管理](/zh-CN/gateway/secrets)。 -支持的凭证路径列在 [SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface) 中。 +SecretRef 的详细信息（包括用于 `env` / `file` / `exec` 的 `secrets.providers`）请参阅[Secrets Management](/zh-CN/gateway/secrets)。 +支持的凭证路径列于[SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface)。 -有关完整优先级和来源，请参阅[环境](/zh-CN/help/environment)。 +完整的优先级和来源请参阅[环境变量](/zh-CN/help/environment)。 ## 完整参考 -有关完整的逐字段参考，请参阅 **[配置参考](/zh-CN/gateway/configuration-reference)**。 +如需查看按字段逐项说明的完整参考，请参阅 **[配置参考](/zh-CN/gateway/configuration-reference)**。 ---