概述

本文档记录如何将飞书（Feishu）机器人接入 Hermes Agent，使其能通过飞书平台与用户对话。整个过程通过 Hermes CLI 的交互式向导完成，无需手动编辑配置文件。

前置条件

已安装并运行 Hermes Agent（版本 ≥ 2.0）
拥有飞书开放平台账号（open.feishu.cn）
已创建飞书自建应用并获取 App ID 和 App Secret
能访问 Hermes 所在服务器的终端

配置步骤

步骤一：创建飞书应用

在飞书开放平台（https://open.feishu.cn）创建企业自建应用：

在「凭证与基础信息」页面获取 App ID 和 App Secret
在「权限管理」中添加机器人所需权限（至少：获取用户信息、机器人）
在「事件订阅」中配置回调（WebSocket 方式无需填写回调 URL）
在「机器人」页面启用机器人能力
发布版本并审核通过

步骤二：通过 Hermes CLI 配置飞书

在终端中运行以下命令启动飞书配置向导：

在菜单中选择飞书/Feishu（选项 10）。有两种配置方式：

扫码自动创建机器人（推荐）- 生成二维码，扫码后自动创建并配置完毕
手动输入 - 填入已有的 App ID 和 App Secret 本次配置采用的是手动输入方式。

域名选择

根据你的飞书站点选择域名：

feishu（中国站）- 适用于中国用户
lark（国际站）- 适用于海外用户

连接方式

WebSocket（推荐）- 无需公网 URL，Hermes 主动连接飞书服务器
Webhook - 需要一个可访问的 HTTP 端点

授权设置

私信授权方式：

使用私信配对授权（推荐）- 新用户需通过 hermes pairing approve 批准
允许所有私信
仅允许指定用户 ID 群聊设置：
仅在 @提及时回复（推荐）
禁用群聊

步骤三：重启 Gateway

配置完成后，向导会询问是否重启 Gateway。选择 Y 后配置即刻生效。

也可以在后续通过以下命令手动重启：

验证配置

配置完成后，可以在飞书中找到你的机器人进行测试：

在飞书搜索中找到机器人名称（本配置中的机器人为：猫头鹰🦞一号机）
发送消息测试连接
如果设置了配对授权，需先通过命令批准：

查看当前配置

配置信息存储在环境变量中，可通过以下方式查看：

FEISHU_APP_ID - 应用 ID
FEISHU_APP_SECRET - 应用密钥
FEISHU_DOMAIN - 域名（feishu/lark）
FEISHU_CONNECTION_MODE - 连接模式（websocket/webhook）
FEISHU_GROUP_POLICY - 群聊策略

常见问题

机器人不回复

检查 Gateway 是否运行：hermes gateway status
检查日志：cat ~/.hermes/logs/gateway.log | tail -20
确认已在飞书开放平台发布应用

飞书文档权限

如需机器人具备飞书文档的读写能力（docx:document 权限），需要在飞书开放平台后台添加对应权限并重新发布，同时启用 feishu_doc 工具集。

文档信息

本文档由 Hermes Agent 自动生成于 2026 年 5 月 23 日。

通过飞书开放平台 API 自动创建，内容记录了完整的飞书配置流程。

Hermes Agent 飞书配置指南

概述