From ff8a323c886da4f398cdf692f8945e09f3de0e2f Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 25 Apr 2026 20:15:53 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/gateway/config-agents.md | 496 +++++++------- docs/zh-CN/gateway/configuration-reference.md | 640 +++++++++--------- docs/zh-CN/install/updating.md | 54 +- docs/zh-CN/nodes/talk.md | 54 +- 4 files changed, 622 insertions(+), 622 deletions(-) diff --git a/docs/zh-CN/gateway/config-agents.md b/docs/zh-CN/gateway/config-agents.md index 6a1939fa3..06c6b7176 100644 --- a/docs/zh-CN/gateway/config-agents.md +++ b/docs/zh-CN/gateway/config-agents.md @@ -1,22 +1,22 @@ --- read_when: - - 调整智能体默认设置（模型、思考、工作区、心跳、媒体、Skills） + - 调整智能体默认值（模型、思考、工作区、心跳、媒体、Skills） - 配置多智能体路由和绑定 - - 调整会话、消息传递和 talk 模式行为 -summary: 智能体默认设置、多智能体路由、会话、消息和 talk 配置 + - 调整会话、消息传递和通话模式行为 +summary: 智能体默认值、多智能体路由、会话、消息和通话配置 title: 配置 — 智能体 x-i18n: - generated_at: "2026-04-25T18:33:45Z" + generated_at: "2026-04-25T20:12:47Z" model: gpt-5.4 provider: openai - source_hash: d017648f522fe7be7cfca2691735132f60888c8c1ac6d84689ab327e9187e965 + source_hash: 0f072438d8445e494b296d2d48f31841292f55758270c2f8095df5c89a6ba013 source_path: gateway/config-agents.md workflow: 15 --- -`agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下的智能体作用域配置键。对于渠道、工具、Gateway 网关运行时以及其他顶层键，请参阅 [配置参考](/zh-CN/gateway/configuration-reference)。 +`agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下按智能体作用域划分的配置键。对于渠道、工具、Gateway 网关运行时以及其他顶层键，请参阅 [配置参考](/zh-CN/gateway/configuration-reference)。 -## 智能体默认设置 +## 智能体默认值 ### `agents.defaults.workspace` @@ -30,7 +30,7 @@ x-i18n: ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示中的 Runtime 行里。如果未设置，OpenClaw 会从工作区开始向上遍历并自动检测。 +可选的仓库根目录，会显示在系统提示中的 Runtime 行。如果未设置，OpenClaw 会从工作区开始向上遍历并自动检测。 ```json5 { @@ -40,7 +40,7 @@ x-i18n: ### `agents.defaults.skills` -为未设置 `agents.list[].skills` 的智能体提供可选的默认 Skills 允许列表。 +对于未设置 `agents.list[].skills` 的智能体，可选的默认 Skills 允许列表。 ```json5 { @@ -49,7 +49,7 @@ x-i18n: list: [ { id: "writer" }, // 继承 github、weather { id: "docs", skills: ["docs-search"] }, // 替换默认值 - { id: "locked-down", skills: [] }, // 无 Skills + { id: "locked-down", skills: [] }, // 没有 Skills ], }, } @@ -57,12 +57,12 @@ x-i18n: - 省略 `agents.defaults.skills`，则默认 Skills 不受限制。 - 省略 `agents.list[].skills`，则继承默认值。 -- 设置 `agents.list[].skills: []` 表示不启用任何 Skills。 +- 设置 `agents.list[].skills: []` 表示没有 Skills。 - 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。 ### `agents.defaults.skipBootstrap` -禁用自动创建工作区 bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 +禁用自动创建工作区引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 ```json5 { @@ -72,10 +72,10 @@ x-i18n: ### `agents.defaults.contextInjection` -控制何时将工作区 bootstrap 文件注入系统提示。默认值：`"always"`。 +控制何时将工作区引导文件注入到系统提示中。默认值：`"always"`。 -- `"continuation-skip"`：安全的续写轮次（在助手完成一次响应之后）会跳过重新注入工作区 bootstrap，从而减小提示大小。Heartbeat 运行和压缩后重试仍会重建上下文。 -- `"never"`：在每一轮都禁用工作区 bootstrap 和上下文文件注入。仅对完全自行管理提示生命周期的智能体使用此选项（例如自定义上下文引擎、自行构建上下文的原生运行时，或专门的不使用 bootstrap 的工作流）。Heartbeat 和压缩恢复轮次同样会跳过注入。 +- `"continuation-skip"`：安全的续接轮次（在助手完成一次响应之后）会跳过重新注入工作区引导内容，以减少提示大小。Heartbeat 运行和压缩后重试仍会重建上下文。 +- `"never"`：在每一轮都禁用工作区引导和上下文文件注入。仅将此选项用于那些完全自行管理其提示生命周期的智能体（自定义上下文引擎、会自行构建上下文的原生运行时，或专门的不使用引导的工作流）。Heartbeat 和压缩恢复轮次也会跳过注入。 ```json5 { @@ -85,7 +85,7 @@ x-i18n: ### `agents.defaults.bootstrapMaxChars` -每个工作区 bootstrap 文件在截断前允许的最大字符数。默认值：`12000`。 +每个工作区引导文件在被截断前允许的最大字符数。默认值：`12000`。 ```json5 { @@ -95,7 +95,7 @@ x-i18n: ### `agents.defaults.bootstrapTotalMaxChars` -所有工作区 bootstrap 文件合计可注入的最大字符数。默认值：`60000`。 +在所有工作区引导文件中注入的总字符数上限。默认值：`60000`。 ```json5 { @@ -105,12 +105,11 @@ x-i18n: ### `agents.defaults.bootstrapPromptTruncationWarning` -控制在 bootstrap 上下文被截断时，向智能体显示的警告文本。 -默认值：`"once"`。 +控制在引导上下文被截断时，对智能体可见的警告文本。默认值：`"once"`。 - `"off"`：绝不将警告文本注入系统提示。 -- `"once"`：每种唯一的截断签名只注入一次警告（推荐）。 -- `"always"`：只要存在截断，每次运行都注入警告。 +- `"once"`：对每个唯一的截断签名只注入一次警告（推荐）。 +- `"always"`：只要存在截断，就在每次运行时都注入警告。 ```json5 { @@ -120,29 +119,29 @@ x-i18n: ### 上下文预算归属映射 -OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统有意拆分，而不是全部通过一个通用开关控制。 +OpenClaw 有多个高容量的提示 / 上下文预算，这些预算是有意按子系统拆分的，而不是全部通过一个通用旋钮来控制。 - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`： - 常规工作区 bootstrap 注入。 + 常规工作区引导注入。 - `agents.defaults.startupContext.*`： 一次性的 `/new` 和 `/reset` 启动前导内容，包括最近的每日 `memory/*.md` 文件。 - `skills.limits.*`： 注入到系统提示中的精简 Skills 列表。 - `agents.defaults.contextLimits.*`： - 有界的运行时摘录和注入的运行时自有区块。 + 有界的运行时摘录和由运行时拥有的注入块。 - `memory.qmd.limits.*`： - 已索引 memory 搜索片段与注入大小控制。 + 已索引内存搜索片段和注入大小。 -只有当某个智能体需要不同的预算时，才使用对应的按智能体覆盖项： +只有在某个智能体需要不同预算时，才使用对应的按智能体覆盖项： - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -控制在纯 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。 +控制在裸 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。 ```json5 { @@ -163,7 +162,7 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统 #### `agents.defaults.contextLimits` -用于有界运行时上下文表面的共享默认值。 +有界运行时上下文面的共享默认值。 ```json5 { @@ -180,14 +179,14 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统 } ``` -- `memoryGetMaxChars`：`memory_get` 摘录在添加截断元数据和续读提示之前的默认上限。 +- `memoryGetMaxChars`：`memory_get` 摘录在添加截断元数据和续接提示之前的默认上限。 - `memoryGetDefaultLines`：当省略 `lines` 时，`memory_get` 的默认行窗口。 - `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。 -- `postCompactionMaxChars`：在压缩后刷新注入期间使用的 `AGENTS.md` 摘录上限。 +- `postCompactionMaxChars`：在压缩后刷新注入期间，`AGENTS.md` 摘录的上限。 #### `agents.list[].contextLimits` -用于共享 `contextLimits` 开关的按智能体覆盖。省略的字段会继承自 `agents.defaults.contextLimits`。 +共享 `contextLimits` 旋钮的按智能体覆盖项。未填写的字段会继承自 `agents.defaults.contextLimits`。 ```json5 { @@ -213,8 +212,7 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统 #### `skills.limits.maxSkillsPromptChars` -注入到系统提示中的精简 Skills 列表的全局上限。 -这不会影响按需读取 `SKILL.md` 文件。 +注入到系统提示中的精简 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。 ```json5 { @@ -228,7 +226,7 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统 #### `agents.list[].skillsLimits.maxSkillsPromptChars` -针对 Skills 提示预算的按智能体覆盖。 +按智能体覆盖 Skills 提示预算。 ```json5 { @@ -247,8 +245,7 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，转录/工具图像区块中图像最长边的最大像素尺寸。 -默认值：`1200`。 +在调用提供商之前，transcript / 工具图像块中图像最长边的最大像素尺寸。默认值：`1200`。 较低的值通常会减少视觉 token 使用量以及以截图为主的运行中的请求负载大小。 较高的值则会保留更多视觉细节。 @@ -261,7 +258,7 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统 ### `agents.defaults.userTimezone` -用于系统提示上下文的时区（不影响消息时间戳）。如果未设置，则回退到主机时区。 +系统提示上下文所用的时区（不影响消息时间戳）。回退到主机时区。 ```json5 { @@ -309,7 +306,7 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统 primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // 全局默认 provider 参数 + params: { cacheRetention: "long" }, // 全局默认提供商参数 embeddedHarness: { runtime: "pi", // pi | auto | 已注册的 harness id，例如 codex fallback: "pi", // pi | none @@ -330,51 +327,51 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统 - `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 字符串形式仅设置主模型。 - - 对象形式设置主模型以及按顺序的故障切换模型。 + - 对象形式设置主模型以及按顺序排列的故障转移模型。 - `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 作为 `image` 工具路径的视觉模型配置使用。 - - 当所选/默认模型无法接受图像输入时，也会用作回退路由。 + - 用作 `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，或 `openai/gpt-image-1.5` 用于支持透明背景的 OpenAI PNG/WebP 输出。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证（例如，`google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` / `openai/gpt-image-1.5` 使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 使用 `FAL_KEY`）。 - - 如果省略，`image_generate` 仍可推断出一个具备凭证支持的默认提供商。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的图像生成提供商。 + - 用于共享的图像生成功能，以及任何将来会生成图像的工具 / 插件表面。 + - 常见值：`google/gemini-3.1-flash-image-preview`（用于原生 Gemini 图像生成）、`fal/fal-ai/flux/dev`（用于 fal）、`openai/gpt-image-2`（用于 OpenAI Images），或 `openai/gpt-image-1.5`（用于支持透明背景的 OpenAI PNG/WebP 输出）。 + - 如果你直接选择某个 provider / model，也要配置匹配的提供商凭证，例如：`google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` / `openai/gpt-image-1.5` 使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 使用 `FAL_KEY`。 + - 如果省略，`image_generate` 仍然可以推断出一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的图像生成提供商。 - `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 用于共享的音乐生成功能和内置的 `music_generate` 工具。 - - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.6`。 - - 如果省略，`music_generate` 仍可推断出一个具备凭证支持的默认提供商。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的音乐生成提供商。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证/API 密钥。 + - 常见值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.6`。 + - 如果省略，`music_generate` 仍然可以推断出一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的音乐生成提供商。 + - 如果你直接选择某个 provider / model，也要配置匹配的提供商凭证 / API key。 - `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 用于共享的视频生成功能和内置的 `video_generate` 工具。 - - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 - - 如果省略，`video_generate` 仍可推断出一个具备凭证支持的默认提供商。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的视频生成提供商。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证/API 密钥。 + - 常见值：`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 顺序尝试其余已注册的视频生成提供商。 + - 如果你直接选择某个 provider / model，也要配置匹配的提供商凭证 / API key。 - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 - `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 用于 `pdf` 工具的模型路由。 - - 如果省略，PDF 工具会回退到 `imageModel`，然后再回退到已解析的会话/默认模型。 + - 如果省略，PDF 工具会回退到 `imageModel`，再回退到已解析的会话 / 默认模型。 - `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。 - `pdfMaxPages`：`pdf` 工具在提取回退模式下默认考虑的最大页数。 -- `verboseDefault`：智能体的默认详细级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 +- `verboseDefault`：智能体的默认详细输出级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 - `elevatedDefault`：智能体的默认增强输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 -- `model.primary`：格式为 `provider/model`（例如，`openai/gpt-5.5` 用于 API 密钥访问，或 `openai-codex/gpt-5.5` 用于 Codex OAuth）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 id 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此更推荐显式使用 `provider/model`）。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露一个陈旧的、已移除提供商默认值。 -- `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`extra_body`/`extraBody`）。 - - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非传入 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换操作。 - - 提供商作用域的配置/新手引导流程会将所选提供商模型合并到该映射中，并保留已配置的无关提供商。 - - 对于直接使用的 OpenAI Responses 模型，服务端压缩会自动启用。使用 `params.responsesServerCompaction: false` 可停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。 +- `model.primary`：格式为 `provider/model`（例如，使用 API key 访问时为 `openai/gpt-5.5`，使用 Codex OAuth 时为 `openai-codex/gpt-5.5`）。如果省略 provider，OpenClaw 会先尝试别名，然后尝试与该确切模型 id 唯一匹配的已配置 provider，最后才回退到已配置的默认 provider（这是已弃用的兼容行为，因此更推荐显式使用 `provider/model`）。如果该 provider 不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider / model，而不是暴露一个过期、已移除 provider 的默认值。 +- `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可以包含 `alias`（快捷别名）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`extra_body` / `extraBody`）。 + - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非传入 `--replace`，否则 `config set` 会拒绝可能移除现有允许列表条目的替换操作。 + - 按提供商作用域划分的配置 / 新手引导流程会将所选 provider 模型合并到这个映射中，并保留已配置的其他无关提供商。 + - 对于直接使用的 OpenAI Responses 模型，会自动启用服务端压缩。使用 `params.responsesServerCompaction: false` 可停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。 - `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)。 -- `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并到 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果它与生成的请求键冲突，则以额外请求体为准；非原生 completions 路由之后仍会剥离 OpenAI 专用的 `store`。 -- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。未指定 runtime 时默认使用 OpenClaw Pi。使用 `runtime: "pi"` 可强制使用内置 PI harness，使用 `runtime: "auto"` 可让已注册插件 harness 声明支持的模型，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动回退到 PI。像 `codex` 这样的显式插件运行时默认是失败即关闭，除非你在同一覆盖作用域中设置 `fallback: "pi"`。保持模型引用为规范格式 `provider/model`；通过运行时配置选择 Codex、Claude CLI、Gemini CLI 和其他执行后端，而不是使用旧式运行时提供商前缀。关于它与提供商/模型选择的区别，参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 -- 会变更这些字段的配置写入器（例如 `/models set`、`/models set-image` 和回退项添加/删除命令）会保存为规范对象形式，并尽可能保留现有回退列表。 -- `maxConcurrent`：跨会话的最大智能体并行运行数（每个会话仍然串行）。默认值：4。 +- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配的智能体 id）按键进一步覆盖。详情参见 [提示缓存](/zh-CN/reference/prompt-caching)。 +- `params.extra_body` / `params.extraBody`：高级透传 JSON，会合并到 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果它与生成的请求键冲突，则以额外请求体为准；非原生 completions 路由之后仍会剥离 OpenAI 专用的 `store`。 +- `embeddedHarness`：默认的低级内嵌智能体运行时策略。省略 `runtime` 时默认使用 OpenClaw Pi。使用 `runtime: "pi"` 可强制使用内置 PI harness，使用 `runtime: "auto"` 可让已注册的插件 harness 认领受支持的模型，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动回退到 PI。像 `codex` 这样的显式插件运行时默认是失败即关闭，除非你在同一覆盖作用域中设置 `fallback: "pi"`。模型引用请保持为规范形式 `provider/model`；通过运行时配置而不是旧版运行时 provider 前缀来选择 Codex、Claude CLI、Gemini CLI 以及其他执行后端。关于这与 provider / model 选择的区别，参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 +- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及 fallback add / remove 命令）会保存规范的对象形式，并尽可能保留现有的回退列表。 +- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍然串行）。默认值：4。 ### `agents.defaults.embeddedHarness` -`embeddedHarness` 控制哪个底层执行器运行嵌入式智能体轮次。 +`embeddedHarness` 控制哪个低级执行器运行内嵌智能体轮次。 大多数部署应保留默认的 OpenClaw Pi 运行时。 -当受信任的插件提供原生 harness 时可使用它，例如内置的 -Codex 应用服务器 harness。关于其心智模型，参见 +当受信任的插件提供原生 harness 时使用它，例如内置的 +Codex 应用服务器 harness。其概念模型请参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 ```json5 @@ -392,13 +389,13 @@ Codex 应用服务器 harness。关于其心智模型，参见 ``` - `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置的 Codex 插件注册为 `codex`。 -- `fallback`：`"pi"` 或 `"none"`。在 `runtime: "auto"` 中，省略时默认值为 `"pi"`，这样旧配置在没有插件 harness 接管运行时仍可继续使用 PI。在显式插件运行时模式下，例如 `runtime: "codex"`，省略时默认值为 `"none"`，这样缺少 harness 时会直接失败，而不是静默使用 PI。运行时覆盖不会从更宽作用域继承 fallback；如果你有意需要该兼容回退，请在显式 runtime 旁边一并设置 `fallback: "pi"`。所选插件 harness 的失败始终会直接暴露。 +- `fallback`：`"pi"` 或 `"none"`。在 `runtime: "auto"` 中，省略 `fallback` 时默认是 `"pi"`，这样旧配置在没有插件 harness 认领运行时仍可继续使用 PI。在显式插件运行时模式下，例如 `runtime: "codex"`，省略 `fallback` 时默认是 `"none"`，这样在缺少 harness 时会失败，而不是静默改用 PI。运行时覆盖项不会继承更广作用域中的 fallback；如果你确实希望保留这种兼容回退，需要与显式运行时一起设置 `fallback: "pi"`。所选插件 harness 的失败始终会直接显示。 - 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 会覆盖该进程的 fallback。 -- 对于仅使用 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `embeddedHarness.runtime: "codex"`。为了提高可读性，你也可以显式设置 `embeddedHarness.fallback: "none"`；这是显式插件运行时的默认值。 -- 在首次嵌入式运行后，harness 选择会按会话 id 固定。配置/环境变量变更会影响新的或已重置的会话，不会影响现有转录。带有转录历史但未记录固定值的旧会话会被视为固定到 PI。`/status` 会报告生效的运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。 -- 这仅控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。 +- 对于仅使用 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `embeddedHarness.runtime: "codex"`。你也可以显式设置 `embeddedHarness.fallback: "none"` 以增强可读性；这是显式插件运行时的默认值。 +- 在第一次内嵌运行后，harness 选择会按会话 id 固定。配置 / 环境变量的更改会影响新会话或已重置的会话，不会影响现有 transcript。具有 transcript 历史但没有记录固定值的旧会话会被视为固定到 PI。`/status` 会报告实际运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。 +- 这仅控制内嵌聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的 provider / model 设置。 -**内置别名简写**（仅在模型位于 `agents.defaults.models` 中时生效）： +**内置别名简写**（仅在模型位于 `agents.defaults.models` 中时适用）： | 别名 | 模型 | | ------------------- | ------------------------------------------ | @@ -411,15 +408,15 @@ Codex 应用服务器 harness。关于其心智模型，参见 | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -你配置的别名始终优先于默认值。 +你自己配置的别名始终优先于默认值。 -Z.AI GLM-4.x 模型会自动启用思考模式，除非你设置 `--thinking off` 或自行定义 `agents.defaults.models["zai/"].params.thinking`。 -Z.AI 模型默认启用 `tool_stream` 用于工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设置为 `false` 可禁用它。 -Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adaptive` 思考。 +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。 ### `agents.defaults.cliBackends` -用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，这可作为备份。 +用于纯文本回退运行（无工具调用）的可选 CLI 后端。在 API 提供商失败时可作为备用方案。 ```json5 { @@ -448,13 +445,13 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti } ``` -- CLI 后端以文本优先；工具始终禁用。 +- CLI 后端以文本为主；工具始终会被禁用。 - 设置了 `sessionArg` 时支持会话。 - 当 `imageArg` 接受文件路径时，支持图像透传。 ### `agents.defaults.systemPromptOverride` -用固定字符串替换整个由 OpenClaw 组装的系统提示。可设置在默认级别（`agents.defaults.systemPromptOverride`）或按智能体设置（`agents.list[].systemPromptOverride`）。按智能体设置的值优先；空值或仅包含空白字符的值会被忽略。适用于受控提示实验。 +用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体级别（`agents.list[].systemPromptOverride`）设置。按智能体设置的值优先；空值或仅包含空白字符的值会被忽略。适用于受控提示实验。 ```json5 { @@ -468,7 +465,7 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti ### `agents.defaults.promptOverlays` -按模型家族应用的、与提供商无关的提示叠加层。GPT-5 系列模型 id 会在不同提供商之间接收共享的行为契约；`personality` 仅控制友好的交互风格层。 +按模型家族应用、与提供商无关的提示叠加层。GPT-5 系列模型 id 会跨提供商接收共享的行为契约；`personality` 仅控制友好的交互风格层。 ```json5 { @@ -485,8 +482,8 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti ``` - `"friendly"`（默认）和 `"on"` 会启用友好的交互风格层。 -- `"off"` 仅禁用友好层；带标签的 GPT-5 行为契约仍会启用。 -- 当未设置此共享设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。 +- `"off"` 仅禁用友好层；带标签的 GPT-5 行为契约仍会保持启用。 +- 当这个共享设置未设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。 ### `agents.defaults.heartbeat` @@ -497,16 +494,16 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti agents: { defaults: { heartbeat: { - every: "30m", // 0m 表示禁用 + every: "30m", // 0m disables model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // 默认：true；false 会从系统提示中省略 Heartbeat 部分 - lightContext: false, // 默认：false；true 只保留工作区 bootstrap 文件中的 HEARTBEAT.md - isolatedSession: false, // 默认：false；true 会让每次 heartbeat 在全新会话中运行（无对话历史） + includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt + lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files + isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) session: "main", to: "+15555550123", - directPolicy: "allow", // allow（默认） | block - target: "none", // 默认：none | 可选值：last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow (default) | block + target: "none", // default: none | options: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -517,14 +514,14 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti } ``` -- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API 密钥认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 -- `includeSystemPromptSection`：为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。 -- `suppressToolErrorWarnings`：为 true 时，在 Heartbeat 运行期间抑制工具错误警告负载。 -- `timeoutSeconds`：Heartbeat 智能体轮次在被中止前允许的最长秒数。留空则使用 `agents.defaults.timeoutSeconds`。 -- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会阻止直接目标投递，并发出 `reason=dm-blocked`。 -- `lightContext`：为 true 时，Heartbeat 运行会使用轻量 bootstrap 上下文，并且只保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次 Heartbeat 都会在没有任何先前对话历史的全新会话中运行。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次 Heartbeat 的 token 成本从约 100K 降至约 2–5K token。 -- 按智能体设置：使用 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 Heartbeat。 +- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 +- `includeSystemPromptSection`：为 false 时，会省略系统提示中的 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入引导上下文。默认值：`true`。 +- `suppressToolErrorWarnings`：为 true 时，会在 Heartbeat 运行期间抑制工具错误警告负载。 +- `timeoutSeconds`：Heartbeat 智能体轮次在被中止前允许的最长秒数。若未设置，则使用 `agents.defaults.timeoutSeconds`。 +- `directPolicy`：直接 / 私信投递策略。`allow`（默认）允许直接目标投递。`block` 会阻止直接目标投递，并发出 `reason=dm-blocked`。 +- `lightContext`：为 true 时，Heartbeat 运行使用轻量级引导上下文，并且仅保留工作区引导文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：为 true 时，每次 Heartbeat 都会在一个全新的会话中运行，没有任何先前的对话历史。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次 Heartbeat 的 token 成本从约 100K 降低到约 2-5K token。 +- 按智能体设置：使用 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**只会由这些智能体**运行 Heartbeat。 - Heartbeat 会运行完整的智能体轮次——间隔越短，消耗的 token 越多。 ### `agents.defaults.compaction` @@ -535,16 +532,16 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // 已注册 compaction provider 插件的 id（可选） + provider: "my-provider", // id of a registered compaction provider plugin (optional) timeoutSeconds: 900, reserveTokensFloor: 24000, keepRecentTokens: 50000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用 + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom qualityGuard: { enabled: true, maxRetries: 1 }, - postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入 - model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于 compaction 的模型覆盖 - notifyUser: true, // compaction 开始和完成时发送简短通知（默认：false） + postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection + model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override + notifyUser: true, // send brief notices when compaction starts and completes (default: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -558,20 +555,20 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti ``` - `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`。 -- `keepRecentTokens`：Pi 截断点预算，用于原样保留最近的转录尾部。手动 `/compact` 在显式设置时会遵循此值；否则手动 compaction 是硬检查点。 -- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要前附加内置的不透明标识符保留指引。 +- `provider`：已注册压缩 provider 插件的 id。设置后，会调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置方式。设置 provider 会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `timeoutSeconds`：OpenClaw 中止单次压缩操作前允许的最长秒数。默认值：`900`。 +- `keepRecentTokens`：Pi 切点预算，用于逐字保留最近的 transcript 尾部。手动 `/compact` 在显式设置时会遵循此值；否则手动压缩就是一个硬检查点。 +- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要时预先附加内置的不透明标识符保留指导。 - `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 -- `qualityGuard`：针对 safeguard 摘要的格式错误输出重试检查。在 safeguard 模式下默认启用；设置 `enabled: false` 可跳过审计。 -- `postCompactionSections`：compaction 后要重新注入的可选 `AGENTS.md` H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。当未设置或显式设为这对默认值时，也会接受旧版 `Every Session`/`Safety` 标题作为兼容回退。 -- `model`：可选的 `provider/model-id` 覆盖项，仅用于 compaction 摘要。当主会话应继续使用某个模型，而 compaction 摘要应使用另一个模型时可使用此项；未设置时，compaction 使用会话的主模型。 -- `notifyUser`：为 `true` 时，会在 compaction 开始和完成时向用户发送简短通知（例如 “Compacting context...” 和 “Compaction complete”）。默认禁用，以保持 compaction 静默进行。 -- `memoryFlush`：在自动 compaction 之前执行的静默智能体轮次，用于存储持久记忆。当工作区为只读时会跳过。 +- `qualityGuard`：针对 safeguard 摘要中格式错误输出的重试检查。在 safeguard 模式下默认启用；设置 `enabled: false` 可跳过审计。 +- `postCompactionSections`：压缩后重新注入的可选 `AGENTS.md` H2/H3 章节名称。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。当未设置，或显式设置为该默认对时，也接受旧版的 `Every Session` / `Safety` 标题作为兼容回退。 +- `model`：仅用于压缩摘要的可选 `provider/model-id` 覆盖项。当主会话应保留某个模型，但压缩摘要应使用另一个模型时可使用此项；若未设置，压缩会使用会话的主模型。 +- `notifyUser`：为 `true` 时，会在压缩开始和完成时向用户发送简短通知（例如 “Compacting context...” 和 “Compaction complete”）。默认禁用，以保持压缩静默。 +- `memoryFlush`：自动压缩前的静默智能体轮次，用于存储持久记忆。当工作区为只读时会跳过。 ### `agents.defaults.contextPruning` -在发送给 LLM 之前，从内存上下文中修剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 +在发送到 LLM 之前，从内存中的上下文中修剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -579,7 +576,7 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // 时长（ms/s/m/h），默认单位：分钟 + ttl: "1h", // duration (ms/s/m/h), default unit: minutes keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -595,23 +592,23 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti -- `mode: "cache-ttl"` 会启用修剪流程。 -- `ttl` 控制下次允许再次执行修剪的时间间隔（自上次缓存触碰后算起）。 -- 如有需要，修剪会先对过大的工具结果执行软截断，然后再对更旧的工具结果执行硬清除。 +- `mode: "cache-ttl"` 会启用修剪过程。 +- `ttl` 控制多久之后才允许再次运行修剪（从上次缓存触碰之后开始计算）。 +- 修剪会先对过大的工具结果做软截断，必要时再对更旧的工具结果做硬清除。 **软截断**会保留开头和结尾，并在中间插入 `...`。 **硬清除**会用占位符替换整个工具结果。 -注意： +注意事项： -- 图像区块永远不会被截断/清除。 -- 各比例基于字符数（近似），而不是精确 token 数。 +- 图像块永远不会被截断 / 清除。 +- 比例基于字符数（近似），不是精确的 token 数。 - 如果 assistant 消息少于 `keepLastAssistants` 条，则会跳过修剪。 -有关行为细节，请参见 [会话修剪](/zh-CN/concepts/session-pruning)。 +行为详情请参见 [会话修剪](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -623,19 +620,19 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom（使用 minMs/maxMs） + humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) }, }, } ``` -- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。 -- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号的变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 +- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 +- 渠道覆盖项：`channels..blockStreamingCoalesce`（以及按账号的变体）。Signal / Slack / Discord / Google Chat 默认使用 `minChars: 1500`。 - `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500 ms。按智能体覆盖：`agents.list[].humanDelay`。 -有关行为和分块细节，请参见 [流式传输](/zh-CN/concepts/streaming)。 +行为和分块详情请参见 [流式传输](/zh-CN/concepts/streaming)。 -### 输入中指示器 +### 正在输入指示器 ```json5 { @@ -648,16 +645,16 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti } ``` -- 默认值：直接聊天/提及时使用 `instant`，未被提及的群聊中使用 `message`。 +- 默认值：直接聊天 / 提及时为 `instant`，未提及的群聊中为 `message`。 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 -参见 [输入中指示器](/zh-CN/concepts/typing-indicators)。 +参见 [正在输入指示器](/zh-CN/concepts/typing-indicators)。 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南请参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 +内嵌智能体的可选沙箱隔离。完整指南请参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -703,7 +700,7 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // 也支持 SecretRefs / 内联内容： + // SecretRefs / inline contents also supported: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -769,19 +766,19 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti - `command`：SSH 客户端命令（默认：`ssh`） - `workspaceRoot`：用于按作用域工作区的远程绝对根目录 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 -- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRefs，OpenClaw 会在运行时将其写入临时文件 -- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 +- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件 +- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略选项 **SSH 认证优先级：** - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前从当前激活的 secrets 运行时快照中解析 +- 由 SecretRef 支持的 `*Data` 值会在沙箱会话开始前，从当前激活的 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重新创建后，初始化一次远程工作区 +- 在创建或重新创建后，会先为远程工作区执行一次初始化 - 然后保持远程 SSH 工作区为规范副本 - 通过 SSH 路由 `exec`、文件工具和媒体路径 - 不会自动将远程更改同步回主机 @@ -789,7 +786,7 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti **工作区访问：** -- `none`：位于 `~/.openclaw/sandboxes` 下的按作用域沙箱工作区 +- `none`：位于 `~/.openclaw/sandboxes` 下按作用域划分的沙箱工作区 - `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent` - `rw`：智能体工作区以读写方式挂载到 `/workspace` @@ -812,10 +809,10 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // 可选 - gatewayEndpoint: "https://lab.example", // 可选 - policy: "strict", // 可选的 OpenShell 策略 id - providers: ["openai"], // 可选 + gateway: "lab", // optional + gatewayEndpoint: "https://lab.example", // optional + policy: "strict", // optional OpenShell policy id + providers: ["openai"], // optional autoProviders: true, timeoutSeconds: 120, }, @@ -827,29 +824,29 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti **OpenShell 模式：** -- `mirror`：在执行前从本地初始化远程，执行后同步回本地；本地工作区保持为规范副本 -- `remote`：在创建沙箱时仅初始化一次远程，之后保持远程工作区为规范副本 +- `mirror`：在执行前将本地内容同步到远程，执行后再同步回本地；本地工作区保持为规范副本 +- `remote`：在创建沙箱时仅向远程初始化一次，之后保持远程工作区为规范副本 -在 `remote` 模式下，在 OpenClaw 外部于主机本地进行的编辑，在初始化步骤之后不会自动同步到沙箱中。 -传输层是通过 SSH 连接到 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的镜像同步。 +在 `remote` 模式下，在 OpenClaw 外部于主机本地所做的编辑，在初始化步骤之后不会自动同步到沙箱中。 +传输通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的镜像同步。 -**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 +**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统以及 root 用户。 -**容器默认使用 `network: "none"`**——如果智能体需要出站访问，请设置为 `"bridge"`（或自定义桥接网络）。 -`"host"` 会被阻止。默认也会阻止 `"container:"`，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（破窗措施）。 +**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 +`"host"` 会被阻止。默认情况下，`"container:"` 也会被阻止，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急破窗选项）。 -**入站附件** 会暂存到当前活动工作区中的 `media/inbound/*`。 +**入站附件** 会暂存到当前工作区中的 `media/inbound/*`。 -**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的绑定会合并。 +**`docker.binds`** 用于挂载额外的主机目录；全局和按智能体设置的绑定会合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会注入到系统提示中。无需在 `openclaw.json` 中启用 `browser.enabled`。 -noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时效 token URL（而不是在共享 URL 中暴露密码）。 +**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行的 Chromium + CDP。noVNC URL 会注入到系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。 +noVNC 观察者访问默认使用 VNC 认证，并且 OpenClaw 会发出一个短时有效的 token URL（而不是在共享 URL 中暴露密码）。 - `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。 -- `network` 默认为 `openclaw-sandbox-browser`（专用桥接网络）。仅当你明确需要全局桥接连通性时，才设置为 `bridge`。 -- `cdpSourceRange` 可选地将 CDP 入站流量在容器边界限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 +- `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=` @@ -869,19 +866,20 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时效 - `--metrics-recording-only` - `--disable-extensions`（默认启用） - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` - 默认启用；如果 WebGL/3D 使用场景需要，可通过 - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 将其禁用。 - - 如果你的工作流依赖扩展，`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` - 会重新启用扩展。 + 默认启用；如果工作流中的 WebGL / 3D 使用需要它们，可通过 + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些标志。 + - 如果你的工作流依赖扩展，可通过 + `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 重新启用扩展。 - `--renderer-process-limit=2` 可通过 - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 更改；设置为 `0` 可使用 Chromium 的 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 可使用 Chromium 的 默认进程限制。 - - 以及当启用 `noSandbox` 时附加 `--no-sandbox`。 - - 这些默认值是容器镜像的基线；如需更改容器默认值，请使用带有自定义入口点的自定义浏览器镜像。 + - 另外，当启用 `noSandbox` 时会附加 `--no-sandbox`。 + - 这些默认值属于容器镜像基线；如需更改容器默认值，请使用自定义浏览器镜像和自定义 + entrypoint。 -浏览器沙箱隔离和 `sandbox.docker.binds` 仅适用于 Docker。 +浏览器沙箱隔离和 `sandbox.docker.binds` 仅支持 Docker。 构建镜像： @@ -890,7 +888,7 @@ scripts/sandbox-setup.sh # 主沙箱镜像 scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 ``` -### `agents.list`（按智能体覆盖） +### `agents.list`（按智能体覆盖项） ```json5 { @@ -902,13 +900,13 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks } - thinkingDefault: "high", // 按智能体覆盖思考级别 - reasoningDefault: "on", // 按智能体覆盖推理可见性 - fastModeDefault: false, // 按智能体覆盖快速模式 + model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } + thinkingDefault: "high", // per-agent thinking level override + reasoningDefault: "on", // per-agent reasoning visibility override + fastModeDefault: false, // per-agent fast mode override embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params - skills: ["docs-search"], // 设置时会替换 agents.defaults.skills + params: { cacheRetention: "none" }, // overrides matching defaults.models params by key + skills: ["docs-search"], // replaces agents.defaults.skills when set identity: { name: "Samantha", theme: "helpful sloth", @@ -940,20 +938,20 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 ``` - `id`：稳定的智能体 id（必填）。 -- `default`：设置了多个时，以第一个为准（会记录警告）。如果一个都未设置，则列表中的第一个条目为默认智能体。 -- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖两者（`[]` 会禁用全局回退）。仅覆盖 `primary` 的 cron 任务仍会继承默认回退，除非你设置 `fallbacks: []`。 -- `params`：按智能体的流参数，会合并到 `agents.defaults.models` 中选定模型条目之上。用它可为某个智能体设置特定覆盖，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。 -- `skills`：可选的按智能体 Skills 允许列表。如果省略，且设置了 `agents.defaults.skills`，则该智能体会继承它；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。 -- `thinkingDefault`：可选的按智能体默认思考级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置按消息或按会话覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。所选提供商/模型配置决定了哪些值有效；对于 Google Gemini，`adaptive` 会保留由提供商控制的动态思考（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。 -- `reasoningDefault`：可选的按智能体默认推理可见性（`on | off | stream`）。当未设置按消息或按会话的推理覆盖时生效。 -- `fastModeDefault`：可选的按智能体默认快速模式（`true | false`）。当未设置按消息或按会话的快速模式覆盖时生效。 -- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex" }` 可让某一个智能体只使用 Codex，而其他智能体继续使用 `auto` 模式下默认的 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` 调用（强制显式选择配置文件；默认：false）。 +- `default`：如果设置了多个，以第一个为准（会记录警告）。如果一个都没设置，则列表中的第一项是默认值。 +- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖两者（`[]` 会禁用全局 fallback）。仅覆盖 `primary` 的 cron 作业仍会继承默认 fallback，除非你设置 `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`。所选 provider / model 配置决定哪些值有效；对于 Google Gemini，`adaptive` 会保留由提供商控制的动态 thinking（在 Gemini 3 / 3.1 上省略 `thinkingLevel`，在 Gemini 2.5 上使用 `thinkingBudget: -1`）。 +- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当没有按消息或按会话的 reasoning 覆盖项时生效。 +- `fastModeDefault`：可选的按智能体 fast mode 默认值（`true | false`）。当没有按消息或按会话的 fast-mode 覆盖项时生效。 +- `embeddedHarness`：可选的按智能体低级 harness 策略覆盖项。使用 `{ runtime: "codex" }` 可让某一个智能体只使用 Codex，而其他智能体在 `auto` 模式下继续保留默认的 PI fallback。 +- `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` 调用（强制显式选择配置档；默认：false）。 --- @@ -978,11 +976,11 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 ### 绑定匹配字段 -- `type`（可选）：`route` 用于普通路由（缺失时默认是 route），`acp` 用于持久化 ACP 对话绑定。 +- `type`（可选）：正常路由使用 `route`（未填写 type 时默认是 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 }` **确定性匹配顺序：** @@ -990,17 +988,17 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId`（精确匹配，无 peer/guild/team） -5. `match.accountId: "*"`（整个渠道） +4. `match.accountId`（精确匹配，无 peer / guild / team） +5. `match.accountId: "*"`（整个渠道范围） 6. 默认智能体 -在每一层内，第一个匹配的 `bindings` 条目胜出。 +在每一层级内，第一个匹配到的 `bindings` 条目获胜。 -对于 `type: "acp"` 条目，OpenClaw 会按精确会话身份（`match.channel` + 账号 + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。 +对于 `type: "acp"` 条目，OpenClaw 会按精确对话身份（`match.channel` + 账号 + `match.peer.id`）进行解析，而不会使用上面的 route 绑定层级顺序。 -### 按智能体访问配置 +### 按智能体划分的访问配置档 - + ```json5 { @@ -1093,7 +1091,7 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 -有关优先级细节，请参见 [多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 +有关优先级详情，请参见 [多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1119,22 +1117,22 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 父线程超过此 token 数时跳过父线程分叉（0 表示禁用） + parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // 时长或 false - maxDiskBytes: "500mb", // 可选硬预算 - highWaterBytes: "400mb", // 可选清理目标 + resetArchiveRetention: "30d", // duration or false + maxDiskBytes: "500mb", // optional hard budget + highWaterBytes: "400mb", // optional cleanup target }, threadBindings: { enabled: true, - idleHours: 24, // 默认按小时计算的不活动自动取消聚焦时间（`0` 表示禁用） - maxAgeHours: 0, // 默认按小时计算的最大生命周期上限（`0` 表示禁用） + idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) + maxAgeHours: 0, // default hard max age in hours (`0` disables) }, - mainKey: "main", // 旧版字段（运行时始终使用 "main"） + mainKey: "main", // legacy (runtime always uses "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1146,35 +1144,35 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 -- **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在渠道上下文中，每个发送者都有独立的会话。 - - `global`：渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。 +- **`scope`**：群聊上下文中的基础会话分组策略。 + - `per-sender`（默认）：在一个渠道上下文内，每个发送者都有一个隔离的会话。 + - `global`：一个渠道上下文中的所有参与者共享同一个会话（仅在确实需要共享上下文时使用）。 - **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - - `per-peer`：按发送者 id 跨渠道隔离。 + - `per-peer`：按发送者 id 在跨渠道范围内隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 -- **`identityLinks`**：将规范 id 映射到带提供商前缀的 peer，以实现跨渠道会话共享。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。如果两者都已配置，则以先到期者为准。 -- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建分叉线程会话时允许的父会话最大 `totalTokens`（默认 `100000`）。 - - 如果父会话的 `totalTokens` 高于该值，OpenClaw 会启动一个全新的线程会话，而不是继承父转录历史。 - - 设置为 `0` 可禁用此保护，并始终允许从父会话分叉。 +- **`identityLinks`**：将规范 id 映射到带 provider 前缀的 peer，用于跨渠道共享会话。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在空闲 `idleMinutes` 后重置。当两者都已配置时，以先到期者为准。 +- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 仍可作为 `direct` 的别名使用。 +- **`parentForkMaxTokens`**：创建分叉线程会话时，允许的父会话 `totalTokens` 最大值（默认 `100000`）。 + - 如果父会话 `totalTokens` 高于此值，OpenClaw 会启动一个全新的线程会话，而不是继承父 transcript 历史。 + - 设为 `0` 可禁用此保护，并始终允许从父会话分叉。 - **`mainKey`**：旧版字段。运行时始终对主直接聊天桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体之间交互时，彼此回复的最大来回轮次数（整数，范围：`0`–`5`）。`0` 会禁用乒乓式链路。 -- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 作为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 规则优先。 +- **`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.` 转录归档的保留时长。默认值与 `pruneAfter` 相同；设置为 `false` 可禁用。 - - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的工件/会话。 + - `rotateBytes`：当 `sessions.json` 超过此大小时轮转（默认 `10mb`）。 + - `resetArchiveRetention`：`*.reset.` transcript 归档的保留期。默认与 `pruneAfter` 相同；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下只记录警告；在 `enforce` 模式下会优先删除最旧的工件 / 会话。 - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认按小时计算的不活动自动取消聚焦时间（`0` 表示禁用；提供商可覆盖） - - `maxAgeHours`：默认按小时计算的最大生命周期上限（`0` 表示禁用；提供商可覆盖） + - `idleHours`：默认不活动自动取消聚焦时间（单位：小时，`0` 禁用；提供商可覆盖） + - `maxAgeHours`：默认硬性最大存续时间（单位：小时，`0` 禁用；提供商可覆盖） @@ -1185,7 +1183,7 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 ```json5 { messages: { - responsePrefix: "🦞", // 或 "auto" + responsePrefix: "🦞", // or "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1200,7 +1198,7 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 }, }, inbound: { - debounceMs: 2000, // 0 表示禁用 + debounceMs: 2000, // 0 disables byChannel: { whatsapp: 5000, slack: 1500, @@ -1212,36 +1210,36 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 ### 响应前缀 -按渠道/账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 +按渠道 / 账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解析顺序（最具体者优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。 +解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。 **模板变量：** -| 变量 | 说明 | 示例 | -| ----------------- | ---------------- | --------------------------- | -| `{model}` | 短模型名 | `claude-opus-4-6` | -| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | -| `{provider}` | 提供商名称 | `anthropic` | -| `{thinkingLevel}` | 当前思考级别 | `high`、`low`、`off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| 变量 | 说明 | 示例 | +| ----------------- | -------------- | --------------------------- | +| `{model}` | 短模型名称 | `claude-opus-4-6` | +| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | +| `{provider}` | 提供商名称 | `anthropic` | +| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | +| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 ### 确认反应 -- 默认使用当前活跃智能体的 `identity.emoji`，否则为 `"👀"`。设置为 `""` 可禁用。 +- 默认使用当前活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 - 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 -- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。 +- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退值。 - 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 - `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上回复后移除确认反应。 -- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 - 在 Slack 和 Discord 上，未设置时，当确认反应处于激活状态，状态反应会保持启用。 - 在 Telegram 上，必须显式将其设置为 `true` 才会启用生命周期状态反应。 +- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期 Status 反应。 + 在 Slack 和 Discord 上，未设置时会在确认反应处于活动状态时保持 Status 反应启用。 + 在 Telegram 上，需显式将其设为 `true` 才会启用生命周期 Status 反应。 ### 入站防抖 -将来自同一发送者的快速纯文本消息合并为一次智能体轮次。媒体/附件会立即触发发送。控制命令会绕过防抖。 +将同一发送者快速连续发送的纯文本消息批量合并为单个智能体轮次。媒体 / 附件会立即刷新。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -1291,19 +1289,19 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 } ``` -- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示生效状态。 -- `summaryModel` 会覆盖自动摘要所使用的 `agents.defaults.model.primary`。 -- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认是 `false`（需显式启用）。 -- API 密钥会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 -- 内置语音提供商由插件负责。如果设置了 `plugins.allow`，请包含你要使用的每个 TTS 提供商插件，例如用于 Edge TTS 的 `microsoft`。旧版提供商 id `edge` 可作为 `microsoft` 的别名使用。 -- `providers.openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序是配置值，然后是 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。 -- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容的 TTS 服务器，并放宽模型/语音校验。 +- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好设置，`/tts status` 会显示实际状态。 +- `summaryModel` 会覆盖用于自动摘要的 `agents.defaults.model.primary`。 +- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需要显式启用）。 +- API key 会回退到 `ELEVENLABS_API_KEY` / `XI_API_KEY` 和 `OPENAI_API_KEY`。 +- 内置语音提供商由插件负责。如果设置了 `plugins.allow`，请包含你想使用的每个 TTS provider 插件，例如 Edge TTS 使用 `microsoft`。旧版 `edge` provider id 仍可作为 `microsoft` 的别名使用。 +- `providers.openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为：配置值，然后是 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。 +- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型 / 声音校验。 --- -## talk +## 通话 -Talk 模式的默认设置（macOS/iOS/Android）。 +通话模式的默认值（macOS / iOS / Android）。 ```json5 { @@ -1325,21 +1323,23 @@ Talk 模式的默认设置（macOS/iOS/Android）。 }, system: {}, }, + speechLocale: "ru-RU", silenceTimeoutMs: 1500, interruptOnSpeech: true, }, } ``` -- 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 -- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.`。 -- 语音 id 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 +- `talk.provider` 在配置了多个通话提供商时，必须匹配 `talk.providers` 中的某个键。 +- 旧版扁平通话键（`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 密钥时，才会回退到 `ELEVENLABS_API_KEY`。 -- `providers.*.voiceAliases` 允许 Talk 指令使用友好的名称。 -- `providers.mlx.modelId` 用于选择 macOS 本地 MLX 辅助程序所使用的 Hugging Face 仓库。如果省略，macOS 会使用 `mlx-community/Soprano-80M-bf16`。 -- macOS 上的 MLX 播放会通过内置的 `openclaw-mlx-tts` 辅助程序执行；如果该程序不存在，则会使用 `PATH` 上的可执行文件。开发时可用 `OPENCLAW_MLX_TTS_BIN` 覆盖辅助程序路径。 -- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多长时间再发送转录。未设置时会保留平台默认的停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- 仅当未配置通话 API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。 +- `providers.*.voiceAliases` 允许通话指令使用友好的名称。 +- `providers.mlx.modelId` 选择 macOS 本地 MLX helper 使用的 Hugging Face 仓库。如果省略，macOS 会使用 `mlx-community/Soprano-80M-bf16`。 +- macOS MLX 播放会通过内置的 `openclaw-mlx-tts` helper 运行；若不存在，则使用 `PATH` 上的可执行文件。开发时可通过 `OPENCLAW_MLX_TTS_BIN` 覆盖 helper 路径。 +- `speechLocale` 设置 iOS / macOS 通话语音识别使用的 BCP 47 locale id。留空则使用设备默认值。 +- `silenceTimeoutMs` 控制通话模式在用户停止说话后等待多久才发送 transcript。未设置时将保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index a836234bc..bcd9f2964 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -2,66 +2,68 @@ read_when: - 你需要精确到字段级别的配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向专用子系统参考文档的链接 +summary: Gateway 网关配置参考，涵盖 OpenClaw 核心键名、默认值，以及指向专用子系统参考文档的链接 title: 配置参考 x-i18n: - generated_at: "2026-04-25T19:34:27Z" + generated_at: "2026-04-25T20:12:48Z" model: gpt-5.4 provider: openai - source_hash: 3f9941fc10dd1929d62354fb604534e0526de8098de2484f8e3a571fd0c65082 + source_hash: f0b229369c1242e1bb58561abaa49021b1d3ce12ce1abc2d62eb362022650682 source_path: gateway/configuration-reference.md workflow: 15 --- -`~/.openclaw/openclaw.json` 的核心配置参考。若想查看面向任务的概览，请参见 [配置](/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 表面，校验配置文档基线哈希 +- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据 +- `config.schema.lookup` 会返回单个按路径限定范围的 schema 节点，供下钻工具使用 +- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面校验配置文档基线哈希 -专门的深入参考文档： +专用深入参考： -- [内存配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 -- [斜杠命令](/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 在省略时会使用安全的默认值。 --- ## 渠道 -每个渠道的配置键已移至专门页面 —— 请参见 -[配置 — 渠道](/zh-CN/gateway/config-channels) 了解 `channels.*`， -其中包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 以及其他 +每个渠道的配置键已移至独立页面 —— 请参见 +[配置 —— 渠道](/zh-CN/gateway/config-channels)，了解 `channels.*`， +其中包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他 内置渠道（认证、访问控制、多账号、提及门控）。 ## 智能体默认值、多智能体、会话和消息 -已移至专门页面 —— 请参见 -[配置 — 智能体](/zh-CN/gateway/config-agents) 了解： +已移至独立页面 —— 请参见 +[配置 —— 智能体](/zh-CN/gateway/config-agents)，了解： - `agents.defaults.*`（工作区、模型、思考、心跳、内存、媒体、Skills、沙箱） - `multiAgent.*`（多智能体路由与绑定） - `session.*`（会话生命周期、压缩、清理） - `messages.*`（消息投递、TTS、Markdown 渲染） - `talk.*`（Talk 模式） - - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录内容前保留平台默认的静默等待窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`） + - `talk.speechLocale`：iOS/macOS 上 Talk 语音识别的可选 BCP 47 locale id + - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录内容前保持平台默认的停顿窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`） ## 工具和自定义提供商 工具策略、实验性开关、由提供商支持的工具配置，以及自定义 -提供商 / base-URL 设置，已移至专门页面 —— 请参见 -[配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools)。 +提供商 / base-URL 设置已移至独立页面 —— 请参见 +[配置 —— 工具和自定义提供商](/zh-CN/gateway/config-tools)。 ## MCP -由 OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式 Pi 及其他运行时适配器使用。`openclaw mcp list`、 -`show`、`set` 和 `unset` 命令可管理此配置块，而无需在编辑配置期间连接到 +由 OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下， +嵌入式 Pi 和其他运行时适配器会使用这些定义。`openclaw mcp list`、 +`show`、`set` 和 `unset` 命令可管理此配置块，并且在编辑配置期间不会连接到 目标服务器。 ```json5 @@ -86,16 +88,15 @@ x-i18n: } ``` -- `mcp.servers`：供运行时使用的已命名 stdio 或远程 MCP 服务器定义， - 这些运行时会暴露已配置的 MCP 工具。 -- `mcp.sessionIdleTtlMs`：用于会话作用域内置 MCP 运行时的空闲 TTL。 - 一次性嵌入式运行会在运行结束时请求清理；该 TTL 是针对 +- `mcp.servers`：供暴露已配置 MCP 工具的运行时使用的、具名的 stdio 或远程 MCP 服务器定义。 +- `mcp.sessionIdleTtlMs`：面向会话作用域的内置 MCP 运行时的空闲 TTL。 + 单次嵌入式运行会请求在运行结束时清理；此 TTL 是针对 长生命周期会话和未来调用方的兜底机制。 -- `mcp.*` 下的更改会通过释放缓存的会话 MCP 运行时来热应用。 - 下一次工具发现/使用时会根据新配置重新创建它们，因此被移除的 - `mcp.servers` 条目会立即回收，而不是等待空闲 TTL 到期。 +- `mcp.*` 下的变更会通过释放缓存的会话 MCP 运行时来热应用。 + 下一次工具发现/使用会基于新配置重新创建它们，因此被移除的 + `mcp.servers` 条目会被立即回收，而不是等待空闲 TTL 到期。 -有关运行时行为，请参见 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 +运行时行为请参见 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 [CLI 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays)。 ## Skills @@ -113,7 +114,7 @@ x-i18n: }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 或纯文本字符串 env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -123,14 +124,13 @@ x-i18n: } ``` -- `allowBundled`：仅针对内置 skills 的可选允许列表（不影响托管/工作区 skills）。 -- `load.extraDirs`：额外的共享 skill 根目录（优先级最低）。 -- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器， - 然后才会回退到其他安装器类型。 -- `install.nodeManager`：用于 `metadata.openclaw.install` +- `allowBundled`：仅针对内置捆绑技能的可选允许列表（托管/工作区 Skills 不受影响）。 +- `load.extraDirs`：额外的共享技能根目录（优先级最低）。 +- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，然后才回退到其他安装器类型。 +- `install.nodeManager`：`metadata.openclaw.install` 规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false`：即使 skill 已内置/已安装，也会禁用该 skill。 -- `entries..apiKey`：为声明了主环境变量的 skills 提供的便捷字段（明文字符串或 SecretRef 对象）。 +- `entries..enabled: false`：即使某个技能已内置/已安装，也会禁用该技能。 +- `entries..apiKey`：为声明主环境变量的 Skills 提供的便捷字段（纯文本字符串或 SecretRef 对象）。 --- @@ -160,45 +160,45 @@ x-i18n: - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 - 设备发现支持原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 -- **配置更改需要重启 Gateway 网关。** +- **配置变更需要重启 Gateway 网关。** - `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 -- `plugins.entries..apiKey`：插件级 API key 便捷字段（插件支持时可用）。 +- `plugins.entries..apiKey`：插件级 API key 便捷字段（当插件支持时）。 - `plugins.entries..env`：插件作用域的环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子，以及受支持的 bundle 提供的钩子目录。 -- `plugins.entries..hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可从类型化钩子中读取原始会话内容，例如 `llm_input`、`llm_output` 和 `agent_end`。 -- `plugins.entries..subagent.allowModelOverride`：显式信任该插件，使其可为后台子智能体运行请求按次覆盖 `provider` 和 `model`。 -- `plugins.entries..subagent.allowedModels`：针对受信任的子智能体覆盖的规范 `provider/model` 目标可选允许列表。仅当你确实希望允许任意模型时，才使用 `"*"`。 -- `plugins.entries..config`：插件定义的配置对象（在可用时，由原生 OpenClaw 插件 schema 验证）。 -- 渠道插件的账号/运行时设置位于 `channels.` 下，应由所属插件的 manifest `channelConfigs` 元数据描述，而不是由中央 OpenClaw 选项注册表描述。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子以及受支持的 bundle 提供钩子目录。 +- `plugins.entries..hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可从 `llm_input`、`llm_output` 和 `agent_end` 等类型化钩子中读取原始对话内容。 +- `plugins.entries..subagent.allowModelOverride`：显式信任该插件，使其可为后台子智能体运行请求按次运行的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖可用的标准 `provider/model` 目标的可选允许列表。仅当你明确希望允许任意模型时才使用 `"*"`。 +- `plugins.entries..config`：插件定义的配置对象（当可用时，由原生 OpenClaw 插件 schema 验证）。 +- 渠道插件的账号/运行时设置位于 `channels.` 下，应由对应插件 manifest 的 `channelConfigs` 元数据描述，而不是由集中式 OpenClaw 选项注册表描述。 - `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` 环境变量。 + - `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`）。 + - `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 * * *"`）。 + - `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 * * *"`）。 - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 -- 完整的内存配置请参见 [内存配置参考](/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`：选择活动内存插件 id，或设为 `"none"` 以禁用内存插件。 -- `plugins.slots.contextEngine`：选择活动 context engine 插件 id；默认值为 `"legacy"`，除非你安装并选择了其他 engine。 -- `plugins.installs`：已弃用的兼容性回退项， - 用于旧版 CLI 管理的安装元数据。新的插件安装会改为写入受管理的 +- 已启用的 Claude bundle 插件还可从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为经过净化的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。 +- `plugins.slots.memory`：选择活动中的 memory 插件 id，或使用 `"none"` 禁用 memory 插件。 +- `plugins.slots.contextEngine`：选择活动中的 context engine 插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 +- `plugins.installs`：已弃用的兼容性回退项，用于旧版 + CLI 管理的安装元数据。新的插件安装会改为写入托管的 `plugins/installs.json` 状态账本。 - 旧版记录包括 `source`、`spec`、`sourcePath`、`installPath`、 `version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、 `shasum`、`resolvedAt`、`installedAt`。 - - 请将 `plugins.installs.*` 视为受管理状态；优先使用 CLI 命令，而不是 + - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是 手动编辑。 请参见 [插件](/zh-CN/tools/plugin)。 @@ -214,7 +214,7 @@ x-i18n: evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // 仅在受信任的私有网络访问场景中选择启用 + // dangerouslyAllowPrivateNetwork: true, // 仅在受信任的私有网络访问场景下选择启用 // allowPrivateNetwork: true, // 旧版别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -252,49 +252,49 @@ x-i18n: ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- `tabCleanup` 会在空闲超时后，或当某个 - 会话超过其上限时，回收被跟踪的主智能体标签页。将 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 设为 - 可禁用这些单独的清理模式。 -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用状态，因此浏览器导航默认保持严格。 -- 仅当你有意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/发现检查期间，也会受到相同的私有网络阻止。 -- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 -- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 添加显式例外。 -- 远程配置文件为仅附加模式（禁用 start/stop/reset）。 +- `tabCleanup` 会在空闲一段时间后，或当某个 + 会话超过其上限时，回收受跟踪的主智能体标签页。将 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 设为 + 可分别禁用这些单独的清理模式。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用状态，因此默认情况下浏览器导航会保持严格模式。 +- 仅当你明确信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 +- 在严格模式下，远程 CDP 配置档端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到相同的私有网络阻止规则约束。 +- `ssrfPolicy.allowPrivateNetwork` 仍然作为旧版别名受支持。 +- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 来设置显式例外。 +- 远程配置档为仅附加模式（禁用 start/stop/reset）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)；使用 WS(S) - 则适用于你的提供商直接提供 DevTools WebSocket URL 的场景。 -- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程以及 - `attachOnly` CDP 可达性检查和标签页打开请求。托管的 local loopback - 配置文件会保留本地 CDP 默认值。 + 当你希望 OpenClaw 发现 `/json/version` 时，使用 HTTP(S)；使用 WS(S) + 则适用于提供商直接给你 DevTools WebSocket URL 的情况。 +- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程及 + `attachOnly` CDP 可达性检查，以及标签页打开请求。受管的 local loopback + 配置档会保留本地 CDP 默认值。 - 如果某个外部管理的 CDP 服务可通过 local loopback 访问，请将该 - 配置文件的 `attachOnly: true` 设为 true；否则 OpenClaw 会把该 loopback 端口视为 - 本地托管浏览器配置文件，并可能报告本地端口归属错误。 -- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以在 - 所选主机上附加，或通过已连接的浏览器节点附加。 -- `existing-session` 配置文件可以设置 `userDataDir`，以定位特定的 - 基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。 -- `existing-session` 配置文件保留当前 Chrome MCP 路由限制： - 使用快照/ref 驱动的操作，而不是 CSS 选择器定位；单文件上传 - 钩子；不支持对话框超时覆盖；不支持 `wait --load networkidle`；也不支持 + 配置档的 `attachOnly: true` 设为 true；否则 OpenClaw 会将该 loopback 端口视为 + 本地受管浏览器配置档，并且可能报告本地端口占用错误。 +- `existing-session` 配置档使用 Chrome MCP 而不是 CDP，并且可以附加到 + 所选主机上，或通过已连接的浏览器节点进行附加。 +- `existing-session` 配置档可设置 `userDataDir`，以指定某个特定的 + 基于 Chromium 的浏览器配置档，例如 Brave 或 Edge。 +- `existing-session` 配置档保留当前 Chrome MCP 路由限制： + 使用基于 snapshot/ref 的操作，而不是基于 CSS 选择器的定位；仅支持单文件上传 + 钩子；不支持对话框超时覆盖；不支持 `wait --load networkidle`；并且不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；只有在远程 CDP 场景下 - 才需要显式设置 `cdpUrl`。 -- 本地托管配置文件可以设置 `executablePath`，以覆盖该配置文件的全局 - `browser.executablePath`。可用它让一个配置文件运行在 +- 本地受管的 `openclaw` 配置档会自动分配 `cdpPort` 和 `cdpUrl`；只有 + 在远程 CDP 场景下才应显式设置 `cdpUrl`。 +- 本地受管配置档可设置 `executablePath`，以覆盖该配置档的全局 + `browser.executablePath`。可用它让一个配置档运行在 Chrome 中，另一个运行在 Brave 中。 -- 本地托管配置文件在进程启动后，会使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP - 发现，并使用 `browser.localCdpReadyTimeoutMs` 检查 - 启动后 CDP websocket 就绪状态。在较慢的主机上，如果 Chrome 能成功启动， - 但就绪检查与启动过程竞争，请提高这些值。两个值都必须是 +- 本地受管配置档在进程启动后，会使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP + 设备发现，并使用 `browser.localCdpReadyTimeoutMs` 处理 + 启动后 CDP websocket 就绪检查。在主机较慢、Chrome 虽能成功启动但就绪检查与启动竞争时， + 可提高这些值。两个值都必须是 不超过 `120000` ms 的正整数；无效配置值会被拒绝。 -- 自动检测顺序：默认浏览器（若基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 自动检测顺序：默认浏览器（如果基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 - `browser.executablePath` 和 `browser.profiles..executablePath` 都 - 支持在 Chromium 启动前将 `~` 和 `~/...` 展开为你的操作系统主目录。 - `existing-session` 配置文件上的每配置文件 `userDataDir` 也支持波浪号展开。 -- Control 服务：仅限 loopback（端口派生自 `gateway.port`，默认值为 `18791`）。 -- `extraArgs` 会向本地 Chromium 启动追加额外的启动标志（例如 - `--disable-gpu`、窗口大小设置或调试标志）。 + 接受 `~` 和 `~/...`，会在启动 Chromium 前展开为你的操作系统主目录路径。 + `existing-session` 配置档中的逐配置档 `userDataDir` 也支持波浪号展开。 +- Control 服务：仅限 loopback（端口由 `gateway.port` 派生，默认值为 `18791`）。 +- `extraArgs` 会将额外启动标志追加到本地 Chromium 启动参数中（例如 + `--disable-gpu`、窗口尺寸设置或调试标志）。 --- @@ -306,14 +306,14 @@ x-i18n: seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, short text, image URL, or data URI + avatar: "CB", // emoji、短文本、图片 URL 或 data URI }, }, } ``` - `seamColor`：原生应用 UI 外框的强调色（Talk 模式气泡着色等）。 -- `assistant`：Control UI 身份覆盖。回退到当前活动智能体身份。 +- `assistant`：Control UI 身份覆盖。会回退到当前活动智能体身份。 --- @@ -328,8 +328,8 @@ x-i18n: auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth + // password: "your-password", // 或 OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // 适用于 mode=trusted-proxy；参见 /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -347,9 +347,9 @@ x-i18n: basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs - // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI - // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode + // allowExternalEmbedUrls: false, // 危险：允许绝对外部 http(s) 嵌入 URL + // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必填 + // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host 标头 origin 回退模式 // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -371,7 +371,7 @@ x-i18n: denyCommands: ["system.run"], }, tools: { - // 额外的 /tools/invoke HTTP 拒绝项 + // 额外的 /tools/invoke HTTP 拒绝列表 deny: ["browser"], // 从默认 HTTP 拒绝列表中移除工具 allow: ["gateway"], @@ -390,71 +390,70 @@ x-i18n: -- `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"`）以监听所有接口。 -- **认证**：默认必需。非 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"`：显式无认证模式。仅用于受信任的本地 loopback 环境；新手引导提示中不会提供此选项，这是有意为之。 -- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求代理来源为**非 loopback**；同主机 loopback 反向代理不满足 trusted-proxy 认证条件。 -- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份头可用于满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用这种 Tailscale 头认证；它们仍遵循 Gateway 网关常规的 HTTP 认证模式。这个无 token 流程假定 Gateway 网关主机是受信任的。当 `tailscale.mode = "serve"` 时，默认值为 `true`。 -- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域生效（共享密钥与设备 token 会分别跟踪）。被拦截的尝试会返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径上，对于相同 `{scope, clientIp}` 的失败尝试，会在写入失败记录前串行化处理。因此，同一客户端的并发错误尝试，可能会在第二个请求时触发限流，而不是两个请求都作为普通不匹配同时穿过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；如果你有意希望连 localhost 流量也受到限流（例如测试环境或严格代理部署），请设为 `false`。 -- 来自浏览器来源的 WS 认证尝试始终会启用限流，且关闭 loopback 豁免（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 -- 在 loopback 上，这些来自浏览器来源的锁定会按规范化后的 `Origin` - 值隔离，因此来自某一个 localhost origin 的重复失败，不会自动 +- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 +- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关将无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或设置 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以监听所有网络接口。 +- **认证**：默认必须启用。非 loopback 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` 的身份标头（参见 [可信代理认证](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求 **非 loopback** 代理来源；同主机的 loopback 反向代理不满足 trusted-proxy 认证要求。 +- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份标头可满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点 **不会** 使用该 Tailscale 标头认证；它们仍遵循 Gateway 网关常规的 HTTP 认证模式。此无 token 流程假定 Gateway 网关主机是受信任的。当 `tailscale.mode = "serve"` 时，默认值为 `true`。 +- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域应用（共享密钥和设备 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 连接的显式浏览器 origin 允许列表。当预期浏览器客户端来自非 loopback origin 时，这是必需的。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，启用 Host 头 origin 回退，适用于有意依赖 Host 头 origin 策略的部署。 +- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器源允许列表。预期来自非 loopback 源的浏览器客户端时必须设置。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 标头 origin 策略的部署启用 Host 标头 origin 回退。 - `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境中的 - 紧急放行覆盖项，允许对受信任私有网络 IP 使用明文 `ws://`； - 默认情况下，明文仍仅限 loopback。没有等价的 `openclaw.json` - 配置项，且浏览器私有网络配置，例如 - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`，也不会影响 Gateway 网关 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境变量中的紧急放行覆盖项， + 允许对受信任的私有网络 IP 使用明文 `ws://`；默认情况下，明文连接仍仅限 loopback。不存在对应的 `openclaw.json` + 配置项，并且浏览器私有网络配置（例如 + `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`）不会影响 Gateway 网关 WebSocket 客户端。 -- `gateway.remote.token` / `.password`：远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 -- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，供官方/TestFlight iOS 构建在将基于 relay 的注册发布到 Gateway 网关后使用。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。 -- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时，单位为毫秒。默认值为 `10000`。 -- 基于 relay 的注册会委派给特定的 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将按注册范围的发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用该已存储注册。 +- `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`。 +- `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.auth.*` 未设置时，本地 Gateway 网关调用路径才可以回退使用 `gateway.remote.*`。 -- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但未能解析，解析会以关闭方式失败（不会由远程回退进行掩盖）。 -- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP。只列出你控制的代理。对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理），loopback 条目仍然有效，但它们**不会**让 loopback 请求有资格使用 `gateway.auth.mode: "trusted-proxy"`。 -- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认为 `false`，以实现失败即关闭的行为。 -- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR/IP 允许列表，用于自动批准首次节点设备配对，且该配对未请求任何 scopes。未设置时为禁用状态。它不会自动批准 operator/browser/Control UI/WebChat 配对，也不会自动批准 role、scope、metadata 或公钥升级。 +- `gateway.channelMaxRestartsPerHour`：按滚动一小时统计，每个渠道/账号允许的健康监测重启上限。默认值：`10`。 +- `channels..healthMonitor.enabled`：渠道级选项，可在保持全局监测启用的同时，为该渠道选择退出健康监测重启。 +- `channels..accounts..healthMonitor.enabled`：多账号渠道的账号级覆盖项。设置后，其优先级高于渠道级覆盖。 +- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可将 `gateway.remote.*` 用作回退。 +- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但无法解析，则解析会以失败关闭方式处理（不会由远程回退掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端标头的反向代理 IP。仅列出你控制的代理。loopback 条目对于同主机代理/本地检测场景仍然有效（例如 Tailscale Serve 或本地反向代理），但它们 **不会** 让 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的条件。 +- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以保持失败关闭行为。 +- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR/IP 允许列表，用于在首次节点设备配对且未请求任何作用域时自动批准。未设置时为禁用状态。它不会自动批准 operator/browser/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。 - `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和允许列表评估之后，对已声明节点命令进行全局允许/拒绝塑形。 -- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外屏蔽的工具名（扩展默认拒绝列表）。 -- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名。 +- `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认拒绝列表）。 +- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。 ### OpenAI 兼容端点 -- Chat Completions：默认禁用。使用 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 +- 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` - 空允许列表会被视为未设置；如需禁用 URL 抓取，请使用 `gateway.http.endpoints.responses.files.allowUrl=false` - 和/或 `gateway.http.endpoints.responses.images.allowUrl=false`。 -- 可选的响应加固头： - - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS origin 设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） + 空允许列表会被视为未设置；请使用 `gateway.http.endpoints.responses.files.allowUrl=false` + 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 抓取。 +- 可选的响应加固标头： + - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 源设置；参见 [可信代理认证](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 -在同一主机上运行多个 Gateway 网关实例时，请使用唯一的端口和状态目录： +在同一主机上运行多个 Gateway 网关时，请使用唯一的端口和状态目录： ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -464,7 +463,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` @@ -482,10 +481,10 @@ openclaw gateway --port 19001 } ``` -- `enabled`：在 Gateway 网关监听器处启用 TLS 终止（HTTPS/WSS）（默认值：`false`）。 -- `autoGenerate`：在未配置显式文件时，自动生成本地自签名证书/密钥对；仅供本地/开发使用。 +- `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS/WSS）（默认值：`false`）。 +- `autoGenerate`：在未配置显式文件时自动生成本地自签名证书/密钥对；仅适用于本地/开发环境。 - `certPath`：TLS 证书文件的文件系统路径。 -- `keyPath`：TLS 私钥文件的文件系统路径；应限制权限。 +- `keyPath`：TLS 私钥文件的文件系统路径；应限制访问权限。 - `caPath`：可选的 CA bundle 路径，用于客户端验证或自定义信任链。 ### `gateway.reload` @@ -503,16 +502,16 @@ openclaw gateway --port 19001 ``` - `mode`：控制配置编辑在运行时如何应用。 - - `"off"`：忽略实时编辑；更改需要显式重启。 + - `"off"`：忽略实时编辑；变更需要显式重启。 - `"restart"`：配置变更时始终重启 Gateway 网关进程。 - - `"hot"`：在进程内应用更改，无需重启。 - - `"hybrid"`（默认）：先尝试热重载；如有需要则回退为重启。 -- `debounceMs`：应用配置更改前的防抖窗口，单位为 ms（非负整数）。 -- `deferralTimeoutMs`：可选的最大等待时间，单位为 ms，用于等待正在进行中的操作后再强制重启。省略或设为 `0` 表示无限等待，并定期记录“仍在等待中”的警告。 + - `"hot"`：在不重启的情况下于进程内应用变更。 + - `"hybrid"`（默认）：优先尝试热重载；如有需要则回退到重启。 +- `debounceMs`：应用配置变更前的防抖窗口，单位为毫秒（非负整数）。 +- `deferralTimeoutMs`：可选的最大等待时间，单位为毫秒，用于等待进行中的操作完成，然后再强制重启。省略或设为 `0` 表示无限期等待，并记录周期性的“仍在等待”警告。 --- -## 钩子 +## Hooks ```json5 { @@ -546,46 +545,46 @@ openclaw gateway --port 19001 ``` 认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 -拒绝使用查询字符串 hook token。 +查询字符串中的 hook token 会被拒绝。 -验证与安全说明： +验证和安全说明： -- `hooks.enabled=true` 需要非空的 `hooks.token`。 +- `hooks.enabled=true` 要求 `hooks.token` 为非空。 - `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关 token 会被拒绝。 - `hooks.path` 不能是 `/`；请使用专用子路径，例如 `/hooks`。 -- 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 -- 如果某个映射或 preset 使用模板化的 `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` 时，才接受请求负载中的 `sessionKey`（默认值：`false`）。 + - 仅当 `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` 内（绝对路径和路径穿越会被拒绝）。 -- `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。 +- `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 +- `match.source` 匹配通用路径的某个负载字段。 +- `{{messages[0].subject}}` 这样的模板会从负载中读取数据。 +- `transform` 可以指向返回 hook 动作的 JS/TS 模块。 + - `transform.module` 必须是相对路径，并且必须位于 `hooks.transformsDir` 之内（绝对路径和路径穿越会被拒绝）。 +- `agentId` 会路由到特定智能体；未知 id 会回退到默认值。 - `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。 - `defaultSessionKey`：可选的固定会话键，用于未显式提供 `sessionKey` 的 hook 智能体运行。 -- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及模板驱动的映射会话键设置 `sessionKey`（默认值：`false`）。 -- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任意映射或 preset 使用模板化 `sessionKey` 时，它就成为必需项。 +- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及模板驱动的 mapping 会话键设置 `sessionKey`（默认值：`false`）。 +- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + mapping）的可选前缀允许列表，例如 `["hook:"]`。当任何 mapping 或 preset 使用模板化 `sessionKey` 时，它会变为必填项。 - `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。 -- `model` 会为此次 hook 运行覆盖 LLM（如果设置了模型目录，则该模型必须被允许）。 +- `model` 会覆盖此次 hook 运行所用的 LLM（如果设置了模型目录，则该模型必须被允许）。 ### Gmail 集成 - 内置 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 -- 如果你保留这种按消息路由的方式，请设置 `hooks.allowRequestSessionKey: true`，并约束 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 -- 如果你需要 `hooks.allowRequestSessionKey: false`，请使用静态 `sessionKey` 覆盖该 preset，而不要使用模板化默认值。 +- 如果你保留这种按消息路由的方式，请设置 `hooks.allowRequestSessionKey: true`，并将 `hooks.allowedSessionKeyPrefixes` 限制为匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 +- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖该 preset，而不要使用其默认的模板化值。 ```json5 { @@ -608,8 +607,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`。 --- @@ -620,22 +619,22 @@ openclaw gateway --port 19001 canvasHost: { root: "~/.openclaw/workspace/canvas", liveReload: true, - // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 + // enabled: false, // 或 OPENCLAW_SKIP_CANVAS_HOST=1 }, } ``` -- 通过 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 网关认证（token/password/trusted-proxy）。 -- 节点 WebView 通常不会发送认证头；当节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问通告节点作用域能力 URL。 -- 能力 URL 绑定到当前活动节点 WS 会话，并且很快过期。不使用基于 IP 的回退。 -- 会向所提供的 HTML 中注入 live-reload 客户端。 -- 当目录为空时，会自动创建起始 `index.html`。 -- 也会在 `/__openclaw__/a2ui/` 提供 A2UI。 -- 更改需要重启 Gateway 网关。 +- 仅限本地：保持 `gateway.bind: "loopback"`（默认）。 +- 非 loopback bind：canvas 路由和其他 Gateway 网关 HTTP 表面一样，要求 Gateway 网关认证（token/password/trusted-proxy）。 +- 节点 WebView 通常不会发送认证标头；节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问通告节点作用域能力 URL。 +- 能力 URL 绑定到当前活动的节点 WS 会话，并且会很快过期。不使用基于 IP 的回退。 +- 会将 live-reload 客户端注入到所提供的 HTML 中。 +- 在内容为空时会自动创建初始 `index.html`。 +- 也会在 `/__openclaw__/a2ui/` 下提供 A2UI。 +- 变更需要重启 Gateway 网关。 - 对于大型目录或出现 `EMFILE` 错误时，请禁用 live reload。 --- @@ -654,8 +653,8 @@ openclaw gateway --port 19001 } ``` -- `minimal`（默认）：在 TXT 记录中省略 `cliPath` + `sshPort`。 -- `full`：包含 `cliPath` + `sshPort`。 +- `minimal`（默认）：在 TXT 记录中省略 `cliPath` 和 `sshPort`。 +- `full`：包含 `cliPath` 和 `sshPort`。 - 主机名默认为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 ### 广域网（DNS-SD） @@ -668,7 +667,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`。 @@ -693,9 +692,9 @@ openclaw gateway --port 19001 } ``` -- 仅当进程环境中缺少对应键时，才会应用内联环境变量。 -- `.env` 文件：当前工作目录 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 -- `shellEnv`：从你的登录 shell 配置文件导入缺失的预期键名。 +- 内联环境变量仅会在进程环境中缺少对应键时生效。 +- `.env` 文件：当前工作目录的 `.env` + `~/.openclaw/.env`（二者都不会覆盖现有变量）。 +- `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。 - 完整优先级请参见 [环境](/zh-CN/help/environment)。 ### 环境变量替换 @@ -710,20 +709,20 @@ openclaw gateway --port 19001 } ``` -- 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失/为空的变量会在配置加载时抛出错误。 -- 使用 `$${VAR}` 可转义为字面量 `${VAR}`。 -- 适用于 `$include`。 +- 仅匹配全大写名称：`[A-Z_][A-Z0-9_]*`。 +- 缺失/为空的变量会在加载配置时抛出错误。 +- 使用 `$${VAR}` 来转义并表示字面量 `${VAR}`。 +- 可与 `$include` 一起使用。 --- ## Secrets -SecretRef 是增量式的：明文值仍然可用。 +SecretRef 是增量式的：纯文本值仍然可用。 ### `SecretRef` -使用以下对象结构之一： +使用以下对象结构： ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -733,15 +732,15 @@ SecretRef 是增量式的：明文值仍然可用。 - `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$` - `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` 的 id：绝对 JSON 指针（例如 `"/providers/openai/apiKey"`） +- `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` 会被拒绝） ### 支持的凭证表面 -- 规范矩阵：[SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface) +- 标准矩阵：[SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface) - `secrets apply` 以受支持的 `openclaw.json` 凭证路径为目标。 -- `auth-profiles.json` 中的 refs 也包含在运行时解析和审计覆盖范围内。 +- `auth-profiles.json` 中的引用也包含在运行时解析和审计覆盖范围内。 ### Secret 提供商配置 @@ -749,7 +748,7 @@ SecretRef 是增量式的：明文值仍然可用。 { secrets: { providers: { - default: { source: "env" }, // optional explicit env provider + default: { source: "env" }, // 可选的显式 env 提供商 filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -773,14 +772,14 @@ SecretRef 是增量式的：明文值仍然可用。 说明： -- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须是 `"value"`）。 -- 当无法验证 Windows ACL 时，file 和 exec 提供商路径会以关闭方式失败。仅对无法验证但你信任的路径设置 `allowInsecurePath: true`。 -- `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin/stdout 上的协议负载工作。 -- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍会验证解析后的目标路径。 -- 如果配置了 `trustedDirs`，则受信任目录检查会应用到解析后的目标路径。 +- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 +- 当无法进行 Windows ACL 验证时，file 和 exec 提供商路径会以失败关闭方式处理。仅对无法验证但受信任的路径设置 `allowInsecurePath: true`。 +- `exec` 提供商要求 `command` 为绝对路径，并通过 stdin/stdout 使用协议负载。 +- 默认情况下，会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍会验证解析后的目标路径。 +- 如果配置了 `trustedDirs`，则受信任目录检查会应用于解析后的目标路径。 - `exec` 子进程环境默认最小化；请使用 `passEnv` 显式传递所需变量。 -- Secret refs 会在激活时解析为内存快照，之后请求路径只读取该快照。 -- 激活期间会应用活动表面过滤：已启用表面上无法解析的 refs 会导致启动/重载失败，而非活动表面会被跳过并附带诊断信息。 +- Secret 引用会在激活时解析为内存快照，然后请求路径只读取该快照。 +- 激活期间会应用活动表面过滤：启用表面上无法解析的引用会导致启动/重载失败，而未激活表面则会跳过并记录诊断信息。 --- @@ -802,13 +801,13 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- 每个智能体的 profile 存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 支持值级别 refs（静态凭证模式下，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 -- OAuth 模式的 profiles（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 -- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时，会将其清除。 +- 每个智能体的配置档存储在 `/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` 导入。 - 请参见 [OAuth](/zh-CN/concepts/oauth)。 -- Secrets 运行时行为，以及 `audit/configure/apply` 工具：请参见 [Secrets Management](/zh-CN/gateway/secrets)。 +- Secrets 运行时行为及 `audit/configure/apply` 工具：参见 [Secrets 管理](/zh-CN/gateway/secrets)。 ### `auth.cooldowns` @@ -830,20 +829,19 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `billingBackoffHours`：当某个 profile 因真实的 - 计费/余额不足错误而失败时的基础退避时长（小时）（默认值：`5`）。即使在 `401`/`403` 响应下，明确的计费文本 - 仍可能落入这里，但提供商特定的文本匹配器 - 仍然仅限于拥有它们的提供商（例如 OpenRouter 的 - `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或 +- `billingBackoffHours`：当某个配置档因真实的 + 计费/余额不足错误而失败时使用的基础退避时长（小时）（默认值：`5`）。即使在 `401`/`403` 响应上，显式计费文本 + 仍可能归入这里，但提供商特定的文本匹配器仍仅限于拥有它们的提供商（例如 OpenRouter + 的 `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或 organization/workspace 支出上限消息则仍归入 `rate_limit` 路径。 -- `billingBackoffHoursByProvider`：可选的按提供商覆盖计费退避小时数。 -- `billingMaxHours`：计费退避指数增长的上限小时数（默认值：`24`）。 -- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避分钟数（默认值：`10`）。 -- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的上限分钟数（默认值：`60`）。 -- `failureWindowHours`：用于退避计数器的滚动时间窗口（小时）（默认值：`24`）。 -- `overloadedProfileRotations`：同一提供商 auth-profile 因过载错误进行轮换的最大次数，超过后才切换到模型回退（默认值：`1`）。诸如 `ModelNotReadyException` 之类的提供商繁忙形态归入这里。 -- `overloadedBackoffMs`：在重试某个过载的提供商/profile 轮换前的固定延迟（默认值：`0`）。 -- `rateLimitedProfileRotations`：同一提供商 auth-profile 因速率限制错误进行轮换的最大次数，超过后才切换到模型回退（默认值：`1`）。该速率限制桶包括提供商特定文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 +- `billingBackoffHoursByProvider`：可选的按提供商划分的计费退避小时覆盖值。 +- `billingMaxHours`：计费退避指数增长的小时上限（默认值：`24`）。 +- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避时长（分钟）（默认值：`10`）。 +- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的分钟上限（默认值：`60`）。 +- `failureWindowHours`：用于退避计数器的滚动窗口时长（小时）（默认值：`24`）。 +- `overloadedProfileRotations`：对于 overloaded 错误，在切换到模型回退之前，同一提供商 auth-profile 允许的最大轮换次数（默认值：`1`）。如 `ModelNotReadyException` 之类的提供商繁忙形态会归入这里。 +- `overloadedBackoffMs`：在重试 overloaded 提供商/配置档轮换前的固定延迟（默认值：`0`）。 +- `rateLimitedProfileRotations`：对于 rate-limit 错误，在切换到模型回退之前，同一提供商 auth-profile 允许的最大轮换次数（默认值：`1`）。该 rate-limit 类别包括带有提供商特征的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 --- @@ -863,9 +861,9 @@ SecretRef 是增量式的：明文值仍然可用。 ``` - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 -- 设置 `logging.file` 可使用固定路径。 -- 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 -- `maxFileBytes`：在抑制写入前，日志文件允许的最大字节数（正整数；默认值：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 +- 设置 `logging.file` 可使用稳定路径。 +- 当使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 +- `maxFileBytes`：在抑制写入之前允许的最大日志文件大小（字节）（正整数；默认值：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 --- @@ -910,20 +908,20 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `enabled`：仪表化输出的总开关（默认值：`true`）。 -- `flags`：启用定向日志输出的标志字符串数组（支持通配符，例如 `"telegram.*"` 或 `"*"`）。 -- `stuckSessionWarnMs`：当会话持续处于处理状态时，发出卡住会话警告的年龄阈值，单位为 ms。 +- `enabled`：检测埋点输出的总开关（默认值：`true`）。 +- `flags`：用于启用定向日志输出的标志字符串数组（支持通配符，例如 `"telegram.*"` 或 `"*"`）。 +- `stuckSessionWarnMs`：当某个会话持续处于处理状态时，用于发出卡住会话警告的年龄阈值，单位为毫秒。 - `otel.enabled`：启用 OpenTelemetry 导出流水线（默认值：`false`）。 - `otel.endpoint`：用于 OTel 导出的 collector URL。 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 -- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据头。 +- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据标头。 - `otel.serviceName`：资源属性的服务名称。 -- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或日志导出。 -- `otel.sampleRate`：trace 采样率，范围 `0`–`1`。 -- `otel.flushIntervalMs`：定期刷新遥测数据的间隔，单位为 ms。 +- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。 +- `otel.sampleRate`：`0`–`1` 的 trace 采样率。 +- `otel.flushIntervalMs`：定期刷新遥测数据的时间间隔，单位为毫秒。 - `otel.captureContent`：为 OTEL span 属性选择启用原始内容捕获。默认关闭。布尔值 `true` 会捕获非 system 消息/工具内容；对象形式则允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。 -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：环境变量开关，用于启用最新的实验性 GenAI span provider 属性。默认情况下，span 会保留旧版 `gen_ai.system` 属性以保持兼容；GenAI metrics 使用有界语义属性。 -- `OPENCLAW_OTEL_PRELOADED=1`：环境变量开关，用于那些已经注册全局 OpenTelemetry SDK 的主机。此时 OpenClaw 会跳过插件拥有的 SDK 启动/关闭，同时保留诊断监听器处于活动状态。 +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：用于启用最新实验性 GenAI span provider 属性的环境变量开关。默认情况下，span 会保留旧版 `gen_ai.system` 属性以保持兼容性；GenAI metrics 使用有界语义属性。 +- `OPENCLAW_OTEL_PRELOADED=1`：适用于已注册全局 OpenTelemetry SDK 的主机的环境变量开关。此时 OpenClaw 会跳过插件自有 SDK 的启动/关闭流程，同时保持诊断监听器处于活动状态。 - `cacheTrace.enabled`：为嵌入式运行记录缓存跟踪快照（默认值：`false`）。 - `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认值：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 - `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含哪些内容（默认均为 `true`）。 @@ -948,12 +946,12 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `channel`：用于 npm/git 安装的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。 +- `channel`：npm/git 安装所使用的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。 - `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认值：`true`）。 -- `auto.enabled`：为包安装启用后台自动更新（默认值：`false`）。 -- `auto.stableDelayHours`：稳定渠道自动应用前的最小延迟小时数（默认值：`6`；最大值：`168`）。 -- `auto.stableJitterHours`：稳定渠道发布扩散窗口的额外小时数（默认值：`12`；最大值：`168`）。 -- `auto.betaCheckIntervalHours`：beta 渠道检查运行的频率（小时）（默认值：`1`；最大值：`24`）。 +- `auto.enabled`：为软件包安装启用后台自动更新（默认值：`false`）。 +- `auto.stableDelayHours`：稳定渠道自动应用前的最小延迟（小时）（默认值：`6`；最大值：`168`）。 +- `auto.stableJitterHours`：稳定渠道额外的发布分散窗口（小时）（默认值：`12`；最大值：`168`）。 +- `auto.betaCheckIntervalHours`：beta 渠道执行检查的频率（小时）（默认值：`1`；最大值：`24`）。 --- @@ -986,22 +984,22 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `enabled`：全局 ACP 功能开关（默认值：`false`）。 -- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认值：`true`）。设为 `false` 可保留 ACP 命令可用，但阻止执行。 +- `enabled`：全局 ACP 功能门控（默认值：`false`）。 +- `dispatch.enabled`：ACP 会话轮次分发的独立门控（默认值：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 - `backend`：默认 ACP 运行时后端 id（必须匹配已注册的 ACP 运行时插件）。 -- `defaultAgent`：当派生运行未指定显式目标时，使用的回退 ACP 目标智能体 id。 -- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；空值表示没有额外限制。 -- `maxConcurrentSessions`：同时处于活动状态的 ACP 会话最大数量。 -- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口，单位为 ms。 -- `stream.maxChunkChars`：流式块投影在拆分前的最大块大小。 -- `stream.repeatSuppression`：每轮抑制重复的状态/工具行（默认值：`true`）。 -- `stream.deliveryMode`：`"live"` 表示增量流式传输；`"final_only"` 表示缓冲到轮次终止事件后再输出。 -- `stream.hiddenBoundarySeparator`：在隐藏工具事件之后、可见文本之前使用的分隔符（默认值：`"paragraph"`）。 -- `stream.maxOutputChars`：每个 ACP 轮次投影的 assistant 输出最大字符数。 -- `stream.maxSessionUpdateChars`：投影的 ACP 状态/更新行最大字符数。 -- `stream.tagVisibility`：一个记录，保存 tag 名称到布尔可见性覆盖值的映射，用于流式事件。 -- `runtime.ttlMinutes`：ACP 会话 worker 在可被清理前的空闲 TTL，单位为分钟。 -- `runtime.installCommand`：在引导 ACP 运行时环境时运行的可选安装命令。 +- `defaultAgent`：当生成的新实例未指定显式目标时，使用的回退 ACP 目标智能体 id。 +- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；空值表示不做额外限制。 +- `maxConcurrentSessions`：并发活动 ACP 会话的最大数量。 +- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口，单位为毫秒。 +- `stream.maxChunkChars`：在拆分流式分块投影前允许的最大块大小。 +- `stream.repeatSuppression`：按轮次抑制重复的状态/工具行（默认值：`true`）。 +- `stream.deliveryMode`：`"live"` 表示增量流式传输；`"final_only"` 表示缓冲直到轮次终态事件。 +- `stream.hiddenBoundarySeparator`：隐藏工具事件后、可见文本前的分隔符（默认值：`"paragraph"`）。 +- `stream.maxOutputChars`：每个 ACP 轮次投影的最大助手输出字符数。 +- `stream.maxSessionUpdateChars`：投影的 ACP 状态/更新行的最大字符数。 +- `stream.tagVisibility`：记录 tag 名称到布尔可见性覆盖值的映射，用于流式事件。 +- `runtime.ttlMinutes`：ACP 会话工作进程在符合清理条件前的空闲 TTL，单位为分钟。 +- `runtime.installCommand`：在引导 ACP 运行时环境时执行的可选安装命令。 --- @@ -1017,11 +1015,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `cli.banner.taglineMode` 控制 banner 标语样式： - - `"random"`（默认）：轮换的有趣/季节性标语。 +- `cli.banner.taglineMode` 用于控制 banner 标语样式： + - `"random"`（默认）：轮换显示有趣/季节性标语。 - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 - `"off"`：不显示标语文本（仍显示 banner 标题/版本）。 -- 若要隐藏整个 banner（而不仅仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 +- 若要隐藏整个 banner（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- @@ -1051,7 +1049,7 @@ SecretRef 是增量式的：明文值仍然可用。 ## Bridge protocol（旧版节点，历史参考）（旧版，已移除） -当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前会导致验证失败；`openclaw doctor --fix` 可剥离未知键）。 +当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可移除未知键）。 @@ -1080,22 +1078,22 @@ SecretRef 是增量式的：明文值仍然可用。 cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs - webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth - sessionRetention: "24h", // duration string or false + webhook: "https://example.invalid/legacy", // 已弃用，用于已存储 notify:true 任务的回退项 + webhookToken: "replace-with-dedicated-token", // 可选，用于出站 webhook 认证的 bearer token + sessionRetention: "24h", // 时长字符串或 false runLog: { - maxBytes: "2mb", // default 2_000_000 bytes - keepLines: 2000, // default 2000 + maxBytes: "2mb", // 默认 2_000_000 字节 + keepLines: 2000, // 默认 2000 }, }, } ``` -- `sessionRetention`：从 `sessions.json` 中清理前，保留已完成隔离 cron 运行会话的时长。也控制已归档删除的 cron 转录内容的清理。默认值：`24h`；设为 `false` 可禁用。 +- `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；若省略则不发送认证头。 -- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于那些仍有 `notify: true` 的已存储作业。 +- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；如省略，则不会发送认证标头。 +- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍保留 `notify: true` 的已存储任务。 ### `cron.retry` @@ -1111,11 +1109,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `maxAttempts`：一次性作业在瞬时错误上的最大重试次数（默认值：`3`；范围：`0`–`10`）。 -- `backoffMs`：每次重试尝试的退避延迟数组，单位为 ms（默认值：`[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` @@ -1133,11 +1131,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `enabled`：启用 cron 作业失败告警（默认值：`false`）。 -- `after`：在触发告警前允许的连续失败次数（正整数，最小值：`1`）。 -- `cooldownMs`：同一作业重复告警之间的最小毫秒间隔（非负整数）。 -- `mode`：投递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 向已配置的 webhook 发起 POST。 -- `accountId`：用于限定告警投递范围的可选账号或渠道 id。 +- `enabled`：为 cron 任务启用失败提醒（默认值：`false`）。 +- `after`：连续失败多少次后触发提醒（正整数，最小值：`1`）。 +- `cooldownMs`：同一任务重复提醒之间的最小间隔，单位为毫秒（非负整数）。 +- `mode`：投递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 则向已配置的 webhook 发起 POST。 +- `accountId`：用于限定提醒投递范围的可选账号或渠道 id。 ### `cron.failureDestination` @@ -1154,16 +1152,16 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- 所有作业共享的 cron 失败通知默认目标。 -- `mode`：`"announce"` 或 `"webhook"`；当存在足够目标数据时，默认值为 `"announce"`。 -- `channel`：用于 announce 投递的渠道覆盖值。`"last"` 会复用上一次已知的投递渠道。 +- 所有任务共用的 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"`。 +- 每个任务的 `delivery.failureDestination` 会覆盖该全局默认值。 +- 当全局和按任务的失败目标都未设置时，已通过 `announce` 投递的任务在失败时会回退到其主要 announce 目标。 +- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的任务，除非该任务的主要 `delivery.mode` 为 `"webhook"`。 -请参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 +请参见 [Cron 任务](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 --- @@ -1171,32 +1169,32 @@ SecretRef 是增量式的：明文值仍然可用。 在 `tools.media.models[].args` 中展开的模板占位符： -| 变量 | 说明 | +| 变量 | 说明 | | ------------------ | ------------------------------------------------- | -| `{{Body}}` | 完整入站消息正文 | -| `{{RawBody}}` | 原始正文（无历史记录/发送者包装） | -| `{{BodyStripped}}` | 去除群组提及后的正文 | -| `{{From}}` | 发送者标识符 | -| `{{To}}` | 目标标识符 | -| `{{MessageSid}}` | 渠道消息 id | -| `{{SessionId}}` | 当前会话 UUID | -| `{{IsNewSession}}` | 新建会话时为 `"true"` | -| `{{MediaUrl}}` | 入站媒体伪 URL | -| `{{MediaPath}}` | 本地媒体路径 | -| `{{MediaType}}` | 媒体类型（image/audio/document/…） | -| `{{Transcript}}` | 音频转录文本 | -| `{{Prompt}}` | 用于 CLI 条目的已解析媒体提示词 | -| `{{MaxChars}}` | 用于 CLI 条目的已解析最大输出字符数 | -| `{{ChatType}}` | `"direct"` 或 `"group"` | -| `{{GroupSubject}}` | 群组主题（尽力提供） | -| `{{GroupMembers}}` | 群组成员预览（尽力提供） | -| `{{SenderName}}` | 发送者显示名称（尽力提供） | -| `{{SenderE164}}` | 发送者电话号码（尽力提供） | -| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | +| `{{Body}}` | 完整的入站消息正文 | +| `{{RawBody}}` | 原始正文（不含历史记录/发送者包装） | +| `{{BodyStripped}}` | 去除群组提及后的正文 | +| `{{From}}` | 发送者标识符 | +| `{{To}}` | 目标标识符 | +| `{{MessageSid}}` | 渠道消息 id | +| `{{SessionId}}` | 当前会话 UUID | +| `{{IsNewSession}}` | 创建新会话时为 `"true"` | +| `{{MediaUrl}}` | 入站媒体伪 URL | +| `{{MediaPath}}` | 本地媒体路径 | +| `{{MediaType}}` | 媒体类型（image/audio/document/…） | +| `{{Transcript}}` | 音频转录文本 | +| `{{Prompt}}` | CLI 条目的已解析媒体提示词 | +| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 | +| `{{ChatType}}` | `"direct"` 或 `"group"` | +| `{{GroupSubject}}` | 群组主题（尽力而为） | +| `{{GroupMembers}}` | 群组成员预览（尽力而为） | +| `{{SenderName}}` | 发送者显示名称（尽力而为） | +| `{{SenderE164}}` | 发送者电话号码（尽力而为） | +| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | --- -## 配置 include（`$include`） +## 配置包含（`$include`） 将配置拆分为多个文件： @@ -1215,12 +1213,12 @@ SecretRef 是增量式的：明文值仍然可用。 - 单个文件：替换其所在的包含对象。 - 文件数组：按顺序深度合并（后者覆盖前者）。 -- 同级键：在 includes 之后合并（覆盖已包含的值）。 -- 嵌套 includes：最多支持 10 层深度。 -- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。只有在最终仍解析到该边界内时，才允许使用绝对路径/`../` 形式。 -- 当 OpenClaw 自有写入仅更改由单文件 include 支持的某个顶层分区时，该写入会透传到被包含的文件。例如，`plugins install` 会更新 `plugins: { $include: "./plugins.json5" }` 中的 `plugins.json5`，并保持 `openclaw.json` 不变。 -- 根级 include、include 数组，以及带有同级覆盖的 include，对于 OpenClaw 自有写入均为只读；这类写入会以关闭方式失败，而不是将配置展平。 -- 错误：针对缺失文件、解析错误和循环 include 提供清晰消息。 +- 同级键：在 include 之后合并（覆盖被包含的值）。 +- 嵌套 include：最多支持 10 层深度。 +- 路径：相对于发起包含的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）之内。仅当绝对路径/`../` 形式在解析后仍位于该边界内时才允许使用。 +- 当 OpenClaw 自有写入只修改由单文件 include 支持的某个顶层 section 时，写入会透传到该被包含文件。例如，`plugins install` 会将 `plugins: { $include: "./plugins.json5" }` 的更新写入 `plugins.json5`，并保持 `openclaw.json` 不变。 +- 根级 include、include 数组，以及带有同级覆盖的 include，对于 OpenClaw 自有写入而言均为只读；这些写入会以失败关闭方式处理，而不是将配置展平。 +- 错误：对于缺失文件、解析错误和循环 include，会提供清晰的错误消息。 --- diff --git a/docs/zh-CN/install/updating.md b/docs/zh-CN/install/updating.md index 75bd1cc3f..88de986ff 100644 --- a/docs/zh-CN/install/updating.md +++ b/docs/zh-CN/install/updating.md @@ -2,18 +2,18 @@ read_when: - 更新 OpenClaw - 更新后出现问题 -summary: 安全更新 OpenClaw（全局安装或源码），以及回滚策略 -title: 更新 +summary: 安全更新 OpenClaw（全局安装或源码安装），以及回滚策略 +title: 更新中 x-i18n: - generated_at: "2026-04-25T01:02:44Z" + generated_at: "2026-04-25T20:12:46Z" model: gpt-5.4 provider: openai - source_hash: af88eaa285145dd5fc370b28c0f9d91069b815c75ec416df726cfce4271a6b54 + source_hash: edb0fb8514130fbac2d5300dbfef85b8cfea8fafb80cc644eb9054f94131a6d4 source_path: install/updating.md workflow: 15 --- -让 OpenClaw 保持最新。 +保持 OpenClaw 为最新版本。 ## 推荐：`openclaw update` @@ -23,7 +23,7 @@ x-i18n: openclaw update ``` -如需切换通道或指定特定版本： +如需切换渠道或指定特定版本： ```bash openclaw update --channel beta @@ -31,19 +31,19 @@ openclaw update --tag main openclaw update --dry-run # 仅预览，不实际应用 ``` -`--channel beta` 会优先选择 beta，但当 beta 标签缺失，或其版本早于最新稳定版时，运行时会回退到 stable/latest。若你想针对一次性的包更新使用原始 npm beta dist-tag，请使用 `--tag beta`。 +`--channel beta` 会优先选择 beta，但当 beta 标签缺失或比最新 stable 版本更旧时，运行时会回退到 stable/latest。若你想在一次性包更新中使用原始的 npm beta dist-tag，请使用 `--tag beta`。 -通道语义请参见 [Development channels](/zh-CN/install/development-channels)。 +渠道语义请参见 [Development channels](/zh-CN/install/development-channels)。 -## 另一种方式：重新运行安装器 +## 备选方案：重新运行安装脚本 ```bash curl -fsSL https://openclaw.ai/install.sh | bash ``` -添加 `--no-onboard` 可跳过新手引导。对于源码安装，传入 `--install-method git --no-onboard`。 +添加 `--no-onboard` 可跳过新手引导。对于源码安装，请传入 `--install-method git --no-onboard`。 -## 另一种方式：手动使用 npm、pnpm 或 bun +## 备选方案：手动使用 npm、pnpm 或 bun ```bash npm i -g openclaw@latest @@ -59,28 +59,28 @@ bun add -g openclaw@latest ### 全局 npm 安装与运行时依赖 -OpenClaw 会将打包后的全局安装视为运行时只读，即使当前用户对全局包目录有写权限也是如此。内置插件的运行时依赖会被暂存到一个可写的运行时目录，而不是直接修改包目录树。这样可以避免 `openclaw update` 与正在运行的 Gateway 网关或本地智能体发生竞争，尤其是在同一次安装期间修复插件依赖时。 +OpenClaw 会将打包后的全局安装在运行时视为只读，即使当前用户对全局包目录具有写权限也是如此。内置插件的运行时依赖会被暂存到可写的运行时目录中，而不是直接修改包树。这样可以避免 `openclaw update` 与正在运行的 Gateway 网关或本地智能体发生竞争，因为后者可能在同一次安装期间修复插件依赖。 -某些 Linux 的 npm 配置会将全局包安装到由 root 拥有的目录下，例如 `/usr/lib/node_modules/openclaw`。OpenClaw 通过同一个外部暂存路径支持这种布局。 +某些 Linux 的 npm 配置会将全局包安装到 root 拥有的目录下，例如 `/usr/lib/node_modules/openclaw`。OpenClaw 通过相同的外部暂存路径支持这种布局。 -对于强化过的 systemd 单元，请设置一个可写的暂存目录，并确保它包含在 `ReadWritePaths` 中： +对于加固的 systemd 单元，请设置一个可写的暂存目录，并将其包含在 `ReadWritePaths` 中： ```ini Environment=OPENCLAW_PLUGIN_STAGE_DIR=/var/lib/openclaw/plugin-runtime-deps ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp ``` -如果未设置 `OPENCLAW_PLUGIN_STAGE_DIR`，OpenClaw 会在 systemd 提供 `$STATE_DIRECTORY` 时优先使用它，否则回退到 `~/.openclaw/plugin-runtime-deps`。 +如果未设置 `OPENCLAW_PLUGIN_STAGE_DIR`，OpenClaw 会在 systemd 提供 `$STATE_DIRECTORY` 时优先使用它，否则回退到 `~/.openclaw/plugin-runtime-deps`。修复步骤会将该暂存区视为由 OpenClaw 管理的本地包根目录，并忽略用户的 npm prefix/global 设置，因此全局安装的 npm 配置不会将内置插件依赖重定向到 `~/node_modules` 或全局包树中。 ### 内置插件运行时依赖 -打包安装会将内置插件运行时依赖保留在只读包目录树之外。在启动时以及运行 `openclaw doctor --fix` 期间，OpenClaw 仅会为以下内置插件修复运行时依赖：在配置中处于活动状态、通过旧版渠道配置处于活动状态，或在其内置清单默认设置中启用的插件。 +打包安装会将内置插件运行时依赖保留在只读包树之外。在启动时以及执行 `openclaw doctor --fix` 期间，OpenClaw 只会为以下内置插件修复运行时依赖：在配置中处于活动状态、通过旧版渠道配置处于活动状态，或由其内置清单默认启用的插件。 -显式禁用具有最高优先级。已禁用的插件或渠道不会仅因为存在于安装包中就被修复其运行时依赖。外部插件和自定义加载路径仍需使用 `openclaw plugins install` 或 `openclaw plugins update`。 +显式禁用优先。已禁用的插件或渠道，不会仅因为它存在于包中就修复其运行时依赖。外部插件和自定义加载路径仍需使用 `openclaw plugins install` 或 `openclaw plugins update`。 ## 自动更新器 -自动更新器默认关闭。在 `~/.openclaw/openclaw.json` 中启用： +自动更新器默认关闭。可在 `~/.openclaw/openclaw.json` 中启用： ```json5 { @@ -98,11 +98,11 @@ ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp | Channel | 行为 | | -------- | ---- | -| `stable` | 等待 `stableDelayHours`，然后在 `stableJitterHours` 范围内按确定性抖动应用更新（分散发布）。 | +| `stable` | 等待 `stableDelayHours`，然后在 `stableJitterHours` 范围内按确定性抖动应用（分散发布）。 | | `beta` | 每隔 `betaCheckIntervalHours` 检查一次（默认：每小时），并立即应用。 | | `dev` | 不会自动应用。请手动使用 `openclaw update`。 | -Gateway 网关 还会在启动时记录更新提示（可通过 `update.checkOnStart: false` 禁用）。 +Gateway 网关也会在启动时记录更新提示（可通过 `update.checkOnStart: false` 禁用）。 ## 更新后 @@ -114,7 +114,7 @@ Gateway 网关 还会在启动时记录更新提示（可通过 `update.checkOnS openclaw doctor ``` -迁移配置、审计私信策略，并检查 Gateway 网关 健康状态。详情请参见：[Doctor](/zh-CN/gateway/doctor) +迁移配置、审计私信策略并检查 Gateway 网关健康状态。详情参见：[Doctor](/zh-CN/gateway/doctor) ### 重启 Gateway 网关 @@ -140,9 +140,9 @@ openclaw doctor openclaw gateway restart ``` -提示：`npm view openclaw version` 会显示当前已发布版本。 +提示：`npm view openclaw version` 会显示当前已发布的版本。 -### 固定到某个提交（源码） +### 固定提交（源码） ```bash git fetch origin @@ -151,17 +151,17 @@ pnpm install && pnpm build openclaw gateway restart ``` -如需返回最新版本：`git checkout main && git pull`。 +如需恢复到最新版本：`git checkout main && git pull`。 ## 如果你卡住了 -- 再次运行 `openclaw doctor`，并仔细阅读输出内容。 +- 再次运行 `openclaw doctor`，并仔细阅读输出。 - 对于源码检出的 `openclaw update --channel dev`，更新器会在需要时自动引导安装 `pnpm`。如果你看到 pnpm/corepack 引导错误，请手动安装 `pnpm`（或重新启用 `corepack`），然后重新运行更新。 - 查看：[故障排除](/zh-CN/gateway/troubleshooting) - 在 Discord 中提问：[https://discord.gg/clawd](https://discord.gg/clawd) ## 相关内容 -- [安装概览](/zh-CN/install) — 所有安装方式 +- [Install Overview](/zh-CN/install) — 所有安装方式 - [Doctor](/zh-CN/gateway/doctor) — 更新后的健康检查 -- [迁移](/zh-CN/install/migrating) — 主要版本迁移指南 +- [Migrating](/zh-CN/install/migrating) — 主要版本迁移指南 diff --git a/docs/zh-CN/nodes/talk.md b/docs/zh-CN/nodes/talk.md index d996d03d9..00b8fe7f6 100644 --- a/docs/zh-CN/nodes/talk.md +++ b/docs/zh-CN/nodes/talk.md @@ -1,14 +1,14 @@ --- read_when: - - 在 macOS/iOS/Android 上实现通话模式 + - 在 macOS / iOS / Android 上实现通话模式 - 更改语音 / TTS / 打断行为 -summary: 通话模式：与已配置的 TTS 提供商进行连续语音对话 +summary: 通话模式：使用已配置的 TTS 提供商进行连续语音对话 title: 通话模式 x-i18n: - generated_at: "2026-04-25T19:17:43Z" + generated_at: "2026-04-25T20:12:47Z" model: gpt-5.4 provider: openai - source_hash: 5f2130c58870000faa6c818587f4a487948f189b777426a81764e37c39204f51 + source_hash: afdddaa81c0a09076eaeeafd25295b0c02681f03b273ec4afe4ea2afa692dc2a source_path: nodes/talk.md workflow: 15 --- @@ -22,15 +22,15 @@ x-i18n: ## 行为（macOS） -- 启用通话模式后，会显示**常驻悬浮层**。 +- 启用通话模式时，显示**常驻悬浮层**。 - 在**监听 → 思考 → 朗读**阶段之间切换。 -- 在出现**短暂停顿**（静音窗口）时，会发送当前转录文本。 +- 在**短暂停顿**（静音窗口）后，发送当前转录文本。 - 回复会**写入 WebChat**（与手动输入相同）。 -- **说话时打断**（默认开启）：如果助手正在朗读时用户开始说话，我们会停止播放，并记录打断时间戳，用于下一次提示。 +- **语音打断**（默认开启）：如果智能体正在朗读时用户开始说话，我们会停止播放，并记录打断时间戳，以供下一个提示使用。 ## 回复中的语音指令 -助手可以在回复前添加**单独一行 JSON** 来控制语音： +智能体可以在回复前添加**单独一行 JSON** 来控制语音： ```json { "voice": "", "once": true } @@ -38,7 +38,7 @@ x-i18n: 规则： -- 仅第一行非空行有效。 +- 仅第一条非空行有效。 - 未知键会被忽略。 - `once: true` 仅应用于当前这次回复。 - 如果没有 `once`，该语音会成为通话模式新的默认语音。 @@ -48,8 +48,8 @@ x-i18n: - `voice` / `voice_id` / `voiceId` - `model` / `model_id` / `modelId` -- `speed`、`rate`（WPM）、`stability`、`similarity`、`style`、`speakerBoost` -- `seed`、`normalize`、`lang`、`output_format`、`latency_tier` +- `speed`, `rate`（WPM）, `stability`, `similarity`, `style`, `speakerBoost` +- `seed`, `normalize`, `lang`, `output_format`, `latency_tier` - `once` ## 配置（`~/.openclaw/openclaw.json`） @@ -70,6 +70,7 @@ x-i18n: }, system: {}, }, + speechLocale: "ru-RU", silenceTimeoutMs: 1500, interruptOnSpeech: true, }, @@ -79,38 +80,39 @@ x-i18n: 默认值： - `interruptOnSpeech`：true -- `silenceTimeoutMs`：未设置时，通话会在发送转录文本前使用平台默认的停顿窗口（`macOS` 和 Android 为 `700 ms`，iOS 为 `900 ms`） -- `provider`：选择当前启用的通话提供商。对于 macOS 本地播放路径，可使用 `elevenlabs`、`mlx` 或 `system`。 -- `providers..voiceId`：对于 ElevenLabs，会回退到 `ELEVENLABS_VOICE_ID` / `SAG_VOICE_ID`（或者在 API key 可用时，使用第一个 ElevenLabs 语音）。 +- `silenceTimeoutMs`：未设置时，通话模式会在发送转录文本前使用平台默认的停顿窗口（`macOS` 和 `Android` 为 `700 ms`，`iOS` 为 `900 ms`） +- `provider`：选择当前启用的通话提供商。对于 `macOS` 本地播放路径，可使用 `elevenlabs`、`mlx` 或 `system`。 +- `providers..voiceId`：对于 ElevenLabs，会回退到 `ELEVENLABS_VOICE_ID` / `SAG_VOICE_ID`（或者在 API key 可用时使用第一个 ElevenLabs 语音）。 - `providers.elevenlabs.modelId`：未设置时默认为 `eleven_v3`。 - `providers.mlx.modelId`：未设置时默认为 `mlx-community/Soprano-80M-bf16`。 -- `providers.elevenlabs.apiKey`：会回退到 `ELEVENLABS_API_KEY`（或者在可用时使用 Gateway 网关 shell profile）。 -- `outputFormat`：在 macOS/iOS 上默认为 `pcm_44100`，在 Android 上默认为 `pcm_24000`（设置为 `mp3_*` 可强制使用 MP3 流式传输） +- `providers.elevenlabs.apiKey`：会回退到 `ELEVENLABS_API_KEY`（如果可用，也可使用 Gateway 网关 shell 配置文件中的值）。 +- `speechLocale`：可选的 BCP 47 区域设置 ID，用于 `iOS` / `macOS` 上设备端通话语音识别。不设置则使用设备默认值。 +- `outputFormat`：在 `macOS` / `iOS` 上默认是 `pcm_44100`，在 `Android` 上默认是 `pcm_24000`（设置 `mp3_*` 可强制使用 MP3 流式传输） ## macOS UI -- 菜单栏开关：**通话** -- 配置标签页：**通话模式**分组（voice id + 打断开关） +- 菜单栏开关：**Talk** +- 配置标签页：**Talk Mode** 分组（voice id + 打断开关） - 悬浮层： - - **监听中**：云朵会随着麦克风音量脉动 - - **思考中**：下沉动画 - - **朗读中**：放射状波纹 + - **Listening**：云朵随麦克风音量脉动 + - **Thinking**：下沉动画 + - **Speaking**：向外辐射的圆环 - 点击云朵：停止朗读 - 点击 X：退出通话模式 ## Android UI -- Voice 标签页开关：**通话** +- 语音标签页开关：**Talk** - 手动 **Mic** 和 **Talk** 是互斥的运行时采集模式。 -- 当应用离开前台或用户离开 Voice 标签页时，手动 Mic 会停止。 -- 通话模式会持续运行，直到被关闭或 Android 节点断开连接，并且在启用期间使用 Android 麦克风前台服务类型。 +- 当应用离开前台或用户离开语音标签页时，手动 Mic 会停止。 +- Talk Mode 会持续运行，直到被关闭或 Android 节点断开连接，并且在启用期间使用 Android 麦克风前台服务类型。 ## 说明 - 需要语音和麦克风权限。 -- 通过会话键 `main` 使用 `chat.send`。 +- 使用会话键 `main` 对 `chat.send` 发起调用。 - Gateway 网关会使用当前启用的通话提供商，通过 `talk.speak` 解析通话播放。只有在该 RPC 不可用时，Android 才会回退到本地系统 TTS。 -- macOS 本地 MLX 播放会在存在时使用内置的 `openclaw-mlx-tts` helper，或使用 `PATH` 上的可执行文件。开发期间可设置 `OPENCLAW_MLX_TTS_BIN` 来指向自定义 helper 二进制文件。 +- `macOS` 本地 MLX 播放会在可用时使用内置的 `openclaw-mlx-tts` helper，或者使用 `PATH` 上的可执行文件。开发时可设置 `OPENCLAW_MLX_TTS_BIN`，指向自定义 helper 二进制文件。 - `eleven_v3` 的 `stability` 会校验为 `0.0`、`0.5` 或 `1.0`；其他模型接受 `0..1`。 - 设置 `latency_tier` 时，会校验其范围为 `0..4`。 - Android 支持 `pcm_16000`、`pcm_22050`、`pcm_24000` 和 `pcm_44100` 输出格式，以实现低延迟 `AudioTrack` 流式传输。