openclaw 与飞书断开：完整排查与重连指南
openclaw 与飞书（Feishu）的连接基于 WebSocket 长连接模式，而非传统 Webhook——这意味着断开的根本原因通常不是网络配置问题，而是 Gateway 未运行、飞书应用凭据失效、事件订阅未启用或权限配置不完整四类之一。本文提供从快速诊断到逐类修复的完整流程，覆盖所有已知断开场景。
飞书连接机制说明
理解断开原因前，先明确 openclaw 与飞书的连接架构：
关键推论：WebSocket 长连接模式下，只要 Gateway 进程存活，连接由 openclaw 主动维护。若连接断开，首先排查 Gateway 本身，而不是飞书侧配置。
快速诊断：30 秒定位断开原因
按顺序执行：
# Step 1：检查 Gateway 是否在运行
openclaw gateway status
# Step 2：检查飞书渠道连接状态
openclaw channels status --probe
# Step 3：查看实时日志（保留此窗口）
openclaw logs --follow
# Step 4：全面健康检查
openclaw doctor
状态对照表：
原因 1：Gateway 未运行
最常见原因。系统重启、手动关闭或崩溃后，Gateway 进程不再存活，飞书 WebSocket 连接随之断开。
# 确认当前状态
openclaw gateway status
# 若显示 Runtime: stopped，执行以下命令
# 重启 Gateway
openclaw gateway start
# 若 Daemon 元数据损坏（start 无效），强制重装后重启
openclaw gateway install --force && openclaw gateway start
# 验证
openclaw gateway status --deep
# 预期：Runtime: running，RPC probe: ok
预防措施：若未配置开机自启，参考以下方式确保 Daemon 随系统启动：
# macOS：通过 launchd 自启（onboard 时已安装，确认即可）
launchctl list | grep openclaw
# Linux：通过 systemd 自启
systemctl enable openclaw
systemctl start openclaw
原因 2：飞书应用凭据失效
App ID 或 App Secret 配置错误、飞书管理员重置了应用密钥，或环境变量未正确加载。
验证凭据配置
# 查看当前飞书渠道配置
openclaw config get channels.feishu
# 检查环境变量是否已加载
echo $FEISHU_APP_ID
echo $FEISHU_APP_SECRET
重新配置凭据
方式一：环境变量（推荐）
# ~/.openclaw/.env
FEISHU_APP_ID=cli_xxxxxxxxxxxxxx
FEISHU_APP_SECRET=your_app_secret_here
方式二：配置文件
// ~/.openclaw/openclaw.json { channels: { feishu: { enabled: true, appId: "${FEISHU_APP_ID}", appSecret: "${FEISHU_APP_SECRET}" } } } 凭据获取路径：飞书开放平台（open.feishu.cn）→ 我的应用 → 选择对应应用 → 凭证与基础信息 → App ID / App Secret。
修改配置后，channels 配置支持热重载，无需重启 Gateway：
# 触发渠道重连
openclaw channels login
openclaw channels status --probe
原因 3：飞书应用权限缺失
openclaw 与飞书通信需要特定权限范围（Scope），权限不足时连接建立后仍无法收发消息，日志中出现 missing_scope 或 Forbidden。
必须开通的权限
在飞书开放平台 → 应用权限 → 搜索并添加以下权限：
批量导入方式：在飞书控制台权限配置页，使用 JSON 批量导入，openclaw 官方文档提供完整权限列表。
权限修改后的注意事项
飞书企业应用的权限变更需要企业管理员审批。权限提交后，需联系管理员在飞书管理后台（admin.feishu.cn）审批通过，否则权限不会生效。审批完成后执行：
openclaw channels login
原因 4：事件订阅未正确配置
WebSocket 长连接模式下，飞书需要在开放平台明确启用"使用长连接接收事件"，并订阅消息事件。缺少任一步骤，连接看似建立但消息不会推送。
配置步骤
1. 进入飞书开放平台 → 应用功能 → 机器人，确认已启用机器人能力
2. 进入事件订阅 → 将接收方式切换为 “使用长连接接收事件”（非 Webhook URL 模式）
3. 添加事件订阅：搜索并添加 im.message.receive_v1（接收消息事件）
4. 保存设置后，确保 openclaw Gateway 正在运行，飞书会立即尝试建立长连接
5. 验证：
openclaw logs --follow | grep -i "feishu\|lark"
# 应出现连接建立的日志
原因 5：消息路由策略阻断
Gateway 和渠道连接正常，但发送消息后 openclaw 无响应——通常是路由策略将消息静默丢弃。
# 查看是否有消息被 drop
openclaw logs | grep "drop"
常见 drop 场景及修复：
调整 DM 和群组策略：
{ channels: { feishu: { enabled: true, appId: "${FEISHU_APP_ID}", appSecret: "${FEISHU_APP_SECRET}", // 私聊策略 dmPolicy: "open", // pairing | allowlist | open | disabled // 群组策略 groupPolicy: "open", // open | allowlist | disabled // 群组中是否强制 @Bot groups: { "*": { requireMention: true } } } } }
配置参考：完整飞书渠道配置
// ~/.openclaw/openclaw.json { channels: { feishu: { enabled: true, // 凭据（建议从环境变量引用） appId: "${FEISHU_APP_ID}", appSecret: "${FEISHU_APP_SECRET}", // 消息策略 dmPolicy: "pairing", // 私聊：配对审批 groupPolicy: "open", // 群组：允许所有 // 群组 @ 要求（按群 ID 配置，"*" 表示所有群） groups: { "*": { requireMention: true } } } } }
预防断开：心跳配置
openclaw 内置心跳机制，默认每 30 分钟向最近联系的渠道发送探活消息。可通过配置调低心跳间隔，更快发现连接异常：
{ agents: { defaults: { heartbeat: { every: "10m", // 每 10 分钟检测一次（默认 30m） target: "last", // 向最近联系的渠道发送 directPolicy: "allow" } } } } 心跳行为说明：
● 若 Agent 仅返回 HEARTBEAT_OK（300 字符内），消息会被静默抑制，不会推送给用户
● 若主队列繁忙，当前心跳跳过，下一周期重试
● 心跳不会主动重置会话空闲计时器
常见问题
Q：飞书开放平台显示长连接已建立，但 openclaw 日志没有连接成功的记录，怎么排查？
飞书平台显示的连接状态有时有延迟。优先检查 openclaw 日志：openclaw logs | grep -i feishu。若日志中出现 reconnecting 循环，通常是 App Secret 错误或权限审批未通过。尝试执行 openclaw channels login 强制重新认证。
Q：切换到新的飞书应用后，旧的连接还在，新的连接建立失败？
删除旧的飞书渠道配置，清除缓存的凭据后重新配置：
openclaw config unset channels.feishu
# 重新写入新应用凭据
openclaw channels login
Q：飞书群组机器人正常，但私聊不响应？
私聊（DM）走 dmPolicy 策略，默认为 pairing，需要先完成配对才能响应。执行 openclaw pairing list feishu 查看是否有待批准的配对请求，或将 dmPolicy 改为 open 允许所有私聊。
Q：openclaw 与飞书断开后会自动重连吗？
会。WebSocket 断开后，openclaw 会按指数退避策略自动重试（默认最多 3 次，最大间隔 30 秒），轻微的网络抖动通常可自动恢复。若持续无法重连，需要手动执行 openclaw channels login 触发重新认证流程。
Q：企业版飞书和普通版飞书的配置有区别吗？
企业版飞书（Feishu for Enterprise）的应用审批流程更严格，权限变更必须经管理员审批，且应用需要在"应用目录"发布或由管理员直接安装。若在企业环境中使用，先确认应用已被管理员批准并安装，再进行 openclaw 的渠道配置。
总结
openclaw 与飞书断开的排查优先级：① 先确认 Gateway 在运行 → ② 检查渠道 probe 状态 → ③ 查日志找具体错误信号 → ④ 按错误类型修复凭据/权限/事件订阅/路由策略。
WebSocket 长连接模式下，飞书侧的配置错误通常在建立连接时就会失败，而非连接后断开——若连接曾经正常、突然断开，优先检查 Gateway 进程存活和 App Secret 是否被重置。
本文基于 OpenClaw 官方文档（docs.openclaw.ai）及飞书开放平台文档，内容对应 2026 年 3 月版本，权限名称和事件 ID 建议以飞书开放平台最新文档为准。
延伸资源
● OpenClaw 飞书渠道文档：https://docs.openclaw.ai/channels/feishu
● OpenClaw 渠道故障排查：https://docs.openclaw.ai/channels/troubleshooting
● 飞书开放平台：https://open.feishu.cn
