1. 为什么要在 Windows 原生跑 Hermes Agent
Hermes Agent 是 2026 年 GitHub 上增长最快的开源 AI 智能体框架之一，它能读写本地文件、执行命令、调用浏览器、串联多步任务，还能把成功经验沉淀成可复用的技能。过去在 Windows 上想用它，基本只有一条路：装 WSL2，进 Ubuntu，再按 Linux 那套流程走一遍。对不熟悉 Linux 的开发者来说，光是配 WSL2 的网络、文件权限、GPU 透传就能耗掉半天。
现在情况变了。官方在近几个版本合并了大量 Windows 适配补丁，Hermes Agent 已经可以在 PowerShell 里原生安装和运行，不需要 WSL2、不需要虚拟机、不需要 Docker。文件系统直接走 Windows 原生路径，浏览器自动化能直接调用本机 Chrome/Edge，本地模型也能对接 Ollama 或 LM Studio。对想快速体验、或者主要处理 Windows 本地文件的开发者来说，原生部署的体验明显更顺。
这篇手册面向的是：已经决定摆脱 WSL2、想在 PowerShell 里把 Hermes Agent 跑起来，并且希望用一套统一的 Key 通道完成模型调用的开发者。我会给出可复制的配置骨架、PowerShell 验证命令，以及安装后最容易踩的几个坑。核心检索词先记住：Windows 原生安装 Hermes Agent、PowerShell 配置、TaoToken 统一 Key、告别 WSL2。
需要提前说明的是，Hermes Agent 本身只是一个智能体框架，它自己不生产模型能力，必须接一个模型通道才能工作。所以安装只是第一步，真正让它跑起来的是后面的 Key 配置和通道接入。这也是本篇把「安装」和「统一 Key 配置」放在一起讲的原因——只装不配，等于装了个空壳。
2. 安装前的环境准备与 TaoToken 通道前置
2.1 系统与依赖检查
先确认你的机器满足基本要求。操作系统建议 Windows 11 22H2 及以上，Windows 10 2004 也能跑但兼容性补丁少一些。内存最低 8GB，想跑本地模型建议 32GB 起步。磁盘至少留 20GB。另外必须装 Git for Windows，因为 Hermes 内部很多 shell 操作依赖 Git Bash。
打开任务管理器（Ctrl+Shift+Esc），切到「性能」→「CPU」，看右下角「虚拟化」是否为「已启用」。大部分现代电脑默认开启，如果显示已禁用，需要进 BIOS 打开。
# 检查 PowerShell 版本，建议 7.x $PSVersionTable.PSVersion # 检查 Git 是否已安装 git --version # 检查 Python，Hermes 需要 3.11+ python --version如果 Git 没装，用 winget 一条命令搞定：
winget install Git.Git2.2 为什么需要 TaoToken 统一 Key
Hermes Agent 支持多种模型提供商，但如果你同时用 OpenAI、Anthropic、以及一些国产模型，就要维护多套 Key、多个计费入口、多份配置。切换模型时改配置很容易出错。TaoToken 的思路是提供一个统一的 API 通道，你只需要一个 Key，就能在同一个入口下调用不同厂商的模型，配置里只写一个 base_url 和一个 api_key。
对 Hermes 这种需要频繁切换模型做任务编排的框架来说，统一 Key 的价值很直接：config.toml 里不用堆一堆 provider 段落，换模型只改 model 字段，通道地址不动。后面我会给出完整的配置骨架。
先到官网注册并拿到 Key：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
登录后进入控制台创建 API Key：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite
Key 只在创建时完整显示一次，复制后先存到安全的地方。API 基础地址是 https://taotoken.net/api ，注意这个地址后面配置里要用到，不要多加斜杠或路径。
3. 可复制的安装与配置骨架
3.1 三种安装方式怎么选
官方提供了一键安装脚本，社区也有增强版脚本修复了 Windows 兼容性问题。我的建议是：如果你只是想快速跑起来，直接用社区增强版；如果你想了解每一步在做什么，走手动安装。下面三种都给出命令。
方式一，官方一键安装（管理员 PowerShell）：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.cmd -o install.cmd; .\install.cmd; del install.cmd方式二，社区增强版（推荐，自动修 UTF-8 编码和兼容性补丁）：
irm https://gist.githubusercontent.com/HoriLiu/e95d48009cf0d76e8f52a9009c0a79c4/raw/install-hermes-windows.ps1 | iex方式三，手动安装（适合需要自定义的开发者）：
# 安装 uv（快速 Python 包管理器） powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # 克隆仓库 git clone --recursive https://github.com/NousResearch/hermes-agent.git cd hermes-agent # 创建虚拟环境并安装依赖 uv venv .\.venv\Scripts\Activate.ps1 uv pip install -e . # 把 hermes 命令加入 PATH $hermesPath = "$pwd\.venv\Scripts" $env:PATH += ";$hermesPath" [Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")安装完成后必须关闭并重新打开 PowerShell，否则 hermes 命令不会生效。这一步很多人会忽略，然后报「命令找不到」。
3.2 config.toml 统一 Key 骨架
Hermes 的配置文件默认在%USERPROFILE%\.hermes\config.toml。下面是一个接入 TaoToken 统一通道的最小可用骨架，你可以直接复制后改 model 字段：
# ~/.hermes/config.toml [provider] name = "taotoken" base_url = "https://taotoken.net/api" api_key = "sk-你的TaoToken密钥" api_style = "openai" [agent] default_model = "claude-3-5-sonnet" max_tokens = 4096 temperature = 0.7 [features] browser_automation = false code_execution = true file_manipulation = true web_search = true [windows] shell = "C:\\Program Files\\Git\\bin\\bash.exe" encoding = "utf-8"几个关键点说明。api_style = "openai"表示用 OpenAI 兼容协议发请求，TaoToken 的统一通道兼容这种格式，所以大部分模型都能通过同一个 base_url 调用。default_model换成你想用的模型名即可，不用改 base_url。windows.shell指向 Git Bash，因为 Hermes 的代码执行功能依赖 bash，不配这个会报错。
如果你更习惯用 JSON 格式（部分版本支持 settings.json），等价骨架如下：
{ "provider": { "name": "taotoken", "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoToken密钥", "api_style": "openai" }, "agent": { "default_model": "claude-3-5-sonnet", "max_tokens": 4096, "temperature": 0.7 }, "windows": { "shell": "C:\\Program Files\\Git\\bin\\bash.exe", "encoding": "utf-8" } }3.3 环境变量方式（可选，更安全）
不想把 Key 明文写进配置文件的话，可以用环境变量。Hermes 会优先读环境变量：
# 当前会话生效 $env:TAOTOKEN_API_KEY = "sk-你的TaoToken密钥" $env:TAOTOKEN_BASE_URL = "https://taotoken.net/api" # 永久写入用户环境变量 [Environment]::SetEnvironmentVariable("TAOTOKEN_API_KEY", "sk-你的TaoToken密钥", "User") [Environment]::SetEnvironmentVariable("TAOTOKEN_BASE_URL", "https://taotoken.net/api", "User")然后在 config.toml 里把 api_key 留空或写成${TAOTOKEN_API_KEY}，让程序自己读环境变量。这样配置文件可以安全地放进 Git 仓库。
4. PowerShell 验证请求与成功结果
4.1 先用 curl 验证通道通不通
在配置 Hermes 之前，先用一条 curl 确认 TaoToken 通道能正常返回。这一步能帮你把「通道问题」和「Hermes 配置问题」分开排查：
$headers = @{ "Authorization" = "Bearer sk-你的TaoToken密钥" "Content-Type" = "application/json" } $body = @{ model = "claude-3-5-sonnet" messages = @( @{ role = "user"; content = "只回复两个字：通了" } ) max_tokens = 32 } | ConvertTo-Json -Depth 5 Invoke-RestMethod -Uri "https://taotoken.net/api/v1/chat/completions" ` -Method Post -Headers $headers -Body $body如果返回里能看到choices字段和模型回复内容，说明 Key 和通道都没问题。如果返回 401，检查 Key 是否复制完整；返回 404，检查 base_url 是否写成了https://taotoken.net/api（不要多加/v1之外的路径）。
4.2 启动 Hermes 并跑一次真实调用
通道验证通过后，启动 Hermes：
hermes第一次启动会进入配置向导，如果你已经手写了 config.toml，可以直接跳过向导。看到欢迎界面后，输入一句测试指令：
帮我读取当前目录下的文件列表，并总结有几个 .py 文件Hermes 会调用模型、执行文件操作、返回结果。如果它能正确列出文件并给出统计，说明安装、配置、通道三件事全部打通。这一步是整个流程的验收点，跑通了才算真正完成。
4.3 用 hermes 命令行做非交互验证
不想进交互界面的话，可以用一次性命令验证：
hermes run "用一句话说明你现在用的是哪个模型通道"返回内容里如果提到 TaoToken 或对应模型名，说明配置生效。这个方式适合写进 CI 或自动化脚本里做健康检查。
5. 本篇常见错误排查
5.1 OSError: [WinError 87] The parameter is incorrect
这是 Windows 原生版最常见的问题，出现在运行hermes gateway时。原因是代码里用了os.kill(pid, 0)这个 Linux/macOS 特有的写法，Windows 上不支持。
打开%USERPROFILE%\.hermes\hermes-agent\hermes_cli\gateway\status.py，找到所有os.kill(pid, 0)调用，替换为：
try: os.kill(pid, 0) except (ProcessLookupError, PermissionError, OSError, SystemError): return False或者直接用社区增强版安装脚本，它已经内置了这个修复。
5.2 UnicodeEncodeError: 'charmap' codec can't encode character
Windows 终端默认用 cp1252 编码，遇到 Hermes 界面里的 Unicode 字符就崩。两种解法。临时方案是每次运行前设环境变量：
$env:PYTHONIOENCODING = "utf-8"永久方案是以管理员身份改注册表，把系统默认编码设为 UTF-8：
reg add "HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage" /v ACP /t REG_SZ /d 65001 /f reg add "HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage" /v OEMCP /t REG_SZ /d 65001 /f改完重启电脑生效。
5.3 代码执行功能不工作
Hermes 默认用 bash 执行命令，Windows 上需要 Git Bash。确认 Git for Windows 已安装，然后把 Git Bash 的 bin 目录加进 PATH：
$env:PATH += ";C:\Program Files\Git\bin" [Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")同时检查 config.toml 里的windows.shell是否指向了正确的 bash.exe 路径。重启终端后再试。
5.4 hermes 命令找不到
安装脚本没把命令写进 PATH。手动补：
$hermesPath = "$env:USERPROFILE\.hermes\hermes-agent\.venv\Scripts" $env:PATH += ";$hermesPath" [Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")关掉 PowerShell 重新打开。如果还不行，用Get-Command hermes看系统能不能找到，找不到就说明路径写错了。
5.5 通道返回 401 或超时
先确认 Key 没有多余空格，再确认 base_url 是https://taotoken.net/api。如果公司网络有出口限制，检查是否能正常访问该域名。用第 4.1 节的 curl 命令单独测通道，能返回就说明是 Hermes 配置问题，不能返回就是网络或 Key 问题。
6. 长期编码与 Agent 场景的通道选择
如果你只是偶尔用 Hermes 跑几个任务，按上面的配置接统一 Key 就够了。但如果你打算把 Hermes 当成日常编码助手、或者用它跑长期的 Agent 自动化任务，调用频率和上下文长度都会上去，这时候更划算的做法是用 Coding Plan 这类面向长期编码场景的方案，把通道成本和额度管理统一起来。
配置入口在这里：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite
模型对话调试入口（想快速试不同模型效果时用）：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite
API Key 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite
接入文档（config.toml 字段含义、支持的模型列表都在这里）：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite
如果你用的是 Claude Code 或 Anthropic 风格的客户端，对应的接入说明在：https://taotoken.net/claude-code?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite
最后提醒一句：Hermes Agent 的 Windows 原生支持还在快速迭代，遇到报错先看官方仓库的 issue 区，很多问题社区已经给了补丁。配置改完后养成用第 4 节的 curl 命令先验通道的习惯，能把大部分「以为是 Hermes 坏了」的问题挡在门外。