openclaw 与飞书断开：完整排查与重连指南

openclaw 与飞书（Feishu）的连接基于 WebSocket 长连接模式，而非传统 Webhook——这意味着断开的根本原因通常不是网络配置问题，而是 Gateway 未运行、飞书应用凭据失效、事件订阅未启用或权限配置不完整四类之一。本文提供从快速诊断到逐类修复的完整流程，覆盖所有已知断开场景。

飞书连接机制说明

理解断开原因前，先明确 openclaw 与飞书的连接架构：

连接模式	说明	适用场景
WebSocket 长连接（推荐）	openclaw 主动向飞书建立持久连接，无需公网 IP	本地部署、内网环境
Webhook 模式	飞书推送事件到 openclaw 的公网 URL	有公网 IP 的服务器

关键推论：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

状态对照表：

诊断结果	含义	跳转
`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 进程不再存活，飞书 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。

必须开通的权限

在飞书开放平台 → 应用权限 → 搜索并添加以下权限：

权限	用途
`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：事件订阅未正确配置

WebSocket 长连接模式下，飞书需要在开放平台明确启用"使用长连接接收事件"，并订阅消息事件。缺少任一步骤，连接看似建立但消息不会推送。

配置步骤

进入飞书开放平台 → 应用功能 → 机器人，确认已启用机器人能力
进入事件订阅 → 将接收方式切换为 "使用长连接接收事件"（非 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 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
七牛云 AI 推理服务（多模型接入）：https://www.qiniu.com/ai/models