Windows 安装 Hermes 的那些坑

看似一行命令搞定，实际踩坑踩到怀疑人生——这份避坑指南帮你省下半天折腾时间

什么是 Hermes Agent？

Hermes Agent 是 Nous Research 开源的一款 AI 智能体框架。简单说，它就是一个能跑在终端里的 AI 助手——可以写代码、搜网页、管理文件、操作浏览器，还能接入微信、Telegram、飞书等十几个平台。

跟 Claude Code、Codex 是同类产品，但 Hermes 的亮点在于：

• 完全开源
  ，不绑定任何厂商
• 支持 20+ 模型供应商
  ，OpenRouter、DeepSeek、Anthropic 随便换
• 跨平台网关
  ，同一个 Agent 同时跑在微信和 Telegram 上
• 持久记忆和技能系统
  ，越用越懂你

听起来很香对吧？但如果你是 Windows 用户，安装过程可能会让你想砸键盘。下面就是我在 Windows 上安装 Hermes 踩过的 4 个大坑，以及每个坑的正确解法。最后还会给你一个一键安装脚本，把四个坑全填平。

坑一：必须在 WSL 下安装

为什么 Windows 原生跑不了？

Hermes Agent 的安装脚本（install.sh）是 Bash 写的，底层依赖大量 Linux 工具链：

• 终端交互：
  依赖 prompt_toolkit，需要真正的 PTY（伪终端）。Windows 的 cmd 和 PowerShell 不是 POSIX 终端，很多快捷键和信号处理不一致。
• 进程管理：
  Hermes 会启动后台进程（gateway、cron scheduler），依赖 Unix 的进程组和信号机制。
• 文件权限：
  创建 .env 存储 API Key，依赖 chmod 600 保护密钥。NTFS 的 ACL 行为不同。
• 路径系统：
  安装脚本假设 /home/$USER/、/usr/local/bin/ 等 Unix 路径存在。

你可以试着在 Git Bash 或 MSYS2 里跑，但大概率会在某个环节报错。结论：老老实实用 WSL2。

第一步：检查 Windows 版本

WSL2 需要 Windows 10 版本 2004 或更高（Build 19041 以上），或 Windows 11 任意版本。在 PowerShell 中运行 winver 查看版本。

第二步：安装 WSL2

打开 PowerShell（管理员权限），执行：

PowerShell（管理员）
# 一条命令安装 WSL2 + Ubuntuwsl--install# 如果之前装过 WSL1，手动升级到 WSL2wsl--set-default-version 2

安装完成后重启电脑。重启后 Ubuntu 会自动启动，提示创建用户名和密码。

第三步：确认 WSL 版本

PowerShell
wsl-l -v# 输出示例：#   NAME      STATE           VERSION# * Ubuntu    Running         2

确保 VERSION 列显示 2。如果显示 1，执行 wsl --set-version Ubuntu 2。

第四步：更新 WSL 内的系统包

进入 WSL（在 PowerShell 中输入 wsl），更新系统：

Bash (WSL)
sudo apt update && sudo apt upgrade -y

WSL 自带的 Ubuntu 镜像可能很旧，curl、git、python3 版本偏低，必须更新。

第五步：安装必要工具

Bash (WSL)
sudo apt install -y curl git python3 python3-pip python3-venv build-essential# 验证版本python3 --version# 需要 3.10+git --version# 需要 2.30+curl --version# 需要 7.68+

如果 python3 --version 低于 3.10，需要手动升级：

Bash (WSL)
sudo apt install -y software-properties-commonsudo add-apt-repository -y ppa:deadsnakes/ppasudo apt install -y python3.11 python3.11-venv python3.11-devsudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1

第六步：安装 Hermes

Bash (WSL)
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装完成后验证：

Bash
hermes doctor# 检查所有依赖是否就绪hermes setup# 交互式配置：选模型、设 API Key

坑二：安装过程狂拉 GitHub，国内网络直接卡死

问题有多严重？

安装脚本执行时会做这些事：

1. git clone 整个 Hermes Agent 仓库（约 300MB，含文档、测试、skill 包）
2. pip install -r requirements.txt（约 50 个 Python 依赖包）
3. 下载预构建的 skill 索引和模板文件
4. 部分依赖包自身也托管在 GitHub 上

在国内直连的情况下，典型表现：

如果你人在国内，不挂代理几乎不可能顺利装完。

在 WSL 中配置代理

WSL2 通过 Hyper-V 虚拟网卡与 Windows 主机通信。Windows 主机在 WSL 视角下的 IP 不是 127.0.0.1，而是 NAT 地址：

Bash (WSL)
# 获取宿主机 IPHOST_IP=$(ip route show default | awk '{print $3}')# 假设代理 HTTP 端口是 7890（Clash 默认）exportHTTP_PROXY="http://${HOST_IP}:7890"exportHTTPS_PROXY="http://${HOST_IP}:7890"

注意：HTTPS_PROXY 的值仍然是 http://，不是 https://。 它告诉工具「HTTPS 请求也走这个 HTTP 代理」，而不是说代理服务器本身是 HTTPS 的。

验证代理是否生效

Bash (WSL)
# 应该返回 HTTP 200curl -I https://github.com 2>&1 | head -5# 测试 raw.githubusercontent.comcurl -I https://raw.githubusercontent.com 2>&1 | head -5# 看看出口 IPcurl -s https://httpbin.org/ip

如果超时或报 Could not resolve host，常见原因：

1. 代理软件的 Allow LAN 没开——最常见的遗漏
2. Windows 防火墙拦截了入站连接
3. WSL2 虚拟网卡 IP 段变了——重新获取 HOST_IP
4. 代理软件本身没翻出去——先在 Windows 浏览器里确认

持久化代理 + 给 Git 单独配代理

Bash (WSL)
# 写入 bashrc（每次打开终端自动生效）cat >> ~/.bashrc << 'EOF'# WSL2 代理配置HOST_IP=$(ip route show default | awk '{print $3}')exportHTTP_PROXY="http://${HOST_IP}:7890"exportHTTPS_PROXY="http://${HOST_IP}:7890"exportNO_PROXY="localhost,127.0.0.1,::1"EOFsource ~/.bashrc# Git 也配代理（防止 git clone 失败）git config --global http.proxy http://${HOST_IP}:7890git config --global https.proxy http://${HOST_IP}:7890

坑三：WSL DNS 每次重启都重置

这个坑为什么最隐蔽？

装 Hermes 的当天一切正常。第二天开机，打开 WSL，输入 hermes，报错：

Error
Connection error: [Errno -2] Name or service not knownTemporary failure in name resolution

你第一反应是「代理挂了」，检查代理——正常。curl baidu.com——也超时。ping baidu.com——Temporary failure in name resolution。

这就是 DNS 挂了。 WSL 默认的 DNS 链路：程序 → /etc/resolv.conf → Windows 虚拟 DNS → 真实 DNS。WSL 每次重启都会重新生成 /etc/resolv.conf，写入 Windows 虚拟 DNS 地址。这个机制在挂代理、公司 VPN、或复杂网络环境下会失效。

彻底修复三步走

第一步：禁用 WSL 自动生成 resolv.conf

编辑 /etc/wsl.conf（如没有就新建）：

/etc/wsl.conf
[network]generateResolvConf = false

第二步：手动写入稳定 DNS

先删掉旧文件（通常是软链接），再写入新内容：

Bash (WSL)
# 查看当前是软链接还是普通文件ls -la /etc/resolv.conf# 删除（可能需要先解锁）sudo chattr -i /etc/resolv.conf 2>/dev/null; sudo rm /etc/resolv.conf# 写入稳定的国内 DNSsudo bash -c 'cat > /etc/resolv.conf << EOFnameserver 114.114.114.114nameserver 223.5.5.5EOF'# 验证内容cat /etc/resolv.conf

第三步：锁定文件防止被改写

Bash (WSL)
sudo chattr +i /etc/resolv.conf# 验证锁定：尝试删除应被拒绝sudo rm /etc/resolv.conf# → rm: cannot remove '/etc/resolv.conf': Operation not permitted

最后在 PowerShell 中执行 wsl --shutdown 重启 WSL，验证 DNS 解析正常。

推荐 DNS：114.114.114.114（114DNS，最稳）、223.5.5.5（阿里 DNS，延迟低）、119.29.29.29（DNSPod，备选）。

⚠️ 顺序很重要：先改 wsl.conf → 再改 resolv.conf → 最后 chattr +i。如果顺序反了，下次重启 wsl.conf 在 resolv.conf 被重置之后才生效——锁了个寂寞。极少数 WSL 版本不支持 chattr，用 systemd-resolved 替代：sudo systemctl disable systemd-resolved && sudo systemctl mask systemd-resolved。

坑四：pip 下载依赖慢到怀疑人生

pip 为什么这么慢？

Hermes 的 requirements.txt 包含约 50 个包，加上子依赖总下载量约 100~200MB。PyPI 官方源（pypi.org）的 CDN 节点主要在欧美，国内访问延迟 200~400ms，单线程速度仅 50~200 KB/s，而且高峰期丢包严重。总耗时：100MB ÷ 100KB/s ≈ 15~30 分钟（实际上经常中断重试）。

方案一：永久配置（推荐）

Bash (WSL)
# 设置默认镜像源为阿里云pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/# 添加信任主机（跳过 HTTPS 证书校验，加速连接）pip config set global.trusted-host mirrors.aliyun.com# 验证pip config listcat ~/.config/pip/pip.conf

方案二：临时使用

Bash
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

国内主要镜像源对比

为什么首推阿里云？速度快、同步及时（<1小时）、稳定性好、覆盖全。如果遇到阿里云没有的包，临时切回官方源：pip install xxx -i https://pypi.org/simple/

建议：国内安装脚本，一键填平所有坑

看完上面四个坑，你可能想：「每个坑都要手动修，好烦啊！」

没问题，这里给你一个一键安装脚本

Bash (WSL)
# 1. 一个命令安装curl -fsSL https://raw.githubusercontent.com/itech001/theaiera/main/scripts/install-cn.sh | bash

🔍 关注本号，获取更多 AI 工具实战教程

👆 点击上方蓝字 → 关注

💬 你装 Hermes 时还遇到了什么坑？评论区聊聊

👍 觉得有用？点个「在看」转给也在折腾的朋友