1. hermes agent 在 Windows PowerShell 下的安装场景与痛点hermes agent 是一个可本地运行、支持多模型接入的智能体框架能帮你把对话、工具调用、会话记忆这些能力跑在自己的 Windows 机器上。它适合想折腾本地 Agent、又不想被单一模型厂商锁死的开发者尤其是习惯用 PowerShell 做自动化的人。但真到安装这一步很多人会卡在三个地方一是 PowerShell 和 CMD 的语法差异导致命令报错二是虚拟环境激活后hermes命令找不到三是默认 endpoint 指向官方地址在国内网络下请求经常超时或直接失败。我试过在一台干净的 Windows 11 上从零走一遍发现最耗时的不是装依赖而是把 endpoint 改到一条稳定、统一的 API 通道上。默认配置里 endpoint 写死在示例文件里改错一个字段就会在启动时报Connection error或者401 Unauthorized。所以这篇内容的核心不是教你“装个软件”而是把安装、目录规划、endpoint 改写、连通性验证串成一条能直接复制的流程。先明确几个关键路径后面所有命令都围绕它们展开项目代码目录D:\hermes-agent\统一数据目录D:\hermes\配置、日志、会话、缓存全在这里全局命令目录D:\hermes\local\bin\这样拆分的好处是以后升级代码只动hermes-agent你的配置和数据不会丢。下面从环境准备开始一步步来。在动手前确认你的 PowerShell 是管理员权限并且已经装了 Python 3.11 和 uv。uv 是一个比 pip 快很多的包管理器hermes agent 的依赖安装用它体验最好。如果没装 uv可以先执行powershell -c irm https://astral.sh/uv/install.ps1 | iex装完后关掉窗口重开输入uv --version能看到版本号即可。Python 版本建议 3.11太新的版本部分依赖轮子还没跟上容易在编译阶段报错。2. TaoToken 前置准备拿到统一 Key 与 endpoint在改配置之前你需要先有一条可用的 API 通道。TaoToken 提供统一的 Key 和 endpoint把不同模型的调用收敛到一个入口这样 hermes agent 里只需要配一次地址和密钥不用为每个模型单独改配置。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 API Key。具体操作路径进入控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 找到 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 新建一个 Key 并复制保存。这个 Key 只会完整显示一次丢了只能重建。拿到 Key 之后你需要记住两个值后面写进配置文件配置项值说明Base URLhttps://taotoken.net/api统一 API 入口不加 UTMAPI Keysk-开头的一串控制台生成妥善保存Model ID例如claude-sonnet-4-5按你实际要用的模型填如果你不确定该用哪个 Model ID可以先去模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 试跑一下确认模型能正常返回再把对应的 ID 写进 hermes 配置。这一步很关键因为 hermes agent 启动时会用配置里的 Model ID 去请求ID 写错会直接报model not found。另外如果你后续要做长期编码或 Agent 任务可以了解下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更适合高频调用场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 遇到字段疑问可以对照查。注意Base URL 用https://taotoken.net/api不要在后面加多余斜杠也不要带 UTM 参数否则部分客户端会拼接出错误路径导致 404。3. 可复制配置PowerShell 安装命令与 endpoint 改写这一节是全文的核心所有命令都可以直接复制到管理员 PowerShell 里执行。我按顺序拆成安装、目录、配置、快捷方式四块你跟着走就行。3.1 克隆项目与创建虚拟环境cd D:\ git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git cd hermes-agent uv venv venv --python 3.11 .\venv\Scripts\activate uv pip install -r requirements.txt uv pip install -e .[all]--recurse-submodules不能省hermes agent 有些能力放在子模块里漏了会在运行时报模块缺失。激活虚拟环境后命令行前面会出现(venv)前缀看到它才说明激活成功。3.2 创建统一数据目录New-Item -Path D:\hermes\cron -ItemType Directory -Force New-Item -Path D:\hermes\sessions -ItemType Directory -Force New-Item -Path D:\hermes\logs -ItemType Directory -Force New-Item -Path D:\hermes\memories -ItemType Directory -Force New-Item -Path D:\hermes\skills -ItemType Directory -Force New-Item -Path D:\hermes\pairing -ItemType Directory -Force New-Item -Path D:\hermes\hooks -ItemType Directory -Force New-Item -Path D:\hermes\image_cache -ItemType Directory -Force New-Item -Path D:\hermes\audio_cache -ItemType Directory -Force New-Item -Path D:\hermes\whatsapp\session -ItemType Directory -Force Copy-Item -Path D:\hermes-agent\cli-config.yaml.example -Destination D:\hermes\config.yaml New-Item -Path D:\hermes\.env -ItemType File -Force-Force的作用是目录已存在时不报错重复执行也安全。配置文件从示例复制一份到D:\hermes\config.yaml这样升级代码不会覆盖你的配置。3.3 改写 endpoint 到 TaoToken打开D:\hermes\config.yaml找到模型或 provider 相关段落把 base_url 和 api_key 改成 TaoToken 的值。如果你更习惯用环境变量管理密钥可以写进D:\hermes\.envTAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api HERMES_MODELclaude-sonnet-4-5然后在config.yaml里引用这些变量。一个最小可用的 provider 配置片段如下YAML 格式注意缩进用空格provider: name: taotoken base_url: https://taotoken.net/api api_key: ${TAOTOKEN_API_KEY} model: ${HERMES_MODEL} timeout: 60这里base_url就是统一入口api_key从环境变量读取避免明文写在配置里。timeout设 60 秒给长回复留足时间。如果你用的是 JSON 风格的配置部分版本支持等价写法是{ provider: { name: taotoken, base_url: https://taotoken.net/api, api_key: sk-你的Key, model: claude-sonnet-4-5, timeout: 60 } }改完后保存。记住三件套Base URL 是https://taotoken.net/apiKey 是控制台生成的sk-串Model ID 是你验证过能用的那个。这三者缺一不可任何一项写错都会在验证阶段暴露。3.4 创建全局命令与 PATHNew-Item -ItemType Directory -Path D:\hermes\local\bin -Force $target D:\hermes-agent\venv\Scripts\hermes.exe $link D:\hermes\local\bin\hermes.exe New-Item -ItemType HardLink -Path $link -Target $target -Force $env:PATH ;D:\hermes\local\bin [Environment]::SetEnvironmentVariable(PATH, $env:PATH ;D:\hermes\local\bin, User)硬链接的好处是虚拟环境里的可执行文件更新后全局命令自动指向新版本不用重新建链接。最后一行把目录写进用户级 PATH永久生效。4. 验证请求确认 endpoint 与模型都通配置改完先别急着跑复杂任务用最小请求验证连通性。关掉当前 PowerShell 重新打开让 PATH 生效然后hermes --version能打印版本号说明安装和全局命令都正常。接着验证 endpoint 是否真的指向 TaoTokenhermes config show这条命令会输出当前生效的 base_url 和 model。确认 base_url 显示为https://taotoken.net/apimodel 是你填的 ID。如果这里显示的还是默认地址说明config.yaml没被读取检查文件路径是否为D:\hermes\config.yaml以及环境变量HERMES_CONFIG是否指向了别处。再做一次真实请求验证hermes chat 用一句话说明你现在用的是哪个模型如果返回正常文本说明 Key、endpoint、model 三者都对上了。返回内容里通常会带上模型标识你可以据此确认请求确实走了 TaoToken 通道。实测下来第一次请求可能稍慢因为要建立连接和加载会话后续会快很多。如果返回的是错误先看错误类型401 UnauthorizedKey 错了或没读到检查.env是否被加载Key 是否有多余空格。404 Not Foundbase_url 拼错确认是https://taotoken.net/api没有多余斜杠或路径。model not foundModel ID 写错去模型对话页面确认正确 ID。Connection error/local proxy failed网络层问题检查本机网络和防火墙确认能访问taotoken.net。验证通过后你的 hermes agent 就已经跑在 TaoToken 统一通道上了。后续换模型只需要改HERMES_MODEL这一个变量不用动其他配置。5. 本篇常见报错排查这一节把安装和接入过程中最容易踩的坑集中列一下对照真实报错定位。报错一hermes : 无法将“hermes”项识别为 cmdlet这是 PATH 没生效。原因通常是设置完 PATH 后没重开窗口或者硬链接创建失败。先确认D:\hermes\local\bin\hermes.exe存在再执行$env:PATH看是否包含该目录。如果临时窗口里能用、新窗口不能用说明用户级环境变量没写成功重新执行[Environment]::SetEnvironmentVariable那行。报错二401 Unauthorized或invalid api keyKey 没被正确读取。检查D:\hermes\.env里TAOTOKEN_API_KEY的值确认没有引号、没有换行、没有多余空格。如果配置里直接写 Key确认sk-前缀完整。还有一种情况是 Key 被禁用或额度耗尽去控制台 API Keys 页面确认状态。报错三local proxy failed或Connection error这类报错指向网络层。先确认本机能正常访问https://taotoken.net/api可以用Invoke-WebRequest测一下Invoke-WebRequest -Uri https://taotoken.net/api -Method Head如果这里就失败说明网络不通检查防火墙或本机网络设置。如果这里通、hermes 里不通检查config.yaml的 base_url 是否被其他配置覆盖比如环境变量OPENAI_BASE_URL之类残留值。报错四reading choices或返回结构解析失败这通常说明请求发出去了但返回格式和客户端预期不一致。常见原因是 base_url 指向了错误的路径比如多加了/v1导致实际请求打到不存在的端点。确认 base_url 就是https://taotoken.net/api不要自行拼接版本路径。另外确认 Model ID 是 TaoToken 支持的模型不支持的 ID 可能返回非标准结构。报错五OAuth相关报错如果你之前配过其他需要 OAuth 的客户端环境里可能残留了认证配置导致 hermes 走了错误的认证流程。检查是否有~/.config下的旧凭据文件或者环境变量里残留的 token。清理后重新用 API Key 方式接入。报错六虚拟环境激活失败PowerShell 默认执行策略可能阻止脚本运行。如果.\venv\Scripts\activate报无法加载文件因为在此系统上禁止运行脚本执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned然后重新激活。这只影响当前用户安全性可控。排查时记住一个原则先确认配置读到了hermes config show再确认网络通Invoke-WebRequest最后确认 Key 和 Model 对。三步走下来绝大多数问题都能定位。6. 接入后的下一步与长期使用建议装好并验证通过后你可以把 hermes agent 当成一个本地常驻的 Agent 来用。日常调用直接hermes chat ...需要跑长任务时结合 Coding Plan 的额度会更划算。如果你要把它接到编辑器或自动化流程里接入文档里有完整的字段说明对照着改就行。几个实用建议一是把D:\hermes整个目录纳入你的备份范围会话和记忆都在里面换机器时直接拷过去就能续上二是 Key 不要写死在代码里用.env管理方便轮换三是升级 hermes-agent 代码时只git pull项目目录配置和数据不受影响。需要再确认模型能力或试新模型时去模型对话页面跑一下确认可用再把 ID 写进配置。控制台里可以随时查看用量和 Key 状态避免跑着跑着额度没了。整套流程走通后你就有了一条从 Windows PowerShell 到统一 API 通道的稳定链路后面换模型、加工具都只是改配置的事。