openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-04 00:49:50 +00:00
parent 6821c44c78
commit d5d36befda
10 changed files with 1178 additions and 1100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

476
docs/zh-CN/channels/discord.md
View File

File diff suppressed because it is too large Load Diff

230
docs/zh-CN/channels/groups.md
View File

@ -2,37 +2,37 @@
read_when:
- 更改群聊行为或提及门控
sidebarTitle: Groups
summary: 跨各平台的群聊行为（Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo）
summary: 跨各平台的群聊行为 (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
title: 群组
x-i18n:
generated_at: "2026-05-03T09:36:56Z"
generated_at: "2026-05-04T00:46:53Z"
model: gpt-5.5
provider: openai
source_hash: 6fd4fcaa8335f1dc4b4b1a719d6654ab0c10530f74284269ed6205dd5f87c116
source_hash: dea506c011a5d8f6155b2f56aacb236482cb8c5b7457001cb2171fd45932443d
source_path: channels/groups.md
workflow: 16
---
OpenClaw 在各个接入面上一致地处理群聊：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。
OpenClaw 在各个表面上一致地处理群聊：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。
## 新手简介（2 分钟）
## 初学者简介（2 分钟）
OpenClaw “存在于”你自己的消息账号中。没有单独的 WhatsApp 机器人用户。如果 **你** 在某个群组中，OpenClaw 就能看到该群组并在那里响应。
OpenClaw “存在于”你自己的消息账号中。没有单独的 WhatsApp 机器人用户。如果**你**在某个群组里，OpenClaw 就能看到该群组并在那里回复。
默认行为：
- 群组受限（`groupPolicy: "allowlist"`）。
- 回复需要提及，除非你明确禁用提及门控。
- 群组/渠道中的普通最终回复默认是私密的。可见的房间输出使用 `message` 工具。
- 除非你明确禁用提及门控，否则回复需要提及。
- 群组/渠道中的普通最终回复默认是私密的。可见的聊天室输出使用 `message` 工具。
换句话说：允许列表中的发送者可以通过提及 OpenClaw 来触发它。
<Note>
**摘要**
**简而言之**
- **私信访问** 由 `*.allowFrom` 控制。
- **群组访问** 由 `*.groupPolicy` + 允许列表（`*.groups`、`*.groupAllowFrom`）控制。
- **回复触发** 由提及门控（`requireMention`、`/activation`）控制。
- **私信访问**由 `*.allowFrom` 控制。
- **群组访问**由 `*.groupPolicy` + 允许列表（`*.groups`、`*.groupAllowFrom`）控制。
- **回复触发**由提及门控（`requireMention`、`/activation`）控制。
</Note>
@ -47,20 +47,28 @@ otherwise -> reply
## 可见回复
对于群组/渠道房间，OpenClaw 默认使用 `messages.groupChat.visibleReplies: "message_tool"`。
`openclaw doctor --fix` 会把这个默认值写入缺少它的已配置渠道配置中。
这意味着智能体仍会处理这一轮，并且可以更新记忆/会话状态，但它的普通最终回答不会自动发回房间。要可见地发言，智能体会使用 `message(action=send)`。
对于群组/渠道聊天室，OpenClaw 默认使用 `messages.groupChat.visibleReplies: "message_tool"`。
`openclaw doctor --fix` 会把这个默认值写入已配置但省略该项的渠道配置。
这意味着智能体仍会处理这一轮，并且可以更新记忆/会话状态，但它的普通最终答案不会自动发布回聊天室。要可见地发言，智能体会使用 `message(action=send)`。
此默认值依赖能够可靠调用工具的模型/运行时。如果日志显示
assistant 文本但 `didSendViaMessagingTool: false`，说明模型进行了
私密回答，而不是调用消息工具。这不是
Discord/Slack/Telegram 发送失败。请为
群组/渠道会话使用工具调用可靠的模型，或设置
`messages.groupChat.visibleReplies: "automatic"` 来恢复旧版可见
最终回复。
如果在当前工具策略下消息工具不可用，OpenClaw 会回退到自动可见回复，而不是静默抑制响应。
`openclaw doctor` 会警告这种不匹配。
`openclaw doctor` 会对此不匹配发出警告。
对于直接聊天和任何其他来源轮次，使用 `messages.visibleReplies: "message_tool"` 可在全局应用相同的仅工具可见回复行为。Harness 也可以选择将它作为未设置时的默认值；Codex harness 会对 Codex 模式的直接聊天这样做。`messages.groupChat.visibleReplies` 仍然是针对群组/渠道房间的更具体覆盖。
对于直接聊天和任何其他来源轮次，使用 `messages.visibleReplies: "message_tool"` 可在全局应用相同的仅工具可见回复行为。Harness 也可以将其选为未设置时的默认值；Codex harness 会对 Codex 模式直接聊天这样做。`messages.groupChat.visibleReplies` 仍是群组/渠道聊天室更具体的覆盖项。
这取代了旧模式：强制模型在大多数潜伏模式轮次中回答 `NO_REPLY`。在仅工具模式中，不产生可见输出只是意味着不调用消息工具。
这取代了旧模式：强制模型在大多数潜伏模式轮次中回答 `NO_REPLY`。在仅工具模式下，不产生可见输出只表示不调用消息工具。
在仅工具模式中，智能体工作时仍会发送输入状态指示器。对于这些轮次，默认群组输入状态模式会从 “message” 升级为 “instant”，因为在智能体决定是否调用消息工具之前，可能永远不会出现普通助手消息文本。显式的输入状态模式配置仍然优先。
在仅工具模式下，智能体工作时仍会发送正在输入指示器。这些轮次的默认群组输入模式会从 “message” 升级为 “instant”，因为智能体决定是否调用消息工具之前，可能永远不会有普通 assistant 消息文本。显式的输入模式配置仍然优先。
要恢复群组/渠道房间的旧版自动最终回复：
要恢复群组/渠道聊天室的旧版自动最终回复：
```json5
{
@ -72,7 +80,7 @@ otherwise -> reply
}
```
文件保存后，Gateway 网关会热重载 `messages` 配置。只有在部署中禁用了文件监视或配置重载时才需要重启。
文件保存后，Gateway 网关会热重载 `messages` 配置。只有在部署中禁用文件监听或配置重载时才需要重启。
要要求每个来源聊天的可见输出都通过消息工具：
@ -84,73 +92,73 @@ otherwise -> reply
}
```
原生命令斜杠命令（Discord、Telegram，以及其他支持原生命令的接入面）会绕过 `visibleReplies: "message_tool"`，并始终可见地回复，以便渠道原生命令 UI 获得它预期的响应。这只适用于通过验证的原生命令轮次；以文本输入的 `/...` 命令和普通聊天轮次仍遵循已配置的群组默认值。
原生斜杠命令（Discord、Telegram，以及其他支持原生命令的表面）会绕过 `visibleReplies: "message_tool"`，并始终可见地回复，这样渠道原生命令 UI 才能获得预期响应。这只适用于经过验证的原生命令轮次；文本输入的 `/...` 命令和普通聊天轮次仍遵循已配置的群组默认值。
## 上下文可见性和允许列表
## 上下文可见性与允许列表
群组安全涉及两种不同控制：
- **触发授权**：谁可以触发智能体（`groupPolicy`、`groups`、`groupAllowFrom`、渠道特定允许列表）。
- **上下文可见性**：哪些补充上下文会注入模型（回复文本、引用、线程历史、转发元数据）。
- **上下文可见性**：哪些补充上下文会被注入模型（回复文本、引用、线程历史、转发元数据）。
默认情况下，OpenClaw 优先保持正常聊天行为，并让上下文大多按接收时保留。这意味着允许列表主要决定谁可以触发操作，而不是为每个引用或历史片段提供通用脱敏边界。
默认情况下，OpenClaw 优先保持正常聊天行为，并基本按接收时的样子保留上下文。这意味着允许列表主要决定谁能触发操作，而不是针对每段引用或历史片段的通用删改边界。
<AccordionGroup>
<Accordion title="当前行为因渠道而异">
- 某些渠道已经在特定路径中对补充上下文应用基于发送者的过滤（例如 Slack 线程播种、Matrix 回复/线程查找）。
- 其他渠道仍会按接收时传递引用/回复/转发上下文。
- 一些渠道已经在特定路径中对补充上下文应用基于发送者的过滤（例如 Slack 线程播种、Matrix 回复/线程查找）。
- 其他渠道仍会按接收时的样子传递引用/回复/转发上下文。
</Accordion>
<Accordion title="加固方向（计划中）">
- `contextVisibility: "all"`（默认）保持当前按接收时保留的行为。
- `contextVisibility: "allowlist"` 会把补充上下文过滤为允许列表中的发送者。
- `contextVisibility: "allowlist_quote"` 是 `allowlist` 加上一个显式引用/回复例外。
- `contextVisibility: "all"`（默认）保持当前按接收样子处理的行为。
- `contextVisibility: "allowlist"` 将补充上下文过滤为允许列表发送者。
- `contextVisibility: "allowlist_quote"` 是 `allowlist` 加一个显式引用/回复例外。
在这个加固模型在各渠道间一致实现之前，请预期不同接入面之间存在差异。
在此加固模型于各渠道中一致实现之前，预期不同表面之间会存在差异。
</Accordion>
</AccordionGroup>
![群组消息流程](/images/groups-flow.svg)
如果你想要……
如果你想要...
| 目标 | 要设置的内容 |
| 目标 | 设置内容 |
| -------------------------------------------- | ---------------------------------------------------------- |
| 允许所有群组，但只在 @提及 时回复 | `groups: { "*": { requireMention: true } }` |
| 允许所有群组，但只在 @提及时回复 | `groups: { "*": { requireMention: true } }` |
| 禁用所有群组回复 | `groupPolicy: "disabled"` |
| 仅特定群组 | `groups: { "<group-id>": { ... } }`（没有 `"*"` 键） |
| 只有你可以在群组中触发 | `groupPolicy: "allowlist"`，`groupAllowFrom: ["+1555..."]` |
| 跨渠道复用一组受信任发送者 | `groupAllowFrom: ["accessGroup:operators"]` |
| 仅特定群组 | `groups: { "<group-id>": { ... } }`（没有 `"*"` 键） |
| 只有你能在群组中触发 | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
| 跨渠道复用一组受信任发送者 | `groupAllowFrom: ["accessGroup:operators"]` |
关于可复用的发送者允许列表，请参阅 [访问组](/zh-CN/channels/access-groups)。
有关可复用发送者允许列表，请参阅[访问组](/zh-CN/channels/access-groups)。
## 会话键
- 群组会话使用 `agent:<agentId>:<channel>:group:<id>` 会话键（房间/渠道使用 `agent:<agentId>:<channel>:channel:<id>`）。
- Telegram 论坛话题会在群组 ID 后添加 `:topic:<threadId>`，因此每个话题都有自己的会话。
- 直接聊天使用主会话（如果已配置，也可以按发送者分别使用会话）。
- 群组会话使用 `agent:<agentId>:<channel>:group:<id>` 会话键（聊天室/渠道使用 `agent:<agentId>:<channel>:channel:<id>`）。
- Telegram 论坛主题会向群组 ID 添加 `:topic:<threadId>`，使每个主题都有自己的会话。
- 直接聊天使用主会话（如果已配置，也可以按发送者分开）。
- 群组会话会跳过 Heartbeat。
<a id="pattern-personal-dms-public-groups-single-agent"></a>
## 模式：个人私信 + 公共群组（单智能体）
## 模式：个人私信 + 公开群组（单智能体）
可以。如果你的“个人”流量是**私信**，而“公共”流量是**群组**，这种方式运行良好。
可以，这在你的“个人”流量是**私信**、你的“公开”流量是**群组**时效果很好。
原因：在单智能体模式中，私信通常落入**主**会话键（`agent:main:main`），而群组始终使用**非主**会话键（`agent:main:<channel>:group:<id>`）。如果你启用沙箱隔离并设置 `mode: "non-main"`，这些群组会话会在已配置的沙箱后端中运行，而你的主私信会话仍留在主机上。如果你没有选择后端，Docker 是默认后端。
原因：在单智能体模式中，私信通常落到**主**会话键（`agent:main:main`），而群组始终使用**非主**会话键（`agent:main:<channel>:group:<id>`）。如果你以 `mode: "non-main"` 启用沙箱隔离，这些群组会话会在已配置的沙箱后端中运行，而你的主私信会话留在主机上。如果你没有选择后端，Docker 是默认后端。
这样你会得到一个智能体“大脑”（共享工作区 + 记忆），但有两种执行姿态：
这会给你一个智能体“大脑”（共享工作区 + 记忆），但有两种执行姿态：
- **私信**：完整工具（主机）
- **群组**：沙箱 + 受限工具
<Note>
如果你需要真正独立的工作区/人设（“个人”和“公共”绝不能混用），请使用第二个智能体 + 绑定。参见 [多智能体路由](/zh-CN/concepts/multi-agent)。
如果你需要真正分离的工作区/人格（“个人”和“公开”绝不能混合），请使用第二个智能体 + 绑定。参阅[多智能体路由](/zh-CN/concepts/multi-agent)。
</Note>
<Tabs>
<Tab title="私信在主机上，群组在沙箱中">
<Tab title="私信在主机上，群组沙箱隔离">
```json5
{
agents: {
@ -174,8 +182,8 @@ otherwise -> reply
}
```
</Tab>
<Tab title="群组只能看到一个允许列表文件夹">
想要“群组只能看到文件夹 X”，而不是“没有主机访问权限”？保留 `workspaceAccess: "none"`，并且只把允许列表中的路径挂载进沙箱：
<Tab title="群组只能看到允许列表文件夹">
想要“群组只能看到文件夹 X”，而不是“没有主机访问权限”？保留 `workspaceAccess: "none"`，并只将允许列表路径挂载进沙箱：
```json5
{
@ -200,20 +208,20 @@ otherwise -> reply
</Tab>
</Tabs>
相关：
相关内容：
- 配置键和默认值：[Gateway 网关配置](/zh-CN/gateway/config-agents#agentsdefaultssandbox)
- 调试工具为什么被阻止：[沙箱 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated)
- 调试工具被阻止的原因：[沙箱 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated)
- 绑定挂载详情：[沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts)
## 显示标签
- UI 标签会在可用时使用 `displayName`，格式为 `<channel>:<token>`。
- `#room` 保留给房间/渠道；群聊使用 `g-<slug>`（小写，空格 -> `-`，保留 `#@+._-`）。
- UI 标签在可用时使用 `displayName`，格式化为 `<channel>:<token>`。
- `#room` 保留给聊天室/渠道；群聊使用 `g-<slug>`（小写，空格 -> `-`，保留 `#@+._-`）。
## 群组策略
按渠道控制如何处理群组/房间消息：
按渠道控制群组/聊天室消息的处理方式：
```json5
{
@ -264,21 +272,21 @@ otherwise -> reply
| ------------- | ------------------------------------------------------------ |
| `"open"` | 群组绕过允许列表；提及门控仍然适用。 |
| `"disabled"` | 完全阻止所有群组消息。 |
| `"allowlist"` | 仅允许匹配已配置允许列表的群组/房间。 |
| `"allowlist"` | 只允许匹配已配置允许列表的群组/聊天室。 |
<AccordionGroup>
<Accordion title="按渠道说明">
- `groupPolicy` 与提及门控分开（提及门控要求 @提及）。
<Accordion title="按频道说明">
- `groupPolicy` 与提及门控分开（后者需要 @mentions）。
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：使用 `groupAllowFrom`（回退：显式 `allowFrom`）。
- Signal：`groupAllowFrom` 可以匹配入站 Signal 群组 ID 或发送者手机号/UUID。
- 私信配对批准（`*-allowFrom` 存储条目）只适用于私信访问；群组发送者授权仍显式保留在群组允许列表中。
- Discord：允许列表使用 `channels.discord.guilds.<id>.channels`。
- Slack：允许列表使用 `channels.slack.channels`。
- Matrix：允许列表使用 `channels.matrix.groups`。优先使用房间 ID 或别名；已加入房间名称查找是尽力而为的，运行时会忽略未解析的名称。使用 `channels.matrix.groupAllowFrom` 来限制发送者；也支持按房间配置的 `users` 允许列表。
- Signal：`groupAllowFrom` 可以匹配入站 Signal 群组 ID 或发送者电话/UUID。
- 私信配对批准（`*-allowFrom` 存储条目）仅适用于私信访问；群组发送者授权仍然明确依赖群组 allowlist。
- Discord：allowlist 使用 `channels.discord.guilds.<id>.channels`。
- Slack：allowlist 使用 `channels.slack.channels`。
- Matrix：allowlist 使用 `channels.matrix.groups`。优先使用房间 ID 或别名；已加入房间的名称查找是尽力而为，运行时会忽略无法解析的名称。使用 `channels.matrix.groupAllowFrom` 限制发送者；也支持按房间的 `users` allowlist。
- 群组私信单独控制（`channels.discord.dm.*`、`channels.slack.dm.*`）。
- Telegram 允许列表可以匹配用户 ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）或用户名（`"@alice"` 或 `"alice"`）；前缀不区分大小写。
- 默认值是 `groupPolicy: "allowlist"`；如果你的群组允许列表为空，群组消息会被阻止。
- 运行时安全：当提供商块完全缺失（不存在 `channels.<provider>`）时，群组策略会回退到失败关闭模式（通常是 `allowlist`），而不是继承 `channels.defaults.groupPolicy`。
- Telegram allowlist 可以匹配用户 ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）或用户名（`"@alice"` 或 `"alice"`）；前缀不区分大小写。
- 默认值是 `groupPolicy: "allowlist"`；如果你的群组 allowlist 为空，群组消息会被阻止。
- 运行时安全性：当 provider 块完全缺失（不存在 `channels.<provider>`）时，群组策略会回退到故障关闭模式（通常是 `allowlist`），而不是继承 `channels.defaults.groupPolicy`。
</Accordion>
</AccordionGroup>
@ -287,21 +295,21 @@ otherwise -> reply
<Steps>
<Step title="groupPolicy">
`groupPolicy`（开放/禁用/允许列表）。
`groupPolicy`（open/disabled/allowlist）。
</Step>
<Step title="Group allowlists">
群组允许列表（`*.groups`、`*.groupAllowFrom`、渠道专用允许列表）。
<Step title="群组 allowlist">
群组 allowlist（`*.groups`、`*.groupAllowFrom`、频道专用 allowlist）。
</Step>
<Step title="Mention gating">
<Step title="提及门控">
提及门控（`requireMention`、`/activation`）。
</Step>
</Steps>
## 提及门控（默认）
群组消息需要提及，除非按群组覆盖。默认值按子系统存放在 `*.groups."*"` 下。
群组消息默认需要提及，除非按群组覆盖。默认值位于每个子系统的 `*.groups."*"` 下。
当渠道支持回复元数据时，回复机器人消息会计为隐式提及。在暴露引用元数据的渠道上，引用机器人消息也可以计为隐式提及。当前内置场景包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。
当 channel 支持回复元数据时，回复机器人消息会被视为隐式提及。在公开引用元数据的 channel 上，引用机器人消息也可以算作隐式提及。当前内置情况包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。
```json5
{
@ -340,40 +348,40 @@ otherwise -> reply
```
<AccordionGroup>
<Accordion title="Mention gating notes">
<Accordion title="提及门控说明">
- `mentionPatterns` 是不区分大小写的安全正则表达式模式；无效模式和不安全的嵌套重复形式会被忽略。
- 提供显式提及的界面仍会通过；模式只是回退方案。
- 提供显式提及的表面仍会通过；模式是回退方案。
- 按智能体覆盖：`agents.list[].groupChat.mentionPatterns`（当多个智能体共享一个群组时很有用）。
- 只有在可以进行提及检测时（配置了原生提及或 `mentionPatterns`），才会强制执行提及门控。
- 将群组或发送者加入允许列表不会禁用提及门控；如果所有消息都应触发，请将该群组的 `requireMention` 设为 `false`。
- 群聊提示词上下文会在每一轮携带已解析的静默回复指令；工作区文件不应重复 `NO_REPLY` 机制。
- 允许静默回复的群组会将干净的空模型轮次或仅推理轮次视为静默，等同于 `NO_REPLY`。直接聊天只有在明确允许直接静默回复时才会这样处理；否则空回复仍会被视为失败的智能体轮次。
- Discord 默认值位于 `channels.discord.guilds."*"`（可按服务器/渠道覆盖）。
- 群组历史上下文在各渠道中统一封装，并且**仅限待处理**（因提及门控而跳过的消息）；使用 `messages.groupChat.historyLimit` 设置全局默认值，并使用 `channels.<channel>.historyLimit`（或 `channels.<channel>.accounts.*.historyLimit`）进行覆盖。设为 `0` 可禁用。
- 仅在可以进行提及检测时（配置了原生提及或 `mentionPatterns`）才强制执行提及门控。
- 将群组或发送者加入 allowlist 不会禁用提及门控；当所有消息都应触发时，将该群组的 `requireMention` 设置为 `false`。
- 群组聊天提示上下文每轮都会携带已解析的静默回复指令；工作区文件不应重复 `NO_REPLY` 机制。
- 允许静默回复的群组会将干净的空模型回合或仅推理模型回合视为静默，等同于 `NO_REPLY`。直接聊天仅在明确允许直接静默回复时才会这样处理；否则空回复仍会被视为失败的智能体回合。
- Discord 默认值位于 `channels.discord.guilds."*"`（可按 guild/channel 覆盖）。
- 群组历史上下文在各 channel 间统一包装，并且**仅包含待处理内容**（因提及门控而跳过的消息）；使用 `messages.groupChat.historyLimit` 设置全局默认值，使用 `channels.<channel>.historyLimit`（或 `channels.<channel>.accounts.*.historyLimit`）进行覆盖。设置为 `0` 可禁用。
</Accordion>
</AccordionGroup>
## 群组/渠道工具限制（可选）
## 群组/channel 工具限制（可选）
某些渠道配置支持限制**特定群组/房间/渠道内**可用的工具。
某些 channel 配置支持限制**特定群组/房间/channel 内**可用的工具。
- `tools`：允许/拒绝整个群组的工具。
- `toolsBySender`：群组内按发送者覆盖。使用显式键前缀：`id:<senderId>`、`e164:<phone>`、`username:<handle>`、`name:<displayName>`，以及 `"*"` 通配符。仍接受旧版无前缀键，并仅按 `id:` 匹配。
- `toolsBySender`：群组内按发送者覆盖。使用显式键前缀：`id:<senderId>`、`e164:<phone>`、`username:<handle>`、`name:<displayName>` 和 `"*"` 通配符。旧版无前缀键仍会被接受，并且仅按 `id:` 匹配。
解析顺序（最具体者优先）：
<Steps>
<Step title="Group toolsBySender">
群组/渠道 `toolsBySender` 匹配。
<Step title="群组 toolsBySender">
群组/channel `toolsBySender` 匹配。
</Step>
<Step title="Group tools">
群组/渠道 `tools`。
<Step title="群组 tools">
群组/channel `tools`。
</Step>
<Step title="Default toolsBySender">
<Step title="默认 toolsBySender">
默认（`"*"`）`toolsBySender` 匹配。
</Step>
<Step title="Default tools">
<Step title="默认 tools">
默认（`"*"`）`tools`。
</Step>
</Steps>
@ -399,28 +407,28 @@ otherwise -> reply
```
<Note>
群组/渠道工具限制会叠加到全局/智能体工具策略之上（拒绝仍优先）。某些渠道对房间/渠道使用不同的嵌套结构（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。
群组/channel 工具限制会额外叠加在全局/智能体工具策略之上（拒绝仍然优先）。某些 channel 对房间/channel 使用不同的嵌套方式（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。
</Note>
## 群组允许列表
## 群组 allowlist
配置 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，这些键会作为群组允许列表。使用 `"*"` 可允许所有群组，同时仍设置默认提及行为。
配置 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，键会作为群组 allowlist。使用 `"*"` 可允许所有群组，同时仍设置默认提及行为。
<Warning>
常见混淆：私信配对批准不同于群组授权。对于支持私信配对的渠道，配对存储仅解锁私信。群组命令仍需要来自配置允许列表（如 `groupAllowFrom`）的显式群组发送者授权，或该渠道记录的配置回退。
常见混淆：私信配对批准不等同于群组授权。对于支持私信配对的 channel，配对存储仅解锁私信。群组命令仍需要来自配置 allowlist 的显式群组发送者授权，例如 `groupAllowFrom` 或该 channel 的文档化配置回退。
</Warning>
常见意图（复制/粘贴）：
<Tabs>
<Tab title="Disable all group replies">
<Tab title="禁用所有群组回复">
```json5
{
channels: { whatsapp: { groupPolicy: "disabled" } },
}
```
</Tab>
<Tab title="Allow only specific groups (WhatsApp)">
<Tab title="仅允许特定群组（WhatsApp）">
```json5
{
channels: {
@ -434,7 +442,7 @@ otherwise -> reply
}
```
</Tab>
<Tab title="Allow all groups but require mention">
<Tab title="允许所有群组但需要提及">
```json5
{
channels: {
@ -445,7 +453,7 @@ otherwise -> reply
}
```
</Tab>
<Tab title="Owner-only triggers (WhatsApp)">
<Tab title="仅 owner 触发（WhatsApp）">
```json5
{
channels: {
@ -460,48 +468,48 @@ otherwise -> reply
</Tab>
</Tabs>
## 激活（仅所有者）
## 激活（仅 owner）
群组所有者可以切换按群组的激活方式：
群组 owner 可以切换按群组激活：
- `/activation mention`
- `/activation always`
所有者由 `channels.whatsapp.allowFrom` 决定（未设置时使用机器人自身的 E.164）。请将该命令作为独立消息发送。其他界面目前会忽略 `/activation`。
Owner 由 `channels.whatsapp.allowFrom` 决定（未设置时使用机器人的自身 E.164）。将命令作为独立消息发送。其他表面目前会忽略 `/activation`。
## 上下文字段
群组入站载荷会设置：
群组入站负载会设置：
- `ChatType=group`
- `GroupSubject`（如果已知）
- `GroupMembers`（如果已知）
- `WasMentioned`（提及门控结果）
- Telegram 论坛主题还会包含 `MessageThreadId` 和 `IsForum`。
- Telegram 论坛主题还包括 `MessageThreadId` 和 `IsForum`。
渠道专用说明：
Channel 专用说明：
- BlueBubbles 可以在填充 `GroupMembers` 前，可选地从本地联系人数据库中补充未命名的 macOS 群组参与者。此功能默认关闭，并且只会在正常群组门控通过后运行。
- BlueBubbles 可以选择在填充 `GroupMembers` 之前，从本地通讯录数据库补充未命名的 macOS 群组参与者。此功能默认关闭，并且只会在正常群组门控通过后运行。
智能体系统提示词会在新群组会话的第一轮包含群组介绍。它会提醒模型像真人一样回复，避免 Markdown 表格，尽量减少空行并遵循正常聊天间距，且避免输入字面量 `\n` 序列。来自渠道的群组名称和参与者标签会渲染为带围栏的不受信元数据，而不是内联系统指令。
智能体系统提示会在新群组会话的第一轮包含群组介绍。它提醒模型像真人一样回应、避免 Markdown 表格、尽量减少空行并遵循普通聊天间距，以及避免输入字面量 `\n` 序列。来自 channel 的群组名称和参与者标签会渲染为 fenced 不受信任元数据，而不是内联系统指令。
## iMessage 细节
- 路由或加入允许列表时，优先使用 `chat_id:<id>`。
- 路由或加入 allowlist 时优先使用 `chat_id:<id>`。
- 列出聊天：`imsg chats --limit 20`。
- 群组回复始终返回到同一个 `chat_id`。
- 群组回复始终发回同一个 `chat_id`。
## WhatsApp 系统提示词
## WhatsApp 系统提示
请参阅 [WhatsApp](/zh-CN/channels/whatsapp#system-prompts)，了解规范的 WhatsApp 系统提示词规则，包括群组和直接提示词解析、通配符行为以及账号覆盖语义。
请参阅 [WhatsApp](/zh-CN/channels/whatsapp#system-prompts)，了解规范的 WhatsApp 系统提示规则，包括群组和直接提示解析、通配符行为以及账号覆盖语义。
## WhatsApp 细节
请参阅[群组消息](/zh-CN/channels/group-messages)，了解仅限 WhatsApp 的行为（历史注入、提及处理细节）。
请参阅 [群组消息](/zh-CN/channels/group-messages)，了解 WhatsApp 专用行为（历史注入、提及处理细节）。
## 相关
## 相关内容
- [广播群组](/zh-CN/channels/broadcast-groups)
- [渠道路由](/zh-CN/channels/channel-routing)
- [Channel 路由](/zh-CN/channels/channel-routing)
- [群组消息](/zh-CN/channels/group-messages)
- [配对](/zh-CN/channels/pairing)

125
docs/zh-CN/channels/troubleshooting.md
View File

@ -1,21 +1,21 @@
---
read_when:
- 渠道传输协议显示已连接，但回复失败
- 在深入阅读提供商文档前，你需要进行渠道特定检查
summary: 渠道级快速故障排除，包含各渠道的失败特征和修复方法
- 渠道传输显示已连接，但回复失败
- 在深入阅读提供商文档之前，你需要进行渠道特定检查
summary: 快速渠道级故障排除，包含各渠道故障特征和修复方法
title: 渠道故障排除
x-i18n:
generated_at: "2026-04-28T22:39:13Z"
generated_at: "2026-05-04T00:46:55Z"
model: gpt-5.5
provider: openai
source_hash: 6024f2ae0a058b2296758c237c912a5cd8ea6bbafea33cc201690cc081efcbee
source_hash: a3a0737156ae83897c44d18505e0355a5d8e5700106b984496d94874c270deb2
source_path: channels/troubleshooting.md
workflow: 16
---
当渠道连接成功但行为异常时，使用本页。
当某个渠道已连接但行为不正确时，使用此页面。
## 命令排查顺序
## 命令排查阶梯
先按顺序运行这些命令：
@ -32,70 +32,71 @@ openclaw channels status --probe
- `Runtime: running`
- `Connectivity probe: ok`
- `Capability: read-only`、`write-capable` 或 `admin-capable`
- 渠道探测显示传输协议已连接，并且在支持的情况下显示 `works` 或 `audit ok`
- 渠道探测显示传输协议已连接，并在支持的情况下显示 `works` 或 `audit ok`
## WhatsApp
### WhatsApp 故障特征
### WhatsApp 失败特征
| 现象 | 最快检查 | 修复 |
| ------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 已连接但没有私信回复 | `openclaw pairing list whatsapp` | 批准发送者，或切换私信策略/允许列表。 |
| 群组消息被忽略 | 检查配置中的 `requireMention` 和提及模式 | 提及机器人，或放宽该群组的提及策略。 |
| 二维码登录超时并返回 408 | 检查 Gateway 网关的 `HTTPS_PROXY` / `HTTP_PROXY` 环境变量 | 设置可访问的代理；仅将 `NO_PROXY` 用于绕过代理。 |
| 随机断开连接/重新登录循环 | `openclaw channels status --probe` + 日志 | 即使当前已连接，最近的重连也会被标记；观察日志，重启 Gateway 网关，如果仍然反复抖动，再重新链接。 |
| 症状 | 最快检查 | 修复 |
| ------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| 已连接但没有私信回复 | `openclaw pairing list whatsapp` | 批准发送者，或切换私信策略/允许列表。 |
| 群组消息被忽略 | 检查配置中的 `requireMention` + 提及模式 | 提及机器人，或放宽该群组的提及策略。 |
| 二维码登录超时并返回 408 | 检查 Gateway 网关的 `HTTPS_PROXY` / `HTTP_PROXY` 环境变量 | 设置可访问的代理；仅将 `NO_PROXY` 用于绕过。 |
| 随机断开连接/重新登录循环 | `openclaw channels status --probe` + 日志 | 即使当前已连接，最近的重连也会被标记；观察日志，重启 Gateway 网关，如果持续抖动再重新链接。 |
完整故障排除：[WhatsApp 故障排除](/zh-CN/channels/whatsapp#troubleshooting)
## Telegram
### Telegram 故障特征
### Telegram 失败特征
| 现象 | 最快检查 | 修复 |
| ------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `/start` 后没有可用的回复流程 | `openclaw pairing list telegram` | 批准配对，或更改私信策略。 |
| 机器人在线但群组保持静默 | 验证提及要求和机器人隐私模式 | 禁用隐私模式以获得群组可见性，或提及机器人。 |
| 发送失败并伴随网络错误 | 检查日志中的 Telegram API 调用失败 | 修复到 `api.telegram.org` 的 DNS/IPv6/代理路由。 |
| 启动时报 `getMe returned 401` | 检查配置的令牌来源 | 重新复制或重新生成 BotFather 令牌，并更新 `botToken`、`tokenFile` 或默认账户的 `TELEGRAM_BOT_TOKEN`。 |
| 轮询卡住或重连缓慢 | 使用 `openclaw logs --follow` 查看轮询诊断 | 升级；如果重启是误报，调整 `pollingStallThresholdMs`。持续卡住仍然指向代理/DNS/IPv6 问题。 |
| 启动时 `setMyCommands` 被拒绝 | 检查日志中的 `BOT_COMMANDS_TOO_MUCH` | 减少插件/Skills/自定义 Telegram 命令，或禁用原生命令菜单。 |
| 升级后允许列表阻止了你 | `openclaw security audit` 和配置允许列表 | 运行 `openclaw doctor --fix`，或将 `@username` 替换为数字发送者 ID。 |
| 症状 | 最快检查 | 修复 |
| ------------------------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `/start` 后没有可用的回复流程 | `openclaw pairing list telegram` | 批准配对或更改私信策略。 |
| 机器人在线但群组保持静默 | 验证提及要求和机器人隐私模式 | 禁用隐私模式以获得群组可见性，或提及机器人。 |
| 发送失败并出现网络错误 | 检查日志中的 Telegram API 调用失败 | 修复到 `api.telegram.org` 的 DNS/IPv6/代理路由。 |
| 启动报告 `getMe returned 401` | 检查配置的令牌来源 | 重新复制或重新生成 BotFather 令牌，并更新 `botToken`、`tokenFile` 或默认账户 `TELEGRAM_BOT_TOKEN`。 |
| 轮询停滞或重连缓慢 | 用 `openclaw logs --follow` 查看轮询诊断 | 升级；如果重启是假阳性，调整 `pollingStallThresholdMs`。持续停滞仍然指向代理/DNS/IPv6 问题。 |
| 启动时 `setMyCommands` 被拒绝 | 检查日志中的 `BOT_COMMANDS_TOO_MUCH` | 减少插件/skill/自定义 Telegram 命令，或禁用原生命令菜单。 |
| 升级后允许列表阻止了你 | `openclaw security audit` 和配置允许列表 | 运行 `openclaw doctor --fix`，或将 `@username` 替换为数字发送者 ID。 |
完整故障排除：[Telegram 故障排除](/zh-CN/channels/telegram#troubleshooting)
## Discord
### Discord 故障特征
### Discord 失败特征
| 现象 | 最快检查 | 修复 |
| ---------------------------- | ----------------------------------- | ---------------------------------------------------------- |
| 机器人在线但没有服务器回复 | `openclaw channels status --probe` | 允许服务器/渠道，并验证消息内容意图。 |
| 群组消息被忽略 | 检查日志中的提及门控丢弃记录 | 提及机器人，或设置服务器/渠道 `requireMention: false`。 |
| 缺少私信回复 | `openclaw pairing list discord` | 批准私信配对，或调整私信策略。 |
| 症状 | 最快检查 | 修复 |
| ----------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 机器人在线但没有服务器回复 | `openclaw channels status --probe` | 允许服务器/渠道，并验证消息内容 intent。 |
| 群组消息被忽略 | 检查日志中的提及门控丢弃 | 提及机器人，或设置服务器/渠道 `requireMention: false`。 |
| 有输入状态/令牌使用量但没有 Discord 消息 | 会话日志显示助手文本且 `didSendViaMessagingTool: false` | 模型进行了私下回答，而不是调用消息工具。使用可靠调用工具的模型，或设置 `messages.groupChat.visibleReplies: "automatic"` 以自动发布。 |
| 缺少私信回复 | `openclaw pairing list discord` | 批准私信配对，或调整私信策略。 |
完整故障排除：[Discord 故障排除](/zh-CN/channels/discord#troubleshooting)
## Slack
### Slack 故障特征
### Slack 失败特征
| 现象 | 最快检查 | 修复 |
| ------------------------------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Socket mode 已连接但没有响应 | `openclaw channels status --probe` | 验证应用令牌 + 机器人令牌和所需作用域；在 SecretRef 支持的设置中留意 `botTokenStatus` / `appTokenStatus = configured_unavailable`。 |
| 私信被阻止 | `openclaw pairing list slack` | 批准配对，或放宽私信策略。 |
| 渠道消息被忽略 | 检查 `groupPolicy` 和渠道允许列表 | 允许该渠道，或将策略切换为 `open`。 |
| 症状 | 最快检查 | 修复 |
| -------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Socket 模式已连接但没有响应 | `openclaw channels status --probe` | 验证 app 令牌 + 机器人令牌和所需作用域；在基于 SecretRef 的设置中注意 `botTokenStatus` / `appTokenStatus = configured_unavailable`。 |
| 私信被阻止 | `openclaw pairing list slack` | 批准配对，或放宽私信策略。 |
| 渠道消息被忽略 | 检查 `groupPolicy` 和渠道允许列表 | 允许该渠道，或将策略切换为 `open`。 |
完整故障排除：[Slack 故障排除](/zh-CN/channels/slack#troubleshooting)
## iMessage 和 BlueBubbles
### iMessage 和 BlueBubbles 故障特征
### iMessage 和 BlueBubbles 失败特征
| 现象 | 最快检查 | 修复 |
| --------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------ |
| 没有入站事件 | 验证 webhook/服务器可达性和应用权限 | 修复 webhook URL 或 BlueBubbles 服务器状态。 |
| macOS 上可以发送但无法接收 | 检查 macOS Messages 自动化的隐私权限 | 重新授予 TCC 权限并重启渠道进程。 |
| 私信发送者被阻止 | `openclaw pairing list imessage` 或 `openclaw pairing list bluebubbles` | 批准配对，或更新允许列表。 |
| 症状 | 最快检查 | 修复 |
| -------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------- |
| 没有入站事件 | 验证 webhook/服务器可达性和应用权限 | 修复 webhook URL 或 BlueBubbles 服务器状态。 |
| 在 macOS 上可以发送但不能接收 | 检查 Messages 自动化的 macOS 隐私权限 | 重新授予 TCC 权限并重启渠道进程。 |
| 私信发送者被阻止 | `openclaw pairing list imessage` 或 `openclaw pairing list bluebubbles` | 批准配对，或更新允许列表。 |
完整故障排除：
@ -104,40 +105,40 @@ openclaw channels status --probe
## Signal
### Signal 故障特征
### Signal 失败特征
| 现象 | 最快检查 | 修复 |
| ---------------------------- | ------------------------------------------ | --------------------------------------------------------- |
| 守护进程可达但机器人静默 | `openclaw channels status --probe` | 验证 `signal-cli` 守护进程 URL/账户和接收模式。 |
| 私信被阻止 | `openclaw pairing list signal` | 批准发送者，或调整私信策略。 |
| 群组回复未触发 | 检查群组允许列表和提及模式 | 添加发送者/群组，或放宽门控。 |
| 症状 | 最快检查 | 修复 |
| ------------------------------- | ------------------------------------------ | -------------------------------------------------------- |
| 守护进程可达但机器人静默 | `openclaw channels status --probe` | 验证 `signal-cli` 守护进程 URL/账户和接收模式。 |
| 私信被阻止 | `openclaw pairing list signal` | 批准发送者，或调整私信策略。 |
| 群组回复未触发 | 检查群组允许列表和提及模式 | 添加发送者/群组，或放宽门控。 |
完整故障排除：[Signal 故障排除](/zh-CN/channels/signal#troubleshooting)
## QQ Bot
### QQ Bot 故障特征
### QQ Bot 失败特征
| 现象 | 最快检查 | 修复 |
| 症状 | 最快检查 | 修复 |
| ------------------------------- | ------------------------------------------- | --------------------------------------------------------------- |
| 机器人回复“gone to Mars” | 验证配置中的 `appId` 和 `clientSecret` | 设置凭证或重启 Gateway 网关。 |
| 没有入站消息 | `openclaw channels status --probe` | 在 QQ Open Platform 上验证凭证。 |
| 语音未转写 | 检查 STT 提供商配置 | 配置 `channels.qqbot.stt` 或 `tools.media.audio`。 |
| 主动消息未到达 | 检查 QQ 平台交互要求 | 如果近期没有交互，QQ 可能会阻止机器人发起的消息。 |
| 机器人回复 “gone to Mars” | 验证配置中的 `appId` 和 `clientSecret` | 设置凭证，或重启 Gateway 网关。 |
| 没有入站消息 | `openclaw channels status --probe` | 在 QQ Open Platform 上验证凭证。 |
| 语音未转写 | 检查 STT 提供商配置 | 配置 `channels.qqbot.stt` 或 `tools.media.audio`。 |
| 主动消息未送达 | 检查 QQ 平台交互要求 | 如果近期没有交互，QQ 可能会阻止机器人发起的消息。 |
完整故障排除：[QQ Bot 故障排除](/zh-CN/channels/qqbot#troubleshooting)
## Matrix
### Matrix 故障特征
### Matrix 失败特征
| 现象 | 最快检查 | 修复 |
| 症状 | 最快检查 | 修复 |
| ----------------------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
| 已登录但忽略房间消息 | `openclaw channels status --probe` | 检查 `groupPolicy`、房间允许列表和提及门控。 |
| 私信不处理 | `openclaw pairing list matrix` | 批准发送者，或调整私信策略。 |
| 加密房间失败 | `openclaw matrix verify status` | 重新验证设备，然后检查 `openclaw matrix verify backup status`。 |
| 备份恢复处于待处理/损坏状态 | `openclaw matrix verify backup status` | 运行 `openclaw matrix verify backup restore`，或带恢复密钥重新运行。 |
| 交叉签名/bootstrap 看起来异常 | `openclaw matrix verify bootstrap` | 一次性修复秘密存储、交叉签名和备份状态。 |
| 已登录但忽略房间消息 | `openclaw channels status --probe` | 检查 `groupPolicy`、房间允许列表和提及门控。 |
| 私信未处理 | `openclaw pairing list matrix` | 批准发送者，或调整私信策略。 |
| 加密房间失败 | `openclaw matrix verify status` | 重新验证设备，然后检查 `openclaw matrix verify backup status`。 |
| 备份恢复处于待处理/损坏状态 | `openclaw matrix verify backup status` | 运行 `openclaw matrix verify backup restore`，或使用恢复密钥重新运行。 |
| 交叉签名/引导看起来不正确 | `openclaw matrix verify bootstrap` | 一次性修复密钥存储、交叉签名和备份状态。 |
完整设置和配置：[Matrix](/zh-CN/channels/matrix)

159
docs/zh-CN/concepts/progress-drafts.md
View File

@ -1,32 +1,36 @@
---
read_when:
- 为长时间运行的聊天轮次配置可见进度更新
- 在部分流式传输、分块流式传输和进度流式传输模式之间选择
- 说明 OpenClaw 如何在工作进行期间更新一条渠道消息
- 进度草稿、独立进度消息或最终化回退的故障排除
summary: 进度草稿：一条可见的进行中消息，会在智能体运行期间更新
- 为长时间运行的聊天轮次配置可见的进度更新
- 在部分、分块和进度流式传输模式之间选择
- 说明 OpenClaw 如何在工作进行时更新一条渠道消息
- 故障排除：进度草稿、独立进度消息或最终化回退
summary: 进度草稿：一条可见的进行中消息，会在智能体运行时更新
title: 进度草稿
x-i18n:
generated_at: "2026-05-03T23:54:52Z"
generated_at: "2026-05-04T00:47:10Z"
model: gpt-5.5
provider: openai
source_hash: 079d4b63554fee0fc968027195d2707f2f0a16fa527b0ec81f88baedfe809c1e
source_hash: 8ce19262800f1c3c3e505a3cf1d41ed5c3dffcbca168ad7b7afabdce62eee8fe
source_path: concepts/progress-drafts.md
workflow: 16
---
进度草稿让长时间运行的智能体轮次在聊天中显得仍在活动，而不会把对话变成一叠临时状态回复。
进度草稿让长时间运行的智能体轮次在聊天中显得有响应，而不会把
对话变成一堆临时状态回复。
启用进度草稿后，OpenClaw 只会在该轮次证明自己正在执行实际工作后创建一条可见的进行中消息，在智能体读取、规划、调用工具或等待批准时更新它，然后在渠道可以安全执行时，将该草稿转换为最终回答。
启用进度草稿后，OpenClaw 只会在轮次证明自己正在执行实际工作后创建一条可见的进行中
消息，在智能体读取、规划、调用工具或等待批准时更新它，然后在渠道可以安全执行时，将该草稿
转换为最终回答。
```text
Shelling...
- reading recent channel context
- checking matching issues
- preparing reply
📖 Read: from docs/concepts/progress-drafts.md
🔎 Web Search: for "discord edit message"
🛠️ Exec: run tests
```
当你希望在工具密集型工作期间只显示一条整洁的状态消息，并在轮次完成后显示最终回答时，请使用进度草稿。
当你希望在工具密集型工作期间显示一条整洁的状态消息，并在轮次完成时显示最终回答时，
请使用进度草稿。
## 快速开始
@ -44,41 +48,55 @@ Shelling...
}
```
这通常就足够了。OpenClaw 会自动选择一个单词标签，等到工作持续至少五秒或发出第二个工作事件后，随着有用工作发生添加紧凑的进度行，并在该轮次中抑制重复的独立进度闲聊。
这通常就足够了。OpenClaw 会选择一个自动的单词标签，等待
工作持续至少五秒或发出第二个工作事件，在有用工作发生时添加紧凑的
进度行，并抑制该轮次中重复的独立进度闲聊。
## 用户看到的内容
## 用户会看到什么
进度草稿包含两个部分：
进度草稿由两部分组成：
| 部分 | 目的 |
| 部分 | 用途 |
| -------------- | --------------------------------------------------------------------------- |
| 标签 | 短标题，例如 `Thinking...` 或 `Shelling...`。 |
| 进度行 | 使用与详细输出相同工具标签和图标的紧凑运行更新。 |
| 标签 | 简短标题，例如 `Thinking...` 或 `Shelling...`。 |
| 进度行 | 使用与详细输出相同的工具标签和图标的紧凑运行更新。 |
标签会在智能体开始有意义的工作后出现，并且工作持续五秒或发出第二个工作事件时显示。纯文本回复不会显示进度草稿。只有在智能体发出有用的工作更新时才会添加进度行，例如 `🛠️ Exec`、`🔎 Web Search` 或 `✍️ Write: to /tmp/file`。如果可能，最终回答会替换草稿；否则 OpenClaw 会正常发送最终回答，并根据渠道的传输方式清理草稿或停止更新草稿。
标签会在智能体开始有意义的工作，并且保持忙碌五秒或发出第二个工作事件后出现。纯文本回复不会
显示进度草稿。只有当智能体发出有用的
工作更新时，才会添加进度行，例如 `🛠️ Exec`、`🔎 Web Search` 或 `✍️ Write: to /tmp/file`。
默认情况下，它们使用与 `/verbose` 相同的紧凑解释模式；当调试并且你也希望附加原始
命令/详情时，请设置 `agents.defaults.toolProgressDetail: "raw"`。
最终回答会在可能时替换草稿；否则
OpenClaw 会正常发送最终回答，并根据渠道的传输协议清理或停止更新
草稿。
## 选择模式
`channels.<channel>.streaming.mode` 控制可见的进行中行为：
| 模式 | 最适合 | 聊天中显示的内容 |
| 模式 | 最适合 | 聊天中会出现什么 |
| ---------- | -------------------------------- | ------------------------------------------------- |
| `off` | 安静渠道 | 只有最终回答。 |
| `partial` | 观察回答文本出现 | 一个用最新回答文本编辑的草稿。 |
| `block` | 更大的回答预览分块 | 一个以更大分块更新或追加的预览。 |
| `progress` | 工具密集型或长时间运行的轮次 | 一个状态草稿，然后是最终回答。 |
| `off` | 安静渠道 | 只有最终回答。 |
| `partial` | 观看回答文本出现 | 一个用最新回答文本编辑的草稿。 |
| `block` | 更大的回答预览分块 | 一个以更大分块更新或追加的预览。 |
| `progress` | 工具密集型或长时间运行的轮次 | 一条状态草稿，然后是最终回答。 |
当用户更关心“正在发生什么”，而不是逐 token 观看回答文本流式输出时，请选择 `progress`。
当用户更关心“正在发生什么”，而不是逐 token 观看
回答文本流式输出时，请选择 `progress`。
当回答本身就是进度信号时，请选择 `partial`。
当你想以更大的文本分块进行草稿预览更新时，请选择 `block`。在 Discord 和 Telegram 上，`streaming.mode: "block"` 仍然是预览流式传输，而不是普通分块交付。当你想要普通分块回复时，请使用 `streaming.block.enabled` 或旧版 `blockStreaming`。
当你希望以更大的文本块更新草稿预览时，请选择 `block`。在
Discord 和 Telegram 上，`streaming.mode: "block"` 仍然是预览流式传输，而不是
普通的分块交付。当你希望使用普通分块回复时，请使用 `streaming.block.enabled` 或旧版
`blockStreaming`。
## 配置标签
进度标签位于 `channels.<channel>.streaming.progress` 下。
默认标签是 `auto`，它会从 OpenClaw 内置的带省略号单词标签池中选择：
默认标签是 `auto`，它会从 OpenClaw 内置的
带省略号的单词标签池中选择：
```text
Thinking...
@ -157,9 +175,34 @@ Surfacing...
## 控制进度行
在进度模式中，进度行默认启用。它们来自真实的运行事件：工具启动、项目更新、任务计划、批准、命令输出、补丁摘要，以及类似的智能体活动。
进度行在进度模式中默认启用。它们来自真实的运行
事件：工具启动、条目更新、任务计划、批准、命令输出、补丁
摘要，以及类似的智能体活动。
限制保留可见的行数：
OpenClaw 对进度草稿和 `/verbose` 使用相同的格式化器：
```json5
{
agents: {
defaults: {
toolProgressDetail: "explain", // explain | raw
},
},
}
```
`"explain"` 是默认值，会使用类似
`🛠️ Exec: check JS syntax for /tmp/app.js` 的简洁标签来保持草稿稳定。`"raw"` 会在可用时附加底层
命令/详情，这在调试时有用，但在聊天中更嘈杂。
例如，同一条命令会根据详情模式以不同方式显示：
| 模式 | 进度行 |
| --------- | -------------------------------------------------------------------- |
| `explain` | `🛠️ Exec: check JS syntax for /tmp/app.js` |
| `raw` | `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js` |
限制保持可见的行数：
```json5
{
@ -176,7 +219,7 @@ Surfacing...
}
```
保留单个进度草稿，但隐藏工具和任务行：
保留单条进度草稿，但隐藏工具和任务行：
```json5
{
@ -193,54 +236,68 @@ Surfacing...
}
```
使用 `toolProgress: false` 时，OpenClaw 仍会在该轮次中抑制较旧的独立工具进度消息。除了已配置的标签外，渠道在视觉上会保持安静，直到最终回答出现。
使用 `toolProgress: false` 时，OpenClaw 仍会抑制该轮次中较旧的独立
工具进度消息。除了已配置的标签之外，渠道在最终回答出现前会保持视觉上的安静。
## 渠道行为
每个渠道都会使用其支持的最干净传输方式：
| 渠道 | 进度传输 | 备注 |
| 渠道 | 进度传输方式 | 说明 |
| --------------- | -------------------------------------- | --------------------------------------------------------------------- |
| Discord | 发送一条消息，然后编辑它。 | 当最终文本适合一条安全预览消息时，会原地编辑。 |
| Matrix | 发送一个事件，然后编辑它。 | 账户级流式传输配置控制账户级草稿。 |
| Microsoft Teams | 个人聊天中的原生 Teams 流。 | `streaming.mode: "block"` 映射到 Teams 分块交付。 |
| Slack | 原生流或可编辑草稿帖子。 | 线程可用性会影响是否可以使用原生流式传输。 |
| Telegram | 发送一条消息，然后编辑它。 | 较早的可见草稿可能会被替换，以便最终时间戳保持有用。 |
| Mattermost | 可编辑草稿帖子。 | 工具活动会折叠进同一个草稿式帖子。 |
| Discord | 发送一条消息，然后编辑它。 | 当最终文本适合一条安全预览消息时，会原地编辑。 |
| Matrix | 发送一个事件，然后编辑它。 | 账号级流式传输配置控制账号级草稿。 |
| Microsoft Teams | 在个人聊天中使用原生 Teams 流。 | `streaming.mode: "block"` 映射到 Teams 分块交付。 |
| Slack | 原生流或可编辑的草稿帖子。 | 线程可用性会影响是否可以使用原生流式传输。 |
| Telegram | 发送一条消息，然后编辑它。 | 较旧的可见草稿可能会被替换，以便最终时间戳保持有用。 |
| Mattermost | 可编辑的草稿帖子。 | 工具活动会折叠到同一个草稿样式的帖子中。 |
没有安全编辑支持的渠道通常会回退到输入指示器或仅最终交付。
不支持安全编辑的渠道通常会回退到正在输入指示器或仅最终回答交付。
## 最终化
## 完成
当最终回答准备好时，OpenClaw 会尝试保持聊天整洁：
当最终回答准备就绪时，OpenClaw 会尝试保持聊天干净：
- 如果草稿可以安全地变成最终回答，OpenClaw 会原地编辑它。
- 如果渠道使用原生进度流式传输，OpenClaw 会在原生传输接受最终文本时最终化该流。
- 如果最终回答包含媒体、批准提示、显式回复目标、过多分块，或编辑/发送失败，OpenClaw 会通过普通渠道交付路径发送最终回答。
- 如果渠道使用原生进度流式传输，OpenClaw 会在原生传输接受最终文本时
完成该流。
- 如果最终回答包含媒体、批准提示、显式回复目标、
过多分块，或编辑/发送失败，OpenClaw 会通过
正常渠道交付路径发送最终回答。
回退路径是有意设计的。发送一条新的最终回答，比丢失文本、把回复发错线程，或用渠道无法安全表示的载荷覆盖草稿更好。
回退路径是有意设计的。发送一条新的最终回答，比
丢失文本、把回复发到错误线程，或用渠道无法安全表示的载荷覆盖草稿更好。
## 故障排除
**我只看到最终回答。**
检查处理该消息的账户或渠道是否已将 `channels.<channel>.streaming.mode` 设置为 `progress`。当渠道无法安全编辑正确消息时，某些群组或引用回复路径可能会禁用该轮次的草稿预览。
检查 `channels.<channel>.streaming.mode` 是否已为处理该消息的
账号或渠道设置为 `progress`。当渠道无法安全编辑正确的
消息时，某些群组或引用回复路径可能会为该轮次禁用草稿预览。
**我看到标签，但没有工具行。**
检查 `streaming.progress.toolProgress`。如果它是 `false`，OpenClaw 会保留单草稿行为，但隐藏工具和任务进度行。
检查 `streaming.progress.toolProgress`。如果它是 `false`，OpenClaw 会保留
单条草稿行为，但隐藏工具和任务进度行。
**我看到的是一条新的最终消息，而不是编辑后的草稿。**
**我看到一条新的最终消息，而不是编辑后的草稿。**
这是安全回退。媒体回复、长回答、显式回复目标、旧 Telegram 草稿、缺失的 Slack 线程目标、已删除的预览消息，或原生流最终化失败，都可能导致这种情况。
这是安全回退。媒体回复、长回答、
显式回复目标、旧的 Telegram 草稿、缺失的 Slack 线程目标、
已删除的预览消息，或原生流完成失败时都可能发生这种情况。
**我仍然看到独立进度消息。**
当草稿处于活动状态时，进度模式会抑制默认的独立工具进度消息。如果仍然出现独立消息，请确认该轮次确实在使用进度模式，而不是 `streaming.mode: "off"`，也不是某条无法为该消息创建草稿的渠道路径。
当草稿处于活动状态时，进度模式会抑制默认的独立工具进度消息。如果独立消息仍然出现，请确认该轮次确实
使用进度模式，而不是 `streaming.mode: "off"`，也不是无法为该消息
创建草稿的渠道路径。
**Teams 的行为与 Discord 或 Telegram 不同。**
Microsoft Teams 在个人聊天中使用原生流，而不是通用的发送并编辑预览传输。Teams 还会把 `streaming.mode: "block"` 视为 Teams 分块交付，因为它没有 Discord 和 Telegram 所使用的同类草稿预览分块模式。
Microsoft Teams 在个人聊天中使用原生流，而不是通用的
发送并编辑预览传输。Teams 还会将 `streaming.mode: "block"` 视为
Teams 分块交付，因为它没有 Discord 和 Telegram 使用的相同草稿预览分块模式。
## 相关

442
docs/zh-CN/gateway/config-agents.md
View File

@ -1,22 +1,20 @@
---
read_when:
- 调优智能体默认设置（模型、思考、工作区、Heartbeat、媒体、Skills）
- 调整智能体默认设置（模型、思考、工作区、Heartbeat、媒体、Skills）
- 配置多智能体路由和绑定
- 调整会话、消息投递和对话模式行为
summary: 智能体默认值、多智能体路由、会话、消息和 talk 配置
summary: 智能体默认值、多智能体路由、会话、消息和对话配置
title: 配置 — 智能体
x-i18n:
generated_at: "2026-05-04T00:38:26Z"
generated_at: "2026-05-04T00:47:08Z"
model: gpt-5.5
provider: openai
source_hash: c8df30ca5d52754d85dc50f9df0832c74f09031361a75a17013a73423b8ee03d
source_hash: 9d339b82b8b3b82e55820ca6568b3ed569fe64135e698515fa7f316c3afbbfd9
source_path: gateway/config-agents.md
workflow: 16
---
`agents.*`、`multiAgent.*`、`session.*`、
`messages.*` 和 `talk.*` 下的智能体作用域配置键。关于渠道、工具、Gateway 网关运行时和其他
顶层键，请参阅[配置参考](/zh-CN/gateway/configuration-reference)。
`agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下的智能体级配置键。对于渠道、工具、Gateway 网关运行时以及其他顶层键，请参阅[配置参考](/zh-CN/gateway/configuration-reference)。
## 智能体默认值
@ -32,7 +30,7 @@ x-i18n:
### `agents.defaults.repoRoot`
可选的仓库根目录，会显示在系统提示的 Runtime 行中。如果未设置，OpenClaw 会从工作区开始向上遍历自动检测。
系统提示词的 Runtime 行中显示的可选仓库根目录。如果未设置，OpenClaw 会从工作区向上遍历并自动检测。
```json5
{
@ -42,7 +40,7 @@ x-i18n:
### `agents.defaults.skills`
对于未设置 `agents.list[].skills` 的智能体，可选的默认技能允许列表。
不设置 `agents.list[].skills` 的智能体使用的可选默认技能允许列表。
```json5
{
@ -57,10 +55,10 @@ x-i18n:
}
```
- 省略 `agents.defaults.skills` 时，默认不限制技能。
- 省略 `agents.list[].skills` 时，会继承默认值。
- 设置 `agents.list[].skills: []` 表示不启用技能。
- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。
- 默认情况下省略 `agents.defaults.skills` 表示不限制技能。
- 省略 `agents.list[].skills` 以继承默认值。
- 设置 `agents.list[].skills: []` 表示没有技能。
- 非空的 `agents.list[].skills` 列表是该智能体的最终集合；它不会与默认值合并。
### `agents.defaults.skipBootstrap`
@ -88,10 +86,10 @@ x-i18n:
### `agents.defaults.contextInjection`
控制何时将工作区引导文件注入系统提示。默认值：`"always"`。
控制何时将工作区引导文件注入系统提示词。默认值：`"always"`。
- `"continuation-skip"`：安全的续接轮次（在已完成的助手响应之后）会跳过重新注入工作区引导内容，从而减小提示大小。Heartbeat 运行和压缩后的重试仍会重建上下文。
- `"never"`：在每个轮次都禁用工作区引导和上下文文件注入。仅对完全自行管理提示生命周期的智能体使用此项（自定义上下文引擎、构建自身上下文的原生运行时，或不需要引导的专用工作流）。Heartbeat 和压缩恢复轮次也会跳过注入。
- `"continuation-skip"`：安全的延续轮次（在一次完整的助手回复之后）会跳过工作区引导重新注入，从而减小提示词大小。Heartbeat 运行和压缩后的重试仍会重建上下文。
- `"never"`：在每个轮次都禁用工作区引导和上下文文件注入。仅将此用于完全自行拥有提示词生命周期的智能体（自定义上下文引擎、构建自身上下文的原生运行时，或专用的无引导工作流）。Heartbeat 和压缩恢复轮次也会跳过注入。
```json5
{
@ -111,7 +109,7 @@ x-i18n:
### `agents.defaults.bootstrapTotalMaxChars`
所有工作区引导文件注入的总最大字符数。默认值：`60000`。
所有工作区引导文件中注入的总字符数上限。默认值：`60000`。
```json5
{
@ -121,14 +119,14 @@ x-i18n:
### `agents.defaults.bootstrapPromptTruncationWarning`
控制引导上下文被截断时，智能体可见的系统提示通知。
控制引导上下文被截断时智能体可见的系统提示词通知。
默认值：`"once"`。
- `"off"`：绝不向系统提示注入截断通知文本。
- `"once"`：每个唯一的截断签名只注入一次简短通知（推荐）。
- `"always"`：只要存在截断，就在每次运行时注入简短通知。
- `"off"`：从不将截断通知文本注入系统提示词。
- `"once"`：每个唯一截断签名注入一次简短通知（推荐）。
- `"always"`：存在截断时，每次运行都注入简短通知。
详细的原始/已注入计数和配置调优字段会保留在上下文/Status 报告和日志等诊断信息中；常规 WebChat 用户/运行时上下文只会获得简短的恢复通知。
详细的原始/注入计数和配置调优字段会保留在诊断信息中，例如上下文/状态报告和日志；常规 WebChat 用户/运行时上下文只会获得简短的恢复通知。
```json5
{
@ -136,30 +134,30 @@ x-i18n:
}
```
### 上下文预算归属图
### 上下文预算所有权映射
OpenClaw 有多个高容量提示/上下文预算，它们有意按子系统拆分，而不是全部流经一个通用开关。
OpenClaw 有多个高容量提示词/上下文预算，并且它们有意按子系统拆分，而不是全部流经一个通用旋钮。
- `agents.defaults.bootstrapMaxChars` /
`agents.defaults.bootstrapTotalMaxChars`：
常规工作区引导注入。
- `agents.defaults.startupContext.*`：
一次性的重置/启动模型运行前奏，包括最近的每日 `memory/*.md` 文件。纯聊天 `/new` 和 `/reset` 命令会在不调用模型的情况下确认重置。
一次性重置/启动模型运行前奏，包括最近的每日 `memory/*.md` 文件。裸聊天 `/new` 和 `/reset` 命令会在不调用模型的情况下确认重置。
- `skills.limits.*`：
注入系统提示的紧凑 Skills 列表。
注入系统提示词的紧凑 Skills 列表。
- `agents.defaults.contextLimits.*`：
有界运行时摘录和注入的运行时自有块。
有界运行时摘录和注入的运行时拥有块。
- `memory.qmd.limits.*`：
已索引记忆搜索片段和注入大小。
索引记忆搜索片段和注入大小。
仅当某个智能体需要不同预算时，才使用匹配的每智能体覆盖项：
仅当某个智能体需要不同预算时，才使用匹配的每智能体覆盖：
- `agents.list[].skillsLimits.maxSkillsPromptChars`
- `agents.list[].contextLimits.*`
#### `agents.defaults.startupContext`
控制重置/启动模型运行时注入的首轮启动前奏。纯聊天 `/new` 和 `/reset` 命令会在不调用模型的情况下确认重置，因此不会加载此前奏。
控制在重置/启动模型运行时注入的首轮启动前奏。裸聊天 `/new` 和 `/reset` 命令会在不调用模型的情况下确认重置，因此它们不会加载此前奏。
```json5
{
@ -197,14 +195,14 @@ OpenClaw 有多个高容量提示/上下文预算，它们有意按子系统拆
}
```
- `memoryGetMaxChars`：添加截断元数据和续接通知前，默认的 `memory_get` 摘录上限。
- `memoryGetDefaultLines`：省略 `lines` 时，默认的 `memory_get` 行窗口。
- `memoryGetMaxChars`：添加截断元数据和延续通知前，默认 `memory_get` 摘录上限。
- `memoryGetDefaultLines`：省略 `lines` 时默认的 `memory_get` 行窗口。
- `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。
- `postCompactionMaxChars`：压缩后刷新注入期间使用的 AGENTS.md 摘录上限。
#### `agents.list[].contextLimits`
共享 `contextLimits` 开关的每智能体覆盖项。省略的字段会继承自 `agents.defaults.contextLimits`。
共享 `contextLimits` 旋钮的每智能体覆盖。省略的字段会从 `agents.defaults.contextLimits` 继承。
```json5
{
@ -230,7 +228,7 @@ OpenClaw 有多个高容量提示/上下文预算，它们有意按子系统拆
#### `skills.limits.maxSkillsPromptChars`
注入系统提示的紧凑 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。
注入系统提示词的紧凑 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。
```json5
{
@ -244,7 +242,7 @@ OpenClaw 有多个高容量提示/上下文预算，它们有意按子系统拆
#### `agents.list[].skillsLimits.maxSkillsPromptChars`
Skills 提示预算的每智能体覆盖项。
技能提示词预算的每智能体覆盖。
```json5
{
@ -263,10 +261,10 @@ Skills 提示预算的每智能体覆盖项。
### `agents.defaults.imageMaxDimensionPx`
在调用提供商之前，转录/工具图像块中图像最长边的最大像素尺寸。
在 provider 调用前，转录/工具图像块中图像最长边的最大像素尺寸。
默认值：`1200`。
较低的值通常会降低截图密集型运行的视觉 token 用量和请求载荷大小。
较低的值通常会减少截图密集型运行的视觉 token 用量和请求载荷大小。
较高的值会保留更多视觉细节。
```json5
@ -277,7 +275,7 @@ Skills 提示预算的每智能体覆盖项。
### `agents.defaults.userTimezone`
系统提示上下文的时区（不是消息时间戳）。回退到主机时区。
系统提示词上下文使用的时区（不是消息时间戳）。回退到主机时区。
```json5
{
@ -287,7 +285,7 @@ Skills 提示预算的每智能体覆盖项。
### `agents.defaults.timeFormat`
系统提示中的时间格式。默认值：`auto`（操作系统偏好）。
系统提示词中的时间格式。默认值：`auto`（操作系统偏好）。
```json5
{
@ -333,6 +331,7 @@ Skills 提示预算的每智能体覆盖项。
pdfMaxPages: 20,
thinkingDefault: "low",
verboseDefault: "off",
toolProgressDetail: "explain",
reasoningDefault: "off",
elevatedDefault: "on",
timeoutSeconds: 600,
@ -346,57 +345,54 @@ Skills 提示预算的每智能体覆盖项。
- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 字符串形式只设置主模型。
- 对象形式设置主模型以及按顺序排列的故障转移模型。
- 对象形式设置主模型以及有序故障转移模型。
- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 被 `image` 工具路径用作其视觉模型配置。
- 当所选/默认模型无法接受图像输入时，也用作回退路由。
- 优先使用显式 `provider/model` 引用。为兼容性也接受裸 ID；如果某个裸 ID 能唯一匹配 `models.providers.*.models` 中已配置且支持图像的条目，OpenClaw 会将其限定到该提供商。已配置匹配存在歧义时，需要显式提供商前缀。
- 优先使用显式 `provider/model` 引用。为兼容性也接受裸 ID；如果某个裸 ID 唯一匹配 `models.providers.*.models` 中已配置且支持图像的条目，OpenClaw 会将其限定到该提供商。已配置的匹配项存在歧义时，需要显式提供商前缀。
- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 被共享图像生成能力以及未来任何生成图像的工具/插件界面使用。
- 被共享图像生成能力以及任何未来会生成图像的工具/插件表面使用。
- 典型值：用于原生 Gemini 图像生成的 `google/gemini-3.1-flash-image-preview`、用于 fal 的 `fal/fal-ai/flux/dev`、用于 OpenAI Images 的 `openai/gpt-image-2`，或用于透明背景 OpenAI PNG/WebP 输出的 `openai/gpt-image-1.5`。
- 如果你直接选择提供商/模型，也要配置匹配的提供商凭证（例如用于 `google/*` 的 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，用于 `openai/gpt-image-2` / `openai/gpt-image-1.5` 的 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，用于 `fal/*` 的 `FAL_KEY`）。
- 如果省略，`image_generate` 仍可推断有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。
- 如果你直接选择提供商/模型，也要配置匹配的提供商身份验证（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` / `openai/gpt-image-1.5` 使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 使用 `FAL_KEY`）。
- 如果省略，`image_generate` 仍可推断由身份验证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。
- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 被共享音乐生成能力和内置 `music_generate` 工具使用。
- 被共享音乐生成能力以及内置 `music_generate` 工具使用。
- 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.6`。
- 如果省略，`music_generate` 仍可推断有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。
- 如果你直接选择提供商/模型，也要配置匹配的提供商凭证/API key。
- 如果省略，`music_generate` 仍可推断由身份验证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。
- 如果你直接选择提供商/模型，也要配置匹配的提供商身份验证/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 顺序尝试其余已注册的视频生成提供商。
- 如果你直接选择提供商/模型，也要配置匹配的提供商凭证/API key。
- 如果省略，`video_generate` 仍可推断由身份验证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。
- 如果你直接选择提供商/模型，也要配置匹配的提供商身份验证/API key。
- 内置 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。
- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 被 `pdf` 工具用于模型路由。
- 如果省略，PDF 工具会回退到 `imageModel`，再回退到解析后的会话/默认模型。
- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。
- 如果省略，PDF 工具会回退到 `imageModel`，然后回退到解析后的会话/默认模型。
- `pdfMaxBytesMb`：在调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。
- `pdfMaxPages`：`pdf` 工具中提取回退模式会考虑的默认最大页数。
- `verboseDefault`：智能体的默认详细程度。值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。
- `reasoningDefault`：智能体的默认推理可见性。值：`"off"`、`"on"`、`"stream"`。每个智能体的 `agents.list[].reasoningDefault` 会覆盖此默认值。配置的推理默认值只会在没有设置每条消息或会话推理覆盖时，应用于所有者、已授权发送者或 operator-admin Gateway 网关上下文。
- `verboseDefault`：智能体的默认详细级别。值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。
- `toolProgressDetail`：`/verbose` 工具摘要和进度草稿工具行的详细模式。值：`"explain"`（默认，紧凑的人类可读标签）或 `"raw"`（可用时附加原始命令/详情）。按智能体设置的 `agents.list[].toolProgressDetail` 会覆盖此默认值。
- `reasoningDefault`：智能体的默认推理可见性。值：`"off"`、`"on"`、`"stream"`。按智能体设置的 `agents.list[].reasoningDefault` 会覆盖此默认值。已配置的推理默认值仅在未设置按消息或会话推理覆盖项时，应用于所有者、已授权发送者或 operator-admin gateway 上下文。
- `elevatedDefault`：智能体的默认提升输出级别。值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。
- `model.primary`：格式为 `provider/model`（例如，使用 API key 访问时为 `openai/gpt-5.5`，使用 Codex OAuth 时为 `openai-codex/gpt-5.5`）。如果省略提供商，OpenClaw 会先尝试别名，再尝试该精确模型 ID 的唯一已配置提供商匹配，最后才回退到已配置的默认提供商（这是已弃用的兼容性行为，因此优先使用显式 `provider/model`）。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露过时的已移除提供商默认值。
- `models`：已配置的模型目录和 `/model` 允许列表。每个条目可包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`chat_template_kwargs`、`extra_body`/`extraBody`）。
- `model.primary`：格式为 `provider/model`（例如，用于 API key 访问的 `openai/gpt-5.5`，或用于 Codex OAuth 的 `openai-codex/gpt-5.5`）。如果省略提供商，OpenClaw 会先尝试别名，然后尝试该精确模型 ID 的唯一已配置提供商匹配项，只有在此之后才会回退到已配置的默认提供商（已弃用的兼容行为，因此请优先使用显式 `provider/model`）。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露过时的已移除提供商默认值。
- `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`chat_template_kwargs`、`extra_body`/`extraBody`）。
- 安全编辑：使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加条目。除非传入 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换。
- 按提供商限定的配置/新手引导流程会将所选提供商模型合并进此映射，并保留已配置的无关提供商。
- 按提供商限定的配置/新手引导流程会将所选提供商模型合并到此映射中，并保留已配置的无关提供商。
- 对于直接 OpenAI Responses 模型，会自动启用服务器端压缩。使用 `params.responsesServerCompaction: false` 停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务器端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。
- `params`：应用于所有模型的全局默认提供商参数。设置在 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。
- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配的智能体 ID）会按键覆盖。详情参见 [Prompt Caching](/zh-CN/reference/prompt-caching)。
- `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并进 OpenAI 兼容代理的 `api: "openai-completions"` 请求体。如果它与生成的请求键冲突，额外请求体优先；非原生 completions 路由之后仍会剥离仅 OpenAI 支持的 `store`。
- `params.chat_template_kwargs`：vLLM/OpenAI 兼容聊天模板参数，会合并进顶层 `api: "openai-completions"` 请求体。对于关闭思考的 `vllm/nemotron-3-*`，内置 vLLM 插件会自动发送 `enable_thinking: false` 和 `force_nonempty_content: true`；显式 `chat_template_kwargs` 会覆盖生成的默认值，而 `extra_body.chat_template_kwargs` 仍具有最终优先级。对于 vLLM Qwen 思考控制，请在该模型条目上将 `params.qwenThinkingFormat` 设置为 `"chat-template"` 或 `"top-level"`。
- `compat.supportedReasoningEfforts`：每个模型的 OpenAI 兼容推理强度列表。对于确实接受它的自定义端点，包含 `"xhigh"`；随后 OpenClaw 会在命令菜单、Gateway 网关会话行、会话补丁验证、智能体 CLI 验证，以及该已配置提供商/模型的 `llm-task` 验证中公开 `/think xhigh`。当后端需要某个规范级别的提供商特定值时，使用 `compat.reasoningEffortMap`。
- `params.preserveThinking`：仅 Z.AI 的保留思考选择加入项。启用且思考开启时，OpenClaw 会发送 `thinking.clear_thinking: false` 并重放先前的 `reasoning_content`；参见 [Z.AI 思考和保留思考](/zh-CN/providers/zai#thinking-and-preserved-thinking)。
- `agentRuntime`：默认低级智能体运行时策略。省略 id 时默认使用 OpenClaw Pi。使用 `id: "pi"` 强制使用内置 PI harness，使用 `id: "auto"` 让已注册插件 harness 声明支持的模型并在没有匹配时使用 PI，使用已注册 harness id（例如 `id: "codex"`）要求使用该 harness，或使用受支持的 CLI 后端别名（例如 `id: "claude-cli"`）。显式插件运行时会在 harness 不可用或失败时关闭失败。保持模型引用为规范的 `provider/model`；通过运行时配置选择 Codex、Claude CLI、Gemini CLI 和其他执行后端，而不是使用旧版运行时提供商前缀。参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，了解这与提供商/模型选择的区别。
- `params`：应用到所有模型的全局默认提供商参数。设置在 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。
- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配智能体 ID）按键覆盖。详情参见 [提示缓存](/zh-CN/reference/prompt-caching)。
- `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并到 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果它与生成的请求键冲突，额外体优先；非原生 completions 路由随后仍会剥离仅 OpenAI 支持的 `store`。
- `params.chat_template_kwargs`：vLLM/OpenAI 兼容聊天模板参数，会合并到顶层 `api: "openai-completions"` 请求体中。对于关闭 thinking 的 `vllm/nemotron-3-*`，内置 vLLM 插件会自动发送 `enable_thinking: false` 和 `force_nonempty_content: true`；显式 `chat_template_kwargs` 会覆盖生成的默认值，而 `extra_body.chat_template_kwargs` 仍具有最终优先级。对于 vLLM Qwen thinking 控制，请在该模型条目上将 `params.qwenThinkingFormat` 设置为 `"chat-template"` 或 `"top-level"`。
- `compat.supportedReasoningEfforts`：按模型设置的 OpenAI 兼容推理强度列表。对于真正接受它的自定义端点，请包含 `"xhigh"`；随后 OpenClaw 会在命令菜单、Gateway 网关会话行、会话补丁验证、智能体 CLI 验证和该已配置提供商/模型的 `llm-task` 验证中公开 `/think xhigh`。当后端希望为规范级别使用提供商特定值时，请使用 `compat.reasoningEffortMap`。
- `params.preserveThinking`：Z.AI 专用的保留 thinking 选择加入项。启用且 thinking 开启时，OpenClaw 会发送 `thinking.clear_thinking: false` 并重放之前的 `reasoning_content`；参见 [Z.AI thinking 和保留 thinking](/zh-CN/providers/zai#thinking-and-preserved-thinking)。
- `agentRuntime`：默认低层智能体运行时策略。省略的 ID 默认使用 OpenClaw Pi。使用 `id: "pi"` 强制使用内置 PI harness，使用 `id: "auto"` 让已注册的插件 harness 认领受支持的模型并在无匹配时使用 PI，使用已注册的 harness ID（例如 `id: "codex"`）要求使用该 harness，或使用受支持的 CLI 后端别名（例如 `id: "claude-cli"`）。显式插件运行时在 harness 不可用或失败时会关闭失败。请保持模型引用为规范的 `provider/model`；通过运行时配置选择 Codex、Claude CLI、Gemini CLI 和其他执行后端，而不是使用旧版运行时提供商前缀。关于这与提供商/模型选择的区别，参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
- 会改变这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退添加/移除命令）会保存规范对象形式，并尽可能保留现有回退列表。
- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍然串行化）。默认值：4。
### `agents.defaults.agentRuntime`
`agentRuntime` 控制哪个低级执行器运行智能体轮次。大多数
部署应保留默认的 OpenClaw Pi 运行时。当受信任
插件提供原生 harness（例如内置 Codex 应用服务器 harness）时，
或当你需要受支持的 CLI 后端（例如 Claude CLI）时使用它。关于心智
模型，参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
`agentRuntime` 控制哪个低层执行器运行智能体轮次。大多数部署应保留默认 OpenClaw Pi 运行时。当可信插件提供原生 harness（例如内置 Codex app-server harness），或你想使用受支持的 CLI 后端（例如 Claude CLI）时，请使用它。关于心智模型，参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
```json5
{
@ -411,22 +407,22 @@ Skills 提示预算的每智能体覆盖项。
}
```
- `id`：`"auto"`、`"pi"`、已注册插件 harness id，或受支持的 CLI 后端别名。内置 Codex 插件会注册 `codex`；内置 Anthropic 插件提供 `claude-cli` CLI 后端。
- `id: "auto"` 允许已注册插件 harness 声明支持的轮次，并在没有 harness 匹配时使用 PI。显式插件运行时（例如 `id: "codex"`）要求该 harness 存在，并在其不可用或失败时关闭失败。
- `id`：`"auto"`、`"pi"`、已注册的插件 harness ID，或受支持的 CLI 后端别名。内置 Codex 插件注册 `codex`；内置 Anthropic 插件提供 `claude-cli` CLI 后端。
- `id: "auto"` 会让已注册的插件 harness 认领受支持的轮次，并在没有匹配的 harness 时使用 PI。显式插件运行时（例如 `id: "codex"`）要求使用该 harness，并在其不可用或失败时关闭失败。
- 环境覆盖：`OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` 会覆盖该进程的 `id`。
- 对于仅 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `agentRuntime.id: "codex"`。
- 对于 Claude CLI 部署，优先使用 `model: "anthropic/claude-opus-4-7"` 加 `agentRuntime.id: "claude-cli"`。旧版 `claude-cli/claude-opus-4-7` 模型引用仍可用于兼容性，但新配置应保持提供商/模型选择的规范性，并将执行后端放在 `agentRuntime.id`。
- 旧版运行时策略键会由 `openclaw doctor --fix` 重写为 `agentRuntime`。
- 首次嵌入式运行后，harness 选择会按会话 ID 固定。配置/环境更改会影响新的或已重置的会话，不会影响现有 transcript。带有 transcript 历史但未记录固定项的旧版会话会被视为已固定到 PI。`/status` 会报告有效运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。
- 对于 Claude CLI 部署，优先使用 `model: "anthropic/claude-opus-4-7"` 加 `agentRuntime.id: "claude-cli"`。旧版 `claude-cli/claude-opus-4-7` 模型引用仍可兼容使用，但新配置应保持提供商/模型选择为规范形式，并将执行后端放在 `agentRuntime.id` 中。
- 较旧的运行时策略键会由 `openclaw doctor --fix` 重写为 `agentRuntime`。
- 首次嵌入式运行后，harness 选择会按会话 ID 固定。配置/环境更改会影响新的或重置的会话，不会影响现有转录记录。拥有转录历史但没有记录固定项的旧版会话会被视为固定到 PI。`/status` 会报告有效运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。
- 这只控制文本智能体轮次执行。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。
**内置别名简写**（仅在模型位于 `agents.defaults.models` 中时适用）：
**内置别名速记**（仅当模型位于 `agents.defaults.models` 中时适用）：
| 别名 | 模型 |
| ------------------- | ------------------------------------------ |
| `opus` | `anthropic/claude-opus-4-6` |
| `sonnet` | `anthropic/claude-sonnet-4-6` |
| `gpt` | `openai/gpt-5.5` 或 `openai-codex/gpt-5.5` |
| `gpt` | `openai/gpt-5.5` or `openai-codex/gpt-5.5` |
| `gpt-mini` | `openai/gpt-5.4-mini` |
| `gpt-nano` | `openai/gpt-5.4-nano` |
| `gemini` | `google/gemini-3.1-pro-preview` |
@ -436,12 +432,12 @@ Skills 提示预算的每智能体覆盖项。
你配置的别名始终优先于默认值。
Z.AI GLM-4.x 模型会自动启用思考模式，除非你设置 `--thinking off` 或自行定义 `agents.defaults.models["zai/<model>"].params.thinking`。
Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/<model>"].params.tool_stream` 设置为 `false` 可禁用它。
Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `adaptive` 思考。
Z.AI 模型默认启用 `tool_stream`，用于工具调用流式传输。将 `agents.defaults.models["zai/<model>"].params.tool_stream` 设置为 `false` 可禁用它。
Anthropic Claude 4.6 模型在未设置显式思考等级时，默认使用 `adaptive` 思考。
### `agents.defaults.cliBackends`
用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，可作为备用方案。
可选的 CLI 后端，用于纯文本回退运行（无工具调用）。当 API 提供商失败时，可用作备份。
```json5
{
@ -476,7 +472,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
### `agents.defaults.systemPromptOverride`
用固定字符串替换整个由 OpenClaw 组装的系统提示词。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体（`agents.list[].systemPromptOverride`）设置。按智能体设置的值优先；空值或仅包含空白的值会被忽略。适用于受控提示词实验。
用固定字符串替换 OpenClaw 组装的整个系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或每个智能体（`agents.list[].systemPromptOverride`）设置。每个智能体的值优先；空值或仅包含空白的值会被忽略。适用于受控提示实验。
```json5
{
@ -490,7 +486,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
### `agents.defaults.promptOverlays`
按模型系列应用的、与提供商无关的提示词叠加层。GPT-5 系列模型 ID 会跨提供商接收共享行为契约；`personality` 仅控制友好的交互风格层。
按模型系列应用的、与提供商无关的提示覆盖层。GPT-5 系列模型 ID 会在不同提供商之间接收共享行为契约；`personality` 只控制友好的交互风格层。
```json5
{
@ -506,13 +502,13 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
}
```
- `"friendly"`（默认）和 `"on"` 会启用友好的交互风格层。
- `"off"` 仅禁用友好层；带标签的 GPT-5 行为契约仍保持启用。
- 当未设置此共享设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。
- `"friendly"`（默认）和 `"on"` 启用友好的交互风格层。
- `"off"` 只禁用友好层；带标签的 GPT-5 行为契约仍保持启用。
- 未设置此共享设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。
### `agents.defaults.heartbeat`
周期性 Heartbeat 运行。
定期 Heartbeat 运行。
```json5
{
@ -541,15 +537,15 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
```
- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 凭证）或 `1h`（OAuth 凭证）。设置为 `0m` 可禁用。
- `includeSystemPromptSection`：为 false 时，从系统提示词中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入启动上下文。默认值：`true`。
- `includeSystemPromptSection`：为 false 时，从系统提示中省略 Heartbeat 部分，并跳过向引导上下文注入 `HEARTBEAT.md`。默认值：`true`。
- `suppressToolErrorWarnings`：为 true 时，在 Heartbeat 运行期间抑制工具错误警告载荷。
- `timeoutSeconds`：Heartbeat 智能体轮次在被中止前允许的最长秒数。未设置时使用 `agents.defaults.timeoutSeconds`。
- `directPolicy`：直接/私信投递策略。`allow`（默认）允许投递到直接目标。`block` 会抑制投递到直接目标，并发出 `reason=dm-blocked`。
- `lightContext`：为 true 时，Heartbeat 运行使用轻量启动上下文，并且在工作区启动文件中仅保留 `HEARTBEAT.md`。
- `isolatedSession`：为 true 时，每次 Heartbeat 都在没有先前对话历史的新会话中运行。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。将每次 Heartbeat 的 token 成本从约 100K 降至约 2-5K token。
- `skipWhenBusy`：为 true 时，Heartbeat 运行会在额外繁忙的通道上延后：子智能体或嵌套命令工作。即使没有此标志，cron 通道也始终会延后 Heartbeat。
- 按智能体：设置 `agents.list[].heartbeat`。当任何智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 Heartbeat。
- Heartbeat 会运行完整的智能体轮次，间隔越短消耗的 token 越多。
- `timeoutSeconds`：Heartbeat 智能体轮次在中止前允许的最长时间（秒）。未设置时使用 `agents.defaults.timeoutSeconds`。
- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递并发出 `reason=dm-blocked`。
- `lightContext`：为 true 时，Heartbeat 运行使用轻量引导上下文，并且只从工作区引导文件中保留 `HEARTBEAT.md`。
- `isolatedSession`：为 true 时，每次 Heartbeat 都在没有先前对话历史的新会话中运行。隔离模式与 cron `sessionTarget: "isolated"` 相同。将每次 Heartbeat 的 token 成本从约 100K 降至约 2-5K token。
- `skipWhenBusy`：为 true 时，Heartbeat 运行会在额外忙碌通道上延后：子智能体或嵌套命令工作。即使没有此标志，Cron 通道也始终会延后 Heartbeat。
- 每个智能体：设置 `agents.list[].heartbeat`。当任何智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 Heartbeat。
- Heartbeat 会运行完整的智能体轮次——更短的间隔会消耗更多 token。
### `agents.defaults.compaction`
@ -585,19 +581,19 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
}
```
- `mode`：`default` 或 `safeguard`（用于长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。
- `provider`：已注册压缩提供商插件的 ID。设置后，会调用该提供商的 `summarize()`，而不是内置 LLM 摘要。失败时回退到内置实现。设置提供商会强制 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。
- `mode`：`default` 或 `safeguard`（用于长历史的分块摘要）。请参阅 [Compaction](/zh-CN/concepts/compaction)。
- `provider`：已注册的压缩提供商插件 ID。设置后会调用该提供商的 `summarize()`，而不是内置 LLM 摘要。失败时回退到内置摘要。设置提供商会强制 `mode: "safeguard"`。请参阅 [Compaction](/zh-CN/concepts/compaction)。
- `timeoutSeconds`：OpenClaw 中止单次压缩操作前允许的最长秒数。默认值：`900`。
- `keepRecentTokens`：用于逐字保留最近 transcript 尾部的 Pi 切分点预算。手动 `/compact` 在显式设置时会遵循该值；否则手动压缩是一个硬检查点。
- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要期间前置内置的不透明标识符保留指导。
- `keepRecentTokens`：Pi 切点预算，用于逐字保留最近的转录尾部。手动 `/compact` 在显式设置时会遵守此值；否则手动压缩是硬检查点。
- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要期间前置内置的不透明标识符保留指引。
- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。
- `qualityGuard`：针对 safeguard 摘要的格式异常输出重试检查。在 safeguard 模式下默认启用；设置 `enabled: false` 可跳过审计。
- `midTurnPrecheck`：可选 Pi 工具循环压力检查。当 `enabled: true` 时，OpenClaw 会在追加工具结果之后、下一次模型调用之前检查上下文压力。如果上下文不再适配，它会在提交提示词前中止当前尝试，并复用现有的预检查恢复路径来截断工具结果，或执行压缩后重试。适用于 `default` 和 `safeguard` 两种压缩模式。默认：禁用。
- `postCompactionSections`：压缩后要重新注入的可选 AGENTS.md H2/H3 章节名称。默认值为 `["Session Startup", "Red Lines"]`；设置 `[]` 可禁用重新注入。未设置或显式设置为该默认对时，旧版 `Every Session`/`Safety` 标题也会作为兼容回退被接受。
- `model`：仅用于压缩摘要的可选 `provider/model-id` 覆盖。当主会话应保留一个模型，而压缩摘要应在另一个模型上运行时使用；未设置时，压缩使用会话的主模型。
- `maxActiveTranscriptBytes`：可选字节阈值（`number` 或类似 `"20mb"` 的字符串），当活动 JSONL 超过该阈值时，会在运行前触发常规本地压缩。需要 `truncateAfterCompaction`，以便成功压缩后可以轮转到更小的后继 transcript。未设置或为 `0` 时禁用。
- `notifyUser`：为 `true` 时，在压缩开始和完成时向用户发送简短通知（例如，“Compacting context...” 和 “Compaction complete”）。默认禁用，以保持压缩静默。
- `memoryFlush`：自动压缩前的静默智能体轮次，用于存储持久记忆。当此维护轮次应停留在本地模型上时，将 `model` 设置为精确的提供商/模型，例如 `ollama/qwen3:8b`；该覆盖不会继承活动会话的回退链。当工作区为只读时会跳过。
- `qualityGuard`：用于 safeguard 摘要的格式异常输出重试检查。在 safeguard 模式中默认启用；设置 `enabled: false` 可跳过审核。
- `midTurnPrecheck`：可选的 Pi 工具循环压力检查。当 `enabled: true` 时，OpenClaw 会在追加工具结果之后、下一次模型调用之前检查上下文压力。如果上下文已无法容纳，它会在提交提示前中止当前尝试，并复用现有的预检查恢复路径来截断工具结果，或进行压缩后重试。适用于 `default` 和 `safeguard` 两种压缩模式。默认：禁用。
- `postCompactionSections`：压缩后要重新注入的可选 AGENTS.md H2/H3 节名称。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。未设置或显式设置为该默认组合时，也会接受较旧的 `Every Session`/`Safety` 标题作为旧版回退。
- `model`：可选的 `provider/model-id` 覆盖，仅用于压缩摘要。当主会话应保持一个模型、而压缩摘要应在另一个模型上运行时使用；未设置时，压缩使用会话的主模型。
- `maxActiveTranscriptBytes`：可选的字节阈值（`number` 或类似 `"20mb"` 的字符串），当活动 JSONL 超过该阈值时，会在运行前触发普通本地压缩。需要 `truncateAfterCompaction`，以便成功压缩后可轮换到更小的后继转录。未设置或为 `0` 时禁用。
- `notifyUser`：为 `true` 时，在压缩开始和完成时向用户发送简短通知（例如，“正在压缩上下文...”和“压缩完成”）。默认禁用，以保持压缩静默。
- `memoryFlush`：自动压缩前的静默智能体轮次，用于存储持久记忆。当此内务轮次应保持在本地模型上时，将 `model` 设置为精确的提供商/模型，例如 `ollama/qwen3:8b`；该覆盖不会继承活动会话的回退链。当工作区为只读时跳过。
### `agents.defaults.contextPruning`
@ -626,7 +622,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
<Accordion title="cache-ttl 模式行为">
- `mode: "cache-ttl"` 启用修剪过程。
- `ttl` 控制修剪多久可以再次运行（从上次缓存触碰之后算起）。
- `ttl` 控制修剪再次运行的频率（在上次缓存触碰之后）。
- 修剪会先软修剪过大的工具结果，然后在需要时硬清除更旧的工具结果。
**软修剪**会保留开头 + 结尾，并在中间插入 `...`。
@ -636,12 +632,12 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
注意：
- 图像块永远不会被修剪/清除。
- 比率按字符计算（近似），不是精确的 token 数。
- 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过修剪。
- 比例按字符计算（近似），不是精确的 token 数。
- 如果助手消息少于 `keepLastAssistants` 条，则跳过修剪。
</Accordion>
有关行为详情，请参见 [会话修剪](/zh-CN/concepts/session-pruning)。
行为详情请参阅 [Session Pruning](/zh-CN/concepts/session-pruning)。
### 分块流式传输
@ -660,10 +656,10 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
```
- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。
- 渠道覆盖：`channels.<channel>.blockStreamingCoalesce`（以及按账号的变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。
- 渠道覆盖：`channels.<channel>.blockStreamingCoalesce`（以及每账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。每智能体覆盖：`agents.list[].humanDelay`。
有关行为和分块详情，请参见 [Streaming](/zh-CN/concepts/streaming)。
行为 + 分块详情请参阅 [Streaming](/zh-CN/concepts/streaming)。
### 输入指示器
@ -678,16 +674,16 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
}
```
- 默认值：`instant` 用于直接聊天/提及，`message` 用于未提及的群聊。
- 每会话覆盖项：`session.typingMode`、`session.typingIntervalSeconds`。
- 默认值：直接聊天/提及时为 `instant`，未提及的群聊为 `message`。
- 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。
参见 [输入指示器](/zh-CN/concepts/typing-indicators)。
请参阅[输入状态指示器](/zh-CN/concepts/typing-indicators)。
<a id="agentsdefaultssandbox"></a>
### `agents.defaults.sandbox`
嵌入式智能体的可选沙箱隔离。完整指南请参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。
嵌入式智能体的可选沙箱隔离。完整指南请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)。
```json5
{
@ -782,12 +778,12 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
}
```
<Accordion title="沙箱详情">
<Accordion title="Sandbox details">
**后端：**
- `docker`：本地 Docker 运行时（默认）
- `ssh`：通用的 SSH 后端远程运行时
- `ssh`：通用 SSH 支持的远程运行时
- `openshell`：OpenShell 运行时
选择 `backend: "openshell"` 时，运行时特定设置会移至
@ -795,31 +791,31 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
**SSH 后端配置：**
- `target`：采用 `user@host[:port]` 形式的 SSH 目标
- `target`：`user@host[:port]` 形式的 SSH 目标
- `command`：SSH 客户端命令（默认：`ssh`）
- `workspaceRoot`：用于每个范围工作区的绝对远程根目录
- `workspaceRoot`：用于按范围工作区的绝对远程根目录
- `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件
- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在运行时具体化为临时文件的内联内容或 SecretRef
- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略旋钮
- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在运行时物化为临时文件的内联内容或 SecretRefs
- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关
**SSH 凭证优先级：**
- `identityData` 优先于 `identityFile`
- `certificateData` 优先于 `certificateFile`
- `knownHostsData` 优先于 `knownHostsFile`
- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从活动的密钥运行时快照中解析
- 基于 SecretRef 的 `*Data` 值会在沙箱会话启动前，从活动密钥运行时快照中解析
**SSH 后端行为：**
- 创建或重新创建后，会为远程工作区播种一次
- 随后保持远程 SSH 工作区为规范来源
- 创建或重新创建后，对远程工作区执行一次种子初始化
- 然后保持远程 SSH 工作区为权威来源
- 通过 SSH 路由 `exec`、文件工具和媒体路径
- 不会自动将远程更改同步回主机
- 不支持沙箱浏览器容器
**工作区访问：**
- `none`：位于 `~/.openclaw/sandboxes` 下的每范围沙箱工作区
- `none`：`~/.openclaw/sandboxes` 下的按范围沙箱工作区
- `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent`
- `rw`：智能体工作区以读写方式挂载到 `/workspace`
@ -857,30 +853,30 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
**OpenShell 模式：**
- `mirror`：执行前从本地为远程播种，执行后同步回来；本地工作区保持为规范来源
- `remote`：创建沙箱时为远程播种一次，随后保持远程工作区为规范来源
- `mirror`：执行前从本地为远程做种子初始化，执行后同步回来；本地工作区保持为权威来源
- `remote`：创建沙箱时为远程做一次种子初始化，然后保持远程工作区为权威来源
在 `remote` 模式下，在 OpenClaw 外部进行的主机本地编辑，不会在播种步骤之后自动同步到沙箱中。
传输方式是通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期和可选的镜像同步。
在 `remote` 模式下，种子初始化步骤之后，在 OpenClaw 外部进行的主机本地编辑不会自动同步到沙箱中。
传输方式是通过 SSH 进入 OpenShell 沙箱，但插件拥有沙箱生命周期和可选的镜像同步。
**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根目录和 root 用户。
**容器默认使用 `network: "none"`**——如果智能体需要出站访问，请设置为 `"bridge"`（或自定义桥接网络）。
`"host"` 被阻止。默认也会阻止 `"container:<id>"`，除非你显式设置
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（应急选项）。
**容器默认为 `network: "none"`** — 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义桥接网络）。
`"host"` 会被阻止。默认情况下也会阻止 `"container:<id>"`，除非你显式设置
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（应急开关）。
**入站附件** 会暂存到活动工作区中的 `media/inbound/*`。
**入站附件** 会暂存在活动工作区的 `media/inbound/*` 中。
**`docker.binds`** 会挂载额外的主机目录；全局绑定和每智能体绑定会合并。
**`docker.binds`** 会挂载额外的主机目录；全局绑定和按智能体绑定会合并。
**沙箱浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入系统提示。不需要在 `openclaw.json` 中启用 `browser.enabled`。
**沙箱浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入到系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。
noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出短期有效的令牌 URL（而不是在共享 URL 中暴露密码）。
- `allowHostControl: false`（默认）会阻止沙箱会话以主机浏览器为目标。
- `network` 默认为 `openclaw-sandbox-browser`（专用桥接网络）。仅当你明确需要全局桥接连接时，才设置为 `bridge`。
- `cdpSourceRange` 可选地将容器边缘的 CDP 入站限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。
- `sandbox.browser.binds` 只会将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。
- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机调优：
- `allowHostControl: false`（默认）会阻止沙箱隔离会话把主机浏览器作为目标。
- `network` 默认为 `openclaw-sandbox-browser`（专用桥接网络）。仅当你明确需要全局桥接连通性时，才设置为 `bridge`。
- `cdpSourceRange` 可选地将容器边界上的 CDP 入站限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。
- `sandbox.browser.binds` 只会把额外的主机目录挂载到沙箱浏览器容器中。设置时（包括 `[]`），它会替换浏览器容器的 `docker.binds`。
- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优：
- `--remote-debugging-address=127.0.0.1`
- `--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>`
- `--user-data-dir=${HOME}/.chrome`
@ -899,37 +895,37 @@ 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` 会重新启用扩展。
- `--renderer-process-limit=2` 可以通过
- `--renderer-process-limit=2` 可通过
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 更改；设置为 `0` 可使用 Chromium 的
默认进程限制。
- 当启用 `noSandbox` 时，还会加上 `--no-sandbox`。
- 默认值是容器镜像基线；要更改容器默认值，请使用带有自定义
- 默认值是容器镜像基线；如需更改容器默认值，请使用带自定义
入口点的自定义浏览器镜像。
</Accordion>
浏览器沙箱隔离和 `sandbox.docker.binds` 仅限 Docker。
构建镜像（从源码检出目录）：
构建镜像（从源码检出）：
```bash
scripts/sandbox-setup.sh # main sandbox image
scripts/sandbox-browser-setup.sh # optional browser image
```
对于没有源码检出目录的 npm 安装，请参见 [沙箱隔离 § 镜像和设置](/zh-CN/gateway/sandboxing#images-and-setup)，其中包含内联 `docker build` 命令。
对于没有源码检出的 npm 安装，请参阅[沙箱隔离 § 镜像和设置](/zh-CN/gateway/sandboxing#images-and-setup)，其中提供了内联 `docker build` 命令。
### `agents.list`（每智能体覆盖项）
### `agents.list`（按智能体覆盖）
使用 `agents.list[].tts` 为智能体提供自己的 TTS 提供商、语音、模型、
风格或自动 TTS 模式。智能体块会深度合并到全局
`messages.tts` 之上，因此共享凭证可以保留在一个位置，而各个
智能体只覆盖它们需要的语音或提供商字段。活动智能体的
覆盖项适用于自动语音回复、`/tts audio`、`/tts status` 和
`tts` 智能体工具。有关提供商示例和优先级，请参见 [文本转语音](/zh-CN/tools/tts#per-agent-voice-overrides)。
覆盖适用于自动语音回复、`/tts audio`、`/tts status` 和
`tts` 智能体工具。提供商示例和优先级请参阅[文本转语音](/zh-CN/tools/tts#per-agent-voice-overrides)。
```json5
{
@ -983,28 +979,28 @@ scripts/sandbox-browser-setup.sh # optional browser image
}
```
- `id`：稳定的智能体 id（必填）。
- `default`：设置多个时，第一个生效（会记录警告）。如果未设置，则列表中的第一项为默认项。
- `model`：字符串形式会设置严格的按智能体主模型，且没有模型回退；对象形式 `{ primary }` 也同样严格，除非你添加 `fallbacks`。使用 `{ primary, fallbacks: [...] }` 让该智能体启用回退，或使用 `{ primary, fallbacks: [] }` 显式指定严格行为。仅覆盖 `primary` 的 Cron 任务仍会继承默认回退，除非你设置 `fallbacks: []`。
- `params`：按智能体的流参数，会合并覆盖 `agents.defaults.models` 中选定的模型条目。使用它为智能体设置特定覆盖，例如 `cacheRetention`、`temperature` 或 `maxTokens`，无需复制整个模型目录。
- `tts`：可选的按智能体文本转语音覆盖。该块会深度合并覆盖 `messages.tts`，因此请将共享的提供商凭证和回退策略保留在 `messages.tts` 中，并仅在这里设置角色特定的值，例如提供商、声音、模型、风格或自动模式。
- `skills`：可选的按智能体 Skills 允许列表。如果省略，并且已设置 `agents.defaults.skills`，该智能体会继承它；显式列表会替换默认值而不是合并，`[]` 表示没有 Skills。
- `thinkingDefault`：可选的按智能体默认思考等级（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当没有设置按消息或会话覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。选定的提供商/模型配置会控制哪些值有效；对于 Google Gemini，`adaptive` 会保留提供商拥有的动态思考（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。
- `reasoningDefault`：可选的按智能体默认推理可见性（`on | off | stream`）。当没有设置按消息或会话推理覆盖时，会覆盖该智能体的 `agents.defaults.reasoningDefault`。
- `fastModeDefault`：可选的按智能体快速模式默认值（`true | false`）。当没有设置按消息或会话快速模式覆盖时适用。
- `agentRuntime`：可选的按智能体低层运行时策略覆盖。使用 `{ id: "codex" }` 让某个智能体仅使用 Codex，而其他智能体在 `auto` 模式下继续保留默认 Pi 回退。
- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 搭配 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。
- `id`：稳定的智能体 id（必需）。
- `default`：设置多个时，第一个生效（会记录警告）。如果都未设置，列表中的第一项为默认值。
- `model`：字符串形式会为每个智能体设置严格的主模型，且没有模型回退；对象形式 `{ primary }` 也同样严格，除非你添加 `fallbacks`。使用 `{ primary, fallbacks: [...] }` 可让该智能体启用回退，或使用 `{ primary, fallbacks: [] }` 明确指定严格行为。仅覆盖 `primary` 的 Cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。
- `params`：每个智能体的流参数，会合并覆盖 `agents.defaults.models` 中选定的模型条目。可用它设置智能体专属覆盖项，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。
- `tts`：可选的每个智能体文本转语音覆盖项。该块会深度合并覆盖 `messages.tts`，因此请将共享的提供商凭证和回退策略保留在 `messages.tts` 中，并仅在此处设置角色专属值，例如提供商、语音、模型、风格或自动模式。
- `skills`：可选的每个智能体 Skills 允许列表。如果省略，并且已设置 `agents.defaults.skills`，该智能体会继承它；显式列表会替换默认值而不是合并，`[]` 表示没有 Skills。
- `thinkingDefault`：可选的每个智能体默认思考级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当没有设置每条消息或会话覆盖项时，为该智能体覆盖 `agents.defaults.thinkingDefault`。所选提供商/模型配置文件决定哪些值有效；对于 Google Gemini，`adaptive` 会保留由提供商拥有的动态思考（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。
- `reasoningDefault`：可选的每个智能体默认推理可见性（`on | off | stream`）。当没有设置每条消息或会话推理覆盖项时，为该智能体覆盖 `agents.defaults.reasoningDefault`。
- `fastModeDefault`：可选的每个智能体快速模式默认值（`true | false`）。当没有设置每条消息或会话快速模式覆盖项时应用。
- `agentRuntime`：可选的每个智能体低级运行时策略覆盖项。使用 `{ id: "codex" }` 可让一个智能体仅使用 Codex，而其他智能体在 `auto` 模式下保留默认 Pi 回退。
- `runtime`：可选的每个智能体运行时描述符。当该智能体应默认使用 ACP harness 会话时，配合 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）使用 `type: "acp"`。
- `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。
- `identity` 会派生默认值：从 `emoji` 派生 `ackReaction`，从 `name`/`emoji` 派生 `mentionPatterns`。
- `subagents.allowAgents`：用于显式 `sessions_spawn.agentId` 目标的智能体 id 允许列表（`["*"]` = 任意；默认：仅同一智能体）。当应允许自定向的 `agentId` 调用时，请包含请求方 id。
- 沙箱继承防护：如果请求方会话已沙箱隔离，`sessions_spawn` 会拒绝会以非沙箱隔离方式运行的目标。
- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件；默认值：false）。
- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。
- `subagents.allowAgents`：用于显式 `sessions_spawn.agentId` 目标的智能体 id 允许列表（`["*"]` = 任意；默认：仅同一智能体）。当应允许自目标 `agentId` 调用时，请包含请求方 id。
- 沙箱继承保护：如果请求方会话处于沙箱隔离状态，`sessions_spawn` 会拒绝那些将以非沙箱隔离方式运行的目标。
- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件；默认：false）。
---
## 多智能体路由
在一个 Gateway 网关内运行多个隔离的智能体。参见 [多智能体](/zh-CN/concepts/multi-agent)。
在一个 Gateway 网关内运行多个隔离的智能体。请参阅 [Multi-Agent](/zh-CN/concepts/multi-agent)。
```json5
{
@ -1023,11 +1019,11 @@ scripts/sandbox-browser-setup.sh # optional browser image
### 绑定匹配字段
- `type`（可选）：`route` 用于普通路由（缺失 type 默认使用 route），`acp` 用于持久 ACP 对话绑定。
- `match.channel`（必填）
- `match.accountId`（可选；`*` = 任意账户；省略 = 默认账户）
- `type`（可选）：`route` 表示普通路由（缺少 type 时默认为 route），`acp` 表示持久 ACP 对话绑定。
- `match.channel`（必需）
- `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号）
- `match.peer`（可选；`{ kind: direct|group|channel, id }`）
- `match.guildId` / `match.teamId`（可选；特定于渠道）
- `match.guildId` / `match.teamId`（可选；渠道专属）
- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }`
**确定性匹配顺序：**
@ -1036,14 +1032,14 @@ scripts/sandbox-browser-setup.sh # optional browser image
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` + 账户 + `match.peer.id`）解析，并且不使用上面的 route 绑定层级顺序。
对于 `type: "acp"` 条目，OpenClaw 会按精确的对话身份（`match.channel` + 账号 + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。
### 按智能体访问配置文件
### 每个智能体的访问配置文件
<Accordion title="完全访问（无沙箱）">
@ -1092,7 +1088,7 @@ scripts/sandbox-browser-setup.sh # optional browser image
</Accordion>
<Accordion title="无文件系统访问权限（仅消息传递）">
<Accordion title="无文件系统访问（仅消息）">
```json5
{
@ -1138,7 +1134,7 @@ scripts/sandbox-browser-setup.sh # optional browser image
</Accordion>
有关优先级详情，请参阅 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。
有关优先级详情，请参阅 [Multi-Agent 沙箱和工具](/zh-CN/tools/multi-agent-sandbox-tools)。
---
@ -1190,33 +1186,33 @@ scripts/sandbox-browser-setup.sh # optional browser image
<Accordion title="会话字段详情">
- **`scope`**：群聊上下文的基础会话分组策略。
- `per-sender`（默认）：每个发送者在一个渠道上下文中获得一个隔离的会话。
- `global`：一个渠道上下文中的所有参与者共享单个会话（仅在确实需要共享上下文时使用）。
- `per-sender`（默认）：每个发送者在一个渠道上下文中获得一个隔离会话。
- `global`：一个渠道上下文中的所有参与者共享单个会话（仅在有意共享上下文时使用）。
- **`dmScope`**：私信的分组方式。
- `main`：所有私信共享主会话。
- `per-peer`：跨渠道按发送者 ID 隔离。
- `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。
- `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。
- **`identityLinks`**：将规范 ID 映射到带提供商前缀的对端，用于跨渠道会话共享。诸如 `/dock_discord` 这样的停靠命令使用同一映射，将活动会话的回复路由切换到另一个已关联的渠道对端；请参阅 [渠道停靠](/zh-CN/concepts/channel-docking)。
- **`reset`**：主重置策略。`daily` 在本地时间 `atHour` 重置；`idle` 在 `idleMinutes` 之后重置。如果两者都已配置，则以先到期者为准。每日重置的新鲜度使用会话行的 `sessionStartedAt`；空闲重置的新鲜度使用 `lastInteractionAt`。后台/系统事件写入（例如 Heartbeat、cron 唤醒、exec 通知和 Gateway 网关记账）可以更新 `updatedAt`，但它们不会让每日/空闲会话保持新鲜。
- **`identityLinks`**：将规范 ID 映射到带提供商前缀的对等方，用于跨渠道会话共享。诸如 `/dock_discord` 的停靠命令使用同一个映射，将活跃会话的回复路由切换到另一个已链接的渠道对等方；请参阅[渠道停靠](/zh-CN/concepts/channel-docking)。
- **`reset`**：主要重置策略。`daily` 在本地时间 `atHour` 重置；`idle` 在 `idleMinutes` 后重置。两者都配置时，先到期者生效。每日重置的新鲜度使用会话行的 `sessionStartedAt`；空闲重置的新鲜度使用 `lastInteractionAt`。后台/系统事件写入（例如 Heartbeat、cron 唤醒、exec 通知和 Gateway 网关记账）可以更新 `updatedAt`，但它们不会让每日/空闲会话保持新鲜。
- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。
- **`mainKey`**：旧版字段。运行时始终对主直接聊天存储桶使用 `"main"`。
- **`agentToAgent.maxPingPongTurns`**：智能体间交换期间，智能体之间来回回复的最大轮数（整数，范围：`0`–`5`）。`0` 会禁用乒乓式串联。
- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 可作别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个拒绝规则生效。
- **`mainKey`**：旧版字段。运行时始终使用 `"main"` 作为主直接聊天桶。
- **`agentToAgent.maxPingPongTurns`**：智能体间交换期间，智能体之间的最大来回回复轮数（整数，范围：`0`–`5`）。`0` 会禁用来回链式回复。
- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，带旧版 `dm` 别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个拒绝规则生效。
- **`maintenance`**：会话存储清理 + 保留控制。
- `mode`：`warn` 仅发出警告；`enforce` 会执行清理。
- `mode`：`warn` 仅发出警告；`enforce` 应用清理。
- `pruneAfter`：陈旧条目的年龄截止值（默认 `30d`）。
- `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。运行时会用一个较小的高水位缓冲批量写入清理，以适配生产规模的上限；`openclaw sessions cleanup --enforce` 会立即应用该上限。
- `rotateBytes`：已弃用并被忽略；`openclaw doctor --fix` 会从旧配置中移除它。
- `resetArchiveRetention`：`*.reset.<timestamp>` 转录归档的保留期限。默认为 `pruneAfter`；设为 `false` 可禁用。
- `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。运行时会为生产规模上限写入带有小型高水位缓冲区的批量清理；`openclaw sessions cleanup --enforce` 会立即应用该上限。
- `rotateBytes`：已弃用并被忽略；`openclaw doctor --fix` 会从较旧配置中移除它。
- `resetArchiveRetention`：`*.reset.<timestamp>` 对话记录归档的保留期。默认值为 `pruneAfter`；设为 `false` 可禁用。
- `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的工件/会话。
- `highWaterBytes`：预算清理后的可选目标值。默认为 `maxDiskBytes` 的 `80%`。
- `highWaterBytes`：预算清理后的可选目标。默认值为 `maxDiskBytes` 的 `80%`。
- **`threadBindings`**：线程绑定会话功能的全局默认值。
- `enabled`：主默认开关（提供商可以覆盖；Discord 使用 `channels.discord.threadBindings.enabled`）
- `idleHours`：默认的非活动自动取消聚焦时间，单位为小时（`0` 禁用；提供商可以覆盖）
- `maxAgeHours`：默认的硬性最大年龄，单位为小时（`0` 禁用；提供商可以覆盖）
- `spawnSessions`：用于从 `sessions_spawn` 和 ACP 线程生成创建线程绑定工作会话的默认闸门。启用线程绑定时默认为 `true`；提供商/账号可以覆盖。
- `defaultSpawnContext`：线程绑定生成的默认原生子智能体上下文（`"fork"` 或 `"isolated"`）。默认为 `"fork"`。
- `idleHours`：默认非活跃自动取消聚焦时间，单位为小时（`0` 禁用；提供商可以覆盖）
- `maxAgeHours`：默认硬性最大年龄，单位为小时（`0` 禁用；提供商可以覆盖）
- `spawnSessions`：从 `sessions_spawn` 和 ACP 线程生成创建线程绑定工作会话的默认门控。启用线程绑定时默认为 `true`；提供商/账号可以覆盖。
- `defaultSpawnContext`：线程绑定生成的默认原生子智能体上下文（`"fork"` 或 `"isolated"`）。默认值为 `"fork"`。
</Accordion>
@ -1254,36 +1250,36 @@ scripts/sandbox-browser-setup.sh # optional browser image
### 响应前缀
按渠道/账号覆盖：`channels.<channel>.responsePrefix`、`channels.<channel>.accounts.<id>.responsePrefix`。
每个渠道/账号的覆盖项：`channels.<channel>.responsePrefix`、`channels.<channel>.accounts.<id>.responsePrefix`。
解析（最具体者优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 派生为 `[{identity.name}]`。
解析规则（最具体者优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 派生为 `[{identity.name}]`。
**模板变量：**
| 变量 | 描述 | 示例 |
| ----------------- | ------------------ | --------------------------- |
| `{model}` | 短模型名称 | `claude-opus-4-6` |
| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` |
| `{provider}` | 提供商名称 | `anthropic` |
| `{thinkingLevel}` | 当前思考等级 | `high`, `low`, `off` |
| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） |
| 变量 | 描述 | 示例 |
| ----------------- | -------------------- | --------------------------- |
| `{model}` | 简短模型名称 | `claude-opus-4-6` |
| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` |
| `{provider}` | 提供商名称 | `anthropic` |
| `{thinkingLevel}` | 当前思考级别 | `high`, `low`, `off` |
| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） |
变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。
### 确认反应
- 默认使用活动智能体的 `identity.emoji`，否则使用 `"👀"`。设为 `""` 可禁用。
- 按渠道覆盖：`channels.<channel>.ackReaction`、`channels.<channel>.accounts.<id>.ackReaction`。
- 解析顺序：账号 → 渠道 → `messages.ackReaction` → 身份回退。
- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。
- `removeAckAfterReply`：在支持 reaction 的渠道（如 Slack、Discord、Telegram、WhatsApp 和 BlueBubbles）上，回复后移除确认反应。
- 默认使用活跃智能体的 `identity.emoji`，否则使用 `"👀"`。设为 `""` 可禁用。
- 每个渠道覆盖项：`channels.<channel>.ackReaction`、`channels.<channel>.accounts.<id>.ackReaction`。
- 解析顺序：账号 → 渠道 → `messages.ackReaction` → 身份回退值。
- 范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。
- `removeAckAfterReply`：在 Slack、Discord、Telegram、WhatsApp 和 BlueBubbles 等支持反应的渠道上，回复后移除确认反应。
- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。
在 Slack 和 Discord 上，未设置时，如果确认反应处于活动状态，则保持状态反应启用。
在 Telegram 上，将它显式设为 `true` 以启用生命周期状态反应。
在 Slack 和 Discord 上，未设置时，如果确认反应处于活跃状态，状态反应会保持启用。
在 Telegram 上，需要显式设为 `true` 才能启用生命周期状态反应。
### 入站防抖
将同一发送者快速发送的纯文本消息批处理为单个智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。
将同一发送者的快速纯文本消息合并为单个智能体回合。媒体/附件会立即刷新。控制命令会绕过防抖。
### TTS（文本转语音）
@ -1333,13 +1329,13 @@ scripts/sandbox-browser-setup.sh # optional browser image
}
```
- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好，`/tts status` 会显示生效状态。
- `summaryModel` 会覆盖用于自动摘要的 `agents.defaults.model.primary`。
- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（选择启用）。
- API key 回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。
- 内置语音提供商由插件拥有。如果设置了 `plugins.allow`，请包含你想使用的每个 TTS 提供商插件，例如用于 Edge TTS 的 `microsoft`。旧版 `edge` 提供商 ID 可作为 `microsoft` 的别名接受。
- `providers.openai.baseUrl` 覆盖 OpenAI TTS 端点。解析顺序为配置，然后是 `OPENAI_TTS_BASE_URL`，然后是 `https://api.openai.com/v1`。
- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型/语音校验。
- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好设置，`/tts status` 会显示有效状态。
- `summaryModel` 会覆盖 `agents.defaults.model.primary`，用于自动摘要。
- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需选择加入）。
- API key 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。
- 内置语音提供商由插件拥有。如果设置了 `plugins.allow`，请包含你要使用的每个 TTS 提供商插件，例如用于 Edge TTS 的 `microsoft`。旧版 `edge` 提供商 id 会作为 `microsoft` 的别名被接受。
- `providers.openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置，然后是 `OPENAI_TTS_BASE_URL`，然后是 `https://api.openai.com/v1`。
- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容的 TTS 服务器，并放宽模型/语音验证。
---
@ -1374,20 +1370,20 @@ Talk 模式（macOS/iOS/Android）的默认值。
}
```
- 配置多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的一个键。
- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.<provider>`。
- 语音 ID 回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
- 配置多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。
- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容性，并会自动迁移到 `talk.providers.<provider>`。
- 语音 ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
- `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。
- 仅当未配置 Talk API key 时，才会应用 `ELEVENLABS_API_KEY` 回退。
- 仅在未配置 Talk API key 时才会应用 `ELEVENLABS_API_KEY` 回退值。
- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。
- `providers.mlx.modelId` 选择 macOS 本地 MLX helper 使用的 Hugging Face repo。如果省略，macOS 会使用 `mlx-community/Soprano-80M-bf16`。
- macOS MLX 播放会在存在时通过内置 `openclaw-mlx-tts` helper 运行，或通过 `PATH` 上的可执行文件运行；`OPENCLAW_MLX_TTS_BIN` 会覆盖用于开发的 helper 路径。
- `speechLocale` 设置 iOS/macOS Talk 语音识别使用的 BCP 47 区域设置 ID。留空则使用设备默认值。
- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久才发送转录。未设置时保留平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）。
- `providers.mlx.modelId` 选择 macOS 本地 MLX 辅助程序使用的 Hugging Face 仓库。如果省略，macOS 会使用 `mlx-community/Soprano-80M-bf16`。
- macOS MLX 播放会在存在时通过内置的 `openclaw-mlx-tts` 辅助程序运行，或通过 `PATH` 上的可执行文件运行；`OPENCLAW_MLX_TTS_BIN` 会覆盖用于开发的辅助程序路径。
- `speechLocale` 设置 iOS/macOS Talk 语音识别使用的 BCP 47 区域设置 id。未设置时使用设备默认值。
- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久才发送转录文本。未设置时会保留平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）。
---
## 相关
## 相关内容
- [配置参考](/zh-CN/gateway/configuration-reference) — 所有其他配置键
- [配置](/zh-CN/gateway/configuration) — 常见任务和快速设置

310
docs/zh-CN/gateway/config-channels.md
View File

@ -1,54 +1,54 @@
---
read_when:
- 配置渠道插件（认证、访问控制、多账号）
- 按渠道配置键的故障排除
- 配置渠道插件（身份验证、访问控制、多账号）
- 按渠道配置键名故障排除
- 审计私信策略、群组策略或提及门控
summary: 频道配置：Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等渠道的访问控制、配对和每渠道密钥
summary: 频道配置：访问控制、配对，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等的各渠道密钥
title: 配置 — 渠道
x-i18n:
generated_at: "2026-05-03T21:05:42Z"
generated_at: "2026-05-04T00:47:06Z"
model: gpt-5.5
provider: openai
source_hash: 366bcee632c649219bbf6cf44d64cc13d966ec813abc74d54088d89de640b47c
source_hash: 57dcc0b5148324ea6fdee51b7b6e97ec7bd7dc3ca89518ab0816fe4172feefbc
source_path: gateway/config-channels.md
workflow: 16
---
`channels.*` 下的每渠道配置键。涵盖私信和群组访问、多账号设置、提及门控，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他内置渠道插件的每渠道键。
Per-channel 配置键位于 `channels.*` 下。涵盖私信和群组访问、多账号设置、提及门控，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他内置渠道插件的每渠道键。
关于智能体、工具、Gateway 网关运行时和其他顶级键，请参阅
对于智能体、工具、Gateway 网关运行时和其他顶级键，请参阅
[配置参考](/zh-CN/gateway/configuration-reference)。
## 渠道
每个渠道会在其配置部分存在时自动启动（除非设置了 `enabled: false`）。
每个渠道会在其配置节存在时自动启动（除非设置了 `enabled: false`）。
### 私信和群组访问
所有渠道都支持私信策略和群组策略：
| 私信策略 | 行为 |
| 私信策略 | 行为 |
| ------------------- | --------------------------------------------------------------- |
| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 |
| `allowlist` | 仅允许 `allowFrom`（或已配对的允许存储）中的发送者 |
| `open` | 允许所有入站私信（需要 `allowFrom: ["*"]`） |
| `disabled` | 忽略所有入站私信 |
| `pairing`（默认） | 未知发送者会获得一次性配对码；所有者必须批准 |
| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对的允许存储中的发送者） |
| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） |
| `disabled` | 忽略所有传入私信 |
| 群组策略 | 行为 |
| 群组策略 | 行为 |
| --------------------- | ------------------------------------------------------ |
| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 |
| `open` | 跳过群组允许列表（提及门控仍适用） |
| `open` | 绕过群组允许列表（提及门控仍然适用） |
| `disabled` | 阻止所有群组/房间消息 |
<Note>
当提供商的 `groupPolicy` 未设置时，`channels.defaults.groupPolicy` 会设置默认值。
配对码会在 1 小时后过期。待处理的私信配对请求限制为**每个渠道 3 个**。
如果提供商块完全缺失（不存在 `channels.<provider>`），运行时群组策略会回退到 `allowlist`（失败关闭），并在启动时给出警告。
`channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时设置默认值。
配对码会在 1 小时后过期。待处理的私信配对请求上限为**每个渠道 3 个**。
如果提供商块完全缺失（不存在 `channels.<provider>`），运行时群组策略会回退为 `allowlist`（失败时关闭），并显示启动警告。
</Note>
### 渠道模型覆盖
使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当会话还没有模型覆盖时（例如通过 `/model` 设置），会应用该渠道映射。
使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当会话尚未设置模型覆盖（例如通过 `/model` 设置）时，渠道映射会生效。
```json5
{
@ -71,7 +71,7 @@ x-i18n:
### 渠道默认值和 Heartbeat
使用 `channels.defaults` 跨提供商共享群组策略和 Heartbeat 行为：
使用 `channels.defaults` 为各提供商共享群组策略和 Heartbeat 行为：
```json5
{
@ -90,14 +90,14 @@ x-i18n:
```
- `channels.defaults.groupPolicy`：提供商级 `groupPolicy` 未设置时的回退群组策略。
- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与允许列表相同，但保留明确的引用/回复上下文）。每渠道覆盖：`channels.<channel>.contextVisibility`。
- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与允许列表相同，但保留显式引用/回复上下文）。每渠道覆盖：`channels.<channel>.contextVisibility`。
- `channels.defaults.heartbeat.showOk`：在 Heartbeat 输出中包含健康的渠道 Status。
- `channels.defaults.heartbeat.showAlerts`：在 Heartbeat 输出中包含降级/错误 Status。
- `channels.defaults.heartbeat.useIndicator`：渲染紧凑的指示器风格 Heartbeat 输出。
- `channels.defaults.heartbeat.useIndicator`：渲染紧凑的指示器式 Heartbeat 输出。
### WhatsApp
WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在已链接会话时，它会自动启动。
WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。存在已链接会话时会自动启动。
```json5
{
@ -135,7 +135,7 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在
}
```
<Accordion title="Multi-account WhatsApp">
<Accordion title="多账号 WhatsApp">
```json5
{
@ -153,8 +153,8 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在
}
```
- 如果存在 `default`，出站命令默认使用账号 `default`；否则使用第一个已配置的账号 ID（排序后）。
- 可选的 `channels.whatsapp.defaultAccount` 在匹配已配置账号 ID 时，会覆盖该回退默认账号选择。
- 出站命令默认使用账号 `default`（如果存在）；否则使用第一个已配置的账号 ID（排序后）。
- 可选的 `channels.whatsapp.defaultAccount` 会在匹配已配置账号 ID 时覆盖该回退默认账号选择。
- 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。
- 每账号覆盖：`channels.whatsapp.accounts.<id>.sendReadReceipts`、`channels.whatsapp.accounts.<id>.dmPolicy`、`channels.whatsapp.accounts.<id>.allowFrom`。
@ -215,13 +215,13 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在
}
```
- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅限常规文件；拒绝符号链接），默认账号会回退使用 `TELEGRAM_BOT_TOKEN`。
- `apiRoot` 仅是 Telegram Bot API 根地址。使用 `https://api.telegram.org` 或你的自托管/代理根地址，而不是 `https://api.telegram.org/bot<TOKEN>`；`openclaw doctor --fix` 会移除意外追加的 `/bot<TOKEN>` 后缀。
- 可选的 `channels.telegram.defaultAccount` 在匹配已配置账号 ID 时，会覆盖默认账号选择。
- 在多账号设置（2 个以上账号 ID）中，设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；缺失或无效时，`openclaw doctor` 会发出警告。
- `configWrites: false` 会阻止由 Telegram 发起的配置写入（超级群组 ID 迁移、`/config set|unset`）。
- 带有 `type: "acp"` 的顶级 `bindings[]` 条目会为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#persistent-channel-bindings) 中共享。
- Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于私聊和群组聊天）。
- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅限普通文件；拒绝符号链接），并以 `TELEGRAM_BOT_TOKEN` 作为默认账号的回退。
- `apiRoot` 仅是 Telegram Bot API 根地址。使用 `https://api.telegram.org` 或你的自托管/代理根地址，而不是 `https://api.telegram.org/bot<TOKEN>`；`openclaw doctor --fix` 会移除意外尾随的 `/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 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings) 中共享。
- Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于直接聊天和群组聊天）。
- 重试策略：请参阅[重试策略](/zh-CN/concepts/retry)。
### Discord
@ -327,41 +327,41 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在
}
```
- 令牌：`channels.discord.token`，默认账号使用 `DISCORD_BOT_TOKEN` 作为回退。
- 提供显式 Discord `token` 的直接出站调用会使用该令牌发起调用；账号重试/策略设置仍来自活动运行时快照中选定的账号。
- 可选的 `channels.discord.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
- 对投递目标使用 `user:<id>`（私信）或 `channel:<id>`（服务器渠道）；裸数字 ID 会被拒绝。
- 服务器 slug 为小写，并将空格替换为 `-`；渠道键使用 slug 化名称（不带 `#`）。优先使用服务器 ID。
- 默认忽略由机器人发送的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 仅接受提及机器人的机器人消息（仍会过滤自身消息）。
- `channels.discord.guilds.<id>.ignoreOtherMentions`（以及渠道级覆盖）会丢弃提及其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。
- `channels.discord.mentionAliases` 会在发送前将稳定的出站 `@handle` 文本映射到 Discord 用户 ID，因此即使临时目录缓存为空，也能确定性地提及已知队友。按账号覆盖位于 `channels.discord.accounts.<accountId>.mentionAliases` 下。
- `maxLinesPerMessage`（默认 17）即使在少于 2000 个字符时也会拆分过高的消息。
- 令牌：`channels.discord.token`，默认账户回退使用 `DISCORD_BOT_TOKEN`。
- 提供显式 Discord `token` 的直接出站调用会将该令牌用于调用；账户重试/策略设置仍来自活跃运行时快照中的所选账户。
- 可选的 `channels.discord.defaultAccount` 在匹配已配置账户 ID 时会覆盖默认账户选择。
- 使用 `user:<id>`（私信）或 `channel:<id>`（服务器频道）作为投递目标；裸数字 ID 会被拒绝。
- 服务器 slug 为小写，并将空格替换为 `-`；频道键使用 slug 化名称（不含 `#`）。优先使用服务器 ID。
- 默认忽略机器人发送的消息。`allowBots: true` 会启用这些消息；使用 `allowBots: "mentions"` 只接受提及机器人的机器人消息（自己的消息仍会被过滤）。
- `channels.discord.guilds.<id>.ignoreOtherMentions`（以及频道覆盖项）会丢弃提及其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。
- `channels.discord.mentionAliases` 会在发送前将稳定的出站 `@handle` 文本映射到 Discord 用户 ID，因此即使临时目录缓存为空，也可以确定性地提及已知队友。按账户覆盖项位于 `channels.discord.accounts.<accountId>.mentionAliases` 下。
- `maxLinesPerMessage`（默认 17）即使在少于 2000 个字符时，也会拆分很高的消息。
- `channels.discord.threadBindings` 控制 Discord 线程绑定路由：
- `enabled`：线程绑定会话功能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由）的 Discord 覆盖
- `idleHours`：按小时设置的不活动自动取消聚焦 Discord 覆盖（`0` 禁用）
- `maxAgeHours`：按小时设置的硬性最长时限 Discord 覆盖（`0` 禁用）
- `spawnSessions`：`sessions_spawn({ thread: true })` 和 ACP 线程生成自动创建/绑定线程的开关（默认：`true`）
- `enabled`：线程绑定会话功能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由）的 Discord 覆盖项
- `idleHours`：按小时计的非活跃自动取消聚焦 Discord 覆盖项（`0` 禁用）
- `maxAgeHours`：按小时计的硬性最大年龄 Discord 覆盖项（`0` 禁用）
- `spawnSessions`：`sessions_spawn({ thread: true })` 和 ACP 线程生成自动线程创建/绑定的开关（默认：`true`）
- `defaultSpawnContext`：线程绑定生成的原生子智能体上下文（默认 `"fork"`）
- 带有 `type: "acp"` 的顶层 `bindings[]` 条目会为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 ID）。字段语义在 [ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings) 中共享。
- `channels.discord.ui.components.accentColor` 设置 Discord components v2 容器的强调色。
- `channels.discord.voice` 启用 Discord 语音渠道对话，以及可选的自动加入 + LLM + TTS 覆盖。纯文本 Discord 配置默认关闭语音；设置 `channels.discord.voice.enabled=true` 以选择启用。
- `channels.discord.voice.model` 可选地覆盖用于 Discord 语音渠道响应的 LLM 模型。
- 带有 `type: "acp"` 的顶层 `bindings[]` 条目会为频道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用频道/线程 ID）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#persistent-channel-bindings) 中共享。
- `channels.discord.ui.components.accentColor` 设置 Discord 组件 v2 容器的强调色。
- `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入 + LLM + TTS 覆盖项。纯文本 Discord 配置默认关闭语音；设置 `channels.discord.voice.enabled=true` 以选择启用。
- `channels.discord.voice.model` 可选择覆盖用于 Discord 语音频道响应的 LLM 模型。
- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传到 `@discordjs/voice` DAVE 选项（默认分别为 `true` 和 `24`）。
- `channels.discord.voice.connectTimeoutMs` 控制 `/vc join` 和自动加入尝试的初始 `@discordjs/voice` Ready 等待时间（默认 `30000`）。
- `channels.discord.voice.reconnectGraceMs` 控制已断开的语音会话在 OpenClaw 销毁它之前可花多长时间进入重连信令（默认 `15000`）。
- OpenClaw 还会在重复解密失败后，通过离开/重新加入语音会话来尝试语音接收恢复。
- `channels.discord.voice.reconnectGraceMs` 控制断开的语音会话在 OpenClaw 销毁它之前，可以用多久进入重连信令（默认 `15000`）。
- OpenClaw 还会在重复解密失败后，通过离开并重新加入语音会话来尝试语音接收恢复。
- `channels.discord.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔值 `streaming` 会自动迁移。
- `channels.discord.autoPresence` 将运行时可用性映射到机器人在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。
- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/标签匹配（应急兼容模式）。
- `channels.discord.execApprovals`：Discord 原生 exec 审批投递和审批者授权。
- `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析审批者时，exec 审批会激活。
- `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。
- `channels.discord.autoPresence` 将运行时可用性映射到机器人在线状态（healthy => online、degraded => idle、exhausted => dnd），并允许可选的状态文本覆盖项。
- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/标签匹配（破窗兼容模式）。
- `channels.discord.execApprovals`：Discord 原生 exec 审批投递和审批人授权。
- `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当审批人可从 `approvers` 或 `commands.ownerAllowFrom` 解析时，会激活 exec 审批。
- `approvers`：允许审批 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。
- `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。
- `sessionFilter`：可选的会话键模式（子字符串或正则）。
- `target`：发送审批提示的位置。`"dm"`（默认）发送到审批者私信，`"channel"` 发送到发起渠道，`"both"` 发送到两者。当 target 包含 `"channel"` 时，按钮仅可由已解析的审批者使用。
- `sessionFilter`：可选的会话键模式（子字符串或正则表达式）。
- `target`：审批提示的发送位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到来源频道，`"both"` 同时发送到两者。当目标包含 `"channel"` 时，按钮仅可由已解析的审批人使用。
- `cleanupAfterResolve`：为 `true` 时，在批准、拒绝或超时后删除审批私信。
**反应通知模式：**`off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自所有消息上的 `guilds.<id>.users`）。
**反应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自所有消息上的 `guilds.<id>.users`）。
### Google Chat
@ -392,11 +392,11 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在
}
```
- 服务账号 JSON：内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。
- 也支持服务账号 SecretRef（`serviceAccountRef`）。
- 服务账户 JSON：内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。
- 也支持服务账户 SecretRef（`serviceAccountRef`）。
- 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。
- 对投递目标使用 `spaces/<spaceId>` 或 `users/<userId>`。
- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变邮箱主体匹配（应急兼容模式）。
- 使用 `spaces/<spaceId>` 或 `users/<userId>` 作为投递目标。
- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（破窗兼容模式）。
### Slack
@ -468,23 +468,23 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在
}
```
- **Socket 模式** 需要同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。
- **HTTP 模式** 需要 `botToken` 加 `signingSecret`（位于根级或按账号配置）。
- `socketMode` 会将 Slack SDK Socket Mode 传输调优透传到公开的 Bolt 接收器 API。仅在调查 ping/pong 超时或陈旧 websocket 行为时使用它。
- **Socket 模式**需要同时提供 `botToken` 和 `appToken`（默认账户环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。
- **HTTP 模式**需要 `botToken` 加 `signingSecret`（位于根级别或按账户配置）。
- `socketMode` 会将 Slack SDK Socket Mode 传输调优透传到公共 Bolt receiver API。仅在调查 ping/pong 超时或陈旧 websocket 行为时使用它。
- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。
- Slack 账号快照会暴露按凭证划分的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef 配置，但当前命令/运行时路径无法解析密钥值。
- Slack 账户快照会公开按凭据划分的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 `signingSecretStatus`。`configured_unavailable` 表示该账户通过 SecretRef 配置，但当前命令/运行时路径无法解析密钥值。
- `configWrites: false` 会阻止由 Slack 发起的配置写入。
- 可选的 `channels.slack.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
- `channels.slack.streaming.mode` 是规范的 Slack 流模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版 `streamMode`、布尔值 `streaming` 和 `nativeStreaming` 会自动迁移。
- 对投递目标使用 `user:<id>`（私信）或 `channel:<id>`。
- 可选的 `channels.slack.defaultAccount` 在匹配已配置账户 ID 时会覆盖默认账户选择。
- `channels.slack.streaming.mode` 是规范的 Slack 流模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输协议。旧版 `streamMode`、布尔值 `streaming` 和 `nativeStreaming` 会自动迁移。
- 使用 `user:<id>`（私信）或 `channel:<id>` 作为投递目标。
**反应通知模式：**`off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。
**反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。
**线程会话隔离：**`thread.historyScope` 是按线程（默认）或跨渠道共享。`thread.inheritParent` 会将父渠道转录复制到新线程。
**线程会话隔离：** `thread.historyScope` 是按线程（默认）或在频道中共享。`thread.inheritParent` 会将父频道转录复制到新线程。
- Slack 原生流式传输以及 Slack 助手风格的 “is typing...” 线程状态需要回复线程目标。顶层私信默认保持在线程外，因此它们仍可通过 Slack 草稿发布并编辑预览进行流式传输，而不是显示线程风格的原生流/状态预览。
- `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"`）。
- Slack 原生流式传输加上 Slack 助手风格的“is typing...”线程状态需要回复线程目标。顶层私信默认保持在线程外，因此它们仍可通过 Slack 草稿发布并编辑预览进行流式传输，而不是显示线程风格的原生流/状态预览。
- `typingReaction` 会在回复运行期间向入站 Slack 消息添加临时反应，并在完成时移除。使用 Slack 表情短代码，例如 `"hourglass_flowing_sand"`。
- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批人授权。架构与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。
| 操作组 | 默认值 | 说明 |
| ------------ | ------- | ---------------------- |
@ -492,11 +492,11 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在
| messages | 已启用 | 读取/发送/编辑/删除 |
| pins | 已启用 | 置顶/取消置顶/列出 |
| memberInfo | 已启用 | 成员信息 |
| emojiList | 已启用 | 自定义 emoji 列表 |
| emojiList | 已启用 | 自定义表情列表 |
### Mattermost
Mattermost 在当前 OpenClaw 版本中作为内置插件提供。较旧或自定义构建可以使用 `openclaw plugins install @openclaw/mattermost` 安装当前 npm 包。固定版本前，请查看 [npmjs.com/package/@openclaw/mattermost](https://www.npmjs.com/package/@openclaw/mattermost) 了解当前 dist-tags。
Mattermost 在当前 OpenClaw 版本中作为内置插件提供。较旧版本或自定义构建可以使用 `openclaw plugins install @openclaw/mattermost` 安装当前 npm 包。固定版本前，请在 [npmjs.com/package/@openclaw/mattermost](https://www.npmjs.com/package/@openclaw/mattermost) 查看当前 dist-tags。
```json5
{
@ -530,14 +530,14 @@ Mattermost 在当前 OpenClaw 版本中作为内置插件提供。较旧或自
启用 Mattermost 原生命令时：
- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），而不是完整 URL。
- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器能够访问。
- 原生斜杠回调使用 Mattermost 在斜杠命令注册期间返回的逐命令令牌进行身份验证。如果注册失败或没有激活任何命令，OpenClaw 会以 `Unauthorized: invalid command token.` 拒绝回调。
- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。使用主机/域名值，而不是完整 URL。
- `channels.mattermost.configWrites`：允许或拒绝由 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。
- `channels.mattermost.configWrites`：允许或拒绝 Mattermost 发起的配置写入。
- `channels.mattermost.requireMention`：在渠道中回复前要求 `@mention`。
- `channels.mattermost.groups.<channelId>.requireMention`：逐渠道的提及门控覆盖（`"*"` 表示默认）。
- 可选的 `channels.mattermost.defaultAccount` 在匹配已配置账户 ID 时覆盖默认账户选择。
- `channels.mattermost.groups.<channelId>.requireMention`：按渠道的提及门控覆盖项（`"*"` 表示默认值）。
- 可选的 `channels.mattermost.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
### Signal
@ -558,11 +558,11 @@ Mattermost 在当前 OpenClaw 版本中作为内置插件提供。较旧或自
}
```
**表情回应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。
**回应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。
- `channels.signal.account`：将渠道启动固定到特定 Signal 账户身份。
- `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。
- 可选的 `channels.signal.defaultAccount` 在匹配已配置账户 ID 时覆盖默认账户选择。
- `channels.signal.account`：将渠道启动固定到特定的 Signal 账号身份。
- `channels.signal.configWrites`：允许或拒绝 Signal 发起的配置写入。
- 可选的 `channels.signal.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
### BlueBubbles
@ -581,9 +581,9 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，在 `channels.blueb
}
```
- 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。
- 可选的 `channels.bluebubbles.defaultAccount` 在匹配已配置账户 ID 时覆盖默认账户选择。
- 带有 `type: "acp"` 的顶层 `bindings[]` 条目可以将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles 句柄或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings)。
- 这里涵盖的核心键路径：`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#persistent-channel-bindings)。
- 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。
### iMessage
@ -612,15 +612,15 @@ OpenClaw 会启动 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护
}
```
- 可选的 `channels.imessage.defaultAccount` 在匹配已配置账户 ID 时覆盖默认账户选择。
- 可选的 `channels.imessage.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
- 需要对 Messages 数据库的完全磁盘访问权限。
- 需要对 Messages DB 授予 Full Disk Access。
- 优先使用 `chat_id:<id>` 目标。使用 `imsg chats --limit 20` 列出聊天。
- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。
- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制入站附件路径（默认：`/Users/*/Library/Messages/Attachments`）。
- SCP 使用严格的主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts`。
- `channels.imessage.configWrites`：允许或拒绝由 iMessage 发起的配置写入。
- 带有 `type: "acp"` 的顶层 `bindings[]` 条目可以将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化句柄或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#persistent-channel-bindings)。
- SCP 使用严格的主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。
- `channels.imessage.configWrites`：允许或拒绝 iMessage 发起的配置写入。
- 顶层 `bindings[]` 条目在带有 `type: "acp"` 时，可以将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP Agents](/zh-CN/tools/acp-agents#persistent-channel-bindings)。
<Accordion title="iMessage SSH 包装器示例">
@ -663,20 +663,20 @@ Matrix 由插件支持，并在 `channels.matrix` 下配置。
}
```
- 令牌身份验证使用 `accessToken`；密码身份验证使用 `userId` + `password`。
- `channels.matrix.proxy` 通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账户可以使用 `channels.matrix.accounts.<id>.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"`。
- 逐账户覆盖：`channels.matrix.accounts.<id>.execApprovals`。
- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组为会话：`per-user`（默认）按路由的对端共享，而 `per-room` 会隔离每个私信房间。
- Matrix Status 探测和实时目录查找使用与运行时流量相同的代理策略。
- token 认证使用 `accessToken`；密码认证使用 `userId` + `password`。
- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可以用 `channels.matrix.accounts.<id>.proxy` 覆盖它。
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 和这个网络显式启用项是彼此独立的控制项。
- `channels.matrix.defaultAccount` 在多账号设置中选择首选账号。
- `channels.matrix.autoJoin` 默认为 `off`，因此邀请的房间和新的私信样式邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并使用 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。
- `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递和审批者授权。
- `enabled`：`true`、`false` 或 `"auto"`（默认）。在 auto 模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析审批者时，会激活 exec 审批。
- `approvers`：允许审批 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。
- `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的审批。
- `sessionFilter`：可选的会话键模式（子字符串或正则）。
- `target`：发送审批提示的位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。
- 按账号覆盖：`channels.matrix.accounts.<id>.execApprovals`。
- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组到会话中：`per-user`（默认）按路由的对端共享，而 `per-room` 会隔离每个私信房间。
- Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。
- 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。
### Microsoft Teams
@ -696,8 +696,8 @@ Microsoft Teams 由插件支持，并在 `channels.msteams` 下配置。
}
```
- 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。
- 完整的 Teams 配置（凭证、webhook、私信/群组策略、逐 team/逐渠道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。
- 这里涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。
- 完整的 Teams 配置（凭据、webhook、私信/群组策略、按团队/按渠道覆盖项）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。
### IRC
@ -722,13 +722,13 @@ IRC 由插件支持，并在 `channels.irc` 下配置。
}
```
- 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。
- 可选的 `channels.irc.defaultAccount` 在匹配已配置账户 ID 时覆盖默认账户选择。
- 完整的 IRC 渠道配置（主机/端口/TLS/渠道/允许列表/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。
- 这里涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。
- 可选的 `channels.irc.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。
- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。
### 多账户（所有渠道）
### 多账号（所有渠道）
每个渠道运行多个账户（每个账户都有自己的 `accountId`）：
为每个渠道运行多个账号（每个账号都有自己的 `accountId`）：
```json5
{
@ -749,34 +749,36 @@ IRC 由插件支持，并在 `channels.irc` 下配置。
}
```
- 省略 `accountId` 时会使用 `default`（CLI + 路由）。
- 环境变量令牌只应用于**默认**账户。
- 基础渠道设置应用于所有账户，除非逐账户覆盖。
- 使用 `bindings[].match.accountId` 将每个账户路由到不同智能体。
- 如果你通过 `openclaw channels add`（或渠道新手引导）添加非默认账户，而当前仍使用单账户顶层渠道配置，OpenClaw 会先将账户作用域的顶层单账户值提升到渠道账户映射中，以便原账户继续工作。大多数渠道会将它们移入 `channels.<channel>.accounts.default`；Matrix 则可以改为保留现有匹配的命名/默认目标。
- 现有的仅渠道绑定（无 `accountId`）继续匹配默认账户；账户作用域绑定仍为可选。
- `openclaw doctor --fix` 也会通过将账户作用域的顶层单账户值移动到为该渠道选择的已提升账户来修复混合形态。大多数渠道使用 `accounts.default`；Matrix 则可以改为保留现有匹配的命名/默认目标。
- 省略 `accountId` 时使用 `default`（CLI + 路由）。
- 环境变量 token 只适用于 **默认** 账号。
- 基础渠道设置会应用于所有账号，除非按账号覆盖。
- 使用 `bindings[].match.accountId` 将每个账号路由到不同的智能体。
- 如果你在仍使用单账号顶层渠道配置时，通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，OpenClaw 会先将账号作用域的顶层单账号值提升到渠道账号映射中，以便原账号继续工作。大多数渠道会将它们移动到 `channels.<channel>.accounts.default`；Matrix 可以改为保留现有匹配的命名/默认目标。
- 现有仅渠道绑定（没有 `accountId`）会继续匹配默认账号；账号作用域绑定仍然是可选的。
- `openclaw doctor --fix` 也会通过将账号作用域的顶层单账号值移动到为该渠道选择的已提升账号中，来修复混合形态。大多数渠道使用 `accounts.default`；Matrix 可以改为保留现有匹配的命名/默认目标。
### 其他插件渠道
许多插件渠道配置为 `channels.<id>`，并记录在各自专用的渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。
请参阅完整渠道索引：[Channels](/zh-CN/channels)。
查看完整渠道索引：[Channels](/zh-CN/channels)。
### 群聊提及门控
群组消息默认**要求提及**（元数据提及或安全的正则表达式模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。
群组消息默认 **要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。
可见回复由单独设置控制。群组/渠道房间默认为 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍会处理该轮对话，但普通最终回复保持私密，房间中的可见输出需要 `message(action=send)`。仅当你想要普通回复发布回房间的旧版行为时，才设置 `"automatic"`。若要将同样的仅工具可见回复行为也应用到直接聊天，请设置 `messages.visibleReplies: "message_tool"`；Codex harness 也将这种仅工具行为用作其未设置时的直接聊天默认值。
可见回复由单独的设置控制。群组/渠道房间默认使用 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍会处理本轮交互，但普通最终回复会保持私密，可见的房间输出需要 `message(action=send)`。仅当你想要旧版行为，即普通回复会被发回房间时，才设置 `"automatic"`。若要把相同的仅工具可见回复行为也应用到直接聊天，请设置 `messages.visibleReplies: "message_tool"`；Codex harness 也将该仅工具行为作为其未设置的直接聊天默认值。
如果消息工具在当前有效工具策略下不可用，OpenClaw 会回退到自动可见回复，而不是静默抑制响应。`openclaw doctor` 会警告此不匹配。
仅工具可见回复需要能够可靠调用工具的模型/运行时。如果会话日志显示 assistant 文本带有 `didSendViaMessagingTool: false`，则表示模型生成了私密最终回答，而不是调用消息工具。为该渠道切换到更强的工具调用模型，或设置 `messages.groupChat.visibleReplies: "automatic"` 以恢复旧版可见最终回复。
Gateway 网关会在文件保存后热重载 `messages` 配置。只有在部署中禁用了文件监视或配置重载时才需要重启。
如果消息工具在当前工具策略下不可用，OpenClaw 会回退到自动可见回复，而不是静默抑制响应。`openclaw doctor` 会对此不匹配发出警告。
文件保存后，Gateway 网关会热重载 `messages` 配置。仅当部署中禁用了文件监听或配置重载时才需要重启。
**提及类型：**
- **元数据提及**：原生平台 @ 提及。在 WhatsApp 自聊模式中忽略。
- **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则表达式模式。无效模式和不安全的嵌套重复会被忽略。
- 仅在可以检测时（原生提及或至少一个模式）强制执行提及门控。
- **元数据提及**：原生平台 `@` 提及。在 WhatsApp 自聊模式中会被忽略。
- **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。
- 只有在可以检测时（原生提及或至少一个模式），才会强制执行提及门控。
```json5
{
@ -793,9 +795,9 @@ Gateway 网关会在文件保存后热重载 `messages` 配置。只有在部署
}
```
`messages.groupChat.historyLimit` 设置全局默认值。渠道可以使用 `channels.<channel>.historyLimit`（或按账号）覆盖。设为 `0` 可禁用。
`messages.groupChat.historyLimit` 设置全局默认值。渠道可以使用 `channels.<channel>.historyLimit`（或按账号）覆盖。设置为 `0` 可禁用。
`messages.visibleReplies` 是全局源轮次默认值；`messages.groupChat.visibleReplies` 会为群组/渠道源轮次覆盖它。当未设置 `messages.visibleReplies` 时，harness 可以提供自己的直接/源默认值；Codex harness 默认使用 `message_tool`。渠道允许列表和提及门控仍会决定是否处理某个轮次。
`messages.visibleReplies` 是全局源轮次默认值；`messages.groupChat.visibleReplies` 会为群组/频道源轮次覆盖它。当 `messages.visibleReplies` 未设置时，harness 可以提供自己的直接/源默认值；Codex harness 默认使用 `message_tool`。渠道允许列表和提及门控仍会决定是否处理某个轮次。
#### 私信历史限制
@ -818,7 +820,7 @@ Gateway 网关会在文件保存后热重载 `messages` 配置。只有在部署
#### 自聊模式
在 `allowFrom` 中包含你自己的号码以启用自聊模式（忽略原生 @ 提及，仅响应文本模式）：
在 `allowFrom` 中包含你自己的号码可启用自聊模式（忽略原生 `@` 提及，只响应文本模式）：
```json5
{
@ -868,28 +870,28 @@ Gateway 网关会在文件保存后热重载 `messages` 配置。只有在部署
<Accordion title="命令详情">
- 此块配置命令界面。有关当前内置 + 捆绑命令目录，请参阅 [Slash Commands](/zh-CN/tools/slash-commands)。
- 此页面是**配置键参考**，不是完整命令目录。由渠道/插件拥有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、设备配对 `/pair`、记忆 `/dreaming`、手机控制 `/phone` 和 Talk `/voice`，记录在各自的渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。
- 此区块配置命令入口。当前内置 + 捆绑命令目录见 [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"`）。对于 Discord，`false` 会在启动期间跳过原生命令注册和清理。
- `native: "auto"` 为 Discord/Telegram 开启原生命令，Slack 保持关闭。
- `nativeSkills: "auto"` 为 Discord/Telegram 开启原生 Skills 命令，Slack 保持关闭。
- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。对于 Discord，`false` 会跳过启动期间的原生命令注册和清理。
- 使用 `channels.<provider>.commands.nativeSkills` 按渠道覆盖原生 Skills 注册。
- `channels.telegram.customCommands` 会添加额外的 Telegram Bot 菜单项。
- `bash: true` 会为主机 shell 启用 `! <cmd>`。需要 `tools.elevated.enabled`，且发送者在 `tools.elevated.allowFrom.<channel>` 中。
- `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.<provider>.configWrites` 按渠道门控配置变更（默认值：true）。
- 对于多账号渠道，`channels.<provider>.accounts.<id>.configWrites` 也会门控面向该账号的写入（例如 `/allowlist --config --account <id>` 或 `/config set channels.<provider>.accounts.<id>...`）。
- `restart: false` 会禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。
- `ownerAllowFrom` 是 owner-only 命令/工具的显式所有者允许列表。它独立于 `allowFrom`。
- `channels.telegram.customCommands` 会添加额外的 Telegram bot 菜单条目。
- `bash: true` 为主机 shell 启用 `! <cmd>`。需要 `tools.elevated.enabled`，且发送者在 `tools.elevated.allowFrom.<channel>` 中。
- `config: true` 启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化 `/config set|unset` 写入还需要 `operator.admin`；只读 `/config show` 仍可供普通写入范围的操作员客户端使用。
- `mcp: true` 为 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。
- `plugins: true` 为插件发现、安装以及启用/禁用控制启用 `/plugins`。
- `channels.<provider>.configWrites` 按渠道控制配置变更（默认：true）。
- 对于多账号渠道，`channels.<provider>.accounts.<id>.configWrites` 也会控制针对该账号的写入（例如 `/allowlist --config --account <id>` 或 `/config set channels.<provider>.accounts.<id>...`）。
- `restart: false` 禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。
- `ownerAllowFrom` 是仅限所有者的命令/工具的显式所有者允许列表。它独立于 `allowFrom`。
- `ownerDisplay: "hash"` 会在系统提示中哈希所有者 ID。设置 `ownerDisplaySecret` 可控制哈希。
- `allowFrom` 按提供商设置。设置后，它是**唯一**授权来源（渠道允许列表/配对和 `useAccessGroups` 都会被忽略）。
- 当未设置 `allowFrom` 时，`useAccessGroups: false` 允许命令绕过访问组策略。
- `allowFrom` 是按提供商设置的。设置后，它是**唯一**授权来源（渠道允许列表/配对和 `useAccessGroups` 会被忽略）。
- 当 `allowFrom` 未设置时，`useAccessGroups: false` 允许命令绕过访问组策略。
- 命令文档映射：
- 内置 + 捆绑目录：[Slash Commands](/zh-CN/tools/slash-commands)
- 渠道特定命令界面：[Channels](/zh-CN/channels)
- 渠道特定命令入口：[Channels](/zh-CN/channels)
- QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot)
- 配对命令：[Pairing](/zh-CN/channels/pairing)
- LINE 卡片命令：[LINE](/zh-CN/channels/line)
@ -903,4 +905,4 @@ Gateway 网关会在文件保存后热重载 `messages` 配置。只有在部署
- [配置参考](/zh-CN/gateway/configuration-reference) — 顶层键
- [配置 — 智能体](/zh-CN/gateway/config-agents)
- [Channels 概览](/zh-CN/channels)
- [渠道概览](/zh-CN/channels)

47
docs/zh-CN/gateway/configuration-examples.md
View File

@ -3,22 +3,22 @@ read_when:
- 学习如何配置 OpenClaw
- 正在查找配置示例
- 首次设置 OpenClaw
summary: 适用于常见 OpenClaw 设置的、符合模式定义的配置示例
summary: 适用于常见 OpenClaw 设置的符合模式定义的配置示例
title: 配置示例
x-i18n:
generated_at: "2026-04-29T21:53:04Z"
generated_at: "2026-05-04T00:47:06Z"
model: gpt-5.5
provider: openai
source_hash: 8bc1f8877bc635d6e3aafd911852d61e71fa08de9144751209542fd67c70f0ba
source_hash: 60c8c2d731f8dce93c4d14657041d72043bc36e3d71ab6cb13c02993ba90dbe3
source_path: gateway/configuration-examples.md
workflow: 16
---
以下示例与当前配置 schema 保持一致。完整参考和每个字段的说明，请参阅[配置](/zh-CN/gateway/configuration)。
Examples below are aligned with the current config schema. For the exhaustive reference and per-field notes, see [Configuration](/zh-CN/gateway/configuration).
## 快速开始
## Quick start
### 绝对最小配置
### Absolute minimum
```json5
{
@ -27,9 +27,9 @@ x-i18n:
}
```
保存到 `~/.openclaw/openclaw.json` 后，你就可以从该号码向 bot 发送私信。
Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
### 推荐起步配置
### Recommended starter
```json5
{
@ -57,9 +57,9 @@ x-i18n:
}
```
## 扩展示例（主要选项）
## Expanded example (major options)
> JSON5 允许使用注释和尾随逗号。普通 JSON 也可以使用。
> JSON5 lets you use comments and trailing commas. Regular JSON works too.
```json5
{
@ -256,6 +256,7 @@ x-i18n:
skills: ["github", "weather"], // inherited by agents that omit list[].skills
thinkingDefault: "low",
verboseDefault: "off",
toolProgressDetail: "explain",
reasoningDefault: "off",
elevatedDefault: "on",
blockStreamingDefault: "off",
@ -470,9 +471,9 @@ x-i18n:
}
```
## 常见模式
## Common patterns
### 带一个覆盖项的共享 skill 基线
### Shared skill baseline with one override
```json5
{
@ -490,8 +491,8 @@ x-i18n:
```
- `agents.defaults.skills` 是共享基线。
- `agents.list[].skills` 会为单个智能体替换该基线。
- 当智能体不应看到任何 Skills 时，使用 `skills: []`。
- `agents.list[].skills` 会为一个智能体替换该基线。
- 当某个智能体不应看到任何 Skills 时，使用 `skills: []`。
### 多平台设置
@ -516,7 +517,7 @@ x-i18n:
### 可信节点网络自动批准
除非你控制网络路径，否则请保持设备配对为手动。对于专用实验室或 tailnet 子网，你可以选择使用精确的 CIDR 或 IP，为首次节点设备启用自动批准：
除非你控制网络路径，否则保持设备配对为手动。对于专用实验室或 tailnet 子网，你可以选择使用精确的 CIDR 或 IP，启用首次节点设备自动批准：
```json5
{
@ -530,11 +531,11 @@ x-i18n:
}
```
未设置时，此功能保持关闭。它仅适用于没有请求作用域的新 `role: node` 配对。操作员/浏览器客户端，以及 role、scope、metadata 或 public-key 升级仍需要手动批准。
未设置时，此功能保持关闭。它只适用于没有请求作用域的新 `role: node` 配对。操作员/浏览器客户端，以及角色、作用域、元数据或公钥升级，仍然需要手动批准。
### 安全私信模式（共享收件箱 / 多用户私信）
如果不止一个人可以向你的机器人发送私信（`allowFrom` 中有多个条目、多个用户的配对批准，或 `dmPolicy: "open"`），请启用**安全私信模式**，这样来自不同发送者的私信默认不会共享同一个上下文：
如果不止一个人可以私信你的 bot（`allowFrom` 中有多个条目、为多人批准了配对，或设置了 `dmPolicy: "open"`），请启用**安全私信模式**，这样来自不同发送者的私信默认不会共享同一个上下文：
```json5
{
@ -559,7 +560,7 @@ x-i18n:
```
对于 Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC，发送者授权默认优先使用 ID。
只有在你明确接受该风险时，才为各渠道启用 `dangerouslyAllowNameMatching: true`，以允许直接使用可变的名称/电子邮件/昵称进行匹配。
只有在你明确接受相应风险时，才通过每个渠道的 `dangerouslyAllowNameMatching: true` 启用直接可变的名称/电子邮件/nick 匹配。
### Anthropic API key + MiniMax 回退
@ -595,7 +596,7 @@ x-i18n:
}
```
### 工作机器人（受限访问）
### 工作 bot（受限访问）
```json5
{
@ -620,7 +621,7 @@ x-i18n:
}
```
### 仅本地模型
### 仅使用本地模型
```json5
{
@ -654,12 +655,12 @@ x-i18n:
## 提示
- 如果你设置了 `dmPolicy: "open"`，对应的 `allowFrom` 列表必须包含 `"*"`。
- 如果你设置 `dmPolicy: "open"`，对应的 `allowFrom` 列表必须包含 `"*"`。
- 提供商 ID 各不相同（电话号码、用户 ID、渠道 ID）。请使用提供商文档确认格式。
- 稍后可添加的可选部分：`web`、`browser`、`ui`、`discovery`、`canvasHost`、`talk`、`signal`、`imessage`。
- 请参阅[提供商](/zh-CN/providers)和[故障排除](/zh-CN/gateway/troubleshooting)，了解更深入的设置说明。
- 如需更深入的设置说明，请参阅[提供商](/zh-CN/providers)和[故障排除](/zh-CN/gateway/troubleshooting)。
## 相关内容
## 相关
- [配置参考](/zh-CN/gateway/configuration-reference)
- [配置](/zh-CN/gateway/configuration)

125
docs/zh-CN/tools/thinking.md
View File

@ -4,57 +4,57 @@ read_when:
summary: /think、/fast、/verbose、/trace 的指令语法和推理可见性
title: 思考级别
x-i18n:
generated_at: "2026-04-30T15:38:02Z"
generated_at: "2026-05-04T00:46:57Z"
model: gpt-5.5
provider: openai
source_hash: f9adf065e46cb64e4c2149b95ecd69ed887a17e2eff5a5569894defa3e7217b7
source_hash: 6fa1b0a2b5f7b93a706488c3ad39dfe08c08eed0bdd30880eb4c07d730ee4d4f
source_path: tools/thinking.md
workflow: 16
---
## 它的作用
- 任意入站正文中的内联指令：`/t <level>`、`/think:<level>` 或 `/thinking <level>`。
- 在任何入站正文中的内联指令：`/t <level>`、`/think:<level>` 或 `/thinking <level>`。
- 级别（别名）：`off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → “think”
- low → “think hard”
- medium → “think harder”
- high → “ultrathink”（最大预算）
- xhigh → “ultrathink+”（GPT-5.2+ 和 Codex 模型，以及 Anthropic Claude Opus 4.7 effort）
- adaptive → 由提供商管理的自适应思考（支持 Anthropic/Bedrock 上的 Claude 4.6、Anthropic Claude Opus 4.7，以及 Google Gemini 动态思考）
- max → 提供商最大推理（Anthropic Claude Opus 4.7；Ollama 会将其映射到自己的最高原生 `think` effort）
- adaptive → 提供商管理的自适应思考（支持 Anthropic/Bedrock 上的 Claude 4.6、Anthropic Claude Opus 4.7，以及 Google Gemini 动态思考）
- max → 提供商最大推理（Anthropic Claude Opus 4.7；Ollama 会将其映射到自身最高的原生 `think` effort）
- `x-high`、`x_high`、`extra-high`、`extra high` 和 `extra_high` 映射到 `xhigh`。
- `highest` 映射到 `high`。
- 提供商说明：
- 思考菜单和选择器由提供商配置文件驱动。提供商插件会声明所选模型的精确级别集合，包括二进制 `on` 等标签。
- `adaptive`、`xhigh` 和 `max` 只会为支持它们的提供商/模型配置文件展示。为不支持的级别输入的指令会被拒绝，并返回该模型的有效选项。
- 已存储的过期不支持级别会按提供商配置文件的等级重新映射。在非自适应模型上，`adaptive` 会回退到 `medium`，而 `xhigh` 和 `max` 会回退到所选模型支持的最大非 `off` 级别。
- Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adaptive`。
- Anthropic Claude Opus 4.7 不默认使用自适应思考。除非你显式设置思考级别，否则其 API effort 默认值仍由提供商拥有。
- Anthropic Claude Opus 4.7 会将 `/think xhigh` 映射到自适应思考加 `output_config.effort: "xhigh"`，因为 `/think` 是思考指令，而 `xhigh` 是 Opus 4.7 的 effort 设置。
- Anthropic Claude Opus 4.7 也暴露 `/think max`；它会映射到同一个提供商拥有的最大 effort 路径。
- DeepSeek V4 模型暴露 `/think xhigh|max`；两者都会映射到 DeepSeek `reasoning_effort: "max"`，而较低的非 `off` 级别会映射到 `high`。
- 支持思考的 Ollama 模型暴露 `/think low|medium|high|max`；`max` 会映射到原生 `think: "high"`，因为 Ollama 的原生 API 接受 `low`、`medium` 和 `high` effort 字符串。
- 思考菜单和选择器由提供商配置档案驱动。提供商插件会声明所选模型的精确级别集合，包括二元 `on` 等标签。
- `adaptive`、`xhigh` 和 `max` 只会对支持它们的提供商/模型配置档案公开。对不支持级别的类型化指令会被拒绝，并附上该模型的有效选项。
- 现有已存储但不支持的级别会按提供商配置档案排名重新映射。`adaptive` 在非自适应模型上回退到 `medium`，而 `xhigh` 和 `max` 会回退到所选模型支持的最大非关闭级别。
- 未设置显式思考级别时，Anthropic Claude 4.6 模型默认使用 `adaptive`。
- Anthropic Claude Opus 4.7 不会默认使用自适应思考。除非你显式设置思考级别，否则它的 API effort 默认值仍由提供商拥有。
- Anthropic Claude Opus 4.7 会将 `/think xhigh` 映射为自适应思考加 `output_config.effort: "xhigh"`，因为 `/think` 是思考指令，而 `xhigh` 是 Opus 4.7 的 effort 设置。
- Anthropic Claude Opus 4.7 也公开 `/think max`；它会映射到同一条提供商拥有的最大 effort 路径。
- DeepSeek V4 模型公开 `/think xhigh|max`；两者都会映射到 DeepSeek `reasoning_effort: "max"`，较低的非关闭级别会映射到 `high`。
- 支持思考的 Ollama 模型公开 `/think low|medium|high|max`；`max` 映射到原生 `think: "high"`，因为 Ollama 的原生 API 接受 `low`、`medium` 和 `high` effort 字符串。
- OpenAI GPT 模型会通过特定模型的 Responses API effort 支持来映射 `/think`。只有目标模型支持时，`/think off` 才会发送 `reasoning.effort: "none"`；否则 OpenClaw 会省略已禁用的推理载荷，而不是发送不支持的值。
- 自定义 OpenAI 兼容目录条目可以通过将 `models.providers.<provider>.models[].compat.supportedReasoningEfforts` 设为包含 `"xhigh"` 来选择启用 `/think xhigh`。这会使用同一套兼容元数据来映射出站 OpenAI 推理 effort 载荷，因此菜单、会话校验、智能体 CLI 和 `llm-task` 会与传输行为保持一致。
- 过期配置的 OpenRouter Hunter Alpha 引用会跳过代理推理注入，因为那条已废弃路由可能通过推理字段返回最终答案文本。
- Google Gemini 会将 `/think adaptive` 映射到 Gemini 由提供商拥有的动态思考。Gemini 3 请求会省略固定的 `thinkingLevel`，而 Gemini 2.5 请求会发送 `thinkingBudget: -1`；固定级别仍会映射到该模型家族最接近的 Gemini `thinkingLevel` 或预算。
- Anthropic 兼容流式路径上的 MiniMax（`minimax/*`）默认使用 `thinking: { type: "disabled" }`，除非你在模型参数或请求参数中显式设置思考。这可以避免 MiniMax 非原生 Anthropic 流格式泄漏 `reasoning_content` 增量。
- Z.AI（`zai/*`）只支持二进制思考（`on`/`off`）。任何非 `off` 级别都会被视为 `on`（映射到 `low`）。
- 自定义 OpenAI 兼容目录条目可以通过将 `models.providers.<provider>.models[].compat.supportedReasoningEfforts` 设置为包含 `"xhigh"` 来选择加入 `/think xhigh`。这会使用同一份用于映射出站 OpenAI 推理 effort 载荷的兼容元数据，因此菜单、会话校验、智能体 CLI 和 `llm-task` 会与传输行为保持一致。
- 过期配置的 OpenRouter Hunter Alpha 引用会跳过代理推理注入，因为该已退役路由可能通过推理字段返回最终答案文本。
- Google Gemini 会将 `/think adaptive` 映射到 Gemini 的提供商拥有动态思考。Gemini 3 请求会省略固定的 `thinkingLevel`，而 Gemini 2.5 请求会发送 `thinkingBudget: -1`；固定级别仍会映射到该模型系列最接近的 Gemini `thinkingLevel` 或预算。
- Anthropic 兼容流式路径上的 MiniMax（`minimax/*`）默认使用 `thinking: { type: "disabled" }`，除非你在模型参数或请求参数中显式设置思考。这避免了 MiniMax 非原生 Anthropic 流格式泄露 `reasoning_content` 增量。
- Z.AI（`zai/*`）只支持二元思考（`on`/`off`）。任何非 `off` 级别都会被视为 `on`（映射到 `low`）。
- Moonshot（`moonshot/*`）会将 `/think off` 映射到 `thinking: { type: "disabled" }`，并将任何非 `off` 级别映射到 `thinking: { type: "enabled" }`。启用思考时，Moonshot 只接受 `tool_choice` `auto|none`；OpenClaw 会将不兼容的值规范化为 `auto`。
## 解析顺序
1. 消息上的内联指令（仅应用于该消息）。
2. 会话覆盖（通过发送仅含指令的消息设置）。
3. 每个智能体默认值（配置中的 `agents.list[].thinkingDefault`）。
3. 每智能体默认值（配置中的 `agents.list[].thinkingDefault`）。
4. 全局默认值（配置中的 `agents.defaults.thinkingDefault`）。
5. 回退：可用时使用提供商声明的默认值；否则，具备推理能力的模型会解析为 `medium` 或该模型支持的最接近的非 `off` 级别，不具备推理能力的模型保持 `off`。
5. 回退：可用时使用提供商声明的默认值；否则，具备推理能力的模型会解析为 `medium` 或该模型最接近的受支持非 `off` 级别，不具备推理能力的模型保持 `off`。
## 设置会话默认值
- 发送一条**只包含**该指令的消息（允许空白），例如 `/think:medium` 或 `/t high`。
- 这会固定到当前会话（默认按发送者区分）；通过 `/think:off` 或会话空闲重置清除。
- 发送一条**仅**包含指令的消息（允许空白），例如 `/think:medium` 或 `/t high`。
- 它会在当前会话中保持生效（默认按发送者区分）；通过 `/think:off` 或会话空闲重置清除。
- 会发送确认回复（`Thinking level set to high.` / `Thinking disabled.`）。如果级别无效（例如 `/thinking big`），命令会被拒绝并附带提示，会话状态保持不变。
- 发送不带参数的 `/think`（或 `/think:`）可查看当前思考级别。
@ -66,75 +66,78 @@ x-i18n:
- 级别：`on|off`。
- 仅含指令的消息会切换会话快速模式覆盖，并回复 `Fast mode enabled.` / `Fast mode disabled.`。
- 发送不带模式的 `/fast`（或 `/fast status`）可查看当前有效快速模式状态。
- 发送不带模式的 `/fast`（或 `/fast status`）可查看当前生效的快速模式状态。
- OpenClaw 按以下顺序解析快速模式：
1. 内联/仅含指令的 `/fast on|off`
2. 会话覆盖
3. 每个智能体默认值（`agents.list[].fastModeDefault`）
4. 每个模型配置：`agents.defaults.models["<provider>/<model>"].params.fastMode`
3. 每智能体默认值（`agents.list[].fastModeDefault`）
4. 每模型配置：`agents.defaults.models["<provider>/<model>"].params.fastMode`
5. 回退：`off`
- 对于 `openai/*`，快速模式会通过在支持的 Responses 请求上发送 `service_tier=priority` 映射到 OpenAI 优先处理。
- 对于 `openai-codex/*`，快速模式会在 Codex Responses 上发送同一个 `service_tier=priority` 标志。OpenClaw 在两个凭证路径之间保持一个共享的 `/fast` 开关。
- 对于直接公开的 `anthropic/*` 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，快速模式会映射到 Anthropic service tiers：`/fast on` 设置 `service_tier=auto`，`/fast off` 设置 `service_tier=standard_only`。
- 对于 Anthropic 兼容路径上的 `minimax/*`，`/fast on`（或 `params.fastMode: true`）会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
- 当显式 Anthropic `serviceTier` / `service_tier` 模型参数与快速模式默认值同时设置时，前者会覆盖后者。OpenClaw 仍会对非 Anthropic 代理基础 URL 跳过 Anthropic service-tier 注入。
- `/status` 只有在快速模式启用时才显示 `Fast`。
- 对于 `openai-codex/*`，快速模式会在 Codex Responses 上发送同一个 `service_tier=priority` 标志。OpenClaw 会在两条身份验证路径之间保留一个共享的 `/fast` 切换。
- 对于直接公开的 `anthropic/*` 请求，包括发送到 `api.anthropic.com` 的 OAuth 身份验证流量，快速模式会映射到 Anthropic 服务层级：`/fast on` 设置 `service_tier=auto`，`/fast off` 设置 `service_tier=standard_only`。
- 对于 Anthropic 兼容路径上的 `minimax/*`，`/fast on`（或 `params.fastMode: true`）会将 `MiniMax-M2.7` 改写为 `MiniMax-M2.7-highspeed`。
- 当两者都设置时，显式 Anthropic `serviceTier` / `service_tier` 模型参数会覆盖快速模式默认值。对于非 Anthropic 代理基准 URL，OpenClaw 仍会跳过 Anthropic 服务层级注入。
- `/status` 只会在启用快速模式时显示 `Fast`。
## 详细指令（/verbose 或 /v）
- 级别：`on`（最小）| `full` | `off`（默认）。
- 仅含指令的消息会切换会话详细日志并回复 `Verbose logging enabled.` / `Verbose logging disabled.`；无效级别会返回提示且不改变状态。
- `/verbose off` 会存储显式会话覆盖；可在会话 UI 中选择 `inherit` 来清除。
- 仅含指令的消息会切换会话详细模式，并回复 `Verbose logging enabled.` / `Verbose logging disabled.`；无效级别会返回提示且不改变状态。
- `/verbose off` 会存储一个显式会话覆盖；可通过会话 UI 选择 `inherit` 来清除它。
- 内联指令只影响该消息；否则应用会话/全局默认值。
- 发送不带参数的 `/verbose`（或 `/verbose:`）可查看当前详细级别。
- 启用详细模式时，会发出结构化工具结果的智能体（Pi 和其他 JSON 智能体）会把每次工具调用作为单独的仅元数据消息发回，可用时前缀为 `<emoji> <tool-name>: <arg>`（路径/命令）。这些工具摘要会在每个工具启动后立即发送（单独气泡），而不是作为流式增量发送。
- 启用详细模式时，会发出结构化工具结果的智能体（Pi、其他 JSON 智能体）会将每次工具调用作为自己的仅元数据消息发回，可用时前缀为 `<emoji> <tool-name>: <arg>`。这些工具摘要会在每个工具启动后立即发送（单独气泡），而不是作为流式增量发送。
- 工具失败摘要在普通模式下仍可见，但原始错误详情后缀会隐藏，除非详细级别为 `on` 或 `full`。
- 当详细级别为 `full` 时，工具输出也会在完成后转发（单独气泡，截断到安全长度）。如果你在一次运行进行中切换 `/verbose on|full|off`，后续工具气泡会遵循新设置。
- 当详细级别为 `full` 时，工具输出也会在完成后转发（单独气泡，截断到安全长度）。如果你在运行过程中切换 `/verbose on|full|off`，后续工具气泡会遵循新设置。
- `agents.defaults.toolProgressDetail` 控制 `/verbose` 工具摘要和进度草稿工具行的形态。使用 `"explain"`（默认）获得紧凑的人类标签，例如 `🛠️ Exec: checking JS syntax`；当你还希望追加原始命令/详情用于调试时，使用 `"raw"`。每智能体 `agents.list[].toolProgressDetail` 会覆盖默认值。
- `explain`：`🛠️ Exec: check JS syntax for /tmp/app.js`
- `raw`：`🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js`
## 插件跟踪指令（/trace）
## 插件追踪指令（/trace）
- 级别：`on` | `off`（默认）。
- 仅含指令的消息会切换会话插件跟踪输出并回复 `Plugin trace enabled.` / `Plugin trace disabled.`。
- 仅含指令的消息会切换会话插件追踪输出，并回复 `Plugin trace enabled.` / `Plugin trace disabled.`。
- 内联指令只影响该消息；否则应用会话/全局默认值。
- 发送不带参数的 `/trace`（或 `/trace:`）可查看当前跟踪级别。
- `/trace` 比 `/verbose` 范围更窄：它只暴露插件拥有的跟踪/调试行，例如 Active Memory 调试摘要。
- 跟踪行可以出现在 `/status` 中，也可以在普通助手回复之后作为后续诊断消息出现。
- 发送不带参数的 `/trace`（或 `/trace:`）可查看当前追踪级别。
- `/trace` 比 `/verbose` 更窄：它只公开插件拥有的追踪/调试行，例如主动记忆调试摘要。
- 追踪行可出现在 `/status` 中，也可在正常助手回复后作为后续诊断消息出现。
## 推理可见性（/reasoning）
- 级别：`on|off|stream`。
- 仅含指令的消息会切换是否在回复中显示思考块。
- 启用后，推理会作为**单独消息**发送，并以 `Reasoning:` 为前缀。
- `stream`（仅 Telegram）：在回复生成期间将推理流式传输到 Telegram 草稿气泡中，然后发送不含推理的最终答案。
- 启用后，推理会作为**单独消息**发送，前缀为 `Reasoning:`。
- `stream`（仅 Telegram）：在生成回复时将推理流式传输到 Telegram 草稿气泡中，然后发送不含推理的最终答案。
- 别名：`/reason`。
- 发送不带参数的 `/reasoning`（或 `/reasoning:`）可查看当前推理级别。
- 解析顺序：内联指令，然后是会话覆盖，然后是每个智能体默认值（`agents.list[].reasoningDefault`），最后回退（`off`）。
- 解析顺序：内联指令，然后会话覆盖，然后每智能体默认值（`agents.list[].reasoningDefault`），然后回退（`off`）。
格式错误的本地模型推理标签会被保守处理。已闭合的 <think>...</think> 块在普通回复中保持隐藏，已可见文本之后未闭合的推理也会隐藏。如果回复完全包裹在单个未闭合起始标签中，并且原本会作为空文本交付，OpenClaw 会移除格式错误的起始标签并交付剩余文本。
格式错误的本地模型推理标签会被保守处理。闭合的 `<think>...</think>` 块在普通回复中保持隐藏，已显示文本之后未闭合的推理也会隐藏。如果回复完全包裹在单个未闭合的开始标签中，并且原本会作为空文本发送，OpenClaw 会移除格式错误的开始标签并发送剩余文本。
## 相关
## 相关内容
- 提权模式文档位于 [提权模式](/zh-CN/tools/elevated)。
- 提升模式文档位于[提升模式](/zh-CN/tools/elevated)。
## Heartbeat
## Heartbeats
- Heartbeat 探测正文是配置的 Heartbeat 提示（默认：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。Heartbeat 消息中的内联指令会照常应用（但应避免从 Heartbeat 更改会话默认值）。
- Heartbeat 交付默认只发送最终载荷。如需同时发送单独的 `Reasoning:` 消息（可用时），请设置 `agents.defaults.heartbeat.includeReasoning: true` 或每个智能体的 `agents.list[].heartbeat.includeReasoning: true`。
- Heartbeat 探测正文是配置的 Heartbeat 提示（默认：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。Heartbeat 消息中的内联指令照常应用（但避免通过 Heartbeat 更改会话默认值）。
- Heartbeat 交付默认仅发送最终载荷。若还要发送单独的 `Reasoning:` 消息（可用时），请设置 `agents.defaults.heartbeat.includeReasoning: true` 或每智能体 `agents.list[].heartbeat.includeReasoning: true`。
## Web 聊天 UI
- 页面加载时，Web 聊天思考选择器会从入站会话存储/配置镜像该会话已存储的级别。
- Web 聊天思考选择器会在页面加载时从入站会话存储/配置中镜像会话的已存储级别。
- 选择另一个级别会立即通过 `sessions.patch` 写入会话覆盖；它不会等待下一次发送，也不是一次性的 `thinkingOnce` 覆盖。
- 第一个选项始终是 `Default (<resolved level>)`，其中解析后的默认值来自活跃会话模型的提供商思考配置文件，以及 `/status` 和 `session_status` 使用的同一套回退逻辑。
- 选择器使用 Gateway 网关会话行/默认值返回的 `thinkingLevels`，并将 `thinkingOptions` 保留为旧版标签列表。浏览器 UI 不保留自己的提供商正则列表；插件拥有特定模型的级别集合。
- `/think:<level>` 仍然有效，并会更新同一个已存储的会话级别，因此聊天指令和选择器会保持同步。
- 第一个选项始终是 `Default (<resolved level>)`，其中解析后的默认值来自活跃会话模型的提供商思考配置档案，以及 `/status` 和 `session_status` 使用的同一套回退逻辑。
- 选择器使用 Gateway 网关会话行/默认值返回的 `thinkingLevels`，并将 `thinkingOptions` 保留为旧版标签列表。浏览器 UI 不保留自己的提供商正则列表；插件拥有模型特定的级别集合。
- `/think:<level>` 仍然有效，并会更新同一个已存储会话级别，因此聊天指令和选择器保持同步。
## 提供商配置文件
## 提供商配置档案
- 提供商插件可以公开 `resolveThinkingProfile(ctx)`，用于定义模型支持的级别和默认值。
- 代理 Claude 模型的提供商插件应复用 `openclaw/plugin-sdk/provider-model-shared` 中的 `resolveClaudeThinkingProfile(modelId)`，以便直接 Anthropic 和代理目录保持一致。
- 每个配置级别都有一个已存储的规范 `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive` 或 `max`），并且可以包含一个显示用的 `label`。二元提供商使用 `{ id: "low", label: "on" }`。
- 需要验证显式思考覆盖设置的工具插件应使用 `api.runtime.agent.resolveThinkingPolicy({ provider, model })` 加上 `api.runtime.agent.normalizeThinkingLevel(...)`；它们不应维护自己的提供商/模型级别列表。
- 能访问已配置自定义模型元数据的工具插件可以将 `catalog` 传入 `resolveThinkingPolicy`，这样 `compat.supportedReasoningEfforts` 选择启用项会体现在插件侧验证中。
- 已发布的旧版钩子（`supportsXHighThinking`、`isBinaryThinking` 和 `resolveDefaultThinkingLevel`）会继续作为兼容性适配器保留，但新的自定义级别集合应使用 `resolveThinkingProfile`。
- Gateway 网关行/默认值会公开 `thinkingLevels`、`thinkingOptions` 和 `thinkingDefault`，以便 ACP/chat 客户端渲染与运行时验证所用相同的配置 `id` 和标签。
- 提供商插件可以暴露 `resolveThinkingProfile(ctx)`，用于定义模型支持的等级和默认值。
- 代理 Claude 模型的提供商插件应复用来自 `openclaw/plugin-sdk/provider-model-shared` 的 `resolveClaudeThinkingProfile(modelId)`，这样直接 Anthropic 和代理目录能保持一致。
- 每个配置等级都有一个已存储的规范 `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive` 或 `max`），并且可以包含显示用的 `label`。二值型提供商使用 `{ id: "low", label: "on" }`。
- 需要验证显式 thinking 覆盖值的工具插件应使用 `api.runtime.agent.resolveThinkingPolicy({ provider, model })` 加上 `api.runtime.agent.normalizeThinkingLevel(...)`；它们不应维护自己的提供商/模型等级列表。
- 能访问已配置自定义模型元数据的工具插件可以将 `catalog` 传入 `resolveThinkingPolicy`，这样 `compat.supportedReasoningEfforts` 的选择启用会反映到插件侧验证中。
- 已发布的旧钩子（`supportsXHighThinking`、`isBinaryThinking` 和 `resolveDefaultThinkingLevel`）会继续作为兼容性适配器保留，但新的自定义等级集合应使用 `resolveThinkingProfile`。
- Gateway 网关行/默认值会暴露 `thinkingLevels`、`thinkingOptions` 和 `thinkingDefault`，这样 ACP/chat 客户端会渲染与运行时验证使用的相同配置 `id` 和标签。

289
docs/zh-CN/web/control-ui.md
View File

@ -3,23 +3,23 @@ read_when:
- 你想通过浏览器操作 Gateway 网关
- 你想要无需 SSH 隧道即可访问 Tailnet
sidebarTitle: Control UI
summary: 用于 Gateway 网关的基于浏览器的控制 UI（聊天、节点、配置）
summary: 基于浏览器的 Gateway 网关控制界面（聊天、节点、配置）
title: 控制界面
x-i18n:
generated_at: "2026-05-02T23:43:24Z"
generated_at: "2026-05-04T00:47:42Z"
model: gpt-5.5
provider: openai
source_hash: 88959ccf435b31015039bf28c3043023d99f0b953a1489986ab2d0cbd261771c
source_hash: c890d83da2c296b600e4b5a00a538f37e6bd54da31fbe62113ecd6177b15626e
source_path: web/control-ui.md
workflow: 16
---
Control UI 是由 Gateway 网关提供服务的小型 **Vite + Lit** 单页应用：
控制 UI 是由 Gateway 网关提供服务的小型 **Vite + Lit** 单页应用：
- 默认：`http://<host>:18789/`
- 可选前缀：设置 `gateway.controlUi.basePath`（例如 `/openclaw`）
它会在同一端口上**直接连接到 Gateway 网关 WebSocket**。
它会在同一端口上**直接与 Gateway 网关 WebSocket** 通信。
## 快速打开（本地）
@ -33,160 +33,161 @@ Control UI 是由 Gateway 网关提供服务的小型 **Vite + Lit** 单页应
- `connect.params.auth.token`
- `connect.params.auth.password`
- 当 `gateway.auth.allowTailscale: true` 时使用 Tailscale Serve 身份标头
- 当 `gateway.auth.mode: "trusted-proxy"` 时使用可信代理身份标头
- `gateway.auth.allowTailscale: true` 时的 Tailscale Serve 身份标头
- `gateway.auth.mode: "trusted-proxy"` 时的可信代理身份标头
仪表盘设置面板会为当前浏览器标签页会话和所选 Gateway 网关 URL 保留一个令牌；密码不会持久保存。新手引导通常会在首次连接时为共享密钥身份验证生成 Gateway 网关令牌，但当 `gateway.auth.mode` 为 `"password"` 时，密码身份验证也可使用。
仪表盘设置面板会为当前浏览器标签页会话和选定的 Gateway 网关 URL 保留一个令牌；密码不会被持久保存。新手引导通常会在首次连接时为共享密钥身份验证生成 Gateway 网关令牌，但当 `gateway.auth.mode` 为 `"password"` 时，也可以使用密码身份验证。
## 设备配对（首次连接）
当你从新的浏览器或设备连接到 Control UI 时，Gateway 网关通常会要求进行**一次性配对批准**。这是一项安全措施，用于防止未经授权的访问。
当你从新的浏览器或设备连接到控制 UI 时，Gateway 网关通常需要**一次性配对批准**。这是一项防止未授权访问的安全措施。
**你会看到：**“disconnected (1008): pairing required”
<Steps>
<Step title="List pending requests">
<Step title="列出待处理请求">
```bash
openclaw devices list
```
</Step>
<Step title="Approve by request ID">
<Step title="按请求 ID 批准">
```bash
openclaw devices approve <requestId>
```
</Step>
</Steps>
如果浏览器使用已更改的身份验证详情（角色/范围/公钥）重试配对，之前待处理的请求会被取代，并创建新的 `requestId`。批准前请重新运行 `openclaw devices list`。
如果浏览器使用已更改的身份验证详情（角色/范围/公钥）重试配对，之前的待处理请求会被取代，并创建新的 `requestId`。批准前请重新运行 `openclaw devices list`。
如果浏览器已经配对，而你将它从读取访问权限改为写入/管理员访问权限，这会被视为一次批准升级，而不是静默重新连接。OpenClaw 会保留旧批准的活跃状态，阻止权限更宽的重新连接，并要求你明确批准新的范围集合。
如果浏览器已配对，而你将其从读取访问改为写入/管理员访问，这会被视为一次批准升级，而不是静默重连。OpenClaw 会保持旧批准有效，阻止范围更广的重连，并要求你显式批准新的范围集合。
批准后，设备会被记住，不会再要求重新批准，除非你使用 `openclaw devices revoke --device <id> --role <role>` 撤销它。有关令牌轮换和撤销，请参阅 [设备 CLI](/zh-CN/cli/devices)。
批准后，设备会被记住，不会再次要求批准，除非你使用 `openclaw devices revoke --device <id> --role <role>` 撤销它。有关令牌轮换和撤销，请参阅 [设备 CLI](/zh-CN/cli/devices)。
<Note>
- 直接的 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会自动批准。
- 当 `gateway.auth.allowTailscale: true`、Tailscale 身份验证通过，并且浏览器呈现其设备身份时，Tailscale Serve 可以为 Control UI 操作员会话跳过配对往返。
- 直接 Tailnet 绑定、LAN 浏览器连接，以及没有设备身份的浏览器配置文件仍需要显式批准。
- 每个浏览器配置文件都会生成唯一设备 ID，因此切换浏览器或清除浏览器数据需要重新配对。
- 直接 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会自动批准。
- 当 `gateway.auth.allowTailscale: true`、Tailscale 身份通过验证，并且浏览器提供其设备身份时，Tailscale Serve 可以为控制 UI 操作员会话跳过配对往返。
- 直接 Tailnet 绑定、局域网浏览器连接，以及没有设备身份的浏览器配置文件仍然需要显式批准。
- 每个浏览器配置文件都会生成唯一的设备 ID，因此切换浏览器或清除浏览器数据将需要重新配对。
</Note>
## 个人身份（浏览器本地）
Control UI 支持按浏览器设置个人身份（显示名称和头像），并将其附加到外发消息，以便在共享会话中标明归属。它存储在浏览器存储中，作用域限定为当前浏览器配置文件，不会同步到其他设备，也不会在服务器端持久保存，除非是你实际发送消息时正常的转录作者身份元数据。清除站点数据或切换浏览器会将其重置为空。
控制 UI 支持按浏览器设置个人身份（显示名称和头像），并将其附加到发出的消息中，以便在共享会话中标明归属。它存放在浏览器存储中，作用域限定为当前浏览器配置文件，不会同步到其他设备，也不会在服务器端持久保存，除了你实际发送的消息上正常的转录作者元数据。清除站点数据或切换浏览器会将其重置为空。
同样的浏览器本地模式也适用于助手头像覆盖。上传的助手头像只会在本地浏览器中覆盖 Gateway 网关解析出的身份，且绝不会通过 `config.patch` 往返传输。共享的 `ui.assistant.avatar` 配置字段仍可供非 UI 客户端直接写入该字段（例如脚本化 Gateway 网关或自定义仪表盘）。
同样的浏览器本地模式也适用于助手头像覆盖。上传的助手头像只会在本地浏览器中覆盖 Gateway 网关解析出的身份，绝不会通过 `config.patch` 往返传输。共享的 `ui.assistant.avatar` 配置字段仍可供直接写入该字段的非 UI 客户端使用（例如脚本化 Gateway 网关或自定义仪表盘）。
## 运行时配置端点
Control UI 会从 `/__openclaw/control-ui-config.json` 获取其运行时设置。该端点与 HTTP 其余表面一样受同一 Gateway 网关身份验证保护：未经身份验证的浏览器无法获取它；成功获取需要已有有效的 Gateway 网关令牌/密码、Tailscale Serve 身份，或可信代理身份。
控制 UI 会从 `/__openclaw/control-ui-config.json` 获取运行时设置。该端点与 HTTP 表面的其余部分一样受同一 Gateway 网关身份验证保护：未经身份验证的浏览器无法获取它；成功获取需要已有有效的 Gateway 网关令牌/密码、Tailscale Serve 身份，或可信代理身份。
## 语言支持
Control UI 可以在首次加载时根据你的浏览器语言区域本地化自身。若要稍后覆盖它，请打开 **Overview -> Gateway Access -> Language**。语言区域选择器位于 Gateway Access 卡片中，而不是 Appearance 下。
控制 UI 可以在首次加载时根据你的浏览器区域设置进行本地化。若要稍后覆盖它，请打开 **概览 -> Gateway 网关访问 -> 语言**。区域设置选择器位于 Gateway 网关访问卡片中，而不是外观下。
- 支持的语言区域：`en`、`zh-CN`、`zh-TW`、`pt-BR`、`de`、`es`、`ja-JP`、`ko`、`fr`、`ar`、`it`、`tr`、`uk`、`id`、`pl`、`th`、`vi`、`nl`、`fa`
- 支持的区域设置：`en`、`zh-CN`、`zh-TW`、`pt-BR`、`de`、`es`、`ja-JP`、`ko`、`fr`、`ar`、`it`、`tr`、`uk`、`id`、`pl`、`th`、`vi`、`nl`、`fa`
- 非英语翻译会在浏览器中懒加载。
- 所选语言区域会保存在浏览器存储中，并在未来访问时复用。
- 选定的区域设置会保存在浏览器存储中，并在以后访问时复用。
- 缺失的翻译键会回退到英语。
文档翻译会为同一组非英语语言区域生成，但文档站点内置的 Mintlify 语言选择器受限于 Mintlify 接受的语言区域代码。泰语（`th`）和波斯语（`fa`）文档仍会在发布仓库中生成；在 Mintlify 支持这些代码之前，它们可能不会出现在该选择器中。
文档翻译会为同一组非英语区域设置生成，但文档站点内置的 Mintlify 语言选择器仅限于 Mintlify 接受的区域设置代码。泰语（`th`）和波斯语（`fa`）文档仍会在发布仓库中生成；在 Mintlify 支持这些代码之前，它们可能不会出现在该选择器中。
## 外观主题
Appearance 面板保留内置的 Claw、Knot 和 Dash 主题，以及一个浏览器本地 tweakcn 导入槽位。要导入主题，请打开 [tweakcn themes](https://tweakcn.com/themes)，选择或创建主题，点击 **Share**，然后将复制的主题链接粘贴到 Appearance。导入器也接受 `https://tweakcn.com/r/themes/<id>` 注册表 URL、类似 `https://tweakcn.com/editor/theme?theme=amethyst-haze` 的编辑器 URL、相对 `/themes/<id>` 路径、原始主题 ID，以及 `amethyst-haze` 等默认主题名称。
外观面板保留内置的 Claw、Knot 和 Dash 主题，外加一个浏览器本地的 tweakcn 导入槽。若要导入主题，请打开 [tweakcn 主题](https://tweakcn.com/themes)，选择或创建一个主题，点击 **分享**，然后将复制的主题链接粘贴到外观中。导入器也接受 `https://tweakcn.com/r/themes/<id>` 注册表 URL、类似 `https://tweakcn.com/editor/theme?theme=amethyst-haze` 的编辑器 URL、相对 `/themes/<id>` 路径、原始主题 ID，以及 `amethyst-haze` 等默认主题名称。
导入的主题只存储在当前浏览器配置文件中。它们不会写入 Gateway 网关配置，也不会跨设备同步。替换导入的主题会更新唯一的本地槽位；如果当前选中了导入的主题，清除它会将活跃主题切回 Claw。
导入的主题只会存储在当前浏览器配置文件中。它们不会写入 Gateway 网关配置，也不会跨设备同步。替换导入的主题会更新这一个本地槽；如果已选择导入的主题，清除它会将活动主题切回 Claw。
## 它现在能做什么
## 它目前可以做什么
<AccordionGroup>
<Accordion title="Chat and Talk">
<Accordion title="聊天和语音">
- 通过 Gateway 网关 WS 与模型聊天（`chat.history`、`chat.send`、`chat.abort`、`chat.inject`）。
- 通过浏览器实时会话进行语音对话。OpenAI 使用直接 WebRTC，Google Live 通过 WebSocket 使用受限的一次性浏览器令牌，而仅后端的实时语音插件使用 Gateway 网关中继传输。中继会将提供商凭据保留在 Gateway 网关上，同时浏览器通过 `talk.realtime.relay*` RPC 流式传输麦克风 PCM，并通过 `chat.send` 将 `openclaw_agent_consult` 工具调用发送回更大的已配置 OpenClaw 模型。
- 在 Chat 中流式传输工具调用 + 实时工具输出卡片（智能体事件）。
- 通过浏览器实时会话进行语音通话。OpenAI 使用直接 WebRTC，Google Live 通过 WebSocket 使用受限的一次性浏览器令牌，而仅后端实时语音插件使用 Gateway 网关中继传输。中继会将提供商凭证保留在 Gateway 网关上，同时浏览器通过 `talk.realtime.relay*` RPC 流式传输麦克风 PCM，并通过 `chat.send` 将 `openclaw_agent_consult` 工具调用发回给已配置的更大型 OpenClaw 模型。
- 在聊天中流式传输工具调用 + 实时工具输出卡片（智能体事件）。
</Accordion>
<Accordion title="Channels, instances, sessions, dreams">
- 渠道：内置渠道以及内置/外部插件渠道的状态、二维码登录和按渠道配置（`channels.status`、`web.login.*`、`config.patch`）。
<Accordion title="渠道、实例、会话、梦境">
- 渠道：内置渠道以及内置/外部插件渠道的 Status、二维码登录和按渠道配置（`channels.status`、`web.login.*`、`config.patch`）。
- 实例：在线列表 + 刷新（`system-presence`）。
- 会话：列表 + 按会话设置模型/思考/快速/详细/跟踪/推理覆盖项（`sessions.list`、`sessions.patch`）。
- Dreams：Dreaming 状态、启用/禁用开关，以及 Dream Diary 阅读器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。
- 会话：列表 + 按会话的模型/思考/快速/详细/跟踪/推理覆盖（`sessions.list`、`sessions.patch`）。
- 梦境：Dreaming 状态、启用/禁用切换，以及 Dream Diary 阅读器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。
</Accordion>
<Accordion title="Cron, skills, nodes, exec approvals">
- Cron 作业：列出/添加/编辑/运行/启用/禁用 + 运行历史（`cron.*`）。
- Skills：状态、启用/禁用、安装、API key 更新（`skills.*`）。
<Accordion title="Cron、Skills、节点、exec 批准">
- Cron 任务：列出/添加/编辑/运行/启用/禁用 + 运行历史（`cron.*`）。
- Skills：Status、启用/禁用、安装、API key 更新（`skills.*`）。
- 节点：列表 + 能力（`node.list`）。
- Exec 批准：编辑 Gateway 网关或节点 allowlist + `exec host=gateway/node` 的询问策略（`exec.approvals.*`）。
</Accordion>
<Accordion title="Config">
<Accordion title="配置">
- 查看/编辑 `~/.openclaw/openclaw.json`（`config.get`、`config.set`）。
- 通过验证应用 + 重启（`config.apply`），并唤醒上一个活跃会话。
- 通过验证应用 + 重启（`config.apply`），并唤醒上一个活动会话。
- 写入包含 base-hash 保护，以防覆盖并发编辑。
- 写入（`config.set`/`config.apply`/`config.patch`）会对提交的配置载荷中的引用预检活跃 SecretRef 解析；未解析的活跃已提交引用会在写入前被拒绝。
- Schema + 表单渲染（`config.schema` / `config.schema.lookup`，包括字段 `title` / `description`、匹配的 UI 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点上的文档元数据，以及可用时的插件 + 渠道 schema）；仅当快照具备安全的原始往返能力时，Raw JSON 编辑器才可用。
- 如果快照无法安全地往返原始文本，Control UI 会强制使用 Form 模式，并为该快照禁用 Raw 模式。
- Raw JSON 编辑器的 “Reset to saved” 会保留原始作者编辑的形态（格式、注释、`$include` 布局），而不是重新渲染扁平化快照，因此当快照可以安全往返时，外部编辑会在重置后保留下来。
- 结构化 SecretRef 对象值会在表单文本输入中以只读方式呈现，以防意外发生对象到字符串的损坏。
- 写入（`config.set`/`config.apply`/`config.patch`）会预检提交的配置载荷中引用的活动 SecretRef 解析；未解析的活动提交引用会在写入前被拒绝。
- Schema + 表单渲染（`config.schema` / `config.schema.lookup`，包括字段 `title` / `description`、匹配的 UI 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点上的文档元数据，以及可用时的插件 + 渠道 schema）；仅当快照可以安全进行原始往返时，原始 JSON 编辑器才可用。
- 如果快照无法安全往返原始文本，控制 UI 会强制使用表单模式，并为该快照禁用原始模式。
- 原始 JSON 编辑器的“重置为已保存”会保留原始编写的形状（格式、注释、`$include` 布局），而不是重新渲染扁平化快照，因此当快照可以安全往返时，外部编辑在重置后仍会保留。
- 结构化 SecretRef 对象值会在表单文本输入中以只读方式渲染，以防意外发生对象到字符串的损坏。
</Accordion>
<Accordion title="Debug, logs, update">
- 调试：状态/健康/模型快照 + 事件日志 + 手动 RPC 调用（`status`、`health`、`models.list`）。
- 日志：带过滤/导出的 Gateway 网关文件日志实时 tail（`logs.tail`）。
- 更新：运行包/git 更新 + 重启（`update.run`）并生成重启报告，然后在重新连接后轮询 `update.status`，以验证正在运行的 Gateway 网关版本。
<Accordion title="调试、日志、更新">
- 调试：Status/health/models 快照 + 事件日志 + 手动 RPC 调用（`status`、`health`、`models.list`）。
- 日志：Gateway 网关文件日志的实时 tail，支持过滤/导出（`logs.tail`）。
- 更新：运行包/git 更新 + 重启（`update.run`）并生成重启报告，然后在重连后轮询 `update.status` 以验证正在运行的 Gateway 网关版本。
</Accordion>
<Accordion title="Cron jobs panel notes">
- 对于隔离作业，投递默认会发布摘要。如果你想要仅内部运行，可以切换为 none。
- 选择 announce 时会显示渠道/目标字段。
- Webhook 模式使用 `delivery.mode = "webhook"`，并将 `delivery.to` 设置为有效的 HTTP(S) webhook URL。
- 对于主会话作业，webhook 和 none 投递模式可用。
- 高级编辑控件包括运行后删除、清除智能体覆盖项、cron exact/stagger 选项、智能体模型/思考覆盖项，以及尽力投递开关。
- 表单验证以内联方式显示字段级错误；无效值会禁用保存按钮，直到修正为止。
- 设置 `cron.webhookToken` 可发送专用 bearer 令牌；如果省略，则 webhook 会在没有身份验证标头的情况下发送。
- 已弃用的回退：存储的旧版作业如果带有 `notify: true`，在迁移前仍可使用 `cron.webhook`。
<Accordion title="Cron 任务面板说明">
- 对于隔离任务，交付默认发布摘要。如果你想要仅内部运行，可以切换为无。
- 选择发布时会显示渠道/目标字段。
- Webhook 模式使用 `delivery.mode = "webhook"`，并将 `delivery.to` 设为有效的 HTTP(S) webhook URL。
- 对于主会话任务，可以使用 webhook 和无交付模式。
- 高级编辑控件包括运行后删除、清除智能体覆盖、cron 精确/错峰选项、智能体模型/思考覆盖，以及尽力交付切换。
- 表单验证以内联方式显示字段级错误；无效值会禁用保存按钮，直到修复为止。
- 设置 `cron.webhookToken` 以发送专用 bearer 令牌；如果省略，webhook 会在没有身份验证标头的情况下发送。
- 已弃用的回退：存储的旧版任务如果带有 `notify: true`，在迁移前仍可使用 `cron.webhook`。
</Accordion>
</AccordionGroup>
## Chat 行为
## 聊天行为
<AccordionGroup>
<Accordion title="发送和历史语义">
- `chat.send` 是**非阻塞**的：它会立即确认并返回 `{ runId, status: "started" }`，响应会通过 `chat` 事件流式传输。
- 聊天上传接受图片和非视频文件。图片保留原生图片路径；其他文件会作为托管媒体存储，并在历史记录中显示为附件链接。
- 使用同一个 `idempotencyKey` 重新发送时，运行中会返回 `{ status: "in_flight" }`，完成后会返回 `{ status: "ok" }`。
- 为保证 UI 安全，`chat.history` 响应有大小限制。当转录条目过大时，Gateway 网关可能会截断长文本字段，省略较大的元数据块，并将超大的消息替换为占位符（`[chat.history omitted: message too large]`）。
- 助手/生成的图片会作为托管媒体引用持久化，并通过经过身份验证的 Gateway 网关媒体 URL 返回，因此重新加载不依赖原始 base64 图片载荷继续保留在聊天历史响应中。
- `chat.history` 还会从可见的助手文本中剥离仅用于显示的内联指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 载荷（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 以及被截断的工具调用块），以及泄漏的 ASCII/全角模型控制标记，并省略整个可见文本仅为精确静默标记 `NO_REPLY` / `no_reply` 的助手条目。
- 在一次活跃发送和最终历史刷新期间，如果 `chat.history` 短暂返回较旧的快照，聊天视图会继续显示本地乐观的用户/助手消息；一旦 Gateway 网关历史追上，规范转录会替换这些本地消息。
- `chat.inject` 会向会话转录追加一条助手注释，并广播一个 `chat` 事件，用于仅 UI 更新（无智能体运行，无渠道投递）。
- 聊天标题栏的模型和思考选择器会通过 `sessions.patch` 立即修补活跃会话；它们是持久的会话覆盖项，不是仅限单轮的发送选项。
- 在 Control UI 中输入 `/new` 会创建并切换到与 New Chat 相同的全新仪表盘会话。输入 `/reset` 会保留 Gateway 网关针对当前会话的显式原地重置。
- 聊天模型选择器会请求 Gateway 网关配置的模型视图。如果存在 `agents.defaults.models`，该允许列表会驱动选择器。否则，选择器会显示显式的 `models.providers.*.models` 条目以及具有可用身份验证的提供商。完整目录仍可通过调试用 `models.list` RPC 并使用 `view: "all"` 获取。
- 当新的 Gateway 网关会话使用情况报告显示上下文压力较高时，聊天撰写区域会显示一条上下文提示，并且在推荐的压缩级别下显示一个 compact 按钮，用于运行常规会话压缩路径。过期的 token 快照会被隐藏，直到 Gateway 网关再次报告新的使用情况。
- `chat.send` 是**非阻塞**的：它会立即确认并返回 `{ runId, status: "started" }`，响应通过 `chat` 事件流式传输。
- 聊天上传接受图片以及非视频文件。图片保留原生图片路径；其他文件会作为托管媒体存储，并在历史记录中显示为附件链接。
- 使用相同的 `idempotencyKey` 重新发送时，运行中会返回 `{ status: "in_flight" }`，完成后会返回 `{ status: "ok" }`。
- 为保证 UI 安全，`chat.history` 响应有大小限制。当转录条目过大时，Gateway 网关可能会截断长文本字段，省略较大的元数据块，并用占位符（`[chat.history omitted: message too large]`）替换超大消息。
- 助手/生成的图片会持久化为托管媒体引用，并通过已认证的 Gateway 网关媒体 URL 返回，因此重新加载不依赖原始 base64 图片载荷继续保留在聊天历史响应中。
- `chat.history` 还会从可见助手文本中移除仅用于显示的内联指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 载荷（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 以及被截断的工具调用块），以及泄漏的 ASCII/全角模型控制令牌，并省略整个可见文本仅为精确静默令牌 `NO_REPLY` / `no_reply` 的助手条目。
- 在活动发送期间以及最终历史刷新时，如果 `chat.history` 短暂返回较旧快照，聊天视图会继续显示本地乐观用户/助手消息；一旦 Gateway 网关历史追上，规范转录就会替换这些本地消息。
- 实时 `chat` 事件表示投递状态，而 `chat.history` 会从持久会话转录重建。工具最终事件之后，Control UI 会重新加载历史，并仅合并一小段乐观尾部；转录边界记录在 [WebChat](/zh-CN/web/webchat) 中。
- `chat.inject` 会向会话转录追加一条助手备注，并广播一个 `chat` 事件用于仅 UI 更新（无智能体运行，无渠道投递）。
- 聊天标题中的模型和思考选择器会通过 `sessions.patch` 立即修补活动会话；它们是持久会话覆盖项，不是仅用于单轮发送的选项。
- 在 Control UI 中输入 `/new` 会创建并切换到与 New Chat 相同的全新仪表板会话。输入 `/reset` 会保留 Gateway 网关针对当前会话的显式原地重置。
- 聊天模型选择器会请求 Gateway 网关配置的模型视图。如果存在 `agents.defaults.models`，该允许列表会驱动选择器。否则，选择器会显示显式的 `models.providers.*.models` 条目以及具备可用认证的提供商。完整目录仍可通过调试 `models.list` RPC 使用 `view: "all"` 访问。
- 当新的 Gateway 网关会话用量报告显示较高上下文压力时，聊天输入区域会显示上下文提示；在推荐压缩级别下，还会显示一个压缩按钮，用于运行正常的会话压缩路径。过期令牌快照会被隐藏，直到 Gateway 网关再次报告新的用量。
</Accordion>
<Accordion title="Talk 模式（浏览器实时）">
Talk 模式使用已注册的实时语音提供商。可使用 `talk.provider: "openai"` 加 `talk.providers.openai.apiKey` 配置 OpenAI，或使用 `talk.provider: "google"` 加 `talk.providers.google.apiKey` 配置 Google；Voice Call 实时提供商配置仍可作为回退复用。浏览器永远不会收到标准提供商 API key。OpenAI 会收到一个用于 WebRTC 的临时 Realtime 客户端密钥。Google Live 会收到一个一次性、受约束的 Live API 身份验证 token，用于浏览器 WebSocket 会话，指令和工具声明由 Gateway 网关锁定到该 token 中。仅公开后端实时桥接的提供商会通过 Gateway 网关中继传输运行，因此凭证和供应商 socket 会保留在服务器端，而浏览器音频通过经过身份验证的 Gateway 网关 RPC 传输。Realtime 会话提示由 Gateway 网关组装；`talk.realtime.session` 不接受调用方提供的指令覆盖。
<Accordion title="对话模式（浏览器实时）">
对话模式使用已注册的实时语音提供商。使用 `talk.provider: "openai"` 和 `talk.providers.openai.apiKey` 配置 OpenAI，或使用 `talk.provider: "google"` 和 `talk.providers.google.apiKey` 配置 Google；Voice Call 实时提供商配置仍可作为回退复用。浏览器绝不会收到标准提供商 API key。OpenAI 会收到用于 WebRTC 的临时 Realtime 客户端密钥。Google Live 会收到一次性、受约束的 Live API 认证令牌，用于浏览器 WebSocket 会话，其中指令和工具声明会由 Gateway 网关锁定到令牌中。仅公开后端实时桥接的提供商会通过 Gateway 网关中继传输运行，因此凭据和供应商套接字保持在服务器端，而浏览器音频通过已认证的 Gateway 网关 RPC 传输。Realtime 会话提示词由 Gateway 网关组装；`talk.realtime.session` 不接受调用方提供的指令覆盖。
在 Chat 撰写器中，Talk 控件是麦克风听写按钮旁边的波形按钮。Talk 启动时，撰写器状态行会显示 `Connecting Talk...`，音频连接后显示 `Talk live`，或当实时工具调用正在通过 `chat.send` 咨询已配置的较大模型时显示 `Asking OpenClaw...`。
在聊天输入框中，Talk 控件是麦克风听写按钮旁边的波形按钮。Talk 启动时，输入框状态行会显示 `Connecting Talk...`，随后在音频连接时显示 `Talk live`，或在实时工具调用通过 `chat.send` 咨询配置的更大模型时显示 `Asking OpenClaw...`。
维护者实时冒烟测试：`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 会验证 OpenAI 浏览器 WebRTC SDP 交换、Google Live 受约束 token 浏览器 WebSocket 设置，以及带有假麦克风媒体的 Gateway 网关中继浏览器适配器。该命令只打印提供商状态，不记录密钥。
维护者实时冒烟测试：`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 会验证 OpenAI 浏览器 WebRTC SDP 交换、Google Live 受约束令牌浏览器 WebSocket 设置，以及带伪造麦克风媒体的 Gateway 网关中继浏览器适配器。该命令只打印提供商状态，不记录密钥。
</Accordion>
<Accordion title="停止和中止">
- 点击 **Stop**（调用 `chat.abort`）。
- 当运行处于活跃状态时，普通后续消息会排队。点击排队消息上的 **Steer**，可将该后续消息注入正在运行的轮次。
- 输入 `/stop`（或独立的中止短语，如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）可带外中止。
- `chat.abort` 支持 `{ sessionKey }`（无 `runId`），用于中止该会话的所有活跃运行。
- 运行处于活动状态时，普通后续消息会进入队列。点击排队消息上的 **Steer** 可将该后续消息注入正在运行的轮次。
- 输入 `/stop`（或单独的中止短语，如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）可带外中止。
- `chat.abort` 支持 `{ sessionKey }`（无 `runId`）以中止该会话的所有活动运行。
</Accordion>
<Accordion title="中止部分内容保留">
- 当运行被中止时，部分助手文本仍可显示在 UI 中。
- 当存在已缓冲输出时，Gateway 网关会将已中止的部分助手文本持久化到转录历史中。
- 运行被中止时，部分助手文本仍可显示在 UI 中。
- 当存在已缓冲输出时，Gateway 网关会将被中止的部分助手文本持久化到转录历史中。
- 持久化条目包含中止元数据，因此转录消费者可以区分中止部分内容和正常完成输出。
</Accordion>
@ -194,12 +195,12 @@ Appearance 面板保留内置的 Claw、Knot 和 Dash 主题，以及一个浏
## PWA 安装和 Web 推送
Control UI 随附一个 `manifest.webmanifest` 和一个 service worker，因此现代浏览器可以将其安装为独立 PWA。Web Push 让 Gateway 网关即使在标签页或浏览器窗口未打开时，也能通过通知唤醒已安装的 PWA。
Control UI 随附一个 `manifest.webmanifest` 和一个服务工作线程，因此现代浏览器可以将其安装为独立 PWA。Web Push 允许 Gateway 网关通过通知唤醒已安装的 PWA，即使标签页或浏览器窗口未打开。
| 表面 | 作用 |
| ----------------------------------------------------- | ------------------------------------------------------------------ |
| `ui/public/manifest.webmanifest` | PWA 清单。浏览器在可访问后会提供 “Install app”。 |
| `ui/public/sw.js` | 处理 `push` 事件和通知点击的 service worker。 |
| `ui/public/manifest.webmanifest` | PWA 清单。可访问后，浏览器会提供 “Install app”。 |
| `ui/public/sw.js` | 处理 `push` 事件和通知点击的服务工作线程。 |
| `push/vapid-keys.json`（位于 OpenClaw 状态目录下） | 自动生成的 VAPID 密钥对，用于签名 Web Push 载荷。 |
| `push/web-push-subscriptions.json` | 持久化的浏览器订阅端点。 |
@ -211,28 +212,28 @@ Control UI 随附一个 `manifest.webmanifest` 和一个 service worker，因此
Control UI 使用这些受范围限制的 Gateway 网关方法来注册和测试浏览器订阅：
- `push.web.vapidPublicKey` — 获取活跃的 VAPID 公钥。
- `push.web.vapidPublicKey` — 获取活动 VAPID 公钥。
- `push.web.subscribe` — 注册一个 `endpoint` 以及 `keys.p256dh`/`keys.auth`。
- `push.web.unsubscribe` — 移除已注册的端点。
- `push.web.test` — 向调用方的订阅发送测试通知。
<Note>
Web Push 独立于 iOS APNS 中继路径（关于中继支持的推送，请参阅[配置](/zh-CN/gateway/configuration)）以及现有的 `push.test` 方法，后者面向原生移动端配对。
Web Push 独立于 iOS APNS 中继路径（参见 [配置](/zh-CN/gateway/configuration) 了解基于中继的推送）以及现有的 `push.test` 方法，后者面向原生移动端配对。
</Note>
## 托管嵌入
助手消息可以使用 `[embed ...]` 短代码内联渲染托管的 Web 内容。iframe 沙箱策略由 `gateway.controlUi.embedSandbox` 控制：
助手消息可以使用 `[embed ...]` 短代码内联渲染托管 Web 内容。iframe 沙箱策略由 `gateway.controlUi.embedSandbox` 控制：
<Tabs>
<Tab title="strict">
禁用托管嵌入中的脚本执行。
禁用托管嵌入内的脚本执行。
</Tab>
<Tab title="scripts（默认）">
允许交互式嵌入，同时保持源隔离；这是默认值，通常足以满足自包含的浏览器游戏/小组件。
允许交互式嵌入，同时保持源隔离；这是默认设置，通常足以满足自包含的浏览器游戏/小组件。
</Tab>
<Tab title="trusted">
在 `allow-scripts` 之上添加 `allow-same-origin`，用于有意需要更高权限的同站点文档。
在 `allow-scripts` 之上添加 `allow-same-origin`，用于有意需要更强权限的同站点文档。
</Tab>
</Tabs>
@ -249,14 +250,14 @@ Web Push 独立于 iOS APNS 中继路径（关于中继支持的推送，请参
```
<Warning>
仅在嵌入文档确实需要同源行为时才使用 `trusted`。对于大多数智能体生成的游戏和交互式画布，`scripts` 是更安全的选择。
仅当嵌入文档确实需要同源行为时，才使用 `trusted`。对于大多数智能体生成的游戏和交互式画布，`scripts` 是更安全的选择。
</Warning>
默认情况下，绝对外部 `http(s)` 嵌入 URL 仍会被阻止。如果你明确希望 `[embed url="https://..."]` 加载第三方页面，请设置 `gateway.controlUi.allowExternalEmbedUrls: true`。
默认情况下，绝对外部 `http(s)` 嵌入 URL 仍会被阻止。如果你有意希望 `[embed url="https://..."]` 加载第三方页面，请设置 `gateway.controlUi.allowExternalEmbedUrls: true`。
## 聊天消息宽度
分组聊天消息使用可读性较好的默认最大宽度。宽屏显示器部署可以通过设置 `gateway.controlUi.chatMessageMaxWidth` 覆盖该值，而无需修补内置 CSS：
分组聊天消息使用易读的默认最大宽度。宽屏部署可以通过设置 `gateway.controlUi.chatMessageMaxWidth` 覆盖它，而无需修补内置 CSS：
```json5
{
@ -268,13 +269,13 @@ Web Push 独立于 iOS APNS 中继路径（关于中继支持的推送，请参
}
```
该值会在到达浏览器前进行验证。支持的值包括普通长度和百分比，例如 `960px` 或 `82%`，以及受约束的 `min(...)`、`max(...)`、`clamp(...)`、`calc(...)` 和 `fit-content(...)` 宽度表达式。
该值在到达浏览器前会被验证。支持的值包括普通长度和百分比，例如 `960px` 或 `82%`，以及受约束的 `min(...)`、`max(...)`、`clamp(...)`、`calc(...)` 和 `fit-content(...)` 宽度表达式。
## Tailnet 访问（推荐）
<Tabs>
<Tab title="集成 Tailscale Serve（首选）">
将 Gateway 网关保留在 loopback 上，并让 Tailscale Serve 通过 HTTPS 代理它：
将 Gateway 网关保持在 loopback 上，并让 Tailscale Serve 使用 HTTPS 代理它：
```bash
openclaw gateway --tailscale serve
@ -284,16 +285,16 @@ Web Push 独立于 iOS APNS 中继路径（关于中继支持的推送，请参
- `https://<magicdns>/`（或你配置的 `gateway.controlUi.basePath`）
默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Control UI/WebSocket Serve 请求可以通过 Tailscale 身份标头（`tailscale-user-login`）进行身份验证。OpenClaw 会通过 `tailscale whois` 解析 `x-forwarded-for` 地址并将其与该标头匹配来验证身份，并且仅在请求命中 loopback 且带有 Tailscale 的 `x-forwarded-*` 标头时接受这些身份。对于带有浏览器设备身份的 Control UI 操作者会话，这个经过验证的 Serve 路径还会跳过设备配对往返；无设备浏览器和节点角色连接仍会遵循正常设备检查。如果你想即使对于 Serve 流量也要求显式共享密钥凭证，请设置 `gateway.auth.allowTailscale: false`。然后使用 `gateway.auth.mode: "token"` 或 `"password"`。
默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Control UI/WebSocket Serve 请求可以通过 Tailscale 身份标头（`tailscale-user-login`）认证。OpenClaw 会通过 `tailscale whois` 解析 `x-forwarded-for` 地址并将其与该标头匹配来验证身份，并且只在请求命中 loopback 且带有 Tailscale 的 `x-forwarded-*` 标头时接受这些标头。对于具有浏览器设备身份的 Control UI 操作员会话，这条已验证的 Serve 路径也会跳过设备配对往返；无设备浏览器和节点角色连接仍会遵循正常设备检查。如果你希望即使对 Serve 流量也要求显式共享密钥凭据，请设置 `gateway.auth.allowTailscale: false`。然后使用 `gateway.auth.mode: "token"` 或 `"password"`。
对于该异步 Serve 身份路径，同一客户端 IP 和身份验证范围的失败身份验证尝试会在写入速率限制之前串行化。因此，来自同一浏览器的并发错误重试可能会在第二个请求上显示 `retry later`，而不是两个普通不匹配并行竞争。
对于该异步 Serve 身份路径，来自相同客户端 IP 和认证范围的失败认证尝试会在写入速率限制前被串行化。因此，同一浏览器的并发错误重试可能会在第二个请求上显示 `retry later`，而不是两个普通不匹配并行竞争。
<Warning>
无 token 的 Serve 身份验证假设 gateway 主机可信。如果不受信任的本地代码可能在该主机上运行，请要求 token/password 身份验证。
无令牌 Serve 认证假定 Gateway 网关主机可信。如果不受信任的本地代码可能在该主机上运行，请要求使用令牌/密码认证。
</Warning>
</Tab>
<Tab title="绑定到 tailnet + token">
<Tab title="绑定到 tailnet + 令牌">
```bash
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
```
@ -309,21 +310,21 @@ Web Push 独立于 iOS APNS 中继路径（关于中继支持的推送，请参
## 不安全 HTTP
如果你通过普通 HTTP（`http://<lan-ip>` 或 `http://<tailscale-ip>`）打开仪表盘，浏览器会在**非安全上下文**中运行并阻止 WebCrypto。默认情况下，OpenClaw 会**阻止**没有设备身份的 Control UI 连接。
如果你通过明文 HTTP（`http://<lan-ip>` 或 `http://<tailscale-ip>`）打开仪表板，浏览器会在**非安全上下文**中运行并阻止 WebCrypto。默认情况下，OpenClaw 会**阻止**没有设备身份的 Control UI 连接。
已记录的例外：
- 使用 `gateway.controlUi.allowInsecureAuth=true` 的仅 localhost 不安全 HTTP 兼容性
- 通过 `gateway.auth.mode: "trusted-proxy"` 成功进行的操作者 Control UI 身份验证
- 应急用 `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
- 仅 localhost 的不安全 HTTP 兼容性，使用 `gateway.controlUi.allowInsecureAuth=true`
- 通过 `gateway.auth.mode: "trusted-proxy"` 成功完成操作员 Control UI 认证
- 破窗选项 `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
**推荐修复：**使用 HTTPS（Tailscale Serve）或在本地打开 UI：
- `https://<magicdns>/`（Serve）
- `http://127.0.0.1:18789/`（在 gateway 主机上）
- `http://127.0.0.1:18789/`（在 Gateway 网关主机上）
<AccordionGroup>
<Accordion title="不安全认证开关行为">
<Accordion title="Insecure-auth toggle behavior">
```json5
{
gateway: {
@ -336,12 +337,12 @@ Web Push 独立于 iOS APNS 中继路径（关于中继支持的推送，请参
`allowInsecureAuth` 只是一个本地兼容性开关：
- 它允许 localhost 控制界面会话在非安全 HTTP 上下文中无需设备身份即可继续。
- 它允许 localhost Control UI 会话在非安全 HTTP 上下文中不带设备身份继续运行。
- 它不会绕过配对检查。
- 它不会放宽远程（非 localhost）设备身份要求。
</Accordion>
<Accordion title="仅限紧急破例">
<Accordion title="Break-glass only">
```json5
{
gateway: {
@ -353,52 +354,52 @@ Web Push 独立于 iOS APNS 中继路径（关于中继支持的推送，请参
```
<Warning>
`dangerouslyDisableDeviceAuth` 会禁用控制界面的设备身份检查，这是严重的安全降级。紧急使用后请尽快恢复。
`dangerouslyDisableDeviceAuth` 会禁用 Control UI 设备身份检查，属于严重的安全降级。紧急使用后请尽快还原。
</Warning>
</Accordion>
<Accordion title="可信代理说明">
- 成功的可信代理认证可以允许**操作员**控制界面会话无需设备身份进入。
- 这**不**会扩展到节点角色的控制界面会话。
- 同主机 loopback 反向代理仍然无法满足可信代理认证；请参阅[可信代理认证](/zh-CN/gateway/trusted-proxy-auth)。
<Accordion title="Trusted-proxy note">
- 成功的可信代理认证可以允许没有设备身份的**操作员** Control UI 会话进入。
- 这**不**适用于节点角色的 Control UI 会话。
- 同主机 loopback 反向代理仍然不满足可信代理认证；请参阅[可信代理认证](/zh-CN/gateway/trusted-proxy-auth)。
</Accordion>
</AccordionGroup>
请参阅 [Tailscale](/zh-CN/gateway/tailscale) 获取 HTTPS 设置指南。
有关 HTTPS 设置指南，请参阅 [Tailscale](/zh-CN/gateway/tailscale)。
## 内容安全策略
控制界面附带严格的 `img-src` 策略：只允许**同源**资产、`data:` URL，以及本地生成的 `blob:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，并且不会发起网络获取。
Control UI 附带严格的 `img-src` 策略：只允许**同源**资源、`data:` URL 和本地生成的 `blob:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，并且不会发起网络获取。
实际含义如下：
这在实践中意味着：
- 通过相对路径提供的头像和图片（例如 `/avatars/<id>`）仍会渲染，包括界面获取并转换为本地 `blob:` URL 的已认证头像路由。
- 通过相对路径提供的头像和图片（例如 `/avatars/<id>`）仍会渲染，包括 UI 获取后转换为本地 `blob:` URL 的已认证头像路由。
- 内联 `data:image/...` URL 仍会渲染（对协议内载荷很有用）。
- 控制界面创建的本地 `blob:` URL 仍会渲染。
- 渠道元数据发出的远程头像 URL 会在控制界面的头像辅助逻辑中被剥离，并替换为内置徽标/徽章，因此被攻陷或恶意的渠道无法强制操作员浏览器获取任意远程图片。
- Control UI 创建的本地 `blob:` URL 仍会渲染。
- 渠道元数据发出的远程头像 URL 会在 Control UI 的头像辅助逻辑中被剥离，并替换为内置徽标/徽章，因此被攻陷或恶意的渠道无法强制操作员浏览器获取任意远程图片。
你无需更改任何内容即可获得此行为——它始终启用且不可配置。
你不需要更改任何内容即可获得此行为 —— 它始终启用且不可配置。
## 头像路由认证
配置 Gateway 网关认证后，控制界面头像端点需要与 API 其余部分相同的 Gateway 网关令牌：
配置 Gateway 网关认证后，Control UI 头像端点要求使用与 API 其余部分相同的 Gateway 网关令牌：
- `GET /avatar/<agentId>` 只向已认证调用方返回头像图片。`GET /avatar/<agentId>?meta=1` 按相同规则返回头像元数据。
- 对任一路由的未认证请求都会被拒绝（与同级 assistant-media 路由一致）。这可以防止头像路由在其他方面受保护的主机上泄露智能体身份。
- 控制界面本身在获取头像时会将 Gateway 网关令牌作为 bearer 头转发，并使用已认证的 blob URL，因此图片仍会在仪表板中渲染。
- `GET /avatar/<agentId>` 仅向已认证调用方返回头像图片。`GET /avatar/<agentId>?meta=1` 在相同规则下返回头像元数据。
- 对任一路由的未认证请求都会被拒绝（与同级 assistant-media 路由一致）。这可以防止头像路由在其他方面受保护的主机上泄露 agent 身份。
- Control UI 自身在获取头像时会将 Gateway 网关令牌作为 bearer 标头转发，并使用已认证的 blob URL，因此图片仍会在仪表盘中渲染。
如果你禁用 Gateway 网关认证（不建议在共享主机上这样做），头像路由也会与 Gateway 网关其余部分一样变为未认证。
如果你禁用 Gateway 网关认证（不建议在共享主机上这样做），头像路由也会变为无需认证，与 Gateway 网关的其余部分保持一致。
## 构建界面
## 构建 UI
Gateway 网关从 `dist/control-ui` 提供静态文件。使用以下命令构建：
Gateway 网关从 `dist/control-ui` 提供静态文件。使用以下命令构建它们：
```bash
pnpm ui:build
```
可选的绝对基路径（当你需要固定资产 URL 时）：
可选的绝对基路径（当你需要固定资源 URL 时）：
```bash
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
@ -410,24 +411,24 @@ OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
pnpm ui:dev
```
然后将界面指向你的 Gateway 网关 WS URL（例如 `ws://127.0.0.1:18789`）。
然后将 UI 指向你的 Gateway 网关 WS URL（例如 `ws://127.0.0.1:18789`）。
## 调试/测试：开发服务器 + 远程 Gateway 网关
控制界面是静态文件；WebSocket 目标可配置，并且可以不同于 HTTP 来源。当你想在本地使用 Vite 开发服务器，而 Gateway 网关在其他地方运行时，这很有用。
Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 HTTP 来源。当你希望 Vite 开发服务器在本地运行，而 Gateway 网关在其他位置运行时，这很方便。
<Steps>
<Step title="启动界面开发服务器">
<Step title="Start the UI dev server">
```bash
pnpm ui:dev
```
</Step>
<Step title="使用 gatewayUrl 打开">
<Step title="Open with gatewayUrl">
```text
http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
```
可选的一次性认证（如有需要）：
可选的一次性认证（如果需要）：
```text
http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
@ -437,18 +438,18 @@ pnpm ui:dev
</Steps>
<AccordionGroup>
<Accordion title="说明">
- `gatewayUrl` 会在加载后存储到 localStorage 中，并从 URL 中移除。
- 如果你通过 `gatewayUrl` 传递完整的 `ws://` 或 `wss://` 端点，请对 `gatewayUrl` 值进行 URL 编码，以便浏览器正确解析查询字符串。
- 应尽可能通过 URL 片段（`#token=...`）传递 `token`。片段不会发送到服务器，这可以避免请求日志和 Referer 泄露。旧版 `?token=` 查询参数仍会为兼容性导入一次，但仅作为回退，并会在启动引导后立即剥离。
- `password` 只保留在内存中。
- 设置 `gatewayUrl` 后，界面不会回退到配置或环境凭据。请显式提供 `token`（或 `password`）。缺少显式凭据会导致错误。
<Accordion title="Notes">
- `gatewayUrl` 会在加载后存储到 localStorage，并从 URL 中移除。
- 如果你通过 `gatewayUrl` 传入完整的 `ws://` 或 `wss://` 端点，请对 `gatewayUrl` 值进行 URL 编码，以便浏览器正确解析查询字符串。
- 只要可行，`token` 应通过 URL 片段（`#token=...`）传递。片段不会发送到服务器，这可以避免请求日志和 Referer 泄露。旧版 `?token=` 查询参数仍会为了兼容性导入一次，但仅作为回退，并会在启动后立即剥离。
- `password` 只保存在内存中。
- 设置 `gatewayUrl` 后，UI 不会回退到配置或环境凭证。请显式提供 `token`（或 `password`）。缺少显式凭证是错误。
- 当 Gateway 网关位于 TLS 后方时（Tailscale Serve、HTTPS 代理等），请使用 `wss://`。
- `gatewayUrl` 只在顶层窗口中被接受（不能嵌入），以防止点击劫持。
- 非 loopback 控制界面部署必须显式设置 `gateway.controlUi.allowedOrigins`（完整来源）。这包括远程开发设置。
- Gateway 网关启动可能会根据有效运行时绑定和端口注入本地来源，例如 `http://localhost:<port>` 和 `http://127.0.0.1:<port>`，但远程浏览器来源仍需要显式条目。
- 除非用于严格受控的本地测试，否则不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允许任何浏览器来源，而不是“匹配我正在使用的任意主机”。
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 头来源回退模式，但这是危险的安全模式。
- `gatewayUrl` 只会在顶层窗口中被接受（不能嵌入），以防止点击劫持。
- 非 loopback Control UI 部署必须显式设置 `gateway.controlUi.allowedOrigins`（完整来源）。这包括远程开发设置。
- Gateway 网关启动时可能会根据有效的运行时绑定和端口填充本地来源，例如 `http://localhost:<port>` 和 `http://127.0.0.1:<port>`，但远程浏览器来源仍需要显式条目。
- 除了严格受控的本地测试外，不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允许任意浏览器来源，而不是“匹配我正在使用的任何主机”。
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 标头来源回退模式，但这是危险的安全模式。
</Accordion>
</AccordionGroup>
@ -469,7 +470,7 @@ pnpm ui:dev
## 相关内容
- [仪表板](/zh-CN/web/dashboard) — Gateway 网关仪表板
- [健康检查](/zh-CN/gateway/health) — Gateway 网关健康监控
- [Dashboard](/zh-CN/web/dashboard) — Gateway 网关仪表盘
- [Health Checks](/zh-CN/gateway/health) — Gateway 网关健康监控
- [TUI](/zh-CN/web/tui) — 终端用户界面
- [WebChat](/zh-CN/web/webchat) — 基于浏览器的聊天界面

75
docs/zh-CN/web/webchat.md
View File

@ -1,13 +1,13 @@
---
read_when:
- 调试或配置 WebChat 访问
summary: 回环 WebChat 静态托管和用于聊天 UI 的 Gateway 网关 WS 用法
summary: 用于聊天 UI 的回环 WebChat 静态托管和 Gateway 网关 WS 用法
title: 网页聊天
x-i18n:
generated_at: "2026-05-04T00:38:11Z"
generated_at: "2026-05-04T00:47:51Z"
model: gpt-5.5
provider: openai
source_hash: 58f5a19344a366a02985ef697444fa0c3636fece06931c7fa6dbe288e6c398cd
source_hash: bf435585a13a1cde5885714837017109eeeb61ffa5e33a400017706f676f57ea
source_path: web/webchat.md
workflow: 16
---
@ -18,51 +18,62 @@ Status：macOS/iOS SwiftUI 聊天 UI 直接与 Gateway 网关 WebSocket 通信
- 面向 Gateway 网关的原生聊天 UI（没有嵌入式浏览器，也没有本地静态服务器）。
- 使用与其他渠道相同的会话和路由规则。
- 确定性路由：回复始终返回到 WebChat。
- 确定性路由：回复始终返回 WebChat。
## 快速开始
1. 启动 Gateway 网关。
2. 打开 WebChat UI（macOS/iOS 应用）或 Control UI 聊天标签页。
3. 确保已配置有效的 Gateway 网关认证路径（默认使用 shared-secret，
即使在 loopback 上也是如此）。
3. 确保配置了有效的 Gateway 网关认证路径（默认使用共享密钥，
即使在回环上也是如此）。
## 工作方式（行为）
- UI 连接到 Gateway 网关 WebSocket，并使用 `chat.history`、`chat.send` 和 `chat.inject`。
- 为了保持稳定性，`chat.history` 有边界限制：Gateway 网关可能会截断很长的文本字段，省略较大的元数据，并将过大的条目替换为 `[chat.history omitted: message too large]`。
- 对于现代追加式会话文件，`chat.history` 会跟随当前活跃的转录分支，因此废弃的重写分支和被取代的提示词副本不会在 WebChat 中渲染。
- 压缩条目会渲染为明确的已压缩历史分隔线。该分隔线说明更早的轮次已保存在检查点中，并链接到会话检查点控件；当操作员权限允许时，可在那里创建分支或恢复压缩前视图。
- Control UI 会记住 `chat.history` 返回的后端 Gateway 网关 `sessionId`，并在后续 `chat.send` 调用中包含它，因此重新连接和页面刷新会继续同一个已存储对话，除非用户开始或重置会话。
- Control UI 会在生成新的 `chat.send` 运行 id 之前，合并同一会话、消息和附件的重复进行中提交；Gateway 网关仍会对复用同一幂等键的重复请求进行去重。
- 工作区启动文件和待处理的 `BOOTSTRAP.md` 指令会通过智能体系统提示词的项目上下文提供，而不会复制到 WebChat 用户消息中。Bootstrap 截断只会添加简洁的系统提示词恢复通知；详细计数和配置旋钮保留在诊断界面上。
- `chat.history` 也会进行显示规范化：仅运行时使用的 OpenClaw 上下文、
入站信封包装、内联投递指令标签
- 为了稳定性，`chat.history` 是有边界的：Gateway 网关可能会截断较长的文本字段、省略较重的元数据，并将过大的条目替换为 `[chat.history omitted: message too large]`。
- 对于现代追加式会话文件，`chat.history` 会跟随活动转录分支，因此废弃的重写分支和被取代的提示词副本不会在 WebChat 中渲染。
- 压缩条目会渲染为显式的已压缩历史分隔线。分隔线会说明更早的轮次已保留在检查点中，并链接到会话检查点控件；在权限允许时，操作者可以在那里分支或恢复压缩前视图。
- Control UI 会记住 `chat.history` 返回的后端 Gateway 网关 `sessionId`，并在后续 `chat.send` 调用中包含它，因此重新连接和页面刷新会继续同一个已存储对话，除非用户启动或重置会话。
- Control UI 会在生成新的 `chat.send` 运行 ID 之前，合并同一会话、消息和附件的重复进行中提交；Gateway 网关仍会对复用相同幂等键的重复请求去重。
- 工作区启动文件和待处理的 `BOOTSTRAP.md` 指令会通过智能体系统提示词的项目上下文提供，而不是复制到 WebChat 用户消息中。Bootstrap 截断只会添加一条简洁的系统提示词恢复通知；详细计数和配置旋钮保留在诊断界面上。
- `chat.history` 还会进行显示规范化：仅运行时使用的 OpenClaw 上下文、
入站信封包装器、内联投递指令标签
如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`、纯文本工具调用 XML
载荷（包括 `<tool_call>...</tool_call>`、
`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、
`<function_calls>...</function_calls>` 以及被截断的工具调用块），以及
泄漏的 ASCII/全角模型控制令牌，都会从可见文本中移除，
并且当 assistant 条目的全部可见文本仅为精确静默
令牌 `NO_REPLY` / `no_reply` 时，该条目会被省略。
- 带推理标记的回复载荷（`isReasoning: true`）会从 WebChat assistant 内容、转录回放文本和音频内容块中排除，因此仅思考用载荷不会作为可见 assistant 消息或可播放音频出现。
- `chat.inject` 会直接向转录追加一条 assistant 注记，并广播给 UI（不会运行智能体）。
- 已中止的运行可以在 UI 中保留部分 assistant 输出可见。
- 当存在已缓冲输出时，Gateway 网关会将已中止的部分 assistant 文本持久化到转录历史中，并为这些条目标记中止元数据。
- 历史始终从 Gateway 网关获取（不监听本地文件）。
- 如果 Gateway 网关不可达，WebChat 为只读。
`<function_calls>...</function_calls>` 以及截断的工具调用块），以及
泄漏的 ASCII/全角模型控制标记都会从可见文本中剥离，
并且整段可见文本仅为精确静默
标记 `NO_REPLY` / `no_reply` 的助手条目会被省略。
- 带推理标记的回复载荷（`isReasoning: true`）会从 WebChat 助手内容、转录回放文本和音频内容块中排除，因此仅思考载荷不会显示为可见助手消息或可播放音频。
- `chat.inject` 会将一条助手备注直接追加到转录中，并广播给 UI（不会运行智能体）。
- 已中止的运行可以让部分助手输出继续显示在 UI 中。
- 当存在已缓冲输出时，Gateway 网关会将已中止的部分助手文本持久化到转录历史中，并用中止元数据标记这些条目。
- 历史始终从 Gateway 网关获取（没有本地文件监听）。
- 如果 Gateway 网关无法访问，WebChat 为只读。
### 转录和投递模型
WebChat 有两条独立的数据路径：
- 会话 JSONL 文件是持久的模型/运行时转录。对于正常的智能体运行，Pi 会通过其会话管理器持久化模型可见的 `user`、`assistant` 和 `toolResult` 消息。WebChat 不会将任意投递、状态或辅助文本写入该转录。
- Gateway 网关 `ReplyPayload` 事件是实时投递投影。它们可以针对 WebChat/渠道显示、分块流式传输、指令标签、媒体嵌入、TTS/音频标志和 UI 兜底行为进行规范化。它们本身不是规范会话日志。
- 只有当 Gateway 网关在正常 Pi 助手轮次之外拥有一条已显示消息时，WebChat 才会注入助手转录条目：`chat.inject`、非智能体命令回复、已中止的部分输出，以及 WebChat 管理的媒体转录补充。
- `chat.history` 会读取已存储的会话转录并应用 WebChat 显示投影。如果运行期间出现实时助手文本，但在历史重新加载后消失，先检查原始 JSONL 是否包含助手文本，再检查 `chat.history` 投影是否将其剥离，然后检查 Control UI 乐观尾部合并是否用持久化快照替换了本地投递状态。
正常智能体运行的最终答案应该是持久的，因为 Pi 会写入助手 `message_end`。任何将已投递最终载荷镜像到转录中的兜底，都必须先避免重复写入 Pi 已经写入的助手轮次。
## Control UI 智能体工具面板
- Control UI `/agents` 工具面板有两个独立视图：
- **当前可用**使用 `tools.effective(sessionKey=...)`，并显示当前
会话在运行时实际可以使用的内容，包括核心、插件和渠道拥有的工具。
- **工具配置**使用 `tools.catalog`，并聚焦于配置档、覆盖项和
- **工具配置**使用 `tools.catalog`，并专注于配置文件、覆盖项和
目录语义。
- 运行时可用性按会话限定。在同一个智能体上切换会话可能会改变
- 运行时可用性以会话为作用域。在同一个智能体上切换会话可能会改变
**当前可用**列表。
- 配置编辑器并不表示运行时可用；有效访问仍遵循策略
优先级（`allow`/`deny`、按智能体以及提供商/渠道覆盖项）。
- 配置编辑器并不表示运行时可用；有效访问仍然遵循策略
优先级（`allow`/`deny`、按智能体以及提供商/渠道的覆盖项）。
## 远程使用
@ -75,20 +86,20 @@ Status：macOS/iOS SwiftUI 聊天 UI 直接与 Gateway 网关 WebSocket 通信
WebChat 选项：
- `gateway.webchat.chatHistoryMaxChars`：`chat.history` 响应中文本字段的最大字符数。当转录条目超过此限制时，Gateway 网关会截断较长的文本字段，并可能用占位符替换过大的消息。客户端也可以发送按请求设置的 `maxChars`，以覆盖单次 `chat.history` 调用的默认值。
- `gateway.webchat.chatHistoryMaxChars`：`chat.history` 响应中文本字段的最大字符数。当转录条目超过此限制时，Gateway 网关会截断较长的文本字段，并且可能用占位符替换过大的消息。客户端还可以发送按请求设置的 `maxChars`，以覆盖单次 `chat.history` 调用的默认值。
相关全局选项：
- `gateway.port`、`gateway.bind`：WebSocket 主机/端口。
- `gateway.auth.mode`、`gateway.auth.token`、`gateway.auth.password`：
shared-secret WebSocket 认证。
共享密钥 WebSocket 认证。
- `gateway.auth.allowTailscale`：启用后，浏览器 Control UI 聊天标签页可以使用 Tailscale
Serve 身份标头。
- `gateway.auth.mode: "trusted-proxy"`：用于位于身份感知型 **non-loopback** 代理源后方的浏览器客户端的反向代理认证（请参阅 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。
- `gateway.auth.mode: "trusted-proxy"`：面向位于支持身份感知的**非回环**代理来源之后的浏览器客户端的反向代理认证（请参阅[受信任代理认证](/zh-CN/gateway/trusted-proxy-auth)）。
- `gateway.remote.url`、`gateway.remote.token`、`gateway.remote.password`：远程 Gateway 网关目标。
- `session.*`：会话存储和主键默认值。
## 相关
## 相关内容
- [Control UI](/zh-CN/web/control-ui)
- [Dashboard](/zh-CN/web/dashboard)