Windows 上安装 Hermes Agent 详细指南(2026 版,含一键安装失败处理)

写于 2026-11-22

适用对象:使用 Windows 10 / Windows 11 电脑、不熟悉命令行的读者。目标:把 Hermes Agent(Nous Research 开源的 AI 智能体)装到自己的 Windows 电脑上并跑通第一次对话。编写依据:官方安装文档 https://hermes-agent.nousresearch.com/docs/getting-started/installation、Windows 原生指南 /docs/user-guide/windows-native,以及 2026-11 实测的官方安装脚本 install.ps1 行为。Hermes 迭代较快,命令请以官方文档为最终依据;本指南的每条命令都做过可获得性核对。

Windows 系统安装(一键脚本)

安装步骤

Windows 安装非常简单,以管理员身份打开 PowerShell,执行以下一键安装命令:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

脚本会自动下载最新版本并完成安装,最好能连接外网,大概10多分钟能自动安装好。

但如果安装失败、安装卡顿,则看以下详细信息。

〇、先花 1 分钟判断:你该装哪一种

你的情况 推荐装法 说明
Windows 11(22H2 及以上) 桌面打包版(官网下载.appinstaller,双击安装) 自带 Python/Node/全部依赖,不需要编译,最省事
Windows 11 22H2 以上 + 想用命令行 源码脚本版(本指南主路线) 一条 PowerShell 命令,功能与桌面版同一个内核
Windows 10(任何版本) 源码脚本版(本指南主路线) 桌面打包版 MSIX 只支持 Win11 22H2+,Win10 用脚本版
想同时拥有桌面窗口和命令行 先脚本版,再hermes desktop或另装 MSIX 两种方式共用同一份配置数据

关键事实先说清楚,避免误会:

  • 不需要管理员权限。安装全部写在你的用户目录 %LOCALAPPDATA%\hermes\ 里,不动 C:\Windows,不加开机启动项。
  • 不需要装 WSL、不需要装 Docker、不需要自己装 Python。安装脚本会自己准备固定版本的 Python 3.14、Node、FFmpeg、ripgrep 等(走一个叫 PM 的内置依赖管理器)。
  • Git:本机没有 git 也没关系,脚本会下载一个固定版本的 Git for Windows;但本机已有 git 会更省时间。
  • 磁盘:建议 C 盘至少留 10 GB 空闲(Python 运行时 + 依赖 + 可选浏览器组件)。想装到 D 盘见「四、进阶」。
  • 网络:脚本要从 GitHub(源码)、PyPI(Python 依赖)、GitHub Releases(uv、Python 运行时、Chromium)下载东西。国内能连通但大文件容易慢、容易断——本指南第五节的失败处理就是为此准备的。

安装成功后你得到的东西:

%LOCALAPPDATA%\hermes\                ← 你的数据、配置、密钥、会话、技能、日志
%LOCALAPPDATA%\hermes\hermes-agent\   ← 程序源码本体
%LOCALAPPDATA%\hermes\bin\hermes.exe  ← 命令行入口(已自动加进"用户 PATH")

一、安装前的 5 件准备(每件 1 分钟)

  1. 打开 PowerShell。按键盘 Win 键 → 直接输入 powershell → 点「Windows PowerShell」(或 Win11 的「终端 / Terminal」)。不熟悉命令行也完全没问题:你只需要"复制 → 在窗口里右键粘贴(或按 Ctrl+V)→ 回车"。
  2. 要用新版终端窗口,不要用老 cmd。Win11 自带的「Windows 终端」最好;老 cmd.exe 显示中文会出现 ? 乱码。判断标准:窗口标题写着 Windows Terminal / PowerShell 即可。
  3. 临时缩小杀毒软件的干扰。第三方杀毒(360、火绒等)可能在解压可执行文件时锁文件,导致安装中途失败。如果后面出现"文件被占用/解压失败",请把 %LOCALAPPDATA%\hermes 加进杀软排除目录,或临时关闭实时防护再装。
  4. 记一个关键词:日志在哪。安装一旦出问题,先看这一个文件:

%LOCALAPPDATA%\hermes\logs\install.log

在文件资源管理器地址栏里粘贴这一行回车就能打开。

二、主路线:一键安装(命令行版)

第 1 步:给本次安装加上国内 PyPI 镜像(强烈建议,只影响当前窗口)

在 PowerShell 里整段粘贴回车:

$env:UV_INDEX_URL     = "https://pypi.tuna.tsinghua.edu.cn/simple"
$env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"
$env:UV_HTTP_TIMEOUT  = "120"

作用:让几百个 Python 依赖全部从清华镜像下载(国内 1–2 秒级的响应),而不是从国外 PyPI 一个一个拉。这是无代理环境下提速最有效的一步。

验证是否生效:

echo $env:UV_INDEX_URL

能打印出清华地址就对了。

第 2 步:执行一键安装

先给出最稳的那条(跳过两个最容易卡住的组件):

& ([scriptblock]::Create((irm https://hermes-agent.nousresearch.com/install.ps1))) -SkipBrowser -SkipComputerUse

为什么带这两个参数:

  • -SkipBrowser:不下载本地 Chromium(浏览器自动化用的,几十到上百 MB,国内经常拉不动)。
  • -SkipComputerUse:不装"操作你的鼠标键盘"的驱动 cua-driver。
  • 二者不影响日常能力:网页搜索与网页正文抓取用的是 Hermes 内置的 web 工具,不需要本地 Chromium。以后想要,随时补装(见第六节)。
  • 脚本会记住你跳过它们,之后的安装和 hermes update 不会自作主张加回来。

如果你就是个极简主义者,也可以只用官方最短那一行(不跳过任何组件,风险是更容易卡):

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

第 3 步:耐心看它跑,认识 9 个阶段

安装器会按下面的顺序逐段执行,每段给你一行状态提示。只要还在往下走新的一行,就是正常的:

阶段名 干什么 常见卡点
prerequisites 检查/补装固定版本 Git for Windows 杀软锁文件、磁盘满
repository 拉取 Hermes 源码(精简拉取,体积不大) GitHub 慢/断(国内最常见)
venv 准备固定版本 Python 3.14 运行时 Python 运行时下载慢
python-deps 安装全部 Python 依赖(走 uv) PyPI 慢(镜像能救)
config 创建配置目录、技能目录 目录被占用
products 生成hermes启动器(可选构建桌面 App) 磁盘满、杀软拦截
setup 配置模型/API Key(会问你问题) 不知道该填什么就先跳过
gateway 配置消息平台网关(会问你问题) 用不上就先跳过
complete 收尾、写完成标记 —

耗时预期:网络顺利 3–15 分钟;国内网络不设镜像、卡在 GitHub 时可能 30 分钟以上甚至失败——那就按第五节处理。

setup / gateway 两个阶段会问你要不要现在配置。完全不懂就全部回车跳过或输入 N,装完再单独配置更清楚(见第三节)。想彻底不被打断,可以加 -NonInteractive。

第 4 步:装完必须做的一件事——重开窗口

安装器把你的 %LOCALAPPDATA%\hermes\bin 写进了用户 PATH,但已经打开的窗口不会自动刷新。所以:把这个 PowerShell 窗口关掉,重新开一个。

第 5 步:三个验证命令

在新窗口里依次执行:

Get-Command hermes

期望输出类似 C:\Users\<你的用户名>\AppData\Local\hermes\bin\hermes.exe。

hermes --version

期望输出一行版本号。

hermes doctor

体检报告。绿/✓ 的项是好的;有 ✗ 或黄字,它会直接告诉你怎么补(照着做即可,不用懂原理)。

image-20261122081750190

三件事都过了,说明安装成功。失败了三步中的任何一步,直接跳第五节。

三、装完的第一次配置(5 分钟,比安装更重要)

Hermes 是一台"发动机",还需要告诉它用哪个大模型、用哪把钥匙。没有模型,hermes 启动后一问三不知。

路线 A:一条命令全搞定(如果你买了 Nous Portal 订阅)

hermes setup --portal

它会打开浏览器让你登录,登录完成后自动把"模型 + 联网搜索 + 生图 + 语音 + 云浏览器"一整套工具都接上,不用再逐个填 API Key。推荐给不想折腾的人。但要连接外网,按使用量收费。

路线 B:用你自己的模型 API(国内用户常用)

hermes model

image-20260627093237693

这是个交互向导,方向键选择 → 回车确认:

或者直接进行网关设置

image-20260627093426081

  1. 选厂商(Provider),模型提供商:支持 OpenAI、Anthropic、Groq、Ollama 本地模型等。国内直连可用的常见选择: * 火山方舟(Volcengine Ark):OpenAI 兼容,国内速度快,通常选 custom(自定义 OpenAI 兼容端点)后填 base URL; * DeepSeek:OpenAI 兼容,价格低; * 阿里百炼 / 智谱:同样走 custom 兼容端点; * OpenRouter:模型最全,但国内直连常不通,没有代理别选。

推荐选择 29 自定义模型(如果你有自己偏好的模型或 API),可以自由配置

根据需要选择连接微信或其他消息通道(Telegram、Discord 等)

配置完成后即可正常使用

image-20260621081237766

输入应数字 ,如29,选择29自定义模型

填 Base URL(例如火山方的编码端点 https://ark.cn-beijing.volces.com/api/coding/v3)、模型名、API Key。

向导会写入配置文件,你不用手改 YAML。

image-20260621081623898

连接微信设置

image-20260621081858845

设置完成

三条铁律(避免 90% 的"配错了")

  1. 密钥只放在 %LOCALAPPDATA%\hermes\.env,设置项放 config.yaml。 不要把密钥塞进 config.yaml,也不要贴到聊天窗口/群里/截图里。
  2. 不要用记事本直接改 config.yaml。 老记事本会存成"带 BOM 的 UTF-8",Hermes 读出来会报 400 No models provided。要改就用:

hermes config edit # 用系统编辑器安全打开并保存(不要用记事本另存为其他编码)

若确实要手动另存,务必选 UTF-8(不带 BOM)。带 BOM 的文件会直接导致上面那个 400 报错。 3. 单条设置用命令改,不要手抄:

hermes config get model.default hermes config set model.default ark-code-latest

第一次对话验证

hermes

启动使用

配置完成后,在终端输入:

hermes

看到启动成功的提示界面,就表示安装完成,可以开始使用你的 AI 助手了!

image-20260627093145570

进入对话界面后,先发一句:

你好,请报一下你当前使用的模型名称,并搜索一下今天的 AI 新闻

能报出模型名 → 模型通了;能给出带来源的搜索结果 → 联网也通了。两条都通,安装 + 配置就全部完成。

(多行输入技巧:Windows 上用 Ctrl+Enter 换行;Alt+Enter 会被终端抢走,无效。)

四、装完之后怎么用(不用背命令)

你想做的事 命令
进对话(默认界面) hermes
只问一句就走 hermes chat -q "帮我把这份 csv 转成表格"
打开图形桌面窗口 hermes desktop(从源码构建,较慢);Win11 22H2+ 更推荐官网 MSIX 包
打开网页版管理面板 hermes dashboard
换模型 / 换厂商 hermes model
管工具开关 hermes tools
升级到新版 hermes update
体检 hermes doctor
卸载 hermes uninstall(先看hermes uninstall --dry-run)
整机备份 / 迁移到新电脑 hermes backup/hermes import
数据/密钥/会话放哪 %LOCALAPPDATA%\hermes\(改位置用-HermesHome或环境变量HERMES_HOME)

想装到 D 盘(C 盘紧张时):安装时加参数指定数据目录与源码目录,例如

& ([scriptblock]::Create((irm https://hermes-agent.nousresearch.com/install.ps1))) -HermesHome "D:\Hermes" -InstallDir "D:\Hermes\hermes-agent" -SkipBrowser -SkipComputerUse

(-HermesHome 与 -InstallDir 不能互相嵌套,脚本会拒绝并说明原因。)

hermes dashboard效果如下

image-20261122083005010

图片内容是我的面板打开效果,可以看得到,目前Hermes已经掌握了我自己经常使用的200多个技能,大都是我在日常工作生活中使用智能体中它自主学习我的一些工作流程和记忆,成为新的skill技能。

五、一键安装失败了怎么办(本节是重点,请按顺序做)

5.1 第 0 步:先别急着重装,先取证

失败时安装器不会只说"失败",它会打印最后几行错误和日志路径。请做三件事:

# 1) 看日志最后 100 行(把它整段复制保存,后面对照表和求助都用得上)
Get-Content "$env:LOCALAPPDATA\hermes\logs\install.log" -Tail 100
# 2) 看"失败回执":里面直接写着失败的阶段名和失败类别
Get-ChildItem "$env:LOCALAPPDATA\hermes\telemetry\shared_metrics\pending_installs" |
  Sort-Object LastWriteTime -Descending | Select-Object -First 1 |
  Get-Content

它会输出类似 {"outcome":"failed","failed_stage":"repository","failure_class":"git_fetch_failed",...}。failed_stage 告诉你卡在哪一步,failure_class 告诉你属于哪类问题——照下面 5.3 的表对号入座。

# 3) 体检一次(有时失败只是某个组件缺了,hermes 已能用)
hermes doctor

5.2 第 1 步:把安装脚本下载到本地,改成"分段重试"

反复用 irm | iex 远程执行是最难排查的方式。把脚本存到本地,就能一段一段重跑,失败哪段修哪段,已成功的部分会复用,不用从头再来。

# 下载到本地
irm https://hermes-agent.nousresearch.com/install.ps1 -OutFile "$env:TEMP\install.ps1"

# 解除"来自网络的文件"限制(浏览器下载的脚本必须做这一步)
Unblock-File "$env:TEMP\install.ps1"

# 看看阶段清单(确认脚本能正常执行)
powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1" -Manifest

然后按需单跑某一段(这就是"断点续装"):

powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1" -Stage prerequisites
powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1" -Stage repository
powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1" -Stage venv
powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1" -Stage python-deps
powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1" -Stage config
powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1" -Stage products
powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1" -Stage complete

想让某段把细节都吐出来(排查卡在哪一行时用):

powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1" -Stage repository -Verbose

修好问题后,最后再完整跑一次(把跳过项和镜像一起带上):

$env:UV_INDEX_URL = "https://pypi.tuna.tsinghua.edu.cn/simple"
powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1" -SkipBrowser -SkipComputerUse

-Stage setup / -Stage gateway 需要交互输入;不想答题就用 -NonInteractive 跳过。

5.3 第 2 步:按失败阶段对号入座

A. repository ── 拉源码失败(国内 90% 的失败都在这)

现象:日志里 git clone failed / git fetch failed / 卡在 Download Hermes Agent 很久不动。

A-1 换下载通道(首选,改 repo 地址)

$env:HERMES_REPO_URL = "https://gh-proxy.com/https://github.com/NousResearch/hermes-agent.git"
powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1" -SkipBrowser -SkipComputerUse

HERMES_REPO_URL 被脚本正式支持(源码第 79 行读取),而且后续重跑也会一直用这个地址,不会偷偷换回 GitHub。gh-proxy.com 这类前缀站存活期短、地区差异大,不同前缀可轮流试:

  • https://gh-proxy.com/https://github.com/...
  • https://ghproxy.net/https://github.com/...
  • https://ghfast.top/https://github.com/...(2026-10 实测常不可用)

A-2 让另一台"已经装好"的电脑帮你(最省心,不需要代理)

在有网络的另一台电脑上完成安装后,把整个目录 %LOCALAPPDATA%\hermes\hermes-agent 完整拷贝(必须连同隐藏的 .git 目录一起,用 U 盘/移动硬盘),放到目标电脑同一位置,然后重跑安装脚本。脚本检测到合法 git 仓库就会复用,只补齐缺的部分。

⚠️ 只拷 GitHub 网页下载的 zip 包没用:脚本要求该目录是真正的 git 仓库(有 .git),否则会报... exists and is not a Hermes git checkout(dir_not_checkout)。要么用 git clone 得到,要么整目录连 .git 一起拷。

A-3 换网络:手机开热点给电脑,GitHub 走移动网络常常能过;或在代理窗口里设好 HTTP_PROXY/HTTPS_PROXY 后重跑(见第一节第 4 条)。

B. prerequisites ── Git 装不上 / 解压失败

现象:日志 pinned git self-extractor ... (usual causes: disk full, path-length limit, antivirus lock) 或 git.exe not found in the downloaded archive。

处理顺序:

  1. 清盘(C 盘至少 10 GB 空闲);
  2. 把 %LOCALAPPDATA%\hermes 加入杀软排除;
  3. 本机自己装 Git for Windows 也可以(脚本检测到能用的 git 就不再下载):到 https://git-scm.com/download/win 下载安装,安装时勾选"Git Bash"(Hermes 在 Windows 上是用 Git Bash 执行 shell 命令的,只装 MinGit 不行),然后重跑;
  4. 还失败就删掉半成品目录再试: Remove-Item "$env:LOCALAPPDATA\hermes\tools" -Recurse -Force -ErrorAction SilentlyContinue

C. venv ── Python 运行时下载失败

现象:日志 bootstrap Python installation failed / python_install_failed,或长时间停在 Create Python environment。

处理:

  1. 先在有代理的窗口里重跑(uv 会继承 HTTPS_PROXY);
  2. 中国大陆可让 uv 从代理前缀取 python-build-standalone(可选尝试,格式必须是整段前缀): $env:UV_PYTHON_INSTALL_MIRROR = "https://gh-proxy.com/https://github.com/indygreg/python-build-standalone/releases/download" powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1" -Stage venv
  3. 换时段重试(GitHub Releases 的可用性随时间波动很大,半夜/早晨常更好)。

D. python-deps ── 依赖装不上(大量 Retrying / timeout)

现象:满屏 Retrying、Read timed out、No matching distribution。

处理:

  1. 确认镜像真的生效(echo $env:UV_INDEX_URL 必须是清华地址,每个新窗口都要重设一遍);
  2. 备选镜像: $env:UV_INDEX_URL = "https://mirrors.aliyun.com/pypi/simple"
  3. 再加超时放宽,然后只重跑这一段: $env:UV_HTTP_TIMEOUT = "180" powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1" -Stage python-deps -Verbose
  4. 如果报的是编译错误(error: Microsoft Visual C++ 14.0 or greater is required),安装微软的 C++ 生成工具(Visual Studio Build Tools,勾选"使用 C++ 的桌面开发"),再重跑。

E. 卡在浏览器 / 电脑操作驱动(Chromium、cua-driver)

现象:跑到最后一步不动,或 agent-browser / cua-driver 下载失败。

处理:直接跳过,不影响主功能:

powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1" -SkipBrowser -SkipComputerUse

以后网络好了再补(这就是"补装"的正规做法,不要手改文件):

hermes pm install chromium
hermes pm install cua-driver

F. products ── 生成启动器 / 构建桌面 App 失败

现象:app products or command publication failed / launcher staging failed / products_build_failed。

处理:

  1. 不要用 -IncludeDesktop(那会从源码构建 Electron,对国内网络和非专业人士都不友好)。想要桌面窗口,Win11 22H2+ 直接装官网 MSIX 包(见 5.4)。
  2. 关杀软再重跑这一段:-Stage products。
  3. 确认 %LOCALAPPDATA%\hermes\bin 没被别的程序占用(关掉所有 hermes 窗口/进程后重试)。

G. 脚本本身跑不起来(PowerShell 层)

现象 原因 处理
irm : 无法连接/超时 连不上hermes-agent.nousresearch.com 用浏览器手动下载https://hermes-agent.nousresearch.com/install.ps1,存到%TEMP%\install.ps1,再powershell -ExecutionPolicy Bypass -File ...
无法加载文件 ... 因为在此系统上禁止运行脚本 执行策略限制 用powershell -ExecutionPolicy Bypass -File方式执行(上面每条命令都是这个写法)
The assignment expression is not valid 脚本被存成了带 BOM 的 UTF-8 说明用了[scriptblock]::Create的写法但下载带了 BOM。改用「下载到本地 +-File执行」的方式,或用简单写法iex (irm ...)
未知参数 -SkipBrowser之类 参数拼在iex (irm ...)后面了 iex那条不能带参数;要带参数必须用& ([scriptblock]::Create((irm ...))) -SkipBrowser,或本地脚本-File方式
路径奇怪 / 明明是 C 盘却报路径不存在 Windows 8.3 短路径别名 先诊断:powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1" -ShowResolvedPaths(打印它实际要用的路径,不做任何修改)
想指定 D 盘 — -HermesHome "D:\Hermes" -InstallDir "D:\Hermes\hermes-agent",两者不能嵌套

H. 其他

  • 磁盘满:download_digest_mismatch 有时是下载被中途截断(磁盘/断网),先清盘再重试。
  • 公司/学校网络有防火墙专杀 exe 下载:把热点方案(A-3)或 MSIX 方案(5.4)当主线。
  • 实在查不出来:按第八节的模板把信息发出来,别自己删目录瞎试。

5.4 两条保底路线(源码脚本彻底装不上时)

保底一:桌面打包版(Win11 22H2 及以上)

  1. 浏览器打开 https://hermes-agent.nousresearch.com/;
  2. 下载 Windows 的 .appinstaller;
  3. 双击,用系统自带「应用安装程序 (App Installer)」打开,按提示装;
  4. 这个包自带 Python、Node、依赖和界面,不需要 git clone、不需要编译、不需要管理员权限;下载只是一个大文件,比 clone 上千个小文件稳得多;
  5. 装完在开始菜单找 Hermes 图标;数据同样在 %LOCALAPPDATA%\hermes\,与命令行版共享。

Windows 10 用不了这条路(MSIX 需要 Win11 22H2+),请走保底二或热点重试。

保底二:WSL2 里装(Linux 方式)

wsl --install -d Ubuntu

重启 → 首次进入 Ubuntu 设用户名密码 → 在 Ubuntu 里执行:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser --skip-computer-use

WSL2 的数据在 ~/.hermes,与 Windows 原生那份互不干扰(可以两个都留着)。

用 WSL 的代价:Hermes 操作的是 Ubuntu 文件系统,访问 Windows 的 D 盘要写 /mnt/d/...。非专业用户只在"原生实在装不上"时才用这条。

5.5 想彻底重来时的正确姿势

先别删 %LOCALAPPDATA%\hermes 整个目录! 那里面装着你的会话、密钥、技能、日志。删了它 = 把数据和配置一起扔了。正确做法:

hermes uninstall --dry-run     # 先看它会删什么(只看不动)
hermes uninstall               # 卸载程序本体,保留数据

只想重装程序本体(配置不受影响):

Remove-Item "$env:LOCALAPPDATA\hermes\hermes-agent" -Recurse -Force

然后再重跑安装脚本。安装器也会自己处理"上次克隆留下的坏仓库"(会把损坏目录改名成 .broken-时间戳 备份,不会直接删)。

六、装好之后常见的 6 个小毛病

现象 原因 处理
新窗口里hermes提示"不是内部或外部命令" PATH 没刷新或被别的程序覆盖 关掉所有终端重开;临时可用& "$env:LOCALAPPDATA\hermes\bin\hermes.exe";再用Get-Command hermes -All看是否有多个来源
中文显示成? 用了老cmd.exe,UTF-8 不了 换 Windows 终端 / PowerShell;确认没有设置HERMES_DISABLE_WINDOWS_UTF8=1
首次对话报400 No models provided config.yaml被存成了带 BOM 的 UTF-8 hermes config edit重开保存;或hermes config check后hermes config migrate
模型报 401 / 403 / 超时 Key 错、余额不足、base_url 或模型名不对 核对.env/config.yaml;到厂商控制台确认额度与模型名拼写
搜索/抓网页没结果 搜索后端没配 hermes tools或hermes config set web.search_backend tavily,并在.env放对应 Key
浏览器工具能用但一直超时 首次启动 Chromium 慢 hermes doctor、hermes pm doctor;hermes config set browser.command_timeout 60
想让网关在登录 Windows 后自动跑 — hermes gateway install;查状态hermes gateway status;排障schtasks /Query /TN Hermes_Gateway /V /FO LIST(不需要管理员权限,用的是计划任务)
升级后配置字段缺失 版本跨代升级 hermes config check然后hermes config migrate

七、速查:完整命令一次复制(新机器用这一段)

# ── 1)(可选)代理:地址换成你自己的
# $env:HTTP_PROXY = "http://192.170.3.4:7890"; $env:HTTPS_PROXY = $env:HTTP_PROXY

# ── 2) 国内 PyPI 镜像 + 超时放宽(只影响当前窗口)
$env:UV_INDEX_URL     = "https://pypi.tuna.tsinghua.edu.cn/simple"
$env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"
$env:UV_HTTP_TIMEOUT  = "120"

# ── 3) 一键安装(跳过最易卡的两个组件)
& ([scriptblock]::Create((irm https://hermes-agent.nousresearch.com/install.ps1))) -SkipBrowser -SkipComputerUse

# ── 4) 关掉本窗口,重新打开一个 PowerShell,然后验证
Get-Command hermes
hermes --version
hermes doctor

# ── 5) 配置模型(二选一)
# hermes setup --portal     # 有 Nous Portal 订阅
# hermes model              # 用自己的 API(火山方舟/DeepSeek/百炼…)

# ── 6) 开始使用
hermes

失败时的"应急三连":

Get-Content "$env:LOCALAPPDATA\hermes\logs\install.log" -Tail 100
Get-ChildItem "$env:LOCALAPPDATA\hermes\telemetry\shared_metrics\pending_installs" | Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Get-Content
irm https://hermes-agent.nousresearch.com/install.ps1 -OutFile "$env:TEMP\install.ps1"; Unblock-File "$env:TEMP\install.ps1"

八、求助模板(把这几样发出去,别人 3 分钟能判断原因)

  1. hermes --version 或"命令找不到"的原话;
  2. %LOCALAPPDATA%\hermes\telemetry\shared_metrics\pending_installs\ 里最新那个 .json(含 failed_stage / failure_class);
  3. logs\install.log 的最后 100 行;
  4. hermes doctor 的完整输出;
  5. 三句背景:Windows 版本(Win10/Win11,在"设置 → 系统 → 关于"里看)、有没有用代理、失败时卡在哪一行(截图也行)。

⚠️ 发之前务必检查:日志和 .json 里可能包含你的用户名、路径;.env 里的 API Key 绝对不要发出去。

附:一句话原理(懂了就不慌)

Hermes 的 Windows 安装器本质是 9 个可单独重跑的步骤:补 git → 拉源码 → 备 Python → 装依赖 → 建配置目录 → 生成启动器 →(可选)配模型、(可选)配网关 → 收尾。每一步的产物都会留在磁盘上,所以任何一步失败,你都可以只重跑那一步,不需要从头再来;把所有日志写在同一个文件里,就是为了让你能定位到那一步。

文档结束。记住三件事:数据在 %LOCALAPPDATA%\hermes\、命令叫 hermes、出问题先看 logs\install.log 和 pending_installs 里的回执。

相关课程

这篇笔记涉及的主题,我录过对应的视频课程: