从零打通 Hermes Agent：Windows + WSL2 + Clash 全链路安装、认证与首次实战

伞伞悦读2026-10-02 12:57

一篇从"Ubuntu 无法访问外网"开始，最终完成 Hermes Agent 安装、Nous Portal OAuth 登录、免费模型选择、本地终端后端配置、Playwright 浏览器验证与首次中文对话的完整实战记录。

写在前面

很多安装教程只给出一条命令：

复制代码 
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

这条命令没有问题，它来自 Nous Research 官方仓库。但在真实的 Windows + WSL2 环境中，真正耗时的部分往往不是输入命令，而是解决下面这些问题：

  • WSL2 无法直接复用 Windows 的 127.0.0.1 代理；

  • Clash 已开启，但 Ubuntu 访问宿主机代理端口仍然超时；

  • astral.sh、GitHub 或 files.pythonhosted.org 出现 TLS 握手中断；

  • Playwright Chromium 下载完成，却因缺少 Linux 动态库无法启动；

  • Nous Portal 网页登录成功，但终端设备码已经过期；

  • GitHub OAuth 页面能打开，授权按钮却始终无法点击；

  • 安装完成后输入 hermes，终端短时间内看起来没有反应。

本文不回避这些问题。它既给出官方标准路径，也记录一套经过完整验证的 Windows + WSL2 实战路径。

最终验证结果：

  • WSL2 Ubuntu 外网链路正常；

  • Clash Verge 代理可被 WSL2 稳定使用；

  • Hermes Agent CLI 安装成功；

  • Nous Portal OAuth 登录成功；

  • 免费模型配置成功；

  • Local 终端后端配置成功；

  • Playwright Chromium 实际启动成功；

  • Gateway 用户服务正常运行；

  • Hermes Agent 完成第一次中文对话。

1. 依据、范围与版本快照

1.1 官方依据

本文涉及 Hermes Agent 的安装命令、目录结构、CLI 命令和主要功能，依据以下 Nous Research 官方资源：

中文社区站点可用于辅助阅读，但不是 Nous Research 官方站点：

1.2 实测环境

本文最后一次验证环境：

项目 实测值
宿主系统 Windows 11
Linux 环境 Ubuntu on WSL2
WSL 网络 NAT
代理软件 Clash Verge
Clash mixed-port 7897
Hermes Agent v0.21.4
仓库提交 913c045
Hermes Python 3.11.16
OpenAI SDK 2.24.0
Hermes Node.js v26.9.0
认证提供方 nous
实测免费模型 poolside/laguna-s-2.1:free
终端后端 local

软件版本、模型目录、免费额度和模型价格会变化。读者应以安装时的官方页面和终端输出为准。

1.3 本文的证据边界

需要明确区分两类内容：

  1. Hermes 安装脚本、仓库、命令和 Nous Portal 登录流程来自官方。

  2. WSL NAT、Clash 局域网访问、防火墙规则、PyPI 镜像与 TLS 故障处理，是针对本次 Windows 环境完成的实测方案。

第二类方案具备实践参考价值，但不等于所有机器都必须使用相同配置。

2. Hermes Agent 是什么

Hermes Agent 是 Nous Research 开发的开源智能代理。它不只是一个聊天界面，而是把模型、终端、文件、浏览器、技能、记忆、定时任务和消息平台组织在同一套 Agent 运行环境中。

官方仓库强调的主要能力包括：

  • 终端 TUI 交互；

  • 文件读写与项目操作；

  • 浏览器自动化；

  • 技能系统与经验学习；

  • 持久记忆与会话搜索；

  • 定时任务；

  • 子 Agent 委派与并行任务；

  • Telegram、Discord、Slack、WhatsApp、Signal 等消息平台接入；

  • Local、Docker、SSH、Singularity、Modal、Daytona、Vercel Sandbox 等终端后端；

  • Nous Portal、OpenRouter、自定义 OpenAI 兼容端点等模型来源。

如果只想聊天，普通聊天产品更简单。如果希望 Agent 能在真实环境里读文件、执行命令、操作浏览器、维护技能和长期运行，Hermes Agent 才能体现价值。

3. 整体链路

本教程最终打通的链路如下：

复制代码 
Windows 11
  -> Clash Verge
  -> Windows 宿主机代理端口 7897
  -> WSL2 NAT 网络
  -> Ubuntu
  -> Hermes Agent
  -> Nous Portal OAuth
  -> 免费模型
  -> Local 终端后端
  -> CLI 首次对话

推荐按这个顺序操作：

复制代码 
确认 WSL2
  -> 修复 Ubuntu 网络
  -> 验证代理出口
  -> 验证 GitHub/PyPI
  -> 下载并检查安装脚本
  -> 安装 Hermes
  -> 验证 CLI 和浏览器
  -> 登录 Nous Portal
  -> 选择模型
  -> 选择 Local 后端
  -> 完成首次对话

不要在网络尚未稳定时反复执行安装脚本，否则很难区分安装错误与下载错误。

4. 安装前准备

4.1 检查 WSL

在 Windows PowerShell 中执行：

复制代码 
wsl --version
wsl --status
wsl -l -v

确认 Ubuntu 的 VERSION 为 2。

如果尚未安装 Ubuntu：

复制代码 
wsl --install -d Ubuntu

安装完成后重启 Windows，并打开 Ubuntu 完成初始用户名和密码设置。

4.2 检查 Ubuntu 基础状态

在 Ubuntu 中执行：

复制代码 
whoami
uname -a
cat /etc/os-release
ip -brief address
ip route
cat /etc/resolv.conf

健康的 WSL NAT 网络通常至少应看到：

  • lo 回环接口；

  • eth0 网络接口；

  • default via ... dev eth0 默认路由；

  • /etc/resolv.conf 中的 nameserver。

如果只有 lo，没有 eth0 和默认路由，先处理第 14.2 节，不要继续安装。

5. WSL2 与 Clash Verge 的正确关系

5.1 为什么会出现 localhost 代理警告

常见提示：

复制代码 
wsl: 检测到 localhost 代理配置，但未镜像到 WSL。
NAT 模式下的 WSL 不支持 localhost 代理。

原因是：

  • Windows 的系统代理监听 127.0.0.1:7897；

  • WSL2 NAT 中的 127.0.0.1 指向 Ubuntu 自己；

  • 它不等于 Windows 的 127.0.0.1。

所以在 NAT 模式下，Ubuntu 需要通过 Windows 宿主机在 WSL 网络中的地址访问代理。

5.2 本次实测采用的 .wslconfig

文件路径：

复制代码 
C:\Users\<Windows用户名>\.wslconfig

内容：

复制代码 
[wsl2]
networkingMode=nat
dnsTunneling=true
autoProxy=false
firewall=true

应用配置：

复制代码 
wsl --shutdown

然后重新打开 Ubuntu。

为什么选择 NAT：本次机器尝试 networkingMode=mirrored 后，Ubuntu 只剩 lo，默认路由和 /etc/resolv.conf 均消失。即使启用 Windows Hypervisor Platform 并完整重启，镜像网络仍未恢复，因此回退到稳定的 NAT。

这不代表镜像网络普遍不可用。如果你的镜像网络工作正常，可以继续使用，不必照搬 NAT。

5.3 Clash Verge 设置

在 Clash Verge 中启用：

  • 虚拟网卡模式；

  • 系统代理；

  • 局域网连接。

确认端口。本次环境为：

复制代码 
mixed-port: 7897

在 Windows PowerShell 检查监听：

复制代码 
Get-NetTCPConnection -LocalPort 7897 -State Listen

5.4 获取 Windows 宿主机地址

在 Ubuntu 中：

复制代码 
WIN_HOST=$(ip route | awk '/default/ {print $3}')
echo "$WIN_HOST"

本次环境曾得到 192.168.128.1，但这个地址可能在 WSL 重启或网络变化后改变，所以脚本中应动态获取，不要永久写死。

5.5 为当前终端设置代理

复制代码 
export HTTP_PROXY="http://${WIN_HOST}:7897"
export HTTPS_PROXY="http://${WIN_HOST}:7897"
export ALL_PROXY="http://${WIN_HOST}:7897"

检查：

复制代码 
env | grep -i proxy

这些环境变量只对当前 Shell 及其子进程有效。

5.6 只允许 WSL 子网访问 Clash

如果 Clash 已开启"局域网连接"，但 Ubuntu 访问 ${WIN_HOST}:7897 仍超时，可在管理员 PowerShell 中创建规则：

复制代码 
New-NetFirewallRule `
  -DisplayName "Clash-Wsl-7897" `
  -Direction Inbound `
  -Action Allow `
  -Protocol TCP `
  -LocalPort 7897 `
  -RemoteAddress 192.168.128.0/20 `
  -Profile Any

这里的 192.168.128.0/20 应按你的 WSL 实际子网调整。可在 Ubuntu 用下面的命令确认：

复制代码 
ip -4 addr show eth0
ip route

检查规则：

复制代码 
Get-NetFirewallRule -DisplayName "Clash-Wsl-7897"

这条规则限定了远端 WSL 子网，不应改成任意来源地址。

6. 在安装前证明网络真的可用

6.1 检查代理出口

复制代码 
curl -4 -x "http://${WIN_HOST}:7897" https://ipinfo.io

需要看到代理出口信息，而不是本地网络出口。

6.2 检查 Hermes 安装脚本

复制代码 
curl -4 -I --connect-timeout 10 --max-time 30 \
  https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh

6.3 检查 GitHub

复制代码 
curl -4 -I --connect-timeout 10 --max-time 30 \
  https://github.com/NousResearch/hermes-agent

6.4 检查 PyPI

复制代码 
curl -4 -I --connect-timeout 10 --max-time 30 \
  https://pypi.org/simple/

6.5 检查 GitHub 静态资源

这一项很重要。GitHub OAuth 页面依赖 github.githubassets.com 的 CSS 与 JavaScript：

复制代码 
curl -4 -I --connect-timeout 10 --max-time 30 \
  https://github.githubassets.com/favicons/favicon.svg

如果 GitHub 主站能打开，但这个域名 TLS 失败，GitHub 授权按钮可能永远保持禁用。

只有这些检查稳定通过后，才开始安装。

7. 官方标准安装路径

7.1 官方一行命令

Nous Research 官方 README 给出的 Linux、macOS、WSL2 安装方式：

复制代码 
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

安装完成后：

复制代码 
source ~/.bashrc
hermes

7.2 更适合生产排障的三步安装

为了能审查脚本并保留安装文件，推荐：

复制代码 
curl -fsSLO \
  https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh

less install.sh
bash -n install.sh
bash install.sh

含义：

  1. 下载官方仓库中的安装脚本；

  2. 用 less 阅读脚本；

  3. 用 bash -n 做语法检查；

  4. 执行安装。

不要从来历不明的镜像站下载修改过的安装脚本。

7.3 带显式代理执行安装

复制代码 
WIN_HOST=$(ip route | awk '/default/ {print $3}')
export HTTP_PROXY="http://${WIN_HOST}:7897"
export HTTPS_PROXY="http://${WIN_HOST}:7897"
export ALL_PROXY="http://${WIN_HOST}:7897"

bash install.sh

安装器会处理或检查：

  • uv；

  • Python；

  • Git；

  • Node.js；

  • C++ 编译器；

  • Hermes Agent 仓库；

  • Python 虚拟环境和依赖；

  • Node.js 浏览器依赖；

  • Playwright Chromium；

  • Computer Use 驱动；

  • PATH；

  • 配置模板；

  • 内置技能。

7.4 可选系统包怎么选

安装器可能询问：

复制代码 
Install ripgrep for faster file search ffmpeg for TTS voice messages?

说明：

  • ripgrep：加快文本搜索，非核心依赖；

  • ffmpeg：用于音视频与部分语音能力，非核心对话依赖；

  • build-essential、python3-dev、libffi-dev：原生包编译工具。

有 sudo 权限时建议安装。没有 sudo 权限时可先跳过，遇到明确的编译错误后再处理。

8. 本次实际遇到的安装故障与恢复

正常网络环境通常不需要本节。只有安装器失败时才按错误类型处理。

8.1 astral.sh 下载 uv 超时

错误特征：

复制代码 
Failed to download uv installer from https://astral.sh/uv/install.sh

先显式设置代理，然后手工安装官方 uv：

复制代码 
WIN_HOST=$(ip route | awk '/default/ {print $3}')
export HTTP_PROXY="http://${WIN_HOST}:7897"
export HTTPS_PROXY="http://${WIN_HOST}:7897"
export ALL_PROXY="http://${WIN_HOST}:7897"

mkdir -p "$HOME/.hermes/bin"
curl -4 -LsSf https://astral.sh/uv/install.sh -o /tmp/uv-install.sh
UV_UNMANAGED_INSTALL="$HOME/.hermes/bin" sh /tmp/uv-install.sh

"$HOME/.hermes/bin/uv" --version

然后重新运行 bash install.sh，安装器会识别已安装的 uv。

8.2 files.pythonhosted.org TLS 握手失败

典型错误：

复制代码 
tls handshake eof
SSL_ERROR_SYSCALL

先分别测试：

复制代码 
curl -4 -I -x "http://${WIN_HOST}:7897" \
  https://pypi.org/simple/

curl -4 -I -x "http://${WIN_HOST}:7897" \
  https://files.pythonhosted.org/

如果代理节点对 PyPI 文件域名不稳定，优先切换 Clash 节点。不要默认关闭 TLS 校验。

必要时可临时使用可信 PyPI 镜像：

复制代码 
export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
export UV_DEFAULT_INDEX=https://mirrors.aliyun.com/pypi/simple/
export UV_HTTP_TIMEOUT=120

8.3 镜像缺少上传时间导致 exclude-newer 误判

Hermes 项目的 uv 配置可能限制最近发布的依赖。部分镜像缺少上传时间元数据，可能出现：

复制代码 
No solution found when resolving dependencies
was filtered by exclude-newer

只对当前安装进程临时关闭：

复制代码 
export UV_EXCLUDE_NEWER=false

不要直接修改官方仓库的 pyproject.toml 或 uv.lock。

8.4 保留锁文件版本与哈希的恢复方式

如果 uv sync --locked 因镜像元数据不兼容失败，可以从官方 uv.lock 导出固定版本和 SHA256 哈希：

复制代码 
cd "$HOME/.hermes/hermes-agent"

"$HOME/.hermes/bin/uv" export \
  --frozen \
  --extra all \
  --no-dev \
  --no-emit-project \
  --format requirements.txt \
  --output-file /tmp/hermes-requirements.txt

随后按哈希从镜像安装：

复制代码 
"$HOME/.hermes/bin/uv" pip install \
  --python "$HOME/.hermes/hermes-agent/venv/bin/python" \
  --no-config \
  --require-hashes \
  --index-url https://mirrors.aliyun.com/pypi/simple/ \
  -r /tmp/hermes-requirements.txt

这种方法保留了锁文件的固定版本和哈希校验，比无约束重新解析依赖更严谨。

8.5 本地 Hermes 包构建仍访问官方 PyPI

如果本地包构建因为 setuptools 或 wheel 下载失败：

复制代码 
"$HOME/.hermes/bin/uv" pip install \
  --python "$HOME/.hermes/hermes-agent/venv/bin/python" \
  --no-config \
  --index-url https://mirrors.aliyun.com/pypi/simple/ \
  setuptools wheel

再安装本地包：

复制代码 
cd "$HOME/.hermes/hermes-agent"

"$HOME/.hermes/bin/uv" pip install \
  --python venv/bin/python \
  --no-config \
  --no-build-isolation \
  --no-deps \
  -e .

验证：

复制代码 
venv/bin/hermes --version

9. Playwright Chromium 的完整验证

浏览器二进制下载成功，不代表浏览器一定能启动。Linux 还需要系统动态库。

9.1 常见缺库错误

复制代码 
error while loading shared libraries: libnspr4.so

9.2 安装 Playwright 系统依赖

复制代码 
cd "$HOME/.hermes/hermes-agent"
export PATH="$HOME/.hermes/node/bin:$PATH"
sudo npx playwright install-deps chromium

如果只能从 Windows 侧调用 WSL root：

复制代码 
wsl -d Ubuntu -u root -- bash -lc `
  'cd /home/<Linux用户名>/.hermes/hermes-agent && `
   export PATH=/home/<Linux用户名>/.hermes/node/bin:/usr/local/bin:/usr/bin:/bin && `
   npx playwright install-deps chromium'

9.3 实际启动测试

复制代码 
cd "$HOME/.hermes/hermes-agent"
export PATH="$HOME/.hermes/node/bin:$PATH"
export PLAYWRIGHT_BROWSERS_PATH="$HOME/.cache/ms-playwright"

npx playwright screenshot about:blank /tmp/hermes-browser-test.png
test -s /tmp/hermes-browser-test.png && echo browser_ok

只有看到 browser_ok，才说明 Chromium 真正可运行。

10. 安装完成后的验收

重新加载 Shell：

复制代码 
source ~/.bashrc

10.1 检查 Hermes

复制代码 
command -v hermes
hermes --version
hermes --help

10.2 检查 Python 环境

复制代码 
~/.hermes/hermes-agent/venv/bin/python --version

10.3 检查配置文件

复制代码 
ls -l ~/.hermes/config.yaml ~/.hermes/.env

10.4 运行诊断

复制代码 
hermes doctor

hermes doctor 可能检查多个 API 端点，需要等待。以下警告未必阻断基础对话：

  • 未配置图片生成密钥；

  • 未安装本地 Whisper；

  • 未设置 GitHub Token；

  • 未安装 ripgrep；

  • 未启用消息平台。

应重点关注：

  • Python 环境；

  • SSL 证书；

  • 必需包；

  • Hermes 命令；

  • 模型认证；

  • API 连通性。

11. Nous Portal 登录与设备码绑定

11.1 为什么使用 Nous Portal

官方提供的 Nous Portal 可以统一承载模型与部分工具能力，减少分别维护多个服务商 API Key 的负担。

登录命令：

复制代码 
hermes portal

或运行完整向导：

复制代码 
hermes setup

11.2 WSL 无法自动打开 Windows 浏览器

常见提示：

复制代码 
gio: Operation not supported

这不代表登录失败，只是 WSL 无法自动拉起 Windows Chrome。手动复制终端输出的链接到 Windows 浏览器即可。

11.3 设备码必须保持一致

终端会显示类似：

复制代码 
Open: https://portal.nousresearch.com/manage-subscription?user_code=XXXX-XXXX

正确流程：

  1. 保持终端中的 hermes portal 进程运行；

  2. 立即在浏览器打开终端给出的链接；

  3. 确认网页和终端显示同一个设备码；

  4. 登录 Nous Portal；

  5. 点击 CONNECT；

  6. 等待终端显示 Login successful!。

不要重复运行多个 hermes portal。每次重跑都会生成新设备码，旧码可能失效。

11.4 invalid_grant: Invalid device code

这表示：

  • 设备码已过期；或

  • 浏览器使用的是旧设备码；或

  • 终端轮询已结束。

重新执行：

复制代码 
hermes portal

使用新链接，并立刻完成连接。

11.5 GitHub OAuth 授权按钮不可点击

本次实测中，原因不是邮箱未验证，而是：

复制代码 
github.githubassets.com
net::ERR_CONNECTION_CLOSED

GitHub OAuth 页面的 CSS 和 JavaScript 没有加载，页面只剩裸 HTML。授权按钮由服务端初始输出为禁用，GitHub 的 OAuth 脚本加载后才会启用。

验证静态资源：

复制代码 
curl.exe -I -x http://127.0.0.1:7897 `
  --connect-timeout 10 --max-time 30 `
  https://github.githubassets.com/favicons/favicon.svg

如果只有：

复制代码 
HTTP/1.1 200 Connection established

却没有后续 HTTP/1.1 200 OK 或 HTTP/2 200，说明只建立了代理隧道，目标站 TLS 尚未成功。

处理方法：

  1. 切换 Clash 节点；

  2. 重新测试 github.githubassets.com；

  3. 确认返回完整 HTTP 200；

  4. 在 OAuth 页面按 Ctrl+Shift+R 强制刷新。

不要通过开发者工具强行移除按钮的 disabled 属性。那是在绕过页面安全状态，而不是修复登录。

11.6 邮箱六位验证码在哪里

GitHub 登录 Nous Portal 后，Nous Portal 可能要求确认 GitHub 账号绑定的邮箱。

验证码在 GitHub 主邮箱的收件箱中，不在 GitHub 设置页面中。可在：

复制代码 
GitHub -> Settings -> Emails

确认主邮箱，然后登录对应邮箱查找 Nous Portal 邮件。检查：

  • 收件箱；

  • 垃圾邮件；

  • 订阅邮件；

  • 搜索关键词 Nous、verification code。

验证码属于登录凭据，不要发给他人。

11.7 最终认证验收

复制代码 
hermes auth status nous

必须看到：

复制代码 
nous: logged in

浏览器显示已登录，不等于终端已经拿到认证。以该命令结果为准。

12. 选择模型、终端后端和消息平台

12.1 选择免费模型

如果 Nous Portal 余额为 $0.00，应选择列表中标注 :free 的模型。

本次实测选择：

复制代码 
poolside/laguna-s-2.1:free

它偏向编程与代码任务。

免费模型目录随时可能变化，应以 hermes model 当时显示的列表为准。

切换模型：

复制代码 
hermes model

查看当前配置：

复制代码 
hermes config get model.provider
hermes config get model.default

实测结果：

复制代码 
nous
poolside/laguna-s-2.1:free

12.2 终端后端选择 Local

在本地 WSL2 使用时，选择：

复制代码 
Keep current (local)

或者选择：

复制代码 
Local - run directly on this machine

Local 表示 Agent 的 Shell 命令直接在当前 Ubuntu 环境运行。

其他后端适用于不同目标：

  • Docker/Podman：容器隔离；

  • SSH：远程机器；

  • Singularity/Apptainer：HPC 环境；

  • Modal、Daytona、Vercel Sandbox：云端或沙箱运行。

不要因为名称看起来高级就随意选择。后端决定命令执行、文件访问和隔离边界。

12.3 消息平台可以以后配置

首次安装可以选择：

复制代码 
Skip - set up later

本地 CLI 不依赖 Telegram 或 Discord。

以后配置：

复制代码 
hermes setup gateway

13. Gateway 服务

检查：

复制代码 
hermes gateway status

重启并刷新服务定义：

复制代码 
hermes gateway restart

如果没有配置消息平台，日志中出现：

复制代码 
No messaging platforms enabled

属于正常提示，不影响本地 hermes CLI。

Gateway 使用 systemd 用户服务时，可以通过下面命令查看日志：

复制代码 
journalctl --user -u hermes-gateway -f

14. 启动 Hermes 与第一次对话

14.1 启动

复制代码 
source ~/.bashrc
hermes

首次启动可能需要几秒初始化模型、工具、技能和安全扫描。短时间黑屏不一定是卡死。

可在另一个终端检查进程：

复制代码 
ps -ef | grep -E '[h]ermes($| .*chat|hermes_cli)'

14.2 如果 TUI 长时间不显示

先按一次 Enter，或等待 10 至 30 秒。

仍无显示时，按 Ctrl+C 退出，使用传统 CLI 模式：

复制代码 
hermes --cli

也可显式启动聊天：

复制代码 
hermes chat --cli

查看终端变量：

复制代码 
echo "$TERM"
stty size

如果终端尺寸异常，可先调整 Windows Terminal 窗口大小，再启动 Hermes。

14.3 第一次建议输入什么

先测试普通对话：

复制代码 
你好，请介绍一下你当前可用的模型、工具和技能。

然后测试只读项目分析：

复制代码 
请检查当前目录的项目结构，告诉我它是什么项目以及如何启动，但暂时不要修改任何文件。

再测试终端：

复制代码 
请运行 pwd 和 ls，解释当前目录中的主要文件，不要写入或删除任何内容。

不要一开始就让 Agent 执行大范围删除、系统升级或不可逆操作。

15. 常用命令速查

15.1 Shell 命令

复制代码 
hermes                         # 启动交互界面
hermes --cli                   # 使用传统 CLI 界面
hermes --version               # 查看版本
hermes doctor                  # 环境诊断
hermes status                  # 查看组件状态
hermes model                   # 选择模型
hermes tools                   # 配置工具
hermes setup                   # 完整设置向导
hermes setup terminal          # 配置终端后端
hermes setup gateway           # 配置消息平台
hermes portal                  # Nous Portal 登录与模型配置
hermes portal info             # 查看 Portal 路由状态
hermes auth status nous        # 检查 Nous 登录
hermes gateway status          # 检查 Gateway
hermes gateway restart         # 重启 Gateway
hermes update                  # 更新 Hermes

15.2 对话内命令

复制代码 
/help
/model
/tools
/skills
/new
/reset
/retry
/undo
/compress
/usage

具体可用命令以当前版本 /help 输出为准。

16. 配置与数据目录

默认目录：

复制代码 
~/.hermes/

常见文件：

复制代码 
~/.hermes/config.yaml       CLI 和模型等配置
~/.hermes/.env              API Key 等环境变量
~/.hermes/auth.json         认证状态
~/.hermes/hermes-agent/     代码与虚拟环境
~/.hermes/skills/           技能
~/.hermes/sessions/         会话
~/.hermes/logs/             日志
~/.hermes/cron/             定时任务
~/.hermes/state.db          状态数据库

查看配置：

复制代码 
hermes config

编辑配置：

复制代码 
hermes config edit

不要把 .env、auth.json 或其他凭据文件提交到 Git。

17. 安全边界

17.1 Local 后端意味着什么

Local 后端下，Hermes 可以在当前 WSL Ubuntu 中：

  • 读取和修改文件；

  • 执行 Shell 命令；

  • 访问 /mnt/c 等 Windows 挂载目录；

  • 调用浏览器工具；

  • 安装依赖；

  • 运行项目。

因此应把它视为一个具有当前 Linux 用户权限的自动化程序。

17.2 推荐的操作习惯

  • 首次进入项目先要求只读检查；

  • 明确指定工作目录；

  • 修改前要求说明计划；

  • 删除前要求列出精确目标；

  • 外部消息、支付、发布、授权等动作必须人工确认；

  • 不把密码、邮箱验证码、API Key 发到对话中；

  • 重要项目使用 Git；

  • 高风险任务考虑 Docker 或其他隔离后端。

17.3 防火墙规则的清理

不再需要 WSL 访问 Clash 7897 时：

复制代码 
Remove-NetFirewallRule -DisplayName "Clash-Wsl-7897"

删除前确认不会影响 WSL 后续联网。

18. 常见问题索引

18.1 Ubuntu 域名无法解析

复制代码 
ip route
cat /etc/resolv.conf
getent hosts github.com

没有默认路由时先恢复 WSL 网络，不要只改 DNS。

18.2 Ubuntu 只有 lo

将 .wslconfig 回退到 NAT：

复制代码 
[wsl2]
networkingMode=nat
dnsTunneling=true
autoProxy=false
firewall=true

然后：

复制代码 
wsl --shutdown

18.3 WSL 访问 7897 超时

依次检查：

  1. Clash 是否运行；

  2. 端口是否为 7897；

  3. 局域网连接是否打开；

  4. Windows 是否监听该端口；

  5. 防火墙规则是否允许 WSL 子网；

  6. Ubuntu 使用的是宿主机地址而不是 127.0.0.1。

18.4 GitHub 页面裸奔、无样式

测试：

复制代码 
curl.exe -I -x http://127.0.0.1:7897 `
  https://github.githubassets.com/favicons/favicon.svg

切换能完整返回 HTTP 200 的代理节点。

18.5 Nous Portal 浏览器已登录，但 Hermes 仍 logged out

复制代码 
hermes auth status nous

如果是 logged out，重新运行：

复制代码 
hermes portal

浏览器登录与设备码绑定是两个步骤。

18.6 hermes 启动后暂时黑屏

等待初始化，或使用：

复制代码 
hermes --cli

18.7 免费模型是否永久免费

不能保证。:free 代表选择时目录中的免费路由，是否持续免费、速率限制和可用性由服务端决定。

18.8 Gateway 没有消息平台

不影响本地 CLI。以后执行：

复制代码 
hermes setup gateway

19. 最终验收清单

逐项执行：

复制代码 
source ~/.bashrc

hermes --version
hermes auth status nous
hermes config get model.provider
hermes config get model.default
hermes gateway status

本次实测得到：

复制代码 
Hermes Agent v0.21.4
nous: logged in
nous
poolside/laguna-s-2.1:free
Gateway active (running)

浏览器验收：

复制代码 
cd "$HOME/.hermes/hermes-agent"
export PATH="$HOME/.hermes/node/bin:$PATH"
export PLAYWRIGHT_BROWSERS_PATH="$HOME/.cache/ms-playwright"
npx playwright screenshot about:blank /tmp/hermes-browser-test.png
test -s /tmp/hermes-browser-test.png && echo browser_ok

最后启动：

复制代码 
hermes

完成一次实际对话，才算完整链路真正打通。

20. 结语

这次实践的价值，不只是"把一个 CLI 装上了"。真正完成的是一条可复现、可验证、可排障的 Agent 运行链路：

复制代码 
WSL 网络
  -> Clash 代理
  -> 防火墙边界
  -> 官方安装脚本
  -> Python 与 Node 运行时
  -> 浏览器引擎
  -> Nous Portal OAuth
  -> 免费模型
  -> Local 终端后端
  -> Gateway
  -> 第一次真实对话

官方命令提供了入口，真实环境验证补齐了入口之后的工程细节。

只要读者遵守三个原则，这套流程就具备较强的可迁移性：

  1. 每一层都先验证，再进入下一层；

  2. 区分网络故障、依赖故障、认证故障和运行故障；

  3. 不通过关闭安全校验或强行绕过页面状态来"解决"问题。

当终端最终出现 Hermes Agent 的 TUI，并能使用已认证的模型完成第一次中文回复时，这条链路才真正闭环。

相关推荐
happylifetree1 小时前
Python17：核心语法-数据存储与运算-输入与输出
python
梅雅达编程笔记1 小时前
04-Python CSV数据保存与翻页抓取
开发语言·爬虫·python·pandas·数据采集·csv
估值探索者2 小时前
【Python量化策略实战 #04】Donchian 通道假突破太多？用 ATR 阈值过滤跑通真实突破信号
开发语言·python·接口·api接口·数据api接口·股票数据api接口
oooost2 小时前
Jupyter Notebook 常用快捷键速查
ide·python·jupyter
阿钱真强道2 小时前
30 嵌入式操作系统 | 上位机界面：Flask 网页显示 + 控制闭环
后端·python·flask
ysu_03142 小时前
Docker-Desktop-WSL2实战指南-Windows从安装配置到项目容器化
windows·python·docker·容器·composer·dockerfile·wsl2
郝学胜-神的一滴3 小时前
AI 编程智能体 02：AI智能体到底是什么
开发语言·人工智能·python·程序人生·pycharm
Guarding and trust3 小时前
python系列之多线程编程
python
梅雅达编程笔记3 小时前
03_网页表格数据抓取
爬虫·python·beautifulsoup·pandas·数据采集
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02历年考研数学一、数学二、数学三真题试卷及答案PDF03GitHub 镜像站点04Telegram APK 下载安装完整指南 — 2026年最新05蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接06微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新072026 爱知・名古屋亚运会怎么看？直播平台+赛程安排分享082026 年 9 月国内外主流大模型横向硬核评测：价格、算力、业务场景全维度对比，GPT‑6 Astra横空出世09给AI一张“业务概念地图“：本体如何从哲学走向企业智能10jev-ultrafast 深度解析：7 秒订机票的浏览器 Agent 是如何炼成的