40toRetire
主题

项目 · Log

OpenClaw 接入飞书：我现在这套手动配置怎么做

不讲大而全的 AI 助理。按我实际跑通的手动路线，把飞书机器人、WebSocket、权限、共享文件夹和文件上传的操作顺序写下来。

2026年8月6日

OpenClaw飞书AI Agent实操记录自动化

这篇只解决一件事：把已经部署好的 OpenClaw 接进飞书，让你能在飞书里和它聊天，并让它把资料写进文档或共享文件夹。

我走的是手动创建飞书自建应用的路线。现在这套配置已经跑了一段时间：私聊能收消息，群里 @ 它才回应，文档和共享文件夹可以操作。

如果你还没有一台能稳定运行 OpenClaw 的机器，先把机器和 Gateway 跑起来；这篇不重复服务器安装。下面从飞书开放平台开始。

先准备这四样东西

开始前，准备好：

  1. 一台正在运行 OpenClaw Gateway 的机器；
  2. 一个可以登录飞书开放平台的管理员账号；
  3. 一个测试用飞书群；
  4. 一个测试用文件夹——后面会共享给机器人。

不要一开始就把机器人拉进工作群，也不要直接给它整个云盘权限。先用测试群和测试文件夹把链路跑通。

第一步：在飞书开放平台创建自建应用

打开飞书开放平台，创建 企业自建应用。

创建后，先做三件事：

  • 在“应用能力”里启用 机器人；
  • 填好应用名称和头像，方便后面在飞书里识别；
  • 到“凭证与基础信息”找到 App ID 和 App Secret。

App ID 和 App Secret 只做一件事：交给服务器上的 OpenClaw 配置读取。

不要把它们放到：

  • Git 仓库；
  • 网站教程截图；
  • 聊天记录；
  • 发给别人的配置文件。

第二步：事件订阅选长连接，不配公网回调

飞书的事件订阅里有两条路线：回调地址和长连接。

我选的是 长连接（WebSocket）。

原因很简单：OpenClaw Gateway 主动与飞书建立连接，不需要为了接收消息再给飞书暴露一个公网 Webhook 地址、端口和回调路径。

在事件订阅页：

  1. 选择 使用长连接接收事件；
  2. 添加接收消息事件：im.message.receive_v1；
  3. 保存。

如果你看到其他教程要求填回调 URL、Verification Token、Encrypt Key，先停一下。那是 Webhook 路线需要的东西；长连接不需要照抄。

第三步：先申请最小权限，再按场景加

我一开始的目标是：在飞书发消息给机器人，让它整理资料，必要时写入文档或共享文件夹。

所以权限也按这个目标拆，不要一次全选。

只想先让机器人收发消息

先保证消息和会话相关权限能用，并完成消息事件订阅。然后发布应用，先验证私聊和群聊。

需要读写飞书文档

再补 Docx 文档相关权限。实际用起来会涉及：读取文档、创建文档、写入块内容，以及把生成的文档交还给你。

一个容易漏的点：机器人新建文档后，要确保你自己有编辑权限。最简单的验收不是“接口返回创建成功”，而是：

机器人创建文档
→ 你用自己的飞书账号打开
→ 能看到内容
→ 能编辑

需要操作云盘文件夹

再补云盘相关权限。

但先记住一条：机器人不是你的飞书个人账号，它没有“我的空间”。

所以不要让它直接往你的云盘根目录写文件，也不能在文件夹协作设置里直接把“应用/机器人”作为普通协作者加进去——我当时试过，这条路走不通。

我实际跑通的是下面这条：

你在飞书建一个专用群
→ 把机器人作为群机器人加进群
→ 你在飞书手动创建目标文件夹
→ 在文件夹的协作设置里，把这个群设为协作者
→ 机器人通过群获得该文件夹的访问权限

建议把这个群和文件夹都起清楚的名字，例如“OpenClaw 备份”。不要为了图方便把常用工作群或整个云盘共享出去。

验证时，先让机器人在目标文件夹里列一次目录，或创建一个测试子文件夹/上传一个小文件；然后你自己打开文件夹确认新内容在正确位置。跑通后再让它处理正式资料。

我之前就是这样给机器人共享过一个专门的备份文件夹，用于备份 Workspace 的部分文件。这条路只跑过一次，后来长期备份改用 GitHub；但这个“群 → 群机器人 → 文件夹共享”的权限链路，是实际验证过的。

第四步：把 App ID 和 App Secret 配到 OpenClaw

OpenClaw 的飞书通道需要一组应用凭证。常规做法是运行飞书通道的配置向导，选择手动配置，然后粘贴 App ID 和 App Secret。

下面是我当前正在运行的飞书通道配置，删掉了真实 App ID、Secret 和用户 ID。不同 OpenClaw 版本的字段组织可能略有变化，但关键项就是这些：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "connectionMode": "websocket",
      "dmPolicy": "allowlist",
      "allowFrom": ["ou_已脱敏的用户ID"],
      "groupPolicy": "open",
      "requireMention": true,
      "streaming": true,
      "accounts": {
        "default": {
          "appId": "cli_已脱敏",
          "appSecret": "***"
        }
      }
    }
  }
}

这几个字段怎么理解：

  • connectionMode: "websocket"：走长连接，不填公网回调地址；
  • dmPolicy: "allowlist" + allowFrom：只允许指定用户私聊机器人；
  • groupPolicy: "open"：机器人可以加入并服务群聊；
  • requireMention: true：但在群里必须 @ 它才回应；
  • streaming: true：飞书里会以流式卡片逐步显示较长回复。

这里最容易误读的是 groupPolicy: "open"。它不是“机器人会自动回复群里每一句话”；是否回应还受 requireMention: true 约束。我当前就是这套策略：私聊只允许白名单用户，群聊需要 @ 它才回答。

不要复制上面的 appId、appSecret 或 allowFrom。它们必须替换成你自己的应用凭证和用户 ID。

这样做不是为了增加设置项，而是为了避免两件麻烦事：陌生人直接把机器人当公开客服，以及机器人在群里每句话都插嘴。

配置改完后重启 Gateway。重启后，不要直接判断“应该好了”，按下面顺序测。

第五步：按顺序测试，不要一上来就排复杂问题

测试 A：私聊

在飞书里找到机器人，发一句：

你好，回复“飞书已接通”

如果没响应，按这个顺序看：

  1. Gateway 服务是否在运行；
  2. OpenClaw 状态里飞书通道是否为 ON / OK；
  3. 飞书应用是否已发布/审批生效；
  4. 消息事件 im.message.receive_v1 是否已订阅；
  5. 你的账号是否在私聊白名单中；
  6. App ID / App Secret 是否填错。

测试 B：群聊

新建一个测试群，把机器人拉进去，然后发送：

@机器人 你好，回复“群聊已接通”

群里没响应，优先看：

  • 机器人是否真的已加入该群；
  • 你是否直接 @ 了机器人；
  • 是否设置了“群聊必须 @ 才回复”；
  • 群聊策略有没有被设成禁用。

我建议先一直保留“需要 @”这个策略。等你确认某个固定群要让它自动参与，再只对那个群单独放开。

第六步：文档、共享文件夹、聊天附件，别混用

这一段是我后来才想清楚的。三个看起来都像“发文件”，实际用法完全不同。

场景 1：把调研结果写进飞书文档

适合：任务结果、会议纪要、专题资料、可继续编辑的内容。

做法：让机器人创建或更新一篇 Docx，然后把链接回给你。文档可以放在你事先共享给机器人的文件夹里。

验收：你打开文档，确认内容、归属和编辑权限。

场景 2：让机器人处理固定资料区

适合：一个长期资料库、项目文件夹、需要自动归档的共享目录。

做法：只共享一个专门文件夹给机器人。不要为了方便把整个云盘都开放。

验收：先让它列出目录或新建一个测试子文件夹；确认它只能看到你授权的那一块资料。

场景 3：把文件存进你自己的飞书云盘

适合：PDF、研报、备份文件，想沉到“我的空间”里自己管理。

这不是机器人 API 的强项。我后来用的是 lark-cli 的用户身份模式：

# 先进入文件所在目录，再用相对路径上传
lark-cli drive +upload --as user --file report.pdf

# 上传到指定文件夹
lark-cli drive +upload --as user \
  --file report.pdf \
  --folder-token <文件夹 token>

--as user 不是把你的 Token 手工交给命令，而是走飞书 OAuth 授权：CLI 发起授权，你在浏览器/飞书确认，之后它才可以代表你的账号调用云盘。

我踩过三个坑：

  • 参数是 --folder-token，不是 --folder；
  • --file 要用相对路径，绝对路径会报 unsafe file path；
  • 没有用户上传权限或授权过期时，会报 need_user_authorization。这时重新做用户授权，并确认有 drive:file:upload。

这台机器上的用户授权现在已经失效，所以以后真要再上传个人云盘，需要重新授权一次。长期备份我也不再依赖这条路，代码和重要资料还是放 GitHub。

场景 4：把 PDF 或图片直接发到聊天

适合：你需要马上下载、查看或转发的交付物。

OpenClaw 会把本地图片或文件上传成飞书消息附件再发出去。它不等于把文件归档到云盘。

我遇到过 MEDIA: 发 PDF 重复投递，所以现在把它只当“聊天交付”，不当“备份成功”的证据。

最小可用闭环：先跑这个

如果你是第一次接，不要急着做自动备份、知识库和一堆定时任务。先让它稳定跑通这一条：

飞书里发一条调研需求
→ 机器人回复整理结果
→ 你确认后，让它写进一篇测试文档或共享文件夹
→ 用自己的账号打开，检查内容和权限

跑通后，你已经验证了：消息入口、机器人权限、文档写入和人工验收。

后面再加能力时，先问自己：这次需要的是聊天交付、共享资料处理、个人云盘保存，还是版本化备份？把目标位置想清楚，很多“飞书权限怎么又报错”的问题就不会出现。

还在路上，先记下来。