1. WSL2 Ubuntu 里装 Hermes Agent 到底卡在哪Node.js 版本冲突与 nvm 路径问题全复盘Hermes Agent 是一个跑在本地、通过 Web UI 操作的多模型智能体工具能接不同厂商的模型做对话、写代码、跑任务。它原生不支持 Windows官方推荐在 WSL2 的 Ubuntu 里装。听起来简单但真正动手你会发现从 WSL2 内核、Ubuntu 发行版、Node.js 版本到 nvm 环境变量每一步都可能给你一个报错。这篇就把我从零到跑通 Hermes Agent 的完整踩坑过程摊开讲重点解决两个最折磨人的问题——Node.js 版本冲突和 nvm 路径找不到。先说结论Ubuntu 20.04 默认源里的 Node.js 是 v10.19.0而 hermes-web-ui 要求 Node.js 23.0.0这个版本鸿沟是绝大多数安装失败的根源。再叠加 WSL2 挂载 Windows 磁盘导致 npm 读到 Windows 的 .npmrc 配置nvm 的 prefix 冲突就来了。下面按「环境准备 → nvm 装 Node → 装 Hermes → 配 TaoToken 通道 → 验证 → 排错」的顺序走一遍命令都能直接复制。适合谁看在 Windows 上用 WSL2 折腾过 Linux 环境、被 Node 版本和 nvm 路径坑过的开发者想本地跑 Hermes Agent 但卡在安装环节的人以及需要给 Hermes 配一个统一 API 通道、不想每个模型单独填 Key 的人。我试过最省事的路径其实是先把 WSL2 和 Ubuntu 弄干净再用 nvm 装 Node 23最后统一走 TaoToken 的 API 通道。下面一步步来。2. 前置准备WSL2 内核、Ubuntu 发行版与 TaoToken 统一 Key 的获取这一节把地基打牢。很多人一上来就npm install -g hermes-web-ui结果报WSL 1 is not supported回头再修 WSL2来回折腾。所以顺序很重要先确认 WSL2 正常再进 Ubuntu再装 Node最后才碰 Hermes。2.1 确认 WSL2 而不是 WSL1Hermes 明确不支持 WSL1。以管理员身份打开 PowerShell先看状态wsl --status wsl --set-default-version 2如果提示需要更新内核去下载wsl_update_x64.msi双击安装重启后再执行一次wsl --status确认默认版本是 2。装 Ubuntu 时指定版本wsl --install -d Ubuntu-20.04如果wsl --install报「无效的 install」说明系统版本太老先wsl --update。若wsl --update报「处理器类型不支持该安装程序包」多半是 CPU 虚拟化没开或系统架构不匹配去任务管理器 → 性能 → CPU看右下角「虚拟化」是否为「已启用」。没启用就进 BIOS 打开 VT-x/AMD-V。2.2 进 Ubuntu 后先别急着装 Hermes进入 Ubuntu 终端先更新源、装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y curl git build-essential这里有个坑Ubuntu 20.04 默认源的 Node.js 是 v10.19.0你sudo apt install -y nodejs npm装完就是这个老版本后面必然报wanted: {node:23.0.0}。所以别用 apt 装 Node直接用 nvm。2.3 拿 TaoToken 统一 KeyHermes 要调模型就得有 API 通道。与其每个厂商单独申请 Key、单独填 Base URL不如用 TaoToken 做统一入口——一个 Key 走所有模型Base URL 固定省得在 Hermes 里反复改配置。去官网注册后进控制台在 API Keys 页面创建一个 Key复制保存。这个 Key 后面会填进 Hermes 的模型配置里。Base URL 用https://taotoken.net/api注意这个地址不带任何查询参数。注册与控制台入口https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contenthermes_wsl2接入文档各模型 Base URL 与参数说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contenthermes_wsl2Key 拿到手先别急着填等 Hermes 装好、网关起来之后再配否则你分不清是安装问题还是配置问题。3. 可复制配置nvm 安装、Node 23 切换与 TaoToken settings 片段这一节是全文的核心操作区。nvm 路径问题和 Node 版本冲突都在这里解决。3.1 用 Gitee 镜像装 nvm直接curlGitHub 的 raw 地址在国内经常Connection refused换成 Gitee 镜像curl -o- https://gitee.com/mirrors/nvm/raw/v0.39.7/install.sh | bash装完重新开一个终端或者手动加载source ~/.bashrc nvm --version如果报Command nvm not found说明.bashrc没写入 nvm 的环境变量。手动补上echo export NVM_DIR$HOME/.nvm ~/.bashrc echo [ -s $NVM_DIR/nvm.sh ] . $NVM_DIR/nvm.sh ~/.bashrc source ~/.bashrc nvm --version3.2 配国内 Node 镜像并装 Node 23nvm 默认从 nodejs.org 下载慢且容易断。先设镜像export NVM_NODEJS_ORG_MIRRORhttps://npmmirror.com/mirrors/node nvm install 23 nvm use 23 node -v # 应显示 v23.x.x npm -v # 应显示 10.x.x把镜像写进.bashrc免得每次重设echo export NVM_NODEJS_ORG_MIRRORhttps://npmmirror.com/mirrors/node ~/.bashrc3.3 处理 Windows .npmrc 干扰nvm prefix 冲突nvm install 23时如果报Your project npmrc file (/mnt/c/Users/Administrator/.npmrc) has a globalconfig and/or a prefix setting, which are incompatible with nvm.这是因为 WSL2 挂载了 Windows 的 C 盘npm 读到了 Windows 用户目录下的.npmrc里面的prefix和 nvm 冲突。最干净的做法是把它备份移走mv /mnt/c/Users/Administrator/.npmrc /mnt/c/Users/Administrator/.npmrc.bak source ~/.bashrc npm -v如果nvm use --delete-prefix v23.11.1报Syntax error: ) unexpected那多半是 nvm 下载的 Node 二进制架构不对ARM64 装到了 x64 环境或者 WSL2 内核太老。先确认架构uname -m # 应为 x86_64是 x86_64 就重装一次 Nodenvm uninstall 23 nvm install 23 nvm use 233.4 装 Hermes 并写 TaoToken 配置Node 23 就位后装 Hermesnpm install -g hermes-web-ui hermes-web-ui start启动后进 Web UI在模型配置里填 TaoToken 的通道。Hermes 的模型配置本质是一段 JSON路径通常在~/.hermes/config.json或 Web UI 的模型设置页。可复制的片段如下把sk-你的Key换成控制台里复制的 Key{ provider: custom, base_url: https://taotoken.net/api, api_key: sk-你的Key, model: deepseek-v4-flash, models: [ { id: deepseek-v4-flash, name: DeepSeek V4 Flash }, { id: deepseek-v4-pro, name: DeepSeek V4 Pro } ] }如果你用的是 Claude Code 那套配置习惯对应的settings.json片段是{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }三件套记牢Base URL 填https://taotoken.net/apiKey 填控制台复制的Model ID 填你要用的模型名。三者缺一请求就会 401 或 404。4. 验证请求hermes 启动自检、端口监听与成功返回配置填完不代表通了得验证。这一节给你一套自检动作从进程、端口到实际请求逐层确认。4.1 确认进程和端口Hermes 正常跑起来应该有两个进程一个监听 8648Web UI 前端一个监听网关端口常见 3000 或其他。检查ps aux | grep hermes ss -tlnp | grep 8648 ss -tlnp | grep 3000如果只看到 8648 没有网关进程说明网关没起来。用带网关参数的方式重启hermes-web-ui start --gateway4.2 用 curl 直接验证 TaoToken 通道在配 Hermes 之前先用 curl 确认通道本身是通的这样能把「网络问题」和「Hermes 配置问题」分开curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的Key正常会返回一个模型列表 JSON类似{object:list,data:[{id:deepseek-v4-flash,object:model},{id:deepseek-v4-pro,object:model}]}看到这个列表说明 Key 和 Base URL 都没问题。如果这里就失败先解决通道问题别去动 Hermes。4.3 在 Web UI 里发一条测试消息回到 Hermes Web UI选一个模型输入一句简单的话比如「你好报一下你的模型名」。能正常返回就说明整条链路通了。第一次请求成功、第二次失败的情况多半是免费模型的速率限制不是配置问题后面排错节会讲。4.4 检查环境变量有没有代理干扰有时候 curl 通但 Hermes 不通是因为环境里残留了代理变量。查一下env | grep -i proxy如果返回了http_proxy或https_proxy而你的网络环境并不需要它就会导致 Hermes 内部请求走错出口。清掉unset http_proxy https_proxy all_proxy然后重启 Hermes 再试。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth 报错对照这一节把安装和运行中最容易撞上的报错逐个拆开给你对照表和回退动作。5.1 401 Unauthorized现象Web UI 里发消息返回 401或 curl 返回{error:{message:Invalid API key}}。原因基本是 Key 填错、Key 前后有空格、或者 Base URL 写成了带/v1的完整路径导致拼接重复。检查三件套配置项正确值常见错误Base URLhttps://taotoken.net/api多写/v1或带查询参数API Keysk-开头完整串复制时漏字符、带空格Model ID控制台列出的模型名自己编的模型名回退动作重新从控制台复制 KeyBase URL 严格用https://taotoken.net/apiModel ID 从/v1/models返回列表里挑。5.2 local proxy failed / Proxy error: fetch failed现象对话返回Error: API Error 502: {error:{message:Proxy error: fetch failed}}。这个报错的关键是「fetch failed」——Hermes 内部转发层没连上目标。先按 4.2 用 curl 测通道如果 curl 通、Hermes 不通那就是 Hermes 网关没启动。检查ps aux | grep hermes ss -tlnp | grep 3000网关没起来就hermes-web-ui start --gateway。如果网关起来了还报检查env | grep -i proxy有没有残留代理变量。5.3 reading choices / choices 相关报错现象返回里出现reading choices或Cannot read properties of undefined (reading choices)。这通常意味着返回体不是标准的 OpenAI 格式Hermes 解析choices字段时拿到 undefined。原因可能是 Base URL 指向了非兼容端点或者模型名不被通道识别返回了一个错误对象而不是正常响应。回退动作确认 Base URL 是https://taotoken.net/apiModel ID 用列表里真实存在的别用带:free后缀的第三方写法。5.4 OAuth / 认证相关报错现象出现OAuth字样或要求重新登录。Hermes 某些版本会走 OAuth 流程做设备认证。如果你用的是 API Key 模式确保配置里没有混入 OAuth 的字段。检查配置文件里是否有oauth、token_type之类的残留删掉后重启。如果确实需要 OAuth按接入文档里的说明走别自己拼参数。5.5 Node 版本与权限报错回退现象gyp ERR! configure error、EACCES: permission denied, mkdir /usr/local/lib/...、wanted: {node:23.0.0}。这三个是连在一起的用sudo npm install -g装到系统目录导致权限混乱同时 Node 版本太老触发 node-pty 重编译失败。回退动作# 别用 sudo用 nvm 装的 Node nvm use 23 npm install -g hermes-web-ui如果之前用 sudo 装过先清掉sudo npm uninstall -g hermes-web-ui nvm use 23 npm install -g hermes-web-ui5.6 速率限制 429现象第一次请求成功第二次返回HTTP 429: Provider returned error。这是免费模型的速率限制通常 10-20 请求/分钟。不是配置问题等一会儿再发或者换成付费模型。别在这个报错上反复改配置浪费时间。6. 长期跑 Hermes Agent 的通道选择从 API Key 到 Coding PlanHermes 装好、通道配通之后日常使用就是长期调模型了。如果你只是偶尔测一下用 API Key 按量付费就够但如果你打算把 Hermes 当日常编码助手、跑 Agent 任务请求量会上来这时候按量付费的成本和速率限制都会变成瓶颈。TaoToken 的 Coding Plan 就是为这种长期编码/Agent 场景准备的包月方式适合高频调用。你可以先去模型对话页试试不同模型的手感确定常用哪个再决定要不要上 Coding Plan。模型对话先试模型https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contenthermes_wsl2Coding Plan长期编码/Agenthttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contenthermes_wsl2API Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contenthermes_wsl2接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contenthermes_wsl2最后留一个我踩过的坑WSL2 里跑 Hermes别把项目放在/mnt/c/下文件 IO 会慢很多而且 Windows 的.npmrc会持续干扰。把工作目录放在 Ubuntu 的家目录里比如~/projects能省掉一堆莫名其妙的路径问题。网关进程记得用--gateway参数启动否则 Web UI 能开但对话一直 502。