ByteNoteByteNote
字

字节笔记本

2026年6月21日

hermes教程-桌面应用

#AI 前沿
API中转
¥120
每日科技简报 · 每天一篇,快速了解科技圈大事

Hermes 桌面应用是一个原生应用，围绕与 CLI 和网关相同的代理构建——相同的配置、相同的 API 密钥、相同的会话、相同的技能、相同的内存。它不是独立的产品或轻量级克隆；它使用相同的 Hermes Agent 核心和设置，并通过现代且精心设计的 UI 驱动。如果你在终端中使用过 hermes，你在这里设置的所有内容都已经存在，并且你在这里做的任何操作也会在那里出现。

它运行在 macOS、Windows 和 Linux 上。

提示——哪个界面是哪个？

Hermes 有多个前端，它们都与同一个代理通信：

  • 桌面应用（本页）——一个原生应用，具有专为聊天、配置和管理设计的 UI。
  • CLI (hermes) 和 TUI (hermes --tui) ——终端界面。
  • Web 仪表盘 (hermes dashboard) ——一个浏览器管理面板；其可选的聊天标签页通过伪终端嵌入 TUI。

选择适合当前场景的界面。它们共享状态，因此你可以在一个界面中开始会话，然后在另一个界面中继续。

安装

按照 Hermes 桌面版安装说明 进行操作。

如果你已经安装了 Hermes，只需运行

bash
hermes desktop

这将使用你当前的配置、密钥、会话和技能。

应用包含什么

桌面应用组织为一个以聊天为主的窗口，左侧边栏用于导航。它旨在允许管理多个并发的代理对话、配置消息提供商、创建工件、浏览项目的文件夹结构，并同时处理多个项目。

聊天

应用的中心。你可以获得：

  • 流式响应，包含实时的工具活动和结构化的工具调用摘要，当代理工作时。
  • 与所有其他 Hermes 界面相同的对话历史——在此处开始的会话可以在 CLI/TUI 中继续，反之亦然。
  • 拖放文件到聊天区域的任何位置，以将文件附加到你的下一条消息。
  • 右侧预览栏——在继续聊天的同时，并排渲染网页、文件和工具输出。
  • 编辑器历史和队列编辑——在空编辑器中按上/下箭头键可以回忆并重复使用之前的提示，并在发送前编辑已排队的消息。

状态栏

聊天底部的栏显示实时的会话状态，并提供快速控制，无需打开设置：

  • 每个会话的 YOLO 切换——为此会话打开或关闭 YOLO（与 TUI 匹配）。YOLO 绕过危险命令的批准提示，因此请了解你关闭了什么——请参阅 安全 → YOLO 模式。

正在与另一台机器上的 Hermes 实例聊天，而不是与捆绑的本地后端？请参阅下面的连接到远程后端——有关远程托管仪表盘连接如何工作的完整说明（身份验证网关、/api/ws 聊天套接字和 WebSocket 关闭代码分类），请参阅 Web 仪表盘 → 将 Hermes 桌面版连接到远程后端。

选择模型

模型选择器位于编辑器中，麦克风按钮的左侧。点击它可以从一个下拉菜单中切换模型、推理努力和快速模式。

  • 编辑器选择器是粘性 UI 状态，永远不会触及你的默认设置。 它在本地（每台设备）记住，并在新聊天和重启时跟随，而不是恢复到默认值——选择一次模型，下次 Cmd/Ctrl+N 就会打开它。在实时聊天中，切换模型会将更改范围限定到当前聊天；无论哪种方式，当会话创建/切换时，选择都会随之移动，并且从不写入配置文件默认值。（切换配置文件会重新使用该配置文件自己的默认值。）
  • 在设置 → 模型中设置默认值。 那个“主要”模型是你的每个配置文件的全局默认值——新聊天、定时任务、子代理和辅助任务都从它开始，并且它是唯一写入它的地方。每个配置文件保留自己的默认值。
  • 每个模型的努力/快速预设。 每个模型在桌面应用中记住自己的推理努力和快速模式选择，并在你选择该模型时重新应用到会话。这些预设是桌面版的便利功能，不会更改定时任务或子代理。

文件浏览器

无需离开应用即可浏览和预览工作目录——在代理读取、写入和编辑文件时，方便跟进。使用 hermes desktop --cwd <path>（或 HERMES_DESKTOP_CWD 环境变量）设置初始项目目录。

语音

与 Hermes 对话并听到它的回应，与语音模式在其他地方提供的功能相同。在 macOS 上，操作系统会提示一次麦克风访问权限。

设置与入门引导

通过真实的 UI 管理提供商、模型、工具和凭据，而不是编辑 YAML。首次运行的入门引导让你在几秒钟内发送第一条消息。设置面板涵盖提供商/密钥、模型选择、工具集配置、MCP 服务器、网关和会话管理。

  • 提供商设置面板——一个专门管理推理提供商的地方，具有账户/API 密钥的用户体验，用于登录和存储每个提供商的凭据。
  • 菜单中的每个提供商和模型——GUI 显示完整的提供商列表和 hermes model 知道的每个模型，因此你从 CLI 看到的相同目录中选择，而不是精选子集。
  • xAI Grok OAuth——Grok 是启动器中的一等 OAuth 提供商；像其他 OAuth 提供商一样通过浏览器流程登录。
  • 从 GUI 安装工具后端——直接从应用运行工具后端的安装后设置步骤，而不是切换到终端。
  • 辅助模型警告——如果你将主要模型切换到新的提供商，而辅助任务（标题、摘要和类似助手）仍固定到另一个提供商，应用会警告你，这样你就不会无意中将工作分散到两个提供商。

首次运行的入门引导已重新设计为统一的覆盖设计系统，你可以选择稍后选择提供商以跳过提供商设置并先进入应用。

管理面板

应用还提供了更广泛的 Hermes 管理界面，因此你无需切换到终端：

  • 技能——浏览、安装和管理技能。
  • 定时任务——查看和管理计划任务。
  • 配置文件——切换 Hermes 配置文件（隔离的配置/技能/会话）。
  • 消息——设置网关通道。
  • 代理和指挥中心——用于多代理工作的编排界面。

键盘与导航

  • 命令面板——按 Cmd+K（Windows/Linux 上为 Ctrl+K）跳转到操作并从键盘导航应用。
  • 可重新绑定的快捷键——设置中的快捷键面板允许你将应用的键盘快捷键重新映射到你自己的按键。
  • 自定义缩放快捷键——以半步增量缩放界面，以便更精细地控制文本大小。
  • UI 语言切换器——在应用内更改应用的界面语言，包括简体中文（zh-Hans）。

会话与配置文件

  • 会话列表大修——重新设计的会话列表，带有归档和常规会话卫生，以便在列表增长时保持可管理。
  • 按 ID 搜索会话——直接通过 ID 查找特定会话。
  • 并发多配置文件会话——同时在多个配置文件上运行会话，并使用跨配置文件的 @session 链接引用另一个配置文件中的会话。

更新

应用在后台检查更新，并在有更新时提供一键更新。

手动更新过程也适用于 GUI。

卸载

打开设置 → 关于 → 危险区域，选择要删除的内容：

  • 仅卸载聊天 GUI——删除桌面应用及其数据；Hermes 代理、你的配置和聊天记录保留。（与 hermes uninstall --gui 相同。）
  • 卸载 GUI + 代理，保留我的数据——删除应用和代理，但保留配置、聊天记录和密钥，以便将来重新安装。（与 hermes uninstall 相同。）
  • 卸载所有内容——删除应用、代理和所有用户数据。（与 hermes uninstall --full 相同。）

应用会关闭以完成操作（清理在退出后运行，因此它可以删除正在运行的应用包及其自己的 venv）。当没有安装本地代理时（例如，连接到远程后端的仅 GUI“精简”客户端），代理删除选项会自动隐藏。

你也可以从终端执行相同操作——hermes uninstall --gui 仅删除 GUI，或 hermes uninstall / hermes uninstall --full 同时删除代理。

注意

从源代码检出（hermes desktop 开发构建）运行 hermes uninstall --gui 也会删除工作区的 node_modules 和 apps/desktop/{dist,release} 构建输出，因为这些是 GUI 构建工件。它们可以通过 hermes desktop（或 npm install + 重新构建）恢复——但如果你正在积极开发桌面应用，之后需要重新安装依赖项。

CLI 参考：hermes desktop

要通过 CLI 启动，只需运行 hermes desktop。默认情况下，它会安装工作区 Node 依赖项，构建当前操作系统的未打包 Electron 应用，然后启动该打包的工件。

标志描述
--skip-build跳过 npm install/package，并从 apps/desktop/release 启动现有的未打包应用
--force-build即使内容戳匹配，也强制完全重新构建
--build-only构建桌面应用但不启动它（由 hermes update 使用）
--source通过 electron . 针对 apps/desktop/dist 启动，而不是打包的应用
--cwd PATH桌面聊天会话的初始项目目录（设置 HERMES_DESKTOP_CWD）
--hermes-root PATH覆盖应用使用的 Hermes 源代码根目录（设置 HERMES_DESKTOP_HERMES_ROOT）
--ignore-existing强制应用在后台解析期间忽略 PATH 上已有的任何 hermes CLI
--fake-boot启用确定性启动延迟，用于验证启动 UI

工作原理

打包的应用仅包含 Electron 外壳。首次启动时，它将 Hermes Agent 运行时安装到 HERMES_HOME（~/.hermes，或 Windows 上的 %LOCALAPPDATA%\hermes）——与 CLI 安装使用的布局相同，这就是为什么两者可以互换。React 渲染器通过标准网关 API 与 hermes dashboard 后端通信，并重用代理而不是重新实现它。安装、后端解析和自更新逻辑位于 Electron 主进程中。

连接到远程后端

默认情况下，应用启动并管理自己的本地后端。你可以将其指向另一台机器上运行的 Hermes 后端——VPS、家庭服务器或 Tailscale 后面的 Mini。

信息——远程后端是一个正在运行的 hermes dashboard 进程

“远程后端”指的是远程机器上运行的 hermes dashboard 服务器——这是桌面应用连接的进程。除非该仪表盘实际运行并可访问，否则本节中的任何内容都不起作用。桌面应用不会为你启动它；你（或 systemd 服务）在远程主机上保持 hermes dashboard 运行，应用会附加到它。如果你还使用消息通道（Telegram、Discord 等），网关是一个独立的长时间运行进程，你需要单独启动——请参阅设置步骤后的注释。

连接分为两部分：在后端，你使用身份验证提供商保护仪表盘；在应用中，你输入后端的 URL 并登录。将仪表盘绑定到非回环地址会自动启用其身份验证网关，你配置的提供商允许桌面应用通过。

根据后端所在位置选择提供商：

  • OAuth（Nous Portal）——对于任何超出你自己机器可访问范围的情况，首选。 登录凭据会针对你的 Nous 账户进行验证，因此这是适用于 VPS、公共主机或任何远程后端的选项。使用 hermes dashboard register（或 Portal /local-dashboards 页面）注册仪表盘以配置其 OAuth 客户端，然后从应用中使用使用 Nous Research 登录进行登录。如果你运行自己的身份提供商，自托管的 OIDC 提供商的工作方式相同。
  • 用户名/密码——仅限本地/受信任网络使用。 当后端位于同一受信任的 LAN 上或仅通过 VPN（例如 Tailscale）可访问时，这是最简单的选项。它使用单个共享凭据保护，没有外部身份提供商，因此不要将其用于暴露在公共互联网上的仪表盘——在这种情况下请使用 OAuth。

本节的其余部分展示了用户名/密码路径，因为这是在受信任网络上最快搭建的方式；有关 OAuth 路径，请参阅 Web 仪表盘 → 默认提供商：Nous Research。

在后端（远程机器）

设置用户名和密码，然后启动仪表盘并绑定到可访问的地址。凭据位于 ~/.hermes/.env（密钥文件，模式 0600）：

bash
## 1. 设置仪表盘登录凭据。
cat >> ~/.hermes/.env <<'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
## 推荐：一个稳定的签名密钥，以便会话在重启后仍然存在。
## 如果没有它，每次启动都会生成一个随机密钥，你会在每次重启时被注销。
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env
## 2. 运行仪表盘并绑定到可访问的地址。非回环绑定会启用身份验证网关；用户名/密码提供商处理登录。
hermes dashboard --no-open --host 0.0.0.0 --port 9119

保持 hermes dashboard 进程运行，只要你想让桌面应用能够连接——如果它停止，应用将无法再访问后端。在 systemd、tmux 或你选择的进程管理器下运行它，以便在注销和重启后仍然存在。

另外，如果你依赖消息通道，请确保网关在远程主机上运行——桌面应用与仪表盘后端通信，但你的 Telegram/Discord/Slack 网关会话是另一个进程，你需要单独启动并保持运行。请参阅消息了解网关设置。

不想在静态时保留明文密码？将 HERMES_DASHBOARD_BASIC_AUTH_PASSWORD_HASH 设置为 scrypt 哈希——使用 python -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('PW'))" 计算。完整配置表面（config.yaml 键、每个环境变量、速率限制器）：Web 仪表盘 → 用户名/密码提供商。

将仪表盘作为 systemd 服务运行？为单元提供 EnvironmentFile=%h/.hermes/.env，以便凭据在启动时位于环境中。

警告

仪表盘读取和写入你的 .env（API 密钥、密钥），并且可以运行代理命令。上面显示的用户名/密码设置适用于受信任的网络——切勿将受密码保护的仪表盘直接暴露在开放的互联网上；将其放在 VPN 后面。Tailscale 是干净的选择：绑定到机器的 tailscale IP（--host <tailscale-ip>）并使用 http://<tailscale-ip>:9119 作为远程 URL，这样只有你的 tailnet 可以访问它。要通过公共互联网访问后端，请改用 OAuth（Nous Portal） 提供商。

在应用中

设置 → 网关 → 远程网关：

  1. 远程 URL——http://<backend-host>:9119（如果你在前面使用反向代理，路径前缀如 /hermes 也可以）
  2. 登录——应用检测后端通告的提供商并调整按钮。对于用户名/密码后端，它会显示一个登录按钮，打开一个凭据表单（输入步骤 1 中的凭据）。对于 OAuth 后端，它会显示使用 <provider> 登录（例如使用 Nous Research 登录），它会运行提供商的浏览器登录。无论哪种方式，应用最终都会获得一个针对后端的经过身份验证的会话。
  3. 保存并重新连接——将桌面外壳切换到远程后端。会话会自动刷新；当设置了 HERMES_DASHBOARD_BASIC_AUTH_SECRET 时，你会在重启后保持登录状态。

你也可以在启动应用之前通过 HERMES_DESKTOP_REMOTE_URL 环境变量设置后端 URL，而无需使用 UI（它会覆盖应用内设置）；你仍然需要从网关设置面板登录。

注意——每个配置文件的远程主机

远程网关主机是按配置文件配置的，因此每个配置文件可以指向自己的远程后端（或保留在本地后端上）。切换配置文件会切换应用连接到的远程主机。

故障排除

  • 登录失败，显示 401 / "无效凭据"——用户名或密码与后端的 HERMES_DASHBOARD_BASIC_AUTH_USERNAME / HERMES_DASHBOARD_BASIC_AUTH_PASSWORD 不匹配。后端对未知用户和错误密码返回相同的通用错误（无枚举 oracle），因此请仔细检查两者。使用 curl -s http://<host>:9119/api/status | jq '.auth_required, .auth_providers' 确认网关已启用——它应报告 true 并包含 "basic"。
  • 没有“登录”按钮——它要求输入会话令牌——后端的用户名/密码提供商未激活。/api/status 不会在 auth_providers 中列出 "basic"。确保用户名和密码（或密码哈希）都已设置在 ~/.hermes/.env 中，并且仪表盘进程实际加载了它们。
  • 每次重启后都被注销——将 HERMES_DASHBOARD_BASIC_AUTH_SECRET 设置为一个稳定的值。没有它，令牌签名密钥会在每次启动时重新生成，从而使所有会话失效。
  • 连接被拒绝/超时——后端绑定到 127.0.0.1（默认）或防火墙/VPN 正在阻止端口。绑定到 0.0.0.0 或 tailscale IP，并打开端口到你的受信任网络。

有关从 Web 仪表盘角度进行的相同设置，请参阅 Web 仪表盘 → 将 Hermes 桌面版连接到远程后端；环境变量在环境变量 → Web 仪表盘和 Hermes 桌面版中列出。

故障排除

启动日志位于 HERMES_HOME/logs/desktop.log（包括后端输出和最近的 Python 回溯）——如果应用报告启动失败，请先检查此文件。你也可以从 CLI 跟踪它：

bash
hermes logs gui -f

常见重置：

bash
## 强制干净的首次启动设置（macOS/Linux）
rm "$HOME/.hermes/hermes-agent/.hermes-bootstrap-complete"
## 重建损坏的 Python venv（macOS/Linux）
rm -rf "$HOME/.hermes/hermes-agent/venv"
## 重置卡住的 macOS 麦克风提示
tccutil reset Microphone com.nousresearch.hermes

“构建桌面应用”卡在 Electron 下载

构建会从 github.com/electron/electron/releases 下载 Electron 运行时（约 114 MB）。如果安装程序在构建桌面应用步骤上挂起，并且实时输出重复 retrying attempt=…，则说明 GitHub 在你的网络上被阻止或限流（防火墙、代理或地区）。

安装程序会自动修复此问题：在构建失败时，它会（1）清除损坏的缓存 Electron zip 并重试，然后（2）如果仍然失败并且你尚未设置 ELECTRON_MIRROR，则通过 npmmirror.com（事实上的 Electron 社区镜像）再重试一次。@electron/get 会进行 SHASUM 校验下载，但校验和来自同一镜像——这可以捕获损坏或不完整的下载，但不能捕获被篡改的镜像。如果你不想信任第三方主机，请固定你自己的 ELECTRON_MIRROR（如下）；构建永远不会覆盖你设置的值。

要选择你自己的镜像（例如公司/受信任的镜像），请在安装前设置 ELECTRON_MIRROR 或手动重新构建——构建会尊重它并且不会覆盖它：

bash
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ \
  bash -c 'cd "$HOME/.hermes/hermes-agent/apps/desktop" && CSC_IDENTITY_AUTO_DISCOVERY=false npm run pack'

手动清除损坏的缓存 zip：

bash
rm -f "$HOME/Library/Caches/electron"/electron-*.zip   # macOS
rm -f "$HOME/.cache/electron"/electron-*.zip            # Linux

从源代码构建

如果你想自己修改应用，请从仓库根目录安装工作区依赖项一次，然后从 apps/desktop 运行开发服务器：

bash
npm install          # 从仓库根目录——链接 apps/desktop、web、apps/shared
cd apps/desktop
npm run dev          # Vite 渲染器 + Electron，它会启动 Python 后端

将应用指向特定的检出，或将其与你的真实配置隔离：

bash
HERMES_DESKTOP_HERMES_ROOT=/path/to/clone npm run dev
HERMES_HOME=/tmp/throwaway npm run dev
npm run dev:fake-boot   # 使用确定性延迟测试启动覆盖层

构建安装程序：

bash
npm run dist:mac     # DMG + zip
npm run dist:win     # NSIS + MSI
npm run dist:linux   # AppImage + deb + rpm
npm run pack         # 未打包的应用在 release/ 下（无安装程序）

macOS/Windows 签名和公证会在环境中存在相关凭据时自动运行（macOS 为 CSC_LINK / CSC_KEY_PASSWORD / APPLE_*，Windows 为 WIN_CSC_*）。

另请参阅

  • CLI 指南 —— 终端界面
  • TUI —— 桌面后端重用的现代终端 UI
  • Web 仪表盘 —— 带有嵌入式聊天标签页的浏览器管理面板
  • 配置 —— 桌面应用读取和写入的配置
  • Windows（原生） —— 原生 Windows 安装路径
AI 前沿
上一篇

hermes教程-检查点与 /rollback

下一篇

hermes教程-桌面应用

分享: