1. 为什么 Windows 上跑 Hermes Agent 总卡在第一步Hermes Agent 是 Nous Research 开源的一个终端 AI Agent 框架社区里常把它叫做“开源版 Claude Code”。它能读写文件、执行终端命令、做浏览器自动化、生成和调试代码还能把任务委托给子流程。你给它一句自然语言它在终端里把活干完。适合谁适合想在本地跑 Agent、又不想把代码和数据交给云端的人尤其是手里有 Windows 机器加一块还不错的显卡的开发者。但它的官方文档写得很直白原生 Windows 不被支持必须走 WSL2。这一句话就劝退了不少人。我见过太多人卡在“装完了但连不上模型”这一步最后放弃。问题不在 Hermes Agent 本身而在 Windows 和 WSL2 之间的网络是隔离的——WSL2 里的 localhost 不指向 Windows 宿主机Ollama 默认又只监听 127.0.0.1两边根本握不上手。这篇就按真实链路走一遍WSL2 环境准备、Ollama 本地模型拉取、把 settings 配置改到 TaoToken 统一 Key/API 通道最后给出可复制的配置片段和逐项报错排查清单。核心检索词就三个Hermes Agent、Windows、WSL2、Ollama 本地模型配置。你跟着做一次跑通的概率会高很多。先说清楚整体流程心里有张图Windows 端 WSL2 内 │ │ ├─ 1. 安装 WSL2 ───────────────────→ 已有 Ubuntu │ │ ├─ 2. 安装 Ollama ├─ 3. 安装 Hermes Agent │ (监听 0.0.0.0) │ │ │ ├─ 4. 开放防火墙端口 11434 ←────────┤ │ │ └─ 5. 配置 Hermes 连接 Ollama ──────┘ ▼ hermes chat 启动这张图里第 4、5 步是重灾区。社区反馈里大约九成的配置问题都出在 WSL2 与 Windows 的网络互通上。所以下面我会把网络打通单独拎出来讲透而不是一笔带过。环境要求先对一下别到一半发现机器带不动项目最低要求推荐配置操作系统Windows 10 64-bit (2004)Windows 11WSL2必须安装必须安装内存8 GB16 GB显卡显存8 GB7B 模型16 GB30B 模型磁盘空间20 GB50 GB显存这块要提醒一句7B 模型量化后大概吃 6 GB 显存32B 模型要 20 GB 左右。如果你只有 8 GB 显存就老老实实从 7B 起步别硬上 32B否则 Ollama 会直接 OOM 退出报错还不好定位。2. TaoToken 前置把统一 Key 和 API 通道准备好在动手装 Hermes Agent 之前先把模型通道这件事想清楚。本地 Ollama 适合离线、免费、数据不出本机但 32B 本地模型在 Agent 任务上的综合表现和云端大模型还是有明显差距。Hermes Agent 的效果高度依赖底层模型能力所以更实用的做法是本地 Ollama 和云端 API 两条腿走路日常轻量任务走本地复杂 Agent 任务切到云端。TaoToken 在这里扮演的角色就是给你一个统一的 Key 和 API 通道把模型调用收敛到一个入口。你不用在 Hermes 里维护一堆不同厂商的 Key改配置时只改一处 base_url 和 model 就行。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置里填的就是这个干净地址。你需要提前准备三样东西后面配置里会反复用到第一是 API Key。登录后进控制台在 API Keys 页面创建一个复制出来存好。这个 Key 就是 Hermes 调用模型时的凭证别泄露。第二是 Base URL。Hermes 走的是 OpenAI 兼容协议所以 base_url 填 https://taotoken.net/api/v1 。注意末尾的 /v1 不能少很多“连不上”的报错就是漏了这段路径。第三是 Model ID。这个取决于你想用哪个模型在模型列表里挑一个把准确的模型名记下来。填错模型名会直接返回 404 或 model not found。如果你打算长期跑编码类 Agent 任务可以顺手看一下 Coding Plan它更适合高频、长时间的编码场景如果只是想先验证模型能不能通用模型对话页面测一下最快。这几个入口分别是模型对话https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel-chatCoding Planhttps://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan控制台https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsoleAPI Keyshttps://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys接入文档https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc这里有个关键点要讲明白Hermes Agent 的配置文件里模型通道是分 provider 的。本地 Ollama 是一个 custom endpointTaoToken 是另一个 OpenAI 兼容 endpoint。你可以两个都配用 hermes model 命令切换。这样既保留了本地离线的能力又能在需要强模型时一键切到云端。注意TaoToken 是合规的 API 聚合通道配置时只填 base_url 和 Key不要在任何地方写代理相关的东西。Hermes 的 git 配置里如果之前设过代理记得清空否则克隆会失败。3. 可复制配置WSL2、Ollama 与 settings 全片段这一节是全文的核心所有命令和配置都可以直接复制。我按执行顺序排好你从上往下走。3.1 安装 WSL2 并迁移到非 C 盘以管理员身份打开 PowerShell执行wsl --install这条命令默认装 Ubuntu重启后按提示设置用户名和密码。装完先看状态wsl --list --verboseWSL2 默认把虚拟磁盘放在 C 盘的 %AppData% 下模型体积一大C 盘很快就满。强烈建议迁到非系统盘以 G 盘为例# 创建目标目录 New-Item -ItemType Directory -Path G:\WSL\Ubuntu -Force # 导出备份 wsl --export Ubuntu G:\WSL\ubuntu-backup.tar # 注销原有实例 wsl --unregister Ubuntu # 重新导入到 G 盘 wsl --import Ubuntu G:\WSL\Ubuntu G:\WSL\ubuntu-backup.tar --version 2导入后默认是 root 登录需要建普通用户# 进入 WSL wsl -d Ubuntu # 创建用户yourname 换成你的用户名 useradd -m -s /bin/bash yourname passwd yourname usermod -aG sudo yourname # 设置默认用户 echo -e [user]\ndefaultyourname /etc/wsl.conf重启 WSL 生效wsl --terminate Ubuntu wsl -d Ubuntu3.2 在 WSL2 里安装 Hermes Agent先更新依赖再配 Git 参数防止克隆中断sudo apt update sudo apt install -y ripgrep ffmpeg git config --global http.postBuffer 524288000 git config --global http.proxy git config --global https.proxy 执行安装脚本cd ~ curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash如果脚本因网络问题失败手动克隆rm -rf ~/.hermes/hermes-agent git clone --depth1 https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent装 Python 依赖。如果提示 uv: command not found先装 uvcurl -LsSf https://astral.sh/uv/install.sh | sh source ~/.bashrc cd ~/.hermes/hermes-agent export PATH$HOME/.local/bin:$PATH uv venv venv --python 3.11 export VIRTUAL_ENV$(pwd)/venv UV_HTTP_TIMEOUT300 uv pip install -e .[messaging,cron,cli,mcp,pty]创建全局命令软链接ln -sf ~/.hermes/hermes-agent/hermes ~/.local/bin/hermes echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrc hermes version3.3 安装 Ollama 并拉取本地模型在 Windows 端装 Ollama装完托盘会出现图标。拉模型时用实际存在的标签ollama pull qwen2.5:7b ollama pull qwen2.5:32b ollama pull deepseek-r1:32b ollama pull qwen2.5-coder:7bOllama 默认上下文较小需要扩上下文就建自定义模型FROM qwen2.5:32bnPARAMETER num_ctx 32768 | Out-File -FilePath Modelfile -Encoding utf8 ollama create qwen2.5-32b-32k -f Modelfile3.4 打通 WSL2 到 Windows Ollama 的网络这是最关键的一步。让 Ollama 监听所有接口管理员 PowerShell[System.Environment]::SetEnvironmentVariable(OLLAMA_HOST, 0.0.0.0, User)然后彻底重启 Ollama托盘右键退出再启动验证监听netstat -an | findstr 11434 # 预期TCP 0.0.0.0:11434 0.0.0.0:0 LISTENING加防火墙放行规则New-NetFirewallRule -DisplayName Ollama WSL -Direction Inbound -Protocol TCP -LocalPort 11434 -Action Allow检查并删除可能存在的阻止规则这一步很多人漏掉Get-NetFirewallRule -DisplayName *Ollama* | Format-Table DisplayName, Enabled, Direction, Action Get-NetFirewallRule -DisplayName ollama.exe | Where-Object {$_.Action -eq Block} | Remove-NetFirewallRule在 WSL 里测试连接HOST_IP$(ip route | grep default | awk {print $3}) echo $HOST_IP curl http://$HOST_IP:11434/api/tags能返回模型列表就说明通了。3.5 settings 配置改到 TaoTokenHermes 的配置文件在 ~/.hermes/config.yaml。先看本地 Ollama 的配置再叠加 TaoToken 通道。下面是一份可直接参考的配置片段路径和字段名按实际文件为准# ~/.hermes/config.yaml providers: - name: local-ollama type: openai-compatible base_url: http://172.27.112.1:11434/v1 api_key: model: qwen2.5-32b-32k:latest context_length: 65536 - name: taotoken type: openai-compatible base_url: https://taotoken.net/api/v1 api_key: 你的_TaoToken_API_Key model: 你的_Model_ID context_length: 65536 default_provider: local-ollama如果你更习惯用交互式配置执行hermes model选 More providers... → Custom endpoint然后填API base URLhttp://你的宿主机IP:11434/v1API key留空Model nameqwen2.5-32b-32k:latestContext length32768切到 TaoToken 时base URL 填 https://taotoken.net/api/v1 API key 填你的 KeyModel name 填对应模型 ID。三件套就是 Base URL Key Model ID缺一不可。用 sed 批量改 base_url 时要小心确保 URL 里带 /v1HOST_IP$(ip route | grep default | awk {print $3}) sed -i s|http://[^/]*:11434|http://$HOST_IP:11434/v1|g ~/.hermes/config.yaml grep -E base_url|model ~/.hermes/config.yaml3.6 修复上下文窗口限制Hermes Agent 要求最低 64K 上下文本地模型默认 32K不改会拒绝启动sed -i s/context_length: 32768/context_length: 65536/ ~/.hermes/config.yaml grep context_length ~/.hermes/config.yaml这只是绕过启动检查实际模型还是 32K 能力。显存够的话在 Modelfile 里把 num_ctx 设成 65536生成真正的 64K 模型。4. 验证请求从 hermes doctor 到成功对话配置改完别急着 chat先跑健康检查hermes doctor它会逐项检查依赖、配置、模型连通性。确认没有 error 再启动hermes chat启动成功后终端会显示 ASCII 标题和可用工具列表。状态栏长这样qwen2.5-32b-32k:latest | 16.7K/65.5K | [###.......] 26% | 5m从左到右是当前模型 / 已用 token / 总上下文 / 占用比例 / 会话时长。验证 TaoToken 通道是否通最直接的办法是切过去发一条指令hermes model taotoken hermes 用 Python 写一个读取 CSV 并统计行数的脚本如果返回正常代码说明 Key、Base URL、Model ID 三件套都对。想单独验证 API 通道可以用 curlcurl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的_TaoToken_API_Key \ -H Content-Type: application/json \ -d { model: 你的_Model_ID, messages: [{role: user, content: ping}] }返回带 choices 的 JSON 就说明通道没问题。常用命令速查命令说明hermes chat进入交互式对话hermes 写一个爬虫执行单次任务hermes doctor全面健康检查hermes model交互式切换模型hermes model qwen2.5:7b快速切到指定模型5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错对照遇到问题直接查。401 UnauthorizedTaoToken 通道报 401基本是 Key 错了或没带 Bearer 前缀。检查 config.yaml 里 api_key 是否完整有没有多余空格。如果 Key 是从控制台复制的注意别把换行带进去。local proxy failed / connection refusedWSL 里 curl Ollama 报 Connection refused说明 Ollama 没监听 0.0.0.0。回到 3.4 节检查 OLLAMA_HOST 环境变量然后彻底重启 Ollama不是关窗口是托盘右键退出再启动。Connection timed out一般是防火墙拦截。Windows 防火墙有时会为 ollama.exe 自动创建阻止规则而阻止规则优先级高于允许规则。按 3.4 节的命令查出来删掉。reading choices 报错 / 返回体解析失败通常是 base_url 漏了 /v1或者模型返回了非预期格式。确认 base_url 是 https://taotoken.net/api/v1 Model ID 填的是准确名称。模型名写错会返回 model not found不会返回 choices。OAuth 相关报错如果你在配置里误开了需要 OAuth 的 providerHermes 会尝试走授权流程然后失败。本地 Ollama 和 TaoToken 都是 API Key 模式不需要 OAuth检查配置里有没有多余的 auth 字段。hermes 命令找不到软链接没建好或 PATH 没生效。重新执行ln -sf ~/.hermes/hermes-agent/hermes ~/.local/bin/hermes export PATH$HOME/.local/bin:$PATH source ~/.bashrcuv: command not found先装 uv再装依赖顺序别反。Python 依赖安装超时加大超时时间UV_HTTP_TIMEOUT300 uv pip install -e .[messaging,cron,cli,mcp,pty]WSL 导出备份找不到 ext4.vhdx虚拟磁盘损坏直接按 3.1 节的重建方法下载 rootfs 重新导入。ollama pull 失败模型标签不存在。别用 qwen3.5:35b 这种不存在的名字改用 qwen2.5:32b 或 deepseek-r1:32b。上下文窗口过小拒绝启动按 3.6 节改 context_length 到 65536。排查顺序建议先 hermes doctor再 curl 测 Ollama再 curl 测 TaoToken最后才怀疑 Hermes 本身。大部分问题都在网络和配置路径上不在框架代码里。6. 长期跑 Agent 任务通道怎么选跑通之后你会面临一个实际选择本地 Ollama 还是 TaoToken 通道。我的经验是分场景用。本地 Ollama 的优势是离线、免费、数据不出本机。适合日常轻量任务、隐私敏感的文件处理、以及网络不稳定时的兜底。7B 模型响应快32B 模型质量更好但吃显存。缺点是 Agent 任务上本地模型和云端强模型差距明显复杂任务容易跑偏。TaoToken 通道的优势是模型能力强、切换方便、不用管显存。适合复杂编码、长链路 Agent 任务、需要强推理的场景。配置上就是 Base URL Key Model ID 三件套改一处就能切模型。如果你打算长期高频跑编码类 Agent可以看下 Coding Plan它针对长时间编码场景做了优化。想先验证模型效果用模型对话页面最快。接入细节都在接入文档里API Keys 在控制台创建。最后给个实用技巧把两个 provider 都写进 config.yaml用 hermes model 切换别每次手动改文件。本地跑不通的时候切云端云端额度用完切本地两条腿走路最稳。跑通之后你会发现Hermes Agent 真正好用的地方在于它把终端、文件、浏览器串成了一条流水线你只需要说清楚要什么。