OpenClaw 消息系统：多平台消息收发深度解析

七夜zippoe

414人浏览 · 2026-06-16 23:54:59

七夜zippoe · 2026-06-16 23:54:59 发布

摘要

OpenClaw 是一款自托管的多通道 AI 网关，能够将 Discord、Telegram、WhatsApp、飞书、Slack、Signal、iMessage、Microsoft Teams、QQ Bot 等数十个即时通讯平台统一接入，实现跨平台消息的收发与智能处理。本文深入剖析 OpenClaw 消息系统的核心架构，从消息通道与协议、消息发送机制、事件监听与回调、富媒体消息处理、跨平台格式转换、会话管理等维度展开全面解析，并结合三个实战案例——跨平台消息聚合中心、智能自动回复系统、富媒体消息推送管道——展示 OpenClaw 消息系统在生产场景中的工程实践。无论你是刚接触 OpenClaw 的新手，还是正在构建多平台消息集成方案的架构师，本文都将为你提供系统性的参考与可落地的代码示例。读完本文，你将掌握 OpenClaw 消息系统的全貌，能够独立设计并部署一个多平台消息集成方案。

一、消息系统架构：消息通道与协议 🏗️

1.1 Gateway 核心架构

OpenClaw 的核心是一个名为 Gateway 的自托管网关进程。Gateway 运行在你自己的硬件上，作为所有消息平台与 AI 智能体之间的桥梁。它采用事件驱动的架构设计，所有消息的流入与流出都经过 Gateway 的统一路由与处理。

从上图可以看出，Gateway 是消息路由的唯一入口。各平台的消息通过各自的通道协议进入 Gateway，经过路由判断、会话管理、格式转换和安全校验后，分发给对应的智能体处理。

1.2 内置通道与插件通道

OpenClaw 将通道分为内置通道和插件通道两大类：

分类	通道列表	接入方式
内置通道	Discord、Telegram、WhatsApp、Slack、Signal、iMessage、IRC、WebChat	开箱即用，配置即生效
捆绑插件	飞书、Microsoft Teams、Matrix、QQ Bot、Nostr、Zalo、Twitch、Nextcloud Talk、Synology Chat	无需额外安装，Gateway 加载时自动识别
外部插件	WeChat（微信）、LINE、Voice Call、Yuanbao	需要通过 ClawHub 安装或 npm 集成

这种分层设计的好处是显而易见的：核心通道零配置启动，扩展通道按需加载，既保持了 Gateway 进程本身的轻量性，又不牺牲消息覆盖的灵活性。每个通道都有独立的适配器模块，遵循统一的接口契约，确保新增通道不会影响已有通道的稳定性。如果你需要接入一个 OpenClaw 尚未内置的平台，也可以通过 ClawHub 社区查找第三方插件，或者按照插件开发规范自行编写适配器。

1.3 通道协议适配层

每个通道都有独立的协议适配器，负责将平台特有的消息格式转换为 OpenClaw 内部的统一消息模型。这种适配是双向的——入站消息被标准化为内部格式，出站消息则被还原为目标平台的原始协议。

以 WhatsApp 为例，它通过 Baileys Web 协议与 WhatsApp 服务器通信，而 Telegram 则使用 grammY 库对接 Bot API。不同协议的连接方式、认证机制、消息编码各有差异，但 Gateway 将这些复杂性封装在适配层内部，对上层的智能体完全透明。

这种协议适配层的设计，使得同一个智能体可以无缝地为多个平台提供服务，而不需要关心底层协议的细节。

二、消息发送机制 📤

2.1 message 工具详解

OpenClaw 的消息发送核心是 message 工具。智能体通过调用该工具向用户发送消息、管理消息状态、执行频道操作。message 工具支持多种操作类型（action），以下是最常用的几个：

Action	功能	典型用途
`send`	发送消息	向用户或频道发送文本、图片、文件
`read`	读取消息	拉取聊天记录、获取对话上下文
`edit`	编辑消息	修正已发送的消息内容
`react`	添加表情反应	对消息快速回应（👍、✅等）
`pin` / `unpin`	置顶/取消置顶	重要消息标记
`thread-reply`	线程回复	在 Slack/Discord 线程中回复

2.2 发送文本消息

最基本的用法是向指定目标发送文本消息。target 参数决定了消息的接收方，格式因平台而异：

# 示例：通过 message 工具发送文本消息
# target 格式说明：
#   WhatsApp/Signal: E.164 号码，如 "+8613800138000"
#   Telegram: chat_id 或 @username
#   Discord/Slack: channelId 或 user:ID
#   iMessage: Apple ID 或手机号

message_action = {
    "action": "send",
    "target": "+8613800138000",  # WhatsApp 目标号码
    "message": "你好！这是一条来自 OpenClaw 的测试消息。"
}

上述代码展示了消息发送的核心参数。target 采用 E.164 格式适配 WhatsApp，而对于 Telegram 则需要使用 chat_id。Gateway 会根据当前激活的通道自动选择正确的协议进行投递。

2.3 发送富媒体消息

OpenClaw 支持发送图片、音频、视频、文档等多种媒体类型。媒体可以通过 URL 引用或本地文件路径提供：

# 示例：发送图片消息
message_image = {
    "action": "send",
    "target": "tg:123456789",  # Telegram 用户
    "message": "这是今天的天气图表 🌤️",
    "media": "https://example.com/weather-chart.png"  # 图片URL
}

# 示例：发送文件消息
message_file = {
    "action": "send",
    "target": "+8613800138000",  # WhatsApp 用户
    "message": "这是你请求的报告",
    "filePath": "/workspace/reports/quarterly-2025.pdf",
    "filename": "2025年Q1季度报告.pdf"
}

# 示例：发送语音消息
message_voice = {
    "action": "send",
    "target": "discord:channel:987654321",  # Discord 频道
    "media": "/workspace/audio/notification.mp3",
    "asVoice": True  # 标记为语音消息
}

每种媒体类型在发送时会经过不同的处理管道。图片会被自动压缩至最大 2048px 边长（WhatsApp 通道），音频会以语音笔记（voice note）模式发送，文档则保留原始文件名并直接投递。媒体处理的最大限制如下：

媒体类型	大小限制	处理方式
图片	50 MB（压缩后）	自动缩放 + JPEG 重压缩
音频/语音	16 MB	语音笔记模式投递
视频	16 MB	原样传递
文档	100 MB	保留文件名，原样投递

2.4 发送带结构的消息

对于支持富文本的平台（如 Discord、Slack、Telegram），OpenClaw 支持通过 presentation 参数发送带按钮、选择器等交互元素的结构化消息：

# 示例：发送带按钮的交互式消息
message_buttons = {
    "action": "send",
    "target": "discord:channel:987654321",
    "presentation": {
        "title": "任务确认",
        "tone": "info",
        "blocks": [
            {
                "type": "text",
                "text": "你确定要执行此操作吗？"
            },
            {
                "type": "buttons",
                "buttons": [
                    {"label": "✅ 确认", "style": "success", "value": "confirm"},
                    {"label": "❌ 取消", "style": "danger", "value": "cancel"}
                ]
            }
        ]
    }
}

presentation 的 blocks 数组支持 text、context、divider、buttons、select 等类型，可以灵活组合出丰富的消息布局。对于不支持富文本的平台，OpenClaw 会自动降级为纯文本格式，确保跨平台兼容性。

三、消息接收处理 📥

3.1 事件监听机制

OpenClaw 采用事件驱动的消息接收模型。当用户在某个平台发送消息时，对应通道的适配器会将消息推送到 Gateway，Gateway 经过一系列处理后将其包装为标准事件分发给智能体。

整个消息接收流程可以用以下状态图描述：

3.2 DM 安全策略

消息接收的第一道防线是 DM 策略（dmPolicy）。OpenClaw 提供四种 DM 访问控制模式：

pairing（默认）：未知发送者会收到一次性配对码，需要用户在 Gateway 端确认授权
allowlist：仅允许 allowFrom 列表中的发送者
open：允许所有入站 DM（需设置 allowFrom: ["*"]）
disabled：忽略所有 DM

配置示例：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456:ABC-DEF",
      dmPolicy: "pairing",    // 默认配对模式
      allowFrom: ["tg:123456789"],  // allowlist 模式下的白名单
    },
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+8613800138000", "+8613900139000"],
    },
  },
}

这段配置展示了如何为不同通道设置不同的 DM 策略。Telegram 使用配对模式（更安全），WhatsApp 使用白名单模式（更便捷）。

3.3 群聊消息处理

群聊消息的处理比 DM 更复杂，需要考虑触发授权和上下文可见性两个维度。

触发授权决定了谁可以激活智能体：

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",  // 群聊策略：allowlist | open | disabled
      groups: {
        "*": { requireMention: true },  // 所有群默认需要 @提及
        "120363xxx@g.us": { requireMention: false },  // 特定群免提及
      },
      groupAllowFrom: ["+8613800138000"],  // 群内允许触发的人
    },
  },
}

上下文可见性则控制智能体能够看到多少群聊上下文信息。默认情况下，OpenClaw 保持"即收即用"的语义，不过滤引用和转发内容。

3.4 可见回复模式

OpenClaw 引入了**可见回复（visibleReplies）**的概念，控制智能体在群聊中的回复行为：

automatic（默认）：智能体的最终文本回复自动发送到群聊，适合较弱的模型或不需要精确控制回复的场景
message_tool：智能体必须显式调用 message(action=send) 才能在群聊中发送可见消息，适合需要精确控制何时发言的场景

{
  messages: {
    groupChat: {
      visibleReplies: "message_tool",  // 群聊必须用 message 工具发送
      unmentionedInbound: "room_event",  // 未提及的群消息作为静默上下文
    },
  },
}

message_tool 模式特别适合"常驻群"场景——智能体持续监听群消息但不主动发言，仅在需要时才通过 message 工具输出。这种模式下，未调用 message 工具的回复会被静默丢弃，不会打扰群聊。

四、富媒体消息处理 🖼️

4.1 入站媒体处理管道

当用户发送包含媒体的消息时，OpenClaw 会启动一个完整的媒体处理管道：

入站媒体被下载到临时文件后，根据类型进入不同的理解管道。图片会被视觉模型描述，音频会被转写为文字，视频则生成摘要描述。这些理解结果会注入到消息的 Body 字段中，使智能体能够"看到"和"听到"媒体内容。

4.2 媒体模板变量

OpenClaw 为入站媒体提供了便捷的模板变量，方便在命令和工作流中引用：

变量	含义	示例值
`{{MediaUrl}}`	入站媒体的伪 URL	`media://inbound/photo.jpg`
`{{MediaPath}}`	本地临时文件路径	`/tmp/openclaw-media/abc123.jpg`
`{{Transcript}}`	音频转写文本	“今天天气不错…”

当启用 Docker 沙箱时，MediaPath 会被重写为沙箱内的相对路径（如 media/inbound/photo.jpg），媒体文件会被自动复制到沙箱工作空间中。

4.3 媒体理解配置

默认情况下，OpenClaw 只处理第一个匹配的媒体附件。如果需要处理多个附件，可以配置 tools.media.<capability>.attachments：

{
  tools: {
    media: {
      image: {
        maxBytes: 10485760,  // 10 MB，图片理解上限
        attachments: 3,       // 最多处理3张图片
      },
      audio: {
        maxBytes: 20971520,  // 20 MB，音频转写上限
        attachments: 1,       // 只处理1条音频
      },
      video: {
        maxBytes: 52428800,  // 50 MB，视频描述上限
        attachments: 1,
      },
    },
  },
}

如果智能体的主要模型已经原生支持视觉能力（如 GPT-4o、Claude Sonnet），OpenClaw 会跳过独立的图片理解步骤，直接将原始图片传递给模型，避免重复处理和潜在的信息损失。

五、消息格式转换：跨平台兼容 🔄

5.1 格式转换的挑战

不同消息平台对富文本的支持差异巨大，这是跨平台消息系统面临的核心挑战之一：

特性	Discord	Telegram	WhatsApp	Slack	飞书
Markdown	✅ 完整	⚠️ 子集	❌ 极有限	✅ 完整	✅ 完整
按钮	✅	✅	✅	✅	✅
卡片/Embed	✅	✅	❌	✅	✅
表格	❌	❌	❌	❌	✅
线程	✅	✅	❌	✅	✅
反应/表情	✅	✅	✅	✅	✅
文件附件	✅	✅	✅	✅	✅

5.2 降级策略

OpenClaw 采用优雅降级策略处理跨平台格式差异：

Markdown 转换：完整 Markdown 在 WhatsApp 等平台降级为纯文本；表格在 Discord 中转为代码块或列表
交互元素降级：按钮和选择器在不支持的平台降级为带编号的文本选项
图片语法转换：Telegram 通道中，回复里的 Markdown 图片语法 ![alt](url) 会被自动转换为媒体回复
链接格式适配：Discord 中多个链接用 <> 包裹以抑制嵌入预览

# 示例：跨平台消息格式适配器
def adapt_message_for_platform(message_content, target_platform):
    """根据目标平台适配消息格式"""
    
    if target_platform == "whatsapp":
        # WhatsApp 不支持 Markdown，转为纯文本
        adapted = strip_markdown(message_content)
        # 表格转为列表格式
        adapted = table_to_list(adapted)
        # 移除嵌入预览
        adapted = remove_embeds(adapted)
        
    elif target_platform == "telegram":
        # Telegram 支持 Markdown 子集
        adapted = convert_to_telegram_md(message_content)
        # 图片语法转为媒体回复
        adapted = md_image_to_media(adapted)
        
    elif target_platform == "discord":
        # Discord 支持完整 Markdown
        # 多链接抑制嵌入
        adapted = wrap_links_no_embed(message_content)
        
    elif target_platform == "feishu":
        # 飞书支持完整富文本
        adapted = message_content  # 无需转换
        
    return adapted

这段代码展示了一个简化的跨平台消息适配器。实际中 OpenClaw 的格式转换器更复杂，覆盖了 HTML、Markdown、纯文本等多种输入输出格式的双向转换。

5.3 平台特性保留

在降级的同时，OpenClaw 也尽量保留各平台的独有特性。例如：

Discord Embed：发送到 Discord 的消息可以利用 Embed 结构展示更丰富的卡片式布局
Telegram 内联键盘：在 Telegram 中可以发送带内联键盘的交互式消息
WhatsApp 语音笔记：音频文件在 WhatsApp 中自动标记为语音笔记（ptt: true），收件人可以像播放语音消息一样播放
飞书卡片消息：在飞书通道中支持完整的交互式卡片消息

六、会话管理：私聊与群聊 💬

6.1 会话键（Session Key）设计

OpenClaw 的会话管理基于**会话键（Session Key）**机制，不同类型的会话有不同的键格式：

会话类型	会话键格式	说明
私聊（DM）	`agent:<agentId>:<mainKey>`	所有私聊合并到主会话
群聊	`agent:<agentId>:<channel>:group:<id>`	每个群独立会话
频道	`agent:<agentId>:<channel>:channel:<id>`	每个频道独立会话
论坛话题	`agent:<agentId>:<channel>:group:<id>:topic:<threadId>`	Telegram 论坛的每个话题独立

私聊会话合并到主会话（main session）是一个关键设计决策——这意味着用户在不同平台上与同一个智能体的私聊共享同一个上下文，实现了真正的跨平台会话连续性。

6.2 多智能体会话隔离

在多智能体模式下，每个智能体拥有完全隔离的会话空间：

{
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "coding", workspace: "~/.openclaw/workspace-coding" },
      { id: "alerts", workspace: "~/.openclaw/workspace-alerts" },
    ],
  },
  bindings: [
    { agentId: "main", match: { channel: "whatsapp", accountId: "default" } },
    { agentId: "coding", match: { channel: "discord", accountId: "coding" } },
    { agentId: "alerts", match: { channel: "telegram", accountId: "alerts" } },
  ],
}

每个智能体有独立的工作空间（workspace）、认证配置（auth profiles）和会话存储（sessions），互不干扰。消息通过**绑定（bindings）**规则路由到正确的智能体。

6.3 绑定路由优先级

当消息到达 Gateway 时，绑定匹配按以下优先级进行：

这种**最具体优先（most-specific-wins）**的路由策略确保了消息分发的精确性。在同一优先级内出现多个匹配时，配置文件中排在前面的绑定胜出。

6.4 群聊沙箱隔离

一个特别实用的模式是私聊走主机、群聊走沙箱。通过配置沙箱模式为 non-main，所有群聊会话自动在 Docker 沙箱中执行，而私聊会话保持在主机上运行：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",      // 非主会话使用沙箱
        scope: "session",       // 每个群/频道独立容器
        workspaceAccess: "none", // 沙箱无法访问工作空间
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: ["group:messaging", "group:sessions"],
        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
      },
    },
  },
}

这种模式下，群聊用户无法通过消息访问主机的文件系统或运行危险命令，而私聊用户则享有完整的工具访问权限。一个智能体、两种执行姿态，兼顾了便利性与安全性。

七、实战案例 1：跨平台消息聚合中心 🌐

7.1 场景描述

假设你是一个团队的负责人，团队使用 Discord 讨论技术、Telegram 接收告警、WhatsApp 进行日常沟通。你需要一个统一的消息聚合中心，将三个平台的重要消息汇总到一个智能体中处理。

7.2 架构设计

7.3 配置实现

{
  agents: {
    list: [
      {
        id: "aggregator",
        workspace: "~/.openclaw/workspace-aggregator",
      },
    ],
  },
  bindings: [
    // 所有通道消息路由到聚合 Agent
    { agentId: "aggregator", match: { channel: "discord", accountId: "default" } },
    { agentId: "aggregator", match: { channel: "telegram", accountId: "default" } },
    { agentId: "aggregator", match: { channel: "whatsapp", accountId: "default" } },
  ],
  channels: {
    discord: {
      accounts: {
        default: { token: "${DISCORD_TOKEN}" },
      },
      groups: {
        "123456789": { requireMention: true },
      },
    },
    telegram: {
      accounts: {
        default: { botToken: "${TELEGRAM_TOKEN}" },
      },
      dmPolicy: "allowlist",
      allowFrom: ["tg:123456789"],
    },
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+8613800138000"],
    },
  },
  messages: {
    groupChat: {
      visibleReplies: "message_tool",  // 仅在主动调用时发言
      unmentionedInbound: "room_event", // 静默监听群消息
    },
  },
}

这个配置将三个通道统一路由到一个聚合智能体。群聊模式下，智能体静默监听所有消息（room_event），只在需要时通过 message 工具发送汇总。这样既不会在群中造成消息骚扰，又能确保不遗漏重要信息。

八、实战案例 2：消息自动回复系统 🤖

8.1 场景描述

构建一个智能自动回复系统，根据消息内容自动分类处理：常见问题直接回复，技术问题转发到技术频道，紧急告警立即通知负责人。

8.2 工作流设计

8.3 实现代码

以下是一个基于 OpenClaw 智能体的自动回复逻辑伪代码，展示了消息分类和路由的核心思路：

# 自动回复系统核心逻辑
# 该逻辑运行在 OpenClaw Agent 的上下文中

class AutoReplySystem:
    """智能自动回复系统"""
    
    # FAQ 数据库（示例）
    FAQ_DATABASE = {
        "营业时间": "我们的营业时间是周一至周五 9:00-18:00",
        "联系方式": "客服电话：400-123-4567，邮箱：support@example.com",
        "退款政策": "购买后7天内可申请全额退款，请提供订单号",
    }
    
    # 紧急关键词
    URGENT_KEYWORDS = ["宕机", "故障", "紧急", "down", "urgent", "critical"]
    
    # 技术关键词
    TECH_KEYWORDS = ["API", "部署", "代码", "bug", "错误", "异常"]
    
    def process_message(self, message_text, sender, channel):
        """处理收到的消息并自动回复"""
        
        # Step 1: 检查是否为紧急消息
        if self._is_urgent(message_text):
            # 立即通知管理员
            self._notify_admin(message_text, sender)
            # 在原频道确认收到
            self._send_reply(
                channel, sender,
                f"⚠️ 已收到紧急消息，管理员已通知，将尽快处理。"
            )
            return
        
        # Step 2: 检查是否为常见问题
        faq_answer = self._match_faq(message_text)
        if faq_answer:
            self._send_reply(channel, sender, faq_answer)
            return
        
        # Step 3: 检查是否为技术问题
        if self._is_tech_question(message_text):
            # 转发到技术频道
            self._forward_to_tech_channel(message_text, sender)
            self._send_reply(
                channel, sender,
                "🔧 技术问题已转发到技术团队，预计30分钟内回复。"
            )
            return
        
        # Step 4: 默认回复
        self._send_reply(
            channel, sender,
            "收到您的消息，我们会尽快处理。如有紧急事项请标注【紧急】。"
        )
    
    def _is_urgent(self, text):
        return any(kw in text.lower() for kw in self.URGENT_KEYWORDS)
    
    def _match_faq(self, text):
        for question, answer in self.FAQ_DATABASE.items():
            if question in text:
                return answer
        return None
    
    def _is_tech_question(self, text):
        return any(kw in text.lower() for kw in self.TECH_KEYWORDS)
    
    def _notify_admin(self, message_text, sender):
        # 调用 message 工具发送紧急通知
        pass  # message(action=send, target=admin_whatsapp, message=...)
    
    def _send_reply(self, channel, sender, reply_text):
        # 调用 message 工具发送回复
        pass  # message(action=send, target=sender, message=reply_text)
    
    def _forward_to_tech_channel(self, message_text, sender):
        # 调用 message 工具转发到技术频道
        pass  # message(action=send, target=tech_channel, message=...)

这个自动回复系统通过分层判断逻辑，将消息分为紧急、FAQ、技术、普通四个级别，每个级别采取不同的处理策略。紧急消息双通道通知（原频道确认 + 管理员私聊推送），FAQ 直接命中回复，技术问题转发专业频道，普通消息兜底回复。

九、实战案例 3：富媒体消息推送管道 📊

9.1 场景描述

构建一个定时数据报告推送管道，每天自动生成数据图表和 PDF 报告，推送到飞书群和 Telegram 频道。支持图片、PDF 文档和交互式卡片消息。

9.2 架构设计

9.3 实现代码

# 富媒体消息推送管道
# 基于 OpenClaw message 工具实现跨平台富媒体推送

class MediaPushPipeline:
    """富媒体消息推送管道"""
    
    def push_daily_report(self, chart_path, pdf_path, summary_text):
        """推送每日报告到各平台"""
        
        # ---- 推送到飞书群 ----
        # 飞书支持完整的卡片消息 + 图片 + 文件
        self._push_to_feishu(chart_path, pdf_path, summary_text)
        
        # ---- 推送到 Telegram 频道 ----
        # Telegram 支持图片 + 文档 + Markdown 文字
        self._push_to_telegram(chart_path, pdf_path, summary_text)
        
        # ---- 推送到 WhatsApp ----
        # WhatsApp 支持图片 + 文档 + 纯文本
        self._push_to_whatsapp(chart_path, pdf_path, summary_text)
    
    def _push_to_feishu(self, chart_path, pdf_path, summary_text):
        """推送到飞书：使用卡片消息"""
        
        # 步骤1: 发送交互式卡片消息
        feishu_card = {
            "action": "send",
            "target": "feishu:chat:oc_xxxxxxx",
            "presentation": {
                "title": "📊 每日数据报告",
                "tone": "info",
                "blocks": [
                    {"type": "text", "text": summary_text},
                    {"type": "divider"},
                    {"type": "text", "text": "📅 报告日期：2025-06-16"},
                    {"type": "divider"},
                    {
                        "type": "buttons",
                        "buttons": [
                            {"label": "📄 查看完整报告", "style": "primary", "value": "view_report"},
                            {"label": "📈 查看趋势", "style": "secondary", "value": "view_trend"},
                        ]
                    }
                ]
            }
        }
        # 调用 message 工具发送卡片消息
        # message(**feishu_card)
        
        # 步骤2: 发送图表图片
        feishu_image = {
            "action": "send",
            "target": "feishu:chat:oc_xxxxxxx",
            "message": "今日数据趋势图",
            "media": chart_path,  # 本地图片路径
        }
        # message(**feishu_image)
        
        # 步骤3: 发送 PDF 报告
        feishu_pdf = {
            "action": "send",
            "target": "feishu:chat:oc_xxxxxxx",
            "message": "完整 PDF 报告",
            "filePath": pdf_path,
            "filename": "2025-06-16-每日报告.pdf",
        }
        # message(**feishu_pdf)
    
    def _push_to_telegram(self, chart_path, pdf_path, summary_text):
        """推送到 Telegram：图片 + 文档"""
        
        # Telegram 先发图片（带 caption）
        tg_image = {
            "action": "send",
            "target": "tg:-1001234567890",  # Telegram 频道 ID
            "message": f"📊 每日数据报告\n\n{summary_text}",
            "media": chart_path,
        }
        # message(**tg_image)
        
        # 再发 PDF 文档
        tg_pdf = {
            "action": "send",
            "target": "tg:-1001234567890",
            "message": "📄 完整 PDF 报告",
            "filePath": pdf_path,
            "filename": "daily-report-2025-06-16.pdf",
        }
        # message(**tg_pdf)
    
    def _push_to_whatsapp(self, chart_path, pdf_path, summary_text):
        """推送到 WhatsApp：图片 + 文档"""
        
        # WhatsApp 图片会自动压缩优化
        wa_image = {
            "action": "send",
            "target": "+8613800138000",
            "message": f"每日数据报告\n\n{summary_text}",
            "media": chart_path,
        }
        # message(**wa_image)
        
        # WhatsApp 文档保留原始文件名
        wa_pdf = {
            "action": "send",
            "target": "+8613800138000",
            "filePath": pdf_path,
            "filename": "2025-06-16-daily-report.pdf",
        }
        # message(**wa_pdf)

这个推送管道的核心思路是：同一份数据，根据目标平台的能力选择最佳的呈现方式。飞书用卡片消息呈现交互式报告，Telegram 用 Markdown + 图片 + 文档组合，WhatsApp 用纯文本 + 图片 + 文档。所有平台都能收到完整的信息，但每个平台都能以最自然的方式呈现。

9.4 媒体处理细节

在推送过程中，OpenClaw 会自动处理以下媒体转换：

图片压缩：WhatsApp 通道会自动将图片缩放至最大 2048px 边长并重新压缩为 JPEG，确保在移动端快速加载
文件名保留：文档发送时保留原始文件名（通过 filename 参数指定），方便接收方识别
语音笔记模式：如果推送的是音频文件，WhatsApp 通道会自动以语音笔记模式发送
GIF 播放：视频文件可以通过 gifPlayback: true 标记为 GIF 模式，在移动端循环内联播放

十、高级话题与最佳实践 🎯

10.1 Bot 循环防护

当两个机器人互相监听同一个频道时，可能出现无限回复循环。OpenClaw 提供了内置的 Bot 循环防护机制，自动检测并中断这种循环。在多机器人共存的频道中，建议始终启用此功能。

10.2 环境房间事件

对于需要智能体"常驻但不主动说话"的场景，可以使用环境房间事件（Ambient Room Events）模式。此模式下，未被提及的群聊消息作为静默上下文传递给智能体，智能体不会自动回复，但可以基于上下文在必要时主动发言。

10.3 多账号支持

OpenClaw 支持在同一 Gateway 中配置同一通道的多个账号。例如，你可以同时连接两个 WhatsApp 号码、两个 Telegram Bot，分别路由到不同的智能体：

{
  channels: {
    telegram: {
      accounts: {
        default: {
          botToken: "123456:ABC...",   // 主 Bot
          dmPolicy: "pairing",
        },
        alerts: {
          botToken: "987654:XYZ...",   // 告警 Bot
          dmPolicy: "allowlist",
          allowFrom: ["tg:123456789"],
        },
      },
    },
  },
}

10.4 CLI 消息发送

除了通过智能体调用 message 工具外，OpenClaw 还提供了命令行接口直接发送消息：

# 发送文本消息
openclaw message send --target "+8613800138000" --message "测试消息"

# 发送带媒体的消息
openclaw message send --media /workspace/chart.png --message "今日图表"

# 干跑模式（只显示将要发送的内容，不实际发送）
openclaw message send --target "tg:123456789" --message "测试" --dry-run

# JSON 输出模式
openclaw message send --target "+8613800138000" --message "测试" --json

CLI 方式特别适合在脚本和自动化工作流中使用，例如 CI/CD 管道中的通知推送。

10.5 安全最佳实践

最小权限原则：使用 allowlist 而非 open 模式，仅允许已知的发送者
群聊沙箱化：为群聊会话启用 Docker 沙箱，隔离主机资源访问
定期审计：使用 openclaw doctor 定期检查配置安全性和通道健康状态
密钥管理：API Token 等敏感信息使用环境变量注入，不要硬编码在配置文件中
可见回复控制：在公共群中使用 message_tool 模式，避免智能体意外泄露信息

十一、总结与展望 🔭

OpenClaw 的消息系统设计体现了几个核心工程理念：

协议无关性：智能体不需要关心底层消息平台的协议细节，Gateway 统一处理适配
优雅降级：跨平台消息格式差异通过自动降级策略解决，确保信息不丢失
会话连续性：跨平台私聊共享同一会话上下文，用户可以无缝切换平台继续对话
安全优先：从 DM 策略到群聊沙箱，多层安全机制保护主机和用户数据
灵活路由：基于绑定的路由系统支持多智能体、多账号的复杂部署场景

随着 AI 智能体的应用场景不断扩展，消息系统作为人机交互的核心界面，其重要性将持续增长。OpenClaw 通过统一的 Gateway 架构和灵活的消息处理管道，为开发者提供了一个强大而可靠的基础设施。

如果你正在构建多平台消息集成方案，或者希望让自己的 AI 助手同时服务于多个即时通讯平台，OpenClaw 无疑是一个值得深入探索的选择。更多信息请访问官方文档。

📌 参考链接：

OpenClaw 官方文档：https://docs.openclaw.ai

通道配置指南：https://docs.openclaw.ai/channels

多智能体路由：https://docs.openclaw.ai/concepts/multi-agent

群聊行为配置：https://docs.openclaw.ai/channels/groups

媒体支持文档：https://docs.openclaw.ai/nodes/images

Gateway 配置参考：https://docs.openclaw.ai/gateway/configuration

龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

从Copilot到Agent——我的开发工作流正在被颠覆（兼谈那个让LLM沉默的“螺旋数“）

摘要： 2026年AI Agent已能高效生成业务代码，但在涉及硬核数学物理（如各向异性热传导仿真）时仍表现糟糕，暴露出其缺乏深层数学理解的问题。突破点来自《螺旋数原理》提出的新代数系统——螺旋数（I²=−N），将旋转与伸缩耦合，简化了各向异性介质建模。开发者通过调整Prompt策略（先定义螺旋数代数环境），使Agent能正确推导各向异性拉普拉斯算子的求解器。作者指出，未来竞争力在于掌握Agent

龙虾开发者社区

2026 AI Agent技术趋势预测

本文基于当前AI Agent的技术瓶颈、全球头部科技公司的研发路线、产业端的投入方向，系统性预测2026年AI Agent领域的8个核心技术趋势，覆盖技术架构、落地场景、商业模式、监管体系4个维度，每个趋势都会包含技术实现路径、落地门槛、企业/个人布局建议，所有专业术语都会做通俗解释，哪怕你是没有技术背景的产品经理、创业者也能看懂。在讲趋势之前，我们先统一AI Agent的核心概念，避免认知偏差：

龙虾开发者社区

安全视角：AI Agent Harness Engineering 权限控制体系

术语简明定义生活化类比AI Agent具备自主感知、推理、决策、行动能力的人工智能实体，核心特征是可以调用外部工具完成复杂任务配备了工具包的执行专员Harness（挂载层）介于Agent推理内核和外部工具/资源之间的中间层，负责工具挂载、请求转发、权限校验、审计回溯等核心能力带智能锁的战术腰带，所有工具都挂在腰带上，使用前必须过锁的校验Harness Engineering 权限控制体系。

龙虾开发者社区

所有评论(0)

查看更多评论

七夜zippoe

@sinat_41617212

已为社区贡献41条内容

OpenClaw 消息系统：多平台消息收发深度解析

七夜zippoe

目录

摘要

一、消息系统架构：消息通道与协议 🏗️

1.1 Gateway 核心架构

1.2 内置通道与插件通道

1.3 通道协议适配层

二、消息发送机制 📤

2.1 message 工具详解

2.2 发送文本消息

2.3 发送富媒体消息

2.4 发送带结构的消息

三、消息接收处理 📥

3.1 事件监听机制

3.2 DM 安全策略

3.3 群聊消息处理

3.4 可见回复模式

四、富媒体消息处理 🖼️

4.1 入站媒体处理管道

4.2 媒体模板变量

4.3 媒体理解配置

五、消息格式转换：跨平台兼容 🔄

5.1 格式转换的挑战

5.2 降级策略

5.3 平台特性保留

六、会话管理：私聊与群聊 💬

6.1 会话键（Session Key）设计

6.2 多智能体会话隔离

6.3 绑定路由优先级

6.4 群聊沙箱隔离

七、实战案例 1：跨平台消息聚合中心 🌐

7.1 场景描述

7.2 架构设计

7.3 配置实现

八、实战案例 2：消息自动回复系统 🤖

8.1 场景描述

8.2 工作流设计

8.3 实现代码

九、实战案例 3：富媒体消息推送管道 📊

9.1 场景描述

9.2 架构设计

9.3 实现代码

9.4 媒体处理细节

十、高级话题与最佳实践 🎯

10.1 Bot 循环防护

10.2 环境房间事件

10.3 多账号支持

10.4 CLI 消息发送

10.5 安全最佳实践

十一、总结与展望 🔭

所有评论(0)

温馨提示：您尚未绑定手机号

七夜zippoe