Hermes + 飞书 (Feishu) 配置指南

前置条件

• 飞书账号（个人版也可以创建自建应用 ✅）
• 管理员后台 open.feishu.cn 访问权限
• Hermes Agent 已安装且能正常运行

---

架构示意图

架构说明

消息从飞书 App 发出后经过三层处理：

1. 飞书开放平台 — 自建应用通过事件订阅收到消息，通过 WebSocket 或 Webhook 推送给 Hermes
2. Hermes Gateway — Feishu Adapter 接收消息，去重、批量合并后交给 Gateway Core 路由到 Agent
3. Hermes Agent Core — LLM 处理消息，生成回复，经由反向路径发送回飞书

---

一、飞书开放平台侧配置

1.1 创建自建应用

有两种方式：

方式 A：模版创建（推荐 · 即刻获得 App ID/Secret）⭐

1. 浏览器打开 https://open.feishu.cn/app，用飞书 App 扫码登录
2. 点击「创建应用」→ 选择「使用模版创建」→ 搜索 "机器人" 相关模版
3. 选择模版后，应用立即创建完成，无需填写任何信息
4. 进入应用详情页 → 左侧 凭证与基础信息 → App ID 和 App Secret 已经自动生成
5. 直接复制到 .env 即可

✅ 优势：省去「创建版本 → 申请发布 → 审核」流程，模版自带基本权限和事件配置

方式 B：空白创建（手动配置）

1. 浏览器打开 https://open.feishu.cn/app，用飞书 App 扫码登录
2. 点击「创建应用」→ 选择「企业自建应用」→ 填写名称（如 "Hermes Bot"）和描述
3. 创建后进入应用详情页，后续需手动添加事件和权限

1.2 获取凭证

左侧菜单 → 凭证与基础信息

页面字段	.env 变量	必填
App ID	FEISHU_APP_ID	✅ 必填
App Secret	FEISHU_APP_SECRET	✅ 必填

1.3 配置事件订阅（可选 · 模版创建可能已有）

左侧菜单 → 事件与回调

页面从上到下分三个区：

① 订阅方式（推送地址）

默认显示「监听回调 URL」，这是 Webhook 模式用的。
如果打算用 WebSocket 直连（推荐），通常可在页面下方选择「长轮询订阅」或用客户端 SDK 直连——Hermes 默认就是 WebSocket 模式，无需配置推送 URL。

② 加密策略（可选）

此区域包含两个值，WebSocket 模式可完全跳过：

字段	界面位置	说明
Encrypt Key	「加密策略」下方，默认关闭，点「重置」生成	消息加密用，WebSocket 模式不需要
Verification Token	「加密策略」下方，直接显示（内容用 **** 遮盖）	请求来源校验，WebSocket 模式不需要

③ 事件列表

1. 确认是否已有 im.message.receive_v1（模版创建可能已预配）
2. 如果没有，点击「添加事件」搜索并添加

⚠️ 核心结论：只用 App ID + App Secret 就能启动。 Encrypt Key 和 Verification Token 在 WebSocket 模式下非必需，.env 中注释掉即可，Hermes 启动时会跳过校验。

事件	说明	必需
im.message.receive_v1	接收用户/群聊消息（核心）	✅
im.message.message_read_v1	消息已读回执（可选）	❌

⚠️ 添加事件后，需在 权限管理 中添加对应的权限，否则事件无法生效。

1.4 配置权限

左侧菜单 → 权限管理

权限	用途	必需
im:message:send_as_bot	以 Bot 身份发送消息	✅
im:message:readonly	读取用户发给 Bot 的消息	✅
im:chat:readonly	获取群聊信息	✅
im:resource:readonly	获取消息中的图片/文件资源	✅
contact:contact:readonly	读取用户信息（识别发送者身份）	❌

1.5 发布应用

左侧菜单 → 版本管理与发布 → 创建版本 → 填写版本号和描述 → 「保存」→ 「申请发布」

企业自建应用需管理员审核通过。

---

二、Hermes 侧配置

2.1 方式 A：.env 配置（推荐）

在 ~/.hermes/.env 或 /opt/data/.env 中添加：

# ========== 飞书 Feishu (必填) ==========
FEISHU_APP_ID=cli_a7f23e8a4b38d510
FEISHU_APP_SECRET=p0R6tVk2mN8xQw...

# ========== 事件校验 (可选，WebSocket 模式可跳过) ==========
# FEISHU_VERIFICATION_TOKEN=abCdEf123456...
# FEISHU_ENCRYPT_KEY=abcdef1234567890abcdef1234567890

# ========== 连接方式 (可选) ==========
FEISHU_DOMAIN=feishu                  # feishu (国内) 或 lark (国际版)
FEISHU_CONNECTION_MODE=websocket      # websocket (默认/推荐) 或 webhook

# ========== 权限控制 (可选) ==========
FEISHU_GROUP_POLICY=allowlist         # allowlist 或 open
FEISHU_ALLOWED_USERS=ou_xxx1,ou_xxx2 # 允许使用 Bot 的 open_id 列表
FEISHU_ALLOW_BOTS=mentions            # none | mentions (仅@响应) | all

# ========== 高级调优 (可选) ==========
# HERMES_FEISHU_TEXT_BATCH_MAX_MESSAGES=8
# HERMES_FEISHU_TEXT_BATCH_MAX_CHARS=4000
# HERMES_FEISHU_DEDUP_CACHE_SIZE=1024

2.2 方式 B：config.yaml 配置

# ~/.hermes/config.yaml
gateway:
  enabled: true
  platforms:
    feishu:
      enabled: true
      extra:
        app_id: "cli_a7f23e..."
        app_secret: "p0R6tVk..."
        # encrypt_key / verification_token 可选
        connection_mode: "websocket"   # websocket | webhook
        group_policy: "allowlist"
        allow_bots: "mentions"

2.3 启动网关

# 配置完毕后启动 gateway
hermes gateway run

# 或安装为后台服务
hermes gateway install
hermes gateway start

🟢 验证方法：

• 查看启动日志，出现以下内容即表示 WebSocket 连接成功：

hermes-agent  | [Lark] [2026-05-14 20:05:08,325] [INFO] connected to wss://msg-frontier.feishu.cn/

• 然后在飞书 App 中搜索 Bot 名称（即自建应用名称）→ 发送消息 → 看 Hermes 是否回复

---

三、使用方法

3.1 私聊 (DM)

• 在飞书 App 中搜索 Bot 名称（即自建应用名称）
• 进入对话，直接发送消息
• 等同于向 Hermes 发起一次命令行对话

3.2 群聊 (@ 提及)

• 将 Bot 拉入群聊（群设置 → 添加机器人 → 选择你的应用）
• 必须 @ 提及 Bot 才会触发响应（受 FEISHU_ALLOW_BOTS=mentions 控制）
• 支持命令：/help, /new, /retry 等 Hermes 斜杠命令

3.3 管理命令（群聊中可用）

命令	说明
/help	查看所有可用命令
/new	重置当前会话（开始新对话）
/title <name>	命名当前会话
/retry	重新生成上一次回复
/undo	撤回上一轮
/model <name>	切换模型
/verbose	切换详细输出模式（展示思考链）
/status	查看当前会话状态
/platforms	查看所有平台连接状态
/restart	重启 Gateway

3.4 风控与话题隔离

• /approve — 批准待审批的命令（管理员用）
• /deny — 拒绝待审批的命令
• /sethome — 将当前群聊/私聊设置为 home 频道
• 每条消息独立会话 Token，Bot 回复前会显示 🤔 Typing... 状态

3.5 多媒体支持

• 图片 — 发送图片，Hermes 会缓存到本地并用 vision 能力分析
• 文件 — 支持文件接收（受 im:resource:readonly 权限控制）
• 语音 — 语音消息自动转录为文字（需 STT 组件配置）

---

四、最新版已知问题 (截至 2026-05)

🐞 Markdown 表格渲染异常

Issue #9549 — 飞书消息中 Markdown 表格不渲染，Hermes 生成的表格内容在飞书中显示为纯文本而非表格。

影响范围： 所有包含 Markdown 表格的回复

临时方案： 使用列表、分隔线等替代表格格式

🐞 群聊回复停留在群聊中

Issue #24290 — 在群聊中 @ Bot 后，回复有时不能保持在群聊线程中，可能发送到错误的位置。

影响范围： 群聊场景

状态： 已有修复 commit

🐞 WebSocket 断连重连

表现： 网络波动后 WebSocket 连接断开，默认重试 30 次，间隔 120 秒。在长时间无人值守运行时可能丢失消息。

配置调优：

HERMES_FEISHU_WS_RECONNECT_NONCE=60       # 重试次数（默认 30）
HERMES_FEISHU_WS_RECONNECT_INTERVAL=30    # 重试间隔秒数（默认 120）

🐞 消息去重可能误判

表现： 飞书 WebSocket 偶发重复推送事件，内部使用 24 小时去重缓存（dedup），极端情况下正常消息可能被误判为重复。

影响范围： 高频消息场景

🐞 文本拆分连接延迟

表现： 长消息（超过 4000 字符）自动拆分发送，中间有 100ms 延迟 + 每段间 50ms 延迟，导致用户在飞书中看到消息分段逐条出现。

⚠️ 已知限制

• 最大消息长度 8000 字符 — 超过会被截断
• 不支持富文本卡片消息 — 仅支持纯文本和 Markdown
• Webhook 模式下需要公网地址 — 飞书必须能访问到 Hermes 的 Webhook 地址
• lark_oapi 依赖 — 需要提前安装 pip install lark-oapi
• 单 Bot 模式 — 目前 Hermes 只支持单个飞书 Bot 实例

---

五、排错指南

消息发出去 Bot 不回复

1. 检查 Gateway 日志：grep feishu ~/.hermes/logs/gateway.log | tail -20
2. 确认应用已发布且管理员已审核
3. 确认事件 im.message.receive_v1 已添加
4. 确认权限已添加并已生效
5. 飞书中重新搜索 Bot 名称，确认是已发布版本

WebSocket 连接失败

1. 检查 FEISHU_APP_ID 和 FEISHU_APP_SECRET 是否正确
2. 确认网络能访问飞书 API（国内需稳定外网）
3. 尝试切换到 Webhook 模式：FEISHU_CONNECTION_MODE=webhook

Bot 在群聊中不响应 @ 提及

1. 确认 FEISHU_ALLOW_BOTS=mentions（或 all）
2. 确认 Bot 已被添加到群聊（群设置 → 机器人）
3. Verify 确认 Bot 的 open_id 正确（应用凭证页面可查）