Windows 安装 Hermes Agent 完整指南：从报错到成功运行的全过程

Hermes Agent 是由 Nous Research 开源的 AI 智能体框架，支持接入 OpenAI、Anthropic、Ollama 等多种推理后端。但对于国内用户来说，安装过程经常卡在网络访问、脚本权限、浏览器下载等环节。

这篇文章完整记录了在 Windows 系统上安装 Hermes Agent 的全过程，包括每一个报错的原因和对应的解决办法。如果你已经踩过某个坑，可以直接跳到对应章节。

安装前需要准备什么

在开始之前，确认你的电脑已经装好以下工具。安装脚本会自动检测，缺什么它会告诉你。

依赖项	用途	版本要求
Python	运行 Agent 核心逻辑	3.11.x
Git	克隆仓库和后续更新	任意版本
Node.js	浏览器自动化工具依赖	建议 v18 以上
ripgrep	文件快速搜索	任意版本
ffmpeg	语音消息（TTS）功能	任意版本
uv	Python 虚拟环境管理	自动安装

安装脚本检测成功后会看到这样的输出：

[OK] Python found: Python 3.11.15
[OK] Git found (git version 2.54.0.windows.1)
[OK] Node.js v22.23.1 found
[OK] ripgrep 15.1.0 found
[OK] ffmpeg found

第一步：运行官方安装脚本

打开 PowerShell，运行以下命令：

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

脚本会自动完成依赖检测、仓库克隆、虚拟环境创建和 Python 包安装。顺利的话，整个过程大约需要 3 到 5 分钟。

常见问题一：GitHub 无法访问，克隆失败

这是国内用户最常遇到的问题。安装日志会出现：

fatal: unable to access 'https://github.com/NousResearch/hermes-agent.git/':
Failed to connect to github.com port 443 after 21079 ms: Could not connect to server
[X] Installation failed: git fetch failed (exit 128)

原因： 脚本需要从 GitHub 克隆仓库，国内直连 GitHub 经常超时或失败。

解决方法：

安装脚本在 SSH 和 HTTPS 都失败后，会自动改用 ZIP 下载方式，你会看到：

[!] Git clone failed -- downloading ZIP archive instead...
[OK] Downloaded and extracted

这是正常的降级处理，不影响安装结果。如果脚本没有自动降级，说明连 ZIP 下载也失败了，这时需要先开启网络代理，再重新运行脚本。

常见问题二：目录变成 .broken 文件夹

安装后你会发现目录里出现很多这样的文件夹：

hermes-agent.broken-20260626-165435
hermes-agent.broken-20260626-170027
hermes-agent.broken-20260626-171749

原因： 每次重新运行安装脚本时，脚本发现 hermes-agent 目录存在但不是有效的 git 仓库（因为上次安装失败或使用了 ZIP 方式），就会自动把它重命名为 .broken-时间戳 备份，然后重新开始。运行了几次安装脚本，就会产生几个 broken 文件夹。

这些文件夹可以直接删除：

Get-ChildItem "C:\Users\你的用户名\AppData\Local\hermes" -Filter "*.broken-*" | Remove-Item -Recurse -Force

常见问题三：PowerShell 脚本执行策略报错

激活虚拟环境时可能出现：

.\venv\Scripts\activate : 无法加载文件...因为在此系统上禁止运行脚本。

同样地，使用 npm 命令时也可能出现：

npm : 无法加载文件 C:\nvm4w\nodejs\npm.ps1，因为在此系统上禁止运行脚本。

原因： Windows 默认禁止执行 .ps1 脚本文件，这是系统的安全策略。

解决方法一：改用 .bat 或 .cmd 版本（推荐，无需修改系统设置）

# 激活虚拟环境用 .bat 版本
.\venv\Scripts\activate.bat

# npm 用 .cmd 版本
npm.cmd install
npm.cmd config set registry https://registry.npmmirror.com

解决方法二：修改当前用户的执行策略

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned -Force

执行后再运行 .\venv\Scripts\activate 即可，不需要重启。

常见问题四：Node.js 依赖安装卡住或失败

运行 npm install 时可能遇到两类问题。

问题 4a：Electron 下载失败（ECONNRESET）

npm error command failed
npm error command C:\Windows\system32\cmd.exe /d /s /c node install.js
npm error RequestError: read ECONNRESET

原因： Electron 的安装包需要从 GitHub Releases 下载，体积在 100MB 以上，国内直连容易断连。

解决方法：设置 Electron 国内镜像

$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
npm.cmd install

问题 4b：EPERM 权限错误

npm warn cleanup [Error: EPERM: operation not permitted, rmdir ...]

原因： 上次安装中断后，有些目录被系统锁定。

解决方法：

关闭杀毒软件的实时防护（Windows Defender 也算），然后以管理员身份打开命令提示符，重新安装：

Remove-Item -Recurse -Force node_modules -ErrorAction SilentlyContinue
npm.cmd install

常见问题五：Playwright Chromium 下载慢或 404

安装过程会下载 Playwright 的 Chrome 浏览器，用于网页自动化功能：

Downloading Chrome for Testing 149.0.7827.55 from https://cdn.playwright.dev/...
|                                            |   0% of 183.6 MiB

这个文件有 183MB，从境外 CDN 下载速度通常很慢。

切换到 npmmirror 镜像可能遇到 404：

Error: Download failed: server returned code 404
<Code>NoSuchKey</Code>

原因： Playwright v1228 是较新版本，国内镜像尚未同步这个版本的文件。

解决方法：跳过浏览器下载，先把 Agent 核心功能跑起来

$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD="1"
npm.cmd install

说明： Playwright 浏览器（Chromium）是 Hermes Agent 的可选附加功能，用于网页截图、自动操作等场景。如果你主要用 Agent 做文本对话、代码生成等任务，完全可以先跳过，之后再按需安装。

第二步：配置 API Key

安装完成后，需要告诉 Hermes Agent 使用哪个 AI 推理服务。

cd C:\Users\你的用户名\AppData\Local\hermes\hermes-agent
.\venv\Scripts\activate.bat
hermes setup model

运行后会进入交互式配置界面，用方向键选择你的推理提供商：

◆ Inference Provider
  Choose how to connect to your main chat model.

  > Anthropic
    OpenAI
    OpenRouter
    Ollama
    ...

如何选择推理提供商：

提供商	适合场景	需要什么
Anthropic	使用 Claude 系列模型	Anthropic API Key
OpenAI	使用 GPT 系列模型	OpenAI API Key
OpenRouter	接入多种模型，支持按需付费	OpenRouter API Key
Ollama	本地运行开源模型，不产生费用	本地安装 Ollama

选择后，根据提示输入对应的 API Key 即可。

第三步：启动 Hermes Agent

配置完成后，以后每次启动只需要两行命令：

cd C:\Users\你的用户名\AppData\Local\hermes\hermes-agent
.\venv\Scripts\activate.bat && hermes

建议：创建一个桌面快捷方式

新建一个文本文件，改名为 启动Hermes.bat，内容如下：

@echo off
cd /d C:\Users\你的用户名\AppData\Local\hermes\hermes-agent
call .\venv\Scripts\activate.bat
hermes
pause

把文件名里的「你的用户名」替换成实际的 Windows 用户名（可以在 C:\Users\ 目录下查看）。双击这个文件就能直接启动 Agent，不需要每次手动输入命令。

安装流程总览

运行安装脚本
    │
    ├─ GitHub 无法访问 → 脚本自动改用 ZIP 下载 → 正常继续
    │
    ├─ npm install 卡住
    │       ├─ Electron 下载失败 → 设置 ELECTRON_MIRROR 镜像
    │       └─ Playwright 404 → 设置 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
    │
    ├─ PowerShell 脚本禁止运行 → 改用 .bat / .cmd 后缀版本
    │
    └─ 安装成功
            │
            ├─ hermes setup model（配置 API Key）
            └─ hermes（启动 Agent）

常见问题解答

Q：安装脚本可以重复运行吗？

可以，但每次运行时如果检测到现有目录不是有效的 git 仓库，就会把旧目录重命名备份，重新安装。建议安装成功后不要再重复运行脚本，否则会产生很多 .broken 备份文件夹。

Q：broken 文件夹里有什么？可以删吗？

里面是之前安装失败的残留文件，没有使用价值，可以直接删除。

Q：跳过 Playwright 浏览器安装后，哪些功能会缺失？

主要影响需要控制浏览器的功能，比如自动打开网页、截图、填写表单等。文本对话、代码执行、文件操作等核心功能不受影响。

Q：安装完成后提示 hermes 命令找不到怎么办？

确认虚拟环境已激活（命令行前有 (venv) 字样），然后尝试：

python -m hermes

如果仍然找不到，检查安装是否完整：

pip show hermes-agent

Q：每次启动都要输入两行命令，有没有更简单的方式？

使用前面提到的 .bat 批处理文件，双击即可启动。也可以把这个 .bat 文件放入 Windows 启动项，实现开机自动启动。

Q：支持哪些本地模型？

选择 Ollama 作为提供商后，支持 Ollama 能运行的所有开源模型，包括 Llama、Mistral、Qwen、Gemma 等。本地运行不消耗 API 费用，但需要有足够的显存或内存。

Q：国内可以正常使用 Anthropic 和 OpenAI 的 API 吗？

API 调用和网页访问不同，很多情况下可以通过代理正常使用。具体取决于你的网络环境，建议在配置代理后测试 API 连通性。

小结

Hermes Agent 的核心安装步骤并不复杂，大部分卡点都是网络问题引起的。整理一下关键结论：

GitHub 连不上：脚本会自动用 ZIP 方式下载，不用手动处理
PowerShell 脚本禁止运行：改用 .bat 或 .cmd 后缀的同名命令
npm 下载慢或失败：设置 ELECTRON_MIRROR 镜像，Playwright 用跳过方式处理
安装成功后：激活虚拟环境，运行 hermes 即可使用

安装过程中产生的 .broken 文件夹都是无用备份，清理掉即可。核心功能和浏览器自动化功能可以分开安装，优先把 Agent 主体跑通，再按需补充其他功能。

Windows安装Hermes Agent踩坑实录：从GitHub报错到成功运行的完整解决方案