目录

2026 年最新：Windows 原生安装 Hermes Agent 完整手册（告别 WSL2）

前言

为什么选择原生 Windows 而不是 WSL2？

系统要求

方法一：官方一键安装（最简单）

步骤 1：以管理员身份打开 PowerShell

步骤 2：执行官方安装命令

步骤 3：等待安装完成

步骤 4：重启终端

方法二：社区增强版一键安装（推荐）

步骤 1：以管理员身份打开 PowerShell

步骤 2：执行社区增强版安装命令

步骤 3：按照提示操作

方法三：手动安装（适合开发者）

步骤 1：安装前置依赖

步骤 2：克隆仓库

步骤 3：创建虚拟环境并安装依赖

步骤 4：设置全局命令

配置向导

验证安装是否成功

常见问题与解决方案

问题 1：运行hermes gateway时出现OSError: [WinError 87] The parameter is incorrect

问题 2：启动时出现UnicodeEncodeError: 'charmap' codec can't encode character

问题 3：代码执行功能无法正常工作

问题 4：hermes命令找不到

性能优化技巧

1. 启用本地模型 GPU 加速

2. 增加虚拟内存

3. 关闭不必要的功能

总结与展望

写在最后

---

前言

好消息！截至 2026 年 4 月，Hermes Agent 终于支持 Windows 原生运行了！

在过去的两个月里，这个 GitHub 上增长最快的 AI 智能体框架（已突破 10 万星标）一直只能通过 WSL2 或 Docker 在 Windows 上运行，这让很多不想折腾 Linux 环境的用户望而却步。

但就在最近几周，官方团队合并了大量 Windows 适配 PR，现在你可以直接在 PowerShell 里一键安装，不需要 WSL2，不需要虚拟机，不需要 Docker，真正实现了 "开箱即用"。

这篇手册将带你从零开始，在 Windows 上原生部署 Hermes Agent，同时解决所有你可能遇到的坑。

为什么选择原生 Windows 而不是 WSL2？

很多人会问：官方不是还推荐 WSL2 吗？为什么要冒险用原生？

维度	原生 PowerShell 部署	WSL2（Ubuntu）部署
安装速度	⚡ 5 分钟搞定	15-30 分钟（含 WSL2 配置）
文件系统访问	原生 Windows 路径，无缝访问所有文件	通过/mnt/c/访问，I/O 性能损失 30-50%
浏览器自动化	直接调用 Windows Chrome/Edge	需要额外配置，经常出现权限问题
本地模型支持	完美支持 Ollama/LM Studio	支持但 GPU 加速配置复杂
系统资源占用	更低	额外占用 2-4GB 内存运行 Linux 内核
稳定性	良好（90%+ 功能正常）	极佳（官方唯一推荐）
适合人群	新手、快速体验者、非开发者	开发者、长期使用者、追求极致稳定性

我的建议：如果你只是想快速体验 Hermes 的强大功能，或者主要用它来处理 Windows 上的文件和任务，原生部署绝对是更好的选择。如果你是开发者，需要集成 GitHub、MCP 或者跑非常复杂的自动化任务，那还是推荐 WSL2。

系统要求

• 操作系统：Windows 10 2004 及以上版本，Windows 11 22H2 + 推荐
• 内存：最低 8GB，推荐 16GB 及以上（跑本地大模型需要 32GB+）
• 存储：至少 20GB 空闲空间
• 其他：
  • 开启 CPU 虚拟化（BIOS 中设置，大部分电脑默认已开启）
  • 安装 Git for Windows（必须，Hermes 内部依赖 Git Bash 执行 shell 命令）
  • 稳定的网络连接（首次安装需要下载依赖）

检查虚拟化是否开启：

1. 打开任务管理器（Ctrl+Shift+Esc）
2. 切换到 "性能" 标签页
3. 点击 "CPU"，看右下角是否显示 "虚拟化：已启用"

方法一：官方一键安装（最简单）

这是官方最新提供的原生 Windows 安装方法，推荐大多数用户使用。

步骤 1：以管理员身份打开 PowerShell

右键点击 Windows 开始菜单 → 选择 "终端 (管理员)" 或 "Windows PowerShell (管理员)"

步骤 2：执行官方安装命令

复制粘贴以下命令并回车：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.cmd -o install.cmd && install.cmd && del install.cmd

步骤 3：等待安装完成

安装脚本会自动完成以下操作：

1. 安装 uv（超快的 Python 包管理器）
2. 安装 Python 3.11（如果系统没有）
3. 克隆 Hermes Agent 仓库到~/.hermes/hermes-agent
4. 创建虚拟环境并安装所有依赖
5. 设置全局hermes命令
6. 启动交互式配置向导

步骤 4：重启终端

安装完成后，必须关闭并重新打开 PowerShell，否则hermes命令不会生效。

方法二：社区增强版一键安装（推荐）

官方脚本虽然简单，但还有一些小问题没有解决。社区开发者 HoriLiu 制作了一个增强版安装脚本，修复了大部分已知的 Windows 兼容性问题，强烈推荐使用这个版本。

步骤 1：以管理员身份打开 PowerShell

步骤 2：执行社区增强版安装命令

irm https://gist.githubusercontent.com/HoriLiu/e95d48009cf0d76e8f52a9009c0a79c4/raw/install-hermes-windows.ps1 | iex

步骤 3：按照提示操作

这个脚本会：

• 自动检测并安装 Git for Windows（如果没有）
• 配置 Windows 终端为 UTF-8 编码（解决中文乱码问题）
• 应用所有已知的 Windows 兼容性补丁
• 安装完成后自动验证安装是否成功

方法三：手动安装（适合开发者）

如果你想了解安装过程或者需要自定义配置，可以选择手动安装。

步骤 1：安装前置依赖

# 安装Git for Windows（如果没有）
winget install Git.Git

# 安装uv
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

步骤 2：克隆仓库

git clone --recursive https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

步骤 3：创建虚拟环境并安装依赖

uv venv
.venv\Scripts\activate.ps1
uv pip install -e .

步骤 4：设置全局命令

# 将hermes命令添加到PATH
$env:PATH += ";$pwd\.venv\Scripts"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")

配置向导

安装完成后，运行以下命令启动配置向导：

hermes setup

向导会引导你配置：

1. AI 模型提供商：支持 OpenAI、Anthropic、OpenRouter、Ollama（本地模型）等
2. API 密钥：输入你选择的提供商的 API 密钥
3. 默认模型：选择你想使用的模型
4. 可选功能：是否启用浏览器自动化、代码执行等

推荐配置：

• 新手：OpenRouter（支持所有主流模型，免费额度足够体验）
• 追求隐私：Ollama + Llama 3 8B（完全本地运行）
• 最佳效果：Anthropic Claude 3.5 Sonnet

验证安装是否成功

运行以下命令启动 Hermes：

hermes

如果看到 Hermes 的欢迎界面，说明安装成功！你现在可以开始和它聊天了。

常见问题与解决方案

这是目前 Windows 原生版本最常见的问题，我都帮你整理好了解决方案。

问题 1：运行hermes gateway时出现OSError: [WinError 87] The parameter is incorrect

原因：这是最常见的问题，由os.kill(pid, 0)这个 Linux/macOS 特有的函数引起。

解决方案：

1. 打开文件%USERPROFILE%\.hermes\hermes-agent\hermes_cli\gateway\status.py
2. 找到所有os.kill(pid, 0)的调用
3. 将它们替换为以下代码：

try:
    os.kill(pid, 0)
except (ProcessLookupError, PermissionError, OSError, SystemError):
    # PID不存在或没有权限访问
    return False

或者直接使用社区增强版安装脚本，它已经自动修复了这个问题。

问题 2：启动时出现UnicodeEncodeError: 'charmap' codec can't encode character

原因：Windows 终端默认使用 cp1252 编码，无法显示 Hermes 界面中的 Unicode 字符。

解决方案：

1. 以管理员身份打开 PowerShell
2. 运行以下命令：

# 设置系统默认编码为UTF-8
reg add "HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage" /v ACP /t REG_SZ /d 65001 /f
reg add "HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage" /v OEMCP /t REG_SZ /d 65001 /f

1. 重启电脑

或者在每次运行 Hermes 前先执行：

$env:PYTHONIOENCODING="utf-8"

问题 3：代码执行功能无法正常工作

原因：Hermes 默认使用 bash 执行命令，Windows 上需要 Git Bash。

解决方案：

1. 确保已经安装了 Git for Windows
2. 将 Git Bash 的 bin 目录添加到系统 PATH：

   $env:PATH += ";C:\Program Files\Git\bin"
   [Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")
   

3. 重启终端

问题 4：hermes命令找不到

原因：安装脚本没有正确将命令添加到 PATH。

解决方案：

1. 手动添加路径到系统环境变量：

   $hermesPath = "$env:USERPROFILE\.hermes\hermes-agent\.venv\Scripts"
   $env:PATH += ";$hermesPath"
   [Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")
   

2. 重启终端

性能优化技巧

1. 启用本地模型 GPU 加速

如果你有 NVIDIA 显卡，可以安装 Ollama 并启用 GPU 加速：

winget install Ollama.Ollama
ollama run llama3:8b

然后在 Hermes 中配置使用 Ollama：

hermes model set ollama/llama3:8b

2. 增加虚拟内存

如果运行大模型时出现内存不足，可以增加 Windows 虚拟内存：

1. 右键 "此电脑" → "属性" → "高级系统设置"
2. "高级" 标签页 → "性能" → "设置"
3. "高级" 标签页 → "虚拟内存" → "更改"
4. 将虚拟内存大小设置为物理内存的 1.5-2 倍

3. 关闭不必要的功能

如果你的电脑配置较低，可以在配置文件中关闭一些不常用的功能：

# ~/.hermes/config.yaml
features:
  browser_automation: false
  code_execution: true
  file_manipulation: true
  web_search: true

总结与展望

截至 2026 年 4 月 26 日，Hermes Agent 的 Windows 原生支持已经达到了可用状态，90% 以上的核心功能都能正常工作。虽然还有一些小问题，但对于大多数用户来说，已经完全可以替代 WSL2 部署了。

官方团队表示，v0.11.0 版本（预计 2026 年 5 月中旬发布）将正式支持 Windows 原生，届时所有已知的兼容性问题都将得到修复，并且会提供官方的 MSI 安装包。

如果你想第一时间体验这个目前最强大的开源 AI 智能体，现在就可以按照这篇手册在你的 Windows 电脑上安装它了。

写在最后

Hermes Agent 最大的优势在于它的自学习能力—— 它会从每次成功完成的任务中学习，创建可重用的 "技能"，越用越聪明。随着 Windows 原生支持的完善，相信它会成为更多 Windows 用户的 AI 助手首选。

如果你在安装过程中遇到了任何问题，欢迎在评论区留言，我会尽力帮你解决。