1. Windows 本地部署 Hermes Agent 到底难在哪如果你在 Windows 上直接跑 Hermes Agent大概率第一步就会卡住。官方文档写得很直白Native Windows is not supported。也就是说你没法像装个普通软件那样双击 exe 就完事必须借助 WSLWindows 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 部署前置这一章解决的是“地基”问题。没有 WSLHermes 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 装 uvUbuntu 从某个版本开始对系统自带的 Python 做了“外部管理”保护。如果你直接pip install uv会看到类似error: externally-managed-environment的报错。这不是你操作错了而是系统在防止你覆盖 apt 管理的包。正确的做法是先用 apt 装 pipx再用 pipx 装 uv。pipx 会把每个工具装进独立的虚拟环境既干净又不污染系统 Python。先更新软件源并安装 pipxsudo 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把这个路径写进 bashrcecho 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/apiAPI 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验证。配置完成后启动 Hermeshermes进入交互界面后可以用/model命令切换模型。如果你想在启动前就指定模型可以在配置里写好启动后直接生效。4. 启动 Agent 并验证服务响应请求与结果对照装好不等于跑通必须实际发一次请求看到模型返回内容才算部署成功。这一章给出完整的验证动作和预期结果。4.1 启动 Hermes 并进入交互模式在 WSL 终端执行hermes首次启动会加载配置、初始化 agent。如果配置正确你会看到类似Hermes Agent ready的提示然后进入一个交互式命令行。这时候可以直接输入问题比如你好请用一句话介绍你自己如果模型配置正确几秒内会返回一段文本。这就是最直接的验证Agent 能收到请求模型能返回响应。4.2 用 curl 直接验证 API 连通性如果你想绕过 Hermes单独验证 API 是否通可以用 curlcurl -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 foundhermes启动进入交互界面报配置错误交互提问模型返回文本无响应或报错curl API返回 JSON401/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/apiKey 在控制台生成Model ID 按需填写。这样无论是脚本调用还是工具集成都统一走一套认证。第四WSL 的环境要定期更新。sudo apt update sudo apt upgrade保持系统包最新uv 也用uv self update升级。依赖版本太旧有时会导致 Hermes 的某些功能异常。第五日志要留着。Hermes 运行时的报错信息是排查问题的关键建议把输出重定向到文件出问题时直接翻日志比凭记忆复现快得多。如果你还没生成 API Key可以去控制台创建想先体验模型对话效果可以直接用模型对话页面测试如果打算长期跑编码和 Agent 任务Coding Plan 会更合适。接入文档里有完整的参数说明和示例配置时对照着填就行。本地部署这件事跑通一次之后后面就是维护和调优了。