Hermes Agent 部署配置使用完全实战指南

前言

Hermes 是 Nous Research 开源的 AI Agent 项目,分两个部分:

这篇文档记录的是在 macOS 上从零部署到跑通飞书机器人的完整过程。不讲原理,只讲操作。拿着这篇文档,你可以在一台干净的 Mac 上 30 分钟内完成全部部署。

环境信息:

项目 版本
macOS Sonoma (Darwin 24.6.0, x86_64)
hermes-agent v0.14.0
hermes-desktop v0.4.5
Homebrew 5.x

1. 前置依赖

hermes-agent 的安装脚本会自动检测并安装大部分依赖,但有一个硬性前提:Homebrew 必须提前装好。

1.1 安装 Homebrew(如果没有)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后确认:

brew --version
# Homebrew 5.x.x

1.2 安装脚本会自动处理的依赖

以下依赖不需要手动安装,hermes 安装脚本会自动搞定:

依赖 用途 安装方式
uv Python 包管理器 自动安装到 ~/.local/bin
Python 3.11 Agent 运行时 通过 uv 安装
Node.js 22 LTS 浏览器工具 安装到 ~/.hermes/node/
ripgrep 文件搜索 通过 Homebrew 安装
Playwright Chromium 浏览器引擎 自动下载

1.3 hermes-desktop 额外需要的依赖

构建 desktop 版本时会用到 gettext 库(DMG 打包依赖),需要提前安装:

brew install gettext

不装这个,构建到最后一步打 DMG 包时会报 Library not loaded: /usr/local/opt/gettext/lib/libintl.8.dylib 错误。


2. 安装 hermes-agent

2.1 一键安装

一条命令搞定:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装过程大约 5-10 分钟(取决于网络),你会看到逐项检测和安装的输出。全部绿色 ✓ 就是成功。

2.2 安装完成后的目录结构

~/.hermes/
├── hermes-agent/      # Agent 源码和 venv
├── node/              # Node.js 运行时
├── config.yaml        # 主配置文件(模型、终端、网关等)
├── .env               # 环境变量(API Key、消息平台凭证等)
├── SOUL.md            # Agent 人格设定(可自定义)
├── skills/            # 内置技能(90+ 个)
├── sessions/          # 会话存储
├── logs/              # 日志
└── cron/              # 定时任务

2.3 激活命令

安装脚本会自动把 ~/.local/bin 加入 PATH,但当前 shell 需要手动刷新:

source ~/.zshrc

验证安装:

hermes --help

3. 安装 hermes-desktop

3.1 克隆并安装依赖

cd /tmp
git clone https://github.com/fathah/hermes-desktop.git
cd hermes-desktop

确保 Node.js 在 PATH 中(hermes-agent 安装的 Node.js):

export PATH="$HOME/.hermes/node/bin:$PATH"
npm install

npm install 大约需要 10 分钟,会下载 900+ 个包并编译 better-sqlite3 原生模块。有几个 deprecated 警告可以忽略。

3.2 构建 macOS 版本

npm run build:mac

构建产物在 dist/ 目录下:

dist/
├── mac/
│   └── Hermes Agent.app    # macOS 应用
├── hermes-desktop-0.4.5-x64-mac.zip
└── hermes-desktop-0.4.5-x64.dmg

3.3 安装到 Applications

cp -R 'dist/mac/Hermes Agent.app' /Applications/

注意: 由于没有 Apple 开发者证书签名,首次打开时 macOS 会弹出安全警告。解决方法:系统设置 → 隐私与安全性 → 安全性,找到被阻止的应用,点击"仍要打开"。


4. 配置自定义模型网关

hermes 默认走 OpenRouter,但支持接入任何 OpenAI 兼容的 API 网关。这里以自建网关为例。

4.1 修改 config.yaml

编辑 ~/.hermes/config.yaml,找到 model: 部分,修改三个关键字段:

model:
  default: "gpt-5.5"           # 你要用的模型名
  provider: "custom"            # 使用自定义端点
  base_url: "https://your-gateway.example.com/v1"   # 你的网关地址
  api_key: "sk-your-api-key-here"                    # 你的 API Key

同时在 ~/.hermes/.env 中也设置 OPENAI_API_KEY(部分组件会读这个环境变量):

OPENAI_API_KEY=sk-your-api-key-here

4.2 验证模型连通性

hermes

启动 CLI 后输入一句话测试,能正常回复就说明网关配置没问题。


5. 配置飞书机器人

hermes 原生支持飞书(Feishu/Lark),通过 WebSocket 长连接模式工作,不需要公网回调地址。

5.1 创建飞书应用

  1. 打开 飞书开放平台
  2. 创建一个自建应用
  3. 记录 App ID 和 App Secret

5.2 配置应用权限

在飞书开放平台的应用管理页面,添加以下权限:

权限 说明
im:message 接收消息
im:message:send_as_bot 以机器人身份发送消息
im:chat:readonly 读取群聊信息

添加完权限后,创建版本并发布(审核通过后才生效)。

5.3 开启长连接模式

在飞书开放平台的应用管理页面:事件与回调 → 选择 WebSocket 模式。

这一步很关键,不开启的话 hermes 的 websocket 连接模式用不了。

5.4 写入环境变量

编辑 ~/.hermes/.env,追加以下内容:

# =============================================================================
# FEISHU / LARK INTEGRATION
# =============================================================================
FEISHU_APP_ID=cli_xxxxxxxxxxxx          # 替换为你的 App ID
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxx    # 替换为你的 App Secret
FEISHU_DOMAIN=feishu                     # 国内用 feishu,国际版用 lark
FEISHU_CONNECTION_MODE=websocket         # WebSocket 模式,无需公网 IP

# 允许所有用户访问(测试阶段)
GATEWAY_ALLOW_ALL_USERS=true

安全提示: 生产环境不建议 GATEWAY_ALLOW_ALL_USERS=true,应该用 FEISHU_ALLOWED_USERS=user_id_1,user_id_2 做白名单控制。


6. 启动网关服务

6.1 安装为系统服务(推荐)

hermes gateway install

这会创建一个 macOS launchd 服务(ai.hermes.gateway),开机自启,后台常驻。

服务文件位置:~/Library/LaunchAgents/ai.hermes.gateway.plist

6.2 常用管理命令

# 查看状态
hermes gateway status

# 重启服务
hermes gateway restart

# 查看日志(实时)
tail -f ~/.hermes/logs/gateway.log

# 查看错误日志
tail -f ~/.hermes/logs/gateway.error.log

# 卸载服务
hermes gateway uninstall

6.3 验证飞书连接

启动后检查日志,看到以下内容就说明飞书连接成功:

INFO gateway.platforms.feishu: [Feishu] Connected in websocket mode (feishu)
INFO gateway.run: ✓ feishu connected
[Lark] connected to wss://msg-frontier.feishu.cn/ws/v2?...

7. 首次使用:配对与频道设置

7.1 用户配对

第一次在飞书给机器人发消息时,会收到配对验证提示:

Hi~ I don't recognize you yet!
Here's your pairing code: XXXXXXXX
Ask the bot owner to run:
hermes pairing approve feishu XXXXXXXX

在 Mac 上执行批准命令:

hermes pairing approve feishu XXXXXXXX

批准后再发消息就能正常对话了。

7.2 设置主频道

配对成功后会收到设置主频道的提示。在飞书对话中回复:

/sethome

主频道用于接收定时任务结果和跨平台通知。


8. 其他常用操作

8.1 CLI 模式直接对话

不需要飞书,直接在终端对话:

hermes

8.2 修改 Agent 人格

编辑 ~/.hermes/SOUL.md,自定义 Agent 的人格、语气和行为偏好。

8.3 配置向导

首次使用建议跑一遍配置向导:

hermes setup

8.4 更新版本

hermes update

8.5 查看/编辑配置

hermes config              # 查看当前配置
hermes config edit         # 用编辑器打开配置文件

9. 踩坑记录

9.1 hermes-desktop 构建报 libintl.8.dylib 找不到

现象:

dyld: Library not loaded: /usr/local/opt/gettext/lib/libintl.8.dylib

原因: electron-builder 的 DMG 打包工具依赖 gettext 库。

解决:

brew install gettext

然后重新 npm run build:mac。

9.2 飞书权限不足导致获取群聊信息失败

现象: 日志中出现:

Access denied. One of the following scopes is required: [im:chat:readonly, im:chat, im:chat:read]

解决: 去飞书开放平台给应用添加 im:chat:readonly 权限,发布新版本。

9.3 所有用户被拒绝

现象: 日志中出现:

No user allowlists configured. All unauthorized users will be denied.

解决: 在 ~/.hermes/.env 中添加:

GATEWAY_ALLOW_ALL_USERS=true

或者配置白名单:

FEISHU_ALLOWED_USERS=ou_xxxxxxxxxxxx

修改后执行 hermes gateway restart 重启生效。

9.4 Git clone hermes-agent 仓库很慢

现象: 安装脚本卡在 Cloning into '/Users/xxx/.hermes/hermes-agent'... 很久。

解决: hermes-agent 仓库较大,国内网络环境可能较慢。可以考虑:


10. 文件速查表

文件 用途
~/.hermes/config.yaml 主配置:模型、终端、网关
~/.hermes/.env 环境变量:API Key、平台凭证
~/.hermes/SOUL.md Agent 人格设定
~/.hermes/skills/ 技能目录(90+ 内置技能)
~/.hermes/logs/gateway.log 网关日志
~/.hermes/logs/gateway.error.log 网关错误日志
~/.hermes/sessions/ 会话持久化存储
~/Library/LaunchAgents/ai.hermes.gateway.plist 网关 launchd 服务定义