Hermes Agent 是我过去一年用得最久的 AI 代理——不是 OpenClaw 的继任者，是更"自进化"的一代。装了不下十次，踩过端口、venv、systemd、Termux 各种坑。这篇文章把整个流程拆开来讲，从官方一行 curl，到我后来手动拆的 systemd 常驻方案，全写下来。

本文不是官方文档的复制品。官方 README 已经足够好——我这篇是讲"装完以后还要做什么"以及"哪些坑是文档没写的"。

TL;DR：最省事的装法

如果你只是想用，一行命令搞定：

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

装完重启 shell：

terminal bash 
1source ~/.bashrc    # 或 source ~/.zshrc2hermes            # 开始对话

支持的系统：Linux、macOS、WSL2、Android (Termux)。Windows 原生不支持，要用请装 WSL2。

安装程序会自动处理：

  • uv（Python 包管理，比 pip 快 10-100 倍）
  • Python 3.11（Hermes 的最低要求）
  • Node.js（运行 Ink TUI 用的）
  • ripgrep、ffmpeg（部分 skill 需要）
  • MinGit（Windows 用，避免污染系统 Git）

到这里，官方文档就讲完了。但 大多数人装完不会用——因为它默认装在 ~/.hermes 下、没有 systemd 服务、跟现有服务可能抢端口。下面讲"装完还要做什么"。

第一步（装完 5 分钟内）：先看装到哪了

很多人在这一步就懵了——"我装了，但找不到文件"。

terminal bash 
1which hermes2ls -la ~/.hermes/ | head -203hermes home    # 官方命令，输出 HERMES_HOME 路径

官方约定路径是 ~/.hermes，所有配置、记忆、skills、日志都放这里。如果你用了 profile，路径会变成 ~/.hermes-profiles/<name>/。

关键目录：

  • ~/.hermes/config.yaml — 主配置（YAML）
  • ~/.hermes/.env — API keys（不要提交到 git）
  • ~/.hermes/MEMORY.md + USER.md — 记忆文件
  • ~/.hermes/skills/ — 自定义技能
  • ~/.hermes/logs/ — agent.log + gateway.log

第二步：选模型（最常被问的）

Hermes 不绑定任何模型供应商。一条命令切换：

terminal bash 
1hermes model23# 交互式选择 provider + model4# 或者直接指定：5hermes model openrouter:anthropic/claude-3.5-sonnet6hermes model minimax-cn:MiniMax-M3

支持 200+ 模型。我自己常用的：

  • 开发调试：OpenRouter 的 Claude 3.5 Sonnet（贵但稳）
  • 日常对话：minimax-cn:MiniMax-M3（我自己的 MiniMax 接入，便宜）
  • 离线/隐私：本地 Ollama（要先装 ollama + 拉模型）

第三步：让 Gateway 跑起来（飞书/Telegram 接入）

如果你只想用 CLI，到这里就够了。但很多人装 Hermes 是为了从飞书/Telegram 跟它聊天——这就需要 Gateway。

terminal bash 
1hermes gateway setup    # 交互式配置（输入飞书 app_id / app_secret）2hermes gateway start   # 前台启动

前台跑能用，但 SSH 一断就死。需要常驻后台——下面讲 systemd 化。

手动写 systemd service（gateway 常驻）

官方不提供 systemd unit（因为 Hermes 设计是个人开发工具，不是服务），但生产环境你需要。我手写的版本：

/etc/systemd/system/hermes-gateway.service systemd 
1[Unit]2Description=Hermes Agent Gateway - Messaging Platform Integration3After=network-online.target4Wants=network-online.target5StartLimitIntervalSec=067[Service]8Type=simple9User=root10Group=root11ExecStart=/opt/hermes-venv/bin/python -m hermes_cli.main gateway run --replace12WorkingDirectory=/root/.hermes13Environment="HOME=/root"14Environment="PATH=/opt/hermes-venv/bin:/root/.hermes/node/bin:/root/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"15Environment="VIRTUAL_ENV=/opt/hermes-venv"16Environment="HERMES_HOME=/root/.hermes"17Restart=always18RestartSec=51920[Install]21WantedBy=multi-user.target

注意几个坑：

坑 1：vhost 路径必须在 PATH 里

ExecStart 用了绝对路径 /opt/hermes-venv/bin/python——你装的位置可能不一样。装完先跑 which python（在 venv 里）确认实际位置。直接写 python 不行，systemd 的环境 PATH 跟你登录 shell 不一样。

坑 2：HERMES_HOME 必须显式设

Hermes 不会从 WorkingDirectory 推断 HERMES_HOME，不设就找不到 ~/.hermes。我之前栽过——Gateway 启动"成功"了，但日志全空，排查了半天才发现是它跑了个临时 profile。

坑 3：HERMES_HOME 跟 VIRTUAL_ENV 配套

如果你用 uv venv /opt/hermes-venv，VIRTUAL_ENV 设成 /opt/hermes-venv，HERMES_HOME 别设到 venv 目录（我见过有人 HERMES_HOME=/opt/hermes-venv，结果 .hermes 目录被写到 venv 里——下次 uv 装包就把它清了）。

启用：

terminal bash 
1systemctl daemon-reload2systemctl enable --now hermes-gateway3systemctl status hermes-gateway4journalctl -u hermes-gateway -f

第四步：接入飞书（最常问的）

官方支持 Telegram/Discord/Slack/WhatsApp/Signal，飞书不在官方列表里——但有第三方 adapter。要装飞书：

  1. 去 飞书开放平台 创建一个企业自建应用
  2. 权限至少给：im:message、im:message:receive、im:message.group_at_msg
  3. 事件订阅 URL 填 https://<你的域名>/feishu/webhook（Hermes Gateway 默认端口）
  4. 把 App ID + App Secret 写到 ~/.hermes/.env：
~/.hermes/.env bash 
1FEISHU_APP_ID=cli_xxxxxxxx2FEISHU_APP_SECRET=****3FEISHU_HOME_CHANNEL=oc_xxxxxxxx4FEISHU_ENCRYPT_KEY=****5FEISHU_VERIFICATION_TOKEN=****
飞书 App 上线必踩的坑：权限必须"发布"

加完权限要在「版本管理与发布」里点"保存"+"申请发布"。仅勾权限、不发版=没生效，错误码 1770024。我在这个坑上栽过 2 次才反应过来——文档里只字未提。

配置完后重启 gateway：

terminal bash 
1systemctl restart hermes-gateway2journalctl -u hermes-gateway --since "1 min ago"34# 看到 "feishu: connected" 就 OK

在飞书里给机器人发消息，应该能收到回复了。

第五步：备份和迁移（装机必做）

Hermes 真正值钱的是你的 ~/.hermes 里的记忆 + skills + 配置——不是它本身。装新机器时，git clone + curl install.sh 一行就搞定，值钱的数据你得自己备份。

最小备份集

  • ~/.hermes/MEMORY.md + USER.md — 核心记忆
  • ~/.hermes/skills/ — 自定义技能（已发布的、累积改过的）
  • ~/.hermes/config.yaml — 主配置（不含 .env，密钥分开存）
  • ~/.hermes/.env — 密钥（单独加密存储，比如 1Password / Bitwarden）

迁移脚本（我用的）

~/bin/hermes-backup.sh bash 
1#!/usr/bin/env bash2set -e3DEST="$1:~/backup/hermes/$(date +%Y%m%d)"45if [ -z "$1" ]; then6    echo "usage: hermes-backup.sh user@host"7    exit 18fi910rsync -avz --progress \11    --exclude="*.lock" \12    --exclude="cache/" \13    --exclude="*.log" \14    --exclude="models/" \15    ~/.hermes/ "$DEST"1617if [ -f ~/.hermes/.env ]; then18    scp ~/.hermes/.env "$DEST/.env"19fi2021echo "✓ backup at $DEST"

恢复时：

terminal bash 
1# 新机器2curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash34# 停掉 gateway，恢复 .hermes5systemctl stop hermes-gateway 2>/dev/null || true6rsync -avz ~/backup/hermes/20260610/ ~/.hermes/78# 启动9systemctl enable --now hermes-gateway

记忆、技能、偏好全回来了。

常见坑速查

1. "装完跑 hermes 报错 ModuleNotFoundError"

基本是 venv 没激活，或者 systemd 跑的不是 venv 里的 Python。which python（在 venv 里）确认路径，把 ExecStart 改成绝对路径。

2. "Gateway 启动了，飞书消息收不到"

去 journalctl -u hermes-gateway 看是不是 FEISHU_APP_SECRET not set。hermes config set 设了但没写到 .env——手动 export 或者在 service 的 Environment 里加。

3. "RSS/定时任务跑了但没投递"

Cron 任务完成后默认存到 ~/.hermes/cron/output/，不投递。要投递到飞书/Telegram，在 hermes config 里设 cron.delivery。

4. "升级后旧 skills 失效"

Hermes 的 skills 跟版本有耦合关系。升完跑 hermes doctor，它会列出哪些 skill 兼容、哪些需要重装。一次性脚本：

terminal bash 
1hermes update2hermes doctor3hermes skills --refresh

什么时候不要装

老实说几句：

  • Windows 原生：官方明确 early beta，坑多。先上 WSL2。
  • Mac Apple Silicon：能装能跑，但 TUI 有时字体渲染有问题。介意的话 Linux server 走起。
  • 没有持久磁盘的 serverless：用 Daytona/Modal 后端，本地不装。
  • 只是想要个 ChatGPT 替代：太重了，llm CLI 工具够用。

装完之后

命令行先跑 hermes doctor 看下健康度——它会告诉你 env、模型、gateway、cron 各自状态。

然后从飞书发一句"在吗"过去——能收到回复就算打通。

最后，给我自己的系统装个备份 cron，每天 3 点跑一次 hermes-backup.sh。

三步搞定，剩下的就是让它自己慢慢长大。