Skip to content
Back to search

feishu-openclaw

Connect 飞书Feishu/Lark bot to openclaw (formerly Clawdbot) — no public server, no domain, no ngrok needed. 稳定免安装、共需5 分钟,2.2更新支持照片文件视频等

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alexanys--feishu-openclaw/badge.svg)](/listings/alexanys--feishu-openclaw)

HTML

<a href="/listings/alexanys--feishu-openclaw"><img src="/api/listings/alexanys--feishu-openclaw/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

| 方式 | 说明 | 链接 | |------|------|------| | **① 一键安装** | 让 Clawdbot 帮你安装插件 | [openclaw-feishu](https://github.com/AlexAnys/openclaw-feishu) | | **② npm 命令** | `clawdbot plugins install feishu-openclaw` | [npm](https://www.npmjs.com/package/feishu-openclaw) | | **③ 独立桥接** ⬅️ | 本项目,独立进程 | 见下方 |

插件 vs 桥接

| | 插件 (①②) | 桥接 (③) | |---|---|---| | 进程 | 1 个(内置 Gateway) | 2 个(独立) | | 崩溃 | 影响 Gateway | **互不影响** | | 适合 | 日常使用 | **生产/隔离部署** |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 78 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: feishu-bridge
  3. description: Connect a Feishu (Lark) bot to Clawdbot via WebSocket long-connection. No public server, domain, or ngrok required. Use when setting up Feishu/Lark as a messaging channel, troubleshooting the Feishu bridge, or managing the bridge service (start/stop/logs). Covers bot creation on Feishu Open Platform, credential setup, bridge startup, macOS launchd auto-restart, and group chat behavior tuning.
  4. ---
  5. # Feishu Bridge
  6. Bridge Feishu bot messages to Clawdbot Gateway over local WebSocket.
  7. ## Architecture
  8. ```
  9. Feishu user → Feishu cloud ←WS→ bridge.mjs (local) ←WS→ Clawdbot Gateway → AI agent
  10. ```
  11. - Feishu SDK connects outbound (no inbound port / public IP needed)
  12. - Bridge authenticates to Gateway using the existing gateway token
  13. - Each Feishu chat maps to a Clawdbot session (`feishu:<chatId>`)
  14. ## Setup
  15. ### 1. Create Feishu bot
  16. 1. Go to [open.feishu.cn/app](https://open.feishu.cn/app) → Create self-built app → Add **Bot** capability
  17. 2. Enable permissions: `im:message`, `im:message.group_at_msg`, `im:message.p2p_msg`
  18. 3. Events: add `im.message.receive_v1`, set delivery to **WebSocket long-connection**
  19. 4. Publish the app (create version → request approval)
  20. 5. Note the **App ID** and **App Secret**
  21. ### 2. Store secret
  22. ```bash
  23. mkdir -p ~/.clawdbot/secrets
  24. echo "YOUR_APP_SECRET" > ~/.clawdbot/secrets/feishu_app_secret
  25. chmod 600 ~/.clawdbot/secrets/feishu_app_secret
  26. ```
  27. ### 3. Install & run
  28. ```bash
  29. cd <skill-dir>/feishu-bridge
  30. npm install
  31. FEISHU_APP_ID=cli_xxx node bridge.mjs
  32. ```
  33. ### 4. Auto-start (macOS)
  34. ```bash
  35. FEISHU_APP_ID=cli_xxx node setup-service.mjs
  36. launchctl load ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist
  37. ```
  38. ## Diagnostics
  39. ```bash
  40. # Check service
  41. launchctl list | grep feishu
  42. # Logs
  43. tail -f ~/.clawdbot/logs/feishu-bridge.err.log
  44. # Stop
  45. launchctl unload ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist
  46. ```
  47. ## Group chat behavior
  48. Bridge replies only when: user @-mentions the bot, message ends with `?`/`?`, contains request verbs (帮/请/分析/总结…), or calls the bot by name. Customize the name list in `bridge.mjs` → `shouldRespondInGroup()`.
  49. ## Environment variables
  50. | Variable | Required | Default |
  51. |---|---|---|
  52. | `FEISHU_APP_ID` | ✅ | — |
  53. | `FEISHU_APP_SECRET_PATH` | — | `~/.clawdbot/secrets/feishu_app_secret` |
  54. | `CLAWDBOT_CONFIG_PATH` | — | `~/.clawdbot/clawdbot.json` |
  55. | `CLAWDBOT_AGENT_ID` | — | `main` |
  56. | `FEISHU_THINKING_THRESHOLD_MS` | — | `2500` |
README.md · README · 396 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # feishu-openclaw (桥接)
  2. 飞书 × AI 助手 **独立桥接器** — 无需公网服务器
  3. Feishu × AI Assistant **standalone bridge** — no public server required
  4. ---
  5. > ### 📚 装好了飞书桥接,然后做什么?
  6. >
  7. > 查看 **[OpenClaw 中文用例 & 案例合集](https://github.com/AlexAnys/awesome-openclaw-usecases-zh)** — 46 个经过验证的真实场景,涵盖自动化办公、内容创作、运维、AI 助理、知识管理,新手友好。
  8. >
  9. > 飞书 × OpenClaw 的专属用例也在里面 🦞
  10. ---
  11. ## 🆕 飞书官方开源 Lark CLI(2026.3.28)
  12. 飞书官方开源了 [Lark CLI](https://github.com/larksuite/cli)(MIT 协议)——让你的 AI Agent 直接操作飞书:搜文档、读妙记、查日历、发消息、操作多维表格…… **2500+ API,11 个业务领域,19 个 AI Agent Skills**。
  13. 安装只需要告诉你的 Agent 一句话,你只需要点一个授权链接。
  14. 👉 **[Lark CLI 上手指南](docs/lark-cli-guide.md)**
  15. ---
  16. ## 你应该用哪个?(插件 vs 独立桥接)
  17. - 想要**最省事、一键安装**:用插件版(OpenClaw/Clawdbot)→ <https://github.com/AlexAnys/openclaw-feishu>
  18. - 想要**媒体最稳(收图/收视频/生图回传)、并且和 Gateway 进程隔离**:用本仓库(独立桥接)
  19. > 建议:先用插件跑通,再按需求升级到桥接;或者直接用桥接(更稳,但需要你自己维护一个进程/服务)。
  20. ## 🔥 2026.02.02 重磅更新(强烈建议所有旧版本升级)
  21. 这次更新解决了“能聊天但媒体不通”的所有相关痛点:
  22. - ✅ **飞书传送图片 → AI 真正能看图**(自动根据 `image_key` 下载并以图片附件喂给模型)
  23. - ✅ **飞书传送视频/文件 → 桥接可接收并下载**(会把本地 `file://...` 路径传给 AI;大文件受大小限制)
  24. - ✅ **AI 生成图片 → 自动回传飞书**(支持工具返回的 `mediaUrl(s)` + `MEDIA:` 文本行 + 临时目录文件)
  25. - ✅ **列表格式修复**:飞书偶发把 `- 1` 拆成 `-\n1` 的情况,会自动合并回 `- 1`
  26. - ✅ **更安全的本地文件发送白名单**:默认仅允许 `~/.clawdbot/media`、系统临时目录、`/tmp`
  27. - ✅ 更强的调试能力:`FEISHU_BRIDGE_DEBUG=1` 可打印下载/转发细节
  28. ### 从旧版本升级(逐步引导)
  29. > 假设你之前已经按本 README 跑通过,并且现在桥接是“开机自启(launchd)”在后台运行。
  30. 1) **打开“终端 Terminal”**
  31. 2) **进入你之前克隆本项目的目录**
  32. - 不知道目录在哪:先在电脑里搜索 `feishu-openclaw` 文件夹
  33. - 小技巧:在 Finder 里找到该文件夹后,把文件夹**拖进终端**,就能直接得到路径
  34. 3) **停止旧的桥接服务(避免旧进程继续跑旧代码)**
  35. > 如果你当初没有做“开机自启(launchd)”,而是手动在终端运行的 `node bridge.mjs`:
  36. > 你可以跳过这一步(或者直接在旧终端窗口按 `Ctrl + C` 停止)。
  37. ```bash
  38. launchctl unload ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist 2>/dev/null || true
  39. ```
  40. 4) **拉取最新代码**
  41. ```bash
  42. cd /path/to/feishu-openclaw
  43. git pull
  44. ```
  45. 5) **更新依赖**(建议照做)
  46. ```bash
  47. npm install
  48. ```
  49. 6) **重新启动桥接服务**
  50. - 如果你使用了 launchd(开机自启):
  51. ```bash
  52. launchctl load ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist
  53. ```
  54. - 如果你是手动运行:
  55. ```bash
  56. FEISHU_APP_ID=cli_xxxxxxxxx node bridge.mjs
  57. ```
  58. 7) **验证是否成功**
  59. - 在飞书里发一张图片给机器人(它应该能看懂图片内容)
  60. - 让机器人“生成一张图片”(它应该会把图片发回飞书)
  61. 如果不工作,先开调试模式运行一次(见下方“调试”章节)。
  62. ## **🆕 2025.2.1**:同步更新飞书插件=> [openclaw-feishu](https://github.com/AlexAnys/openclaw-feishu),适配OpenClaw
  63. ---
  64. ## 📦 安装方式 / Install Methods
  65. | 方式 | 说明 | 链接 |
  66. |------|------|------|
  67. | **① 一键安装** | 让 Clawdbot 帮你安装插件 | [openclaw-feishu](https://github.com/AlexAnys/openclaw-feishu) |
  68. | **② npm 命令** | `clawdbot plugins install feishu-openclaw` | [npm](https://www.npmjs.com/package/feishu-openclaw) |
  69. | **③ 独立桥接** ⬅️ | 本项目,独立进程 | 见下方 |
  70. ### 插件 vs 桥接
  71. | | 插件 (①②) | 桥接 (③) |
  72. |---|---|---|
  73. | 进程 | 1 个(内置 Gateway) | 2 个(独立) |
  74. | 崩溃 | 影响 Gateway | **互不影响** |
  75. | 适合 | 日常使用 | **生产/隔离部署** |
  76. **推荐**:日常用插件,生产环境用桥接。
  77. ---
  78. ## 它是怎么工作的?
  79. 想象三个角色:
  80. ```
  81. 飞书用户 ←→ 飞书云端 ←→ 桥接脚本(你的电脑上) ←→ Clawdbot 智能体
  82. ```
  83. ### 通俗解释
  84. 1. **飞书那边**:你在飞书开发者后台创建一个"自建应用"(机器人),飞书会给你一个 App ID 和 App Secret——这就像是机器人的"身份证"。
  85. 2. **桥接脚本**:一个运行在你电脑上的小程序。它用飞书提供的 **WebSocket 长连接**(而不是传统的 Webhook)来接收消息——这意味着:
  86. - ✅ 不需要公网 IP / 域名
  87. - ✅ 不需要 ngrok / frp 等内网穿透
  88. - ✅ 不需要 HTTPS 证书
  89. - 就像微信一样,你的客户端主动连上去,消息就推过来了
  90. 3. **Clawdbot**:桥接脚本收到飞书消息后,通过本地 WebSocket 转发给 Clawdbot Gateway。Clawdbot 调用 AI 模型生成回复,桥接脚本再把回复发回飞书。
  91. ### 保活机制
  92. 脚本通过 macOS 的 **launchd**(系统服务管理器)运行:
  93. - 开机自动启动
  94. - 崩溃自动重启
  95. - 日志自动写入文件
  96. 就像把一个程序设成了"开机启动项",但更可靠。
  97. ---
  98. ## 5 分钟上手
  99. ### 前提
  100. - macOS(已安装 Clawdbot 并正常运行)
  101. - Node.js ≥ 18
  102. - Clawdbot Gateway 已启动(`clawdbot gateway status` 检查)
  103. - 桥接脚本需与 Gateway 在同一台机器(默认连接 `127.0.0.1`)
  104. ### 第一步:创建飞书机器人
  105. 1. 打开 [飞书开放平台](https://open.feishu.cn/app),登录
  106. 2. 点击 **创建自建应用**
  107. 3. 填写应用名称(随意,比如 "My AI Assistant")
  108. 4. 进入应用 → **添加应用能力** → 选择 **机器人**
  109. 5. 进入 **权限管理**,开通以下权限(推荐照抄,少踩坑):
  110. - `im:message` — 获取与发送消息
  111. - `im:message:send_as_bot` — 以机器人身份发消息(避免 403)
  112. - `im:message.group_at_msg` — 接收群聊中 @ 机器人的消息
  113. - `im:message.p2p_msg` — 接收机器人单聊消息
  114. - `im:resource` — 上传/下载图片与文件(**收图/收视频**必须)
  115. 6. 进入 **事件与回调** → **事件配置**:
  116. - 添加事件:`接收消息 im.message.receive_v1`
  117. - 请求方式选择:**使用长连接接收事件**(这是关键!)
  118. 7. 发布应用(创建版本 → 申请上线)
  119. 8. 记下 **App ID** 和 **App Secret**(在"凭证与基础信息"页面)
  120. ### 第二步:安装依赖
  121. ```bash
  122. cd /path/to/feishu-openclaw
  123. npm install
  124. ```
  125. ### 第三步:配置凭证
  126. 把你的飞书 App Secret 保存到安全位置:
  127. ```bash
  128. # 创建 secrets 目录
  129. mkdir -p ~/.clawdbot/secrets
  130. # 写入 secret(替换成你自己的)
  131. echo "你的AppSecret" > ~/.clawdbot/secrets/feishu_app_secret
  132. # 设置权限,只有自己能读
  133. chmod 600 ~/.clawdbot/secrets/feishu_app_secret
  134. ```
  135. > 如需自定义路径,可设置 `FEISHU_APP_SECRET_PATH` 指向该文件。
  136. ### 第四步:测试运行
  137. ```bash
  138. # 替换成你的 App ID
  139. FEISHU_APP_ID=cli_xxxxxxxxx node bridge.mjs
  140. ```
  141. 该桥接兼容 Clawdbot / OpenClaw Gateway。
  142. 在飞书里给机器人发一条消息,看到回复就说明成功了 🎉
  143. ### 第五步:设置开机自启(可选但推荐)
  144. ```bash
  145. # 生成 launchd 服务配置(自动检测路径)
  146. node setup-service.mjs
  147. # 加载服务
  148. launchctl load ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist
  149. # 查看状态
  150. launchctl list | grep feishu
  151. ```
  152. 之后电脑重启也会自动连上。
  153. ---
  154. ## 文件说明
  155. ```
  156. feishu-openclaw/
  157. ├── bridge.mjs # 核心桥接脚本
  158. ├── setup-service.mjs # 自动生成 launchd 保活配置
  159. ├── package.json # 依赖声明
  160. └── README.md # 你正在读的这个
  161. ```
  162. ---
  163. ## 进阶
  164. ### 群聊行为
  165. 在群聊中,桥接器默认"低打扰"模式——只在以下情况回复:
  166. - 被 @ 了
  167. - 消息看起来是提问(以 `?` / `?` 结尾)
  168. - 消息包含请求类动词(帮、请、分析、总结、写…)
  169. - 用名字呼唤(bot、助手…,可在代码中自定义)
  170. 其他闲聊不会回复,避免刷屏。
  171. ### "正在思考…" 提示
  172. 如果 AI 回复超过 2.5 秒,会先发一条"正在思考…",等回复生成后自动替换成完整内容。
  173. ### 日志位置
  174. ```
  175. ~/.clawdbot/logs/feishu-bridge.out.log # 正常输出
  176. ~/.clawdbot/logs/feishu-bridge.err.log # 错误日志
  177. ```
  178. ### 调试(推荐)
  179. 如果你遇到“图片发不过来 / 生图发不出来 / 只看到 key / 只收到文字”等问题:
  180. 1) 在本项目目录新建或编辑 `.env`(注意:`.env` 不会上传到 GitHub,很安全)
  181. ```bash
  182. FEISHU_BRIDGE_DEBUG=1
  183. ```
  184. 2) 重启桥接服务(launchd):
  185. ```bash
  186. launchctl unload ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist
  187. launchctl load ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist
  188. ```
  189. 3) 查看日志:
  190. ```bash
  191. tail -n 200 ~/.clawdbot/logs/feishu-bridge.err.log
  192. ```
  193. ---
  194. ## 排查清单(遇到问题先看这里)
  195. ### 1) 能发消息,但收不到消息
  196. - 飞书开放平台 → **事件与回调**:订阅方式是否选了 **“使用长连接接收事件”**?
  197. - 是否添加了事件:`im.message.receive_v1`?
  198. - 应用是否已发布(至少测试版发布)?
  199. - 机器人是否已添加到对应群聊/可用范围?
  200. ### 2) 你发图片/视频,AI 看不到(只看到 key / [图片])
  201. - 权限是否开了 `im:resource`(媒体资源权限)?
  202. - 打开调试:在 `.env` 里设 `FEISHU_BRIDGE_DEBUG=1`,然后看日志:
  203. - `~/.clawdbot/logs/feishu-bridge.err.log`
  204. ### 3) AI 说“生成了图片”,但飞书收不到图片
  205. 通常是两类原因:
  206. - 生成的图片路径不在允许发送的白名单目录里(默认只允许 `~/.clawdbot/media`、系统临时目录、`/tmp`)
  207. - 图片文件太大或不可读
  208. 也建议先开调试,看日志定位。
  209. ### 4) 视频/文件能收到,但 AI “理解内容”有限
  210. - 目前桥接会下载视频/文件,并把 `file://...` 路径传给 AI。
  211. - 但 AI 是否能“读懂”文件内容,取决于你使用的 agent/工具链是否会去读取该文件。
  212. > 如果你希望自动解析 PDF/Word/Excel 并把内容转成文本喂给 AI,需要额外扩展(欢迎提 issue)。
  213. ### 5) 升级到 OpenClaw 2026.2.x 后报 "missing scope: operator.write"
  214. 这是因为新版 OpenClaw 引入了 Device Identity 认证机制。**解决方法:升级桥接到最新版本。**
  215. ```bash
  216. cd /path/to/feishu-openclaw
  217. git pull
  218. npm install
  219. # 重启服务
  220. launchctl unload ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist
  221. launchctl load ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist
  222. ```
  223. 升级后桥接会自动生成设备密钥并完成认证,无需额外操作。
  224. ## 常见歧义与配置说明
  225. ### 1) Clawdbot 配置路径
  226. 默认读取:`~/.clawdbot/clawdbot.json`
  227. 如果你把 Clawdbot 安装在其他目录,需手动指定:
  228. ```bash
  229. CLAWDBOT_CONFIG_PATH=/your/path/clawdbot.json FEISHU_APP_ID=cli_xxx node bridge.mjs
  230. ```
  231. ### 2) 选择 Clawdbot 的 Agent
  232. 默认使用 `main`,如需切换:
  233. ```bash
  234. CLAWDBOT_AGENT_ID=你的AgentID FEISHU_APP_ID=cli_xxx node bridge.mjs
  235. ```
  236. ### 3) Gateway 必须在本机
  237. 桥接器固定连接 `127.0.0.1`,所以桥接脚本必须与 Gateway 在同一台机器。
  238. 如果你想跨机器部署,需要自行改代码或加一层转发。
  239. ### 停止服务
  240. ```bash
  241. launchctl unload ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist
  242. ```
  243. ---
  244. ## 版本与更新(Releases)
  245. - 推荐从 GitHub 的 **Releases** 获取“稳定版本”的更新说明与升级指引:
  246. <https://github.com/AlexAnys/feishu-openclaw/releases>
  247. - 如果你是通过 `git clone` 安装的:升级基本就是 `git pull` + `npm install` + 重启服务。
  248. ## 常见问题
  249. **Q: 需要服务器吗?**
  250. 不需要。飞书的 WebSocket 长连接模式让你的电脑直接连到飞书云端,不需要公网暴露。
  251. **Q: 电脑关机了怎么办?**
  252. 机器人会离线。重新开机后 launchd 会自动重启桥接服务。如需 24/7 在线,可以部署到一台常开的机器(比如 NAS、云服务器、甚至树莓派)。
  253. **Q: 飞书免费版能用吗?**
  254. 可以。自建应用和机器人能力对所有飞书版本开放。
  255. **Q: 能同时接 Telegram 吗?**
  256. 可以。Clawdbot 原生支持 Telegram 等渠道,飞书桥接只是多加一个入口,互不影响。
  257. ---
  258. ## 链接 / Links
  259. - 📦 [npm: feishu-openclaw](https://www.npmjs.com/package/feishu-openclaw)
  260. - 🔌 [GitHub: openclaw-feishu](https://github.com/AlexAnys/openclaw-feishu) (插件)
  261. - 🌉 [GitHub: feishu-openclaw](https://github.com/AlexAnys/feishu-openclaw) (本项目)
  262. - 📖 [Clawdbot 文档](https://docs.clawd.bot)
  263. ## License
  264. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.