别急着装 Hermes Agent：Windows 上这 7 个坑，我替你踩完了

兮动人

2026-08-24 01:43

阅读27

兮动人

2026-08-24 01:43

阅读 27

欢迎关注我的公众号【兮动人】，每天分享一些技术文章和实战经验。

从安装目录、安全软件、GitHub 代理，到 402 额度、模型列表和“只会说英文”的真相。这不是一份照着官网抄的教程，而是一份真实的排错复盘。

公众号封面

我原本以为，这件事最多十分钟：下载一个 Windows 安装包，填入 API Key，然后开始聊天。

结果整整绕了一大圈。

安装器默认往 C 盘写，界面又没有选择目录；GitHub 在浏览器里明明能打开，安装脚本却一直超时；腾讯电脑管家已经加了信任区，uv 生成的临时程序还是运行失败；好不容易装完，Hermes 的模型列表里只有一个 Hy3；手动切到一个仍有额度的模型后，它倒是不报错了，却无论我说什么都只回一句英文：

I'm ready to help! What would you like me to assist you with?

最后真正跑通时，Hermes 被完整安装在 E:\Hermes，模型接入腾讯 TokenHub，并且可以在 qwen3.5-plus 和 qwen3.5-flash 之间切换。

回头看，最浪费时间的并不是报错本身，而是几个很容易混在一起的概念：安装包的位置不等于安装目录；浏览器能访问 GitHub 不等于 Git 能访问；账号有额度不等于当前服务有额度；配置文件改了不等于当前会话已经切换。

这篇文章就把这几个坑一次讲清楚。

一、Windows 安装包和 PowerShell 安装，到底有什么区别？

Hermes 官网同时提供 Windows 安装包和 PowerShell 安装方式。

Hermes 官方安装说明

Hermes Windows 下载入口

表面上看，它们像是两套完全不同的安装方案。实际跑过日志后会发现，Windows 安装包更像一个图形化的 bootstrapper（引导安装器）：

下载 install.ps1；
安装或检测 uv、Python、Git、Node.js；
获取 Hermes 仓库；
创建虚拟环境并安装依赖；
构建桌面应用；
写入配置并启动后端。

所以，两者安装出来的核心 Hermes 并没有本质区别。差异主要在体验：安装包有进度界面，PowerShell 更透明，也更容易传入环境变量和观察报错。

我的建议是：

想省事，可以用 Hermes-Setup.exe；
想改安装目录、配置代理或排错，最好从 PowerShell 启动安装包；
普通用户权限通常就够了，不必一开始就用管理员 PowerShell。

二、第一个坑：安装包放在 E 盘，不代表 Hermes 会装在 E 盘

我的安装包位于：

▼
text
复制代码
E:\浏览器下载\Hermes-Setup.exe

但直接双击，Hermes 仍会使用默认目录。真正决定数据、配置、运行时和仓库位置的，是环境变量 HERMES_HOME。

我最后成功安装到 E 盘时，实际执行的是下面这组完整命令。它不只指定了 Hermes 的安装目录，还把安装过程中用到的临时文件放到了 E 盘，并让 Git/Python、npm 和 Electron 下载器都走同一个代理：

▼
powershell
复制代码
$proxyUrl = 'http://127.0.0.1:7897'
$targetPath = 'E:\Hermes'
$tempPath = 'E:\HermesTemp'

New-Item -ItemType Directory -Path $tempPath -Force | Out-Null

$env:HERMES_HOME = $targetPath
$env:TEMP = $tempPath
$env:TMP = $tempPath

# Git、Python 和普通网络请求
$env:HTTP_PROXY = $proxyUrl
$env:HTTPS_PROXY = $proxyUrl
$env:ALL_PROXY = $proxyUrl
$env:NO_PROXY = 'localhost,127.0.0.1'

# npm
$env:npm_config_proxy = $proxyUrl
$env:npm_config_https_proxy = $proxyUrl

# Electron 下载器
$env:ELECTRON_GET_USE_PROXY = '1'
$env:GLOBAL_AGENT_HTTP_PROXY = $proxyUrl
$env:GLOBAL_AGENT_HTTPS_PROXY = $proxyUrl
$env:GLOBAL_AGENT_NO_PROXY = 'localhost,127.0.0.1'

Start-Process -FilePath 'E:\浏览器下载\Hermes-Setup.exe' -Wait

这段命令可以整段复制到 PowerShell 运行，不要求管理员权限。7897 是我当时本机代理软件监听的端口，其他人照着操作时，要换成自己代理软件显示的端口；如果网络可以直接访问 GitHub，也可以删掉所有代理相关的环境变量，只保留安装目录、临时目录和最后一行启动命令。

安装成功后，目录大致会变成：

▼
text
复制代码
E:\Hermes\
├─ bin\
├─ node\
├─ logs\
├─ sessions\
├─ config.yaml
├─ .env
└─ hermes-agent\

日志也证明，便携版 Node.js、uv、Python 虚拟环境和 Hermes 仓库都被放进了这个根目录。

可以用下面的命令检查用户级环境变量是否已经保存：

▼
powershell
复制代码
[Environment]::GetEnvironmentVariable('HERMES_HOME', 'User')

这里最容易产生的误解是：安装包在哪个盘，和软件最终安装在哪个盘，没有必然关系。

三、第二个坑：浏览器能打开 GitHub，安装器照样可能连不上

安装日志里先后出现了三种情况：

▼
text
复制代码
git@github.com: Permission denied (publickey)
Could not resolve host: github.com
Failed to connect to github.com port 443

Hermes 安装器会先尝试 SSH，再尝试 HTTPS，失败后还可能退回 ZIP 下载。因此，你可能看到浏览器能打开仓库，但安装器仍然卡在“Cloning Hermes repository”。

原因很简单：浏览器、Git、PowerShell、Node/Electron 不一定共用同一套代理设置。

如果本机代理监听在 127.0.0.1:7897，可以在启动安装器前设置：

▼
powershell
复制代码
$proxy = 'http://127.0.0.1:7897'
$env:HTTP_PROXY  = $proxy
$env:HTTPS_PROXY = $proxy
$env:ALL_PROXY   = $proxy

git config --global http.proxy  $proxy
git config --global https.proxy $proxy

一个很反直觉的细节：HTTPS_PROXY 的值仍然可以是 http://127.0.0.1:7897。前面的 http:// 描述的是“如何连接本地代理”，不是目标网站只能使用 HTTP。

如果以后不再需要 Git 全局代理，可以清理：

▼
powershell
复制代码
git config --global --unset http.proxy
git config --global --unset https.proxy

这次安装过程中，Git 仓库最终能拉取，Electron 依赖也能继续下载，才算真正解决了网络问题。

四、第三个坑：信任了安装目录，安全软件仍可能拦截临时 EXE

真正让我反复重装的是这段错误：

▼
text
复制代码
Failed to update Windows PE resources
uv-trampoline-xxxxx.exe
系统无法打开指定的设备或文件

它先发生在创建虚拟环境阶段，后来又发生在安装 Python 包阶段。共同点是：失败对象都是 uv 临时生成的 uv-trampoline-*.exe。

一开始我把 E:\Hermes 和 E:\HermesTemp 加进腾讯电脑管家的信任区，以为这样就够了。

但信任区并不一定覆盖所有临时目录、进程行为和实时防护策略。更麻烦的是，电脑管家的实时防护服务并不好直接停止。

腾讯电脑管家实时防护服务无法直接停止

最终，在完全退出乃至卸载电脑管家后，同一阶段顺利通过。后续日志显示：

▼
text
复制代码
Creating Python virtual environment ... Succeeded
Installed 100 packages
All dependencies installed

这并不意味着所有人都必须卸载安全软件。更稳妥的排查顺序是：

先退出实时防护；
同时信任 Hermes 根目录和系统临时目录；
重试并观察是否仍卡在同一个 uv-trampoline 文件；
如果依旧失败，再考虑临时卸载，安装完成后重新启用系统防护。

还有一点：失败后不必立刻手工删除整个目录。Hermes 安装器会把不完整的仓库移动为类似：

▼
text
复制代码
hermes-agent.broken-20260803-154541

保留这些目录，反而有助于回看失败现场。盲目清空目录，会把日志和证据一起删掉。

五、别猜，先看这四份日志

这次排错最有价值的经验，是把问题按层次拆开，而不是盯着弹窗猜。

Hermes 排错流程图

Windows 版 Hermes 的关键日志位于：

▼
text
复制代码
E:\Hermes\logs\bootstrap-installer.log
E:\Hermes\logs\agent.log
E:\Hermes\logs\errors.log
E:\Hermes\logs\desktop.log

它们分别回答不同问题：

bootstrap-installer.log：安装卡在哪个阶段；
agent.log：请求实际用了哪个 provider、model 和 endpoint；
errors.log：接口错误、堆栈和 HTTP 状态码；
desktop.log：桌面后端是否正常启动。

常用查看方式：

▼
powershell
复制代码
Get-Content 'E:\Hermes\logs\bootstrap-installer.log' -Tail 120
Get-Content 'E:\Hermes\logs\agent.log' -Tail 160
Get-Content 'E:\Hermes\logs\errors.log' -Tail 120

只要抓住四个字段，很多问题会立刻变简单：

▼
text
复制代码
stage=
provider=
model=
HTTP xxx

六、第四个坑：腾讯账号“有额度”，不等于当前模型服务有额度

安装完成后，我在 Hermes 中配置了腾讯 TokenHub：

▼
yaml
复制代码
model:
  provider: tencent-tokenhub
  base_url: https://tokenhub.tencentmaas.com/v1
  api_mode: chat_completions

API Key 应保存在 Hermes 设置或本地 .env 中，不要贴进聊天记录，也不要写进截图。

当时 Hermes 默认只显示 Hy3，发送消息后返回 HTTP 402：

▼
text
复制代码
The free trial quota for the service has been exhausted

我第一反应是：腾讯 TokenHub 的免费额度是不是全部用完了？

打开控制台才发现并不是。hy3 服务已经停止且额度为 0，但其他服务仍在运行，并且各自拥有独立额度。

腾讯 TokenHub 各在线推理服务的额度相互独立

所以，HTTP 402 不能只看“账号”两个字，必须结合日志里的具体模型：

▼
text
复制代码
Provider: tencent-tokenhub
Model: hy3-preview

这次耗尽的是 hy3-preview 对应的服务，不是整个 TokenHub 账户。

七、第五个坑：腾讯控制台有模型，Hermes 下拉列表里却没有

腾讯控制台里明明有：

▼
text
复制代码
hy-mt2-pro
hy-mt2-lite
qwen3.5-flash
qwen3.5-plus

但 Hermes 模型列表最初只有一个 Hy3。

Hermes 当时只列出了 Hy3

点击“刷新模型”也没有用。原因是 Hermes 的下拉列表依赖自己的 provider 模型目录和缓存，并不会完整枚举腾讯控制台里所有自定义在线推理服务。

这时不要被下拉列表卡住，可以直接在 Hermes 消息框输入：

▼
text
复制代码
/model qwen3.5-flash --provider tencent-tokenhub --global

切换到 Plus：

▼
text
复制代码
/model qwen3.5-plus --provider tencent-tokenhub --global

这里有两个细节特别重要。

第一，正确语法是“模型名”和“提供方”分开写：

▼
text
复制代码
/model <服务ID> --provider <提供方> --global

不要写成：

▼
text
复制代码
/model tencent-tokenhub:qwen3.5-flash --global

Hermes 可能会把整段 tencent-tokenhub:qwen3.5-flash 当成模型名，结果提示模型不存在。

第二，--global 会更新全局默认配置，但已经打开的会话可能仍固定在旧模型。判断是否真的切换成功，不要只看 config.yaml，还要看右下角当前会话的模型标签。

如果右下角仍是旧模型，就在这个会话里再执行一次 /model 命令。

直接编辑配置文件当然也可以：

▼
yaml
复制代码
model:
  default: qwen3.5-flash
  provider: tencent-tokenhub
  base_url: https://tokenhub.tencentmaas.com/v1
  api_mode: chat_completions

直接修改 config.yaml 中的默认模型

但要记住：改配置文件解决的是“以后默认用什么”，/model 命令解决的是“当前会话现在用什么”。

八、第六个坑：接口返回 200，不代表这个模型适合 Hermes Agent

在 hy-mt2-pro 还有大量额度时，我成功把 Hermes 切了过去。接口不再报 402，也没有鉴权错误。

可聊天结果非常奇怪：

hy-mt2-pro 对中文指令反复返回固定英文

无论输入“你好”“说中文”还是“中文回答我的问题”，它都只返回几乎相同的英文欢迎语。

这不是语言设置，也不是前端缓存。

日志显示，三次请求都成功发给了：

▼
text
复制代码
provider=tencent-tokenhub
model=hy-mt2-pro
finish_reason=stop

但每次输入都恰好记为 4096 tokens，输出只有 15～18 tokens。也就是说，Hermes 没有偷偷替换回复，腾讯接口确实正常结束了请求，只是模型没有正确理解 Hermes 的长系统提示和 Agent 上下文。

MT 很容易让人联想到 machine translation。无论它的内部实现如何，这次实际表现已经足以说明：它不适合作为 Hermes 的通用 Agent 主模型。

换成面向通用对话的 qwen3.5-plus 后，中文对话和任务执行恢复正常；Plus 额度用完后，再用同样的方法切到 qwen3.5-flash 即可。

所以，选模型不能只看“额度还剩多少”，还要看它是否适合：

多轮对话；
长系统提示；
工具调用；
Agent 工作流。

九、第七个坑：当前会话、全局默认和模型列表，是三套状态

这是最后一个、也是最容易反复踩的坑。

Hermes 里至少存在三种“模型状态”：

模型下拉列表：Hermes 当前能展示的目录；
全局默认模型：config.yaml 里的 model.default；
当前会话模型：右下角实际显示并用于下一次请求的模型。

它们可能不一致。

例如：

配置文件已经写成 qwen3.5-flash；
下拉列表仍然没有 Flash；
当前旧会话仍显示 qwen3.5-plus。

这不是配置失效，而是会话仍保留旧的固定模型。

最省事的处理方式，还是在目标会话中执行：

▼
text
复制代码
/model qwen3.5-flash --provider tencent-tokenhub --global

看到下面这类提示才算完成：

▼
text
复制代码
Model switched: qwen3.5-flash
Provider: Tencent TokenHub
Saved to config.yaml

十、最终可复用的检查清单

如果让我重新装一次，我会严格按下面的顺序来。

安装前

确定 HERMES_HOME，不要只看安装包所在位置；
确认 GitHub 能被 Git/PowerShell 访问，不只是浏览器能打开；
同时设置 HTTP_PROXY 和 HTTPS_PROXY；
暂停可能拦截临时 EXE 的安全软件。

安装失败时

优先查看 bootstrap-installer.log；
先找失败的 stage；
如果出现 uv-trampoline.exe，优先检查实时防护；
如果出现 github.com:443、DNS 或 ETIMEDOUT，优先检查代理；
不要上来就删除整个 Hermes 目录。

模型接入时

TokenHub 地址使用 https://tokenhub.tencentmaas.com/v1；
模型名使用腾讯控制台中的“服务 ID”；
HTTP 402 要确认究竟是哪个服务额度耗尽；
下拉列表没有模型时，直接使用 /model；
右下角标签才代表当前会话实际使用的模型；
优先选择适合通用对话和工具调用的模型。

写在最后

这次经历最有意思的地方，是每一个报错都很像另一个问题。

安装目录不对，看起来像安装器设计问题；GitHub 超时，看起来像代理没开；uv 失败，看起来像 Python 环境坏了；HTTP 402，看起来像账号没钱；固定英文回复，看起来像中文设置没生效；模型列表为空，看起来像服务没创建成功。

但真正解决问题的方式始终只有一个：确认请求走到了哪一层，再用日志里的路径、阶段、服务 ID、模型名和状态码说话。

如果你也准备在 Windows 上部署 Hermes Agent，希望这篇复盘能帮你少走几小时弯路。

注：本文记录的是一次真实安装和排错过程。Hermes 与腾讯 TokenHub 都可能更新界面、模型目录和命令行为，实际使用时请以当前版本为准；API Key 请始终保存在本地配置中，不要发布到文章或截图里。

问答助学