Hermes 对接飞书企业群完整配置指南：权限、群聊策略、@触发与常见故障排查

本文根据 Hermes 接入飞书企业群的实际配置与排障过程整理，重点解决以下问题：

• 自己@机器人可以回复，其他成员@机器人不回复；
• 希望企业群内所有成员都能使用机器人；
• 希望机器人只在被@时回复；
• 配置已经修改，但重启后仍然没有生效；
• 不清楚每个飞书环境变量的具体作用；
• 不清楚应该修改哪个文件、重启哪个进程。

一、最终要实现的效果

本文推荐的生产环境策略是：

1. 企业群内所有成员都可以使用机器人；
2. 群聊中必须@机器人才触发；
3. 私聊可以正常使用；
4. 使用 WebSocket 长连接接收飞书事件；
5. 不需要公网回调地址；
6. 避免机器人监听并回复群内所有普通消息。

对应的核心配置如下：

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 国际版。

常见取值

修改后达到的效果

让 Hermes 请求正确的平台接口域名。

中国大陆企业一般使用：

FEISHU_DOMAIN=feishu

如果误写为lark，可能出现登录、鉴权或者接口访问失败。

4.FEISHU_CONNECTION_MODE

FEISHU_CONNECTION_MODE=websocket

功能

指定 Hermes 接收飞书消息事件的方式。

推荐配置

FEISHU_CONNECTION_MODE=websocket

WebSocket 模式的特点

• 不需要公网域名；
• 不需要 HTTPS 回调地址；
• 不需要配置反向代理；
• 适合本地电脑、内网服务器和普通 VPS；
• Hermes 主动连接飞书事件服务器。

修改后达到的效果

让飞书通过长连接把群消息和私聊消息推送给 Hermes。

注意事项

飞书开发者后台也必须选择：

使用长连接接收事件

Hermes 配置为 WebSocket，但飞书后台仍使用 HTTP 回调时，消息可能无法到达 Hermes。

5.FEISHU_ALLOW_ALL_USERS

FEISHU_ALLOW_ALL_USERS=true

功能

控制是否允许所有飞书用户调用 Hermes。

这是“别人 @ 机器人不回复”问题中最关键的配置之一。

配置效果

允许企业群所有成员使用

配置为：

FEISHU_ALLOW_ALL_USERS=true

典型错误

错误配置：

FEISHU_ALLOW_ALL_USERS=false FEISHU_ALLOWED_USERS=* FEISHU_GROUP_POLICY=open

这里存在两个问题：

1. FEISHU_ALLOW_ALL_USERS=false会启用用户限制；
2. FEISHU_ALLOWED_USERS=*不应当被当作全员通配符使用。

正确配置：

FEISHU_ALLOW_ALL_USERS=true FEISHU_ALLOWED_USERS= FEISHU_GROUP_POLICY=open

6.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

功能

控制机器人在飞书群聊中的访问策略。

常见策略

不同 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=open

8.FEISHU_REQUIRE_MENTION

FEISHU_REQUIRE_MENTION=true </