1. 为什么要在 Windows WSL 里跑 Hermes AgentHermes Agent 是一个能直接操作你电脑的 AI 智能体它不只是聊天还能执行命令、读写文件、跑代码、联网搜索并且把每次解决过的问题沉淀成技能下次自动复用。它由 Nous Research 维护属于开源 Agent 项目里比较活跃的一支。如果你平时主力机是 Windows又想让它稳定跑起来Windows WSL 环境是目前最省心的路径——WSL2 提供的是完整 Linux 内核Hermes 的 Gateway 服务依赖 systemd纯 Windows 下很多能力会被阉割虚拟机又太重所以 WSL2 基本是官方开发环境同款。这篇指南面向的是零基础但愿意照着敲命令的人。你不需要会 Linux不需要懂编程全程复制粘贴为主。我会把 Windows WSL 下从环境准备、依赖安装、模型接入到第一个任务跑通的完整链路拆开讲包括可复制的 WSL 配置片段、安装命令、验证步骤以及怎么通过 TaoToken 统一 Key 和 API 通道完成模型调用配置。整套流程走完你本地就有一个能用的 Agent 工作流。先说清楚它适合谁想在自己电脑上跑一个能动手干活的 AI 助手、又不想折腾双系统或云服务器的人做自动化脚本、批量文件处理、定时任务的人以及想研究 Agent 工具调用机制、技能系统怎么设计的开发者。如果你只是想找个聊天窗口那用网页版就够了没必要上 Hermes。我实测下来整个安装链路最容易卡住的不是 Hermes 本身而是三件事WSL2 的 systemd 没开、国内镜像源没配导致依赖下载超时、以及模型 API 通道没打通。这三块我会重点展开每一步都给验证命令确保你知道自己走到哪了、有没有走对。环境要求先对一遍Windows 10 2004 以上或 Windows 11按 WinR 输入 winver 能看到版本号CPU 支持虚拟化任务管理器性能页能看到「虚拟化已启用」内存建议 16GB 起8GB 能跑但会紧磁盘留 50GB 可用SSD 最好。软件栈是 WSL2 Ubuntu 22.04 LTS Node.js 22 LTS Python 3.10Hermes 安装脚本会自动建 Python 虚拟环境你只要保证系统层有 python3 和 venv 就行。下面从 WSL2 开始一步步来。2. TaoToken 前置准备统一 Key 与 API 通道在装 Hermes 之前先把模型调用通道准备好这样后面配置模型时直接填就行不用来回切平台。Hermes 支持 20 多家模型供应商但如果你想让配置简单、Key 管理统一用 TaoToken 做统一入口是比较顺的做法——一个 Key 走多个模型Base URL 固定切换模型只改 Model ID。TaoToken 是什么它是一个模型 API 聚合通道把不同厂商的模型调用统一成 OpenAI 兼容格式。对 Hermes 这种支持自定义 provider 的 Agent 来说你只要把 Base URL 指向它填一个 Key就能在配置里自由切换模型不用为每个厂商单独申请 Key、单独配环境变量。官网在 https://taotoken.netAPI 入口是 https://taotoken.net/api注意 API 地址不带查询参数配置时直接填这个。你需要准备的东西一个 TaoToken 账号登录后在控制台创建 API Key。控制台地址是 https://taotoken.net/consoleKey 管理在 https://taotoken.net/api-keys。创建完 Key 先复制保存页面关掉后一般不再完整显示。这个 Key 就是后面 Hermes 配置里要填的凭证。为什么建议用统一通道而不是每个厂商单独接Hermes 的 config.yaml 里 provider 配置是结构化的如果你接多个原生厂商每个都要写 base_url、api_key_env、model 列表改起来容易乱。用 TaoToken 的话provider 只配一个模型列表里想加哪个加哪个Model ID 按平台文档填。对新手来说少一层心智负担。这里要强调一点TaoToken 是正规的 API 聚合服务不是所谓的中转代理配置时按官方文档填 Base URL 和 Key 即可。如果你之前用过别的通道注意别把旧的环境变量名混进来Hermes 读的是它自己 .env 里的变量。模型选择上Hermes 对工具调用function calling支持要求比较高选模型时优先挑支持工具调用的。TaoToken 的模型列表里主流几家都支持具体 Model ID 以平台文档为准。文档入口在 https://taotoken.net/doc配置前扫一眼确认你要用的模型 ID 拼写正确这个后面排障会用到。Key 拿到后先别急着填进 Hermes等 Hermes 装完、跑完 setup 再填顺序是装 Hermes → 配 provider → 填 Key → 验证。这样出问题好定位。如果你在配置阶段想先验证 Key 本身能不能用可以走模型对话页面 https://taotoken.net/chat 发一条测试消息确认通道通了再往下走。另外提一句 Coding Plan如果你打算长期用 Hermes 做编码类任务、跑 Agent 工作流可以了解下 https://taotoken.net/coding-plan它面向的是高频编码场景和单次调用计费是两条线。新手先不用管把基础链路跑通再说。3. 可复制配置WSL2 Hermes TaoToken 接入这一节是核心所有配置片段都可以直接复制。顺序是开 WSL2 → 装 Ubuntu 22.04 → 配镜像源 → 装 Node.js → 装 Hermes → 配 TaoToken provider → 填 Key。先开 WSL2。以管理员身份打开 PowerShell 或终端执行wsl --install这条命令会一次性启用虚拟机平台、安装 WSL2 内核、把 WSL2 设为默认版本。执行完必须重启电脑不能跳过。重启后验证wsl --version wsl --status能看到版本号输出就说明 WSL2 就绪。如果 --status 提示默认版本不是 2执行wsl --set-default-version 2修正。接着装 Ubuntu 22.04wsl --install -d Ubuntu-22.04下载完会自动打开 Ubuntu 窗口提示Enter new UNIX username:输入全小写英文用户名回车然后输密码屏幕不显示字符是正常的输完回车再输一次确认。看到usernameDESKTOP-XXXX:~$就进 Linux 了。进系统先更新并装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git build-essential python3 python3-pip python3-venv然后开 systemd这是 Hermes Gateway 后台运行的前提。编辑sudo nano /etc/wsl.conf写入[boot] systemdtrueCtrlO 保存CtrlX 退出。回 PowerShell 执行wsl --shutdown等 10 秒重新打开 Ubuntu验证systemctl list-units --typeservice | head -10能列出服务就说明 systemd 生效。再开用户驻留防止关终端后 Gateway 被回收sudo loginctl enable-linger $USER loginctl show-user $USER | grep Linger应输出Lingeryes。配国内镜像源加速。备份后编辑 APT 源sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo nano /etc/apt/sources.list清空内容粘贴清华源deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy main restricted universe multiverse deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-security main restricted universe multiverse保存退出后sudo apt update看到从 tuna 下载就对了。再配 PyPI 源Hermes 依赖大量 Python 包mkdir -p ~/.config/uv cat ~/.config/uv/uv.toml EOF [pip] index-url https://pypi.tuna.tsinghua.edu.cn/simple extra-index-url [https://pypi.mirrors.ustc.edu.cn/simple/] EOF mkdir -p ~/.config/pip cat ~/.config/pip/pip.conf EOF [global] index-url https://pypi.tuna.tsinghua.edu.cn/simple extra-index-url https://pypi.mirrors.ustc.edu.cn/simple/ [install] trusted-host pypi.tuna.tsinghua.edu.cn pypi.mirrors.ustc.edu.cn EOF装 Node.js 22 LTS用 nvmcurl -o- https://gitee.com/mirrors/nvm/raw/master/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22 nvm alias default 22 node --version npm --version npm config set registry https://registry.npmmirror.com装 Hermescurl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash source ~/.bashrc hermes --version安装过程会问是否装 ripgrep 和 ffmpeg建议都选 Y前者加速文件搜索后者支持语音功能。装完跑健康检查hermes doctor现在配 TaoToken provider。Hermes 的配置在~/.hermes/config.yaml密钥在~/.hermes/.env。先编辑 config.yaml加入 provider 段model: provider: taotoken default: your-model-id providers: taotoken: base_url: https://taotoken.net/api api_key_env: TAOTOKEN_API_KEY api_style: openai models: - your-model-id - your-second-model-id把your-model-id换成你在 TaoToken 文档里确认过的 Model IDyour-second-model-id是可选的第二个模型。注意 base_url 填https://taotoken.net/api不带任何查询参数。然后编辑 .env 填 Keynano ~/.hermes/.env写入TAOTOKEN_API_KEY你的Key保存退出。验证配置hermes config check hermes doctor | grep -i taotoken到这里三件套就齐了Base URL 是https://taotoken.net/apiKey 在 .env 的TAOTOKEN_API_KEYModel ID 在 config.yaml 的model.default。这三个值后面排障会反复对照。4. 验证请求跑通第一个 Agent 任务配置填完不代表通了必须发真实请求验证。先做最小验证单次问答hermes chat -q 用中文告诉我你是什么模型能做什么如果返回正常中文回答说明 Base URL、Key、Model ID 三者都对上了。如果报错先别改配置看下一节的排障对照。接着验证工具调用这是 Agent 和普通聊天的区别。让它执行一个只读命令hermes chat -q 列出当前目录下的文件并告诉我系统内核版本正常的话它会调用 terminal 工具返回文件列表和uname -r的结果。这一步能过说明工具链是通的。再验证文件读写。建个测试目录mkdir -p ~/hermes-test cd ~/hermes-test hermes chat -q 在当前目录创建一个 hello.txt内容写 Hermes 跑通了然后读出来确认跑完cat hello.txt看内容对不对。这一步验证的是 file 工具。然后验证会话记忆。先起一个交互式会话hermes在交互界面里输入记住我的项目路径是 ~/hermes-test退出后重新进问它「我的项目路径是什么」能答出来说明 memory 工具和会话持久化正常。交互界面里/new开新会话/quit退出/model看当前模型/reasoning medium调推理深度。最后验证 Gateway 后台服务这是多平台接入的基础hermes gateway install hermes gateway start hermes gateway status看到active (running)就对了。如果这里失败八成是 systemd 或 linger 没配好回第 3 节检查。全部验证通过后你本地就有了一个可用的 Agent 工作流终端里hermes直接对话hermes chat -q做单次任务hermes cron create挂定时任务Gateway 在后台待命。想接飞书、微信这类平台在 Gateway 基础上配对应适配器即可那是下一步的事。验证阶段建议按顺序来先单次问答再工具调用再文件读写最后 Gateway。哪一步断了就停在那排查别跳步不然出问题不知道是哪层。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错对照每条都给定位方法和修复动作。Hermes 的日志在~/.hermes/logs/Gateway 日志是gateway.log排障先看日志。401 Unauthorized / authentication failed。这是 Key 问题。先确认 .env 里的变量名和 config.yaml 里api_key_env写的一致都是TAOTOKEN_API_KEY。然后直接测 Keycurl -s https://taotoken.net/api/models \ -H Authorization: Bearer $(grep TAOTOKEN_API_KEY ~/.hermes/.env | cut -d -f2) \ | head -20返回 401 说明 Key 无效或过期去 https://taotoken.net/api-keys 重新创建。返回模型列表说明 Key 没问题那问题在 Hermes 配置读取检查 config.yaml 缩进YAML 对缩进敏感provider 段和 model 段层级别写错。local proxy failed / connection refused。这个报错通常是 base_url 写错或网络不通。确认 config.yaml 里是https://taotoken.net/api没有多余斜杠、没有查询参数。然后测连通性curl -sI https://taotoken.net/api能返回 HTTP 头说明网络通。如果这里就失败检查 WSL 的 DNScat /etc/resolv.conf看有没有正常 nameserver必要时在/etc/wsl.conf里加[network] generateResolvConftrue后wsl --shutdown重启。Error reading choices / invalid response format。这个报错说明请求发出去了但返回结构 Hermes 解析不了。常见原因是 Model ID 填错或者选的模型不支持 OpenAI 兼容的返回格式。回 config.yaml 核对model.default的拼写去 https://taotoken.net/doc 对照文档里的 Model ID。另外确认api_style: openai没写错。如果换了模型就好说明是模型兼容性问题换一个支持工具调用的模型。OAuth / token expired。如果你在配置里误用了需要 OAuth 的 provider 配置会走到这条路径。TaoToken 走的是 API Key 模式不需要 OAuth。检查 config.yaml 里 provider 段有没有残留的oauth字段删掉。同时确认 .env 里没有旧的 OAuth token 变量干扰。hermes: command not found。PATH 没加载source ~/.bashrc echo export PATH$HOME/.hermes/bin:$PATH ~/.bashrc source ~/.bashrc which hermesGateway 关终端就停。三个条件缺一不可systemd 开了、linger 开了、D-Bus 套接字正常。前两个第 3 节配过D-Bus 在 WSL 里偶发问题在~/.bashrc末尾加if [ -z $DBUS_SESSION_BUS_ADDRESS ] [ ! -S /run/user/$(id -u)/bus ]; then export DBUS_SESSION_BUS_ADDRESSunix:path/run/user/$(id -u)/bus fi重开终端后hermes gateway install hermes gateway start再systemctl --user status hermes-gateway确认。依赖安装超时。回第 3 节确认 uv.toml 和 pip.conf 都配了然后手动补cd ~/.hermes/hermes-agent source venv/bin/activate pip install -e .[all] --index-url https://pypi.tuna.tsinghua.edu.cn/simple hermes doctor排障的核心思路是分层先确认 Key 本身能用curl 直测再确认 Hermes 读到了配置config check最后确认模型返回格式兼容换模型试。大部分报错落在第一层和第二层之间也就是配置读取环节YAML 缩进和变量名是重灾区。6. 把 Hermes 用起来从跑通到日常跑通之后日常使用其实就几条命令。终端里直接hermes进交互模式适合多轮对话和探索hermes chat -q 任务适合脚本里调用hermes --continue接着上次会话聊。工具管理用hermes tools list看清单hermes tools enable web开联网hermes tools disable browser关掉不用的。技能系统是 Hermes 的特色hermes skills browse逛技能市场hermes skills install ID装装完它会自动在合适场景调用。定时任务是很多人忽略的实用功能hermes cron create 0 9 * * * --prompt 总结昨天的会话列出待办 hermes cron list这条会每天早上 9 点自动跑一次结果存在会话里。配合 Gateway 后台服务等于你有个 7×24 在线的助手。维护上每周hermes update hermes skills update每月hermes sessions prune清旧会话hermes insights --days 30看用量。API Key 别提交到 Git别截图分享定期在 TaoToken 控制台检查使用情况。备份就两条cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak cp ~/.hermes/.env ~/.hermes/.env.bak如果你后面想接飞书、微信这类平台在 Gateway 基础上加适配器配置逻辑和本篇的 provider 配置类似都是 Base URL Key Model ID 三件套的思路。先把终端这条链路用熟再扩展平台不容易乱。最后给个实用建议把hermes doctor设成每周固定动作它会把配置、依赖、Key、Gateway 状态一次性体检比出问题再查快得多。Agent 这类工具配置一次跑通后真正的价值在于你持续用它干活、沉淀技能而不是装完就放着。