2. 安装与首次配置

这是什么：安装 = 把 Hermes Agent 变成一条能敲的 hermes 命令；首次配置 = 告诉它用哪家模型、拿哪把 API Key。

为什么用：Hermes Agent 本身不附带任何模型，Key 没配好它连一句话都说不出来；而 Python 版本选错，脚本会在装到一半时报一堆看不懂的错。

如何用：本章先跑一行官方安装脚本，再走一遍 hermes setup 向导，最后搞清楚配置和密钥分别存在哪个文件里。

2.1 一行命令装好

官方推荐源码安装脚本——它自己准备好 uv、Python、Node.js、ripgrep、FFmpeg 和全部 Python 依赖。

# Linux / macOS / WSL2
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# Windows 原生（PowerShell，不需要管理员权限）
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Windows 原生支持 Windows 10/11，不用装 WSL。原生数据在 %LOCALAPPDATA%\hermes\，WSL2 在 ~/.hermes/，两者可干净共存。

想要图形界面，官网还提供桌面软件包：Windows 是 .appinstaller（需 Windows 11 22H2+），macOS 是 DMG（仅 Apple Silicon）。

2.2 版本说明：Python 的坑

这段请认真读，能省半小时。

场景	Python 要求
PyPI 包 `hermes-agent` 0.19.0 的元数据	`>=3.11, <3.14`
官方安装脚本实际准备的版本	Python 3.14（由 `pm/lock.json` 锁死）
主分支 `pyproject.toml` 写的范围	`>=3.11, <3.15`

为什么对不上？3.11–3.13 只是为了让旧安装能跑完升级器，真正支持的运行时只有 3.14。

⚠️ 全站基线 Python 3.15 不受支持。 你多半不用自己装 Python，脚本会用 PM（Hermes 自己的包管理器）准备受管的 3.14 环境。

装完记得重开一个终端，否则 PATH 里的新命令读不到。

2.3 装到哪儿去了

平台	源码目录	命令入口	数据目录
Linux / macOS / WSL2	`~/.hermes/hermes-agent/`	`~/.local/bin/hermes`	`~/.hermes/`
Windows 原生	`%LOCALAPPDATA%\hermes\hermes-agent\`	`%LOCALAPPDATA%\hermes\bin\`	`%LOCALAPPDATA%\hermes\`

数据目录由 HERMES_HOME 决定，配置、密钥、会话、技能、插件、日志全在里面。

PATH 里会有三个命令：hermes（交互式聊天）、hermes-agent（单次查询跑完就退）、hermes-acp（当作 ACP 服务端）。

2.4 首次配置：`hermes setup`

hermes setup

第一次跑进向导，给你三个模式：

模式	适合谁
Quick Setup（Nous Portal）	懒人首选。OAuth 登录，覆盖 300+ 模型和工具
Full Setup	自带 Key，逐项配置每个提供商和工具
Blank Slate	极简主义。除模型、文件、终端三样外全关

只想跑通最快路径，直接用 Portal：

hermes setup --portal

一条命令：OAuth 登录 → 把 Nous 设成提供商 → 打开 Tool Gateway（搜索、图像、TTS、云浏览器）。

已经配过了想改？hermes setup 会进重配向导，每个问题都拿当前值当默认值，回车即保留。也可以只配某一节：

hermes setup model      # 只配提供商和模型
hermes setup tools      # 只配工具开关
hermes setup terminal   # 只配终端后端和沙箱
hermes setup gateway    # 只配消息平台
hermes setup agent      # 只配 Agent 行为

2.5 配置和密钥，分两个文件

~/.hermes/config.yaml 存不敏感的设置（模型名、终端后端、插件开关……明文 YAML）；~/.hermes/.env 存密钥（API Key、Bot Token，一行一个 KEY=value）。

用 CLI 改最省心，会自动判断该写进哪个文件：

hermes config set model anthropic/claude-opus-4.6
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...

想读某个值用 hermes config get。

2.6 验证 + 排障

hermes --version
hermes doctor

你会看到（示意）：

  hermes-agent 0.19.0
  install: git (~/.hermes/hermes-agent)
  python:  3.14.2 (managed)
  status:  ok — no issues found

hermes doctor 是体检命令：告诉你缺什么、怎么补，还包括安装方式。

症状	原因	解法
`hermes: command not found`	PATH 没刷新	开新终端；或 `export PATH="$HOME/.local/bin:$PATH"`
`API key not set`	没配提供商	跑 `hermes model`
更新后配置丢了	配置格式过期	`hermes config check` 然后 `hermes config migrate`
杀毒软件误杀 `uv.exe`	未签名 Rust 二进制的误报	把 `%LOCALAPPDATA%\hermes\bin` 整个加白名单

📌 Windows 专属：Hermes 在 Windows 上执行终端命令走 Git Bash（和 Claude Code 同一策略）。没有 Git 时脚本会自动下载一份校验过的 Git for Windows，不碰你系统里已有的。

动手改

按你的系统跑一行安装命令，开一个新终端，跑 hermes --version 把版本号记下来。
跑 hermes doctor，把输出通读一遍——这是了解这次安装状态最快的办法。
执行 hermes setup --portal（或走 Full Setup），再用 hermes config get 看模型名和 Key 是否落在该落的文件里。

小结

官方安装方式是源码脚本：curl ... install.sh | bash（POSIX）/ iex (irm ... install.ps1)（Windows 原生）
Python：脚本自己准备 3.14；PyPI 0.19.0 元数据是 >=3.11,<3.14；3.15 不受支持
装完有三个命令：hermes / hermes-agent / hermes-acp
数据目录由 HERMES_HOME 决定：POSIX 在 ~/.hermes/，Windows 在 %LOCALAPPDATA%\hermes\
hermes setup 有 Quick / Full / Blank Slate 三种模式；hermes setup --portal 最快
配置在 config.yaml，密钥在 .env，用 hermes config set 改最安全

下一章：跑起来：接云端 API 或本地模型 🐸