跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客GitHub 精选镜像工具UI配色美学隐私政策关于联系
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
JavaScriptNode.jsAI

飞书与 OpenClaw 接入指南：无需服务器，长连接运行机器人

飞书对接 OpenClaw 无需公网服务器，通过 WebSocket 长连接即可运行机器人。从新建应用到权限配置的全流程，涵盖新旧版本迁移、事件订阅设置及常见问题排查。内容包含基础命令速查、群组策略配置、多 Agent 路由及独立桥接模式说明，帮助开发者快速实现稳定的飞书 AI 机器人部署与群控功能。

山野诗人发布于 2026/3/27更新于 2026/6/818 浏览

飞书与 OpenClaw 接入指南

想在飞书里部署一个能稳定对话、支持发图收文件、按规则群控的 AI 机器人？通常面临两大挑战：配置步骤繁琐和出错后排查困难。本文旨在将'飞书接 OpenClaw'整理成一套对非技术人员友好的配置方案，并集中列出常见坑位的排查清单。

OpenClaw 现已内置官方飞书插件 @openclaw/feishu，功能更完整且维护及时。本指南不仅提供从零开始的新手教程（预计 15–20 分钟），也包含旧版独立桥接或 npm 插件迁移至官方插件的路径，以及进阶场景下的独立模式说明。

一、老用户迁移到官方插件

如果你之前使用过本项目的独立桥接或 npm 插件，现在可以无缝迁移到 OpenClaw 内置的官方飞书插件。

迁移前须知

  • 应用复用：之前创建的飞书应用可直接沿用，无需重建。
  • 凭证不变：App ID 和 App Secret 保持不变。
  • 数据兼容：聊天记录存储在飞书端，不受影响。
  • 短暂离线：迁移过程中机器人会短暂离线几分钟。

方式一：通过 OpenClaw 升级（推荐）

前提是你的 OpenClaw 版本 ≥ 2026.2，此时官方飞书插件已内置。

  1. 升级 OpenClaw 升级完成后网关会自动重启。

  2. 添加飞书渠道 选择 Feishu → 填入 App ID → 填入 App Secret。

    提示：App Secret 可能保存在旧环境文件中，例如 ~/.clawdbot/secrets/feishu_app_secret。若找不到，请前往飞书开放平台的应用详情页复制。

  3. 补全权限 去飞书开放平台 → 你的应用 → 权限管理 → 批量导入，粘贴以下 JSON 配置以支持图片、文件及流式消息：

{"scopes":{"tenant":["aily:file:read","aily:file:write","application:application.app_message_stats.overview:readonly","application:application.self_manage","application:bot.menu:write","cardkit:card:write","contact:user.employee_id:readonly","corehr:file:download","docs:document.content:read","event:ip_list","im:chat","im:chat.access_event.bot_p2p_chat:read","im:chat.members:bot_access","im:message","im:message.group_at_msg:readonly","im:message.group_msg","im:message.p2p_msg:readonly","im:message:readonly","im:message:send_as_bot","im:resource","sheets:spreadsheet","wiki:wiki:readonly"],"user":["aily:file:read","aily:file:write","im:chat.access_event.bot_p2p_chat:read"]}}

导入后务必执行：创建新版本 → 发布，否则新权限不会生效。

  1. 清理旧插件 避免新旧插件冲突，建议移除旧组件：
# 移除旧的 npm 插件
openclaw plugins remove feishu-openclaw 2>/dev/null

# 停掉旧的桥接服务（macOS launchctl）
launchctl unload ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist 2>/dev/null

# 重启网关
openclaw gateway restart

方式二：手动安装插件 + 配置

适用于不想整体升级 OpenClaw 的场景。

  1. 准备凭证：同上，获取 App ID 和 App Secret。
  2. 补全权限：同方式一，确保批量导入并发布新版本。
  3. 安装配置：
# 安装官方飞书插件
openclaw plugins install @openclaw/feishu

# 添加飞书渠道（交互式引导）
openclaw channels add
# 选择 Feishu → 粘贴 App ID → 粘贴 App Secret

# 清理旧插件与服务
openclaw plugins remove feishu-openclaw 2>/dev/null
launchctl unload ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist 2>/dev/null

# 重启网关
openclaw gateway restart

验证连接

查看日志确认飞书连接成功：

openclaw logs --follow

看到 feishu ws connected 或 feishu provider ready 即表示连接正常。在飞书中给机器人发消息，若能回复则完成配置。若收到配对码，需执行批准操作：

openclaw pairing approve feishu <配对码>

稳定运行几天后，可清理旧配置文件（如 ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist）。

二、新手从零配置（15–20 分钟）

适用人群：首次使用 OpenClaw + 飞书。前提：OpenClaw 已安装并正常运行。

1. 创建飞书应用

打开飞书开放平台，创建'企业自建应用'，填写名称、描述及图标。

2. 启用机器人能力

进入应用详情页 → 应用能力 > 机器人 → 开启并命名机器人。

3. 配置权限

进入 权限管理 → 批量导入，粘贴上文提供的权限 JSON。这是支持图片、文件等高级功能的关键。

4. 配置事件订阅（关键）

注意：此步骤必须在 OpenClaw 网关启动后进行，否则保存可能失败。

  • 路径：事件与回调 > 事件配置
  • 请求方式：选择 使用长连接接收事件
  • 添加事件：im.message.receive_v1（用于接收消息）

5. 记下凭证

在 凭证与基础信息 中记录 App ID 和 App Secret（请勿分享）。

6. 发布应用

进入 版本管理与发布 → 创建版本 → 提交 → 发布上线。

7. 在 OpenClaw 中配置

# 安装插件
openclaw plugins install @openclaw/feishu

# 添加渠道（跟随提示输入 App ID 和 Secret）
openclaw channels add

# 重启网关
openclaw gateway restart

# 查看日志
openclaw logs --follow

8. 测试与配对

飞书内发送'你好'。若出现配对码，执行 openclaw pairing approve feishu <配对码>。批准后即可正常对话。

如果跳过了事件订阅配置，请在网关启动后补上第四步，保存后再重启网关。

9. 开机自启（可选）

使用 openclaw gateway install 命令可将网关注册为系统服务，实现电脑重启后自动上线。

三、常见问题 & 排查清单

1. 没有消息发送框？

最常见原因是事件订阅未配置。权限导入不会自动配置事件。

  • 检查飞书开放平台 → 事件与回调。
  • 确保添加了 im.message.receive_v1 事件。
  • 订阅方式必须选 使用长连接接收事件。
  • 记得创建新版本并发布。

2. 机器人完全没反应？

按顺序检查：

  1. 网关是否运行？尝试 openclaw gateway restart。
  2. 飞书应用是否已发布？
  3. 事件订阅是否正确？确认是长连接而非 Webhook，且添加了 im.message.receive_v1。
  4. 权限是否足够？最低要求包括 im:message, im:message.p2p_msg:readonly, im:message:send_as_bot。
  5. 观察日志是否有报错。

3. 时断时续？

  • 网络波动（尤其是 VPN/代理环境）可能导致频繁断连。
  • 检查网关日志：openclaw logs | grep -i "restart\|reconnect\|disconnect"。
  • 确保 open.feishu.cn 走直连，不走代理。

4. 发图片/文件，AI 看不到？

  • 检查权限是否包含 im:resource。
  • 补权限后需重新创建版本并发布。
  • 重启网关生效。

5. AI 说生成了图片，但飞书没收到？

  • 同样检查 im:resource 权限。
  • 查看日志中的 upload 相关错误信息。

6. 群聊中机器人不回复？

  • 默认需要 @机器人。
  • 确认机器人已加入群组。
  • 检查 groupPolicy 配置。

7. 回复特别慢？

主要由模型响应速度决定。默认已开启流式输出，超过 30 秒可查看日志是否模型调用出错。

8. Lark（国际版）用户怎么配？

在配置中指定域名：

{"channels":{"feishu":{"domain":"lark"}}}

四、进阶配置参考

配置文件位置

~/.openclaw/openclaw.json

基础配置示例

{"channels":{"feishu":{"enabled":true,"dmPolicy":"pairing","accounts":{"main":{"appId":"cli_xxxxxxxxx","appSecret":"你的 AppSecret","botName":"我的 AI 助手"}}}}}

群组策略

  • 默认：所有群允许，但必须 @。
  • 指定群无需 @：
{"channels":{"feishu":{"groups":{"oc_你的群组 ID":{"requireMention":false}}}}}
  • 白名单模式：仅允许特定用户使用。
{"channels":{"feishu":{"groupPolicy":"allowlist","groupAllowFrom":["ou_用户 1","ou_用户 2"]}}}

流式输出

默认开启。如需关闭，设置 streaming: false。

多 Agent 路由

{"bindings":[{"agentId":"main","match":{"channel":"feishu","peer":{"kind":"dm","id":"ou_用户 A"}}},{"agentId":"另一个 agent","match":{"channel":"feishu","peer":{"kind":"group","id":"oc_某群组"}}}]}

访问控制策略

  • pairing：默认，新用户需配对码批准。
  • allowlist：仅白名单用户。
  • open：所有人可对话。
  • disabled：禁止私聊。

常用命令速查

  • openclaw gateway status：查看状态
  • openclaw gateway restart：重启
  • openclaw gateway install：开机自启
  • openclaw logs --follow：实时日志
  • openclaw pairing list feishu：查看待授权
  • openclaw pairing approve feishu <CODE>：批准配对
  • openclaw plugins list：插件列表

五、独立桥接模式（进阶）

适用于需要进程隔离（桥接崩溃不影响网关）或有特殊定制需求的场景。大多数用户直接使用官方插件即可。

插件 vs 桥接

  • 官方插件：与网关同进程，维护随 OpenClaw 更新，适合日常。
  • 独立桥接：独立进程，互不影响，需自行维护，适合生产环境。

快速启动

# 克隆项目
git clone https://github.com/AlexAnys/feishu-openclaw.git
cd feishu-openclaw

# 安装依赖
npm install

# 配置凭证
mkdir -p ~/.clawdbot/secrets
echo "你的 AppSecret" > ~/.clawdbot/secrets/feishu_app_secret
chmod 600 ~/.clawdbot/secrets/feishu_app_secret

# 启动
FEISHU_APP_ID=cli_xxxxxxxxx node bridge.mjs

开机自启 (launchd)

node setup-service.mjs
launchctl load ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist
launchctl list | grep feishu

调试模式

echo "FEISHU_BRIDGE_DEBUG=1" > .env
tail -n 200 ~/.clawdbot/logs/feishu-bridge.err.log

工作原理

飞书用户 ↔ 飞书云端 ↔ 本地桥接脚本 ↔ OpenClaw 网关。桥接通过 WebSocket 长连接接收消息，无需公网 IP、域名或内网穿透。

六、快问快答

  • 需要服务器吗？ 不需要。利用 WebSocket 长连接，电脑直接连飞书云端。
  • 电脑关机了怎么办？ 机器人离线；开机后自动重连（若配置了自启）。24/7 在线建议使用常开设备或云服务器。
  • 飞书免费版能用吗？ 可以，自建应用与机器人功能对所有版本开放。
  • 能同时接其它渠道吗？ 可以，OpenClaw 支持多渠道并行。
  • 用了官方插件后，这个项目还有用吗？ 有，继续提供配置教程、迁移指南及排查支持。

目录

  1. 飞书与 OpenClaw 接入指南
  2. 一、老用户迁移到官方插件
  3. 迁移前须知
  4. 方式一：通过 OpenClaw 升级（推荐）
  5. 移除旧的 npm 插件
  6. 停掉旧的桥接服务（macOS launchctl）
  7. 重启网关
  8. 方式二：手动安装插件 + 配置
  9. 安装官方飞书插件
  10. 添加飞书渠道（交互式引导）
  11. 选择 Feishu → 粘贴 App ID → 粘贴 App Secret
  12. 清理旧插件与服务
  13. 重启网关
  14. 验证连接
  15. 二、新手从零配置（15–20 分钟）
  16. 1. 创建飞书应用
  17. 2. 启用机器人能力
  18. 3. 配置权限
  19. 4. 配置事件订阅（关键）
  20. 5. 记下凭证
  21. 6. 发布应用
  22. 7. 在 OpenClaw 中配置
  23. 安装插件
  24. 添加渠道（跟随提示输入 App ID 和 Secret）
  25. 重启网关
  26. 查看日志
  27. 8. 测试与配对
  28. 9. 开机自启（可选）
  29. 三、常见问题 & 排查清单
  30. 1. 没有消息发送框？
  31. 2. 机器人完全没反应？
  32. 3. 时断时续？
  33. 4. 发图片/文件，AI 看不到？
  34. 5. AI 说生成了图片，但飞书没收到？
  35. 6. 群聊中机器人不回复？
  36. 7. 回复特别慢？
  37. 8. Lark（国际版）用户怎么配？
  38. 四、进阶配置参考
  39. 配置文件位置
  40. 基础配置示例
  41. 群组策略
  42. 流式输出
  43. 多 Agent 路由
  44. 访问控制策略
  45. 常用命令速查
  46. 五、独立桥接模式（进阶）
  47. 插件 vs 桥接
  48. 快速启动
  49. 克隆项目
  50. 安装依赖
  51. 配置凭证
  52. 启动
  53. 开机自启 (launchd)
  54. 调试模式
  55. 工作原理
  56. 六、快问快答
  • 💰 8折买阿里云服务器限时8折了解详情
  • Magick API 一键接入全球大模型注册送1000万token查看
  • 🤖 一键搭建Deepseek满血版了解详情
  • 一键打造专属AI 智能体了解详情
极客日志微信公众号二维码

微信扫一扫，关注极客日志

微信公众号「极客日志V2」，在微信中扫描左侧二维码关注。展示文案：极客日志V2 zeeklog

更多推荐文章

查看全部
  • 基于 OpenClaw 与 GLM-4.7 Flash 搭建飞书联网问答机器人
  • 产品经理视角：理性应对大模型时代的挑战与机遇
  • LazyLLM 多 Agent 应用全流程实践：从源码部署到可视化 Web 调试的低代码方案
  • 天然气管道内检测机器人检测节设计与结构分析
  • Ubuntu 22.04 下 libwebkit2gtk-4.1-0 安装配置指南
  • 从软件工程视角理解低代码的价值、边界与演进路径
  • Java 开发环境搭建：JDK 安装与变量配置详解
  • 基于 Python 和 Ollama 搭建本地 AI 智能体 OpenClaw 指南
  • AIGC Bar API 站接入与工程化最佳实践
  • Ubuntu 22.04 部署 OpenClaw 实战：多模型接入与网络搜索配置
  • OCR 后处理：CRNN 模型的纠错算法实践
  • 自适应图像变焦与边界框变换用于无人机目标检测
  • WebP 格式简记
  • OpenClaw 高级使用：多 Agent 协作与云端 Gateway 控制本地 macOS
  • C++ 结构体基础用法与排序实现
  • 基于 SpringBoot+Vue 的中山社区医疗综合服务平台系统设计
  • ES6 扩展运算符（...）在对象与数组中的实战用法
  • C++红黑树原理与实现详解
  • MacOS 平台 Whisper-WebUI 崩溃问题实战解决方案
  • DSPy 技术详解：从 Prompt 工程到编程式大模型应用

相关免费在线工具

  • RSA密钥对生成器

    生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online

  • Mermaid 预览与可视化编辑

    基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online

  • 随机西班牙地址生成器

    随机生成西班牙地址（支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选），支持数量快捷选择、显示全部与下载。 在线工具，随机西班牙地址生成器在线工具，online

  • Keycode 信息

    查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online

  • Escape 与 Native 编解码

    JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online

  • JavaScript / HTML 格式化

    使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online