Channels

OpenClaw 将回复路由回消息来源的渠道。模型不会选择渠道；路由是确定性的，由主机配置控制。 关键术语 渠道：whatsapp、telegram、discord、slack、signal、imessage、webchat。 AccountId：每个渠道的账户实例（在支持的情况下）。 AgentId：隔离的工作区 + 会话存储（“大脑”）。 SessionKey：用于存储上下文和控制并发的桶键。 会话键格式（示例） 私信会折叠到智能体的主会话： agent:<agentId>:<mainKey>（默认：agent: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 路由规则（如何选择智能体） 路由为每条入站消息选择一个智能体： 精确对端匹配（bindings 中的 peer.kind + peer.id）。 Guild 匹配（Discord）通过 guildId。 Team 匹配（Slack）通过 teamId。 账户匹配（渠道上的 accountId）。 渠道匹配（该渠道上的任意账户）。 默认智能体（agents.list[].default，否则取列表第一项，兜底为 main）。 匹配到的智能体决定使用哪个工作区和会话存储。 广播组（运行多个智能体） 广播组允许你为同一对端运行多个智能体，在 OpenClaw 正常回复时触发（例如：在 WhatsApp 群组中，经过提及/激活门控之后）。 配置： { broadcast: { strategy: "parallel", "[email protected]": ["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 将聊天渠道中分享的位置标准化为： 附加到入站消息体的可读文本，以及 自动回复上下文负载中的结构化字段。 目前支持： Telegram（位置图钉 + 地点 + 实时位置） WhatsApp（locationMessage + liveLocationMessage） Matrix（m.location 配合 geo_uri） 文本格式 位置以友好的行格式呈现，不带括号： 图钉： 📍 48.858844, 2.294351 ±12m 命名地点： 📍 Eiffel Tower — Champ de Mars, Paris (48.858844, 2.294351 ±12m) 实时分享： 🛰 Live location: 48.858844, 2.294351 ±12m 如果渠道包含标题/评论，会附加在下一行： 📍 48.858844, 2.294351 ±12m Meet here 上下文字段 当存在位置信息时，以下字段会被添加到 ctx 中： LocationLat（数字） LocationLon（数字） LocationAccuracy（数字，米；可选） LocationName（字符串；可选） LocationAddress（字符串；可选） LocationSource（pin | place | live） LocationIsLive（布尔值） 渠道说明 Telegram：地点映射到 LocationName/LocationAddress；实时位置使用 live_period。 WhatsApp：locationMessage.comment 和 liveLocationMessage.caption 作为标题行附加。 Matrix：geo_uri 解析为图钉位置；忽略海拔高度，LocationIsLive 始终为 false。

首先运行： openclaw doctor openclaw channels status --probe channels status --probe 会在检测到常见渠道配置错误时输出警告，并包含小型实时检查（凭据、部分权限/成员资格）。 渠道 Discord：/channels/discord#troubleshooting Telegram：/channels/telegram#troubleshooting WhatsApp：/channels/whatsapp#troubleshooting-quick Telegram 快速修复 日志显示 HttpError: Network request for 'sendMessage' failed 或 sendChatAction → 检查 IPv6 DNS。如果 api.telegram.org 优先解析为 IPv6 而主机缺少 IPv6 出站连接，请强制使用 IPv4 或启用 IPv6。参见 /channels/telegram#troubleshooting。 日志显示 setMyCommands failed → 检查到 api.telegram.org 的出站 HTTPS 和 DNS 可达性（常见于限制严格的 VPS 或代理环境）。

OpenClaw 在各平台上统一处理群聊：WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Microsoft Teams。 新手入门（2 分钟） OpenClaw"运行"在你自己的消息账户上。没有单独的 WhatsApp 机器人用户。如果你在一个群组中，OpenClaw 就可以看到该群组并在其中回复。 默认行为： 群组受限（groupPolicy: "allowlist"）。 除非你明确禁用提及限制，否则回复需要 @ 提及。 解释：允许列表中的发送者可以通过提及来触发 OpenClaw。 简而言之 私信访问由 *.allowFrom 控制。 群组访问由 *.groupPolicy + 允许列表（*.groups、*.groupAllowFrom）控制。 回复触发由提及限制（requireMention、/activation）控制。 快速流程（群消息会发生什么）： groupPolicy? disabled -> 丢弃 groupPolicy? allowlist -> 群组允许? 否 -> 丢弃 requireMention? 是 -> 被提及? 否 -> 仅存储为上下文 否则 -> 回复 如果你想… 目标 设置什么 允许所有群组但仅在 @ 提及时回复 groups: { "*": { requireMention: true } } 禁用所有群组回复 groupPolicy: "disabled" 仅特定群组 groups: { "<group-id>": { ... } }（无 "*" 键） 仅你可以在群组中触发 groupPolicy: "allowlist"、groupAllowFrom: ["+1555..."] 会话键 群组会话使用 agent:<agentId>:<channel>:group:<id> 会话键（房间/频道使用 agent:<agentId>:<channel>:channel:<id>）。 Telegram 论坛话题在群组 ID 后添加 :topic:<threadId>，因此每个话题都有自己的会话。 私聊使用主会话（或按发送者配置时使用各自的会话）。 群组会话跳过心跳。 模式：个人私信 + 公开群组（单智能体） 是的——如果你的"个人"流量是私信而"公开"流量是群组，这种方式效果很好。 ...

目标：让 Clawd 留在 WhatsApp 群组中，仅在被提及时唤醒，并将该对话线程与个人私信会话分开。 注意：agents.list[].groupChat.mentionPatterns 现在也被 Telegram/Discord/Slack/iMessage 使用；本文档重点介绍 WhatsApp 特定的行为。对于多智能体设置，为每个智能体设置 agents.list[].groupChat.mentionPatterns（或使用 messages.groupChat.mentionPatterns 作为全局回退）。 已实现的功能（2025-12-03） 激活模式：mention（默认）或 always。mention 需要被提及（通过 mentionedJids 的真实 WhatsApp @提及、正则表达式模式，或文本中任意位置的机器人 E.164 号码）。always 会在每条消息时唤醒智能体，但它应该只在能提供有意义价值时才回复；否则返回静默令牌 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 或 /think high（作为独立消息发送）等命令仅作用于该群组；个人私信状态不受影响。群组线程会跳过心跳。 上下文注入：仅待处理的群组消息（默认 50 条），即未触发运行的消息，会以 [Chat messages since your last reply - for context] 为前缀注入，触发行在 [Current message - respond to this] 下。已在会话中的消息不会重复注入。 发送者显示：每个群组批次现在以 [from: Sender Name (+E164)] 结尾，让 Pi 知道是谁在说话。 阅后即焚/一次性查看：我们在提取文本/提及之前会先解包这些消息，因此其中的提及仍会触发。 群组系统提示：在群组会话的第一轮（以及每当 /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 剥离文本正文中的可视 @ 时，显示名称提及仍能正常工作： ...

“配对"是 OpenClaw 的显式所有者批准步骤。它用于两个地方： 私信配对（谁被允许与机器人对话） 节点配对（哪些设备/节点被允许加入 Gateway 网关网络） 安全上下文：安全 1）私信配对（入站聊天访问） 当渠道配置为私信策略 pairing 时，未知发送者会收到一个短代码，他们的消息不会被处理，直到你批准。 默认私信策略记录在：安全 配对代码： 8 个字符，大写，无歧义字符（0O1I）。 1 小时后过期。机器人仅在创建新请求时发送配对消息（大约每个发送者每小时一次）。 待处理的私信配对请求默认上限为每个渠道 3 个；在一个过期或被批准之前，额外的请求将被忽略。 批准发送者 openclaw pairing list telegram openclaw pairing approve telegram <CODE> 支持的渠道：telegram、whatsapp、signal、imessage、discord、slack。 状态存储位置 存储在 ~/.openclaw/credentials/ 下： 待处理请求：<channel>-pairing.json 已批准允许列表存储：<channel>-allowFrom.json 将这些视为敏感信息（它们控制对你助手的访问）。 2）节点设备配对（iOS/Android/macOS/无头节点） 节点作为 role: node 的设备连接到 Gateway 网关。Gateway 网关创建一个必须被批准的设备配对请求。 批准节点设备 openclaw devices list openclaw devices approve <requestId> openclaw devices reject <requestId> 状态存储位置 存储在 ~/.openclaw/devices/ 下： pending.json（短期；待处理请求会过期） paired.json（已配对设备 + 令牌） 说明 旧版 node.pair.* API（CLI：openclaw nodes pending/approve）是一个单独的 Gateway 网关拥有的配对存储。WS 节点仍然需要设备配对。 相关文档 安全模型 + 提示注入：安全 安全更新（运行 doctor）：更新 渠道配置： Telegram：Telegram WhatsApp：WhatsApp Signal：Signal iMessage：iMessage Discord：Discord Slack：Slack

状态：生产就绪，支持机器人私聊和群组。使用 WebSocket 长连接模式接收消息。 内置插件 当前版本的 OpenClaw 已内置 Feishu 插件，因此通常不需要单独安装。 如果你使用的是较旧版本，或是没有内置 Feishu 的自定义安装，可手动安装： openclaw plugins install @openclaw/feishu 快速开始 添加飞书渠道有两种方式： 方式一：通过安装向导添加（推荐） 如果您刚安装完 OpenClaw，可以直接运行向导，根据提示添加飞书： openclaw onboard 向导会引导您完成： 创建飞书应用并获取凭证 配置应用凭证 启动网关 ✅ 完成配置后，您可以使用以下命令检查网关状态： openclaw gateway status - 查看网关运行状态 openclaw logs --follow - 查看实时日志 方式二：通过命令行添加 如果您已经完成了初始安装，可以用以下命令添加飞书渠道： openclaw channels add 然后根据交互式提示选择 Feishu，输入 App ID 和 App Secret 即可。 ✅ 完成配置后，您可以使用以下命令管理网关： openclaw gateway status - 查看网关运行状态 openclaw gateway restart - 重启网关以应用新配置 openclaw logs --follow - 查看实时日志 第一步：创建飞书应用 1. 打开飞书开放平台 访问 飞书开放平台，使用飞书账号登录。 ...