Hermes Desktop

Hermes 桌面应用是一个围绕同一个 agent 构建的原生应用——你从 CLI 和网关得到的那个 agent——同样的配置、同样的 API key、同样的会话、同样的 skill、同样的记忆。它不是独立产品或轻量克隆；它使用同一个 Hermes Agent 核心和设置，并通过一个现代、设计考究的 UI 驱动它。如果你在终端里用过 hermes，你在那里配置好的一切都已在这里，你在这里做的任何事也会在那里出现。

它跑在 macOS（Apple Silicon）、Windows 和 Linux 上——完整矩阵见平台支持。

安装

从 Hermes Desktop 产品页下载应用，或按 Hermes Desktop 安装说明操作。

如果你已经装了 Hermes，直接运行

hermes desktop

即可。它用你当前的配置、key、会话和 skill。

应用里有什么

桌面应用是一个聊天优先的窗口，左侧边栏用于导航。它被设计为同时管理多个 agent 会话、配置消息提供商、创建产物、浏览项目文件夹结构，并同时处理多个项目。

边栏选中跟随聚焦的聊天窗格。打开或聚焦一个会话标签页会清除某页面的高亮（包括看板这类贡献页面），即使工作区保留该页面路由。

聊天

应用的中心。你得到：

• 流式响应，随 agent 工作显示实时工具活动和结构化工具调用摘要。当一个工具在处理图片时（例如 vision_analyze 处理后端文件系统下的文件），展开其活动行可看到图片，点击可全屏打开；远程连接时图片从网关拉取，而不是从运行应用的机器。
• Markdown 换行遵循 Markdown 语义：行尾两个空格产生硬换行；普通换行保持软换行。媒体和预览提取会保留被移除附件段之外的文本，包括首行代码缩进和未闭合围栏代码的留白。代码显示和复制保留 Markdown 解析器给出的前导空行、行尾空格和终端空行。
• 与其他每个 Hermes 界面相同的会话历史——在这里开始的会话可在 CLI/TUI 恢复，反之亦然。
• 聊天区任意位置拖拽文件即可附到下一条消息。
• 独立后台草稿——隐藏的聊天标签页可以更新自己的草稿，而不移动可见输入框中的光标或选区。
• 未发送草稿在丢失会话后存活——你在一个会话已不存在的聊天里输入的草稿（在别处被删、或 profile 改名/后端清空后的陈旧标签页）会被带进应用回退到的新聊天，输入框上方显示一条内联 已恢复你的未发送消息 条。撤销把文本放回原处；不替你发送、跳转或聚焦，该条每次丢失草稿只出现一次。
• 指令 chip 动作——悬停一个可操作引用（如 URL）以显示其动作胶囊。一段短暂宽限期让你从 chip 移到胶囊后再消失。在胶囊内移动时它保持可用；离开后无关指针移动不延迟消失。点击其动作保留草稿选区。
• 右侧预览栏——一边继续聊天，一边并排渲染网页、文件和工具输出。
• 有状态窗格的隐藏与关闭——一个装有浏览器（或 HTML 预览）或终端窗格的区域提供隐藏而非最小化。隐藏把区域折叠到恢复栏，但保留窗格主体挂载：活页面保留未保存的表单输入、定时器、滚动位置和 agent 的 drive_preview 自动化目标；终端保留其运行中的 shell 和回滚；恢复显示同样内容而不重载。隐藏的主体是惰性的——它绝不抢键盘快捷键或抢输入框焦点。关闭（标签页的 ×）才真正释放页面或 shell。
• 应用内浏览器的评论模式——在预览浏览器栏点 Annotate，然后在活页面上点任意元素（或拖一个框）并写注释；每条保存的评论作为带编号图钉留在页面上。保存图钉绝不发送一轮——完成后，添加 N 条评论把每个图钉的裁剪截图和一条点名每条评论的短提示附到输入框，发送仍由你自己点。每条元素评论带它的 CSS 选择器、标记和对布局重要的计算样式，因此 agent 能在你的源码里找到元素，而非凭图片猜。密码和隐藏字段值、以及任何看起来像 key 或 token 的属性，在标记离开页面前被打码。较大批次按每条评论所在页面部位分组到达，因此二十几条评论变成一小堆工作而非每条一个任务——而且因为各组是独立 DOM 子树，它们通常碰不同文件，这正是把它们交给并行 worker 安全的原因。删除一个图钉后编号保持稳定，切换聊天清空栈。
• 输入框历史与队列编辑——在空输入框按上下方向键召回并复用之前的提示，在发送前编辑已排队的消息。轮次排队时按停止（或 Esc）暂停队列并在输入框上方展开；从那里恢复，或单独发送、编辑、删除条目。
• 输入框上方的任务进度——展开 Tasks 头查看每个阶段。长列表在输入框上方有界，在展开列表内滚动即可到达最后任务而不移动对话。
• 会话时间线栏——长聊天在转录边缘得到一条细标记栏，每条提示一个标记。悬停它弹出提示列表，点一条直接跳到对话中那一点。跳转后，转录顶部的 Show earlier 从该提示继续向前翻页，一直到会话开头。（聊天有几轮后出现。）
• 阅读位置记忆——回到会话时恢复其保存的距底部距离，而非总是跳到最新消息。留在底部的会话继续跟随新输出。用 Scroll to bottom 回到实时边缘。位置保存在本 Desktop 安装的本地存储中；不通过后端同步。
• 页内查找——按 Cmd/Ctrl+F 打开查找栏，搜索渲染后的聊天转录。Enter / Shift+Enter（或栏打开时 Cmd/Ctrl+G / Cmd/Ctrl+Shift+G）步进匹配项；Esc 关闭。

异步 cron 和委派完成以折叠的时间线披露项出现。打开完成标签可把结果正文（含任务输出）作为 Markdown 阅读；长报告在披露项内滚动。任务指令和投递信封不作为报告内容显示。

状态栏

聊天底部的栏显示实时会话状态，并暴露快捷控制而无需打开设置：

• 按会话 YOLO 开关——只为本会话开/关 YOLO（与 TUI 一致）。YOLO 跳过危险命令审批提示，因此要清楚你在关什么——见安全 → YOLO 模式。
• 上下文用量表——会话上下文窗口的实时"% 已满"表。点击打开 Context Usage 弹层，按类别（系统提示词、工具定义、skill、记忆、规则、MCP、子 agent 定义，以及对话本身）分解 token，让你在压缩发生前确切看到是什么在吃窗口。
• 缓存命中率和每秒 token 数——默认关闭；从右键菜单开启。缓存命中率是本会话提示 token 中由提供商提示缓存服务的比例（缓存 token 更便宜，因此越高越省——你可以看着会话预热后变便宜）。每秒 token 数是最近 10 次模型调用平均的输出吞吐。两者在一轮中实时更新。
• 可定制项——右键状态栏（Show in status bar）选择显示什么：上下文量表、缓存命中率、每秒 token、工作区、模型、审批、轮次/会话计时器、终端、Command Center、后端版本等——或完全隐藏该栏（Cmd/Ctrl+Shift+S 切换）。工作区项菜单只在聚焦会话跑在本机时提供 Open containing folder；远程网关上的会话其文件夹留在那台机器，因此改用 Reveal in filetree。当 OS 文件管理器找不到某路径时，应用会明说，而非什么都不做。

连到另一台机器上的 Hermes 实例而非内置本地后端聊天？见下方连接远程后端——远程托管仪表盘连接如何工作（认证门、/api/ws 聊天 socket、WebSocket 关闭码分诊）的完整图景见 Web 仪表盘 → 把 Hermes Desktop 连到远程后端。

字体

两个独立字体设置在 Settings → Appearance，都按 profile 存在 config.yaml：

• Chat Font（desktop.font_family）——聊天和应用其余 UI。OpenDyslexic 或 Atkinson Hyperlegible 这类可读性字体在系统装好后即可用；当前主题的字体栈留在你的选择后面，因此缺字仍能渲染。留空表示用主题字体。
• Terminal Font（terminal.font_family）——内嵌终端窗格；Nerd Fonts 在这里渲染 shell 图标。留空表示内置 JetBrains Mono。

仓库发现

Hermes Desktop 通过有界深度扫描你的家目录，为 Projects 边栏发现本地 Git 仓库。你可以按 profile 在 Settings → Workspace 或 config.yaml 改：

desktop:
  repo_scan_enabled: true
  repo_scan_roots: []
  repo_scan_exclude_paths: []

• 设 repo_scan_enabled: false 完全停止文件系统扫描。该 profile 已有的磁盘发现缓存行被清除；显式项目和从有意的 Hermes 会话推断出的仓库仍可用。
• 把 repo_scan_roots 设为文件夹列表以限制扫描。空列表保留默认家目录扫描。
• 把 repo_scan_exclude_paths 设为应跳过完整子树的文件夹。

改这些值只使该 profile 的磁盘发现缓存失效并启动符合策略的刷新。Hide from sidebar 仍是独立的逐项整理动作。

用 Group by → Projects 时，每个项目行预览其最近三个会话。超过的项目以 Show all N sessions 行结尾，就地展开其余；边栏菜单的 Show all sessions 开关一次性移除所有项目的预览上限。

选模型

模型选择器在输入框里，麦克风左边。点击切换模型；悬停模型行看其选项（thinking、effort、fast）。旁边一个 reasoning pill 显示当前模型的 effort 级别（Med、High……）并直接打开同样选项，因此你不用找模型行就能改 effort。目录不报推理控制的模型，pill 隐藏。当路由夹紧 Hermes 内部步骤（ultra 作为路由最强级别发送，如 max）时，pill 显示两端（Ultra→Max），其 tooltip 用与 CLI 相同措辞说明 Ultra (sends Max on this route)，因此你看到的级别就是发送的级别。当网关把切换标记为有风险（大缓存上下文、昂贵模型、数据训练档），应用先在对话框问：Switch anyway 应用它，Keep current model（或 Esc）保持原样。

麦克风是听写；悬停它，其他语音开关在其上方展开——Read replies aloud 和唤醒词耳朵。开启的开关显示为实心圆盘。开启完整语音对话仍走右边的主按钮。在 HUD 和窄磁贴里，同样控件折叠进麦克风后的一个菜单。当听写直接连语音转文本提供商（客户端直连语音）时，请求遵守与网关自己转写客户端相同的 stt.openai.timeout 预算（默认 60 秒），因此慢端点以"Transcription timed out"失败，而非让麦克风卡在转写。

• 输入框选择器是粘性 UI 状态，绝不碰你的默认。 它本地记忆（按设备）并在新聊天和重启间跟随，而非弹回默认——选一次模型，下次 Cmd/Ctrl+N 就开在它上面。活跃聊天中切换模型把变更限定到当前聊天；两种情况下选区都在会话创建/切换时随行，且绝不写入 profile 默认——一个例外：在还没配 model.default/model.provider 的全新 profile 上，第一次选择会被持久化，这样应用有真实默认，而非重启后落到某个零散的 API key 环境变量。持久化遵循与 /model 相同规则（model.persist_switch_by_default）；用 Settings → Model 刻意改默认。（切换 profile 会重新播种到该 profile 自己的默认。）
• 在 Settings → Model 设默认。 那个"主"模型是你的按 profile 全局默认——新聊天、cron、子 agent 和辅助任务从它起步，也是唯一写它的地方。每个 profile 保留自己的默认。
• 按模型的 effort/fast 预设。 每个模型在桌面应用里记住自己的推理 effort 和 fast 模式选择，你选该模型时重新应用到会话。这些预设是桌面便利，不改 cron 或子 agent。
• 聊天中途切换重置提示缓存。 活跃聊天内切模型意味着下一条消息以全输入价重读整个对话（提供商提示缓存按模型为键）。偶尔为之无妨；长聊天上，在新模型上开新聊天通常比来回弹便宜。

文件浏览器

不离开应用即可浏览和预览工作目录——便于跟着 agent 读、写、编辑文件。用 hermes desktop --cwd <path>（或 HERMES_DESKTOP_CWD 环境变量）设初始项目目录。

Artifacts

输入框上方的预览链接是会话建议，不是任务完成清单。忽略一个会阻止历史工具行在导航或重载后把它带回来。新的成功工具完成可以再次提供该文件。只读文件检查和失败写入不产生建议。同名文件显示足够目录上下文以区分；忽略建议不删其文件或转录。改 /goal 不擦除一个对话的 artifacts。

连到远程网关时，打开文件 artifact 经该网关下载，使用 artifact 来源的 profile 和会话。相对路径对照会话保存的工作目录解析；家相对路径用网关的家，绝不用 Desktop 机器的家。Windows 风格相对路径与斜杠路径一起被识别，文件 URI 保留盘符和网络共享信息供网关解释。缺失会话或工作目录产生错误，而非选另一个本地文件。

Artifacts 视图把你会话产生的东西——图片、文件和链接——收集进一个可搜索、可浏览的画廊。从边栏、命令面板（Artifacts — Browse generated outputs）或你自己绑定的 nav.artifacts 快捷键打开。它自动索引最近会话输出；每个 artifact 显示是哪个会话产生的，并可跳回那个聊天，图片和文件在预览中打开，带下载/浏览器打开/复制动作。

窗口、标签页与窗格

应用为同时做多件事而建：

• 标签页——Cmd/Ctrl+T 开新会话标签页；Ctrl+Tab / Ctrl+Shift+Tab 循环会话，Ctrl+1…9 按位置跳到最近会话。Cmd/Ctrl+W 关闭聚焦标签页，Cmd/Ctrl+Shift+T 重开最后关闭的。
• 多窗口——Cmd/Ctrl+Shift+N 开新窗口，任何会话可通过其右键菜单（New window）或命令面板弹出。弹出的窗口只渲染那个聊天而无全局边栏——适合把长运行会话停在另一台显示器上。活 agent 输出流入显示该会话的每个窗口。
• 窗格——Cmd/Ctrl+B 切左边栏，Cmd/Ctrl+J 切右边栏，Cmd/Ctrl+\ 交换边栏在哪侧。

界面模式

布局编辑器（标题栏按钮，或 Cmd/Ctrl+Shift+\）打开时带一个 Interface mode 选择——也在 Settings → Appearance → Window & layout 下，命令面板里名为 Simple mode。它改变显示什么，不改变 Hermes 能做什么。

• Advanced（默认）是你已配置好的应用。未显式选 Simple 的用户留在 Advanced。
• Simple 是聊天优先：状态栏、profile 栏、终端、文件浏览器和审查窗格、技术工具调用视图、内联代码 diff、以及 Artifacts / Scheduled jobs 行都靠边站（Capabilities 和 Messaging 留下——它们是你配置 Hermes 的方式）；thinking 默认折叠；会话行显示标题、预览和上次活跃时间。标题栏保留 Settings 和布局编辑器。Simple 的布局选择器提供 Sidebar left 或 Sidebar right。模板和保存的布局是 Advanced。

一个布局说屏幕上有什么，不只是东西在哪：应用一个布局会打开它放置的每个窗格，关闭它留下休息的窗格，因此 Ctrl+**、**Cmd/Ctrl+J** 和 **Cmd/Ctrl+G** 永远与你所见一致。*Basic* 是会话和聊天，终端作为聊天下折叠栏休息，文件浏览器和审查在右列休息——**Ctrl+ 打开聊天下终端，Cmd/Ctrl+J 打开右侧树。Focus 把文件和审查作为聊天后标签页，带同样终端栏。Default、Terminal deck 和 Quad 打开它们放置的一切。你保存的布局记住其窗格哪些被关了。

每个模式记住自己的安排：窗格位置、大小、活跃标签页、隐藏标签页、忽略项、折叠侧和浮动卡片位置。回到一个模式恢复那个安排，而非重新应用预设。Simple 从左边栏开始；把它移到右边不改 Advanced。对话、草稿、预览和运行中的工作保持共享。

升级时保留已有布局。Advanced 继续用原存储键。如果你已显式选 Simple，其当前布局被复制进 Simple 的独立存储而不删原件。这次分离前被覆盖的旧安排无法重建。

Simple 跟随而非覆盖你的显示偏好。Simple 里每个键绑定仍工作——Ctrl+`、Cmd/Ctrl+J、Cmd/Ctrl+G 为当前会话打开终端、文件浏览器和审查，下次启动又安静如初。多于一个 profile 时 profile 栏保留，因为那时它是切换的唯一方式。首次运行引导按你选的布局设模式：Basic 从 Simple 开始，Elite 从 Advanced；跳过则留在 Advanced。

最小化到托盘

开启 Settings → Appearance → Window layout → Minimize to tray，让最小化窗口从任务栏或 Dock 隐藏，同时其会话继续跑。该设置默认关闭，只作用于本设备。

设置开启且有托盘时，用 X 或 Alt+F4 关主窗口会隐藏它而不停 Hermes 或销毁其会话。关次要窗口仍关那些窗口。用系统托盘（macOS 菜单栏）的 Show Hermes 恢复隐藏窗口。托盘菜单的 Quit Hermes 和 Cmd+Q 仍退出，包括正常的活跃工作确认。无托盘时关主窗口行为如常。

macOS 上，Dock 图标只在没有普通 Hermes 窗口可见时隐藏。Linux 上需要已注册的 StatusNotifier 托盘宿主；没有它的桌面保持正常最小化行为。宿主消失时，隐藏窗口被恢复。

终端

右侧边栏有一个真正的终端，紧挨文件浏览器：

• Ctrl+** 显示终端（没有就开一个）；**Ctrl+Shift+ 再开一个。多个终端在标签栏堆叠——Ctrl+Shift+↓/↑ 在其间走，Ctrl+Shift+W 关活跃的。
• shell 隐藏时持续。 关或隐藏面板不杀你的 shell——每个打开的终端保持挂载，回滚和运行进程完好，直到你显式关闭它。
• Add to chat——选中终端输出，作为下一条消息的上下文送进输入框。

活的子 agent

委派 worker 活跃时，输入框上方出现一个 Subagents 框，显示其数量、任务名、已耗时和最新活动。它预览最多三个 worker；展开头看名册，然后选一个 worker 看详情和 Steer / Stop 控制。每个框属于它的聊天，包括分屏里的。Steer 表示指导已排队到一个检查点，而非子进程已读到。见监控子 agent。

Git 审查与 worktree

对于跑在 Git 仓库里的会话，应用有内置源码控制界面：

• Review 窗格——Cmd/Ctrl+G 切工作树审查窗格：分支和领先/落后状态、改动文件（列表或树视图）、范围为 Uncommitted、Branch 或 Last turn（agent 最近一轮改了什么）的 diff。暂存/取消暂存文件、撤销改动、写提交信息（或 Generate commit message），然后 Commit 或 Commit & Push——并通过 GitHub CLI（gh）Create PR，或用 Ask Hermes to open PR 把整件事交给 agent。你也可以从这里创建和切换分支。
• Worktree——Cmd/Ctrl+Shift+B（或边栏某项目的 New worktree）在新分支上创建一个 Git worktree，让 agent 在仓库的并行副本上工作而不碰你的检出。Worktree 在项目下作为自己的泳道出现；移除时提供删除 worktree 目录（分支保留）或只隐藏泳道留在磁盘，有未提交改动时带 force 选项。聊天也跟随 agent：你让它建 worktree 并在里面工作时，聊天在轮末移到那条泳道，边栏随它重新定范围。只有你刻意把聊天切到的工作区（文件夹选择器或项目切换）才原地不动。

Memory Graph

Memory Graph（命令面板 → Memory Graph，或状态栏项）是 Hermes 为你所学内容的交互地图——skill 和记忆作为可缩放节点图布局，带时间线，可按 All / Used / Learned 过滤。一个分享控件把地图布局导出为紧凑代码，你可粘贴给别人（仅布局——不含你的记忆或 skill 文本），并以同样方式导入代码。

Quick Entry

Quick Entry 是一个随时可用的小输入框，由全局热键从系统任意处召唤——不用切到（甚至打开）主窗口就能发提示。在 Settings → Advanced → Quick Entry 开启；默认快捷键 Ctrl/Cmd+Shift+Space，你可自设（至少需要一个修饰键）。如果另一个应用已占用该和弦，设置行会告诉你，以便另选。

语音

和 Hermes 对话并听它回话，与别处可用的同一语音模式。macOS 上系统会提示一次麦克风访问。

HUD 模式

⌘/Ctrl+Shift+H（或标题栏按钮）把聊天分离成一个无 chrome、置顶的浮动条，浮在你正在工作的任何东西上。应用窗口让开；HUD 保留你的实时对话和输入框。你把它停在哪就是上下文——条的位置告诉 Hermes 你在问哪个应用和屏幕，因此"this"、"here"、"that page"解析到它下面的东西。

• 移动条——macOS 和 Windows 上，在输入框任意处按住一拍再拖。Linux/X11 上，按住 Ctrl 用鼠标主键拖可立即抓取（包括在选中文本上）；按住仍可用。调用桌面切换快捷键时保持抓取，把 HUD 带到另一个虚拟桌面。原生 Wayland 上输入框条是 compositor 拖动手柄（唯一移动方式，因为应用不能自己摆放窗口）。
• 缩放——拖条的任意边或角；对边保持锚定。原生 Wayland 暴露右边和底边，因为 compositor 不允许应用自己摆放顶层窗口。
• Reset layout——条上的丢弃控件恢复默认大小和（X11/macOS/Windows 上）位置。持久大小让 HUD 不可用时用它。
• 点按召唤——在 Settings → Keyboard Shortcuts → HUD gesture 下开启 Tap to summon HUD，然后在 macOS 上点按并松开 ⌘+Option，Windows/Linux X11 上 Ctrl+Alt。半秒内松开两键，无其他键或鼠标动作。Windows 上用左 Alt；右 Alt 留给 AltGr 布局。这从另一个应用打开或聚焦 HUD；它不切换关闭它、录音或发消息。默认关闭，只存本设备。macOS 需要 Input Monitoring 权限；页面只在权限或其他错误需要注意时提供恢复控件。Linux Wayland 不暴露此手势，因此在那里继续用应用内 HUD 快捷键。
• Snap to pointer——⌘/Ctrl+Shift+G（全局热键，从任意应用生效）把 HUD 跳到光标所在。原生 Wayland 上这是 no-op——摆放归 compositor。
• 退出——点条上的退出按钮、再按 ⌘/Ctrl+Shift+H、或 HUD 聚焦时按 ⌘/Ctrl+W。应用窗口带着你的会话和输入框光标回到前面。

Linux / Wayland

本地 Wayland 会话上（XDG_SESSION_TYPE=wayland，或设了 WAYLAND_DISPLAY）Hermes 以 --ozone-platform=wayland 启动，这样 Electron 不回退到 XWayland。平台必须在应用 JavaScript 加载前出现在进程命令行上。显式 --ozone-platform、desktop.ozone_platform_hint: x11、或 desktop.electron_flags 里的 ozone 平台仍胜出。拖、点击穿透和缩放走原生 Wayland 路径。

Hyprland（含 Omarchy）上，HUD 映射后通过 compositor 的 IPC 被浮动并钉住——否则 Hyprland 像对待任何窗口一样平铺它，always-on-top 被忽略，compositor 拖拽无效果。无需额外窗口规则。

少数 compositor（ notably COSMIC）对原生 Wayland 窗口忽略 always-on-top。要在那里恢复钉住，在 XWayland 下跑应用：

desktop:
  ozone_platform_hint: x11

这在启动时桥接到 ELECTRON_OZONE_PLATFORM_HINT（显式环境变量仍胜出）。代价：X11 无法恢复一个已忽略鼠标的窗口，因此 HUD 保持实心窗口而非点击穿透。某些 KDE 配置在 X11 ozone 后端下还报告键盘损坏——除非需要 always-on-top，否则把 hint 留在 auto。

WSLg（从 WSL2 用 Windows GPU）

本地 WSLg 下，Hermes 以 --ozone-platform=wayland 启动，避免 XWayland 最大化窗口偏移和鼠标命中测试错位（microsoft/wslg#1015）。平台必须在进程启动时选，在 Electron 加载应用 JavaScript 之前。显式 --ozone-platform=x11 和 desktop.ozone_platform_hint: x11 仍可用。应用在 WSLg 上自绘最小化、最大化和关闭控件。

当 hermes gui 在 WSL2 内运行、有 /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 保持软件渲染）。

启动标志与渲染器堆上限

两个 desktop.* 键在每条路径启动时到达 Chromium——hermes desktop、开始菜单快捷方式和 Linux .desktop 入口一视同仁（应用在第一个窗口打开前从 config.yaml 读它们）：

desktop:
  electron_flags: ["--ozone-platform=x11"]   # 额外 Chromium 开关；单个字符串按空格拆分
  renderer_max_old_space_mb: 2048            # 聊天渲染器的 V8 堆上限；0 = Chromium 默认

renderer_max_old_space_mb 作为 --js-flags=--max-old-space-size=N 应用，并与你已传的任何 --js-flags 合并，因此互不覆盖。当一个超长、工具密集的会话把渲染器推过机器可让范围时设它：渲染器随后撞到自己的上限并重载（每分钟最多三次），而非冻住整台机器。

两个键必须严格照写——顶层 desktop: 键下两个空格缩进，块列表 - 前四个空格：

desktop:
  electron_flags:
    - "--ozone-platform=x11"
    - "--js-flags=--expose-gc"

窗口前读取器是一个小 YAML 子集，不是 Hermes 其余部分用的完整解析器，因为它必须在应用加载任何东西前跑。其他缩进是合法 YAML 但在这里被忽略；发生时应用在启动时记 desktop.electron_flags / desktop.renderer_max_old_space_mb were ignored 日志并以 Chromium 默认启动。

设置与引导

用真正的 UI 管理提供商、模型、工具和凭据，而非编辑 YAML。首次运行引导几秒内带你到第一条消息。设置窗格覆盖提供商/key、模型选择、工具集配置、MCP 服务器、网关和会话管理。

• Providers 设置窗格——专门管理推理提供商的地方，带 Accounts / API-keys UX，按提供商登录并存凭据。Accounts、API key 和自定义端点共享 Settings 的 Applies to 选择：凭据读取和编辑、OAuth 账号移除、自定义端点保存/测试、以及从这里发起的登录都指向所选 profile，而非活跃聊天 profile。登录流程在凭据保存和模型选择中保持该目标。改 Applies to 丢弃未保存的凭据草稿。关闭登录取消轮询并忽略迟到结果；已发出的凭据写入可能仍在其原 profile 完成。外部管理的 CLI 凭据用自己的 CLI，不受此 profile 选择器覆盖。其 Local Models 视图安装和管理设备上的 llama.cpp 运行时——见本地模型。
• 菜单里的每个提供商和模型——GUI 呈现完整提供商列表和 hermes model 知道的每个模型，因此你从与 CLI 相同目录选，而非策展子集。
• 带 API 模式的自定义端点——Settings → Providers → Custom Endpoints 有一个 API Mode 选择器（Auto-detect、Chat Completions、Responses API、Anthropic Messages）——与 hermes model 为自定义提供商提供的相同选择。它存为 config.yaml 里的 providers.<id>.api_mode，因此只支持 Responses 或 Anthropic 兼容的主机不再被打到 /chat/completions。Test 检查你实际将用的传输，不只是 /v1/models：它向固定模式的路由发一个单 token 请求（或 Auto-detect 解析到的模式），主机不服务时以传输名失败。Test 还保留网关在 /v1/models 宣告的别名元数据（canonical_model、reasoning_effort）：选 gpt-5.6-sol-high 这类别名会保存规范模型并把其 effort 固定在 agent.reasoning_overrides 下。
• xAI Grok OAuth——Grok 是启动器里的一等 OAuth 提供商；像其他 OAuth 提供商一样走浏览器流程登录。
• 从 GUI 装工具后端——直接从应用跑工具后端的安装后步骤，而不用下到终端。在终端后端选择器里，选一个标 Needs setup 的后端会先要求确认；拒绝则保持当前后端。
• 终端字体选择器——在 Settings → Appearance 选已装字体。MesloLGS NF 这类 Nerd Fonts 在交互终端和 agent 终端都渲染 Powerlevel10k 分隔符和图标；设置按 profile 保存。
• Reasoning Blocks——Settings → Chat → Reasoning Blocks（config.yaml 里 display.show_reasoning）显示或隐藏转录中模型的思考（关则只显示答案）。设置一保存，打开的聊天立即更新。在输入框打 /reasoning hide 或 /reasoning show 翻转同一设置，打开的转录立即跟随。
• 启动时重开上次聊天——默认应用冷启动时从你停下的地方继续。在 Settings → Appearance 关掉（或 config.yaml 设 display.resume_last_session: false）则总是以新聊天开始。深链和显式目标在两种情况下都绝不被覆盖。
• 辅助模型警告——如果你把主模型切到新提供商，而辅助任务（标题、摘要和类似 helper）仍钉在另一个提供商，应用警告你，免得不知情地把工作拆到两个提供商。
• 按任务的推理 effort——Settings → Model → Auxiliary models 下每行在其提供商/模型选择器旁有一个推理选择器：一个级别、Off、或 inherit · main model effort（默认，移除该任务覆盖）。它存为 config.yaml 里的 auxiliary.<task>.reasoning_effort，与 hermes model 写的同一键，设置后在行摘要中显示。用它让压缩或标题等高频 helper 跑低或无推理，而主 agent 保持高。
• VS Code Marketplace 主题——除内置主题预设外，外观设置含实时 VS Code Marketplace 搜索：选任意颜色主题，应用下载、转换并安装为桌面主题。同一导入器可从命令面板（Install theme）获得，导入的主题可从外观设置再移除。
• 保持电脑唤醒——Settings → Advanced → Keep computer awake 阻止机器休眠，让长或过夜的 agent 运行继续（显示器仍可变暗）。这是按电脑设置。

首次运行引导已在统一覆盖设计系统上重做，你可以选 Choose provider later 跳过提供商设置先进应用。

按 profile 设置："Applies to" 作用域

当你有两个或更多 profile 时，配置支撑的设置页——Model、Workspace、Safety、Memory & Context、Voice、Chat、Advanced、Tools & Keys——加 Providers → Custom Endpoints 和 Messaging 覆盖层，顶部显示共享的 Applies to chip 行。它选你的编辑目标哪个 profile：

• 默认选择跟随活跃 profile，行为与以前完全一样——编辑你正在用的 profile。
• 选另一个 profile 查看并编辑它的设置而不切换整个应用；你在设置页间移动时选择持续。
• 切换应用活跃 profile 会重置选择器，因此编辑不会悄悄落到之前选的 profile。
• 少于两个 profile 时 chip 行完全隐藏。

（Gateways 页不同处理 profile——通过其 Per-profile overrides 子节——Capabilities 和 Scheduled Jobs 视图有自己的作用域选择器。）

管理窗格

应用还呈现更宽的 Hermes 管理界面，让你不必下到终端：

• Skills——打开 Capabilities → Skills 管理 skill。Installed 显示所选 profile 的实际 skill 和启用/禁用状态。Browse 搜索与公共 Skills Hub 相同的完整发布目录，带原生卡片和详情。
• Plugins——Capabilities → Plugins 用同样的 Installed / Browse 布局。Installed 把实际应用级桌面插件与所选 profile 的 agent 插件合并；Browse 显示公共插件目录。搜索留在顶部，标签切换和动作在两页共享一行。
• Memory graph（Star Map）——聊天里打 /journey（别名 /learning、/memory-graph）打开一个随时间学习的 skill 和记忆的交互星座，带播放滑块。节点可直接从面板编辑或删除（skill 归档，记忆移除）。见 Learning Journey。
• Cron——查看和管理计划任务。开 All profiles 时列表聚合每个 profile 的任务；一个任务的运行历史和动作（暂停、恢复、编辑、删除）总去任务所属 profile，无论哪个 profile 活跃。
• Profiles——在 Hermes profile（隔离的配置/skill/会话）间切换。
• Messaging——配置网关频道。Telegram 有一张 Quick setup 卡：点 Create with QR，在 Telegram 里扫码（或打开链接），Hermes 就为你创建 bot、检测你的用户 ID 加入允许列表、保存凭据并重启网关。任何凭据保存、清除或启用开关都在页面上保留 Restart now 横幅，直到网关真正重启；重启失败则横幅保留以便重试或手动重启。
• Agents 和 Command Center——多 agent 工作的编排界面。

Browse 的数据从哪来

这些是原生 Desktop 视图，不是嵌入网页。Desktop 和公共网站消费同一生成的 CDN 快照：

skill 快照合并 skills/、optional-skills/ 和集中的 skill 索引。插件快照来自 plugin-catalog/*.yaml 和缓存 star 数；同一次发布提供安装器的已移除条目列表。浏览不发起实时 GitHub API 调用或拉取插件/skill 源码仓库。Installed 是分开的：其状态来自所选 profile 的后端和应用的桌面插件注册表，而非那些公共快照。

公共 hub 的安装按钮打开 hermes://skill/install?identifier=... 或 hermes://plugin/install?catalog=... 链接，并需在 Desktop 确认。这些路由用更新的 Desktop 构建；应用缺失或太旧时卡片保留可复制的 CLI 命令。参数和审查流程见 skill 链接 和 plugin 链接。

Bot Mode（内置）

Bot Mode 随应用发布，默认开启：一个"每 agent 一个聊天"的名册，每个 Hermes profile 作为 bot 出现，带自己的头像（几何脸、上传图、AI 生成肖像或像素宠物）、自己的规范 Bot Chat 会话、自己的 Routines（由 Hermes cron 支撑的周期任务）。名册在左边栏作为你会话旁的一个标签页——一条 Sessions | Bots 标签栏——而非会话列表下方堆叠的第二个窗格。捡起旧堆叠布局的安装自动一次性归置到标签栏；如果你自己手摆过窗格，你的布局不动。Cronjobs（Routines）窗格只在 Bots 标签页活跃时停靠在聊天旁，切回 Sessions 时消失（旧桌面构建保持常显）。

从名册创建新 agent——Name / Title / Description 加一个 Advanced 披露项，带完整能力面（模型、SOUL、skill、工具集、MCP 服务器）——把它们分组到分区，并打开多个 bot 商议的群聊。群聊作为独立 Discord 风格行出现在名册——堆叠成员头像、成员数、最新房间行预览、"needs you"徽章——与 bot 行按相同的置顶+近期顺序交错。点群行把房间作为标签页打开，接管主聊天窗口（旧桌面构建回退到在 bots 侧面板内打开）。

bot 互相发消息：在任意聊天打 @researcher have a look at this，活跃 bot 把消息交出去并回报，bot 直接到达彼此的 Bot Chat（hermes -p <bot> chat）。后端自动教每个 bot 的规范 Bot Chat 会话消息协议（配置 agent.bot_mode_protocol，默认开）——包括队友 bot 从 CLI 无头打开它时——因此 bot 间回复和交接不用碰你的 SOUL.md，你的常规会话也不动。

Bot Mode 的会话——每个 bot 的规范 Bot Chat 和每个群聊成员会话——始终从全局 Sessions 边栏隐藏。它们住在 Bots 窗格（名册行、房间视图和每个 bot 的会话浏览器），而非与你自己的对话交错。

你不用的 bot 可以收起：右键 bot 行 → Hide Bot。隐藏的 bot 离开名册但继续工作——@提及仍解析，群聊成员资格不动。至少隐藏一个 bot 时 Bots 头出现眼睛开关；点它就地变暗显示隐藏 bot（右键 → Unhide Bot 带回一个），隐藏 bot 有未读活动时眼睛显示一个点。隐藏状态存在 bot 的 profile 里，因此它跨机器跟随 bot。

不想要？在 Capabilities → Plugins → Bots 关掉它的 Desktop 开关——名册、routines 窗格和输入框中间件实时注销，无需重启。

完整指南——创建 agent（含多机 Create on 选择器）、跨连接名册、bot 间提及、群聊如何决定谁回复：Bot Mode: A Roster of Agents。

键盘与导航

• 命令面板——按 Cmd+K 或 Cmd+P（Windows/Linux 上 Ctrl+K / Ctrl+P）跳到动作并从键盘导航应用：打开任意页面或设置节、按标题或 id 跳到会话、切模型/主题/颜色模式、派生终端、重启网关、更新 Hermes 等。
• 可重绑快捷键——Settings → Keyboard Shortcuts（或 Cmd/Ctrl+/）打开快捷键面板，几乎可重映射每个绑定——profile 切换、会话导航、视图开关、桌面插件贡献的任何快捷键。重复赋值标记为冲突。几个值得知道的默认：Cmd/Ctrl+N 新会话、Cmd/Ctrl+. Command Center、Cmd/Ctrl+, Settings、Cmd/Ctrl+Shift+F 搜索会话、Cmd/Ctrl+1–9 切到指针下窗格（或聚焦窗格）的第 N 个标签页，无窗格有标签栏时切 profile、Shift+X 切亮/暗。
• 自定义缩放快捷键——以半档增量缩放界面，更细控制文本大小。
• UI 语言切换器——应用内切界面语言：English、简体中文（zh-Hans）、繁体中文（zh-Hant）、日语、阿拉伯语（RTL）和俄语。

会话与 profile

• 会话列表重做——重做的会话列表，带归档和常规会话卫生，让列表随增长可管理。
• 按 id 搜会话——直接按 id 找特定会话。
• 并发多 profile 会话——同时跨多个 profile 跑会话，并用跨 profile @session 链接引用另一个 profile 的会话。
• 导出/导入 profile——把整套配置作为单文件分享。⌘K → Export profile…（或右键栏中 profile 方块）写出一个 .tar.gz，含 skill、记忆、人格、cron、插件和设置；API key 被剥离。从桌面导出还打包你的外观和界面——皮肤、亮/暗模式、自定义主题、profile 栏颜色和你的窗口布局——因此导入的 profile 到达时长得和发送者那里一样。通过 ⌘K → Import profile… 或栏旁 + 旁按钮导入；它应用覆盖层并把你放进新 profile。同一归档在聊天 /export / /import 和 shell 的 hermes profile export / import 都可用。见导出导入 profile 文件。

更新

应用后台检查更新，就绪时提供一键更新。

后台检查向 GitHub API 问分支顶端。匿名 GitHub 请求每网络地址每小时限 60 次，因此共享连接（办公室 NAT、VPN、代理）上，即使本机几乎没发请求，检查也可能报 GitHub API rate limit reached。要用 5000/小时预算，检查按此顺序用它找到的第一个凭据：

1. 从应用启动环境读 GITHUB_TOKEN，再 GH_TOKEN——每次请求读，绝不存储。
2. GitHub CLI 自己的登录（gh auth token）。这一档帮助从 Dock、Finder 或桌面启动器启动的应用——它们继承极简环境而没有你 shell 的变量。gh 在 PATH 和常见安装位置（Homebrew、/usr/local/bin、~/.local/bin、Windows GitHub CLI 安装器）查找；答案缓存到应用重启，因此 gh 每会话最多跑一次。
3. 匿名。

GitHub 拒绝的凭据（HTTP 401——过期或撤销）在 desktop.log 记一次，点名来源而绝不点名 token，请求匿名重试。应用更新用 git 而非 API，不受影响。

本地更新期间，详细构建输出流入活跃 profile 的 logs/update.log，包括分离的 --gateway 更新。它不进终端，但在构建完成前可用于排障。Windows 移交把该日志里新输出算作进度；不产生输出的子进程仍受空闲看门狗约束。进程存活本身不重置看门狗，取消更新不等其构建完成。

桌面应用和它对话的 Hermes 后端按各自时钟更新——你机器上的应用包、后端跑在哪就在哪。多于一个更新目标时（远程网关或多个已注册网关），更新控件（About 面板的 Update now、⌘K Update Hermes 行和更新就绪 toast）更新一切：先连的后端，然后其他每个合格已注册网关（Hermes Cloud 项由平台管理，跳过），最后桌面应用本身，因为应用客户端更新会重启应用。单机安装保持一键体验。

任何后端更新后，应用还重查自己版本，若 GUI 仍落后则用一键 Update desktop app 动作警告——因此更新远程后端绝不会悄悄让你留在旧桌面构建上。

手动更新流程也与 GUI 合用。

卸载

对于应用管理的安装，打开 Settings → About → Danger zone，选移除多少：

• Uninstall Chat GUI only——移除桌面应用及其数据；Hermes agent、你的配置和聊天保留。（同 hermes uninstall --gui。）
• Uninstall GUI + agent, keep my data——移除应用和 agent，但保留配置、聊天和机密供以后重装。（同 hermes uninstall。）
• Uninstall everything——移除应用、agent 和所有用户数据。（同 hermes uninstall --full。）

应用关闭以完成工作（清理在它退出后跑，这样它能移除运行中的应用包和自己的 venv）。无本地 agent 时移除 agent 的选项自动隐藏。

这些控件对 Nix、内置/Light 包和其他外部拥有的安装隐藏。那些通过其包管理器或操作系统移除。应用独立于远程后端更新状态检查自己的本地包属主。无法确认属主时不提供卸载动作。

自管理安装可从终端做同样的事——hermes uninstall --gui 只卸 GUI，或 hermes uninstall / hermes uninstall --full 连 agent 一起。

CLI 参考：hermes desktop

要从 CLI 启动，直接跑 hermes desktop。默认它安装工作区 Node 依赖、构建当前 OS 的解包 Electron 应用，然后启动那个打包产物。

Linux 上，启动会刷新 $XDG_DATA_HOME/applications/hermes.desktop（默认 ~/.local/share/applications/hermes.desktop），这样 Hermes 出现在应用菜单里。要保留手编条目，禁用刷新：

hermes config set desktop.manage_launcher_entry false

缺失条目仍会创建；该标志只阻止 hermes desktop 重写已存在的条目。

当你从应用宫格或菜单启动 Hermes（启动器设 DESKTOP_STARTUP_ID）时，条目只在窗口上屏后写入。如果应用在窗口出现前退出，那次什么都不写；下次显示窗口的终端启动、更新器重启动或宫格启动会装上它。某些 GNOME Shell 版本会丢失追踪一个 .desktop 文件在它仍启动时变化的应用（它们在启动通知完成或超时前保持该状态，而非等到进程退出），那可能稍后崩溃整个会话；等窗口出现可避免。终端启动和更新器重启仍立即写条目。

工作原理

打包应用带 Electron shell 和原生 React 聊天界面。首次启动可把 Hermes Agent 运行时装进 HERMES_HOME（~/.hermes，Windows 上 %LOCALAPPDATA%\hermes）——与 CLI 安装相同布局，因此两者可互换。内置应用用自带后端。无内置后端时，解析尊重 HERMES_DESKTOP_HERMES_ROOT，然后开发检出，然后为 Nix 等打包者提供的显式 HERMES_DESKTOP_HERMES 命令覆盖，最后可用的托管安装。命令覆盖优先于托管安装，因此 Nix 桌面不能悄悄启动旧的可变运行时。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 提供本地网关之外的替代：

• Remote gateway——输入你自己跑的 hermes serve 后端 URL 并登录。本节其余部分走这个模式。
• Hermes Cloud——一次登录 Hermes Cloud，从你账号上的 agent 里选；无需粘贴 URL。应用发现你的 agent（若账号跨多个组织则带组织选择器），连上一个后自动切会话。活跃时状态栏显示云连接。

网关连接是机器级的：Gateways 页管理这台桌面能连哪些网关后端，profile 从你连的网关发现。会话一次选一个网关，旁边的 profile 栏选该网关上发现的 profile。

多连接注册表

同一 Settings → Gateways 页再往下，Registered gateways 管理应用知道的每个 Hermes 网关的命名列表——本地运行时、任意数量远程网关（LAN、Tailscale、互联网）、Hermes Cloud 实例和 SSH 主机——全部持久化在一处。你可以从边栏 profile 栏右端插头按钮（Connect another Hermes gateway…）或 ⌘K → Gateways 跳到那里。完整指南，含并集 agent 名册、@name-device 句柄、机群范围更新和插件 SDK 界面，见把 Desktop 连到多台 Hermes 实例。

• 每个连接需唯一名字（设备名如 "Homelab" 或 "Work laptop"）。同一 profile 名存在于多个已注册网关时，界面以 @profile-device 消歧（如 @research-homelab）。
• 从 Sessions 边栏切网关。 多于一个网关注册时出现命名网关选择器，处理任意注册表大小而不让网关看起来像 profile。旁边 profile 栏只显示该网关的 agent，并记住那里上次用的 profile；大 profile 集独立折叠。
• 隐藏 profile 栏。 如果你的 profile 是 bot 而非工作区，边栏底部那行彩色 profile 方块与会话列表重复。从 Sessions 视图菜单（Profile rail）、shell 右键菜单或 ⌘K → Toggle profile rail 关掉。隐藏时，状态栏在网关选择器旁出现 Profiles 下拉，带同样选择——本网关的 profile、其他网关的 agent、New profile、Import profile…、Manage profiles…——因此切 profile 总有门。
• 选重启后打开什么。 Open on launch 保持向后兼容的 Primary gateway 默认，或连上成功后恢复 Last used 网关。此偏好存在应用包外，跨 Desktop 更新存活。
• 从面板添加/编辑/移除/测试连接。Add 流程提供全部四种——Local、Hermes Cloud、Remote gateway、SSH（应用管理的本地条目存在时 Local 按钮禁用，提示指向上面登录/发现流程的云添加）。本地条目由应用管理，不能移除。Test 直接探测连接自己的 HTTP 和 WebSocket 段。
• 保存时拒绝重复：只有一个 local 条目；远程和云条目按规范化 URL 去重（trim、去尾斜杠、小写——跨两类）；SSH 条目按规范化 user@host:port 加远程 profile 去重。
• 已有设置在你第一次跑带注册表的构建时自动导入：你当前全局连接和任何旧按 profile 覆盖变成命名条目。旧设置文件不动，因此旧构建继续工作。
• 云条目来自上面 Hermes Cloud 登录/发现流程，而非手输 URL。
• token 用 OS keyring 加密存储（无 keyring 的 Linux 显式明文选项）。

并排路由是活的：每个已注册网关按需拨自己的后端和 socket（按连接 + profile 为键），插件 SDK 暴露并集 agent 名册（host.agents() / host.ensureAgent()），Gateways 页的 Update all instances 一次向每个合格网关派发 hermes update——Hermes Cloud 条目跳过（平台更新它们），每个实例报自己的结果。

连接有两半：后端你用认证提供商保护它，应用里你输入后端 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 仪表盘 → 默认提供商：Nous Research。

在后端（远程机器）上

设用户名密码，然后启动后端绑到可达地址。凭据在 ~/.hermes/.env（机密文件，模式 0600）：

# 1. 设仪表盘登录凭据。
cat >> ~/.hermes/.env <<'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
# 推荐：一个稳定签名机密，让会话跨重启存活。
# 没有它每次启动生成随机 key，你每次重启都被登出。
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env

# 2. 跑后端绑到可达地址。非回环绑定启用认证门；用户名/密码提供商处理登录。
hermes serve --host 0.0.0.0 --port 9119

只要你想让桌面应用能连，就保持那个 hermes serve 进程跑——它停了，应用就够不到后端。把它跑在 systemd、tmux 或你选的进程管理器下，让它跨登出和重启存活。

另外，如果你依赖消息频道，确认网关在远程主机上跑着——hermes serve 后端是桌面应用对话的东西，但你的 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 仪表盘 → 用户名/密码提供商。

把后端跑成 systemd 服务？给 unit EnvironmentFile=%h/.hermes/.env，这样启动时凭据在环境里。

在应用里

Settings → Gateways → 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（它覆盖应用内设置）；你仍从 Gateways 设置面板登录。

故障排查

• 登录失败 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"。
• 没有"Sign in"按钮——它要会话 token——后端用户名/密码提供商没启用。/api/status 的 auth_providers 不列 "basic"。确认 ~/.hermes/.env 里用户名和密码（或密码哈希）都设了，且仪表盘进程真的加载了它们。
• 每次重启被登出——把 HERMES_DASHBOARD_BASIC_AUTH_SECRET 设为稳定值。没有它 token 签名 key 每次启动重生成，使所有会话失效。
• 连接被拒 / 超时——后端绑到 127.0.0.1（默认）或防火墙/VPN 挡端口。绑到 0.0.0.0 或 tailscale IP，把端口对可信网络打开。

从 web 仪表盘角度的同一设置见 Web 仪表盘 → 把 Hermes Desktop 连到远程后端；环境变量编目于 环境变量 → Web 仪表盘与 Hermes Desktop。

扩展桌面应用

桌面应用是贡献驱动的——窗格、页面、边栏导航、状态栏项、面板命令、键位和主题都通过一个 SDK 注册，你可以加自己的。插件是一个丢进 $HERMES_HOME/desktop-plugins/<id>/plugin.js 的单个 ESM 文件；应用几秒内加载，每次保存热重载。在 Capabilities → Plugins 实时管理已装插件。

完整参考见桌面插件 SDK。（这与 web 仪表盘插件系统 分开。）

桌面插件不沙箱：它在应用内以应用自己的权限跑（网关 RPC、原生桥、其他插件的存储）。只加载你写过或审查过的文件；目录安装的保护是目录信任模型（人工审查、SHA 固定）加入口允许列表——不是隔离。register() 抛错的插件回滚，行上显示为 Failed 带错误；⌘K → Reload desktop plugins 重读每个已装 plugin.js，包括安装器原地替换的那个。

Capabilities → Plugins → Installed 显示实际安装状态：每个插件一个列表项，详情窗格带 Desktop 和 Agent 控制。

• 插件可扩展这个应用、agent 或两者——每行徽章说哪个，从包内容推断（plugin.yaml → agent 半，plugin.js → 桌面半）。两半都有的插件是一行，绝不两行。
• Desktop 控制——装进这个应用的半。它是应用级的：同一开关、同一值，无论窗口看哪个 profile、网关或远程机器。桌面代码只从一个地方加载，~/.hermes/desktop-plugins/；统一 agent+桌面包的桌面半由应用在包安装时复制到那里（并跟随其更新和卸载），因此切 profile 绝不加载、卸载或重定范围一个窗格。开关实时应用。
• Agent 控制——装在所选 profile 后端的半（agent 插件：user、git、project、pip 和便携安装），目录钉移动时带一个 Update chip。profile 选择器只管 agent 半；单 profile 时根本没有选择器。仓库内置（平台适配器、提供商插件）不列：它们随发布启用，从自己的界面配置。例外是无自己界面的内置生命周期插件（disk-cleanup、security-guidance），它们出现在这里以便像其他 agent 插件一样开关。
• 插件不发的半显示破折号。桌面半的 agent 半未装在所选 profile 时显示 Install here，从包来源（目录条目或 git 远程）为该 profile 预填安装对话框。可选附加如 Accent Picker 通过 Install from Git 从自己仓库装。
• Uninstall——所选 profile plugins/ 文件夹下装的每个插件（user 或 git 安装）名字旁有垃圾桶按钮。它要求确认，然后从该 profile 删插件文件和安装元数据——与 hermes plugins remove <name> 同操作——并修剪统一包桌面半的应用级副本。重启网关以卸载插件代码。仓库内置和 pip 安装（入口）插件无垃圾桶按钮：前者不能移除，后者随 Python 包走。独立桌面插件（你丢进 ~/.hermes/desktop-plugins/、无 agent 包的文件夹）得同样垃圾桶按钮；确认后删本机该文件夹并立即卸载插件，不涉及网关。

切到 Browse 看原生插件目录。Browse 和 Install from Git 都打开审查后安装对话框。agent 插件目录安装时，后端把目录名解析到其审查钉。网站链接只带那个名字；Desktop 查找审查过的仓库和提交，而非信任链接提供的元数据。Install from Git 还为 agent 插件安装提供 Pin to commit（完整 40 字符 SHA，含私有仓库）；固定的 agent 插件显示 pinned @ <sha8> 徽章。旧 Settings → Plugins 链接重定向到这里。

故障排查

不重启应用重连

如果 Desktop 聊天或 bot 停止响应而连接仍显示 Connected，选那个 bot/profile 或网关，打开状态栏的网关菜单，点 Reconnect gateway。重连对打开、连接中和已断开的传输都可用。它重拨活跃路由，不重启 Desktop 也不故意关其他路由的 socket。所选 socket 上在途请求可能被中断；这是显式恢复动作，不是后端或模型重启。

hermes update 后应用消失

早先一次更新替换了检出却没保留 apps/desktop/release/，导致没有打包应用可启动。只要 HERMES_HOME/desktop-build-stamp.json（只由成功桌面构建写入）还在，下次 hermes update 注意到应用缺失并重建。手动重建：hermes desktop --build-only --force-build。Windows 上 ZIP 回退还在交换中保留构建好的应用、其渲染器包和 Electron node_modules。

本地后端在后台停了

如果本地 Hermes 后端进程在就绪后退出，Desktop 自己重启它并显示 Hermes stopped working in the background 通知；替换者起来后聊天重连。HERMES_HOME/logs/desktop.log 记录退出码和后端最后输出行（Hermes backend exited (1) 后接 Recent backend output:），因此即使应用自己恢复了，它死的原因也在日志里。每次重启后几秒内就死的后端指向后端本身——看那个尾部的 traceback。两分钟内三次这种重启后，Desktop 停止重生并显示 keeps crashing 通知而非循环；原因修好后重启动应用。

失败轮次点名失败层

一轮失败时，聊天渲染一张错误卡，点名哪一层失败——提供商/模型、自定义端点、流式连接、认证、计费、网关、本地运行时或磁盘——而非通用错误 toast。卡片提供匹配失败的恢复动作：

• Retry——原地重跑失败轮（重试会确定性复现失败时隐藏，如内容策略拒绝）。当限流或用量限制响应点名限制何时解除（Retry-After 头或 resets_at 字段），卡片在 Retry 旁显示 Limit resets at HH:mm (in 1h 05m)，让你知道重试何时可行；CLI/TUI 在错误下打印同一行。提示本身是信息性的，但卡片还提供 Retry when the limit resets (HH:mm)：点它，应用在重置时重试那轮一次，带实时倒计时和 Cancel 控制。调度只存在于打开窗口——切会话、发另一条消息或关应用都会丢弃，无人值守时什么都不重试。
• Switch provider——对提供商、端点、认证和计费失败，打开输入框的实时模型菜单，让你立即把这个聊天移到另一个提供商/模型（Settings → Models 只改新聊天默认）。屏幕上无聊天界面时回退到 Settings → Models。
• Open logs——在文件管理器打开 HERMES_HOME/logs。远程或云连接上按钮读作 Open Desktop logs：它打开本地 Desktop 侧日志（传输证据），因为失败轮的网关/agent 日志在远程机器上。
• Send diagnostics——经显式同意提示后上传打码调试包到 Nous 内部存储（与 hermes debug share --nous 同管道；机密永远打码，包仅 Nous 员工可见，14 天后自动删）。成功后你得到一个私有视图链接贴进支持帖，加上 GitHub Issues、Nous Portal Support 和 Discord 的快捷链接。远程或云连接上后端打包自己的 agent/网关日志，本地 Desktop 日志附在旁，因此支持看到两半。
• Copy error details——复制紧凑纯文本摘要（层、码、提供商/模型、错误消息），贴进 bug 报告或 Discord。

层来自 agent 重试循环用的同一错误分类器，因此它反映真实失败语义，而非从消息文本猜。早于描述符的旧后端仍渲染带通用标题和 Retry / Open logs / Copy error details 动作的卡片。

启动日志落在 HERMES_HOME/logs/desktop.log（含后端输出和最近 Python traceback）——应用报启动失败时先查它。你也可从 CLI tail：

hermes logs gui -f

规范源码安装时，Desktop 检查并跑安装启动器。PM 选其解释器和依赖生成。那个启动器工作时，缺引导标记不强制安装。

Linux 上，Chromium 自己的错误去 HERMES_HOME/logs/desktop-chromium.log，shell 本身崩溃在应用 Crashpad/ 目录留 minidump（在 Electron 用户数据目录内，connection.json 旁）。窗口随 journal 里 SIGTRAP 消失时，那个日志里的 FATAL: 行点名叫出触发的检查；附到 bug 报告。不上传任何东西。

Python 依赖损坏时，跑安装的 hermes pm repair。然后重启 Desktop。不要删猜测的 venv 路径或 PM 事实。应用文件损坏，通过安装属主修复。

# 重置卡住的 macOS 麦克风提示
tccutil reset Microphone com.nousresearch.hermes

Windows：SSH 客户端缺失或损坏

Windows 上应用通过内置 OpenSSH 客户端（%SystemRoot%\System32\OpenSSH\ssh.exe）跑 SSH。那个客户端没装时，回退到 Git for Windows 自带的 usr\bin\ssh.exe，再回退到 PATH 上的 ssh。内置客户端装了但坏了（例如 Windows 更新后每个 ssh.exe 以码 255 退出），启动停在点名客户端的错误上而非重试。要用不同客户端，在 config.yaml 设并重启应用：

desktop:
  ssh_path: 'C:\Program Files\Git\usr\bin\ssh.exe'

用单引号或不用引号，这样反斜杠保持字面。键在 desktop: 下两空格，像上面启动键。它对 macOS 或 Linux 无效。

"主机 key 自你上次连接后已变化"（SSH 远程）

如果你的 SSH 远程被重装或主机 key 轮换，SSH 关闭失败，Desktop 锁住错误覆盖层而非重试（陈旧 key 清除前重试永不会成功）。确认变化是预期的，然后从覆盖层移除旧条目并重试：

ssh-keygen -R <host>

清除条目后点 Retry（或在 Settings → Gateway 重应用连接）——锁重置，下次启动重新拨。

"Build desktop app" 卡在 Electron 下载

构建从 github.com/electron/electron/releases 下载 Electron 运行时（约 114 MB）。如果安装器卡在 Build desktop app 步骤，实时输出重复 retrying attempt=…，是你的网络（防火墙、代理或地区）挡了或限了 GitHub。

构建不自己回退镜像，也不重试失败下载：因任何原因失败的构建不动之前的应用（staged-and-swap，见更新），更新本身失败，hermes desktop --build-only --force-build（或下次 hermes update）重跑构建。如果失败是缓存 Electron zip 损坏，重建前从 @electron/get 缓存删它（Linux ~/.cache/electron/，macOS ~/Library/Caches/electron/，Windows %LOCALAPPDATA%\electron\Cache）。@electron/get 对每次下载做 SHASUM 校验，但校验和来自同一主机，因此你指向的镜像对两者都受信任。

要用镜像（如公司镜像或 npmmirror.com，事实 Electron 社区镜像），安装前或手动重建时设 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/。更新器派生的每个 npm ci/npm run（desktop、web 和 TUI 构建）在该文件存在时把 NPM_CONFIG_USERCONFIG 指向它，因此配置跨 hermes update 存活；仓库根 .npmrc 被 git 跟踪，每次更新自动 stash，~/.npmrc 可能被漏，因为桌面移交继承 GUI 环境。你自己设的 NPM_CONFIG_USERCONFIG 绝不被覆盖。

get-windows 缺失或半装： 构建不再失败——它打印 [stage-native-deps] get-windows not installed ... read_window_below will be unavailable in this build 并不带 read_window_below 工具发布。包目录存在但不可加载（运行中的 Hermes 窗口打断了 Windows 原地更新，安装日志 TAR_ENTRY_ERROR）时，同样警告点名目录，下次 hermes desktop --force-build 或更新在 npm install 前删它，这样包被重新解压——先关每个 Hermes 窗口和网关，免得解压再被打断。原生绑定或 macOS helper 缺失的包同样不带窗口枚举发布，而非让构建失败。

手动清损坏缓存 zip：

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

从源码构建

你要在应用本身上折腾时，从仓库根装一次工作区依赖，然后从 apps/desktop 跑开发服务器：

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

把应用指向特定检出，或从你真实配置沙箱化：

HERMES_DESKTOP_HERMES_ROOT=/path/to/clone npm run dev
HERMES_HOME=$HOME/.hermes/cache/scratch/throwaway npm run dev
npm run dev:fake-boot   # 用确定性延迟演练启动覆盖层

构建安装器：

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_*）。

可选的 HUD 修饰键点按 helper 与 Electron 包一起构建，打包在 ASAR 外。macOS 用已有 Xcode 命令行工具前置。Windows 构建用操作系统 .NET Framework 自带的 C# 编译器；无需 Clang 或开发者 SDK。Windows 打包失败而非悄悄省略 helper。Linux 构建需要 C 编译器和 X11/XInput 开发头（Debian/Ubuntu 上 libx11-dev 和 libxi-dev）；没有那些可选 Linux 前置时，打包不带修饰键点按支持继续。在目标 OS 上构建；Linux 还需目标架构。已装用户不需要开发者工具链。Settings 区分 helper 缺失、启动失败和不支持的桌面会话；缺或失败 Windows helper 时不显示 X11/Wayland 警告。

macOS 权限与本地重建（TCC）

一个开关让每个文件夹提示闭嘴。 Hermes 碰每个文件夹时 macOS 按类别提示（Desktop，然后 Downloads，然后 Documents……）。单个完全磁盘访问授权永久覆盖全部——而且有 Hermes 稳定签名身份，它跨每次更新存活：

1. 系统设置 → 隐私与安全性 → 完全磁盘访问（或跑 open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"）
2. 启用你的终端应用——如果你用 Desktop，还有 Hermes.app。
3. 完全退出并重开它们一次。

hermes doctor 报告当前终端上下文是否已有授权，hermes setup 在没有时于 macOS 显示此提示。

macOS 把权限授权（完全磁盘访问、Desktop/Downloads/Documents、辅助功能、自动化、麦克风）记在应用的代码签名身份上，不是路径。本地构建和自更新应用以稳定、固定标识符的临时签名签署，因此授权跨更新持续。

一次性说明：标识符固定签名修复（PR #73681）之前构建的授权带旧 cdhash 固定要求。macOS 对那些陈旧授权仍把开关显示为 ON 但仍重新提示，因为存储授权不再匹配重建二进制——而且现代提示没有 Allow 按钮，因此看起来没什么可重查。发生时，重置陈旧授权一次再重新授权：

tccutil reset ScreenCapture com.nousresearch.hermes   # 每个服务重复

然后在系统设置把新条目开关拨到 ON，完全退出并重开 Hermes。此后授权稳定。

要最强保证——证书锚定身份，yabai/skhd 用户依赖的同一机制——创建一个自签名代码签名证书一次，告诉 Hermes 用它。这条一次性命令做一切（在你的登录 keychain 创建证书、授予 codesign 访问、写配置、重签打包应用）：

hermes desktop --setup-tcc-identity

或手动：

1. Keychain Access → Certificate Assistant → Create a Certificate…
2. Name: Hermes Local Signing，Identity Type: Self-Signed Root，Certificate Type: Code Signing。
3. Keychain Access 里双击新证书 → Trust → 把 Code Signing 设为 Always Trust（导入的自签名证书在被信任用于代码签名前不是有效签名身份——此后 security find-identity -v -p codesigning 应列出它）。
4. hermes config set desktop.macos_signing_identity "Hermes Local Signing"

命令用 --identity <name 创建/使用不同名证书（默认 Hermes Local Signing）。命令幂等——更新后重跑它重指配置并重签重建应用。

下次更新用那个证书重签重建应用；每个 TCC 授权存活。无需 Apple 开发者账号。公证发布构建被检测，绝不重签。

一次性说明：改签名身份（包括此修复后第一次更新）改应用身份一次，因此 macOS 最后再提示一次。此后授权稳定。权限卡住时，用 tccutil reset All com.nousresearch.hermes 重置再重新授权。

另见

• CLI 指南——终端界面
• TUI——hermes --tui 和仪表盘聊天标签页用的现代终端 UI
• Web 仪表盘——带内嵌聊天标签页的浏览器管理面板
• 配置——桌面应用读写的配置
• Windows（原生）——原生 Windows 安装路径