[OpenClaw 文档]消息渠道--配置

2026年 5月 12日 OpenClaw SE_You

本文档汇总了 OpenClaw 官方文档站 消息渠道 > 配置子模块下的全部 7 篇内容，源自 docs.openclaw.ai/zh-CN。

📑 本文目录（7 篇）

📄 配对

原文：https://docs.openclaw.ai/zh-CN/channels/pairing

“配对”是 OpenClaw 显式的访问批准步骤。
它用于两个地方：

私信配对（谁可以和机器人对话）
节点配对（哪些设备/节点可以加入 Gateway 网关网络）

安全上下文：安全

1) 私信配对（入站聊天访问）

当某个渠道配置为 DM 策略 pairing 时，未知发送者会收到一个短代码，并且他们的消息在你批准之前不会被处理。

默认 DM 策略记录在：安全

dmPolicy: "open" 只有在有效的 DM 允许列表包含 "*" 时才是公开的。
设置和验证要求公开开放配置使用该通配符。如果现有
状态包含带有具体 allowFrom 条目的 open，运行时仍然只接纳
那些发送者，并且配对存储中的批准不会扩大 open 访问范围。

配对代码：

8 个字符，大写，不含易混淆字符（0O1I）。
1 小时后过期。机器人仅在创建新请求时发送配对消息（每个发送者大约每小时一次）。
待处理的 DM 配对请求默认限制为每个渠道 3 个；额外请求会被忽略，直到其中一个过期或被批准。

批准发送者

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

如果尚未配置命令所有者，批准 DM 配对代码也会将
commands.ownerAllowFrom 引导设置为已批准的发送者，例如 telegram:123456789。
这会为首次设置提供一个显式所有者，用于特权命令和 exec
批准提示。在所有者存在之后，后续配对批准只授予 DM
访问权限；它们不会添加更多所有者。

支持的渠道：discord、feishu、googlechat、imessage、irc、line、matrix、mattermost、msteams、nextcloud-talk、nostr、openclaw-weixin、signal、slack、synology-chat、telegram、twitch、whatsapp、zalo、zalouser。

可复用发送者组

当同一组受信任发送者应应用于多个消息渠道，或同时应用于 DM 和群组允许列表时，
使用顶层 accessGroups。

静态组使用 type: "message.senders"，并通过渠道允许列表中的
accessGroup:<name> 引用：

{
  accessGroups: {
    operators: {
      type: "message.senders",
      members: {
        discord: ["discord:123456789012345678"],
        telegram: ["987654321"],
        whatsapp: ["+15551234567"],
      },
    },
  },
  channels: {
    telegram: { dmPolicy: "allowlist", allowFrom: ["accessGroup:operators"] },
    whatsapp: { groupPolicy: "allowlist", groupAllowFrom: ["accessGroup:operators"] },
  },
}

访问组在这里有详细文档：访问组

状态存储位置

存储在 ~/.openclaw/credentials/ 下：

待处理请求：<channel>-pairing.json
已批准允许列表存储：
默认账户：<channel>-allowFrom.json
非默认账户：<channel>-<accountId>-allowFrom.json

账户作用域行为：

非默认账户只读写其作用域内的允许列表文件。
默认账户使用渠道作用域的非作用域允许列表文件。

将这些视为敏感数据（它们控制对你的助手的访问）。

配对允许列表存储用于 DM 访问。群组授权是独立的。
批准 DM 配对代码不会自动允许该发送者运行群组
命令或在群组中控制机器人。首个所有者引导是
commands.ownerAllowFrom 中独立的配置状态，而群组聊天投递仍遵循
渠道的群组允许列表（例如 groupAllowFrom、groups，或根据渠道而定的每群组
或每主题覆盖）。

2) 节点设备配对（iOS/Android/macOS/无头节点）

节点作为设备以 role: node 连接到 Gateway 网关。Gateway 网关
会创建设备配对请求，该请求必须获得批准。

通过 Telegram 配对（推荐用于 iOS）

如果你使用 device-pair 插件，可以完全通过 Telegram 完成首次设备配对：

在 Telegram 中给你的机器人发送消息：/pair
机器人会回复两条消息：一条说明消息，以及一条单独的设置代码消息（便于在 Telegram 中复制/粘贴）。
在手机上打开 OpenClaw iOS 应用 → 设置 → Gateway 网关。
扫描二维码或粘贴设置代码并连接。
回到 Telegram：/pair pending（查看请求 ID、角色和作用域），然后批准。

设置代码是一个 base64 编码的 JSON 载荷，包含：

url：Gateway 网关 WebSocket URL（ws://... 或 wss://...）
bootstrapToken：用于初始配对握手的短期单设备引导令牌

该引导令牌携带内置的配对引导配置：

主要交接的 node 令牌保持 scopes: []
任何交接的 operator 令牌仍受引导允许列表限制：
operator.approvals、operator.read、operator.talk.secrets、operator.write
引导作用域检查带有角色前缀，而不是一个扁平作用域池：
operator 作用域条目只满足 operator 请求，非 operator 角色
仍必须在自己的角色前缀下请求作用域
后续令牌轮换/撤销仍同时受设备已批准
角色契约和调用方会话的 operator 作用域限制

在设置代码有效期间，将它当作密码处理。

对于 Tailscale、公开或其他远程移动端配对，使用 Tailscale Serve/Funnel
或另一个 wss:// Gateway 网关 URL。明文 ws:// 设置代码只接受
local loopback、私有 LAN 地址、.local Bonjour 主机和 Android
模拟器主机。Tailnet CGNAT 地址、.ts.net 名称和公共主机仍会在二维码/设置代码签发前
默认拒绝。

批准节点设备

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>

当显式批准因为正在批准的已配对设备会话以仅配对作用域打开而被拒绝时，
CLI 会使用 operator.admin 重试同一请求。这让已有具备管理员能力的已配对设备
可以恢复新的 Control UI/浏览器配对，而无需手动编辑 devices/paired.json。
Gateway 网关仍会验证重试后的连接；无法使用
operator.admin 认证的令牌仍会被阻止。

如果同一设备使用不同的认证详情重试（例如不同的
角色/作用域/公钥），之前的待处理请求会被取代，并创建新的
requestId。

已配对设备不会静默获得更广泛的访问权限。如果它重新连接并请求更多作用域或更广泛的角色，OpenClaw 会保持现有批准不变，并创建一个新的待处理升级请求。批准前，使用 openclaw devices list 比较当前已批准访问权限和新请求的访问权限。

可选的受信任 CIDR 节点自动批准

设备配对默认保持手动。对于严格受控的节点网络，
你可以选择使用显式 CIDR 或精确 IP 进行首次节点自动批准：

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

这只适用于没有请求
作用域的全新 role: node 配对请求。Operator、浏览器、Control UI 和 WebChat 客户端仍需要手动
批准。角色、作用域、元数据和公钥变更仍需要手动
批准。

节点配对状态存储

存储在 ~/.openclaw/devices/ 下：

pending.json（短期；待处理请求会过期）
paired.json（已配对设备 + 令牌）

说明

旧版 node.pair.* API（CLI：openclaw nodes pending|approve|reject|remove|rename）是一个
独立的 Gateway 网关拥有的配对存储。WS 节点仍需要设备配对。
配对记录是已批准角色的持久事实来源。活动
设备令牌仍受该已批准角色集限制；已批准角色之外的零散令牌条目
不会创建新的访问权限。

📄 WhatsApp 群组消息

原文：https://docs.openclaw.ai/zh-CN/channels/group-messages

对于跨渠道群组模型（Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo），请参阅群组。本页介绍该模型之上的 WhatsApp 专属行为：激活、群组允许列表、按群组划分的会话键，以及待处理消息上下文注入。

目标：让 OpenClaw 驻留在 WhatsApp 群组中，只在被 ping 时唤醒，并将该线程与个人私信会话分开。

agents.list[].groupChat.mentionPatterns 也由 Telegram、Discord、Slack 和 iMessage 使用。对于多智能体设置，请按智能体设置它，或使用 messages.groupChat.mentionPatterns 作为全局回退。

行为

激活模式：mention（默认）或 always。mention 需要 ping（通过 mentionedJids 传递的真实 WhatsApp @ 提及、安全的正则模式，或文本中任意位置的机器人 E.164 号码）。always 会在每条消息上唤醒智能体，但它只应在能提供有意义价值时回复；否则返回精确的静默令牌 NO_REPLY / no_reply。默认值可以在配置（channels.whatsapp.groups）中设置，并可通过 /activation 按群组覆盖。设置 channels.whatsapp.groups 时，它也会作为群组允许列表（包含 "*" 表示允许全部）。
群组策略：channels.whatsapp.groupPolicy 控制是否接受群组消息（open|disabled|allowlist）。allowlist 使用 channels.whatsapp.groupAllowFrom（回退：显式的 channels.whatsapp.allowFrom）。默认值为 allowlist（在你添加发送者之前会被阻止）。
按群组划分的会话：会话键形如 agent:<agentId>:whatsapp:group:<jid>，因此 /verbose on、/trace on 或 /think high（作为独立消息发送）等命令仅作用于该群组；个人私信状态不受影响。群组线程会跳过 Heartbeat。
上下文注入：仅待处理的群组消息（默认 50 条），即_未_触发运行的消息，会以 [Chat messages since your last reply - for context] 为前缀注入，触发消息行位于 [Current message - respond to this] 下。已经在会话中的消息不会被重新注入。
发送者呈现：每个群组批次现在都会以 [from: Sender Name (+E164)] 结尾，因此 Pi 知道是谁在发言。
临时/阅后即焚：我们会先解包这些消息，再提取文本/提及，因此其中的 ping 仍会触发。
群组系统提示：在群组会话的首轮（以及每次 /activation 更改模式时），我们会向系统提示注入一小段说明，例如 You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), ... Activation: trigger-only ... Address the specific sender noted in the message context. 如果元数据不可用，我们仍会告诉智能体这是群聊。

配置示例（WhatsApp）

向 ~/.openclaw/openclaw.json 添加一个 groupChat 块，这样即使 WhatsApp 从正文中剥离可见的 @，显示名称 ping 也能工作：

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          historyLimit: 50,
          mentionPatterns: ["@?openclaw", "\\+?15555550123"],
        },
      },
    ],
  },
}

说明：

正则表达式不区分大小写，并使用与其他配置正则表面相同的安全正则护栏；无效模式和不安全的嵌套重复会被忽略。
当有人点按联系人时，WhatsApp 仍会通过 mentionedJids 发送规范提及，因此号码回退很少需要，但它是一个有用的安全网。

激活命令（仅所有者）

使用群聊命令：

/activation mention
/activation always

只有所有者号码（来自 channels.whatsapp.allowFrom，未设置时为机器人自己的 E.164）可以更改此项。在群组中将 /status 作为独立消息发送，可查看当前激活模式。

使用方法

将你的 WhatsApp 账号（运行 OpenClaw 的那个账号）添加到群组。
发送 @openclaw …（或包含号码）。除非你设置 groupPolicy: "open"，否则只有允许列表中的发送者可以触发它。
智能体提示会包含最近的群组上下文以及末尾的 [from: …] 标记，以便它能称呼正确的人。
会话级指令（/verbose on、/trace on、/think high、/new 或 /reset、/compact）仅适用于该群组的会话；请将它们作为独立消息发送，以便它们被注册。你的个人私信会话保持独立。

测试 / 验证

手动冒烟测试：
在群组中发送一个 @openclaw ping，并确认回复引用了发送者姓名。
发送第二个 ping，并验证历史块已包含，然后在下一轮被清除。
检查 Gateway 网关日志（使用 --verbose 运行），查看显示 from: <groupJid> 和 [from: …] 后缀的 inbound web message 条目。

已知注意事项

群组会有意跳过 Heartbeat，以避免产生嘈杂的广播。
回声抑制使用组合后的批次字符串；如果你发送两次不带提及的相同文本，只有第一次会获得响应。
会话存储条目会在会话存储中显示为 agent:<agentId>:whatsapp:group:<jid>（默认位于 ~/.openclaw/agents/<agentId>/sessions/sessions.json）；缺失条目只表示该群组尚未触发运行。
群组中的输入指示器遵循 agents.defaults.typingMode。当可见回复使用默认的仅消息工具模式时，输入默认会立即开始，因此即使没有发布自动最终回复，群组成员也能看到智能体正在工作。显式的输入模式配置仍然优先。

📄 群组

原文：https://docs.openclaw.ai/zh-CN/channels/groups

OpenClaw 在各个界面上一致处理群聊：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。

新手简介（2 分钟）

OpenClaw “存在于”你自己的消息账号中。没有单独的 WhatsApp 机器人用户。如果你在某个群组中，OpenClaw 就能看到该群组并在那里响应。

默认行为：

群组受限（groupPolicy: "allowlist"）。
除非你明确禁用提及门控，否则回复需要提及。
群组/频道中的普通最终回复默认是私密的。可见的房间输出使用 message 工具。

换句话说：允许列表中的发送者可以通过提及 OpenClaw 来触发它。

摘要

私信访问由 *.allowFrom 控制。
群组访问由 *.groupPolicy + 允许列表（*.groups、*.groupAllowFrom）控制。
回复触发由提及门控（requireMention、/activation）控制。

快速流程（群组消息会发生什么）：

groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply

可见回复

对于群组/频道房间，OpenClaw 默认使用 messages.groupChat.visibleReplies: "message_tool"。
openclaw doctor --fix 会把这个默认值写入已配置但省略该项的渠道配置。
这意味着 agent 仍会处理该轮次，并可以更新记忆/会话状态，但它的普通最终回答不会自动发回房间。若要可见地发言，agent 使用 message(action=send)。

此默认值依赖会可靠调用工具的模型/运行时。如果日志显示
assistant 文本但 didSendViaMessagingTool: false，说明模型私下回答了，
而不是调用 message 工具。这不是 Discord/Slack/Telegram 发送失败。
请为群组/频道会话使用工具调用可靠的模型，或设置
messages.groupChat.visibleReplies: "automatic" 以恢复旧版可见最终回复。

如果在当前工具策略下 message 工具不可用，OpenClaw 会回退到自动可见回复，
而不是静默抑制响应。openclaw doctor 会对此不匹配发出警告。

对于直接聊天和任何其他来源轮次，使用 messages.visibleReplies: "message_tool" 将相同的仅工具可见回复行为全局应用。Harness 也可以将其选为未设置时的默认值；Codex harness 会对 Codex 模式直接聊天这样做。messages.groupChat.visibleReplies 仍然是群组/频道房间更具体的覆盖项。

这取代了旧模式：强制模型在大多数潜伏模式轮次中回答 NO_REPLY。在仅工具模式下，没有可见动作只是意味着不调用 message 工具。

在仅工具模式下，agent 工作时仍会发送输入指示。对于这些轮次，默认群组输入模式会从 “message” 升级为 “instant”，因为在 agent 决定是否调用 message 工具之前，可能永远不会有普通 assistant 消息文本。显式输入模式配置仍然优先。

要为群组/频道房间恢复旧版自动最终回复：

{
  messages: {
    groupChat: {
      visibleReplies: "automatic",
    },
  },
}

文件保存后，Gateway 网关会热重载 messages 配置。只有在部署中禁用文件监听或配置重载时才需要重启。

要要求每个来源聊天的可见输出都通过 message 工具：

{
  messages: {
    visibleReplies: "message_tool",
  },
}

原生命令（Discord、Telegram 以及其他支持原生命令的界面）会绕过 visibleReplies: "message_tool"，并始终可见地回复，以便频道原生命令 UI 获得其预期的响应。这仅适用于已验证的原生命令轮次；文本输入的 /... 命令和普通聊天轮次仍遵循配置的群组默认值。

上下文可见性和允许列表

群组安全涉及两种不同控制：

触发授权：谁可以触发 agent（groupPolicy、groups、groupAllowFrom、渠道特定允许列表）。
上下文可见性：哪些补充上下文会注入模型（回复文本、引用、线程历史、转发元数据）。

默认情况下，OpenClaw 优先保持正常聊天行为，并基本按接收时的样子保留上下文。这意味着允许列表主要决定谁可以触发动作，而不是作为每个引用或历史片段的通用脱敏边界。

- 一些渠道已经在特定路径中对补充上下文应用基于发送者的过滤（例如 Slack 线程播种、Matrix 回复/线程查找）。
- 其他渠道仍会按接收时的样子传递引用/回复/转发上下文。

- contextVisibility: "all"（默认）保持当前按接收时处理的行为。
- contextVisibility: "allowlist" 将补充上下文过滤为允许列表发送者。
- contextVisibility: "allowlist_quote" 是 allowlist 加一个显式引用/回复例外。

在此加固模型跨渠道一致实现之前，预期不同界面之间会有差异。

群组消息流程

如果你想要……

目标	要设置的内容
允许所有群组，但只在 @ 提及时回复	`groups: { "*": { requireMention: true } }`
禁用所有群组回复	`groupPolicy: "disabled"`
只允许特定群组	`groups: { "<group-id>": { ... } }`（没有 `"*"` 键）
只有你可以在群组中触发	`groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]`
跨渠道复用一组可信发送者	`groupAllowFrom: ["accessGroup:operators"]`

关于可复用发送者允许列表，请参阅访问组。

会话键

群组会话使用 agent:<agentId>:<channel>:group:<id> 会话键（房间/频道使用 agent:<agentId>:<channel>:channel:<id>）。
Telegram 论坛话题会向群组 id 添加 :topic:<threadId>，因此每个话题都有自己的会话。
直接聊天使用主会话（如果已配置，也可按发送者使用单独会话）。
群组会话会跳过 Heartbeat。

模式：个人私信 + 公开群组（单个 agent）

可以。如果你的“个人”流量是私信，而你的“公开”流量是群组，这种方式很适合。

原因：在单 agent 模式下，私信通常落在主会话键（agent:main:main）中，而群组始终使用非主会话键（agent:main:<channel>:group:<id>）。如果你启用沙箱隔离并设置 mode: "non-main"，这些群组会话会在配置的沙箱后端中运行，而你的主私信会话仍留在主机上。如果你没有选择后端，Docker 是默认后端。

这会给你一个 agent “大脑”（共享工作区 + 记忆），但有两种执行姿态：

私信：完整工具（主机）
群组：沙箱 + 受限工具

如果你需要真正分离的工作区/人格（“个人”和“公开”绝不能混用），请使用第二个 agent + 绑定。参阅多 Agent 路由。

json5 { agents: { defaults: { sandbox: { mode: "non-main", // groups/channels are non-main -> sandboxed scope: "session", // strongest isolation (one container per group/channel) workspaceAccess: "none", }, }, }, tools: { sandbox: { tools: { // If allow is non-empty, everything else is blocked (deny still wins). allow: ["group:messaging", "group:sessions"], deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"], }, }, }, }

想要“群组只能看到文件夹 X”，而不是“无主机访问”？保留 workspaceAccess: "none"，并只把允许列表路径挂载进沙箱：

```json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
        docker: {
          binds: [
            // hostPath:containerPath:mode
            "/home/user/FriendsShared:/data:ro",
          ],
        },
      },
    },
  },
}
```

显示标签

UI 标签在可用时使用 displayName，格式为 <channel>:<token>。
#room 保留给房间/频道；群聊使用 g-<slug>（小写，空格 -> -，保留 #@+._-）。

群组策略

按渠道控制如何处理群组/房间消息：

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // numeric Telegram user id (wizard can resolve @username)
    },
    signal: {
      groupPolicy: "disabled",
      groupAllowFrom: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "disabled",
      groupAllowFrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "disabled",
      groupAllowFrom: ["user@org.com"],
    },
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        GUILD_ID: { channels: { help: { allow: true } } },
      },
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { allow: true } },
    },
    matrix: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["@owner:example.org"],
      groups: {
        "!roomId:example.org": { enabled: true },
        "#alias:example.org": { enabled: true },
      },
    },
  },
}

策略	行为
`"open"`	群组绕过允许列表；提及门控仍然适用。
`"disabled"`	完全阻止所有群组消息。
`"allowlist"`	只允许匹配已配置允许列表的群组/房间。

- 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 允许列表。
- 群组私信单独控制（channels.discord.dm.*、channels.slack.dm.*）。
- Telegram 允许列表可以匹配用户 ID（"123456789"、"telegram:123456789"、"tg:123456789"）或用户名（"@alice" 或 "alice"）；前缀不区分大小写。
- 默认值是 groupPolicy: "allowlist"；如果你的群组允许列表为空，群组消息会被阻止。
- 运行时安全：当提供商块完全缺失（不存在 channels.<provider>）时，群组策略会回退到故障关闭模式（通常是 allowlist），而不是继承 channels.defaults.groupPolicy。

快速心智模型（群组消息的评估顺序）：

groupPolicy（open/disabled/allowlist）。

群组允许列表（*.groups、*.groupAllowFrom、频道特定允许列表）。

提及门控（requireMention、/activation）。

提及门控（默认）

除非按群组覆盖，否则群组消息需要提及。默认值位于每个子系统的 *.groups."*" 下。

当频道支持回复元数据时，回复机器人消息会算作隐式提及。在暴露引用元数据的频道上，引用机器人消息也可以算作隐式提及。当前内置场景包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
        "123@g.us": { requireMention: false },
      },
    },
    telegram: {
      groups: {
        "*": { requireMention: true },
        "123456789": { requireMention: false },
      },
    },
    imessage: {
      groups: {
        "*": { requireMention: true },
        "123": { requireMention: false },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
          historyLimit: 50,
        },
      },
    ],
  },
}

- mentionPatterns 是不区分大小写的安全正则表达式模式；无效模式和不安全的嵌套重复形式会被忽略。
- 提供显式提及的界面仍会通过；模式只是回退方案。
- 按 agent 覆盖：agents.list[].groupChat.mentionPatterns（当多个 agent 共享一个群组时很有用）。
- 仅当可以检测提及时（配置了原生提及或 mentionPatterns），才会强制执行提及门控。
- 将群组或发送者加入允许列表不会禁用提及门控；如果所有消息都应触发，请将该群组的 requireMention 设置为 false。
- 群聊提示上下文会在每一轮携带解析后的静默回复指令；工作区文件不应重复 NO_REPLY 机制。
- 允许静默回复的群组会将干净的空模型轮次或仅推理模型轮次视为静默，等同于 NO_REPLY。直接聊天只有在明确允许直接静默回复时才会这样；否则空回复仍会被视为失败的 agent 轮次。
- Discord 默认值位于 channels.discord.guilds."*"（可按服务器/频道覆盖）。
- 群组历史上下文会在各频道中统一包装。提及门控群组会保留待处理的已跳过消息；当频道支持时，始终开启的群组也可能保留最近已处理的房间消息。使用 messages.groupChat.historyLimit 设置全局默认值，并使用 channels.<channel>.historyLimit（或 channels.<channel>.accounts.*.historyLimit）进行覆盖。设置为 0 可禁用。

群组/频道工具限制（可选）

某些频道配置支持限制特定群组/房间/频道内可用的工具。

tools：为整个群组允许/拒绝工具。
toolsBySender：群组内按发送者覆盖。使用显式键前缀：channel:<channelId>:<senderId>、id:<senderId>、e164:<phone>、username:<handle>、name:<displayName> 和 "*" 通配符。频道 ID 使用规范 OpenClaw 频道 ID；teams 等别名会规范化为 msteams。旧版无前缀键仍被接受，并且只按 id: 匹配。

解析顺序（最具体者优先）：

群组/频道 toolsBySender 匹配。

群组/频道 tools。

默认（"*"）toolsBySender 匹配。

默认（"*"）tools。

示例（Telegram）：

{
  channels: {
    telegram: {
      groups: {
        "*": { tools: { deny: ["exec"] } },
        "-1001234567890": {
          tools: { deny: ["exec", "read", "write"] },
          toolsBySender: {
            "id:123456789": { alsoAllow: ["exec"] },
          },
        },
      },
    },
  },
}

群组/频道工具限制会在全局/agent 工具策略之外额外应用（拒绝仍优先）。某些频道对房间/频道使用不同的嵌套结构（例如 Discord guilds.*.channels.*、Slack channels.*、Microsoft Teams teams.*.channels.*）。

群组允许列表

配置 channels.whatsapp.groups、channels.telegram.groups 或 channels.imessage.groups 时，键会作为群组允许列表。使用 "*" 可允许所有群组，同时仍设置默认提及行为。

常见混淆：私信配对批准不等同于群组授权。对于支持私信配对的频道，配对存储只会解锁私信。群组命令仍需要来自配置允许列表的显式群组发送者授权，例如 groupAllowFrom，或该频道记录的配置回退。

常见意图（复制/粘贴）：

json5 { channels: { whatsapp: { groupPolicy: "disabled" } }, }

json5 { channels: { whatsapp: { groups: { "123@g.us": { requireMention: true }, "456@g.us": { requireMention: false }, }, }, }, }

json5 { channels: { whatsapp: { groups: { "*": { requireMention: true } }, }, }, }

json5 { channels: { whatsapp: { groupPolicy: "allowlist", groupAllowFrom: ["+15551234567"], groups: { "*": { requireMention: true } }, }, }, }

激活（仅所有者）

群组所有者可以切换每个群组的激活状态：

/activation mention
/activation always

所有者由 channels.whatsapp.allowFrom 决定（未设置时为机器人的自身 E.164）。将该命令作为独立消息发送。其他界面目前会忽略 /activation。

上下文字段

群组入站载荷会设置：

ChatType=group
GroupSubject（如果已知）
GroupMembers（如果已知）
WasMentioned（提及门控结果）
Telegram 论坛主题还包含 MessageThreadId 和 IsForum。

agent 系统提示会在新群组会话的第一轮包含群组介绍。它会提醒模型像真人一样回复，避免使用 Markdown 表格，尽量减少空行并遵循正常聊天间距，避免输入字面量 \n 序列。来自频道的群组名称和参与者标签会作为围栏中的不可信元数据呈现，而不是内联系统指令。

iMessage 细节

路由或加入允许列表时优先使用 chat_id:<id>。
列出聊天：imsg chats --limit 20。
群组回复始终发回同一个 chat_id。

WhatsApp 系统提示

有关规范 WhatsApp 系统提示规则，请参阅 WhatsApp，包括群组和直接提示解析、通配符行为，以及账号覆盖语义。

WhatsApp 细节

有关 WhatsApp 专用行为（历史注入、提及处理细节），请参阅群组消息。

📄 广播组

原文：https://docs.openclaw.ai/zh-CN/channels/broadcast-groups

Status: 实验性。已在 2026.1.9 中添加。

概览

Broadcast Groups 允许多个智能体同时处理并回复同一条消息。这样你可以创建专门的智能体团队，让它们在同一个 WhatsApp 群组或私信中协作，且全部使用同一个电话号码。

当前范围：仅 WhatsApp（Web 渠道）。

Broadcast groups 会在渠道允许列表和群组激活规则之后评估。在 WhatsApp 群组中，这意味着当 OpenClaw 通常会回复时（例如：被提及时，取决于你的群组设置），就会进行广播。

使用场景

部署多个职责原子化且聚焦的智能体：

```
Group: "Development Team"
Agents:
  - CodeReviewer (reviews code snippets)
  - DocumentationBot (generates docs)
  - SecurityAuditor (checks for vulnerabilities)
  - TestGenerator (suggests test cases)
```

每个智能体都会处理同一条消息，并提供自己的专业视角。

Group: "International Support" Agents: - Agent_EN (responds in English) - Agent_DE (responds in German) - Agent_ES (responds in Spanish)

Group: "Customer Support" Agents: - SupportAgent (provides answer) - QAAgent (reviews quality, only responds if issues found)

Group: "Project Management" Agents: - TaskTracker (updates task database) - TimeLogger (logs time spent) - ReportGenerator (creates summaries)

配置

基本设置

添加一个顶层 broadcast 部分（与 bindings 同级）。键是 WhatsApp 对端 ID：

群组聊天：群组 JID（例如 120363403215116621@g.us）
私信：E.164 电话号码（例如 +15551234567）

{
  "broadcast": {
    "120363403215116621@g.us": ["alfred", "baerbel", "assistant3"]
  }
}

结果： 当 OpenClaw 会在此聊天中回复时，它会运行全部三个智能体。

处理策略

控制智能体如何处理消息：

所有智能体同时处理：

```json
{
  "broadcast": {
    "strategy": "parallel",
    "120363403215116621@g.us": ["alfred", "baerbel"]
  }
}
```

智能体按顺序处理（一个等待前一个完成）：

```json
{
  "broadcast": {
    "strategy": "sequential",
    "120363403215116621@g.us": ["alfred", "baerbel"]
  }
}
```

完整示例

{
  "agents": {
    "list": [
      {
        "id": "code-reviewer",
        "name": "Code Reviewer",
        "workspace": "/path/to/code-reviewer",
        "sandbox": { "mode": "all" }
      },
      {
        "id": "security-auditor",
        "name": "Security Auditor",
        "workspace": "/path/to/security-auditor",
        "sandbox": { "mode": "all" }
      },
      {
        "id": "docs-generator",
        "name": "Documentation Generator",
        "workspace": "/path/to/docs-generator",
        "sandbox": { "mode": "all" }
      }
    ]
  },
  "broadcast": {
    "strategy": "parallel",
    "120363403215116621@g.us": ["code-reviewer", "security-auditor", "docs-generator"],
    "120363424282127706@g.us": ["support-en", "support-de"],
    "+15555550123": ["assistant", "logger"]
  }
}

工作原理

消息流程

收到一条 WhatsApp 群组或私信消息。

系统检查对端 ID 是否在 broadcast 中。

- 所有列出的智能体都会处理该消息。
- 每个智能体都有自己的会话键和隔离上下文。
- 智能体并行（默认）或顺序处理。

应用正常路由（第一个匹配的绑定）。

Broadcast groups 不会绕过渠道允许列表或群组激活规则（提及/命令等）。它们只会在消息符合处理条件时改变_运行哪些智能体_。

会话隔离

Broadcast group 中的每个智能体都会维护完全独立的：

会话键（agent:alfred:whatsapp:group:120363... 与 agent:baerbel:whatsapp:group:120363...）
对话历史（智能体看不到其他智能体的消息）
工作区（如果已配置，则使用独立沙箱）
工具访问权限（不同的允许/拒绝列表）
记忆/上下文（独立的 IDENTITY.md、SOUL.md 等）
群组上下文缓冲区（用于上下文的近期群组消息）按对端共享，因此所有广播智能体被触发时都会看到相同上下文

这让每个智能体可以拥有：

不同的性格
不同的工具访问权限（例如，只读与读写）
不同的模型（例如，opus 与 sonnet）
安装不同的 Skills

示例：隔离会话

在群组 120363403215116621@g.us 中，智能体为 ["alfred", "baerbel"]：

Session: agent:alfred:whatsapp:group:120363403215116621@g.us History: [user message, alfred's previous responses] Workspace: /Users/user/openclaw-alfred/ Tools: read, write, exec

Session: agent:baerbel:whatsapp:group:120363403215116621@g.us History: [user message, baerbel's previous responses] Workspace: /Users/user/openclaw-baerbel/ Tools: read only

最佳实践

为每个智能体设计单一且清晰的职责：

```json
{
  "broadcast": {
    "DEV_GROUP": ["formatter", "linter", "tester"]
  }
}
```

✅ **好：** 每个智能体只有一项工作。❌ **不好：** 一个通用的 “dev-helper” 智能体。

清楚说明每个智能体的作用：

```json
{
  "agents": {
    "security-scanner": { "name": "Security Scanner" },
    "code-formatter": { "name": "Code Formatter" },
    "test-generator": { "name": "Test Generator" }
  }
}
```

只给智能体提供它们需要的工具：

```json
{
  "agents": {
    "reviewer": {
      "tools": { "allow": ["read", "exec"] }
    },
    "fixer": {
      "tools": { "allow": ["read", "write", "edit", "exec"] }
    }
  }
}
```

`reviewer` 是只读的。`fixer` 可以读取和写入。

当有很多智能体时，请考虑：

- 使用 `"strategy": "parallel"`（默认）以提升速度
- 将 broadcast groups 限制为 5-10 个智能体
- 为更简单的智能体使用更快的模型

智能体会独立失败。一个智能体的错误不会阻塞其他智能体：

```
Message → [Agent A ✓, Agent B ✗ error, Agent C ✓]
Result: Agent A and C respond, Agent B logs error
```

兼容性

提供商

Broadcast groups 目前适用于：

✅ WhatsApp（已实现）
🚧 Telegram（计划中）
🚧 Discord（计划中）
🚧 Slack（计划中）

路由

Broadcast groups 可与现有路由配合使用：

{
  "bindings": [
    {
      "match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } },
      "agentId": "alfred"
    }
  ],
  "broadcast": {
    "GROUP_B": ["agent1", "agent2"]
  }
}

GROUP_A：只有 alfred 回复（正常路由）。
GROUP_B：agent1 和 agent2 都会回复（广播）。

优先级： broadcast 优先于 bindings。

故障排除

检查：

1. 智能体 ID 存在于 `agents.list` 中。
2. 对端 ID 格式正确（例如 `120363403215116621@g.us`）。
3. 智能体不在拒绝列表中。

**调试：**

```bash
tail -f ~/.openclaw/logs/gateway.log | grep broadcast
```

原因： 对端 ID 可能在 bindings 中，但不在 broadcast 中。

**修复：** 添加到 broadcast 配置，或从 bindings 中移除。

如果多个智能体导致速度变慢：

- 减少每个群组的智能体数量。
- 使用更轻量的模型（使用 sonnet 而不是 opus）。
- 检查沙箱启动时间。

示例

json { "broadcast": { "strategy": "parallel", "120363403215116621@g.us": [ "code-formatter", "security-scanner", "test-coverage", "docs-checker" ] }, "agents": { "list": [ { "id": "code-formatter", "workspace": "~/agents/formatter", "tools": { "allow": ["read", "write"] } }, { "id": "security-scanner", "workspace": "~/agents/security", "tools": { "allow": ["read", "exec"] } }, { "id": "test-coverage", "workspace": "~/agents/testing", "tools": { "allow": ["read", "exec"] } }, { "id": "docs-checker", "workspace": "~/agents/docs", "tools": { "allow": ["read"] } } ] } }

**用户发送：** 代码片段。

**回复：**

- code-formatter：“已修复缩进并添加类型提示”
- security-scanner：“⚠️ 第 12 行存在 SQL 注入漏洞”
- test-coverage：“覆盖率为 45%，缺少错误情况测试”
- docs-checker：“函数 `process_data` 缺少文档字符串”

json { "broadcast": { "strategy": "sequential", "+15555550123": ["detect-language", "translator-en", "translator-de"] }, "agents": { "list": [ { "id": "detect-language", "workspace": "~/agents/lang-detect" }, { "id": "translator-en", "workspace": "~/agents/translate-en" }, { "id": "translator-de", "workspace": "~/agents/translate-de" } ] } }

API 参考

配置模式

interface OpenClawConfig {
  broadcast?: {
    strategy?: "parallel" | "sequential";
    [peerId: string]: string[];
  };
}

字段

如何处理智能体。parallel 会同时运行所有智能体；sequential 会按数组顺序运行它们。

WhatsApp 群组 JID、E.164 号码或其他对端 ID。值是应处理消息的智能体 ID 数组。

限制

最大智能体数： 没有硬性限制，但 10 个以上智能体可能会变慢。
共享上下文： 智能体看不到彼此的回复（设计如此）。
消息顺序： 并行回复可能以任意顺序到达。
速率限制： 所有智能体都会计入 WhatsApp 速率限制。

未来增强

计划功能：

[ ] 共享上下文模式（智能体看到彼此的回复）
[ ] 智能体协调（智能体可以互相发信号）
[ ] 动态智能体选择（根据消息内容选择智能体）
[ ] 智能体优先级（某些智能体先于其他智能体回复）

📄 渠道路由

原文：https://docs.openclaw.ai/zh-CN/channels/channel-routing

渠道与路由

OpenClaw 会将回复路由回消息来源的渠道。模型不会选择渠道；路由是确定性的，并由主机配置控制。

关键术语

渠道：telegram、whatsapp、discord、irc、googlechat、slack、signal、imessage、line，以及插件渠道。webchat 是内部 WebChat UI 渠道，不是可配置的出站渠道。
AccountId：每个渠道的账号实例（支持时）。
可选的渠道默认账号：channels.<channel>.defaultAccount 选择在出站路径未指定 accountId 时使用哪个账号。
在多账号设置中，如果配置了两个或更多账号，请设置显式默认值（defaultAccount 或 accounts.default）。如果不设置，回退路由可能会选择第一个规范化后的账号 ID。
AgentId：隔离的工作区 + 会话存储（“大脑”）。
SessionKey：用于存储上下文和控制并发的桶键。

出站目标前缀

显式出站目标可以包含提供商前缀，例如 telegram:123 或 tg:123。核心仅在所选渠道为 last 或仍未解析，且已加载插件声明了该前缀时，才会将该前缀视为渠道选择提示。如果调用方已经选择了显式渠道，则提供商前缀必须匹配该渠道；跨渠道组合（例如将 WhatsApp 投递到 telegram:123）会在插件专属目标规范化之前失败。

目标类型和服务前缀（例如 channel:<id>、user:<id>、room:<id>、thread:<id>、imessage:<handle> 和 sms:<number>）保留在所选渠道的语法内。它们本身不会选择提供商。

会话键形态（示例）

默认情况下，私信会折叠到智能体的 main 会话：

agent:<agentId>:<mainKey>（默认：agent:main:main）

即使私信对话历史与 main 共享，沙箱和工具策略也会为外部私信使用派生的每账号直接聊天运行时键，因此来自渠道的消息不会被视为本地 main 会话运行。

群组和频道会按渠道保持隔离：

群组：agent:<agentId>:<channel>:group:<id>
频道/房间：agent:<agentId>:<channel>:channel:<id>

线程：

Slack/Discord 线程会在基础键后附加 :thread:<threadId>。
Telegram 论坛话题会在群组键中嵌入 :topic:<topicId>。

示例：

agent:main:telegram:group:-1001234567890:topic:42
agent:main:discord:channel:123456:thread:987654

Main 私信路由固定

当 session.dmScope 为 main 时，私信可以共享一个 main 会话。为防止会话的 lastRoute 被非所有者私信覆盖，在以下条件全部为真时，OpenClaw 会从 allowFrom 推断固定所有者：

allowFrom 只有一个非通配符条目。
该条目可以规范化为该渠道的具体发送者 ID。
入站私信发送者与该固定所有者不匹配。

在这种不匹配情况下，OpenClaw 仍会记录入站会话元数据，但会跳过更新 main 会话的 lastRoute。

受保护的入站记录

当受保护路径不得创建新的 OpenClaw 会话时，渠道插件可以将入站会话记录标记为 createIfMissing: false。在该模式下，OpenClaw 可以更新现有会话的元数据和 lastRoute，但不会仅仅因为观察到一条消息就创建仅用于路由的会话条目。

路由规则（如何选择智能体）

路由会为每条入站消息选择一个智能体：

精确对等方匹配（带有 peer.kind + peer.id 的 bindings）。
父对等方匹配（线程继承）。
服务器 + 角色匹配（Discord），通过 guildId + roles。
服务器匹配（Discord），通过 guildId。
团队匹配（Slack），通过 teamId。
账号匹配（渠道上的 accountId）。
渠道匹配（该渠道上的任意账号，accountId: "*"）。
默认智能体（agents.list[].default，否则第一个列表条目，回退到 main）。

当某个绑定包含多个匹配字段（peer、guildId、teamId、roles）时，所有已提供字段都必须匹配，该绑定才会生效。

匹配到的智能体决定使用哪个工作区和会话存储。

广播群组（运行多个智能体）

广播群组允许你在同一个对等方上运行多个智能体，前提是 OpenClaw 通常会回复（例如：在 WhatsApp 群组中，通过提及/激活门控之后）。

配置：

{
  broadcast: {
    strategy: "parallel",
    "120363403215116621@g.us": ["alfred", "baerbel"],
    "+15555550123": ["support", "logger"],
  },
}

参见：广播群组。

配置概览

agents.list：命名智能体定义（工作区、模型等）。
bindings：将入站渠道/账号/对等方映射到智能体。

示例：

{
  agents: {
    list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }],
  },
  bindings: [
    { match: { channel: "slack", teamId: "T123" }, agentId: "support" },
    { match: { channel: "telegram", peer: { kind: "group", id: "-100123" } }, agentId: "support" },
  ],
}

会话存储

会话存储位于状态目录下（默认 ~/.openclaw）：

~/.openclaw/agents/<agentId>/sessions/sessions.json
JSONL 转录记录与存储位于同一位置

你可以通过 session.store 和 {agentId} 模板覆盖存储路径。

Gateway 网关和 ACP 会话发现也会扫描默认 agents/ 根目录以及模板化 session.store 根目录下的磁盘支持的智能体存储。发现的存储必须保留在解析后的智能体根目录内，并使用常规的 sessions.json 文件。符号链接和根目录之外的路径会被忽略。

WebChat 行为

WebChat 会附加到所选智能体，并默认使用该智能体的 main 会话。因此，WebChat 让你可以在一个位置查看该智能体的跨渠道上下文。

回复上下文

入站回复包含：

可用时包含 ReplyToId、ReplyToBody 和 ReplyToSender。
引用上下文会作为 [Replying to ...] 块追加到 Body。

这在各渠道之间保持一致。

📄 渠道位置解析

原文：https://docs.openclaw.ai/zh-CN/channels/location

OpenClaw 会将来自聊天渠道的共享位置标准化为：

追加到入站消息正文中的简洁坐标文本，以及
自动回复上下文载荷中的结构化字段。渠道提供的标签、地址以及标题/评论会通过共享的“不受信任元数据 JSON 块”渲染到提示词中，而不会内联到用户消息正文里。

当前支持：

Telegram（位置图钉 + 地点 + 实时位置）
WhatsApp（locationMessage + liveLocationMessage）
Matrix（带有 geo_uri 的 m.location）

文本格式

位置信息会被渲染为不带括号的友好文本行：

图钉：
📍 48.858844, 2.294351 ±12m
命名地点：
📍 48.858844, 2.294351 ±12m
实时共享：
🛰 Live location: 48.858844, 2.294351 ±12m

如果渠道包含标签、地址或标题/评论，它会保留在上下文载荷中，并在提示词里以带围栏的不受信任 JSON 显示：

位置（不受信任元数据）：
```json
{
  "latitude": 48.858844,
  "longitude": 2.294351,
  "name": "Eiffel Tower",
  "address": "Champ de Mars, Paris",
  "caption": "Meet here"
}
```

上下文字段

当存在位置信息时，这些字段会添加到 ctx 中：

LocationLat（number）
LocationLon（number）
LocationAccuracy（number，单位为米；可选）
LocationName（string；可选）
LocationAddress（string；可选）
LocationSource（pin | place | live）
LocationIsLive（boolean）
LocationCaption（string；可选）

提示词渲染器会将 LocationName、LocationAddress 和 LocationCaption 视为不受信任元数据，并通过与其他渠道上下文相同的有界 JSON 路径对其进行序列化。

渠道说明

Telegram：地点会映射到 LocationName/LocationAddress；实时位置使用 live_period。
WhatsApp：locationMessage.comment 和 liveLocationMessage.caption 会填充到 LocationCaption。
Matrix：geo_uri 会被解析为图钉位置；海拔会被忽略，且 LocationIsLive 始终为 false。

📄 渠道故障排除

原文：https://docs.openclaw.ai/zh-CN/channels/troubleshooting

当渠道已连接但行为异常时，请使用此页面。

命令阶梯

先按顺序运行这些命令：

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

健康基线：

Runtime: running
Connectivity probe: ok
Capability: read-only、write-capable 或 admin-capable
渠道探测显示传输协议已连接，并且在支持的情况下显示 works 或 audit ok

WhatsApp 故障特征

症状	最快检查	修复
已连接但没有私信回复	`openclaw pairing list whatsapp`	批准发送者，或切换私信策略/允许列表。
群组消息被忽略	检查配置中的 `requireMention` + 提及模式	提及机器人，或放宽该群组的提及策略。
二维码登录因 408 超时	检查 Gateway 网关的 `HTTPS_PROXY` / `HTTP_PROXY` 环境变量	设置可访问的代理；仅将 `NO_PROXY` 用于绕过。
随机断开连接/重新登录循环	`openclaw channels status --probe` + 日志	即使当前已连接，最近的重连也会被标记；观察日志，重启 Gateway 网关，如果仍持续抖动则重新关联。
回复延迟数秒/数分钟才到达	`openclaw doctor --fix`	当已验证的陈旧本地 TUI 客户端正在拖慢 Gateway 网关事件循环时，Doctor 会停止它们。

完整故障排除：WhatsApp 故障排除

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`	减少插件/技能/自定义 Telegram 命令，或禁用原生命令菜单。
升级后允许列表阻止了你	`openclaw security audit` 和配置允许列表	运行 `openclaw doctor --fix`，或将 `@username` 替换为数字发送者 ID。

完整故障排除：Telegram 故障排除

Discord

Discord 故障特征

症状	最快检查	修复
机器人在线但没有服务器回复	`openclaw channels status --probe`	允许服务器/频道，并验证消息内容意图。
群组消息被忽略	检查日志中因提及门控而丢弃的记录	提及机器人，或设置服务器/频道 `requireMention: false`。
有输入状态/令牌使用但没有 Discord 消息	会话日志显示助手文本且 `didSendViaMessagingTool: false`	模型私下回答了，而不是调用消息工具。使用可靠调用工具的模型，或设置 `messages.groupChat.visibleReplies: "automatic"` 以自动发布。
私信回复缺失	`openclaw pairing list discord`	批准私信配对，或调整私信策略。

完整故障排除：Discord 故障排除

Slack

Slack 故障特征

症状	最快检查	修复
Socket mode 已连接但没有响应	`openclaw channels status --probe`	验证 app token + bot token 和所需 scopes；在基于 SecretRef 的设置中留意 `botTokenStatus` / `appTokenStatus = configured_unavailable`。
私信被阻止	`openclaw pairing list slack`	批准配对，或放宽私信策略。
频道消息被忽略	检查 `groupPolicy` 和频道允许列表	允许该频道，或将策略切换为 `open`。

完整故障排除：Slack 故障排除

iMessage

iMessage 故障特征

症状	最快检查	修复
`imsg` 缺失或在非 macOS 上失败	`openclaw channels status --probe --channel imessage`	在 Messages Mac 上运行 OpenClaw，或为 `cliPath` 使用 SSH 包装器。
在 macOS 上可以发送但无法接收	检查 macOS 对 Messages 自动化的隐私权限	重新授予 TCC 权限，并重启渠道进程。
私信发送者被阻止	`openclaw pairing list imessage`	批准配对，或更新允许列表。

完整故障排除：

iMessage 故障排除

Signal

Signal 故障特征

症状	最快检查	修复
守护进程可访问但机器人静默	`openclaw channels status --probe`	验证 `signal-cli` 守护进程 URL/账户和接收模式。
私信被阻止	`openclaw pairing list signal`	批准发送者，或调整私信策略。
群组回复未触发	检查群组允许列表和提及模式	添加发送者/群组，或放宽门控。

完整故障排除：Signal 故障排除

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 可能会阻止机器人发起的消息。

完整故障排除：QQ Bot 故障排除

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`	一次性修复密钥存储、交叉签名和备份状态。

完整设置和配置：Matrix

[OpenClaw 文档]消息渠道--配置

📄 配对

1) 私信配对（入站聊天访问）

批准发送者

可复用发送者组

状态存储位置

2) 节点设备配对（iOS/Android/macOS/无头节点）

通过 Telegram 配对（推荐用于 iOS）

批准节点设备

可选的受信任 CIDR 节点自动批准

节点配对状态存储

说明

相关文档

📄 WhatsApp 群组消息

行为

配置示例（WhatsApp）

激活命令（仅所有者）

使用方法

测试 / 验证

已知注意事项

相关

📄 群组

新手简介（2 分钟）

可见回复

上下文可见性和允许列表

会话键

模式：个人私信 + 公开群组（单个 agent）

显示标签

群组策略

提及门控（默认）

群组/频道工具限制（可选）

群组允许列表

激活（仅所有者）

上下文字段

iMessage 细节

WhatsApp 系统提示

WhatsApp 细节

相关

📄 广播组

概览

使用场景

配置

基本设置

处理策略

完整示例

工作原理

消息流程

会话隔离

示例：隔离会话

最佳实践

兼容性

提供商

路由

故障排除

示例

API 参考

配置模式

字段

限制

未来增强

相关

📄 渠道路由

渠道与路由

关键术语

出站目标前缀

会话键形态（示例）

Main 私信路由固定

受保护的入站记录

路由规则（如何选择智能体）

广播群组（运行多个智能体）

配置概览

会话存储

WebChat 行为

回复上下文

相关内容

📄 渠道位置解析

文本格式

上下文字段

渠道说明

相关内容