diff --git a/docs/zh-CN/concepts/compaction.md b/docs/zh-CN/concepts/compaction.md index a6ca98e36..3fe3e5eae 100644 --- a/docs/zh-CN/concepts/compaction.md +++ b/docs/zh-CN/concepts/compaction.md @@ -1,65 +1,123 @@ --- read_when: - 你想了解自动压缩和 /compact - - 你正在调试因长会话触及上下文限制的问题 -summary: OpenClaw 如何总结长对话以保持在模型限制之内 -title: Compaction + - 你正在排查达到上下文限制的长会话 +summary: OpenClaw 如何总结长对话以保持在模型限制范围内 +title: 压缩 x-i18n: - generated_at: "2026-04-05T08:20:48Z" + generated_at: "2026-04-07T17:57:26Z" model: gpt-5.4 provider: openai - source_hash: 4c6dbd6ebdcd5f918805aafdc153925efef3e130faa3fab3c630832e938219fc + source_hash: e6590b82a8c3a9c310998d653459ca4d8612495703ca0a8d8d306d7643142fd1 source_path: concepts/compaction.md workflow: 15 --- -# Compaction +# 压缩 -每个模型都有一个上下文窗口——即它最多能处理的 token 数量。 +每个模型都有一个上下文窗口——即它能够处理的最大 token 数量。 当对话接近这个限制时，OpenClaw 会将较早的消息**压缩**为摘要， -以便聊天可以继续进行。 +以便聊天能够继续。 ## 工作原理 1. 较早的对话轮次会被总结为一条压缩条目。 -2. 该摘要会保存在会话转录中。 +2. 摘要会保存在会话转录中。 3. 最近的消息会保持原样。 -当 OpenClaw 将历史拆分为压缩分块时，它会让 assistant 工具 -调用与其匹配的 `toolResult` 条目保持配对。如果拆分点落在工具块 -内部，OpenClaw 会移动边界，以便这对条目保持在一起，并保留 -当前未总结的尾部内容。 +当 OpenClaw 将历史记录拆分为压缩分块时，它会让智能体工具调用 +与其对应的 `toolResult` 条目保持配对。如果拆分点落在工具块内部， +OpenClaw 会移动边界，以确保这对内容保持在一起，并保留当前尚未摘要的尾部内容。 -完整的对话历史仍会保存在磁盘上。压缩只会改变模型在下一轮 -看到的内容。 +完整的对话历史仍会保存在磁盘上。压缩只会改变模型在下一轮中看到的内容。 ## 自动压缩 -自动压缩默认开启。当会话接近上下文 -限制时，或当模型返回上下文溢出错误时，它就会运行（在这种情况下， -OpenClaw 会执行压缩并重试）。典型的溢出特征包括 +自动压缩默认开启。当会话接近上下文限制时，或者当模型返回上下文溢出错误时，它就会运行（在这种情况下，OpenClaw 会先压缩再重试）。典型的溢出特征包括 `request_too_large`、`context length exceeded`、`input exceeds the maximum number of tokens`、`input token count exceeds the maximum number of input tokens`、`input is too long for the model` 和 `ollama error: context length exceeded`。 -在压缩之前，OpenClaw 会自动提醒智能体将重要 -备注保存到 [memory](/concepts/memory) 文件中。这样可以防止上下文丢失。 +在压缩之前，OpenClaw 会自动提醒智能体将重要笔记保存到 [memory](/zh-CN/concepts/memory) 文件中。这样可以防止上下文丢失。 +使用你的 `openclaw.json` 中的 `agents.defaults.compaction` 设置来配置压缩行为（模式、目标 token 数等）。 +压缩摘要默认会保留不透明标识符（`identifierPolicy: "strict"`）。你可以使用 `identifierPolicy: "off"` 覆盖此行为，或者使用 `identifierPolicy: "custom"` 和 `identifierInstructions` 提供自定义文本。 + +你也可以通过 `agents.defaults.compaction.model` 为压缩摘要指定不同的模型。当你的主模型是本地模型或小模型，而你希望由能力更强的模型生成压缩摘要时，这会很有用。该覆盖项接受任意 `provider/model-id` 字符串： + +```json +{ + "agents": { + "defaults": { + "compaction": { + "model": "openrouter/anthropic/claude-sonnet-4-6" + } + } + } +} +``` + +这同样适用于本地模型，例如专门用于摘要的第二个 Ollama 模型，或经过微调的压缩专用模型： + +```json +{ + "agents": { + "defaults": { + "compaction": { + "model": "ollama/llama3.1:8b" + } + } + } +} +``` + +如果未设置，压缩会使用该智能体的主模型。 + +## 可插拔压缩提供商 + +插件可以通过插件 API 上的 `registerCompactionProvider()` 注册自定义压缩提供商。当某个提供商已注册并配置后，OpenClaw 会将摘要生成委托给它，而不是使用内置的 LLM 流程。 + +要使用已注册的提供商，请在你的配置中设置提供商 id： + +```json +{ + "agents": { + "defaults": { + "compaction": { + "provider": "my-provider" + } + } + } +} +``` + +设置 `provider` 会自动强制使用 `mode: "safeguard"`。提供商会收到与内置路径相同的压缩指令和标识符保留策略，并且在提供商输出后，OpenClaw 仍会保留最近轮次和拆分轮次的后缀上下文。如果提供商失败或返回空结果，OpenClaw 会回退到内置 LLM 摘要生成。 + +## 自动压缩（默认开启） + +当会话接近或超出模型的上下文窗口时，OpenClaw 会触发自动压缩，并可能使用压缩后的上下文重试原始请求。 + +你会看到： + +- 在详细模式下显示 `🧹 Auto-compaction complete` +- `/status` 显示 `🧹 Compactions: ` + +在压缩之前，OpenClaw 可以运行一次**静默 memory 刷新**轮次，以将持久笔记存储到磁盘。详情和配置请参阅 [Memory](/zh-CN/concepts/memory)。 + ## 手动压缩 -在任意聊天中输入 `/compact` 即可强制执行一次压缩。你还可以添加说明来引导 -摘要内容： +在任意聊天中输入 `/compact` 即可强制执行一次压缩。你还可以添加说明来引导摘要： ``` /compact Focus on the API design decisions ``` -## 使用其他模型 +## 使用不同的模型 -默认情况下，压缩使用你的智能体主模型。你也可以使用能力更强的模型来获得更好的摘要： +默认情况下，压缩使用你的智能体主模型。你可以使用能力更强的模型来获得更好的摘要： ```json5 { @@ -75,8 +133,7 @@ exceeded`。 ## 压缩开始通知 -默认情况下，压缩会静默执行。若要在压缩 -开始时显示简短通知，请启用 `notifyUser`： +默认情况下，压缩会静默运行。若要在压缩开始时显示简短通知，请启用 `notifyUser`： ```json5 { @@ -90,39 +147,33 @@ exceeded`。 } ``` -启用后，用户会在每次压缩开始时看到一条简短消息（例如，“正在压缩 -上下文...”）。 +启用后，用户会在每次压缩开始时看到一条简短消息（例如，“正在压缩上下文...”）。 ## 压缩与修剪 | | 压缩 | 修剪 | | ---------------- | ---------------------------- | -------------------------------- | -| **它的作用** | 总结较早的对话 | 裁剪旧的工具结果 | -| **是否保存？** | 是（保存在会话转录中） | 否（仅在内存中，每次请求单独处理） | +| **作用** | 总结较早的对话内容 | 裁剪旧的工具结果 | +| **会保存吗？** | 会（保存在会话转录中） | 不会（仅在内存中、按每次请求） | | **范围** | 整个对话 | 仅工具结果 | -[Session pruning](/concepts/session-pruning) 是一种更轻量的补充方式， -可在不总结的情况下裁剪工具输出。 +[Session pruning](/zh-CN/concepts/session-pruning) 是一种更轻量的补充方式，它会在不生成摘要的情况下裁剪工具输出。 ## 故障排除 -**压缩过于频繁？** 模型的上下文窗口可能较小，或者工具 -输出可能较大。可以尝试启用 -[Session pruning](/concepts/session-pruning)。 +**压缩太频繁？** 模型的上下文窗口可能较小，或者工具输出可能较大。尝试启用 +[session pruning](/zh-CN/concepts/session-pruning)。 -**压缩后感觉上下文过时？** 使用 `/compact Focus on ` 来 -引导摘要，或启用 [memory flush](/concepts/memory)，以便备注 -能够保留下来。 +**压缩后感觉上下文不够新鲜？** 使用 `/compact Focus on ` 来引导摘要，或者启用 [memory flush](/zh-CN/concepts/memory)，以便笔记得以保留。 -**需要一个全新的开始？** `/new` 会启动一个全新的会话，而不会执行压缩。 +**需要一个全新的开始？** `/new` 会启动一个新的会话，而不会进行压缩。 -有关高级配置（预留 token、标识符保留、自定义 -上下文引擎、OpenAI 服务端压缩），请参阅 -[Session Management Deep Dive](/reference/session-management-compaction)。 +有关高级配置（预留 token、标识符保留、自定义上下文引擎、OpenAI 服务端压缩），请参阅 +[Session Management Deep Dive](/zh-CN/reference/session-management-compaction)。 ## 相关内容 -- [Session](/concepts/session) — 会话管理与生命周期 -- [Session Pruning](/concepts/session-pruning) — 裁剪工具结果 -- [Context](/concepts/context) — 如何为智能体轮次构建上下文 -- [Hooks](/automation/hooks) — 压缩生命周期 hooks（before_compaction、after_compaction） +- [Session](/zh-CN/concepts/session) — 会话管理与生命周期 +- [Session Pruning](/zh-CN/concepts/session-pruning) — 裁剪工具结果 +- [Context](/zh-CN/concepts/context) — 如何为智能体轮次构建上下文 +- [Hooks](/zh-CN/automation/hooks) — 压缩生命周期钩子（before_compaction、after_compaction） diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 6fedd0de1..f6aa41288 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -5,52 +5,52 @@ read_when: summary: 每个 OpenClaw 配置键、默认值和渠道设置的完整参考 title: 配置参考 x-i18n: - generated_at: "2026-04-07T15:03:06Z" + generated_at: "2026-04-07T18:03:05Z" model: gpt-5.4 provider: openai - source_hash: 1eb296bd35db5d26be5a72ce2cbf94c5173d4e8ebeb6eb2d891dddd102511d05 + source_hash: 2c7991b948cbbb7954a3e26280089ab00088e7f4878ec0b0540c3c9acf222ebb source_path: gateway/configuration-reference.md workflow: 15 --- # 配置参考 -`~/.openclaw/openclaw.json` 中可用的每个字段。若想查看面向任务的概览，请参阅 [Configuration](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 中可用的每个字段。要查看面向任务的概览，请参阅 [配置](/zh-CN/gateway/configuration)。 -配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段均为可选——省略时，OpenClaw 会使用安全的默认值。 +配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全的默认值。 --- ## 渠道 -只要某个渠道的配置段存在，该渠道就会自动启动（除非设置了 `enabled: false`）。 +每个渠道在其配置节存在时都会自动启动（除非设置了 `enabled: false`）。 ### 私信和群组访问 所有渠道都支持私信策略和群组策略： -| 私信策略 | 行为 | -| ------------------- | -------------------------------------------------------- | -| `pairing`（默认） | 未知发送者会收到一次性配对码；必须由所有者批准 | -| `allowlist` | 仅允许 `allowFrom`（或已配对允许存储）中的发送者 | -| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有传入私信 | +| 私信策略 | 行为 | +| ------------------- | ------------------------------ | +| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | +| `allowlist` | 仅允许 `allowFrom`（或已配对的允许存储）中的发送者 | +| `open` | 允许所有入站私信（要求 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有入站私信 | -| 群组策略 | 行为 | -| --------------------- | -------------------------------------------------------- | -| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 | -| `open` | 绕过群组允许列表（仍然会应用提及门控） | -| `disabled` | 阻止所有群组/房间消息 | +| 群组策略 | 行为 | +| --------------------- | ------------------------------ | +| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 | +| `open` | 绕过群组允许列表（仍然应用提及门控） | +| `disabled` | 阻止所有群组/房间消息 | -`channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时作为默认值。 -配对码会在 1 小时后过期。待处理的私信配对请求每个渠道最多 **3 个**。 -如果某个提供商配置块完全缺失（不存在 `channels.`），运行时群组策略会回退为 `allowlist`（默认拒绝），并在启动时发出警告。 +当提供商的 `groupPolicy` 未设置时，`channels.defaults.groupPolicy` 会设置默认值。 +配对码会在 1 小时后过期。待处理的私信配对请求上限为**每个渠道 3 个**。 +如果整个提供商块缺失（即不存在 `channels.`），运行时群组策略会回退为 `allowlist`（默认拒绝），并在启动时发出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。只有当某个会话尚未拥有模型覆盖时（例如通过 `/model` 设置），才会应用该渠道映射。 +使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当某个会话尚未设置模型覆盖时（例如通过 `/model` 设置），会应用该渠道映射。 ```json5 { @@ -73,7 +73,7 @@ x-i18n: ### 渠道默认值和心跳 -使用 `channels.defaults` 可为各提供商共享群组策略和心跳行为： +使用 `channels.defaults` 为各提供商共享群组策略和心跳行为： ```json5 { @@ -92,14 +92,14 @@ x-i18n: ``` - `channels.defaults.groupPolicy`：当提供商级别的 `groupPolicy` 未设置时使用的后备群组策略。 -- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。每渠道覆盖：`channels..contextVisibility`。 +- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（只包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。单渠道覆盖：`channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。 - `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 - `channels.defaults.heartbeat.useIndicator`：渲染紧凑的指示器样式心跳输出。 ### WhatsApp -WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已链接会话时会自动启动。 +WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当已存在已关联会话时，它会自动启动。 ```json5 { @@ -110,7 +110,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // 蓝色对勾（self-chat 模式下为 false） + sendReadReceipts: true, // 蓝色对勾（在 self-chat 模式下为 false） groups: { "*": { requireMention: true }, }, @@ -132,7 +132,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` - + ```json5 { @@ -150,10 +150,10 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 出站命令默认使用 `default` 账号（如果存在）；否则使用按排序后的第一个已配置账号 ID。 -- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖该后备默认账号选择。 -- 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 -- 每账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 +- 出站命令默认使用账户 `default`（如果存在）；否则使用第一个已配置的账户 id（排序后）。 +- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖该后备默认账户选择。 +- 旧版单账户 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 +- 每账户覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -188,7 +188,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress（默认：off；请显式启用以避免预览编辑速率限制） + streaming: "partial", // off | partial | block | progress（默认：off；需显式启用以避免预览编辑速率限制） actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -211,13 +211,13 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅允许普通文件；拒绝符号链接），默认账号还可回退到 `TELEGRAM_BOT_TOKEN`。 -- 可选的 `channels.telegram.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 在多账号设置中（2 个及以上账号 ID），请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；当该值缺失或无效时，`openclaw doctor` 会发出警告。 +- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅允许常规文件；拒绝符号链接），默认账户还可回退到 `TELEGRAM_BOT_TOKEN`。 +- 可选的 `channels.telegram.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖默认账户选择。 +- 在多账户设置中（2 个或更多账户 id），设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免后备路由；若缺失或无效，`openclaw doctor` 会发出警告。 - `configWrites: false` 会阻止由 Telegram 发起的配置写入（supergroup ID 迁移、`/config set|unset`）。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目可为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。 -- Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于私聊和群聊）。 -- 重试策略：参见 [Retry policy](/zh-CN/concepts/retry)。 +- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目会为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范形式 `chatId:topic:topicId`）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。 +- Telegram 流式预览使用 `sendMessage` + `editMessageText`（在私聊和群聊中都有效）。 +- 重试策略：参见 [重试策略](/zh-CN/concepts/retry)。 ### Discord @@ -272,7 +272,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress（在 Discord 上 progress 映射为 partial） + streaming: "off", // off | partial | block | progress（progress 在 Discord 上会映射为 partial） maxLinesPerMessage: 17, ui: { components: { @@ -319,36 +319,36 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- Token：`channels.discord.token`，默认账号还可回退到 `DISCORD_BOT_TOKEN`。 -- 直接出站调用若显式提供 Discord `token`，则该调用会使用该 token；账号重试/策略设置仍来自活动运行时快照中选定的账号。 -- 可选的 `channels.discord.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 使用 `user:`（私信）或 `channel:`（服务器频道）作为投递目标；裸数字 ID 会被拒绝。 -- Guild slug 会转为小写，空格替换为 `-`；频道键使用 slug 化后的名称（不含 `#`）。优先使用 guild ID。 -- 默认会忽略机器人发送的消息。`allowBots: true` 可启用；`allowBots: "mentions"` 则仅接受提及该机器人的机器人消息（机器人自己的消息仍会被过滤）。 -- `channels.discord.guilds..ignoreOtherMentions`（以及频道覆盖）会丢弃提及其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。 -- `maxLinesPerMessage`（默认 17）会拆分过高的消息，即使其不足 2000 字符。 +- Token：`channels.discord.token`，默认账户还可回退到 `DISCORD_BOT_TOKEN`。 +- 直接出站调用如果提供了显式的 Discord `token`，该调用会使用该 token；账户重试/策略设置仍来自活动运行时快照中选定的账户。 +- 可选的 `channels.discord.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖默认账户选择。 +- 交付目标使用 `user:`（私信）或 `channel:`（服务器频道）；纯数字 ID 会被拒绝。 +- Guild slug 使用小写，并将空格替换为 `-`；渠道键使用 slug 化名称（不带 `#`）。优先使用 guild ID。 +- 默认忽略机器人自己发送的消息。`allowBots: true` 会启用；`allowBots: "mentions"` 仅接受提及该机器人的机器人消息（机器人自己的消息仍会被过滤）。 +- `channels.discord.guilds..ignoreOtherMentions`（以及渠道级覆盖）会丢弃提及其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。 +- `maxLinesPerMessage`（默认 17）会拆分过高的消息，即使消息长度未超过 2000 个字符。 - `channels.discord.threadBindings` 控制 Discord 线程绑定路由： - - `enabled`：线程绑定会话功能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及绑定投递/路由）的 Discord 覆盖 - - `idleHours`：以小时计的 Discord 非活动自动取消聚焦覆盖（`0` 表示禁用） - - `maxAgeHours`：以小时计的 Discord 硬性最大存活时间覆盖（`0` 表示禁用） - - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程的显式开关 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目可为频道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用频道/线程 ID）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。 -- `channels.discord.ui.components.accentColor` 用于设置 Discord components v2 容器的强调色。 -- `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入 + TTS 覆盖。 -- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传到 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 -- OpenClaw 还会在重复解密失败后通过离开/重新加入语音会话来尝试恢复语音接收。 -- `channels.discord.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 -- `channels.discord.autoPresence` 会将运行时可用性映射为机器人状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 + - `enabled`：线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及绑定交付/路由） + - `idleHours`：按小时计算的无活动自动取消聚焦 Discord 覆盖（`0` 表示禁用） + - `maxAgeHours`：按小时计算的硬性最大生命周期 Discord 覆盖（`0` 表示禁用） + - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程的显式启用开关 +- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目会为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用 channel/thread id）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。 +- `channels.discord.ui.components.accentColor` 为 Discord components v2 容器设置强调色。 +- `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入和 TTS 覆盖。 +- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` DAVE 选项（默认分别为 `true` 和 `24`）。 +- OpenClaw 还会在重复解密失败后，通过离开/重新加入语音会话来尝试语音接收恢复。 +- `channels.discord.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔值 `streaming` 会自动迁移。 +- `channels.discord.autoPresence` 会将运行时可用性映射到机器人状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 - `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（紧急兼容模式）。 -- `channels.discord.execApprovals`：Discord 原生 exec 批准投递和审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在 auto 模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，会激活 exec 批准。 +- `channels.discord.execApprovals`：Discord 原生 exec 审批交付和审批人授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在 auto 模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析到审批人时，exec 审批会激活。 - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 - - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的批准请求。 - - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：批准提示发送位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到发起频道，`"both"` 同时发送。若目标包含 `"channel"`，按钮仅对已解析出的审批人可用。 - - `cleanupAfterResolve`：当为 `true` 时，在批准、拒绝或超时后删除批准私信。 + - `agentFilter`：可选智能体 ID 允许列表。省略则转发所有智能体的审批。 + - `sessionFilter`：可选会话键模式（子串或正则）。 + - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到发起渠道，`"both"` 同时发送到两者。当 target 包含 `"channel"` 时，按钮仅对已解析的审批人可用。 + - `cleanupAfterResolve`：为 `true` 时，在审批、拒绝或超时后删除审批私信。 -**反应通知模式：** `off`（无）、`own`（机器人自己的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users` 的所有消息）。 +**反应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users` 的所有消息）。 ### Google Chat @@ -379,10 +379,10 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 服务账号 JSON：支持内联（`serviceAccount`）或文件方式（`serviceAccountFile`）。 -- 也支持服务账号 SecretRef（`serviceAccountRef`）。 +- 服务账户 JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 +- 也支持服务账户 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 使用 `spaces/` 或 `users/` 作为投递目标。 +- 交付目标使用 `spaces/` 或 `users/`。 - `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（紧急兼容模式）。 ### Slack @@ -448,37 +448,37 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP mode** 需要 `botToken` 以及 `signingSecret`（可位于根级别或每账号级别）。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 支持明文字符串 - 或 SecretRef 对象。 -- Slack 账号快照会暴露按凭证划分的来源/状态字段，例如 - `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 下的 - `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef - 完成配置，但当前命令/运行时路径无法解析该 secret 值。 +- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账户环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP mode** 需要 `botToken` 加 `signingSecret`（可位于根级或每账户级）。 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 + 字符串或 SecretRef 对象。 +- Slack 账户快照会公开每项凭据的来源/状态字段，例如 + `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 + `signingSecretStatus`。`configured_unavailable` 表示该账户通过 SecretRef 完成配置， + 但当前命令/运行时路径无法解析该 secret 值。 - `configWrites: false` 会阻止由 Slack 发起的配置写入。 -- 可选的 `channels.slack.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- `channels.slack.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 -- 使用 `user:`（私信）或 `channel:` 作为投递目标。 +- 可选的 `channels.slack.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖默认账户选择。 +- `channels.slack.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔值 `streaming` 会自动迁移。 +- 交付目标使用 `user:`（私信）或 `channel:`。 **反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 可按线程隔离（默认）或在频道内共享。`thread.inheritParent` 会将父频道转录复制到新线程中。 +**线程会话隔离：** `thread.historyScope` 可为每线程（默认）或整个频道共享。`thread.inheritParent` 会将父频道的会话记录复制到新线程。 -- `typingReaction` 会在回复执行期间临时向传入 Slack 消息添加一个反应，并在完成后移除。请使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 -- `channels.slack.execApprovals`：Slack 原生 exec 批准投递和审批人授权。其 schema 与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 +- `typingReaction` 会在回复执行期间为入站 Slack 消息添加一个临时反应，并在完成后移除。请使用 Slack emoji shortcode，例如 `"hourglass_flowing_sand"`。 +- `channels.slack.execApprovals`：Slack 原生 exec 审批交付和审批人授权。与 Discord 相同的 schema：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 -| 操作组 | 默认值 | 说明 | -| ------------ | -------- | ---------------------- | -| reactions | 已启用 | 反应 + 列出反应 | -| messages | 已启用 | 读取/发送/编辑/删除 | -| pins | 已启用 | 固定/取消固定/列出 | -| memberInfo | 已启用 | 成员信息 | -| emojiList | 已启用 | 自定义 emoji 列表 | +| 操作组 | 默认值 | 说明 | +| ------------ | ------ | -------------------- | +| reactions | 已启用 | 添加反应 + 列出反应 | +| messages | 已启用 | 读取/发送/编辑/删除 | +| pins | 已启用 | 置顶/取消置顶/列出 | +| memberInfo | 已启用 | 成员信息 | +| emojiList | 已启用 | 自定义 emoji 列表 | ### Mattermost -Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermost`。 +Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost`。 ```json5 { @@ -498,7 +498,7 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos native: true, // 显式启用 nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // 面向反向代理/公共部署的可选显式 URL + // 反向代理/公共部署可选显式 URL callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -508,21 +508,21 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos } ``` -聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（响应以触发前缀开头的消息）。 +聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（以触发前缀开头的消息）。 启用 Mattermost 原生命令时： - `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 -- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器可以访问。 -- 原生斜杠命令回调使用 Mattermost 在斜杠命令注册期间返回的每命令 token 进行认证。如果注册失败，或没有任何命令被激活，OpenClaw 会拒绝回调并返回 - `Unauthorized: invalid command token.` +- `commands.callbackUrl` 必须能解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器可以访问。 +- 原生 slash 回调使用 Mattermost 在 slash 命令注册期间返回的每命令 token 进行认证。如果注册失败或没有激活任何命令，OpenClaw 会以 + `Unauthorized: invalid command token.` 拒绝回调。 - 对于私有/tailnet/内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机/域名。 请使用主机/域名值，而不是完整 URL。 -- `channels.mattermost.configWrites`：允许或拒绝 Mattermost 发起的配置写入。 +- `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。 - `channels.mattermost.requireMention`：要求在频道中回复前必须有 `@mention`。 -- `channels.mattermost.groups..requireMention`：按频道覆盖提及门控（`"*"` 表示默认值）。 -- 可选的 `channels.mattermost.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 +- `channels.mattermost.groups..requireMention`：按频道的提及门控覆盖（`"*"` 表示默认）。 +- 可选的 `channels.mattermost.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖默认账户选择。 ### Signal @@ -531,7 +531,7 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos channels: { signal: { enabled: true, - account: "+15555550123", // 可选账号绑定 + account: "+15555550123", // 可选账户绑定 dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -545,13 +545,13 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos **反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -- `channels.signal.account`：将渠道启动固定到特定 Signal 账号身份。 -- `channels.signal.configWrites`：允许或拒绝 Signal 发起的配置写入。 -- 可选的 `channels.signal.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 +- `channels.signal.account`：将渠道启动固定到某个特定 Signal 账户身份。 +- `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。 +- 可选的 `channels.signal.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖默认账户选择。 ### BlueBubbles -BlueBubbles 是推荐的 iMessage 路径（插件支持，配置位于 `channels.bluebubbles`）。 +BlueBubbles 是推荐的 iMessage 路径（由插件支持，在 `channels.bluebubbles` 下配置）。 ```json5 { @@ -567,13 +567,13 @@ BlueBubbles 是推荐的 iMessage 路径（插件支持，配置位于 `channels ``` - 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 可选的 `channels.bluebubbles.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目可将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 可选的 `channels.bluebubbles.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖默认账户选择。 +- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目可将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 - 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。 ### iMessage -OpenClaw 会启动 `imsg rpc`（基于 stdio 的 JSON-RPC）。无需守护进程或端口。 +OpenClaw 会启动 `imsg rpc`（基于 stdio 的 JSON-RPC）。不需要守护进程或端口。 ```json5 { @@ -597,17 +597,17 @@ OpenClaw 会启动 `imsg rpc`（基于 stdio 的 JSON-RPC）。无需守护进 } ``` -- 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 +- 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖默认账户选择。 -- 需要对 Messages 数据库授予完全磁盘访问权限。 -- 优先使用 `chat_id:` 目标。可使用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可以指向 SSH 包装脚本；设置 `remoteHost`（`host` 或 `user@host`）以便通过 SCP 获取附件。 -- `attachmentRoots` 和 `remoteAttachmentRoots` 用于限制传入附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 -- SCP 使用严格主机密钥校验，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 -- `channels.imessage.configWrites`：允许或拒绝 iMessage 发起的配置写入。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目可将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用标准化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 需要对 Messages 数据库授予完整磁盘访问权限。 +- 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。 +- `cliPath` 可以指向一个 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）用于通过 SCP 获取附件。 +- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制入站附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 +- SCP 使用严格主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 +- `channels.imessage.configWrites`：允许或拒绝由 iMessage 发起的配置写入。 +- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目可将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 - + ```bash #!/usr/bin/env bash @@ -618,7 +618,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix 由扩展支持，配置位于 `channels.matrix`。 +Matrix 由扩展支持，在 `channels.matrix` 下配置。 ```json5 { @@ -649,24 +649,24 @@ Matrix 由扩展支持，配置位于 `channels.matrix`。 ``` - Token 认证使用 `accessToken`；密码认证使用 `userId` + `password`。 -- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可用 `channels.matrix.accounts..proxy` 进行覆盖。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许使用私有/内部 homeserver。`proxy` 与该网络显式开关是相互独立的控制项。 -- `channels.matrix.defaultAccount` 用于在多账号设置中选择首选账号。 -- `channels.matrix.autoJoin` 默认是 `off`，因此受邀房间和新的私信式邀请都会被忽略，直到你设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。 -- `channels.matrix.execApprovals`：Matrix 原生 exec 批准投递和审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在 auto 模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，会激活 exec 批准。 +- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理转发 Matrix HTTP 流量。命名账户可通过 `channels.matrix.accounts..proxy` 覆盖它。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 与这个网络显式启用是独立控制项。 +- `channels.matrix.defaultAccount` 在多账户设置中选择首选账户。 +- `channels.matrix.autoJoin` 默认是 `off`，因此收到邀请的房间和新的 DM 风格邀请都会被忽略，直到你设置 `autoJoin: "allowlist"` 并配置 `autoJoinAllowlist`，或者设置 `autoJoin: "always"`。 +- `channels.matrix.execApprovals`：Matrix 原生 exec 审批交付和审批人授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在 auto 模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析到审批人时，exec 审批会激活。 - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的批准请求。 - - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：批准提示发送位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。 - - 每账号覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组到会话中：`per-user`（默认）按路由对端共享，`per-room` 则对每个私信房间隔离。 -- Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 + - `agentFilter`：可选智能体 ID 允许列表。省略则转发所有智能体的审批。 + - `sessionFilter`：可选会话键模式（子串或正则）。 + - `target`：发送审批提示的位置。`"dm"`（默认）、`"channel"`（发起房间）或 `"both"`。 + - 每账户覆盖：`channels.matrix.accounts..execApprovals`。 +- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组到会话中：`per-user`（默认）按路由对端共享，`per-room` 则将每个私信房间隔离。 +- Matrix 状态探测和实时目录查找与运行时流量使用相同的代理策略。 - 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 ### Microsoft Teams -Microsoft Teams 由扩展支持，配置位于 `channels.msteams`。 +Microsoft Teams 由扩展支持，在 `channels.msteams` 下配置。 ```json5 { @@ -682,11 +682,11 @@ Microsoft Teams 由扩展支持，配置位于 `channels.msteams`。 ``` - 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 -- 完整 Teams 配置（凭证、webhook、私信/群组策略、按团队/按频道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 +- 完整的 Teams 配置（凭据、webhook、私信/群组策略、按团队/按频道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 ### IRC -IRC 由扩展支持，配置位于 `channels.irc`。 +IRC 由扩展支持，在 `channels.irc` 下配置。 ```json5 { @@ -708,12 +708,12 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ``` - 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可选的 `channels.irc.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 完整 IRC 渠道配置（主机/端口/TLS/频道/允许列表/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 +- 可选的 `channels.irc.defaultAccount` 会在其匹配某个已配置账户 id 时覆盖默认账户选择。 +- 完整的 IRC 渠道配置（host/port/TLS/频道/允许列表/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 -### 多账号（所有渠道） +### 多账户（所有渠道） -为每个渠道运行多个账号（每个账号都有自己的 `accountId`）： +为每个渠道运行多个账户（每个账户都有自己的 `accountId`）： ```json5 { @@ -734,28 +734,28 @@ IRC 由扩展支持，配置位于 `channels.irc`。 } ``` -- 当省略 `accountId` 时使用 `default`（CLI + 路由）。 -- 环境变量 token 仅适用于 **default** 账号。 -- 基础渠道设置适用于所有账号，除非在每账号级别覆盖。 -- 使用 `bindings[].match.accountId` 将每个账号路由到不同智能体。 -- 如果你通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，而当前仍使用单账号顶层渠道配置，OpenClaw 会先把按账号划分的顶层单账号值提升进渠道账号映射，以保证原账号继续可用。大多数渠道会将它们移动到 `channels..accounts.default`；Matrix 则可以保留现有的匹配命名/默认目标。 -- 现有的仅渠道绑定（无 `accountId`）仍会匹配默认账号；账号作用域绑定仍然是可选的。 -- `openclaw doctor --fix` 也会修复混合形状配置，它会将按账号划分的顶层单账号值移动到该渠道所选的提升后账号中。大多数渠道使用 `accounts.default`；Matrix 则可以保留现有的匹配命名/默认目标。 +- 当省略 `accountId` 时，使用 `default`（CLI + 路由）。 +- 环境变量 token 仅适用于**默认**账户。 +- 基础渠道设置会应用到所有账户，除非被每账户配置覆盖。 +- 使用 `bindings[].match.accountId` 将每个账户路由到不同智能体。 +- 如果你通过 `openclaw channels add`（或渠道新手引导）添加了一个非默认账户，而当前仍使用单账户顶层渠道配置，OpenClaw 会先将顶层单账户值中属于账户作用域的内容提升到渠道账户映射中，以确保原始账户继续正常工作。大多数渠道会将其移到 `channels..accounts.default`；Matrix 则可以保留已有的匹配命名/默认目标。 +- 现有仅渠道绑定（无 `accountId`）仍会匹配默认账户；账户作用域绑定仍然是可选的。 +- `openclaw doctor --fix` 也会通过将账户作用域顶层单账户值移动到该渠道所选的提升账户中来修复混合结构。大多数渠道使用 `accounts.default`；Matrix 则可以保留已有的匹配命名/默认目标。 ### 其他扩展渠道 -许多扩展渠道都配置为 `channels.`，并在各自的渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 -请参阅完整渠道索引：[Channels](/zh-CN/channels)。 +许多扩展渠道都配置为 `channels.`，并在各自的专用渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 +请参阅完整渠道索引：[渠道](/zh-CN/channels)。 ### 群聊提及门控 -群组消息默认 **需要提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 +群组消息默认**要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 **提及类型：** - **元数据提及**：平台原生 @ 提及。在 WhatsApp self-chat 模式下会被忽略。 -- **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 仅当能够进行检测时（原生提及或至少一个模式），才会强制执行提及门控。 +- **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 +- 只有在可以检测提及时（原生提及或至少一个模式），才会强制执行提及门控。 ```json5 { @@ -768,7 +768,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。渠道可使用 `channels..historyLimit`（或每账号级别）进行覆盖。设置为 `0` 可禁用。 +`messages.groupChat.historyLimit` 设置全局默认值。渠道可以通过 `channels..historyLimit`（或每账户配置）覆盖。设置为 `0` 可禁用。 #### 私信历史限制 @@ -785,13 +785,13 @@ IRC 由扩展支持，配置位于 `channels.irc`。 } ``` -解析顺序：每私信覆盖 → 提供商默认值 → 无限制（全部保留）。 +解析顺序：每私信覆盖 → 提供商默认值 → 不限制（全部保留）。 支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 -#### Self-chat 模式 +#### self-chat 模式 -在 `allowFrom` 中包含你自己的号码即可启用 self-chat 模式（忽略原生 @ 提及，只响应文本模式）： +将你自己的号码包含在 `allowFrom` 中可启用 self-chat 模式（忽略原生 @ 提及，只响应文本模式）： ```json5 { @@ -818,12 +818,12 @@ IRC 由扩展支持，配置位于 `channels.irc`。 { commands: { native: "auto", // 在支持时注册原生命令 - text: true, // 解析聊天消息中的 /commands + text: true, // 在聊天消息中解析 /commands bash: false, // 允许 !（别名：/bash） bashForegroundMs: 2000, config: false, // 允许 /config debug: false, // 允许 /debug - restart: false, // 允许 /restart + gateway restart tool + restart: false, // 允许 /restart + Gateway 网关重启工具 allowFrom: { "*": ["user1"], discord: ["user:123"], @@ -836,15 +836,15 @@ IRC 由扩展支持，配置位于 `channels.irc`。 - 文本命令必须是带前导 `/` 的**独立**消息。 -- `native: "auto"` 会为 Discord/Telegram 打开原生命令，而保持 Slack 关闭。 -- 可按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前注册的命令。 +- `native: "auto"` 会为 Discord/Telegram 打开原生命令，Slack 保持关闭。 +- 可按渠道覆盖：`channels.discord.commands.native`（bool 或 `"auto"`）。`false` 会清除先前注册的命令。 - `channels.telegram.customCommands` 会添加额外的 Telegram 机器人菜单项。 -- `bash: true` 启用宿主 shell 的 `! `。要求 `tools.elevated.enabled`，且发送者位于 `tools.elevated.allowFrom.` 中。 -- `config: true` 启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化的 `/config set|unset` 写入还需要 `operator.admin`；只读的 `/config show` 对普通写权限 operator 客户端仍然可用。 -- `channels..configWrites` 用于按渠道控制配置变更（默认：true）。 -- 对于多账号渠道，`channels..accounts..configWrites` 也会控制针对该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 -- `allowFrom` 是按提供商划分的。设置后，它将成为**唯一**的授权来源（渠道允许列表/配对和 `useAccessGroups` 都会被忽略）。 -- 当 `allowFrom` 未设置时，`useAccessGroups: false` 允许命令绕过访问组策略。 +- `bash: true` 会为主机 shell 启用 `! `。要求 `tools.elevated.enabled`，且发送者位于 `tools.elevated.allowFrom.` 中。 +- `config: true` 启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化 `/config set|unset` 写入还要求 `operator.admin`；只读 `/config show` 对普通写入权限的 operator 客户端仍可用。 +- `channels..configWrites` 控制每个渠道的配置变更权限（默认：true）。 +- 对于多账户渠道，`channels..accounts..configWrites` 也会控制针对该账户的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 +- `allowFrom` 按提供商生效。设置后，它将成为**唯一**授权来源（渠道允许列表/配对及 `useAccessGroups` 都会被忽略）。 +- `useAccessGroups: false` 允许在未设置 `allowFrom` 时绕过访问组策略来执行命令。 @@ -864,7 +864,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示词的 Runtime 行中。如果未设置，OpenClaw 会从工作区开始向上遍历自动检测。 +可选的仓库根目录，会显示在系统提示的 Runtime 行中。如果未设置，OpenClaw 会从工作区向上遍历自动检测。 ```json5 { @@ -874,8 +874,8 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.skills` -适用于未设置 -`agents.list[].skills` 的智能体的可选默认 Skills 允许列表。 +为未设置 +`agents.list[].skills` 的智能体提供可选默认 Skills 允许列表。 ```json5 { @@ -891,14 +891,14 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ``` - 省略 `agents.defaults.skills` 表示默认不限制 Skills。 -- 省略 `agents.list[].skills` 表示继承默认值。 -- 设置 `agents.list[].skills: []` 表示没有 Skills。 +- 省略 `agents.list[].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 { @@ -908,9 +908,9 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.contextInjection` -控制何时将工作区 bootstrap 文件注入系统提示词。默认值：`"always"`。 +控制何时将工作区引导文件注入系统提示。默认值：`"always"`。 -- `"continuation-skip"`：安全续写回合（在助手已完成回复之后）会跳过工作区 bootstrap 的重新注入，从而减小提示词大小。心跳运行和压缩后的重试仍会重建上下文。 +- `"continuation-skip"`：安全续接轮次（在 assistant 完成响应之后）会跳过工作区引导的再次注入，以减少提示大小。Heartbeat 运行和压缩后重试仍会重建上下文。 ```json5 { @@ -920,7 +920,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.bootstrapMaxChars` -每个工作区 bootstrap 文件在截断前允许的最大字符数。默认值：`20000`。 +每个工作区引导文件在截断前允许的最大字符数。默认值：`20000`。 ```json5 { @@ -930,7 +930,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.bootstrapTotalMaxChars` -所有工作区 bootstrap 文件合计可注入的最大字符数。默认值：`150000`。 +所有工作区引导文件注入的总最大字符数。默认值：`150000`。 ```json5 { @@ -940,10 +940,10 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.bootstrapPromptTruncationWarning` -控制 bootstrap 上下文被截断时，是否向智能体显示警告文本。 +控制当 bootstrap 上下文被截断时，向智能体显示的警告文本。 默认值：`"once"`。 -- `"off"`：永不在系统提示词中注入警告文本。 +- `"off"`：绝不将警告文本注入系统提示。 - `"once"`：对每个唯一的截断签名仅注入一次警告（推荐）。 - `"always"`：只要存在截断，每次运行都注入警告。 @@ -955,11 +955,11 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，转录/工具图像块中最长边允许的最大像素尺寸。 +在调用提供商之前，会话/工具中的图像块允许的最长边最大像素值。 默认值：`1200`。 -较低的值通常会降低视觉 token 使用量，并减小截图密集型运行的请求负载大小。 -较高的值会保留更多视觉细节。 +较低的值通常会减少视觉 token 使用量和请求负载大小，适合截图较多的运行。 +较高的值则可保留更多视觉细节。 ```json5 { @@ -969,7 +969,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.userTimezone` -用于系统提示词上下文的时区（不影响消息时间戳）。未设置时回退到宿主机时区。 +用于系统提示上下文的时区（不影响消息时间戳）。会回退到主机时区。 ```json5 { @@ -979,7 +979,7 @@ IRC 由扩展支持，配置位于 `channels.irc`。 ### `agents.defaults.timeFormat` -系统提示词中的时间格式。默认值：`auto`（操作系统偏好）。 +系统提示中的时间格式。默认值：`auto`（操作系统偏好）。 ```json5 { @@ -1032,43 +1032,43 @@ IRC 由扩展支持，配置位于 `channels.irc`。 } ``` -- `model`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 +- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 字符串形式只设置主模型。 - - 对象形式设置主模型及按顺序排列的故障转移模型。 -- `imageModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 对象形式设置主模型及有序故障转移模型。 +- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 由 `image` 工具路径作为其视觉模型配置使用。 - - 当所选/默认模型无法接受图像输入时，也会用作后备路由。 -- `imageGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于共享的图像生成能力，以及未来任何生成图像的工具/插件表面。 - - 典型值：用于原生 Gemini 图像生成的 `google/gemini-3.1-flash-image-preview`，用于 fal 的 `fal/fal-ai/flux/dev`，或用于 OpenAI Images 的 `openai/gpt-image-1`。 - - 如果你直接选择某个 provider/model，还要配置对应的提供商认证/API key（例如 `google/*` 需要 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 需要 `OPENAI_API_KEY`，`fal/*` 需要 `FAL_KEY`）。 - - 若省略，`image_generate` 仍可推断出带认证的提供商默认值。它会先尝试当前默认提供商，再按 provider-id 顺序尝试其余已注册的图像生成提供商。 -- `musicGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于共享的音乐生成能力和内置的 `music_generate` 工具。 + - 当选中/默认模型不能接受图像输入时，也作为后备路由使用。 +- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由共享图像生成能力及未来任何生成图像的工具/插件接口使用。 + - 典型值：`google/gemini-3.1-flash-image-preview` 用于原生 Gemini 图像生成，`fal/fal-ai/flux/dev` 用于 fal，或 `openai/gpt-image-1` 用于 OpenAI Images。 + - 如果你直接选择某个提供商/模型，也要配置对应的提供商认证/API key（例如 `google/*` 需要 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 需要 `OPENAI_API_KEY`，`fal/*` 需要 `FAL_KEY`）。 + - 如果省略，`image_generate` 仍可推断出一个具备认证的默认提供商。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的图像生成提供商。 +- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由共享音乐生成能力和内置 `music_generate` 工具使用。 - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 - - 若省略，`music_generate` 仍可推断出带认证的提供商默认值。它会先尝试当前默认提供商，再按 provider-id 顺序尝试其余已注册的音乐生成提供商。 - - 如果你直接选择某个 provider/model，还要配置对应的提供商认证/API key。 -- `videoGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于共享的视频生成能力和内置的 `video_generate` 工具。 + - 如果省略，`music_generate` 仍可推断出一个具备认证的默认提供商。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的音乐生成提供商。 + - 如果你直接选择某个提供商/模型，也要配置对应的提供商认证/API key。 +- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由共享视频生成能力和内置 `video_generate` 工具使用。 - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 - - 若省略，`video_generate` 仍可推断出带认证的提供商默认值。它会先尝试当前默认提供商，再按 provider-id 顺序尝试其余已注册的视频生成提供商。 - - 如果你直接选择某个 provider/model，还要配置对应的提供商认证/API key。 - - 当前内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图片、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 -- `pdfModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 用于 `pdf` 工具的模型路由。 - - 若省略，PDF 工具会回退到 `imageModel`，再回退到已解析出的会话/默认模型。 -- `pdfMaxBytesMb`：在调用时未传入 `maxBytesMb` 的情况下，`pdf` 工具使用的默认 PDF 大小限制。 -- `pdfMaxPages`：`pdf` 工具在提取回退模式下默认考虑的最大页数。 -- `verboseDefault`：智能体的默认 verbose 级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 -- `elevatedDefault`：智能体的默认 elevated-output 级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 -- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果你省略 provider，OpenClaw 会先尝试别名，然后尝试与该模型 ID 精确匹配的唯一已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此请优先使用显式的 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置 provider/model，而不是暴露一个陈旧的已删除提供商默认值。 -- `models`：为 `/model` 配置的模型目录和允许列表。每个条目可包含 `alias`（快捷名）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 -- `params`：应用到所有模型的全局默认提供商参数。设置位置为 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 -- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（每模型）覆盖，再由 `agents.list[].params`（匹配的智能体 ID）按键覆盖。详情见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 -- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 和 fallback add/remove 命令）会保存为规范对象形式，并在可能时保留现有 fallback 列表。 -- `maxConcurrent`：跨会话允许的最大并行智能体运行数（每个会话自身仍然串行）。默认值：4。 + - 如果省略，`video_generate` 仍可推断出一个具备认证的默认提供商。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的视频生成提供商。 + - 如果你直接选择某个提供商/模型，也要配置对应的提供商认证/API key。 + - 内置的 Qwen 视频生成提供商目前最多支持 1 个输出视频、1 张输入图片、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 +- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由 `pdf` 工具用于模型路由。 + - 如果省略，PDF 工具会回退到 `imageModel`，再回退到已解析的会话/默认模型。 +- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb`，`pdf` 工具使用的默认 PDF 大小限制。 +- `pdfMaxPages`：`pdf` 工具在提取回退模式中考虑的默认最大页数。 +- `verboseDefault`：智能体的默认 verbose 级别。取值：`"off"`、`"on"`、`"full"`。默认：`"off"`。 +- `elevatedDefault`：智能体的默认 elevated-output 级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认：`"on"`。 +- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，再尝试与该精确模型 id 唯一匹配的已配置提供商，最后才回退到已配置默认提供商（这是已弃用的兼容行为，因此建议优先使用显式 `provider/model`）。如果该提供商不再公开已配置默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是继续暴露一个已失效、已移除提供商的默认值。 +- `models`：为 `/model` 配置的模型目录和允许列表。每个条目可包含 `alias`（快捷方式）和 `params`（提供商专用参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 +- `params`：应用于所有模型的全局默认提供商参数。设置在 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 +- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配 agent id）按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 +- 会变更这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及后备项添加/删除命令）会保存为规范对象形式，并尽可能保留现有后备列表。 +- `maxConcurrent`：跨会话并行运行的最大智能体数量（每个会话本身仍是串行的）。默认：4。 -**内置别名简写**（仅在模型存在于 `agents.defaults.models` 中时适用）： +**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： | 别名 | 模型 | | ------------------- | -------------------------------------- | @@ -1083,13 +1083,13 @@ IRC 由扩展支持，配置位于 `channels.irc`。 你自己配置的别名始终优先于默认值。 -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` 可禁用它。 +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 { @@ -1117,13 +1117,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- CLI 后端以文本为主；工具始终被禁用。 +- CLI 后端以文本为主；工具始终禁用。 - 当设置了 `sessionArg` 时支持会话。 -- 当 `imageArg` 可接受文件路径时，支持图像透传。 +- 当 `imageArg` 接受文件路径时支持图像透传。 ### `agents.defaults.heartbeat` -周期性心跳运行。 +定期心跳运行。 ```json5 { @@ -1133,8 +1133,8 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 every: "30m", // 0m 表示禁用 model: "openai/gpt-5.4-mini", includeReasoning: false, - lightContext: false, // 默认：false；true 时仅保留工作区 bootstrap 文件中的 HEARTBEAT.md - isolatedSession: false, // 默认：false；true 时每次心跳都在全新会话中运行（无对话历史） + lightContext: false, // 默认：false；true 仅保留工作区引导文件中的 HEARTBEAT.md + isolatedSession: false, // 默认：false；true 在全新会话中运行每次心跳（无对话历史） session: "main", to: "+15555550123", directPolicy: "allow", // allow（默认）| block @@ -1148,13 +1148,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 +- `every`：时长字符串（ms/s/m/h）。默认：`30m`（API key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 - `suppressToolErrorWarnings`：为 true 时，在心跳运行期间抑制工具错误警告负载。 -- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并输出 `reason=dm-blocked`。 -- `lightContext`：为 true 时，心跳运行使用轻量 bootstrap 上下文，并仅保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次心跳运行都在一个无先前对话历史的新会话中进行。与 cron 的 `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次心跳的 token 成本从约 100K 降低到约 2-5K。 +- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会阻止直接目标投递，并发出 `reason=dm-blocked`。 +- `lightContext`：为 true 时，心跳运行使用轻量 bootstrap 上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：为 true 时，每次心跳都在没有先前对话历史的新会话中运行。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次心跳的 token 成本从约 100K 降到约 2-5K。 - 每智能体：设置 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。 -- 心跳会运行完整智能体回合——间隔越短，消耗的 token 越多。 +- 心跳会执行完整的智能体轮次——间隔越短，消耗的 token 越多。 ### `agents.defaults.compaction` @@ -1164,13 +1164,14 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 defaults: { compaction: { mode: "safeguard", // default | safeguard + provider: "my-provider", // 已注册 compaction 提供商插件的 id（可选） timeoutSeconds: 900, reserveTokensFloor: 24000, 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.", // 当 identifierPolicy=custom 时使用 postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入 model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于 compaction 的模型覆盖 - notifyUser: true, // 在 compaction 开始时向用户发送简短通知（默认：false） + notifyUser: true, // compaction 开始时发送简短通知给用户（默认：false） memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1184,17 +1185,18 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ``` - `mode`：`default` 或 `safeguard`（对长历史执行分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 放弃单次 compaction 操作前允许的最长秒数。默认值：`900`。 -- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内建的不透明标识符保留指导。 +- `provider`：已注册 compaction 提供商插件的 id。设置后，会调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置实现。设置提供商会强制 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `timeoutSeconds`：OpenClaw 在中止单次 compaction 操作前允许的最大秒数。默认：`900`。 +- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要时预置内建的不透明标识符保留指导。 - `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 -- `postCompactionSections`：compaction 后可选重新注入的 AGENTS.md H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。当未设置或显式设为该默认对时，也接受旧版 `Every Session`/`Safety` 标题作为兼容回退。 -- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当主会话应继续使用某个模型，但 compaction 摘要应使用另一个模型时可使用它；未设置时，compaction 使用会话的主模型。 -- `notifyUser`：为 `true` 时，在 compaction 开始时向用户发送简短通知（例如“Compacting context...”）。默认禁用，以保持 compaction 静默。 -- `memoryFlush`：在自动 compaction 之前执行静默智能体回合，以存储持久记忆。若工作区为只读，则会跳过。 +- `postCompactionSections`：compaction 后可选重新注入的 AGENTS.md H2/H3 章节名称。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。当未设置，或显式设为该默认对时，较旧的 `Every Session`/`Safety` 标题也会作为兼容回退被接受。 +- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。用于让主会话继续使用一个模型，而 compaction 摘要改用另一个模型；未设置时，compaction 使用会话的主模型。 +- `notifyUser`：为 `true` 时，在 compaction 开始时向用户发送简短通知（例如 “Compacting context...”）。默认禁用，以保持 compaction 静默。 +- `memoryFlush`：在自动 compaction 前执行静默智能体轮次，用于存储持久记忆。工作区只读时会跳过。 ### `agents.defaults.contextPruning` -在发送到 LLM 之前，从内存上下文中修剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 +在发送给 LLM 之前，从内存上下文中修剪**旧工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -1218,23 +1220,23 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 -- `mode: "cache-ttl"` 会启用修剪过程。 -- `ttl` 控制多长时间后才能再次运行修剪（自上次缓存触碰之后）。 -- 修剪会先对过大的工具结果进行软修剪，必要时再硬清空较旧的工具结果。 +- `mode: "cache-ttl"` 启用修剪流程。 +- `ttl` 控制多久后才能再次运行修剪（以上一次缓存触达为准）。 +- 修剪会先对过大的工具结果做软裁剪，必要时再对更旧的工具结果做硬清空。 -**软修剪**会保留开头和结尾，并在中间插入 `...`。 +**软裁剪**保留开头和结尾，并在中间插入 `...`。 **硬清空**会用占位符替换整个工具结果。 说明： -- 图像块永远不会被修剪/清空。 -- 各种比率按字符计算（近似），不是精确 token 数。 -- 如果助手消息数量少于 `keepLastAssistants`，则跳过修剪。 +- 图像块永远不会被裁剪/清空。 +- 各种比例基于字符数（近似），不是精确 token 数。 +- 如果 assistant 消息少于 `keepLastAssistants`，会跳过修剪。 -行为详情请参阅 [Session Pruning](/zh-CN/concepts/session-pruning)。 +行为细节参见 [会话修剪](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -1252,13 +1254,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 -- 渠道覆盖：`channels..blockStreamingCoalesce`（以及每账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 -- `humanDelay`：分块回复之间的随机停顿。`natural` = 800–2500ms。每智能体覆盖：`agents.list[].humanDelay`。 +- 非 Telegram 渠道需要显式 `*.blockStreaming: true` 才会启用分块回复。 +- 渠道覆盖：`channels..blockStreamingCoalesce`（以及每账户变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 +- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。每智能体覆盖：`agents.list[].humanDelay`。 -关于行为和分块细节，请参阅 [Streaming](/zh-CN/concepts/streaming)。 +行为和分块细节参见 [流式传输](/zh-CN/concepts/streaming)。 -### 输入中指示器 +### 输入状态指示器 ```json5 { @@ -1271,16 +1273,16 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 默认值：对于私聊/被提及消息使用 `instant`，对于未被提及的群聊使用 `message`。 +- 默认值：私聊/提及时为 `instant`，未提及的群聊中为 `message`。 - 每会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 -请参阅 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 +参见 [输入状态指示器](/zh-CN/concepts/typing-indicators)。 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南请参阅 [Sandboxing](/zh-CN/gateway/sandboxing)。 +为嵌入式智能体启用可选沙箱隔离。完整指南参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -1326,7 +1328,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // 也支持 SecretRef / 内联内容： + // 也支持 SecretRefs / 内联内容： // 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" }, @@ -1383,16 +1385,16 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `ssh`：通用 SSH 远程运行时 - `openshell`：OpenShell 运行时 -当选择 `backend: "openshell"` 时，运行时专属设置会移动到 +当选择 `backend: "openshell"` 时，运行时专用设置会移到 `plugins.entries.openshell.config`。 **SSH 后端配置：** -- `target`：形如 `user@host[:port]` 的 SSH 目标 +- `target`：`user@host[:port]` 形式的 SSH 目标 - `command`：SSH 客户端命令（默认：`ssh`） - `workspaceRoot`：用于每作用域工作区的远程绝对根路径 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 -- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件 +- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其物化为临时文件 - `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 **SSH 认证优先级：** @@ -1400,26 +1402,26 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 基于 SecretRef 的 `*Data` 值会在沙箱会话开始前从活动 secrets 运行时快照中解析 +- 基于 SecretRef 的 `*Data` 值会在沙箱会话启动前，从活跃 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重建后仅对远程工作区执行一次初始播种 -- 之后保持远程 SSH 工作区为规范源 +- 创建或重建后只会为远程工作区做一次初始化 +- 之后保持远程 SSH 工作区为规范副本 - 通过 SSH 路由 `exec`、文件工具和媒体路径 -- 不会自动将远程更改同步回宿主机 +- 不会自动将远程变更同步回主机 - 不支持沙箱浏览器容器 **工作区访问：** -- `none`：每作用域沙箱工作区位于 `~/.openclaw/sandboxes` +- `none`：位于 `~/.openclaw/sandboxes` 下的每作用域沙箱工作区 - `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent` - `rw`：智能体工作区以读写方式挂载到 `/workspace` **作用域：** - `session`：每会话一个容器 + 工作区 -- `agent`：每个智能体一个容器 + 工作区（默认） +- `agent`：每智能体一个容器 + 工作区（默认） - `shared`：共享容器和工作区（无跨会话隔离） **OpenShell 插件配置：** @@ -1450,30 +1452,30 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **OpenShell 模式：** -- `mirror`：在 exec 之前先将本地同步到远程，exec 后再同步回来；本地工作区保持为规范源 -- `remote`：在创建沙箱时仅对远程执行一次播种，之后保持远程工作区为规范源 +- `mirror`：在 exec 前将本地内容同步到远端，在 exec 后再同步回来；本地工作区保持为规范副本 +- `remote`：在创建沙箱时只进行一次本地到远端的初始化，之后保持远端工作区为规范副本 -在 `remote` 模式下，于 OpenClaw 外部对宿主机本地所做的编辑，在播种步骤之后不会自动同步进沙箱。 -传输方式是通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期和可选 mirror 同步。 +在 `remote` 模式下，种子步骤之后，在 OpenClaw 之外对主机本地所做的编辑不会自动同步到沙箱中。 +传输通过 SSH 进入 OpenShell 沙箱，但沙箱生命周期和可选 mirror 同步由插件自行管理。 -**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 +**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。它需要网络出口、可写根文件系统和 root 用户。 **容器默认使用 `network: "none"`** ——如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 -默认情况下会阻止 `"host"`。除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急模式），否则也会阻止 `"container:"`。 +`"host"` 会被阻止。默认也会阻止 `"container:"`，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急模式）。 -**传入附件** 会被暂存到活动工作区中的 `media/inbound/*`。 +**入站附件** 会被暂存到活动工作区中的 `media/inbound/*`。 -**`docker.binds`** 用于挂载额外的宿主目录；全局和每智能体的 binds 会合并。 +**`docker.binds`** 会挂载额外的主机目录；全局和每智能体的 binds 会合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。会将 noVNC URL 注入系统提示词。不要求在 `openclaw.json` 中启用 `browser.enabled`。 -noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出短时效 token URL（而不是在共享 URL 中暴露密码）。 +**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会注入系统提示。不需要在 `openclaw.json` 中启用 `browser.enabled`。 +noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出短期有效的 token URL（而不是在共享 URL 中公开密码）。 -- `allowHostControl: false`（默认）会阻止沙箱隔离会话以宿主浏览器为目标。 -- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。只有在你明确需要全局 bridge 连通性时才设置为 `bridge`。 -- `cdpSourceRange` 可选，用于在容器边界处将 CDP 入站限制在某个 CIDR 范围（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅将额外宿主目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 -- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器宿主做了调优： +- `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。 +- `network` 默认是 `openclaw-sandbox-browser`（专用桥接网络）。仅在你明确想要全局桥接连通性时，才设为 `bridge`。 +- `cdpSourceRange` 可选地将 CDP 入口在容器边缘限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。 +- `sandbox.browser.binds` 仅为沙箱浏览器容器挂载额外的主机目录。设置后（包括 `[]`），它会替代浏览器容器上的 `docker.binds`。 +- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机做了调优： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1491,19 +1493,21 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出短时效 token - `--no-zygote` - `--metrics-recording-only` - `--disable-extensions`（默认启用） - - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` 默认启用；如果 WebGL/3D 使用场景需要，可以通过 - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用它们。 + - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` 默认启用； + 如果 WebGL/3D 使用场景需要它们，可通过 + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用。 - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展，如果你的工作流 - 依赖它们。 + 依赖扩展。 - `--renderer-process-limit=2` 可通过 - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 将使用 Chromium 的 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设置为 `0` 可使用 Chromium 的 默认进程限制。 - - 若启用了 `noSandbox`，还会额外加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - - 这些默认值是容器镜像基线；如需修改容器默认值，请使用带自定义 entrypoint 的自定义浏览器镜像。 + - 当启用 `noSandbox` 时，还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。 + - 这些默认值是容器镜像基线；如需更改容器默认行为，请使用带自定义 + entrypoint 的自定义浏览器镜像。 -浏览器沙箱隔离和 `sandbox.docker.binds` 当前仅支持 Docker。 +浏览器沙箱隔离和 `sandbox.docker.binds` 目前仅支持 Docker。 构建镜像： @@ -1529,7 +1533,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 reasoningDefault: "on", // 每智能体 reasoning 可见性覆盖 fastModeDefault: false, // 每智能体快速模式覆盖 params: { cacheRetention: "none" }, // 按键覆盖匹配 defaults.models params - skills: ["docs-search"], // 设置时替换 agents.defaults.skills + skills: ["docs-search"], // 设置时会替换 agents.defaults.skills identity: { name: "Samantha", theme: "helpful sloth", @@ -1560,26 +1564,26 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 } ``` -- `id`：稳定的智能体 ID（必填）。 -- `default`：若设置了多个，则第一个生效（会记录警告）。若都未设置，则 `list` 中第一个条目为默认值。 -- `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`）。在未设置每消息或会话覆盖时，覆盖该智能体的 `agents.defaults.thinkingDefault`。 -- `reasoningDefault`：可选的每智能体默认 reasoning 可见性（`on | off | stream`）。在未设置每消息或会话 reasoning 覆盖时生效。 -- `fastModeDefault`：可选的每智能体默认快速模式（`true | false`）。在未设置每消息或会话快速模式覆盖时生效。 -- `runtime`：可选的每智能体运行时描述符。当智能体默认应使用 ACP harness 会话时，使用 `type: "acp"` 以及 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 +- `id`：稳定的智能体 id（必填）。 +- `default`：设置多个时，第一个生效（会记录警告）。如果都未设置，则列表中的第一个条目是默认值。 +- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖两者（`[]` 会禁用全局后备）。仅覆盖 `primary` 的 cron 作业仍会继承默认后备，除非你设置 `fallbacks: []`。 +- `params`：每智能体流参数，会合并到 `agents.defaults.models` 中选定的模型项之上。可用于智能体特定覆盖，如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。 +- `skills`：可选的每智能体 Skills 允许列表。如果省略，并且设置了 `agents.defaults.skills`，智能体会继承它；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。 +- `thinkingDefault`：可选的每智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。当未设置每消息或会话覆盖时，它会覆盖该智能体的 `agents.defaults.thinkingDefault`。 +- `reasoningDefault`：可选的每智能体默认 reasoning 可见性（`on | off | stream`）。当未设置每消息或会话 reasoning 覆盖时应用。 +- `fastModeDefault`：可选的每智能体默认快速模式（`true | false`）。当未设置每消息或会话快速模式覆盖时应用。 +- `runtime`：可选的每智能体运行时描述符。当智能体默认应使用 ACP harness 会话时，使用 `type: "acp"` 并设置 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 - `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。 -- `identity` 会派生默认值：从 `emoji` 派生 `ackReaction`，从 `name`/`emoji` 派生 `mentionPatterns`。 -- `subagents.allowAgents`：用于 `sessions_spawn` 的智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝目标运行在非沙箱模式下。 +- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。 +- `subagents.allowAgents`：`sessions_spawn` 的智能体 id 允许列表（`["*"]` = 任意；默认：仅相同智能体）。 +- 沙箱继承保护：如果请求方会话处于沙箱中，`sessions_spawn` 会拒绝运行目标为非沙箱隔离状态的请求。 - `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。 --- ## 多智能体路由 -在一个 Gateway 网关内运行多个隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关中运行多个隔离智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -1598,12 +1602,12 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 绑定匹配字段 -- `type`（可选）：普通路由用 `route`（缺失时默认即为 route），持久 ACP 对话绑定用 `acp`。 +- `type`（可选）：普通路由用 `route`（缺失时默认 route），持久 ACP 对话绑定用 `acp` - `match.channel`（必填） -- `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号） +- `match.accountId`（可选；`*` = 任意账户；省略 = 默认账户） - `match.peer`（可选；`{ kind: direct|group|channel, id }`） -- `match.guildId` / `match.teamId`（可选；渠道特定） -- `acp`（可选；仅适用于 `type: "acp"`）：`{ mode, label, cwd, backend }` +- `match.guildId` / `match.teamId`（可选；渠道专用） +- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }` **确定性匹配顺序：** @@ -1614,9 +1618,9 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 5. `match.accountId: "*"`（渠道级） 6. 默认智能体 -在每一层级内，首个匹配的 `bindings` 条目胜出。 +在每一层中，第一个匹配的 `bindings` 条目生效。 -对于 `type: "acp"` 的条目，OpenClaw 会按精确会话身份（`match.channel` + account + `match.peer.id`）进行解析，不使用上述 route 绑定层级顺序。 +对于 `type: "acp"` 条目，OpenClaw 会按精确对话身份（`match.channel` + account + `match.peer.id`）解析，不会使用上面的 route 绑定层级顺序。 ### 每智能体访问配置 @@ -1667,7 +1671,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - + ```json5 { @@ -1713,7 +1717,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 -有关优先级细节，请参阅 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 +优先级细节参见 [多智能体沙箱隔离和工具](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1739,7 +1743,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 超过此 token 数时跳过父线程 fork（0 表示禁用） + parentForkMaxTokens: 100000, // 超过该 token 数则跳过父线程 fork（0 表示禁用） maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1751,8 +1755,8 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, threadBindings: { enabled: true, - idleHours: 24, // 默认非活动自动取消聚焦时长（小时）（`0` 表示禁用） - maxAgeHours: 0, // 默认硬性最大存活时长（小时）（`0` 表示禁用） + idleHours: 24, // 默认无活动自动取消聚焦时长（小时，`0` 表示禁用） + maxAgeHours: 0, // 默认硬性最大生命周期（小时，`0` 表示禁用） }, mainKey: "main", // 旧版（运行时始终使用 "main"） agentToAgent: { maxPingPongTurns: 5 }, @@ -1767,34 +1771,34 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在同一渠道上下文中，每个发送者拥有独立会话。 - - `global`：一个渠道上下文中的所有参与者共享单个会话（仅在确实需要共享上下文时使用）。 -- **`dmScope`**：私信如何分组。 + - `per-sender`（默认）：在一个渠道上下文中，每个发送者都有独立会话。 + - `global`：一个渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。 +- **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - - `per-peer`：跨渠道按发送者 ID 隔离。 + - `per-peer`：按发送者 id 跨渠道隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 -- **`identityLinks`**：将规范 ID 映射到带提供商前缀的对端，以实现跨渠道会话共享。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。如果两者同时配置，则先到期者生效。 -- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 被接受为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建 fork 线程会话时，允许父会话 `totalTokens` 的最大值（默认 `100000`）。 - - 如果父会话 `totalTokens` 高于此值，OpenClaw 会启动一个全新的线程会话，而不是继承父会话转录历史。 - - 设置为 `0` 可禁用该保护，并始终允许父会话 fork。 -- **`mainKey`**：旧版字段。运行时现在始终对主私聊桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体之间在 agent-to-agent 交互中可进行的最大往返回复轮数（整数，范围：`0`–`5`）。`0` 表示禁用 ping-pong 链式回复。 -- **`sendPolicy`**：可按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。首个 deny 生效。 + - `per-account-channel-peer`：按账户 + 渠道 + 发送者隔离（推荐用于多账户）。 +- **`identityLinks`**：将规范 id 映射到带提供商前缀的 peer，用于跨渠道共享会话。 +- **`reset`**：主重置策略。`daily` 在本地时间 `atHour` 重置；`idle` 在 `idleMinutes` 后重置。当两者都配置时，哪个先到期就先触发。 +- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 接受为 `direct` 的别名。 +- **`parentForkMaxTokens`**：创建分叉线程会话时允许的父会话 `totalTokens` 最大值（默认 `100000`）。 + - 如果父会话 `totalTokens` 高于此值，OpenClaw 会启动一个新的线程会话，而不是继承父会话历史记录。 + - 设为 `0` 可禁用此保护，并始终允许父会话分叉。 +- **`mainKey`**：旧字段。运行时现在始终使用 `"main"` 作为主私聊桶。 +- **`agentToAgent.maxPingPongTurns`**：智能体到智能体交换期间，智能体之间允许的最大往返回复轮次（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链式交互。 +- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 生效。 - **`maintenance`**：会话存储清理 + 保留控制。 - - `mode`：`warn` 仅发出警告；`enforce` 会执行清理。 - - `pruneAfter`：过期条目的年龄截止值（默认 `30d`）。 - - `maxEntries`：`sessions.json` 中允许的最大条目数（默认 `500`）。 - - `rotateBytes`：当 `sessions.json` 超过该大小时轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` 转录归档的保留期。默认等于 `pruneAfter`；设为 `false` 可禁用。 - - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下记录警告；在 `enforce` 模式下优先移除最旧的工件/会话。 + - `mode`：`warn` 仅发出警告；`enforce` 应用清理。 + - `pruneAfter`：过期条目的年龄阈值（默认 `30d`）。 + - `maxEntries`：`sessions.json` 中条目的最大数量（默认 `500`）。 + - `rotateBytes`：当 `sessions.json` 超过此大小时轮转（默认 `10mb`）。 + - `resetArchiveRetention`：`*.reset.` 会话归档的保留时长。默认与 `pruneAfter` 一致；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下记录警告；在 `enforce` 模式下会优先删除最旧的制品/会话。 - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认非活动自动取消聚焦时长（小时）（`0` 表示禁用；提供商可覆盖） - - `maxAgeHours`：默认硬性最大存活时长（小时）（`0` 表示禁用；提供商可覆盖） + - `idleHours`：默认按小时计算的无活动自动取消聚焦时长（`0` 表示禁用；提供商可覆盖） + - `maxAgeHours`：默认按小时计算的硬性最大生命周期（`0` 表示禁用；提供商可覆盖） @@ -1832,36 +1836,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}` | 当前 thinking 级别 | `high`、`low`、`off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| 变量 | 描述 | 示例 | +| ----------------- | ---------------- | --------------------------- | +| `{model}` | 短模型名 | `claude-opus-4-6` | +| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | +| `{provider}` | 提供商名称 | `anthropic` | +| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | +| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 -### Ack 反应 +### 确认反应 -- 默认使用当前智能体的 `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 上回复后移除 ack。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上回复后移除确认反应。 - `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 - 在 Slack 和 Discord 上，若未设置，则当 ack 反应处于活动状态时保持状态反应启用。 + 在 Slack 和 Discord 上，未设置时，只要确认反应处于激活状态，就会保持状态反应启用。 在 Telegram 上，需要显式设为 `true` 才会启用生命周期状态反应。 -### 传入去抖 +### 入站防抖 -会将同一发送者快速连续发送的纯文本消息合并为一次智能体回合。媒体/附件会立即冲刷。控制命令会绕过去抖。 +将同一发送者快速发送的纯文本消息批处理为一次智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -1906,16 +1910,16 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - `auto` 控制自动 TTS。`/tts off|always|inbound|tagged` 会按会话覆盖。 - `summaryModel` 会覆盖 `agents.defaults.model.primary` 用于自动摘要。 -- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需显式启用）。 +- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需要显式启用）。 - API key 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 -- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置、然后 `OPENAI_TTS_BASE_URL`、最后 `https://api.openai.com/v1`。 -- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI-compatible TTS 服务器，并放宽对模型/语音的校验。 +- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置，其次是 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。 +- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI-compatible TTS 服务器，并放宽 model/voice 校验。 --- ## Talk -Talk 模式的默认值（macOS/iOS/Android）。 +Talk 模式（macOS/iOS/Android）的默认值。 ```json5 { @@ -1940,12 +1944,12 @@ Talk 模式的默认值（macOS/iOS/Android）。 ``` - 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 -- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.`。 +- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.`。 - Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 -- `providers.*.apiKey` 支持明文字符串或 SecretRef 对象。 -- 仅当未配置 Talk API key 时，才会应用 `ELEVENLABS_API_KEY` 回退。 -- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 -- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久才发送转录。未设置时保持平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。 +- 只有在未配置 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。 +- `providers.*.voiceAliases` 让 Talk 指令可以使用友好的名称。 +- `silenceTimeoutMs` 控制 Talk 模式在用户静默后等待多久才发送转录文本。未设置时将保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- @@ -1953,37 +1957,37 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### 工具配置 -`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置一个基础允许列表： +`tools.profile` 会先设置一个基础允许列表，然后再应用 `tools.allow`/`tools.deny`： -本地新手引导在新建本地配置且未设置时，默认使用 `tools.profile: "coding"`（已有显式 profile 会保留）。 +当未设置时，本地新手引导会将新的本地配置默认写为 `tools.profile: "coding"`（现有显式配置会被保留）。 | 配置 | 包含内容 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | 仅 `session_status` | +| `minimal` | 仅 `session_status` | | `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | | `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | | `full` | 无限制（与未设置相同） | ### 工具组 -| 组 | 工具 | -| -------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | -| `group:fs` | `read`、`write`、`edit`、`apply_patch` | -| `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | -| `group:memory` | `memory_search`、`memory_get` | -| `group:web` | `web_search`、`x_search`、`web_fetch` | -| `group:ui` | `browser`、`canvas` | -| `group:automation` | `cron`、`gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | -| `group:openclaw` | 所有内置工具（不包括 provider 插件） | +| 组 | 工具 | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | +| `group:fs` | `read`、`write`、`edit`、`apply_patch` | +| `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | +| `group:memory` | `memory_search`、`memory_get` | +| `group:web` | `web_search`、`x_search`、`web_fetch` | +| `group:ui` | `browser`、`canvas` | +| `group:automation` | `cron`、`gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | +| `group:openclaw` | 所有内置工具（不含提供商插件） | ### `tools.allow` / `tools.deny` -全局工具允许/拒绝策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭也会应用。 +全局工具允许/拒绝策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱已关闭也会应用。 ```json5 { @@ -1993,7 +1997,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.byProvider` -进一步限制特定提供商或模型的工具。顺序：基础 profile → provider profile → allow/deny。 +进一步限制特定提供商或模型可用的工具。顺序：基础配置 → 提供商配置 → allow/deny。 ```json5 { @@ -2026,8 +2030,8 @@ Talk 模式的默认值（macOS/iOS/Android）。 ``` - 每智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。 -- `/elevated on|off|ask|full` 会按会话保存状态；内联指令仅适用于单条消息。 -- Elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，若 exec 目标是 `node` 则使用 `node`）。 +- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅作用于单条消息。 +- Elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，或当 exec 目标为 `node` 时使用 `node`）。 ### `tools.exec` @@ -2051,8 +2055,8 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.loopDetection` -工具循环安全检查**默认禁用**。设置 `enabled: true` 可启用检测。 -设置可在 `tools.loopDetection` 中全局定义，也可在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 +工具循环安全检查默认**关闭**。设置 `enabled: true` 可启用检测。 +可以在全局 `tools.loopDetection` 中定义设置，并在每智能体 `agents.list[].tools.loopDetection` 中覆盖。 ```json5 { @@ -2073,14 +2077,14 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- `historySize`：用于循环分析所保留的最大工具调用历史数。 -- `warningThreshold`：重复无进展模式触发警告的阈值。 +- `historySize`：为循环分析保留的最大工具调用历史长度。 +- `warningThreshold`：对重复无进展模式发出警告的阈值。 - `criticalThreshold`：阻止严重循环的更高重复阈值。 -- `globalCircuitBreakerThreshold`：任何无进展运行触发硬停止的阈值。 +- `globalCircuitBreakerThreshold`：任何无进展运行的硬停止阈值。 - `detectors.genericRepeat`：对重复的同工具/同参数调用发出警告。 -- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。 -- `detectors.pingPong`：对交替出现的无进展对模式发出警告/阻止。 -- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证会失败。 +- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展轮询发出警告/阻止。 +- `detectors.pingPong`：对交替出现的无进展成对模式发出警告/阻止。 +- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，校验会失败。 ### `tools.web` @@ -2114,7 +2118,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.media` -配置传入媒体理解（图像/音频/视频）： +配置入站媒体理解（图像/音频/视频）： ```json5 { @@ -2148,29 +2152,29 @@ Talk 模式的默认值（macOS/iOS/Android）。 -**Provider 条目**（`type: "provider"` 或省略）： +**提供商条目**（`type: "provider"` 或省略）： -- `provider`：API 提供商 ID（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） -- `model`：模型 ID 覆盖 +- `provider`：API 提供商 id（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） +- `model`：模型 id 覆盖 - `profile` / `preferredProfile`：`auth-profiles.json` 配置选择 **CLI 条目**（`type: "cli"`）： -- `command`：要执行的可执行文件 +- `command`：要运行的可执行文件 - `args`：模板化参数（支持 `{{MediaPath}}`、`{{Prompt}}`、`{{MaxChars}}` 等） **通用字段：** - `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai`/`anthropic`/`minimax` → image，`google` → image+audio+video，`groq` → audio。 -- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：每条目覆盖。 +- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：每条目的覆盖值。 - 失败时会回退到下一个条目。 -Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 +提供商认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 **异步完成字段：** -- `asyncCompletion.directSend`：当为 `true` 时，已完成的异步 `music_generate` - 和 `video_generate` 任务会先尝试直接渠道投递。默认值：`false` +- `asyncCompletion.directSend`：为 `true` 时，已完成的异步 `music_generate` + 和 `video_generate` 任务会优先尝试直接渠道投递。默认：`false` （旧版请求方会话唤醒/模型投递路径）。 @@ -2190,9 +2194,9 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m ### `tools.sessions` -控制 session 工具（`sessions_list`、`sessions_history`、`sessions_send`）可以针对哪些会话。 +控制哪些会话可以被会话工具（`sessions_list`、`sessions_history`、`sessions_send`）作为目标。 -默认值：`tree`（当前会话 + 由其派生出的会话，例如子智能体）。 +默认值：`tree`（当前会话 + 由其派生的会话，例如子智能体）。 ```json5 { @@ -2208,10 +2212,10 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m 说明： - `self`：仅当前会话键。 -- `tree`：当前会话 + 由当前会话派生出的会话（子智能体）。 -- `agent`：属于当前智能体 ID 的任意会话（如果你在同一智能体 ID 下运行按发送者划分的会话，则可能包含其他用户）。 +- `tree`：当前会话 + 由当前会话派生的会话（子智能体）。 +- `agent`：属于当前智能体 id 的任意会话（如果你在同一个智能体 id 下运行按发送者隔离的会话，可能包含其他用户）。 - `all`：任意会话。跨智能体定向仍需要 `tools.agentToAgent`。 -- 沙箱钳制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 +- 沙箱收紧：当当前会话处于沙箱隔离状态，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 ### `tools.sessions_spawn` @@ -2222,8 +2226,8 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m tools: { sessions_spawn: { attachments: { - enabled: false, // 显式启用：设置为 true 以允许内联文件附件 - maxTotalBytes: 5242880, // 全部文件总计 5 MB + enabled: false, // 显式启用：设为 true 可允许内联文件附件 + maxTotalBytes: 5242880, // 所有文件总计 5 MB maxFiles: 50, maxFileBytes: 1048576, // 每个文件 1 MB retainOnSessionKeep: false, // 当 cleanup="keep" 时保留附件 @@ -2235,16 +2239,16 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m 说明： -- 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 -- 文件会实体化到子工作区的 `.openclaw/attachments//` 中，并附带 `.manifest.json`。 -- 附件内容会自动从转录持久化中脱敏。 -- Base64 输入会进行严格字母表/填充校验，并在解码前进行大小保护检查。 +- 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝它们。 +- 文件会物化到子工作区的 `.openclaw/attachments//` 下，并带有 `.manifest.json`。 +- 附件内容会自动从会话记录持久化中脱敏。 +- Base64 输入会执行严格字母表/填充校验，并在解码前进行大小保护。 - 文件权限为目录 `0700`、文件 `0600`。 -- 清理遵循 `cleanup` 策略：`delete` 总会移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留附件。 +- 清理由 `cleanup` 策略决定：`delete` 始终会删除附件；只有在 `retainOnSessionKeep: true` 时，`keep` 才会保留它们。 ### `tools.experimental` -实验性内置工具开关。默认关闭，除非有运行时特定的自动启用规则。 +实验性内置工具标志。默认关闭，除非某条运行时专用自动启用规则生效。 ```json5 { @@ -2258,9 +2262,9 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m 说明： -- `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 +- `planTool`：为非琐碎、多步骤工作跟踪启用结构化 `update_plan` 工具。 - 默认值：对非 OpenAI 提供商为 `false`。OpenAI 和 OpenAI Codex 运行会自动启用它。 -- 启用后，系统提示词还会加入使用指导，使模型仅在较大型工作中使用它，并始终最多保持一个 `in_progress` 步骤。 +- 启用后，系统提示还会加入使用指导，让模型仅在实质性工作中使用它，并始终最多只保留一个 `in_progress` 步骤。 ### `agents.defaults.subagents` @@ -2280,8 +2284,8 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m } ``` -- `model`：派生子智能体的默认模型。若省略，子智能体继承调用方模型。 -- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，用于 `sessions_spawn` 目标智能体 ID 的默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- `model`：派生子智能体的默认模型。若省略，子智能体继承调用者模型。 +- `allowAgents`：当请求智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 允许的目标智能体 id 默认列表（`["*"]` = 任意；默认：仅相同智能体）。 - `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时（秒）。`0` 表示无超时。 - 每子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 @@ -2318,47 +2322,47 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -- 如有自定义认证需求，可使用 `authHeader: true` + `headers`。 -- 使用 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 -- 对于匹配的 provider ID，合并优先级如下： - - 非空的智能体 `models.json` `baseUrl` 值优先。 - - 非空的智能体 `apiKey` 值仅在该 provider 在当前配置/auth-profile 上下文中不是 SecretRef 管理时优先。 - - 由 SecretRef 管理的 provider `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的 secret。 - - 由 SecretRef 管理的 provider header 值也会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。 +- 使用 `authHeader: true` + `headers` 以满足自定义认证需求。 +- 用 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 +- 匹配提供商 ID 的合并优先级： + - 非空的智能体 `models.json` `baseUrl` 优先。 + - 非空的智能体 `apiKey` 仅在当前 config/auth-profile 上下文中该提供商不是 SecretRef 管理时优先。 + - 受 SecretRef 管理的提供商 `apiKey` 会从源标记刷新（环境变量引用为 `ENV_VAR_NAME`，file/exec 引用为 `secretref-managed`），而不是持久化已解析的 secret。 + - 受 SecretRef 管理的提供商 header 值也会从源标记刷新（环境变量引用为 `secretref-env:ENV_VAR_NAME`，file/exec 引用为 `secretref-managed`）。 - 空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 - - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值和隐式目录值之间取较高者。 - - 匹配模型的 `contextTokens` 会在存在显式运行时上限时保留它；可用它限制有效上下文，而不改动模型原生元数据。 - - 当你希望配置完全重写 `models.json` 时，请使用 `models.mode: "replace"`。 - - 标记持久化以源为准：标记根据活动源配置快照（预解析）写入，而不是根据已解析出的运行时 secret 值写入。 + - 匹配模型的 `contextWindow`/`maxTokens` 使用显式配置值与隐式目录值中的较高者。 + - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；用它可以限制实际上下文，而不修改原生模型元数据。 + - 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。 + - 标记持久化是源权威的：标记从活动源配置快照（解析前）写入，而不是从已解析的运行时 secret 值写入。 ### 提供商字段详情 -- `models.mode`：provider 目录行为（`merge` 或 `replace`）。 -- `models.providers`：以 provider id 为键的自定义 provider 映射。 +- `models.mode`：提供商目录行为（`merge` 或 `replace`）。 +- `models.providers`：按提供商 id 键控的自定义提供商映射。 - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。 -- `models.providers.*.apiKey`：provider 凭证（建议使用 SecretRef/环境变量替换）。 +- `models.providers.*.apiKey`：提供商凭据（优先使用 SecretRef/环境变量替换）。 - `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 -- `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，在请求中注入 `options.num_ctx`（默认：`true`）。 -- `models.providers.*.authHeader`：在有需要时强制通过 `Authorization` 头传递凭证。 +- `models.providers.*.injectNumCtxForOpenAICompat`：对 Ollama + `openai-completions`，将 `options.num_ctx` 注入请求（默认：`true`）。 +- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传递凭据。 - `models.providers.*.baseUrl`：上游 API base URL。 -- `models.providers.*.headers`：用于代理/租户路由的额外静态请求头。 +- `models.providers.*.headers`：用于代理/租户路由的额外静态 headers。 - `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖。 - - `request.headers`：额外请求头（与 provider 默认值合并）。值支持 SecretRef。 - - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用 provider 内建认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`，可选 `prefix`）。 - - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。这两种模式都支持可选 `tls` 子对象。 - - `request.tls`：直连时的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（都支持 SecretRef）、`serverName`、`insecureSkipVerify`。 -- `models.providers.*.models`：显式 provider 模型目录条目。 -- `models.providers.*.models.*.contextWindow`：模型原生上下文窗口元数据。 -- `models.providers.*.models.*.contextTokens`：可选运行时上下文上限。如果你希望有效上下文预算小于模型原生 `contextWindow`，请使用它。 -- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 非空并指向非原生地址（host 不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空或省略 `baseUrl` 则保持默认 OpenAI 行为。 -- `models.providers.*.models.*.compat.requiresStringContent`：适用于仅支持字符串内容的 OpenAI-compatible chat 端点的可选兼容性提示。当为 `true` 时，OpenClaw 会在发送请求前将纯文本的 `messages[].content` 数组展平成普通字符串。 -- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根路径。 -- `plugins.entries.amazon-bedrock.config.discovery.enabled`：打开/关闭隐式发现。 -- `plugins.entries.amazon-bedrock.config.discovery.region`：发现所用的 AWS 区域。 -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用于定向发现的可选 provider-id 过滤器。 -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新轮询间隔。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：发现模型时使用的后备上下文窗口。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：发现模型时使用的后备最大输出 token 数。 + - `request.headers`：额外 headers（与提供商默认值合并）。值支持 SecretRef。 + - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`、可选 `prefix`）。 + - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。 + - `request.tls`：直连时的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（均支持 SecretRef）、`serverName`、`insecureSkipVerify`。 +- `models.providers.*.models`：显式提供商模型目录条目。 +- `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。 +- `models.providers.*.models.*.contextTokens`：可选运行时上下文上限。用于当你希望实际上下文预算小于模型原生 `contextWindow` 时。 +- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 非空、非原生（host 不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空/省略 `baseUrl` 则保持默认 OpenAI 行为。 +- `models.providers.*.models.*.compat.requiresStringContent`：用于仅支持字符串的 OpenAI-compatible chat 端点的可选兼容性提示。为 `true` 时，OpenClaw 会在发送请求前将纯文本 `messages[].content` 数组压平为普通字符串。 +- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根。 +- `plugins.entries.amazon-bedrock.config.discovery.enabled`：开启/关闭隐式发现。 +- `plugins.entries.amazon-bedrock.config.discovery.region`：用于发现的 AWS 区域。 +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：可选的提供商 id 过滤器，用于定向发现。 +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新的轮询间隔。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的后备上下文窗口。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的后备最大输出 token。 ### 提供商示例 @@ -2396,7 +2400,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7`。 +Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 @@ -2430,11 +2434,11 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 +设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是可接受别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 - 通用端点：`https://api.z.ai/api/paas/v4` -- 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` -- 若要使用通用端点，请定义带 base URL 覆盖的自定义 provider。 +- Coding 端点（默认）：`https://api.z.ai/api/coding/paas/v4` +- 若要使用通用端点，请定义一个带 base URL 覆盖的自定义提供商。 @@ -2473,11 +2477,11 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -中国端点请使用：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 +中国端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 原生 Moonshot 端点会在共享的 `openai-completions` 传输上声明流式使用兼容性，OpenClaw 现在会根据端点 -能力而不是仅根据内置 provider id 来判断这一点。 +能力而不仅仅是内置提供商 id 来判断这一点。 @@ -2495,7 +2499,7 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -Anthropic-compatible，内置 provider。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 +Anthropic-compatible，内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 @@ -2577,7 +2581,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 设置 `MINIMAX_API_KEY`。快捷方式： `openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。 -模型目录现已默认仅包含 M2.7。 +模型目录现在默认仅包含 M2.7。 在 Anthropic-compatible 流式路径上，OpenClaw 默认会禁用 MiniMax thinking， 除非你显式自行设置 `thinking`。`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 @@ -2587,7 +2591,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 -请参阅 [Local Models](/zh-CN/gateway/local-models)。简要来说：在性能较强的硬件上，通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 +参见 [本地模型](/zh-CN/gateway/local-models)。简而言之：在性能足够强的硬件上，通过 LM Studio Responses API 运行大型本地模型；并保留已合并的托管模型作为后备。 @@ -2618,13 +2622,12 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `allowBundled`：仅适用于内置 Skills 的可选允许列表（托管/workspace Skills 不受影响）。 -- `load.extraDirs`：额外的共享 Skills 根目录（优先级最低）。 -- `install.preferBrew`：为 true 时，如果存在 `brew`，则优先使用 Homebrew 安装器，再回退到其他安装方式。 -- `install.nodeManager`：`metadata.openclaw.install` - 规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false`：即使某个 Skill 已内置/安装，也会将其禁用。 -- `entries..apiKey`：为声明主环境变量的 Skills 提供的便捷主 API key 字段（明文字符串或 SecretRef 对象）。 +- `allowBundled`：仅对内置 Skills 生效的可选允许列表（managed/workspace Skills 不受影响）。 +- `load.extraDirs`：额外共享 Skills 根目录（优先级最低）。 +- `install.preferBrew`：为 true 时，在 `brew` 可用的情况下优先使用 Homebrew 安装器，再回退到其他安装类型。 +- `install.nodeManager`：`metadata.openclaw.install` 规范使用的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使某个 skill 已内置/已安装，也会禁用它。 +- `entries..apiKey`：为声明主环境变量的 skill 提供的便捷 API key 字段（明文字符串或 SecretRef 对象）。 --- @@ -2653,36 +2656,36 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 设备发现支持原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 -- **配置更改需要重启 Gateway 网关。** +- 设备发现接受原生 OpenClaw 插件、兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 +- **配置变更需要重启 Gateway 网关。** - `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 -- `plugins.entries..apiKey`：插件级 API key 便捷字段（如果插件支持）。 +- `plugins.entries..apiKey`：插件级 API key 便捷字段（插件支持时）。 - `plugins.entries..env`：插件作用域环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks 以及受支持 bundle 提供的 hook 目录。 -- `plugins.entries..subagent.allowModelOverride`：显式信任该插件，使其可为后台子智能体运行请求按次覆盖 `provider` 和 `model`。 -- `plugins.entries..subagent.allowedModels`：对受信任子智能体覆盖的规范 `provider/model` 目标进行可选允许列表限制。仅当你确实想允许任意模型时才使用 `"*"`。 -- `plugins.entries..config`：插件定义的配置对象（如果有可用 schema，则由原生 OpenClaw 插件 schema 验证）。 -- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch provider 设置。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略来自旧版 `before_agent_start` 的可变更提示字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks 和支持的 bundle 提供 hook 目录。 +- `plugins.entries..subagent.allowModelOverride`：显式信任该插件，可为后台子智能体运行请求每次运行级别的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖允许的规范 `provider/model` 目标可选列表。仅当你明确想允许任意模型时才使用 `"*"`。 +- `plugins.entries..config`：插件定义的配置对象（如果可用，会由原生 OpenClaw 插件 schema 校验）。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web 抓取提供商设置。 - `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 provider。 + - `enabled`：启用 X Search 提供商。 - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`：memory dreaming（实验性）设置。关于阶段和阈值，请参阅 [Dreaming](/zh-CN/concepts/dreaming)。 +- `plugins.entries.memory-core.config.dreaming`：memory dreaming（实验性）设置。阶段和阈值参见 [Dreaming](/zh-CN/concepts/dreaming)。 - `enabled`：dreaming 主开关（默认 `false`）。 - `frequency`：每次完整 dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。 - - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 -- 已启用的 Claude bundle 插件也可以通过 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将这些值作为已清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 + - phase policy 和阈值属于实现细节（不是面向用户的配置键）。 +- 已启用的 Claude bundle 插件也可以提供内嵌 Pi 默认值，来自 `settings.json`；OpenClaw 会将它们作为已净化的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 - `plugins.slots.memory`：选择活动 memory 插件 id，或使用 `"none"` 禁用 memory 插件。 -- `plugins.slots.contextEngine`：选择活动 context engine 插件 id；默认是 `"legacy"`，除非你安装并选择了其他 engine。 +- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；默认值是 `"legacy"`，除非你安装并选择其他引擎。 - `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 - - 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - - 请将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 + - 包含 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 + - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 -请参阅 [Plugins](/zh-CN/tools/plugin)。 +参见 [插件](/zh-CN/tools/plugin)。 --- @@ -2695,7 +2698,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - dangerouslyAllowPrivateNetwork: true, // 默认可信网络模式 + dangerouslyAllowPrivateNetwork: true, // 默认 trusted-network 模式 // allowPrivateNetwork: true, // 旧版别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2723,27 +2726,26 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认是 `true`（可信网络模型）。 -- 将 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` 设为严格的仅公共网络浏览导航模式。 -- 在严格模式下，远程 CDP 配置端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到相同的私有网络阻止。 -- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 -- 在严格模式下，请使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 作为显式例外。 -- 远程 profile 为仅附加模式（无法 start/stop/reset）。 -- `profiles.*.cdpUrl` 支持 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)； - 当 provider 直接给你 DevTools WebSocket URL 时，请使用 WS(S)。 -- `existing-session` profile 仅限宿主机，并使用 Chrome MCP 而非 CDP。 -- `existing-session` profile 可设置 `userDataDir` 以指定某个特定的 - Chromium-based 浏览器配置，例如 Brave 或 Edge。 -- `existing-session` profile 保持当前 Chrome MCP 路由限制： - 使用 snapshot/ref 驱动动作而不是 CSS 选择器定向、单文件上传 - hook、不支持对话框超时覆盖、不支持 `wait --load networkidle`，也不支持 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时默认为 `true`（trusted-network 模型）。 +- 若要使用严格的仅公共网络浏览导航，请设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false`。 +- 在严格模式下，远程 CDP 配置端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到相同的私有网络阻止策略约束。 +- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名支持。 +- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 作为显式例外。 +- 远程 profiles 为仅附加模式（无法 start/stop/reset）。 +- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 + 如果你想让 OpenClaw 发现 `/json/version`，请使用 HTTP(S)； + 当提供商直接给你 DevTools WebSocket URL 时，请使用 WS(S)。 +- `existing-session` profiles 仅限主机使用，并使用 Chrome MCP 而非 CDP。 +- `existing-session` profiles 可以设置 `userDataDir` 以指定特定的 + Chromium-based 浏览器 profile，如 Brave 或 Edge。 +- `existing-session` profiles 保留当前 Chrome MCP 路由限制： + 基于快照/ref 的操作，而不是 CSS 选择器目标；单文件上传 hooks； + 不支持对话框超时覆盖；不支持 `wait --load networkidle`；也不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地托管的 `openclaw` profile 会自动分配 `cdpPort` 和 `cdpUrl`；仅在 - 远程 CDP 场景下显式设置 `cdpUrl`。 -- 自动检测顺序：默认浏览器（如果是 Chromium-based）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 -- 控制服务：仅 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 -- `extraArgs` 会向本地 Chromium 启动追加额外标志（例如 +- 本地托管的 `openclaw` profiles 会自动分配 `cdpPort` 和 `cdpUrl`；只有远程 CDP 才需要显式设置 `cdpUrl`。 +- 自动检测顺序：默认浏览器（若为 Chromium-based）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 控制服务：仅 loopback（端口从 `gateway.port` 派生，默认 `18791`）。 +- `extraArgs` 会将额外启动标志附加到本地 Chromium 启动参数中（例如 `--disable-gpu`、窗口尺寸或调试标志）。 --- @@ -2763,11 +2765,11 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - `seamColor`：原生应用 UI 外观的强调色（Talk Mode 气泡着色等）。 -- `assistant`：Control UI 身份覆盖。未设置时回退到当前活动智能体身份。 +- `assistant`：Control UI 身份覆盖。会回退到当前活跃智能体身份。 --- -## Gateway 网关 +## Gateway ```json5 { @@ -2779,7 +2781,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 mode: "token", // none | token | password | trusted-proxy token: "your-token", // password: "your-password", // 或 OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // 用于 mode=trusted-proxy；见 /gateway/trusted-proxy-auth + // trustedProxy: { userHeader: "x-forwarded-user" }, // 用于 mode=trusted-proxy；参见 /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -2796,8 +2798,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 enabled: true, basePath: "/openclaw", // root: "dist/control-ui", - // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 所必需 - // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host 头 origin 回退模式 + // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必填 + // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host-header origin 回退模式 // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2830,27 +2832,26 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 -- `mode`：`local`（运行 gateway）或 `remote`（连接到远程 gateway）。除非为 `local`，否则 Gateway 网关会拒绝启动。 -- `port`：WS + HTTP 共用的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 +- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接远程 Gateway 网关）。除非是 `local`，否则 Gateway 网关会拒绝启动。 +- `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。 -- **旧版 bind 别名**：在 `gateway.bind` 中请使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用 host 别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关不可达。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 且 `customBindHost: "0.0.0.0"`）以监听所有接口。 -- **认证**：默认要求认证。非 loopback bind 需要 Gateway 网关认证。实际中这意味着共享 token/password，或使用带 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成 token。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式设置 `gateway.auth.mode` 为 `token` 或 `password`。若两者都已配置而 mode 未设置，启动和服务安装/修复流程都会失败。 -- `gateway.auth.mode: "none"`：显式无认证模式。仅适用于可信的本地 local loopback 设置；新手引导提示中不会提供此选项。 -- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份头（见 [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`。 -- 来自浏览器 origin 的 WS 认证尝试始终会在禁用 loopback 豁免的情况下进行节流（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 -- 在 loopback 上，这些源自浏览器 origin 的锁定会按归一化后的 `Origin` - 值独立计算，因此一个 localhost origin 的重复失败不会自动 - 锁定另一个 origin。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开访问，需要认证）。 -- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器 origin 允许列表。当预期浏览器客户端来自非 loopback origin 时必需。 -- `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 使用明文。 -- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 -- `gateway.push.ap \ No newline at end of file +- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用 host 别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 +- **Docker 说明**：默认 `loopback` bind 只会在容器内的 `127.0.0.1` 上监听。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关不可达。请使用 `--network host`，或者设置 `bind: "lan"`（或 `bind: "custom"` 且 `customBindHost: "0.0.0.0"`）以监听所有接口。 +- **认证**：默认必须启用。非 loopback bind 要求 Gateway 网关认证。实际上，这意味着需要共享 token/password，或者使用带 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成 token。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式设置 `gateway.auth.mode` 为 `token` 或 `password`。若两者都配置但 mode 未设置，启动以及服务安装/修复流程都会失败。 +- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 设置；新手引导不会提供该选项。 +- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份头（参见 [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 流程假定网关主机是可信的。当 `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 连接的显式浏览器源允许列表。当浏览器客户端来自非 loopback 源时必须设置。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，可为故意依赖 Host-header origin 策略的部署启用 Host-header origin 回退。 +- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。若使用 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端紧急模式覆盖，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍只允许 loopback 使用明文连接。 +- `gateway.remote.token` / \ No newline at end of file diff --git a/docs/zh-CN/reference/session-management-compaction.md b/docs/zh-CN/reference/session-management-compaction.md index 94e1d44f2..8d609f013 100644 --- a/docs/zh-CN/reference/session-management-compaction.md +++ b/docs/zh-CN/reference/session-management-compaction.md @@ -1,15 +1,15 @@ --- read_when: - - 你需要调试 session id、transcript JSONL 或 sessions.json 字段 - - 你正在修改自动压缩行为，或添加“压缩前”清理逻辑 - - 你想实现 memory flush 或静默 system turn -summary: 深入解析：会话存储 + transcript、生命周期，以及（自动）压缩内部机制 + - 你需要调试会话 id、转录 JSONL 或 sessions.json 字段 + - 你正在更改自动压缩行为，或添加“压缩前”整理逻辑 + - 你想要实现 memory flush 或静默系统轮次 +summary: 深入解析：会话存储 + 转录、生命周期，以及（自动）压缩内部机制 title: 会话管理深入解析 x-i18n: - generated_at: "2026-04-06T12:45:16Z" + generated_at: "2026-04-07T17:57:46Z" model: gpt-5.4 provider: openai - source_hash: e379d624dd7808d3af25ed011079268ce6a9da64bb3f301598884ad4c46ab091 + source_hash: cb1a4048646486693db8943a9e9c6c5bcb205f0ed532b34842de3d0346077454 source_path: reference/session-management-compaction.md workflow: 15 --- @@ -19,14 +19,14 @@ x-i18n: 本文档解释 OpenClaw 如何端到端管理会话： - **会话路由**（入站消息如何映射到 `sessionKey`） -- **会话存储**（`sessions.json`）及其跟踪内容 -- **Transcript 持久化**（`*.jsonl`）及其结构 -- **Transcript 清理**（运行前针对特定提供商的修正） -- **上下文限制**（上下文窗口与已跟踪 token 的区别） -- **压缩**（手动 + 自动压缩）以及应在何处挂接压缩前工作 -- **静默清理**（例如不应产生用户可见输出的 memory 写入） +- **会话存储**（`sessions.json`）及其跟踪的内容 +- **转录持久化**（`*.jsonl`）及其结构 +- **转录清理**（运行前按提供商进行的特定修正） +- **上下文限制**（上下文窗口与已跟踪 token） +- **压缩**（手动 + 自动压缩）以及在哪里挂接压缩前逻辑 +- **静默整理**（例如不应产生用户可见输出的 memory 写入） -如果你想先看更高层级的概览，请从以下内容开始： +如果你想先看更高层的概览，请从以下内容开始： - [/concepts/session](/zh-CN/concepts/session) - [/concepts/compaction](/zh-CN/concepts/compaction) @@ -37,12 +37,12 @@ x-i18n: --- -## 单一事实来源：Gateway 网关 +## 事实来源：Gateway 网关 -OpenClaw 的设计围绕单个**Gateway 网关 进程**展开，由它持有会话状态。 +OpenClaw 围绕一个拥有会话状态的单一 **Gateway 网关进程** 进行设计。 -- UI（macOS 应用、网页 Control UI、TUI）应向 Gateway 网关 查询会话列表和 token 计数。 -- 在远程模式下，会话文件位于远程主机上；“查看你本地 Mac 上的文件”并不能反映 Gateway 网关 实际使用的内容。 +- UI（macOS 应用、网页 Control UI、TUI）应向 Gateway 网关查询会话列表和 token 计数。 +- 在远程模式下，会话文件位于远程主机上；“检查你本地 Mac 上的文件”不会反映 Gateway 网关实际使用的内容。 --- @@ -51,24 +51,24 @@ OpenClaw 的设计围绕单个**Gateway 网关 进程**展开，由它持有会 OpenClaw 以两层方式持久化会话： 1. **会话存储（`sessions.json`）** - - 键 / 值映射：`sessionKey -> SessionEntry` - - 体积小、可变、安全可编辑（或删除条目） - - 跟踪会话元数据（当前 session id、最近活动时间、开关、token 计数器等） + - 键/值映射：`sessionKey -> SessionEntry` + - 小型、可变、可安全编辑（或删除条目） + - 跟踪会话元数据（当前会话 id、最近活动时间、开关、token 计数器等） -2. **Transcript（`.jsonl`）** - - 追加写入的 transcript，带树结构（条目具有 `id` + `parentId`） +2. **转录（`.jsonl`）** + - 具有树结构的仅追加转录（条目包含 `id` + `parentId`） - 存储实际对话 + 工具调用 + 压缩摘要 - 用于为后续轮次重建模型上下文 --- -## 磁盘上的位置 +## 磁盘位置 -每个智能体在 Gateway 网关 主机上的位置： +对于 Gateway 网关主机上的每个智能体： - 存储：`~/.openclaw/agents//sessions/sessions.json` -- Transcripts：`~/.openclaw/agents//sessions/.jsonl` - - Telegram 话题会话：`.../-topic-.jsonl` +- 转录：`~/.openclaw/agents//sessions/.jsonl` + - Telegram 主题会话：`.../-topic-.jsonl` OpenClaw 通过 `src/config/sessions.ts` 解析这些路径。 @@ -76,23 +76,23 @@ OpenClaw 通过 `src/config/sessions.ts` 解析这些路径。 ## 存储维护和磁盘控制 -会话持久化为 `sessions.json` 和 transcript 工件提供了自动维护控制（`session.maintenance`）： +会话持久化为 `sessions.json` 和转录产物提供自动维护控制（`session.maintenance`）： - `mode`：`warn`（默认）或 `enforce` -- `pruneAfter`：陈旧条目的保留期限截止值（默认 `30d`） -- `maxEntries`：`sessions.json` 中条目上限（默认 `500`） +- `pruneAfter`：过期条目的陈旧时间阈值（默认 `30d`） +- `maxEntries`：`sessions.json` 中的条目上限（默认 `500`） - `rotateBytes`：当 `sessions.json` 过大时进行轮转（默认 `10mb`） -- `resetArchiveRetention`：`*.reset.` transcript 归档的保留期（默认与 `pruneAfter` 相同；`false` 表示禁用清理） -- `maxDiskBytes`：可选的 sessions 目录预算 +- `resetArchiveRetention`：`*.reset.` 转录归档的保留期（默认：与 `pruneAfter` 相同；`false` 表示禁用清理） +- `maxDiskBytes`：可选的 sessions 目录容量预算 - `highWaterBytes`：清理后的可选目标值（默认是 `maxDiskBytes` 的 `80%`） 磁盘预算清理的执行顺序（`mode: "enforce"`）： -1. 先移除最旧的归档或孤立 transcript 工件。 -2. 如果仍高于目标值，则逐出最旧的会话条目及其 transcript 文件。 -3. 持续执行，直到占用量小于或等于 `highWaterBytes`。 +1. 先移除最旧的已归档或孤立转录产物。 +2. 如果仍高于目标，则驱逐最旧的会话条目及其转录文件。 +3. 持续执行，直到使用量小于或等于 `highWaterBytes`。 -在 `mode: "warn"` 下，OpenClaw 会报告潜在的逐出项，但不会修改存储 / 文件。 +在 `mode: "warn"` 下，OpenClaw 会报告可能的驱逐操作，但不会修改存储/文件。 按需运行维护： @@ -103,57 +103,57 @@ openclaw sessions cleanup --enforce --- -## Cron 会话和运行日志 +## 定时任务会话和运行日志 -隔离的 cron 运行也会创建会话条目 / transcript，并且它们有专门的保留控制： +隔离的 cron 运行也会创建会话条目/转录，并且它们有专用的保留控制： - `cron.sessionRetention`（默认 `24h`）会从会话存储中清理旧的隔离 cron 运行会话（`false` 表示禁用）。 -- `cron.runLog.maxBytes` + `cron.runLog.keepLines` 会裁剪 `~/.openclaw/cron/runs/.jsonl` 文件（默认：`2_000_000` 字节和 `2000` 行）。 +- `cron.runLog.maxBytes` + `cron.runLog.keepLines` 会清理 `~/.openclaw/cron/runs/.jsonl` 文件（默认值：`2_000_000` 字节和 `2000` 行）。 --- ## 会话键（`sessionKey`） -`sessionKey` 用于标识你所在的_哪个会话桶_（路由 + 隔离）。 +`sessionKey` 用于标识你处于哪个 _对话桶_ 中（路由 + 隔离）。 常见模式： -- 主 / 直接聊天（每个智能体）：`agent::`（默认 `main`） +- 主/直接聊天（每个智能体）：`agent::`（默认 `main`） - 群组：`agent:::group:` -- 房间 / 渠道（Discord / Slack）：`agent:::channel:` 或 `...:room:` +- 房间/渠道（Discord/Slack）：`agent:::channel:` 或 `...:room:` - Cron：`cron:` - Webhook：`hook:`（除非被覆盖） -规范规则记录在 [/concepts/session](/zh-CN/concepts/session)。 +规范规则记录于 [/concepts/session](/zh-CN/concepts/session)。 --- ## 会话 id（`sessionId`） -每个 `sessionKey` 都会指向当前的 `sessionId`（用于延续对话的 transcript 文件）。 +每个 `sessionKey` 都指向当前的 `sessionId`（继续该对话的转录文件）。 经验规则： - **重置**（`/new`、`/reset`）会为该 `sessionKey` 创建新的 `sessionId`。 -- **每日重置**（默认是 Gateway 网关 主机本地时间凌晨 4:00）会在越过重置边界后的下一条消息时创建新的 `sessionId`。 -- **空闲过期**（`session.reset.idleMinutes` 或旧版 `session.idleMinutes`）会在消息于空闲窗口之后到达时创建新的 `sessionId`。如果同时配置了 daily 和 idle，以先过期者为准。 -- **线程父级分叉保护**（`session.parentForkMaxTokens`，默认 `100000`）会在父会话已经过大时跳过父 transcript 分叉；新线程会从头开始。设置为 `0` 可禁用。 +- **每日重置**（默认是 Gateway 网关主机本地时间凌晨 4:00）会在越过重置边界后的下一条消息时创建新的 `sessionId`。 +- **空闲过期**（`session.reset.idleMinutes` 或旧版 `session.idleMinutes`）会在消息于空闲窗口之后到达时创建新的 `sessionId`。当每日重置和空闲过期同时配置时，以先到期者为准。 +- **线程父级分叉保护**（`session.parentForkMaxTokens`，默认 `100000`）会在父会话已经过大时跳过父转录分叉；新线程将从全新状态开始。设为 `0` 可禁用。 -实现细节：这一决策发生在 `src/auto-reply/reply/session.ts` 中的 `initSessionState()`。 +实现细节：该决策发生在 `src/auto-reply/reply/session.ts` 中的 `initSessionState()`。 --- ## 会话存储结构（`sessions.json`） -存储的值类型是 `src/config/sessions.ts` 中的 `SessionEntry`。 +存储的值类型是在 `src/config/sessions.ts` 中定义的 `SessionEntry`。 关键字段（非完整列表）： -- `sessionId`：当前 transcript id（除非设置了 `sessionFile`，否则文件名从这里派生） +- `sessionId`：当前转录 id（除非设置了 `sessionFile`，否则文件名从这里派生） - `updatedAt`：最近活动时间戳 -- `sessionFile`：可选的显式 transcript 路径覆盖 +- `sessionFile`：可选的显式转录路径覆盖 - `chatType`：`direct | group | room`（帮助 UI 和发送策略） -- `provider`、`subject`、`room`、`space`、`displayName`：用于群组 / 渠道标签的元数据 +- `provider`、`subject`、`room`、`space`、`displayName`：用于群组/渠道标签的元数据 - 开关： - `thinkingLevel`、`verboseLevel`、`reasoningLevel`、`elevatedLevel` - `sendPolicy`（按会话覆盖） @@ -161,69 +161,72 @@ openclaw sessions cleanup --enforce - `providerOverride`、`modelOverride`、`authProfileOverride` - Token 计数器（尽力而为 / 取决于提供商）： - `inputTokens`、`outputTokens`、`totalTokens`、`contextTokens` -- `compactionCount`：该会话键完成自动压缩的次数 -- `memoryFlushAt`：最近一次压缩前 memory flush 的时间戳 -- `memoryFlushCompactionCount`：最近一次 flush 运行时的压缩计数 +- `compactionCount`：此会话键已完成自动压缩的次数 +- `memoryFlushAt`：上次压缩前 memory flush 的时间戳 +- `memoryFlushCompactionCount`：上次 flush 运行时的压缩计数 -这个存储可以安全编辑，但 Gateway 网关 才是权威：随着会话运行，它可能会重写或重新填充条目。 +该存储可安全编辑，但 Gateway 网关才是权威来源：会话运行时，它可能会重写或重新填充条目。 --- -## Transcript 结构（`*.jsonl`） +## 转录结构（`*.jsonl`） -Transcripts 由 `@mariozechner/pi-coding-agent` 的 `SessionManager` 管理。 +转录由 `@mariozechner/pi-coding-agent` 的 `SessionManager` 管理。 -该文件采用 JSONL 格式： +该文件为 JSONL： - 第一行：会话头（`type: "session"`，包含 `id`、`cwd`、`timestamp`、可选的 `parentSession`） -- 后续内容：带 `id` + `parentId` 的会话条目（树结构） +- 然后：带有 `id` + `parentId` 的会话条目（树） 值得注意的条目类型： -- `message`：用户 / 助手 / `toolResult` 消息 -- `custom_message`：由扩展注入的、_会_进入模型上下文的消息（可对 UI 隐藏） -- `custom`：_不会_进入模型上下文的扩展状态 -- `compaction`：持久化的压缩摘要，带 `firstKeptEntryId` 和 `tokensBefore` +- `message`：用户/助手/`toolResult` 消息 +- `custom_message`：由扩展注入、且 _会_ 进入模型上下文的消息（可在 UI 中隐藏） +- `custom`：_不会_ 进入模型上下文的扩展状态 +- `compaction`：持久化的压缩摘要，带有 `firstKeptEntryId` 和 `tokensBefore` - `branch_summary`：在导航树分支时持久化的摘要 -OpenClaw 有意**不会**“修正” transcripts；Gateway 网关 使用 `SessionManager` 来读写它们。 +OpenClaw 有意 **不会** “修正”转录；Gateway 网关使用 `SessionManager` 读写它们。 --- ## 上下文窗口与已跟踪 token -有两个不同的概念很重要： +有两个不同的概念需要关注： -1. **模型上下文窗口**：每个模型的硬性上限（模型可见的 token） -2. **会话存储计数器**：写入 `sessions.json` 的滚动统计值（用于 `/status` 和仪表盘） +1. **模型上下文窗口**：每个模型的硬上限（模型可见的 token） +2. **会话存储计数器**：写入 `sessions.json` 的滚动统计（用于 `/status` 和仪表盘） -如果你要调优限制： +如果你在调整限制： -- 上下文窗口来自模型目录（并且可通过配置覆盖）。 -- 存储中的 `contextTokens` 是运行时估算 / 报告值；不要把它当作严格保证。 +- 上下文窗口来自模型目录（也可通过配置覆盖）。 +- 存储中的 `contextTokens` 是运行时估算/报告值；不要把它当作严格保证。 -更多信息见 [/token-use](/zh-CN/reference/token-use)。 +更多信息请参见 [/token-use](/zh-CN/reference/token-use)。 --- ## 压缩：它是什么 -压缩会将较早的对话总结为 transcript 中一个持久化的 `compaction` 条目，并保留最近的消息不变。 +压缩会把较早的对话总结为转录中一个持久化的 `compaction` 条目，并保留最近的消息不变。 -压缩之后，后续轮次会看到： +压缩后，后续轮次将看到： - 压缩摘要 - `firstKeptEntryId` 之后的消息 压缩是**持久化的**（不同于会话裁剪）。参见 [/concepts/session-pruning](/zh-CN/concepts/session-pruning)。 -## 压缩分块边界和工具配对 +## 压缩分块边界与工具配对 -当 OpenClaw 将较长 transcript 拆分为压缩分块时，它会让助手工具调用与其匹配的 `toolResult` 条目保持配对。 +当 OpenClaw 将长转录拆分为压缩分块时，它会保持 +助手工具调用与其对应的 `toolResult` 条目配对。 -- 如果按 token 占比分割的边界落在工具调用和其结果之间，OpenClaw 会将边界移动到助手工具调用消息，而不是把这一对拆开。 -- 如果尾部的工具结果块原本会让分块超过目标大小，OpenClaw 会保留该待处理工具块，并保持未总结的尾部不变。 -- 已中止 / 出错的工具调用块不会让待处理分割一直保持打开状态。 +- 如果 token 份额切分点落在工具调用与其结果之间，OpenClaw + 会将边界移动到助手工具调用消息处，而不是拆开这一对。 +- 如果尾部的工具结果块本会让分块超出目标， + OpenClaw 会保留这个待处理的工具块，并保持未摘要的尾部完整。 +- 已中止/报错的工具调用块不会让待处理切分保持开启。 --- @@ -235,17 +238,17 @@ OpenClaw 有意**不会**“修正” transcripts；Gateway 网关 使用 `Sessi （`request_too_large`、`context length exceeded`、`input exceeds the maximum number of tokens`、`input token count exceeds the maximum number of input tokens`、`input is too long for the model`、`ollama error: context length -exceeded`，以及类似的提供商格式变体）→ 压缩 → 重试。 -2. **阈值维护**：在一次成功轮次之后，当： +exceeded`，以及类似的提供商风格变体）→ 压缩 → 重试。 +2. **阈值维护**：在成功完成一轮后，当： `contextTokens > contextWindow - reserveTokens` 其中： - `contextWindow` 是模型的上下文窗口 -- `reserveTokens` 是为提示词 + 下一次模型输出保留的余量 +- `reserveTokens` 是为提示词 + 下一次模型输出预留的余量 -这些是 Pi 运行时语义（OpenClaw 会消费这些事件，但何时压缩由 Pi 决定）。 +这些都是 Pi 运行时语义（OpenClaw 会消费这些事件，但何时压缩由 Pi 决定）。 --- @@ -265,85 +268,101 @@ Pi 的压缩设置位于 Pi settings 中： OpenClaw 还会为嵌入式运行强制执行一个安全下限： -- 如果 `compaction.reserveTokens < reserveTokensFloor`，OpenClaw 会提升它。 -- 默认下限是 `20000` token。 +- 如果 `compaction.reserveTokens < reserveTokensFloor`，OpenClaw 会将其提升。 +- 默认下限为 `20000` token。 - 设置 `agents.defaults.compaction.reserveTokensFloor: 0` 可禁用该下限。 -- 如果它本来就更高，OpenClaw 不会改动。 +- 如果它已经更高，OpenClaw 不会改动。 -原因：在压缩变得不可避免之前，为多轮“清理”操作（例如 memory 写入）保留足够的余量。 +原因：为多轮“整理”操作（如 memory 写入）预留足够余量，避免压缩变得不可避免之前就没有空间。 实现：`src/agents/pi-settings.ts` 中的 `ensurePiCompactionReserveTokens()` （由 `src/agents/pi-embedded-runner.ts` 调用）。 --- +## 可插拔压缩提供商 + +插件可以通过插件 API 上的 `registerCompactionProvider()` 注册压缩提供商。当 `agents.defaults.compaction.provider` 设置为已注册提供商 id 时，safeguard 扩展会将摘要生成委托给该提供商，而不是使用内置的 `summarizeInStages` 流水线。 + +- `provider`：已注册压缩提供商插件的 id。不设置时使用默认 LLM 摘要。 +- 设置 `provider` 会强制使用 `mode: "safeguard"`。 +- 提供商会接收与内置路径相同的压缩说明和标识符保留策略。 +- 在提供商输出后，safeguard 仍会保留最近轮次和拆分轮次的后缀上下文。 +- 如果提供商失败或返回空结果，OpenClaw 会自动回退到内置 LLM 摘要。 +- 中止/超时信号会被重新抛出（不会被吞掉），以遵守调用方取消。 + +来源：`src/plugins/compaction-provider.ts`、`src/agents/pi-hooks/compaction-safeguard.ts`。 + +--- + ## 用户可见界面 你可以通过以下方式观察压缩和会话状态： -- `/status`（在任意聊天会话中） +- `/status`（在任何聊天会话中） - `openclaw status`（CLI） - `openclaw sessions` / `sessions --json` - 详细模式：`🧹 Auto-compaction complete` + 压缩计数 --- -## 静默清理（`NO_REPLY`） +## 静默整理（`NO_REPLY`） -OpenClaw 支持“静默”轮次，用于用户不应看到中间输出的后台任务。 +OpenClaw 支持用于后台任务的“静默”轮次，用户不应看到其中间输出。 约定： - 助手以精确的静默 token `NO_REPLY` / - `no_reply` 开始其输出，以表示“不要向用户发送回复”。 -- OpenClaw 会在发送层剥离 / 抑制它。 -- 对精确静默 token 的抑制不区分大小写，因此当整个负载仅为该静默 token 时，`NO_REPLY` 和 - `no_reply` 都算。 -- 这仅用于真正的后台 / 不投递轮次；它不是普通可执行用户请求的快捷方式。 + `no_reply` 开始输出，以表示“不要向用户发送回复”。 +- OpenClaw 会在发送层中剥离/抑制它。 +- 精确静默 token 抑制不区分大小写，因此当整个载荷只是该静默 token 时，`NO_REPLY` 和 + `no_reply` 都算数。 +- 这仅用于真正的后台/不发送轮次；它不是普通可执行用户请求的捷径。 -自 `2026.1.10` 起，OpenClaw 在部分分块以 `NO_REPLY` 开头时，也会抑制**草稿 / 输入中流式传输**，这样静默操作就不会在轮次中途泄露部分输出。 +从 `2026.1.10` 起，如果部分分块以 `NO_REPLY` 开头， +OpenClaw 还会抑制 **草稿/输入中流式传输**，这样静默操作就不会在轮次中途泄露部分输出。 --- ## 压缩前 “memory flush”（已实现） -目标：在自动压缩发生之前，运行一次静默的智能体轮次，将持久状态写入磁盘（例如智能体工作区中的 `memory/YYYY-MM-DD.md`），这样压缩就无法抹掉关键上下文。 +目标：在自动压缩发生之前，运行一次静默的 agentic 轮次，将持久状态写入磁盘（例如智能体工作区中的 `memory/YYYY-MM-DD.md`），这样压缩就无法抹掉关键上下文。 OpenClaw 使用**阈值前 flush** 方法： 1. 监控会话上下文使用量。 -2. 当它越过一个“软阈值”（低于 Pi 的压缩阈值）时，向智能体运行一个静默的 - “立即写入 memory” 指令。 -3. 使用精确的静默 token `NO_REPLY` / `no_reply`，这样用户就 - 看不到任何内容。 +2. 当它越过“软阈值”（低于 Pi 的压缩阈值）时，向智能体运行一个静默的 + “现在写入 memory” 指令。 +3. 使用精确的静默 token `NO_REPLY` / `no_reply`，这样用户看不到 + 任何内容。 配置（`agents.defaults.compaction.memoryFlush`）： - `enabled`（默认：`true`） - `softThresholdTokens`（默认：`4000`） - `prompt`（用于 flush 轮次的用户消息） -- `systemPrompt`（附加到 flush 轮次的额外系统提示词） +- `systemPrompt`（附加到 flush 轮次中的额外系统提示词） 说明： -- 默认 prompt / system prompt 包含 `NO_REPLY` 提示，以抑制 +- 默认 prompt/system prompt 包含 `NO_REPLY` 提示，用于抑制 发送。 -- 每个压缩周期只运行一次 flush（记录在 `sessions.json` 中）。 -- Flush 仅对嵌入式 Pi 会话运行（CLI 后端会跳过）。 -- 当会话工作区为只读时会跳过 flush（`workspaceAccess: "ro"` 或 `"none"`）。 -- 关于工作区文件布局和写入模式，请参见 [Memory](/zh-CN/concepts/memory)。 +- 每个压缩周期只运行一次 flush（在 `sessions.json` 中跟踪）。 +- flush 仅对嵌入式 Pi 会话运行（CLI 后端会跳过）。 +- 当会话工作区为只读时（`workspaceAccess: "ro"` 或 `"none"`），会跳过 flush。 +- 有关工作区文件布局和写入模式，请参见 [Memory](/zh-CN/concepts/memory)。 Pi 也会在扩展 API 中暴露一个 `session_before_compact` hook，但 OpenClaw 的 -flush 逻辑目前位于 Gateway 网关 侧。 +flush 逻辑目前位于 Gateway 网关侧。 --- ## 故障排除清单 -- 会话键不对？从 [/concepts/session](/zh-CN/concepts/session) 开始，并在 `/status` 中确认 `sessionKey`。 -- 存储与 transcript 不匹配？确认 Gateway 网关 主机，以及 `openclaw status` 中的存储路径。 -- 压缩刷屏？检查： - - 模型上下文窗口（是否太小） +- 会话键不对？从 [/concepts/session](/zh-CN/concepts/session) 开始，并确认 `/status` 中的 `sessionKey`。 +- 存储与转录不匹配？确认 Gateway 网关主机以及 `openclaw status` 提供的存储路径。 +- 压缩过于频繁？检查： + - 模型上下文窗口（过小） - 压缩设置（对于模型窗口来说，`reserveTokens` 过高会导致更早压缩） - - `toolResult` 膨胀：启用 / 调整会话裁剪 -- 静默轮次泄露了输出？确认回复以 `NO_REPLY` 开头（大小写不敏感的精确 token），并且你使用的是包含流式抑制修复的构建版本。 + - 工具结果膨胀：启用/调整会话裁剪 +- 静默轮次有泄露？确认回复以 `NO_REPLY` 开头（不区分大小写的精确 token），并且你使用的是包含流式抑制修复的构建版本。