diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md
index 687e8987e..c1898ff99 100644
--- a/docs/zh-CN/gateway/configuration-reference.md
+++ b/docs/zh-CN/gateway/configuration-reference.md
@@ -5,17 +5,17 @@ read_when:
summary: 每个 OpenClaw 配置键、默认值和渠道设置的完整参考
title: 配置参考
x-i18n:
- generated_at: "2026-04-06T02:35:56Z"
+ generated_at: "2026-04-06T04:37:33Z"
model: gpt-5.4
provider: openai
- source_hash: 6aa6b24b593f6f07118817afabea4cc7842aca6b7c5602b45f479b40c1685230
+ source_hash: 6ae6c19666f65433361e1c8b100ae710448c8aa055a60c140241a8aea09b98a5
source_path: gateway/configuration-reference.md
workflow: 15
---
# 配置参考
-`~/.openclaw/openclaw.json` 中可用的每个字段。要查看面向任务的概览，请参阅 [Configuration](/zh-CN/gateway/configuration)。
+`~/.openclaw/openclaw.json` 中可用的每个字段。若需按任务组织的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。
配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全的默认值。
@@ -23,34 +23,34 @@ x-i18n:
## 渠道
-当每个渠道的配置部分存在时，它会自动启动（除非设置了 `enabled: false`）。
+每个渠道在其配置段存在时都会自动启动（除非设置了 `enabled: false`）。
### 私信和群组访问
所有渠道都支持私信策略和群组策略：
-| 私信策略 | 行为 |
-| ------------------- | -------------------------------------------- |
-| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 |
-| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对允许存储） |
-| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） |
-| `disabled` | 忽略所有传入私信 |
+| 私信策略 | 行为 |
+| ------------------- | ------------------------------------------------------------ |
+| `pairing`（默认） | 未知发送者会收到一次性配对码；必须由所有者批准 |
+| `allowlist` | 仅允许 `allowFrom`（或已配对允许存储）中的发送者 |
+| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） |
+| `disabled` | 忽略所有传入私信 |
-| 群组策略 | 行为 |
-| --------------------- | -------------------------------------------------- |
-| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 |
-| `open` | 绕过群组允许列表（仍然应用提及门控） |
-| `disabled` | 屏蔽所有群组/房间消息 |
+| 群组策略 | 行为 |
+| --------------------- | ------------------------------------------------------ |
+| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 |
+| `open` | 绕过群组允许列表（仍然应用提及门控） |
+| `disabled` | 阻止所有群组/房间消息 |
-当提供商的 `groupPolicy` 未设置时，`channels.defaults.groupPolicy` 会设置默认值。
-配对码会在 1 小时后过期。待处理的私信配对请求每个渠道最多为 **3 个**。
-如果某个提供商配置块完全缺失（即不存在 `channels.`），运行时群组策略会回退到 `allowlist`（失败时默认关闭），并在启动时发出警告。
+`channels.defaults.groupPolicy` 会在提供商的 `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
{
@@ -91,15 +91,15 @@ x-i18n:
}
```
-- `channels.defaults.groupPolicy`：当提供商级别的 `groupPolicy` 未设置时使用的后备群组策略。
-- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。按渠道覆盖：`channels..contextVisibility`。
+- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时的回退群组策略。
+- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。单渠道覆盖：`channels..contextVisibility`。
- `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。
- `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。
-- `channels.defaults.heartbeat.useIndicator`：以紧凑的指示器样式渲染心跳输出。
+- `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, // blue ticks (false in self-chat mode)
groups: {
"*": { requireMention: true },
},
@@ -150,10 +150,10 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在
}
```
-- 出站命令默认使用账号 `default`（如果存在）；否则使用第一个已配置的账号 id（排序后）。
-- 可选的 `channels.whatsapp.defaultAccount` 会在匹配已配置账号 id 时覆盖该后备默认账号选择。
+- 出站命令默认使用 `default` 账号（如果存在）；否则使用第一个已配置账号 ID（排序后）。
+- 可选的 `channels.whatsapp.defaultAccount` 可在其匹配已配置账号 ID 时覆盖该默认账号选择。
- 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。
-- 每账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。
+- 按账号覆盖：`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 (default: off; opt in explicitly to avoid preview-edit rate limits)
actions: { reactions: true, sendMessage: true },
reactionNotifications: "own", // off | own | all
mediaMaxMb: 100,
@@ -212,11 +212,11 @@ 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` 会发出警告。
-- `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`（可用于私聊和群聊）。
+- 可选的 `channels.telegram.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。
+- 在多账号设置（2 个及以上账号 ID）中，设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；若缺失或无效，`openclaw doctor` 会发出警告。
+- `configWrites: false` 会阻止由 Telegram 发起的配置写入（超级群组 ID 迁移、`/config set|unset`）。
+- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目可为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。
+- Telegram 流式预览使用 `sendMessage` + `editMessageText`（在私聊和群聊中都可用）。
- 重试策略：参见 [Retry policy](/zh-CN/concepts/retry)。
### 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 maps to partial on Discord)
maxLinesPerMessage: 17,
ui: {
components: {
@@ -283,7 +283,7 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在
enabled: true,
idleHours: 24,
maxAgeHours: 0,
- spawnSubagentSessions: false, // 为 `sessions_spawn({ thread: true })` 显式启用
+ spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true })
},
voice: {
enabled: true,
@@ -320,35 +320,35 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在
```
- Token：`channels.discord.token`，默认账号可回退到 `DISCORD_BOT_TOKEN`。
-- 直接出站调用如果提供了显式 Discord `token`，则调用会使用该 token；账号重试/策略设置仍来自活动运行时快照中所选账号。
-- 可选的 `channels.discord.defaultAccount` 会在匹配已配置账号 id 时覆盖默认账号选择。
-- 交付目标使用 `user:`（私信）或 `channel:`（guild 渠道）；裸数字 ID 会被拒绝。
-- Guild slug 会转换为小写并将空格替换为 `-`；渠道键使用 slug 化名称（不带 `#`）。优先使用 guild ID。
-- 默认会忽略机器人撰写的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 则只接受提及该机器人的机器人消息（仍会过滤自身消息）。
-- `channels.discord.guilds..ignoreOtherMentions`（以及渠道覆盖）会丢弃那些提及其他用户或角色、但未提及机器人的消息（不包括 @everyone/@here）。
-- `maxLinesPerMessage`（默认 17）即使在未超过 2000 字符时，也会拆分过高的消息。
+- 提供显式 Discord `token` 的直接出站调用会使用该 token 发起调用；账号的重试/策略设置仍来自活动运行时快照中所选账号。
+- 可选的 `channels.discord.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。
+- 使用 `user:`（私信）或 `channel:`（服务器频道）作为投递目标；裸数字 ID 会被拒绝。
+- 服务器 slug 为小写，空格替换为 `-`；频道键使用 slug 化后的名称（不含 `#`）。优先使用服务器 ID。
+- 机器人自己发出的消息默认会被忽略。`allowBots: true` 可启用；使用 `allowBots: "mentions"` 则仅接受提及机器人的机器人消息（自己的消息仍会被过滤）。
+- `channels.discord.guilds..ignoreOtherMentions`（以及频道级覆盖）会丢弃提及其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。
+- `maxLinesPerMessage`（默认 17）会拆分过高消息，即使它们未超过 2000 字符。
- `channels.discord.threadBindings` 控制 Discord 线程绑定路由：
- - `enabled`：Discord 对线程绑定会话功能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及绑定交付/路由）的覆盖开关
- - `idleHours`：以小时为单位的 Discord 非活动自动取消聚焦覆盖（`0` 表示禁用）
- - `maxAgeHours`：以小时为单位的 Discord 最大存活时间硬限制覆盖（`0` 表示禁用）
+ - `enabled`：线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及绑定投递/路由）
+ - `idleHours`：按小时计算的不活动自动取消焦点 Discord 覆盖（`0` 表示禁用）
+ - `maxAgeHours`：按小时计算的硬性最大存活时间 Discord 覆盖（`0` 表示禁用）
- `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程的显式启用开关
-- 顶层 `bindings[]` 中 `type: "acp"` 的条目会为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 id）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。
+- 顶层 `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），并允许可选的状态文本覆盖。
-- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（紧急兼容模式）。
-- `channels.discord.execApprovals`：Discord 原生 exec 审批交付和审批者授权。
- - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批者时，会激活 exec 审批。
- - `approvers`：允许审批 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。
- - `agentFilter`：可选的智能体 ID 允许列表。省略时转发所有智能体的审批。
+- `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入 + TTS 覆盖。
+- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会直接透传给 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。
+- OpenClaw 还会在重复解密失败后，通过离开/重新加入语音会话来尝试恢复语音接收。
+- `channels.discord.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔型 `streaming` 值会被自动迁移。
+- `channels.discord.autoPresence` 会将运行时可用性映射为机器人状态（健康 => online，降级 => idle，耗尽 => dnd），并允许可选状态文本覆盖。
+- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（破玻璃兼容模式）。
+- `channels.discord.execApprovals`：Discord 原生的 exec 批准投递和批准者授权。
+ - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出批准者时，exec 批准会激活。
+ - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。
+ - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的批准请求。
- `sessionFilter`：可选的会话键模式（子串或正则）。
- - `target`：审批提示发送位置。`"dm"`（默认）发送到审批者私信，`"channel"` 发送到原始渠道，`"both"` 同时发送。若 target 包含 `"channel"`，按钮仅可由已解析的审批者使用。
- - `cleanupAfterResolve`：当为 `true` 时，在审批、拒绝或超时后删除审批私信。
+ - `target`：批准提示发送位置。`"dm"`（默认）发送到批准者私信，`"channel"` 发送到原始频道，`"both"` 同时发送。若 target 包含 `"channel"`，按钮仅对已解析出的批准者可用。
+ - `cleanupAfterResolve`：设为 `true` 时，在批准、拒绝或超时后删除批准私信。
-**反应通知模式：** `off`（无）、`own`（机器人自己的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users`，作用于所有消息）。
+**反应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users` 的所有消息）。
### Google Chat
@@ -382,8 +382,8 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在
- 服务账号 JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。
- 也支持服务账号 SecretRef（`serviceAccountRef`）。
- 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。
-- 交付目标使用 `spaces/` 或 `users/`。
-- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（紧急兼容模式）。
+- 使用 `spaces/` 或 `users/` 作为投递目标。
+- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（破玻璃兼容模式）。
### Slack
@@ -433,8 +433,8 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在
typingReaction: "hourglass_flowing_sand",
textChunkLimit: 4000,
chunkMode: "length",
- streaming: "partial", // off | partial | block | progress（预览模式）
- nativeStreaming: true, // 当 streaming=partial 时使用 Slack 原生流式 API
+ streaming: "partial", // off | partial | block | progress (preview mode)
+ nativeStreaming: true, // use Slack native streaming API when streaming=partial
mediaMaxMb: 20,
execApprovals: {
enabled: "auto", // true | false | "auto"
@@ -448,33 +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 模式下的 `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 mode 下的
+ `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 审批交付和审批者授权。与 Discord 使用相同 schema：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。
+- `typingReaction` 会在回复执行期间，为传入 Slack 消息添加临时反应，并在完成后移除。使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。
+- `channels.slack.execApprovals`：Slack 原生的 exec 批准投递和批准者授权。与 Discord 使用相同 schema：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。
-| 操作组 | 默认值 | 说明 |
-| ----------- | -------- | -------------------- |
-| reactions | 已启用 | 添加反应 + 列出反应 |
-| messages | 已启用 | 读取/发送/编辑/删除 |
-| pins | 已启用 | 置顶/取消置顶/列出 |
-| memberInfo | 已启用 | 成员信息 |
-| emojiList | 已启用 | 自定义 emoji 列表 |
+| 操作组 | 默认值 | 说明 |
+| ------------ | -------- | ---------------------- |
+| reactions | enabled | 反应 + 列出反应 |
+| messages | enabled | 读取/发送/编辑/删除 |
+| pins | enabled | 固定/取消固定/列出 |
+| memberInfo | enabled | 成员信息 |
+| emojiList | enabled | 自定义 emoji 列表 |
### Mattermost
-Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost`。
+Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermost`。
```json5
{
@@ -491,10 +495,10 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost`
"team-channel-id": { requireMention: false },
},
commands: {
- native: true, // 显式启用
+ native: true, // opt-in
nativeSkills: true,
callbackPath: "/api/channels/mattermost/command",
- // 反向代理/公网部署时可选的显式 URL
+ // Optional explicit URL for reverse-proxy/public deployments
callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
},
textChunkLimit: 4000,
@@ -504,21 +508,21 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost`
}
```
-聊天模式：`oncall`（在 @ 提及时回复，默认）、`onmessage`（每条消息都回复）、`onchar`（以触发前缀开头的消息）。
+聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（以触发前缀开头的消息）。
启用 Mattermost 原生命令时：
- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。
-- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器必须可访问该地址。
-- 原生 slash 回调使用 Mattermost 在 slash 命令注册期间返回的每命令 token 进行认证。如果注册失败或没有任何命令被激活，OpenClaw 会以
+- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器可访问。
+- 原生斜杠命令回调使用 Mattermost 在斜杠命令注册期间返回的每命令 token 进行身份验证。如果注册失败或没有激活任何命令，OpenClaw 会以
`Unauthorized: invalid command token.` 拒绝回调。
-- 对于私有/tailnet/内部回调主机，Mattermost 可能需要
+- 对于私有/tailnet/内部回调主机，Mattermost 可能要求
`ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。
- 使用主机/域名值，不要使用完整 URL。
+ 使用主机/域名值，而不是完整 URL。
- `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。
-- `channels.mattermost.requireMention`：在渠道中回复前要求 `@mention`。
-- `channels.mattermost.groups..requireMention`：每渠道的提及门控覆盖（`"*"` 表示默认）。
-- 可选的 `channels.mattermost.defaultAccount` 会在匹配已配置账号 id 时覆盖默认账号选择。
+- `channels.mattermost.requireMention`：在频道中回复前要求 `@mention`。
+- `channels.mattermost.groups..requireMention`：按频道设置的提及门控覆盖（`"*"` 用作默认值）。
+- 可选的 `channels.mattermost.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。
### Signal
@@ -527,7 +531,7 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost`
channels: {
signal: {
enabled: true,
- account: "+15555550123", // 可选账号绑定
+ account: "+15555550123", // optional account binding
dmPolicy: "pairing",
allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
configWrites: true,
@@ -541,9 +545,9 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost`
**反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。
-- `channels.signal.account`：将渠道启动固定到特定的 Signal 账号身份。
+- `channels.signal.account`：将渠道启动固定到特定 Signal 账号身份。
- `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。
-- 可选的 `channels.signal.defaultAccount` 会在匹配已配置账号 id 时覆盖默认账号选择。
+- 可选的 `channels.signal.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。
### BlueBubbles
@@ -555,21 +559,21 @@ BlueBubbles 是推荐的 iMessage 路径（插件支持，在 `channels.bluebubb
bluebubbles: {
enabled: true,
dmPolicy: "pairing",
- // serverUrl、password、webhookPath、群组控制和高级操作：
- // 参见 /channels/bluebubbles
+ // serverUrl, password, webhookPath, group controls, and advanced actions:
+ // see /channels/bluebubbles
},
},
}
```
-- 此处覆盖的核心键路径：`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)。
-- 完整的 BlueBubbles 渠道配置见 [BlueBubbles](/zh-CN/channels/bluebubbles)。
+- 此处涵盖的核心键路径：`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)。
+- 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles)。
### iMessage
-OpenClaw 会启动 `imsg rpc`（基于 stdio 的 JSON-RPC）。无需守护进程或端口。
+OpenClaw 会启动 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护进程或端口。
```json5
{
@@ -593,17 +597,17 @@ OpenClaw 会启动 `imsg rpc`（基于 stdio 的 JSON-RPC）。无需守护进
}
```
-- 可选的 `channels.imessage.defaultAccount` 会在匹配已配置账号 id 时覆盖默认账号选择。
+- 可选的 `channels.imessage.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。
-- 需要对 Messages DB 授予完整磁盘访问权限。
-- 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 可列出聊天。
-- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。
+- 需要对 Messages DB 具有完整磁盘访问权限。
+- 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。
+- `cliPath` 可以指向 SSH 包装脚本；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。
- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制传入附件路径（默认：`/Users/*/Library/Messages/Attachments`）。
-- SCP 使用严格主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。
+- SCP 使用严格的主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。
- `channels.imessage.configWrites`：允许或拒绝由 iMessage 发起的配置写入。
-- 顶层 `bindings[]` 中 `type: "acp"` 的条目可将 iMessage 会话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化后的 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。
+- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目可将 iMessage 会话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。
-
+
```bash
#!/usr/bin/env bash
@@ -614,7 +618,7 @@ exec ssh -T gateway-host imsg "$@"
### Matrix
-Matrix 由扩展支持，并在 `channels.matrix` 下配置。
+Matrix 由扩展提供支持，并在 `channels.matrix` 下配置。
```json5
{
@@ -644,24 +648,24 @@ Matrix 由扩展支持，并在 `channels.matrix` 下配置。
}
```
-- Token 认证使用 `accessToken`；密码认证使用 `userId` + `password`。
-- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可通过 `channels.matrix.accounts..proxy` 覆盖它。
-- `channels.matrix.allowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 和 `allowPrivateNetwork` 是彼此独立的控制项。
-- `channels.matrix.defaultAccount` 会在多账号配置中选择首选账号。
-- `channels.matrix.execApprovals`：Matrix 原生 exec 审批交付和审批者授权。
- - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批者时，会激活 exec 审批。
- - `approvers`：允许审批 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。
- - `agentFilter`：可选的智能体 ID 允许列表。省略时转发所有智能体的审批。
+- Token 身份验证使用 `accessToken`；密码身份验证使用 `userId` + `password`。
+- `channels.matrix.proxy` 通过显式 HTTP(S) 代理转发 Matrix HTTP 流量。命名账号可通过 `channels.matrix.accounts..proxy` 覆盖。
+- `channels.matrix.allowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 与 `allowPrivateNetwork` 是相互独立的控制项。
+- `channels.matrix.defaultAccount` 在多账号设置中选择首选账号。
+- `channels.matrix.execApprovals`：Matrix 原生的 exec 批准投递和批准者授权。
+ - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出批准者时，exec 批准会激活。
+ - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。
+ - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的批准请求。
- `sessionFilter`：可选的会话键模式（子串或正则）。
- - `target`：审批提示发送位置。`"dm"`（默认）、`"channel"`（原始房间）或 `"both"`。
- - 每账号覆盖：`channels.matrix.accounts..execApprovals`。
-- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归入会话：`per-user`（默认）按路由对端共享，`per-room` 则隔离每个私信房间。
-- Matrix 状态探测和实时目录查找与运行时流量使用相同的代理策略。
-- 完整的 Matrix 配置、目标规则和设置示例见 [Matrix](/zh-CN/channels/matrix)。
+ - `target`：批准提示发送位置。`"dm"`（默认）、`"channel"`（原始房间）或 `"both"`。
+ - 按账号覆盖：`channels.matrix.accounts..execApprovals`。
+- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归入会话：`per-user`（默认）按路由 peer 共享，`per-room` 将每个私信房间隔离开。
+- Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。
+- 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix)。
### Microsoft Teams
-Microsoft Teams 由扩展支持，并在 `channels.msteams` 下配置。
+Microsoft Teams 由扩展提供支持，并在 `channels.msteams` 下配置。
```json5
{
@@ -669,19 +673,19 @@ Microsoft Teams 由扩展支持，并在 `channels.msteams` 下配置。
msteams: {
enabled: true,
configWrites: true,
- // appId、appPassword、tenantId、webhook、团队/渠道策略：
- // 参见 /channels/msteams
+ // appId, appPassword, tenantId, webhook, team/channel policies:
+ // see /channels/msteams
},
},
}
```
-- 此处覆盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。
-- 完整的 Teams 配置（凭据、webhook、私信/群组策略、每团队/每渠道覆盖）见 [Microsoft Teams](/zh-CN/channels/msteams)。
+- 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。
+- 完整的 Teams 配置（凭证、webhook、私信/群组策略、按团队/频道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams)。
### IRC
-IRC 由扩展支持，并在 `channels.irc` 下配置。
+IRC 由扩展提供支持，并在 `channels.irc` 下配置。
```json5
{
@@ -702,13 +706,13 @@ 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`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。
+- 可选的 `channels.irc.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。
+- 完整的 IRC 渠道配置（主机/端口/TLS/频道/允许列表/提及门控）记录在 [IRC](/zh-CN/channels/irc)。
### 多账号（所有渠道）
-每个渠道运行多个账号（每个都有自己的 `accountId`）：
+为每个渠道运行多个账号（每个账号都有自己的 `accountId`）：
```json5
{
@@ -730,27 +734,27 @@ 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 则可以保留现有的匹配命名/默认目标。
+- 环境变量 token 仅适用于**默认**账号。
+- 基础渠道设置会应用到所有账号，除非在每账号级别被覆盖。
+- 使用 `bindings[].match.accountId` 将每个账号路由到不同智能体。
+- 如果你在仍为单账号顶层渠道配置时，通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，OpenClaw 会先将账号作用域的顶层单账号值提升到渠道账号映射中，以确保原账号继续工作。大多数渠道会将其移到 `channels..accounts.default`；Matrix 则可以保留现有匹配的命名/默认目标。
+- 现有的仅渠道绑定（无 `accountId`）仍会匹配默认账号；账号作用域绑定仍是可选的。
+- `openclaw doctor --fix` 也会通过将账号作用域的顶层单账号值移动到为该渠道选定的提升后账号中来修复混合形状。大多数渠道使用 `accounts.default`；Matrix 则可以保留现有匹配的命名/默认目标。
### 其他扩展渠道
-许多扩展渠道以 `channels.` 的形式配置，并记录在各自的专用渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。
-查看完整渠道索引：[Channels](/zh-CN/channels)。
+许多扩展渠道配置为 `channels.`，并在其专用渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。
+请参见完整渠道索引：[Channels](/zh-CN/channels)。
### 群聊提及门控
-群组消息默认 **要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。
+群组消息默认**要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。
**提及类型：**
-- **元数据提及**：平台原生 @ 提及。在 WhatsApp self-chat 模式下会被忽略。
-- **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。
-- 仅在能够检测到提及时（原生提及或至少一个模式），才会强制执行提及门控。
+- **元数据提及**：原生平台 @ 提及。在 WhatsApp 自聊模式下会被忽略。
+- **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。
+- 仅在可以检测到提及时（原生提及或至少一个模式），才会强制执行提及门控。
```json5
{
@@ -763,7 +767,7 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。
}
```
-`messages.groupChat.historyLimit` 设置全局默认值。渠道可以使用 `channels..historyLimit`（或每账号值）来覆盖。设置为 `0` 可禁用。
+`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号）覆盖。设置为 `0` 以禁用。
#### 私信历史限制
@@ -780,13 +784,13 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。
}
```
-解析顺序：每私信覆盖 → 提供商默认值 → 不限（全部保留）。
+解析顺序：按私信覆盖 → 提供商默认值 → 不限制（全部保留）。
支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。
-#### self-chat 模式
+#### 自聊模式
-将你自己的号码包含在 `allowFrom` 中以启用 self-chat 模式（忽略原生 @ 提及，仅响应文本模式）：
+将你自己的号码包含在 `allowFrom` 中以启用自聊模式（忽略原生 @ 提及，仅响应文本模式）：
```json5
{
@@ -812,13 +816,13 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。
```json5
{
commands: {
- native: "auto", // 在支持的平台上注册原生命令
- text: true, // 解析聊天消息中的 /commands
- bash: false, // 允许 !（别名：/bash）
+ native: "auto", // register native commands when supported
+ text: true, // parse /commands in chat messages
+ bash: false, // allow ! (alias: /bash)
bashForegroundMs: 2000,
- config: false, // 允许 /config
- debug: false, // 允许 /debug
- restart: false, // 允许 /restart + gateway restart 工具
+ config: false, // allow /config
+ debug: false, // allow /debug
+ restart: false, // allow /restart + gateway restart tool
allowFrom: {
"*": ["user1"],
discord: ["user:123"],
@@ -831,15 +835,15 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。
- 文本命令必须是带前导 `/` 的**独立**消息。
-- `native: "auto"` 会为 Discord/Telegram 打开原生命令，但保持 Slack 关闭。
-- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前注册的命令。
+- `native: "auto"` 会为 Discord/Telegram 打开原生命令，而对 Slack 保持关闭。
+- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"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）。
+- `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` 时让命令绕过访问组策略。
+- `allowFrom` 按提供商生效。设置后，它会成为**唯一**授权来源（渠道允许列表/配对和 `useAccessGroups` 都会被忽略）。
+- `useAccessGroups: false` 会在 `allowFrom` 未设置时，允许命令绕过访问组策略。
@@ -859,7 +863,7 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。
### `agents.defaults.repoRoot`
-可选的仓库根目录，会显示在系统提示词的 Runtime 行中。如果未设置，OpenClaw 会从工作区开始向上遍历并自动检测。
+可选的仓库根目录，会显示在系统提示的 Runtime 行中。若未设置，OpenClaw 会从工作区向上遍历自动检测。
```json5
{
@@ -876,22 +880,22 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。
agents: {
defaults: { skills: ["github", "weather"] },
list: [
- { id: "writer" }, // 继承 github、weather
- { id: "docs", skills: ["docs-search"] }, // 替换默认值
- { id: "locked-down", skills: [] }, // 无 Skills
+ { id: "writer" }, // inherits github, weather
+ { id: "docs", skills: ["docs-search"] }, // replaces defaults
+ { id: "locked-down", skills: [] }, // no skills
],
},
}
```
-- 省略 `agents.defaults.skills`，则默认 Skills 不受限制。
-- 省略 `agents.list[].skills` 将继承默认值。
-- 设置 `agents.list[].skills: []` 表示无 Skills。
+- 省略 `agents.defaults.skills` 表示默认 Skills 不受限制。
+- 省略 `agents.list[].skills` 则继承默认值。
+- 设置 `agents.list[].skills: []` 表示不允许任何 Skills。
- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；不会与默认值合并。
### `agents.defaults.skipBootstrap`
-禁用自动创建工作区引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。
+禁用工作区 bootstrap 文件的自动创建（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。
```json5
{
@@ -899,9 +903,21 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。
}
```
+### `agents.defaults.contextInjection`
+
+控制何时将工作区 bootstrap 文件注入系统提示。默认值：`"always"`。
+
+- `"continuation-skip"`：安全续写轮次（在助手完成响应之后）会跳过重新注入工作区 bootstrap，从而减少提示大小。心跳运行和压缩后重试仍会重建上下文。
+
+```json5
+{
+ agents: { defaults: { contextInjection: "continuation-skip" } },
+}
+```
+
### `agents.defaults.bootstrapMaxChars`
-单个工作区引导文件在截断前的最大字符数。默认值：`20000`。
+工作区每个 bootstrap 文件在被截断前允许的最大字符数。默认值：`20000`。
```json5
{
@@ -911,7 +927,7 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。
### `agents.defaults.bootstrapTotalMaxChars`
-所有工作区引导文件注入内容的总最大字符数。默认值：`150000`。
+所有工作区 bootstrap 文件合计注入的最大字符数。默认值：`150000`。
```json5
{
@@ -921,11 +937,11 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。
### `agents.defaults.bootstrapPromptTruncationWarning`
-控制当引导上下文被截断时，对智能体可见的警告文本。
+控制当 bootstrap 上下文被截断时，对智能体可见的警告文本。
默认值：`"once"`。
-- `"off"`：绝不在系统提示词中注入警告文本。
-- `"once"`：每个唯一截断签名仅注入一次警告（推荐）。
+- `"off"`：绝不将警告文本注入系统提示。
+- `"once"`：对每个唯一的截断签名只注入一次警告（推荐）。
- `"always"`：只要存在截断，每次运行都注入警告。
```json5
@@ -936,11 +952,11 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。
### `agents.defaults.imageMaxDimensionPx`
-在调用提供商前，transcript/tool 图像块中最长边的最大像素尺寸。
+在调用提供商之前，转录/工具图片块中图像最长边的最大像素尺寸。
默认值：`1200`。
-较低值通常会减少视觉 token 使用量和请求负载大小，适合包含大量截图的运行。
-较高值则会保留更多视觉细节。
+较低的值通常会减少视觉 token 使用量和请求负载大小，特别适合截图较多的运行。
+较高的值则保留更多视觉细节。
```json5
{
@@ -950,7 +966,7 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。
### `agents.defaults.userTimezone`
-系统提示词上下文使用的时区（不影响消息时间戳）。会回退到主机时区。
+系统提示上下文所用时区（不影响消息时间戳）。会回退到宿主机时区。
```json5
{
@@ -960,7 +976,7 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。
### `agents.defaults.timeFormat`
-系统提示词中的时间格式。默认值：`auto`（操作系统偏好）。
+系统提示中的时间格式。默认值：`auto`（操作系统偏好）。
```json5
{
@@ -998,7 +1014,7 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5.4-mini"],
},
- params: { cacheRetention: "long" }, // 全局默认 provider 参数
+ params: { cacheRetention: "long" }, // global default provider params
pdfMaxBytesMb: 10,
pdfMaxPages: 20,
thinkingDefault: "low",
@@ -1013,43 +1029,43 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。
}
```
-- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
+- `model`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 字符串形式只设置主模型。
- - 对象形式设置主模型以及有序故障转移模型。
-- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- - 被 `image` 工具路径用作其视觉模型配置。
- - 当已选/默认模型不能接受图像输入时，也用作后备路由。
-- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- - 用于共享的图像生成能力以及任何未来生成图像的工具/插件接口。
- - 常见值：`google/gemini-3.1-flash-image-preview`（Gemini 原生图像生成）、`fal/fal-ai/flux/dev`（fal）或 `openai/gpt-image-1`（OpenAI Images）。
- - 如果你直接选择某个 provider/model，也需要配置匹配的提供商认证/API key（例如 `google/*` 的 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 的 `OPENAI_API_KEY`，`fal/*` 的 `FAL_KEY`）。
- - 如果省略，`image_generate` 仍可推断出基于认证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的图像生成提供商。
-- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- - 用于共享的音乐生成能力和内置 `music_generate` 工具。
- - 常见值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。
- - 如果省略，`music_generate` 仍可推断出基于认证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的音乐生成提供商。
- - 如果你直接选择某个 provider/model，也需要配置匹配的提供商认证/API key。
-- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- - 用于共享的视频生成能力和内置 `video_generate` 工具。
- - 常见值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。
- - 如果省略，`video_generate` 仍可推断出基于认证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的视频生成提供商。
- - 如果你直接选择某个 provider/model，也需要配置匹配的提供商认证/API key。
- - 内置的 Qwen 视频生成提供商当前最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。
-- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- - 被 `pdf` 工具用于模型路由。
+ - 对象形式设置主模型及有序故障转移模型。
+- `imageModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
+ - 由 `image` 工具路径作为其视觉模型配置使用。
+ - 当选定/默认模型无法接受图像输入时，也作为回退路由使用。
+- `imageGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
+ - 由共享图像生成能力以及任何未来会生成图像的工具/插件接口使用。
+ - 典型值：`google/gemini-3.1-flash-image-preview`（Gemini 原生图像生成）、`fal/fal-ai/flux/dev`（fal）或 `openai/gpt-image-1`（OpenAI Images）。
+ - 如果你直接选择某个提供商/模型，也要配置对应的提供商身份验证/API key（例如 `google/*` 需要 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 需要 `OPENAI_API_KEY`，`fal/*` 需要 `FAL_KEY`）。
+ - 如果省略，`image_generate` 仍然可以推断出基于身份验证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。
+- `musicGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
+ - 由共享音乐生成能力和内置 `music_generate` 工具使用。
+ - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。
+ - 如果省略，`music_generate` 仍然可以推断出基于身份验证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。
+ - 如果你直接选择某个提供商/模型，也要配置对应的提供商身份验证/API key。
+- `videoGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
+ - 由共享视频生成能力和内置 `video_generate` 工具使用。
+ - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。
+ - 如果省略，`video_generate` 仍然可以推断出基于身份验证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。
+ - 如果你直接选择某个提供商/模型，也要配置对应的提供商身份验证/API key。
+ - 当前内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图片、4 个输入视频、10 秒时长，以及提供商级 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。
+- `pdfModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
+ - 由 `pdf` 工具用于模型路由。
- 如果省略，PDF 工具会回退到 `imageModel`，再回退到已解析的会话/默认模型。
-- `pdfMaxBytesMb`：当调用时未传递 `maxBytesMb` 时，`pdf` 工具使用的默认 PDF 大小限制。
-- `pdfMaxPages`：`pdf` 工具在提取回退模式下默认考虑的最大页数。
-- `verboseDefault`：智能体默认 verbose 级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。
-- `elevatedDefault`：智能体默认 elevated 输出级别。取值：`"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`（provider 特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。
-- `params`：应用到所有模型的全局默认 provider 参数。设置在 `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` 和后备 add/remove 命令）会保存规范对象形式，并尽可能保留现有后备列表。
-- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍然串行）。默认值：4。
+- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具使用的默认 PDF 大小限制。
+- `pdfMaxPages`：`pdf` 工具在提取回退模式下考虑的默认最大页数。
+- `verboseDefault`：智能体的默认详细级别。取值：`"off"`、`"on"`、`"full"`。默认：`"off"`。
+- `elevatedDefault`：智能体的默认提权输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认：`"on"`。
+- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果省略提供商，OpenClaw 会先尝试别名，然后尝试精确模型 ID 的唯一已配置提供商匹配，最后才会回退到已配置的默认提供商（已弃用的兼容行为，因此建议显式使用 `provider/model`）。如果该提供商不再暴露已配置默认模型，OpenClaw 会回退到第一个已配置提供商/模型，而不是继续使用已移除提供商的过时默认值。
+- `models`：为 `/model` 配置的模型目录和允许列表。每个条目可包含 `alias`（快捷名）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。
+- `params`：适用于所有模型的全局默认提供商参数。设置在 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。
+- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（每模型）覆盖，然后 `agents.list[].params`（匹配的智能体 ID）再按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。
+- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 和回退模型的添加/移除命令）会保存为规范对象形式，并尽可能保留现有回退列表。
+- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍然串行）。默认：4。
-**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时才生效）：
+**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）：
| 别名 | 模型 |
| ------------------- | -------------------------------------- |
@@ -1062,14 +1078,14 @@ IRC 由扩展支持，并在 `channels.irc` 下配置。
| `gemini-flash` | `google/gemini-3-flash-preview` |
| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` |
-你配置的别名始终优先于默认值。
+你自己配置的别名始终优先于默认值。
-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。
-- 当设置了 `sessionArg` 时，支持会话。
-- 当 `imageArg` 接受文件路径时，支持图像透传。
+- 当设置了 `sessionArg` 时支持会话。
+- 当 `imageArg` 接受文件路径时支持图像透传。
### `agents.defaults.heartbeat`
@@ -1080,15 +1096,15 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用
agents: {
defaults: {
heartbeat: {
- every: "30m", // 0m 禁用
+ every: "30m", // 0m disables
model: "openai/gpt-5.4-mini",
includeReasoning: false,
- lightContext: false, // 默认：false；true 时仅从工作区引导文件中保留 HEARTBEAT.md
- isolatedSession: false, // 默认：false；true 时每次心跳都在一个全新会话中运行（无对话历史）
+ lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
+ isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
session: "main",
to: "+15555550123",
- directPolicy: "allow", // allow（默认）| block
- target: "none", // 默认：none | 可选：last | whatsapp | telegram | discord | ...
+ directPolicy: "allow", // allow (default) | block
+ target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
prompt: "Read HEARTBEAT.md if it exists...",
ackMaxChars: 300,
suppressToolErrorWarnings: false,
@@ -1098,13 +1114,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用
}
```
-- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。
-- `suppressToolErrorWarnings`：为 true 时，在心跳运行期间抑制工具错误警告负载。
-- `directPolicy`：直接/私信交付策略。`allow`（默认）允许直接目标交付。`block` 会抑制直接目标交付，并发出 `reason=dm-blocked`。
-- `lightContext`：为 true 时，心跳运行使用轻量级引导上下文，并且仅保留工作区引导文件中的 `HEARTBEAT.md`。
-- `isolatedSession`：为 true 时，每次心跳都在一个没有先前对话历史的全新会话中运行。与 cron `sessionTarget: "isolated"` 的隔离模式相同。可将每次心跳的 token 成本从约 100K 降至约 2-5K。
-- 每智能体：设置 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。
-- 心跳会运行完整智能体轮次——间隔越短，消耗的 token 越多。
+- `every`：持续时间字符串（ms/s/m/h）。默认值：`30m`（API key 身份验证）或 `1h`（OAuth 身份验证）。设为 `0m` 可禁用。
+- `suppressToolErrorWarnings`：设为 true 时，在心跳运行期间抑制工具错误警告负载。
+- `directPolicy`：direct/私信投递策略。`allow`（默认）允许 direct 目标投递。`block` 会阻止 direct 目标投递并发出 `reason=dm-blocked`。
+- `lightContext`：设为 true 时，心跳运行使用轻量 bootstrap 上下文，并且只保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。
+- `isolatedSession`：设为 true 时，每次心跳都会在一个全新会话中运行，不带任何先前对话历史。与 cron 的 `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次心跳的 token 成本从约 100K 降至约 2-5K。
+- 按智能体：设置 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。
+- 心跳会运行完整的智能体轮次——间隔越短，消耗的 token 越多。
### `agents.defaults.compaction`
@@ -1117,10 +1133,10 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用
timeoutSeconds: 900,
reserveTokensFloor: 24000,
identifierPolicy: "strict", // strict | off | 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）
+ identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
+ postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
+ model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
+ notifyUser: true, // send a brief notice when compaction starts (default: false)
memoryFlush: {
enabled: true,
softThresholdTokens: 6000,
@@ -1133,18 +1149,18 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用
}
```
-- `mode`：`default` 或 `safeguard`（针对长历史记录的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。
-- `timeoutSeconds`：OpenClaw 在中止前允许单次 compaction 操作持续的最大秒数。默认值：`900`。
+- `mode`：`default` 或 `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
{
@@ -1152,7 +1168,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用
defaults: {
contextPruning: {
mode: "cache-ttl", // off | cache-ttl
- ttl: "1h", // 时长（ms/s/m/h），默认单位：分钟
+ ttl: "1h", // duration (ms/s/m/h), default unit: minutes
keepLastAssistants: 3,
softTrimRatio: 0.3,
hardClearRatio: 0.5,
@@ -1168,23 +1184,23 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用
-- `mode: "cache-ttl"` 会启用修剪过程。
-- `ttl` 控制在上次缓存触碰之后，多久可以再次运行修剪。
-- 修剪会先对超大的工具结果进行软裁剪，如有需要再对更旧的工具结果进行硬清除。
+- `mode: "cache-ttl"` 启用修剪过程。
+- `ttl` 控制修剪在上次缓存触碰后，多久之后才能再次运行。
+- 修剪会先对过大的工具结果执行软裁剪，如仍需要则对更旧的工具结果执行硬清除。
-**软裁剪**保留开头和结尾，并在中间插入 `...`。
+**软裁剪**会保留开头和结尾，并在中间插入 `...`。
**硬清除**会用占位符替换整个工具结果。
注意：
- 图像块永远不会被裁剪/清除。
-- 比例按字符数计算（近似），不是精确 token 数。
-- 如果 assistant 消息数量少于 `keepLastAssistants`，则跳过修剪。
+- 比例按字符计算（近似），不是精确 token 计数。
+- 如果助手消息数量少于 `keepLastAssistants`，则跳过修剪。
-行为详情请参见 [Session Pruning](/zh-CN/concepts/session-pruning)。
+行为细节参见 [Session Pruning](/zh-CN/concepts/session-pruning)。
### 分块流式传输
@@ -1196,19 +1212,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用
blockStreamingBreak: "text_end", // text_end | message_end
blockStreamingChunk: { minChars: 800, maxChars: 1200 },
blockStreamingCoalesce: { idleMs: 1000 },
- humanDelay: { mode: "natural" }, // off | natural | custom（使用 minMs/maxMs）
+ humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs)
},
},
}
```
- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。
-- 渠道覆盖：`channels..blockStreamingCoalesce`（以及每账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
-- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。每智能体覆盖：`agents.list[].humanDelay`。
+- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
+- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。
-行为和分块细节请参见 [Streaming](/zh-CN/concepts/streaming)。
+行为和分块细节参见 [Streaming](/zh-CN/concepts/streaming)。
-### 输入中指示器
+### 输入指示器
```json5
{
@@ -1221,8 +1237,8 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用
}
```
-- 默认值：私聊/被提及时使用 `instant`，未被提及的群聊使用 `message`。
-- 每会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。
+- 默认值：私聊/被提及时为 `instant`，未被提及的群聊中为 `message`。
+- 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。
参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。
@@ -1230,7 +1246,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用
### `agents.defaults.sandbox`
-为嵌入式智能体提供可选沙箱隔离。完整指南请参见 [Sandboxing](/zh-CN/gateway/sandboxing)。
+嵌入式智能体的可选沙箱隔离。完整指南参见 [Sandboxing](/zh-CN/gateway/sandboxing)。
```json5
{
@@ -1276,7 +1292,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用
identityFile: "~/.ssh/id_ed25519",
certificateFile: "~/.ssh/id_ed25519-cert.pub",
knownHostsFile: "~/.ssh/known_hosts",
- // 也支持 SecretRef / 内联内容：
+ // SecretRefs / inline contents also supported:
// identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
// certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
// knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
@@ -1340,30 +1356,30 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用
- `target`：`user@host[:port]` 形式的 SSH 目标
- `command`：SSH 客户端命令（默认：`ssh`）
-- `workspaceRoot`：用于每个作用域工作区的绝对远程根路径
+- `workspaceRoot`：用于按作用域工作区的远程绝对根目录
- `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件
- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件
-- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略旋钮
+- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关
-**SSH 认证优先级：**
+**SSH 身份验证优先级：**
- `identityData` 优先于 `identityFile`
- `certificateData` 优先于 `certificateFile`
- `knownHostsData` 优先于 `knownHostsFile`
-- 基于 SecretRef 的 `*Data` 值会在沙箱会话开始前从活动 secrets 运行时快照中解析
+- 由 SecretRef 支持的 `*Data` 值会在沙箱会话开始前，从当前激活的 secrets 运行时快照中解析
**SSH 后端行为：**
-- 在创建或重建后，向远程工作区执行一次初始化填充
-- 之后保持远程 SSH 工作区为规范副本
+- 在创建或重建后，初始化远程工作区一次
+- 然后保持远程 SSH 工作区为规范副本
- 通过 SSH 路由 `exec`、文件工具和媒体路径
-- 不会自动将远程更改同步回主机
+- 不会自动将远程更改同步回宿主机
- 不支持沙箱浏览器容器
**工作区访问：**
- `none`：在 `~/.openclaw/sandboxes` 下为每个作用域创建沙箱工作区
-- `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent`
+- `ro`：沙箱工作区位于 `/workspace`，智能体工作区只读挂载到 `/agent`
- `rw`：智能体工作区以读写方式挂载到 `/workspace`
**作用域：**
@@ -1385,10 +1401,10 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用
from: "openclaw",
remoteWorkspaceDir: "/sandbox",
remoteAgentWorkspaceDir: "/agent",
- gateway: "lab", // 可选
- gatewayEndpoint: "https://lab.example", // 可选
- policy: "strict", // 可选 OpenShell policy id
- providers: ["openai"], // 可选
+ gateway: "lab", // optional
+ gatewayEndpoint: "https://lab.example", // optional
+ policy: "strict", // optional OpenShell policy id
+ providers: ["openai"], // optional
autoProviders: true,
timeoutSeconds: 120,
},
@@ -1400,31 +1416,30 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用
**OpenShell 模式：**
-- `mirror`：在 exec 前从本地初始化远程，exec 后再同步回本地；本地工作区保持为规范副本
-- `remote`：仅在创建沙箱时向远程初始化一次，之后保持远程工作区为规范副本
+- `mirror`：执行前将本地内容播种到远端，执行后同步回来；本地工作区保持为规范副本
+- `remote`：沙箱创建时只向远端播种一次，之后保持远程工作区为规范副本
-在 `remote` 模式下，于 OpenClaw 外部在主机本地做出的修改，在初始化步骤之后不会自动同步到沙箱。
+在 `remote` 模式下，种子步骤之后，在 OpenClaw 外部对宿主机本地所做的编辑不会自动同步进沙箱。
+传输方式是通过 SSH 连接到 OpenShell 沙箱，但插件负责沙箱生命周期和可选的镜像同步。
-传输使用 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期和可选的镜像同步。
+**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。它需要网络出口、可写根文件系统以及 root 用户。
-**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统以及 root 用户。
+**容器默认使用 `network: "none"`**——如果智能体需要对外访问，请设置为 `"bridge"`（或自定义 bridge 网络）。
+默认会阻止 `"host"`。除非你显式设置
+`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（破玻璃模式），否则也会默认阻止 `"container:"`。
-**容器默认使用 `network: "none"`**——如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。
-默认阻止 `"host"`。默认也会阻止 `"container:"`，除非你显式设置
-`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急模式）。
+**传入附件**会被暂存到活动工作区中的 `media/inbound/*`。
-**传入附件** 会暂存到当前活动工作区中的 `media/inbound/*`。
+**`docker.binds`** 会挂载额外的宿主目录；全局和按智能体的绑定会被合并。
-**`docker.binds`** 会挂载额外的主机目录；全局和每智能体 binds 会合并。
+**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会被注入系统提示。不需要在 `openclaw.json` 中启用 `browser.enabled`。
+noVNC 观察者访问默认使用 VNC 身份验证，并且 OpenClaw 会发出短时有效 token URL（而不是在共享 URL 中暴露密码）。
-**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。会将 noVNC URL 注入系统提示词中。不需要在 `openclaw.json` 中启用 `browser.enabled`。
-noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有效的 token URL（而不是在共享 URL 中暴露密码）。
-
-- `allowHostControl: false`（默认）会阻止沙箱会话把目标指向主机浏览器。
-- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。仅当你明确需要全局 bridge 连接性时，才设置为 `bridge`。
-- `cdpSourceRange` 可选地将容器边缘的 CDP 入站限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。
-- `sandbox.browser.binds` 仅向沙箱浏览器容器挂载额外主机目录。设置后（包括 `[]`）会替换浏览器容器的 `docker.binds`。
-- 启动默认值定义于 `scripts/sandbox-browser-entrypoint.sh`，并针对容器主机进行过调优：
+- `allowHostControl: false`（默认）会阻止沙箱隔离会话定位宿主浏览器。
+- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。仅当你明确需要全局 bridge 连通性时才设为 `bridge`。
+- `cdpSourceRange` 可选择在容器边界通过 CIDR 范围限制 CDP 入站（例如 `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`
@@ -1442,14 +1457,13 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有
- `--no-zygote`
- `--metrics-recording-only`
- `--disable-extensions`（默认启用）
- - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu`
- 默认启用；如果 WebGL/3D 使用场景需要，可以通过
- `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 关闭。
+ - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` 默认启用，如需 WebGL/3D，可通过设置
+ `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 来禁用它们。
- `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展，如果你的工作流依赖它们。
- `--renderer-process-limit=2` 可通过
- `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设置为 `0` 则使用 Chromium 的默认进程限制。
+ `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 可使用 Chromium 的默认进程限制。
- 当启用 `noSandbox` 时，还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。
- - 这些默认值是容器镜像基线；如需更改容器默认行为，请使用带自定义入口点的自定义浏览器镜像。
+ - 这些默认值是容器镜像基线；如需更改容器默认值，请使用自定义浏览器镜像和自定义入口点。
@@ -1458,11 +1472,11 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有
构建镜像：
```bash
-scripts/sandbox-setup.sh # 主沙箱镜像
-scripts/sandbox-browser-setup.sh # 可选浏览器镜像
+scripts/sandbox-setup.sh # main sandbox image
+scripts/sandbox-browser-setup.sh # optional browser image
```
-### `agents.list`（每智能体覆盖）
+### `agents.list`（按智能体覆盖）
```json5
{
@@ -1474,12 +1488,12 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
name: "Main Agent",
workspace: "~/.openclaw/workspace",
agentDir: "~/.openclaw/agents/main/agent",
- model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks }
- thinkingDefault: "high", // 每智能体 thinking 级别覆盖
- reasoningDefault: "on", // 每智能体 reasoning 可见性覆盖
- fastModeDefault: false, // 每智能体 fast mode 覆盖
- params: { cacheRetention: "none" }, // 按键覆盖匹配 defaults.models params
- skills: ["docs-search"], // 设置时会替换 agents.defaults.skills
+ model: "anthropic/claude-opus-4-6", // or { primary, fallbacks }
+ thinkingDefault: "high", // per-agent thinking level override
+ reasoningDefault: "on", // per-agent reasoning visibility override
+ fastModeDefault: false, // per-agent fast mode override
+ params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
+ skills: ["docs-search"], // replaces agents.defaults.skills when set
identity: {
name: "Samantha",
theme: "helpful sloth",
@@ -1510,26 +1524,26 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
}
```
-- `id`：稳定的智能体 id（必需）。
-- `default`：当设置了多个时，以第一个为准（会记录警告）。如果都未设置，则列表第一项为默认。
-- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖二者（`[]` 禁用全局后备）。仅覆盖 `primary` 的 cron 任务仍会继承默认后备，除非你设置 `fallbacks: []`。
-- `params`：按智能体区分的流参数，合并到 `agents.defaults.models` 中所选模型条目之上。用于智能体特定覆盖，如 `cacheRetention`、`temperature` 或 `maxTokens`，而不必复制整个模型目录。
-- `skills`：可选的每智能体 Skills 允许列表。若省略，智能体会在已设置时继承 `agents.defaults.skills`；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。
-- `thinkingDefault`：可选的每智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。当未设置每消息或每会话覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。
-- `reasoningDefault`：可选的每智能体默认 reasoning 可见性（`on | off | stream`）。当未设置每消息或每会话 reasoning 覆盖时生效。
-- `fastModeDefault`：可选的每智能体默认 fast mode（`true | false`）。当未设置每消息或每会话 fast-mode 覆盖时生效。
-- `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`：可选的按智能体 fast mode 默认值（`true | false`）。当未设置按消息或按会话的 fast mode 覆盖时生效。
+- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 并设置 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。
- `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。
- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。
-- `subagents.allowAgents`：`sessions_spawn` 的智能体 id 允许列表（`["*"]` = 任意；默认：仅同一智能体）。
-- 沙箱继承保护：如果请求方会话位于沙箱中，`sessions_spawn` 会拒绝那些将以非沙箱方式运行的目标。
+- `subagents.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
{
@@ -1548,11 +1562,11 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
### 绑定匹配字段
-- `type`（可选）：正常路由使用 `route`（缺失 type 时默认是 route），持久 ACP 会话绑定使用 `acp`。
-- `match.channel`（必需）
+- `type`（可选）：正常路由用 `route`（缺失时默认 route），持久 ACP 会话绑定用 `acp`
+- `match.channel`（必填）
- `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号）
- `match.peer`（可选；`{ kind: direct|group|channel, id }`）
-- `match.guildId` / `match.teamId`（可选；渠道特定）
+- `match.guildId` / `match.teamId`（可选；特定渠道使用）
- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }`
**确定性匹配顺序：**
@@ -1560,15 +1574,15 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
1. `match.peer`
2. `match.guildId`
3. `match.teamId`
-4. `match.accountId`（精确匹配，无 peer/guild/team）
-5. `match.accountId: "*"`（整个渠道范围）
+4. `match.accountId`（精确，无 peer/guild/team）
+5. `match.accountId: "*"`（渠道级）
6. 默认智能体
-在每个层级内，第一个匹配的 `bindings` 条目获胜。
+在每一层中，第一个匹配的 `bindings` 条目胜出。
-对于 `type: "acp"` 条目，OpenClaw 按精确会话身份（`match.channel` + account + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。
+对于 `type: "acp"` 条目，OpenClaw 会通过精确会话身份（`match.channel` + 账号 + `match.peer.id`）解析，而不会使用上述 route 绑定分层顺序。
-### 每智能体访问配置
+### 按智能体访问配置
@@ -1663,11 +1677,11 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
-优先级细节请参见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。
+优先级细节参见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。
---
-## 会话
+## Session 会话
```json5
{
@@ -1689,22 +1703,22 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
},
resetTriggers: ["/new", "/reset"],
store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
- parentForkMaxTokens: 100000, // 超过此 token 数则跳过父线程 fork（0 表示禁用）
+ parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables)
maintenance: {
mode: "warn", // warn | enforce
pruneAfter: "30d",
maxEntries: 500,
rotateBytes: "10mb",
- resetArchiveRetention: "30d", // 时长或 false
- maxDiskBytes: "500mb", // 可选硬预算
- highWaterBytes: "400mb", // 可选清理目标
+ resetArchiveRetention: "30d", // duration or false
+ maxDiskBytes: "500mb", // optional hard budget
+ highWaterBytes: "400mb", // optional cleanup target
},
threadBindings: {
enabled: true,
- idleHours: 24, // 默认以小时为单位的非活动自动取消聚焦（`0` 表示禁用）
- maxAgeHours: 0, // 默认以小时为单位的最大存活时间硬限制（`0` 表示禁用）
+ idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
+ maxAgeHours: 0, // default hard max age in hours (`0` disables)
},
- mainKey: "main", // 旧版字段（运行时始终使用 "main"）
+ mainKey: "main", // legacy (runtime always uses "main")
agentToAgent: { maxPingPongTurns: 5 },
sendPolicy: {
rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
@@ -1714,48 +1728,48 @@ 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 会启动新的线程会话，而不是继承父 transcript 历史。
- - 设置为 `0` 可禁用此保护，并始终允许父 fork。
-- **`mainKey`**：旧版字段。运行时现在始终对主私聊桶使用 `"main"`。
-- **`agentToAgent.maxPingPongTurns`**：智能体互相交流时的最大来回回复轮数（整数，范围：`0`–`5`）。`0` 表示禁用乒乓链接续。
-- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 优先。
-- **`maintenance`**：会话存储清理和保留控制。
- - `mode`：`warn` 仅发出警告；`enforce` 应用清理。
- - `pruneAfter`：过期条目的时间阈值（默认 `30d`）。
+- **`identityLinks`**：将规范 ID 映射到带提供商前缀的 peer，用于跨渠道共享会话。
+- **`reset`**：主重置策略。`daily` 在本地时间 `atHour` 重置；`idle` 在 `idleMinutes` 后重置。当两者都配置时，先到期者生效。
+- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名接受。
+- **`parentForkMaxTokens`**：创建分叉线程会话时允许的父会话 `totalTokens` 最大值（默认 `100000`）。
+ - 如果父会话的 `totalTokens` 超过此值，OpenClaw 会启动新的线程会话，而不是继承父转录历史。
+ - 设为 `0` 可禁用此保护，并始终允许父级分叉。
+- **`mainKey`**：旧版字段。运行时现在始终使用 `"main"` 作为主私聊桶。
+- **`agentToAgent.maxPingPongTurns`**：智能体之间进行 agent-to-agent 交换时，允许的最大来回回复轮次（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链接。
+- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 可作为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 胜出。
+- **`maintenance`**：会话存储清理 + 保留控制。
+ - `mode`：`warn` 仅发出警告；`enforce` 执行清理。
+ - `pruneAfter`：过期条目的时间截止（默认 `30d`）。
- `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。
- - `rotateBytes`：当 `sessions.json` 超过该大小时进行轮换（默认 `10mb`）。
- - `resetArchiveRetention`：`*.reset.` transcript 归档的保留期。默认继承 `pruneAfter`；设置为 `false` 可禁用。
- - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下记录警告；在 `enforce` 模式下优先移除最旧的工件/会话。
- - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。
+ - `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` 表示禁用；提供商可覆盖）
---
-## 消息
+## Messages 消息
```json5
{
messages: {
- responsePrefix: "🦞", // 或 "auto"
+ responsePrefix: "🦞", // or "auto"
ackReaction: "👀",
ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
removeAckAfterReply: false,
@@ -1770,7 +1784,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
},
},
inbound: {
- debounceMs: 2000, // 0 禁用
+ debounceMs: 2000, // 0 disables
byChannel: {
whatsapp: 5000,
slack: 1500,
@@ -1780,38 +1794,38 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
}
```
-### 响应前缀
+### 回复前缀
-每渠道/每账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。
+按渠道/账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。
解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"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}` | 智能体 identity 名称 | （与 `"auto"` 相同） |
-变量大小写不敏感。`{think}` 是 `{thinkingLevel}` 的别名。
+变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。
### 确认反应
-- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设置 `""` 可禁用。
-- 每渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。
-- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 后备。
-- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。
-- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上于回复后移除 ack。
-- `messages.statusReactions.enabled`：为 Slack、Discord 和 Telegram 启用生命周期状态反应。
- 在 Slack 和 Discord 上，未设置时只要 ack 反应处于激活状态，状态反应就会保持启用。
- 在 Telegram 上，需要显式设置为 `true` 才会启用生命周期状态反应。
+- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。
+- 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。
+- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。
+- 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。
+- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除确认反应。
+- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。
+ 在 Slack 和 Discord 上，未设置时若确认反应处于启用状态，则会保持状态反应启用。
+ 在 Telegram 上，需要显式设置为 `true` 才能启用生命周期状态反应。
-### 传入去抖
+### 入站防抖
-将同一发送者快速连续发送的纯文本消息合并为单个智能体轮次。媒体/附件会立即冲刷。控制命令会绕过去抖。
+将同一发送者快速连续发送的纯文本消息合并为单个智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。
### TTS（文本转语音）
@@ -1855,17 +1869,17 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
```
- `auto` 控制自动 TTS。`/tts off|always|inbound|tagged` 会按会话覆盖。
-- `summaryModel` 会覆盖自动摘要所使用的 `agents.defaults.model.primary`。
-- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认值为 `false`（需显式启用）。
+- `summaryModel` 会覆盖 `agents.defaults.model.primary` 用于自动摘要。
+- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认是 `false`（需显式启用）。
- API key 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。
-- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为：配置，然后 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。
+- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置、然后 `OPENAI_TTS_BASE_URL`、然后 `https://api.openai.com/v1`。
- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型/语音校验。
---
## Talk
-Talk 模式（macOS/iOS/Android）的默认值。
+Talk 模式的默认值（macOS/iOS/Android）。
```json5
{
@@ -1889,13 +1903,13 @@ Talk 模式（macOS/iOS/Android）的默认值。
}
```
-- 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的一个键。
-- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.`。
-- Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
-- `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。
-- `ELEVENLABS_API_KEY` 回退仅在未配置 Talk API key 时适用。
-- `providers.*.voiceAliases` 允许 Talk 指令使用友好的名称。
-- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久再发送转录文本。未设置时保留平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。
+- 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。
+- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.`。
+- 语音 ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
+- `providers.*.apiKey` 可接受明文字符串或 SecretRef 对象。
+- 仅在未配置 Talk API key 时，才会应用 `ELEVENLABS_API_KEY` 回退。
+- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。
+- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久再发送转录。未设置时保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。
---
@@ -1905,35 +1919,35 @@ Talk 模式（macOS/iOS/Android）的默认值。
`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置基础允许列表：
-当未设置时，本地新手引导会默认将新的本地配置设为 `tools.profile: "coding"`（已有的显式配置文件会保留）。
+本地新手引导在新建本地配置且未设置时，会默认使用 `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` | 无限制（与未设置相同） |
+| `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` | 所有内置工具（不包括提供商插件） |
+| 组 | 工具 |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `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
{
@@ -1959,7 +1973,7 @@ Talk 模式（macOS/iOS/Android）的默认值。
### `tools.elevated`
-控制沙箱之外的 elevated exec 访问：
+控制沙箱外的提权 exec 访问：
```json5
{
@@ -1975,9 +1989,9 @@ Talk 模式（macOS/iOS/Android）的默认值。
}
```
-- 每智能体覆盖（`agents.list[].tools.elevated`）只能进一步限制。
-- `/elevated on|off|ask|full` 会为每个会话存储状态；内联指令仅适用于单条消息。
-- elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认 `gateway`，或当 exec 目标是 `node` 时使用 `node`）。
+- 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧。
+- `/elevated on|off|ask|full` 会按会话存储状态；内联指令只应用于单条消息。
+- 提权 `exec` 会绕过沙箱隔离，并使用已配置的 escape path（默认为 `gateway`，当 exec 目标为 `node` 时为 `node`）。
### `tools.exec`
@@ -2001,8 +2015,8 @@ Talk 模式（macOS/iOS/Android）的默认值。
### `tools.loopDetection`
-工具循环安全检查默认**关闭**。设置 `enabled: true` 即可激活检测。
-设置可以在 `tools.loopDetection` 中全局定义，并在 `agents.list[].tools.loopDetection` 中按智能体覆盖。
+工具循环安全检查**默认关闭**。设置 `enabled: true` 可激活检测。
+可在全局 `tools.loopDetection` 中定义设置，并在每智能体 `agents.list[].tools.loopDetection` 处覆盖。
```json5
{
@@ -2023,13 +2037,13 @@ Talk 模式（macOS/iOS/Android）的默认值。
}
```
-- `historySize`：用于循环分析的最大工具调用历史保留数。
-- `warningThreshold`：用于发出警告的重复无进展模式阈值。
-- `criticalThreshold`：用于阻止关键循环的更高重复阈值。
+- `historySize`：保留用于循环分析的最大工具调用历史。
+- `warningThreshold`：重复无进展模式触发警告的阈值。
+- `criticalThreshold`：阻止严重循环的更高重复阈值。
- `globalCircuitBreakerThreshold`：任何无进展运行的硬停止阈值。
- `detectors.genericRepeat`：对重复的同工具/同参数调用发出警告。
-- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。
-- `detectors.pingPong`：对交替出现的无进展双工具模式发出警告/阻止。
+- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）上的无进展模式发出警告/阻止。
+- `detectors.pingPong`：对交替出现的无进展配对模式发出警告/阻止。
- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证会失败。
### `tools.web`
@@ -2040,14 +2054,14 @@ Talk 模式（macOS/iOS/Android）的默认值。
web: {
search: {
enabled: true,
- apiKey: "brave_api_key", // 或 BRAVE_API_KEY 环境变量
+ apiKey: "brave_api_key", // or BRAVE_API_KEY env
maxResults: 5,
timeoutSeconds: 30,
cacheTtlMinutes: 15,
},
fetch: {
enabled: true,
- provider: "firecrawl", // 可选；省略则自动检测
+ provider: "firecrawl", // optional; omit for auto-detect
maxChars: 50000,
maxCharsCap: 50000,
maxResponseBytes: 2000000,
@@ -2072,7 +2086,7 @@ Talk 模式（macOS/iOS/Android）的默认值。
media: {
concurrency: 2,
asyncCompletion: {
- directSend: false, // 显式启用：将完成的异步音乐/视频直接发送到渠道
+ directSend: false, // opt-in: send finished async music/video directly to the channel
},
audio: {
enabled: true,
@@ -2098,10 +2112,10 @@ 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"`）：
@@ -2112,16 +2126,16 @@ Talk 模式（macOS/iOS/Android）的默认值。
**通用字段：**
- `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`
- （旧版请求者会话唤醒/模型交付路径）。
+ 和 `video_generate` 任务会优先尝试直接发送到渠道。默认：`false`
+ （旧版请求者会话唤醒/模型投递路径）。
@@ -2140,9 +2154,9 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m
### `tools.sessions`
-控制哪些会话可以被会话工具（`sessions_list`、`sessions_history`、`sessions_send`）访问。
+控制 session 工具（`sessions_list`、`sessions_history`、`sessions_send`）可以定位哪些会话。
-默认值：`tree`（当前会话 + 由其生成的会话，例如子智能体）。
+默认值：`tree`（当前会话 + 由其派生的会话，例如子智能体）。
```json5
{
@@ -2158,10 +2172,10 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m
注意：
- `self`：仅当前会话键。
-- `tree`：当前会话 + 由当前会话生成的会话（子智能体）。
-- `agent`：属于当前智能体 id 的任意会话（如果你在同一个智能体 id 下运行按发送者分会话，可能包括其他用户）。
-- `all`：任意会话。跨智能体定向仍需要 `tools.agentToAgent`。
-- 沙箱限制：当当前会话处于沙箱中且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。
+- `tree`：当前会话 + 由当前会话派生的会话（子智能体）。
+- `agent`：属于当前智能体 ID 的任意会话（如果你在同一智能体 ID 下运行按发送者分会话，这也可能包含其他用户）。
+- `all`：任意会话。跨智能体定位仍需要 `tools.agentToAgent`。
+- 沙箱钳制：当当前会话已沙箱隔离且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。
### `tools.sessions_spawn`
@@ -2172,11 +2186,11 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m
tools: {
sessions_spawn: {
attachments: {
- enabled: false, // 显式启用：设置为 true 以允许内联文件附件
- maxTotalBytes: 5242880, // 所有文件总计 5 MB
+ enabled: false, // opt-in: set true to allow inline file attachments
+ maxTotalBytes: 5242880, // 5 MB total across all files
maxFiles: 50,
- maxFileBytes: 1048576, // 每个文件 1 MB
- retainOnSessionKeep: false, // 当 cleanup="keep" 时保留附件
+ maxFileBytes: 1048576, // 1 MB per file
+ retainOnSessionKeep: false, // keep attachments when cleanup="keep"
},
},
},
@@ -2185,22 +2199,22 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m
注意：
-- 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝它们。
-- 文件会实体化到子工作区中的 `.openclaw/attachments//`，并附带 `.manifest.json`。
-- 附件内容会自动从 transcript 持久化中脱敏。
-- Base64 输入会使用严格的字母表/填充校验以及解码前大小保护进行验证。
-- 文件权限为：目录 `0700`，文件 `0600`。
-- 清理遵循 `cleanup` 策略：`delete` 总是移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。
+- 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。
+- 文件会实体化到子工作区的 `.openclaw/attachments//`，并附带 `.manifest.json`。
+- 附件内容会自动从转录持久化中脱敏。
+- Base64 输入会通过严格的字母表/填充检查以及解码前大小保护进行验证。
+- 目录权限为 `0700`，文件权限为 `0600`。
+- 清理遵循 `cleanup` 策略：`delete` 总会删除附件；仅在 `retainOnSessionKeep: true` 时，`keep` 才会保留它们。
### `tools.experimental`
-实验性内置工具标志。默认关闭，除非存在运行时特定的自动启用规则。
+实验性内置工具开关。默认关闭，除非某个运行时特定的自动启用规则适用。
```json5
{
tools: {
experimental: {
- planTool: true, // 启用实验性的 update_plan
+ planTool: true, // enable experimental update_plan
},
},
}
@@ -2208,9 +2222,9 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m
注意：
-- `planTool`：为非琐碎多步骤工作跟踪启用结构化 `update_plan` 工具。
+- `planTool`：为非简单多步骤工作跟踪启用结构化 `update_plan` 工具。
- 默认：对非 OpenAI 提供商为 `false`。OpenAI 和 OpenAI Codex 运行会自动启用它。
-- 启用后，系统提示词还会添加使用指导，以便模型仅在实质性工作中使用它，并且最多只保留一个 `in_progress` 步骤。
+- 启用后，系统提示也会添加使用指导，使模型仅在实质性工作中使用它，并且最多只保留一个 `in_progress` 步骤。
### `agents.defaults.subagents`
@@ -2230,10 +2244,10 @@ Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m
}
```
-- `model`：生成的子智能体默认模型。如果省略，子智能体会继承调用方模型。
-- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 的目标智能体 id 默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。
-- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时时间（秒）。`0` 表示无超时。
-- 每子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。
+- `model`：生成的子智能体默认模型。如果省略，子智能体会继承调用者模型。
+- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 目标智能体 ID 的默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。
+- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时（秒）。`0` 表示无超时。
+- 按子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。
---
@@ -2244,7 +2258,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~
```json5
{
models: {
- mode: "merge", // merge（默认）| replace
+ mode: "merge", // merge (default) | replace
providers: {
"custom-proxy": {
baseUrl: "http://localhost:4000/v1",
@@ -2268,46 +2282,46 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~
}
```
-- 使用 `authHeader: true` + `headers` 来满足自定义认证需求。
+- 针对自定义身份验证需求，使用 `authHeader: true` + `headers`。
- 使用 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。
-- 对于匹配的 provider ID，合并优先级如下：
+- 对于匹配的提供商 ID，合并优先级如下：
- 非空的智能体 `models.json` `baseUrl` 值优先。
- - 非空的智能体 `apiKey` 值仅在当前配置/auth-profile 上下文中该提供商不是由 SecretRef 管理时优先。
- - 由 SecretRef 管理的 provider `apiKey` 值会从源标记刷新（环境变量引用为 `ENV_VAR_NAME`，文件/exec 引用为 `secretref-managed`），而不是持久化已解析的 secret。
- - 由 SecretRef 管理的 provider header 值会从源标记刷新（环境变量引用为 `secretref-env:ENV_VAR_NAME`，文件/exec 引用为 `secretref-managed`）。
- - 空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。
- - 匹配模型的 `contextWindow`/`maxTokens` 使用显式配置值和隐式目录值中的较大者。
- - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；用它可在不更改模型原生元数据的情况下限制有效上下文。
+ - 非空的智能体 `apiKey` 值仅在该提供商在当前配置/auth-profile 上下文中不是由 SecretRef 管理时优先。
+ - 由 SecretRef 管理的提供商 `apiKey` 值会根据来源标记刷新（环境变量引用用 `ENV_VAR_NAME`，file/exec 引用用 `secretref-managed`），而不是持久化已解析出的 secret。
+ - 由 SecretRef 管理的提供商 header 值会根据来源标记刷新（环境变量引用用 `secretref-env:ENV_VAR_NAME`，file/exec 引用用 `secretref-managed`）。
+ - 为空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。
+ - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值和隐式目录值之间取较高者。
+ - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；可用它限制有效上下文，而不改变原生模型元数据。
- 如果你希望配置完全重写 `models.json`，请使用 `models.mode: "replace"`。
- - 标记持久化遵循源配置权威：标记会从活动源配置快照（解析前）写入，而不是从已解析的运行时 secret 值写入。
+ - 标记持久化以来源为准：标记从活动来源配置快照（解析前）写入，而不是从已解析的运行时 secret 值写入。
### 提供商字段详情
- `models.mode`：提供商目录行为（`merge` 或 `replace`）。
-- `models.providers`：按 provider id 键控的自定义提供商映射。
+- `models.providers`：以提供商 ID 为键的自定义提供商映射。
- `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。
-- `models.providers.*.apiKey`：提供商凭据（推荐使用 SecretRef/环境变量替换）。
-- `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。
-- `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，向请求中注入 `options.num_ctx`（默认：`true`）。
-- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭据。
+- `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` header 传输凭证。
- `models.providers.*.baseUrl`：上游 API base URL。
- `models.providers.*.headers`：用于代理/租户路由的额外静态 headers。
- `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖。
- `request.headers`：额外 headers（与提供商默认值合并）。值接受 SecretRef。
- - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内建认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value` 和可选 `prefix`）。
+ - `request.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`：显式 provider 模型目录条目。
+ - `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`（主机不是 `api.openai.com`），OpenClaw 会在运行时强制设为 `false`。空/省略的 `baseUrl` 则保留默认 OpenAI 行为。
+- `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用。
+- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且非空、非原生 `baseUrl`（host 不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空或省略的 `baseUrl` 会保留默认 OpenAI 行为。
- `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.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。
+- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的回退上下文窗口。
+- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的回退最大输出 token 数。
### 提供商示例
@@ -2379,11 +2393,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 覆盖的自定义提供商。
+- 若要使用通用端点，请定义一个带 base URL 覆盖的自定义提供商。
@@ -2422,10 +2436,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 来判断这一点。
+原生 Moonshot 端点会在共享
+`openai-completions` 传输上声明流式使用兼容性，OpenClaw 现在会根据端点
+能力而不是仅根据内置提供商 ID 来判断。
@@ -2443,11 +2458,11 @@ Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。
}
```
-Anthropic 兼容，内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。
+兼容 Anthropic 的内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。
-
+
```json5
{
@@ -2482,7 +2497,7 @@ Anthropic 兼容，内置提供商。快捷方式：`openclaw onboard --auth-cho
}
```
-Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。
+Base URL 应省略 `/v1`（Anthropic 客户端会追加它）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。
@@ -2525,16 +2540,17 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
设置 `MINIMAX_API_KEY`。快捷方式：
`openclaw onboard --auth-choice minimax-global-api` 或
`openclaw onboard --auth-choice minimax-cn-api`。
-模型目录现在默认只包含 M2.7。
-在 Anthropic 兼容的流式路径上，除非你显式设置 `thinking`，否则 OpenClaw 默认会关闭 MiniMax thinking。
-`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为
+模型目录现在默认仅包含 M2.7。
+在兼容 Anthropic 的流式路径上，OpenClaw 默认禁用 MiniMax thinking，
+除非你显式设置 `thinking`。`/fast on` 或
+`params.fastMode: true` 会将 `MiniMax-M2.7` 重写为
`MiniMax-M2.7-highspeed`。
-参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在性能较强的硬件上通过 LM Studio Responses API 运行大型本地模型；保留已合并的托管模型作为后备。
+参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在性能足够强的硬件上，通过 LM Studio Responses API 运行大型本地模型；并保留托管模型合并配置用于回退。
@@ -2555,7 +2571,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
},
entries: {
"image-lab": {
- apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 或明文字符串
+ apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
},
peekaboo: { enabled: true },
@@ -2566,11 +2582,12 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
```
- `allowBundled`：仅针对内置 Skills 的可选允许列表（托管/工作区 Skills 不受影响）。
-- `load.extraDirs`：额外的共享 skill 根目录（优先级最低）。
-- `install.preferBrew`：为 true 时，如果存在 `brew`，则优先使用 Homebrew 安装器，然后再回退到其他安装器类型。
-- `install.nodeManager`：`metadata.openclaw.install` 规范的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。
-- `entries..enabled: false`：即使某个 skill 已内置/已安装，也会禁用它。
-- `entries..apiKey`：为声明了主环境变量的 skill 提供便利字段（明文字符串或 SecretRef 对象）。
+- `load.extraDirs`：额外共享 Skill 根目录（最低优先级）。
+- `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 对象）。
---
@@ -2598,41 +2615,41 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
}
```
-- 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 和 `plugins.load.paths` 加载。
-- 设备发现接受原生 OpenClaw 插件以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。
-- **配置变更需要重启 Gateway 网关。**
+- 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。
+- 设备发现支持原生 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` 时，核心会阻止 `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..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hook 以及受支持 bundle 提供的 hook 目录。
+- `plugins.entries..subagent.allowModelOverride`：显式信任该插件，以便为后台子智能体运行请求按次 `provider` 和 `model` 覆盖。
+- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖可用的规范 `provider/model` 目标的可选允许列表。仅当你明确要允许任意模型时，才使用 `"*"`。
+- `plugins.entries..config`：插件定义的配置对象（如可用，将由原生 OpenClaw 插件 schema 验证）。
- `plugins.entries.firecrawl.config.webFetch`：Firecrawl Web 抓取提供商设置。
- `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。
- `baseUrl`：Firecrawl API base URL（默认：`https://api.firecrawl.dev`）。
- `onlyMainContent`：仅提取页面主体内容（默认：`true`）。
- - `maxAgeMs`：最大缓存年龄（毫秒）（默认：`172800000` / 2 天）。
- - `timeoutSeconds`：抓取请求超时时间（秒）（默认：`60`）。
-- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok Web 搜索）设置。
+ - `maxAgeMs`：缓存最大存活时间（毫秒）（默认：`172800000` / 2 天）。
+ - `timeoutSeconds`：抓取请求超时（秒）（默认：`60`）。
+- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。
- `enabled`：启用 X Search 提供商。
- `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。
-- `plugins.entries.memory-core.config.dreaming`：记忆 dreaming（实验性）设置。阶段和阈值请参见 [Dreaming](/zh-CN/concepts/dreaming)。
- - `enabled`：dreaming 总开关（默认 `false`）。
+- `plugins.entries.memory-core.config.dreaming`：记忆 dreaming（实验性）设置。关于阶段和阈值，请参见 [Dreaming](/zh-CN/concepts/dreaming)。
+ - `enabled`：dreaming 主开关（默认 `false`）。
- `frequency`：每次完整 dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。
- 阶段策略和阈值属于实现细节（不是面向用户的配置键）。
-- 已启用的 Claude bundle 插件还可以通过 `settings.json` 提供内嵌 Pi 默认值；OpenClaw 会将其作为已净化的智能体设置来应用，而不是作为原始 OpenClaw 配置补丁。
-- `plugins.slots.memory`：选择活动 memory 插件 id，或使用 `"none"` 禁用 memory 插件。
-- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；默认是 `"legacy"`，除非你安装并选择其他引擎。
+- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供内嵌 Pi 默认值；OpenClaw 会将它们作为已净化的智能体设置应用，而不是原始 OpenClaw 配置补丁。
+- `plugins.slots.memory`：选择活动记忆插件 ID，或设为 `"none"` 以禁用记忆插件。
+- `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)。
---
-## 浏览器
+## Browser 浏览器
```json5
{
@@ -2641,8 +2658,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
evaluateEnabled: true,
defaultProfile: "user",
ssrfPolicy: {
- dangerouslyAllowPrivateNetwork: true, // 默认受信网络模式
- // allowPrivateNetwork: true, // 旧版别名
+ dangerouslyAllowPrivateNetwork: true, // default trusted-network mode
+ // allowPrivateNetwork: true, // legacy alias
// hostnameAllowlist: ["*.example.com", "example.com"],
// allowedHostnames: ["localhost"],
},
@@ -2669,27 +2686,21 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
```
- `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。
-- 当未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认值为 `true`（受信网络模型）。
-- 如需严格的仅公网浏览器导航，请设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false`。
+- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时默认为 `true`（受信任网络模型）。
+- 对于严格的仅公共浏览器导航，请设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false`。
- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到同样的私有网络阻止。
- `ssrfPolicy.allowPrivateNetwork` 仍支持作为旧版别名。
-- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 配置显式例外。
+- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 作为显式例外。
- 远程配置文件为仅附加模式（禁用 start/stop/reset）。
- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。
- 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)；
- 当提供商直接给出 DevTools WebSocket URL 时，请使用 WS(S)。
-- `existing-session` 配置文件仅限主机使用，并使用 Chrome MCP 而不是 CDP。
-- `existing-session` 配置文件可以设置 `userDataDir`，以针对特定的
- Chromium 系浏览器配置文件，例如 Brave 或 Edge。
-- `existing-session` 配置文件保留当前 Chrome MCP 路由限制：
- 使用 snapshot/ref 驱动的操作而不是 CSS 选择器定位、单文件上传
- hooks、无对话框超时覆盖、无 `wait --load networkidle`，并且不支持
- `responsebody`、PDF 导出、下载拦截或批量操作。
-- 本地受管 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；只有在远程 CDP 情况下才需要显式设置 `cdpUrl`。
-- 自动检测顺序：默认浏览器（如果是 Chromium 系）→ Chrome → Brave → Edge → Chromium → Chrome Canary。
+ 当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)；当提供商直接给出 DevTools WebSocket URL 时使用 WS(S)。
+- `existing-session` 配置文件仅限宿主使用，并使用 Chrome MCP 而不是 CDP。
+- `existing-session` 配置文件可设置 `userDataDir` 来定位特定的 Chromium 系浏览器配置文件，例如 Brave 或 Edge。
+- `existing-session` 配置文件保留当前 Chrome MCP 路由限制：基于快照/ref 的操作而非 CSS 选择器定位、单文件上传 hook、无对话框超时覆盖、无 `wait --load networkidle`，且不支持 `responsebody`、PDF 导出、下载拦截或批量操作。
+- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下显式设置 `cdpUrl`。
+- 自动检测顺序：默认浏览器（若为 Chromium 系）→ Chrome → Brave → Edge → Chromium → Chrome Canary。
- 控制服务：仅 loopback（端口由 `gateway.port` 派生，默认 `18791`）。
-- `extraArgs` 会向本地 Chromium 启动追加额外启动参数（例如
- `--disable-gpu`、窗口大小或调试标志）。
+- `extraArgs` 会向本地 Chromium 启动附加额外 launch 标志（例如 `--disable-gpu`、窗口尺寸或调试标志）。
---
@@ -2701,14 +2712,14 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
seamColor: "#FF4500",
assistant: {
name: "OpenClaw",
- avatar: "CB", // emoji、短文本、图片 URL 或 data URI
+ avatar: "CB", // emoji, short text, image URL, or data URI
},
},
}
```
-- `seamColor`：原生应用 UI 外观的强调色（Talk Mode 气泡色调等）。
-- `assistant`：Control UI 身份覆盖。会回退到活动智能体身份。
+- `seamColor`：原生应用 UI 边框的强调色（Talk Mode 气泡色调等）。
+- `assistant`：Control UI identity 覆盖。会回退到活动智能体 identity。
---
@@ -2723,8 +2734,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
auth: {
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
+ // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD
+ // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth
allowTailscale: true,
rateLimit: {
maxAttempts: 10,
@@ -2741,8 +2752,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
enabled: true,
basePath: "/openclaw",
// root: "dist/control-ui",
- // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必需
- // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host header origin 回退模式
+ // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI
+ // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode
// allowInsecureAuth: false,
// dangerouslyDisableDeviceAuth: false,
},
@@ -2753,12 +2764,12 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
// password: "your-password",
},
trustedProxies: ["10.0.0.1"],
- // 可选。默认 false。
+ // Optional. Default false.
allowRealIpFallback: false,
tools: {
- // 附加的 /tools/invoke HTTP deny
+ // Additional /tools/invoke HTTP denies
deny: ["browser"],
- // 从默认 HTTP deny 列表中移除工具
+ // Remove tools from the default HTTP deny list
allow: ["gateway"],
},
push: {
@@ -2775,39 +2786,38 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
-- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关拒绝启动。
-- `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。
+- `mode`：`local`（运行 gateway）或 `remote`（连接远程 gateway）。除非为 `local`，否则 Gateway 网关会拒绝启动。
+- `port`：WS + HTTP 复用的单一端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。
- `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。
-- **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），而不是主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。
-- **Docker 注意事项**：默认的 `loopback` bind 会在容器内部监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关不可达。请使用 `--network host`，或者设置 `bind: "lan"`（或 `bind: "custom"` 并设置 `customBindHost: "0.0.0.0"`）来监听所有接口。
-- **认证**：默认要求认证。非 loopback bind 必须启用 Gateway 网关认证。实践中这意味着共享 token/password，或使用设置了 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导默认会生成 token。
-- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式设置 `gateway.auth.mode` 为 `token` 或 `password`。如果两者都已配置而 mode 未设置，启动以及服务安装/修复流程都会失败。
-- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信的本地 loopback 设置；新手引导提示中不会提供该选项。
-- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 代理来源；同机 loopback 反向代理不满足 trusted-proxy 认证要求。
-- `gateway.auth.allowTailscale`：当为 `true` 时，Tailscale Serve 身份头可以满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用这种 Tailscale header 认证；它们仍遵循 Gateway 网关正常的 HTTP 认证模式。此无 token 流程假设 Gateway 网关主机是受信的。当 `tailscale.mode = "serve"` 时默认为 `true`。
-- `gateway.auth.rateLimit`：可选的认证失败限制器。按客户端 IP 和认证作用域应用（共享密钥和设备 token 分开跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。
- - 在异步 Tailscale Serve Control UI 路径上，对于相同 `{scope, clientIp}` 的失败尝试，会在写入失败记录前进行串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限制器，而不是两个都作为普通不匹配而竞态通过。
- - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；如果你确实希望 localhost 流量也被限速（用于测试环境或严格代理部署），请设置为 `false`。
-- 浏览器来源的 WS 认证尝试始终会在禁用 loopback 豁免的情况下受到限流（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。
-- 在 loopback 上，这些浏览器来源锁定会按规范化后的 `Origin`
- 值进行隔离，因此来自某个 localhost origin 的重复失败不会自动
- 锁定另一个不同的 origin。
-- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公网，需要认证）。
-- `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当浏览器客户端来自非 loopback origin 时必需。
-- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，用于那些刻意依赖 Host-header origin 策略的部署，可启用 Host-header origin 回退。
+- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用 host 别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。
+- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会进入 `eth0`，因此 Gateway 网关无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 配合 `customBindHost: "0.0.0.0"`）以监听所有接口。
+- **身份验证**：默认必须启用。非 loopback 绑定要求 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 和身份验证范围生效（共享 secret 和设备 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 绑定）或 `funnel`（公开，需要身份验证）。
+- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当预期浏览器客户端来自非 loopback 来源时必须设置。
+- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，允许依赖 Host 头 origin 策略的部署使用 Host 头 origin 回退。
- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。
-- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧的紧急开关，允许对受信私有网络 IP 使用明文 `ws://`；默认仍只允许对 loopback 使用明文。
-- `gateway.remote.token` / `.password` 是远程客户端凭据字段。它们本身不会配置 Gateway 网关认证。
-- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在向 Gateway 网关发布基于 relay 的注册后所使用的外部 APNs relay 的 base HTTPS URL。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。
-- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间（毫秒）。默认值为 `10000`。
-- 基于 relay 的注册会委托给特定 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并向 Gateway 网关转发一个基于注册范围的发送授权。其他 Gateway 网关不能复用该已存储注册。
-- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述 relay 配置的临时环境变量覆盖。
-- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发的紧急开关，允许 loopback HTTP relay URL。生产 relay URL 应保持为 HTTPS。
-- `gateway.channelHealthCheckMinutes`：渠道健康监测间隔（分钟）。设置为 `0` 可全局禁用健康监测重启。默认值：`5`。
-- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。应保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。
-- `gateway.channelMaxRestartsPerHour`：滚动一小时内，每个渠道/账号允许的最大健康监测重启次数。默认值：`10`。
-- `channels..healthMonitor.enabled`：在保留全局监测启用状态的同时，按渠道选择退出健康监测重启。
-- `channels..accounts..healthMonitor.enabled`：多账号渠道的每账号覆盖。设置后，它优先于渠道级覆盖。
-- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可以使用 `gateway.remote.*` 作为回退。
-- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但未解析，则解析会失败关闭（不会用远程回退掩盖）。
-- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP。仅列出你控制的代理。loopback 条目对同机代理/本地检测设置（例如 Tailscale Serve 或本地反
\ No newline at end of file
+- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧的破玻璃覆盖，允许对可信私有网络 IP 使用明文 `ws://`；默认仍仅允许对 loopback 使用明文。
+- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关身份验证。
+- `gateway.push.apns.relay.baseUrl`：外部 APNs 中继的基础 HTTPS URL，官方/TestFlight iOS 构建在将基于中继的注册发布到 Gateway 网关后会使用它。此 URL 必须与编译进 iOS 构建中的中继 URL 匹配。
+- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到中继的发送超时（毫秒）。默认值为 `10000`。
+- 基于中继的注册会委托给特定的 Gateway 网关 identity。已配对的 iOS 应用会获取 `gateway.identity.get`，将该 identity 包含在中继注册中，并将按注册范围的发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用该已存储注册。
+- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述中继配置的临时环境变量覆盖。
+- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅供开发使用的逃生舱，允许 loopback HTTP 中继 URL。生产中继 URL 应保持使用 HTTPS。
+- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设为 `0` 可全局禁用健康监控重启。默认：`5`。
+- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认：`30`。
+- `gateway.channelMaxRestartsPerHour`：滚动一小时内，每个渠道/账号允许的最大健康监控重启次数。默认：`10`。
+- `channels..healthMonitor.enabled`：在保持全局监控启用的同时，为单个渠道选择退出健康监控重启。
+- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。设置后，其优先级高于渠道级覆盖。
+- 只有在 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可将 `gateway.remote.*` 作为回退使用。
+- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但未解析，则解析会以默认拒绝的方式失败（不会使用远程回退来掩盖）。
+- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP
\ No newline at end of file