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

目录

• 背景
• 需求
• 解决方案：.bat 启动脚本
• 实现要点
• .bat 脚本编写踩坑记录
• 坑1：%errorlevel%在代码块里不实时更新
• 坑2：!errorlevel!必须开启延迟扩展才能用
• 坑3：if %errorlevel%==0在代码块里失效
• 坑4：%%在 .bat 文件中的特殊含义
• 坑5：start /min wsl …的进程生命周期
• 坑6：timeout /t在等待循环里不能用/nobreak
• 完整代码
• 使用方法
• 效果
• 总结

Hermes Agent 是 Nous Research 开发的 AI 智能体，可以在 WSL2 中运行并提供 Web Dashboard 界面。但每次启动都需要打开 WSL2 终端，运行命令，然后手动打开浏览器访问 http://127.0.0.1:9119，步骤繁琐。

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

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

创建一个 .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秒

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

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

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

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

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

:: ❌ 错误写法（会报错）
@echo off
echo !errorlevel!
:: ✅ 正确写法
@echo off
setlocal enabledelayedexpansion
echo !errorlevel!

同理，因为 %errorlevel% 只解析一次，判断结果不准确。

解决方法：用 if not errorlevel 1（经典写法，不需要延迟扩展）。

if not errorlevel 1 的含义是：如果 errorlevel 不小于 1（即 errorlevel == 0）

这是 Windows .bat 脚本的经典 idiom，推荐优先使用。

在 .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} 当作环境变量来展开，导致错误。

最开始我用了 wsl -d Ubuntu-22 -- ... 直接启动，但发现 .bat 文件执行完毕后，WSL 进程也随之退出（因为 .bat 是同步等待子进程结束的）。

解决方法：用 start /min wsl ... 在独立的最小化窗口中启动 WSL，这样：

• .bat 文件不会被阻塞（ start 是异步的）
• WSL 进程不会随 .bat 退出而丢失
• 窗口是最小化的，不会干扰用户

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 图标

场景	行为
Dashboard 已在运行	直接打开浏览器访问 http://127.0.0.1:9119
Dashboard 未运行	在后台（最小化窗口）启动 WSL2 中的 Hermes，等待 5 秒后开始轮询，检测到就绪后立即打开浏览器

通过 .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 Agent Web Dashboard的详细步骤的文章就介绍到这了,更多相关Windows启动Hermes Agent Web Dashboard内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！