Hermes 对接飞书企业群完整配置指南：权限、群聊策略、@触发与常见故障排查
Hermes 对接飞书企业群完整配置指南：权限、群聊策略、@触发与常见故障排查
本文根据 Hermes 接入飞书企业群的实际配置与排障过程整理，重点解决以下问题：
- 自己
@机器人可以回复，其他成员@机器人不回复；- 希望企业群内所有成员都能使用机器人；
- 希望机器人只在被
@时回复；- 配置已经修改，但重启后仍然没有生效；
- 不清楚每个飞书环境变量的具体作用；
- 不清楚应该修改哪个文件、重启哪个进程。
一、最终要实现的效果
本文推荐的生产环境策略是：
- 企业群内所有成员都可以使用机器人；
- 群聊中必须
@机器人才触发； - 私聊可以正常使用；
- 使用 WebSocket 长连接接收飞书事件；
- 不需要公网回调地址；
- 避免机器人监听并回复群内所有普通消息。
对应的核心配置如下：
FEISHU_ALLOW_ALL_USERS=true FEISHU_ALLOWED_USERS= FEISHU_GROUP_POLICY=open FEISHU_REQUIRE_MENTION=true这四项中，最容易配置错误的是：
FEISHU_ALLOW_ALL_USERS=false即使设置了：
FEISHU_GROUP_POLICY=open如果FEISHU_ALLOW_ALL_USERS仍然是false，其他群成员仍可能被用户授权层拦截。
二、完整推荐配置
下面是一份适合“飞书企业群内所有成员都能使用，但必须 @ 机器人”的配置模板。
# ================================================== # Hermes 基础环境 # ================================================== TERMINAL_ENV=local # ================================================== # 飞书应用认证 # ================================================== FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxxx FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx # ================================================== # 飞书平台类型 # ================================================== FEISHU_DOMAIN=feishu # ================================================== # 飞书消息接入方式 # ================================================== FEISHU_CONNECTION_MODE=websocket # ================================================== # 用户访问控制 # ================================================== FEISHU_ALLOW_ALL_USERS=true # 开启全部用户后，此项留空 FEISHU_ALLOWED_USERS= # ================================================== # 群聊权限策略 # ================================================== FEISHU_GROUP_POLICY=open # ================================================== # 群聊是否必须 @ 机器人 # ================================================== FEISHU_REQUIRE_MENTION=true # ================================================== # 默认飞书会话，可用于定时任务主动发送消息 # ================================================== FEISHU_HOME_CHANNEL=oc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx三、配置项与功能清单
1.FEISHU_APP_ID
FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxxx功能
飞书应用的 App ID，用于标识当前机器人应用。
在哪里获取
进入飞书开放平台：
开发者后台 → 企业自建应用 → 凭证与基础信息 → App ID修改后达到的效果
让 Hermes 连接到指定的飞书机器人应用。
常见问题
如果 App ID 填错，通常会出现：
- WebSocket 无法连接；
- 获取访问令牌失败；
- 飞书机器人无法上线；
- Hermes 日志出现应用认证错误。
2.FEISHU_APP_SECRET
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx功能
飞书应用密钥，Hermes 使用它申请应用访问凭证。
修改后达到的效果
允许 Hermes 以当前飞书应用的身份读取事件、发送消息。
安全要求
App Secret 不能：
- 上传到 GitHub；
- 发到公开群；
- 写进博客截图；
- 放入前端代码；
- 直接粘贴到公开问题中。
如果密钥已经在截图中暴露，应立即进入飞书开放平台重置 App Secret。
3.FEISHU_DOMAIN
FEISHU_DOMAIN=feishu功能
指定连接的是飞书中国版还是 Lark 国际版。
常见取值
| 配置值 | 对应平台 |
|---|---|
feishu | 中国大陆飞书 |
lark | Lark 国际版 |
修改后达到的效果
让 Hermes 请求正确的平台接口域名。
中国大陆企业一般使用：
FEISHU_DOMAIN=feishu如果误写为lark，可能出现登录、鉴权或者接口访问失败。
4.FEISHU_CONNECTION_MODE
FEISHU_CONNECTION_MODE=websocket功能
指定 Hermes 接收飞书消息事件的方式。
推荐配置
FEISHU_CONNECTION_MODE=websocketWebSocket 模式的特点
- 不需要公网域名；
- 不需要 HTTPS 回调地址；
- 不需要配置反向代理；
- 适合本地电脑、内网服务器和普通 VPS；
- Hermes 主动连接飞书事件服务器。
修改后达到的效果
让飞书通过长连接把群消息和私聊消息推送给 Hermes。
注意事项
飞书开发者后台也必须选择：
使用长连接接收事件Hermes 配置为 WebSocket，但飞书后台仍使用 HTTP 回调时，消息可能无法到达 Hermes。
5.FEISHU_ALLOW_ALL_USERS
FEISHU_ALLOW_ALL_USERS=true功能
控制是否允许所有飞书用户调用 Hermes。
这是“别人 @ 机器人不回复”问题中最关键的配置之一。
配置效果
| 配置 | 效果 |
|---|---|
true | 所有用户可以使用机器人 |
false | 仅允许授权或白名单中的用户 |
允许企业群所有成员使用
配置为：
FEISHU_ALLOW_ALL_USERS=true典型错误
错误配置：
FEISHU_ALLOW_ALL_USERS=false FEISHU_ALLOWED_USERS=* FEISHU_GROUP_POLICY=open这里存在两个问题：
FEISHU_ALLOW_ALL_USERS=false会启用用户限制；FEISHU_ALLOWED_USERS=*不应当被当作全员通配符使用。
正确配置：
FEISHU_ALLOW_ALL_USERS=true FEISHU_ALLOWED_USERS= FEISHU_GROUP_POLICY=open6.FEISHU_ALLOWED_USERS
FEISHU_ALLOWED_USERS=功能
配置允许使用机器人的飞书用户 ID 白名单。
适用场景
只允许指定员工使用机器人时，可以填写：
FEISHU_ALLOW_ALL_USERS=false FEISHU_ALLOWED_USERS=ou_user001,ou_user002,ou_user003多个用户 ID 使用英文逗号分隔：
FEISHU_ALLOWED_USERS=ou_xxxxx,ou_yyyyy,ou_zzzzz建议不要在逗号后增加空格。
允许所有人时
配置为：
FEISHU_ALLOW_ALL_USERS=true FEISHU_ALLOWED_USERS=也可以直接删除或注释白名单配置：
# FEISHU_ALLOWED_USERS=不推荐配置
FEISHU_ALLOWED_USERS=**不一定会被 Hermes 解析为所有用户，反而可能被当作一个普通字符串。
7.FEISHU_GROUP_POLICY
FEISHU_GROUP_POLICY=open功能
控制机器人在飞书群聊中的访问策略。
常见策略
| 策略 | 效果 |
|---|---|
open | 群内成员均可调用 |
allowlist | 只有白名单成员可以调用 |
admin_only | 只有管理员可以调用 |
disabled | 禁止该群使用机器人 |
不同 Hermes 版本支持的策略名称可能略有区别，应以当前版本生成的示例配置为准。
允许所有群成员使用
FEISHU_GROUP_POLICY=open仅允许白名单成员使用
FEISHU_ALLOW_ALL_USERS=false FEISHU_ALLOWED_USERS=ou_xxxxx,ou_yyyyy FEISHU_GROUP_POLICY=allowlist重要说明
FEISHU_GROUP_POLICY=open只代表群聊策略开放。
如果同时存在：
FEISHU_ALLOW_ALL_USERS=false用户仍可能在更上层的授权检查中被拒绝。
因此“所有人可用”需要同时设置：
FEISHU_ALLOW_ALL_USERS=true FEISHU_GROUP_POLICY=open8.FEISHU_REQUIRE_MENTION
FEISHU_REQUIRE_MENTION=true </