[特殊字符] Hermes Agent 对接飞书机器人 — 保姆级实战教程

🤖 Hermes Agent 对接飞书机器人 --- 保姆级实战教程

阅读时间： 约 8 分钟 ｜ 实操时间： 约 15 分钟

本文记录了从零开始将 Hermes Agent 接入飞书机器人的完整过程，包含飞书开放平台配置、Hermes 网关设置、以及踩坑解决方案。

---

📖 你会得到什么？

完成本教程后，你可以在飞书中拥有一个 AI 机器人：

• ✅ 私聊直接对话
• ✅ 群聊 @机器人 提问
• ✅ 支持代码、图片、文件等富内容交互
• ✅ 本地运行，无需公网 IP

---

🧩 流程总览

┌─────────────────────────────────────────────────────────┐
│  飞书开放平台（~10 分钟）                                  │
│  创建应用 → 添加机器人 → 配权限 → 订阅事件 → 发布         │
└───────────────────────────┬─────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────┐
│  本地终端（~2 分钟）                                      │
│  hermes gateway setup → 选飞书 → 填凭证 → 选 WebSocket   │
└───────────────────────────┬─────────────────────────────┘
                            ▼
                      ✅ 飞书聊天即可

---

📋 前置条件

条件	说明	检查方式
Hermes Agent 已安装	安装教程https://pan.quark.cn/s/201be654a70b	终端运行 hermes --version
大模型已配置	至少配好一个 LLM	终端运行 hermes model
飞书账号	个人版或企业版均可	能登录 open.feishu.cn

跨平台说明： macOS 和 Linux 步骤完全一致。Windows 用户需通过 WSL 操作，仅 .env 文件路径不同。

---

Part 1：飞书开放平台配置

Step 1：创建企业自建应用

1. 打开 飞书开放平台：https://open.feishu.cn/app?lang=zh-CN
2. 点击 创建企业自建应用

3. 填写应用名称（如 Hermes），选择图标，点击 确认创建

---

Step 2：添加机器人能力

在应用详情页 → 添加应用能力 → 选择 机器人

---

Step 3：配置权限

进入 权限管理 → 批量导入/导出权限，粘贴以下配置：

{
  "scopes": {
    "tenant": [
      "cardkit:card:read",
      "cardkit:card:write",
      "docx:document:readonly",
      "im:chat.members:read",
      "im:chat:read",
      "im:message.group_at_msg.include_bot:readonly",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": []
  }
}

关键权限说明：

权限	用途
im:message:send_as_bot	机器人主动发消息
im:message.p2p_msg:readonly	读取私聊消息
im:message.group_at_msg:readonly	读取群聊 @机器人 的消息
im:message.group_msg	在群聊中发送消息
im:resource	访问图片、文件等资源

---

Step 4：配置事件订阅

这是整个配置中最容易遗漏的一步。

1. 进入 事件与回调 → 事件配置

2. 点击 添加事件 ，搜索 receive，添加 接收消息 v2.0

💡 为什么要配置事件？

飞书采用「事件推送」机制。当用户给机器人发消息时，飞书需要知道把这条消息推送给谁。

添加 im.message.receive_v1 事件后，飞书才会把用户消息推送给你的应用，Hermes 才能"听到"用户说话。

3. 配置 回调配置 ：添加回调 → 卡片回传交互 → 添加（共三个回调，可全选）

---

Step 5：发布机器人

1. 点击 创建版本 → 保存

⚠️ 企业用户注意： 勾选"外部"需要管理员审批，不勾选则直接发布。

2. 发布成功后，飞书客户端会显示机器人，点击即可开始对话

🎉 飞书侧配置完成！ 接下来回到终端，配置 Hermes。

---

Part 2：Hermes 网关配置

Step 1：启动配置向导

hermes gateway setup

Step 2：选择飞书平台

输入 10（飞书 / Feishu），回车确认。

Windows 用户直接输入数字 10 回车；Linux / macOS 用户用方向键选择后回车。

Step 3：输入应用凭证

1. 选择 2（手动输入已有的 App ID 和 App Secret）
2. 回到 飞书开放平台 → 你的应用 → 凭证与基础信息
3. 复制 App ID 和 App Secret，粘贴到终端

选择平台类型 1（飞书）：

Step 4：选择连接模式

选择 1 --- WebSocket（推荐）

为什么推荐 WebSocket？

模式	公网 IP	防火墙配置	适用场景
WebSocket ✅	不需要	不需要	本地开发、内网部署
Webhook	需要	需要	云服务器、生产环境

WebSocket 模式下，飞书主动将消息推送到你的本地服务，无需暴露端口。

Step 5：完成并重启

后续选项直接 回车 使用默认值，等待网关重启完成。

Step 6：验证连接

看到类似以下输出，说明连接成功：

[feishu] Gateway connected via WebSocket
[feishu] Listening for messages...

打开飞书，给机器人发条消息测试：

---

🛠️ 常见问题排查

Q1：重启网关报错 "User not authorized"

现象：

原因： Hermes 默认只允许已授权用户对话，飞书用户尚未被识别。

解决方案：

在 .env 文件末尾追加两行配置：

GATEWAY_ALLOW_ALL_USERS=true
API_SERVER_KEY=a12345678

不同系统的操作方式：
Windows

打开 %LOCALAPPDATA%\hermes\.env，用记事本追加上面两行。
Linux / macOS

echo -e "GATEWAY_ALLOW_ALL_USERS=true\nAPI_SERVER_KEY=a12345678" >> ~/.hermes/.env

修改后重启网关：

hermes gateway restart

---

Q2：机器人不回复消息

按顺序排查：

# 1. 检查网关是否在运行
hermes gateway status

# 2. 查看日志找线索
tail -50 ~/.hermes/logs/gateway.log

# 3. 确认模型配置正确
hermes model

如果以上都没问题，回到飞书开放平台检查：

• 是否添加了 im.message.receive_v1 事件订阅
• 权限是否全部审批通过
• 机器人是否已发布（未发布的应用不会接收事件）

---

Q3：日志中出现权限相关错误

解决： 飞书开放平台 → 权限管理 → 确认所有权限已启用且通过审批。部分权限可能需要管理员审批。

---

Q4：WebSocket 连接频繁断开

Hermes 会自动重连。如果长时间无法恢复：

hermes gateway restart

💡 建议将 Hermes 安装为后台服务，这样开机自动启动，断连自动恢复：

hermes gateway install

---

📎 附录

常用运维命令

命令	用途
hermes gateway status	查看网关运行状态
hermes gateway restart	重启网关
hermes gateway stop	停止网关
hermes gateway run	前台运行（调试用，可看实时日志）
hermes gateway install	安装为后台服务（开机自启）

.env 关键变量

变量	作用	默认值
GATEWAY_ALLOW_ALL_USERS	是否允许所有用户与机器人对话	false
API_SERVER_KEY	API 服务器密钥	未设置

调试技巧

用前台模式运行网关，可以实时看到请求和响应日志：

# 终端 1：前台运行网关
hermes gateway run

# 终端 2：给机器人发消息，观察终端 1 的输出

---

✅ 总结

整个接入流程只有两大步：

阶段	核心操作
飞书侧	创建应用 → 添加机器人 → 导入权限 → 订阅 receive 事件 → 发布
Hermes 侧	hermes gateway setup → 选飞书 → 填 App ID/Secret → 选 WebSocket → 完成

遇到问题？ 先看日志：~/.hermes/logs/gateway.log，90% 的问题都能在日志中找到原因。

---

📬 有问题欢迎反馈，祝你玩得开心！🎉