OpenClaw飞书机器人无响应与连接失败：完整排查指南 - 文章 - 开发者社区

写在前面

OpenClaw的飞书插件分为OpenClaw原生社区维护插件@openclaw/feishu和飞书官方维护插件@larksuite/openclaw-lark，推荐优先使用使用飞书官方插件，迭代更快，功能更强。本文档也是基于飞书官方插件。
如果OpenClaw Gateway活着，使用openclaw tui在Gateway本地打开对话窗口，让OpenClaw自己排查问题。

"学习一下这两篇文档：https://www.volcengine.com/docs/82379/2183190?lang=zh 和 OpenClaw飞书官方插件使用指南（公开版），排查一下XXX问题"。

一、快速分诊（5 分钟检查清单）

当OpenClaw飞书机器人出现无响应或者连接失败时，按照以下清单快速检查。

检查项 1：Gateway是否运行？
- 在终端执行 openclaw gateway status，应显示 running。
- 如果Gateway状态异常，需要先修复Gateway问题。

picture.image

检查项 2：Gateway 配置是否正常？ 日志有无报错？ 和飞书开放平台的网络联通性是否正常？
- 插件成功初始化后，飞书机器人的appId和appSecret会写入到OpenClaw的配置文件。检查配置文件openclaw.json，确认存在飞书channels配置，appId和appSecret配置正确。
- 登录飞书开放平台，导航到"凭证与基础信息"，查看appId和appSecret。
- 执行 openclaw logs --follow，查看有无飞书插件的[error] 或 connect failed 等关键词。如果有的话，执行下npx -y @larksuite/openclaw-lark-tools doctor 看看是否能修复。
- 尝试 curl https://open.feishu.cn 或 ping open.feishu.cn，确认Gateway和飞书开放平台网络连通性正常。如果连通性有异常，需要按照下面"网络/平台级问题"中的内容进行排查。
检查项 3： 飞书机器人 事件 配置和回调配置 是否正确？
- 登录飞书开放平台，导航到"事件与回调"，检查"事件配置"是否为长连接模式，且已添加 im.message.receive_v1 事件。检查"回调配置"是否为长连接模式。

picture.image

检查项 4： 机器人 应用是否发布？
- 登录飞书开放平台，导航到"版本管理与发布"页面，确认机器人应用状态为“已上线”。

picture.image

检查项 5：权限是否已开通？
- 登录飞书开放平台，导航到"权限管理"，确认 im:message.send_as_bot 核心权限已启用。

picture.image

检查项 6： 检查 是否已配对？
- 配对是指OpenClaw Gateway和飞书开放平台建立WebSocket长连接。只有建立长连接之后，双方才能进行消息通信。
- 配置好飞书机器人，首次私聊时会触发一个配对码，在gateway中输入该命令进行授权。
- 或者在安装配置飞书官方插件时选择创建机器人，然后通过飞书扫描配对。
检查项 7 ：官方插件安装与诊断（推荐）
- 在终端执行 npx -y @larksuite/openclaw-lark-tools install，确保已安装或更新官方 Feishu/Lark 插件 openclaw-lark。
- 使用 openclaw plugins list 确认插件列表；如果仍存在旧版 feishu 插件，可在详细排查阶段按文档说明禁用。
- 如仍不确定权限、账户或 API 连通性问题，可运行 npx -y @larksuite/openclaw-lark-tools doctor 获取一份自动化诊断报告。
检查项 8 ：群聊是否 @机器人？
- 如果是群聊，默认需要 @ 机器人才会响应。
检查项 9 ： 使用国际版Lark时，OpenClaw配置中的 domain是否正确？
- 当使用国际版Lark时，需要显式设置 domain，以确保 Gateway 连接到正确的开放平台。

如未在 openclaw.json 中显式配置 domain 字段，OpenClaw 默认使用国内版飞书端点（等价于 domain: "feishu"），无需额外设置。只有当你的租户为国际版 Lark 时，才需要显式设置 domain，以确保 Gateway 连接到正确的开放平台。

可配置路径：

全局：channels.feishu.domain

按账号：channels.feishu.accounts.<id>.domain

常用命令示例：
# 设置为 Lark（国际版）
openclaw config set channels.feishu.domain lark

# 设置为 Feishu（国内版，亦为默认）
openclaw config set channels.feishu.domain feishu

# 修改后重启网关
openclaw gateway restart

二、技术背景与架构

理解 OpenClaw 与飞书的协作方式，是排查所有问题的起点。

一般情况下，使用Gateway主动和飞书开放平台建立WebSocket 长连接这种最高效、最安全、最简单的模式。

1. WebSocket 建链流程

首先，OpenClaw 的 Gateway 服务会主动与飞书开放平台建立一个持久化的 WebSocket 连接。这个过程是所有通信的基础。

暂时无法在飞书文档外展示此内容

图 1：WebSocket 建链流程

步骤详解：

读取配置：Gateway 发起配对时从配置中读取 Feishu 渠道参数，包括 domain（"feishu"/"lark"） 、App ID、App Secret，以及已在飞书开放平台配置为长连接的事件订阅和关键权限。
DNS 解析：向 DNS 服务器解析飞书开放平台的域名（如 open.feishu.cn 或 open.larksuite.com），得到目标 IP 地址。
TLS 握手：与飞书服务器发起 TLS 握手，建立安全的 wss:// 通道。
WebSocket 握手与鉴权：通过 Feishu SDK 携带 App ID / App Secret 发起 WebSocket 握手，请求建立长连接并完成鉴权。
连接维持：连接建立后，Gateway 与飞书平台通过 心跳 ping/pong 保持连接，异常断开时会自动重连。
保存配置并验证连接：在飞书开放平台"事件配置"页面将订阅方式设置为 " 通过长连接接收事件 " 并保存。

现场判断点：

启动 Gateway 后，使用 openclaw logs --follow，应能看到类似飞书插件注册成功的日志，而不是持续的 connect failed 或 timeout。
在飞书开放平台"事件配置"页面应该配置为"通过长连接接收事件"，且配置了 im.message.receive_v1 事件。
飞书机器人本身需要正常工作：机器人应用已发布，核心权限已开通。

2. 用户消息处理流程

建链成功后，当用户与机器人交互时，消息将通过这条已建立的长连接进行端到端处理。

暂时无法在飞书文档外展示此内容

图 2：用户消息处理流程

步骤详解：

用户发送消息：用户在飞书或 Lark 客户端向机器人私聊，或在群聊中 @机器人 发送消息。
事件推送到 Gateway：飞书开放平台通过已建立的 WebSocket 长连接，将 im.message.receive_v1 事件推送到 OpenClaw Gateway。
Gateway 触发 Agent / LLM 与工具链：Gateway 根据会话配置选择对应 Agent，携带上下文和权限信息调用 LLM 及相关工具，完成意图理解与业务处理。
通过 Feishu Bot API 回复：处理完成后，Gateway 调用 Feishu Bot API 将回复消息（文本或卡片）发送回对应会话。
消息抵达客户端：回复在用户侧显示，线程与话题保持一致；如启用了流式卡片，会看到内容逐步刷新。

现场判断点：

在正常收发消息之前需要完成配对过程。
群聊场景：优先确认是否正确 @机器人，默认情况下在群聊中需要@才会响应。

三、详细排查步骤

如果快速分诊未能解决问题，请根据以下分类进行详细排查。

1. 应用级问题

这类问题通常与飞书开放平台的配置有关。

应用未发布/审批
- 现象：搜索不到机器人，或机器人无任何响应。
- 排查：进入“版本管理与发布”页面，确保你已创建一个版本并成功发布。企业内部应用通常会自动审批，但部分组织可能需要管理员手动通过。
事件/权限配置错误
- 现象：机器人能发消息但收不到消息，或反之。
- 排查：
  - 仔细核对“事件配置”页面，确保模式是“长连接” ，且 im.message.receive_v1 事件已被添加并保存。
  - 仔细核对“权限管理”，确保 im:message、im:message.send_as_bot 已启用。
私聊/群聊策略限制
- 现象：机器人只在某些群或与某些人聊天时有响应。
- 排查：
  - 私聊：OpenClaw 默认 dmPolicy 为 "pairing" 。首次私聊时，你需要在 Gateway 的日志中找到配对码，并用 openclaw pairing approve CODE 授权。
  - 群聊：确认机器人已被添加到目标群聊。同时，检查 groupPolicy 和 requireMention 配置，默认情况下，机器人只在被 @ 时才会响应。
凭证错误或失效
- 现象：Gateway 日志中出现“认证失败”、“invalid credential”或 HTTP 401/403 错误。
- 排查：
  - 重新从“凭证与基础信息”页面复制 App ID 和 App Secret。
  - 粘贴到 OpenClaw 的配置文件中，确保前后没有多余的空格或特殊字符。
  - 如果你最近重置过 App Secret，必须更新配置文件并重启 Gateway。

2. 网关/插件级问题

这类问题与 OpenClaw 本身的运行状态和配置有关。

Gateway 未运行或未重启
- 现象：任何飞书消息都无响应，openclaw gateway status 显示 stopped 或 error。
- 排查：
  - 执行 openclaw gateway restart 重启网关。
  - 使用 openclaw logs --follow 实时观察启动日志，检查有无错误信息。
官方插件安装与识别 / 禁用旧插件
- 建议在 Feishu/Lark 场景中优先使用官方插件 openclaw-lark。在终端执行 npx -y @larksuite/openclaw-lark-tools install 可完成安装或升级。
- 使用 openclaw plugins list 确认插件列表中存在 openclaw-lark，并检查是否同时存在旧版 feishu 插件。
- 若 Gateway 日志中频繁出现 plugin id mismatch 或多个飞书插件同时生效的提示，可通过命令禁用旧版/内置插件：
  - openclaw config set plugins.entries.feishu.enabled false --json
  - openclaw gateway restart
- 如仍不确定权限、账户启用或 API 连通性是否正常，建议运行：
  - npx -y @larksuite/openclaw-lark-tools doctor用于一次性检查权限、账户启用、API 连通性、用户授权以及是否存在旧版插件冲突等问题。
流式输出开关与常见问题
- 飞书渠道的流式输出可通过以下命令控制：
  - 开启：openclaw config set channels.feishu.streaming true
  - 关闭：openclaw config set channels.feishu.streaming false
- 当前版本中，群聊的流式输出能力可能受限：Gateway 日志中虽然显示 replyMode=streaming，但飞书返回的卡片 streaming_mode=false，表现为群聊只在生成完成后一次性刷出完整卡片，而非逐步流式更新。
- 这种情况通常不是 WebSocket 连接问题，而是飞书/插件在群聊场景下对流式卡片支持度的限制；如需确认，可结合 npx -y @larksuite/openclaw-lark-tools doctor 和 Gateway 日志进行分析。

3. 网络/平台级问题

这类问题通常与运行环境的网络状况有关。

出站 WebSocket 连接被阻断
- 现象：Gateway 日志反复出现 connect failed、ETIMEDOUT 或 ECONNRESET 等网络错误。
- 排查：
  - 在 Gateway 所在服务器上，尝试 curl https://open.feishu.cn 或 ping open.feishu.cn，检查能否访问飞书的开放平台。
  - 联系你的网络管理员，确认防火墙是否允许对外的 WebSocket (WSS) 连接（通常是 TCP 443 端口）。
DNS 解析失败
- 现象：日志中出现 EAI_AGAIN、ENOTFOUND 等 DNS 相关错误。
- 排查：检查服务器的 DNS 配置（如 /etc/resolv.conf），确保可以正常解析公网域名。可以尝试更换为更可靠的公共 DNS 服务器，如 8.8.8.8 或 114.114.114.114。
代理配置问题
- 现象：如果环境需要代理，但 Gateway 日志显示直连超时或连接被拒绝。
- 排查：确保已在系统环境变量（HTTP_PROXY/HTTPS_PROXY）或 OpenClaw 配置中正确设置了代理服务器地址，并且该代理支持 WebSocket 流量。

五、常用命令与入口

添加/配置飞书渠道：openclaw channels add (交互式)
查看 Gateway 状态：openclaw gateway status
查看实时日志：openclaw logs --follow
授权私聊用户：openclaw pairing approve feishu PAIRING_CODE