年最新版openclaw飞书断开排查指南：一步步教你完整重连详细步骤
openclaw 跟飞书（Feishu）之间的连接，走的是 WebSocket 长连接模式，不是传统的 Webhook。这意味着：连接断开，十有八九不是网络配置的锅，而是 Gateway 没跑起来、飞书应用凭据过期、事件订阅没打开、或者权限配置不全这四类原因。下面从快速诊断到逐个修复，把已知的断开场景都过一遍。
飞书连接机制说明
在追查断开原因之前，先搞清楚 openclaw 和飞书是怎么连的：
| 连接模式 | 说明 | 适用场景 |
|---|---|---|
| WebSocket 长连接（推荐） | openclaw 主动向飞书建立持久连接，无需公网 IP | 本地部署、内网环境 |
| Webhook 模式 | 飞书推送事件到 openclaw 的公网 URL | 有公网 IP 的服务器 |
关键点来了：长连接模式下，只要 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状态对照表：
| 诊断结果 | 含义 | 跳转 |
|---|---|---|
Runtime: stopped | Gateway 未运行 | → 原因 1 |
channels: feishu disconnected | 飞书渠道断开 | → 原因 2 / 3 / 4 |
probe: failed | 渠道可达性问题 | → 原因 2 |
日志含 401 / 403 / Forbidden | 认证或权限问题 | → 原因 2 / 3 |
日志含 missing_scope | 权限范围缺失 | → 原因 3 |
| Gateway 正常但消息无响应 | 路由策略问题 | → 原因 5 |
原因 1：Gateway 未运行
这事最常发生。系统重启、手滑关了、或者崩溃了，Gateway 进程没了，飞书连接自然跟着断。
# 确认当前状态
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预防措施：没配开机自启的话，可以这样搞定：
# 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。
必须开通的权限
在飞书开放平台 → 应用权限 → 搜索并添加以下权限：
| 权限 | 用途 |
|---|---|
im:message | 读写消息（核心权限） |
im:message.group_at_msg | 接收群组 @消息 |
im:message.p2p_msg | 接收私聊消息 |
application:bot.menu:write | Bot 菜单操作 |
批量导入方式：在飞书控制台权限配置页，使用 JSON 批量导入，openclaw 官方文档提供了完整权限列表。
权限修改后的注意事项
飞书企业应用的权限变更需要企业管理员审批。提交权限后，记得联系管理员在飞书管理后台（admin.feishu.cn）审批通过，否则不会生效。审批完执行：
openclaw channels login原因 4：事件订阅未正确配置
长连接模式下，飞书那边必须明确把接收方式切换成"使用长连接接收事件"，并且订阅消息事件。缺了哪一步，连接看着建好了，但消息根本不会推过来。
配置步骤
- 进入飞书开放平台 → 应用功能 → 机器人，确认已启用机器人能力
- 进入事件订阅 → 将接收方式切换为 "使用长连接接收事件"（不是 Webhook URL 模式）
- 添加事件订阅：搜索并添加
im.message.receive_v1（接收消息事件） - 保存设置后，确保 openclaw Gateway 正在运行，飞书会立即尝试建立长连接
- 验证：
openclaw logs --follow | grep -i "feishu|lark"
# 应出现连接建立的日志原因 5：消息路由策略阻断
Gateway 和渠道都正常，但消息发出去后 openclaw 没反应——往往是路由策略把消息静默丢弃了。
# 查看是否有消息被 drop
openclaw logs | grep "drop"常见 drop 场景及修复：
| 日志关键字 | 原因 | 修复方式 |
|---|---|---|
mention required | 群组消息要求 @Bot，但没 @ | 在群里 @你的 Bot 发消息 |
pairing pending | 私聊用户未配对 | openclaw pairing list feishu 后批准 |
not in allowlist | 用户不在白名单 | 在配置中添加用户或改为 open 策略 |
channel disabled | 飞书渠道被禁用 | enabled: true |
调整 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 loginQ：飞书群组机器人正常，但私聊不响应？
私聊（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 状态 → ③ 查日志找具体错误信号 → ④ 按错误类型修复凭据/权限/事件订阅/路由策略。
长连接模式下，飞书侧的配置错误通常在建立连接时就会失败，而不是连接后断开——如果连接曾经正常、突然断掉，优先检查 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