跳到主要内容

桌面应用

Hermes 桌面应用是一款原生应用，围绕着你从 CLI 和网关获得的同一个 Agent 构建——相同的配置、相同的 API 密钥、相同的会话、相同的技能、相同的记忆。它不是一个独立的产品或轻量级克隆；它使用相同的 Hermes Agent 核心和设置，并通过现代且经过深思熟虑设计的 UI 来驱动它。如果你在终端中使用过 hermes，那么你在那里设置的一切都已在此处可用，而你在此处执行的操作也会反映在那里。

它支持 macOS、Windows 和 Linux。

哪个界面对应什么？

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

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

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

安装​

请遵循 Hermes Desktop 安装说明。

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

hermes desktop

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

应用内容​

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

聊天​

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

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

状态栏​

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

  • 内联模型选择器 —— 直接从状态栏切换活动会话的模型。
  • 每会话 YOLO 开关 —— 仅为此会话开启或关闭 YOLO（与 TUI 匹配）。YOLO 会绕过危险命令的批准提示，因此请清楚你关闭的是什么 —— 参见 安全 → YOLO 模式。

是与另一台机器上的 Hermes 实例聊天，而不是使用捆绑的本地后端？请参阅下方的 连接到远程后端 —— 有关远程托管仪表板连接工作原理的完整细节（认证关卡、/api/ws 聊天 socket 以及 WebSocket 关闭代码分类），请参阅 Web 仪表板 → 将 Hermes Desktop 连接到远程后端。

文件浏览器​

在不离开应用的情况下探索和预览工作目录 —— 这对于跟踪 Agent 读取、写入和编辑文件的过程非常有用。使用 hermes desktop --cwd <path>（或 HERMES_DESKTOP_CWD 环境变量）设置初始项目目录。

语音​

与 Hermes 交谈并听取其回复，使用与其他地方相同的 语音模式。在 macOS 上，操作系统会提示一次麦克风访问权限。

设置与入门引导​

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

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

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

管理面板​

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

  • Skills（技能） — 浏览、安装和管理 skills。
  • Cron（定时任务） — 查看和管理 scheduled jobs。
  • Profiles（配置文件） — 在 Hermes profiles（隔离的配置/技能/会话）之间切换。
  • Messaging（消息） — 设置网关通道。
  • Agents（代理） 和 Command Center（指挥中心） — 用于多代理工作的编排界面。

键盘与导航​

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

会话与配置文件​

  • 会话列表重构 — 经过重新设计的会话列表，支持归档和常规会话清理，以便在列表增长时保持其易于管理。
  • 按 ID 搜索会话 — 直接通过 ID 查找特定会话。
  • 并发多配置文件会话 — 同时在多个 profiles 中运行会话，并通过跨配置文件 @session 链接引用另一个配置文件中的会话。

更新​

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

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

卸载​

打开 Settings → About → Danger zone 并选择要移除的内容：

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

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

你也可以从终端执行相同的操作 — 仅使用 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针对 apps/desktop/dist 通过 electron . 启动，而不是使用打包后的应用
--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 客户端，然后在应用程序中使用 Sign in with Nous Research 登录。如果你运行自己的身份提供者，自托管的 OIDC 提供者也以相同方式工作。
  • 用户名/密码——仅限本地/受信任网络使用。 当后端位于同一受信任的 LAN 或仅可通过 VPN（例如 Tailscale）访问时，这是最简单的选项。它保护单个共享凭据，无需外部身份提供者，因此不要将其用于暴露于公共互联网的仪表板——在这种情况下请使用 OAuth。

本节的其余部分展示了用户名/密码路径，因为它是在受信任网络上快速搭建的最快方法；有关 OAuth 路径，请参阅 Web Dashboard → Default provider: Nous Research。

在后端（远程机器上）​

设置用户名和密码，然后启动绑定到可访问地址的仪表板。凭据存储在 ~/.hermes/.env（秘密文件，权限模式为 0600）中：

# 1. Set the dashboard login credentials.
cat >> ~/.hermes/.env <<'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
# Recommended: a stable signing secret so sessions survive restarts.
# Without it a random key is generated per boot and you'll be logged out
# on every restart.
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env

# 2. Run the dashboard bound to a reachable address. The non-loopback bind
#    engages the auth gate; the username/password provider handles login.
hermes dashboard --no-open --host 0.0.0.0 --port 9119

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

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

不希望以明文形式存储密码？可以将 HERMES_DASHBOARD_BASIC_AUTH_PASSWORD_HASH 设置为 scrypt 哈希值——使用 python -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('PW'))" 计算它。完整的配置表面（config.yaml 键、每个环境变量、速率限制器）：Web Dashboard → Username/password provider。

作为 systemd 服务运行仪表板？给单元添加 EnvironmentFile=%h/.hermes/.env，以便在启动时将凭据加载到环境中。

注意

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

在应用程序中​

Settings → Gateway → Remote gateway：

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

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

每个配置文件对应的远程主机

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

故障排除​

  • 登录失败，返回 401 / “Invalid credentials”（无效凭据） — 用户名或密码与后端的 HERMES_DASHBOARD_BASIC_AUTH_USERNAME / HERMES_DASHBOARD_BASIC_AUTH_PASSWORD 不匹配。对于未知用户和错误密码，后端返回相同的通用错误（无枚举漏洞），因此请仔细检查两者。通过 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 Desktop 连接到远程后端；环境变量收录在 环境变量 → Web 仪表板和 Hermes Desktop 下。

故障排除​

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

hermes logs gui -f

常见重置操作：

# Force a clean first-launch setup (macOS/Linux)
rm "$HOME/.hermes/hermes-agent/.hermes-bootstrap-complete"

# Rebuild a broken Python venv (macOS/Linux)
rm -rf "$HOME/.hermes/hermes-agent/venv"

# Reset a stuck macOS microphone prompt
tccutil reset Microphone com.nousresearch.hermes

“构建桌面应用程序”卡在 Electron 下载阶段​

构建过程会从 github.com/electron/electron/releases 下载 Electron 运行时（约 114 MB）。如果安装程序在 Build desktop app 步骤挂起，且实时输出重复显示 retrying attempt=…，则说明你的网络（防火墙、代理或区域限制）阻止或限制了访问 GitHub。

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

要选择你自己的镜像（例如企业内部或受信任的镜像），请在安装前设置 ELECTRON_MIRROR 或手动重新构建 — 构建过程会尊重该设置且不会覆盖它：

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 文件：

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

从源代码构建​

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

npm install          # from repo root — links apps/desktop, web, apps/shared
cd apps/desktop
npm run dev          # Vite renderer + Electron, which boots the Python backend

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

HERMES_DESKTOP_HERMES_ROOT=/path/to/clone npm run dev
HERMES_HOME=/tmp/throwaway npm run dev
npm run dev:fake-boot   # exercise the startup overlay with deterministic delays

构建安装程序：

npm run dist:mac     # DMG + zip
npm run dist:win     # NSIS + MSI
npm run dist:linux   # AppImage + deb + rpm
npm run pack         # unpacked app under release/ (no installer)

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

另见​