2026 Hermes Agent 全网最完整安装与配置指南：清单式保姆教程加实战案例
Hermes Agent 教程最怕「看着很完整，做完没法验收」。本文把安装、配置、首次运行和实战案例整理成六阶段清单——每项都写明检查动作、通过标准，以及没通过时先查哪里。
你可能已经执行了安装命令，但 API Key 没配好；也可能启动成功了，但权限范围太大，日志也不知道在哪里。完整安装配置应该按阶段验收：只有环境、安装、模型、权限、日志和实战案例都通过，才算 Hermes Agent 真正可用。
先行结论：官方推荐 macOS 使用一行安装脚本（仅需预先安装 Git）；配置集中在 ~/.hermes/；健康检查用 hermes doctor；实战案例只在专用测试目录里跑，不要一上来就给全盘权限。
总清单：从 0 到案例跑通
按顺序勾选六个阶段。全部打勾后，再考虑接入 Gateway、Cron 或生产仓库。
| 阶段 | 核心验收 | 关键命令/路径 |
|---|---|---|
| ① 安装前 | Git、网络、测试目录、API Key 账号就绪 | git --version、~/hermes-workspace |
| ② 安装 | hermes --version 可用，目录结构正确 |
官方 install.sh、~/.local/bin/hermes |
| ③ 配置 | provider、模型、.env、工作目录、日志路径确认 | hermes setup、~/.hermes/.env |
| ④ 首次运行 | 模型 ping、读写测试文件、日志写入、重启恢复 | hermes、hermes doctor |
| ⑤ 实战案例 | 摘要+待办输出、日志可追溯、可回滚 | 测试目录内 sample.txt |
| ⑥ 排错/收尾 | 分层倒查，权限收敛后再扩 workflow | ~/.hermes/logs/ |
1. 安装前清单
在复制任何 curl 命令之前，先把下面表格逐项打勾。官方 Git 安装器唯一硬性前置依赖是 Git；Python 3.11、Node.js v22、uv、ripgrep、ffmpeg 会由安装脚本自动处理。
| ☐ | 检查动作 | 通过标准 | 失败先查 |
|---|---|---|---|
| ☐ | 确认 macOS 与芯片 | Apple Silicon 或 Intel Mac，系统版本满足当前 官方安装文档 要求 | 系统升级或换用 pip / Nix 路径 |
| ☐ | git --version |
能输出版本号；未安装则 xcode-select --install 或 Homebrew 安装 git |
Xcode CLT / Homebrew |
| ☐ | 测试网络 | curl -I https://raw.githubusercontent.com 与所选 LLM provider 域名均可达 |
代理、DNS、公司防火墙 |
| ☐ | 确认磁盘空间 | 至少预留 5–10 GB（含 Python venv、Node、浏览器自动化依赖） | 清理 ~/Library/Caches |
| ☐ | 注册 LLM 账号并生成 API Key | 推荐 OpenRouter（灵活）或 Anthropic / OpenAI 等；Key 已复制到密码管理器，未写入聊天或截图 | provider 控制台账单与地区可用性 |
| ☐ | 创建测试工作区 | mkdir -p ~/hermes-workspace/{inbox,outbox,scratch,backups} 且 chmod 700 ~/hermes-workspace |
路径拼写、磁盘权限 |
| ☐ | 备份现有配置（若重装） | 旧 ~/.hermes/ 已 tar 备份到 backups/ |
勿直接 rm -rf ~/.hermes 除非已备份 |
| ☐ | 准备样本文本（实战用） | ~/hermes-workspace/inbox/sample.txt 已创建，内容 200–500 字即可 |
文件编码 UTF-8 |
2. 安装清单
macOS 官方推荐命令（2026 年 5 月文档）：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash备选：pip install hermes-agent（PyPI，v0.14+）；Nix 用户见官方 Nix 指南。自定义安装目录可设 HERMES_INSTALL_DIR，详见官方文档。
| ☐ | 检查动作 | 通过标准 | 失败先查 |
|---|---|---|---|
| ☐ | 确认命令来源 | URL 指向 NousResearch/hermes-agent 官方仓库 main/scripts/install.sh |
勿使用来路不明的一键脚本 |
| ☐ | 观察安装输出 | 无致命 error；出现 clone venv、uv、Node 等步骤且无中断 | 网络超时 → 重试；权限 → 勿 sudo 除非明确需要 root 模式 |
| ☐ | source ~/.zshrc 后 which hermes |
路径为 ~/.local/bin/hermes（per-user 安装） |
PATH 未刷新 → 重开终端；检查 ~/.local/bin 是否在 PATH |
| ☐ | hermes --version 或 hermes doctor |
CLI 正常输出版本/诊断，无 command not found |
是否误用系统 Python 调 repo 源码而非 venv launcher |
| ☐ | 核对安装布局 | 代码在 ~/.hermes/hermes-agent/，数据目录 ~/.hermes/ 已创建 |
HERMES_HOME 是否被意外覆盖 |
| ☐ | 检查运行时依赖 | hermes doctor 对 Python、Node、ripgrep 等项为 green / 有修复建议 |
doctor 输出中的具体缺失项；必要时 hermes update |
3. 配置清单
配置主文件：~/.hermes/config.yaml（主设置）与 ~/.hermes/.env（API Key 与环境变量）。推荐首次运行完整向导：
hermes setup # 全量向导
# 或分项：
hermes model # 选择 provider 与模型
hermes tools # 启用/禁用工具
hermes config set KEY value| ☐ | 检查动作 | 通过标准 | 失败先查 |
|---|---|---|---|
| ☐ | 配置 LLM provider | hermes model 完成后 config.yaml 含 model.default；OpenRouter 示例：OPENROUTER_API_KEY 写入 .env |
Key 拼写、provider 地区限制、余额 |
| ☐ | 密钥文件权限 | chmod 600 ~/.hermes/.env；config.yaml 中无明文 key |
是否误把 key 写进 yaml 或 git |
| ☐ | 工作目录 | MESSAGING_CWD=~/hermes-workspace（或绝对路径）已写入 .env |
路径不存在、iCloud 同步目录误用 |
| ☐ | 终端后端与权限 | 试用阶段保持 terminal.backend: local + approvals.mode: manual；生产再考虑 docker/ssh |
是否误开 YOLO 或 GATEWAY_ALLOW_ALL_USERS |
| ☐ | 日志位置 | ~/.hermes/logs/ 存在且可写；确认不在 Dropbox/iCloud 同步路径 |
磁盘满、目录权限 |
| ☐ | 工具集 | hermes tools 仅启用案例所需工具（文件读写、终端）；浏览器/网关可后续再加 |
多余工具导致权限面过大 |
| ☐ | 配置完整性 | hermes config check 通过；升级后必要时 hermes config migrate |
版本跳跃未 migrate |
4. 首次运行清单
cd ~/hermes-workspace
hermes # 进入交互 CLI| ☐ | 检查动作 | 通过标准 | 失败先查 |
|---|---|---|---|
| ☐ | 模型 ping | 发送「你好，回复 OK」类短 prompt，数秒内收到合理回复；无 API key not set |
hermes model、.env 变量名、provider 状态页 |
| ☐ | 文件读写 | 让 agent 在 scratch/ 创建 ping.txt 并读回；文件仅出现在工作区内 |
cwd、macOS 隐私权限弹窗、审批是否被误拒 |
| ☐ | 日志写入 | 对话后 ~/.hermes/logs/ 有新条目或时间戳更新 |
日志级别、目录权限 |
| ☐ | 关闭终端再开 | 新终端中 hermes 仍可启动，配置未丢失 |
shell profile 未持久化 PATH |
| ☐ | 重启 Mac 后恢复（可选） | 重启后 CLI 仍可用；若已 hermes gateway install，launchd 服务按官方文档自启 |
launchctl list | grep hermes、gateway 日志 |
| ☐ | hermes doctor 终检 |
无 blocking 项；安装方式检测正确（git / pip / nix） | 按 doctor 逐条修复，勿盲目重装 |
5. 实战案例清单：文本摘要 + 待办提取
在测试目录完成第一个可验收任务。不要指向生产仓库、云控制台或 ~/Documents。
5.1 准备输入
cat > ~/hermes-workspace/inbox/sample.txt <<'EOF'
项目周会纪要（测试样本）
- 张三：下周完成 API 文档 v2
- 李四：修复登录页 403 问题，截止周三
- 王五：调研 Hermes Agent 与 OpenClaw 差异，周五汇报
EOF
cp ~/hermes-workspace/inbox/sample.txt ~/hermes-workspace/backups/sample.txt.bak5.2 任务 prompt（复制到 hermes CLI）
请读取 inbox/sample.txt，在 outbox/ 生成两份文件：
1) summary.md — 200 字以内摘要
2) todos.md — Markdown 待办清单，每项含负责人与截止日期
不要修改 inbox 原文件，不要访问工作区以外的路径。| ☐ | 检查动作 | 通过标准 | 失败先查 |
|---|---|---|---|
| ☐ | 输出文件存在 | outbox/summary.md 与 outbox/todos.md 已生成，内容与人名/日期匹配 |
审批是否 pending、模型是否幻觉编造 |
| ☐ | 原文件未变 | diff inbox/sample.txt backups/sample.txt.bak 无差异 |
prompt 约束、工具权限 |
| ☐ | 日志可追溯 | 日志中有本次 session 的工具调用记录 | 日志路径、日志级别 |
| ☐ | 回滚验证 | rm outbox/*.md 后可重新跑任务并成功；backup 仍可恢复 |
会话缓存、文件锁 |
| ☐ | 成本观察 | provider 控制台可见本次 token 用量在预期内；已设 spend limit（若 provider 支持） | 模型是否过大、是否陷入 tool 循环 |
| ☐ | 权限边界 | agent 未尝试读 ~/.hermes/.env 或 ~/.ssh；危险命令触发 manual 审批 |
tools 配置、审批模式 |
6. 排错清单：分层倒查，别先重装
遇到问题时按层向下查，每层通过再进下一层。多数「装完不能用」是 PATH、Key 或 cwd，不是 Hermes 本体损坏。
| 层级 | 症状 | 先查 | 常见修复 |
|---|---|---|---|
| 依赖 | hermes: command not found |
PATH、~/.local/bin |
source ~/.zshrc |
| 网络 | 安装/模型超时 | curl GitHub、provider API | 代理、DNS、换网络 |
| Key | API key not set |
~/.hermes/.env 变量名 |
hermes model 或 hermes config set |
| Provider | 401/429/5xx | provider 状态页、余额、模型 ID | 换模型、设限额、稍后重试 |
| 权限 | 无法写文件 / 命令被拒 | cwd、审批队列、macOS TCC | 批准命令、缩小/修正工作目录 |
| 路径 | 找不到 config | HERMES_HOME、多用户冲突 |
统一 HERMES_HOME 或专用账户 |
| 日志 | 静默失败 | ~/.hermes/logs/、errors.log |
按日志关键字定向修配置 |
| 后台服务 | Gateway 不响应 | launchd 状态、token、白名单 | hermes gateway 子命令、官方 gateway 文档 |
7. 完成后清单：接入真实 workflow 之前
- ☐ 再次备份
~/.hermes/（含 config、skills、非密钥会话若需要） - ☐ 确认
approvals.mode仍为 manual 或符合团队策略 - ☐ Gateway 若启用：白名单 / DM pairing 已配置，未使用
GATEWAY_ALLOW_ALL_USERS - ☐ 在 provider 控制台设置 spend limit 与告警
- ☐ 人工抽查 outbox 输出质量，再决定是否绑定真实 repo
- ☐ 阅读官方 Security 文档，再扩大工具集或 terminal 后端
全部阶段验收通过后，再扩展 Telegram Gateway、Cron 定时任务或 CI 集成。若需进一步收紧 Mac 上的权限与密钥边界，可参考本站同主题的Hermes Agent Mac 安全配置指南。
在 Mac mini 上跑通 Hermes，验收更省心
Hermes Agent 依赖 Git、Python、Node 和 Unix 终端工具链——这些在 macOS 上原生可用，无需 WSL 或额外驱动。把 agent 放在专用 Mac mini 上，可以把 CLI 试用、Gateway 和日志与主力 MacBook 的个人文件隔离开；Apple Silicon 统一内存对本地 Ollama 等辅助路由更友好，macOS 的 Gatekeeper、SIP 与 FileVault 也提供系统级完整性保护。
Mac mini M4 待机功耗约 4W、无风扇静音，适合作为 7×24 的 agent 节点；配合 hermes gateway install 的 launchd 守护，重启后服务可自动恢复。若你正按本文清单验收 Hermes，Mac mini M4 是目前性价比最高的专用主机——现在即可入手，让清单里的每一关都在稳定硬件上通过。