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

飞书 OpenClaw 机器人接入指南：基于长连接无需服务器

介绍如何在无服务器环境下通过长连接将 OpenClaw 与飞书集成。内容包括旧版迁移至官方插件的步骤、新手从零配置流程、权限设置（批量导入 JSON）、事件订阅配置及常见问题排查（如消息框缺失、断连、图片发送等）。支持独立桥接模式作为进阶方案，并提供常用命令速查与群组策略配置示例，帮助用户快速搭建稳定的 AI 机器人。

MongoKing发布于 2026/4/6更新于 2026/5/2034 浏览

飞书 OpenClaw 机器人接入指南

本文介绍如何在无服务器环境下通过长连接将 OpenClaw 与飞书集成，实现稳定对话、发图收文件及群内工作。内容涵盖旧版迁移至官方插件步骤、新手从零配置流程、权限设置、事件订阅配置及常见问题排查。

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

适用人群：以前用过本项目的独立桥接或 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

验证与清理

验证连接

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

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

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

openclaw pairing approve feishu <配对码>

清理旧文件（可选） 稳定运行几天后可清理旧文件：

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

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

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

更多推荐文章

查看全部
  • Superpowers 编码 Agent 技能框架使用与原理分析
  • Web 虚拟卡销售平台架构设计与实战
  • MySQL 权限管理与 C/C++ 客户端开发实战
  • 极客大挑战 2025 Web 安全题目复现
  • C++ 手写二叉搜索树：从定义到完整实现
  • Python 构建 OKX 加密货币量化交易系统实战
  • FPGA 入门指南：从点亮 LED 开始
  • 文艺青年学 Python 转行：从北漂到程序员的职业进阶之路
  • OpenAkita：自我进化的开源 AI 助手框架
  • 使用飞书 AI 知识库搭建个人技术文档系统
  • C++ 入门指南：发展历史、命名空间及输入输出
  • C++ 实现域名与 IP 地址相互解析示例
  • VS Code Copilot 聊天加载超时错误修复指南
  • Cursor AI 使用与 Git 版本控制指南
  • AI 大模型所需的数据类型与质量要求
  • 大模型与生成式 AI 的发展脉络及应用安全思考
  • B-树原理与 Java 模拟实现详解
  • OpenClaw 移动端部署实战：iOS/Android 离线语音 AI 助手
  • Flutter 与 Web 混合开发：跨平台实现方案
  • 基于 Xilinx FPGA 的 RISC-V 五级流水线 CPU 设计实战

相关免费在线工具

  • 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