Hermes Agent 是 Nous Research 开发的 AI 智能体，可以在 WSL2 中运行并提供 Web Dashboard 界面。但每次启动都需要打开 WSL2 终端，运行命令，然后手动打开浏览器访问 http://127.0.0.1:9119，步骤繁琐。
需求
我们希望在 Windows 桌面上双击一个图标，就能自动完成：
- 检查 Dashboard 是否已在运行
- 如果已在运行 → 直接打开浏览器
- 如果没运行 → 自动在后台启动，等就绪后再打开浏览器
解决方案：.bat 启动脚本
创建一个 .bat 批处理文件，利用 Windows 的 wsl 命令启动 WSL2 中的 Hermes，并用 curl 检测端口状态。
实现要点
| 要点 | 实现方式 | |
|---|---|---|
| 检测是否运行 | `curl -s -o nul -w "%%{http_code}" http://127.0.0.1:9119/ 2>nul ^ | findstr "200"` |
| 判断结果 | if not errorlevel 1（errorlevel==0 表示返回200） | |
| 后台启动 WSL2 | start /min wsl -d Ubuntu-22 --user sanlin -- bash -c "..." | |
| 等待就绪 | :waitloop + timeout /t 1 每秒轮询，最多30秒 |
.bat 脚本编写踩坑记录
这部分是本文的核心价值，记录了编写这个不到30行 .bat 文件时踩的所有坑。
坑1：%errorlevel%在代码块里不实时更新
.bat 文件中，%errorlevel% 在 (...) 代码块里只会在进入代码块时解析一次，后续变化不会反映到 %errorlevel% 里。
|
1 2 3 4 |
if condition ( some_command :: 这个命令改变了 errorlevel echo %errorlevel% :: ? 这里永远是进入代码块时的值，不是最新值！ ) |
解决方法：用 setlocal enabledelayedexpansion 开启延迟环境变量扩展，然后用 !errorlevel! 获取实时值。
坑2：!errorlevel!必须开启延迟扩展才能用
如果直接用 !errorlevel! 而没有在文件开头加 setlocal enabledelayedexpansion，cmd.exe 会报错。
|
1 2 3 4 5 6 7 |
:: ? 错误写法（会报错） @echo off echo !errorlevel! :: ? 正确写法 @echo off setlocal enabledelayedexpansion echo !errorlevel! |
坑3：if %errorlevel%==0在代码块里失效
同理，因为 %errorlevel% 只解析一次，判断结果不准确。
解决方法：用 if not errorlevel 1（经典写法，不需要延迟扩展）。
if not errorlevel 1 的含义是：如果 errorlevel 不小于 1（即 errorlevel == 0）
这是 Windows .bat 脚本的经典 idiom，推荐优先使用。
坑4：%%在 .bat 文件中的特殊含义
在 .bat 文件中，%% 表示一个 literal % 字符。所以当我们要将 %{http_code} 传递给 curl 的 -w 参数时，必须写成 %%{http_code}。
|
1 2 3 4 5 |
:: 在 .bat 文件里这样写： curl -s -o nul -w "%%{http_code}" http://127.0.0.1:9119/
:: cmd.exe 执行时，%%{http_code} → %{http_code} :: 这正是 curl -w 参数期望的格式化字符串 |
如果在 .bat 文件里直接写 %{http_code}，cmd.exe 会试图将 {http_code} 当作环境变量来展开，导致错误。
坑5：start /min wsl ...的进程生命周期
最开始我用了 wsl -d Ubuntu-22 -- ... 直接启动，但发现 .bat 文件执行完毕后，WSL 进程也随之退出（因为 .bat 是同步等待子进程结束的）。
解决方法：用 start /min wsl ... 在独立的最小化窗口中启动 WSL，这样：
- .bat 文件不会被阻塞（ start 是异步的）
- WSL 进程不会随 .bat 退出而丢失
- 窗口是最小化的，不会干扰用户
坑6：timeout /t在等待循环里不能用/nobreak
timeout /t 1 /nobreak 在某些 Windows 版本里会等待用户按键。在等待循环里应该用 timeout /t 1 >nul 静默等待。
完整代码
将以下内容保存为 Hermes Web.bat，放到桌面：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
@echo off chcp 65001 >nul 2>&1 setlocal EnableDelayedExpansion title Hermes Web Dashboard
echo ============================================ echo Hermes Agent - Web Dashboard Launcher echo ============================================ echo.
:: Check if already running curl -s -o nul -w "%%{http_code}" http://127.0.0.1:9119/ 2>nul | findstr "200" >nul if not errorlevel 1 ( echo [OK] Already running, opening browser... start http://127.0.0.1:9119 exit /b 0 )
echo [INFO] Starting Hermes Dashboard in WSL2... start /min wsl -d Ubuntu-22 --user sanlin -- bash -c "cd ~/.hermes/hermes-agent && source .venv/bin/activate && hermes dashboard --host 0.0.0.0 --insecure --tui --no-open"
echo [INFO] Waiting for dashboard to start... timeout /t 5 >nul
:waitloop curl -s -o nul -w "%%{http_code}" http://127.0.0.1:9119/ 2>nul | findstr "200" >nul if not errorlevel 1 ( echo [OK] Dashboard is ready! start http://127.0.0.1:9119 exit /b 0 ) timeout /t 1 >nul goto waitloop |
代码说明：
- chcp 65001：切换到 UTF-8 代码页，支持中文显示
- setlocal EnableDelayedExpansion：开启延迟环境变量扩展（本脚本里用 if not errorlevel 1 代替了 !errorlevel!，所以其实可以不用，但加上是好习惯）
- start /min wsl ...：在最小化窗口启动 WSL2，不阻塞 .bat 执行
- :waitloop 循环：每秒检测一次端口，最多等 30 秒（代码里是无限循环，可以自行加上计数器限制）
使用方法
- 打开记事本（Notepad）
- 粘贴上面的代码
- 另存为 → 选择桌面 → 文件名填 Hermes Web.bat → 编码选 ANSI 或 UTF-8 均可 → 保存
- 双击桌面上的 Hermes Web.bat 图标
效果
| 场景 | 行为 |
|---|---|
| Dashboard 已在运行 | 直接打开浏览器访问 http://127.0.0.1:9119 |
| Dashboard 未运行 | 在后台（最小化窗口）启动 WSL2 中的 Hermes，等待 5 秒后开始轮询，检测到就绪后立即打开浏览器 |
总结
通过 .bat 脚本 + wsl 命令，可以在 Windows 上优雅地启动 WSL2 中的 Hermes Agent，并自动打开浏览器访问 Web Dashboard。
核心知识点：
- .bat 脚本中 %errorlevel% 在代码块里不实时更新 → 用 if not errorlevel 1 或 !errorlevel!
- %% 在 .bat 中表示 literal % → 写 %%{http_code} 才能让 curl 收到 %{http_code}
- start /min 可以让子进程在独立窗口运行，不随父进程退出而丢失
