广播群组 - 批量消息推送

Broadcast（广播）是 OpenClaw 的批量消息推送功能，允许你向多个群组或用户同时发送消息。适用于公告通知、定时报告、告警推送等场景。

什么是广播群组

Broadcast Group（广播群组）是一个逻辑上的消息接收者集合。你可以将多个渠道的群组或用户组织到一个广播组中，然后通过一次操作向所有成员推送消息。

                    ┌──────────────┐
                    │  Broadcast   │
                    │   Group      │
                    │  "全员通知"   │
                    └──────┬───────┘
                           │
           ┌───────────────┼───────────────┐
           │               │               │
    ┌──────┴──────┐ ┌──────┴──────┐ ┌──────┴──────┐
    │  Telegram   │ │   飞书       │ │  企业微信    │
    │  group_001  │ │  oc_all     │ │  wc_notice  │
    └─────────────┘ └─────────────┘ └─────────────┘

广播 vs 普通消息

普通消息是用户发起、Agent 回复的交互模式。广播是 Agent 主动发起的单向推送模式，不依赖用户消息触发。

配置广播群组

基础配置

在 openclaw.yaml 中定义 Broadcast Group：

yaml

broadcast:
  groups:
    # 全员通知组
    all-staff:
      name: "全员通知"
      description: "向所有员工推送重要通知"
      targets:
        - channel: feishu
          type: group
          id: "oc_all_staff"
        - channel: wecom
          type: group
          id: "wc_all_staff"
        - channel: dingtalk
          type: group
          id: "dt_all_staff"

    # 技术团队通知组
    tech-team:
      name: "技术团队"
      description: "技术相关通知和告警"
      targets:
        - channel: telegram
          type: group
          id: "group_tech"
        - channel: slack
          type: group
          id: "C04TECHTEAM"
        - channel: feishu
          type: group
          id: "oc_engineering"

    # 个人推送组（向特定用户的 DM 推送）
    vip-users:
      name: "VIP 用户"
      description: "重要客户个人通知"
      targets:
        - channel: telegram
          type: dm
          id: "user_vip_001"
        - channel: telegram
          type: dm
          id: "user_vip_002"
        - channel: whatsapp
          type: dm
          id: "phone_vip_003"

目标类型

类型	`type` 值	说明
群组	`group`	向群组发送消息，所有群组成员可见
私信	`dm`	向特定用户发送私信

发送广播

CLI 方式

bash

# 向广播组发送文本消息
openclaw broadcast send all-staff "系统将于今晚 22:00 进行维护升级，预计 2 小时完成。"

# 向广播组发送 Markdown 格式消息
openclaw broadcast send tech-team --format markdown "## 🚨 紧急告警\n\n生产服务器 CPU 使用率超过 90%，请相关同事尽快排查。"

# 从文件读取消息内容
openclaw broadcast send all-staff --file announcement.md

# 预览模式（不实际发送，仅显示将发送到哪些目标）
openclaw broadcast send all-staff "测试消息" --dry-run

# 输出示例：
# [DRY RUN] Would send to:
#   feishu  → group:oc_all_staff (全员群)
#   wecom   → group:wc_all_staff (企业微信全员群)
#   dingtalk → group:dt_all_staff (钉钉全员群)
# Total targets: 3

API 方式

bash

# 通过 REST API 发送广播
curl -X POST http://localhost:8080/api/broadcast \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group": "all-staff",
    "message": "系统维护通知：今晚 22:00-24:00 进行升级。",
    "format": "text"
  }'

json

// 响应示例
{
  "broadcastId": "bc_20260305_001",
  "status": "sent",
  "targets": 3,
  "delivered": 3,
  "failed": 0,
  "timestamp": "2026-03-05T14:30:00Z"
}

定时广播（Scheduled Broadcast）

配置定时任务

yaml

broadcast:
  schedules:
    # 每日晨报
    daily-report:
      group: tech-team
      cron: "0 9 * * 1-5"         # 工作日每天 09:00
      timezone: "Asia/Shanghai"
      template: daily-report       # 使用模板
      enabled: true

    # 每周周报
    weekly-summary:
      group: all-staff
      cron: "0 17 * * 5"          # 每周五 17:00
      timezone: "Asia/Shanghai"
      template: weekly-summary
      enabled: true

    # 每小时健康检查
    health-check:
      group: tech-team
      cron: "0 * * * *"           # 每小时整点
      timezone: "UTC"
      template: health-check
      enabled: true
      # 条件触发：仅在检查失败时才发送
      condition: "health.status != 'healthy'"

CLI 管理定时任务

bash

# 查看所有定时广播
openclaw broadcast schedules list

# 输出示例：
# Name              Group        Cron              Next Run           Status
# daily-report      tech-team    0 9 * * 1-5       tomorrow 09:00     enabled
# weekly-summary    all-staff    0 17 * * 5        Fri 17:00          enabled
# health-check      tech-team    0 * * * *         in 23 min          enabled

# 手动触发定时广播（不等待 Cron 时间）
openclaw broadcast schedules trigger daily-report

# 暂停/恢复定时广播
openclaw broadcast schedules pause daily-report
openclaw broadcast schedules resume daily-report

Template Messages（模板消息）

模板消息支持动态变量，可以在发送时填充实时数据。

定义模板

yaml

broadcast:
  templates:
    daily-report:
      format: markdown
      content: |
        ## 📊 每日晨报 — {{ date }}

        ### 系统状态
        - 服务可用性：{{ metrics.uptime }}%
        - 平均响应时间：{{ metrics.avgLatency }}ms
        - 活跃用户数：{{ metrics.activeUsers }}

        ### 待处理事项
        {% for item in todos %}
        - [ ] {{ item.title }} ({{ item.priority }})
        {% endfor %}

        ### 昨日摘要
        {{ summary }}

    weekly-summary:
      format: markdown
      content: |
        ## 📋 周报 — {{ weekRange }}

        ### 本周完成
        {% for item in completed %}
        - ✅ {{ item }}
        {% endfor %}

        ### 下周计划
        {% for item in planned %}
        - 📌 {{ item }}
        {% endfor %}

    health-check:
      format: text
      content: |
        🚨 健康检查异常
        服务：{{ service.name }}
        状态：{{ service.status }}
        时间：{{ timestamp }}
        详情：{{ service.message }}

模板变量来源

模板变量可以来自以下数据源：

yaml

broadcast:
  templates:
    daily-report:
      content: "..."
      variables:
        # 静态变量
        static:
          teamName: "工程团队"

        # 从 API 获取
        api:
          metrics:
            url: "http://monitoring-api/metrics/daily"
            method: GET
            headers:
              Authorization: "Bearer ${METRICS_API_KEY}"

        # 从命令执行获取
        command:
          summary:
            cmd: "openclaw agent run --agent reporter --prompt '生成昨日工作摘要'"

        # 内置变量（自动注入）
        # date, timestamp, weekRange 等时间相关变量自动可用

Rate Limiting（速率限制）

不同平台对消息发送频率有严格限制。OpenClaw 内置了 Rate Limiter（速率限制器）以确保合规。

平台限制参考

平台	限制	说明
Telegram	30 msg/sec (群组)	同一群组每秒最多 30 条
Slack	1 msg/sec (per channel)	每个频道每秒 1 条
WhatsApp	80 msg/sec (Business API)	取决于 API 等级
飞书	5 msg/sec (per bot)	单个机器人每秒 5 条
企业微信	20 msg/min (per bot)	单个机器人每分钟 20 条
钉钉	20 msg/min (per bot)	单个机器人每分钟 20 条

配置速率限制

yaml

broadcast:
  rateLimit:
    global:
      maxPerSecond: 10        # 全局每秒最多 10 条
      maxPerMinute: 200       # 全局每分钟最多 200 条

    perChannel:
      telegram:
        maxPerSecond: 25
      slack:
        maxPerSecond: 1
      feishu:
        maxPerSecond: 4
      wecom:
        maxPerMinute: 18      # 留一些余量
      dingtalk:
        maxPerMinute: 18

    # 超出限制时的行为
    onExceed: queue           # queue（排队等待）/ drop（丢弃）/ error（报错）
    queueMaxSize: 1000        # 队列最大长度
    queueTimeout: "5m"        # 队列超时时间

平台封禁风险

超出平台速率限制可能导致你的 Bot 被临时或永久封禁。OpenClaw 会自动适配已知限制，但如果你自定义了速率配置，请确保不超过平台的官方限制。

使用场景

1. 系统公告

bash

# 发送系统维护通知
openclaw broadcast send all-staff --format markdown \
  "## ⚠️ 系统维护通知\n\n**时间**：2026-03-06 22:00 - 2026-03-07 02:00\n**影响**：所有服务将暂时不可用\n**操作**：请提前保存工作内容"

2. 告警推送

yaml

# 结合监控系统自动推送告警
broadcast:
  schedules:
    alert-cpu:
      group: tech-team
      cron: "*/5 * * * *"        # 每 5 分钟检查
      template: health-check
      condition: "metrics.cpu > 90"
      enabled: true

3. 定时报告

yaml

# 每日自动生成并推送数据报告
broadcast:
  schedules:
    sales-report:
      group: sales-team
      cron: "0 18 * * 1-5"
      timezone: "Asia/Shanghai"
      template: sales-daily
      enabled: true

4. 事件通知

bash

# 通过 API 在 CI/CD 流水线中推送部署通知
curl -X POST http://localhost:8080/api/broadcast \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "group": "tech-team",
    "message": "✅ v2.3.1 已部署到生产环境\n提交者: @alice\n变更: 修复登录页面样式问题",
    "format": "text"
  }'

广播历史与监控

bash

# 查看广播发送历史
openclaw broadcast history

# 输出示例：
# Broadcast ID          Group        Targets   Delivered   Failed   Time
# bc_20260305_001       all-staff    3         3           0        14:30
# bc_20260305_002       tech-team    3         2           1        15:00
# bc_20260304_015       all-staff    3         3           0        09:00

# 查看失败详情
openclaw broadcast history bc_20260305_002 --details

# 输出示例：
# Target: slack:C04TECHTEAM
# Status: failed
# Error: rate_limited - Too many requests, retry after 30s
# Will retry at: 15:01

# 重试失败的广播
openclaw broadcast retry bc_20260305_002

最佳实践

始终使用 dry-run：首次发送广播前，先用 --dry-run 确认目标列表
配置合理的速率限制：避免因超出平台限制导致封禁
使用模板：定期发送的消息使用模板，保持格式一致
设置条件触发：定时告警类广播应设置条件，避免发送无意义的「一切正常」消息
监控发送状态：定期检查 openclaw broadcast history，关注失败记录

🇨🇳 中国用户须知

国内平台速率限制较严格： 飞书、企业微信、钉钉的消息频率限制明显低于海外平台。向大量群组推送时，建议将 onExceed 设置为 queue（排队模式），确保消息不丢失。

企业微信模板消息： 企业微信支持「模板卡片消息」，OpenClaw 会自动将 Markdown 格式转换为企业微信卡片格式，提供更好的阅读体验。

钉钉工作通知： 钉钉除了群聊消息外，还支持「工作通知」（OA 消息），可以直接推送到用户的钉钉消息列表。可通过设置 type: oa 使用此功能。

定时任务的时区： 国内用户请务必将定时广播的 timezone 设置为 "Asia/Shanghai"，避免因时区差异导致消息在错误的时间发送。

广播群组 - 批量消息推送 ​

什么是广播群组 ​

配置广播群组 ​

基础配置 ​

目标类型 ​

发送广播 ​

CLI 方式 ​

API 方式 ​

定时广播（Scheduled Broadcast） ​

配置定时任务 ​

CLI 管理定时任务 ​

Template Messages（模板消息） ​

定义模板 ​

模板变量来源 ​

Rate Limiting（速率限制） ​

平台限制参考 ​

配置速率限制 ​

使用场景 ​

1. 系统公告 ​

2. 告警推送 ​

3. 定时报告 ​

4. 事件通知 ​

广播历史与监控 ​

最佳实践 ​

广播群组 - 批量消息推送

什么是广播群组

配置广播群组

基础配置

目标类型

发送广播

CLI 方式

API 方式

定时广播（Scheduled Broadcast）

配置定时任务

CLI 管理定时任务

Template Messages（模板消息）

定义模板

模板变量来源

Rate Limiting（速率限制）

平台限制参考

配置速率限制

使用场景

1. 系统公告

2. 告警推送

3. 定时报告

4. 事件通知

广播历史与监控

最佳实践