#第 7 章：飞书集成与消息自动化

难度: ⭐⭐ 基础 | 预计阅读: 18 分钟 | 前置章节: 第 2 章

本章介绍如何将 OpenClaw Agent 与飞书（Feishu/Lark）集成，实现消息自动接收、处理和发送，支持私聊和群聊场景。飞书通道是 OpenClaw 在企业环境中最常用的消息集成方式之一。

#7.1 飞书集成概述

OpenClaw 原生支持飞书消息通道，通过 WebSocket 连接实现实时消息收发，无需公网回调地址。

#架构

飞书 App ←── WebSocket ──→ OpenClaw Gateway ──→ Agent
              双向实时通信

#支持的功能

#集成优势

• 零公网依赖：WebSocket 模式无需暴露公网回调 URL
• 实时双向：消息延迟通常 < 1 秒
• 企业级安全：基于飞书应用权限体系，支持细粒度控制

#7.2 飞书 App 创建与配置

#Step 1：创建飞书应用

1. 访问 飞书开放平台
2. 点击「创建企业自建应用」
3. 填写应用名称（如 OpenClaw Assistant）和描述
4. 创建完成后，在「凭证与基础信息」获取 App ID 和 App Secret

#Step 2：配置消息能力

在飞书开放平台的应用配置中：

1. 进入「添加应用能力」→ 开启「机器人」
2. 配置 Bot 相关权限：
   • im:message — 获取与发送单聊、群聊消息
   • im:message.group_at_msg — 接收群聊 @消息
   • im:resource — 接收和发送文件/图片
3. 在「事件与回调」中选择 WebSocket 模式（推荐，无需配置回调 URL）
4. 发布应用并设置可用范围

#需要开通的权限清单

#Step 3：配置 OpenClaw

编辑 ~/.openclaw/openclaw.json，添加飞书通道配置：

{
  "channels": {
    "feishu": {
      "appId": "<your-app-id>",
      "appSecret": "<your-app-secret>",
      "enabled": true,
      "connectionMode": "websocket"
    }
  },
  "plugins": {
    "entries": {
      "feishu": { "enabled": true }
    }
  }
}

export FEISHU_APP_ID="cli_xxxx"
export FEISHU_APP_SECRET="xxxx"
```text

#Step 4：验证连接

# 启动 Gateway
openclaw gateway start

# 查看连接状态
openclaw gateway status

在飞书中找到 Bot，发送一条消息（如 "你好"），如果 Agent 正常回复，说明集成成功。

#7.3 私聊与群聊

#私聊模式

Agent 直接响应所有私聊消息，适合作为个人 AI 助手使用。

配置策略：

{
  "channels": {
    "feishu": {
      "dmPolicy": "open"
    }
  }
}

dmPolicy 支持以下值：

#群聊模式

群聊中需要 @提及 才会触发 Agent 响应，避免干扰正常群聊。

{
  "channels": {
    "feishu": {
      "groupPolicy": "open",
      "requireMention": true
    }
  }
}

群聊使用示例：

@OpenClaw Assistant 帮我查一下今天的服务器状态
@OpenClaw Assistant 搜索 "Kubernetes 最佳实践"

#Emoji 回应

Agent 可以使用 emoji 对消息做出快速回应，适用于以下场景：

#7.4 消息自动化

结合 Cron 定时任务，可以实现飞书消息的自动推送，打造真正的自动化工作流。

#自动化流程

Cron 定时触发 → Agent 执行任务 → 生成报告 → 飞书通道发送

#示例：每日报告推送

通过定时任务自动生成日报并推送到飞书：

1. Cron 在每天早上 6:00 触发 Agent 会话
2. Agent 自动执行数据分析任务
3. 汇总生成报告内容
4. 通过飞书通道发送给指定用户或群组

#配置定时推送

在 ~/.openclaw/cron/jobs.json 中添加：

{
  "name": "每日摘要推送",
  "schedule": "0 6 * * *",
  "timezone": "Asia/Shanghai",
  "action": "归纳昨日日志，发送飞书摘要"
}

#主动发送消息

除了被动回复，Agent 也可以主动向飞书用户或群组发送消息：

# 向指定用户发送消息
openclaw message send \
  --channel feishu \
  --target "<open_id>" \
  --message "今日任务已完成，共处理 12 条数据"

# 向群组发送消息
openclaw message send \
  --channel feishu \
  --target "<chat_id>" \
  --message "📊 每日报告已生成，请查收"

#飞书消息格式

OpenClaw 支持多种飞书消息格式：

#7.5 安全与权限控制

#访问白名单

通过 ~/.openclaw/credentials/feishu-default-allowFrom.json 控制哪些用户可以与 Bot 交互：

{
  "allowFrom": [
    "ou_xxxxxxxxxxxx",
    "ou_yyyyyyyyyyyy"
  ]
}

#配对认证

首次使用时，用户需要通过配对码认证。配对信息存储在 ~/.openclaw/credentials/feishu-pairing.json 中：

# 查看当前配对设备
cat ~/.openclaw/devices/paired.json

# 查看待配对请求
cat ~/.openclaw/devices/pending.json

#安全最佳实践

• 生产环境使用 allowlist 策略限制访问
• 定期审查已配对设备列表
• App Secret 不要硬编码在配置文件中
• 启用飞书应用的 IP 白名单功能

#进阶：飞书消息通道架构

理解飞书集成的内部架构有助于排查消息投递问题和优化性能：

消息从飞书到 Agent 的完整链路：飞书服务器 → Browser Relay → Delivery Queue → Channel Router → Agent。

#进阶：飞书消息通道架构

理解飞书集成内部架构有助于排查投递问题：

#实操练习

#练习 1：创建飞书应用并完成基础集成

1. 登录 飞书开放平台，创建一个企业自建应用。
2. 获取 App ID 和 App Secret，配置到 openclaw.json：

   # 编辑配置
   nano ~/.openclaw/openclaw.json
   # 在 channels.feishu 中填入 appId 和 appSecret

3. 开启「机器人」能力，添加必要权限并发布应用。
4. 启动 Gateway 并验证连接：
   ```bash
   openclaw gateway start
   openclaw gateway status

5. 在飞书中向 Bot 发送 "你好"，确认收到回复。

#练习 2：配置群聊 @响应

1. 将 Bot 添加到一个飞书群组中。
2. 在 openclaw.json 中配置群聊策略：

   {
     "channels": {
       "feishu": {
         "groupPolicy": "open",
         "requireMention": true
       }
     }
   }

3. 在群聊中发送不带 @ 的消息，确认 Bot 不会响应。
4. 发送 `@Bot 名称 今天天气怎么样 `，确认 Bot 正常回复。
5. 测试不同类型的请求（搜索、文件处理等）。

### 练习 3：配置定时消息推送

1. 创建一个定时任务，每 5 分钟发送一次测试消息：
   ```json
   {
     "name": "测试推送",
     "schedule": "*/5 * * * *",
     "timezone": "Asia/Shanghai",
     "action": "发送飞书消息: 定时推送测试，当前时间 $(date)"
   }

2. 将配置写入 ~/.openclaw/cron/jobs.json。
3. 等待触发，确认飞书收到推送消息。
4. 验证无误后，将 schedule 改为实际需要的时间。
5. （扩展）配置一个每日早报推送：汇总昨日日志 + 今日待办。

#常见问题 (FAQ)

Q1: 飞书连接失败，Gateway 报错怎么办？

A: 按以下步骤排查：

# 1. 确认 App ID 和 Secret 正确
grep -A5 '"feishu"' ~/.openclaw/openclaw.json

# 2. 检查 Gateway 状态
openclaw gateway status

# 3. 检查网络连通性
curl -I https://open.feishu.cn

常见原因：应用未发布、权限未审批、Secret 输入有误、网络不通。

Q2: 群聊中 Bot 不响应 @消息？

A: 检查以下几点：

1. 确认 openclaw.json 中 requireMention 设为 true
2. 确认应用已开通 im:message.group_at_msg 权限
3. 确认 Bot 已被正确添加到群组中（而非仅是群成员）
4. 检查 @时使用的是 Bot 的实际名称

Q3: 消息延迟很高怎么优化？

A: WebSocket 模式下正常延迟应 < 1 秒。如果延迟高：

• 检查服务器与飞书之间的网络质量：ping open.feishu.cn
• 确认使用的是 WebSocket 模式而非 HTTP 回调模式
• 检查 Agent 负载——高并发时任务排队会导致响应延迟
• 使用 openclaw doctor 诊断系统健康状态

Q4: 如何向多个群组同时推送消息？

A: 在 Cron Action 中指定多个目标群的 chat_id，或使用脚本循环发送：

for chat_id in "oc_xxx" "oc_yyy" "oc_zzz"; do
  openclaw message send \
    --channel feishu \
    --target "$chat_id" \
    --message "📢 广播消息内容"
done

Q5: 如何接收和处理飞书发来的文件/图片？

A: OpenClaw 会自动将飞书消息中的文件和图片下载到 ~/.openclaw/media/inbound/ 目录。Agent 可以在对话中引用这些文件进行处理（如图片分析、文档总结等）。确保应用已开通 im:resource 权限。

#参考资料

• 飞书开放平台文档 — 飞书应用开发官方文档
• 飞书消息类型说明 — 消息格式与发送 API
• OpenClaw 飞书集成讨论 — 社区讨论与功能提案
• feishu-OpenClaw 社区项目 — 第三方飞书集成方案参考
• Clawdbot Lark Integration Guide（视频） — 视频教程演示

#本章小结

• 飞书集成概述：理解 WebSocket 架构和支持的功能矩阵
• App 创建与配置：掌握从创建飞书应用到 OpenClaw 配置的完整流程
• 私聊与群聊：灵活配置 DM 策略和群聊 @响应规则
• 消息自动化：结合 Cron 实现定时推送和主动发送
• 安全与权限：通过白名单和配对认证保障企业级安全
• 遇到问题时，善用 openclaw doctor 进行诊断。

下一章：单 Gateway 多 Agent 配置与管理