# 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 服务
-> 飞书对话成功
```
