WSL2 下启动 Hermes Agent 全记录：安装、代理、GPT/Codex 登录与局域网模型接入如果你和我一样，

如果你和我一样，已经在 Windows 原生环境里把 Hermes Agent 跑起来了，接着又想在 WSL2 里复用这套能力，大概率会遇到一个很真实的问题：

Windows 里明明能用，到了 WSL 里却各种报错。

这篇文章不讲“理想流程”，只讲一套实际踩过坑、最后跑通的流程，包括：

WSL2 里怎么启动 Hermes Agent
为什么 Windows 能用，WSL 却不行
Codex/GPT 在 WSL 里为什么总是登录失败
代理到底该配在哪一层
怎么接入另一台电脑上的本地模型
每类常见报错该怎么判断

如果你是第一次接触 Linux/WSL，也可以直接照着做。

一、先说结论

先把最重要的几点讲清楚：

Windows 原生 Hermes 和 WSL 里的 Hermes 是两套独立环境。
配置、PATH、认证状态、代理、Python 依赖都不会自动共享。
WSL2 里不能直接复用 Windows 的 localhost 代理。
你在 Windows 上看到代理是 127.0.0.1:7897，到了 WSL 里通常不能直接这么写，要改成 Windows 在 WSL 视角下的网关 IP，比如 172.25.16.1:7897。
Hermes 里想用 GPT/Codex，不等于“登录 ChatGPT 网页账号就行”。
在当前这条链路里，Hermes 走的是 OpenAI Codex 的设备码登录 或自定义兼容接口，不是普通 ChatGPT Web 登录那条路径。
如果你已经有一台局域网内的 OpenAI-compatible 模型服务，往往比折腾 Codex 登录更稳。
最实用的做法是分成两套启动方式：
- hermes-codex：启动前自动开代理，给 Codex/GPT 用
- hermes-local：启动前自动关代理，给局域网/本地模型用

二、为什么 Windows 能用，WSL 却不能直接用

这是最容易让人误判的一点。

虽然 WSL2 看起来像“Windows 里的 Linux 终端”，但它本质上是一个 独立的 Linux 运行环境。这意味着：

Windows 里安装好的 Python，不等于 WSL 里也有
Windows 里能执行的 hermes，不等于 WSL 里也能执行
Windows 里已经登录过的认证状态，不等于 WSL 自动继承
Windows 上的本地代理端口，不等于 WSL 直接能走

所以正确心态不是“我已经装好了 Hermes，为啥 WSL 还不行”，而是：

我要在 WSL 里重新补齐一套运行条件。

三、WSL2 下正确的启动思路

1. 先进入 Linux 自己的家目录

第一次打开 Ubuntu 之后，建议先执行：

cd ~
pwd
whoami

正常应该看到类似：

/home/你的用户名

不建议一上来就在 /mnt/c/Users/... 下面折腾安装。
那是 Windows 磁盘挂载进来的路径，能访问，但不是最适合装 Linux 工具的位置。

2. 每次新开终端先确认 `hermes` 是否在 PATH 里

如果你执行：

hermes --version

报：

command 'hermes' not found

通常不是没装，而是 PATH 还没刷新。

这时先执行：

source ~/.bashrc

再试一次：

hermes --version

如果还是不行，再检查 ~/.local/bin 有没有进 PATH。

四、WSL 安装 Hermes 时最容易遇到的坑

1. `curl ... install.sh | bash` 卡住或超时

常见表现：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

执行后长时间没反应，或者直接 timeout。

这类问题大概率不是脚本本身的问题，而是 WSL 当前没有正确走代理，导致：

访问 raw.githubusercontent.com 超时
后续 git clone 中断
Python 依赖下载失败

2. `git clone` 报 early EOF / TLS 错误

常见报错类似：

error: RPC failed; curl 56 GnuTLS recv error (-9): Error decoding the received TLS packet.
fatal: early EOF
fatal: fetch-pack: invalid index-pack output

这通常说明：

网络链路不稳定
代理没通
GitHub 连接被中途截断

结论：先修代理，再重试 clone。
不要一上来就怀疑是 Hermes 仓库坏了。

五、WSL2 代理的关键点：不要用 `localhost`

这是整套流程里最关键的坑。

在 Windows 上，你的代理软件可能监听的是：

127.0.0.1:7897

但在 WSL2 里，127.0.0.1 指向的是 Linux 自己，不是 Windows。

所以你会看到类似提示：

WSL NAT 模式下的 WSL 不支持 localhost 代理

这句话的实际含义是：

Windows 上的 localhost 代理，不会自动镜像给 WSL 用。

正确做法

在 WSL 里先找出 Windows 在当前 WSL 网络里的网关 IP：

ip route show default

如果输出类似：

default via 172.25.16.1 dev eth0

那你真正该用的代理地址就是：

http://172.25.16.1:7897

而不是：

http://127.0.0.1:7897

临时手动配置代理

export http_proxy="http://172.25.16.1:7897"
export https_proxy="http://172.25.16.1:7897"
export HTTP_PROXY="$http_proxy"
export HTTPS_PROXY="$https_proxy"

如果你还要直连局域网模型，建议加上 no_proxy：

export no_proxy="localhost,127.0.0.1,::1,192.168.3.252"
export NO_PROXY="$no_proxy"

验证代理是否生效

curl -I https://chatgpt.com --max-time 15

如果完全超时，说明网络还没通。
如果返回了 HTTP 头，即便是 403，也说明：

代理链路已经通了
WSL 已经能访问到 chatgpt.com

这里的 403 往往是 Cloudflare challenge，不等于“网络不通”。

六、我最后采用的实用方案：给 WSL 加两个启动命令

为了避免每次手动 export 代理，我在 ~/.bash_aliases 里加了两套 helper。

作用很简单：

hermes-codex：自动开代理，再启动 Hermes
hermes-local：自动关代理，再启动 Hermes

可以直接用下面这段：

# Hermes / WSL proxy helpers
_wsl_windows_host_ip() {
    ip route show default 2>/dev/null | head -n1 | cut -d" " -f3
}

codex_proxy_on() {
    local host_ip
    host_ip="$(_wsl_windows_host_ip)"

    if [ -z "$host_ip" ]; then
        echo "Could not detect Windows host IP"
        return 1
    fi

    export http_proxy="http://${host_ip}:7897"
    export https_proxy="http://${host_ip}:7897"
    export HTTP_PROXY="$http_proxy"
    export HTTPS_PROXY="$https_proxy"
    export no_proxy="localhost,127.0.0.1,::1,192.168.3.252"
    export NO_PROXY="$no_proxy"

    echo "Codex proxy enabled: $http_proxy"
}

codex_proxy_off() {
    unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY all_proxy ALL_PROXY
    export no_proxy="localhost,127.0.0.1,::1,192.168.3.252"
    export NO_PROXY="$no_proxy"

    echo "Codex proxy disabled"
}

hermes_codex() {
    codex_proxy_on || return 1
    hermes "$@"
}

hermes_local() {
    codex_proxy_off
    hermes "$@"
}

alias codex-proxy-on=codex_proxy_on
alias codex-proxy-off=codex_proxy_off
alias hermes-codex=hermes_codex
alias hermes-local=hermes_local

写完之后别忘了：

source ~/.bashrc

之后就可以这样用：

hermes-codex

或者：

hermes-local

七、Hermes 里配置 GPT/Codex 时的几个关键认知

1. `hermes model` 要在 shell 里运行，不要在聊天界面里输入

这是一个非常容易踩的坑。

你打开 hermes 进入聊天界面后，再在里面输入：

hermes model

这并不是在执行 shell 命令，而是在把这句话发给 Agent。

正确方式是：

先退出 Hermes 聊天界面
回到 Ubuntu shell
再执行：

hermes model

如果你当前就是想在代理开启的前提下配置 Codex/GPT，也可以直接执行：

hermes-codex model

如果你当前是要配置局域网本地模型，则更建议执行：

hermes-local model

2. 想用 GPT/Codex，不是“打开 ChatGPT 登录”这么简单

在这套链路里，Hermes 提示的通常是：

https://auth.openai.com/codex/device

然后让你输入设备码。

也就是说，Hermes 当前走的是 OpenAI Codex 的设备登录流程。
这和你平时在浏览器里直接打开 ChatGPT，是两回事。

如果你没有 OpenAI API Key，也不是完全不能用，但你要知道：

有些 provider 支持 API Key
有些 provider 走设备码登录
Hermes 的 GPT/Codex 方案，本质上还是在走 OpenAI/Codex 这条认证链

3. 设备码登录时，浏览器要在 Windows 里打开

WSL 本身不是图形桌面系统，最稳的做法是：

在 WSL 终端里看到登录链接和验证码
用 Windows 浏览器打开那个地址
输入验证码
回到 WSL 终端等待完成

例如：

explorer.exe "https://auth.openai.com/codex/device"

注意，不要把链接和验证码再敲回等待中的 Hermes 终端里。
那样不会触发登录，只会让你以为“怎么没反应”。

八、Codex/GPT 登录时的典型报错怎么理解

1. `429`

如果你看到：

Login failed: Device code request returned status 429.

通常表示：

登录请求太频繁
同一出口 IP 被限流
代理出口不稳定

这时不要连点重试，先停一会儿，再重新发起设备登录。

2. `403`

如果你看到：

Login failed: Device code request returned status 403.

一般优先排查：

WSL 里到底有没有走代理
代理出口是否可访问 OpenAI/ChatGPT 相关域名
当前请求是否被 Cloudflare / 风控拦截

这里的重点不是“403 就一定是账号问题”，而是：

先把网络链路和代理链路排清楚。

3. 一直没反应

最常见的原因反而最简单：

你没有在 Windows 浏览器里完成设备码授权
你把链接/验证码输入回了等待中的终端
终端那边在等授权，浏览器这边根本没完成

九、一个很实用的补救办法：复用 Windows 已登录的认证文件

如果你已经在 Windows 原生 Hermes 里登录成功，而 WSL 里一直卡在认证，你可以尝试把 Windows 侧的认证文件复制到 WSL：

rm -f ~/.hermes/auth.json ~/.hermes/auth.lock
mkdir -p ~/.hermes
cp /mnt/c/Users/你的用户名/.hermes/auth.json ~/.hermes/auth.json
chmod 600 ~/.hermes/auth.json

这不是官方“必须流程”，但在实际排障中非常有用。

它的本质是：

Windows Hermes 已经拿到了可用认证状态
WSL Hermes 只是没继承到
手动复制后，能少走很多重复登录流程

十、接入另一台电脑上的本地模型，其实更省心

如果你手里已经有一台局域网内的模型服务，比如：

地址：http://192.168.3.252:48760
模型：gpt-5.4
提供 OpenAI-compatible 接口

那在 Hermes 里最稳的做法通常是走 Custom endpoint。

配置方式

在 hermes model 里填：

Base URL：http://192.168.3.252:48760/v1
API Key：你的服务端 key
Model：gpt-5.4

注意这里的 Base URL 一般要带 /v1。

先用 curl 测一下通不通

查看模型列表：

curl http://192.168.3.252:48760/v1/models \
  -H "Authorization: Bearer 你的API_KEY"

如果不带 key 返回 401，反而说明一件好事：

网络是通的，只是鉴权没过。

这比超时更容易处理。

再测一次最小对话

curl http://192.168.3.252:48760/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 你的API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {"role": "user", "content": "Reply with exactly: ok"}
    ],
    "max_tokens": 10
  }'

如果返回内容里有：

"content":"ok"

那就说明这个 endpoint 已经可以给 Hermes 用了。

十一、为什么我最后建议把 Codex 和本地模型分两套使用

这是这次折腾下来最实用的经验总结。

用 Codex/GPT 时

走：

hermes-codex

特点：

自动开代理
适合访问 chatgpt.com / auth.openai.com
适合设备码登录和远程模型

用局域网本地模型时

走：

hermes-local

特点：

自动关代理
避免局域网请求被错误送进代理
适合自建 OpenAI-compatible endpoint

这两种模式分开，能减少 80% 以上的“到底是模型问题、认证问题还是代理问题”的排查成本。

十二、常见问题速查

1. `hermes: command not found`

先执行：

source ~/.bashrc

如果还是不行，再检查：

是否真的装好了 Hermes
~/.local/bin 是否已加入 PATH

2. `curl https://raw.githubusercontent.com/...` 超时

优先检查：

WSL 有没有代理
代理地址是不是还写着 127.0.0.1
应该改成 WSL 看到的 Windows 网关地址

3. `git clone` 报 `early EOF`

优先判断为网络/代理问题，不要先怀疑仓库本身。

4. `hermes model` 执行了没效果

看看你是不是在 Hermes 的聊天界面里输入了它。
这个命令要在 shell 里执行。

5. `chatgpt.com` 返回 `403`

不要直接等价理解成“彻底不能访问”。
如果能拿到 HTTP 返回头，通常说明代理链路已经通了，只是遇到了 Cloudflare challenge 或风控页面。

6. 本地模型接口返回 `401`

这通常说明：

地址是通的
服务是活的
只是没有带 key，或者 key 不对

这比“连接超时”要好排查得多。

十三、推荐的一套最终工作流

如果你已经在 Windows 和 WSL 两边都折腾过一轮，我建议最后固定成下面这套习惯。

场景 1：我要用 Codex/GPT

cd ~
source ~/.bashrc
hermes-codex model

配置完成后，再正常启动：

hermes-codex

场景 2：我要用局域网本地模型

cd ~
source ~/.bashrc
hermes-local model

配置完成后，再正常启动：

hermes-local

场景 3：我要判断是网络问题还是鉴权问题

先看外网：

curl -I https://chatgpt.com --max-time 15

再看局域网模型：

curl http://你的模型地址/v1/models

判断思路很简单：

超时：先查网络/代理
401：网络通了，查 key
403：网络大概率通了，查风控/挑战/认证链路

十四、最后总结

这次在 WSL2 里跑 Hermes Agent，真正麻烦的不是“安装”本身，而是这三层东西叠在一起：

WSL 和 Windows 是两套环境
代理在 WSL NAT 下不能直接走 localhost
Codex/GPT 的认证链和局域网本地模型不是一回事

只要这三个认知理顺了，后面的排障会快很多。

如果要一句话总结这次的经验，那就是：

在 WSL 里跑 Hermes，先分清“命令是否在 shell 里执行”“请求是否走对代理”“当前用的是远程模型还是本地模型”，问题就会少一大半。

附：我最终保留下来的高频命令

# 刷新 shell 配置
source ~/.bashrc

# 启动 Hermes（Codex/GPT 模式，自动开代理）
hermes-codex

# 在 Codex/GPT 模式下配置模型
hermes-codex model

# 启动 Hermes（本地模型模式，自动关代理）
hermes-local

# 在本地模型模式下配置模型
hermes-local model

# 手动开代理
codex-proxy-on

# 手动关代理
codex-proxy-off

# 查看 Hermes 是否正常
hermes --version

# 配置模型
hermes model

# 环境诊断
hermes doctor

WSL2 下启动 Hermes Agent 全记录：安装、代理、GPT/Codex 登录与局域网模型接入