本文介绍 Hermes Agent 如何接入飞书，以及与飞书有关的的高级配置
配置文件位置：~/.hermes/config.yaml 和 ~/.hermes/.env

创建飞书应用

1
hermes gateway setup

选择 Feishu / Lark，然后用飞书手机 App 扫码。Hermes 会自动帮你创建好机器人应用，配好权限，保存凭证。

基础配置

确认 ~/.hermes/.env 文件中有以下必需配置：

1
2
3
4
5
# 必需
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret...ishu
FEISHU_DOMAIN=feishu                         # feishu（中国）或 lark（国际）
FEISHU_CONNECTION_MODE=websocket

也可以用交互式配置：hermes gateway setup，选择 Feishu / Lark 按提示填写。

配置完成后，重启 Gateway：

1
hermes gateway restart

然后在飞书里给机器人发条消息，确认连接正常。

安全配置

用户白名单

生产环境强烈建议设置白名单：

1
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy

如果留空，任何能接触到机器人的人都可能使用它。群聊中会根据发送者的 open_id 检查白名单。

群聊策略

全局策略

FEISHU_GROUP_POLICY 控制 Hermes 在群聊中的响应行为：

1
FEISHU_GROUP_POLICY=allowlist   # 默认值
值 行为
open 响应任何用户的 @ 消息
allowlist 只响应白名单用户的 @ 消息
disabled 忽略所有群消息

所有模式下，机器人都必须被明确 @（或 @all）才会处理消息。私聊总是绕过这个检查。

免 @ 模式

设置 FEISHU_REQUIRE_MENTION=false 让 Hermes 读取所有群消息，不需要 @：

1
FEISHU_REQUIRE_MENTION=false

⚠️ 注意： 这个设置只控制 Hermes 收到消息后是否响应。如果飞书平台层面不推送非 @ 消息给 Hermes（企业自建应用的常见限制），Hermes 根本收不到消息，自然也无法响应。

单群独立控制

通过 config.yaml 的 group_rules 可以为每个群单独设置策略：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
platforms:
  feishu:
    extra:
      default_group_policy: "open"     # 未列出的群用这个默认策略
      admins:                          # 可以管理机器人设置的用户
        - "ou_admin_open_id"
      group_rules:
        "oc_group_chat_id_1":
          policy: "allowlist"          # open | allowlist | blacklist | admin_only | disabled
          allowlist:
            - "ou_user_open_id_1"
            - "ou_user_open_id_2"
        "oc_free_chat":
          policy: "open"
          require_mention: false       # 这个群不需要 @
策略 说明
open 群里任何人都能用
allowlist 只有 allowlist 里的用户能用
blacklist 除了 blacklist 里的人都能用
admin_only 只有全局 admins 列表里的用户能用
disabled 完全忽略这个群的所有消息

环境变量总览

变量 必需 默认值 说明
FEISHU_APP_ID ✅ — 飞书/Lark App ID
FEISHU_APP_SECRET ✅ — 飞书/Lark App Secret
FEISHU_DOMAIN — feishu feishu（中国）或 lark（国际）
FEISHU_CONNECTION_MODE — websocket 固定使用 websocket
FEISHU_ALLOWED_USERS — (空) 用户白名单（Open ID 逗号分隔）
FEISHU_ALLOW_BOTS — none 接受其他机器人消息：none、mentions、all
FEISHU_REQUIRE_MENTION — true 群消息是否需要 @ 机器人
FEISHU_HOME_CHANNEL — — 定时任务/通知输出的频道 ID
FEISHU_REACTIONS — true 是否显示”正在输入”状态反应
FEISHU_GROUP_POLICY — allowlist 群消息策略：open、allowlist、disabled
FEISHU_BOT_OPEN_ID — (空) 机器人的 open_id（用于 @ 检测）
FEISHU_BOT_USER_ID — (空) 机器人的 user_id（用于 @ 检测）
FEISHU_BOT_NAME — (空) 机器人的显示名称（用于 @ 检测）

单群 ACL 设置通过 config.yaml 的 platforms.feishu.extra 配置。

消息处理优化

文本合并

用户快速发送多条文本消息时，会自动合并成单个事件：

设置 环境变量 默认值
静默期 HERMES_FEISHU_TEXT_BATCH_DELAY_SECONDS 0.6 秒
最大消息数 HERMES_FEISHU_TEXT_BATCH_MAX_MESSAGES 8 条
最大字符数 HERMES_FEISHU_TEXT_BATCH_MAX_CHARS 4000 字符

媒体合并

快速发送多个媒体（比如拖拽多张图片）时：

设置 环境变量 默认值
静默期 HERMES_FEISHU_MEDIA_BATCH_DELAY_SECONDS 0.8 秒

同群串行处理

同一个聊天内的消息串行处理（一次一条），保证对话连贯性。不同聊天之间并发处理。

环境变量示例

.env：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
# ==================== 必须配置 ====================
# 飞书 App ID
FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
# 飞书 App Secret
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# 飞书域名：feishu（中国）或 lark（国际）
FEISHU_DOMAIN=feishu
# 连接模式：websocket
FEISHU_CONNECTION_MODE=websocket


# ==================== 推荐配置 ====================
# 用户白名单：逗号分隔的 Open ID 列表，留空则任何人可用
FEISHU_ALLOWED_USERS=ou_xxxxxxxxxxxx,ou_yyyyyyyyyyyy
# 家频道：定时任务和通知推送的目标群聊 ID。配置方法：在目标群聊中发送 /set-home 命令即可
FEISHU_HOME_CHANNEL=oc_xxxxxxxxxxxxxxxx
# 是否显示"正在输入"状态反应（默认 true）
FEISHU_REACTIONS=true


# ==================== 群聊策略 ====================
# 群聊策略：open（任何人）| allowlist（白名单）| disabled（禁用）
FEISHU_GROUP_POLICY=allowlist
# 群消息是否需要 @ 机器人（默认 true）
FEISHU_REQUIRE_MENTION=true
# 接受其他机器人消息：none（忽略）| mentions（仅@）| all（全部）
FEISHU_ALLOW_BOTS=none


# ==================== 可选配置（一般不需要改） ====================
# 机器人身份（通常自动检测，检测失败时手动设置）
# FEISHU_BOT_OPEN_ID=ou_bot_xxxxxxxxxxxx
# FEISHU_BOT_USER_ID=bot_user_id_xxxx
# FEISHU_BOT_NAME=Hermes Bot

# ==================== 消息处理调优（保持默认值即可，无需修改） ====================
# 文本合并静默期（秒）
# HERMES_FEISHU_TEXT_BATCH_DELAY_SECONDS=0.6
# 文本合并最大消息数
# HERMES_FEISHU_TEXT_BATCH_MAX_MESSAGES=8
# 文本合并最大字符数
# HERMES_FEISHU_TEXT_BATCH_MAX_CHARS=4000
# 媒体合并静默期（秒）
# HERMES_FEISHU_MEDIA_BATCH_DELAY_SECONDS=0.8
# 消息去重缓存大小
# HERMES_FEISHU_DEDUP_CACHE_SIZE=2048

飞书高级功能配置

以下功能需要在飞书开发者控制台中额外配置，才能让 Hermes 支持相应的交互。

卡片交互

用户点击机器人发送的交互式卡片按钮时，会触发 /card 命令事件：

  • 按钮点击变成：/card button {"key": "value", ...}
  • 动作的 value 载荷以 JSON 形式包含
  • 卡片动作有 15 分钟去重窗口

必需配置： 在飞书开发者控制台完成以下三步（缺一不可，否则点击按钮会报错 200340）：

  1. 订阅卡片动作事件： 在 事件订阅 中添加 card.action.trigger
  2. 启用交互式卡片能力： 在 应用功能 > 机器人 中确保 交互式卡片 开关已启用

文档评论智能回复

Hermes 可以回复飞书文档上的 @ 评论。当用户在文档评论中 @ 机器人时：

  • 自动读取文档内容和评论时间线
  • 用 LLM 生成回复并发布到评论线程中
  • 回复超过 4000 字符会自动分条发送

必需配置：

  • 订阅 drive.notice.comment_add_v1 事件
  • 授予 docs:doc:readonly 和 drive:drive:readonly 权限

会议邀请自动加入

你可以像邀请真人一样邀请 Hermes 机器人进入飞书视频会议。收到邀请后：

  • 自动提取邀请人、会议主题、会议号
  • 如果邀请人在白名单内，尝试自动加入会议
  • 邀请格式错误或无法加入时，会向邀请人回复说明

必需配置：

  • 订阅 vc.bot.meeting_invited_v1 事件
  • 启用视频会议权限范围

参考与常见问题