介绍如何在无服务器环境下，通过长连接将飞书机器人接入 OpenClaw。涵盖旧版插件迁移至官方插件的步骤、新手从零配置流程（含权限与事件订阅）、常见问题排查清单（如消息框缺失、断连、图片发送失败等）以及进阶配置（群组策略、多 Agent 路由）。支持独立桥接模式作为备选方案。
本指南旨在帮助开发者在飞书内搭建稳定对话的 AI 机器人，重点解决步骤繁琐和排查困难的问题。OpenClaw 已内置官方飞书插件 @openclaw/feishu，功能更完整、维护更及时。
适用人群：以前用过独立桥接或 npm 插件，现需迁到 OpenClaw 内置官方飞书插件。
前提：OpenClaw 版本 ≥ 2026.2，升级后官方飞书插件已内置。
升级 OpenClaw 升级完成会自动重启网关。
添加飞书渠道 选择 Feishu → 填 App ID → 填 App Secret。
App Secret 可能位置：
~/.clawdbot/secrets/feishu_app_secret（可用 cat 查看）https://open.feishu.cn/app → 你的应用 → 凭证与基础信息 复制补全飞书应用权限 去飞书开放平台：你的应用 → 权限管理 → 批量导入，粘贴以下 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"]}}
导入后：创建新版本 → 发布（让新权限生效）。
# 移除旧的 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，只想把飞书接进来。
准备 App ID / App Secret 同上。
补权限 同方式一（批量导入 + 创建新版本 + 发布）。
安装并配置
# 安装官方飞书插件
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
适用人群：第一次用 OpenClaw + 飞书。前提：OpenClaw 已安装并正常运行。
https://open.feishu.cn/app你的应用 → 应用能力 > 机器人 → 开启 → 命名机器人
你的应用 → 权限管理 → 批量导入 → 粘贴权限 JSON（与上文完全相同）
这里按流程一键导入需要的权限。
警告：这一步必须在 OpenClaw 网关启动后再做，否则保存会失败。
im.message.receive_v1（接收消息）你的应用 → 凭证与基础信息：
cli_xxxxx）你的应用 → 版本管理与发布 → 创建版本 → 提交 → 发布/上线
# 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，该命令可将网关安装为开机自启服务。
结论：事件订阅没有配置。权限批量导入不会自动配置事件订阅。
im.message.receive_v1提醒：配置事件订阅前，确保 OpenClaw/Clawdbot Gateway 已启动，否则长连接验证会失败。
检查顺序：
openclaw gateway restartim.message.receive_v1im:messageim:message.p2p_msg:readonlyim:message:send_as_bot常见原因与处理：
openclaw logs |grep -i "restart\|reconnect\|disconnect"
open.feishu.cn 走直连（不走代理）im:resourceopenclaw gateway restartim:resource 权限（用于上传图片到飞书）groupPolicy（见进阶配置）主要由模型响应速度决定；可开启流式输出（默认已开启）；超过 30 秒看日志是否模型调用出错。
首次出于安全，机器人发配对码，管理员批准一次即可：
openclaw pairing approve feishu <配对码>
在配置里指定域名：
{"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。
{"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：已安装插件列表适用于你需要进程隔离（桥接崩溃不影响网关）或有特殊定制需求。大多数用户用官方插件即可。
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
# 生成服务配置
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、不需要域名、不需要内网穿透。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online