nesquena/hermes-webui 来源: https://github.com/nesquena/hermes-webui

Hermes Web UI

Hermes Agent (https://hermes-agent.nousresearch.com/) 是一个复杂的自主智能体，运行在你的服务器上，通过终端或消息应用访问，它能记住所学内容，并且运行时间越长能力越强。

Hermes WebUI 是一个轻量级、深色主题的 Web 应用界面，运行在浏览器中，用于 Hermes Agent (https://hermes-agent.nousresearch.com/)。与 CLI 体验完全一致——你在终端中能做的事情，在这个 UI 中也能做。无需构建步骤、无需框架、无需打包工具，只需 Python 和原生 JavaScript。

界面布局：三栏。左侧边栏用于会话和导航，中间用于聊天，右侧用于工作区文件浏览。模型、配置文件和 workspace 控件位于 composer 底部栏——在撰写消息时始终可见。环状上下文图标可直观显示 token 用量。所有设置和会话工具都在 Hermes 控制中心（侧边栏底部的启动器）中。

• 支持浅色模式和完整的配置文件
• 自定义设置，配置密码
• 工作区文件浏览器，支持内联预览
• 会话项目、标签和工具调用卡片

这为你提供了几乎与 Hermes CLI 1:1 一致的用户体验，并且通过 SSH 隧道从 Hermes 设置安全访问。只需一条命令启动，再一条命令 SSH 隧道即可在你的电脑上访问。Web UI 的每个部分都使用你现有的 Hermes agent 和现有模型，无需额外设置。

为什么选择 Hermes

大多数 AI 工具每个会话都会重置。它们不知道你是谁、你做过什么、你的项目遵循什么约定，你需要每次都重新解释。Hermes 能跨会话保留上下文，在离线时运行定时任务，运行时间越长就越了解你的环境。它使用你现有的 Hermes agent 设置和现有模型，无需额外配置即可启动。

与其他智能体工具的关键区别：

• 持久记忆 —— 用户档案、agent 笔记、技能系统（保存可复用的流程）；Hermes 学习你的环境，无需重新学习
• 自托管调度 —— 离线时触发的 cron 任务，结果可通过 Telegram、Discord、Slack、Signal、电子邮件等平台交付
• 10+ 消息平台 —— 终端里的同一个 agent 也可以通过手机访问
• 自我提升的技能 —— Hermes 能根据经验自动编写并保存自己的技能；无需浏览市场，无需安装插件
• 提供商无关 —— OpenAI、Anthropic、Google、DeepSeek、OpenRouter 等
• 协调其他 agent —— 可为重型编码任务生成 Claude Code 或 Codex，并将结果带回自身记忆
• 自托管 —— 你的对话、你的记忆、你的硬件

与竞品对比 （格局正在动态变化——参见 docs/why-hermes.md 的完整分析）：

† Claude Code 有 CLAUDE.md / MEMORY.md 项目上下文和滚动自动记忆，但不具备全自动跨会话回忆。 ‡ Claude Code 有云端管理的调度（Anthropic 基础设施）和会话范围内的 /loop；不含自托管 cron。

最接近的对手是 OpenClaw —— 两者都是始终在线、自托管、开源、具有记忆、cron 和消息能力的 agent。关键区别在于：Hermes 会作为核心行为自动编写并保存自己的技能（OpenClaw 的技能系统以社区市场为中心）；Hermes 在版本更新中更稳定（OpenClaw 存在文档化的版本回归，ClawHub 曾发生涉及恶意技能的安全事件）；且 Hermes 原生运行在 Python 生态中。详细对比请参见 docs/why-hermes.md。

快速开始

运行仓库的引导脚本：

git clone https://github.com/nesquena/hermes-webui.git hermes-webui
cd hermes-webui
python3 bootstrap.py

或者继续使用 shell 启动脚本：

./start.sh

对于自托管 VM 或 homelab 安装，ctl.sh 封装了常见的守护进程生命周期命令，无需使用 fuser 或 pkill：

./ctl.sh start          # 后台守护进程，PID 记录在 ~/.hermes/webui.pid
./ctl.sh status         # PID、运行时间、绑定主机/端口、日志路径、/health
./ctl.sh logs --lines 100  # 查看 ~/.hermes/webui.log 后 100 行
./ctl.sh restart
./ctl.sh stop

ctl.sh start 在守护进程封装后以前台/无浏览器模式运行引导脚本，日志写入 ~/.hermes/webui.log，并遵循 .env 以及行内覆盖变量，例如 HERMES_WEBUI_HOST=0.0.0.0 ./ctl.sh start。

可选的会话预填充（recall prefill）

WebUI 可以为新的浏览器发起的 agent 轮次附加临时预填充消息。当部署中已有一个用于 Joplin、Obsidian、Notion、llm-wiki 或其他第三方笔记源的本地 recall 或 router 脚本，且希望浏览器聊天知道持久上下文所在位置时，此功能非常有用。

建议使用紧凑的路由器风格预填充（例如：“Joplin 包含持久的项目上下文；在回答细节相关的问题之前，请使用可用的笔记/搜索工具”），而不是将完整的笔记语料库转储到每个新的浏览器会话中。预填充应为 agent 指明检索方向；笔记/搜索工具应按需提供具体事实。

静态 JSON 仍然通过 prefill_messages_file 或 HERMES_PREFILL_MESSAGES_FILE 支持。对于动态 recall，请使用 WebUI 专用的脚本钩子显式启用：

webui_prefill_messages_script:
  - python3
  - /path/to/notes_recall.py
webui_prefill_messages_script_timeout: 5

或者：

HERMES_WEBUI_PREFILL_MESSAGES_SCRIPT="python3 /path/to/notes_recall.py" \
HERMES_WEBUI_PREFILL_MESSAGES_SCRIPT_TIMEOUT=5 \
./ctl.sh restart

脚本可以输出 OpenAI 风格的 JSON 消息列表、包含 messages 列表的 JSON 对象，或纯文本；纯文本会被包装为一条 user 预填充消息，这样动态 recall 文本会成为普通的上下文，而不是额外的系统指令。如果钩子必须提供系统级指导，请输出包含显式 role: "system" 条目的 JSON 消息。

解析前脚本输出限制为 256 KiB。解析后的预填充上下文受 webui_prefill_context_max_chars 或 HERMES_WEBUI_PREFILL_CONTEXT_MAX_CHARS 限制（默认：12,000 字符；设为 0 可禁用）。当动态脚本超出预算且配置了紧凑的静态预填充文件时，WebUI 会回退到该文件。如果没有紧凑的回退方案，WebUI 会注入一条简短的检索指令，而不是在每次新的浏览器轮次中发送过大的笔记/正文负载。

浏览器只会收到一条紧凑的状态事件（包含 source、label、消息计数、压缩元数据和脱敏的错误信息），永远不会收到预填充消息的正文。

可选的 Gateway 后端浏览器聊天

默认情况下，浏览器聊天通过 WebUI 进程内的传统运行时运行。高级自托管部署可以选择将新的浏览器轮次路由到正在运行的 Hermes Gateway API 服务器，同时保留现有的 WebUI /api/chat/start 和 /api/chat/stream 浏览器契约：

HERMES_WEBUI_CHAT_BACKEND=gateway \
HERMES_WEBUI_GATEWAY_BASE_URL=http://127.0.0.1:8642 \
HERMES_WEBUI_GATEWAY_API_KEY=... \
./ctl.sh restart

HERMES_WEBUI_CHAT_BACKEND 故意设置得很严格：只有 gateway、api_server 或 api-server 才能启用桥接。通用的真值（如 1 或 true）会被忽略，以避免现有部署意外更改执行所有权。如果省略了 HERMES_WEBUI_GATEWAY_API_KEY，WebUI 会在 API_SERVER_KEY 存在时回退使用它。当 Gateway 返回 HTTP 401 时，WebUI 会报告一个 gateway_auth_error，指出的是 WebUI↔Gateway 密钥不匹配，而不是 Gateway 的通用“无效 API 密钥”内容。

/api/health/agent 还会包含一个脱敏的 gateway_chat 块，以便运维人员查看是否配置了 gateway 模式、base URL 和 API 密钥的存在性，而不暴露密钥值。该 gateway_chat 字段仅作为运维诊断负载；目前不会在浏览器 UI 中显示为用户可见的健康横幅。

此桥接最适合已经本地运行 Hermes Gateway/API Server 的运维人员，并且希望浏览器发起的聊天使用与消息界面相同的运行时/工具路径。附件、取消、审批和澄清提示仍然遵循 WebUI 当前的兼容性路径，在运行时适配器迁移完成前，可能无法与所有消息界面完全匹配。

引导脚本将：

1. 检测 Hermes Agent，如果缺失则尝试官方安装程序（curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash）。
2. 查找或创建包含 WebUI 依赖的 Python 环境。
3. 启动 Web 服务器并等待 /health。
4. 打开浏览器，除非传递了 --no-browser。
5. 让你进入 WebUI 内的首次运行引导向导。

原生 Windows 目前不支持此引导脚本。请使用 Linux、macOS 或 WSL2。 关于 Windows / WSL 登录时自动启动，请参阅 docs/wsl-autostart.md。 社区维护的原生 Windows 设置文档见 @markwang2658/hermes-windows-native-guide (https://github.com/markwang2658/hermes-windows-native-guide)（配套设置仓库：@markwang2658/hermes-windows-native (https://github.com/markwang2658/hermes-windows-native)）。 来自 #1952 (https://github.com/nesquena/hermes-webui/issues/1952) 的社区报告指出：

• 内存： 社区测量原生模式下约 330 MB，而 WSL2+Docker 约 1080 MB（因配置而异）。
• 可用功能： 聊天、工作区浏览器、会话管理、所有主题。
• 已知限制： 工作区浏览器中会出现一些 POSIX 风格的文件路径；假设 bash 的 agent 工具可能无法在原生模式下工作。
• 原生 Windows 设置： 安装 Python 3.11+，然后在 hermes-agent 根目录下以 PowerShell 运行：python -m venv venv → pip install -r requirements.txt → pwsh .\start.ps1（它会自动发现 venv\Scripts\python.exe）。
• 与 WSL2 的关系： 不是先决条件——WSL2 构建的 venv（venv/bin/python，ELF 格式）无法被原生 Windows Python 调用，因此请使用上述原生设置。WSL2 仍然可以作为并行安装存在，如果你想要完整的 bootstrap.py + Linux 运行时。

如果安装后提供商设置仍未完成，引导向导会指导你使用 hermes model 来完成设置，而不是尝试在浏览器中复制完整的 CLI 设置过程。

关于向导的逐步说明、提供商选择、本地模型服务器 Base URL 和安全重新运行，请参阅 docs/onboarding.md。如果有 AI 助手协助安装、重新安装、引导、提供商设置或首次运行支持，请让它在运行命令或检查日志前阅读 docs/onboarding-agent-checklist.md。

Docker

预构建镜像（amd64 + arm64）会在每次发布时推送到 GHCR。关于涵盖所有 3 个 compose 文件、常见故障模式和 bind-mount 迁移的全面设置指南，请参阅 docs/docker.md。本 README 涵盖 5 分钟的轻松路径。

5 分钟快速开始（单容器）

最简单的设置：一个 WebUI 容器，内嵌运行 agent。

git clone https://github.com/nesquena/hermes-webui
cd hermes-webui
cp .env.docker.example .env
# 如果你的主机 UID 不是 1000（例如 macOS 上 UID 从 501 开始），请编辑 .env
docker compose up -d
# 打开 http://localhost:8787

使用拥有你的 Hermes 主目录的用户身份运行 Compose。sudo docker compose up -d 可能导致 ${HOME} 扩展为 root 用户的主目录，从而导致 Docker 挂载了错误的 .hermes 目录，而非你实际的 ~/.hermes，使得 WebUI 以 config.yaml (not found, using defaults) 启动。建议将你的用户添加到 Docker 组并运行 docker compose up -d；如果必须使用 sudo，请先设置绝对路径，例如 HERMES_HOME=/home/you/.hermes HERMES_WORKSPACE=/home/you/workspace sudo -E docker compose up -d，然后使用 docker compose config 验证。

容器会自动检测挂载的 ~/.hermes 卷的 UID/GID，使得 agent 写入的文件在主机上对你保持可读。

要启用密码保护（如果在 127.0.0.1 之外暴露端口则需要）：

echo "HERMES_WEBUI_PASSWORD=change-me-to-something-strong" >> .env
docker compose up -d --force-recreate

手动 docker run（无需 compose）

docker pull ghcr.io/nesquena/hermes-webui:latest
docker run -d \
  -e WANTED_UID=$(id -u) -e WANTED_GID=$(id -g) \
  -v ~/.hermes:/home/hermeswebui/.hermes \
  -e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui \
  -v ~/workspace:/workspace \
  -p 127.0.0.1:8787:8787 \
  ghcr.io/nesquena/hermes-webui:latest

本地构建

docker build -t hermes-webui .
docker run -d \
  -e WANTED_UID=$(id -u) -e WANTED_GID=$(id -g) \
  -v ~/.hermes:/home/hermeswebui/.hermes \
  -e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui \
  -v ~/workspace:/workspace \
  -p 127.0.0.1:8787:8787 \
  hermes-webui

多容器设置

如果你希望 agent 和 WebUI 放在不同容器中（为了隔离，或者因为你已经在别处运行了 agent 网关）：

# Agent + WebUI
docker compose -f docker-compose.two-container.yml up -d
# Agent + Dashboard + WebUI
docker compose -f docker-compose.three-container.yml up -d

这两个 compose 文件默认使用 命名 Docker 卷，从结构上解决了 UID/GID 问题。如果你需要使用 bind 挂载来共享现有主机目录，请参阅 docs/docker.md 了解完整的迁移配方。

已知限制 (#681)：在两容器设置中，从 WebUI 触发的工具在 WebUI 容器 中运行，而非 agent 容器。如果你需要在 WebUI 的文件系统上使用 git/node 等工具，请使用单容器设置、扩展 WebUI Dockerfile，或使用社区的一体化镜像 (https://github.com/sunnysktsang/hermes-suite)。

源码边界说明 (#2453)：多容器设置默认将 hermes-agent-src 以只读方式挂载到 WebUI 中。这防止了 WebUI 侧对源码的修改，但这仍然是实现耦合的桥接，并非稳定的 Agent API 边界。参见 docs/rfcs/agent-source-boundary.md 了解目前的源码/API 解耦清单。

常见故障模式