Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

sidebar_position: 3 title: “Hermes Desktop” description: “The native Hermes desktop app — a polished experience for chatting with Hermes, with streaming tool output, side-by-side previews, a file browser, voice, cron, profiles, skills, and settings. macOS, Windows, and Linux.”

Hermes 桌面端

Hermes 桌面应用是一款原生应用程序，它基于与 CLI 和网关中使用的完全相同的 Agent 构建——相同的配置、相同的 API 密钥、相同的会话、相同的技能以及相同的内存。它并非独立产品，也不是轻量级克隆版；而是采用相同的 Hermes Agent 核心与设置，并通过精心设计的现代化用户界面来操控该 Agent。如果您曾在终端中使用过 hermes，那么您在那里设置的所有内容都会同步到桌面端，而在这里进行的操作也会实时反映在终端中。

该应用支持在 macOS、Windows 和 Linux 系统上运行。

::提示 哪种界面适合哪种场景？ Hermes 提供了多种前端界面，它们都可与同一个 Agent 进行交互：

  • 桌面应用（即此页面）——专为聊天、配置和管理功能设计的原生应用程序。
  • CLI（hermes）和 TUI（hermes --tui）——终端界面。
  • Web 控制面板（hermes dashboard）——基于浏览器的管理面板；其可选的 聊天 标签页可通过伪终端嵌入 TUI 界面。
根据当前需求选择合适的界面即可。由于所有界面共享状态，因此您可以在一个界面中开始会话，然后在另一个界面中继续该会话。
::

安装

您可以从 Hermes 桌面端产品页面 下载该应用，或参考 Hermes 桌面端安装指南 进行安装。

如果您已经安装了 Hermes，只需运行相应命令即可。

hermes desktop

该模式将使用您当前的配置、密钥、会话及智能体技能。

应用功能概览

桌面版应用采用以聊天为主的界面设计，左侧设有导航侧边栏。它支持同时管理多条智能体对话、配置消息发送服务、创建输出文件、浏览项目文件夹结构，以及同时处理多个项目。

侧边栏的显示内容会随当前聚焦的聊天窗口而变化。打开或聚焦某个会话标签页后，该页面的高亮显示会被清除，即便工作区仍保留该页面的路径，Kanban 等协作页面也不例外。

聊天功能

这是应用的中心区域，您将享有以下功能：

  • 实时响应：在智能体工作时，可查看实时的工具操作状态以及结构化的工具调用摘要。
  • 符合 Markdown 语法的换行：两个尾随空格会生成硬换行，而普通换行则仅为软换行。媒体文件和预览提取功能会保留被移除附件范围之外的文本，包括代码块的缩进以及未完成的代码块间距。代码显示与复制功能则会保留 Markdown 解析器所识别的开头空行、尾随空行以及终端空白行。
  • 统一的对话历史记录：与所有 Hermes 使用界面一致，此处开始的会话可在 CLI/TUI 中继续，反之亦然。
  • 拖放文件功能：可将文件拖放到聊天区域的任意位置，以便将其附加到下一条消息中。
  • 独立的后台草稿功能：隐藏的聊天标签页可独立更新其草稿内容，而不会影响可见编辑区中的光标位置或选中内容。
  • 指令芯片操作功能——将鼠标悬停在可执行链接（如网址）上，即可显示对应的操作按钮。系统会提供短暂的缓冲时间，让你在按钮消失前从芯片切换到按钮。只要仍在按钮区域内移动，该按钮就会保持可见；一旦离开该区域，其他无关的鼠标移动则不会影响按钮的隐藏时机。点击操作按钮即可保留当前的草稿选择状态。
  • 右侧预览栏——让你在持续聊天的同时，能够并排查看网页、文件以及工具的输出结果。
  • 应用内浏览器的注释模式 — 在预览浏览器栏中点击“添加注释”，随后点击实时页面上的任意元素（或拖动选区），再输入备注；每条保存的注释都会以带编号的图钉形式显示在页面上。保存图钉并不会触发消息发送流程——操作完成后，选择“添加多条注释”即可为每条注释附上一张裁剪后的截图以及简短的说明文字，随后仍需由你手动发送。每条元素注释都会包含其CSS选择器、标记结构以及与布局相关的计算样式，这样智能体就能直接在源代码中定位该元素，而无需仅凭图片进行猜测。在标记数据离开页面之前，密码、隐藏字段的值以及任何类似密钥或令牌的属性都会被遮蔽处理。大量注释会按照其在页面上的位置分组发送，这样一来，20多条注释也就变成了几组独立的任务，而非每条都需单独处理——由于这些组属于不同的DOM子树，它们通常会对应不同的文件，这也正是能够安全地将其分配给并行处理任务的依据。即使删除了某条注释，其编号仍保持不变；而切换聊天窗口则会清空所有已保存的注释记录。
  • 消息编辑器历史记录与队列管理 — 在空的消息编辑器中按下上下箭头键，即可调出并重复使用之前的提示语，还能在消息发送前对其进行修改。当消息正在排队等待发送时，按下“停止”（或Esc）键可暂停队列，并将其显示在消息编辑器上方；之后可从中继续处理队列中的消息，或对单个条目进行发送、编辑或删除操作。
  • 任务进度显示 —— 展开“任务”标题栏即可查看各个阶段的具体情况。长列表会限制在输入区域上方，您只需在展开后的列表中滚动，即可查看最后的任务内容，而无需切换对话界面。
  • 对话时间轴轨道 —— 对于较长的对话，聊天记录边缘会显示一条细长的标记轨，每个提示词对应一个标记。将鼠标悬停在标记上即可查看该提示词的列表，点击某个标记可直接跳转至对话中的对应位置。（当对话内容达到一定长度后才会出现此功能。）
  • 阅读位置记忆 —— 重新打开某个会话时，系统会恢复之前保存的阅读位置，而非直接跳转到最新消息。那些停留在页面底部的会话会继续跟随新的输出内容更新。如需返回到最新内容处，可使用“滚动到底部”功能。这些阅读位置会存储在桌面版的本地存储中，不会通过后台进行同步。
  • 页面内查找 —— 按下 Cmd/Ctrl+F 即可打开查找栏，用于搜索已显示的聊天记录。输入内容后按 / 或 Shift+Enter（或在查找栏打开状态下按 Cmd/Ctrl+G / Cmd/Ctrl+Shift+G）可逐条查看匹配结果；按 Esc 键即可关闭查找栏。

异步定时任务及委托任务的完成情况会以折叠的时间轴形式展示。点击完成状态标签即可以 Markdown 格式查看结果内容（包括任务输出），长篇报告会在展开区域内自动滚动显示。任务说明和交付信息则不会作为报告内容呈现。

状态栏

位于聊天界面底部的状态栏会实时显示会话状态，并提供快捷控制选项，无需打开设置页面即可使用：

  • 会话级 YOLO 开关——仅针对当前会话开启或关闭 YOLO 功能（与 TUI 行为一致）。YOLO 可绕过危险命令的确认提示，因此请务必清楚自己正在关闭什么功能——详情请参阅 安全设置 → YOLO 模式。
  • 上下文使用率指示器——实时显示会话上下文窗口的占用比例。“% full”数值会动态变化。点击该指示器可打开上下文使用情况弹出窗，其中会按类别详细列出令牌消耗情况（系统提示、工具定义、技能、内存、规则、MCP、子代理定义以及对话内容本身），帮助您在压缩机制启动前准确了解哪些部分占用了最多空间。
  • 缓存命中率与每秒令牌数——默认为关闭状态，可通过右键菜单将其开启。缓存命中率指当前会话中从提供方提示词缓存中获取的令牌比例（缓存的令牌成本更低，因此命中率越高，整体成本越低——随着会话逐渐进入稳定状态，成本还会进一步下降）。每秒令牌数则是基于最近 10 次模型调用计算的平均输出吞吐量。这两项数据会在每个对话轮次中实时更新。
  • 可自定义项目——右键点击状态栏（选择“在状态栏显示”），即可决定要展示哪些内容：上下文使用率指示器、缓存命中率、每秒令牌数、工作区信息、模型信息、审批状态、对话轮次/会话计时器、终端界面、命令中心、后端版本等——或者完全隐藏状态栏（按 Cmd/Ctrl+Shift+S 即可切换）。 想要在另一台机器上的Hermes实例而非内置的本地后端进行聊天吗？请参阅下方的连接远程后端指南。如需详细了解远程托管控制面板连接的运作机制（包括身份验证网关、/api/ws聊天套接字以及WebSocket关闭码处理流程），请查看Web控制面板 → 将Hermes桌面版连接到远程后端。

仓库发现功能

Hermes桌面版会通过扫描用户主目录并设定一定的深度范围，从而为“项目”侧边栏发现本地的Git仓库。您可以在设置 → 工作区中为不同配置文件更改此设置，也可直接在config.yaml文件中进行配置：

desktop:
  repo_scan_enabled: true
  repo_scan_roots: []
  repo_scan_exclude_paths: []
  • 将 repo_scan_enabled 设置为 false 即可完全停止文件系统扫描。该配置文件对应的现有磁盘发现缓存记录将被清除；而通过有意的 Hermes 会话明确指定的项目和仓库仍会保留。
  • 将 repo_scan_roots 设置为文件夹列表，即可限制扫描范围。若该列表为空，则保持默认的根目录扫描模式。
  • 将 repo_scan_exclude_paths 设置为需要完全跳过的子树所在文件夹。

更改上述任意值仅会使对应配置文件的磁盘发现缓存失效，并触发符合策略要求的刷新操作。而“隐藏于侧边栏”仍是一项针对单个项目的独立筛选操作。

选择模型

模型选择器位于composer界面中，就在麦克风按钮的左侧。点击该选项即可通过下拉菜单切换模型、推理强度以及快速模式。

  • Composer选择器会保留用户设定的UI状态，绝不会恢复为默认设置。该设置会本地存储（针对每台设备），并在新对话或重启后依然保持原有选择，而不会自动回退到默认值——只需选定一次模型，下次按下Cmd/Ctrl+N时就会直接使用该模型。在实时聊天模式下，切换模型只会影响当前对话；无论哪种情况，所选模型都会在会话创建或切换时随之保留，且绝不会被写入个人资料中的默认设置——但有一个例外：对于尚未配置model.default/model.provider的空白个人资料，首次选择的模型会被保存下来，这样应用在重启时就有明确的默认值，而不会随机使用某个API密钥环境变量。其持久化规则与 /model 功能相同（即model.persist_switch_by_default选项）；如需手动更改默认设置，请通过设置 → 模型进行操作。（切换个人资料时，会重新应用该个人资料自身的默认设置。）
  • 请在“设置 → 模型”中设定默认模型。这个“主”模型就是您每个个人资料对应的全局默认值——新对话、定时任务、子智能体以及辅助任务都会以此为起点，而且也只有此处会保存该默认设置。每个个人资料都拥有独立的默认模型。
  • **模型级的运行效率/快速预设功能。**桌面版应用中，每个模型都会记住自身的推理耗时及快速模式设置，每当您选择该模型时，这些设置就会自动应用于当前会话。这类预设功能主要是为桌面端使用带来的便利，不会影响定时任务或子智能体的设置。
  • **对话中途切换模型会重置提示词缓存。**在实时聊天中更换模型意味着下一条消息需要重新读取整个对话内容，且需支付全额输入费用（因为提供方的提示词缓存是按模型来区分的）。偶尔这样做问题不大；但在长时间对话中，使用新模型重新开始聊天往往比不断切换模型更经济。

文件浏览器

无需离开应用程序即可浏览和预览工作目录——这有助于观察智能体如何读取、写入和编辑文件。可通过 hermes desktop --cwd <路径>（或 HERMES_DESKTOP_CWD 环境变量）来设置初始项目目录。

文件资源

连接到远程网关后，打开文件资源会通过该网关下载文件，同时会使用该文件对应的原始配置文件和会话信息。相对路径会基于会话中保存的工作目录进行解析；以用户主目录为基准的路径则使用网关的主目录，而非桌面机器的主目录。系统既支持Windows风格的相对路径，也支持正斜杠路径；此外，文件URI还会保留驱动器和网络共享信息，以便网关正确解析。如果找不到对应的会话或工作目录，系统会报错，而不会自动选择其他本地文件。

Artifacts视图会将您在会话中生成的各类内容——图片、文件和链接——汇总到一个可搜索、可浏览的图库中。您可以通过侧边栏、命令面板（Artifacts — Browse generated outputs），或自行绑定的nav.artifacts快捷键来打开它。该视图会自动对最近的会话输出进行索引；每项内容都会显示其所属的会话，并提供跳转回对应聊天的功能，而图片和文件则会在预览窗口中打开，同时支持下载、在浏览器中打开或复制操作。

Windows：标签页与分面

该应用专为同时处理多项任务而设计：

  • 标签页——按Cmd/Ctrl+T可打开一个新的会话标签页；Ctrl+Tab/Ctrl+Shift+Tab用于在会话之间切换，Ctrl+1…9则可根据序号跳转到最近的会话。按Cmd/Ctrl+W可关闭当前聚焦的标签页，而Cmd/Ctrl+Shift+T则可重新打开上一个关闭的标签页。
  • 多个窗口——按Cmd/Ctrl+Shift+N可打开一个新的窗口，任何会话都可以通过其上下文菜单（New window）或命令面板单独弹出。弹出的窗口仅显示该单个聊天内容，不会包含全局侧边栏，非常适合将长时间运行的会话切换到另一台显示器上查看。实时代理输出会同步显示在所有展示该会话的窗口中。
  • 分面——按Cmd/Ctrl+B可切换左侧侧边栏的显示状态，Cmd/Ctrl+J可切换右侧侧边栏，**Cmd/Ctrl+\**则可交换两侧边栏的位置。

终端

真正的终端位于右侧侧边栏中，与文件浏览器相邻：

  • Ctrl+** 可显示终端窗口（若不存在则打开一个）；**Ctrl+Shift+ 可再打开一个终端。多个终端会堆叠在标签栏中——使用 Ctrl+Shift+↓/↑ 在它们之间切换，Ctrl+Shift+W 可关闭当前活动终端。
  • 终端在隐藏状态下仍会保持运行状态。 关闭或隐藏面板并不会终止终端进程——每个已打开的终端都会保留其滚动记录和正在运行的进程，直到您主动将其关闭。
  • 添加到聊天内容 —— 选中终端输出并将其发送到对话框中，作为后续消息的上下文。

实时子代理

当被委托的任务处于运行状态时，对话框上方会显示一个 “子代理” 标签页，其中列有子代理的数量、任务名称、耗时以及最新活动状态。该标签页最多可预览三个任务；展开标题栏即可查看完整列表，随后可选择某个任务以查看详细信息及 “引导” / “停止” 控制选项。每个标签页都对应独立的聊天窗口，即便在分屏模式下也是如此。“引导”操作仅表示已有指导内容已排队等待处理，并不意味着子代理已经阅读了该内容。详情请参阅 监控子代理。

Git审查与工作树

对于在 Git 仓库中运行的会话，该应用提供了内置的源代码控制功能：

  • 审查面板 — 按 Cmd/Ctrl+G 即可切换工作树审查面板：显示分支状态及领先/落后情况、已修改文件（列表视图或树状视图），以及针对 未提交更改、特定分支 或 上一次操作 的差异对比（即智能体在最近一次操作中所做的修改）。您可以在此标记文件为已暂存或取消暂存、撤销更改、编写提交信息（或选择 生成提交信息），随后执行 提交 或 提交并推送 操作；还可以通过 GitHub CLI（gh）命令创建 Pull Request，或使用 让 Hermes 创建 PR 功能将整个流程交由智能体处理。此外，您也可以在此创建和切换分支。
  • 工作树 — 按 Cmd/Ctrl+Shift+B（或在侧边栏的项目中选择 新建工作树）即可在新分支上创建 Git 工作树，这样智能体便能在不影响您当前检出版本的情况下，对仓库的并行副本进行操作。工作树会以独立通道的形式显示在项目下方；删除某个工作树时，系统会询问您是要删除该工作树目录（分支本身保留），还是仅隐藏该通道但仍将其保留在磁盘上；若工作树中存在未提交的更改，则还提供强制删除选项。

内存图谱

内存图谱（可通过命令面板选择 Memory Graph，或通过状态栏进入）是一张交互式地图，展示了 Hermes 为您总结的所有内容——各种技能与记忆信息以可缩放的节点图形式呈现，并配有时间轴，还可按 全部 / 已使用 / 已学习 进行筛选。分享功能可将该图谱布局导出为一段简洁的代码，您可以将其粘贴给他人（仅包含布局信息，不包含您的任何记忆或技能文本），同样也可以通过相同方式导入其他人的代码。

快速入口

“快速入口”是一项轻量级且始终可用的指令生成工具，用户可通过系统任意位置的全球热键随时调用它——无需切换至（甚至无需打开）主窗口即可发送指令。可在设置 → 高级选项 → 快速入口中开启该功能；默认快捷键为Ctrl/Cmd+Shift+Space，您也可以自行设置快捷键（需至少包含一个修饰键）。如果已有其他应用程序占用该热键，设置界面会给出提示，以便您选择其他按键。

语音功能

您可以与Hermes进行对话并即时获得回复，其功能与其它地方提供的语音模式完全一致。在macOS系统中，系统会首次请求麦克风使用权限。

HUD模式

按下**⌘/Ctrl+Shift+H**（或标题栏按钮）即可将聊天界面分离为无边框、始终显示在顶部的浮动栏，置于您正在使用的应用程序之上。主窗口会暂时隐藏，而HUD则会保留实时对话和指令生成工具。浮动栏的位置决定了上下文——它的位置会告诉Hermes您正在询问的是哪个应用程序及屏幕，因此“这里”、“那边”以及“那个页面”等表述都能准确对应到其下方的内容。

  • 移动条栏 — 在 macOS 和 Windows 系统上，按住组合器上的任意位置持续一拍的时长，然后拖动即可。在 Linux/X11 系统上，需按住 Ctrl 键并使用鼠标主键拖动即可立即移动条栏（包括在已选文本中拖动）；按住不放的方式同样适用。在调用桌面切换快捷键时，保持拖动状态可将 HUD 移动到另一个虚拟桌面。在原生 Wayland 环境下，组合器条栏实际上是一个拖动手柄（这是移动它的唯一方式，因为应用程序无法自行定位其窗口）。
  • 调整大小 — 拖动条栏的任意边缘或角点即可；另一端的位置将保持固定。在原生 Wayland 环境下，仅右侧和底部边缘可被拖动，因为组合器不允许应用程序自行定位顶层窗口。
  • 重置布局 — 条栏上的“丢弃”控件可恢复条栏的默认大小以及（在 X11 / macOS / Windows 系统上）默认位置。如果某种固定尺寸导致 HUD 无法正常使用，可选用此功能。
  • 对齐到光标位置 — 按下 ⌘/Ctrl+Shift+G（这是一个全局热键，可在任何应用程序中使用）即可将 HUD 移动到光标所在的位置。在原生 Wayland 环境下此操作无效——窗口定位由组合器控制。
  • 退出 — 点击条栏上的退出按钮，或再次按下 ⌘/Ctrl+Shift+H 即可。这样应用程序窗口将会恢复，同时保持当前会话状态不变。

Linux / Wayland

Electron 20 及更高版本已在 Wayland 会话中以原生 Wayland 客户端的形式运行。在该环境下，拖动、点击穿透以及调整大小等功能均可正常使用。

在 Hyprland（包括 Omarchy）环境中，HUD 会在映射完成后通过合成器的 IPC 机制被悬浮并固定；否则 Hyprland 会像处理其他窗口一样对其使用平铺模式，“始终显示在顶层”的设置将被忽略，且合成器的拖动操作也无效。无需额外的窗口规则。

某些合成器（尤其是 COSMIC）会对原生 Wayland 窗口忽略“始终显示在顶层”这一设置。若要恢复其固定状态，需在 XWayland 环境下运行该应用程序：

desktop:
  ozone_platform_hint: x11

这在启动时会关联到 ELECTRON_OZONE_PLATFORM_HINT（显式的环境变量依然具有优先级）。其代价是：X11 无法恢复已忽略鼠标的窗口，因此 HUD 会显示为实心窗口而非可点击穿透的样式。部分 KDE 环境在使用 X11 ozone 后端时还会出现键盘功能异常的问题——除非您需要窗口始终置顶，否则建议将该提示参数设置为 auto。

WSLg（基于 WSL2 的 Windows GPU）

当在 WSL2 环境中运行 hermes gui 且存在 /dev/dxg 接口以及已安装 Mesa 的 d3d12_dri.so 文件时，启动器会为 Electron 设置 GALLIUM_DRIVER=d3d12，从而使渲染工作使用 Windows GPU 而非 llvmpipe 软件光栅化引擎；您在环境中设置的显式 GALLIUM_DRIVER、MESA_LOADER_DRIVER_OVERRIDE、LIBGL_ALWAYS_SOFTWARE 或 LIBGL_DRIVERS_PATH 参数将保持不变（例如，使用 GALLIUM_DRIVER=llvmpipe hermes gui 可维持软件渲染模式）。

设置与入门指南

您无需编辑 YAML 文件，即可通过直观的界面管理提供者、模型、工具及凭证。首次使用时，仅需几秒钟即可发送第一条消息。设置面板涵盖了提供者/密钥管理、模型选择、工具集配置、MCP 服务器、网关以及会话管理等功能。

  • 提供商设置面板——专为管理推理提供商而设，提供账户/API密钥界面，用于登录并存储各提供商的凭证。账户与API密钥共享“适用对象”选择功能：凭证的读取与编辑、OAuth账户的移除以及由此触发的登录操作，均针对所选配置文件生效，而非当前活跃的聊天配置文件。在保存凭证和选择模型期间，登录流程会保持该目标配置文件不变。更改“适用对象”后会丢弃未保存的凭证草稿。关闭登录功能将停止轮询并忽略后续返回的结果；而已发送的凭证写入操作仍可能在原始配置文件中完成处理。由外部管理的CLI凭证使用独立的CLI工具，不受此配置文件选择器的限制。其“本地模型”视图用于安装和管理设备上的llama.cpp运行时环境——详情请参阅本地模型。
  • 菜单中的所有提供商与模型——图形界面会展示完整的提供商列表以及hermes model所识别的所有模型，因此您可以从与CLI相同的目录中选择，而无需面对经过筛选后的子集。
  • xAI Grok OAuth——Grok是启动器中一级别的OAuth提供商，可通过浏览器流程与其他OAuth提供商一样完成登录。
  • 通过图形界面安装工具后端——可直接在应用内运行工具后端的安装后步骤，无需切换到终端操作。
  • 终端字体选择器——可在“设置 → 外观”中选择已安装的字体。诸如 MesloLGS NF 这类的 Nerd Fonts 字体，无论是在交互式终端还是智能体终端中，都能用于显示 Powerlevel10k 的分隔符与图标；该设置会按用户配置文件保存。
  • 启动时重新打开上次对话——默认情况下，应用会在冷启动后继续从您上次离开的位置继续工作。若希望始终以全新对话开始，可在“设置 → 外观”中关闭此功能（或是在 config.yaml 中设置 display.resume_last_session: false）。无论是否开启此功能，深度链接及明确指定的目标地址都不会受到影响。
  • 辅助模型警告——如果您将主模型切换到新的提供方，而某些辅助任务（如标题生成、摘要提取等）仍绑定在另一个提供方上，应用会发出警告，避免您在不知情的情况下将任务分散到两个不同的提供方上处理。
  • VS Code Marketplace 主题——除了内置的主题预设外，外观设置还支持直接搜索 VS Code Marketplace：选择任意颜色主题后，应用便会将其下载、转换并安装为桌面主题。您也可以通过命令面板（“安装主题”）进行相同操作，而已导入的主题同样可通过外观设置删除。
  • 保持电脑唤醒状态——“设置 → 高级 → 保持电脑唤醒状态”可防止电脑在智能体长时间运行时进入睡眠模式（不过屏幕仍可能变暗）。该设置为每台电脑独立配置。 首次启动的引导流程已基于统一的覆盖式设计系统进行重构，您可以选择“稍后选择提供方”，从而跳过提供方设置，直接进入应用程序。

每个配置文件的设置：“适用对象”范围

当您拥有两个或更多配置文件时，那些由配置文件驱动的设置页面——模型、工作空间、安全设置、内存与上下文、语音、聊天、高级选项以及工具与密钥——以及消息传递覆盖面板顶部都会显示一个共用的“适用对象”标签行。该标签行用于指定您的修改将应用于哪个配置文件：

  • 默认情况下，选择项会跟随当前激活的配置文件，其运作方式与以往完全一致——即修改您正在使用的那个配置文件。
  • 您可以选择另一个配置文件，无需切换整个应用程序即可查看和修改该配置文件的设置；在各个设置页面之间切换时，此选择依然有效。
  • 更改应用程序的当前激活配置文件会重置选择器，因此修改内容不会默认继续应用于之前选定的配置文件。
  • 如果配置文件数量少于两个，则该标签行会完全隐藏。

（“网关”页面通过其“每配置文件的覆盖设置”子项来处理配置文件问题；而“能力”和“定时任务”视图则拥有各自的适用范围选择器。）

管理面板

该应用程序还提供了更全面的Hermes管理界面，让您无需切换到终端即可完成操作。

  • 技能管理 — 浏览、安装及管理技能。在“技能”标签页中，您可以查看已安装的技能，并通过开关按钮控制其启用状态；在其下方则是Hermes内置的所有可选技能列表——每项技能都配有“安装”按钮，点击后即可完成安装，相应行会立即显示在已安装列表中。
  • 记忆图谱（星图） — 在聊天框中输入 /journey（别名：/learning、/memory-graph），即可打开一个交互式界面，展示随时间变化的已学习技能与记忆，同时还配有时间轴播放控件。您可以直接在面板上编辑或删除节点（技能会被归档，记忆则会被移除）。详情请参阅学习历程。
  • 定时任务 — 查看及管理计划任务。
  • 配置文件 — 在不同的Hermes配置文件之间切换（每个配置文件可独立管理设置、技能和会话）。
  • 消息传递 — 设置网关通道。
  • 智能体与指挥中心 — 用于实现多智能体协同工作的调度界面。

内置的机器人模式

机器人模式为该应用默认内置且处于开启状态，采用“每个智能体对应一条聊天记录”的机制。在智能体列表中，每一个Hermes配置文件都会以机器人的形式呈现，拥有专属头像（几何图形脸、上传的图片、AI生成的肖像或像素宠物）、独立的机器人聊天对话界面，以及专属的常规任务（由Hermes的cron系统支持的任务调度）。该列表位于左侧边栏，与对话记录并排显示，即会话 | 机器人标签页栏，而非堆叠在会话列表下方的第二个面板。那些采用旧式堆叠布局安装的应用会自动调整至标签页栏中；若您自行设置了面板布局，则原有布局保持不变。定时任务（即常规任务）面板仅在“机器人”标签页处于活动状态时才会显示在聊天界面旁，而当您切换回“会话”视图时则会消失（旧版桌面版本则始终显示该面板）。

您可以从智能体列表中创建新的智能体——可设置名称/标题/描述，还可通过高级选项展示其全部功能（模型、SOUL、技能、工具集、MCP服务器等）——将它们分组，进而创建多个机器人共同协作的群组聊天。群组聊天在列表中以类似Discord的独立行形式呈现：成员头像堆叠显示、成员数量、最新消息预览以及“需要您处理”标识，这些内容与机器人行以相同的“固定顺序+最新优先”原则交错排列。点击某一行即可打开对应群组，该群组会作为一个标签页占据主聊天窗口（旧版桌面版本则会在机器人侧边栏中打开）。

机器人之间可互相发送消息：在任何聊天窗口中输入 @researcher have a look at this，当前活跃的机器人便会将消息转交并反馈结果。此外，机器人还能直接访问彼此的“机器人聊天”界面（使用命令 hermes -p <bot> chat）。后端会自动为每个机器人的标准“机器人聊天”会话配置消息传递协议（可通过 agent.bot_mode_protocol 参数进行设置，默认已开启）——即便有同事通过命令行以无界面模式打开该聊天窗口，这一功能依然正常工作。因此，机器人之间的回复与消息转交无需修改您的 SOUL.md 文件，同时也不会影响您正常的对话会话。

在“机器人模式”下，每个机器人的标准“机器人聊天”会话以及所有群聊成员的会话始终不会显示在全局“会话”侧边栏中。它们仅存在于“机器人”面板中（包括机器人列表行、房间视图以及每个机器人的会话浏览器），而不会混杂在您的个人对话中。

对于不常用的机器人，您可以将其隐藏：右键点击对应的机器人行，选择 Hide Bot。被隐藏的机器人虽会从列表中消失，但依然可以正常工作——@提及功能依然有效，群聊成员身份也不会受影响。每当至少有一个机器人被隐藏时，“机器人”面板的顶部会出现一个眼睛图标；点击该图标即可查看以暗显形式显示的隐藏机器人（右键点击并选择 Unhide Bot 即可将其恢复显示）。如果被隐藏的机器人有未读消息，眼睛图标会显示为一个点。隐藏状态会被存储在机器人的配置文件中，因此无论在何种设备上，该状态都会保持不变。

如果您不想使用此功能，只需在 Settings → Plugins → Bots 中将其关闭即可——列表、流程面板以及作曲器中间件会立即解除关联，无需重启系统。

完整指南——包括创建智能体（含多机器批量创建功能）、跨连接的任务分配机制、智能体间的互提及群聊中的回复决策规则：机器人模式：智能体任务表。

键盘与导航操作

  • 命令面板——按下Cmd+K或Cmd+P（Windows/Linux系统为Ctrl+K / Ctrl+P），即可通过键盘执行各类操作并浏览应用：打开任意页面或设置项，按名称或ID跳转至特定会话，切换模型/主题/颜色模式，启动终端，重启网关，更新Hermes版本等。
  • 可重新绑定的快捷键——通过设置 → 键盘快捷键（或Cmd/Ctrl+/）可打开快捷键面板，在此处你可以重新映射几乎所有的快捷键——包括切换配置文件、导航会话、切换视图，以及桌面插件提供的各类快捷键。重复设置的快捷键会被标记为冲突。以下是几个值得了解的默认快捷键：Cmd/Ctrl+N新建会话，**Cmd/Ctrl+.**打开命令中心，**Cmd/Ctrl+,**进入设置界面，Cmd/Ctrl+Shift+F搜索会话，Cmd/Ctrl+1–9切换配置文件，Shift+X切换深色/浅色模式。
  • 自定义缩放快捷键——以半级为单位调整界面缩放比例，从而更精确地控制文本大小。
  • 用户界面语言切换器——可在应用内直接更改界面语言：英语、简体中文（zh-Hans）、繁体中文（zh-Hant）、日语、阿拉伯语（从右向左显示）以及俄语。

会话与配置文件

  • 会话列表优化 — 对会话列表进行了重构，新增了归档功能以及各项优化措施，以便在会话数量不断增加时仍能保持列表的易管理性。
  • 按 ID 搜索会话 — 直接通过会话的 ID 快速定位特定会话。
  • 多配置文件并行会话 — 支持同时在多个 配置文件 中运行会话，并可通过跨配置文件的 @session 链接引用其他配置文件中的会话。
  • 导出/导入配置文件 — 可将整个设置以单个文件的形式共享。通过 ⌘K → 导出配置文件…（或右键点击侧边栏中的配置文件方块），即可生成包含技能、内存、角色设定、定时任务、插件及各项设置的 .tar.gz 文件，其中 API 密钥会被移除。从桌面端导出时还会一并保存外观与界面设置——包括皮肤风格、深色/浅色模式、自定义主题、侧边栏颜色以及窗口布局——这样导入后的配置文件就会呈现出发送方原有的样式。可通过 ⌘K → 导入配置文件… 或侧边栏 + 号旁的按钮进行导入，系统会应用相应设置并将您带入新配置文件。同样的压缩格式也适用于聊天界面中的 /export / /import 命令，以及命令行中的 hermes profile export / import 命令。详情请参阅 导出和导入配置文件。

更新

该应用会在后台自动检查更新，一旦有新版本可用，便会提供一键更新功能。

在本地更新过程中，详细的构建输出会被记录到当前激活配置文件的 logs/update.log 中，包括通过 --gateway 参数进行的离线更新。这些输出不会显示在终端中，但可在构建完成前用于故障排查。在 Windows 环境下，系统会将此日志中的新内容视为进度；即便某个子进程没有产生任何输出，仍会受到空闲监控机制的约束。仅凭进程是否存活无法重置该监控机制，而且取消更新时也不会等待其构建过程结束。

桌面应用程序与其通信的 Hermes 后端是独立进行更新的——前者更新的是您设备上的应用包，后者则在其运行的位置进行更新。当存在多个更新目标（如远程网关或多个已注册的网关）时，“立即更新”（位于“关于”面板上）、⌘K 键对应的“更新 Hermes”选项以及更新准备就绪的提示信息，会同时触发所有目标的更新：首先更新已连接的后端，接着是其他所有符合条件的已注册网关（Hermes Cloud 项目由平台统一管理，因此不会被更新），最后才是桌面应用程序本身，因为应用客户端的更新会导致程序重新启动。单机安装版本则保留了一键式更新体验。

在任何后端更新之后，应用程序还会重新检查自身的版本信息；如果界面版本仍然滞后，它会通过“更新桌面应用程序”这一一键操作发出警告——这样一来，即使远程后端已更新，也不会让您的桌面应用一直使用过时的版本。

手动更新流程同样适用于通过图形界面进行更新的情况。

卸载

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

  • 仅卸载聊天 GUI —— 会移除桌面应用程序及其数据；Hermes 代理、您的配置以及聊天记录仍会保留。（相当于 hermes uninstall --gui 命令。）
  • 卸载 GUI 和代理，保留我的数据 —— 会移除应用程序和代理，但会保留配置、聊天记录及密钥，以便日后重新安装时使用。（相当于 hermes uninstall 命令。）
  • 卸载所有内容 —— 会移除应用程序、代理以及所有用户数据。（相当于 hermes uninstall --full 命令。）

应用程序会先关闭以完成卸载操作（清理工作会在其退出后进行，从而可以移除正在运行的应用程序包及其虚拟环境）。当未安装本地代理时（例如仅使用连接到远程后端的 GUI “轻量级”客户端），相关代理卸载选项会自动隐藏。

您也可以通过终端执行相同操作——使用 hermes uninstall --gui 仅卸载 GUI，或使用 hermes uninstall/hermes uninstall --full 同时卸载代理。

::note 如果在 源代码检出版本（即 hermes desktop 的开发构建版本）下运行 hermes uninstall --gui 命令，还会同时移除工作区中的 node_modules 文件以及 apps/desktop/{dist,release} 目录下的构建输出，因为这些都是 GUI 的构建产物。这些文件可以通过 hermes desktop（或 npm install 后重新构建）恢复——但如果您正在对桌面应用程序进行开发，就需要在之后重新安装依赖项。

::

CLI 参考：hermes desktop

如需通过命令行启动，只需运行 hermes desktop 即可。该命令会自动安装工作区所需的 Node 依赖项，构建对应操作系统的 Electron 应用程序，随后启动已打包好的应用。

在 Linux 系统上，系统会自动刷新 $XDG_DATA_HOME/applications/hermes.desktop 文件（默认路径为 ~/.local/share/applications/hermes.desktop），从而使 Hermes 显示在应用程序菜单中。若希望保留手动编辑的条目，可禁用自动刷新功能：

hermes config set desktop.manage_launcher_entry false

即便该条目不存在，也会被创建出来；该标志仅能阻止 hermes desktop 覆盖已存在的条目。

标志描述
--skip-build跳过 npm 安装/打包步骤，直接启动 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启用可预测的启动延迟，用于验证启动界面功能

工作原理

该打包应用包含了Electron外壳以及原生的React聊天界面。首次启动时，它会将Hermes Agent运行时安装到HERMES_HOME目录中（在Linux系统中为~/.hermes，在Windows系统中为%LOCALAPPDATA%\hermes）——这一路径与通过CLI安装时的路径相同，这也是两者可以相互替代的原因。后台服务查找顺序首先为HERMES_DESKTOP_HERMES_ROOT指定的路径，其次是已完成的管理式安装路径，接着是PATH环境变量中可找到的hermes命令路径（除非设置了--ignore-existing或HERMES_DESKTOP_IGNORE_EXISTING=1参数），最后则是针对Nix等打包工具的显式HERMES_DESKTOP_HERMES命令覆盖设置。React渲染引擎会与应用自动启动的无头后台服务进行通信，该后台服务即负责提供tui_gateway JSON-RPC/WebSocket API的hermes serve进程，且该应用会重用已安装的Agent运行时，而不会嵌入hermes --tui命令。这款桌面应用是完全自包含的：它自行运行hermes serve后台服务，无需打开也不依赖Web控制面板。（对于版本低于支持serve命令的运行时，系统会自动回退到使用无头的dashboard --no-open模式，因此应用更新永远不会落后于其后台服务。）安装、后台服务查找以及自我更新逻辑均位于Electron主进程中。

连接到远程后台服务

默认情况下，该应用会启动并管理自身的本地后台服务。您也可以将其配置为连接到运行在另一台机器上的Hermes后台服务——无论是VPS、家庭服务器，还是通过Tailscale连接的Mini节点。

所有与连接相关的设置都集中在同一个页面上：Settings → Gateways。（在旧版本中，这些设置分散在独立的 Gateway 和 Connections 页面中——如今它们已合并，旧的 ?tab=connections 深链接也会重定向到这个统一页面。）

Settings → Gateways → Connection mode 提供了除本地网关之外的其他连接选项：

  • 远程网关——输入您自行运行的 hermes serve 后端的 URL 并登录。本节其余内容将详细介绍这种连接方式。
  • Hermes Cloud——只需在 Hermes Cloud 中登录一次，即可从您的账户中选择相应的智能体，无需粘贴任何 URL。应用会自动检测您的智能体（如果您的账户涉及多个组织，还会提供组织选择器），连接到某个智能体后，会自动切换会话。当处于云连接状态时，状态栏会显示相应提示。

网关连接属于机器级操作：Gateways 页面用于管理此桌面端可连接的网关后端，而配置文件则是从您所连接的网关中检测到的。每次会话只能选择一个网关，而旁边的配置文件栏则用于选择该网关上检测到的配置文件。

多连接注册表

在同一设置 → 网关页面的下方，已注册网关功能会统一管理应用所识别的所有Hermes网关的列表——包括本地运行时、各类远程网关（局域网、Tailscale、互联网）、Hermes Cloud实例以及SSH主机——所有信息都存储在同一个地方。您可以通过侧边栏配置栏右侧的插件按钮（连接另一个Hermes网关…）或通过**⌘K → 网关**跳转至此。包含联合代理列表、@name-device的处理方式、集群级更新以及插件SDK相关信息的完整指南，请参阅将桌面设备连接到多个Hermes实例。

  • 每条连接都需要一个唯一名称（如“家庭实验室”或“工作笔记本电脑”之类的设备名）。当多个已注册网关使用相同的配置文件名时，系统会通过@profile-device的形式对其进行区分（例如@research-homelab）。
  • 可通过“会话”侧边栏切换网关。当注册了多个网关时，会出现一个带名称的网关选择器，它能够处理任意规模的网关列表，而不会让这些网关看起来像配置文件。此时，旁边的配置栏仅显示该网关对应的代理，并记住上次在该网关下使用的配置文件；对于大量的配置文件，系统也会进行独立优化。
  • 可自定义重启后自动打开的网关。启动时打开选项会保留向后兼容的主网关作为默认设置，或者让应用在成功连接后继续使用上次使用的网关。此设置存储在应用程序包之外，因此即使桌面端进行更新也不会丢失。
  • 可通过面板添加、编辑、删除或测试连接。添加功能支持四种类型的连接——本地连接、Hermes Cloud 连接、远程网关连接以及SSH 连接（当存在由应用管理的本地连接项时，本地连接按钮会被禁用；相关提示会显示在上述登录/发现流程中）。本地连接项由应用统一管理，无法被删除。测试功能则会直接检测连接的 HTTP 和 WebSocket 链路是否正常。
  • 保存时会自动过滤重复项：仅允许存在一个本地连接项；远程连接和 Cloud 连接会根据标准化后的 URL 进行去重处理（包括去除冗余字符、尾随斜杠以及统一转换为小写）；SSH 连接则依据标准化的 user@host:port 格式以及远程配置文件进行去重。
  • 首次使用注册表构建项目时，现有的设置会自动导入：当前的全局连接设置以及任何旧版的针对特定配置文件的覆盖设置都会被转换为带名称的连接项。原有的设置文件不会被修改，因此之前的构建版本仍可正常运行。
  • Cloud 连接项来自上述的 Hermes Cloud 登录/发现流程，而非手动输入的 URL。
  • 令牌会通过操作系统的密钥环以加密形式存储（在无密钥环的 Linux 系统上，可选择以明文形式存储）。 并行路由功能现已正式上线：每个已注册的网关会根据需求自行调用对应的后端及套接字（按连接和配置文件进行区分）；插件SDK提供了代理列表查询接口（host.agents() / host.ensureAgent()），而“更新所有实例”功能则会在网关页面上一次性向所有符合条件的网关发送hermes update指令——Hermes Cloud中的实例将被跳过（由平台自动处理），每个实例会自行反馈处理结果。
:::info 远程后端是一个正在运行的hermes serve进程 “远程后端”指的是运行在远程机器上的**hermes serve**服务器，也就是桌面应用所连接的进程。除非该后端确实处于运行状态且可访问，否则本节中的任何功能都无法正常工作。桌面应用不会自动启动该进程；需要由您（或systemd服务）在远程主机上保持hermes serve的运行状态，随后应用才会与其建立连接。如果您同时使用消息通道（如Telegram、Discord等），则“网关”是另一个独立运行的长时进程，需由您自行启动——具体说明见设置步骤后的备注。
::

该连接分为两个部分：在后端端，您需要通过认证提供程序来保护连接；而在应用端，则需要输入后端的URL并完成登录。将后端绑定到非回环地址后，其认证网关会自动启用，而您所配置的提供程序则决定了桌面应用能否成功通过认证。

请根据后端的实际位置选择合适的提供程序：

  • **OAuth（Nous Portal）——适用于需要访问本地机器之外的任何服务的场景。**登录过程会通过您的Nous账户进行验证，因此非常适合用于VPS、公共主机或任何远程后端。请使用 hermes dashboard register 命令（或Portal的/local-dashboards页面）注册控制面板，以配置其OAuth客户端，随后即可通过应用中的“使用Nous Research登录”功能进行认证。如果您自行搭建了身份提供者，自托管的OIDC提供者也能采用相同的方式工作。
  • 用户名/密码——仅适用于本地或受信任网络环境。当后端位于同一受信任的局域网内，或仅能通过VPN（如Tailscale）访问时，这是最简单的方案。该方法无需外部身份提供者，仅需保护一组共享的凭证，因此切勿将其用于面向公网的控制面板——此类场景应优先使用OAuth。

本节其余部分会介绍用户名/密码登录方式，因为它在受信任网络中部署最为快捷；关于OAuth登录方式，请参阅Web控制面板 → 默认提供者：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 backend bound to a reachable address. The non-loopback bind
#    engages the auth gate; the username/password provider handles login.
hermes serve --host 0.0.0.0 --port 9119

只要需要桌面应用能够保持连接，就请让 hermes serve 进程持续运行——一旦该进程停止，桌面应用就无法再与后端通信。建议通过 systemd、tmux 或您选择的进程管理工具来运行它，这样即便用户登出或重启系统，该进程也能继续运行。

另外，如果您依赖消息通道，请确保远程主机上的网关正在运行——桌面应用实际上是与 hermes serve 后端进行通信，而 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 Dashboard → 用户名/密码提供器。

如果选择以 systemd 服务的形式运行后端，请为该服务单元设置 EnvironmentFile=%h/.hermes/.env，这样在系统启动时凭证就会自动加载到环境变量中。

::warning 后端会读取和写入您的 .env 文件（其中包含 API 密钥及敏感信息），并能够执行代理命令。上文所示的用户名/密码设置仅适用于可信网络环境——切勿将受密码保护的后端直接暴露在公网上，而应将其置于 VPN 后面。Tailscale 是一种理想的解决方案：通过 --host <tailscale-ip> 参数绑定到设备的 Tailscale IP 地址，并将 http://<tailscale-ip>:9119 设置为远程地址，这样只有属于同一 Tailscale 网络的设备才能访问该后端。若需通过公网访问后端，则应使用**OAuth（Nous Portal）**提供方。

::

在应用中

设置 → 网关 → 远程网关：

  1. 远程地址 — http://<backend-host>:9119（如果在前端设置了反向代理，可使用如 /hermes 这样的路径前缀）
  2. 登录 — 应用会自动识别后端所支持的提供方类型，并相应显示对应的登录按钮。对于用户名/密码类型的后端，会显示一个登录按钮，引导用户填写凭证（即步骤 1 中的用户名和密码）；而对于 OAuth 类型的后端，则会显示使用 <provider> 登录的选项（例如“使用 Nous Research 登录”），从而触发对应提供方的浏览器登录流程。无论哪种方式，应用最终都能在后台建立已认证的会话。
  3. 保存并重新连接 — 该操作会将桌面界面切换到远程后端。会话会自动刷新；只要设置了 HERMES_DASHBOARD_BASIC_AUTH_SECRET，即使重启应用，用户仍可保持登录状态。 在启动应用程序之前，您还可以通过 HERMES_DESKTOP_REMOTE_URL 环境变量直接设置后端 URL，而无需使用用户界面（该设置会覆盖应用内的配置）；不过您仍需通过“网关”设置面板进行登录。
:::note 每个配置文件的远程主机 远程网关主机是按照配置文件来设置的，因此每个配置文件都可以指向各自的远程后端（或继续使用本地的后端）。切换配置文件时，应用程序连接的远程主机也会随之改变。
::

故障排除

  • 登录失败，出现 401 错误或“凭据无效”提示 —— 用户名或密码与后端的 HERMES_DASHBOARD_BASIC_AUTH_USERNAME / HERMES_DASHBOARD_BASIC_AUTH_PASSWORD 设置不一致。由于后端不会针对未知用户或错误密码返回特定错误信息（不存在枚举机制），因此请务必仔细核对这两项内容。可通过命令 curl -s http://<host>:9119/api/status | jq '.auth_required, .auth_providers' 检查认证功能是否启用——该命令应返回 true，且 auth_providers 中需包含 "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 Dashboard → 将 Hermes Desktop 连接到远程后端；环境变量则列在环境变量 → Web Dashboard 与 Hermes Desktop中。

扩展桌面应用

该桌面应用采用贡献驱动的模式——面板、页面、侧边栏导航、状态栏元素、调色板命令、快捷键以及主题均可通过同一个 SDK 进行注册，您也可以自行添加新功能。插件只需将单个 ESM 文件放入 $HERMES_HOME/desktop-plugins/<id>/plugin.js目录中即可；应用会在几秒钟内加载该插件，并在每次保存时实现热重载。您可以在设置 → 插件中实时管理已安装的插件。

如需完整参考资料，请参阅桌面插件 SDK。（此内容与网页控制台插件系统是相互独立的。）

在同一个“设置 → 插件”页面中的Agent插件部分用于管理您所安装的后端（代理端）插件——包括用户类、git类、项目类、pip类以及便携式安装版本。而通过仓库打包的内置插件（如平台适配器、提供程序插件等）则不会显示在此处：这类插件默认处于启用状态，且可通过其专属界面进行配置，因此该部分仅聚焦于您自行添加的插件。当存在两个或更多配置文件时，该部分还会配备专用的适用对象选择器，这样您无需切换整个应用程序，即可列出并切换其他配置文件中的Agent插件（后端的plugins.manage RPC接口支持可选的profile参数来实现此功能）。

故障排除

无需重启应用程序即可重新连接

如果桌面端聊天窗口或机器人停止响应，但连接状态仍显示为已连接，请选择对应的机器人/配置文件或网关，打开状态栏中的网关菜单，然后点击重新连接网关。该功能适用于处于已连接、正在连接或已断开状态的传输通道。它会在不重启桌面端应用程序或刻意关闭其他通道的套接字的情况下，重新拨打当前活跃的连接路径。不过，选定套接字上正在处理的请求可能会被中断；这属于一种主动的恢复操作，并非后端或模型的重启。

失败轮次会显示出出问题的环节

当某次轮次处理失败时，聊天界面会显示一张错误卡片，明确指出是哪一层发生了故障——无论是提供商/模型、自定义端点、流式连接、身份验证、计费系统、网关、本地运行环境还是磁盘存储——而非仅显示通用的错误提示。该卡片还会根据具体的故障类型提供相应的恢复方案。

  • 重试——在原地重新执行失败的轮次（当重试必然会导致相同错误时，此选项会隐藏，例如因内容策略限制而被拒绝的情况）。
  • 切换提供方——在出现提供方、端点、认证或计费相关故障时，跳转至“设置”→“模型”页面。
  • 打开日志——在文件管理器中打开HERMES_HOME/logs文件。在远程或云连接环境下，该按钮会显示为“打开桌面端日志”：此时会打开本地的桌面端日志（传输过程记录），因为失败轮次对应的网关/智能体日志存储在远程机器上。
  • 发送诊断信息——在获得用户明确同意后，会将经过脱敏处理的调试数据包上传至Nous内部存储系统（流程与hermes debug share --nous相同；所有敏感信息都会被脱敏处理，该数据包仅限Nous工作人员查看，并且14天后会自动删除）。操作成功后，系统会生成一个私密链接，可供用户粘贴到支持请求中，同时还会提供通往GitHub Issues、Nous门户支持页面以及Discord的快捷链接。在远程或云连接环境下，后台系统会自行整合智能体/网关日志，再将本地的桌面端日志一并附上，以便支持团队能够查看完整信息。
  • 复制错误详情——复制一份结构清晰的纯文本摘要（包含错误层级、代码、提供方/模型信息以及错误提示），用户可直接将其粘贴到缺陷报告或Discord中。 该层级数据源自代理程序重试循环所使用的同一错误分类器，因此能够准确反映真实的故障含义，而非仅基于消息文本的推测。那些尚未采用该描述格式的旧版后端，在显示该卡片时仍会使用通用的标题，以及“重试”、“查看日志”和“复制错误详情”等操作选项。

启动日志会被保存在 HERMES_HOME/logs/desktop.log 文件中（其中包含后端输出信息及最近的 Python 异常堆栈跟踪）。如果应用程序报告启动失败，应首先检查该文件。您也可以通过命令行界面对它进行实时查看：

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

“自您上次连接后，主机密钥已发生更改”（SSH远程连接）

如果您的SSH远程服务器已被重新安装，或其主机密钥已被更换，SSH连接将会直接失败。此时Desktop会显示错误提示界面，而不会尝试重新连接（在旧密钥被清除之前，重新连接永远无法成功）。请确认该密钥变更确实是预期中的情况，随后删除旧的密钥记录，再从错误提示界面中尝试重新连接。

ssh-keygen -R <host>

清除该条记录后，请点击重试（或通过“设置 → 网关”重新建立连接）——这样锁定机制就会被重置，下次启动时会重新进行连接尝试。

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

构建过程会从github.com/electron/electron/releases下载Electron运行时环境（约114 MB）。如果安装程序在“构建桌面应用”阶段卡住，且界面持续显示“retrying attempt=…”之类的信息，说明您的网络存在对GitHub的访问限制或流量限制（可能是防火墙、代理设置或所在地区的原因）。

安装程序会自动进行自我修复：在构建失败时，它首先会清除损坏的Electron压缩包缓存并重新尝试；如果仍然失败且您未设置ELECTRON_MIRROR，则会通过Electron社区常用的镜像站npmmirror.com再次尝试下载。@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'

**其他需要镜像源的本地预构建包（例如在 Windows 上预编译的 get-windows 包）：**请将对应的 npm 镜像配置键值添加到 $HERMES_HOME/npmrc 文件中（在 Windows 系统中为 %LOCALAPPDATA%\hermes\npmrc，其他系统则为 ~/.hermes/npmrc）——例如设置 node_get_windows_binary_host_mirror=https://<mirror>/sindresorhus/get-windows/releases/download/。每次运行更新工具生成的命令（包括桌面版、网页版和 TUI 版的构建命令）都会在存在该配置文件时将 NPM_CONFIG_USERCONFIG 指向它，从而确保配置信息在执行 hermes update 后依然保留；而项目根目录下的 .npmrc 文件会被 Git 跟踪，因此会在每次更新时自动暂存，不过由于桌面端会继承 GUI 环境，~/.npmrc 文件可能会被忽略。您自行设置的 NPM_CONFIG_USERCONFIG 值永远不会被覆盖。

如需手动清除损坏的缓存压缩包：

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系统的签名与公证操作会自动执行。

macOS权限设置与本地应用重新构建（TCC）

仅需一个开关即可屏蔽所有文件夹权限提示。 在Hermes访问每个文件夹时，macOS会按类别依次弹出提示（首先是桌面文件夹，接着是下载文件夹、文档文件夹等）。授予一次“全盘访问”权限即可永久覆盖所有文件夹，而且由于Hermes使用了稳定的签名身份，该权限在系统更新后依然有效：

  1. 前往“系统设置”→隐私与安全性→“全盘访问”（或运行命令 open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"）；
  2. 启用终端应用——如果使用桌面功能，还需启用Hermes.app；
  3. 完全退出后再重新启动这些应用。

hermes doctor命令可检测当前终端环境是否已拥有该权限，而在macOS上若未获得该权限，hermes setup会显示相关提示。

macOS会根据应用的代码签名身份来记录权限授予情况（全盘访问、桌面/下载/文档文件夹访问、辅助功能访问、自动化访问、麦克风访问等），而非应用的具体路径。本地构建且能自动更新的应用会使用带有稳定标识符的专用签名进行签名，因此这些权限在系统更新后依然保持有效。

特别提示：在应用“标识符锁定签名”修复功能（PR #73681）之前生成的授权令牌，仍需遵循旧的基于 cdhash 的锁定要求。对于这些过期的授权令牌，macOS 会持续将其开关状态显示为“开启”，但还是会再次弹出确认提示——因为存储的授权令牌已与重新编译后的二进制文件不匹配。此外，新版确认界面没有“允许”按钮，因此看起来似乎无需再进行检查。遇到这种情况时，请先重置过期的授权令牌，然后再重新生成授权。

tccutil reset ScreenCapture com.nousresearch.hermes   # repeat per service

接着在系统设置中开启“使用最新条目”选项，然后完全退出并重新启动Hermes。此后，权限配置将保持稳定。

如需最可靠的保障——即基于证书的身份验证机制（这也是yabai/skhd用户所依赖的方式），只需创建一个自签名的代码签名证书，并告知Hermes使用该证书即可。这一条命令即可完成所有操作：在您的登录密钥链中生成证书、授予codesign权限、写入配置文件，以及重新签名打包后的应用程序。

hermes desktop --setup-tcc-identity

或者手动操作：

  1. 打开“钥匙串访问”→“证书助手”→创建证书…
  2. 名称设为 Hermes Local Signing，身份类型选择 自签名根证书，证书类型则选 代码签名。
  3. 在“钥匙串访问”中双击新创建的证书 → 信任 → 将 代码签名 的信任设置改为 始终信任（导入的自签名证书在获得代码签名信任之前并非有效的签名身份——之后执行 security find-identity -v -p codesigning 应能列出该证书）。
  4. 执行命令 hermes config set desktop.macos_signing_identity "Hermes Local Signing"。

若需创建/使用名称不同的证书，可在命令中添加参数 --identity <名称>（默认值为 Hermes Local Signing）。该命令是幂等的——在更新后重新运行即可重新配置并重新签名已重建的应用程序。

后续的每次更新都会使用该证书重新签名已重建的应用，且所有 TCC 权限都会保留。无需 Apple 开发者账户。经公证的发布版本会被识别，不会被再次签名。

特别说明：更改签名身份（包括应用此修复后的首次更新）会一次性改变应用的身份，因此 macOS 会最后提示一次确认。此后权限将保持稳定。如果某个权限出现异常，可使用 tccutil reset All com.nousresearch.hermes 重置后再重新授予权限。

参见

  • CLI指南 — 终端界面
  • TUI — hermes --tui 命令及控制面板聊天栏所使用的现代化终端用户界面
  • Web控制面板 — 带有内置聊天栏的浏览器管理面板
  • 配置文件 — 桌面应用用于读取和写入的配置信息
  • Windows（原生版） — Windows系统的原生安装路径