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

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

OpenClaw 飞书机器人接入无需服务器，通过 WebSocket 长连接实现。支持新旧版本迁移及新手从零配置。核心步骤包括创建飞书应用、配置权限与事件订阅、安装插件或独立桥接。常见问题涵盖无输入框、消息不回复、图片发送失败等排查方法。提供配置文件示例及群组策略设置。

暖阳发布于 2026/4/11更新于 2026/5/2311 浏览

OpenClaw 飞书接入指南

本指南旨在将飞书接入 OpenClaw 的过程整理为对非技术人员友好的配置入口，并提供常见问题的排查清单。OpenClaw 已内置官方飞书插件 @openclaw/feishu，功能更完整、维护也更及时。

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

适用人群：以前用过独立桥接或 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（可 cat 查看）
    • 如果找不到：去飞书开放平台 https://open.feishu.cn/app → 你的应用 → 凭证与基础信息 复制

  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

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

# 重启网关
openclaw gateway restart

方式二：不整体升级，手动安装插件 + 配置

适用：不想升级 OpenClaw，只想把飞书接进来。

  1. 准备 App ID / App Secret 同上，可能在 ~/.clawdbot/secrets/feishu_app_secret。

  2. 补权限 同方式一（批量导入 + 创建新版本 + 发布）。

  3. 安装并配置

# 安装官方飞书插件
openclaw plugins install @openclaw/feishu

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

# 移除旧的 npm 插件（如果装过）
openclaw plugins remove feishu-openclaw 2>/dev/null

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

# 重启网关
openclaw gateway restart

验证与清理

  1. 验证连接
# 查看日志，确认飞书连接成功
openclaw logs --follow

日志里看到类似 feishu ws connected 或 feishu provider ready，说明连上了。去飞书里给机器人发消息，能正常回复即完成。

如果机器人回复了配对码（一次性安全操作），执行：

openclaw pairing approve feishu <配对码>
  1. 清理旧文件（可选） 稳定运行几天后可清理旧文件：
rm -f ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist

二、新手从零：配置飞书 AI 机器人

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

第一步：创建飞书应用（机器人）

  • 打开飞书开放平台 https://open.feishu.cn/app
  • 创建'企业自建应用'，填名称/描述/图标

第二步：启用机器人能力

你的应用 → 应用能力 > 机器人 → 开启 → 命名机器人

第三步：配置权限（批量导入）

你的应用 → 权限管理 → 批量导入 → 粘贴权限 JSON（与上文完全相同）

第四步：配置事件订阅

注意：这一步必须在 OpenClaw 网关启动后再做，否则保存会失败。

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

第五步：记下凭证

你的应用 → 凭证与基础信息：

  • App ID（cli_xxxxx）
  • App Secret（不要分享）

第六步：发布应用

你的应用 → 版本管理与发布 → 创建版本 → 提交 → 发布/上线

第七步：在 OpenClaw 中配置飞书

# 1. 安装飞书插件
openclaw plugins install @openclaw/feishu

# 2. 添加飞书渠道（交互式，跟着提示走）
openclaw channels add
# 选择 Feishu → 粘贴 App ID → 粘贴 App Secret

# 3. 重启网关
openclaw gateway restart

# 4. 查看日志，确认连接成功
openclaw logs --follow

第八步：发消息测试

飞书里给机器人发'你好'。如果出现配对码：

openclaw pairing approve feishu <配对码>

批准后即可正常对话。

如果之前跳过了'事件订阅'，现在网关已启动，回去把第四步补上，保存后再 openclaw gateway restart。

第九步（可选）：开机自启

结合 OpenClaw 命令 openclaw gateway install，该命令可将网关安装为开机自启服务。

三、常见问题 & 排查清单

1）没有消息发送框？

结论：事件订阅没有配置。权限批量导入不会自动配置事件订阅。

  • 飞书开放平台 → 你的应用 → 事件与回调
  • 添加事件：im.message.receive_v1
  • 订阅方式：使用长连接接收事件
  • 版本管理 → 创建新版本 → 发布上线

注意：配置事件订阅前，确保 OpenClaw/Clawdbot Gateway 已启动，否则长连接验证会失败。

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"
  • DNS/代理问题：确保 open.feishu.cn 走直连（不走代理）

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

  1. 检查权限：必须有 im:resource
  2. 补权限后要 创建新版本 → 发布
  3. 重启网关：openclaw gateway restart

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

  1. im:resource 权限（用于上传图片到飞书）
  2. 看日志 upload 相关错误

6）群聊中机器人不回复

  1. 默认需要 @机器人
  2. 确认机器人已被加到群
  3. 检查 groupPolicy（见进阶配置）

7）回复特别慢

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

8）配对码是什么？怎么用？

首次出于安全，机器人发配对码，管理员批准一次即可：

openclaw pairing approve feishu <配对码>

9）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}}}}}

只允许特定用户在群里使用（allowlist）：

{"channels":{"feishu":{"groupPolicy":"allowlist","groupAllowFrom":["ou_用户 1","ou_用户 2"]}}}

获取群组/用户 ID 的方式：给机器人发消息后看 openclaw logs --follow。

流式输出

默认开启：

{"channels":{"feishu":{"streaming":true,"blockStreaming":true}}}

如要关闭：设 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 plugins install，和网关同进程，维护随 OpenClaw 更新，适合日常
  • 独立桥接：git clone + npm install，独立进程，互不影响，但需自行维护，适合生产/隔离部署

快速启动

# 克隆项目
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

日志位置

  • ~/.clawdbot/logs/feishu-bridge.out.log（正常输出）
  • ~/.clawdbot/logs/feishu-bridge.err.log（错误日志）

调试模式

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

工作原理

飞书用户 ↔ 飞书云端 ↔（你的电脑上桥接脚本）↔ OpenClaw 网关

桥接通过飞书 WebSocket 长连接接收消息：不需要公网 IP、不需要域名、不需要内网穿透。

六、快问快答

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

目录

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

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

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

更多推荐文章

查看全部
  • 通义万相 2.1 结合云算力实现 AIGC 高效创作
  • 基于 Git 和 Termux 实现 Obsidian 平板多端同步方案
  • AI 浪潮下的前端演进与跨端实战指南
  • 高校师生工作室任务管理系统设计与实现（Python Flask/Django）
  • C++ 高性能内存池设计与实现
  • 龙虾 AI（OpenClaw）跨平台部署与日常使用教程
  • 如何赋予 LLM 多模态能力（MLLM）
  • 上下文协议（MCP）Java SDK 指南
  • Whisper.cpp 离线语音识别快速入门
  • Cesium 无人机智能航线规划：航点动作组与 AI 识别
  • AI 辅助 FPGA 开发：Vivado 配置与智能编程实践
  • Ovis: 多模态大语言模型的结构化嵌入对齐
  • Lunar Python 快速上手教程：农历日期转换
  • 学术论文避坑指南：降低重复率与 AIGC 检测风险的策略
  • PowerShell 中 Invoke-WebRequest 的正确使用：避免参数匹配错误
  • DeepFace 与 OpenCV 实现的情绪分析器
  • Claude Code、OpenCode 等六大 AI 代理工具全面解析
  • SpiffWorkflow 工作流引擎：Python 业务流程自动化指南
  • 合唱队形问题：动态规划解法
  • 微信 4.1.5.16 UI 树失效修复：UIAutomation 实战与 AI-RPA 落地

相关免费在线工具

  • RSA密钥对生成器

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

  • Mermaid 预览与可视化编辑

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

  • 随机西班牙地址生成器

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

  • Base64 字符串编码/解码

    将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online

  • Base64 文件转换器

    将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online

  • Markdown转HTML

    将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online