Windows 上安装 Hermes Agent 详细指南(2026 版,含一键安装失败处理)
适用对象:使用 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 分钟)
- 打开 PowerShell。按键盘
Win键 → 直接输入powershell→ 点「Windows PowerShell」(或 Win11 的「终端 / Terminal」)。不熟悉命令行也完全没问题:你只需要"复制 → 在窗口里右键粘贴(或按 Ctrl+V)→ 回车"。 - 要用新版终端窗口,不要用老 cmd。Win11 自带的「Windows 终端」最好;老
cmd.exe显示中文会出现?乱码。判断标准:窗口标题写着 Windows Terminal / PowerShell 即可。 - 临时缩小杀毒软件的干扰。第三方杀毒(360、火绒等)可能在解压可执行文件时锁文件,导致安装中途失败。如果后面出现"文件被占用/解压失败",请把
%LOCALAPPDATA%\hermes加进杀软排除目录,或临时关闭实时防护再装。 - 记一个关键词:日志在哪。安装一旦出问题,先看这一个文件:
%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
体检报告。绿/✓ 的项是好的;有 ✗ 或黄字,它会直接告诉你怎么补(照着做即可,不用懂原理)。

三件事都过了,说明安装成功。失败了三步中的任何一步,直接跳第五节。
三、装完的第一次配置(5 分钟,比安装更重要)
Hermes 是一台"发动机",还需要告诉它用哪个大模型、用哪把钥匙。没有模型,hermes 启动后一问三不知。
路线 A:一条命令全搞定(如果你买了 Nous Portal 订阅)
hermes setup --portal
它会打开浏览器让你登录,登录完成后自动把"模型 + 联网搜索 + 生图 + 语音 + 云浏览器"一整套工具都接上,不用再逐个填 API Key。推荐给不想折腾的人。但要连接外网,按使用量收费。
路线 B:用你自己的模型 API(国内用户常用)
hermes model

这是个交互向导,方向键选择 → 回车确认:
或者直接进行网关设置

- 选厂商(Provider),模型提供商:支持 OpenAI、Anthropic、Groq、Ollama 本地模型等。国内直连可用的常见选择:
* 火山方舟(Volcengine Ark):OpenAI 兼容,国内速度快,通常选
custom(自定义 OpenAI 兼容端点)后填 base URL; * DeepSeek:OpenAI 兼容,价格低; * 阿里百炼 / 智谱:同样走custom兼容端点; * OpenRouter:模型最全,但国内直连常不通,没有代理别选。
推荐选择 29 自定义模型(如果你有自己偏好的模型或 API),可以自由配置
根据需要选择连接微信或其他消息通道(Telegram、Discord 等)
配置完成后即可正常使用

输入应数字 ,如29,选择29自定义模型
填 Base URL(例如火山方的编码端点 https://ark.cn-beijing.volces.com/api/coding/v3)、模型名、API Key。
向导会写入配置文件,你不用手改 YAML。

连接微信设置

设置完成
三条铁律(避免 90% 的"配错了")
- 密钥只放在
%LOCALAPPDATA%\hermes\.env,设置项放config.yaml。 不要把密钥塞进 config.yaml,也不要贴到聊天窗口/群里/截图里。 - 不要用记事本直接改
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 助手了!

进入对话界面后,先发一句:
你好,请报一下你当前使用的模型名称,并搜索一下今天的 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效果如下

图片内容是我的面板打开效果,可以看得到,目前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。
处理顺序:
- 清盘(C 盘至少 10 GB 空闲);
- 把
%LOCALAPPDATA%\hermes加入杀软排除; - 本机自己装 Git for Windows 也可以(脚本检测到能用的 git 就不再下载):到
https://git-scm.com/download/win下载安装,安装时勾选"Git Bash"(Hermes 在 Windows 上是用 Git Bash 执行 shell 命令的,只装 MinGit 不行),然后重跑; - 还失败就删掉半成品目录再试:
Remove-Item "$env:LOCALAPPDATA\hermes\tools" -Recurse -Force -ErrorAction SilentlyContinue
C. venv ── Python 运行时下载失败
现象:日志 bootstrap Python installation failed / python_install_failed,或长时间停在 Create Python environment。
处理:
- 先在有代理的窗口里重跑(uv 会继承
HTTPS_PROXY); - 中国大陆可让 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 - 换时段重试(GitHub Releases 的可用性随时间波动很大,半夜/早晨常更好)。
D. python-deps ── 依赖装不上(大量 Retrying / timeout)
现象:满屏 Retrying、Read timed out、No matching distribution。
处理:
- 确认镜像真的生效(
echo $env:UV_INDEX_URL必须是清华地址,每个新窗口都要重设一遍); - 备选镜像:
$env:UV_INDEX_URL = "https://mirrors.aliyun.com/pypi/simple" - 再加超时放宽,然后只重跑这一段:
$env:UV_HTTP_TIMEOUT = "180" powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1" -Stage python-deps -Verbose - 如果报的是编译错误(
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。
处理:
- 不要用
-IncludeDesktop(那会从源码构建 Electron,对国内网络和非专业人士都不友好)。想要桌面窗口,Win11 22H2+ 直接装官网 MSIX 包(见 5.4)。 - 关杀软再重跑这一段:
-Stage products。 - 确认
%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 及以上)
- 浏览器打开 https://hermes-agent.nousresearch.com/;
- 下载 Windows 的
.appinstaller; - 双击,用系统自带「应用安装程序 (App Installer)」打开,按提示装;
- 这个包自带 Python、Node、依赖和界面,不需要 git clone、不需要编译、不需要管理员权限;下载只是一个大文件,比 clone 上千个小文件稳得多;
- 装完在开始菜单找 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 分钟能判断原因)
hermes --version或"命令找不到"的原话;%LOCALAPPDATA%\hermes\telemetry\shared_metrics\pending_installs\里最新那个.json(含failed_stage/failure_class);logs\install.log的最后 100 行;hermes doctor的完整输出;- 三句背景:Windows 版本(Win10/Win11,在"设置 → 系统 → 关于"里看)、有没有用代理、失败时卡在哪一行(截图也行)。
⚠️ 发之前务必检查:日志和 .json 里可能包含你的用户名、路径;.env 里的 API Key 绝对不要发出去。
附:一句话原理(懂了就不慌)
Hermes 的 Windows 安装器本质是 9 个可单独重跑的步骤:补 git → 拉源码 → 备 Python → 装依赖 → 建配置目录 → 生成启动器 →(可选)配模型、(可选)配网关 → 收尾。每一步的产物都会留在磁盘上,所以任何一步失败,你都可以只重跑那一步,不需要从头再来;把所有日志写在同一个文件里,就是为了让你能定位到那一步。
文档结束。记住三件事:数据在 %LOCALAPPDATA%\hermes\、命令叫 hermes、出问题先看 logs\install.log 和 pending_installs 里的回执。
相关课程
这篇笔记涉及的主题,我录过对应的视频课程:
- MCP 协议实战:给大模型装上手和眼 10 讲