大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



 # Hermes Agent 接入飞书机器人完整教程（保姆级 + 可直接发布） 

前言

在 AI Agent 快速发展的今天，如何让 AI 助手真正融入日常工作流，成为每个技术团队关注的核心问题。飞书（Feishu / Lark）作为国内领先的企业协作平台，已经成为众多团队日常沟通和协作的核心工具。本文将手把手教你如何将 Hermes Agent 接入飞书机器人，实现通过飞书直接与 AI Agent 对话、执行任务、查询数据。

本教程全程实战，所有步骤均经过验证，适合有一定 Linux 和 Python 基础的开发者。跟随本文操作，你将在 30 分钟内拥有一个属于自己的飞书 AI 机器人。

---

Hermes Agent 简介

Hermes Agent 是一个开源、高度可扩展的 AI 代理框架，支持通过多种平台与用户交互。其核心特性包括：

• 多平台接入：一套 Agent，多渠道触达（终端、飞书、Telegram、Discord 等）
• 工具系统：内置丰富的工具（文件操作、代码执行、浏览器控制、搜索等）
• 技能系统：可自定义和复用的技能库，支持持久化记忆
• 自主规划：能够分解复杂任务并逐步执行
• 自定义技能开发：通过 YAML + Markdown 定义专属工作流

Hermes 的架构设计使得接入飞书变得非常简洁——只需要配置飞书应用的 Webhook 和 API 凭证即可。Agent 会自动处理消息接收、事件回调、权限验证等复杂逻辑。

---

准备工作

1. 环境要求

在开始之前，请确保你的环境满足以下条件：

环境项	要求	验证命令
操作系统	Linux / macOS / WSL（Windows）	`uname -a`
Python	3.10 或更高版本	`python3 –version`
pip	最新版本	`pip3 –version`
Hermes Agent	已安装	`hermes –version`
网络	公网 IP 或内网穿透	能接收飞书回调

💡 提示：如果你在 Windows 上使用 WSL，推荐 Ubuntu 22.04 LTS 或更新版本。Hermes Agent 在 WSL2 下运行良好，但需要确保 WSL 的网络模式为 Mirrored 或配置好端口转发。

2. 安装 Hermes Agent

如果尚未安装 Hermes Agent，执行以下命令：

bash

使用 pip 安装

pip3 install hermes-agent

验证安装

hermes –version

初始化配置

hermes init

易错点：如果 `hermes` 命令找不到，请检查 Python 的 bin 目录是否在 PATH 中：

bash

找到 hermes 可执行文件位置

python3 -m site –user-base

输出示例：/home/user/.local

将 bin 目录加入 PATH

export PATH=$PATH:/home/user/.local/bin

3. 注册飞书开发者账号

访问 飞书开放平台，使用你的飞书账号登录。

> ⚠️ 注意：企业飞书用户需要使用管理员账号或有应用创建权限的账号。个人开发者可以使用飞书个人版注册开放平台。

4. 创建飞书应用

在开放平台中，点击「创建应用」：

1. 选择 「企业自建应用」
2. 填写应用名称（如 `Hermes 助手`）
3. 填写应用描述（如 `AI Agent 助手，支持对话、代码执行、文件处理等`）
4. 上传应用图标（可选，建议使用 Hermes 相关的 logo）

创建完成后，你将进入应用管理页面。在 「凭证与基础信息」 页面中，可以找到两个核心凭证：

• App ID：应用的唯一标识（格式如 `cli_xxxxxxxxxxxxxxx`）
• App Secret：应用的密钥（请妥善保管，不要泄露）

> 💡 提示：建议将 App ID 和 App Secret 保存在安全的地方，后续配置 Hermes Agent 时需要用到。

---

配置飞书应用权限

1. 开启机器人能力

在应用管理页面中，进入 「应用功能」→「机器人」，开启机器人能力开关。

开启后，你的应用就拥有了发送和接收消息的能力。这是接入飞书机器人最关键的一步。

2. 配置权限（Scopes）

进入 「权限管理」，添加以下权限：

权限名称	权限代码	用途
获取用户信息	`contact:user.base`	获取用户基本信息
获取群信息	`im:chat`	获取群聊信息
获取与发送单聊、群组消息	`im:message`	收发消息的核心权限
获取与上传图片	`im:resource`	支持图片消息
以应用身份发送消息	`im:message:send_as_bot`	机器人主动发送消息
读取应用发送的消息	`im:message:readonly`	读取消息历史

易错点：很多初学者只添加了 `im:message` 权限，而忽略了 `im:message:send_as_bot`，导致机器人无法主动发送消息。请务必检查权限列表是否完整。

3. 配置事件订阅

进入 「事件与回调」，添加以下事件：

1. 点击「添加事件」
2. 搜索并选择 `im.message.receive_v1`（接收消息事件）
3. 配置事件回调地址，格式为： https://你的域名:端口/webhook/feishu > 例如：`https://example.com:8899/webhook/feishu`;

回调地址配置详解：

场景	配置方式	说明
本地测试	使用内网穿透（如 frp、ngrok）	`https://your-ngrok-url.ngrok.io/webhook/feishu`;
服务器部署	使用公网 IP + 反向代理	`https://your-domain.com/webhook/feishu`;
HTTPS 证书	必须使用有效证书	Let‘s Encrypt 免费证书即可

💡 提示：本地开发测试时，推荐使用 `frp` 或 `ngrok` 进行内网穿透。飞书要求回调地址必须是 HTTPS 协议。

验证令牌配置：

在事件订阅页面，你会看到「验证令牌」（Verification Token）字段。这个令牌在后续配置 Hermes Agent 时需要用到，请记录下来。

4. 配置应用加密（可选但推荐）

在「事件与回调」页面中，可以设置 Encrypt Key。开启加密后，飞书发送的消息会使用 AES 加密，增强安全性。

> 如果开启加密，需要在 Hermes Agent 配置中填写对应的 `encrypt_key`。

5. 发布应用

完成所有配置后，点击 「发布版本」→「创建版本」：

1. 填写版本号（如 `1.0.0`）
2. 填写更新说明（如 `首次发布，支持基础对话功能`）
3. 提交审核

> ⚠️ 注意：飞书企业自建应用需要管理员审核。审核通过后，应用才能正式生效。审核通常需要 1-2 个工作日。

---

配置 Hermes Agent 飞书集成

1. 编辑配置文件

Hermes Agent 的配置文件通常位于 `~/.hermes/config.yaml`。如果文件不存在，运行 `hermes init` 自动创建。

打开配置文件，添加飞书平台配置：

yaml

~/.hermes/config.yaml

platforms: feishu:

enabled: true app_id: "cli_xxxxxxxxxxxxxxx" # 替换为你的 App ID app_secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # 替换为你的 App Secret encrypt_key: "" # 如果未开启加密，留空 verification_token: "xxxxxxxx" # 替换为你的验证令牌 

server: host: “0.0.0.0” # 监听所有网络接口 port: 8899 # Webhook 服务端口 ssl_cert: “” # HTTPS 证书路径（可选） ssl_key: “” # HTTPS 密钥路径（可选）

配置项详解：

配置项	必填	说明
`enabled`	是	是否启用飞书平台，设为 `true`
`app_id`	是	飞书开放平台的应用 ID
`app_secret`	是	飞书开放平台的应用密钥
`encrypt_key`	否	AES 加密密钥（如未开启加密则留空）
`verification_token`	否	验证令牌（如未配置则留空）
`server.host`	是	Webhook 服务监听地址，`0.0.0.0` 表示所有网卡
`server.port`	是	Webhook 服务端口，建议 `8899`
`server.ssl_cert`	否	HTTPS 证书路径（生产环境推荐）
`server.ssl_key`	否	HTTPS 密钥路径（生产环境推荐）

2. 配置 HTTPS 支持（生产环境推荐）

生产环境中建议配置 HTTPS。有两种方式：

方式一：使用 Nginx 反向代理（推荐）

nginx

/etc/nginx/sites-available/hermes

server }

方式二：使用 Let’s Encrypt 直接配置

bash

安装 certbot

sudo apt install certbot python3-certbot-nginx

获取证书

sudo certbot –nginx -d your-domain.com

在 Hermes 配置中填写证书路径

ssl_cert: “/etc/letsencrypt/live/your-domain.com/fullchain.pem”

ssl_key: “/etc/letsencrypt/live/your-domain.com/privkey.pem”

> 💡 提示：Let‘s Encrypt 证书有效期为 90 天，建议配置自动续期： > bash > sudo crontab -e > # 添加以下行，每月 1 日自动续期 > 0 0 1 * * /usr/bin/certbot renew –quiet >

3. 启动 Hermes Agent

配置完成后，启动 Hermes Agent：

bash

方式一：启动完整 Hermes Agent 服务（推荐）

hermes start

方式二：仅启动 Webhook 服务

hermes serve –port 8899

方式三：使用 systemd 管理服务（生产环境推荐）

sudo systemctl start hermes sudo systemctl enable hermes # 设置开机自启

验证服务是否正常运行：

bash

检查进程状态

ps aux | grep hermes

查看日志

tail -f ~/.hermes/logs/hermes.log

测试 Webhook 端口是否监听

curl -v http://localhost:8899/health

常见启动问题：

问题	原因	解决方法
`Address already in use`	端口被占用	`lsof -i :8899` 查看占用进程，修改端口
`ModuleNotFoundError`	依赖缺失	`pip3 install hermes-agent[all]`
`Permission denied`	端口权限不足	使用 `sudo` 或改用 1024 以上端口

4. 验证连接

在飞书中向机器人发送一条消息（如 `你好`），如果配置正确，Hermes 会回复你的消息。

排错步骤：

如果机器人没有回复，按照以下顺序排查：

1. 检查飞书回调地址是否可达 bash

   在服务器上测试

   curl -X POST https://your-domain.com/webhook/feishu -H “Content-Type: application/json” -d ’{“challenge”: “test”}‘

2. 检查 Hermes 日志 bash tail -f ~/.hermes/logs/hermes.log | grep feishu
3. 检查飞书开放平台的「事件订阅」状态
   • 进入应用管理页面 → 事件与回调
   • 查看回调地址状态是否为「可用」
   • 如果显示「不可用」，检查网络和证书配置

---

高级配置

1. 群聊机器人

Hermes Agent 支持在飞书群聊中工作。将机器人添加到群聊后：

1. 在群聊设置中搜索并添加你的应用机器人
2. @机器人 提及触发响应（例如：`@Hermes 助手 帮我查一下今天的天气`）
3. 支持群聊中的关键词触发（可选配置）

群聊配置示例：

yaml

~/.hermes/config.yaml 中添加

feishu: group_chat:

enabled: true mention_only: true # 仅 @机器人 时响应 keywords: ["Hermes", "助手"] # 关键词触发（可选） 

2. 消息格式支持

Hermes Agent 支持丰富的消息格式：

消息类型	支持情况	使用示例
文本消息	✅ 完整支持	普通文字对话
富文本消息	✅ 支持 Markdown	带格式的回复
图片消息	✅ 支持发送和接收	`帮我生成一张架构图`
文件消息	✅ 支持文件传输	`帮我处理这个 Excel 文件`
卡片消息	✅ 交互式卡片	待办事项、确认对话框

Markdown 格式支持示例：

markdown 这是加粗文字 这是斜体文字

• 列表项 1
• 列表项 2 > 引用内容 `code` 行内代码

3. 多 Agent 配置

如果你的团队需要多个 AI Agent 处理不同任务，可以配置多实例：

yaml

启动多个 Hermes 实例，监听不同端口

hermes serve –port 8899 –config ~/.hermes/config1.yaml hermes serve –port 8900 –config ~/.hermes/config2.yaml

4. 权限控制与安全

推荐的安全配置：

yaml

~/.hermes/config.yaml

feishu: security:

allowed_users: ["user_id_1", "user_id_2"] # 允许使用的用户列表 admin_users: ["admin_user_id"] # 管理员用户 rate_limit: 10 # 每分钟最大请求数 max_message_length: 5000 # 单条消息最大字符数 

---

常见问题排查

Q1: 飞书机器人不回复消息

检查清单：

1. ✅ 确认 App ID 和 App Secret 是否正确（特别是 App Secret 不要有多余空格）
2. ✅ 确认事件回调地址是否可访问（使用 curl 测试）
3. ✅ 检查 Hermes 日志中是否有错误信息
4. ✅ 确认应用已发布且处于启用状态
5. ✅ 确认机器人已添加到目标会话（单聊或群聊）

Q2: 消息回调报 403 错误

原因：通常是飞书开放平台的事件订阅配置中，验证令牌（Verification Token）不匹配。

解决方法：

1. 进入飞书开放平台 → 应用管理 → 事件与回调
2. 复制「验证令牌」字段的值
3. 在 Hermes 配置文件中更新 `verification_token`
4. 重启 Hermes Agent

Q3: 无法接收图片或文件

原因：未添加 `im:resource` 权限。

解决方法：

1. 进入飞书开放平台 → 权限管理
2. 添加 `im:resource` 权限
3. 重新发布应用版本
4. 等待审核通过

Q4: HTTPS 证书问题

原因：自签名证书会导致飞书服务器无法验证。

解决方法：

1. 使用 Let’s Encrypt 或其他受信任的 CA 签发的证书
2. 不要在本地测试环境中使用 HTTPS，直接使用 HTTP + 内网穿透
3. 如果必须使用自签名证书，需要将 CA 证书添加到飞书信任列表（不推荐）

Q5: 飞书回调超时

原因：Hermes Agent 处理请求超过飞书允许的超时时间（通常为 5 秒）。

解决方法：

• 优化 Agent 的处理逻辑，减少耗时操作
• 使用异步处理模式（Hermes 默认支持）
• 对于耗时任务，先回复“正在处理”，异步执行后再发送结果

---

总结

通过以上步骤，我们成功将 Hermes Agent 接入飞书机器人，实现了：

• ✅ 在飞书中与 AI Agent 直接对话
• ✅ 支持 单聊和群聊 两种模式
• ✅ 丰富的消息格式（文本、图片、文件）
• ✅ 安全的 HTTPS 通信
• ✅ 完善的错误处理和日志记录
• ✅ 权限控制和安全防护

Hermes Agent + 飞书的组合让 AI 能力真正融入了日常协作流程。无论是代码审查、文档生成、数据查询还是任务自动化，你都可以在飞书中直接完成。

下一步探索方向：

1. 开发自定义技能：参考 Hermes Agent 自定义技能开发教程
2. 接入更多平台：Telegram、Discord、Slack 等
3. 集成更多工具：数据库查询、API 调用、CI/CD 触发
4. 部署到生产环境：使用 Docker 容器化部署 + K8s 集群管理

---

参考资源

• Hermes Agent 官方仓库
• 飞书开放平台文档
• Hermes Agent 自定义技能开发教程
• Let‘s Encrypt 免费 SSL 证书
• Nginx 反向代理配置指南

---

本文由 Hermes Agent 自动生成并发布