一份从零到用的保姆级教程，附带踩坑实录
一、什么是 Hermes Agent
Hermes Agent 是 Nous Research 开源的 AI Agent 框架，支持 CLI 和多种消息平台（飞书、Telegram、Discord 等）。可以对接到 DeepSeek、OpenAI、Anthropic 等任意 LLM 提供商。
核心特性：
- 跨平台 Gateway — 同一 Agent 通过飞书/Telegram/Discord 等 10+ 平台使用
- Provider 无关 — 换模型只需一行命令
- Skills 系统 — Agent 从经验中学习，持久化可复用流程
- 持久化 Memory — 跨会话记住用户偏好和环境细节
官方文档：https://hermes-agent.nousresearch.com/docs/
二、安装 Hermes Agent
2.1 一键安装
curl-fsSLhttps://hermes-agent.nousresearch.com/install.sh|bash安装完成后会自动创建~/.hermes/目录，包含配置文件和 venv。
2.2 配置模型（以 DeepSeek 为例）
# 设置 API Keyecho'DEEPSEEK_API_KEY=sk-your-key-here'>>~/.hermes/.env# 选择模型hermes model在交互界面中选择deepseek作为 Provider，选择模型（如deepseek-v4-pro）。
也可以通过命令行：
hermes configsetmodel.provider deepseek hermes configsetmodel.default deepseek-v4-pro2.3 验证安装
hermes doctor# 检查依赖和配置hermes chat-q"你好"# 测试对话三、接入飞书
3.1 创建飞书应用
- 打开 飞书开放平台
- 创建企业自建应用
- 在「凭证与基础信息」页面获取App ID和App Secret
3.2 开启机器人能力
「应用功能 → 机器人」→ 启用
3.3 配置权限
进入「权限管理」，开通以下权限：
| 权限 | 说明 | 必需 |
|---|---|---|
im:message | 获取与发送单聊、群组消息 | ✅ |
im:message.p2p_msg:readonly | 读取用户发给机器人的单聊消息 | ✅ |
im:message.group_at_msg:readonly | 获取群组中用户@机器人消息 | 群聊需要 |
im:message.group_msg | 获取群组中所有消息（敏感权限） | 可选 |
im:resource | 获取与上传图片或文件资源 | ✅ |
3.4 配置事件订阅
「开发配置 → 事件订阅」→ 添加事件：im.message.receive_v1
注意：WebSocket 模式不需要配置回调地址，但事件必须订阅！
3.5 发布应用
⚠️这是最容易漏掉的一步
添加权限和事件后，必须创建新版本并发布才能生效：
「版本管理与发布 → 创建版本 → 申请发布」
不发布的话，权限修改不会生效，机器人收不到消息。
四、配置 Gateway .env
编辑~/.hermes/.env：
# Feishu / LarkFEISHU_APP_ID=cli_xxxxxxxxxxxxFEISHU_APP_SECRET=your_app_secretFEISHU_DOMAIN=feishu# 飞书用 feishu，Lark 用 larkFEISHU_CONNECTION_MODE=websocket# 推荐 WebSocket，无需公网 URL# 访问控制（开发阶段打开，生产环境改用白名单）GATEWAY_ALLOW_ALL_USERS=true依赖安装：
pip3installlark-oapi websockets
五、启动 Gateway
# 前台启动（推荐先这样，看日志）hermes gateway run# 后台启动（WSL 推荐 tmux）tmux new-shermes'hermes gateway run'# 检查状态hermes gateway status成功启动后日志会显示：
✓ feishu connected Gateway running with 1 platform(s)六、遇到的问题与解决方案
问题 1：飞书机器人不回复消息
现象：Gateway 启动正常，飞书显示连接成功，但给机器人发消息完全没反应。
排查过程：
- 检查 Gateway 日志：
tail-f~/.hermes/logs/gateway.log - 发现警告：
No user allowlists configured. All unauthorized users will be denied.
原因：Gateway 默认拒绝所有用户。需要开放访问或配置白名单。
解决：在.env中添加GATEWAY_ALLOW_ALL_USERS=true并重启 Gateway。
问题 2：加了白名单还是没反应
现象：GATEWAY_ALLOW_ALL_USERS=true已配置，重启后仍然收不到消息。
排查：Gateway 日志没有新的错误。问题指向飞书 App 侧。
检查清单：
- ✅ 权限管理中
im:message已开通 - ✅ 事件订阅已添加
im.message.receive_v1 - ❌ 缺少
im:message.p2p_msg:readonly权限 — 读取单聊消息需要这个！
解决：添加im:message.p2p_msg:readonly权限。
问题 3：加了权限还没用
现象：补上p2p_msg:readonly权限后仍然不回复。
原因：飞书开放平台上修改权限和事件订阅后，必须重新创建版本并发布！这是最容易漏的一步。
解决：版本管理与发布 → 创建版本 → 发布。发布后立即生效。
问题 4：Cron Job 投递失败
现象：创建 cron job 设置了deliver=all，但飞书没收到消息。
日志：no delivery target resolved for deliver=all
原因：没有配置FEISHU_HOME_CHANNEL，deliver=all找不到投递目标。
解决：
- 先在飞书给机器人发一条消息，从日志中获取
chat_id - 在
.env中设置：FEISHU_HOME_CHANNEL=oc_xxxxxxxxxxxxxx - 重启 Gateway
之后也可以用命令行直接发消息：
hermes send-tfeishu-f/path/to/message.txt七、验证全链路
- 在飞书中找到你的机器人
- 发送 “你好”
- 应该收到 Hermes 的回复
如果 Gateway 日志中有：
info gateway.run: inbound message: platform=feishu ... info gateway.run: response ready: platform=feishu ...说明全链路通了。
八、常用命令速查
# 配置hermes model# 选模型hermes config edit# 编辑配置hermes doctor# 健康检查# Gatewayhermes gateway run# 启动hermes gateway status# 状态hermes gateway restart# 重启# Cron（定时任务）hermescronlist# 查看任务hermescronrun<id># 手动触发# 直接推送hermes send-tfeishu"消息内容"# 推送到飞书hermes send-tfeishu-ffile.txt# 从文件推送# 日志tail-f~/.hermes/logs/gateway.log# Gateway 日志tail-f~/.hermes/logs/agent.log# Agent 日志九、总结
接入飞书的关键步骤链路：
创建飞书应用 → 启用机器人 → 配置权限 → 订阅事件 → ⚠️发布版本 ↓ 配置 .env（APP_ID + SECRET + ALLOW_ALL_USERS） ↓ 安装依赖（lark-oapi + websockets） ↓ 启动 Gateway → 检查日志中 feishu connected ↓ 飞书发消息测试 → 收到回复 ✅最容易被遗漏的三件事：
im:message.p2p_msg:readonly权限— 单聊必须- 发布版本— 修改权限/事件后必须重新发布
GATEWAY_ALLOW_ALL_USERS=true— 开发阶段必须开放
