Skip to main content

Web 控制台

Web 控制台是一个基于浏览器的界面，用来管理你的 Hermes Agent 安装。你不需要手动编辑 YAML 文件，也不必反复敲 CLI 命令，就能通过网页完成配置、管理 API 密钥并查看会话状态。

快速开始​

hermes dashboard

这个命令会在本地启动一个 Web 服务器，并自动在浏览器中打开 http://127.0.0.1:9119。整个控制台都运行在你的机器上，不会把数据发到外部网络。

选项​

参数默认值说明
--port9119Web 服务器运行的端口
--host127.0.0.1绑定地址
--no-open—不自动打开浏览器
# Custom port
hermes dashboard --port 8080

# Bind to all interfaces (use with caution on shared networks)
hermes dashboard --host 0.0.0.0

# Start without opening browser
hermes dashboard --no-open

前置条件​

Web 控制台依赖 FastAPI 和 Uvicorn。可以通过下面的命令安装：

pip install hermes-agent[web]

如果你之前是通过 pip install hermes-agent[all] 安装的，那这些前端依赖已经一并装好了。

如果你运行 hermes dashboard 时缺少依赖，系统会直接提示需要安装什么。如果前端还没构建，而本机又有 npm，它会在第一次启动时自动构建。

页面功能​

状态​

首页提供对当前安装状态的实时概览：

  • Agent 版本 与 发布日期
  • 网关状态 —— 运行中/已停止，PID，已连接平台及其状态
  • 活跃会话数 —— 最近 5 分钟内活跃的会话数量
  • 最近会话列表 —— 显示最近 20 个会话，包含模型名称、消息数量、Token 使用量以及对话预览

状态页面每 5 秒自动刷新一次。

配置​

这是一个基于表单的 config.yaml 编辑器。150 多个配置字段都会从 DEFAULT_CONFIG 自动发现，并按标签页分类展示：

  • model —— 默认模型、提供商、基础 URL、推理设置
  • terminal —— 后端（本地/Docker/SSH/Modal）、超时时间、Shell 偏好
  • display —— 主题皮肤、工具进度显示、恢复显示、加载动画设置
  • agent —— 最大迭代次数、网关超时时间、服务等级
  • delegation —— 子代理限制、推理努力程度
  • memory —— 存储提供商选择、上下文注入设置
  • approvals —— 危险命令审批模式（询问 / 直接执行 / 拒绝）
  • 以及其他 —— config.yaml 中每个部分都有对应的表单字段

具有已知有效值的字段（如终端后端、皮肤、审批模式等）以下拉菜单形式呈现；布尔值以开关形式展示；其余均为文本输入框。

操作：

  • 保存 —— 立即把变更写回 config.yaml
  • 重置为默认值 —— 把所有字段恢复到默认值，但仍需点击“保存”才会真正生效
  • 导出 —— 下载当前配置为 JSON 格式文件
  • 导入 —— 上传一个 JSON 配置文件以替换当前值
tip

配置更改将在下一个 Agent 会话或网关重启时生效。Web 控制台编辑的是与 hermes config set 和网关读取相同的 config.yaml 文件。

API 密钥​

管理存储 API 密钥和凭证的 .env 文件。密钥按类别分组：

  • LLM 提供商 —— OpenRouter、Anthropic、OpenAI、DeepSeek 等
  • 工具 API 密钥 —— Browserbase、Firecrawl、Tavily、ElevenLabs 等
  • 消息平台 —— Telegram、Discord、Slack 机器人令牌等
  • Agent 设置 —— 非敏感环境变量，如 API_SERVER_ENABLED

每个密钥项都会显示：

  • 是否已设置（并显示脱敏后的值预览）
  • 用途说明
  • 提供商注册/获取密钥的链接
  • 输入框用于设置或更新值
  • 删除按钮用于移除该密钥

高级或不常用密钥默认隐藏，可通过切换按钮展开。

会话​

你可以在这里浏览并检查所有 Agent 会话。每一行都会显示会话标题、来源平台图标（CLI、Telegram、Discord、Slack、cron）、模型名称、消息数量、工具调用次数以及上次活跃时间。正在进行中的会话会用闪烁徽章标出来。

  • 搜索 —— 使用 FTS5 对所有消息内容进行全文检索。结果以高亮片段展示，展开后自动滚动到首个匹配消息。
  • 展开 —— 点击会话可加载完整消息历史。消息按角色（用户、助手、系统、工具）着色，并以 Markdown 渲染，支持语法高亮。
  • 工具调用 —— 包含工具调用的助手消息将显示可折叠的区块，包含函数名和 JSON 参数。
  • 删除 —— 使用垃圾桶图标永久删除会话及其消息历史。

日志​

查看 Agent、网关及错误日志文件，支持过滤和实时尾部查看。

  • 文件 —— 切换查看 agent、errors 或 gateway 日志文件
  • 级别 —— 按日志级别过滤：全部、调试、信息、警告、错误
  • 组件 —— 按来源组件过滤：全部、网关、Agent、工具、CLI、Cron
  • 行数 —— 选择显示的行数（50、100、200 或 500）
  • 自动刷新 —— 开启实时尾部查看，每 5 秒轮询新日志行
  • 颜色编码 —— 日志行按严重性着色（红色表示错误，黄色表示警告，灰色表示调试）

分析​

基于会话历史计算的使用情况与成本分析。选择时间段（7 天、30 天或 90 天）以查看：

  • 摘要卡片 —— 总 Token 数（输入/输出）、缓存命中率、总估算或实际成本、总会话数及日均值
  • 每日 Token 图表 —— 堆叠柱状图，显示每日输入与输出 Token 使用量，悬停显示详细分解与成本
  • 每日明细表格 —— 每日日期、会话数、输入 Token、输出 Token、缓存命中率、成本
  • 按模型细分 —— 表格列出每个使用的模型、其会话数、Token 使用量及估算成本

Cron​

创建和管理定时任务，按预定周期运行 Agent 提示。

  • 新建 —— 填写名称（可选）、提示内容、Cron 表达式（例如 0 9 * * *），以及交付目标（本地、Telegram、Discord、Slack 或邮件）
  • 任务列表 —— 每个任务显示名称、提示预览、调度表达式、状态徽章（启用/暂停/错误）、交付目标、上次运行时间、下次运行时间
  • 暂停 / 恢复 —— 在启用与暂停状态间切换任务
  • 立即触发 —— 手动立即执行任务，不受正常调度限制
  • 删除 —— 永久移除一个 Cron 任务

技能​

浏览、搜索并启用/禁用技能与工具集。技能从 ~/.hermes/skills/ 加载，并按类别分组。

  • 搜索 —— 按名称、描述或类别筛选技能与工具集
  • 类别筛选 —— 点击类别标签（如 MLOps、MCP、红队、AI）缩小列表范围
  • 启用/禁用 —— 使用开关按钮单独启用或禁用技能。更改将在下一个会话中生效。
  • 工具集 —— 单独区域展示内置工具集（文件操作、网页浏览等），显示其启用/禁用状态、设置要求及包含的工具列表
安全提示

Web 控制台会直接读取和写入包含 API 密钥等敏感信息的 .env 文件。它默认只绑定到 127.0.0.1，也就是仅限本机访问；如果你把它绑定到 0.0.0.0，那么同一网络里能访问这台机器的人都可能查看甚至修改你的凭据。控制台本身没有额外认证层。

/reload 斜杠命令​

本次控制台 PR 还为交互式 CLI 添加了 /reload 斜杠命令。在通过 Web 控制台（或直接编辑 .env）更改 API 密钥后，可在活跃的 CLI 会话中使用 /reload 来立即加载新配置，而无需重启：

You → /reload
  Reloaded .env (3 var(s) updated)

这个命令会重新读取 ~/.hermes/.env，并把更新后的环境变量注入到当前运行中的进程里。比如你刚在控制台里加了一组新的提供商密钥，又想立刻使用它，这时就很方便。

REST API​

Web 控制台暴露了一个供前端调用的 REST API。您也可以直接调用这些接口实现自动化：

GET /api/status​

返回代理版本、网关状态、平台状态以及当前活跃会话数量。

GET /api/sessions​

返回最近的 20 个会话及其元数据（模型、token 数量、时间戳、预览内容）。

GET /api/config​

以 JSON 格式返回当前 config.yaml 的内容。

GET /api/config/defaults​

返回默认配置值。

GET /api/config/schema​

返回一个描述所有配置字段的 schema —— 包含类型、描述、类别，以及适用的可选选项。前端使用此信息来为每个字段渲染正确的输入控件。

PUT /api/config​

保存新的配置。请求体：{"config": {...}}。

GET /api/env​

返回所有已知环境变量的设置状态（已设置/未设置）、脱敏后的值、描述和类别。

PUT /api/env​

设置一个环境变量。请求体：{"key": "VAR_NAME", "value": "secret"}。

DELETE /api/env​

移除一个环境变量。请求体：{"key": "VAR_NAME"}。

GET /api/sessions/{session_id}​

返回单个会话的元数据。

GET /api/sessions/{session_id}/messages​

返回该会话的完整消息历史记录，包括工具调用和时间戳。

GET /api/sessions/search​

对消息内容进行全文搜索。查询参数：q。返回匹配的会话 ID 及高亮片段。

DELETE /api/sessions/{session_id}​

删除一个会话及其消息历史。

GET /api/logs​

返回日志行。查询参数：file（agent/errors/gateway），lines（数量），level，component。

GET /api/analytics/usage​

返回 token 使用量、成本及会话分析数据。查询参数：days（默认为 30）。响应包含每日细分数据和各模型聚合统计。

GET /api/cron/jobs​

返回所有已配置的定时任务，包括其状态、调度计划和运行历史。

POST /api/cron/jobs​

创建一个新的定时任务。请求体：{"prompt": "...", "schedule": "0 9 * * *", "name": "...", "deliver": "local"}。

POST /api/cron/jobs/{job_id}/pause​

暂停一个定时任务。

POST /api/cron/jobs/{job_id}/resume​

恢复已暂停的定时任务。

POST /api/cron/jobs/{job_id}/trigger​

立即触发一个定时任务，不受原定计划限制。

DELETE /api/cron/jobs/{job_id}​

删除一个定时任务。

GET /api/skills​

返回所有技能，包括名称、描述、类别和启用状态。

PUT /api/skills/toggle​

启用或禁用某个技能。请求体：{"name": "skill-name", "enabled": true}。

GET /api/tools/toolsets​

返回所有工具集，包括标签、描述、工具列表以及是否处于激活/配置状态。

CORS​

Web 服务器将 CORS 限制为仅允许本地主机来源：

  • http://localhost:9119 / http://127.0.0.1:9119（生产环境）
  • http://localhost:3000 / http://127.0.0.1:3000
  • http://localhost:5173 / http://127.0.0.1:5173（Vite 开发服务器）

如果你在自定义端口上运行服务，该来源会自动添加。

开发​

如果你正在贡献 Web 控制台前端代码：

# Terminal 1: start the backend API
hermes dashboard --no-open

# Terminal 2: start the Vite dev server with HMR
cd web/
npm install
npm run dev

Vite 开发服务器默认运行在 http://localhost:5173，并会把 /api 请求代理到 http://127.0.0.1:9119 上的 FastAPI 后端。

前端基于 React 19、TypeScript、Tailwind CSS v4 和 shadcn/ui 风格组件构建。生产构建输出至 hermes_cli/web_dist/，由 FastAPI 服务器作为静态 SPA 提供服务。

更新时自动构建​

当你运行 hermes update 时，如果 npm 可用，前端将自动重新构建。这确保了控制台与代码更新保持同步。如果 npm 未安装，则更新过程跳过前端构建，hermes dashboard 将在首次启动时完成构建。