首页 Hermes WebUI 速查
master 2026-06-02 nesquena/hermes-webui
打开 Zread CodeWiki
340px

快速定位

目标最短入口说明
本地快速启动./start.sh自动发现大部分依赖与路径
一键 bootstrappython3 bootstrap.py适合仓库首次安装
后台守护启动./ctl.sh start适合自托管 / VM / homelab
查看状态./ctl.sh statusPID、uptime、端口、日志、/health
查看日志./ctl.sh logs --lines 100读 ~/.hermes/webui.log
停止服务./ctl.sh stop停掉后台 daemon
直接跑服务HERMES_WEBUI_PORT=8787 venv/bin/python server.py仅在你知道 Hermes 依赖已就绪时使用
健康检查curl http://127.0.0.1:8787/health验证服务是否可用

一句话架构

  • server.py api/：+ ，纯 Python 标准库 HTTP 服务。
  • static/：，纯 vanilla JS，不走构建链。
  • ~/.hermes/webui：会话、状态、工作区信息放在 一带的状态目录中。

最短启动流

1) 推荐路径：脚本自动发现

git clone https://github.com/nesquena/hermes-webui.git hermes-webui
cd hermes-webui
python3 bootstrap.py
# 或者
./start.sh

2) 自托管常用路径

./ctl.sh start
./ctl.sh status
./ctl.sh logs --lines 100
./ctl.sh restart
./ctl.sh stop

3) 直接启动

cd /path/to/hermes-agent
HERMES_WEBUI_PORT=8787 venv/bin/python /path/to/hermes-webui/server.py

关键能力块

聊天与会话

  • 支持继续会话、会话搜索、会话恢复。
  • 支持后台任务、工具卡片、会话分组。
  • 适合在浏览器里接管 CLI 的大部分工作流。

工作区与文件浏览

  • 可浏览 workspace 文件。
  • 可做文件预览、文件操作、git 检测。
  • workspace.js api/workspace.py

语音与主题

  • 支持语音输入。
  • 支持主题 / skin。
  • 语音引擎、麦克风与浏览器权限相关，常见问题优先看 settings。

认证与安全

  • 支持密码认证。
  • 支持签名 cookie / passkeys 等能力。
  • 127.0.0.1

配置与发现规则

start.sh 默认会自动发现

项目发现顺序 / 默认值
Hermes agent 目录HERMES_WEBUI_AGENT_DIR → $HERMES_HOME/hermes-agent → 相邻 ../hermes-agent
Python 可执行文件agent venv → 本仓库 .venv → system python3
状态目录HERMES_WEBUI_STATE_DIR → $HERMES_HOME/webui
默认工作区HERMES_WEBUI_DEFAULT_WORKSPACE → ~/workspace → 状态目录
端口HERMES_WEBUI_PORT → 命令行参数 → 8787

常用覆盖项

export HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent
export HERMES_WEBUI_PYTHON=/path/to/python
export HERMES_WEBUI_PORT=9000
export HERMES_WEBUI_HOST=0.0.0.0
export HERMES_WEBUI_PASSWORD='your-password'
./start.sh

关键环境变量

变量默认值作用
HERMES_WEBUI_AGENT_DIRauto-discoveredHermes Agent checkout 路径
HERMES_WEBUI_PYTHONauto-discoveredPython 可执行文件
HERMES_WEBUI_HOST127.0.0.1监听地址
HERMES_WEBUI_PORT8787WebUI 端口
HERMES_WEBUI_STATE_DIR$HERMES_HOME/webui会话和状态存储
HERMES_WEBUI_DEFAULT_WORKSPACE~/workspace默认工作区
HERMES_WEBUI_DEFAULT_MODELprovider default可选模型覆盖
HERMES_WEBUI_PASSWORDunset开启密码认证
HERMES_WEBUI_CSP_CONNECT_EXTRAunset额外允许的 connect-src origins
HERMES_WEBUI_EXTENSION_DIRunset扩展目录
HERMES_HOME~/.hermesHermes 基础状态目录
HERMES_CONFIG_PATH$HERMES_HOME/config.yamlHermes 配置文件

Docker

快速判断用哪种部署

场景推荐方式
本机 / 开发调试start.sh / bootstrap.py
自托管 VMctl.sh
需要隔离依赖Docker / Compose
想看完整容器指南docs/docker.md

Docker 速记

  • 官方提供预构建镜像（amd64 + arm64）。
  • docs/docker.md
  • 127.0.0.1

远程访问

常见方式

方式场景关键点
SSH tunnel临时远程访问ssh -N -L 8787:127.0.0.1:8787 user@host
Tailscale手机 / 多设备HERMES_WEBUI_HOST=0.0.0.0 + HERMES_WEBUI_PASSWORD
直接公网监听不推荐要特别注意认证与暴露面

记住这条

  • 127.0.0.1
  • HERMES_WEBUI_HOST
  • 没密码不要裸露到公网。

测试与验收

运行测试

cd hermes-webui
pytest tests/ -v --timeout=60

验收重点

  • 服务能启动。
  • /health
  • 远程访问路径正确。
  • 运行环境能找到 Hermes Agent 目录和 Python 解释器。

常见故障

启动失败 / 找不到路径

  • HERMES_WEBUI_AGENT_DIR
  • Python 不是 agent 依赖所在的 venv。
  • HERMES_HOME

Docker / 权限问题

症状常见原因优先修法
PermissionError at startupUID mismatch.env 里设 UID=$(id -u)
.env: permission denied0600 权限校验HERMES_SKIP_CHMOD=1
workspace 为空挂载 UID 不匹配检查 volume 与 UID
宿主机 localhost 访问失败容器内 localhost 指向容器自身改用 host.docker.internal / host.containers.internal
git: command not found两容器方案限制改单容器或扩展镜像

判断优先级

你要记住的最小集合

  • ./start.sh
  • ./ctl.sh start/status/logs
  • start.sh
  • 默认只监听本机；远程访问必须显式放开 host 并加密码。
  • server.py api/