diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md
index e4cbcbe69..b6233fd2b 100644
--- a/docs/zh-CN/gateway/configuration-reference.md
+++ b/docs/zh-CN/gateway/configuration-reference.md
@@ -1,70 +1,70 @@
---
read_when:
- - 你需要精确到字段级别的配置语义或默认值。
- - 你正在验证渠道、模型、Gateway 网关或工具配置块。
-summary: 用于核心 OpenClaw 键、默认值以及专用子系统参考链接的 Gateway 网关配置参考。
+ - 你需要精确到字段级别的配置语义或默认值
+ - 你正在验证渠道、模型、Gateway 网关或工具配置块
+summary: Gateway 网关配置参考，涵盖 OpenClaw 核心键名、默认值，以及指向专门子系统参考文档的链接
title: 配置参考
x-i18n:
- generated_at: "2026-04-21T02:12:40Z"
+ generated_at: "2026-04-21T04:43:50Z"
model: gpt-5.4
provider: openai
- source_hash: e50315811f2ba31d325983397ffbd0f71c6e5e95a58a4412b62ebb969b50a3db
+ source_hash: 1ce4b2cc50eead5411134eead2e7943ec5dab3b1a9d6772adcd422a721df5071
source_path: gateway/configuration-reference.md
workflow: 15
---
# 配置参考
-`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参阅 [配置](/zh-CN/gateway/configuration)。
+`~/.openclaw/openclaw.json` 的核心配置参考。若需按任务划分的概览，请参阅 [Configuration](/zh-CN/gateway/configuration)。
-本页介绍 OpenClaw 的主要配置面，并在某个子系统拥有更深入的独立参考时提供跳转链接。它**不会**尝试在单个页面中内联所有渠道/插件自有的命令目录，也不会囊括所有深层 memory/QMD 调节项。
+本页涵盖 OpenClaw 的主要配置面，并在某个子系统拥有更深入的独立参考时提供外链。它**不会**尝试在单个页面中内联每个由渠道/插件拥有的命令目录，也不会内联每个深层 memory/QMD 调节项。
-代码真相：
+代码事实来源：
- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据
-- `config.schema.lookup` 返回一个按路径限定的 schema 节点，供深入查询工具使用
-- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面验证配置文档基线哈希
+- `config.schema.lookup` 返回一个按路径范围划分的 schema 节点，供下钻工具使用
+- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 面验证配置文档基线哈希
-专用深度参考：
+专门的深度参考：
-- [Memory 配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置
-- 当前内置 + 内置插件命令目录请参阅 [Slash Commands](/zh-CN/tools/slash-commands)
-- 渠道专属命令面请参阅对应的渠道/插件页面
+- [Memory configuration reference](/zh-CN/reference/memory-config)，用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 Dreaming 配置
+- [Slash Commands](/zh-CN/tools/slash-commands)，用于当前内置 + 内置插件的命令目录
+- 对应渠道/插件页面，用于渠道特定的命令面
-配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全默认值。
+配置格式是 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——OpenClaw 在省略时会使用安全默认值。
---
## 渠道
-每个渠道只要其配置段存在就会自动启动（除非设置了 `enabled: false`）。
+只要某个渠道的配置节存在，它就会自动启动（除非设置了 `enabled: false`）。
### 私信和群组访问
所有渠道都支持私信策略和群组策略：
-| 私信策略 | 行为 |
-| ------------------- | --------------------------------------------------------------- |
-| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 |
-| `allowlist` | 只允许 `allowFrom` 中的发送者（或已配对允许存储中的发送者） |
-| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） |
-| `disabled` | 忽略所有传入私信 |
+| 私信策略 | 行为 |
+| ------------------- | ---- |
+| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 |
+| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对允许存储中的发送者） |
+| `open` | 允许所有传入私信（要求 `allowFrom: ["*"]`） |
+| `disabled` | 忽略所有传入私信 |
-| 群组策略 | 行为 |
-| --------------------- | ------------------------------------------------------ |
-| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 |
-| `open` | 绕过群组允许列表（但仍适用提及门控） |
-| `disabled` | 阻止所有群组/房间消息 |
+| 群组策略 | 行为 |
+| --------------------- | ---- |
+| `allowlist`（默认） | 仅允许与已配置允许列表匹配的群组 |
+| `open` | 绕过群组允许列表（仍会应用提及门控） |
+| `disabled` | 屏蔽所有群组/房间消息 |
-`channels.defaults.groupPolicy` 用于在提供商的 `groupPolicy` 未设置时指定默认值。
-配对码会在 1 小时后过期。待处理的私信配对请求**每个渠道**最多为 **3 个**。
-如果某个提供商配置块完全缺失（即不存在 `channels.`），运行时群组策略会回退为 `allowlist`（失败关闭），并在启动时发出警告。
+`channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时设为默认值。
+配对码会在 1 小时后过期。待处理的私信配对请求上限为**每个渠道 3 个**。
+如果某个提供商配置块完全缺失（`channels.` 不存在），运行时群组策略会回退为 `allowlist`（默认拒绝），并在启动时发出警告。
### 渠道模型覆盖
-使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当某个会话尚未有模型覆盖时（例如通过 `/model` 设置），就会应用该渠道映射。
+使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值可接受 `provider/model` 或已配置的模型别名。当某个会话尚未拥有模型覆盖时（例如通过 `/model` 设置），才会应用该渠道映射。
```json5
{
@@ -87,7 +87,7 @@ x-i18n:
### 渠道默认值和心跳
-使用 `channels.defaults` 为各提供商共享群组策略和心跳行为：
+对各提供商共享的群组策略和心跳行为，请使用 `channels.defaults`：
```json5
{
@@ -106,14 +106,14 @@ x-i18n:
```
- `channels.defaults.groupPolicy`：当提供商级别的 `groupPolicy` 未设置时使用的回退群组策略。
-- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。可选值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。按渠道覆盖：`channels..contextVisibility`。
+- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。按渠道覆盖：`channels..contextVisibility`。
- `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。
- `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。
- `channels.defaults.heartbeat.useIndicator`：以紧凑的指示器样式渲染心跳输出。
### WhatsApp
-WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已关联会话时会自动启动。
+WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在已关联的会话时会自动启动。
```json5
{
@@ -124,7 +124,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已
textChunkLimit: 4000,
chunkMode: "length", // length | newline
mediaMaxMb: 50,
- sendReadReceipts: true, // blue ticks (false in self-chat mode)
+ sendReadReceipts: true, // 蓝色对勾（self-chat 模式下为 false）
groups: {
"*": { requireMention: true },
},
@@ -164,8 +164,8 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已
}
```
-- 出站命令默认使用 `default` 账号；如果不存在，则使用第一个已配置的账号 ID（按排序顺序）。
-- 可选的 `channels.whatsapp.defaultAccount` 可在其匹配已配置账号 ID 时，覆盖该回退默认账号选择。
+- 出站命令默认使用账号 `default`；如果不存在，则使用首个已配置的账号 ID（排序后）。
+- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖该默认账号选择回退逻辑。
- 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。
- 按账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。
@@ -202,7 +202,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已
historyLimit: 50,
replyToMode: "first", // off | first | all | batched
linkPreview: true,
- streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits)
+ streaming: "partial", // off | partial | block | progress（默认：off；显式启用以避免预览编辑速率限制）
actions: { reactions: true, sendMessage: true },
reactionNotifications: "own", // off | own | all
mediaMaxMb: 100,
@@ -225,13 +225,13 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已
}
```
-- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅允许普通文件；拒绝符号链接），默认账号也可回退到 `TELEGRAM_BOT_TOKEN`。
-- 可选的 `channels.telegram.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。
-- 在多账号配置（2 个或更多账号 ID）中，应设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；缺失或无效时，`openclaw doctor` 会发出警告。
-- `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`（在私聊和群聊中都可用）。
-- 重试策略：参见 [重试策略](/zh-CN/concepts/retry)。
+- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅支持常规文件；拒绝符号链接），默认账号还可回退到 `TELEGRAM_BOT_TOKEN`。
+- 可选的 `channels.telegram.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。
+- 在多账号设置中（2 个及以上账号 ID），请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`），以避免回退路由；当该值缺失或无效时，`openclaw doctor` 会发出警告。
+- `configWrites: false` 会阻止由 Telegram 发起的配置写入（supergroup ID 迁移、`/config set|unset`）。
+- 顶层 `bindings[]` 中 `type: "acp"` 的条目会为论坛主题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范形式 `chatId:topic:topicId`）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。
+- Telegram 流式预览使用 `sendMessage` + `editMessageText`（在私聊和群聊中都可工作）。
+- 重试策略：参见 [Retry policy](/zh-CN/concepts/retry)。
### Discord
@@ -286,7 +286,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已
historyLimit: 20,
textChunkLimit: 2000,
chunkMode: "length", // length | newline
- streaming: "off", // off | partial | block | progress (progress maps to partial on Discord)
+ streaming: "off", // off | partial | block | progress（在 Discord 上，progress 会映射为 partial）
maxLinesPerMessage: 17,
ui: {
components: {
@@ -297,7 +297,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已
enabled: true,
idleHours: 24,
maxAgeHours: 0,
- spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true })
+ spawnSubagentSessions: false, // 对 `sessions_spawn({ thread: true })` 的显式启用
},
voice: {
enabled: true,
@@ -333,36 +333,36 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已
}
```
-- Token：`channels.discord.token`，默认账号可回退到 `DISCORD_BOT_TOKEN`。
-- 直接出站调用如果提供了显式的 Discord `token`，该调用将使用该 token；但账号重试/策略设置仍来自活动运行时快照中选定的账号。
-- 可选的 `channels.discord.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。
-- 传递目标请使用 `user:`（私信）或 `channel:`（服务器频道）；裸数字 ID 会被拒绝。
-- 服务器 slug 为小写，并将空格替换为 `-`；频道键使用 slug 化后的名称（不含 `#`）。优先使用服务器 ID。
-- 机器人自己发送的消息默认会被忽略。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 则只接受提及机器人的机器人消息（机器人自己的消息仍会被过滤）。
-- `channels.discord.guilds..ignoreOtherMentions`（以及频道级覆盖）会丢弃提及了其他用户或角色但没有提及机器人的消息（不包括 @everyone/@here）。
-- `maxLinesPerMessage`（默认 17）会拆分过高的消息，即使其长度未超过 2000 个字符。
+- Token：`channels.discord.token`，默认账号还可回退到 `DISCORD_BOT_TOKEN`。
+- 直接出站调用如果显式提供了 Discord `token`，该次调用会使用该 token；账号重试/策略设置仍来自活动运行时快照中选定的账号。
+- 可选的 `channels.discord.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。
+- 传递目标请使用 `user:`（私信）或 `channel:`（guild 渠道）；不接受裸数字 ID。
+- Guild slug 使用小写，并将空格替换为 `-`；渠道键使用 slug 化后的名称（不含 `#`）。优先使用 guild ID。
+- 默认会忽略由 bot 自己发送的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 则仅接受提及该 bot 的 bot 消息（仍会过滤自己的消息）。
+- `channels.discord.guilds..ignoreOtherMentions`（以及渠道级覆盖）会丢弃提及了其他用户或角色但未提及 bot 的消息（不包括 @everyone/@here）。
+- `maxLinesPerMessage`（默认 17）会拆分过高的消息，即使其未超过 2000 个字符。
- `channels.discord.threadBindings` 控制 Discord 线程绑定路由：
- - `enabled`：用于线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及绑定传递/路由）
- - `idleHours`：以小时为单位的 Discord 空闲自动取消聚焦覆盖（`0` 表示禁用）
- - `maxAgeHours`：以小时为单位的 Discord 硬性最大时长覆盖（`0` 表示禁用）
- - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程启用的显式开关
-- 顶层 `bindings[]` 中 `type: "acp"` 的条目用于为频道和线程配置持久化 ACP 绑定（在 `match.peer.id` 中使用频道/线程 ID）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。
-- `channels.discord.ui.components.accentColor` 用于设置 Discord components v2 容器的强调色。
+ - `enabled`：线程绑定会话功能的 Discord 覆盖项（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由）
+ - `idleHours`：以小时计的无活动自动取消聚焦 Discord 覆盖项（`0` 表示禁用）
+ - `maxAgeHours`：以小时计的硬性最大时长 Discord 覆盖项（`0` 表示禁用）
+ - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程的显式启用开关
+- 顶层 `bindings[]` 中 `type: "acp"` 的条目会为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用 channel/thread id）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。
+- `channels.discord.ui.components.accentColor` 设置 Discord components v2 容器的强调色。
- `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入 + TTS 覆盖。
-- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。
-- 此外，OpenClaw 在重复发生解密失败后，还会尝试通过离开并重新加入语音会话来恢复语音接收。
+- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会直通传递给 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。
+- OpenClaw 还会在重复解密失败后通过离开/重新加入语音会话来尝试恢复语音接收。
- `channels.discord.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。
-- `channels.discord.autoPresence` 将运行时可用性映射为机器人在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。
-- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（紧急兼容模式）。
-- `channels.discord.execApprovals`：Discord 原生 exec 审批传递和审批人授权。
- - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。
+- `channels.discord.autoPresence` 将运行时可用性映射为 bot 在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。
+- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（破窗应急兼容模式）。
+- `channels.discord.execApprovals`：原生 Discord exec 审批投递和审批人授权。
+ - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，将启用 exec 审批。
- `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。
- - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批请求。
- - `sessionFilter`：可选的会话键模式（子串或正则表达式）。
- - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到发起频道，`"both"` 同时发送到两者。当目标包含 `"channel"` 时，按钮仅对已解析出的审批人可用。
- - `cleanupAfterResolve`：设为 `true` 时，在批准、拒绝或超时后删除审批私信。
+ - `agentFilter`：可选的智能体 ID 允许列表。省略则会为所有智能体转发审批。
+ - `sessionFilter`：可选的会话键模式（子串或正则）。
+ - `target`：审批提示发送位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到发起渠道，`"both"` 同时发送到两者。当 target 包含 `"channel"` 时，按钮仅对已解析出的审批人可用。
+ - `cleanupAfterResolve`：为 `true` 时，在审批通过、拒绝或超时后删除审批私信。
-**Reaction 通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users` 的所有消息）。
+**反应通知模式：** `off`（无）、`own`（bot 自己的消息，默认）、`all`（所有消息）、`allowlist`（`guilds..users` 中用户在所有消息上的反应）。
### Google Chat
@@ -393,11 +393,11 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已
}
```
-- 服务账号 JSON：支持内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。
+- 服务账号 JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。
- 也支持服务账号 SecretRef（`serviceAccountRef`）。
- 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。
- 传递目标请使用 `spaces/` 或 `users/`。
-- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（紧急兼容模式）。
+- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（破窗应急兼容模式）。
### Slack
@@ -449,7 +449,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已
chunkMode: "length",
streaming: {
mode: "partial", // off | partial | block | progress
- nativeTransport: true, // use Slack native streaming API when mode=partial
+ nativeTransport: true, // 当 mode=partial 时使用 Slack 原生流式 API
},
mediaMaxMb: 20,
execApprovals: {
@@ -465,37 +465,33 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已
```
- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号的环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。
-- **HTTP mode** 需要 `botToken` 加 `signingSecret`（可在根级或按账号配置）。
-- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文
- 字符串或 SecretRef 对象。
-- Slack 账号快照会暴露按凭证区分的来源/状态字段，例如
- `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 下的
- `signingSecretStatus`。`configured_unavailable` 表示该账号是通过 SecretRef
- 配置的，但当前命令/运行时路径无法解析出该密钥值。
+- **HTTP mode** 需要 `botToken` 加 `signingSecret`（可位于根级或按账号配置）。
+- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。
+- Slack 账号快照会暴露按凭证划分的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 下的 `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef 配置，但当前命令/运行时路径无法解析出密钥值。
- `configWrites: false` 会阻止由 Slack 发起的配置写入。
-- 可选的 `channels.slack.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。
+- 可选的 `channels.slack.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。
- `channels.slack.streaming.mode` 是规范的 Slack 流式模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版 `streamMode`、布尔型 `streaming` 和 `nativeStreaming` 值会自动迁移。
- 传递目标请使用 `user:`（私信）或 `channel:`。
-**Reaction 通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。
+**反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。
-**线程会话隔离：** `thread.historyScope` 为每线程（默认）或整个频道共享。`thread.inheritParent` 会将父频道转录复制到新线程。
+**线程会话隔离：** `thread.historyScope` 可为按线程隔离（默认）或在整个渠道共享。`thread.inheritParent` 会将父渠道转录复制到新线程。
-- Slack 原生流式传输以及 Slack 助手样式的“正在输入...”线程状态需要在线程回复目标中使用。顶层私信默认保持非线程模式，因此会使用 `typingReaction` 或普通传递，而不是线程样式预览。
-- `typingReaction` 会在回复运行期间为传入的 Slack 消息添加临时 reaction，并在完成后移除。请使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。
-- `channels.slack.execApprovals`：Slack 原生 exec 审批传递和审批人授权。schema 与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。
+- Slack 原生流式传输加上 Slack 助手风格的“正在输入...”线程状态需要回复线程目标。顶层私信默认保持非线程模式，因此会使用 `typingReaction` 或普通投递，而不是线程风格预览。
+- `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 | 已启用 | 添加 reaction + 列出 reactions |
+| reactions | 已启用 | 反应 + 列出反应 |
| messages | 已启用 | 读取/发送/编辑/删除 |
-| pins | 已启用 | 置顶/取消置顶/列出 |
+| pins | 已启用 | 固定/取消固定/列出 |
| memberInfo | 已启用 | 成员信息 |
| emojiList | 已启用 | 自定义 emoji 列表 |
### Mattermost
-Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermost`。
+Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost`。
```json5
{
@@ -512,10 +508,10 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos
"team-channel-id": { requireMention: false },
},
commands: {
- native: true, // opt-in
+ native: true, // 显式启用
nativeSkills: true,
callbackPath: "/api/channels/mattermost/command",
- // Optional explicit URL for reverse-proxy/public deployments
+ // 面向反向代理/公网部署的可选显式 URL
callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
},
textChunkLimit: 4000,
@@ -525,22 +521,18 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos
}
```
-聊天模式：`oncall`（在 @ 提及时回复，默认）、`onmessage`（每条消息都回复）、`onchar`（以触发前缀开头的消息）。
+聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（以触发前缀开头的消息）。
启用 Mattermost 原生命令时：
- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。
- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器能够访问。
-- 原生斜杠命令回调通过 Mattermost 在斜杠命令注册期间返回的每命令 token 进行身份验证。如果注册失败，或没有任何命令被激活，OpenClaw 会以
- `Unauthorized: invalid command token.`
- 拒绝回调。
-- 对于私有/tailnet/内部回调主机，Mattermost 可能要求
- `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。
- 请使用主机/域名值，而不是完整 URL。
+- 原生 slash 回调使用 Mattermost 在 slash 命令注册期间返回的每命令 token 进行认证。如果注册失败或没有任何命令被激活，OpenClaw 会拒绝回调，并返回 `Unauthorized: invalid command token.`。
+- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。请使用主机/域名值，而不是完整 URL。
- `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。
-- `channels.mattermost.requireMention`：在频道中回复前要求 `@mention`。
-- `channels.mattermost.groups..requireMention`：按频道的提及门控覆盖（`"*"` 表示默认值）。
-- 可选的 `channels.mattermost.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。
+- `channels.mattermost.requireMention`：要求在渠道中先有 `@mention` 才进行回复。
+- `channels.mattermost.groups..requireMention`：按渠道覆盖提及门控（`"*"` 用于默认值）。
+- 可选的 `channels.mattermost.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。
### Signal
@@ -549,7 +541,7 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos
channels: {
signal: {
enabled: true,
- account: "+15555550123", // optional account binding
+ account: "+15555550123", // 可选的账号绑定
dmPolicy: "pairing",
allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
configWrites: true,
@@ -561,11 +553,11 @@ Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermos
}
```
-**Reaction 通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。
+**反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。
- `channels.signal.account`：将渠道启动固定到特定的 Signal 账号身份。
- `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。
-- 可选的 `channels.signal.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。
+- 可选的 `channels.signal.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。
### BlueBubbles
@@ -577,17 +569,17 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `chann
bluebubbles: {
enabled: true,
dmPolicy: "pairing",
- // serverUrl, password, webhookPath, group controls, and advanced actions:
- // see /channels/bluebubbles
+ // serverUrl、password、webhookPath、群组控制和高级操作：
+ // 参见 /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
@@ -615,15 +607,15 @@ OpenClaw 会启动 `imsg rpc`（基于 stdio 的 JSON-RPC）。不需要守护
}
```
-- 可选的 `channels.imessage.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。
+- 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。
-- 需要对 Messages 数据库授予“完全磁盘访问”权限。
-- 优先使用 `chat_id:` 目标。可用 `imsg chats --limit 20` 列出聊天。
-- `cliPath` 可以指向一个 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。
-- `attachmentRoots` 和 `remoteAttachmentRoots` 用于限制传入附件路径（默认值：`/Users/*/Library/Messages/Attachments`）。
-- SCP 使用严格的主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。
+- 需要对 Messages DB 授予完全磁盘访问权限。
+- 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。
+- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。
+- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制传入附件路径（默认：`/Users/*/Library/Messages/Attachments`）。
+- SCP 使用严格的 host-key 检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。
- `channels.imessage.configWrites`：允许或拒绝由 iMessage 发起的配置写入。
-- 顶层 `bindings[]` 中 `type: "acp"` 的条目可将 iMessage 对话绑定到持久化 ACP 会话。在 `match.peer.id` 中使用规范化后的 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。
+- 顶层 `bindings[]` 中 `type: "acp"` 的条目可将 iMessage 会话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。
@@ -667,20 +659,20 @@ Matrix 由扩展支持，配置位于 `channels.matrix` 下。
```
- Token 认证使用 `accessToken`；密码认证使用 `userId` + `password`。
-- `channels.matrix.proxy` 会通过显式的 HTTP(S) 代理转发 Matrix HTTP 流量。命名账号可使用 `channels.matrix.accounts..proxy` 进行覆盖。
-- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许使用私有/内部 homeserver。`proxy` 和这一网络显式启用项是相互独立的控制项。
-- `channels.matrix.defaultAccount` 用于在多账号配置中选择首选账号。
-- `channels.matrix.autoJoin` 默认为 `off`，因此受邀房间和新建的私信式邀请都会被忽略，直到你设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。
-- `channels.matrix.execApprovals`：Matrix 原生 exec 审批传递和审批人授权。
- - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。
+- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可通过 `channels.matrix.accounts..proxy` 进行覆盖。
+- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 和这个网络显式启用项是彼此独立的控制项。
+- `channels.matrix.defaultAccount` 用于在多账号设置中选择首选账号。
+- `channels.matrix.autoJoin` 默认为 `off`，因此被邀请的房间和新的私信式邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。
+- `channels.matrix.execApprovals`：原生 Matrix exec 审批投递和审批人授权。
+ - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，将启用 exec 审批。
- `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。
- - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批请求。
- - `sessionFilter`：可选的会话键模式（子串或正则表达式）。
- - `target`：发送审批提示的位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。
+ - `agentFilter`：可选的智能体 ID 允许列表。省略则会为所有智能体转发审批。
+ - `sessionFilter`：可选的会话键模式（子串或正则）。
+ - `target`：审批提示发送位置。`"dm"`（默认）、`"channel"`（发起房间）或 `"both"`。
- 按账号覆盖：`channels.matrix.accounts..execApprovals`。
-- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组到会话中：`per-user`（默认）按路由对端共享，而 `per-room` 会隔离每个私信房间。
+- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归并到会话：`per-user`（默认）按路由对端共享，而 `per-room` 会隔离每个私信房间。
- Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。
-- 完整的 Matrix 配置、目标规则和设置示例文档见 [Matrix](/zh-CN/channels/matrix)。
+- 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。
### Microsoft Teams
@@ -692,15 +684,15 @@ Microsoft Teams 由扩展支持，配置位于 `channels.msteams` 下。
msteams: {
enabled: true,
configWrites: true,
- // appId, appPassword, tenantId, webhook, team/channel policies:
- // see /channels/msteams
+ // appId、appPassword、tenantId、webhook、团队/渠道策略：
+ // 参见 /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
@@ -725,13 +717,13 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。
}
```
-- 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。
-- 可选的 `channels.irc.defaultAccount` 可在其匹配已配置账号 ID 时覆盖默认账号选择。
-- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/提及门控）文档见 [IRC](/zh-CN/channels/irc)。
+- 这里涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。
+- 可选的 `channels.irc.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。
+- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/mention gating）记录在 [IRC](/zh-CN/channels/irc) 中。
### 多账号（所有渠道）
-每个渠道可运行多个账号（每个账号都有自己的 `accountId`）：
+为单个渠道运行多个账号（每个账号有各自的 `accountId`）：
```json5
{
@@ -739,11 +731,11 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。
telegram: {
accounts: {
default: {
- name: "Primary bot",
+ name: "主 Bot",
botToken: "123456:ABC...",
},
alerts: {
- name: "Alerts bot",
+ name: "告警 Bot",
botToken: "987654:XYZ...",
},
},
@@ -753,27 +745,27 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。
```
- 省略 `accountId` 时使用 `default`（CLI + 路由）。
-- 环境变量 token 仅适用于**默认**账号。
-- 基础渠道设置会应用到所有账号，除非被按账号覆盖。
-- 使用 `bindings[].match.accountId` 可将每个账号路由到不同的智能体。
-- 如果你在仍使用单账号顶层渠道配置时，通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，OpenClaw 会先将按账号划分的顶层单账号值提升到该渠道的账号映射中，以保持原账号继续工作。大多数渠道会将这些值移动到 `channels..accounts.default`；而 Matrix 则可以保留现有匹配的命名/默认目标。
-- 现有仅限渠道的绑定（无 `accountId`）仍会匹配默认账号；按账号作用域的绑定仍然是可选的。
-- `openclaw doctor --fix` 也会通过将按账号划分的顶层单账号值移动到该渠道所选的提升账号中，来修复混合形态。大多数渠道使用 `accounts.default`；而 Matrix 则可以保留现有匹配的命名/默认目标。
+- 环境变量 token 仅适用于 **default** 账号。
+- 基础渠道设置会应用到所有账号，除非在按账号层级进行了覆盖。
+- 使用 `bindings[].match.accountId` 将每个账号路由到不同的智能体。
+- 如果你在仍为单账号顶层渠道配置的情况下通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，OpenClaw 会先将账号作用域的顶层单账号值提升到渠道账号映射中，这样原有账号仍可继续工作。大多数渠道会将其移至 `channels..accounts.default`；而 Matrix 则可以改为保留现有匹配的命名/default 目标。
+- 现有仅渠道级的绑定（无 `accountId`）会继续匹配默认账号；账号作用域绑定仍然是可选的。
+- `openclaw doctor --fix` 也会通过将账号作用域的顶层单账号值移动到该渠道所选的提升账号中来修复混合形状。大多数渠道使用 `accounts.default`；而 Matrix 则可以改为保留现有匹配的命名/default 目标。
### 其他扩展渠道
-许多扩展渠道以 `channels.` 形式配置，并在各自专门的渠道页面中提供文档（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。
-请参阅完整渠道索引： [渠道](/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 自聊模式下会被忽略。
-- **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。
-- 仅当能够检测提及（原生提及或至少一个模式）时，才会强制执行提及门控。
+- **元数据提及**：原生平台 @ 提及。在 WhatsApp self-chat 模式下会被忽略。
+- **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 的安全正则模式。无效模式和不安全的嵌套重复会被忽略。
+- 仅当检测可行时才会强制执行提及门控（存在原生提及，或至少存在一个模式）。
```json5
{
@@ -803,13 +795,13 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。
}
```
-解析顺序：按私信覆盖 → 提供商默认值 → 无限制（保留全部）。
+解析顺序：按私信覆盖 → 提供商默认值 → 不限制（全部保留）。
支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。
-#### 自聊模式
+#### self-chat 模式
-将你自己的号码加入 `allowFrom` 以启用自聊模式（忽略原生 @ 提及，仅响应文本模式）：
+在 `allowFrom` 中包含你自己的号码即可启用 self-chat 模式（忽略原生 @ 提及，仅响应文本模式）：
```json5
{
@@ -830,21 +822,21 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。
}
```
-### 命令（聊天命令处理）
+### Commands（聊天命令处理）
```json5
{
commands: {
- native: "auto", // register native commands when supported
- nativeSkills: "auto", // register native skill commands when supported
- text: true, // parse /commands in chat messages
- bash: false, // allow ! (alias: /bash)
+ native: "auto", // 在支持时注册原生命令
+ nativeSkills: "auto", // 在支持时注册原生 Skills 命令
+ text: true, // 解析聊天消息中的 /commands
+ bash: false, // 允许 !（别名：/bash）
bashForegroundMs: 2000,
- config: false, // allow /config
- mcp: false, // allow /mcp
- plugins: false, // allow /plugins
- debug: false, // allow /debug
- restart: true, // allow /restart + gateway restart tool
+ config: false, // 允许 /config
+ mcp: false, // 允许 /mcp
+ plugins: false, // 允许 /plugins
+ debug: false, // 允许 /debug
+ restart: true, // 允许 /restart + gateway restart 工具
ownerAllowFrom: ["discord:123456789012345678"],
ownerDisplay: "raw", // raw | hash
ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
@@ -859,28 +851,28 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。
-- 此代码块配置命令入口。有关当前内置 + 内置捆绑命令目录，请参见 [Slash Commands](/zh-CN/tools/slash-commands)。
-- 本页是**配置键参考**，不是完整的命令目录。由渠道/插件拥有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、设备配对 `/pair`、memory `/dreaming`、phone-control `/phone` 和 Talk `/voice`，记录在各自的渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。
-- 文本命令必须是带有前导 `/` 的**独立**消息。
-- `native: "auto"` 会为 Discord/Telegram 开启原生命令，Slack 则保持关闭。
-- `nativeSkills: "auto"` 会为 Discord/Telegram 开启原生 Skills 命令，Slack 则保持关闭。
-- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除之前已注册的命令。
+- 此配置块用于设置命令面。当前内置 + 内置插件的命令目录，请参阅 [Slash Commands](/zh-CN/tools/slash-commands)。
+- 本页是**配置键参考**，不是完整命令目录。像 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、device-pair `/pair`、memory `/dreaming`、phone-control `/phone` 和 Talk `/voice` 这类由渠道/插件拥有的命令，记录在它们各自的渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。
+- 文本命令必须是带前导 `/` 的**独立**消息。
+- `native: "auto"` 会为 Discord/Telegram 打开原生命令，Slack 保持关闭。
+- `nativeSkills: "auto"` 会为 Discord/Telegram 打开原生 Skills 命令，Slack 保持关闭。
+- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前已注册的命令。
- 使用 `channels..commands.nativeSkills` 按渠道覆盖原生 Skills 命令注册。
-- `channels.telegram.customCommands` 会添加额外的 Telegram 机器人菜单项。
-- `bash: true` 会为主机 shell 启用 `! `。要求 `tools.elevated.enabled` 已启用，且发送者位于 `tools.elevated.allowFrom.` 中。
+- `channels.telegram.customCommands` 会添加额外的 Telegram bot 菜单项。
+- `bash: true` 会为主机 shell 启用 `! `。需要 `tools.elevated.enabled`，且发送者在 `tools.elevated.allowFrom.` 中。
- `config: true` 会启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化的 `/config set|unset` 写入还要求 `operator.admin`；只读的 `/config show` 对普通写入作用域的 operator 客户端仍然可用。
- `mcp: true` 会为 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。
- `plugins: true` 会启用 `/plugins`，用于插件发现、安装以及启用/禁用控制。
-- `channels..configWrites` 按渠道控制配置修改权限（默认：true）。
-- 对于多账号渠道，`channels..accounts..configWrites` 也会控制面向该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。
-- `restart: false` 会禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。
-- `ownerAllowFrom` 是仅限 owner 命令/工具的显式 owner 允许列表。它与 `allowFrom` 分开。
-- `ownerDisplay: "hash"` 会在系统提示词中对 owner id 进行哈希处理。设置 `ownerDisplaySecret` 以控制哈希。
-- `allowFrom` 是按提供商区分的。设置后，它将成为**唯一**的授权来源（渠道 allowlist/配对和 `useAccessGroups` 会被忽略）。
-- `useAccessGroups: false` 允许命令在未设置 `allowFrom` 时绕过 access-group 策略。
+- `channels..configWrites` 按渠道控制配置变更（默认：true）。
+- 对于多账号渠道，`channels..accounts..configWrites` 也会控制针对该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。
+- `restart: false` 会禁用 `/restart` 和 gateway restart 工具操作。默认：`true`。
+- `ownerAllowFrom` 是 owner-only 命令/工具的显式所有者允许列表。它与 `allowFrom` 是分开的。
+- `ownerDisplay: "hash"` 会在 system prompt 中对所有者 ID 进行哈希。设置 `ownerDisplaySecret` 可控制哈希。
+- `allowFrom` 按提供商设置。设置后，它会成为**唯一**授权来源（渠道允许列表/配对以及 `useAccessGroups` 都会被忽略）。
+- `useAccessGroups: false` 会在未设置 `allowFrom` 时允许命令绕过访问组策略。
- 命令文档映射：
- - 内置 + 内置捆绑目录：[Slash Commands](/zh-CN/tools/slash-commands)
- - 渠道专属命令入口：[Channels](/zh-CN/channels)
+ - 内置 + 内置插件目录：[Slash Commands](/zh-CN/tools/slash-commands)
+ - 渠道特定命令面：[Channels](/zh-CN/channels)
- QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot)
- 配对命令：[Pairing](/zh-CN/channels/pairing)
- LINE 卡片命令：[LINE](/zh-CN/channels/line)
@@ -904,7 +896,7 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。
### `agents.defaults.repoRoot`
-可选的仓库根目录，会显示在系统提示词的 Runtime 行中。如果未设置，OpenClaw 会从工作区向上遍历并自动检测。
+可选的仓库根目录，会显示在 system prompt 的 Runtime 行中。若未设置，OpenClaw 会从工作区向上遍历并自动检测。
```json5
{
@@ -914,16 +906,14 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。
### `agents.defaults.skills`
-为未设置
-`agents.list[].skills`
-的智能体提供的可选默认 Skills 允许列表。
+为未设置 `agents.list[].skills` 的智能体提供可选的默认 Skills 允许列表。
```json5
{
agents: {
defaults: { skills: ["github", "weather"] },
list: [
- { id: "writer" }, // 继承 github, weather
+ { id: "writer" }, // 继承 github、weather
{ id: "docs", skills: ["docs-search"] }, // 替换默认值
{ id: "locked-down", skills: [] }, // 无 Skills
],
@@ -931,15 +921,14 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。
}
```
-- 省略 `agents.defaults.skills`，则默认 Skills 不受限制。
-- 省略 `agents.list[].skills` 以继承默认值。
+- 省略 `agents.defaults.skills` 可使默认 Skills 不受限制。
+- 省略 `agents.list[].skills` 可继承默认值。
- 设置 `agents.list[].skills: []` 表示不启用任何 Skills。
-- 非空的 `agents.list[].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
{
@@ -949,9 +938,9 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。
### `agents.defaults.contextInjection`
-控制何时将工作区引导文件注入系统提示词。默认值：`"always"`。
+控制何时将工作区 bootstrap 文件注入到 system prompt 中。默认值：`"always"`。
-- `"continuation-skip"`：安全续接轮次（在 assistant 完成响应之后）会跳过工作区引导内容的再次注入，从而减小提示词大小。Heartbeat 运行和压缩后重试仍会重建上下文。
+- `"continuation-skip"`：安全续接轮次（在 assistant 完成回复之后）会跳过工作区 bootstrap 的重新注入，从而减小 prompt 大小。heartbeat 运行和压缩后重试仍会重建上下文。
```json5
{
@@ -961,7 +950,7 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。
### `agents.defaults.bootstrapMaxChars`
-每个工作区引导文件在截断前允许的最大字符数。默认值：`12000`。
+每个工作区 bootstrap 文件在截断前允许的最大字符数。默认值：`12000`。
```json5
{
@@ -971,7 +960,7 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。
### `agents.defaults.bootstrapTotalMaxChars`
-所有工作区引导文件合计可注入的最大字符数。默认值：`60000`。
+在所有工作区 bootstrap 文件中注入的总最大字符数。默认值：`60000`。
```json5
{
@@ -981,12 +970,12 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。
### `agents.defaults.bootstrapPromptTruncationWarning`
-控制在引导上下文被截断时，向智能体显示的警告文本。
+控制在 bootstrap 上下文被截断时，向智能体显示的警告文本。
默认值：`"once"`。
-- `"off"`：绝不将警告文本注入系统提示词。
-- `"once"`：对每个唯一的截断签名仅注入一次警告（推荐）。
-- `"always"`：只要存在截断，就在每次运行时都注入警告。
+- `"off"`：绝不向 system prompt 注入警告文本。
+- `"once"`：每个唯一的截断签名仅注入一次警告（推荐）。
+- `"always"`：只要存在截断，每次运行都注入警告。
```json5
{
@@ -996,33 +985,29 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。
### 上下文预算归属映射
-OpenClaw 有多个高容量提示词/上下文预算，它们
-会按子系统有意拆分，而不是全部通过一个通用
-开关来控制。
+OpenClaw 有多个高容量的 prompt/上下文预算，这些预算被有意按子系统拆分，而不是都流经一个通用调节项。
- `agents.defaults.bootstrapMaxChars` /
`agents.defaults.bootstrapTotalMaxChars`：
- 常规工作区引导内容注入。
+ 常规工作区 bootstrap 注入。
- `agents.defaults.startupContext.*`：
一次性的 `/new` 和 `/reset` 启动前导内容，包括最近的每日
`memory/*.md` 文件。
- `skills.limits.*`：
- 注入系统提示词中的紧凑 Skills 列表。
+ 注入到 system prompt 中的紧凑 Skills 列表。
- `agents.defaults.contextLimits.*`：
- 受限的运行时摘录和由运行时拥有的注入内容块。
+ 有界运行时摘录和注入的运行时拥有块。
- `memory.qmd.limits.*`：
- 已索引 memory 搜索片段与注入大小控制。
+ 已索引 memory 搜索片段和注入大小控制。
-仅当某个智能体需要不同的
-预算时，才使用对应的按智能体覆盖项：
+仅当某个智能体需要不同预算时，才使用匹配的按智能体覆盖：
- `agents.list[].skillsLimits.maxSkillsPromptChars`
- `agents.list[].contextLimits.*`
#### `agents.defaults.startupContext`
-控制在裸 `/new` 和 `/reset`
-运行时注入的首轮启动前导内容。
+控制在裸 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。
```json5
{
@@ -1043,7 +1028,7 @@ OpenClaw 有多个高容量提示词/上下文预算，它们
#### `agents.defaults.contextLimits`
-受限运行时上下文入口的共享默认值。
+用于有界运行时上下文面的共享默认值。
```json5
{
@@ -1060,19 +1045,14 @@ OpenClaw 有多个高容量提示词/上下文预算，它们
}
```
-- `memoryGetMaxChars`：`memory_get` 摘录在添加截断
- 元数据和续接提示前的默认上限。
-- `memoryGetDefaultLines`：当省略 `lines` 时，
- `memory_get` 的默认行窗口。
-- `toolResultMaxChars`：用于持久化结果和溢出恢复的
- 实时工具结果上限。
-- `postCompactionMaxChars`：压缩后刷新注入期间
- `AGENTS.md` 摘录的上限。
+- `memoryGetMaxChars`：`memory_get` 摘录在添加截断元数据和续接提示前的默认上限。
+- `memoryGetDefaultLines`：在省略 `lines` 时，`memory_get` 的默认行窗口。
+- `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。
+- `postCompactionMaxChars`：在压缩后刷新注入期间使用的 `AGENTS.md` 摘录上限。
#### `agents.list[].contextLimits`
-共享 `contextLimits` 开关的按智能体覆盖项。省略的字段会继承
-自 `agents.defaults.contextLimits`。
+对共享 `contextLimits` 调节项的按智能体覆盖。省略的字段会继承自 `agents.defaults.contextLimits`。
```json5
{
@@ -1098,8 +1078,7 @@ OpenClaw 有多个高容量提示词/上下文预算，它们
#### `skills.limits.maxSkillsPromptChars`
-注入系统提示词中的紧凑 Skills 列表的全局上限。它
-不会影响按需读取 `SKILL.md` 文件。
+注入到 system prompt 中的紧凑 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。
```json5
{
@@ -1113,7 +1092,7 @@ OpenClaw 有多个高容量提示词/上下文预算，它们
#### `agents.list[].skillsLimits.maxSkillsPromptChars`
-Skills 提示词预算的按智能体覆盖项。
+按智能体覆盖 Skills prompt 预算。
```json5
{
@@ -1132,11 +1111,11 @@ Skills 提示词预算的按智能体覆盖项。
### `agents.defaults.imageMaxDimensionPx`
-在调用提供商之前，transcript/tool 图像块中图像最长边的最大像素尺寸。
+在调用提供商之前，转录/工具图像块中图像最长边的最大像素尺寸。
默认值：`1200`。
-较低的值通常会减少视觉 token 用量和请求负载大小，适合大量截图的运行场景。
-较高的值则能保留更多视觉细节。
+较低的值通常会减少视觉 token 用量和以截图为主的运行中的请求负载大小。
+较高的值则会保留更多视觉细节。
```json5
{
@@ -1146,7 +1125,7 @@ Skills 提示词预算的按智能体覆盖项。
### `agents.defaults.userTimezone`
-用于系统提示词上下文的时区（不影响消息时间戳）。会回退到主机时区。
+用于 system prompt 上下文的时区（不是消息时间戳）。会回退到主机时区。
```json5
{
@@ -1156,7 +1135,7 @@ Skills 提示词预算的按智能体覆盖项。
### `agents.defaults.timeFormat`
-系统提示词中的时间格式。默认值：`auto`（操作系统偏好）。
+system prompt 中的时间格式。默认值：`auto`（操作系统偏好）。
```json5
{
@@ -1196,7 +1175,7 @@ Skills 提示词预算的按智能体覆盖项。
},
params: { cacheRetention: "long" }, // 全局默认提供商参数
embeddedHarness: {
- runtime: "auto", // auto | pi | 已注册的 harness id，例如 codex
+ runtime: "auto", // auto | pi | 已注册 harness id，例如 codex
fallback: "pi", // pi | none
},
pdfMaxBytesMb: 10,
@@ -1214,47 +1193,47 @@ Skills 提示词预算的按智能体覆盖项。
```
- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- - 字符串形式仅设置主模型。
- - 对象形式设置主模型以及按顺序排列的故障切换模型。
+ - 字符串形式只设置主模型。
+ - 对象形式设置主模型以及按顺序的故障转移模型。
- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 作为 `image` 工具路径的视觉模型配置使用。
- 当选定/默认模型无法接受图像输入时，也用作回退路由。
- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- - 用于共享的图像生成能力，以及任何未来会生成图像的工具/插件入口。
- - 典型值：原生 Gemini 图像生成可用 `google/gemini-3.1-flash-image-preview`，fal 可用 `fal/fal-ai/flux/dev`，OpenAI Images 可用 `openai/gpt-image-1`。
+ - 由共享的图像生成能力以及未来任何生成图像的工具/插件面使用。
+ - 典型值：`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 顺序尝试其余已注册的图像生成提供商。
+ - 如果省略，`image_generate` 仍可推断一个有凭证支持的默认提供商。它会先尝试当前默认提供商，再按 provider-id 顺序尝试其余已注册的图像生成提供商。
- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- - 用于共享的音乐生成能力以及内置的 `music_generate` 工具。
+ - 由共享的音乐生成能力和内置 `music_generate` 工具使用。
- 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。
- - 如果省略，`music_generate` 仍可推断出一个带凭证的默认提供商。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的音乐生成提供商。
+ - 如果省略，`music_generate` 仍可推断一个有凭证支持的默认提供商。它会先尝试当前默认提供商，再按 provider-id 顺序尝试其余已注册的音乐生成提供商。
- 如果你直接选择某个 provider/model，也要配置对应的提供商凭证/API key。
- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- - 用于共享的视频生成能力以及内置的 `video_generate` 工具。
+ - 由共享的视频生成能力和内置 `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 顺序尝试其余已注册的视频生成提供商。
+ - 如果省略，`video_generate` 仍可推断一个有凭证支持的默认提供商。它会先尝试当前默认提供商，再按 provider-id 顺序尝试其余已注册的视频生成提供商。
- 如果你直接选择某个 provider/model，也要配置对应的提供商凭证/API key。
- - 内置捆绑的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。
+ - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图片、4 个输入视频、10 秒时长，以及提供商级 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。
- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 由 `pdf` 工具用于模型路由。
- 如果省略，PDF 工具会先回退到 `imageModel`，再回退到解析后的会话/默认模型。
-- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb`，这是 `pdf` 工具的默认 PDF 大小限制。
-- `pdfMaxPages`：`pdf` 工具中提取回退模式默认考虑的最大页数。
+- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。
+- `pdfMaxPages`：`pdf` 工具在提取回退模式下考虑的默认最大页数。
- `verboseDefault`：智能体的默认 verbose 级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。
- `elevatedDefault`：智能体的默认 elevated-output 级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。
-- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试 alias，然后尝试与该精确模型 id 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此更推荐显式使用 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider/model，而不是暴露一个陈旧的、已移除提供商默认值。
-- `models`：`/model` 使用的已配置模型目录与允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。
-- `params`：应用于所有模型的全局默认提供商参数。在 `agents.defaults.params` 处设置（例如 `{ cacheRetention: "long" }`）。
-- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配的智能体 id）会按键覆盖。详情请参见 [Prompt Caching](/zh-CN/reference/prompt-caching)。
-- `embeddedHarness`：默认的低层嵌入式智能体运行时策略。使用 `runtime: "auto"` 让已注册的插件 harness 声明其支持的模型，使用 `runtime: "pi"` 强制使用内置的 Pi harness，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 Pi 回退。
-- 修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及 fallback add/remove 命令）会保存规范对象形式，并在可能时保留现有的 fallback 列表。
-- `maxConcurrent`：跨会话的智能体最大并行运行数（每个会话本身仍然串行）。默认值：4。
+- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果你省略 provider，OpenClaw 会先尝试别名，然后尝试对该精确模型 id 的唯一已配置提供商匹配，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此更推荐显式写成 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider/model，而不是继续暴露一个陈旧的、已移除提供商默认值。
+- `models`：为 `/model` 配置的模型目录和允许列表。每个条目可包含 `alias`（快捷名）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。
+- `params`：应用于所有模型的全局默认提供商参数。设置位置在 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。
+- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配的智能体 id）再按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。
+- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。使用 `runtime: "auto"` 可让已注册插件 harness 接管支持的模型，使用 `runtime: "pi"` 可强制使用内置 PI harness，或填写已注册的 harness id，如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 PI 回退。
+- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退模型 add/remove 命令）会保存为规范对象形式，并在可能时保留现有回退列表。
+- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话本身仍是串行）。默认值：4。
### `agents.defaults.embeddedHarness`
-`embeddedHarness` 控制由哪个低层执行器来运行嵌入式智能体轮次。
+`embeddedHarness` 控制哪个底层执行器来运行嵌入式智能体轮次。
大多数部署应保持默认值 `{ runtime: "auto", fallback: "pi" }`。
-当受信任插件提供原生 harness 时使用它，例如内置捆绑的
+当某个受信任插件提供原生 harness 时使用它，例如内置
Codex app-server harness。
```json5
@@ -1271,15 +1250,15 @@ Codex app-server harness。
}
```
-- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置捆绑的 Codex 插件会注册 `codex`。
-- `fallback`：`"pi"` 或 `"none"`。`"pi"` 会保留内置 Pi harness 作为兼容性回退。`"none"` 会在插件 harness 选择缺失或不受支持时直接失败，而不是静默使用 Pi。
-- 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=none` 会为该进程禁用 Pi 回退。
-- 对于仅使用 Codex 的部署，请设置 `model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。
-- 这仅控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的 provider/model 设置。
+- `runtime`：`"auto"`、`"pi"` 或已注册插件 harness id。内置 Codex 插件注册的 id 是 `codex`。
+- `fallback`：`"pi"` 或 `"none"`。`"pi"` 会保留内置 PI harness 作为兼容性回退。`"none"` 则会在插件 harness 缺失或不支持时直接失败，而不是静默使用 PI。
+- 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=none` 会为该进程禁用 PI 回退。
+- 对于仅 Codex 的部署，请设置 `model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。
+- 这只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的 provider/model 设置。
-**内置 alias 简写**（仅在模型位于 `agents.defaults.models` 中时适用）：
+**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时生效）：
-| Alias | 模型 |
+| 别名 | 模型 |
| ------------------- | -------------------------------------- |
| `opus` | `anthropic/claude-opus-4-6` |
| `sonnet` | `anthropic/claude-sonnet-4-6` |
@@ -1290,15 +1269,15 @@ Codex app-server harness。
| `gemini-flash` | `google/gemini-3-flash-preview` |
| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` |
-你配置的 alias 始终优先于默认值。
+你配置的别名始终优先于默认值。
-Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/"].params.thinking`。
-Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用它。
-Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 `adaptive` thinking。
+Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off` 或自行定义 `agents.defaults.models["zai/"].params.thinking`。
+Z.AI 模型默认启用 `tool_stream` 用于工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用它。
+当未设置显式 thinking 级别时，Anthropic Claude 4.6 模型默认使用 `adaptive` thinking。
### `agents.defaults.cliBackends`
-纯文本回退运行（无工具调用）的可选 CLI 后端。在 API 提供商失败时可作为备用方案。
+可选的 CLI 后端，用于纯文本回退运行（无工具调用）。当 API 提供商失败时，它可作为备份。
```json5
{
@@ -1332,7 +1311,7 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用
### `agents.defaults.systemPromptOverride`
-使用固定字符串替换整个由 OpenClaw 组装的系统提示词。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体（`agents.list[].systemPromptOverride`）设置。按智能体的值优先；空值或仅含空白字符的值会被忽略。适合受控的提示词实验。
+用固定字符串替换整个由 OpenClaw 组装的 system prompt。可设置在默认层级（`agents.defaults.systemPromptOverride`）或按智能体设置（`agents.list[].systemPromptOverride`）。按智能体的值优先；空值或仅空白字符的值会被忽略。适用于受控 prompt 实验。
```json5
{
@@ -1346,7 +1325,7 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用
### `agents.defaults.heartbeat`
-周期性 Heartbeat 运行。
+周期性 heartbeat 运行。
```json5
{
@@ -1356,9 +1335,9 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用
every: "30m", // 0m 表示禁用
model: "openai/gpt-5.4-mini",
includeReasoning: false,
- includeSystemPromptSection: true, // 默认：true；false 会省略系统提示词中的 Heartbeat 部分
- lightContext: false, // 默认：false；true 只保留工作区引导文件中的 HEARTBEAT.md
- isolatedSession: false, // 默认：false；true 会让每次 heartbeat 在新会话中运行（无会话历史）
+ includeSystemPromptSection: true, // 默认：true；false 会从 system prompt 中省略 Heartbeat 部分
+ lightContext: false, // 默认：false；true 仅从工作区 bootstrap 文件中保留 HEARTBEAT.md
+ isolatedSession: false, // 默认：false；true 会让每次 heartbeat 在全新会话中运行（无对话历史）
session: "main",
to: "+15555550123",
directPolicy: "allow", // allow（默认）| block
@@ -1373,15 +1352,15 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用
}
```
-- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。
-- `includeSystemPromptSection`：为 false 时，会省略系统提示词中的 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入引导上下文。默认值：`true`。
-- `suppressToolErrorWarnings`：为 true 时，会在 Heartbeat 运行期间抑制工具错误警告负载。
-- `timeoutSeconds`：Heartbeat 智能体轮次在被中止前允许的最长秒数。未设置时使用 `agents.defaults.timeoutSeconds`。
-- `directPolicy`：直达/私信投递策略。`allow`（默认）允许直达目标投递。`block` 会阻止直达目标投递，并发出 `reason=dm-blocked`。
-- `lightContext`：为 true 时，Heartbeat 运行会使用轻量引导上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。
-- `isolatedSession`：为 true 时，每次 Heartbeat 都会在没有先前对话历史的新会话中运行。与 cron `sessionTarget: "isolated"` 的隔离模式相同。可将每次 heartbeat 的 token 成本从约 100K 降低到约 2-5K。
-- 按智能体设置：使用 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 Heartbeat。
-- Heartbeat 会运行完整的智能体轮次——更短的间隔会消耗更多 token。
+- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API-key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。
+- `includeSystemPromptSection`：为 false 时，会从 system prompt 中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。
+- `suppressToolErrorWarnings`：为 true 时，会在 heartbeat 运行期间抑制工具错误警告负载。
+- `timeoutSeconds`：heartbeat 智能体轮次在被中止前允许的最长秒数。留空则使用 `agents.defaults.timeoutSeconds`。
+- `directPolicy`：direct/私信投递策略。`allow`（默认）允许 direct 目标投递。`block` 会抑制 direct 目标投递，并发出 `reason=dm-blocked`。
+- `lightContext`：为 true 时，heartbeat 运行使用轻量 bootstrap 上下文，并且仅从工作区 bootstrap 文件中保留 `HEARTBEAT.md`。
+- `isolatedSession`：为 true 时，每次 heartbeat 都会在没有先前对话历史的全新会话中运行。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次 heartbeat 的 token 成本从约 100K 降到约 2-5K token。
+- 按智能体设置：使用 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 heartbeat。
+- Heartbeat 会运行完整的智能体轮次——间隔越短，消耗的 token 越多。
### `agents.defaults.compaction`
@@ -1395,15 +1374,15 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用
timeoutSeconds: 900,
reserveTokensFloor: 24000,
identifierPolicy: "strict", // strict | off | custom
- identifierInstructions: "精确保留部署 ID、工单 ID 和 host:port 对。", // 当 identifierPolicy=custom 时使用
+ identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用
postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入
- model: "openrouter/anthropic/claude-sonnet-4-6", // 仅用于 compaction 的模型覆盖（可选）
- notifyUser: true, // 在 compaction 开始和完成时向用户发送简短通知（默认：false）
+ model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于 compaction 的模型覆盖
+ notifyUser: true, // 在 compaction 开始和完成时发送简短通知（默认：false）
memoryFlush: {
enabled: true,
softThresholdTokens: 6000,
- systemPrompt: "会话即将触发 compaction。现在请存储持久记忆。",
- prompt: "将任何需要长期保留的笔记写入 memory/YYYY-MM-DD.md；如果没有要存储的内容，请准确回复静默 token NO_REPLY。",
+ systemPrompt: "Session nearing compaction. Store durable memories now.",
+ prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.",
},
},
},
@@ -1412,18 +1391,18 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用
```
- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。
-- `provider`：已注册 compaction 提供商插件的 id。设置后，将调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置实现。设置提供商会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。
-- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最长秒数。默认值：`900`。
+- `provider`：已注册 compaction 提供商插件的 id。设置后，会调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时回退到内置实现。设置提供商会强制 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。
+- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最大秒数。默认值：`900`。
- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的不透明标识符保留指导。
- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。
-- `postCompactionSections`：compaction 后重新注入的可选 `AGENTS.md` H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。未设置时，或显式设置为该默认组合时，也接受旧版的 `Every Session`/`Safety` 标题作为兼容性回退。
-- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。适用于主会话保留一个模型，而 compaction 摘要改用另一个模型的场景；未设置时，compaction 使用该会话的主模型。
-- `notifyUser`：为 `true` 时，会在 compaction 开始和完成时向用户发送简短通知（例如“正在压缩上下文...”和“上下文压缩完成”）。默认禁用，以保持 compaction 静默进行。
-- `memoryFlush`：在自动 compaction 之前执行的静默智能体轮次，用于存储持久记忆。当工作区为只读时会跳过。
+- `postCompactionSections`：compaction 后重新注入的可选 `AGENTS.md` H2/H3 节名。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。当未设置或显式设置为该默认对时，也会接受旧版 `Every Session`/`Safety` 标题作为兼容回退。
+- `model`：可选的 `provider/model-id` 覆盖，仅用于 compaction 摘要。当主会话应继续使用一个模型，而 compaction 摘要应使用另一个模型时使用；未设置时，compaction 使用会话的主模型。
+- `notifyUser`：为 `true` 时，在 compaction 开始和完成时向用户发送简短通知（例如“正在压缩上下文...”和“上下文压缩完成”）。默认禁用，以保持 compaction 静默。
+- `memoryFlush`：在自动 compaction 之前执行静默智能体轮次以存储持久 memory。工作区为只读时会跳过。
### `agents.defaults.contextPruning`
-在发送给 LLM 之前，从内存上下文中修剪**旧的工具结果**。**不会**修改磁盘上的会话历史。
+在发送到 LLM 之前，从内存上下文中裁剪**旧工具结果**。**不会**修改磁盘上的会话历史。
```json5
{
@@ -1437,7 +1416,7 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用
hardClearRatio: 0.5,
minPrunableToolChars: 50000,
softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
- hardClear: { enabled: true, placeholder: "[旧工具结果内容已清除]" },
+ hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },
tools: { deny: ["browser", "canvas"] },
},
},
@@ -1447,19 +1426,19 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用
-- `mode: "cache-ttl"` 会启用修剪流程。
-- `ttl` 控制修剪再次运行的频率（从上次缓存触发开始计算）。
-- 修剪会先对过大的工具结果进行软修剪，然后在需要时对更旧的工具结果执行硬清除。
+- `mode: "cache-ttl"` 会启用裁剪流程。
+- `ttl` 控制多久后才能再次运行裁剪（自上次缓存触碰后开始计算）。
+- 如有需要，裁剪会先对过大的工具结果进行软裁剪，然后再对更旧的工具结果执行硬清除。
-**软修剪**会保留开头 + 结尾，并在中间插入 `...`。
+**软裁剪**会保留开头和结尾，并在中间插入 `...`。
**硬清除**会用占位符替换整个工具结果。
-注意：
+说明：
-- 图像块永远不会被修剪/清除。
-- 比例按字符计算（近似），不是精确 token 数。
-- 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过修剪。
+- 图像块永远不会被裁剪/清除。
+- 比例是基于字符的（近似值），不是精确 token 数。
+- 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过裁剪。
@@ -1482,12 +1461,12 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用
```
- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。
-- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号区分的变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
+- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。
行为和分块细节请参见 [Streaming](/zh-CN/concepts/streaming)。
-### 输入中指示器
+### 输入指示器
```json5
{
@@ -1500,7 +1479,7 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用
}
```
-- 默认值：私聊/提及时使用 `instant`，未提及的群聊使用 `message`。
+- 默认值：私聊/提及时为 `instant`，未提及的群聊为 `message`。
- 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。
参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。
@@ -1509,7 +1488,7 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用
### `agents.defaults.sandbox`
-嵌入式智能体的可选沙箱隔离。完整指南请参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。
+嵌入式智能体的可选沙箱隔离。完整指南请参见 [Sandboxing](/zh-CN/gateway/sandboxing)。
```json5
{
@@ -1609,47 +1588,47 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用
**后端：**
- `docker`：本地 Docker 运行时（默认）
-- `ssh`：通用 SSH 远程运行时
+- `ssh`：通用的 SSH 支持远程运行时
- `openshell`：OpenShell 运行时
-选择 `backend: "openshell"` 时，运行时专属设置会移动到
+当选择 `backend: "openshell"` 时，运行时特定设置会移到
`plugins.entries.openshell.config`。
**SSH 后端配置：**
- `target`：`user@host[:port]` 形式的 SSH 目标
- `command`：SSH 客户端命令（默认：`ssh`）
-- `workspaceRoot`：用于按作用域划分工作区的远程绝对根目录
+- `workspaceRoot`：用于各 scope 工作区的远程绝对根目录
- `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件
- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件
-- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关
+- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH host-key 策略调节项
**SSH 认证优先级：**
- `identityData` 优先于 `identityFile`
- `certificateData` 优先于 `certificateFile`
- `knownHostsData` 优先于 `knownHostsFile`
-- 基于 SecretRef 的 `*Data` 值会在沙箱会话启动前，从当前 secrets 运行时快照中解析
+- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前从当前活动的 secrets 运行时快照中解析
**SSH 后端行为：**
-- 在创建或重建后，会先为远程工作区执行一次初始化填充
-- 此后保持远程 SSH 工作区为权威副本
+- 在创建或重建后只对远程工作区进行一次初始填充
+- 之后保持远程 SSH 工作区为规范副本
- 通过 SSH 路由 `exec`、文件工具和媒体路径
-- 不会自动将远程更改同步回主机
+- 不会自动将远程变更同步回主机
- 不支持沙箱浏览器容器
**工作区访问：**
-- `none`：在 `~/.openclaw/sandboxes` 下使用按作用域划分的沙箱工作区
+- `none`：在 `~/.openclaw/sandboxes` 下使用按 scope 划分的沙箱工作区
- `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent`
- `rw`：智能体工作区以读写方式挂载到 `/workspace`
-**作用域：**
+**Scope：**
-- `session`：每个会话一个容器 + 工作区
+- `session`：每会话一个容器 + 工作区
- `agent`：每个智能体一个容器 + 工作区（默认）
-- `shared`：共享容器和工作区（不提供跨会话隔离）
+- `shared`：共享容器和工作区（无跨会话隔离）
**OpenShell 插件配置：**
@@ -1679,30 +1658,30 @@ Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用
**OpenShell 模式：**
-- `mirror`：在执行前从本地初始化远程，执行后再同步回来；本地工作区保持为权威副本
-- `remote`：在创建沙箱时仅初始化远程一次，此后保持远程工作区为权威副本
+- `mirror`：在 exec 前将本地内容同步到远程，在 exec 后同步回本地；本地工作区保持为规范副本
+- `remote`：在创建沙箱时只向远程初始填充一次，之后保持远程工作区为规范副本
-在 `remote` 模式下，在 OpenClaw 之外于主机本地进行的编辑，在初始化步骤之后不会自动同步进沙箱。
-传输通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期和可选的镜像同步。
+在 `remote` 模式下，种子步骤之后，在 OpenClaw 外部对主机本地所做的编辑不会自动同步到沙箱中。
+传输通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期和可选的 mirror 同步。
**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。
-**容器默认使用 `network: "none"`**——如果智能体需要出站访问，请将其设置为 `"bridge"`（或自定义 bridge 网络）。
-`"host"` 会被阻止。默认情况下，`"container:"` 也会被阻止，除非你显式设置
-`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急破例开关）。
+**容器默认使用 `network: "none"`**——如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。
+`"host"` 被阻止。默认也会阻止 `"container:"`，除非你显式设置
+`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（破窗开关）。
-**入站附件**会暂存到当前工作区中的 `media/inbound/*`。
+**传入附件** 会暂存到当前活动工作区的 `media/inbound/*` 中。
-**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 binds 会合并。
+**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 bind 会合并。
-**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。会将 noVNC URL 注入系统提示词。不需要在 `openclaw.json` 中启用 `browser.enabled`。
-noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有效的 token URL（而不是在共享 URL 中暴露密码）。
+**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行的 Chromium + CDP。noVNC URL 会注入到 system prompt 中。不需要在 `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` 可选地将容器边界的 CDP 入站限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。
+- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`）会为浏览器容器替换 `docker.binds`。
+- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机做了调优：
- `--remote-debugging-address=127.0.0.1`
- `--remote-debugging-port=`
- `--user-data-dir=${HOME}/.chrome`
@@ -1721,20 +1700,20 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有
- `--metrics-recording-only`
- `--disable-extensions`（默认启用）
- `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu`
- 默认启用；如果 WebGL/3D 使用场景需要它们，可通过
- `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些标志。
+ 默认启用；如果工作流中的 WebGL/3D 使用需要它们，可通过
+ `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些默认标志。
- 如果你的工作流
- 依赖扩展，使用 `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 可重新启用扩展。
+ 依赖扩展，可通过 `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 重新启用扩展。
- `--renderer-process-limit=2` 可通过
- `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 可使用 Chromium 的
+ `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 则使用 Chromium 的
默认进程上限。
- - 此外，当启用 `noSandbox` 时，还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。
- - 这些默认值是容器镜像基线；如需更改容器默认值，请使用自定义浏览器镜像和自定义
- entrypoint。
+ - 此外，当启用 `noSandbox` 时，还会添加 `--no-sandbox` 和 `--disable-setuid-sandbox`。
+ - 这些默认值是容器镜像基线；如需更改容器默认值，请使用带有自定义
+ entrypoint 的自定义浏览器镜像。
-浏览器沙箱隔离和 `sandbox.docker.binds` 仅适用于 Docker。
+浏览器沙箱隔离和 `sandbox.docker.binds` 仅支持 Docker。
构建镜像：
@@ -1756,12 +1735,12 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
workspace: "~/.openclaw/workspace",
agentDir: "~/.openclaw/agents/main/agent",
model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks }
- thinkingDefault: "high", // 按智能体覆盖的默认 thinking 级别
- reasoningDefault: "on", // 按智能体覆盖的默认 reasoning 可见性
- fastModeDefault: false, // 按智能体覆盖的默认快速模式
+ thinkingDefault: "high", // 按智能体覆盖 thinking 级别
+ reasoningDefault: "on", // 按智能体覆盖 reasoning 可见性
+ fastModeDefault: false, // 按智能体覆盖 fast mode
embeddedHarness: { runtime: "auto", fallback: "pi" },
- params: { cacheRetention: "none" }, // 按键覆盖匹配 defaults.models params
- skills: ["docs-search"], // 设置后会替换 agents.defaults.skills
+ params: { cacheRetention: "none" }, // 按键覆盖匹配 defaults.models 的参数
+ skills: ["docs-search"], // 设置时会替换 agents.defaults.skills
identity: {
name: "Samantha",
theme: "helpful sloth",
@@ -1793,26 +1772,26 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
```
- `id`：稳定的智能体 id（必填）。
-- `default`：设置多个时，以第一个为准（会记录警告）。如果一个都没设置，则列表中的第一个条目为默认值。
-- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖两者（`[]` 会禁用全局 fallbacks）。仅覆盖 `primary` 的 cron 任务仍会继承默认 fallbacks，除非你设置 `fallbacks: []`。
-- `params`：按智能体区分的流参数，会合并到 `agents.defaults.models` 中选定模型条目之上。适用于 `cacheRetention`、`temperature` 或 `maxTokens` 等智能体专属覆盖，而无需复制整个模型目录。
-- `skills`：可选的按智能体 Skills 允许列表。如果省略，则在已设置时继承 `agents.defaults.skills`；显式列表会替换默认值而不是合并，`[]` 表示不启用任何 Skills。
+- `default`：设置了多个时，以第一个为准（会记录警告）。如果都未设置，则列表中的第一个为默认值。
+- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖两者（`[]` 会禁用全局回退模型）。仅覆盖 `primary` 的 cron 作业仍会继承默认回退模型，除非你设置 `fallbacks: []`。
+- `params`：按智能体的流参数，会合并覆盖到 `agents.defaults.models` 中选定的模型条目之上。用于像 `cacheRetention`、`temperature` 或 `maxTokens` 这类按智能体的覆盖，而无需复制整个模型目录。
+- `skills`：可选的按智能体 Skills 允许列表。如果省略，在已设置的情况下会继承 `agents.defaults.skills`；显式列表会替换默认值而不是合并，`[]` 表示不启用任何 Skills。
- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。当未设置按消息或按会话覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。
-- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当未设置按消息或按会话 reasoning 覆盖时生效。
-- `fastModeDefault`：可选的按智能体默认快速模式（`true | false`）。当未设置按消息或按会话快速模式覆盖时生效。
-- `embeddedHarness`：可选的按智能体低层 harness 策略覆盖。使用 `{ runtime: "codex", fallback: "none" }` 可让某个智能体仅使用 Codex，而其他智能体保留默认的 Pi 回退。
-- `runtime`：可选的按智能体运行时描述符。当该智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 以及 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。
+- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。在未设置按消息或按会话 reasoning 覆盖时生效。
+- `fastModeDefault`：可选的按智能体 fast mode 默认值（`true | false`）。在未设置按消息或按会话 fast-mode 覆盖时生效。
+- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex", fallback: "none" }` 可让某个智能体仅使用 Codex，而其他智能体保留默认的 PI 回退。
+- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"`，并配合 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。
- `identity.avatar`：工作区相对路径、`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
{
@@ -1831,27 +1810,27 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
### 绑定匹配字段
-- `type`（可选）：普通路由用 `route`（缺失时默认是 route），持久 ACP 对话绑定用 `acp`。
+- `type`（可选）：普通路由使用 `route`（缺失时默认是 route），持久 ACP 会话绑定使用 `acp`。
- `match.channel`（必填）
- `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号）
- `match.peer`（可选；`{ kind: direct|group|channel, id }`）
-- `match.guildId` / `match.teamId`（可选；渠道专属）
+- `match.guildId` / `match.teamId`（可选；渠道特定）
- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }`
-**确定性匹配顺序：**
+**确定性的匹配顺序：**
1. `match.peer`
2. `match.guildId`
3. `match.teamId`
4. `match.accountId`（精确匹配，无 peer/guild/team）
-5. `match.accountId: "*"`（整个渠道范围）
+5. `match.accountId: "*"`（渠道级）
6. 默认智能体
在每一层级内，第一个匹配的 `bindings` 条目获胜。
-对于 `type: "acp"` 条目，OpenClaw 会按精确对话标识（`match.channel` + account + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。
+对于 `type: "acp"` 条目，OpenClaw 会按精确会话身份（`match.channel` + 账号 + `match.peer.id`）解析，不使用上述 route 绑定层级顺序。
-### 按智能体划分的访问配置
+### 按智能体的访问配置
@@ -1972,20 +1951,20 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
},
resetTriggers: ["/new", "/reset"],
store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
- parentForkMaxTokens: 100000, // 超过此 token 数时跳过父线程分叉（0 表示禁用）
+ parentForkMaxTokens: 100000, // 超过此 token 数时跳过父线程 fork（0 表示禁用）
maintenance: {
mode: "warn", // warn | enforce
pruneAfter: "30d",
maxEntries: 500,
rotateBytes: "10mb",
resetArchiveRetention: "30d", // 时长或 false
- maxDiskBytes: "500mb", // 可选硬预算
- highWaterBytes: "400mb", // 可选清理目标
+ maxDiskBytes: "500mb", // 可选的硬预算
+ highWaterBytes: "400mb", // 可选的清理目标
},
threadBindings: {
enabled: true,
- idleHours: 24, // 默认按非活动时间自动取消聚焦的小时数（`0` 表示禁用）
- maxAgeHours: 0, // 默认硬性最大存活小时数（`0` 表示禁用）
+ idleHours: 24, // 默认的按无活动自动取消聚焦小时数（`0` 表示禁用）
+ maxAgeHours: 0, // 默认的硬性最大时长小时数（`0` 表示禁用）
},
mainKey: "main", // 旧版字段（运行时始终使用 "main"）
agentToAgent: { maxPingPongTurns: 5 },
@@ -2000,34 +1979,34 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
- **`scope`**：群聊上下文的基础会话分组策略。
- - `per-sender`（默认）：在同一渠道上下文中，每个发送者都有独立会话。
- - `global`：同一渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。
+ - `per-sender`（默认）：在某个渠道上下文内，每个发送者都有独立会话。
+ - `global`：某个渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。
- **`dmScope`**：私信的分组方式。
- `main`：所有私信共享主会话。
- `per-peer`：按发送者 id 跨渠道隔离。
- `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。
- `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。
-- **`identityLinks`**：将规范 id 映射到带提供商前缀的 peer，以便跨渠道共享会话。
-- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。两者都配置时，先到期者生效。
-- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名使用。
-- **`parentForkMaxTokens`**：创建分叉线程会话时，允许父会话 `totalTokens` 的最大值（默认 `100000`）。
- - 如果父会话的 `totalTokens` 超过该值，OpenClaw 会启动一个新的线程会话，而不是继承父 transcript 历史。
- - 设为 `0` 可禁用此保护，并始终允许从父会话分叉。
+- **`identityLinks`**：将规范 id 映射到带提供商前缀的对端，用于跨渠道共享会话。
+- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。若两者都已配置，则先到期者生效。
+- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。
+- **`parentForkMaxTokens`**：创建 fork 线程会话时，父会话允许的最大 `totalTokens`（默认 `100000`）。
+ - 如果父会话的 `totalTokens` 高于该值，OpenClaw 会启动一个全新的线程会话，而不是继承父转录历史。
+ - 设为 `0` 可禁用该保护，并始终允许父会话 fork。
- **`mainKey`**：旧版字段。运行时始终对主私聊桶使用 `"main"`。
-- **`agentToAgent.maxPingPongTurns`**：智能体之间在 agent-to-agent 交换期间允许的最大往返回复轮数（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链式往返。
-- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 可作别名）、`keyPrefix` 或 `rawKeyPrefix` 进行匹配。首个 deny 规则优先。
+- **`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`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的产物/会话。
+ - `mode`：`warn` 仅发出警告；`enforce` 会实际执行清理。
+ - `pruneAfter`：陈旧条目的时间截止（默认 `30d`）。
+ - `maxEntries`：`sessions.json` 中条目的最大数量（默认 `500`）。
+ - `rotateBytes`：当 `sessions.json` 超过该大小时轮转（默认 `10mb`）。
+ - `resetArchiveRetention`：`*.reset.` 转录归档的保留时长。默认与 `pruneAfter` 相同；设为 `false` 可禁用。
+ - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的产物/会话。
- `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。
- **`threadBindings`**：线程绑定会话功能的全局默认值。
- `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`）
- - `idleHours`：默认按非活动时间自动取消聚焦的小时数（`0` 表示禁用；提供商可覆盖）
- - `maxAgeHours`：默认硬性最大存活小时数（`0` 表示禁用；提供商可覆盖）
+ - `idleHours`：默认的按无活动自动取消聚焦小时数（`0` 表示禁用；提供商可覆盖）
+ - `maxAgeHours`：默认的硬性最大时长小时数（`0` 表示禁用；提供商可覆盖）
@@ -2063,40 +2042,40 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
}
```
-### 响应前缀
+### 回复前缀
按渠道/账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。
-解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会推导为 `[{identity.name}]`。
+解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。
**模板变量：**
-| Variable | 说明 | 示例 |
-| ----------------- | ------------ | --------------------------- |
-| `{model}` | 简短模型名 | `claude-opus-4-6` |
-| `{modelFull}` | 完整模型标识 | `anthropic/claude-opus-4-6` |
-| `{provider}` | 提供商名称 | `anthropic` |
+| 变量 | 说明 | 示例 |
+| ----------------- | ---------------------- | --------------------------- |
+| `{model}` | 短模型名 | `claude-opus-4-6` |
+| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` |
+| `{provider}` | 提供商名称 | `anthropic` |
| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` |
-| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） |
+| `{identity.name}` | 智能体 identity 名称 | （与 `"auto"` 相同） |
变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。
-### 确认 reaction
+### 确认反应
-- 默认为当前活跃智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。
+- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。
- 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。
-- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退值。
+- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。
- 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。
-- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除确认 reaction。
-- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态 reaction。
- 在 Slack 和 Discord 上，未设置时，只要确认 reaction 处于启用状态，就会保持状态 reaction 启用。
- 在 Telegram 上，需要显式设为 `true` 才会启用生命周期状态 reaction。
+- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上于回复后移除确认反应。
+- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。
+ 在 Slack 和 Discord 上，未设置时，如果确认反应处于活动状态，则保持状态反应启用。
+ 在 Telegram 上，需要显式设为 `true` 才会启用生命周期状态反应。
### 入站防抖
-将同一发送者的快速连续纯文本消息批量合并为一次智能体轮次。媒体/附件会立即触发刷新。控制命令会绕过防抖。
+将来自同一发送者的快速纯文本消息合并为单个智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。
-### TTS（文本转语音）
+### TTS（text-to-speech）
```json5
{
@@ -2139,10 +2118,10 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示实际生效状态。
- `summaryModel` 会覆盖用于自动摘要的 `agents.defaults.model.primary`。
-- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需要主动启用）。
+- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需显式启用）。
- API key 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。
-- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为：配置、然后 `OPENAI_TTS_BASE_URL`、最后 `https://api.openai.com/v1`。
-- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型/语音校验。
+- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置项，其次 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。
+- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容 TTS 服务器，并放宽模型/语音校验。
---
@@ -2173,12 +2152,12 @@ Talk 模式的默认值（macOS/iOS/Android）。
```
- `talk.provider` 在配置了多个 Talk 提供商时，必须匹配 `talk.providers` 中的某个键。
-- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅为兼容性保留，并会自动迁移到 `talk.providers.`。
+- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.` 中。
- Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
- `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。
- 仅当未配置 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。
- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。
-- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久才发送 transcript。未设置时会保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。
+- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久再发送转录。未设置时保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。
---
@@ -2188,35 +2167,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` | 不做限制（与未设置相同） |
+| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` |
+| `full` | 无限制（与未设置相同） |
-### 工具分组
+### 工具组
-| 分组 | 工具 |
+| 组 | 工具 |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| `group:runtime` | `exec`、`process`、`code_execution`（接受 `bash` 作为 `exec` 的别名） |
-| `group:fs` | `read`、`write`、`edit`、`apply_patch` |
+| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） |
+| `group:fs` | `read`、`write`、`edit`、`apply_patch` |
| `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` |
-| `group:memory` | `memory_search`、`memory_get` |
-| `group:web` | `web_search`、`x_search`、`web_fetch` |
-| `group:ui` | `browser`、`canvas` |
-| `group:automation` | `cron`、`gateway` |
-| `group:messaging` | `message` |
-| `group:nodes` | `nodes` |
-| `group:agents` | `agents_list` |
-| `group:media` | `image`、`image_generate`、`video_generate`、`tts` |
-| `group:openclaw` | 所有内置工具（不包括 provider 插件） |
+| `group:memory` | `memory_search`、`memory_get` |
+| `group:web` | `web_search`、`x_search`、`web_fetch` |
+| `group:ui` | `browser`、`canvas` |
+| `group:automation` | `cron`、`gateway` |
+| `group:messaging` | `message` |
+| `group:nodes` | `nodes` |
+| `group:agents` | `agents_list` |
+| `group:media` | `image`、`image_generate`、`video_generate`、`tts` |
+| `group:openclaw` | 所有内置工具（不包含提供商插件） |
### `tools.allow` / `tools.deny`
-全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱已关闭，也会生效。
+全局工具允许/拒绝策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭也会应用。
```json5
{
@@ -2226,7 +2205,7 @@ Talk 模式的默认值（macOS/iOS/Android）。
### `tools.byProvider`
-进一步限制特定提供商或模型可用的工具。顺序：基础配置 → 提供商配置 → allow/deny。
+对特定提供商或模型进一步限制工具。顺序：基础配置 → 提供商配置 → allow/deny。
```json5
{
@@ -2259,8 +2238,8 @@ Talk 模式的默认值（macOS/iOS/Android）。
```
- 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。
-- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅应用于单条消息。
-- Elevated `exec` 会绕过沙箱隔离，并使用配置的逃逸路径（默认为 `gateway`，或者当 exec 目标是 `node` 时使用 `node`）。
+- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅作用于单条消息。
+- Elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，或当 exec 目标为 `node` 时使用 `node`）。
### `tools.exec`
@@ -2284,8 +2263,8 @@ Talk 模式的默认值（macOS/iOS/Android）。
### `tools.loopDetection`
-工具循环安全检查**默认关闭**。设置 `enabled: true` 以启用检测。
-设置可在全局 `tools.loopDetection` 中定义，并可按智能体在 `agents.list[].tools.loopDetection` 中覆盖。
+工具循环安全检查默认**禁用**。设置 `enabled: true` 可启用检测。
+设置可全局定义在 `tools.loopDetection` 中，并可在按智能体层级通过 `agents.list[].tools.loopDetection` 覆盖。
```json5
{
@@ -2307,12 +2286,12 @@ Talk 模式的默认值（macOS/iOS/Android）。
```
- `historySize`：为循环分析保留的最大工具调用历史数。
-- `warningThreshold`：对重复无进展模式发出警告的阈值。
+- `warningThreshold`：用于告警的重复无进展模式阈值。
- `criticalThreshold`：用于阻止严重循环的更高重复阈值。
-- `globalCircuitBreakerThreshold`：任何无进展运行的硬停止阈值。
-- `detectors.genericRepeat`：对重复的相同工具/相同参数调用发出警告。
-- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。
-- `detectors.pingPong`：对交替出现的无进展成对模式发出警告/阻止。
+- `globalCircuitBreakerThreshold`：任意无进展运行的硬停止阈值。
+- `detectors.genericRepeat`：对重复的同工具/同参数调用发出告警。
+- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展轮询发出告警/阻止。
+- `detectors.pingPong`：对交替出现的无进展成对模式发出告警/阻止。
- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证会失败。
### `tools.web`
@@ -2330,7 +2309,7 @@ Talk 模式的默认值（macOS/iOS/Android）。
},
fetch: {
enabled: true,
- provider: "firecrawl", // 可选；省略时自动检测
+ provider: "firecrawl", // 可选；省略则自动检测
maxChars: 50000,
maxCharsCap: 50000,
maxResponseBytes: 2000000,
@@ -2355,7 +2334,7 @@ Talk 模式的默认值（macOS/iOS/Android）。
media: {
concurrency: 2,
asyncCompletion: {
- directSend: false, // 需主动启用：将完成的异步音乐/视频直接发送到渠道
+ directSend: false, // 显式启用：将完成的异步音乐/视频直接发送到渠道
},
audio: {
enabled: true,
@@ -2403,8 +2382,8 @@ Talk 模式的默认值（macOS/iOS/Android）。
**异步完成字段：**
- `asyncCompletion.directSend`：为 `true` 时，已完成的异步 `music_generate`
- 和 `video_generate` 任务会先尝试直接投递到渠道。默认值：`false`
- （旧版请求方会话唤醒/模型投递路径）。
+ 和 `video_generate` 任务会优先尝试直接投递到渠道。默认：`false`
+ （旧版的请求方会话唤醒/模型投递路径）。
@@ -2423,9 +2402,9 @@ Talk 模式的默认值（macOS/iOS/Android）。
### `tools.sessions`
-控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可面向哪些会话。
+控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可以指向哪些会话。
-默认值：`tree`（当前会话 + 由其派生的会话，例如 subagents）。
+默认值：`tree`（当前会话 + 由其派生出的会话，例如子智能体）。
```json5
{
@@ -2441,10 +2420,10 @@ Talk 模式的默认值（macOS/iOS/Android）。
说明：
- `self`：仅当前会话键。
-- `tree`：当前会话 + 由当前会话派生的会话（subagents）。
-- `agent`：属于当前智能体 id 的任意会话（如果你在同一智能体 id 下运行按发送者区分的会话，可能包括其他用户）。
+- `tree`：当前会话 + 由当前会话派生出的会话（子智能体）。
+- `agent`：属于当前智能体 id 的任意会话（如果你在同一智能体 id 下运行按发送者隔离的会话，也可能包括其他用户）。
- `all`：任意会话。跨智能体定向仍需要 `tools.agentToAgent`。
-- 沙箱钳制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。
+- 沙箱隔离钳制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。
### `tools.sessions_spawn`
@@ -2455,8 +2434,8 @@ Talk 模式的默认值（macOS/iOS/Android）。
tools: {
sessions_spawn: {
attachments: {
- enabled: false, // 需主动启用：设为 true 以允许内联文件附件
- maxTotalBytes: 5242880, // 所有文件合计 5 MB
+ enabled: false, // 显式启用：设为 true 以允许内联文件附件
+ maxTotalBytes: 5242880, // 所有文件总计 5 MB
maxFiles: 50,
maxFileBytes: 1048576, // 每个文件 1 MB
retainOnSessionKeep: false, // 当 cleanup="keep" 时保留附件
@@ -2468,16 +2447,16 @@ Talk 模式的默认值（macOS/iOS/Android）。
说明：
-- 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝它们。
-- 文件会实体化到子工作区中的 `.openclaw/attachments//`，并附带一个 `.manifest.json`。
-- 附件内容会自动从 transcript 持久化中脱敏。
-- Base64 输入会进行严格的字母表/填充校验，以及解码前大小保护检查。
+- 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。
+- 文件会以 `.manifest.json` 的形式实体化到子工作区中的 `.openclaw/attachments//`。
+- 附件内容会自动从转录持久化中脱敏。
+- Base64 输入会执行严格的字母表/填充校验以及解码前大小保护。
- 目录权限为 `0700`，文件权限为 `0600`。
-- 清理由 `cleanup` 策略控制：`delete` 始终删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。
+- 清理遵循 `cleanup` 策略：`delete` 总会移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留附件。
### `tools.experimental`
-实验性内置工具标志。默认关闭，除非严格智能体式 GPT-5 自动启用规则生效。
+实验性内置工具开关。默认关闭，除非触发 strict-agentic GPT-5 自动启用规则。
```json5
{
@@ -2491,9 +2470,9 @@ Talk 模式的默认值（macOS/iOS/Android）。
说明：
-- `planTool`：为非琐碎的多步骤工作跟踪启用结构化 `update_plan` 工具。
-- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或按智能体覆盖）对 OpenAI 或 OpenAI Codex GPT-5 系列运行设置为 `"strict-agentic"`。设为 `true` 可在该范围之外强制开启该工具；设为 `false` 则即使在 strict-agentic GPT-5 运行中也保持关闭。
-- 启用后，系统提示词也会添加使用指导，使模型仅在重要工作中使用它，并且最多只保留一个 `in_progress` 步骤。
+- `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。
+- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或按智能体覆盖）被设为 OpenAI 或 OpenAI Codex GPT-5 系列运行的 `"strict-agentic"`。设置为 `true` 可在该范围之外强制启用该工具，设置为 `false` 则即使在 strict-agentic GPT-5 运行中也保持关闭。
+- 启用后，system prompt 还会添加使用指引，以便模型仅在实质性工作中使用它，并始终最多只保留一个 `in_progress` 步骤。
### `agents.defaults.subagents`
@@ -2513,16 +2492,16 @@ Talk 模式的默认值（macOS/iOS/Android）。
}
```
-- `model`：派生 subagents 的默认模型。若省略，subagents 会继承调用方的模型。
+- `model`：派生子智能体的默认模型。如果省略，子智能体会继承调用方模型。
- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 目标智能体 id 的默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。
- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时时间（秒）。`0` 表示无超时。
-- 按 subagent 区分的工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。
+- 按子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。
---
## 自定义提供商和 base URL
-OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。
+OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。
```json5
{
@@ -2551,45 +2530,45 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或
}
```
-- 使用 `authHeader: true` + `headers` 以满足自定义认证需求。
+- 使用 `authHeader: true` + `headers` 满足自定义认证需求。
- 使用 `OPENCLAW_AGENT_DIR` 覆盖智能体配置根目录（或使用旧版环境变量别名 `PI_CODING_AGENT_DIR`）。
-- 对于匹配的提供商 id，合并优先级如下：
+- 对于匹配的 provider ID，合并优先级如下：
- 非空的智能体 `models.json` `baseUrl` 值优先。
- 非空的智能体 `apiKey` 值仅在该提供商在当前配置/auth-profile 上下文中不是 SecretRef 管理时优先。
- - 由 SecretRef 管理的提供商 `apiKey` 值会根据来源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化解析后的 secret。
- - 由 SecretRef 管理的提供商 header 值会根据来源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。
- - 空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。
- - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值和隐式目录值之间取较高者。
- - 匹配模型的 `contextTokens` 会在存在显式运行时上限时保留它；用它可以限制有效上下文，而不改变原生模型元数据。
+ - 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。
+ - 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。
+ - 空值或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。
+ - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值和隐式目录值之间取更高值。
+ - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；可用它限制有效上下文，而不改变原生模型元数据。
- 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。
- - 标记持久化以来源为权威：标记写入自当前来源配置快照（解析前），而不是解析后的运行时 secret 值。
+ - 标记持久化以源为准：标记是根据活动源配置快照（解析前）写入的，而不是根据已解析的运行时密钥值写入的。
### 提供商字段详情
- `models.mode`：提供商目录行为（`merge` 或 `replace`）。
-- `models.providers`：以提供商 id 为键的自定义提供商映射。
+- `models.providers`：以 provider 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.*.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。
+- `models.providers.*.headers`：用于代理/租户路由的额外静态 header。
+- `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖。
+ - `request.headers`：额外 header（与提供商默认值合并）。值可接受 SecretRef。
- `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`，可选 `prefix`）。
- `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。
- - `request.tls`：直连时的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（均接受 SecretRef）、`serverName`、`insecureSkipVerify`。
- - `request.allowPrivateNetwork`：为 `true` 时，当 DNS 解析到私有网段、CGNAT 或类似范围时，允许通过提供商 HTTP 抓取保护访问 `baseUrl` 的 HTTPS（供 operator 主动启用，用于受信任的自托管 OpenAI 兼容端点）。WebSocket 会对 headers/TLS 使用相同的 `request`，但不使用该抓取 SSRF 防护。默认值 `false`。
+ - `request.tls`：直连的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（都接受 SecretRef）、`serverName`、`insecureSkipVerify`。
+ - `request.allowPrivateNetwork`：为 `true` 时，当 DNS 解析到私有、CGNAT 或类似网段时，允许通过提供商 HTTP fetch 保护访问 `baseUrl` 的 HTTPS（这是针对受信任、自托管 OpenAI 兼容端点的 operator 显式启用项）。WebSocket 对 header/TLS 使用相同的 `request`，但不经过该 fetch SSRF 保护。默认值为 `false`。
- `models.providers.*.models`：显式提供商模型目录条目。
- `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。
-- `models.providers.*.models.*.contextTokens`：可选运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用。
-- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 为非空、非原生值（主机不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空的/省略的 `baseUrl` 会保留默认 OpenAI 行为。
-- `models.providers.*.models.*.compat.requiresStringContent`：用于仅支持字符串内容的 OpenAI 兼容聊天端点的可选兼容性提示。为 `true` 时，OpenClaw 会在发送请求前，将纯文本的 `messages[].content` 数组压平成普通字符串。
-- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根节点。
+- `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用它。
+- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且使用非空、非原生 `baseUrl`（host 不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空的/省略的 `baseUrl` 会保留默认 OpenAI 行为。
+- `models.providers.*.models.*.compat.requiresStringContent`：面向仅支持字符串内容的 OpenAI 兼容聊天端点的可选兼容性提示。为 `true` 时，OpenClaw 会在发送请求前把纯文本 `messages[].content` 数组扁平化为普通字符串。
+- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根路径。
- `plugins.entries.amazon-bedrock.config.discovery.enabled`：开启/关闭隐式发现。
- `plugins.entries.amazon-bedrock.config.discovery.region`：用于发现的 AWS 区域。
-- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用于定向发现的可选 provider-id 过滤器。
+- `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 数。
@@ -2608,8 +2587,8 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或
fallbacks: ["cerebras/zai-glm-4.6"],
},
models: {
- "cerebras/zai-glm-4.7": { alias: "GLM 4.7（Cerebras）" },
- "cerebras/zai-glm-4.6": { alias: "GLM 4.6（Cerebras）" },
+ "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
+ "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (Cerebras)" },
},
},
},
@@ -2621,8 +2600,8 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或
apiKey: "${CEREBRAS_API_KEY}",
api: "openai-completions",
models: [
- { id: "zai-glm-4.7", name: "GLM 4.7（Cerebras）" },
- { id: "zai-glm-4.6", name: "GLM 4.6（Cerebras）" },
+ { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },
+ { id: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" },
],
},
},
@@ -2707,11 +2686,11 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7`
}
```
-中国区端点请使用：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。
+中国端点请使用：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。
原生 Moonshot 端点会在共享的
-`openai-completions` 传输上声明流式使用兼容性，而 OpenClaw 会根据端点能力
-而不仅仅是内置提供商 id 来判断这一点。
+`openai-completions` 传输上声明流式使用兼容性，OpenClaw 会根据端点能力
+而不只是内置 provider id 来决定相关行为。
@@ -2768,7 +2747,7 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7`
}
```
-Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。
+Base URL 不应包含 `/v1`（Anthropic 客户端会自动追加它）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。
@@ -2812,16 +2791,15 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
`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` 重写为
+在兼容 Anthropic 的流式路径上，除非你显式设置 `thinking`，否则 OpenClaw 默认禁用 MiniMax thinking。
+`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为
`MiniMax-M2.7-highspeed`。
-参见 [本地模型](/zh-CN/gateway/local-models)。简而言之：在配置较强的硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。
+参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在较强硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。
@@ -2853,12 +2831,11 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
```
- `allowBundled`：仅针对内置 Skills 的可选允许列表（托管/工作区 Skills 不受影响）。
-- `load.extraDirs`：额外的共享 Skills 根目录（优先级最低）。
-- `install.preferBrew`：为 true 时，如果存在 `brew`，则优先使用 Homebrew 安装器，然后才回退到其他安装器类型。
-- `install.nodeManager`：用于 `metadata.openclaw.install`
- 规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。
-- `entries..enabled: false`：即使某个 skill 已内置/已安装，也会禁用它。
-- `entries..apiKey`：为声明主环境变量的 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`：为声明主环境变量的 skill 提供的便捷字段（明文字符串或 SecretRef 对象）。
---
@@ -2887,46 +2864,46 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
```
- 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。
-- 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex bundles 和 Claude bundles，包括无 manifest 的 Claude 默认布局 bundles。
+- 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括没有 manifest 的 Claude 默认布局 bundle。
- **配置变更需要重启 Gateway 网关。**
- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。
-- `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`：显式信任该插件可以为后台 subagent 运行请求按次覆盖 `provider` 和 `model`。
-- `plugins.entries..subagent.allowedModels`：受信任 subagent 覆盖可使用的规范 `provider/model` 目标的可选允许列表。仅当你确实希望允许任意模型时才使用 `"*"`。
-- `plugins.entries..config`：插件定义的配置对象（如果有，则按原生 OpenClaw 插件 schema 验证）。
-- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch 提供商设置。
+- `plugins.entries..apiKey`：插件级 API key 便捷字段（插件支持时可用）。
+- `plugins.entries..env`：插件作用域环境变量映射。
+- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改 prompt 的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hook 和受支持 bundle 提供的 hook 目录。
+- `plugins.entries..subagent.allowModelOverride`：显式信任该插件，以便它可为后台子智能体运行请求按次的 `provider` 和 `model` 覆盖。
+- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖允许的规范 `provider/model` 目标可选允许列表。仅当你确实希望允许任意模型时才使用 `"*"`。
+- `plugins.entries..config`：插件定义的配置对象（当原生 OpenClaw 插件 schema 可用时会进行验证）。
+- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web fetch 提供商设置。
- `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。
- `baseUrl`：Firecrawl API base URL（默认：`https://api.firecrawl.dev`）。
- `onlyMainContent`：仅提取页面主体内容（默认：`true`）。
- - `maxAgeMs`：最大缓存年龄（毫秒）（默认：`172800000` / 2 天）。
- - `timeoutSeconds`：抓取请求超时时间（秒）（默认：`60`）。
+ - `maxAgeMs`：最大缓存时长（毫秒，默认：`172800000` / 2 天）。
+ - `timeoutSeconds`：抓取请求超时时间（秒，默认：`60`）。
- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。
- `enabled`：启用 X Search 提供商。
- - `model`：搜索使用的 Grok 模型（例如 `"grok-4-1-fast"`）。
-- `plugins.entries.memory-core.config.dreaming`：memory dreaming 设置。有关阶段和阈值，请参见 [Dreaming](/zh-CN/concepts/dreaming)。
- - `enabled`：dreaming 主开关（默认 `false`）。
+ - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。
+- `plugins.entries.memory-core.config.dreaming`：memory dreaming 设置。关于阶段和阈值，请参见 [Dreaming](/zh-CN/concepts/dreaming)。
+ - `enabled`：dreaming 总开关（默认 `false`）。
- `frequency`：每次完整 dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。
- 阶段策略和阈值属于实现细节（不是面向用户的配置键）。
-- 完整的 memory 配置位于 [Memory configuration reference](/zh-CN/reference/memory-config)：
+- 完整 memory 配置位于 [Memory configuration reference](/zh-CN/reference/memory-config)：
- `agents.defaults.memorySearch.*`
- `memory.backend`
- `memory.citations`
- `memory.qmd.*`
- `plugins.entries.memory-core.config.dreaming`
-- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为已清洗的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。
-- `plugins.slots.memory`：选择当前激活的 memory 插件 id，或设为 `"none"` 以禁用 memory 插件。
-- `plugins.slots.contextEngine`：选择当前激活的上下文引擎插件 id；默认是 `"legacy"`，除非你安装并选择了其他引擎。
+- 已启用的 Claude bundle 插件也可以通过 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将它们作为已净化的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。
+- `plugins.slots.memory`：选择活动 memory 插件 id，或设为 `"none"` 以禁用 memory 插件。
+- `plugins.slots.contextEngine`：选择活动 context engine 插件 id；默认值为 `"legacy"`，除非你安装并选择了其他 engine。
- `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。
- - 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。
+ - 包含 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。
- 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。
参见 [Plugins](/zh-CN/tools/plugin)。
---
-## 浏览器
+## Browser
```json5
{
@@ -2935,7 +2912,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
evaluateEnabled: true,
defaultProfile: "user",
ssrfPolicy: {
- // dangerouslyAllowPrivateNetwork: true, // 仅对受信任的私有网络访问主动启用
+ // dangerouslyAllowPrivateNetwork: true, // 仅在信任私有网络访问时显式启用
// allowPrivateNetwork: true, // 旧版别名
// hostnameAllowlist: ["*.example.com", "example.com"],
// allowedHostnames: ["localhost"],
@@ -2963,29 +2940,21 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
```
- `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。
-- 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 为禁用状态，因此浏览器导航默认保持严格模式。
-- 仅当你明确愿意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。
-- 在严格模式下，远程 CDP 配置端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的私有网络阻止策略约束。
+- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用状态，因此默认情况下 browser 导航保持严格模式。
+- 仅当你明确信任私有网络 browser 导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。
+- 在严格模式下，远程 CDP 配置端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的私有网络阻止。
- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。
-- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 来设置显式例外。
+- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 配置显式例外。
- 远程配置是仅附加模式（禁用 start/stop/reset）。
- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。
- 当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)；
- 当你的提供商直接给出 DevTools WebSocket URL 时使用 WS(S)。
-- `existing-session` 配置使用 Chrome MCP 而不是 CDP，并且可以附加到
- 所选主机，或通过已连接的浏览器节点附加。
-- `existing-session` 配置可以设置 `userDataDir`，以定位特定的
- Chromium 系浏览器配置，例如 Brave 或 Edge。
-- `existing-session` 配置保留当前 Chrome MCP 路由限制：
- 使用 snapshot/ref 驱动的操作而不是 CSS selector 定位、单文件上传
- hooks、无对话框超时覆盖、无 `wait --load networkidle`，以及无
- `responsebody`、PDF 导出、下载拦截或批量操作。
-- 本地托管的 `openclaw` 配置会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下
- 才显式设置 `cdpUrl`。
+ 当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)；当提供商直接给出 DevTools WebSocket URL 时，使用 WS(S)。
+- `existing-session` 配置使用 Chrome MCP 而不是 CDP，并且可以附加到所选主机上，或通过已连接的 browser node 进行附加。
+- `existing-session` 配置可以设置 `userDataDir`，以指向特定的 Chromium 系浏览器配置，例如 Brave 或 Edge。
+- `existing-session` 配置保留当前 Chrome MCP 路由限制：基于快照/引用驱动的操作，而不是 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`、窗口大小设置或调试标志）。
+- 控制服务：仅限 loopback（端口从 `gateway.port` 派生，默认 `18791`）。
+- `extraArgs` 会向本地 Chromium 启动追加额外启动参数（例如 `--disable-gpu`、窗口大小参数或调试参数）。
---
@@ -2997,14 +2966,14 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
seamColor: "#FF4500",
assistant: {
name: "OpenClaw",
- avatar: "CB", // emoji、短文本、图片 URL 或 data URI
+ avatar: "CB", // emoji、短文本、图像 URL 或 data URI
},
},
}
```
-- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡着色等）。
-- `assistant`：Control UI 身份覆盖。会回退到当前激活的智能体身份。
+- `seamColor`：原生应用 UI 外观的强调色（Talk Mode 气泡着色等）。
+- `assistant`：Control UI identity 覆盖。会回退到活动智能体 identity。
---
@@ -3040,7 +3009,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
// embedSandbox: "scripts", // strict | scripts | trusted
// allowExternalEmbedUrls: false, // 危险：允许绝对外部 http(s) 嵌入 URL
// allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必填
- // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host-header origin 回退模式
+ // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host header origin 回退模式
// allowInsecureAuth: false,
// dangerouslyDisableDeviceAuth: false,
},
@@ -3054,7 +3023,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
// 可选。默认 false。
allowRealIpFallback: false,
tools: {
- // 附加的 /tools/invoke HTTP deny
+ // 额外的 /tools/invoke HTTP deny
deny: ["browser"],
// 从默认 HTTP deny 列表中移除工具
allow: ["gateway"],
@@ -3073,45 +3042,45 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
-- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。
+- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。只有在 `local` 模式下，Gateway 网关才允许启动。
- `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。
- `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。
- **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用 host 别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。
-- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。在 Docker bridge 网络（`-p 18789:18789`）下，流量会到达 `eth0`，因此 Gateway 网关无法访问。请使用 `--network host`，或者设置 `bind: "lan"`（或 `bind: "custom"` 并设置 `customBindHost: "0.0.0.0"`）以在所有接口上监听。
-- **认证**：默认要求认证。非 loopback bind 必须启用 Gateway 网关认证。实际使用中，这意味着需要共享 token/password，或使用设置了 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成一个 token。
-- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），则必须显式设置 `gateway.auth.mode` 为 `token` 或 `password`。当两者都已配置但未设置 mode 时，启动以及服务安装/修复流程都会失败。
-- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的 local loopback 环境；新手引导提示不会提供此选项。
-- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份 headers（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 的代理来源；同主机 loopback 反向代理不满足 trusted-proxy 认证要求。
-- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份 headers 可满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale header 认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。该无 token 流程假定 Gateway 网关主机是受信任的。当 `tailscale.mode = "serve"` 时，默认值为 `true`。
-- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域生效（共享密钥与设备 token 分别跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。
- - 在异步 Tailscale Serve Control UI 路径上，相同 `{scope, clientIp}` 的失败尝试会在写入失败状态前进行串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限流，而不是两个都以普通不匹配形式同时通过。
- - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；当你有意希望连 localhost 流量也受限流约束时（用于测试环境或严格代理部署），请设为 `false`。
-- 来自浏览器源的 WS 认证尝试始终会启用限流，且关闭 loopback 豁免（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。
-- 在 loopback 上，这些来自浏览器源的锁定会按规范化后的 `Origin`
- 值隔离，因此来自某个 localhost origin 的重复失败不会自动
- 锁定另一个 origin。
+- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会从 `eth0` 进入，因此 Gateway 网关将无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或设置 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以监听所有接口。
+- **认证**：默认要求开启。非 loopback bind 需要 Gateway 网关认证。实际这意味着需要共享 token/password，或使用设置了 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成 token。
+- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式设置 `gateway.auth.mode` 为 `token` 或 `password`。如果两者都已配置但 mode 未设置，启动以及服务安装/修复流程都会失败。
+- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 设置；新手引导提示中不会提供此选项，这是有意设计。
+- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份 header（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 代理来源；同主机 loopback 反向代理不满足 trusted-proxy 认证条件。
+- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份 header 可以满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale header 认证；它们仍遵循 Gateway 网关正常的 HTTP 认证模式。这种无 token 流程假定 Gateway 网关主机是受信任的。当 `tailscale.mode = "serve"` 时，默认值为 `true`。
+- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域应用（共享密钥和设备 token 会分别跟踪）。被阻止的尝试返回 `429` + `Retry-After`。
+ - 在异步 Tailscale Serve Control UI 路径上，同一个 `{scope, clientIp}` 的失败尝试会在写入失败记录之前串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限流，而不是两个请求都以普通不匹配形式同时穿过。
+ - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；如果你希望 localhost 流量也被限流（例如测试环境或严格代理部署），请设置为 `false`。
+- 来自浏览器来源的 WS 认证尝试始终会启用限流，并禁用 loopback 豁免（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。
+- 在 loopback 上，这些来自浏览器来源的锁定会按规范化后的 `Origin`
+ 值分别隔离，因此某个 localhost origin 的重复失败
+ 不会自动锁定另一个 origin。
- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公网，需要认证）。
-- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器 origin 允许列表。当预期浏览器客户端来自非 loopback origin 时必须设置。
-- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，启用基于 Host header 的 origin 回退，适用于有意依赖 Host header origin 策略的部署。
+- `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当预期有来自非 loopback 来源的浏览器客户端时，此项为必填。
+- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，启用 Host header origin 回退，用于那些有意依赖 Host header origin 策略的部署。
- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。
-- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧紧急破例开关，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍仅允许 loopback 使用明文。
-- `gateway.remote.token` / `.password`：远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。
-- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在向 Gateway 网关发布基于 relay 的注册后，供其使用的外部 APNs relay 基础 HTTPS URL。该 URL 必须与编译进 iOS 构建的 relay URL 一致。
-- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间（毫秒）。默认值为 `10000`。
-- 基于 relay 的注册会委托给某个特定 Gateway 网关身份。配对后的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并向 Gateway 网关转发一个基于注册范围的发送授权。其他 Gateway 网关不能复用该已存储注册。
-- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：对上述 relay 配置的临时环境变量覆盖。
-- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发环境的破例开关，允许 loopback HTTP relay URL。生产 relay URL 应保持为 HTTPS。
-- `gateway.channelHealthCheckMinutes`：渠道健康监视器间隔（分钟）。设为 `0` 可全局禁用健康监视器重启。默认值：`5`。
-- `gateway.channelStaleEventThresholdMinutes`：过期 socket 阈值（分钟）。应保持大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。
-- `gateway.channelMaxRestartsPerHour`：滚动一小时内，每个渠道/账号允许的最大健康监视器重启次数。默认值：`10`。
-- `channels..healthMonitor.enabled`：在保持全局监视器启用的同时，按渠道选择退出健康监视器重启。
-- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。设置后优先于渠道级覆盖。
-- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可使用 `gateway.remote.*` 作为回退。
-- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但未能解析，则解析会以封闭失败方式处理（不会使用远程回退来掩盖问题）。
-- `trustedProxies`：会终止 TLS 或注入转发客户端 headers 的反向代理 IP。仅列出你控制的代理。loopback 条目对于同主机代理/本地检测场景仍然有效（例如 Tailscale Serve 或本地反向代理），但它们**不会**使 loopback 请求有资格使用 `gateway.auth.mode: "trusted-proxy"`。
-- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以保持封闭失败行为。
-- `gateway.tools.deny`：通过 HTTP `POST /tools/invoke` 额外阻止的工具名称（在默认 deny 列表基础上扩展）。
-- `gateway.tools.allow`：从默认 HTTP deny 列表中移除工具名称。
+- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧的破窗开关覆盖，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍然只有 loopback 允许明文。
+- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。
+- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在将基于 relay 的注册发布到 Gateway 网关后，供其使用的外部 APNs relay 基础 HTTPS URL。该 URL 必须与编译进 iOS 构建中的 relay URL 匹配。
+- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时（毫秒）。默认值为 `10000`。
+- 基于 relay 的注册会委托给特定的 Gateway 网关 identity。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该 identity，并将作用于该注册的发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用该已存储的注册。
+- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述 relay 配置的临时环境变量覆盖。
+- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发环境的逃生开关，允许 loopback HTTP relay URL。生产环境 relay URL 应保持使用 HTTPS。
+- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设为 `0` 可全局禁用健康监控重启。默认值：`5`。
+- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。
+- `gateway.channelMaxRestartsPerHour`：每个渠道/账号在滚动一小时内允许的最大健康监控重启次数。默认值：`10`。
+- `channels..healthMonitor.enabled`：按渠道选择退出健康监控重启，同时保留全局监控开启。
+- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。设置后，其优先级高于渠道级覆盖。
+- 本地 Gateway 网关调用路径仅会在 `gateway.auth.*` 未设置时，将 `gateway.remote.*` 作为回退。
+- 如果 `gateway.auth.token` / `gateway.auth.password` 是通过 SecretRef 显式配置但未解析成功，则解析会以失败关闭方式处理（不会被远程回退所掩盖）。
+- `trustedProxies`：终止 TLS 或注入转发客户端 header 的反向代理 IP。只列出你控制的代理。loopback 条目对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**使 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的资格。
+- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以实现失败关闭行为。
+- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名（扩展默认 deny 列表）。
+- `gateway.tools.allow`：从默认 HTTP deny 列表中移除工具名。
@@ -3123,14 +3092,14 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方
- `gateway.http.endpoints.responses.maxUrlParts`
- `gateway.http.endpoints.responses.files.urlAllowlist`
- `gateway.http.endpoints.responses.images.urlAllowlist`
- 空的 allowlist 会被视为未设置；使用 `gateway.http.endpoints.responses.files.allowUrl=false`
- 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 抓取。
-- 可选响应加固 header：
- - `gateway.http.securityHeaders.strictTransportSecurity`（仅为你控制的 HTTPS origin 设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)）
+ 空允许列表会被视为未设置；如需禁用 URL 抓取，请使用 `gateway.http.endpoints.responses.files.allowUrl=false`
+ 和/或 `gateway.http.endpoints.responses.images.allowUrl=false`。
+- 可选的响应加固 header：
+ - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 来源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)）
### 多实例隔离
-在同一主机上运行多个 Gateway 网关，需使用唯一端口和状态目录：
+在同一主机上运行多个 Gateway 网关，并使用不同的端口和状态目录：
```bash
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
@@ -3138,7 +3107,7 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001
```
-便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile `（使用 `~/.openclaw-`）。
+便捷参数：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile `（使用 `~/.openclaw-`）。
参见 [Multiple Gateways](/zh-CN/gateway/multiple-gateways)。
@@ -3159,10 +3128,10 @@ openclaw gateway --port 19001
```
- `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS/WSS）（默认：`false`）。
-- `autoGenerate`：在未配置显式文件时自动生成本地自签名 cert/key 对；仅供本地/开发使用。
+- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书/密钥对；仅用于本地/开发环境。
- `certPath`：TLS 证书文件的文件系统路径。
-- `keyPath`：TLS 私钥文件的文件系统路径；应限制权限。
-- `caPath`：用于客户端验证或自定义信任链的可选 CA bundle 路径。
+- `keyPath`：TLS 私钥文件的文件系统路径；请限制其访问权限。
+- `caPath`：可选的 CA bundle 路径，用于客户端验证或自定义信任链。
### `gateway.reload`
@@ -3180,11 +3149,11 @@ openclaw gateway --port 19001
- `mode`：控制配置编辑在运行时如何应用。
- `"off"`：忽略实时编辑；更改需要显式重启。
- - `"restart"`：配置变更时始终重启 Gateway 网关进程。
- - `"hot"`：进程内应用更改而不重启。
- - `"hybrid"`（默认）：先尝试热重载；必要时回退到重启。
-- `debounceMs`：应用配置更改前的防抖窗口（毫秒）（非负整数）。
-- `deferralTimeoutMs`：在强制重启前等待进行中操作的最长时间（毫秒）（默认：`300000` = 5 分钟）。
+ - `"restart"`：配置更改时始终重启 Gateway 网关进程。
+ - `"hot"`：在不重启的情况下于进程内应用更改。
+ - `"hybrid"`（默认）：先尝试热重载；如有需要则回退到重启。
+- `debounceMs`：在应用配置更改前的防抖窗口（毫秒，非负整数）。
+- `deferralTimeoutMs`：在强制重启前等待进行中操作完成的最长时间（毫秒，默认：`300000` = 5 分钟）。
---
@@ -3198,8 +3167,8 @@ openclaw gateway --port 19001
path: "/hooks",
maxBodyBytes: 262144,
defaultSessionKey: "hook:ingress",
- allowRequestSessionKey: false,
- allowedSessionKeyPrefixes: ["hook:"],
+ allowRequestSessionKey: true,
+ allowedSessionKeyPrefixes: ["hook:", "hook:gmail:"],
allowedAgentIds: ["hooks", "main"],
presets: ["gmail"],
transformsDir: "~/.openclaw/hooks/transforms",
@@ -3222,41 +3191,47 @@ openclaw gateway --port 19001
```
认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。
-拒绝使用查询字符串形式的 hook token。
+查询字符串中的 hook token 会被拒绝。
-验证与安全说明：
+验证和安全说明：
-- `hooks.enabled=true` 要求 `hooks.token` 为非空。
-- `hooks.token` 必须与 `gateway.auth.token` **不同**；重复使用 Gateway 网关 token 会被拒绝。
+- `hooks.enabled=true` 要求 `hooks.token` 为非空值。
+- `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关 token 会被拒绝。
- `hooks.path` 不能是 `/`；请使用专用子路径，例如 `/hooks`。
- 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。
+- 如果某个映射或 preset 使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 并将 `hooks.allowRequestSessionKey=true`。静态映射键不需要此显式启用项。
**端点：**
- `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
- `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }`
- - 仅当 `hooks.allowRequestSessionKey=true`（默认：`false`）时，才接受请求负载中的 `sessionKey`。
+ - 请求负载中的 `sessionKey` 仅在 `hooks.allowRequestSessionKey=true`（默认：`false`）时接受。
- `POST /hooks/` → 通过 `hooks.mappings` 解析
+ - 模板渲染后的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。
- `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。
- `match.source` 匹配通用路径中的某个负载字段。
-- 类似 `{{messages[0].subject}}` 的模板会从负载中读取值。
+- `{{messages[0].subject}}` 这类模板会从负载中读取。
- `transform` 可以指向一个返回 hook action 的 JS/TS 模块。
- - `transform.module` 必须是相对路径，并且必须位于 `hooks.transformsDir` 内（绝对路径和路径穿越都会被拒绝）。
-- `agentId` 会路由到特定智能体；未知 id 会回退到默认值。
+ - `transform.module` 必须是相对路径，并且保持在 `hooks.transformsDir` 内部（绝对路径和路径穿越会被拒绝）。
+- `agentId` 会路由到特定智能体；未知 ID 会回退到默认智能体。
- `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。
-- `defaultSessionKey`：用于未显式设置 `sessionKey` 的 hook 智能体运行的可选固定会话键。
-- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方设置 `sessionKey`（默认：`false`）。
-- `allowedSessionKeyPrefixes`：用于显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。
-- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认是 `last`。
-- `model` 会覆盖本次 hook 运行使用的 LLM（如果设置了模型目录，则该模型必须被允许）。
+- `defaultSessionKey`：对未显式提供 `sessionKey` 的 hook 智能体运行使用的可选固定会话键。
+- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方和模板驱动的映射会话键设置 `sessionKey`（默认：`false`）。
+- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任意映射或 preset 使用模板化 `sessionKey` 时，它会变为必需项。
+- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认值为 `last`。
+- `model` 会覆盖本次 hook 运行使用的 LLM（如果设置了模型目录，则必须在允许范围内）。
### Gmail 集成
+- 内置 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。
+- 如果你保留这种按消息路由方式，请设置 `hooks.allowRequestSessionKey: true`，并约束 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。
+- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖 preset，而不要使用模板化默认值。
+
```json5
{
hooks: {
@@ -3278,8 +3253,8 @@ openclaw gateway --port 19001
}
```
-- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。
-- 不要在 Gateway 网关旁边单独运行 `gog gmail watch serve`。
+- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。如需禁用，请设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1`。
+- 不要在 Gateway 网关之外再单独运行 `gog gmail watch serve`。
---
@@ -3298,15 +3273,15 @@ openclaw gateway --port 19001
- 通过 Gateway 网关端口下的 HTTP 提供智能体可编辑的 HTML/CSS/JS 和 A2UI：
- `http://:/__openclaw__/canvas/`
- `http://:/__openclaw__/a2ui/`
-- 仅限本地：保持 `gateway.bind: "loopback"`（默认）。
-- 非 loopback 绑定：canvas 路由与其他 Gateway 网关 HTTP 入口一样，需要 Gateway 网关认证（token/password/trusted-proxy）。
-- 节点 WebView 通常不会发送认证 headers；节点配对并连接后，Gateway 网关会为 canvas/A2UI 访问发布节点作用域能力 URL。
-- 能力 URL 绑定到当前活跃的节点 WS 会话，并且很快过期。不使用基于 IP 的回退。
+- 仅本地：保持 `gateway.bind: "loopback"`（默认）。
+- 非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP 面一样，需要 Gateway 网关认证（token/password/trusted-proxy）。
+- Node WebViews 通常不会发送认证 header；当 node 已配对并连接后，Gateway 网关会为 canvas/A2UI 访问公布 node 作用域的 capability URL。
+- Capability URL 绑定到活动中的 node WS 会话，并且过期很快。不会使用基于 IP 的回退。
- 会向提供的 HTML 中注入 live-reload 客户端。
-- 为空时会自动创建起始 `index.html`。
-- 也会在 `/__openclaw__/a2ui/` 提供 A2UI。
-- 更改需要重启 Gateway 网关。
-- 对于大型目录或出现 `EMFILE` 错误时，请禁用 live reload。
+- 空目录时会自动创建起始 `index.html`。
+- 同时也会在 `/__openclaw__/a2ui/` 提供 A2UI。
+- 变更需要重启 Gateway 网关。
+- 对于大型目录或 `EMFILE` 错误，请禁用 live reload。
---
@@ -3324,9 +3299,9 @@ openclaw gateway --port 19001
}
```
-- `minimal`（默认）：从 TXT 记录中省略 `cliPath` + `sshPort`。
+- `minimal`（默认）：在 TXT 记录中省略 `cliPath` + `sshPort`。
- `full`：包含 `cliPath` + `sshPort`。
-- 主机名默认为 `openclaw`。使用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。
+- hostname 默认为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。
### 广域网（DNS-SD）
@@ -3338,7 +3313,7 @@ openclaw gateway --port 19001
}
```
-会在 `~/.openclaw/dns/` 下写入一个单播 DNS-SD 区域。对于跨网络设备发现，请配合 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。
+会在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。若要进行跨网络设备发现，请配合 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。
设置：`openclaw dns setup --apply`。
@@ -3363,14 +3338,14 @@ openclaw gateway --port 19001
}
```
-- 仅当进程环境中缺少该键时，才会应用内联环境变量。
-- `.env` 文件：当前工作目录 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。
+- 仅当进程环境中缺少对应键时，才会应用内联环境变量。
+- `.env` 文件：当前工作目录下的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。
- `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。
- 完整优先级请参见 [Environment](/zh-CN/help/environment)。
### 环境变量替换
-可在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量：
+可在任意配置字符串中通过 `${VAR_NAME}` 引用环境变量：
```json5
{
@@ -3381,15 +3356,15 @@ openclaw gateway --port 19001
```
- 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。
-- 缺失/空变量会在加载配置时报错。
-- 使用 `$${VAR}` 转义为字面量 `${VAR}`。
-- 可与 `$include` 一起使用。
+- 缺失/空值变量会在加载配置时抛出错误。
+- 使用 `$${VAR}` 可转义为字面量 `${VAR}`。
+- 适用于 `$include`。
---
## Secrets
-Secret ref 是增量支持的：明文值仍然可用。
+SecretRef 是增量特性：明文值仍然可用。
### `SecretRef`
@@ -3405,13 +3380,13 @@ Secret ref 是增量支持的：明文值仍然可用。
- `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$`
- `source: "file"` 的 id：绝对 JSON pointer（例如 `"/providers/openai/apiKey"`）
- `source: "exec"` 的 id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
-- `source: "exec"` 的 id 不能包含 `.` 或 `..` 形式的斜杠分隔路径段（例如 `a/../b` 会被拒绝）
+- `source: "exec"` 的 id 不得包含 `.` 或 `..` 这类以斜杠分隔的路径段（例如 `a/../b` 会被拒绝）
-### 支持的凭证入口
+### 支持的凭证面
-- 规范矩阵： [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface)
-- `secrets apply` 以受支持的 `openclaw.json` 凭证路径为目标。
-- `auth-profiles.json` refs 也包含在运行时解析和审计覆盖范围内。
+- 规范矩阵：[SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface)
+- `secrets apply` 作用于受支持的 `openclaw.json` 凭证路径。
+- `auth-profiles.json` 的 refs 也包含在运行时解析和审计覆盖范围内。
### Secret 提供商配置
@@ -3443,13 +3418,13 @@ Secret ref 是增量支持的：明文值仍然可用。
说明：
-- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须是 `"value"`）。
-- `exec` 提供商要求 `command` 使用绝对路径，并通过 stdin/stdout 使用协议负载。
-- 默认情况下，会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时验证解析后的目标路径。
-- 如果配置了 `trustedDirs`，受信任目录检查会应用到解析后的目标路径。
-- `exec` 子进程环境默认是最小化的；请使用 `passEnv` 显式传入所需变量。
+- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。
+- `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin/stdout 使用协议负载。
+- 默认情况下，会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可在验证解析后目标路径的同时允许符号链接路径。
+- 如果配置了 `trustedDirs`，受信任目录检查将作用于解析后的目标路径。
+- `exec` 子进程默认使用最小化环境；请通过 `passEnv` 显式传递所需变量。
- Secret refs 会在激活时解析到内存快照中，之后请求路径只读取该快照。
-- 激活期间会应用活动入口过滤：已启用入口上未解析的 refs 会导致启动/重载失败，而非活动入口会跳过并记录诊断信息。
+- 激活期间会应用活动面过滤：已启用面的未解析 ref 会导致启动/重载失败，而非活动面会跳过并附带诊断信息。
---
@@ -3471,13 +3446,13 @@ Secret ref 是增量支持的：明文值仍然可用。
}
```
-- 按智能体区分的配置文件存储在 `/auth-profiles.json`。
-- `auth-profiles.json` 支持静态凭证模式的值级 refs（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。
-- OAuth 模式配置文件（`auth.profiles..mode = "oauth"`）不支持基于 SecretRef 的 auth-profile 凭证。
+- 按智能体配置的 profiles 存储在 `/auth-profiles.json`。
+- `auth-profiles.json` 支持静态凭证模式下的值级 refs（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。
+- OAuth 模式 profile（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。
- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会进行清理。
- 旧版 OAuth 会从 `~/.openclaw/credentials/oauth.json` 导入。
- 参见 [OAuth](/zh-CN/concepts/oauth)。
-- Secrets 运行时行为以及 `audit/configure/apply` 工具：参见 [Secrets Management](/zh-CN/gateway/secrets)。
+- Secrets 运行时行为及 `audit/configure/apply` 工具：参见 [Secrets Management](/zh-CN/gateway/secrets)。
### `auth.cooldowns`
@@ -3499,20 +3474,15 @@ Secret ref 是增量支持的：明文值仍然可用。
}
```
-- `billingBackoffHours`：当某个配置文件因真实
- 计费/余额不足错误而失败时的基础退避时长（小时）（默认：`5`）。即使在 `401`/`403` 响应上，
- 明确的计费文本仍可能落入这里，但提供商特定的文本
- 匹配器仍只限于拥有它们的提供商（例如 OpenRouter
- `Key limit exceeded`）。可重试的 HTTP `402` 用量窗口或
- 组织/工作区支出上限消息仍会进入 `rate_limit` 路径。
-- `billingBackoffHoursByProvider`：可选的按提供商覆盖计费退避小时数。
-- `billingMaxHours`：计费退避指数增长的上限小时数（默认：`24`）。
-- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避分钟数（默认：`10`）。
-- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的上限分钟数（默认：`60`）。
-- `failureWindowHours`：用于退避计数器的滚动时间窗口（小时）（默认：`24`）。
-- `overloadedProfileRotations`：对于 overloaded 错误，在切换到模型回退之前，允许的同一提供商 auth-profile 轮换最大次数（默认：`1`）。像 `ModelNotReadyException` 这样的提供商繁忙形态会落入这里。
-- `overloadedBackoffMs`：在重试 overloaded 提供商/配置文件轮换前的固定延迟（毫秒）（默认：`0`）。
-- `rateLimitedProfileRotations`：对于限流错误，在切换到模型回退之前，允许的同一提供商 auth-profile 轮换最大次数（默认：`1`）。该限流桶包括提供商特征文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。
+- `billingBackoffHours`：当 profile 因真实计费/额度不足错误而失败时，使用的基础退避时长（小时，默认：`5`）。即使在 `401`/`403` 响应中，显式的计费文本也可能落入这里，但提供商特定的文本匹配器仍只作用于拥有它们的提供商（例如 OpenRouter 的 `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或组织/工作区支出上限消息则仍归入 `rate_limit` 路径。
+- `billingBackoffHoursByProvider`：可选的按提供商计费退避时长（小时）覆盖。
+- `billingMaxHours`：计费退避指数增长的上限（小时，默认：`24`）。
+- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避时长（分钟，默认：`10`）。
+- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的上限（分钟，默认：`60`）。
+- `failureWindowHours`：用于退避计数器的滚动窗口（小时，默认：`24`）。
+- `overloadedProfileRotations`：对于 overloaded 错误，在切换到模型回退之前，同一提供商内允许进行的最大 auth-profile 轮换次数（默认：`1`）。像 `ModelNotReadyException` 这样的提供商繁忙形态会归入这里。
+- `overloadedBackoffMs`：在重试 overloaded 提供商/profile 轮换前的固定延迟（毫秒，默认：`0`）。
+- `rateLimitedProfileRotations`：对于 rate-limit 错误，在切换到模型回退之前，同一提供商内允许进行的最大 auth-profile 轮换次数（默认：`1`）。该 rate-limit 桶包括提供商特定文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。
---
@@ -3532,9 +3502,9 @@ Secret ref 是增量支持的：明文值仍然可用。
```
- 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。
-- 设置 `logging.file` 可使用固定路径。
-- 当使用 `--verbose` 时，`consoleLevel` 会提升到 `debug`。
-- `maxFileBytes`：在抑制写入之前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。
+- 设置 `logging.file` 可使用稳定路径。
+- 使用 `--verbose` 时，`consoleLevel` 会提升到 `debug`。
+- `maxFileBytes`：在抑制写入前允许的最大日志文件大小（字节，正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。
---
@@ -3572,19 +3542,19 @@ Secret ref 是增量支持的：明文值仍然可用。
```
- `enabled`：instrumentation 输出的总开关（默认：`true`）。
-- `flags`：启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 这样的通配符）。
-- `stuckSessionWarnMs`：当会话仍处于处理状态时，发出会话卡住警告的年龄阈值（毫秒）。
-- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。
+- `flags`：启用定向日志输出的标志字符串数组（支持通配符，如 `"telegram.*"` 或 `"*"`）。
+- `stuckSessionWarnMs`：当某个会话仍处于处理中状态时，发出卡住会话警告的时间阈值（毫秒）。
+- `otel.enabled`：启用 OpenTelemetry 导出管道（默认：`false`）。
- `otel.endpoint`：OTel 导出的采集器 URL。
- `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。
-- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据 headers。
+- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据 header。
- `otel.serviceName`：资源属性中的服务名称。
-- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。
+- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或日志导出。
- `otel.sampleRate`：trace 采样率，范围 `0`–`1`。
-- `otel.flushIntervalMs`：定期刷新 telemetry 的间隔（毫秒）。
+- `otel.flushIntervalMs`：周期性 telemetry 刷新间隔（毫秒）。
- `cacheTrace.enabled`：为嵌入式运行记录缓存跟踪快照（默认：`false`）。
- `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。
-- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含哪些内容（默认全部为 `true`）。
+- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出包含哪些内容（默认全为 `true`）。
---
@@ -3606,12 +3576,12 @@ Secret ref 是增量支持的：明文值仍然可用。
}
```
-- `channel`：npm/git 安装使用的发布渠道——`"stable"`、`"beta"` 或 `"dev"`。
+- `channel`：用于 npm/git 安装的发布渠道——`"stable"`、`"beta"` 或 `"dev"`。
- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认：`true`）。
- `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。
-- `auto.stableDelayHours`：stable 渠道自动应用前的最小延迟小时数（默认：`6`；最大：`168`）。
-- `auto.stableJitterHours`：stable 渠道额外发布扩散窗口小时数（默认：`12`；最大：`168`）。
-- `auto.betaCheckIntervalHours`：beta 渠道检查的运行频率（小时）（默认：`1`；最大：`24`）。
+- `auto.stableDelayHours`：stable 渠道自动应用前的最小延迟（小时，默认：`6`；最大：`168`）。
+- `auto.stableJitterHours`：stable 渠道额外发布扩散窗口（小时，默认：`12`；最大：`168`）。
+- `auto.betaCheckIntervalHours`：beta 渠道检查运行频率（小时，默认：`1`；最大：`24`）。
---
@@ -3645,21 +3615,21 @@ Secret ref 是增量支持的：明文值仍然可用。
```
- `enabled`：全局 ACP 功能开关（默认：`false`）。
-- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认：`true`）。设为 `false` 可保留 ACP 命令可用，但阻止执行。
-- `backend`：默认 ACP 运行时 backend id（必须匹配某个已注册的 ACP 运行时插件）。
-- `defaultAgent`：当派生未指定显式目标时，使用的回退 ACP 目标智能体 id。
-- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；空表示不做额外限制。
-- `maxConcurrentSessions`：同时活跃的 ACP 会话最大数量。
+- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认：`true`）。设为 `false` 可保留 ACP 命令可用，同时阻止执行。
+- `backend`：默认 ACP 运行时 backend id（必须匹配已注册的 ACP 运行时插件）。
+- `defaultAgent`：当派生时未指定显式目标时，使用的回退 ACP 目标智能体 id。
+- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；为空表示没有额外限制。
+- `maxConcurrentSessions`：允许同时处于活动状态的 ACP 会话最大数。
- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口（毫秒）。
-- `stream.maxChunkChars`：拆分流式块投影前允许的最大分块大小。
+- `stream.maxChunkChars`：流式块投影在拆分前允许的最大块大小。
- `stream.repeatSuppression`：按轮次抑制重复的状态/工具行（默认：`true`）。
-- `stream.deliveryMode`：`"live"` 表示增量流式传输；`"final_only"` 表示缓冲到轮次终止事件后再输出。
-- `stream.hiddenBoundarySeparator`：隐藏工具事件后、可见文本前的分隔符（默认：`"paragraph"`）。
-- `stream.maxOutputChars`：每个 ACP 轮次投影的 assistant 输出最大字符数。
-- `stream.maxSessionUpdateChars`：投影 ACP 状态/更新行的最大字符数。
-- `stream.tagVisibility`：从标签名到布尔可见性覆盖的记录，用于流式事件。
-- `runtime.ttlMinutes`：ACP 会话 worker 在可清理前的空闲 TTL（分钟）。
-- `runtime.installCommand`：在引导 ACP 运行时环境时执行的可选安装命令。
+- `stream.deliveryMode`：`"live"` 表示增量流式传输；`"final_only"` 表示缓存到轮次结束事件后再输出。
+- `stream.hiddenBoundarySeparator`：在隐藏工具事件之后、可见文本之前插入的分隔符（默认：`"paragraph"`）。
+- `stream.maxOutputChars`：每个 ACP 轮次可投影的最大 assistant 输出字符数。
+- `stream.maxSessionUpdateChars`：ACP 状态/更新行可投影的最大字符数。
+- `stream.tagVisibility`：将标签名称映射到布尔可见性覆盖的记录，用于流式事件。
+- `runtime.ttlMinutes`：ACP 会话 worker 在空闲多久后可被清理的 TTL（分钟）。
+- `runtime.installCommand`：可选的安装命令，用于引导 ACP 运行时环境。
---
@@ -3676,10 +3646,10 @@ Secret ref 是增量支持的：明文值仍然可用。
```
- `cli.banner.taglineMode` 控制 banner 标语样式：
- - `"random"`（默认）：轮换显示有趣/季节性标语。
- - `"default"`：固定中性标语（`All your chats, one OpenClaw.`）。
- - `"off"`：不显示标语文本（仍显示 banner 标题/版本）。
-- 如需隐藏整个 banner（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。
+ - `"random"`（默认）：轮换的有趣/季节性标语。
+ - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。
+ - `"off"`：不显示标语文本（仍会显示 banner 标题/版本）。
+- 若要隐藏整个 banner（不仅仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。
---
@@ -3701,15 +3671,15 @@ Secret ref 是增量支持的：明文值仍然可用。
---
-## 身份
+## Identity
-请参见 [智能体默认值](#agent-defaults) 下 `agents.list` 的 identity 字段。
+请参见 [智能体默认值](#agent-defaults) 中 `agents.list` 的 identity 字段。
---
## Bridge protocol（旧版节点，历史参考）（旧版，已移除）
-当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前，验证会失败；可用 `openclaw doctor --fix` 清除未知键）。
+当前构建不再包含 TCP bridge。Nodes 通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除之前验证会失败；`openclaw doctor --fix` 可清除未知键）。
@@ -3738,7 +3708,7 @@ Secret ref 是增量支持的：明文值仍然可用。
cron: {
enabled: true,
maxConcurrentRuns: 2,
- webhook: "https://example.invalid/legacy", // 已弃用，仅作为存储的 notify:true 任务的回退
+ webhook: "https://example.invalid/legacy", // 已弃用：供已存储且 notify:true 的任务使用的回退值
webhookToken: "replace-with-dedicated-token", // 可选：用于出站 webhook 认证的 bearer token
sessionRetention: "24h", // 时长字符串或 false
runLog: {
@@ -3749,11 +3719,11 @@ Secret ref 是增量支持的：明文值仍然可用。
}
```
-- `sessionRetention`：在从 `sessions.json` 清理前，已完成的隔离 cron 运行会话保留多久。也控制已归档、已删除 cron transcript 的清理。默认值：`24h`；设为 `false` 可禁用。
-- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在触发清理前的最大大小。默认值：`2_000_000` 字节。
+- `sessionRetention`：在从 `sessions.json` 清理前，保留已完成的隔离 cron 运行会话多久。也控制已归档、已删除的 cron 转录清理。默认值：`24h`；设为 `false` 可禁用。
+- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在触发清理前允许的最大大小。默认值：`2_000_000` 字节。
- `runLog.keepLines`：触发运行日志清理时保留的最新行数。默认值：`2000`。
-- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；如果省略，则不会发送认证 header。
-- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍然带有 `notify: true` 的已存储任务。
+- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略，则不会发送认证 header。
+- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍带有 `notify: true` 的已存储任务。
### `cron.retry`
@@ -3769,11 +3739,11 @@ Secret ref 是增量支持的：明文值仍然可用。
}
```
-- `maxAttempts`：一次性任务在瞬时错误下的最大重试次数（默认：`3`；范围：`0`–`10`）。
-- `backoffMs`：每次重试尝试对应的退避延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。
-- `retryOn`：触发重试的错误类型——`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时会对所有瞬时类型重试。
+- `maxAttempts`：一次性任务在瞬时错误上的最大重试次数（默认：`3`；范围：`0`–`10`）。
+- `backoffMs`：每次重试尝试对应的退避延迟数组（毫秒，默认：`[30000, 60000, 300000]`；1–10 个条目）。
+- `retryOn`：触发重试的错误类型——`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则会重试所有瞬时错误类型。
-仅适用于一次性 cron 任务。循环任务使用独立的失败处理方式。
+仅适用于一次性 cron 任务。周期性任务使用独立的失败处理机制。
### `cron.failureAlert`
@@ -3791,10 +3761,10 @@ Secret ref 是增量支持的：明文值仍然可用。
}
```
-- `enabled`：为 cron 任务启用失败告警（默认：`false`）。
-- `after`：触发告警前所需的连续失败次数（正整数，最小值：`1`）。
-- `cooldownMs`：同一任务重复告警之间的最小间隔（毫秒）（非负整数）。
-- `mode`：投递模式——`"announce"` 通过渠道消息发送；`"webhook"` 向配置的 webhook 发起 POST。
+- `enabled`：启用 cron 任务失败告警（默认：`false`）。
+- `after`：连续失败多少次后触发告警（正整数，最小值：`1`）。
+- `cooldownMs`：同一任务重复告警之间的最小间隔（毫秒，非负整数）。
+- `mode`：投递模式——`"announce"` 通过渠道消息发送；`"webhook"` 向已配置 webhook 发起 POST。
- `accountId`：用于限定告警投递范围的可选账号或渠道 id。
### `cron.failureDestination`
@@ -3813,12 +3783,12 @@ Secret ref 是增量支持的：明文值仍然可用。
```
- 所有任务共享的 cron 失败通知默认目标。
-- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认是 `"announce"`。
-- `channel`：announce 投递的渠道覆盖。`"last"` 会复用最后一次已知投递渠道。
-- `to`：显式的 announce 目标或 webhook URL。webhook 模式下必填。
+- `mode`：`"announce"` 或 `"webhook"`；当存在足够目标数据时，默认值为 `"announce"`。
+- `channel`：announce 投递的渠道覆盖。`"last"` 表示复用上次已知的投递渠道。
+- `to`：显式的 announce 目标或 webhook URL。webhook 模式下为必填。
- `accountId`：可选的投递账号覆盖。
-- 按任务的 `delivery.failureDestination` 会覆盖此全局默认值。
-- 当全局和按任务失败目标都未设置时，原本通过 `announce` 投递的任务在失败时会回退到其主 announce 目标。
+- 按任务的 `delivery.failureDestination` 会覆盖该全局默认值。
+- 当既未设置全局失败目标，也未设置按任务失败目标时，那些原本通过 `announce` 投递的任务在失败时会回退到其主 announce 目标。
- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的任务，除非该任务的主 `delivery.mode` 为 `"webhook"`。
参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [background tasks](/zh-CN/automation/tasks) 跟踪。
@@ -3829,34 +3799,34 @@ Secret ref 是增量支持的：明文值仍然可用。
在 `tools.media.models[].args` 中展开的模板占位符：
-| Variable | 说明 |
-| ------------------ | --------------------------------- |
-| `{{Body}}` | 完整入站消息正文 |
-| `{{RawBody}}` | 原始正文（无历史/发送者包装） |
-| `{{BodyStripped}}` | 去除群提及后的正文 |
-| `{{From}}` | 发送者标识 |
-| `{{To}}` | 目标标识 |
-| `{{MessageSid}}` | 渠道消息 id |
-| `{{SessionId}}` | 当前会话 UUID |
-| `{{IsNewSession}}` | 新会话创建时为 `"true"` |
-| `{{MediaUrl}}` | 入站媒体伪 URL |
-| `{{MediaPath}}` | 本地媒体路径 |
+| 变量 | 说明 |
+| ------------------ | ------------------------------------------------- |
+| `{{Body}}` | 完整入站消息正文 |
+| `{{RawBody}}` | 原始正文（无历史/发送者包装） |
+| `{{BodyStripped}}` | 去除群组提及后的正文 |
+| `{{From}}` | 发送者标识符 |
+| `{{To}}` | 目标标识符 |
+| `{{MessageSid}}` | 渠道消息 id |
+| `{{SessionId}}` | 当前会话 UUID |
+| `{{IsNewSession}}` | 新建会话时为 `"true"` |
+| `{{MediaUrl}}` | 入站媒体伪 URL |
+| `{{MediaPath}}` | 本地媒体路径 |
| `{{MediaType}}` | 媒体类型（image/audio/document/…） |
-| `{{Transcript}}` | 音频 transcript |
-| `{{Prompt}}` | 用于 CLI 条目的已解析媒体提示词 |
-| `{{MaxChars}}` | 用于 CLI 条目的已解析最大输出字符数 |
-| `{{ChatType}}` | `"direct"` 或 `"group"` |
-| `{{GroupSubject}}` | 群主题（尽力获取） |
-| `{{GroupMembers}}` | 群成员预览（尽力获取） |
-| `{{SenderName}}` | 发送者显示名称（尽力获取） |
-| `{{SenderE164}}` | 发送者电话号码（尽力获取） |
+| `{{Transcript}}` | 音频转录 |
+| `{{Prompt}}` | 为 CLI 条目解析后的媒体 prompt |
+| `{{MaxChars}}` | 为 CLI 条目解析后的最大输出字符数 |
+| `{{ChatType}}` | `"direct"` 或 `"group"` |
+| `{{GroupSubject}}` | 群组主题（尽力而为） |
+| `{{GroupMembers}}` | 群组成员预览（尽力而为） |
+| `{{SenderName}}` | 发送者显示名称（尽力而为） |
+| `{{SenderE164}}` | 发送者电话号码（尽力而为） |
| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） |
---
-## 配置 includes（`$include`）
+## 配置包含（`$include`）
-将配置拆分为多个文件：
+将配置拆分到多个文件中：
```json5
// ~/.openclaw/openclaw.json
@@ -3871,12 +3841,12 @@ Secret ref 是增量支持的：明文值仍然可用。
**合并行为：**
-- 单个文件：替换其所在的对象。
-- 文件数组：按顺序深度合并（后面的覆盖前面的）。
-- 同级键：在 include 之后合并（覆盖 include 的值）。
-- 嵌套 include：最多 10 层。
-- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。允许使用绝对路径/`../` 形式，但前提是最终解析结果仍位于该边界内。
-- 错误：对缺失文件、解析错误和循环 include 提供清晰的错误信息。
+- 单个文件：替换其所在的容器对象。
+- 文件数组：按顺序深度合并（后者覆盖前者）。
+- 同级键：会在 includes 之后合并（覆盖被包含的值）。
+- 嵌套 includes：最多支持 10 层。
+- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内部。绝对路径/`../` 形式仅在解析后仍位于该边界内时才允许。
+- 错误：对缺失文件、解析错误和循环包含提供清晰报错。
---