BitSeek Claw WebUI

@bitseek/hermes-webui 用来在本机启动和管理 BitSeek Claw WebUI。

快速开始

全局安装：

npm install -g @bitseek/hermes-webui
hermes-webui start --port 8787 --open

Windows PowerShell 中请使用 npm 生成的 .cmd shim：

hermes-webui.cmd start --port 8787 --open

不全局安装，直接运行：

npx @bitseek/hermes-webui start --port 8787 --open

Windows PowerShell 中如果遇到 npx.ps1 cannot be loaded，使用 .cmd shim：

npx.cmd @bitseek/hermes-webui@latest start --port 8787 --open

启动成功后访问：

http://localhost:8787

如果 8787 端口已被占用，可以换一个端口：

hermes-webui start --port 8788 --open

使用前提

• Node.js 20 到 24。
• 本机需要可用的 Python 3。
• 如果 WebUI 要调用 Hermes Agent，需要准备 Hermes Agent checkout，并确保其中有 run_agent.py。

默认情况下，WebUI 会尝试从以下位置查找 Hermes Agent：

$HERMES_HOME/hermes-agent
../hermes-agent

如果没有显式设置 HERMES_HOME，默认值与官方 Hermes Agent 安装器保持一致：

Windows: %LOCALAPPDATA%\hermes
macOS/Linux: ~/.hermes

也可以显式指定：

export HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent
hermes-webui start --port 8787 --open

常用命令

hermes-webui start --port 8787 --open
hermes-webui status --port 8787
hermes-webui logs --lines 100
hermes-webui logs --follow
hermes-webui restart --port 8787
hermes-webui stop
hermes-webui version

hermes-webui start 默认是后台 daemon 模式；启动命令退出后，WebUI 仍会继续运行。 关闭终端窗口不会停止它。需要停止时运行：

hermes-webui stop

前台模式适合开发或调试：

hermes-webui start --foreground --port 8787

doctor 是诊断命令，不是启动前的必需步骤。首次安装后或启动失败时可以运行：

hermes-webui doctor

开机或登录自启动

如果希望 WebUI 在系统登录或开机后自动启动，可以安装为系统服务：

hermes-webui service install --port 8787

安装后会立即启动服务；如果只想安装自启动配置，不立刻启动：

hermes-webui service install --port 8787 --no-start

服务管理命令：

hermes-webui service status
hermes-webui service start
hermes-webui service stop
hermes-webui service restart
hermes-webui service uninstall

各平台使用的服务管理器：

• Linux: user systemd，unit 位于 ~/.config/systemd/user/bitseek-hermes-webui.service。
• macOS: launchd，plist 位于 ~/Library/LaunchAgents/com.bitseek.hermes-webui.plist。
• Windows: Task Scheduler，任务名 BitSeekHermesWebUI。

服务模式内部运行 hermes-webui start --foreground，由系统服务管理器负责守护和 自启动。普通的 hermes-webui start 仍适合手动后台启动。

首次启动会做什么

第一次运行 hermes-webui start 时，WebUI 会：

• 创建运行时状态目录。
• 创建并管理 Python venv。
• 安装 WebUI 所需的 Python 依赖。
• 检查当前 Python 是否能导入 Hermes Agent；如果不能，会把 HERMES_WEBUI_AGENT_DIR 指向的 Hermes Agent 以 editable 模式安装到 WebUI venv。
• 默认启用 BitSeek 外观和扩展入口，包括 “AI 同事” 页面。
• 启动 BitSeek Claw WebUI 服务。
• 等待 /health 健康检查通过。
• 把 PID、日志路径和运行时信息写入状态目录。

状态和日志

默认情况下，运行时状态会写入：

$HERMES_HOME/webui

重要文件：

server.pid
server.log
runtime.json
venv/

查看状态：

hermes-webui status --port 8787

查看日志：

hermes-webui logs --lines 200
hermes-webui logs --follow

环境变量

HERMES_HOME              Windows 默认 %LOCALAPPDATA%\hermes；macOS/Linux 默认 ~/.hermes
HERMES_WEBUI_STATE_DIR   默认 $HERMES_HOME/webui
HERMES_WEBUI_PYTHON      使用已有 Python 解释器
HERMES_WEBUI_VENV_DIR    默认 $HERMES_WEBUI_STATE_DIR/venv
HERMES_WEBUI_AGENT_DIR   Hermes Agent checkout 路径
HERMES_WEBUI_HOST        默认 127.0.0.1
HERMES_WEBUI_PORT        默认 8787

BitSeek 扩展默认值：

HERMES_WEBUI_EXTENSION_DIR                默认 ./extensions
HERMES_WEBUI_EXTENSION_STYLESHEET_URLS    默认 /extensions/themes/bitseek/index.css
HERMES_WEBUI_EXTENSION_SCRIPT_URLS        默认 /extensions/themes/bitseek/index.js,/extensions/index.js
HERMES_WEBUI_BOT_NAME                     默认 BitSeek Claw

这些默认值在 macOS、Linux、Windows 上都可用。显式设置同名环境变量可以覆盖 默认值。

示例：

export HERMES_HOME="$HOME/.hermes"
export HERMES_WEBUI_AGENT_DIR="$HERMES_HOME/hermes-agent"
hermes-webui start --port 8787 --open

Windows PowerShell 示例：

$env:HERMES_HOME="$env:LOCALAPPDATA\hermes"
$env:HERMES_WEBUI_AGENT_DIR="$env:HERMES_HOME\hermes-agent"
hermes-webui.cmd start --port 8787 --open

如果不想使用默认 venv，可以指定已有 Python：

export HERMES_WEBUI_PYTHON=/usr/bin/python3
hermes-webui start --port 8787 --open

排查问题

先运行：

hermes-webui doctor

常见问题：

• Port 8787 is already occupied：端口已被其他进程占用，换端口启动。
• Python 3 is required but was not found in PATH：安装 Python 3，或设置 HERMES_WEBUI_PYTHON。
• Hermes Agent dir: not found：设置 HERMES_WEBUI_AGENT_DIR 指向包含 run_agent.py 的 Hermes Agent 目录。
• AIAgent importable: fail：当前 WebUI Python 不能导入 Hermes Agent。运行 hermes-webui start 会自动尝试修复；如果仍失败，请查看 server.log 和 pip install -e 的错误输出。
• systemctl --user is not available：当前 Linux 会话没有可用的 user systemd。 可以先运行 hermes-webui start 手动后台启动，或启用 linger 后重试： sudo loginctl enable-linger $USER。
• WebUI runtime is missing：发布包缺少必要文件，需要维护者重新打包并发布。

维护者说明

同步 WebUI 文件：

npm run sync:vendor

发布前检查：

npm run check
npm pack --dry-run

确认 package.json 的 files 包含：

bin/
scripts/
templates/
vendor/
README.md

发布：

npm publish --access public

发布后验证：

npm view @bitseek/hermes-webui version
npx @bitseek/hermes-webui doctor

Windows PowerShell 验证：

npx.cmd @bitseek/hermes-webui doctor