Hermes对接飞书群无响应：全流程排查与修复指南（Linux版）

在基于Linux系统使用Hermes Agent对接飞书群聊时，“私聊机器人可正常响应、群聊@机器人无任何反馈”是高频出现的问题。这一问题并非单一诱因导致，核心集中在飞书应用配置不全、Hermes网关策略未放开、权限未授权或版本未发布等环节。本文将从基础状态检查到深层日志分析，拆解全流程排查步骤，提供可直接复制执行的修复命令与配置方案，帮助技术人员高效定位并解决Hermes与飞书群对接的响应问题。

一、Hermes群聊支持的核心逻辑

在开始排查前，先明确Hermes对飞书群聊的核心支持规则，这能帮助我们快速锁定问题方向：

  • Hermes对飞书群聊默认采用“白名单模式”，需手动配置为开放策略才能接收群消息；
  • 群聊场景下，Hermes不会自动响应消息，必须通过@机器人的方式触发（私聊无需@）；
  • 飞书消息能否推送至Hermes网关，取决于飞书开放平台的权限配置、事件订阅及版本发布状态；
  • 网关连接状态、模型配对授权是Hermes响应消息的基础前提，缺一不可。

二、第一步：基础状态检查与网关重启

排查的核心原则是“先确认基础连通性，再排查深层配置”，首先通过命令检查Hermes网关状态并重启，排除网关未运行的基础问题。

2.1 查看Hermes网关状态

通过以下命令可直接查看网关运行状态及飞书通道连接情况：

hermes status

正常状态下，输出内容应包含“running”（网关运行中）、“feishu connected”（飞书通道已连接）；若未显示相关状态，说明网关未正常启动或飞书通道未连通。

2.2 重启Hermes网关

无论状态是否正常，先执行重启操作确保网关加载最新配置：

hermes gateway restart

若重启后提示“权限异常”或“服务未找到”，可先停止后台服务再手动启动：

hermes gateway stop
hermes gateway

手动启动（前台运行）的优势是能实时看到网关日志，这也是后续排查的关键方式。

三、第二步：Hermes核心配置修复（Linux一键命令）

Hermes对接飞书群无响应的核心配置问题集中在“群聊策略未放开”“用户权限拦截”“飞书凭证未配置”三个维度，以下是可直接复制执行的修复命令，按顺序执行即可覆盖90%的配置问题：

# 1. 放开飞书群聊策略（默认白名单模式会拦截所有群消息）
hermes config set FEISHU_GROUP_POLICY open

# 2. 允许所有用户访问（测试场景下优先开启，避免用户权限拦截）
hermes config set GATEWAY_ALLOW_ALL_USERS true

# 3. 关闭“仅@回复”限制（可选，提升群聊使用便捷性）
hermes config set GATEWAY_REPLY_AT_ONLY false

# 4. 配置飞书应用基础凭证（替换为自身应用的App ID和Secret）
hermes config set FEISHU_APP_ID cli_xxxx
hermes config set FEISHU_APP_SECRET xxxx

# 5. 若飞书开放平台配置了加密/校验，补充以下参数（与开放平台保持一致）
# hermes config set FEISHU_ENCRYPT_KEY xxxx
# hermes config set FEISHU_VERIFICATION_TOKEN xxxx

# 6. 重启网关使配置生效
hermes gateway restart

3.1 不同配置场景的优化方案

针对实际使用中不同的配置参数组合，以下是两个典型场景的优化配置（直接替换即可使用）：

场景1：备份Hermes机器人配置

HERMES_MAX_ITERATIONS=90
FEISHU_APP_ID=cli_a969108d0e78dbb5
FEISHU_APP_SECRET=BaHhJsjiaLy4jxRKclPiXeo7onKjTBcf
GATEWAY_ALLOW_ALL_USERS=true
FEISHU_GROUP_POLICY=open
FEISHU_BOT_NAME=备份Hermes       # 需与飞书后台机器人名称完全一致
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_ALLOW_ALL_USERS=true
FEISHU_ALLOWED_USERS=            # 开放策略下留空即可
FEISHU_BOT_AT_MENTION_USE_NAME=true  # 基于机器人名称匹配@指令
FEISHU_LOG_LEVEL=debug               # 开启Debug模式便于日志分析

场景2：Hermes@云端机器人配置

HERMES_MAX_ITERATIONS=90
FEISHU_APP_ID=cli_a957ae909b38dcdd
FEISHU_APP_SECRET=NfaVIGuTczYnfVOZ3mtRshkMYUyP8hpq
FEISHU_BOT_NAME=Hermes@云端
FEISHU_CONNECTION_MODE=websocket
FEISHU_GROUP_POLICY=open
FEISHU_ALLOW_ALL_USERS=true
GATEWAY_ALLOW_ALL_USERS=true
FEISHU_LOG_LEVEL=debug

3.2 配置注意事项

  • FEISHU_BOT_NAME必须与飞书开放平台及群内显示的机器人名称完全一致（包括空格、特殊符号如@），名称不匹配会导致@机器人无法被识别；
  • FEISHU_CONNECTION_MODE需固定为websocket，与飞书开放平台的事件订阅方式保持一致；
  • FEISHU_LOG_LEVEL=debug建议开启，便于后续通过日志定位问题。

四、第三步：飞书开放平台配置（最易遗漏的核心环节）

即便Hermes本地配置正确，若飞书开放平台未完成权限开通、事件订阅及版本发布，群消息仍无法推送至Hermes网关。以下是需严格执行的配置步骤：

4.1 飞书开放平台核心权限开通

登录飞书开放平台（https://open.feishu.cn/），进入对应应用的“权限管理”模块，必须开通以下API权限（缺一不可）：

  1. im:message.group_at_msg:readonly（读取用户在群组中@机器人的消息）；
  2. im:message.p2p_msg:readonly（接收私聊消息，确保私聊正常的基础）；
  3. im:message（发送消息权限，机器人回复消息的核心权限）；
  4. 可选补充：im:chat:readonly（获取群信息）、admin:app.info:readonly（自动识别Bot ID）。

4.2 事件订阅配置

进入应用的“事件与回调”→“事件配置”模块，完成以下操作：

  1. 开启“启用订阅”开关；
  2. 添加核心事件：im.message.receive_v1（接收消息v1.0，飞书推送消息至Hermes的核心事件）；
  3. 选择订阅方式为“长连接（WebSocket）”，与Hermes配置的FEISHU_CONNECTION_MODE=websocket匹配；
  4. 确认事件状态为“已启用”。

4.3 版本发布（权限生效的关键）

飞书开放平台的权限与事件配置完成后，必须发布新版本才能生效，步骤如下：

  1. 进入应用的“版本管理与发布”模块；
  2. 点击“创建版本”，填写版本描述（如“群聊功能修复”）；
  3. 保存后点击“发布”，选择“企业内发布”；
  4. 等待1-2分钟，让配置在飞书后台生效。

“

注意：若未发布版本，所有权限和事件配置均不会生效，这是群聊无响应最常见的“隐性问题”。

”

五、第四步：群内使用与授权要点

完成配置后，需确保群内使用方式符合Hermes的触发规则，避免因操作不当导致无响应：

  1. 机器人必须加入目标群聊：在飞书群的“设置→应用”中添加对应机器人；
  2. 群聊触发方式：必须@机器人才能触发响应（如@备份Hermes 你好），Hermes不支持群聊自动响应未@的消息；
  3. 首次使用需授权配对：

    • 私聊机器人，会收到系统发送的pairing code；
    • 在Linux终端执行hermes pairing approve <code>完成授权；
    • 也可通过/sethome设置默认频道简化授权流程；
  4. 避免发送匿名消息：飞书匿名消息无法被机器人接收，会导致@无响应。

六、第五步：日志分析（定位问题的终极手段）

若上述配置完成后仍无响应，可通过日志分析确定问题根源。Linux系统下有两种核心方式查看Hermes网关日志：

6.1 前台运行查看实时日志（推荐）

先停止后台网关服务，再前台启动，实时查看日志输出：

hermes gateway stop
hermes gateway

此时在飞书群@机器人发送消息，日志会实时显示消息接收、处理状态，关键关键词解读如下：

日志关键词 含义 问题定位方向
✓ Feishu channel connected 飞书通道已连接 网关与飞书的基础连通性正常
message received 已收到群消息 问题集中在Hermes权限/模型配置
Mention detected 识别到@机器人指令 机器人名称匹配正常
Group message allowed (policy=open) 群消息策略为开放，允许处理 策略配置正常
无任何日志输出 未收到飞书推送的消息 飞书开放平台配置未发布/权限缺失

6.2 后台服务日志（systemd托管场景）

若Hermes网关以systemd服务形式运行，可通过以下命令查看实时日志：

# 普通用户运行的服务
journalctl --user -u hermes-gateway -f

# root用户运行的服务
journalctl -u hermes-gateway -f

其中-f参数表示实时刷新日志，便于观察群聊@机器人时的日志变化。

七、常见问题解答（FAQ）

针对排查过程中高频出现的问题，以下是精准解答：

Q1：如何查看飞书后台是否开启了群@权限？

登录飞书开放平台（https://open.feishu.cn/），进入对应应用：

  1. 点击左侧导航栏的“权限管理”；
  2. 在“API权限”列表中，搜索im:message.group_at_msg:readonly；
  3. 查看权限状态：若显示“已开通”，则群@权限已开启；若显示“未开通”，点击“开通”并完成授权。

“

提示：权限开通后需发布新版本才能生效，仅开通未发布仍会导致权限未启用。

”

Q2：飞书开放平台发布版本后多久能生效？

一般情况下，版本发布后1-2分钟即可在飞书后台生效；若企业内飞书有特殊的权限审核流程，生效时间可能延长至5分钟以内。

“

验证生效的方式：发布版本后重启Hermes网关（hermes gateway restart），前台运行网关查看是否显示✓ Feishu channel connected，再@机器人测试。

”

Q3：如何验证飞书是否推送了消息给机器人？

通过日志分析是最直接的方式：

  1. 前台启动Hermes网关（hermes gateway）；
  2. 在飞书群@机器人发送测试消息（如@Hermes@云端 测试）；
  3. 观察日志：

    • 若日志有新内容输出（无论是否包含“message received”），说明飞书已推送消息；
    • 若日志无任何新内容，说明飞书未推送消息，需重新检查权限、事件订阅及版本发布。

Q4：私聊机器人正常，群聊无响应，核心原因是什么？

这种场景下90%的原因是：

  1. 飞书开放平台未开通im:message.group_at_msg:readonly权限，或开通后未发布版本；
  2. Hermes配置的FEISHU_BOT_NAME与飞书后台机器人名称不匹配；
  3. Hermes的FEISHU_GROUP_POLICY未设置为open，仍处于白名单拦截状态。

Q5：为什么配置了正确的App ID和Secret，网关仍显示飞书未连接？

可能的原因包括：

  1. 飞书应用的“可用范围”未配置：在飞书管理后台→工作台→应用管理→对应应用，将“可用范围”设为“全部员工”或指定测试用户；
  2. 网络问题：Linux服务器无法访问飞书WebSocket服务（可通过ping open.feishu.cn测试网络连通性）；
  3. 加密/校验参数不匹配：若飞书开放平台配置了FEISHU_ENCRYPT_KEY或FEISHU_VERIFICATION_TOKEN，Hermes未同步配置对应参数。

八、全流程排查清单（快速自检）

为了便于快速定位问题，整理以下自检清单，逐一核对即可覆盖99%的问题：

  • [ ] Hermes网关显示✓ Feishu channel connected；
  • [ ] FEISHU_GROUP_POLICY配置为open；
  • [ ] GATEWAY_ALLOW_ALL_USERS配置为true；
  • [ ] 飞书开放平台已开通im:message.group_at_msg:readonly和im:message.receive_v1事件；
  • [ ] 飞书应用已发布新版本；
  • [ ] FEISHU_BOT_NAME与飞书后台机器人名称完全一致；
  • [ ] 机器人已加入目标群聊；
  • [ ] 群内使用@机器人的方式触发消息；
  • [ ] 日志中能看到message received或Mention detected关键词。

九、总结

Hermes对接飞书群无响应的排查核心可归纳为“三层定位法”：

  1. 基础层：检查网关状态与Hermes本地配置（群策略、Bot名称、凭证）；
  2. 平台层：验证飞书开放平台的权限、事件订阅与版本发布；
  3. 日志层：通过实时日志确认消息推送与处理状态。

在实际排查过程中，“飞书版本未发布”“Bot名称不匹配”“群@权限未开通”是最常见的三个问题，优先核对这三项可大幅提升排查效率。本文提供的命令与配置方案均基于Linux系统验证，可直接复制执行，若需适配Windows系统，需额外处理os.kill报错、编码等特殊问题（如export LANG=zh_CN.UTF-8）。

通过以上全流程的排查与修复步骤，可彻底解决Hermes对接飞书群无响应的问题，确保机器人在群聊场景下稳定响应@指令。