配置 Hermes Agent 连接飞书
将 Hermes Agent 连接到飞书，包括创建应用、选择 WebSocket 或 Webhook 连接模式、配置安全策略、文档评论智能回复、多媒体支持等完整指南。
Hermes Agent 可以作为完整的飞书机器人运行。连接后，你可以在私信或群聊中与 Agent 对话，接收定时任务的推送结果，并通过网关发送文本、图片、音频和文件附件。
支持两种连接模式：
- WebSocket（推荐）—— Hermes 主动建立出站连接，无需公网回调地址
- Webhook —— 飞书通过 HTTP 将事件推送到你的网关
Hermes 在不同场景下的行为
| 场景 | 行为 |
|---|---|
| 私聊 | 回复每条消息 |
| 群聊 | 仅在被 @ 时回复 |
| 共享群聊 | 默认按用户隔离会话历史 |
群聊会话隔离行为由 config.yaml 控制：
group_sessions_per_user: true
除非你明确希望群内所有人共享一个会话，否则不要改为 false。
安装配置步骤
在 WSL2 命令行中输入以下命令：
hermes gateway setup
然后选择 Feishu / Lark。
继续选择 第一个选项，用二维码创建。
系统会生成一个二维码。
用飞书移动端 APP 扫描该二维码。Hermes 会自动创建具有正确权限的机器人应用，并保存凭据。
创建完成后，可点击“打开应用”，进入飞书私信窗口。
接下来要选择私信如何授权。
Hermes Agent 推荐使用 DM 配对审批。
群聊信息的处理，选择 Respond only when @mentioned in groups 即可。
Home chat ID (optional, for cron/notifications): 直接回车跳过。
Install the gateway as a systemd service? (runs in background, starts on boot) [Y/n]: 选“y”。
选择网关在后台的运行方式。
Start the service now? [Y/n]: 选“y”。
完成后，通过飞书 APP 随便给刚才创建的 Hermes 应用发条信息，会收到一条类似 hermes pairing approve feishu XXXXXX 的命令。
在 WSL2 命令行中输入这条命令，即可完成配对。
在飞书 / Lark 聊天中发送 /set-home，将其标记为定时任务结果和跨平台通知的主频道。
以后需要通过飞书 APP 使用 Hermes Agent，只需在 WSL2 命令行中输入以下命令。
hermes gateway
全部环境变量
| 变量 | 必填 | 默认值 | 说明 |
|---|---|---|---|
FEISHU_APP_ID | 是 | — | 飞书 / Lark App ID |
FEISHU_APP_SECRET | 是 | — | 飞书 / Lark App Secret |
FEISHU_DOMAIN | 否 | feishu | feishu（国内）或 lark（国际） |
FEISHU_CONNECTION_MODE | 否 | websocket | websocket 或 webhook |
FEISHU_ALLOWED_USERS | 否 | （空） | 逗号分隔的 open_id 白名单 |
FEISHU_HOME_CHANNEL | 否 | — | 定时任务 / 通知输出的聊天 ID |
FEISHU_ENCRYPT_KEY | 否 | （空） | Webhook 签名验证加密密钥 |
FEISHU_VERIFICATION_TOKEN | 否 | （空） | Webhook 负载认证令牌 |
FEISHU_GROUP_POLICY | 否 | allowlist | 群消息策略：open, allowlist, disabled |
FEISHU_BOT_OPEN_ID | 否 | （空） | 机器人 open_id（用于 @ 检测） |
FEISHU_BOT_USER_ID | 否 | （空） | 机器人 user_id（用于 @ 检测） |
FEISHU_BOT_NAME | 否 | （空） | 机器人显示名称（用于 @ 检测） |
FEISHU_WEBHOOK_HOST | 否 | 127.0.0.1 | Webhook 服务器绑定地址 |
FEISHU_WEBHOOK_PORT | 否 | 8765 | Webhook 服务器端口 |
FEISHU_WEBHOOK_PATH | 否 | /feishu/webhook | Webhook 端点路径 |
HERMES_FEISHU_DEDUP_CACHE_SIZE | 否 | 2048 | 最大去重消息 ID 数 |
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 | 媒体突发合并静默期 |
WebSocket 和群组级 ACL 通过 config.yaml 中的 platforms.feishu.extra 配置。
常见问题排查
| 问题 | 解决方案 |
|---|---|
lark-oapi 未安装 | 安装 SDK：pip install lark-oapi |
websockets 未安装，WebSocket 模式不可用 | 安装：pip install websockets |
aiohttp 未安装，Webhook 模式不可用 | 安装：pip install aiohttp |
FEISHU_APP_ID 或 FEISHU_APP_SECRET 未设置 | 设置环境变量或通过 hermes gateway setup 配置 |
| 同一个 Feishu app_id 已被其他 Hermes 网关使用 | 同一 app_id 同时只能被一个 Hermes 实例使用，先停止其他网关 |
| 机器人在群中不响应 | 确认机器人已被 @，检查 FEISHU_GROUP_POLICY，若策略为 allowlist 则确认发送者在 FEISHU_ALLOWED_USERS 中 |
| Webhook 被拒绝：无效验证令牌 | 确认 FEISHU_VERIFICATION_TOKEN 与飞书应用事件订阅配置中的 token 一致 |
| Webhook 被拒绝：无效签名 | 确认 FEISHU_ENCRYPT_KEY 与飞书应用配置中的加密密钥一致 |
| Post 消息显示为纯文本 | 飞书 API 拒绝了 Post 负载，这是正常的回退行为，查看日志了解详情 |
| 图片 / 文件未收到 | 为飞书应用授予 im:message 和 im:resource 权限范围 |
| 机器人身份未自动检测 | 授予 admin:app.info:readonly 权限，或手动设置 FEISHU_BOT_OPEN_ID / FEISHU_BOT_NAME |
| 点击审批按钮时错误 200340 | 在飞书开发者控制台启用交互式卡片能力并配置卡片请求 URL |
| Webhook 限流 | 同一 IP 每分钟超过 120 个请求，通常是配置错误或循环 |