飞书 OpenClaw 接入指南：长连接运行 AI 机器人

导入后：创建新版本 → 发布。 4. 清理旧插件/桥接：

# 移除旧的 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：同上。
2. 补权限：同方式一。
3. 安装并配置：

# 安装官方飞书插件
openclaw plugins install @openclaw/feishu
# 添加飞书渠道（交互式引导）
openclaw channels add
# → 选择 Feishu
# → 粘贴 App ID
# → 粘贴 App Secret
# 移除旧插件及桥接（参考方式一命令）
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 已安装运行。

1. 创建飞书应用：飞书开放平台 → 创建'企业自建应用'。
2. 启用机器人能力：应用能力 > 机器人 → 开启 → 命名。
3. 配置权限：权限管理 → 批量导入（使用上文 JSON）。
4. 配置事件订阅：
   • 必须在 OpenClaw 网关启动后操作。
   • 事件与回调 > 事件配置 → 请求方式选 使用长连接接收事件。
   • 添加事件：im.message.receive_v1。
5. 记下凭证：凭证与基础信息 → App ID / App Secret。
6. 发布应用：版本管理与发布 → 创建版本 → 提交 → 发布。
7. 在 OpenClaw 中配置：

openclaw plugins install @openclaw/feishu
openclaw channels add # 按提示输入 App ID / Secret
openclaw gateway restart
openclaw logs --follow

8. 测试：飞书发消息，若有配对码则批准。
9. 开机自启：可使用 openclaw gateway install。

三、常见问题 & 排查清单

1. 没有消息发送框：事件订阅未配置。检查飞书开放平台事件与回调，确保选择'使用长连接'并添加 im.message.receive_v1，发布新版本。
2. 机器人没反应：
   • 检查网关是否运行 (openclaw gateway restart)。
   • 确认应用已发布。
   • 确认事件订阅正确（长连接 + im.message.receive_v1）。
   • 检查权限（最低：im:message, im:message.p2p_msg:readonly, im:message:send_as_bot）。
   • 查看日志。
3. 时断时续：网络波动（VPN/代理）、DNS/代理问题。建议 open.feishu.cn 直连。检查日志 openclaw logs |grep -i "restart\|reconnect\|disconnect"。
4. 发图片/文件 AI 看不到：必须有 im:resource 权限，补权限后创建新版本并发布，重启网关。
5. AI 生成图片但飞书没收到：检查 im:resource 权限及 upload 相关日志。
6. 群聊不回复：默认需 @机器人，确认已加群，检查 groupPolicy。
7. 回复慢：模型响应速度决定，可开启流式输出（默认开启），超时看日志。
8. 配对码：首次安全校验，执行 openclaw pairing approve feishu <CODE>。
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}}}}}
  • 白名单：{"channels":{"feishu":{"groupPolicy":"allowlist","groupAllowFrom":["ou_用户 1","ou_用户 2"]}}}
• 流式输出：{"channels":{"feishu":{"streaming":true,"blockStreaming":true}}}
• 多 Agent 路由：

{"bindings":[{"agentId":"main","match":{"channel":"feishu","peer":{"kind":"dm","id":"ou_用户 A"}}}]}

• 访问控制策略：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：插件列表

五、独立桥接模式

适用于需要进程隔离或有特殊定制需求。大多数用户用官方插件即可。

• 快速启动：

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 / .err.log
• 调试模式：设置 FEISHU_BRIDGE_DEBUG=1 环境变量。
• 原理：飞书 WebSocket 长连接 ↔ 电脑桥接脚本 ↔ OpenClaw 网关。无需公网 IP。

六、快问快答

• 需要服务器吗？ 不需要。WebSocket 长连接直接连飞书云端。
• 电脑关机了怎么办？ 机器人离线；开机后自动重连（若配自启）。
• 飞书免费版能用吗？ 可以。
• 能同时接其它渠道吗？ 可以。
• 用了官方插件后，这个项目还有用吗？ 有：继续提供配置教程、迁移指南、排查与答疑。