在Windows上优雅地启动Hermes Agent Web Dashboard的详细步骤实践整理

平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“在Windows上优雅地启动Hermes Agent Web Dashb……”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际使用顺序，把思路、关键写法和容易踩坑的地方讲清楚，方便你直接对照操作。

背景

落到代码里，Hermes Agent 是 Nous Research 开发的 AI 智能体，可以在 WSL2 中运行同时提供 Web Dashboard 界面。但每次启动都需打开 WSL2 终端，运行命令，然后手动打开浏览器访问 （链接已移除），步骤繁琐。

需求

我们希望在 Windows 桌面上双击一个图标，就能自动完成：

1. 检查 Dashboard 是否已在运行
2. 如果已在运行 → 直接打开浏览器
3. 若没运行 → 自动在后台启动，等就绪后再打开浏览器

解决方案：.bat 启动脚本

新建一个 .bat 批处理文件，借助 Windows 的 wsl 命令启动 WSL2 中的 Hermes，同时用 curl 检测端口状态。

实现要点

.bat 脚本编写踩坑记录

在这个场景下，这部分是本文的核心价值，记录了编写这个不到30行 .bat 文件时踩的所有坑。

坑1：%errorlevel%在代码块里不实时更新

.bat 文件中，%errorlevel% 在 (...) 代码块里只会在进入代码块时结合项目来看，解析一次，后续变化不会反映到 %errorlevel% 里。

if condition (
    some_command          :: 这个命令改变了 errorlevel
    echo %errorlevel%    :: ❌ 这里永远是进入代码块时的值，不是最新值！
)

解决方法：用 setlocal enabledelayedexpansion 开启延迟环境变量扩展，随后用 !errorlevel! 拿到实时值。

坑2：!errorlevel!必须开启延迟扩展才能用

如果直接用 !errorlevel! 而没有在文件开头加 setlocal enabledelayedexpansion，cmd.exe 会报错。

:: ❌ 错误写法（会报错）
@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}。

:: 在 .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，放到桌面：

@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 秒（代码里是无限循环，可以自行加上计数器限制）

采用方法

1. 打开记事本（Notepad）
2. 粘贴上面的代码
3. 另存为 → 选择桌面 → 文件名填 Hermes Web.bat → 编码选 ANSI 或 UTF-8 均可 → 保存
4. 双击桌面上的 Hermes Web.bat 图标

效果

总结

借助 .bat 脚本 + wsl 命令，可以在 Windows 上优雅地启动 WSL2 中的 Hermes Agent，同时自动打开浏览器访问 Web Dashboard。

核心知识点：

1. .bat 脚本中 %errorlevel% 在代码块里不实时更新 → 用 if not errorlevel 1 或 !errorlevel!
2. %% 在 .bat 中表示 literal % → 写 %%{http_code} 才能让 curl 收到 %{http_code}
3. start /min 可以让子进程在独立窗口运行，不随父进程退出而丢失

在这个场景下，总的来说，Windows启动Hermes这部分内容适合结合实际项目边做边理解。先抓住核心思路，再逐步补上细节和边界处理，最后效果会更稳定，也更容易复用。