diff --git a/docs/zh-CN/channels/groups.md b/docs/zh-CN/channels/groups.md index b0b4b697d..e426b2943 100644 --- a/docs/zh-CN/channels/groups.md +++ b/docs/zh-CN/channels/groups.md @@ -2,36 +2,36 @@ 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-04-28T17:28:16Z" + generated_at: "2026-04-29T10:10:39Z" model: gpt-5.5 provider: openai - source_hash: edda98307223651fe3e6eb545839eb4e9d98d416c7a7c505a2610aa1f9162ee1 + source_hash: 1f0766149bc208a934c6a07ea409d7ceadc6c5f52f7dab7d3f50d6fc9c383f13 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 bot 用户。如果**你**在某个群组中，OpenClaw 就能看到该群组并在那里响应。 +OpenClaw “存在于”你自己的消息账号中。没有单独的 WhatsApp 机器人用户。如果**你**在某个群组中，OpenClaw 就能看到该群组并在那里响应。 默认行为： -- 群组受限制（`groupPolicy: "allowlist"`）。 -- 回复需要被提及，除非你明确禁用提及门控。 +- 群组受限（`groupPolicy: "allowlist"`）。 +- 回复需要提及，除非你明确禁用提及门控。 - 群组/渠道中的普通最终回复默认是私密的。可见的房间输出使用 `message` 工具。 -换句话说：允许名单中的发送者可以通过提及 OpenClaw 来触发它。 +换句话说：允许列表中的发送者可以通过提及 OpenClaw 来触发它。 -**太长不读** +**太长不看** - **私信访问**由 `*.allowFrom` 控制。 -- **群组访问**由 `*.groupPolicy` + 允许名单（`*.groups`、`*.groupAllowFrom`）控制。 +- **群组访问**由 `*.groupPolicy` + 允许列表（`*.groups`、`*.groupAllowFrom`）控制。 - **回复触发**由提及门控（`requireMention`、`/activation`）控制。 @@ -48,11 +48,13 @@ otherwise -> reply ## 可见回复 对于群组/渠道房间，OpenClaw 默认使用 `messages.groupChat.visibleReplies: "message_tool"`。 -这意味着智能体仍会处理这一轮，并可以更新 memory/会话状态，但它的普通最终答案不会自动发回房间。要可见地发言，智能体会使用 `message(action=send)`。 +这意味着智能体仍会处理这一轮，并且可以更新记忆/会话状态，但它的普通最终答案不会自动发回房间。要公开发言，智能体会使用 `message(action=send)`。 -这取代了旧模式：在大多数潜伏模式轮次中强制模型回答 `NO_REPLY`。在仅工具模式下，什么可见内容都不做，就只是意味着不调用 message 工具。 +对于直接聊天和任何其他来源轮次，使用 `messages.visibleReplies: "message_tool"` 可以在全局应用同样的仅工具可见回复行为。`messages.groupChat.visibleReplies` 仍然是针对群组/渠道房间的更具体覆盖项。 -在智能体以仅工具模式工作时，仍会发送输入状态指示。对于这些轮次，默认群组输入状态模式会从 “message” 升级为 “instant”，因为在智能体决定是否调用 message 工具之前，可能永远不会有普通 assistant 消息文本。显式的输入状态模式配置仍然优先。 +这取代了旧模式中强制模型在大多数旁观模式轮次回答 `NO_REPLY` 的做法。在仅工具模式中，不产生可见输出只是意味着不调用消息工具。 + +智能体在仅工具模式中工作时，仍会发送正在输入指示。对于这些轮次，默认群组输入模式会从 “message” 升级为 “instant”，因为在智能体决定是否调用消息工具之前，可能永远不会有普通助手消息文本。显式输入模式配置仍然优先。 要为群组/渠道房间恢复旧版自动最终回复： @@ -66,70 +68,80 @@ otherwise -> reply } ``` -原生斜杠命令（Discord、Telegram，以及其他支持原生命令的表面）会绕过 `visibleReplies: "message_tool"`，并始终可见地回复，使渠道原生命令 UI 获得它预期的响应。这仅适用于已验证的原生命令轮次；以文本键入的 `/...` 命令和普通聊天轮次仍遵循配置的群组默认值。 +要要求每个来源聊天的可见输出都通过消息工具： -## 上下文可见性和允许名单 +```json5 +{ + messages: { + visibleReplies: "message_tool", + }, +} +``` -群组安全涉及两种不同的控制： +原生命令（Discord、Telegram 以及其他支持原生命令的界面）会绕过 `visibleReplies: "message_tool"`，并始终可见回复，以便渠道原生命令 UI 获得预期响应。这只适用于已验证的原生命令轮次；文本输入的 `/...` 命令和普通聊天轮次仍遵循已配置的群组默认值。 -- **触发授权**：谁可以触发智能体（`groupPolicy`、`groups`、`groupAllowFrom`、渠道特定的允许名单）。 +## 上下文可见性和允许列表 + +群组安全涉及两个不同控制项： + +- **触发授权**：谁可以触发智能体（`groupPolicy`、`groups`、`groupAllowFrom`、渠道专用允许列表）。 - **上下文可见性**：哪些补充上下文会注入模型（回复文本、引用、线程历史、转发元数据）。 -默认情况下，OpenClaw 优先保证正常聊天行为，并大体按收到的内容保留上下文。这意味着允许名单主要决定谁可以触发操作，而不是每段引用或历史片段的通用脱敏边界。 +默认情况下，OpenClaw 优先保证正常聊天行为，并尽量按接收时保留上下文。这意味着允许列表主要决定谁可以触发操作，而不是作为每个引用或历史片段的通用脱敏边界。 - - 一些渠道已经在特定路径中对补充上下文应用基于发送者的过滤（例如 Slack 线程种子数据、Matrix 回复/线程查找）。 - - 其他渠道仍会按收到的内容传递引用/回复/转发上下文。 + - 一些渠道已经在特定路径中对补充上下文应用基于发送者的过滤（例如 Slack 线程播种、Matrix 回复/线程查找）。 + - 其他渠道仍会按接收时传递引用/回复/转发上下文。 - - `contextVisibility: "all"`（默认）保留当前按收到内容处理的行为。 - - `contextVisibility: "allowlist"` 将补充上下文过滤为允许名单中的发送者。 + - `contextVisibility: "all"`（默认）保留当前按接收时处理的行为。 + - `contextVisibility: "allowlist"` 将补充上下文过滤为只包含允许列表中的发送者。 - `contextVisibility: "allowlist_quote"` 是 `allowlist` 加上一个显式引用/回复例外。 - 在这个加固模型跨渠道一致实现之前，预计不同表面之间会存在差异。 + 在这一加固模型在各渠道中一致实现之前，预期不同界面会有差异。 ![群组消息流程](/images/groups-flow.svg) -如果你想要…… +如果你想…… -| 目标 | 要设置的内容 | +| 目标 | 要设置的内容 | | -------------------------------------------- | ---------------------------------------------------------- | | 允许所有群组，但只在 @提及时回复 | `groups: { "*": { requireMention: true } }` | | 禁用所有群组回复 | `groupPolicy: "disabled"` | -| 仅特定群组 | `groups: { "": { ... } }`（没有 `"*"` 键） | +| 只允许特定群组 | `groups: { "": { ... } }`（没有 `"*"` 键） | | 只有你可以在群组中触发 | `groupPolicy: "allowlist"`、`groupAllowFrom: ["+1555..."]` | ## 会话键 - 群组会话使用 `agent:::group:` 会话键（房间/渠道使用 `agent:::channel:`）。 -- Telegram 论坛话题会向群组 ID 添加 `:topic:`，因此每个话题都有自己的会话。 -- 直接聊天使用主会话（如果已配置，也可以按发送者区分）。 +- Telegram 论坛主题会向群组 ID 添加 `:topic:`，因此每个主题都有自己的会话。 +- 直接聊天使用主会话（如果已配置，则使用每发送者会话）。 - 群组会话会跳过心跳。 -## 模式：个人私信 + 公开群组（单智能体） +## 模式：个人私信 + 公共群组（单智能体） -可以，这在你的“个人”流量是**私信**、你的“公开”流量是**群组**时效果很好。 +可以，这在你的“个人”流量是**私信**、你的“公共”流量是**群组**时效果很好。 -原因：在单智能体模式下，私信通常落在**主**会话键（`agent:main:main`）中，而群组始终使用**非主**会话键（`agent:main::group:`）。如果你启用 `mode: "non-main"` 的沙箱隔离，这些群组会话会在配置的沙箱后端中运行，而你的主私信会话仍留在宿主机上。如果你没有选择后端，Docker 是默认后端。 +原因：在单智能体模式中，私信通常落在**主**会话键（`agent:main:main`）中，而群组始终使用**非主**会话键（`agent:main::group:`）。如果你使用 `mode: "non-main"` 启用沙箱隔离，这些群组会话会在已配置的沙箱后端中运行，而你的主私信会话仍保留在主机上。如果你没有选择后端，Docker 是默认后端。 -这会给你一个智能体“大脑”（共享工作区 + memory），但有两种执行姿态： +这会给你一个智能体“大脑”（共享工作区 + 记忆），但有两种执行姿态： -- **私信**：完整工具（宿主机） +- **私信**：完整工具（主机） - **群组**：沙箱 + 受限工具 -如果你需要真正独立的工作区/人格（“个人”和“公开”绝不能混用），请使用第二个智能体 + 绑定。请参阅 [Multi-Agent Routing](/zh-CN/concepts/multi-agent)。 +如果你需要真正分离的工作区/角色（“个人”和“公共”绝不能混合），请使用第二个智能体 + 绑定。参见[多智能体路由](/zh-CN/concepts/multi-agent)。 - + ```json5 { agents: { @@ -153,8 +165,8 @@ otherwise -> reply } ``` - - 想要“群组只能看到文件夹 X”，而不是“没有宿主机访问权限”？保留 `workspaceAccess: "none"`，并只把允许名单中的路径挂载到沙箱中： + + 想要“群组只能看到文件夹 X”，而不是“没有主机访问权限”？保持 `workspaceAccess: "none"`，并只将允许列表中的路径挂载到沙箱中： ```json5 { @@ -182,7 +194,7 @@ otherwise -> reply 相关内容： - 配置键和默认值：[Gateway 网关配置](/zh-CN/gateway/config-agents#agentsdefaultssandbox) -- 调试工具被阻止的原因：[沙箱 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated) +- 调试为什么工具被阻止：[沙箱与工具策略与提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated) - 绑定挂载详情：[沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts) ## 显示标签 @@ -239,36 +251,36 @@ otherwise -> reply } ``` -| 策略 | 行为 | +| 策略 | 行为 | | ------------- | ------------------------------------------------------------ | -| `"open"` | 群组绕过允许名单；提及门控仍然适用。 | -| `"disabled"` | 完全阻止所有群组消息。 | -| `"allowlist"` | 仅允许匹配已配置允许名单的群组/房间。 | +| `"open"` | 群组绕过允许列表；提及门控仍然适用。 | +| `"disabled"` | 完全阻止所有群组消息。 | +| `"allowlist"` | 仅允许匹配已配置允许列表的群组/房间。 | - - - `groupPolicy` 独立于提及门控（后者要求 @提及）。 - - WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：使用 `groupAllowFrom`（后备：显式 `allowFrom`）。 - - 私信配对审批（`*-allowFrom` 存储条目）仅适用于私信访问；群组发送者授权仍然显式归属于群组允许名单。 - - Discord：允许名单使用 `channels.discord.guilds..channels`。 - - Slack：允许名单使用 `channels.slack.channels`。 - - Matrix：允许名单使用 `channels.matrix.groups`。优先使用房间 ID 或别名；已加入房间的名称查找是尽力而为的，未解析的名称会在运行时被忽略。使用 `channels.matrix.groupAllowFrom` 限制发送者；也支持按房间的 `users` 允许名单。 + + - `groupPolicy` 与提及门控分开（后者要求 @提及）。 + - WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：使用 `groupAllowFrom`（回退：显式 `allowFrom`）。 + - 私信配对批准（`*-allowFrom` 存储条目）仅适用于私信访问；群组发送者授权仍显式归属于群组允许列表。 + - Discord：允许列表使用 `channels.discord.guilds..channels`。 + - Slack：允许列表使用 `channels.slack.channels`。 + - Matrix：允许列表使用 `channels.matrix.groups`。优先使用房间 ID 或别名；已加入房间的名称查找是尽力而为，未解析的名称会在运行时被忽略。使用 `channels.matrix.groupAllowFrom` 限制发送者；也支持按房间的 `users` 允许列表。 - 群组私信单独控制（`channels.discord.dm.*`、`channels.slack.dm.*`）。 - - Telegram 允许名单可以匹配用户 ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）或用户名（`"@alice"` 或 `"alice"`）；前缀不区分大小写。 - - 默认是 `groupPolicy: "allowlist"`；如果你的群组允许名单为空，群组消息会被阻止。 - - 运行时安全性：当某个提供商块完全缺失（不存在 `channels.`）时，群组策略会回退到故障关闭模式（通常是 `allowlist`），而不是继承 `channels.defaults.groupPolicy`。 + - Telegram 允许列表可以匹配用户 ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）或用户名（`"@alice"` 或 `"alice"`）；前缀不区分大小写。 + - 默认值是 `groupPolicy: "allowlist"`；如果你的群组允许列表为空，群组消息会被阻止。 + - 运行时安全：当提供商块完全缺失（不存在 `channels.`）时，群组策略会回退到故障关闭模式（通常为 `allowlist`），而不是继承 `channels.defaults.groupPolicy`。 -快速心智模型（群组消息的求值顺序）： +快速心智模型（群组消息的评估顺序）： `groupPolicy`（open/disabled/allowlist）。 - - 群组允许名单（`*.groups`、`*.groupAllowFrom`、渠道特定允许名单）。 + + 群组允许列表（`*.groups`、`*.groupAllowFrom`、渠道专用允许列表）。 提及门控（`requireMention`、`/activation`）。 @@ -277,9 +289,9 @@ otherwise -> reply ## 提及门控（默认） -群组消息需要提及，除非按群组覆盖。默认值按子系统位于 `*.groups."*"` 下。 +群组消息需要提及，除非按群组覆盖。默认值位于每个子系统的 `*.groups."*"` 下。 -当渠道支持回复元数据时，回复 bot 消息会算作隐式提及。在暴露引用元数据的渠道上，引用 bot 消息也可能算作隐式提及。当前内置情况包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。 +回复机器人消息时，如果渠道支持回复元数据，则会算作隐式提及。引用机器人消息时，在暴露引用元数据的渠道上也可以算作隐式提及。当前内置案例包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。 ```json5 { @@ -319,26 +331,26 @@ otherwise -> reply - - `mentionPatterns` 是不区分大小写的安全正则表达式模式；无效模式和不安全的嵌套重复形式会被忽略。 - - 提供显式提及的界面仍会通过；模式是一种回退方式。 - - 单智能体覆盖：`agents.list[].groupChat.mentionPatterns`（当多个智能体共享一个群组时很有用）。 - - 只有在可以检测提及时（已配置原生提及或 `mentionPatterns`），才会强制执行提及门控。 + - `mentionPatterns` 是大小写不敏感的安全正则表达式模式；无效模式和不安全的嵌套重复形式会被忽略。 + - 提供显式提及的表面仍会通过；模式是兜底方案。 + - 按智能体覆盖：`agents.list[].groupChat.mentionPatterns`（当多个智能体共享一个群组时很有用）。 + - 仅当可以进行提及检测时，才会强制执行提及门控（原生提及或已配置 `mentionPatterns`）。 - 群聊提示上下文会在每一轮携带解析后的静默回复指令；工作区文件不应重复 `NO_REPLY` 机制。 - - 允许静默回复的群组会将干净的空模型轮次或仅推理轮次视为静默，等同于 `NO_REPLY`。直接聊天仍会将空回复视为一次失败的智能体轮次。 - - Discord 默认值位于 `channels.discord.guilds."*"`（可按 guild/channel 覆盖）。 - - 群组历史上下文在各渠道中统一包装，并且是**仅待处理**的（因提及门控而跳过的消息）；使用 `messages.groupChat.historyLimit` 设置全局默认值，并使用 `channels..historyLimit`（或 `channels..accounts.*.historyLimit`）进行覆盖。设为 `0` 可禁用。 + - 允许静默回复的群组会将干净的空模型轮次或仅推理的模型轮次视为静默，等同于 `NO_REPLY`。直接聊天仍会将空回复视为一次失败的智能体轮次。 + - Discord 默认值位于 `channels.discord.guilds."*"`（可按 guild/渠道覆盖）。 + - 群组历史上下文在各渠道中会统一包装，并且是**仅待处理**的（因提及门控而跳过的消息）；使用 `messages.groupChat.historyLimit` 设置全局默认值，并使用 `channels..historyLimit`（或 `channels..accounts.*.historyLimit`）进行覆盖。设置为 `0` 可禁用。 ## 群组/渠道工具限制（可选） -某些渠道配置支持限制**特定群组/房间/渠道内**可用的工具。 +一些渠道配置支持限制**特定群组/房间/渠道内**可用的工具。 - `tools`：允许/拒绝整个群组的工具。 -- `toolsBySender`：群组内的按发送者覆盖。使用显式键前缀：`id:`、`e164:`、`username:`、`name:` 和 `"*"` 通配符。旧版无前缀键仍被接受，并且只按 `id:` 匹配。 +- `toolsBySender`：群组内按发送者覆盖。使用显式键前缀：`id:`、`e164:`、`username:`、`name:` 和 `"*"` 通配符。旧版无前缀键仍会被接受，并且仅按 `id:` 匹配。 -解析顺序（最具体者优先）： +解析顺序（最具体的优先）： @@ -350,7 +362,7 @@ otherwise -> reply 默认（`"*"`）`toolsBySender` 匹配。 - + 默认（`"*"`）`tools`。 @@ -376,15 +388,15 @@ otherwise -> reply ``` -群组/渠道工具限制会在全局/智能体工具策略之外额外应用（拒绝仍然优先）。某些渠道对房间/渠道使用不同的嵌套方式（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。 +群组/渠道工具限制会在全局/智能体工具策略之外额外应用（拒绝仍然优先）。一些渠道对房间/渠道使用不同的嵌套方式（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。 ## 群组允许列表 -配置 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，这些键会充当群组允许列表。使用 `"*"` 可允许所有群组，同时仍设置默认提及行为。 +配置 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，这些键会作为群组允许列表。使用 `"*"` 可允许所有群组，同时仍设置默认提及行为。 -常见混淆：私信配对批准不同于群组授权。对于支持私信配对的渠道，配对存储只解锁私信。群组命令仍需要来自配置允许列表的显式群组发送者授权，例如 `groupAllowFrom` 或该渠道记录的配置回退。 +常见混淆：私信配对批准不等同于群组授权。对于支持私信配对的渠道，配对存储只解锁私信。群组命令仍需要来自配置允许列表的显式群组发送者授权，例如 `groupAllowFrom` 或该渠道文档化的配置兜底项。 常见意图（复制/粘贴）： @@ -439,42 +451,42 @@ otherwise -> reply ## 激活（仅所有者） -群组所有者可以切换每个群组的激活方式： +群组所有者可以切换按群组激活： - `/activation mention` - `/activation always` -所有者由 `channels.whatsapp.allowFrom` 决定（未设置时使用机器人的自有 E.164）。将命令作为独立消息发送。其他界面目前会忽略 `/activation`。 +所有者由 `channels.whatsapp.allowFrom` 决定（未设置时为机器人的自身 E.164）。请将该命令作为独立消息发送。其他表面当前会忽略 `/activation`。 ## 上下文字段 -群组入站 payload 会设置： +群组入站载荷会设置： - `ChatType=group` - `GroupSubject`（如果已知） - `GroupMembers`（如果已知） - `WasMentioned`（提及门控结果） -- Telegram 论坛话题还包含 `MessageThreadId` 和 `IsForum`。 +- Telegram 论坛主题还包括 `MessageThreadId` 和 `IsForum`。 渠道特定说明： -- BlueBubbles 可以在填充 `GroupMembers` 之前，从本地“通讯录”数据库中选择性地补充未命名的 macOS 群组参与者信息。此功能默认关闭，并且只会在正常群组门控通过后运行。 +- BlueBubbles 可以选择在填充 `GroupMembers` 前，从本地通讯录数据库补充未命名的 macOS 群组参与者。此功能默认关闭，并且仅在正常群组门控通过后运行。 -智能体系统提示会在新群组会话的第一轮包含群组介绍。它会提醒模型像人一样回复，避免 Markdown 表格，尽量减少空行并遵循正常聊天间距，以及避免输入字面量 `\n` 序列。来自渠道的群组名称和参与者标签会渲染为 fenced 的不受信任元数据，而不是内联系统指令。 +智能体系统提示会在新群组会话的第一轮包含群组介绍。它会提醒模型像真人一样回复，避免 Markdown 表格，尽量减少空行并遵循正常聊天间距，同时避免输入字面量 `\n` 序列。来自渠道的群组名称和参与者标签会呈现为围栏内的不受信任元数据，而不是内联系统指令。 -## iMessage 特定说明 +## iMessage 细节 -- 路由或加入允许列表时优先使用 `chat_id:`。 +- 路由或加入允许列表时，优先使用 `chat_id:`。 - 列出聊天：`imsg chats --limit 20`。 -- 群组回复始终返回同一个 `chat_id`。 +- 群组回复始终回到同一个 `chat_id`。 ## WhatsApp 系统提示 -有关规范的 WhatsApp 系统提示规则，请参阅 [WhatsApp](/zh-CN/channels/whatsapp#system-prompts)，其中包括群组和直接提示解析、通配符行为以及账号覆盖语义。 +请参阅 [WhatsApp](/zh-CN/channels/whatsapp#system-prompts)，了解权威的 WhatsApp 系统提示规则，包括群组和直接提示解析、通配符行为以及账号覆盖语义。 -## WhatsApp 特定说明 +## WhatsApp 细节 -有关仅 WhatsApp 的行为（历史注入、提及处理细节），请参阅[群组消息](/zh-CN/channels/group-messages)。 +请参阅[群组消息](/zh-CN/channels/group-messages)，了解 WhatsApp 专属行为（历史注入、提及处理细节）。 ## 相关 diff --git a/docs/zh-CN/gateway/config-channels.md b/docs/zh-CN/gateway/config-channels.md index ecc407c0a..84b5e12a0 100644 --- a/docs/zh-CN/gateway/config-channels.md +++ b/docs/zh-CN/gateway/config-channels.md @@ -1,26 +1,27 @@ --- read_when: - - 配置渠道插件（认证、访问控制、多账户） + - 配置渠道插件（凭证、访问控制、多账户） - 按渠道配置键名的故障排除 - 审计私信策略、群组策略或提及门控 -summary: 渠道配置：Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等渠道中的访问控制、配对和各渠道密钥 +summary: 渠道配置：跨 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等的访问控制、配对和各渠道密钥 title: 配置 — 渠道 x-i18n: - generated_at: "2026-04-29T05:40:14Z" + generated_at: "2026-04-29T10:10:46Z" model: gpt-5.5 provider: openai - source_hash: 27393684cef61ab3599f9793cc9e691239a5bb5852ad638b3c2dd20de76ee9fa + source_hash: e16ab50020711aac8e06cd234739ac7b566420cf7ce8621c0aca12c22484f07f source_path: gateway/config-channels.md workflow: 16 --- -每个渠道的配置键位于 `channels.*` 下。涵盖私信和群组访问、多账号设置、提及门控，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他内置渠道插件的每渠道键。 +每个渠道在 `channels.*` 下的配置键。涵盖私信和群组访问、多账号设置、提及门控，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他内置渠道插件的每渠道键。 -对于智能体、工具、Gateway 网关运行时和其他顶级键，请参阅[配置参考](/zh-CN/gateway/configuration-reference)。 +如需了解智能体、工具、Gateway 网关运行时和其他顶层键，请参阅 +[配置参考](/zh-CN/gateway/configuration-reference)。 ## 渠道 -每个渠道在其配置段存在时会自动启动（除非 `enabled: false`）。 +每个渠道会在其配置部分存在时自动启动（除非设置了 `enabled: false`）。 ### 私信和群组访问 @@ -28,21 +29,21 @@ x-i18n: | 私信策略 | 行为 | | ------------------- | --------------------------------------------------------------- | -| `pairing`（默认） | 未知发送者会获得一次性配对码；所有者必须批准 | -| `allowlist` | 仅允许 `allowFrom` 中的发送者（或配对允许存储中的发送者） | -| `open` | 允许所有入站私信（需要 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有入站私信 | +| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | +| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对的允许存储） | +| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有传入私信 | -| 群组策略 | 行为 | -| --------------------- | ------------------------------------------------ | -| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 | -| `open` | 绕过群组允许列表（提及门控仍然适用） | -| `disabled` | 阻止所有群组/房间消息 | +| 群组策略 | 行为 | +| --------------------- | ------------------------------------------------------ | +| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 | +| `open` | 绕过群组允许列表（提及门控仍然适用） | +| `disabled` | 阻止所有群组/房间消息 | `channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时设置默认值。 -配对码在 1 小时后过期。待处理的私信配对请求限制为**每个渠道 3 个**。 -如果提供商块完全缺失（不存在 `channels.`），运行时群组策略会回退到 `allowlist`（失败关闭），并在启动时发出警告。 +配对码会在 1 小时后过期。待处理的私信配对请求上限为**每个渠道 3 个**。 +如果完全缺少提供商块（不存在 `channels.`），运行时群组策略会回退到 `allowlist`（故障关闭），并显示启动警告。 ### 渠道模型覆盖 @@ -70,7 +71,7 @@ x-i18n: ### 渠道默认值和心跳 -使用 `channels.defaults` 为各提供商配置共享的群组策略和心跳行为： +使用 `channels.defaults` 配置跨提供商共享的群组策略和心跳行为： ```json5 { @@ -88,15 +89,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：提供商级别的 `groupPolicy` 未设置时的备用群组策略。 -- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与允许列表相同，但保留显式引用/回复上下文）。每渠道覆盖：`channels..contextVisibility`。 +- `channels.defaults.groupPolicy`：提供商级 `groupPolicy` 未设置时的回退群组策略。 +- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。值：`all`（默认，包含所有引用/话题串/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与允许列表相同，但保留显式引用/回复上下文）。每渠道覆盖：`channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康的渠道状态。 - `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 - `channels.defaults.heartbeat.useIndicator`：渲染紧凑的指示器样式心跳输出。 ### WhatsApp -WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在已链接会话时，它会自动启动。 +WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。存在已关联会话时，它会自动启动。 ```json5 { @@ -154,9 +155,9 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 } ``` -- 出站命令默认使用账号 `default`（如果存在）；否则使用第一个已配置的账号 ID（排序后）。 -- 可选的 `channels.whatsapp.defaultAccount` 会在匹配已配置账号 ID 时覆盖该备用默认账号选择。 -- 旧版单账号 Baileys 凭证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 +- 出站命令默认使用账号 `default`（如果存在）；否则使用第一个已配置账号 ID（排序后）。 +- 可选的 `channels.whatsapp.defaultAccount` 在匹配已配置账号 ID 时，会覆盖该回退默认账号选择。 +- 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 - 每账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -216,14 +217,14 @@ 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`；`openclaw doctor --fix` 会移除意外尾随的 `/bot` 后缀。 -- 可选的 `channels.telegram.defaultAccount` 会在匹配已配置账号 ID 时覆盖默认账号选择。 -- 在多账号设置中（2 个以上账号 ID），设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免备用路由；当它缺失或无效时，`openclaw doctor` 会发出警告。 +- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅限常规文件；拒绝符号链接），默认账号会回退使用 `TELEGRAM_BOT_TOKEN`。 +- `apiRoot` 仅是 Telegram Bot API 根地址。请使用 `https://api.telegram.org` 或你自托管/代理的根地址，而不是 `https://api.telegram.org/bot`；`openclaw doctor --fix` 会移除意外尾随的 `/bot` 后缀。 +- 可选的 `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#channel-specific-settings)中共享。 -- Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于直接聊天和群组聊天）。 -- 重试策略：请参阅[重试策略](/zh-CN/concepts/retry)。 +- 顶层 `bindings[]` 条目配合 `type: "acp"`，用于为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。 +- Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于私聊和群聊）。 +- 重试策略：参阅[重试策略](/zh-CN/concepts/retry)。 ### Discord @@ -325,35 +326,35 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 } ``` -- 令牌：`channels.discord.token`，默认账号可回退使用 `DISCORD_BOT_TOKEN`。 -- 提供显式 Discord `token` 的直接出站调用会使用该令牌进行调用；账号重试/策略设置仍来自活动运行时快照中选定的账号。 +- 令牌：`channels.discord.token`，默认账号回退使用 `DISCORD_BOT_TOKEN`。 +- 提供显式 Discord `token` 的直接出站调用会用该令牌执行调用；账号重试/策略设置仍来自活跃运行时快照中的所选账号。 - 可选的 `channels.discord.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。 -- 使用 `user:`（私信）或 `channel:`（公会渠道）作为投递目标；裸数字 ID 会被拒绝。 -- 公会 slug 为小写，并将空格替换为 `-`；渠道键使用 slug 化后的名称（不含 `#`）。优先使用公会 ID。 -- 默认会忽略机器人发送的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 仅接受提及该机器人的机器人消息（自己的消息仍会被过滤）。 -- `channels.discord.guilds..ignoreOtherMentions`（以及渠道覆盖项）会丢弃提及其他用户或角色但未提及该机器人的消息（不包括 @everyone/@here）。 -- `maxLinesPerMessage`（默认 17）即使在低于 2000 个字符时也会拆分较高的消息。 +- 使用 `user:`（私信）或 `channel:`（服务器频道）作为投递目标；裸数字 ID 会被拒绝。 +- 服务器 slug 使用小写并将空格替换为 `-`；频道键使用 slug 化名称（无 `#`）。优先使用服务器 ID。 +- 默认忽略机器人发送的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 只接受提及机器人的机器人消息（仍会过滤自身消息）。 +- `channels.discord.guilds..ignoreOtherMentions`（以及频道覆盖项）会丢弃提及其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。 +- `maxLinesPerMessage`（默认 17）即使在 2000 个字符以内，也会拆分过高的消息。 - `channels.discord.threadBindings` 控制 Discord 线程绑定路由： - - `enabled`：Discord 对线程绑定会话功能的覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由） - - `idleHours`：Discord 对按小时计的不活跃自动取消聚焦的覆盖（`0` 表示禁用） - - `maxAgeHours`：Discord 对按小时计的硬性最大年龄的覆盖（`0` 表示禁用） - - `spawnSubagentSessions`：用于 `sessions_spawn({ thread: true })` 自动创建/绑定线程的选择加入开关 -- 顶层 `bindings[]` 条目使用 `type: "acp"` 为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 ID）。字段语义在 [ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。 + - `enabled`：线程绑定会话功能（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由）的 Discord 覆盖项 + - `idleHours`：不活跃自动取消聚焦小时数的 Discord 覆盖项（`0` 表示禁用） + - `maxAgeHours`：硬性最大年龄小时数的 Discord 覆盖项（`0` 表示禁用） + - `spawnSubagentSessions`：`sessions_spawn({ thread: true })` 自动创建/绑定线程的选择启用开关 +- 顶层 `bindings[]` 条目配合 `type: "acp"` 为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用频道/线程 ID）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享。 - `channels.discord.ui.components.accentColor` 设置 Discord components v2 容器的强调色。 -- `channels.discord.voice` 启用 Discord 语音渠道对话，以及可选的自动加入 + LLM + TTS 覆盖。 -- `channels.discord.voice.model` 可选地覆盖用于 Discord 语音渠道响应的 LLM 模型。 -- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会传递给 `@discordjs/voice` DAVE 选项（默认分别为 `true` 和 `24`）。 -- OpenClaw 还会在重复解密失败后，通过离开/重新加入语音会话来尝试恢复语音接收。 +- `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入 + LLM + TTS 覆盖项。 +- `channels.discord.voice.model` 可选地覆盖用于 Discord 语音频道回复的 LLM 模型。 +- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传到 `@discordjs/voice` DAVE 选项（默认分别为 `true` 和 `24`）。 +- OpenClaw 还会在重复解密失败后，通过离开并重新加入语音会话来尝试语音接收恢复。 - `channels.discord.streaming` 是规范的流模式键。旧版 `streamMode` 和布尔值 `streaming` 会自动迁移。 -- `channels.discord.autoPresence` 将运行时可用性映射到机器人在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 -- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/标签匹配（紧急兼容模式）。 +- `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`。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析审批人时，exec 审批会激活。 + - `approvers`：允许审批 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 - `sessionFilter`：可选的会话键模式（子字符串或正则表达式）。 - - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到来源渠道，`"both"` 同时发送到两者。当目标包含 `"channel"` 时，按钮只能由已解析的审批人使用。 - - `cleanupAfterResolve`：当为 `true` 时，会在批准、拒绝或超时后删除审批私信。 + - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到来源频道，`"both"` 同时发送到两者。当目标包含 `"channel"` 时，按钮只有解析出的审批人可用。 + - `cleanupAfterResolve`：为 `true` 时，在审批、拒绝或超时后删除审批私信。 **反应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自所有消息上的 `guilds..users`）。 @@ -390,7 +391,7 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 - 也支持服务账号 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 - 使用 `spaces/` 或 `users/` 作为投递目标。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（紧急兼容模式）。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变邮箱主体匹配（应急兼容模式）。 ### Slack @@ -462,35 +463,44 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 } ``` -- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP mode** 需要 `botToken` 加 `signingSecret`（位于根级或按账号配置）。 -- `socketMode` 会将 Slack SDK Socket Mode 传输调优传递给公共 Bolt receiver API。仅在调查 ping/pong 超时或陈旧 websocket 行为时使用它。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。 -- Slack 账号快照会公开按凭证划分的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 下的 `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef 配置，但当前命令/运行时路径无法解析密钥值。 -- `configWrites: false` 会阻止由 Slack 发起的配置写入。 +- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号环境变量回退使用 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP mode** 需要 `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 配置，但当前命令/运行时路径无法 + 解析密钥值。 +- `configWrites: false` 会阻止 Slack 发起的配置写入。 - 可选的 `channels.slack.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。 -- `channels.slack.streaming.mode` 是规范的 Slack 流模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输协议。旧版 `streamMode`、布尔值 `streaming` 和 `nativeStreaming` 会自动迁移。 +- `channels.slack.streaming.mode` 是规范的 Slack 流模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版 `streamMode`、布尔值 `streaming` 和 `nativeStreaming` 会自动迁移。 - 使用 `user:`（私信）或 `channel:` 作为投递目标。 **反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 是按线程（默认）或在渠道内共享。`thread.inheritParent` 会将父渠道转录复制到新线程。 +**线程会话隔离：** `thread.historyScope` 是按线程（默认）或在频道间共享。`thread.inheritParent` 会将父频道转录复制到新线程。 -- Slack 原生流式传输加上 Slack 助手风格的 “is typing...” 线程状态需要回复线程目标。顶层私信默认保持在线程外，因此它们使用 `typingReaction` 或普通投递，而不是线程风格预览。 -- `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"`）。 +- Slack 原生流式传输加上 Slack 助手风格的 “is typing...” 线程状态需要回复线程目标。顶层私信默认保持不在线程内，因此它们会使用 `typingReaction` 或普通投递，而不是线程风格预览。 +- `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"`）。 | 操作组 | 默认值 | 备注 | | ------------ | ------- | ---------------------- | -| reactions | enabled | 反应 + 列出反应 | -| messages | enabled | 读取/发送/编辑/删除 | -| pins | enabled | 置顶/取消置顶/列出 | -| memberInfo | enabled | 成员信息 | -| emojiList | enabled | 自定义表情列表 | +| reactions | 已启用 | 反应 + 列出反应 | +| messages | 已启用 | 读取/发送/编辑/删除 | +| pins | 已启用 | 置顶/取消置顶/列出 | +| memberInfo | 已启用 | 成员信息 | +| emojiList | 已启用 | 自定义表情列表 | ### Mattermost -在当前 OpenClaw 版本中，Mattermost 作为内置插件提供。较旧版本或自定义构建可以通过 `openclaw plugins install @openclaw/mattermost` 安装当前 npm 包；如果 npm 报告 OpenClaw 拥有的包已弃用，请使用内置插件或本地检出，直到发布更新的 npm 包。 +Mattermost 在当前 OpenClaw 版本中作为内置插件提供。较旧或 +自定义构建可以用以下命令安装当前 npm 包： +`openclaw plugins install @openclaw/mattermost`；如果 npm 报告 +OpenClaw 拥有的包已弃用，请使用内置插件或本地检出版本， +直到发布更新的 npm 包。 ```json5 { @@ -520,17 +530,23 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 } ``` -聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息）、`onchar`（以触发前缀开头的消息）。 +聊天模式：`oncall`（在 @ 提及时回复，默认）、`onmessage`（每条消息）、`onchar`（以触发前缀开头的消息）。 启用 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 发起的配置写入。 -- `channels.mattermost.requireMention`：在渠道中回复前要求 `@mention`。 -- `channels.mattermost.groups..requireMention`：按渠道提及门控覆盖（`"*"` 表示默认）。 +- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器可访问它。 +- 原生斜杠回调使用 Mattermost 在斜杠命令注册期间返回的每命令令牌 + 进行认证。如果注册失败或没有激活任何 + 命令，OpenClaw 会用 + `Unauthorized: invalid command token.` + 拒绝回调。 +- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 + `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域。 + 使用主机/域值，而不是完整 URL。 +- `channels.mattermost.configWrites`：允许或拒绝 Mattermost 发起的配置写入。 +- `channels.mattermost.requireMention`：要求在频道中回复前先 `@mention`。 +- `channels.mattermost.groups..requireMention`：按频道的提及门控覆盖项（`"*"` 表示默认）。 - 可选的 `channels.mattermost.defaultAccount` 在匹配已配置账号 ID 时会覆盖默认账号选择。 ### Signal @@ -552,11 +568,11 @@ WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在 } ``` -**回应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 +**表情反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -- `channels.signal.account`：将渠道启动固定到特定的 Signal 账户身份。 +- `channels.signal.account`：将渠道启动固定到特定 Signal 账号身份。 - `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。 -- 可选的 `channels.signal.defaultAccount` 在匹配已配置的账户 ID 时，会覆盖默认账户选择。 +- 可选的 `channels.signal.defaultAccount` 会在匹配已配置账号 ID 时覆盖默认账号选择。 ### BlueBubbles @@ -575,9 +591,9 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，在 `channels.blueb } ``` -- 这里涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 可选的 `channels.bluebubbles.defaultAccount` 在匹配已配置的账户 ID 时，会覆盖默认账户选择。 -- 顶层 `bindings[]` 条目带有 `type: "acp"` 时，可以将 BlueBubbles 对话绑定到持久 ACP 会话。请在 `match.peer.id` 中使用 BlueBubbles 句柄或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 +- 可选的 `channels.bluebubbles.defaultAccount` 会在匹配已配置账号 ID 时覆盖默认账号选择。 +- 顶层 `bindings[]` 条目带有 `type: "acp"` 时，可以将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles 句柄或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings)。 - 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。 ### iMessage @@ -606,17 +622,17 @@ OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护 } ``` -- 可选的 `channels.imessage.defaultAccount` 在匹配已配置的账户 ID 时，会覆盖默认账户选择。 +- 可选的 `channels.imessage.defaultAccount` 会在匹配已配置账号 ID 时覆盖默认账号选择。 -- 需要对 Messages 数据库授予完全磁盘访问权限。 +- 需要对 Messages DB 拥有完全磁盘访问权限。 - 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）用于 SCP 附件获取。 -- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制入站附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 -- SCP 使用严格的主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 +- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以便通过 SCP 获取附件。 +- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制传入附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 +- SCP 使用严格的主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts`。 - `channels.imessage.configWrites`：允许或拒绝由 iMessage 发起的配置写入。 -- 顶层 `bindings[]` 条目带有 `type: "acp"` 时，可以将 iMessage 对话绑定到持久 ACP 会话。请在 `match.peer.id` 中使用规范化句柄或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 顶层 `bindings[]` 条目带有 `type: "acp"` 时，可以将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用标准化句柄或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义：[ACP 智能体](/zh-CN/tools/acp-agents#channel-specific-settings)。 - + ```bash #!/usr/bin/env bash @@ -658,20 +674,20 @@ Matrix 由插件支持，并在 `channels.matrix` 下配置。 ``` - 令牌认证使用 `accessToken`；密码认证使用 `userId` + `password`。 -- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账户可以用 `channels.matrix.accounts..proxy` 覆盖它。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 和这个网络选择加入项是彼此独立的控制项。 -- `channels.matrix.defaultAccount` 在多账户设置中选择首选账户。 -- `channels.matrix.autoJoin` 默认是 `off`，因此受邀房间和新的私信风格邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并配置 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。 -- `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递和审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析审批人时，exec 审批会启用。 - - `approvers`：允许审批 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 +- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可以用 `channels.matrix.accounts..proxy` 覆盖它。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 和此网络选择加入是彼此独立的控制项。 +- `channels.matrix.defaultAccount` 在多账号设置中选择首选账号。 +- `channels.matrix.autoJoin` 默认为 `off`，因此受邀房间和新的私信式邀请会被忽略，直到你设置带有 `autoJoinAllowlist` 的 `autoJoin: "allowlist"` 或 `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..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组成会话：`per-user`（默认）按路由后的对端共享，而 `per-room` 会隔离每个私信房间。 -- Matrix Status 探针和实时目录查找使用与运行时流量相同的代理策略。 -- 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 + - 按账号覆盖：`channels.matrix.accounts..execApprovals`。 +- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何分组到会话：`per-user`（默认）按路由到的对等方共享，而 `per-room` 会隔离每个私信房间。 +- Matrix Status 探测和实时目录查找使用与运行时流量相同的代理策略。 +- 完整的 Matrix 配置、目标选择规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 ### Microsoft Teams @@ -690,7 +706,7 @@ Microsoft Teams 由插件支持，并在 `channels.msteams` 下配置。 } ``` -- 这里涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 +- 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 - 完整的 Teams 配置（凭证、webhook、私信/群组策略、按团队/按渠道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 ### IRC @@ -716,13 +732,13 @@ IRC 由插件支持，并在 `channels.irc` 下配置。 } ``` -- 这里涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可选的 `channels.irc.defaultAccount` 在匹配已配置的账户 ID 时，会覆盖默认账户选择。 +- 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 +- 可选的 `channels.irc.defaultAccount` 会在匹配已配置账号 ID 时覆盖默认账号选择。 - 完整的 IRC 渠道配置（主机/端口/TLS/渠道/允许列表/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 -### 多账户（所有渠道） +### 多账号（所有渠道） -每个渠道运行多个账户（每个账户都有自己的 `accountId`）： +每个渠道运行多个账号（每个账号都有自己的 `accountId`）： ```json5 { @@ -743,34 +759,35 @@ IRC 由插件支持，并在 `channels.irc` 下配置。 } ``` -- 省略 `accountId` 时使用 `default`（CLI + 路由）。 -- 环境变量令牌只适用于**默认**账户。 -- 基础渠道设置会应用到所有账户，除非按账户覆盖。 -- 使用 `bindings[].match.accountId` 将每个账户路由到不同的智能体。 -- 如果你通过 `openclaw channels add`（或渠道新手引导）添加非默认账户时，仍在使用单账户顶层渠道配置，OpenClaw 会先将账户范围的顶层单账户值提升到渠道账户映射中，这样原始账户会继续工作。大多数渠道会把它们移入 `channels..accounts.default`；Matrix 可以改为保留现有匹配的命名/默认目标。 -- 现有的仅渠道绑定（没有 `accountId`）继续匹配默认账户；账户范围绑定仍然是可选的。 -- `openclaw doctor --fix` 还会通过把账户范围的顶层单账户值移动到为该渠道选择的已提升账户中，修复混合形状。大多数渠道使用 `accounts.default`；Matrix 可以改为保留现有匹配的命名/默认目标。 +- 省略 `accountId` 时会使用 `default`（CLI + 路由）。 +- 环境变量令牌仅应用于**默认**账号。 +- 基础渠道设置会应用于所有账号，除非按账号覆盖。 +- 使用 `bindings[].match.accountId` 将每个账号路由到不同的智能体。 +- 如果你通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，而仍在使用单账号顶层渠道配置，OpenClaw 会先将账号作用域的顶层单账号值提升到渠道账号映射中，以便原账号继续工作。大多数渠道会将它们移动到 `channels..accounts.default`；Matrix 则可以保留现有的匹配命名/默认目标。 +- 现有的仅渠道绑定（没有 `accountId`）会继续匹配默认账号；账号作用域绑定仍是可选的。 +- `openclaw doctor --fix` 也会通过将账号作用域的顶层单账号值移动到该渠道选定的已提升账号中来修复混合形态。大多数渠道使用 `accounts.default`；Matrix 则可以保留现有的匹配命名/默认目标。 ### 其他插件渠道 -许多插件渠道配置为 `channels.`，并记录在各自专用的渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 -请参阅完整的渠道索引：[渠道](/zh-CN/channels)。 +许多插件渠道配置为 `channels.`，并记录在它们专用的渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 +请参阅完整渠道索引：[渠道](/zh-CN/channels)。 ### 群聊提及门控 -群组消息默认**需要提及**（元数据提及或安全正则表达式模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 +群组消息默认**要求提及**（元数据提及或安全正则表达式模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 -可见回复单独控制。群组/渠道房间默认使用 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍会处理该轮次，但普通最终回复会保持私密，房间中的可见输出需要 `message(action=send)`。仅当你想要旧版行为，也就是普通回复会发回房间时，才设置 `"automatic"`。 +可见回复单独控制。群组/渠道房间默认使用 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍会处理该轮次，但普通最终回复保持私密，房间中的可见输出需要 `message(action=send)`。只有当你想要旧版行为，即普通回复被发回房间时，才设置 `"automatic"`。若要将相同的仅工具可见回复行为也应用到直接聊天，请设置 `messages.visibleReplies: "message_tool"`。 **提及类型：** -- **元数据提及**：原生平台 @ 提及。在 WhatsApp 自聊模式中会被忽略。 +- **元数据提及**：原生平台 @-提及。在 WhatsApp 自聊模式中会被忽略。 - **文本模式**：`agents.list[].groupChat.mentionPatterns` 中的安全正则表达式模式。无效模式和不安全的嵌套重复会被忽略。 -- 仅在可以检测时（原生提及或至少一个模式），才会强制执行提及门控。 +- 仅在可以检测时（原生提及或至少一个模式）才会强制执行提及门控。 ```json5 { messages: { + visibleReplies: "automatic", // global default for direct/source chats groupChat: { historyLimit: 50, visibleReplies: "message_tool", // default; use "automatic" for legacy final replies @@ -782,9 +799,9 @@ IRC 由插件支持，并在 `channels.irc` 下配置。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。渠道可以用 `channels..historyLimit`（或按账户）覆盖。设置为 `0` 可禁用。 +`messages.groupChat.historyLimit` 设置全局默认值。渠道可以用 `channels..historyLimit`（或按账号设置）覆盖。设置为 `0` 可禁用。 -`messages.groupChat.visibleReplies` 对群组/渠道来源轮次是全局的；渠道允许列表和提及门控仍会决定是否处理某个轮次。 +`messages.visibleReplies` 是全局来源轮次默认值；`messages.groupChat.visibleReplies` 会覆盖群组/渠道来源轮次的设置。渠道允许列表和提及门控仍会决定是否处理某个轮次。 #### 私信历史限制 @@ -807,7 +824,7 @@ IRC 由插件支持，并在 `channels.irc` 下配置。 #### 自聊模式 -将你自己的号码包含在 `allowFrom` 中以启用自聊模式（忽略原生 @ 提及，只响应文本模式）： +在 `allowFrom` 中包含你自己的号码以启用自聊模式（忽略原生 @-提及，只响应文本模式）： ```json5 { @@ -857,24 +874,24 @@ IRC 由插件支持，并在 `channels.irc` 下配置。 -- 此块用于配置命令界面。当前内置 + 捆绑命令目录见[斜杠命令](/zh-CN/tools/slash-commands)。 -- 此页面是**配置键参考**，不是完整命令目录。由渠道/插件拥有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、设备配对 `/pair`、memory `/dreaming`、phone-control `/phone` 和 Talk `/voice`，记录在它们各自的渠道/插件页面以及[斜杠命令](/zh-CN/tools/slash-commands)中。 +- 此块配置命令界面。当前内置 + 捆绑的命令目录请参见[斜杠命令](/zh-CN/tools/slash-commands)。 +- 此页面是**配置键参考**，不是完整的命令目录。由渠道/插件拥有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、device-pair `/pair`、memory `/dreaming`、phone-control `/phone` 和 Talk `/voice`，记录在各自的渠道/插件页面以及[斜杠命令](/zh-CN/tools/slash-commands)中。 - 文本命令必须是带有前导 `/` 的**独立**消息。 -- `native: "auto"` 会为 Discord/Telegram 启用原生命令，Slack 保持关闭。 -- `nativeSkills: "auto"` 会为 Discord/Telegram 启用原生 Skills 命令，Slack 保持关闭。 -- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前注册的命令。 +- `native: "auto"` 为 Discord/Telegram 启用原生命令，Slack 保持关闭。 +- `nativeSkills: "auto"` 为 Discord/Telegram 启用原生 Skills 命令，Slack 保持关闭。 +- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除之前注册的命令。 - 使用 `channels..commands.nativeSkills` 按渠道覆盖原生 Skills 注册。 - `channels.telegram.customCommands` 会添加额外的 Telegram 机器人菜单项。 -- `bash: true` 会为主机 shell 启用 `! `。需要 `tools.elevated.enabled`，且发送者位于 `tools.elevated.allowFrom.` 中。 -- `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`。 +- `bash: true` 为主机 shell 启用 `! `。需要 `tools.elevated.enabled`，且发送者位于 `tools.elevated.allowFrom.` 中。 +- `config: true` 启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化的 `/config set|unset` 写入还需要 `operator.admin`；只读的 `/config show` 仍可供普通写入作用域的 operator 客户端使用。 +- `mcp: true` 为 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。 +- `plugins: true` 启用 `/plugins`，用于插件发现、安装以及启用/停用控制。 - `channels..configWrites` 按渠道限制配置变更（默认：true）。 -- 对于多账号渠道，`channels..accounts..configWrites` 也会限制针对该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 -- `restart: false` 会禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。 -- `ownerAllowFrom` 是仅限 owner 命令/工具使用的显式 owner 允许列表。它独立于 `allowFrom`。 -- `ownerDisplay: "hash"` 会在系统提示中对 owner ID 进行哈希处理。设置 `ownerDisplaySecret` 以控制哈希。 -- `allowFrom` 按提供商配置。设置后，它就是**唯一**的授权来源（渠道允许列表/配对和 `useAccessGroups` 会被忽略）。 +- 对于多账号渠道，`channels..accounts..configWrites` 也会限制面向该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 +- `restart: false` 禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。 +- `ownerAllowFrom` 是仅限所有者命令/工具的显式所有者允许列表。它独立于 `allowFrom`。 +- `ownerDisplay: "hash"` 会在系统提示中哈希所有者 ID。设置 `ownerDisplaySecret` 可控制哈希。 +- `allowFrom` 按提供商配置。设置后，它就是**唯一**授权来源（会忽略渠道允许列表/配对和 `useAccessGroups`）。 - 当未设置 `allowFrom` 时，`useAccessGroups: false` 允许命令绕过访问组策略。 - 命令文档映射： - 内置 + 捆绑目录：[斜杠命令](/zh-CN/tools/slash-commands) @@ -882,14 +899,14 @@ IRC 由插件支持，并在 `channels.irc` 下配置。 - QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot) - 配对命令：[配对](/zh-CN/channels/pairing) - LINE 卡片命令：[LINE](/zh-CN/channels/line) - - memory Dreaming：[Dreaming](/zh-CN/concepts/dreaming) + - memory dreaming：[Dreaming](/zh-CN/concepts/dreaming) --- -## 相关 +## 相关内容 -- [配置参考](/zh-CN/gateway/configuration-reference) — 顶级键 +- [配置参考](/zh-CN/gateway/configuration-reference) — 顶层键 - [配置 — 智能体](/zh-CN/gateway/config-agents) - [渠道概览](/zh-CN/channels) diff --git a/docs/zh-CN/gateway/configuration-examples.md b/docs/zh-CN/gateway/configuration-examples.md index 81423bd0d..339ee5492 100644 --- a/docs/zh-CN/gateway/configuration-examples.md +++ b/docs/zh-CN/gateway/configuration-examples.md @@ -1,24 +1,24 @@ --- read_when: - - 了解如何配置 OpenClaw + - 学习如何配置 OpenClaw - 正在查找配置示例 - 首次设置 OpenClaw summary: 常见 OpenClaw 设置的符合模式定义的配置示例 title: 配置示例 x-i18n: - generated_at: "2026-04-28T11:51:06Z" + generated_at: "2026-04-29T10:10:48Z" model: gpt-5.5 provider: openai - source_hash: 77596ca08e296761edcda5b920e766a773a963b94147c0e163853834806fda6a + source_hash: c7de2f711305a4d06f2b31efeafdf72f083e0437155850b549e770ea90f43faa source_path: gateway/configuration-examples.md workflow: 16 --- -下面的示例与当前配置 schema 保持一致。有关完整参考和逐字段说明，请参阅 [配置](/zh-CN/gateway/configuration)。 +以下示例与当前配置 schema 对齐。完整参考和逐字段说明，请参阅 [配置](/zh-CN/gateway/configuration)。 ## 快速开始 -### 最小必需配置 +### 绝对最小配置 ```json5 { @@ -27,7 +27,7 @@ x-i18n: } ``` -保存到 `~/.openclaw/openclaw.json`，然后你就可以从该号码私信机器人。 +保存到 `~/.openclaw/openclaw.json`，然后你就可以从该号码给机器人发送私信。 ### 推荐起始配置 @@ -49,6 +49,7 @@ x-i18n: }, }, messages: { + visibleReplies: "automatic", groupChat: { visibleReplies: "message_tool", // default; use "automatic" for legacy room replies }, @@ -56,9 +57,9 @@ x-i18n: } ``` -## 扩展示例（主要选项） +## 展开示例（主要选项） -> JSON5 允许你使用注释和尾随逗号。普通 JSON 也可以使用。 +> JSON5 允许使用注释和尾随逗号。普通 JSON 也可以使用。 ```json5 { @@ -108,6 +109,7 @@ x-i18n: // Message formatting messages: { messagePrefix: "[openclaw]", + visibleReplies: "automatic", responsePrefix: ">", ackReaction: "👀", ackReactionScope: "group-mentions", @@ -469,7 +471,7 @@ x-i18n: ## 常见模式 -### 共享 Skills 基线和一个覆盖项 +### 共享 Skills 基线，并带有一个覆盖项 ```json5 { @@ -487,7 +489,7 @@ x-i18n: ``` - `agents.defaults.skills` 是共享基线。 -- `agents.list[].skills` 会为某个智能体替换该基线。 +- `agents.list[].skills` 会为一个智能体替换该基线。 - 当某个智能体不应看到任何 Skills 时，使用 `skills: []`。 ### 多平台设置 @@ -513,7 +515,7 @@ x-i18n: ### 受信任节点网络自动批准 -除非你控制网络路径，否则保持设备配对为手动。对于专用实验室或 tailnet 子网，你可以选择使用精确的 CIDR 或 IP 来启用首次节点设备自动批准： +除非你控制网络路径，否则请保持设备配对为手动。对于专用实验室或 tailnet 子网，你可以选择使用精确的 CIDR 或 IP，为首次节点设备配对启用自动批准： ```json5 { @@ -527,11 +529,11 @@ x-i18n: } ``` -未设置时，此功能仍保持关闭。它仅适用于全新的 `role: node` 配对，且没有请求任何范围。操作员/浏览器客户端，以及角色、范围、元数据或公钥升级，仍然需要手动批准。 +未设置时，此功能保持关闭。它只适用于全新的 `role: node` 配对，且没有请求任何作用域。操作员/浏览器客户端，以及角色、作用域、元数据或公钥升级仍然需要手动批准。 ### 安全私信模式（共享收件箱 / 多用户私信） -如果不止一个人可以向你的机器人发送私信（`allowFrom` 中有多个条目、为多个人批准了配对，或设置了 `dmPolicy: "open"`），请启用**安全私信模式**，这样来自不同发送者的私信默认不会共享同一个上下文： +如果不止一个人可以给你的 bot 发送私信（`allowFrom` 中有多个条目、为多人批准配对，或 `dmPolicy: "open"`），请启用**安全私信模式**，这样来自不同发送者的私信默认不会共享同一个上下文： ```json5 { @@ -556,7 +558,7 @@ x-i18n: ``` 对于 Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC，发送者授权默认优先使用 ID。 -只有在你明确接受该风险时，才为每个渠道启用直接可变名称/邮箱/nick 匹配：`dangerouslyAllowNameMatching: true`。 +只有在你明确接受该风险时，才应通过每个渠道的 `dangerouslyAllowNameMatching: true` 启用直接可变的名称/邮箱/nick 匹配。 ### Anthropic API 密钥 + MiniMax 回退 @@ -592,7 +594,7 @@ x-i18n: } ``` -### 工作机器人（受限访问） +### 工作 bot（受限访问） ```json5 { @@ -617,7 +619,7 @@ x-i18n: } ``` -### 仅本地模型 +### 仅使用本地模型 ```json5 { @@ -652,11 +654,11 @@ x-i18n: ## 提示 - 如果你设置了 `dmPolicy: "open"`，对应的 `allowFrom` 列表必须包含 `"*"`。 -- 提供商 ID 各不相同（电话号码、用户 ID、渠道 ID）。请使用提供商文档确认格式。 -- 稍后可添加的可选章节：`web`、`browser`、`ui`、`discovery`、`canvasHost`、`talk`、`signal`、`imessage`。 -- 有关更深入的设置说明，请参阅 [提供商](/zh-CN/providers) 和 [故障排除](/zh-CN/gateway/troubleshooting)。 +- 提供商 ID 各不相同（电话号码、用户 ID、渠道 ID）。使用提供商文档确认格式。 +- 可稍后添加的可选部分：`web`、`browser`、`ui`、`discovery`、`canvasHost`、`talk`、`signal`、`imessage`。 +- 请参阅[提供商](/zh-CN/providers)和[故障排除](/zh-CN/gateway/troubleshooting)，了解更深入的设置说明。 -## 相关 +## 相关内容 - [配置参考](/zh-CN/gateway/configuration-reference) - [配置](/zh-CN/gateway/configuration) diff --git a/docs/zh-CN/gateway/configuration.md b/docs/zh-CN/gateway/configuration.md index d1e3d44f9..039369a58 100644 --- a/docs/zh-CN/gateway/configuration.md +++ b/docs/zh-CN/gateway/configuration.md @@ -3,38 +3,36 @@ read_when: - 首次设置 OpenClaw - 正在查找常见配置模式 - 导航到特定配置部分 -summary: 配置概览：常见任务、快速设置，以及完整参考的链接 +summary: 配置概览：常见任务、快速设置，以及完整参考链接 title: 配置 x-i18n: - generated_at: "2026-04-28T22:57:53Z" + generated_at: "2026-04-29T10:10:49Z" model: gpt-5.5 provider: openai - source_hash: b425a43ea6e40b8380d3a295dc9b190e5dbce7a6d044df786133bfadf3b07c0d + source_hash: 92eaad06dff8ec777adc881edbabc45048a376078d2814f2d3f7e7035abb2e8d source_path: gateway/configuration.md workflow: 16 --- -OpenClaw 从 `~/.openclaw/openclaw.json` 读取可选的 **JSON5** 配置。 -活动配置路径必须是常规文件。对于 OpenClaw 自有写入，不支持符号链接形式的 `openclaw.json` -布局；原子写入可能会替换 -该路径，而不是保留符号链接。如果你将配置保存在 +OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 **JSON5** 配置。 +活动配置路径必须是常规文件。对于 OpenClaw 拥有的写入，不支持符号链接的 `openclaw.json` +布局；原子写入可能会替换该路径，而不是保留符号链接。如果你将配置放在 默认状态目录之外，请将 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。 如果文件缺失，OpenClaw 会使用安全默认值。添加配置的常见原因： -- 连接渠道并控制谁可以给 bot 发消息 +- 连接渠道并控制谁可以给机器人发消息 - 设置模型、工具、沙箱隔离或自动化（cron、钩子） - 调整会话、媒体、网络或 UI -请参阅[完整参考](/zh-CN/gateway/configuration-reference)，了解每个可用字段。 +请参阅[完整参考](/zh-CN/gateway/configuration-reference)了解每个可用字段。 智能体和自动化在编辑配置前，应使用 `config.schema.lookup` 获取精确的字段级 -文档。使用本页获取面向任务的指导，并使用 -[配置参考](/zh-CN/gateway/configuration-reference) 查看更完整的 +文档。将本页用于面向任务的指导，并使用[配置参考](/zh-CN/gateway/configuration-reference)了解更广泛的 字段映射和默认值。 -**刚开始接触配置？** 从 `openclaw onboard` 开始进行交互式设置，或查看 [配置示例](/zh-CN/gateway/configuration-examples)指南，获取完整的可复制粘贴配置。 +**刚接触配置？** 从 `openclaw onboard` 开始进行交互式设置，或查看[配置示例](/zh-CN/gateway/configuration-examples)指南获取完整的可复制粘贴配置。 ## 最小配置 @@ -50,68 +48,65 @@ OpenClaw 从 `~/.openclaw/openclaw.json` 读取可选的 + ```bash openclaw onboard # full onboarding flow openclaw configure # config wizard ``` - + ```bash openclaw config get agents.defaults.workspace openclaw config set agents.defaults.heartbeat.every "2h" openclaw config unset plugins.entries.brave.config.webSearch.apiKey ``` - + 打开 [http://127.0.0.1:18789](http://127.0.0.1:18789)，并使用 **配置** 标签页。 - 控制 UI 会根据实时配置 schema 渲染表单，包括字段 - `title` / `description` 文档元数据，以及可用的插件和渠道 schema， - 并提供 **Raw JSON** 编辑器作为备用方式。对于下钻 - UI 和其他工具，Gateway 网关还会暴露 `config.schema.lookup`， - 用于获取一个限定路径的 schema 节点及其直接子项摘要。 + Control UI 会根据实时配置 schema 渲染表单，包括字段 + `title` / `description` 文档元数据，以及可用时的插件和渠道 schema， + 并提供 **Raw JSON** 编辑器作为逃生通道。对于下钻式 + UI 和其他工具，Gateway 网关还会公开 `config.schema.lookup`，用于 + 获取一个路径范围的 schema 节点及其直接子级摘要。 - - 直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监听该文件并自动应用更改（参见[热重载](#config-hot-reload)）。 + + 直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。 -## 严格校验 +## 严格验证 -OpenClaw 只接受完全匹配 schema 的配置。未知键、格式错误的类型或无效值会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器可以附加 JSON Schema 元数据。 +OpenClaw 只接受完全匹配 schema 的配置。未知键、格式错误的类型或无效值会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器就可以附加 JSON Schema 元数据。 -`openclaw config schema` 会打印控制 UI -和校验使用的权威 JSON Schema。`config.schema.lookup` 会获取单个限定路径的节点及 -子项摘要，供下钻工具使用。字段 `title`/`description` 文档元数据会 -传递到嵌套对象、通配符（`*`）、数组项（`[]`）以及 `anyOf`/ -`oneOf`/`allOf` 分支中。加载 manifest 注册表后，运行时插件和渠道 schema 会合并进来。 +`openclaw config schema` 会打印 Control UI 和验证所使用的规范 JSON Schema。 +`config.schema.lookup` 会获取单个路径范围的节点及子级摘要，供下钻工具使用。 +字段 `title`/`description` 文档元数据会贯穿嵌套对象、通配符（`*`）、数组项（`[]`），以及 `anyOf`/ +`oneOf`/`allOf` 分支。当清单注册表加载后，运行时插件和渠道 schema 会合并进来。 -校验失败时： +验证失败时： - Gateway 网关不会启动 - 只有诊断命令可用（`openclaw doctor`、`openclaw logs`、`openclaw health`、`openclaw status`） - 运行 `openclaw doctor` 查看确切问题 - 运行 `openclaw doctor --fix`（或 `--yes`）应用修复 -Gateway 网关会在每次成功启动后保留一份可信的最后已知良好副本。 -如果 `openclaw.json` 之后校验失败（或丢失 `gateway.mode`、大幅缩小， -或者前面被插入了一行杂散日志），OpenClaw 会将损坏的文件保留为 -`.clobbered.*`，恢复最后已知良好副本，并记录恢复 -原因。下一次智能体轮次也会收到系统事件警告，避免主 -智能体盲目重写已恢复的配置。当候选配置包含经过遮蔽的密钥占位符（例如 `***`）时， -会跳过提升为最后已知良好副本。 -当所有校验问题都限定在 `plugins.entries....` 范围内时，OpenClaw -不会执行整文件恢复。它会保持当前配置生效，并 -呈现插件本地失败，以免插件 schema 或主机版本不匹配 -回滚无关的用户设置。 +Gateway 网关会在每次成功启动后保留一份可信的最近一次可用副本。 +如果 `openclaw.json` 后续验证失败（或丢失 `gateway.mode`、大幅缩小， +或开头被插入了一行无关日志），OpenClaw 会将损坏文件保留为 +`.clobbered.*`，恢复最近一次可用副本，并记录恢复原因。 +下一轮智能体也会收到系统事件警告，以便主智能体不会盲目重写已恢复的配置。 +当候选配置包含已遮盖的密钥占位符（例如 `***`）时，会跳过提升为最近一次可用副本。 +当所有验证问题都限定在 `plugins.entries....` 范围内时，OpenClaw +不会执行整文件恢复。它会保持当前配置处于活动状态，并暴露插件本地失败，这样插件 schema 或主机版本不匹配 +就不能回滚无关的用户设置。 ## 常见任务 - - 每个渠道在 `channels.` 下都有自己的配置部分。请查看对应的渠道页面了解设置步骤： + + 每个渠道在 `channels.` 下都有自己的配置部分。请参阅对应的渠道页面了解设置步骤： - [WhatsApp](/zh-CN/channels/whatsapp) — `channels.whatsapp` - [Telegram](/zh-CN/channels/telegram) — `channels.telegram` @@ -141,8 +136,8 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 - - 设置主模型和可选回退模型： + + 设置主模型和可选回退： ```json5 { @@ -162,34 +157,35 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 ``` - `agents.defaults.models` 定义模型目录，并作为 `/model` 的允许列表。 - - 使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加允许列表条目，而不会移除现有模型。除非传入 `--replace`，否则会移除条目的普通替换会被拒绝。 + - 使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加允许列表条目，而不会移除现有模型。除非你传入 `--replace`，否则会移除条目的普通替换会被拒绝。 - 模型引用使用 `provider/model` 格式（例如 `anthropic/claude-opus-4-6`）。 - - `agents.defaults.imageMaxDimensionPx` 控制 transcript/工具图片缩小尺寸（默认 `1200`）；较低的值通常会减少大量截图运行中的视觉 token 用量。 + - `agents.defaults.imageMaxDimensionPx` 控制 transcript/工具图像降采样（默认值 `1200`）；较低的值通常会降低大量截图运行中的视觉 token 用量。 - 请参阅 [Models CLI](/zh-CN/concepts/models) 了解如何在聊天中切换模型，并参阅[模型故障转移](/zh-CN/concepts/model-failover)了解认证轮换和回退行为。 - 对于自定义/自托管提供商，请参阅参考中的[自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。 - - 私信访问通过每个渠道的 `dmPolicy` 控制： + + 私信访问按渠道通过 `dmPolicy` 控制： - - `"pairing"`（默认）：未知发送者会收到一次性配对码，用于批准 + - `"pairing"`（默认）：未知发送者会收到一次性配对码以供批准 - `"allowlist"`：只允许 `allowFrom`（或已配对允许存储）中的发送者 - `"open"`：允许所有入站私信（需要 `allowFrom: ["*"]`） - `"disabled"`：忽略所有私信 - 对于群组，请使用 `groupPolicy` + `groupAllowFrom` 或渠道特定允许列表。 + 对于群组，请使用 `groupPolicy` + `groupAllowFrom` 或渠道特定的允许列表。 - 请参阅[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)，了解每个渠道的详细信息。 + 请参阅[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)了解每个渠道的详细信息。 - - 群消息默认**需要提及**。按智能体配置触发模式，并让可见的房间回复保留在默认消息工具路径上，除非你有意使用旧版自动最终回复： + + 群组消息默认**需要提及**。按智能体配置触发模式，并让可见房间回复保留在默认消息工具路径上，除非你有意使用旧版自动最终回复： ```json5 { messages: { + visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere groupChat: { visibleReplies: "message_tool", // default; use "automatic" for legacy room replies }, @@ -213,15 +209,15 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 ``` - **元数据提及**：原生 @ 提及（WhatsApp 点按提及、Telegram @bot 等） - - **文本模式**：`mentionPatterns` 中的安全正则模式 - - **可见回复**：`message_tool` 会保持普通最终回复私密；智能体必须调用 `message(action=send)` 才能在群组/渠道中可见地发布。 - - 请参阅[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)，了解可见回复模式、每个渠道的覆盖项以及自聊天模式。 + - **文本模式**：`mentionPatterns` 中的安全正则表达式模式 + - **可见回复**：`messages.visibleReplies` 可以在全局要求使用消息工具发送；`messages.groupChat.visibleReplies` 会为群组/渠道覆盖该设置。 + - 请参阅[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)了解可见回复模式、每个渠道的覆盖项和自聊天模式。 - - 使用 `agents.defaults.skills` 设置共享基线，然后用 `agents.list[].skills` - 覆盖特定智能体： + + 使用 `agents.defaults.skills` 作为共享基线，然后用 + `agents.list[].skills` 覆盖特定智能体： ```json5 { @@ -238,16 +234,16 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 } ``` - - 默认情况下省略 `agents.defaults.skills` 表示不限制 Skills。 - - 省略 `agents.list[].skills` 表示继承默认值。 - - 设置 `agents.list[].skills: []` 表示没有 Skills。 + - 默认情况下，省略 `agents.defaults.skills` 表示 Skills 不受限制。 + - 省略 `agents.list[].skills` 以继承默认值。 + - 将 `agents.list[].skills: []` 设为没有 Skills。 - 请参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config)，以及 [配置参考](/zh-CN/gateway/config-agents#agents-defaults-skills)。 - - 控制 Gateway 网关对看起来停滞的渠道执行重启的激进程度： + + 控制 Gateway 网关重启疑似停滞渠道的激进程度： ```json5 { @@ -269,15 +265,15 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 } ``` - - 设置 `gateway.channelHealthCheckMinutes: 0` 可全局禁用健康监控重启。 + - 将 `gateway.channelHealthCheckMinutes: 0` 设为全局禁用健康监控重启。 - `channelStaleEventThresholdMinutes` 应大于或等于检查间隔。 - - 使用 `channels..healthMonitor.enabled` 或 `channels..accounts..healthMonitor.enabled`，可在不禁用全局监控器的情况下，为某个渠道或账号禁用自动重启。 - - 请参阅[健康检查](/zh-CN/gateway/health)了解运维调试，并参阅[完整参考](/zh-CN/gateway/configuration-reference#gateway)查看所有字段。 + - 使用 `channels..healthMonitor.enabled` 或 `channels..accounts..healthMonitor.enabled`，可以在不禁用全局监控器的情况下，为某个渠道或账号禁用自动重启。 + - 请参阅[健康检查](/zh-CN/gateway/health)了解运维调试，并参阅[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。 - - 给本地客户端更多时间，在负载较高或低性能主机上完成认证前 WebSocket 握手： + + 在负载较高或低功耗主机上，为本地客户端提供更多时间完成认证前 WebSocket 握手： ```json5 { @@ -288,12 +284,12 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 ``` - 默认值为 `15000` 毫秒。 - - `OPENCLAW_HANDSHAKE_TIMEOUT_MS` 对一次性服务或 shell 覆盖仍然优先。 - - 优先修复启动/事件循环停顿；这个旋钮适用于健康但预热期间较慢的主机。 + - `OPENCLAW_HANDSHAKE_TIMEOUT_MS` 仍然优先用于一次性服务或 shell 覆盖。 + - 优先修复启动/事件循环停滞；此旋钮用于健康但预热期间较慢的主机。 - + 会话控制对话连续性和隔离： ```json5 @@ -316,12 +312,12 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 - `dmScope`：`main`（共享）| `per-peer` | `per-channel-peer` | `per-account-channel-peer` - `threadBindings`：线程绑定会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。 - - 查看[会话管理](/zh-CN/concepts/session)，了解作用域、身份关联和发送策略。 - - 查看[完整参考](/zh-CN/gateway/config-agents#session)，了解所有字段。 + - 请参阅[会话管理](/zh-CN/concepts/session)，了解作用域、身份链接和发送策略。 + - 请参阅[完整参考](/zh-CN/gateway/config-agents#session)，了解所有字段。 - + 在隔离的沙箱运行时中运行智能体会话： ```json5 @@ -337,13 +333,13 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 } ``` - 先构建镜像：`scripts/sandbox-setup.sh` + 请先构建镜像：`scripts/sandbox-setup.sh` - 查看[沙箱隔离](/zh-CN/gateway/sandboxing)获取完整指南，并查看[完整参考](/zh-CN/gateway/config-agents#agentsdefaultssandbox)了解所有选项。 + 请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)获取完整指南，并参阅[完整参考](/zh-CN/gateway/config-agents#agentsdefaultssandbox)了解所有选项。 - + 中继支持的推送在 `openclaw.json` 中配置。 在 Gateway 网关配置中设置： @@ -364,43 +360,43 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 } ``` - CLI 等效命令： + 等价的 CLI 命令： ```bash openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com ``` - 这会执行以下操作： + 它的作用： - 允许 Gateway 网关通过外部中继发送 `push.test`、唤醒提醒和重连唤醒。 - - 使用由已配对 iOS 应用转发、限定于注册范围的发送授权。Gateway 网关不需要部署范围的中继令牌。 + - 使用由已配对 iOS 应用转发的注册作用域发送授权。Gateway 网关不需要部署范围的中继令牌。 - 将每个中继支持的注册绑定到 iOS 应用配对的 Gateway 网关身份，因此另一个 Gateway 网关无法复用已存储的注册。 - 让本地/手动 iOS 构建继续使用直接 APNs。中继支持的发送仅适用于通过中继注册的官方分发构建。 - - 必须匹配内置到官方/TestFlight iOS 构建中的中继基础 URL，以便注册和发送流量到达同一个中继部署。 + - 必须匹配写入官方/TestFlight iOS 构建中的中继 base URL，以便注册和发送流量到达同一个中继部署。 端到端流程： - 1. 安装使用相同中继基础 URL 编译的官方/TestFlight iOS 构建。 + 1. 安装使用相同中继 base URL 编译的官方/TestFlight iOS 构建。 2. 在 Gateway 网关上配置 `gateway.push.apns.relay.baseUrl`。 - 3. 将 iOS 应用与 Gateway 网关配对，并让节点和操作员会话都连接。 - 4. iOS 应用获取 Gateway 网关身份，使用 App Attest 加应用收据向中继注册，然后将中继支持的 `push.apns.register` 负载发布到已配对的 Gateway 网关。 + 3. 将 iOS 应用与 Gateway 网关配对，并让节点会话和操作员会话都连接。 + 4. iOS 应用获取 Gateway 网关身份，使用 App Attest 加应用收据向中继注册，然后将中继支持的 `push.apns.register` 载荷发布到已配对的 Gateway 网关。 5. Gateway 网关存储中继句柄和发送授权，然后将它们用于 `push.test`、唤醒提醒和重连唤醒。 运维说明： - - 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接该应用，以便它发布绑定到该 Gateway 网关的新中继注册。 - - 如果你发布指向不同中继部署的新 iOS 构建，应用会刷新其缓存的中继注册，而不是复用旧的中继来源。 + - 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接应用，使其可以发布绑定到该 Gateway 网关的新中继注册。 + - 如果你发布的新 iOS 构建指向不同的中继部署，应用会刷新其缓存的中继注册，而不是复用旧的中继来源。 兼容性说明： - `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可作为临时环境变量覆盖项使用。 - - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍是仅限 loopback 的开发逃生口；不要在配置中持久化 HTTP 中继 URL。 + - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍是仅限 local loopback 的开发逃生口；不要在配置中持久保存 HTTP 中继 URL。 - 查看 [iOS 应用](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)了解端到端流程，并查看[身份验证与信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)了解中继安全模型。 + 请参阅 [iOS 应用](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)了解端到端流程，并参阅[身份验证和信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)了解中继安全模型。 - + ```json5 { agents: { @@ -414,14 +410,14 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 } ``` - - `every`：持续时间字符串（`30m`、`2h`）。设置为 `0m` 可禁用。 + - `every`：时长字符串（`30m`、`2h`）。设置为 `0m` 可禁用。 - `target`：`last` | `none` | ``（例如 `discord`、`matrix`、`telegram` 或 `whatsapp`） - - `directPolicy`：用于私信样式心跳目标的 `allow`（默认）或 `block` - - 查看[心跳](/zh-CN/gateway/heartbeat)获取完整指南。 + - `directPolicy`：用于私信风格心跳目标的 `allow`（默认）或 `block` + - 请参阅[心跳](/zh-CN/gateway/heartbeat)获取完整指南。 - + ```json5 { cron: { @@ -438,11 +434,11 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 - `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设置为 `false` 可禁用）。 - `runLog`：按大小和保留行数清理 `cron/runs/.jsonl`。 - - 查看 [Cron 作业](/zh-CN/automation/cron-jobs)了解功能概览和 CLI 示例。 + - 请参阅 [Cron 任务](/zh-CN/automation/cron-jobs)了解功能概览和 CLI 示例。 - + 在 Gateway 网关上启用 HTTP webhook 端点： ```json5 @@ -467,20 +463,20 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 ``` 安全说明： - - 将所有 hook/webhook 负载内容视为不受信任的输入。 - - 使用专用的 `hooks.token`；不要复用共享 Gateway 网关令牌。 - - Hook 认证仅支持请求头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串令牌会被拒绝。 - - `hooks.path` 不能是 `/`；请将 webhook 入口保持在专用子路径上，例如 `/hooks`。 - - 保持不安全内容绕过标志处于禁用状态（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`），除非正在进行严格限定范围的调试。 - - 如果启用 `hooks.allowRequestSessionKey`，还要设置 `hooks.allowedSessionKeyPrefixes` 来限定调用方选择的会话键。 - - 对于 hook 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如仅限消息发送，并尽可能加上沙箱隔离）。 + - 将所有 hook/webhook 载荷内容视为不可信输入。 + - 使用专用的 `hooks.token`；不要复用共享的 Gateway 网关令牌。 + - Hook 身份验证仅支持标头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串令牌会被拒绝。 + - `hooks.path` 不能是 `/`；请将 webhook 入口保留在专用子路径上，例如 `/hooks`。 + - 除非进行严格限定范围的调试，否则保持不安全内容绕过标志禁用（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`）。 + - 如果你启用 `hooks.allowRequestSessionKey`，也要设置 `hooks.allowedSessionKeyPrefixes` 以约束调用方选择的会话键。 + - 对于 hook 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如仅消息发送，并尽可能启用沙箱隔离）。 - 查看[完整参考](/zh-CN/gateway/configuration-reference#hooks)了解所有映射选项和 Gmail 集成。 + 请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)，了解所有映射选项和 Gmail 集成。 - - 运行多个隔离智能体，每个智能体拥有独立的工作区和会话： + + 使用独立工作区和会话运行多个隔离的智能体： ```json5 { @@ -497,12 +493,12 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 } ``` - 查看[多智能体](/zh-CN/concepts/multi-agent)和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)，了解绑定规则和每智能体访问配置文件。 + 请参阅 [Multi-Agent](/zh-CN/concepts/multi-agent) 和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)，了解绑定规则和每智能体访问配置文件。 - - 使用 `$include` 来组织大型配置： + + 使用 `$include` 组织大型配置： ```json5 // ~/.openclaw/openclaw.json @@ -517,12 +513,12 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 - **单个文件**：替换包含它的对象 - **文件数组**：按顺序深度合并（后者优先） - - **同级键**：在 include 后合并（覆盖已包含的值） - - **嵌套 include**：最多支持 10 层深度 + - **同级键**：在 include 之后合并（覆盖 include 的值） + - **嵌套 include**：最多支持 10 层 - **相对路径**：相对于执行 include 的文件解析 - - **OpenClaw 拥有的写入**：当写入只更改一个由单文件 include 支持的顶层区段时，例如 `plugins: { $include: "./plugins.json5" }`，OpenClaw 会更新该被包含文件，并保持 `openclaw.json` 不变 - - **不支持的透传写入**：root include、include 数组以及带同级覆盖的 include 会对 OpenClaw 拥有的写入失败关闭，而不是扁平化配置 - - **错误处理**：对缺失文件、解析错误和循环 include 提供清晰错误 + - **OpenClaw 拥有的写入**：当写入只更改一个顶层分区，且该分区由单文件 include 支持，例如 `plugins: { $include: "./plugins.json5" }`，OpenClaw 会更新该被 include 的文件，并保持 `openclaw.json` 不变 + - **不支持的透传写入**：根 include、include 数组以及带同级覆盖项的 include 会对 OpenClaw 拥有的写入以关闭方式失败，而不会扁平化配置 + - **错误处理**：对缺失文件、解析错误和循环 include 给出清晰错误 @@ -531,20 +527,20 @@ Gateway 网关会在每次成功启动后保留一份可信的最后已知良好 Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改，大多数设置无需手动重启。 -直接文件编辑在通过验证前会被视为不受信任。监视器会等待编辑器临时写入/重命名抖动稳定，读取最终文件，并通过恢复上一个已知良好配置来拒绝无效的外部编辑。OpenClaw 拥有的配置写入在写入前使用同一个 schema 门禁；破坏性覆盖（例如删除 `gateway.mode` 或将文件缩小超过一半）会被拒绝，并保存为 `.rejected.*` 以供检查。 +直接文件编辑在通过验证前会被视为不可信。监视器会等待编辑器临时写入/重命名抖动稳定，读取最终文件，并通过恢复最后已知良好配置来拒绝无效的外部编辑。OpenClaw 拥有的配置写入会在写入前使用相同的 schema 门禁；破坏性覆盖，例如删除 `gateway.mode` 或将文件缩小超过一半，会被拒绝并保存为 `.rejected.*` 以供检查。 插件本地验证失败是例外：如果所有问题都位于 `plugins.entries....` 下，重载会保留当前配置并报告插件问题，而不是恢复 `.last-good`。 -如果你在日志中看到 `Config auto-restored from last-known-good` 或 `config reload restored last-known-good config`，请检查 `openclaw.json` 旁边匹配的 `.clobbered.*` 文件，修复被拒绝的负载，然后运行 `openclaw config validate`。查看 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)获取恢复检查清单。 +如果你在日志中看到 `Config auto-restored from last-known-good` 或 `config reload restored last-known-good config`，请检查 `openclaw.json` 旁边匹配的 `.clobbered.*` 文件，修复被拒绝的载荷，然后运行 `openclaw config validate`。请参阅 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)获取恢复检查清单。 ### 重载模式 | 模式 | 行为 | | ---------------------- | --------------------------------------------------------------------------------------- | | **`hybrid`**（默认） | 立即热应用安全更改。对关键更改自动重启。 | -| **`hot`** | 仅热应用安全更改。需要重启时记录警告，由你处理。 | -| **`restart`** | 对任何配置更改都重启 Gateway 网关，无论是否安全。 | -| **`off`** | 禁用文件监视。更改会在下一次手动重启时生效。 | +| **`hot`** | 仅热应用安全更改。当需要重启时记录警告，由你处理。 | +| **`restart`** | 任何配置更改都会重启 Gateway 网关，无论是否安全。 | +| **`off`** | 禁用文件监视。更改会在下次手动重启时生效。 | ```json5 { @@ -556,17 +552,17 @@ Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改，大 ### 哪些会热应用，哪些需要重启 -大多数字段都可以无停机热应用。在 `hybrid` 模式下，需要重启的更改会自动处理。 +大多数字段会在不停机的情况下热应用。在 `hybrid` 模式下，需要重启的更改会自动处理。 -| 类别 | 字段 | 是否需要重启？ | +| 类别 | 字段 | 需要重启？ | | ------------------- | ----------------------------------------------------------------- | --------------- | -| 渠道 | `channels.*`、`web`（WhatsApp）— 所有内置和插件渠道 | 否 | +| 渠道 | `channels.*`、`web`（WhatsApp）——所有内置和插件渠道 | 否 | | 智能体和模型 | `agent`、`agents`、`models`、`routing` | 否 | | 自动化 | `hooks`、`cron`、`agent.heartbeat` | 否 | | 会话和消息 | `session`、`messages` | 否 | | 工具和媒体 | `tools`、`browser`、`skills`、`mcp`、`audio`、`talk` | 否 | | UI 和其他 | `ui`、`logging`、`identity`、`bindings` | 否 | -| Gateway 网关服务器 | `gateway.*`（端口、绑定、认证、tailscale、TLS、HTTP） | **是** | +| Gateway 网关服务器 | `gateway.*`（端口、绑定、身份验证、Tailscale、TLS、HTTP） | **是** | | 基础设施 | `discovery`、`canvasHost`、`plugins` | **是** | @@ -575,26 +571,27 @@ Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改，大 ### 重载规划 -OpenClaw 通过 `$include` 引用的源文件时，OpenClaw 会根据源文件编写时的布局来规划重新加载，而不是根据扁平化的内存视图。 -这样即使单个顶级区段位于自己的包含文件中，例如 -`plugins: { $include: "./plugins.json5" }`，热重载决策（热应用与重启）也保持可预测。如果源布局存在歧义，重新加载规划会保守失败。 +当你编辑通过 `$include` 引用的源文件时，OpenClaw 会从源文件编写时的布局来规划重载，而不是从扁平化的内存视图规划。 +即使单个顶层分区位于自己的 include 文件中，例如 +`plugins: { $include: "./plugins.json5" }`，这也能让热重载决策（热应用 vs 重启）保持可预测。 +如果源布局存在歧义，重载规划会以关闭方式失败。 ## 配置 RPC（程序化更新） -对于通过 Gateway 网关 API 写入配置的工具，优先使用此流程： +对于通过 Gateway 网关 API 写入配置的工具，首选以下流程： - `config.schema.lookup` 用于检查一个子树（浅层 schema 节点 + 子项摘要） -- `config.get` 用于获取当前快照以及 `hash` -- `config.patch` 用于部分更新（JSON 合并补丁：对象合并，`null` 删除，数组替换） +- `config.get` 用于获取当前快照和 `hash` +- `config.patch` 用于部分更新（JSON merge patch：对象合并，`null` 删除，数组替换） - 仅当你打算替换整个配置时才使用 `config.apply` -- `update.run` 用于显式自我更新并重启 +- `update.run` 用于显式自更新并重启 - `update.status` 用于检查最新的更新重启哨兵，并在重启后验证正在运行的版本 -智能体应将 `config.schema.lookup` 视为获取精确字段级文档和约束的第一站。当需要更广泛的配置映射、默认值或专用子系统参考链接时，使用 [配置参考](/zh-CN/gateway/configuration-reference)。 +智能体应将 `config.schema.lookup` 作为获取精确字段级文档和约束的第一站。当需要更广泛的配置映射、默认值或指向专用子系统参考的链接时，请使用 [配置参考](/zh-CN/gateway/configuration-reference)。 -控制平面写入（`config.apply`、`config.patch`、`update.run`）按每个 `deviceId+clientIp` 每 60 秒 3 个请求进行限速。重启请求会合并，然后在重启周期之间强制执行 30 秒冷却时间。 -`update.status` 是只读的，但作用域为管理员，因为重启哨兵可能包含更新步骤摘要和命令输出尾部。 +控制平面写入（`config.apply`、`config.patch`、`update.run`）按每个 `deviceId+clientIp` 每 60 秒 3 次请求进行速率限制。重启请求会合并，然后在重启周期之间强制执行 30 秒冷却时间。 +`update.status` 是只读的，但属于管理员范围，因为重启哨兵可能包含更新步骤摘要和命令输出尾部。 部分补丁示例： @@ -607,11 +604,11 @@ openclaw gateway call config.patch --params '{ }' ``` -`config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、`note` 和 `restartDelayMs`。当配置已存在时，这两个方法都需要 `baseHash`。 +`config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、`note` 和 `restartDelayMs`。当配置已存在时，两个方法都要求提供 `baseHash`。 ## 环境变量 -OpenClaw 会从父进程读取环境变量，并额外读取： +OpenClaw 会从父进程以及以下位置读取环境变量： - 当前工作目录中的 `.env`（如果存在） - `~/.openclaw/.env`（全局回退） @@ -627,8 +624,8 @@ OpenClaw 会从父进程读取环境变量，并额外读取： } ``` - - 如果启用且预期键名未设置，OpenClaw 会运行你的登录 shell，并只导入缺失的键： + + 如果启用且预期键名未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键： ```json5 { @@ -638,11 +635,11 @@ OpenClaw 会从父进程读取环境变量，并额外读取： } ``` -等效环境变量：`OPENCLAW_LOAD_SHELL_ENV=1` +环境变量等价项：`OPENCLAW_LOAD_SHELL_ENV=1` - - 使用 `${VAR_NAME}` 在任意配置字符串值中引用环境变量： + + 在任何配置字符串值中使用 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -654,14 +651,14 @@ OpenClaw 会从父进程读取环境变量，并额外读取： 规则： - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*` -- 缺失或为空的变量会在加载时抛出错误 +- 缺失/空变量会在加载时抛出错误 - 使用 `$${VAR}` 转义以输出字面量 -- 可在 `$include` 文件中使用 +- 可在 `$include` 文件内使用 - 内联替换：`"${BASE}/v1"` → `"https://api.example.com/v1"` - + 对于支持 SecretRef 对象的字段，你可以使用： ```json5 @@ -694,15 +691,15 @@ OpenClaw 会从父进程读取环境变量，并额外读取： } ``` -SecretRef 详细信息（包括用于 `env`/`file`/`exec` 的 `secrets.providers`）见 [Secrets 管理](/zh-CN/gateway/secrets)。 -支持的凭证路径列在 [SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface) 中。 +SecretRef 详情（包括用于 `env`/`file`/`exec` 的 `secrets.providers`）位于 [密钥管理](/zh-CN/gateway/secrets)。 +支持的凭据路径列在 [SecretRef 凭据表面](/zh-CN/reference/secretref-credential-surface) 中。 -完整优先级和来源见 [环境](/zh-CN/help/environment)。 +完整的优先级和来源请参见 [环境](/zh-CN/help/environment)。 ## 完整参考 -完整的逐字段参考见 **[配置参考](/zh-CN/gateway/configuration-reference)**。 +完整的逐字段参考，请参见 **[配置参考](/zh-CN/gateway/configuration-reference)**。 ---