🎯 教程目标
解决 WSL 终端乱码、花屏问题
成功部署 Hermes Agent 网页版管理面板
实现后台运行，关闭终端不中断服务
浏览器稳定访问，彻底告别终端操作
最终效果：
📋 前置条件
已安装 WSL 2（Ubuntu 24.04 LTS）
已完成 Hermes Agent 基础安装（可执行
hermes --version验证）已配置好 Python 虚拟环境（
~/.hermes/hermes-agent/venv）
🔧 第一阶段：安装网页版依赖（仅需执行一次）
步骤 1：进入 Hermes 虚拟环境
bash
运行
source ~/.hermes/hermes-agent/venv/bin/activate终端前缀变为
(venv)即成功
步骤 2：安装 Node.js + npm（网页构建必需）
bash
运行
# 更新软件源
sudo apt update
# 安装 Node.js 和 npm
sudo apt install -y nodejs npm
# 升级 npm 到稳定版
sudo npm install -g n
sudo n stable
# 刷新环境变量
PATH="$PATH"步骤 3：安装 Hermes 网页界面依赖
bash
运行
# 安装网页版组件
pip install "hermes-agent[web]"
步骤 4：手动构建网页 UI（解决自动构建失败）
bash
运行
# 进入 web 目录
cd ~/.hermes/hermes-agent/web
# 安装前端依赖
npm install
# 构建网页界面
npm run build
# 回到用户主目录
cd ~步骤 5：验证网页版启动
bash
运行
hermes dashboard成功输出：
Hermes Web UI → http://127.0.0.1:9119后续
xdg-open报错无需处理（WSL 无图形浏览器，服务已正常运行）
🌐 第二阶段：浏览器访问网页版
步骤 1：获取 WSL 真实 IP（解决 localhost 访问失败）
bash
运行
hostname -I示例输出：
172.21.78.204（每个人 IP 不同，以实际为准）
步骤 2：浏览器访问
打开 Windows 浏览器（Edge/Chrome），输入地址：
plaintext
http://<WSL_IP>:9119
# 示例：http://172.21.78.204:9119
# 也可直接尝试 http://localhost:9119（WSL 自动转发正常时可用）成功进入 Hermes Agent 管理面板即完成部署
🚀 第三阶段：后台运行（关闭终端不中断）
方案一：零门槛 nohup 方案（推荐，无需快捷键）
步骤 1：停止当前前台运行的 dashboard
bash
运行
# 按 Ctrl+C 终止当前进程步骤 2：一键后台启动
bash
运行
# 确保在 (venv) 虚拟环境中执行
nohup hermes dashboard > /dev/null 2>&1 &执行后无输出即成功，直接关闭终端即可
步骤 3：验证后台运行
关闭终端后，浏览器重新访问 http://<WSL_IP>:9119，面板正常打开即成功
常用维护命令
bash
运行
# 查看后台进程
ps aux | grep hermes
# 停止后台运行
pkill -f "hermes dashboard"
# 重启后台（先停止再执行启动命令）
nohup hermes dashboard > /dev/null 2>&1 &方案二：tmux 会话方案（适合需要查看日志的场景）
步骤 1：安装 tmux（仅需一次）
bash
运行
sudo apt update && sudo apt install -y tmux步骤 2：创建后台会话
bash
运行
tmux new -s hermes-dashboard步骤 3：进入虚拟环境并启动面板
bash
运行
source ~/.hermes/hermes-agent/venv/bin/activate
hermes dashboard步骤 4：后台分离会话（关键！）
依次按下快捷键（不是输入字符）：
按住
Ctrl键，按一下B，然后松开松开
Ctrl键，按一下D
终端显示
[detached (from session hermes-dashboard)]即成功，可关闭终端
常用维护命令
bash
运行
# 重新连接会话（查看日志/停止服务）
tmux attach -t hermes-dashboard
# 停止服务（连接会话后按 Ctrl+C）
# 彻底删除会话
tmux kill-session -t hermes-dashboard📌 第四阶段：日常使用流程（每次开机后）
1. 启动后台服务
bash
运行
# 打开 WSL 终端，执行
source ~/.hermes/hermes-agent/venv/bin/activate
nohup hermes dashboard > /dev/null 2>&1 &
# 直接关闭终端2. 浏览器访问
plaintext
http://localhost:9119 或 http://<WSL_IP>:9119❌ 常见问题排查
1. 浏览器 ERR_CONNECTION_REFUSED
检查 WSL 内服务是否运行：
ps aux | grep hermes重新启动服务：
pkill -f "hermes dashboard"→ 重新执行后台启动命令用 WSL IP 替代 localhost 访问
2. 网页构建失败（npm install 报错）
切换 npm 国内源：
npm config set registry https://registry.npmmirror.com重新执行
npm install和npm run build
3. 虚拟环境失效
重新进入：
source ~/.hermes/hermes-agent/venv/bin/activate
4. WSL 重启后服务中断
重新执行「日常使用流程」启动后台服务即可
✅ 最终效果
浏览器打开
http://localhost:9119，直接进入 Hermes Agent 网页管理面板支持会话聊天、技能配置、日志查看等全功能
后台运行，关闭终端、WSL 窗口不影响服务
彻底解决终端乱码、花屏问题
💡 补充说明
hermes gateway是消息桥接服务（对接 Telegram/WhatsApp 等），不是网页聊天界面，请勿混淆网页版默认端口
9119，如需修改可在~/.hermes/.env中配置DASHBOARD_PORT=xxxxWSL 完全关闭 / 电脑重启后，后台服务会终止，需重新启动