Hermes Agent 在 Windows 上安装（WSL2 完整指南）

为什么 Windows 不能直接装

你可能想问：Hermes 不就是 Python + Node 吗？Windows 也能跑 Python。为什么必须 WSL2？

• Hermes 大量使用 Unix 风格路径（~/.hermes、/usr/local/bin）。Windows 路径用反斜杠，转义在 Python subprocess 调用里很容易踩坑。
• Hermes 的 Skills 大部分用 Bash / sh 写底层调用（git、ripgrep、fd 等命令），Windows cmd / PowerShell 不兼容。
• Terminal ANSI 色彩 + 进度条在 Windows Terminal 上虽然能渲染，但 Hermes 用的 readline 库在原生 Windows 上经常断裂。
• 一句话：理论上能跑，实践上 60% 的常用 Skill 都会出现奇怪问题。WSL2 让你拿到一个干净的 Linux 环境，体验和 Mac / Linux 同学完全一致。

WSL2 不是虚拟机——它是 Windows 内核里的轻量 Linux 子系统，启动 1 秒，文件系统和 Windows 互通。装一次受用全程。

安装 WSL2（Win10 / Win11）

以管理员身份打开 PowerShell（Win+X 选 Terminal (Admin)），跑下面这条。

wsl --install -d Ubuntu-22.04

1. 1. 重启电脑

   命令跑完后系统会提示重启。重启完成后会自动弹出 Ubuntu 终端窗口，第一次启动会让你设置 Linux 用户名和密码（和 Windows 账户无关，自己起一个就行）。

2. 2. 验证 WSL2

   在 PowerShell 里跑 wsl -l -v，应该看到 Ubuntu-22.04 状态是 Running，VERSION 是 2。如果是 1，跑 wsl --set-version Ubuntu-22.04 2 升级。

3. 3. 更新系统

   在 Ubuntu 终端里跑 sudo apt update && sudo apt upgrade -y。装完用 sudo apt install -y curl git build-essential 装好基础工具。

到这一步你已经有了一个完整的 Linux 环境。Hermes 安装步骤和 Mac / Linux 用户完全一样。

在 WSL Ubuntu 中安装 Hermes

回到 Ubuntu 终端（开始菜单搜 Ubuntu 或在 PowerShell 里跑 wsl 进入），跑官方一行命令。

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

• 装完位置：~/.hermes（这是 WSL Ubuntu 里的 home，对应 Windows 的 \\wsl$\Ubuntu-22.04\home\<user>\.hermes）
• 装完关闭终端再开一次让 PATH 生效，或 source ~/.bashrc
• 验证：hermes --version 应该输出版本号
• 装完跑 hermes doctor 一键自检 12 项

配置 LLM Provider、装 Skills 等步骤都在 /install 主指南里。

VS Code WSL 开发体验

推荐配置：Windows 端装 VS Code，通过 Remote-WSL 扩展连进 WSL 干活。这样你保留 Windows 的图形界面，但所有终端 + 文件操作都在 Linux 里。

1. 1. Windows 端装 VS Code

   从 https://code.visualstudio.com/ 下载安装。安装时勾选"Add to PATH"。

2. 2. 装 Remote - WSL 扩展

   VS Code 里 Ctrl+Shift+X 打开扩展面板，搜 "Remote - WSL"（微软官方），点 Install。

3. 3. 从 WSL 终端打开项目

   在 WSL Ubuntu 终端里 cd 到你的项目目录，然后跑 code .。VS Code 会自动连进 WSL 打开当前目录，左下角会显示绿色的 "WSL: Ubuntu"。

4. 4. 终端共用 WSL

   VS Code 内嵌终端默认就是 WSL Bash，跑 hermes 命令直接在那里跑就行。Hermes 的输出在 VS Code 终端里能正常显示彩色和进度条。

网络代理配置（必看）

中国大陆用户大概率需要配代理才能装 Skills（GitHub raw + 部分 LLM Provider 域名）。WSL2 默认不继承 Windows 的代理设置，需要手动配。

• 前提：Windows 端有 Clash / V2Ray / Surge 在跑，端口比如 7890
• 获取 WSL 看到的 Windows 主机 IP：在 WSL 里跑 cat /etc/resolv.conf 看 nameserver 那一行
• 在 ~/.bashrc 末尾加：export HTTPS_PROXY="http://<上面那个IP>:7890"，HTTP_PROXY 同理
• 保存后 source ~/.bashrc 立即生效
• 验证：curl -I https://www.google.com 应该返回 200，不再卡死

配好代理后再跑 hermes skills sync 拉取 Skills registry。如果不想全局走代理，可以只在 Hermes 配置文件里给 skills.proxy 单独设一个。

WSL 常见报错 8 种

WSL2 + Hermes 安装路上几乎所有人都会撞到下面 8 个错误之一。挨个对照即可。

• WslRegisterDistribution failed with error: 0x800701bc

  原因 / Cause: WSL2 内核未安装或版本太旧。

  修复 / Fix: 在 PowerShell 里跑 wsl --update。仍报错就去微软官网下载 WSL2 Linux 内核更新包手动装一次。

• wsl --install 提示找不到命令

  原因 / Cause: Win10 版本低于 21H2，wsl --install 是 21H2 加的简化命令。

  修复 / Fix: 走老流程：在 "启用或关闭 Windows 功能" 里勾选 Hyper-V、虚拟机平台、适用于 Linux 的 Windows 子系统，重启后到 Microsoft Store 装 Ubuntu。

• WSL Ubuntu 启动后卡死在 "Installing, this may take a few minutes"

  原因 / Cause: 系统盘空间不足或 Hyper-V 没启用。

  修复 / Fix: 检查 C 盘剩余空间需要 ≥ 5 GB。Hyper-V 在 BIOS 里要开启 VT-x（Intel）或 SVM（AMD）。

• curl install 命令在 WSL 里卡在 "Installing Python deps"

  原因 / Cause: WSL2 默认 DNS 用 Windows 主机解析，国内访问 pypi.org 偶尔抽风。

  修复 / Fix: 在 WSL Ubuntu 里：echo "[network]\ngenerateResolvConf = false" | sudo tee /etc/wsl.conf；然后 PowerShell 里 wsl --shutdown 重启 WSL；再手动 sudo nano /etc/resolv.conf 写 nameserver 8.8.8.8。

• hermes 命令在 VS Code 终端里能跑，在 Windows Terminal 里报 not found

  原因 / Cause: Windows Terminal 默认 profile 不是 WSL。

  修复 / Fix: Windows Terminal 里 Ctrl+, 打开设置，把 Default profile 设成 Ubuntu-22.04。

• WSL 文件系统访问 Windows 端 D:\ 项目特别慢

  原因 / Cause: WSL 跨盘访问（/mnt/d/...）走的是 9P 协议，比 ext4 慢 10 倍以上。

  修复 / Fix: 把项目从 Windows D 盘移到 WSL 自己的 ~/projects 下面（在 WSL home 下）。需要 Windows 端访问就走 \\wsl$\Ubuntu-22.04\home\<user>\projects。

• hermes 启动报 ANSI 色彩在 Windows Terminal 里乱码

  原因 / Cause: Windows Terminal 字体不支持 Powerline / Nerd Font。

  修复 / Fix: 装一个 Nerd Font 字体（推荐 JetBrainsMono Nerd Font）然后在 Windows Terminal 设置里把 Ubuntu profile 的字体改成它。

• WSL2 内存占用持续增长不释放

  原因 / Cause: WSL2 默认不会主动归还内存给 Windows。

  修复 / Fix: 在 Windows 用户目录建 .wslconfig 文件，写：[wsl2]\nmemory=4GB\nswap=2GB；保存后 wsl --shutdown 重启 WSL 即可生效。