Hermes 极简安装教程：用 uv + WSL2 把 Python 环境一次跑通-育师

1. Windows 上跑 Hermes 为什么总卡在环境这一步

如果你在 Windows 原生环境里装过 Hermes，大概率经历过这种场面：pip install -e .跑到一半报编译错误，某个依赖死活装不上，或者hermes setup刚启动就抛出一串路径相关的异常。我一开始也是在 Windows 里硬装，折腾了大半天，最后发现问题的根源不在 Hermes 本身，而在 Windows 和 Linux 工具链之间的那层隔阂。

Hermes 这类 Agent 框架的依赖树里，有不少包默认按 POSIX 路径和 Linux 的编译环境来构建。Windows 下即使装了 Visual C++ Build Tools，也经常因为路径分隔符、符号链接权限、shell 脚本执行方式这些细节翻车。所以更省事的做法是：用 WSL2 开一个真正的 Linux 子系统，再配合 uv 这个极快的 Python 包管理器，把整个环境一次性跑通。

这篇教程面向的就是想在 Windows 上把 Hermes 跑起来的用户。核心链路是：WSL2 提供 Linux 运行环境，uv 负责 Python 版本和虚拟环境管理，Git 拉取源码，最后通过 TaoToken 统一配置模型调用的 Key 和 API 通道。整套流程走完，你会得到一个干净、可复现、不污染 Windows 主系统的 Hermes 运行环境。下面每一步都给可复制的命令，照着敲就行。

先说清楚几个概念，方便小白理解。WSL2 是 Windows 自带的 Linux 子系统，相当于在你的 Windows 里开了一台轻量 Linux 虚拟机，但它和 Windows 文件系统互通，性能也接近原生。uv 是用 Rust 写的 Python 包和项目管理工具，装包速度比 pip 快很多，还能直接管理 Python 版本，省去单独装 Python 的麻烦。Hermes 是 NousResearch 出的 Agent 框架，通过hermes chat就能在终端里和模型对话、跑任务。三者组合起来，就是 Windows 用户跑 Hermes 最顺的一条路。

2. WSL2 与 uv 前置准备：把 Linux 底座和 Python 管理器装好

这一节解决的是「地基」问题。很多人 Hermes 装不上，不是 Hermes 的问题，而是 WSL2 没装好或者 uv 没配进 PATH。我们一步步来。

2.1 确认并安装 WSL2

如果你已经装过 WSL2，可以跳过安装，直接确认版本。打开 Windows 的 PowerShell（普通权限即可，安装 WSL 需要管理员时系统会提示），执行：

wsl --list --verbose

如果输出里有VERSION 2的发行版，说明 WSL2 已就绪。如果提示没有安装任何发行版，或者版本是 1，就执行安装：

wsl --install -d Ubuntu

这条命令会安装 WSL2 内核和 Ubuntu 发行版。装完后重启一次电脑，首次进入 Ubuntu 会让你设置用户名和密码，这个用户名密码是 Linux 子系统里的，和 Windows 账户无关，记好即可。

进入 WSL 的方式很简单，在 PowerShell 里敲：

wsl.exe

提示符会从PS C:\Users\你的名字>变成类似yourname@PC-xxxx:~$，这就说明你已经进到 Linux 环境里了。后面所有命令，除非特别说明，都在这个 WSL 终端里执行。

注意：WSL2 需要 Windows 开启虚拟化支持。如果wsl --install报错说虚拟化未启用，需要进 BIOS 打开 Intel VT-x 或 AMD-V。这一步因主板而异，进 BIOS 找 Virtualization 相关选项开启即可。

2.2 安装 uv

uv 的官方安装脚本一行搞定。在 WSL 终端里执行：

curl -LsSf https://astral.sh/uv/install.sh | sh

这个脚本会把 uv 装到~/.local/bin目录下。装完后需要把该目录加进当前 shell 的环境变量，执行：

source $HOME/.local/bin/env

然后验证：

uv --version

正常会输出类似uv 0.11.14 (x86_64-unknown-linux-gnu)的版本号。如果提示uv: command not found，说明 PATH 没生效，重新执行一次source $HOME/.local/bin/env即可。想让它永久生效，可以把这行加到~/.bashrc末尾：

echo 'source $HOME/.local/bin/env' >> ~/.bashrc

2.3 准备 Git

Hermes 源码要从 GitHub 拉取，所以需要 Git。Ubuntu 一般自带，确认一下：

git --version

如果没有，用 apt 装：

sudo apt update && sudo apt install -y git

到这里，WSL2、uv、Git 三件套就齐了。接下来创建项目目录并配置 Python 环境。

3. 用 uv 创建虚拟环境并配置 Hermes 可复制步骤

这一节是核心操作区，包含完整的目录创建、虚拟环境、源码获取、依赖安装和模型通道配置。每一步都给可复制的命令和配置文件片段。

3.1 创建项目目录与 Python 虚拟环境

在 WSL 终端里执行：

mkdir -p ~/hermes-agent && cd ~/hermes-agent uv venv --python 3.11

uv venv --python 3.11会创建一个 Python 3.11 的虚拟环境。uv 会自动下载对应版本的 CPython，不需要你手动装 Python。输出类似：

Using CPython 3.11.15 Creating virtual environment at: .venv Activate with: source .venv/bin/activate

激活虚拟环境：

source .venv/bin/activate

激活后，提示符前面会多出(hermes-agent)字样，说明你已经在这个隔离环境里了。之后所有 pip 安装都只影响这个环境，不会污染系统 Python。

3.2 获取 Hermes 源码

官方仓库地址是https://github.com/NousResearch/Hermes-Agent.git。直接克隆：

git clone https://github.com/NousResearch/Hermes-Agent.git cd Hermes-Agent

如果克隆速度很慢或者中途断掉，可以换个思路：在 Windows 浏览器里打开仓库页面，点 Code 里的 Download ZIP，下载后把压缩包复制到 WSL 能访问的目录。WSL 可以直接访问 Windows 盘符，路径形如/mnt/c/Users/你的名字/Downloads/。解压后进入目录即可：

cd /mnt/c/Users/你的名字/Downloads/Hermes-Agent-main

3.3 安装依赖

在 Hermes 源码目录下，用 pip 以可编辑模式安装：

pip install -e .

-e表示 editable 模式，源码改动会直接生效，适合后续调试。这一步会拉取所有依赖，uv 环境下 pip 的解析速度也很快。如果中途报某个包编译失败，先确认是否装了编译工具：

sudo apt install -y build-essential python3-dev

3.4 配置模型调用通道（TaoToken）

Hermes 要调用模型，需要配置 API Key 和 Base URL。这里用 TaoToken 统一管理 Key 和通道，避免在多个模型供应商之间来回切换配置。TaoToken 的 API 地址是https://taotoken.net/api，Key 在控制台的 API Keys 页面创建。

先创建 Key：访问https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=hermes_wsl2_uv&utm_campaign=rewrite，登录后新建一个 Key，复制保存。

然后在 Hermes 项目里配置环境变量。推荐用.env文件管理，在项目根目录创建：

cat > .env << 'EOF' OPENAI_API_KEY=你的TaoToken_Key OPENAI_BASE_URL=https://taotoken.net/api OPENAI_MODEL=gpt-4o-mini EOF

如果你用的是支持 TOML 配置的版本，也可以写进config.toml：

[model] provider = "openai" base_url = "https://taotoken.net/api" api_key = "你的TaoToken_Key" model_id = "gpt-4o-mini"

三件套要记牢：Base URL 填https://taotoken.net/api，Key 填 TaoToken 控制台创建的 Key，Model ID 填你要用的模型名。这三项缺一不可，后面排障也主要围绕它们。

3.5 运行初始化

配置好通道后，执行 Hermes 的初始化向导：

hermes setup

它会一步步问你模型配置、工作目录等信息。如果它读取到了.env里的环境变量，大部分可以直接回车用默认值。走完 setup，环境就基本就绪了。

4. 启动验证：hermes chat 跑通第一次对话

配置完成后，最直接的验证方式就是启动对话：

hermes chat

如果一切正常，你会看到 Hermes 的交互界面，输入一句话，比如「你好，帮我列一下当前目录的文件」，它会调用模型并返回结果。第一次请求会走 TaoToken 的 API 通道，如果 Key 和 Base URL 都对，几秒内就能看到回复。

想更轻量地验证通道是否通，可以先用 curl 直接打一次 API：

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer 你的TaoToken_Key" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "ping"}] }'

返回 JSON 里如果有choices字段和内容，说明 Key 和通道都没问题。这一步能把「模型通道问题」和「Hermes 本身问题」分开定位，非常实用。

如果hermes chat能进界面但发消息报错，多半是模型配置没读到。检查.env是否在项目根目录、变量名是否拼对、虚拟环境是否激活。确认后重新source .venv/bin/activate再启动。

验证通过后，你就有了一套完整的本地 Hermes 环境。后续想换模型，只改.env里的OPENAI_MODEL即可，Base URL 和 Key 不用动，这就是统一通道的好处。

5. 常见报错排查：401、local proxy failed 与 reading choices

环境搭建过程中，报错基本集中在几类。下面按真实遇到的错误逐个拆解。

401 Unauthorized：这是最常见的。原因通常是 Key 没填对、Key 前后有空格、或者.env没被加载。先确认 Key 是从 TaoToken 控制台复制的完整字符串，再检查.env文件里有没有多余空格或引号。用上面的 curl 命令单独测一次，如果 curl 也 401，就是 Key 本身的问题；如果 curl 通但 Hermes 报 401，就是 Hermes 没读到环境变量，检查是否在项目根目录启动、虚拟环境是否激活。

local proxy failed / connection refused：这类报错说明请求根本没发出去，通常是 Base URL 写错，或者本地网络把请求拦了。确认OPENAI_BASE_URL填的是https://taotoken.net/api，注意不要多加/v1之外的路径，也不要漏掉协议头。如果之前配过其他代理工具，先清掉相关环境变量：

unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy

reading choices 相关报错：比如KeyError: 'choices'或解析响应失败。这通常意味着返回的不是标准 chat completions 结构，可能是模型名写错导致接口返回了错误信息，也可能是 Base URL 指向了错误的端点。核对OPENAI_MODEL是否是通道支持的模型 ID，Base URL 是否是https://taotoken.net/api。用 curl 打印完整返回体，看error字段写了什么，比只看异常堆栈有用得多。

OAuth / 认证跳转类报错：如果 Hermes 某个版本尝试走 OAuth 流程而你的通道是 Key 认证，需要在配置里显式指定用 API Key 模式，避免它去走浏览器授权。检查 setup 过程中是否有 provider 选择项，选 openai 兼容模式，填 Key 而不是走登录。

pip install -e . 编译失败：多半是缺编译工具或 Python 头文件。执行sudo apt install -y build-essential python3-dev后重试。如果某个包在 Python 3.11 下不兼容，可以换 3.10 重建虚拟环境：uv venv --python 3.10。

git clone 卡住或超时：换用 ZIP 下载再复制进 WSL 的方式，前面 3.2 节已经给了路径写法。复制时注意 WSL 访问 Windows 盘符的路径格式是/mnt/c/...。

排查的核心思路就一条：先用 curl 验证通道，再验证 Hermes 配置，最后看依赖和编译。把问题分层，定位会快很多。

6. 把通道固定下来：后续调用与长期使用建议

环境跑通只是开始，真正省心的是把模型通道固定成一套可复用的配置。TaoToken 在这里的价值就是：不管你后面换哪个模型、跑哪个 Agent 项目，Base URL 和 Key 的管理方式是一致的，不用每个项目重新折腾一遍认证。

如果你打算长期在本地跑 Hermes 做编码或 Agent 任务，可以了解一下 Coding Plan，它更适合高频、长期的编码场景：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=hermes_wsl2_uv&utm_campaign=rewrite。日常想快速验证某个模型效果，直接用模型对话页面就行：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=hermes_wsl2_uv&utm_campaign=rewrite。需要管理多个 Key 或查看用量，去控制台：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=hermes_wsl2_uv&utm_campaign=rewrite。接入细节和参数说明都在文档里：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=hermes_wsl2_uv&utm_campaign=rewrite。

最后给几个实操小技巧。第一，把source $HOME/.local/bin/env和source .venv/bin/activate写进一个start.sh，每次进项目直接source start.sh，省得记两条命令。第二，.env不要提交到 Git，加进.gitignore，避免 Key 泄露。第三，WSL2 的文件系统跨盘访问（/mnt/c/...）比在 Linux 原生目录（~/）慢，项目尽量放在~/hermes-agent下，源码 ZIP 复制过来后也移到 Linux 目录再操作。第四，如果 Hermes 升级后配置格式变了，优先看官方仓库的 README 和 release notes，再对照本文的三件套（Base URL、Key、Model ID）检查一遍，大部分问题都能自己解决。