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

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

4. 清理旧插件 避免新旧插件冲突，建议移除旧组件：

# 移除旧的 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 支持多渠道并行。
• 用了官方插件后，这个项目还有用吗？ 有，继续提供配置教程、迁移指南及排查支持。