Hermes Agent

Hermes Agent 消息平台集成

Hermes Agent 接入飞书 / Lark：长连接与权限配置指南

通过官方 WebSocket 长连接将 Hermes 接入飞书或 Lark，支持单聊、群聊、图片、音频、文件和定时任务投递。

平台

飞书 / Lark

连接方式

WebSocket（推荐）或 Webhook

同步版本

v2026.9.14 · 2026-09-17

选择连接方式

WebSocket 是默认推荐方案：Hermes 主动建立出站长连接，不需要公网地址。Webhook 适合已经拥有稳定 HTTPS 入口的生产环境。

  • 个人电脑、内网服务器：选 websocket。
  • 已有反向代理和公网 HTTPS：可选 webhook。
  • Webhook 默认路径为 /feishu/webhook，生产环境必须配置签名验证。

创建飞书 / Lark 应用

最快方式是在 Gateway 向导中选择 Feishu / Lark 并扫码创建。手工方式需在开放平台创建应用、启用机器人、复制 App ID/Secret。

  1. 1. 飞书使用 https://open.feishu.cn/；Lark 使用 https://open.larksuite.com/。
  2. 2. 启用 Bot 能力。
  3. 3. 添加消息、机器人发消息、资源和群聊读取权限。
  4. 4. 订阅 im.message.receive_v1。
  5. 5. 发布应用版本；企业应用可能需要管理员审批。
hermes gateway setup

最低权限与事件

核心权限包括 `im:message`、`im:message:send_as_bot`、`im:resource`、`im:chat` 和 `im:chat:readonly`。建议再加入 reaction、应用信息和用户 ID 只读权限，以支持 @判断和 allowlist。

只在开发后台保存权限还不够，必须发布新版本并完成审批，权限才会生效。

配置 Hermes

中国版飞书使用 `FEISHU_DOMAIN=feishu`，国际版 Lark 使用 `lark`。生产环境建议设置 Open ID allowlist。

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx

启动与验收

群聊默认需要 @机器人，且共享群按用户隔离会话。可在目标聊天中用 `/set-home` 设置定时任务与跨平台通知的投递位置。

  1. 1. 给机器人发单聊消息。
  2. 2. 在群聊中 @机器人并发送文本。
  3. 3. 上传图片或文件验证资源权限。
  4. 4. 发送 /set-home 后测试通知投递。
hermes gateway start
hermes gateway status

Webhook 模式安全要求

Webhook 模式需要公网可达 HTTPS、Verification Token 和 Encrypt Key。Hermes 会校验签名；无效或缺失签名应返回 401。

FEISHU_CONNECTION_MODE=webhook
FEISHU_WEBHOOK_HOST=127.0.0.1
FEISHU_WEBHOOK_PORT=8765
FEISHU_WEBHOOK_PATH=/feishu/webhook
FEISHU_ENCRYPT_KEY=your-encrypt-key

没有公网入口时不要为了 Webhook 暴露本机端口，直接使用 WebSocket。