sidebar_position: 5

将桌面端与多个 Hermes 实例连接

您可以在同一个桌面应用程序中注册所有拥有的 Hermes 后端——无论是本地运行时、局域网或 VPS 上的远程网关、SSH 主机，还是 Hermes Cloud 实例——并同时使用这些实例上的智能体。这种连接是持久化的：每个已注册的网关会根据需求自行建立与后端及 WebSocket 的连接，而后台智能体会在您切换查看其他网关时持续发送数据流。

这实际上是同时运行多个网关功能的桌面端补充：那篇文章介绍的是在单台机器上托管多个网关，而本文则是讲述单个桌面应用程序如何与多台机器进行交互。

如何找到该功能

所有相关设置都集中在统一的设置 → 网关页面中（旧版本有独立的网关和连接页面；旧的连接深度链接也会重定向至此）。可通过以下三种方式进入该页面：

• 设置 → 网关——直接进入该页面（按下Cmd/Ctrl+,，然后在设置导航菜单中选择网关）。连接注册表位于该页面的机器级连接模式控制选项下方。
• 侧边栏配置栏——配置栏右端的插件按钮（工具提示为**“连接另一个 Hermes 网关…”**）可直接跳转至网关页面。即使您尚未创建第二个配置文件或连接，该按钮始终可见。
• 命令面板——按下Cmd/Ctrl+K，然后输入Gateways（同时匹配connections、add gateway、remote、ssh、instances等关键词）。

网关注册表

在“设置 → 网关”页面中的已注册网关板块用于管理Hermes网关的命名列表。该板块的介绍中明确指出：“可借此管理该设备以及它能够通过远程连接、SSH或云连接访问的所有Hermes网关。”每个条目都代表一种连接类型：

需要了解的规则如下：

• 每一种连接都需要一个唯一的设备名称（如“家庭实验室”或“工作用笔记本电脑”）。该名称会出现在实例出现的所有地方——如列表徽章、标识符以及更新结果中。名称的唯一性不区分大小写，因此Homelab和homelab不能同时存在。
• 本地类型的条目由应用直接管理（其标签为“应用管理”），且不可删除。删除其他任何类型的连接都会导致其对应的后端服务及隧道中断；不过实例本身不会受到影响。
• 总是存在一个被标记为主连接的条目（其行上会有特殊标签）：在未指定具体网关的多网关调用中，系统会以此作为注册表的备用选项。执行“设为主连接”操作不会切换当前的会话工作空间；若移除主连接，则系统会回退到本地条目。
• “启动时返回上次使用的网关的会话” 用于控制应用完全重启后 Sessions 应该在哪个网关上打开。该选项默认处于关闭状态，因此 Sessions 会在 Primary 网关上打开。开启此选项后，Sessions 将继续使用最近一次成功连接的网关。失败的切换记录不会被保留，而已被移除或不可用的已保存网关则会回退到 Primary 网关。
• “测试” 会同时检测连接中的 HTTP 和 WebSocket 链路，因此测试通过（显示“可达”提示）意味着聊天功能确实可以正常使用——而不仅仅是主机能被 ping 到而已。
• 保存时会剔除重复项：系统中始终只存在一个 本地 连接记录；远程 和 云端 连接记录则会根据标准化后的 URL 进行去重处理（包括去除冗余字符、尾随斜杠以及统一转换为小写——这两种类型的连接记录都会进行此处理，因此同一个 URL 不能同时对应一个云端记录和一个远程记录）；SSH 连接记录则依据标准化的 user@host:port 格式以及远程配置文件来进行去重。
• 云端连接记录通常来自“网关”页面顶部的 Hermes Cloud 登录/发现流程——在添加连接编辑器中选择 Hermes Cloud 类型即可进入该流程。

可通过 Sessions 侧边栏切换网关。配置文件、聊天功能、消息传递以及定时任务等功能都将局限于当前所选的网关；而由应用管理的窗口后端仍由上文的连接模式控制选项决定。Primary 网关是系统注册表的默认回退选项，不会改变当前的工作空间。

组织会话群组

在“会话”侧边栏的视图菜单中，查看所有配置文件时请选择网关与配置文件。每个网关都会拥有一个可折叠的独立板块，而配置文件则包含其对应的会话子板块。拥有default配置文件的两个网关会保持分开显示。网关标题以保存的连接名称开头，而配置文件标题则显示配置文件名称。

您可以通过网关或配置文件板块的菜单来执行重命名组、重置名称、上移或下移操作。重命名仅会改变侧边栏中的标签，不会影响网关或配置文件本身。网关作为完整板块进行重新排序，而配置文件则在其所属的网关内部重新排序。您可以通过拖动板块前的图标来调整顺序，或者选中该图标后使用空格键、方向键再按一次空格键来确定位置。当前桌面上会记住名称、顺序以及已折叠的板块状态。折叠某个网关时，其各配置文件的独立折叠状态也会被保留。每个配置文件的新会话操作均针对其所在网关上的该配置文件。

当退出门户发现功能后，Hermes Cloud面板还会列出已保存的云网关。使用网关选项用于选择现有的已保存连接，且不会更改默认网关；当前窗口中使用的网关则用于标识当前正在使用的网关。新增实例时会使用其易于识别的云名称，而现有的自定义连接名称则会保持不变。已保存的连接仍需有效的网关认证；您可以通过已注册的连接控件来管理登录信息。

逐步添加连接

1. 打开 设置 → 网关，滚动至连接注册表处（或点击侧边栏中的插件图标）。
2. 点击 添加连接。
3. 选择连接类型：本地、Hermes Cloud、远程网关 或 SSH。若已存在应用管理的本地条目，则 本地 类型将被禁用——这种情况几乎总是如此；选择 Hermes Cloud 会跳转至上述的云平台登录/发现流程。
4. 填写相关字段：
   • 名称 — 必填且唯一，该实例在所有界面中显示的“设备名称”（占位符为 Homelab），最多64个字符。
   • 仅限远程网关：
     • 网关URL — 正在运行的 hermes serve 后端的基准URL，例如 http://homelab.lan:9119，支持使用反向代理路径前缀。
     • 认证方式 — 选择 会话令牌 或 OAuth：
       • 会话令牌 — 粘贴来自远程网关的控制台会话令牌。编辑时，可选择“留空以保留已保存的令牌”。
       • OAuth — 通过Nous Portal的浏览器流程进行登录，无需粘贴令牌。
   • 仅限SSH：
     • SSH主机 — 采用 user@host:22 格式的组合字段（用户和端口为可选项）。系统将使用您的SSH密钥，同时通过隧道传输控制台令牌。
5. 点击 保存连接（或 取消）。
6. 点击新添加的那一行的 测试 按钮，等待显示“可达”状态。 稍后可使用铅笔按钮编辑任何非本地条目，或通过垃圾桶按钮将其删除——删除操作会要求确认，并提醒您：“实例本身不会被修改——您可以随时重新添加它。”

:::info 远程后端是一个正在运行的 hermes serve 进程 除非后端在另一台机器上真正处于运行状态且可访问，否则此处的一切功能都无法使用。桌面应用会连接到该后端，但不会为您启动它（通过 SSH 连接时除外，在这种情况下应用会根据需求通过隧道启动控制面板）。有关后端配置的详细信息——包括身份验证提供程序、绑定到非回环地址以及 Tailscale 的使用指南，请参阅连接远程后端。

::

从单连接设置迁移

首次启动具备注册表功能的版本时，系统会自动导入您现有的设置：全局连接模式以及“设置 → 网关”页面中的任何旧版逐配置文件覆盖设置都会被转换为带名称的注册表条目（通过 URL/主机地址进行去重处理）。（较新的版本在“网关”设置页面中不再提供逐配置文件覆盖功能——网关连接是在机器层面建立的，而配置文件则是从您连接的网关中获取的。）旧版设置文件不会被修改，因此同一台机器上的旧版本仍可正常使用。如果迁移后的名称发生冲突，系统会在其后添加后缀（如 Homelab 2）。

跨网关的 Agent

每个已注册连接中的profile都可视作一个agent。 多网关界面（以及内置的Bot Mode界面）所展示的列表即为此联合列表：

• 当多个网关上存在相同的profile名称时，系统会通过**@name-device**的形式对其进行区分——例如在您的Homelab环境中名为“research”的profile会显示为@research-homelab，而仅在所有网关上都唯一的profile则保留其原始名称。
• 列表生成是即时进行的，但套接字连接则是延迟建立的：应用会通过REST接口列出所有agent，而无需逐一连接每个网关的WebSocket。无法连接的网关只会对应行显示异常状态，而不会导致整个列表出错；SSH连接也会保持按需建立的状态，直到您首次打开该网关上的某个agent（因此不会出现意外建立的隧道）。
• 打开某个agent时，实际上只是连接到它所属的网关——聊天记录、会话内容以及内存数据都存储在拥有该profile的机器上，其使用方式就如同您直接使用该实例一样。

每对“(connection, profile)”组合都会拥有独立的后端和套接字，并采用与本地按profile管理的后端相同的空闲资源回收机制——即便您正在查看另一个网关，后台的agent仍会持续处理数据流。

审批按钮会将请求路由回对应会话的所属后端，而非当前选中的profile所在的后端。对于本地的备用profile，即使缓存的会话绑定信息丢失，Desktop仍可使用发送请求时所用的套接字。不过，已保存的会话归属权始终具有优先级；删除或重命名该本地profile将会清除这条临时路由，而不会尝试重新连接已过时的后端。

切换与作用域管理

侧边栏的层级结构为：网关 → 配置文件 → 会话。网关指的是机器或托管的后端服务；而配置文件则是运行在某个网关上的独立Hermes代理。

• 当仅注册了一个网关时，不会新增任何网关控制功能。仅支持本地使用的桌面版仍保持原有的配置文件栏和键盘操作流程。
• 当注册了多个网关时，侧边栏会显示一个带名称的网关选择器。其对应的设备、云端、网络或终端图标可标识连接类型；配置文件头像则仍位于分隔线之后的独立控制区域。无论网关数量是两个还是更多，该选择器都能正常工作，而不会将其他后端服务显示为类似配置文件的图标，也不会使配置文件操作挤满控制栏。
• 选择某个网关后，会自动恢复此前在该网关下使用的最后一份配置文件。主页按钮会回到默认配置文件，而层级按钮则会显示“该网关下的所有配置文件”。Cmd/Ctrl+1–9 键仍可用于在当前激活的网关内切换配置文件。
• 在存在多个网关的情况下，配置文件栏会变为集群栏：所有已注册网关的配置文件都会显示在同一条栏上，每组配置文件前都有对应网关类型的图标（设备、网络、终端、云端）——这些图标与网关选择器所使用的图标相同。当前激活的网关对应的方块外观与单网关桌面版完全一致；其他处于待机状态的网关方块则会变暗。将鼠标悬停在待机方块上即可显示其对应的机器名称（如“omer · 此设备”），因此即使不同机器上存在同名配置文件，它们的显示也会相互区分。
• 点击处于待机状态的方块会执行与网关选择器相同的切换操作，即定位到对应的特定 (网关, 配置文件) 对：在拨号连接目标期间该方块会旋转，之前的网关图标会保持显示状态直至目标接通；若目标无法响应，则点击操作会以提示信息失败，而不会使界面处于半切换状态。无论哪个网关处于活跃状态，分组都会保持注册顺序，因此被点击的方块永远不会移动到指针下方。右键点击待机状态的方块可执行 切换至、更改颜色、重命名、编辑 SOUL.md 以及 删除 等操作，这些操作均会在该方块所对应的网关上执行；删除操作确认时还需输入目标设备的名称。
• 上次枚举未能访问到的网关会保留其对应的方块，这些方块的图标上会标有一个琥珀色圆点——处于待机状态的设备仍属于用户所有。同一个后端服务的两次注册会被合并为一个分组。当设备总数超过 13 个时，界面上的方块条会按网关分类，整合为单个菜单区域。
• 只有在开启了 设置 → 网关 → 启动时返回到上次使用的网关的会话 选项后，选中的网关在退出并重新启动应用程序后才能保持不变。该偏好设置及网关编号存储在应用程序的用户数据注册表中，因此更换或更新应用程序包不会重置这些设置。
• 若活跃网关上拥有的配置文件数量超过 13 个，其对应的头像条会整合为一个带名称的配置文件选择器。这样一来，庞大的网关和配置文件集合仍可共存，而无需改变 网关 → 配置文件 → 会话 的结构模式。
• 即使远程连接被设为首选，该设备依然属于一级网关。在远程连接中断时，它仍能维持本地会话的可用性，但应用并不会将其标记为“离线模式”：所选的模型或工具可能仍需网络连接。
• 会话列表、消息频道、定时任务、设置、文件以及内存数据均局限于当前激活的 (网关, 配置文件) 组合。从 Telegram 网关切换到 Signal 网关时，侧边栏中的旧网关频道组或会话不会随之消失。
• 切换器仅通过读取 Electron 的本地连接注册表来工作。远程网关仅在被选中时才会建立连接，系统不会定期对所有设备进行轮询。
• 将鼠标悬停在某个智能体上即可预热其后台，从而避免切换时出现冷启动的情况。
• 能力页面（技能/工具/MCP）也具有对应的范围限制：其配置选项会列出联合列表中的所有 (配置文件, 设备) 智能体，选中其中一个后，即可在不切换会话工作区的情况下，读取和修改该设备的技能、工具集及 MCP 服务器信息。Hub 安装、环境变量以及 MCP 设置都会保存在所选智能体的后台中。MCP 选项卡中的热重载到当前会话按钮仅适用于与当前窗口连接的网关上的智能体；在其他设备上进行的编辑则会在该设备的下一次会话中生效。

可通过设置 → 网关来添加、测试、重命名或删除网关。配置文件操作旁边的插件按钮是直达该管理页面的快捷方式，并非另一套添加流程。

会话模式与机器人模式

会话模式有意仅显示一个处于活动状态的网关：这样可以将文件、工具、频道、定时任务以及会话历史记录置于一个清晰易懂的执行上下文中。舰队配置栏仅会扩展“选择器”功能——每次点击后，工作空间依然只存在于某个特定的 (网关, 配置文件) 组合中。而机器人模式则承担不同的功能，它可能会按网关分组展示所有代理列表，从而让用户能够通过同一界面同时打开位于 NAS 和 VPS 上的代理。不过，启动机器人时仍会激活其对应的特定 (网关, 配置文件) 路由。

默认情况下，直接提及机器人或进行任务委托仍局限于当前网关范围内。由于跨越后端边界会导致文件系统、凭据、工具以及信任上下文发生变化，因此跨网关执行应当通过专门的桥梁实现，而非仅仅因为共享同一个桌面窗口而产生的偶然副作用。

同时更新所有实例

设置 → 网关 → 更新所有实例（当注册了多个连接时会再次显示此选项）会同时向所有符合条件的连接发送 hermes update 命令：

• 本地连接通过应用程序自身的更新流程进行更新（与“设置 → 更新”中的流程相同）。
• 远程及 SSH 连接则会被指示通过其各自的后端进行更新——更新操作会在该机器上执行。
• Hermes Cloud 实例则会显示“由 Hermes Cloud 管理”的提示并跳过更新：版本管理工作由该平台负责。 每个实例都会独立上报状态，因此某个无法连接的设备绝不会影响整个批处理进程。那些通过外部方式管理更新的后端（如 Docker、Nix）会针对每一行数据以各自的消息形式进行礼貌的拒绝。

不过，您几乎无需使用“设置”按钮：一旦存在多个更新目标，应用程序的常规更新功能（“关于”面板中的“立即更新”、⌘K 键组合下的“更新 Hermes”以及显示的更新准备就绪提示）就会自动按顺序执行更新操作——首先更新当前激活的后端，接着是其他符合条件的网关，最后才是桌面应用程序本身。详情请参阅桌面应用指南中的更新部分。

安全注意事项

• 令牌的存储位置。远程网关会话令牌（以及以网关基础 URL 为键的本地登录 OAuth 令牌）会作为仅所有者可访问的（0600 权限）文件，存储在 Electron 主进程所在的应用用户数据目录中；渲染进程和插件永远无法查看令牌的具体内容。
• 可选的钥匙串加密功能。默认情况下，这些令牌不会经过操作系统的钥匙串处理——尤其是在 macOS 系统上，Electron 的 safeStorage 会将每个应用对应的密钥存储在登录钥匙串中，而若钥匙串被锁定或损坏，则每次启动应用时都会出现密码输入提示。如果您希望在文件权限的基础上再增加静态加密功能，可开启 设置 → 网关 → “使用操作系统钥匙串对保存的机密信息进行加密”；现有存储的机密信息将会在原位重新加密（macOS 使用钥匙串，Windows 使用 DPAPI，Linux 使用会话密钥环后端）。关闭该功能则会导致这些信息再次解密。
• 注册表文件（位于应用用户数据目录下的 connections.json）用于存储标签、URL 和主机地址——机密信息始终以加密形式存在其中。
• 插件 SDK 的 host.connections() 方法会刻意仅返回标签、类型和主标识符，而绝不会暴露令牌的实际内容。

面向插件开发者

桌面端 插件 SDK 直接提供了对多网关功能的访问接口：

• host.connections() — 已注册的连接列表（包含标签、类型以及主节点信息；绝不包含令牌字节）。
• host.agents() — 联合列表：每行代表一个 (gateway, profile) 组合，并附有预先计算好的 @name-device 标识。
• host.ensureAgent(connectionId, profile) — 激活某个代理的网关，以便后续的 host.request 调用能够访问其后端服务。
• host.warmAgent(connectionId, profile) — 执行即忘式的套接字预热操作（用于提升响应速度）。

以上四个功能均依赖特定特性支持：在较旧版本的桌面版中这些功能并不存在，此时插件应退而使用仅基于单个网关的 profiles.list 工作流程。Bot Mode模式下的多网关列表则是这类功能的参考实现方式。

故障排除

• “连接测试失败” — 表示从当前机器无法通过该 URL 访问后端。请检查远程主机上是否正在运行 hermes serve，端口是否开放，以及（针对令牌认证）令牌是否有效。修复问题后请重新运行测试功能。
• 智能体可见但无法打开 — 请对其连接进行测试。如果 HTTP 连接正常而 WebSocket 连接失败，通常是由于代理、防火墙或网关的认证/源地址限制阻止了对 /api/ws 的访问。
• 列表中缺少某个远程网关 — 说明其后端已关闭或无法访问；列表中会将该网关标记为存在错误的选项。SSH 连接在首次使用前会显示按需连接状态，这是正常设计，并非故障。
• “需升级 Hermes Desktop 才能通过多连接方式与智能体通信” — 该应用程序版本较旧，不支持多连接功能；需升级桌面应用本身。
• 设备名称重复 — 此情况不会发生；系统会在保存时强制确保名称唯一。如果迁移后出现名称冲突，系统会为其添加后缀（如 Homelab 2）。
• “无法保存该连接” — 最常见的原因是缺少名称、名称已被占用，或是网关 URL/SSH 主机地址格式有误；错误信息会明确指出具体问题所在。