Hermes 安装成功和 Hermes 能完成任务是两个检查点。安装器只解决程序、环境和 launcher；一次可追踪的首聊还要经过 profile、provider、model、凭据和网络。把这几层分开验收，失败时才能知道应该修 PATH、配置还是模型链路。
本教程只完成“官方安装 → setup → doctor → 固定首聊 → 新 shell 恢复”。Gateway、Cron、Memory、Skills、Plugins、MCP、浏览器和迁移全部留到后续独立实验。
版本与资料来源： 本页依据 Hermes 当前的 Quickstart、Installation、CLI Commands、Updating 与 GitHub Release 编写，并于 2026-10-07 在 macOS 上实测了升级到 v0.21.5、doctor、首聊和会话恢复（见文末）。命令结果以你的实际环境为准。
下载固定首聊材料
提示词要求 Hermes 不调用工具、不读取文件、不浏览、不用 Memory，只精确返回 HERMES-CANARY-20260909。它只能证明请求到模型再返回终端的最小链路，不能证明工具、Memory、Gateway 或 Cron 已经可用。
第 0 步：选择安装路径
| 环境 | 当前官方入口 | 本教程的注意点 |
|---|---|---|
| macOS / Windows 图形界面 | 官网 Hermes Desktop installer | 同时安装桌面与 CLI，记录官方下载页和应用版本 |
| Linux / macOS / WSL2 | 官方 shell installer | 在普通用户环境执行，记录 launcher 与 install method |
| Windows native CLI | 官方 PowerShell installer | 不与 WSL2 的路径和配置混为一套 |
| Android / Termux | shell installer + 专项指南 | 后台保活、权限和可用 extras 另行验收 |
| Docker / Nix | 对应官方部署文档 | 生命周期和更新方式不同，不照抄 git installer 回滚 |
macOS 和 Windows 新用户可优先评估 Desktop。长期跑在 Linux 服务账号、容器或 NixOS 上时，应走对应部署路径，不先在个人终端跑通就声称服务器已经可用。
第 1 步：核对官方安装命令
Linux、macOS、WSL2 与 Termux 的当前官方 CLI 命令是：
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bashWindows native 在 PowerShell 中使用：
iex (irm https://hermes-agent.nousresearch.com/install.ps1)远程脚本会随上游变化。执行前应先从官方 Quickstart 重新核对域名和命令；企业或受管设备还应按组织规则先下载审查。不要从搜索广告、聊天附件或第三方 gist 执行同名脚本。
CLI 安装后重新打开终端，或按当前 shell 重新加载配置：
source ~/.zshrc # zsh
source ~/.bashrc # bash然后记录 launcher：
command -v hermes
hermes dumpWindows PowerShell 可用：
Get-Command hermes
hermes dump官方 CLI 参考说明，hermes dump 默认输出版本、release date、commit、OS、Python、active profile / HERMES_HOME、model、terminal、API key 是否设置、toolsets、MCP 数量和 Memory provider。不要添加 --show-keys，也不要把 dump 中可能暴露环境的信息直接公开。
第 2 步：理解三种 setup
当前新安装的 hermes setup 提供三种模式：
| 模式 | 官方当前行为 | 适合的首次选择 |
|---|---|---|
| Quick Setup | Nous Portal OAuth；设置模型并启用 Tool Gateway | 接受 Portal 数据与账号边界，希望最快跑通 |
| Full Setup | 逐项选择 provider、工具和其他选项 | 已知道自己的 provider 和工具需求 |
| Blank Slate | provider/model、File Operations 和 Terminal 保留；web、browser、code execution、vision、memory、delegation、cron、skills、plugins、MCP 等关闭 | 希望从最少能力逐项启用 |
Blank Slate 仍然包含文件和终端工具，因此不是“没有权限”。固定首聊提示明确要求不调用工具；首聊结束后还要检查是否真的没有工具调用。
Nous Portal 的快捷路径是：
hermes setup --portal若使用其他 provider，从终端运行：
hermes modelhermes model 可新增 provider、运行 OAuth、填写 API Key 或配置自托管 endpoint。聊天中的 /model 只能切换已配置项，不能替代首次 provider setup。
第 3 步：先跑 doctor，不自动乱修
hermes doctor
hermes config check把退出码和关键错误原文写进验收表。hermes doctor --fix 会尝试修复，应先看它准备处理什么；不要在不了解差异时把自动修复当作默认第一步。
常见分层：
| 现象 | 更可能的层 | 下一项证据 |
|---|---|---|
hermes: command not found | launcher / PATH | command -v、新 shell、~/.local/bin |
| config missing / stale | 配置迁移 | hermes config check，再评估 config migrate |
| API key not set | provider | 重新运行 hermes model，不先加 Gateway |
| doctor 显示错误 install method | 安装身份 | hermes dump 和真实目录 |
ModuleNotFoundError: dotenv | 调错 repo 源文件 | 核对调用的是 venv launcher 而非源码同名文件 |
官方 Installation 文档说明 Hermes 会根据 git installer、Docker 或 Nix store 路径自动识别安装方式，hermes doctor 也会在环境摘要中显示。不要自行设置一个“install method”环境变量掩盖路径问题。
第 4 步：运行固定首聊
把下载的 prompt 放进空练习目录，然后执行：
hermes chat --query-file hermes-first-chat-prompt.txt官方 CLI 文档说明 --query-file 会把文件内容直接传入，文本里的引号、命令替换或反引号不会被 shell 解释。这比把未知提示拼进 shell 参数更适合可复现实验。
本实验通过条件只有四项：
- 命令退出正常；
- 回复只包含一行
HERMES-CANARY-20260909； - 运行记录没有工具调用；
- 验收表记录实际 provider、model 和耗时。
模型多写解释不代表 Hermes 安装失败，但精确指令跟随没有通过，应如实记为首聊失败或有条件通过。不要为了得到绿色结果修改验收标准。
本站实测：首聊与会话恢复（2026-10-07，v0.21.5）
环境：macOS 26.4（Apple Silicon），git 安装，默认 provider zai、模型 glm-5.3-flash。
$ hermes chat --query-file hermes-first-chat-prompt.txt
╭─ ☤ Hermes ──────────────────────────────╮
HERMES-CANARY-20260909
╰──────────────────────────────────────────╯
会话： 20261007_120448_24c9f8
时长： 7秒
消息： 2（用户 1 条，工具调用 0 次）四项通过条件全部满足：退出码 0、只回一行金丝雀、工具调用 0 次、记录了 provider 和模型。
再验证会话能接着用：
hermes --resume 20261007_120448_24c9f8 chat --query-file q2.txt终端显示“↻ 已恢复会话 …（1 条用户消息，共 2 条消息）”，并按新提示回复。hermes sessions list 里能看到这条会话和它所在的工作目录。
v0.21.5 的一个变化：在真实终端（TTY）里，--query-file 会把内容作为第一条消息并进入交互会话；想要“回答完就退出”的旧行为，加 --oneshot。
第 5 步：证明新 shell 和会话恢复可用
关闭终端，打开一个全新 shell，重新运行：
command -v hermes
hermes sessions list
hermes --continue恢复工具的目的不是继续闲聊，而是确认 launcher 不依赖安装时的临时环境，首聊会话也能被准确定位。若 --continue 恢复了错误会话，记录 session 列表与活跃 profile，不用新增 Memory 来掩盖会话问题。
第 6 步：更新检查与版本固定
本页核读的当前 Release 是 2026-09-07 发布的 v0.21.1 / v2026.9.7。现有安装可用：
hermes update --check需要更新时再运行：
hermes update官方更新文档说明 Hermes 会根据安装方式给出匹配路径，并在更新前默认保存轻量状态快照。该快照会覆盖部分运行状态，但大于 1 GiB 的单文件可能跳过；不能把它等同于完整离线备份。生产或迁移环境仍需单独盘点恢复资产。
更新后重新执行 hermes dump、hermes doctor 和固定首聊。只看 hermes update 退出码不能证明 provider 和 session 仍然可用。
本站实测：更新卡在“Preparing Node dependencies”
2026-10-07 本站从 v0.20.6 运行 hermes update --yes。hermes update --check 先提示有更新；--plan 显示安装方式为 git、6 个 profile、没有正在运行的服务。代码几分钟就拉取完成，但收尾阶段卡在安装桌面版依赖，20 多分钟没有进展。
排查方法：
ps aux | grep "node install.js" # 找到卡住的下载进程
lsof -p <PID> | grep -E "TCP|zip" # 看它在下载什么、连到哪里结果是它在直连 GitHub 下载约 113MB 的 Electron（electron-v40.10.2-darwin-arm64.zip），每 20 秒只增加约 290KB。原因：Electron 下载器默认不使用 http_proxy / https_proxy 环境变量，即使系统设置了代理也在直连。
处理：结束卡住的进程，让 Electron 下载走代理后重跑更新。Hermes 会识别“未完成的更新”并接着收尾：
export ELECTRON_GET_USE_PROXY=1
export GLOBAL_AGENT_HTTPS_PROXY=http://127.0.0.1:你的代理端口
hermes update --yes本站换成走代理后，Electron 不到 1 分钟下载完成，更新输出 ✓ Update complete!，6 个 profile 的配置格式从 v39 迁移到 v50。不需要卸载重装。
更新完成后注意两点：
- 输出里有一行“Seeded .env for 5 profile(s) (copied from default)”：默认 profile 的
.env（可能含 API Key）被复制到了其他 profile。各 profile 本来就该用不同凭据的话，更新后要逐个检查。 hermes doctor可能列出“Orphan alias”（指向已删除 profile 的别名）和 npm 漏洞提示，它们不影响首聊。
不在首轮开启的能力
- Messaging Gateway 与真实 bot token；
- Cron 或无人值守任务；
- Memory 自动捕获和长期偏好；
- 未审查的 Skills、Plugins 和 MCP；
- 多 provider fallback、外部 API Server 或 browser 登录态；
- OpenClaw 真实状态迁移。
每增加一项能力，都应保留当前首聊基线，并加入一条正常金丝雀和一条拒绝或失败路径。
最终通过标准
- 安装来自当前官方入口，launcher 和 install method 已记录。
hermes dump显示 v0.21.1 / v2026.9.7 或安装日的更新官方版本。- setup 模式、provider、model、凭据类型和启用 toolsets 已记录，不含秘密值。
hermes doctor没有未处理的关键错误，config check结果明确。- 固定首聊精确返回金丝雀，且没有调用工具。
- 新 shell 仍能调用 Hermes，session list 与 continue 指向正确会话。
- Gateway、Cron、Memory、Skills、Plugins、MCP 和迁移各有独立验收，安装成功不能代替它们。
完成后只选择一个下一步。已有 OpenClaw 状态先进入迁移 dry-run；要长期记忆先做无敏感 Memory 实验；重复流程先做 Skill 回归；消息入口则先完成 allowlist 和撤销设计。