2026 Hermes Agent 全网最完整安装与配置指南：保姆教程实战案例从 0 到跑通

2. 痛点拆解

1. 限制：教程停在「启动成功」。终端里出现欢迎语不等于模型连通、文件工具可用或网关能收消息。Hermes 真正可用要同时完成环境核对、模型连通、权限边界、日志可追踪和低风险案例验收。
2. 隐性成本：密钥与路径散落。API Key 只贴在笔记里、config.yaml 与 .env 不一致、工作区指向整个用户主目录——一次误操作就可能改写 SSH 密钥或生产仓库。
3. 稳定性与审计：装完就忘日志在哪。出问题时盲目重装，反而覆盖掉 ~/.hermes/logs/errors.log 里仅有的线索；也不做备份，升级后无法回滚配置。

3. 安装前准备：Mac 与环境核对清单

目的：避免装到一半才发现网络、Git 或磁盘不满足要求。通过标准：下面清单全部打勾后再执行安装脚本。

• 系统：macOS 12+（Intel 或 Apple Silicon 均可；Apple Silicon 上本地推理可选性更好，但云端模型仍以 provider 文档为准）。
• Git：官方 git 安装器唯一硬性前置是 Git（git --version ≥ 2.30 推荐）。无 Git 时先装 Xcode Command Line Tools 或 brew install git。
• 网络：需能访问 GitHub raw（安装脚本）及你选的 LLM provider API；公司代理环境提前配置 HTTPS_PROXY。
• 磁盘：官方安装会拉取 Python 3.11、Node.js v22、ripgrep、ffmpeg 与代码仓库，建议预留 ≥ 2GB 可用空间（含 Skills 缓存时更接近 1.5–3GB，以当时文档为准）。
• 权限：个人用户安装无需 sudo；若曾用 root 模式安装，数据目录可能在 /root/.hermes，与本文默认路径不同。
• 备份：若已有旧版 ~/.hermes，先 cp -a ~/.hermes ~/.hermes.bak-$(date +%F)。
• 测试目录：创建隔离工作区（下文统一用 ~/hermes-lab），不要把首次实战指向 ~/Documents、生产 git 仓库或含密钥的目录。

# 安装前快速自检（复制整段执行）
git --version
sw_vers
df -h ~
mkdir -p ~/hermes-lab/{inbox,outbox,archive}
echo "Hermes lab sample: Q2 planning notes." > ~/hermes-lab/inbox/sample.txt

失败先看：Git 报错 → CLT/Homebrew；磁盘不足 → 清理 Downloads 或换盘；网络超时 → 换网络或镜像，不要在未确认原因时连续重装三遍。

4. 按官方方式安装 Hermes Agent

目的：用 Nous Research 维护的安装入口，让安装器自动处理 Python、Node 与 CLI。来源：官方 Installation 文档（发布前请再核对是否有新版本号或额外参数）。

4.1 推荐：Git 一键安装（跟踪 main）

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

安装器会自动完成：uv、Python 3.11、Node.js v22、ripgrep、ffmpeg、克隆仓库、创建虚拟环境、将 hermes 加入 PATH。典型布局（per-user）：

• 代码：~/.hermes/hermes-agent/
• 数据与配置：~/.hermes/（可用 HERMES_HOME 覆盖）
• CLI：~/.local/bin/hermes

4.2 备选：pip 安装（需已有 Python 3.11+）

pip install hermes-agent
hermes postinstall   # 可选：补装 Node、浏览器、ripgrep、ffmpeg 并跑 setup

PyPI 版本跟踪标签发布；若要 bleeding-edge，仍建议用上面的 git 安装脚本。两种方式的 hermes update 行为不同，以 hermes doctor 显示的安装方式为准。

4.3 安装后必做三步

source ~/.zshrc          # 或新开一个终端窗口
hermes version           # 记录版本号到笔记，便于日后排错
hermes doctor            # 自动诊断缺失项；可加 --fix 尝试修复

通过标准：which hermes 指向 ~/.local/bin/hermes；hermes doctor 无阻塞性 FAIL。失败先看：安装脚本最后 20 行日志 → PATH → 是否混用系统 Python 直接执行仓库内 hermes 文件（应使用 venv 启动器）。

切忌：安装失败后不要立刻「删掉 ~/.hermes 再装」——先保存终端输出与 hermes doctor 结果，否则难以区分是网络问题还是权限问题。

5. 配置模型与 API Key

目的：让 Hermes 能调用你选的 LLM provider。通过标准：非交互式冒烟收到合理回复；hermes auth list 或 .env 中有对应项且不在 shell history 明文长期停留。

5.1 交互式配置（首次推荐）

hermes setup          # 全量向导：模型、工具、网关等
# 或分步：
hermes model          # 选择 provider 与默认模型
hermes tools          # 按需启用工具集

5.2 环境变量与配置文件

主配置一般在 ~/.hermes/config.yaml；密钥引用多在 ~/.hermes/.env（用 hermes config path、hermes config env-path 确认实际路径）。示例（变量名以你所选 provider 的官方文档为准，勿照抄过期名称）：

# 示例：OpenRouter（请替换为你的 key，勿提交到 git）
hermes config set OPENROUTER_API_KEY "sk-or-v1-xxxxxxxx"

# 或直接编辑 .env（chmod 600 ~/.hermes/.env）
echo 'OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx' >> ~/.hermes/.env

边界提示：模型价格、API 限额、地区可用性与隐私政策会随 provider 调整——上线前务必阅读其最新条款。本文不绑定某一固定模型名。

6. 工作目录、权限与日志

目的：装好后「可追踪、可限制、可回滚」。原则：最小权限——先只允许动测试目录，再逐步放开真实项目。

• 工作区：在 config.yaml 或会话中指定 ~/hermes-lab；可在该目录放 AGENTS.md 描述允许的工具与边界（参见官方 Context Files 文档）。
• macOS 权限：若启用终端/文件类工具，系统可能提示「完全磁盘访问」——首次验收阶段可只授予测试目录相关权限，避免对整个磁盘放权。
• 日志目录：默认 ~/.hermes/logs/（含 agent.log、errors.log、gateway.log）。用 hermes logs list、hermes logs errors --since 30m 查看。
• 密钥安全：chmod 600 ~/.hermes/.env；备份 zip 不要放进同步盘；勿让 Agent 读取 ~/.ssh、支付或生产 kubeconfig。
• 后台运行（可选）：需要 Telegram/Discord 等网关时，用 hermes gateway setup 与 hermes gateway install；长期运维见本站Hermes 长期维护指南。

通过标准：对 Agent 说「只读写 ~/hermes-lab」后，尝试访问主目录外路径应被拒绝或在日志中留下审计记录。

7. 首次运行验收：七步 Runbook

下面七步把「配置完成」推到「实战可用」的门槛——建议原样执行并保存输出截图或日志片段。

1. 诊断：hermes doctor --fix → 无未处理 FAIL。
2. 模型 ping：hermes chat -q "Reply with exactly: HERMES_OK" → 回复含 HERMES_OK。
3. 文件读：让 Agent 读取 ~/hermes-lab/inbox/sample.txt 并复述首句。
4. 文件写：写入 ~/hermes-lab/outbox/ping.txt → cat 可见。
5. 日志：hermes logs errors --since 10m → 无新 ERROR（或已知可忽略项已记录）。
6. 关终端：关闭窗口，新开终端重复步骤 2 → 排除 PATH 仅当前 session 生效。
7. 可选重启：重启 Mac 后再跑步骤 2（若已装 gateway，再加 hermes gateway status）。

可引用阈值（个人验收参考，非官方 SLA）：冒烟回复 < 60s；errors.log 10 分钟内 0 条未解释 ERROR；测试文件写入后 ls -la ~/hermes-lab/outbox 可见新文件。

8. 跑通第一个实战案例：摘要 + 待办 + 可回滚输出

场景设计：在测试目录读取样本文本，生成中文摘要与 3 条待办，写入 Markdown，并保留回滚副本。该案例同时覆盖安装结果（CLI）、配置结果（模型）、真实 workflow（读→推理→写→日志）。

# 1. 准备输入（若第 3 节已创建可跳过）
cat > ~/hermes-lab/inbox/weekly-notes.txt <<'EOF'
本周完成：Hermes 安装文档草稿。
待跟进：配置 OpenRouter 预算告警；下周评估 gateway 接 Telegram。
风险：勿把 API Key 提交到 git。
EOF

# 2. 启动交互会话（或使用一条复合指令）
hermes
# 在会话中发送（示例提示词）：
# 「请只使用 ~/hermes-lab 目录。读取 inbox/weekly-notes.txt，
#   用中文写 150 字以内摘要 + 3 条待办，保存到 outbox/summary-and-todos.md，
#   并把原文件复制到 archive/weekly-notes.bak」

# 3. 非交互验收
ls -la ~/hermes-lab/outbox/summary-and-todos.md
ls -la ~/hermes-lab/archive/
hermes logs agent -n 30 --since 15m

通过标准：

• summary-and-todos.md 含摘要与 3 条待办，且与源文件语义一致。
• archive/ 下有备份，可用 diff 对比。
• 日志中有对应 tool call 记录；provider 账单/dashboard 有本次调用（便于核对成本）。

回滚：rm ~/hermes-lab/outbox/summary-and-todos.md && cp ~/hermes-lab/archive/weekly-notes.bak ~/hermes-lab/inbox/weekly-notes.txt。失败先看：模型是否因上下文截断未读完文件 → 权限是否拒绝写入 outbox → errors.log 中 tool 报错详情。

9. 常见问题排查：按层定位，避免盲目重装

发布前事实核对清单（维护者用）：官方 install.sh URL、最低 macOS、默认目录名、CLI 子命令、provider 环境变量名、日志路径——任一项变更都应先改文档再发布。读者侧只需记住：遇错先 hermes doctor，再查 errors.log，最后才考虑重装。

10. 下一步怎么扩展：从测试目录到真实 workflow

验收通过后，建议按下面节奏扩展，不要一步接入生产仓库或支付系统：

1. 把单个真实 side project 目录加入白名单，仍禁止 ~/.ssh 与全局 * 读写。
2. 启用 hermes cron 跑每日低风险任务（如整理下载文件夹清单——仍限测试目录）。
3. 配置一个消息网关（Telegram/Discord）并用配对模式限制陌生人（见官方 Security 文档）。
4. 建立 hermes backup --quick 的每周节奏，再读长期维护文做升级与回滚演练。