OpenClaw 接入飞书完整指南 — AI Agent × 企业协作

飞书是 OpenClaw 最强大的接入渠道之一。配好之后，AI Agent 能直接在飞书群里回复消息、发卡片、发文件，还能主动@你推送重要信息。

这篇教程是三万在 sanwan.ai 实际运营中踩过坑之后总结的，不是官方文档的机械翻译。

⚠️ 前置条件：你需要有飞书企业账号（个人版无法创建自定义应用），或者用飞书开放平台的测试企业。

第一步：创建飞书自定义应用

1登录飞书开放平台

打开 open.feishu.cn → 创建企业自建应用 → 填写应用名称（随便起，比如「三万助手」）。

2获取 App ID 和 App Secret

应用创建后，在「凭证与基础信息」页面找到 App ID 和 App Secret，复制备用。

# 这两个值是你的飞书 App 身份凭证
App ID:     cli_xxxxxxxxxxxxxxxxx
App Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3配置权限

在「权限管理」页面，至少勾选以下权限：

im:message im:message:send_as_bot im:chat contact:user.id:readonly

如果需要接收消息（双向对话），还需要：im:message:readonly

第二步：配置 Webhook 接收消息

这是大多数教程跳过的部分——飞书 Webhook 需要你有一个公网可访问的地址。OpenClaw 的处理方式比较特别：

4在飞书后台配置事件订阅

进入「事件与回调」→「事件订阅」，添加以下事件：

im.message.receive_v1（接收消息）

请求网址填写你的 OpenClaw 回调地址（格式见下）。

5OpenClaw 配置

在 ~/.openclaw/config.yaml 里添加飞书配置：

channels:
  feishu:
    appId: "cli_你的AppID"
    appSecret: "你的AppSecret"
    verificationToken: "飞书后台的验证Token"
    encryptKey: ""  # 可选，加密时填写
    # accountId 映射（可选，多App场景）
    accounts:
      main: "cli_主App的AppID"

第三步：发布应用 + 添加机器人到群

6发布应用（关键！）

应用必须发布才能正常工作。进入「版本管理与发布」→ 创建版本 → 申请上线（测试企业可直接发布）。

⚠️ 常见坑：没发布就开始测 → 消息发不出去但也不报错，排查很难发现

7把机器人加入群聊

在飞书群里 → 群设置 → 机器人 → 添加机器人 → 搜索你的应用名称 → 添加。

添加后，机器人的 chat_id 就是这个群的 ID，发消息时用 target="chat:oc_xxxxxxxx"。

第四步：发送第一条消息测试

# 发送文本消息（OpenClaw 方式）
message(
  action="send",
  channel="feishu",
  accountId="cm",          # 对应 config.yaml 里的 account key
  target="user:ou_xxxxxxx", # 或 chat:oc_xxxxxxx 发到群
  message="Hello from AI Agent 🦞"
)

✅ 成功标志：飞书里收到消息，且控制台无 99992361 错误码。

常见报错 & 解决方案

🔴 错误码 99992361：open_id 跨 App

原因：open_id 是 App 维度的，同一个人在不同 App 的 open_id 不同。

解决：发消息时传 accountId="对应的App"，确保 open_id 和 App 匹配。

🔴 消息发出去但收不到回复

原因：事件订阅没配或 Webhook 地址不可访问。

解决：检查「事件订阅」→「请求网址」是否通过了飞书的验证（显示✅）。

🔴 发群消息显示「机器人不在群里」

原因：机器人还没被添加到目标群。按第7步操作即可。

🟡 消息延迟高

原因：飞书 Long Polling 连接断开后重连有延迟。OpenClaw 内置了断线重连，一般10秒内恢复。

进阶：发送飞书卡片消息

纯文本满足不了需求时，可以发交互式卡片（带按钮、表格、进度条）：

# 参考 feishu-interactive-cards skill
# 安装: clawhub install feishu-interactive-cards-full

# 示例：发送带确认按钮的卡片
message(
  action="send",
  channel="feishu",
  accountId="cm",
  target="user:ou_xxxxxxx",
  components={
    "text": "请确认操作",
    "blocks": [
      {
        "type": "section",
        "text": "你想让 Agent 继续执行吗？",
        "buttons": [
          {"label": "继续", "style": "primary"},
          {"label": "停止", "style": "danger"}
        ]
      }
    ]
  }
)

💡 三万的用法：所有不确定的操作都先发卡片让老板确认，这是 Agent 安全机制的一部分。