1. Windows 本地部署 Hermes Agent 到底难在哪
如果你在 Windows 上直接跑 Hermes Agent，大概率第一步就会卡住。官方文档写得很直白：Native Windows is not supported。也就是说，你没法像装个普通软件那样双击 exe 就完事，必须借助 WSL（Windows Subsystem for Linux）来提供一个 Linux 运行环境。Hermes Agent 本身是个 Python 项目，依赖管理用的是 uv，这套组合在 Linux 下很顺，但搬到 Windows 的 WSL 里，就会遇到 Python 版本、pip 权限、uv 路径、网络连通性一连串问题。
我这次完整走了一遍 WSL + Python + uv 的部署路线，实测下来比 Docker 方案要折腾一些，但好处是每一步都看得见、可控。这篇文章会从零开始，把 WSL 安装、Python 环境确认、uv 包管理器配置、依赖安装、Agent 启动和验证全部串起来，命令都可以直接复制。适合谁看？如果你是想在 Windows 上本地跑 Hermes Agent、又不想碰 Docker 的开发者，或者你已经在 WSL 里装 Python 包被权限问题卡过，这篇就是给你写的。
核心检索词先明确：Windows 本地部署 Hermes Agent，靠的是 WSL + Python + uv 三件套。WSL 负责提供 Linux 内核接口，Python 负责跑 Hermes 的代码，uv 负责把依赖装得又快又干净。三者缺一不可，而且顺序不能乱。下面我按实际踩坑顺序来讲，每一步都给出可复制命令和预期输出。
先说一个容易忽略的点：WSL 里的 Ubuntu 默认自带 python3，但通常不带 pip，更不带 uv。Ubuntu 出于系统稳定性考虑，禁止直接用 pip install 往系统 Python 里装包，所以你必须走 pipx 这条路来装 uv。这个设计一开始会让人困惑，但理解了就顺了。另外，WSL 访问 Windows 宿主机的网络需要额外配置，否则安装脚本拉取依赖时会超时中断。这些坑我都会在对应章节里给出解法。
整条路线可以概括为：装 WSL → 确认 Python → 装 pipx → 用 pipx 装 uv → 配 PATH → 装 Hermes → 配模型 → 启动验证。每一步都有明确的成功标志，你照着做就能复现。下面进入具体操作。
2. WSL 安装与 Python 环境确认：Hermes Agent 部署前置
这一章解决的是“地基”问题。没有 WSL，Hermes Agent 在 Windows 上根本跑不起来。WSL 的安装现在已经被微软简化成一条命令，但装完之后还有几个细节要确认，否则后面会连环报错。
2.1 一条命令装好 WSL 和 Ubuntu
以管理员身份打开 PowerShell，执行：
wsl --install -d Ubuntu这条命令会做三件事：启用 WSL 功能、下载 WSL2 内核、安装 Ubuntu 发行版。执行过程中会提示你重启电脑，重启后 Ubuntu 会自动启动并要求你设置 Linux 用户名和密码。这个用户名密码是 WSL 内部的，和 Windows 账户无关，记好就行。
装完后验证一下：
wsl --list --verbose预期输出里能看到 Ubuntu 的状态是 Running，版本是 2。如果版本显示 1，建议执行wsl --set-version Ubuntu 2升到 WSL2，因为 WSL2 的网络和文件系统性能更好，对后续装包更友好。
2.2 确认 WSL 里的 Python 版本
进入 WSL 终端（可以在开始菜单搜 Ubuntu，或者在 PowerShell 里直接输wsl），执行：
python3 --version一般会输出类似Python 3.10.x或Python 3.12.x。有版本号就说明 Python 环境是预置好的。但注意，这里只有 python3，没有 pip，也没有 uv。你可以顺手验证一下：
pip3 --version大概率会提示 command not found，或者提示你需要安装 python3-pip。这就是下一个要解决的问题。
2.3 为什么不能直接用 pip 装 uv
Ubuntu 从某个版本开始，对系统自带的 Python 做了“外部管理”保护。如果你直接pip install uv，会看到类似error: externally-managed-environment的报错。这不是你操作错了，而是系统在防止你覆盖 apt 管理的包。正确的做法是先用 apt 装 pipx，再用 pipx 装 uv。pipx 会把每个工具装进独立的虚拟环境，既干净又不污染系统 Python。
先更新软件源并安装 pipx：
sudo apt update sudo apt install -y pipx装完后执行：
pipx ensurepath这一步会把 pipx 的二进制目录写进 PATH。执行完必须关闭当前 WSL 终端，重新开一个新终端，否则 PATH 不生效。这个细节很多人会漏，导致后面pipx install uv找不到命令。
2.4 用 pipx 安装 uv 并配置 PATH
在新开的 WSL 终端里执行：
pipx install uv成功后，uv 会被装到~/.local/bin下。为了确保每次打开终端都能直接用 uv，把这个路径写进 bashrc：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc source ~/.bashrc然后验证：
uv --version which uv两条命令二选一执行即可，正常会输出 uv 的版本号和完整路径。到这里，WSL + Python + uv 的基础环境就搭好了。下一章进入 Hermes Agent 的实际安装和配置。
3. Hermes Agent 安装与 uv 依赖配置可复制片段
这一章是核心操作区。Hermes Agent 的官方安装脚本会自己处理依赖，但在 WSL 环境下，直接跑脚本经常会因为网络问题中断。所以我会先讲网络连通性检查，再给安装命令，最后给出模型配置的完整片段。
3.1 先确认 WSL 能访问外部网络
WSL2 的网络是 NAT 模式，默认能访问外网。但如果你在 Windows 上开了某些网络工具，WSL 里的流量不一定能走通。先做个基础测试：
curl -I --connect-timeout 5 https://raw.githubusercontent.com如果返回 HTTP 状态码（比如 200 或 301），说明网络通。如果卡住或超时，就需要检查 Windows 侧的网络设置，确保 WSL 的流量能正常出去。这一步很关键，因为 Hermes 的安装脚本是从 GitHub 拉取的，网络不通会直接失败。
3.2 执行 Hermes 官方安装脚本
网络确认没问题后，执行：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash这个脚本会自动用 uv 创建虚拟环境并安装 Hermes 及其依赖。安装过程中你会看到 uv 在解析依赖、下载包、创建 venv。如果中途出现连接中断或某个包下载失败，重新执行一次通常就能续上，因为 uv 有缓存机制。
安装完成后，验证 Hermes 是否可用：
hermes --version如果输出版本号，说明安装成功。如果提示 command not found，检查~/.local/bin是否在 PATH 里，或者重新source ~/.bashrc。
3.3 模型配置的 JSON 片段
Hermes 启动后会进入配置流程。我选择的是 quick setup，然后配置语言模型。这里以配置一个自定义模型为例，给出可复制的配置片段。Hermes 的模型配置通常写在~/.hermes/config.json或类似路径下，具体以你安装后的实际路径为准。一个典型的配置结构如下：
{ "model": { "provider": "custom", "base_url": "https://taotoken.net/api", "api_key": "你的API_KEY", "model_id": "claude-3-5-sonnet", "max_tokens": 4096, "temperature": 0.7 }, "agent": { "name": "hermes-local", "workspace": "/home/你的用户名/hermes-workspace" } }这里三个关键字段必须写全：Base URL、API Key、Model ID。Base URL 填https://taotoken.net/api，API Key 在控制台生成，Model ID 根据你要用的模型填写。如果你在配置向导里选择了“自定义模型”，就会走到这一步。注意，配置向导里有一句“Base URL 这一步不要输入，直接回车”的说法，那是针对某些内置 provider 的默认行为；如果你走自定义路线，就必须显式填 Base URL。
3.4 用 uv 手动管理依赖（可选）
如果你不想用一键脚本，想自己控制依赖，可以用 uv 手动操作：
uv venv source .venv/bin/activate uv pip install hermes-agent这种方式适合你想把 Hermes 装进指定虚拟环境的场景。uv 的解析速度比 pip 快很多，实测装几十个依赖也就十几秒。装完后同样用hermes --version验证。
配置完成后，启动 Hermes：
hermes进入交互界面后，可以用/model命令切换模型。如果你想在启动前就指定模型，可以在配置里写好，启动后直接生效。
4. 启动 Agent 并验证服务响应：请求与结果对照
装好不等于跑通，必须实际发一次请求，看到模型返回内容，才算部署成功。这一章给出完整的验证动作和预期结果。
4.1 启动 Hermes 并进入交互模式
在 WSL 终端执行：
hermes首次启动会加载配置、初始化 agent。如果配置正确，你会看到类似Hermes Agent ready的提示，然后进入一个交互式命令行。这时候可以直接输入问题，比如：
你好，请用一句话介绍你自己如果模型配置正确，几秒内会返回一段文本。这就是最直接的验证：Agent 能收到请求，模型能返回响应。
4.2 用 curl 直接验证 API 连通性
如果你想绕过 Hermes，单独验证 API 是否通，可以用 curl：
curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer 你的API_KEY" \ -d '{ "model": "claude-3-5-sonnet", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 50 }'预期返回一个 JSON，里面choices[0].message.content字段就是模型的回复。如果返回 401，说明 API Key 有问题；如果返回 404，检查 Base URL 和路径；如果超时，回到第 3 章检查网络。
4.3 在 Hermes 中切换模型并再次验证
进入 Hermes 后，输入：
/model会列出可用模型，选择你配置的那个。切换后再问一个问题，确认新模型生效。这一步能验证配置里的 Model ID 是否被正确读取。
4.4 验证结果对照表
| 验证动作 | 预期结果 | 异常表现 |
|---|---|---|
hermes --version | 输出版本号 | command not found |
hermes启动 | 进入交互界面 | 报配置错误 |
| 交互提问 | 模型返回文本 | 无响应或报错 |
| curl API | 返回 JSON | 401/404/超时 |
/model切换 | 模型列表出现 | 列表为空 |
实测下来，只要前三步都过，基本就部署成功了。如果某一步卡住，对照下一章的排查清单。
5. 本篇常见报错排查：401、local proxy failed、reading choices
部署过程中最容易遇到的就是网络和认证类报错。这一章把真实出现过的错误和对应解法列出来，你遇到时直接对号入座。
5.1 401 Unauthorized
报错原文通常是：
{"error": {"message": "Invalid API key", "type": "authentication_error"}}原因很明确：API Key 不对或没传。检查三处：配置文件里的api_key字段、环境变量里的 key、curl 命令里的 Authorization 头。注意 key 不要有多余空格，也不要漏掉Bearer前缀。如果你在控制台重新生成过 key，旧 key 会失效，记得同步更新。
5.2 local proxy failed / connection refused
报错原文类似：
local proxy failed: dial tcp 127.0.0.1:7890: connect: connection refused这是 WSL 里配置了代理但代理没启动，或者代理地址写错了。WSL2 访问 Windows 宿主机的服务，不能用 127.0.0.1，要用 WSL 的网关 IP。查网关：
ip route | grep default输出里的第一段 IP 就是网关，比如172.3.2.1。然后确认 Windows 侧的网络工具监听端口，把 WSL 的代理指向http://网关IP:端口。如果不需要代理，直接清掉 WSL 里的http_proxy和https_proxy环境变量：
unset http_proxy unset https_proxy5.3 reading choices 相关报错
报错原文可能是：
error reading choices: unexpected end of JSON input这通常说明 API 返回了空响应或非 JSON 内容。常见原因是 Base URL 写错，请求打到了错误的路径，返回了 HTML 页面。检查 Base URL 是否以/api结尾，以及请求路径是否正确。另外，如果模型 ID 写错，有些服务会返回错误页而不是 JSON，也会触发这个报错。
5.4 OAuth 相关报错
如果你在配置里选了需要 OAuth 的 provider，可能会看到：
OAuth token expired or invalid解法是重新走一遍授权流程，或者改用 API Key 方式。对于本地部署，建议直接用 API Key，省去 OAuth 的刷新逻辑。
5.5 uv 安装后命令找不到
报错：
uv: command not found原因是~/.local/bin没进 PATH。执行：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc source ~/.bashrc然后which uv确认路径。如果还是找不到，检查 pipx 是否装成功，pipx list能看到 uv 就说明装上了。
5.6 Hermes 启动报 Python 版本不兼容
Hermes 对 Python 版本有要求，太低会报语法错误。用python3 --version确认版本，建议 3.10 以上。如果 WSL 自带的版本太低，可以用 uv 装一个新版本：
uv python install 3.12然后在虚拟环境里指定用 3.12。
排查的核心思路是：先看报错关键词，再定位是网络、认证还是配置问题。大部分问题都能通过检查 Base URL、API Key、Model ID 这三个字段解决。
6. 长期编码与 Agent 场景的接入建议
本地把 Hermes Agent 跑起来只是第一步。如果你打算长期用它做编码辅助或者 Agent 任务，有几个实践建议可以让你少走弯路。
第一，把配置固定下来。每次手动改配置容易出错，建议把config.json纳入版本管理，API Key 用环境变量注入，不要硬编码在文件里。这样换机器或者重装时，直接拉配置就能恢复。
第二，模型选择上，日常编码可以用响应快的模型，复杂推理任务再切到能力更强的模型。Hermes 的/model命令支持运行时切换，不用重启。你可以准备两套配置，按任务类型切换。
第三，如果你要把 Hermes 接入到编辑器或 CI 流程里，建议走 API 方式而不是交互式命令行。Base URL 用https://taotoken.net/api，Key 在控制台生成，Model ID 按需填写。这样无论是脚本调用还是工具集成，都统一走一套认证。
第四，WSL 的环境要定期更新。sudo apt update && sudo apt upgrade保持系统包最新，uv 也用uv self update升级。依赖版本太旧有时会导致 Hermes 的某些功能异常。
第五，日志要留着。Hermes 运行时的报错信息是排查问题的关键，建议把输出重定向到文件，出问题时直接翻日志，比凭记忆复现快得多。
如果你还没生成 API Key，可以去控制台创建；想先体验模型对话效果，可以直接用模型对话页面测试；如果打算长期跑编码和 Agent 任务，Coding Plan 会更合适。接入文档里有完整的参数说明和示例，配置时对照着填就行。本地部署这件事，跑通一次之后，后面就是维护和调优了。
