接入飞书机器人：Webhook / 事件回调 / 签名校验 / 安全边界

本章目标：把飞书消息作为 OpenClaw 的输入渠道之一，并确保安全边界清晰：谁能触发 Agent、触发什么工具、输出到哪里。

本章给出“通用接入架构与落地检查项”。飞书开放平台细节（权限、回调、签名字段）以官方文档为准。

1) 推荐架构（稳定 + 可审计）

飞书用户/群聊
   │
   │ 事件回调 / Webhook
   ▼
你自建的 Bot Gateway（轻量服务）
   │ 1) 验签 2) allowlist 3) 限流 4) 规范化输入
   ▼
OpenClaw Gateway
   │
   ▼
Agent + Tools + Skills
   │
   ▼
Bot Gateway 回消息到飞书

为什么不建议“飞书直连到 OpenClaw”：

• 外部消息面是不可信输入

• 你需要验签/过滤/限流/审计，这些更适合在一个薄中间层完成

2) 安全边界（必须有）

2.1 allowlist（用户/群/租户）

• 只允许你自己的 user_id 或指定群聊触发

• 默认拒绝未知来源

2.2 两段式执行（plan → execute）

对“有副作用”的动作（写文件、发消息、下单、提交 PR 等）：

1. 先让 Agent 产出计划与将要修改的文件列表

2. Bot Gateway 要求确认（按钮/关键字确认）后再执行

2.3 工具白名单

给不同的飞书会话配置不同的工具集合：

• 纯聊天：只允许模型推理

• 内容生产：允许 web_search/web_fetch/写入指定目录

• 自动化：允许 exec 但限制工作目录、限制命令

3) 最小闭环：把一条消息变成一次 Agent 调用

你需要定义一个“消息 → Prompt” 的规范化策略：

• 输入：用户文本 + 会话上下文（可选）

• 输出：

  • 直接回复（短文本）
  • 或者产出文件（文章/报告），再返回链接/摘要

建议统一 envelope：

{
  "channel": "feishu",
  "user": {"id": "...", "name": "..."},
  "chat": {"id": "...", "type": "group"},
  "text": "用户消息...",
  "meta": {"timestamp": 0, "messageId": "..."}
}

然后让 OpenClaw 执行：

• “把 envelope 渲染成 prompt”

• “按你的 Agent 设定执行”

4) 回调签名与重放防护

常见必做项：

• 验签（使用飞书提供的签名算法/字段）

• 校验时间戳窗口（例如 5 分钟内）

• messageId 去重（防止重放/重复投递）

5) 生产级工程建议

• 所有触发与输出写入审计日志：logs/feishu/<date>.jsonl

• 对外提供的入口放在反向代理后：HTTPS + 限流

• 如果需要公网回调：使用内网穿透时也要做 allowlist + 验签 + 限流

---

返回目录