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_IDFEISHU_APP_ID=cli_xxxxxxxxxxxxxxxxx功能飞书应用的 App ID，用于标识当前机器人应用。在哪里获取进入飞书开放平台：开发者后台 → 企业自建应用 → 凭证与基础信息 → App ID修改后达到的效果让 Hermes 连接到指定的飞书机器人应用。常见问题如果 App ID 填错，通常会出现：WebSocket 无法连接；获取访问令牌失败；飞书机器人无法上线；Hermes 日志出现应用认证错误。2.FEISHU_APP_SECRETFEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx功能飞书应用密钥，Hermes 使用它申请应用访问凭证。修改后达到的效果允许 Hermes 以当前飞书应用的身份读取事件、发送消息。安全要求App Secret 不能：上传到 GitHub；发到公开群；写进博客截图；放入前端代码；直接粘贴到公开问题中。如果密钥已经在截图中暴露，应立即进入飞书开放平台重置 App Secret。3.FEISHU_DOMAINFEISHU_DOMAIN=feishu功能指定连接的是飞书中国版还是 Lark 国际版。常见取值配置值对应平台feishu中国大陆飞书larkLark 国际版修改后达到的效果让 Hermes 请求正确的平台接口域名。中国大陆企业一般使用：FEISHU_DOMAIN=feishu如果误写为lark，可能出现登录、鉴权或者接口访问失败。4.FEISHU_CONNECTION_MODEFEISHU_CONNECTION_MODE=websocket功能指定 Hermes 接收飞书消息事件的方式。推荐配置FEISHU_CONNECTION_MODE=websocketWebSocket 模式的特点不需要公网域名；不需要 HTTPS 回调地址；不需要配置反向代理；适合本地电脑、内网服务器和普通 VPS；Hermes 主动连接飞书事件服务器。修改后达到的效果让飞书通过长连接把群消息和私聊消息推送给 Hermes。注意事项飞书开发者后台也必须选择：使用长连接接收事件Hermes 配置为 WebSocket，但飞书后台仍使用 HTTP 回调时，消息可能无法到达 Hermes。5.FEISHU_ALLOW_ALL_USERSFEISHU_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_USERSFEISHU_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_POLICYFEISHU_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_MENTIONFEISHU_REQUIRE_MENTION=true /