diff --git a/docs/zh-CN/channels/groups.md b/docs/zh-CN/channels/groups.md index d7f0dcccd..c2b10f0b9 100644 --- a/docs/zh-CN/channels/groups.md +++ b/docs/zh-CN/channels/groups.md @@ -2,33 +2,33 @@ 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-30T14:53:52Z" + generated_at: "2026-04-30T14:57:26Z" model: gpt-5.5 provider: openai - source_hash: c06efdf5d44fa52bcb69444b43e8745a3791837a41899afc75399bfe058f75c3 + source_hash: ed9cba03cf4546a20d473e8095a54858530869b27f8934f2680e8dbe987dbf5e 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 分钟） -OpenClaw “存在”于你自己的消息账号中。没有单独的 WhatsApp bot 用户。如果**你**在某个群组中，OpenClaw 就能看到该群组并在那里回复。 +OpenClaw “存在于”你自己的消息账号中。没有单独的 WhatsApp bot 用户。如果**你**在某个群组中，OpenClaw 就能看到该群组并在那里回复。 默认行为： - 群组受限制（`groupPolicy: "allowlist"`）。 -- 回复需要提及，除非你明确禁用提及门控。 -- 群组/渠道中的普通最终回复默认是私密的。可见的房间输出使用 `message` 工具。 +- 除非你明确禁用提及门控，否则回复需要提及。 +- 群组/渠道中的普通最终回复默认是私有的。可见的房间输出使用 `message` 工具。 换句话说：允许列表中的发送者可以通过提及 OpenClaw 来触发它。 -**太长不读** +**太长不看** - **私信访问**由 `*.allowFrom` 控制。 - **群组访问**由 `*.groupPolicy` + 允许列表（`*.groups`、`*.groupAllowFrom`）控制。 @@ -48,13 +48,13 @@ otherwise -> reply ## 可见回复 对于群组/渠道房间，OpenClaw 默认使用 `messages.groupChat.visibleReplies: "message_tool"`。 -这意味着智能体仍会处理该轮对话，并且可以更新记忆/会话状态，但它的普通最终答案不会自动发布回房间。要公开发言，智能体会使用 `message(action=send)`。 +这意味着智能体仍会处理该轮次，并且可以更新记忆/会话状态，但它的普通最终答案不会自动发回房间。要可见地发言，智能体会使用 `message(action=send)`。 对于直接聊天和任何其他来源轮次，使用 `messages.visibleReplies: "message_tool"` 可在全局应用相同的仅工具可见回复行为。`messages.groupChat.visibleReplies` 仍然是针对群组/渠道房间的更具体覆盖项。 -这取代了旧模式：强制模型在大多数潜伏模式轮次中回答 `NO_REPLY`。在仅工具模式下，不产生任何可见输出就只是意味着不调用消息工具。 +这取代了旧模式：强制模型在大多数潜伏模式轮次中回答 `NO_REPLY`。在仅工具模式中，不产生任何可见输出只意味着不调用消息工具。 -当智能体在仅工具模式下工作时，仍会发送输入状态指示器。对于这些轮次，默认群组输入状态模式会从 “message” 升级为 “instant”，因为在智能体决定是否调用消息工具之前，可能永远不会有普通助手消息文本。显式输入状态模式配置仍然优先。 +当智能体在仅工具模式中工作时，仍会发送输入状态提示。对于这些轮次，默认群组输入状态模式会从 “message” 升级为 “instant”，因为在智能体决定是否调用消息工具之前，可能永远不会有普通的助手消息文本。显式配置的输入状态模式仍然优先生效。 要恢复群组/渠道房间的旧版自动最终回复： @@ -80,29 +80,29 @@ otherwise -> reply } ``` -原生斜杠命令（Discord、Telegram 以及其他支持原生命令的平台）会绕过 `visibleReplies: "message_tool"`，并始终可见回复，以便渠道原生命令 UI 获得它预期的响应。这仅适用于已验证的原生命令轮次；文本输入的 `/...` 命令和普通聊天轮次仍遵循配置的群组默认值。 +原生斜杠命令（Discord、Telegram 以及其他支持原生命令的平台）会绕过 `visibleReplies: "message_tool"`，并始终可见地回复，以便渠道原生命令 UI 获得预期响应。这仅适用于已验证的原生命令轮次；文本输入的 `/...` 命令和普通聊天轮次仍遵循配置的群组默认值。 ## 上下文可见性和允许列表 -群组安全涉及两种不同控制： +群组安全涉及两种不同的控制： -- **触发授权**：谁可以触发智能体（`groupPolicy`、`groups`、`groupAllowFrom`、渠道特定允许列表）。 +- **触发授权**：谁可以触发智能体（`groupPolicy`、`groups`、`groupAllowFrom`、渠道专用允许列表）。 - **上下文可见性**：哪些补充上下文会注入到模型中（回复文本、引用、线程历史、转发元数据）。 -默认情况下，OpenClaw 优先保持正常聊天行为，并基本按接收状态保留上下文。这意味着允许列表主要决定谁可以触发操作，而不是为每个引用片段或历史片段提供通用脱敏边界。 +默认情况下，OpenClaw 优先考虑正常聊天行为，并尽量按接收原样保留上下文。这意味着允许列表主要决定谁可以触发操作，而不是作为每段引用或历史片段的通用脱敏边界。 - - 一些渠道已经在特定路径中对补充上下文应用基于发送者的过滤（例如 Slack 线程种子、Matrix 回复/线程查找）。 - - 其他渠道仍然按接收状态传递引用/回复/转发上下文。 + - 一些渠道已经在特定路径中对补充上下文应用基于发送者的过滤（例如 Slack 线程播种、Matrix 回复/线程查找）。 + - 其他渠道仍会按接收原样传递引用/回复/转发上下文。 - - `contextVisibility: "all"`（默认）保留当前按接收状态处理的行为。 - - `contextVisibility: "allowlist"` 会将补充上下文过滤为允许列表中的发送者。 - - `contextVisibility: "allowlist_quote"` 是 `allowlist` 加上一个显式引用/回复例外。 + - `contextVisibility: "all"`（默认）保持当前按接收原样的行为。 + - `contextVisibility: "allowlist"` 将补充上下文过滤为允许列表中的发送者。 + - `contextVisibility: "allowlist_quote"` 是 `allowlist` 加上一个显式的引用/回复例外。 - 在此加固模型在各渠道中一致实现之前，预计不同平台会有差异。 + 在这个加固模型跨渠道一致实现之前，预期不同平台会存在差异。 @@ -113,37 +113,37 @@ otherwise -> reply | 目标 | 要设置的内容 | | -------------------------------------------- | ---------------------------------------------------------- | -| 允许所有群组，但只在 @提及 时回复 | `groups: { "*": { requireMention: true } }` | +| 允许所有群组，但只在 @提及时回复 | `groups: { "*": { requireMention: true } }` | | 禁用所有群组回复 | `groupPolicy: "disabled"` | -| 仅特定群组 | `groups: { "": { ... } }`（没有 `"*"` 键） | -| 群组中只有你可以触发 | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | +| 仅允许特定群组 | `groups: { "": { ... } }`（没有 `"*"` 键） | +| 只有你可以在群组中触发 | `groupPolicy: "allowlist"`、`groupAllowFrom: ["+1555..."]` | ## 会话键 - 群组会话使用 `agent:::group:` 会话键（房间/渠道使用 `agent:::channel:`）。 -- Telegram 论坛话题会向群组 id 添加 `:topic:`，因此每个话题都有自己的会话。 -- 直接聊天使用主会话（如果已配置，也可按发送者区分）。 +- Telegram 论坛话题会向群组 ID 添加 `:topic:`，因此每个话题都有自己的会话。 +- 直接聊天使用主会话（如果已配置，也可以按发送者使用单独会话）。 - 群组会话会跳过 Heartbeat。 ## 模式：个人私信 + 公开群组（单智能体） -可以，如果你的“个人”流量是**私信**，而你的“公开”流量是**群组**，这种方式效果很好。 +可以。如果你的“个人”流量是**私信**，而“公开”流量是**群组**，这会很好用。 -原因：在单智能体模式下，私信通常会进入**主**会话键（`agent:main:main`），而群组始终使用**非主**会话键（`agent:main::group:`）。如果你启用沙箱隔离并设置 `mode: "non-main"`，这些群组会话会在配置的沙箱后端中运行，而你的主私信会话仍保留在主机上。如果你未选择后端，默认后端是 Docker。 +原因：在单智能体模式下，私信通常会落入**主**会话键（`agent:main:main`），而群组始终使用**非主**会话键（`agent:main::group:`）。如果你启用了 `mode: "non-main"` 的沙箱隔离，这些群组会话会在配置的沙箱后端中运行，而你的主私信会话仍留在主机上。如果你没有选择后端，Docker 是默认后端。 -这为你提供一个智能体“大脑”（共享工作区 + 记忆），但有两种执行姿态： +这会给你一个智能体“大脑”（共享工作区 + 记忆），但有两种执行姿态： - **私信**：完整工具（主机） - **群组**：沙箱 + 受限工具 -如果你需要真正分离的工作区/人格（“个人”和“公开”绝不能混合），请使用第二个智能体 + 绑定。参见[多智能体路由](/zh-CN/concepts/multi-agent)。 +如果你需要真正分离的工作区/角色（“个人”和“公开”绝不能混用），请使用第二个智能体 + 绑定。参见[多智能体路由](/zh-CN/concepts/multi-agent)。 - + ```json5 { agents: { @@ -168,7 +168,7 @@ otherwise -> reply ``` - 想要“群组只能看到文件夹 X”，而不是“没有主机访问权限”？保留 `workspaceAccess: "none"`，并仅将允许列表中的路径挂载进沙箱： + 想让“群组只能看到文件夹 X”，而不是“不能访问主机”？保留 `workspaceAccess: "none"`，并只将允许列表中的路径挂载到沙箱中： ```json5 { @@ -196,7 +196,7 @@ otherwise -> reply 相关： - 配置键和默认值：[Gateway 网关配置](/zh-CN/gateway/config-agents#agentsdefaultssandbox) -- 调试工具被阻止的原因：[沙箱与工具策略与提权](/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) ## 显示标签 @@ -253,25 +253,25 @@ otherwise -> reply } ``` -| 策略 | 行为 | +| 策略 | 行为 | | ------------- | ------------------------------------------------------------ | -| `"open"` | 群组绕过允许列表；提及门控仍然适用。 | -| `"disabled"` | 完全阻止所有群组消息。 | -| `"allowlist"` | 仅允许匹配已配置允许列表的群组/房间。 | +| `"open"` | 群组绕过允许列表；提及门控仍然适用。 | +| `"disabled"` | 完全阻止所有群组消息。 | +| `"allowlist"` | 只允许匹配已配置允许列表的群组/房间。 | - - `groupPolicy` 独立于提及门控（后者需要 @提及）。 + - `groupPolicy` 与提及门控（需要 @提及）是分开的。 - WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：使用 `groupAllowFrom`（回退：显式 `allowFrom`）。 - - Signal：`groupAllowFrom` 可以匹配入站 Signal 群组 id，也可以匹配发送者电话/UUID。 - - 私信配对批准（`*-allowFrom` 存储条目）仅适用于私信访问；群组发送者授权仍然明确使用群组允许列表。 + - Signal：`groupAllowFrom` 可以匹配入站 Signal 群组 ID 或发送者电话/UUID。 + - 私信配对审批（`*-allowFrom` 存储条目）仅适用于私信访问；群组发送者授权仍显式使用群组允许列表。 - Discord：允许列表使用 `channels.discord.guilds..channels`。 - Slack：允许列表使用 `channels.slack.channels`。 - - Matrix：允许列表使用 `channels.matrix.groups`。优先使用房间 ID 或别名；已加入房间的名称查找是尽力而为，无法解析的名称会在运行时被忽略。使用 `channels.matrix.groupAllowFrom` 限制发送者；也支持按房间配置的 `users` 允许列表。 + - 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`。 + - 默认值为 `groupPolicy: "allowlist"`；如果你的群组允许列表为空，群组消息会被阻止。 + - 运行时安全：当提供商块完全缺失（不存在 `channels.`）时，群组策略会回退到故障关闭模式（通常是 `allowlist`），而不是继承 `channels.defaults.groupPolicy`。 @@ -283,7 +283,7 @@ otherwise -> reply `groupPolicy`（open/disabled/allowlist）。 - 群组允许列表（`*.groups`、`*.groupAllowFrom`、渠道特定允许列表）。 + 群组允许列表（`*.groups`、`*.groupAllowFrom`、渠道专用允许列表）。 提及门控（`requireMention`、`/activation`）。 @@ -292,9 +292,9 @@ otherwise -> reply ## 提及门控（默认） -群组消息需要提及，除非按群组覆盖。默认值位于每个子系统的 `*.groups."*"` 下。 +除非按群组覆盖，否则群组消息需要提及。默认值按子系统位于 `*.groups."*"` 下。 -回复机器人消息在渠道支持回复元数据时会算作隐式提及。在暴露引用元数据的渠道上，引用机器人消息也可以算作隐式提及。当前内置案例包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。 +回复机器人消息在渠道支持回复元数据时会计为隐式提及。引用机器人消息在暴露引用元数据的渠道上也可计为隐式提及。当前内置案例包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。 ```json5 { @@ -335,13 +335,14 @@ otherwise -> reply - `mentionPatterns` 是大小写不敏感的安全正则表达式模式；无效模式和不安全的嵌套重复形式会被忽略。 - - 提供显式提及的表面仍会通过；模式是回退方案。 - - 按智能体覆盖：`agents.list[].groupChat.mentionPatterns`（当多个智能体共享一个群组时很有用）。 - - 仅当可以进行提及检测时（配置了原生提及或 `mentionPatterns`），才会强制执行提及门控。 - - 群聊提示上下文会在每一轮携带已解析的静默回复指令；工作区文件不应重复 `NO_REPLY` 机制。 - - 允许静默回复的群组会将干净的空模型轮次或仅推理模型轮次视为静默，等同于 `NO_REPLY`。私聊只有在明确允许直接静默回复时才会这样做；否则空回复仍会被视为失败的智能体轮次。 - - Discord 默认值位于 `channels.discord.guilds."*"`（可按 guild/渠道覆盖）。 - - 群组历史上下文会在各渠道中统一包装，并且是**仅待处理**（因提及门控被跳过的消息）；使用 `messages.groupChat.historyLimit` 设置全局默认值，并使用 `channels..historyLimit`（或 `channels..accounts.*.historyLimit`）进行覆盖。设为 `0` 可禁用。 + - 提供显式提及的界面仍会通过；模式是一种回退机制。 + - 按智能体覆盖：`agents.list[].groupChat.mentionPatterns`（当多个智能体共享同一个群组时很有用）。 + - 只有在可以进行提及检测时，才会强制执行提及门控（配置了原生提及或 `mentionPatterns`）。 + - 将某个群组或发送者加入允许列表不会禁用提及门控；当所有消息都应触发时，请将该群组的 `requireMention` 设置为 `false`。 + - 群聊提示词上下文会在每轮携带解析后的静默回复指令；工作区文件不应重复 `NO_REPLY` 机制。 + - 允许静默回复的群组会将干净的空模型轮次或仅推理的模型轮次视为静默，等同于 `NO_REPLY`。只有在明确允许直接静默回复时，直接聊天才会执行相同行为；否则空回复仍会保留为失败的智能体轮次。 + - Discord 默认值位于 `channels.discord.guilds."*"`（可按服务器/渠道覆盖）。 + - 群组历史上下文在各渠道中以统一方式包装，并且是**仅待处理**的（因提及门控而跳过的消息）；使用 `messages.groupChat.historyLimit` 设置全局默认值，使用 `channels..historyLimit`（或 `channels..accounts.*.historyLimit`）进行覆盖。设置为 `0` 可禁用。 @@ -351,9 +352,9 @@ otherwise -> reply 某些渠道配置支持限制**特定群组/房间/渠道内**可用的工具。 - `tools`：允许/拒绝整个群组的工具。 -- `toolsBySender`：群组内按发送者覆盖。使用显式键前缀：`id:`、`e164:`、`username:`、`name:` 和 `"*"` 通配符。旧版无前缀键仍会被接受，并且仅按 `id:` 匹配。 +- `toolsBySender`：群组内按发送者覆盖。使用显式键前缀：`id:`、`e164:`、`username:`、`name:` 和 `"*"` 通配符。旧版无前缀键仍被接受，并且仅按 `id:` 匹配。 -解析顺序（最具体者优先）： +解析顺序（最具体的优先）： @@ -363,10 +364,10 @@ otherwise -> reply 群组/渠道 `tools`。 - 默认 (`"*"`) `toolsBySender` 匹配。 + 默认（`"*"`）`toolsBySender` 匹配。 - 默认 (`"*"`) `tools`。 + 默认（`"*"`）`tools`。 @@ -396,10 +397,10 @@ otherwise -> reply ## 群组允许列表 -配置 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 后，其键会作为群组允许列表。使用 `"*"` 可允许所有群组，同时仍设置默认提及行为。 +配置 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，这些键会作为群组允许列表。使用 `"*"` 可允许所有群组，同时仍设置默认提及行为。 -常见混淆：私信配对批准并不等同于群组授权。对于支持私信配对的渠道，配对存储只会解锁私信。群组命令仍然需要来自配置允许列表的显式群组发送者授权，例如 `groupAllowFrom` 或该渠道的文档化配置回退。 +常见混淆：私信配对批准并不等同于群组授权。对于支持私信配对的渠道，配对存储只会解锁私信。群组命令仍需要来自配置允许列表（如 `groupAllowFrom`）的显式群组发送者授权，或该渠道记录的配置回退。 常见意图（复制/粘贴）： @@ -459,39 +460,39 @@ otherwise -> reply - `/activation mention` - `/activation always` -所有者由 `channels.whatsapp.allowFrom` 确定（未设置时使用机器人的自身 E.164）。将命令作为独立消息发送。其他表面目前会忽略 `/activation`。 +所有者由 `channels.whatsapp.allowFrom` 确定（未设置时使用机器人的自有 E.164）。将命令作为独立消息发送。其他界面目前会忽略 `/activation`。 ## 上下文字段 -群组入站载荷会设置： +群组入站负载会设置： - `ChatType=group` - `GroupSubject`（如果已知） - `GroupMembers`（如果已知） - `WasMentioned`（提及门控结果） -- Telegram 论坛主题还包括 `MessageThreadId` 和 `IsForum`。 +- Telegram 论坛主题还包含 `MessageThreadId` 和 `IsForum`。 渠道特定说明： -- BlueBubbles 可以选择在填充 `GroupMembers` 之前，从本地通讯录数据库补充未命名的 macOS 群组参与者信息。此功能默认关闭，并且只会在正常群组门控通过后运行。 +- BlueBubbles 可以选择在填充 `GroupMembers` 之前，从本地通讯录数据库补充未命名的 macOS 群组参与者。此功能默认关闭，并且仅在正常群组门控通过后运行。 -智能体系统提示会在新群组会话的第一轮包含群组介绍。它会提醒模型像人类一样回复，避免使用 Markdown 表格，尽量减少空行并遵循正常聊天间距，且避免输入字面量 `\n` 序列。渠道来源的群组名称和参与者标签会渲染为围栏式不受信任元数据，而不是内联系统指令。 +智能体系统提示词会在新群组会话的第一轮包含群组介绍。它会提醒模型像人类一样回复，避免 Markdown 表格，尽量减少空行并遵循正常聊天间距，并避免输入字面量 `\n` 序列。来自渠道的群组名称和参与者标签会渲染为围栏包裹的不受信任元数据，而不是内联系统指令。 ## iMessage 细节 -- 路由或加入允许列表时优先使用 `chat_id:`。 +- 路由或加入允许列表时，优先使用 `chat_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) diff --git a/docs/zh-CN/channels/signal.md b/docs/zh-CN/channels/signal.md index 9df5ffceb..c7568f7a8 100644 --- a/docs/zh-CN/channels/signal.md +++ b/docs/zh-CN/channels/signal.md @@ -2,13 +2,13 @@ read_when: - 设置 Signal 支持 - 调试 Signal 发送/接收 -summary: 通过 signal-cli（JSON-RPC + SSE）支持 Signal、设置路径和号码模型 +summary: 通过 signal-cli（JSON-RPC + SSE）提供 Signal 支持、设置路径和号码模型 title: Signal x-i18n: - generated_at: "2026-04-30T14:53:52Z" + generated_at: "2026-04-30T14:57:29Z" model: gpt-5.5 provider: openai - source_hash: 244a171e969b210b58cd7b5042eb29b167473af6bee979910ba705d8d2f8283a + source_hash: d5f79b34b85b0d963373026d33b066d7865282e9a3619bddd334e67de30940d6 source_path: channels/signal.md workflow: 16 --- @@ -20,15 +20,15 @@ Status：外部 CLI 集成。Gateway 网关通过 HTTP JSON-RPC + SSE 与 `signa - 你的服务器上已安装 OpenClaw（下面的 Linux 流程已在 Ubuntu 24 上测试）。 - 运行 Gateway 网关的主机上可用 `signal-cli`。 - 一个可以接收一次验证短信的电话号码（用于短信注册路径）。 -- 注册期间可通过浏览器访问 Signal captcha（`signalcaptchas.org`）。 +- 注册期间可在浏览器中访问 Signal 验证码（`signalcaptchas.org`）。 -## 快速设置（新手） +## 快速设置（初学者） 1. 为机器人使用一个**单独的 Signal 号码**（推荐）。 2. 安装 `signal-cli`（如果使用 JVM 构建版本，则需要 Java）。 -3. 选择一种设置路径： - - **路径 A（QR 链接）：** `signal-cli link -n "OpenClaw"`，然后用 Signal 扫描。 - - **路径 B（短信注册）：** 使用 captcha + 短信验证注册一个专用号码。 +3. 选择一个设置路径： + - **路径 A（QR 绑定）：** `signal-cli link -n "OpenClaw"`，然后用 Signal 扫描。 + - **路径 B（短信注册）：** 使用验证码 + 短信验证注册一个专用号码。 4. 配置 OpenClaw 并重启 Gateway 网关。 5. 发送第一条私信并批准配对（`openclaw pairing approve signal `）。 @@ -50,18 +50,18 @@ Status：外部 CLI 集成。Gateway 网关通过 HTTP JSON-RPC + SSE 与 `signa 字段参考： -| 字段 | 描述 | -| ----------- | --------------------------------------------------- | -| `account` | E.164 格式的机器人电话号码（`+15551234567`） | -| `cliPath` | `signal-cli` 的路径（若在 `PATH` 上则为 `signal-cli`） | -| `dmPolicy` | 私信访问策略（推荐 `pairing`） | -| `allowFrom` | 允许发送私信的电话号码或 `uuid:` 值 | +| 字段 | 说明 | +| ----------- | ------------------------------------------------- | +| `account` | E.164 格式的机器人电话号码（`+15551234567`） | +| `cliPath` | `signal-cli` 的路径（在 `PATH` 中则为 `signal-cli`） | +| `dmPolicy` | 私信访问策略（推荐 `pairing`） | +| `allowFrom` | 允许发送私信的电话号码或 `uuid:` 值 | ## 它是什么 - 通过 `signal-cli` 实现的 Signal 渠道（不是嵌入式 libsignal）。 -- 确定性路由：回复始终返回 Signal。 -- 私信共享智能体的主会话；群组是隔离的（`agent::signal:group:`）。 +- 确定性路由：回复始终回到 Signal。 +- 私信共享智能体的主会话；群组会隔离（`agent::signal:group:`）。 ## 配置写入 @@ -77,14 +77,14 @@ Status：外部 CLI 集成。Gateway 网关通过 HTTP JSON-RPC + SSE 与 `signa ## 号码模型（重要） -- Gateway 网关连接到一个 **Signal 设备**（即 `signal-cli` 账号）。 -- 如果你在**你的个人 Signal 账号**上运行机器人，它会忽略你自己的消息（循环保护）。 -- 对于“我给机器人发短信，它会回复”的场景，请使用一个**单独的机器人号码**。 +- Gateway 网关连接到一个 **Signal 设备**（`signal-cli` 账户）。 +- 如果你在**自己的个人 Signal 账户**上运行机器人，它会忽略你自己的消息（循环保护）。 +- 如果想实现“我给机器人发短信，它会回复”，请使用一个**单独的机器人号码**。 -## 设置路径 A：链接现有 Signal 账号（QR） +## 设置路径 A：绑定现有 Signal 账户（QR） 1. 安装 `signal-cli`（JVM 或原生构建版本）。 -2. 链接一个机器人账号： +2. 绑定机器人账户： - `signal-cli link -n "OpenClaw"`，然后在 Signal 中扫描 QR。 3. 配置 Signal 并启动 Gateway 网关。 @@ -104,14 +104,14 @@ Status：外部 CLI 集成。Gateway 网关通过 HTTP JSON-RPC + SSE 与 `signa } ``` -多账号支持：使用 `channels.signal.accounts`，并为每个账号提供配置和可选的 `name`。共享模式见 [`gateway/configuration`](/zh-CN/gateway/config-channels#multi-account-all-channels)。 +多账户支持：使用 `channels.signal.accounts` 并为每个账户设置配置和可选的 `name`。参见 [`gateway/configuration`](/zh-CN/gateway/config-channels#multi-account-all-channels) 了解共享模式。 ## 设置路径 B：注册专用机器人号码（短信，Linux） -当你想使用专用机器人号码，而不是链接现有 Signal 应用账号时，请使用此路径。 +当你想要一个专用机器人号码，而不是绑定现有 Signal 应用账户时，请使用此路径。 -1. 获取一个可以接收短信的号码（或为固定电话使用语音验证）。 - - 使用专用机器人号码，避免账号/会话冲突。 +1. 获取一个可以接收短信的号码（固定电话可使用语音验证）。 + - 使用专用机器人号码以避免账户/会话冲突。 2. 在 Gateway 网关主机上安装 `signal-cli`： ```bash @@ -123,7 +123,7 @@ signal-cli --version ``` 如果使用 JVM 构建版本（`signal-cli-${VERSION}.tar.gz`），请先安装 JRE 25+。 -保持 `signal-cli` 更新；上游说明旧版本可能会随着 Signal 服务器 API 变化而失效。 +保持 `signal-cli` 更新；上游说明指出，旧版本可能会因 Signal 服务器 API 变化而失效。 3. 注册并验证号码： @@ -131,12 +131,12 @@ signal-cli --version signal-cli -a + register ``` -如果需要 captcha： +如果需要验证码： 1. 打开 `https://signalcaptchas.org/registration/generate.html`。 -2. 完成 captcha，从 “Open Signal” 复制 `signalcaptcha://...` 链接目标。 -3. 尽可能从与浏览器会话相同的外部 IP 运行。 -4. 立即再次运行注册（captcha 令牌很快过期）： +2. 完成验证码，从 “Open Signal” 复制 `signalcaptcha://...` 链接目标。 +3. 可行时，从与浏览器会话相同的外部 IP 运行。 +4. 立即再次运行注册（验证码令牌很快过期）： ```bash signal-cli -a + register --captcha '' @@ -157,21 +157,21 @@ openclaw channels status --probe 5. 配对你的私信发送方： - 向机器人号码发送任意消息。 - 在服务器上批准代码：`openclaw pairing approve signal `。 - - 在你的手机上将机器人号码保存为联系人，以避免出现 “Unknown contact”。 + - 将机器人号码保存为手机联系人，以避免显示 “Unknown contact”。 -使用 `signal-cli` 注册电话号码账号可能会使该号码的主 Signal 应用会话失去授权。优先使用专用机器人号码；如果需要保留现有手机应用设置，请使用 QR 链接模式。 +使用 `signal-cli` 注册电话号码账户可能会使该号码的主 Signal 应用会话取消认证。建议使用专用机器人号码；如果需要保留现有手机应用设置，请使用 QR 绑定模式。 上游参考： - `signal-cli` README：`https://github.com/AsamK/signal-cli` -- Captcha 流程：`https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha` -- 链接流程：`https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)` +- 验证码流程：`https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha` +- 绑定流程：`https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)` ## 外部守护进程模式（httpUrl） -如果你想自行管理 `signal-cli`（JVM 冷启动较慢、容器初始化或共享 CPU），请单独运行守护进程，并将 OpenClaw 指向它： +如果你想自行管理 `signal-cli`（JVM 冷启动慢、容器初始化或共享 CPU），请单独运行守护进程，并让 OpenClaw 指向它： ```json5 { @@ -184,56 +184,57 @@ openclaw channels status --probe } ``` -这会跳过 OpenClaw 内部的自动生成和启动等待。自动生成时如果启动较慢，请设置 `channels.signal.startupTimeoutMs`。 +这会跳过 OpenClaw 内部的自动派生进程和启动等待。自动派生进程启动较慢时，请设置 `channels.signal.startupTimeoutMs`。 ## 访问控制（私信 + 群组） 私信： -- 默认：`channels.signal.dmPolicy = "pairing"`。 +- 默认值：`channels.signal.dmPolicy = "pairing"`。 - 未知发送方会收到配对代码；批准前消息会被忽略（代码 1 小时后过期）。 - 通过以下方式批准： - `openclaw pairing list signal` - `openclaw pairing approve signal ` - 配对是 Signal 私信的默认令牌交换方式。详情：[配对](/zh-CN/channels/pairing) -- 仅 UUID 的发送方（来自 `sourceUuid`）会在 `channels.signal.allowFrom` 中存储为 `uuid:`。 +- 仅 UUID 发送方（来自 `sourceUuid`）会以 `uuid:` 存储在 `channels.signal.allowFrom` 中。 群组： - `channels.signal.groupPolicy = open | allowlist | disabled`。 -- 当设置为 `allowlist` 时，`channels.signal.groupAllowFrom` 控制哪些群组或发送方可以触发群组回复；条目可以是 Signal 群组 ID（原始值、`group:` 或 `signal:group:`）、发送方电话号码，或 `uuid:` 值。 +- 当设置 `allowlist` 时，`channels.signal.groupAllowFrom` 控制哪些群组或发送方可以触发群组回复；条目可以是 Signal 群组 ID（原始值、`group:` 或 `signal:group:`）、发送方电话号码或 `uuid:` 值。 - `channels.signal.groups["" | "*"]` 可以通过 `requireMention`、`tools` 和 `toolsBySender` 覆盖群组行为。 -- 在多账号设置中，使用 `channels.signal.accounts..groups` 设置每账号覆盖项。 -- 运行时说明：如果完全缺少 `channels.signal`，运行时会回退到 `groupPolicy="allowlist"` 来进行群组检查（即使已设置 `channels.defaults.groupPolicy`）。 +- 在多账户设置中，使用 `channels.signal.accounts..groups` 进行单账户覆盖。 +- 将 Signal 群组加入允许列表不会禁用提及门控。要处理允许列表群组中的每条消息，请设置 `channels.signal.groups[""].requireMention=false`，或使用 `"*"` 群组默认值。 +- 运行时注意事项：如果完全缺少 `channels.signal`，运行时会回退到 `groupPolicy="allowlist"` 进行群组检查（即使已设置 `channels.defaults.groupPolicy`）。 -## 工作原理（行为） +## 工作方式（行为） - `signal-cli` 作为守护进程运行；Gateway 网关通过 SSE 读取事件。 -- 入站消息会规范化为共享渠道信封。 -- 回复始终路由回相同的号码或群组。 +- 入站消息会被规范化为共享渠道信封。 +- 回复始终路由回相同号码或群组。 ## 媒体 + 限制 - 出站文本会按 `channels.signal.textChunkLimit` 分块（默认 4000）。 -- 可选按换行分块：设置 `channels.signal.chunkMode="newline"`，在按长度分块前先按空行（段落边界）拆分。 +- 可选换行分块：设置 `channels.signal.chunkMode="newline"`，先按空行（段落边界）拆分，再按长度分块。 - 支持附件（从 `signal-cli` 获取 base64）。 -- 当缺少 `contentType` 时，语音备注附件会使用 `signal-cli` 文件名作为 MIME 后备，因此音频转写仍可分类 AAC 语音备忘。 +- 当缺少 `contentType` 时，语音备注附件会使用 `signal-cli` 文件名作为 MIME 回退，因此音频转录仍可分类 AAC 语音备忘录。 - 默认媒体上限：`channels.signal.mediaMaxMb`（默认 8）。 -- 使用 `channels.signal.ignoreAttachments` 跳过媒体下载。 +- 使用 `channels.signal.ignoreAttachments` 跳过下载媒体。 - 群组历史上下文使用 `channels.signal.historyLimit`（或 `channels.signal.accounts.*.historyLimit`），并回退到 `messages.groupChat.historyLimit`。设置为 `0` 可禁用（默认 50）。 ## 正在输入 + 已读回执 - **正在输入指示器**：OpenClaw 通过 `signal-cli sendTyping` 发送正在输入信号，并在回复运行期间刷新。 -- **已读回执**：当 `channels.signal.sendReadReceipts` 为 true 时，OpenClaw 会转发允许的私信的已读回执。 -- Signal-cli 不会暴露群组的已读回执。 +- **已读回执**：当 `channels.signal.sendReadReceipts` 为 true 时，OpenClaw 会为允许的私信转发已读回执。 +- Signal-cli 不会公开群组的已读回执。 -## Reactions（消息工具） +## 反应（消息工具） - 使用 `message action=react` 并设置 `channel=signal`。 - 目标：发送方 E.164 或 UUID（使用配对输出中的 `uuid:`；裸 UUID 也可用）。 -- `messageId` 是你要回应的消息的 Signal 时间戳。 -- 群组 reactions 需要 `targetAuthor` 或 `targetAuthorUuid`。 +- `messageId` 是你要反应的消息的 Signal 时间戳。 +- 群组反应需要 `targetAuthor` 或 `targetAuthorUuid`。 示例： @@ -245,22 +246,22 @@ message action=react channel=signal target=signal:group: targetAuthor=u 配置： -- `channels.signal.actions.reactions`：启用/禁用 reaction 操作（默认 true）。 +- `channels.signal.actions.reactions`：启用/禁用反应操作（默认 true）。 - `channels.signal.reactionLevel`：`off | ack | minimal | extensive`。 - - `off`/`ack` 会禁用智能体 reactions（消息工具 `react` 会报错）。 - - `minimal`/`extensive` 会启用智能体 reactions 并设置引导级别。 -- 每账号覆盖项：`channels.signal.accounts..actions.reactions`、`channels.signal.accounts..reactionLevel`。 + - `off`/`ack` 禁用智能体反应（消息工具 `react` 会报错）。 + - `minimal`/`extensive` 启用智能体反应并设置指导级别。 +- 单账户覆盖：`channels.signal.accounts..actions.reactions`、`channels.signal.accounts..reactionLevel`。 -## 投递目标（CLI/cron） +## 发送目标（CLI/cron） - 私信：`signal:+15551234567`（或普通 E.164）。 - UUID 私信：`uuid:`（或裸 UUID）。 - 群组：`signal:group:`。 -- 用户名：`username:`（如果你的 Signal 账号支持）。 +- 用户名：`username:`（如果你的 Signal 账户支持）。 ## 故障排除 -先运行这个排查阶梯： +先运行这组排查命令： ```bash openclaw status @@ -278,7 +279,7 @@ openclaw pairing list signal 常见故障： -- 守护进程可达但没有回复：验证账号/守护进程设置（`httpUrl`、`account`）和接收模式。 +- 守护进程可访问但没有回复：验证账户/守护进程设置（`httpUrl`、`account`）和接收模式。 - 私信被忽略：发送方正在等待配对批准。 - 群组消息被忽略：群组发送方/提及门控阻止了投递。 - 编辑后出现配置验证错误：运行 `openclaw doctor --fix`。 @@ -292,14 +293,14 @@ pgrep -af signal-cli grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20 ``` -排查流程见：[/channels/troubleshooting](/zh-CN/channels/troubleshooting)。 +分诊流程：[/channels/troubleshooting](/zh-CN/channels/troubleshooting)。 -## 安全说明 +## 安全注意事项 -- `signal-cli` 会在本地存储账号密钥（通常位于 `~/.local/share/signal-cli/data/`）。 -- 在服务器迁移或重建前备份 Signal 账号状态。 -- 除非你明确想要更宽泛的私信访问，否则保持 `channels.signal.dmPolicy: "pairing"`。 -- 短信验证只在注册或恢复流程中需要，但如果失去对号码/账号的控制，重新注册会变得复杂。 +- `signal-cli` 会在本地存储账户密钥（通常为 `~/.local/share/signal-cli/data/`）。 +- 在服务器迁移或重建前备份 Signal 账户状态。 +- 除非你明确需要更宽泛的私信访问，否则请保持 `channels.signal.dmPolicy: "pairing"`。 +- 短信验证仅在注册或恢复流程中需要，但如果失去对号码/账户的控制，重新注册可能会变得复杂。 ## 配置参考（Signal） @@ -307,27 +308,27 @@ grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20 提供商选项： -- `channels.signal.enabled`：启用/停用渠道启动。 +- `channels.signal.enabled`：启用/禁用渠道启动。 - `channels.signal.account`：机器人账号的 E.164。 - `channels.signal.cliPath`：`signal-cli` 的路径。 -- `channels.signal.httpUrl`：完整的守护进程 URL（覆盖主机/端口）。 +- `channels.signal.httpUrl`：完整的守护进程 URL（覆盖 host/port）。 - `channels.signal.httpHost`、`channels.signal.httpPort`：守护进程绑定地址（默认 127.0.0.1:8080）。 - `channels.signal.autoStart`：自动生成守护进程（如果未设置 `httpUrl`，默认为 true）。 -- `channels.signal.startupTimeoutMs`：启动等待超时时间，单位为毫秒（上限 120000）。 +- `channels.signal.startupTimeoutMs`：启动等待超时时间，单位为 ms（上限 120000）。 - `channels.signal.receiveMode`：`on-start | manual`。 - `channels.signal.ignoreAttachments`：跳过附件下载。 -- `channels.signal.ignoreStories`：忽略来自守护进程的故事。 +- `channels.signal.ignoreStories`：忽略来自守护进程的动态。 - `channels.signal.sendReadReceipts`：转发已读回执。 - `channels.signal.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）。 - `channels.signal.allowFrom`：私信允许列表（E.164 或 `uuid:`）。`open` 需要 `"*"`。Signal 没有用户名；请使用电话/UUID ID。 - `channels.signal.groupPolicy`：`open | allowlist | disabled`（默认：allowlist）。 - `channels.signal.groupAllowFrom`：群组允许列表；接受 Signal 群组 ID（原始值、`group:` 或 `signal:group:`）、发送者 E.164 号码，或 `uuid:` 值。 -- `channels.signal.groups`：按 Signal 群组 ID（或 `"*"`）键控的每群组覆盖项。支持的字段：`requireMention`、`tools`、`toolsBySender`。 -- `channels.signal.accounts..groups`：用于多账号设置的 `channels.signal.groups` 每账号版本。 -- `channels.signal.historyLimit`：作为上下文包含的群组消息最大数量（0 表示停用）。 -- `channels.signal.dmHistoryLimit`：以用户轮次计的私信历史限制。每用户覆盖项：`channels.signal.dms[""].historyLimit`。 -- `channels.signal.textChunkLimit`：出站分块大小（字符）。 -- `channels.signal.chunkMode`：`length`（默认）或 `newline`，用于在按长度分块之前按空行（段落边界）拆分。 +- `channels.signal.groups`：按 Signal 群组 ID（或 `"*"`）索引的每群组覆盖项。支持的字段：`requireMention`、`tools`、`toolsBySender`。 +- `channels.signal.accounts..groups`：用于多账号设置的 `channels.signal.groups` 按账号版本。 +- `channels.signal.historyLimit`：作为上下文包含的最大群组消息数（0 表示禁用）。 +- `channels.signal.dmHistoryLimit`：以用户轮次计的私信历史限制。按用户覆盖项：`channels.signal.dms[""].historyLimit`。 +- `channels.signal.textChunkLimit`：出站分块大小（字符数）。 +- `channels.signal.chunkMode`：`length`（默认）或 `newline`，用于在按长度分块前按空行（段落边界）拆分。 - `channels.signal.mediaMaxMb`：入站/出站媒体上限（MB）。 相关全局选项：