Hermes Agent 安装与飞书接入实战记录

962456

10人浏览 · 2026-06-29 17:25:12

962456 · 2026-06-29 17:25:12 发布

一份从零到用的保姆级教程，附带踩坑实录

一、什么是 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 -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

安装完成后会自动创建 ~/.hermes/ 目录，包含配置文件和 venv。

2.2 配置模型（以 DeepSeek 为例）

# 设置 API Key
echo 'DEEPSEEK_API_KEY=sk-your-key-here' >> ~/.hermes/.env

# 选择模型
hermes model

在交互界面中选择 deepseek 作为 Provider，选择模型（如 deepseek-v4-pro）。

也可以通过命令行：

hermes config set model.provider deepseek
hermes config set model.default deepseek-v4-pro

2.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 / Lark
FEISHU_APP_ID=cli_xxxxxxxxxxxx
FEISHU_APP_SECRET=your_app_secret
FEISHU_DOMAIN=feishu         # 飞书用 feishu，Lark 用 lark
FEISHU_CONNECTION_MODE=websocket  # 推荐 WebSocket，无需公网 URL

# 访问控制（开发阶段打开，生产环境改用白名单）
GATEWAY_ALLOW_ALL_USERS=true

依赖安装：

pip3 install lark-oapi websockets

五、启动 Gateway

# 前台启动（推荐先这样，看日志）
hermes gateway run

# 后台启动（WSL 推荐 tmux）
tmux new -s hermes '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 -t feishu -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                         # 健康检查

# Gateway
hermes gateway run                    # 启动
hermes gateway status                 # 状态
hermes gateway restart                # 重启

# Cron（定时任务）
hermes cron list                      # 查看任务
hermes cron run <id>                  # 手动触发

# 直接推送
hermes send -t feishu "消息内容"       # 推送到飞书
hermes send -t feishu -f file.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
     ↓
飞书发消息测试 → 收到回复 ✅

最容易被遗漏的三件事：