Hermes Agent 安装

编程技巧网站经验

📅 2026-05-22 20:35 🔄 2026-05-22 20:39 👤 admin

# Hermes Agent 安装记录

这份笔记记录本次在 WSL Ubuntu 中安装 Hermes Agent、连接飞书、配置 MiniMax 模型和 systemd 后台服务的过程。

## 环境

- Windows + WSL Ubuntu
- WSL 用户：`jeffery`
- Windows 代理端口：`7897`
- Hermes 命令路径：`/home/jeffery/.local/bin/hermes`
- 飞书机器人：`徐承杰的智能助手`
- 飞书用户白名单 ID：`ou_2224cd09866215c0267fcc195f2eb3fd`

## 1. WSL 配置代理

一开始直接访问 GitHub 失败：

```text
fatal: unable to access 'https://github.com/NousResearch/hermes-agent.git/':
Failed to connect to github.com port 443
```

`/etc/resolv.conf` 里的 DNS 地址是 `10.255.255.254`，不能直接作为 Windows 代理地址。正确做法是使用 WSL 默认网关。

```bash
export winhost=$(ip route | grep default | awk '{print $3}')
echo $winhost
curl -I -x http://$winhost:7897 https://github.com
```

确认能返回 `HTTP/2 200` 后，设置当前 shell 和 git 代理：

```bash
export http_proxy=http://$winhost:7897
export https_proxy=http://$winhost:7897
git config --global http.proxy http://$winhost:7897
git config --global https.proxy http://$winhost:7897
```

测试 GitHub clone 链路：

```bash
git ls-remote https://github.com/NousResearch/hermes-agent.git
```

可选：把代理写入 `~/.bashrc`，以后打开 WSL 自动生效：

```bash
export winhost=$(ip route | grep default | awk '{print $3}')
export http_proxy=http://$winhost:7897
export https_proxy=http://$winhost:7897
```

## 2. 安装 Hermes Agent

```bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc
hermes doctor
```

`hermes doctor` 里看到这些即可说明核心安装成功：

```text
Python Environment OK
Required Packages OK
Configuration Files OK
Command Installation OK
```

一些可选 warning 可以先忽略，例如 Telegram、Discord、OpenRouter、Google Gemini OAuth 等。

## 3. 配置 MiniMax 模型

进入模型配置：

```bash
hermes model
```

本次关键点：MiniMax 不只要填 API Key，还要填 Base URL。

如果 Base URL 没填，飞书消息会触发模型请求失败，错误类似：

```text
HTTP 401: login fail: Please carry the API secret key in the 'X-Api-Key' field of the request header
```

修复方式是重新运行：

```bash
hermes model
```

然后补齐 MiniMax 的 API Key 和 Base URL。

## 4. 配置飞书 Gateway

运行：

```bash
hermes gateway setup
```

选择：

```text
Feishu / Lark
Domain: feishu
Connection: websocket
```

然后填入飞书开放平台里的：

```text
App ID
App Secret
```

WebSocket 模式适合本机/WSL，不需要公网回调地址或内网穿透。

## 5. 安装 systemd 后台服务

配置完成后，Hermes 会提示：

```text
sudo hermes gateway install --system --run-as-user jeffery
sudo hermes gateway start --system
```

但在 WSL 中 `sudo hermes` 可能找不到命令：

```text
sudo: hermes: command not found
```

先查看 Hermes 真实路径：

```bash
which hermes
```

本次路径是：

```text
/home/jeffery/.local/bin/hermes
```

所以使用完整路径安装并启动服务：

```bash
sudo /home/jeffery/.local/bin/hermes gateway install --system --run-as-user jeffery
sudo /home/jeffery/.local/bin/hermes gateway start --system
```

查看状态：

```bash
/home/jeffery/.local/bin/hermes gateway status
systemctl status hermes-gateway --no-pager
```

正常状态类似：

```text
Active: active (running)
[Lark] connected to wss://msg-frontier.feishu.cn/...
```

## 6. 配置飞书用户白名单

初次收到飞书消息时，可能会看到：

```text
No user allowlists configured. All unauthorized users will be denied.
Unauthorized user: ou_xxx on feishu
```

查看完整飞书用户 ID：

```bash
sudo journalctl -u hermes-gateway -n 120 -o cat --no-pager -l | grep "Unauthorized user"
```

本次用户 ID 是：

```text
ou_2224cd09866215c0267fcc195f2eb3fd
```

写入允许列表：

```bash
echo 'FEISHU_ALLOWED_USERS=ou_2224cd09866215c0267fcc195f2eb3fd' >> ~/.hermes/.env
```

不要长期打开全员访问。如果之前为了测试加过：

```text
GATEWAY_ALLOW_ALL_USERS=true
```

编辑配置文件关闭它：

```bash
nano ~/.hermes/.env
```

改成：

```text
# GATEWAY_ALLOW_ALL_USERS=true
```

或：

```text
GATEWAY_ALLOW_ALL_USERS=false
```

确认配置：

```bash
grep -n "GATEWAY_ALLOW_ALL_USERS" ~/.hermes/.env
grep -n "FEISHU_ALLOWED_USERS" ~/.hermes/.env
```

建议保护 `.env` 权限：

```bash
chmod 600 ~/.hermes/.env
```

## 7. 重启和恢复 Gateway 服务

普通重启：

```bash
sudo systemctl restart hermes-gateway
```

查看状态：

```bash
systemctl status hermes-gateway --no-pager
```

查看实时日志：

```bash
sudo journalctl -u hermes-gateway -f -o cat
```

查看最近日志：

```bash
sudo journalctl -u hermes-gateway -n 100 -o cat --no-pager -l
```

如果服务卡在 `deactivating` 或被 `kill` 后进入失败状态：

```bash
sudo systemctl reset-failed hermes-gateway
sudo systemctl stop hermes-gateway
sudo systemctl start hermes-gateway
systemctl status hermes-gateway --no-pager
```

如果还是不行，可以刷新 systemd 服务定义：

```bash
sudo /home/jeffery/.local/bin/hermes gateway install --system --run-as-user jeffery
sudo systemctl daemon-reload
sudo systemctl reset-failed hermes-gateway
sudo systemctl start hermes-gateway
systemctl status hermes-gateway --no-pager
```

如果要确认 Hermes 本身配置是否正常，可以先前台运行：

```bash
hermes gateway
```

如果前台能连上飞书，但 systemd 不行，说明问题在服务状态或 systemd 环境。

## 8. 飞书测试

私聊机器人：

```text
你好
```

群聊里需要 `@机器人`：

```text
@徐承杰的智能助手你好
```

设置当前飞书聊天为 home channel：

```text
/sethome
```

home channel 用于 Hermes 发送 cron 定时任务结果和跨平台通知。

## 9. 安全建议

Hermes Gateway 接入飞书后，等于允许飞书消息触发本机 Agent 行为。建议：

- 保留 `FEISHU_ALLOWED_USERS` 白名单。
- 不要长期打开 `GATEWAY_ALLOW_ALL_USERS=true`。
- 不要把 `~/.hermes/.env` 发给别人。
- 给 `.env` 设置 `chmod 600`。
- 谨慎安装第三方 skill。
- 涉及终端、文件、MCP、账号授权的 skill 要先看说明和权限。

## 常用命令速查

### WSL 代理

```bash
export winhost=$(ip route | grep default | awk '{print $3}')
export http_proxy=http://$winhost:7897
export https_proxy=http://$winhost:7897
git config --global http.proxy http://$winhost:7897
git config --global https.proxy http://$winhost:7897
curl -I -x http://$winhost:7897 https://github.com
git ls-remote https://github.com/NousResearch/hermes-agent.git
```

### 安装和检查

```bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc
hermes doctor
which hermes
```

### 模型配置

```bash
hermes model
```

### 飞书 Gateway 配置

```bash
hermes gateway setup
hermes gateway
```

### systemd 服务

```bash
sudo /home/jeffery/.local/bin/hermes gateway install --system --run-as-user jeffery
sudo /home/jeffery/.local/bin/hermes gateway start --system
sudo systemctl restart hermes-gateway
sudo systemctl stop hermes-gateway
sudo systemctl start hermes-gateway
systemctl status hermes-gateway --no-pager
```

### 日志

```bash
sudo journalctl -u hermes-gateway -f -o cat
sudo journalctl -u hermes-gateway -n 100 -o cat --no-pager -l
sudo journalctl -u hermes-gateway -n 120 -o cat --no-pager -l | grep "Unauthorized user"
```

### 白名单和安全

```bash
echo 'FEISHU_ALLOWED_USERS=ou_2224cd09866215c0267fcc195f2eb3fd' >> ~/.hermes/.env
grep -n "GATEWAY_ALLOW_ALL_USERS" ~/.hermes/.env
grep -n "FEISHU_ALLOWED_USERS" ~/.hermes/.env
nano ~/.hermes/.env
chmod 600 ~/.hermes/.env
```

### 服务失败恢复

```bash
sudo systemctl reset-failed hermes-gateway
sudo systemctl stop hermes-gateway
sudo systemctl start hermes-gateway
systemctl status hermes-gateway --no-pager
```

## 最终链路

```text
WSL 代理打通 GitHub
-> 安装 Hermes Agent
-> 配置 MiniMax API Key + Base URL
-> 配置 Feishu WebSocket Gateway
-> 设置 FEISHU_ALLOWED_USERS 白名单
-> 启动 hermes-gateway systemd 服务
-> 飞书对话成功
```