1. 为什么要在 WSL 里跑 Hermes AgentWSLWindows Subsystem for Linux是 Windows 里跑 Linux 的一套子系统对开发者来说它最大的好处是不用装双系统、不用开虚拟机直接在 Windows 终端里就能用 Ubuntu 的命令行环境。而 Hermes Agent 是一个开源的终端 AI 助手项目装好之后你可以在命令行里直接跟模型对话、让它帮你读代码、写脚本、查资料相当于给终端配了个随叫随到的助手。这套组合适合谁适合平时主力用 Windows、但又想体验 Linux 开发环境的同学适合不想在本地折腾显卡和推理框架、只想接一个云端模型 API 就能用起来的开发者也适合像我这样喜欢在终端里干活、懒得切浏览器的人。整个流程的核心其实就两件事把 Hermes Agent 装进 WSL然后给它配一个能稳定调用的模型接口。前者容易卡在网络和依赖上后者容易卡在 Key 和端点上。这篇就把这两段路完整走一遍配置骨架直接给你命令可以照着敲。我用的环境是 WSL2 Ubuntu 22.04Windows 11。如果你还没装 WSL在 PowerShell 里执行wsl --install然后重启就行这一步不展开。下面默认你已经能进 Ubuntu 终端。2. 前置准备TaoToken 统一 Key 与 WSL 基础依赖在装 Hermes Agent 之前先把两件事办了一个是模型调用的入口一个是 WSL 里的基础工具链。模型入口这块我用的是 TaoToken 做统一接入。它的作用是给你一个兼容 OpenAI 风格的 API 地址和一把 Key你不需要为每个模型单独去注册、单独去记端点Hermes Agent 里只要把 base_url 和 api_key 指向它就行。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意这个地址后面不加任何参数。先去控制台把 Key 建出来入口是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。建好之后先复制下来后面配置要用。如果你还没想好接哪个模型可以先去模型对话页试试手感https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。WSL 这边先把基础依赖补齐。打开 Ubuntu 终端依次执行sudo apt update sudo apt upgrade -y sudo apt install -y curl git build-essential python3 python3-pipbuild-essential别省Hermes Agent 的部分依赖在编译阶段会用到 gcc 和 make缺了会在 pip 安装时报一堆看不懂的错。装完之后确认一下版本python3 --version git --version curl --version三条都能正常输出版本号前置就算过了。这里有个小提醒WSL 里的 Python 版本建议 3.10 以上Ubuntu 22.04 自带的 3.10 够用不用额外折腾 pyenv。3. 安装 Hermes Agentsettings.json 与 config.toml 骨架Hermes Agent 的安装方式官方给了脚本但脚本里会去拉 GitHub 上的资源网络不稳的时候容易断。我的做法是分步来哪一步断了就单独补哪一步。先装 uv它是 Hermes 用来管理 Python 依赖的工具比 pip 快很多curl -LsSf https://astral.sh/uv/install.sh | sh export PATH$HOME/.local/bin:$PATH装完把export PATH那行写进~/.bashrc不然新开终端又找不到 uv。然后克隆仓库用浅克隆减少数据量git config --global http.postBuffer 524288000 git clone --depth 1 https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent进目录装依赖cd ~/.hermes/hermes-agent uv sync依赖装完后Hermes 的配置分两层一层是settings.json管界面和运行行为一层是config.toml管模型和 provider。两个文件都在~/.hermes/下。先建settings.json{ theme: dark, editor: vim, auto_save: true, history_size: 500, stream: true, timeout: 60 }stream设成 true 是为了让回复逐字输出体验更接近聊天timeout给 60 秒避免网络慢的时候直接断掉。再建config.toml这是接 TaoToken 的关键[provider] name taotoken api_base https://taotoken.net/api api_key sk-你的TaoToken密钥 model gpt-4o-mini [agent] max_tokens 2048 temperature 0.7 system_prompt 你是一个运行在 WSL 终端里的 AI 助手回答尽量简洁代码给完整可运行版本。api_base一定写https://taotoken.net/api不要在后面加/v1或者别的路径加了反而会 404。model字段填你在 TaoToken 里能用的模型名不确定的话先去模型对话页确认一下再填。api_key换成你刚才建的那把。文件建好后给个权限避免读取时报权限错误chmod 600 ~/.hermes/config.toml4. 验证请求逐项命令与成功结果配置写完不能直接信得一步步验证。先验证网络到 TaoToken 通不通curl -s -o /dev/null -w %{http_code}\n https://taotoken.net/api返回 200 或者 401 都说明网络是通的401 只是没带 Key。如果这里就卡住或者超时先查 WSL 的 DNS编辑/etc/resolv.conf加上nameserver 8.8.8.8再试。接着验证 Key 能不能用直接发一个最小请求curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -d { model: gpt-4o-mini, messages: [{role: user, content: 只回复两个字通了}] }正常的话你会看到一段 JSONchoices里带着模型返回的内容。如果返回 401说明 Key 错了或者没带上返回 404八成是api_base写多了路径返回 429是频率限制等一会儿再试。接口通了之后再验证 Hermes 本身能不能读到配置cd ~/.hermes/hermes-agent uv run hermes config show这条命令会把当前生效的 provider、api_base、model 都打出来。确认api_base是https://taotoken.net/apimodel是你填的那个。都对上了就可以启动uv run hermes进去之后问一句“你是什么模型”能正常回你整条链路就通了。如果 Hermes 启动时报config.toml not found检查一下文件是不是建在了~/.hermes/而不是仓库目录里这是最容易搞混的一点。5. 本篇常见错排查装的过程中我遇到和见到的问题基本集中在这几类逐条对一下。第一类是Connection refused或者Failed to connect出现在克隆仓库或装 uv 的时候。这通常是网络到 GitHub 不稳解决办法是换镜像或者重试也可以先把仓库手动下载下来再解压到~/.hermes/hermes-agent。WSL 里如果 DNS 有问题ping github.com会直接失败这时候改/etc/resolv.conf加公共 DNS 往往能救回来。第二类是401 Unauthorized。这个几乎都是 Key 的问题要么 Key 复制的时候带了空格要么config.toml里api_key那行没加引号导致解析出错。检查方法是把 Key 单独用上面的 curl 命令测一遍curl 能通而 Hermes 不通那就是配置文件格式问题。第三类是404 Not Found。这个基本锁定在api_base上。TaoToken 的地址就是https://taotoken.net/api不要自作主张加/v1。有些工具默认会帮你拼/v1如果 Hermes 版本有这种行为就在配置里把 base 写成不带/v1的形式让它自己拼。第四类是ModuleNotFoundError或者依赖装不上。这多半是uv sync没跑完就中断了重新进目录跑一次uv sync即可。如果报编译错误回头确认build-essential装了没有。第五类是 Hermes 启动后回复很慢或者中途断流。把settings.json里的timeout调大到 120stream保持 true通常能缓解。如果还是断检查 WSL 的内存分配~/.wslconfig里给个 4GB 以上会稳很多。第六类是配置改了不生效。Hermes 有些版本会缓存配置改完config.toml后退出重进或者跑一次uv run hermes config reload如果版本支持。最稳的办法是直接uv run hermes config show看当前生效值别靠猜。6. 长期使用与接入文档如果你只是偶尔在终端里问两句上面这套配置就够了。但如果你打算把 Hermes Agent 当成日常编码助手长期用比如让它读项目、改代码、跑 Agent 任务那建议把模型调用单独规划一下。TaoToken 这边有 Coding Plan 可以看https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 适合需要稳定额度和多模型切换的场景。接入细节上如果遇到报错对不上直接翻接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面把端点、鉴权头、常见返回码都列了。另外如果你用的是 Claude Code 这类工具Anthropic 兼容的接法在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 有说明思路和这里一样把 base 和 key 换掉就行。最后说个我自己的习惯把~/.hermes/config.toml里的api_key不要写死改成从环境变量读然后在~/.bashrc里 export。这样换 Key 的时候只改一处也不怕配置文件被误传。Hermes 支持${TAOTOKEN_API_KEY}这种写法的话优先用它不支持就每次启动前 source 一下环境变量文件。终端里跑 AI 助手这件事配一次能管很久值得把这一步做干净。
