Bot 模式（Bot Mode）将你的 Hermes 配置 变成一队有名字的 **Bot。

每个 Bot 都有自己的角色、模型、记忆、技能和头像。
Bot 可以运行周期性例行任务、在群聊中共同协作、并直接互相发送消息。
构建一个专家 Bot 一次，它就永远在那里，一键即可使用。

Bot 模式内置于 桌面应用 之中，并且默认开启——无需安装。
它会以 Bots 标签页的形式出现在左侧边栏中 Sessions 旁边，当 Bots 标签页激活时，一个 Routines（例行任务） 面板会停靠在对话旁边。

[!success] Bot 就是一个配置（profile）

没有需要学习的新原语：一个 Bot 就是一个 Hermes 配置——在 ~/.hermes/profiles/<name>/ 下拥有隔离的配置、记忆、技能、凭证和聊天历史。

Bot 模式是该原语之上的一个 UI，因此你在其中所做的一切在 CLI 中同样可见：hermes -p <bot> chat 打开的是同一个代理，Bot 的例行任务出现在 hermes cron list 中。

无需核心补丁、无需后台守护进程、无需额外存储。

1. Bots 面板

花名册（roster）为每个代理配置显示一行：头像、最新消息预览和时间戳。

• 点击一个 Bot 进入它的聊天——每个 Bot 都有一个规范的、持久的 Bot 聊天（Bot Chat） 会话，该会话在 Bot 诞生的那一刻被创建（并置顶）。
  • 点击某一行总是打开那个 Bot 聊天（即该行预览的同一会话），即使你为该 Bot 打开了其他标签页，那些标签页会保留在旁边。
  • 在标签栏中，Bot 聊天以 Bot 的名字作为标题，因此两个打开的 Bot 一眼就能区分。
• 正在运行（Active now）——花名册上方有一个状态栏，显示当前正在工作的每个 Bot：网关忙的配置，以及任何在最近 90 秒内写入过的 Bot。
  • 每个标签都会打开该 Bot 的聊天。
  • 该状态栏绝不会重新排列花名册，当所有 Bot 空闲时它会消失。
• 搜索——输入时即可过滤花名册。
• 隐藏 Bot——右键点击某一行 → 隐藏 Bot（Hide Bot），把一个你不用的 Bot 从花名册和“正在运行”状态栏中移除。
  • 隐藏只是显示层面的：@提及仍然生效，群聊成员资格不受影响，例行任务继续运行。
  • 一旦至少有一个 Bot 被隐藏，面板标题中就会出现一个眼睛开关——点击它以就地显示变暗的隐藏 Bot，然后右键 → 取消隐藏 Bot（Unhide Bot） 将其恢复。
  • 被隐藏的 Bot 永远不会弹通知，但它们会静默累积未读活动，眼睛徽章上会出现一个圆点，让你知道有事发生。
  • 隐藏状态保存在 Bot 的配置元数据中，因此它会跟随该 Bot 出现在连接到该后端的每个桌面端。

[!secondary] 规范的 Bot 聊天是永久聊天

在 Bot 的规范聊天中键入 /new（或 /reset）会把这段关系分叉成一个临时会话——这正是 Bot 模式承诺永远不会发生的事。

输入框（composer）会改道为 /compact：全新的工作上下文，同一个对话。

同一配置上的普通会话保留完整的 /new 自由度。

1.1. 将 Bot 组织到分区中

分区是你自己创建的文件夹——Clients（客户）、Team（团队），任何你觉得合适的名称——作为自动按网关分组之外的第二个维度。
未创建分区时，花名册就是它一直以来的普通列表。

• 创建分区——从面板的 + 菜单 → 新建分区（New section），或右键点击一个 Bot → 移动到分区（Move to section） → 新建分区…（创建时该 Bot 会被归入其中）。
• 归档 Bot——把它的行拖到某个分区上，悬停时目标会高亮，按 Esc 可取消拖拽；或者右键 → 移动到分区 并选择一个。
  从分区移除（Remove from section） 会把它放回 未分配（Unassigned）。
• 重命名、重新排序或删除分区——从标题的右键菜单（或悬停时出现的 ⋯）操作；双击标题可重命名。
  标题可以像网关标题一样折叠。
• 删除分区绝不会删除 Bot——它们会回到 未分配（Unassigned），toast 会提供 撤销（Undo）。
  不会询问确认。

成员关系存储在每个 Bot 的配置元数据（ui_meta）中，因此 Bot 的分区会跟随它出现在连接到该后端的每个桌面端。
当花名册显示多个网关时，分区会嵌套在每个网关的桶（bucket）内。

2. 创建 Bot

点击花名册中的 New Agent（新建代理）。
快捷路径只有三个字段——名称（Name）、标题（Title）、描述（Description）——Bot 在几秒钟内就存在了，并以它的新 Bot 聊天的第一条消息介绍自己。

Advanced（高级） 折叠面板会展开完整的能力面：

• 从现有配置克隆（Clone from an existing profile）——从另一个 Bot 的配置、技能、SOUL 和记忆开始，或选择 全新配置（Fresh profile） 从头开始。
• 创建空配置（Create empty）——完全跳过捆绑的技能，打造一个最小化配置。
• 模型与提供商固定（Model & provider pin）——给 Bot 指定自己的模型。
  Hermes 认识的任何提供商/模型组合都可用，不同的 Bot 可以并行运行在不同模型上。
  不设置则继承启动配置。
• 自定义 SOUL.md——Bot 的人设和常驻指令。
• 按技能、按工具集、按 MCP 服务器启用——精确勾选这个专家需要的所有能力。
• 共享密钥（Shared keys）——默认情况下，新 Bot 与主配置共享一个 OAuth/token 池，因此凭证刷新不会互相失效。
  （较旧的网关注入复制凭证——仍然可用，只是被分叉了。）

2.1. 选择它所在的机器（“Create on”）

当在 设置 → 连接 中注册了多个连接时，“New Agent”对话框会多出一个 在何处创建（Create on） 选择器。
选择一台设备，配置就会在那台机器的后端上创建——你的窗口绝不会切换网关。
然后这个新 Bot 会以“连接型 Bot（Connections Bot）”的身份出现在花名册中（当该名称在多个机器上存在时，使用 @名称-设备 句柄），与它聊天会路由到它自己的机器。

只有一个连接（常见情况）时，选择器会隐藏，Bot 会在你当前连接的机器上创建——与旧行为完全一致。

远程创建说明：

• **克隆来源（Clone source）**是目标机器的配置（其 default）——远程机器上没有你的本地配置可供克隆。
• 实时 Capabilities（能力） 标签页固定到目标机器的后端，因此你在创建期间配置的技能、工具和 MCP 服务器会落在 Bot 将驻留的机器上。
  （较旧的桌面版对远程目标回退到分阶段加载的技能/工具/MCP 检查清单；两者都读取目标机器的目录。）
• 取消对话框会丢弃草稿配置——无论它是在哪台机器上创建的。

编辑配置（Edit Profile）（右键点击一个 Bot）可以随时在实时配置上重新打开相同的界面：头像、标题、描述、模型固定、技能、工具集、MCP 服务器以及完整的 SOUL.md。

复制（Duplicate）（右键）会制作一个完整的 Bot 克隆——配置、技能、SOUL.md、记忆以及外观。
删除配置（Delete Profile） 会永久移除一个 Bot，并带有桌面端配置菜单使用的相同破坏性确认；默认配置不能被删除。

3. 头像

每个 Bot 都有一个面孔：

• Blob 脸（默认）——一种由 Bot 的名字确定性生成的软体脸：同样的名字，同样的脸，永远如此。
  当你在“New Agent”中键入名字时，脸会实时跟随；点击 Randomize（随机） 重新掷一次，Lock face（锁定面孔） 保留你喜欢的那张脸，即使名字改变也不变，或者固定六种剪影之一（圆形、有机形、盒形、凸块、云朵、太阳），其余部分仍然来自名字。
• 几何脸（Geometric faces）——经典的 7 种形状 × 10 种颜色，眼睛会眨动，在 Bot 工作时来回扫视。
• 上传的图片——任何你喜欢的图片。
• AI 生成的肖像——当配置了图像后端时，原地生成（这走标准的 image.generate RPC，在本地和远程网关上都能工作）。
• 像素宠物（pixel pet）——来自 petdex 画廊 的一个伙伴，在 Bot 忙碌时会在头像旁边蹦跳。
  在终端中运行 hermes pets 来探索画廊。

Bot 的外观、标题和描述存储在后端的配置元数据中，因此同一个 Bot 在连接到该后端的每个桌面端上都以相同方式显示。

4. 例行任务

Routines（例行任务） 面板把周期性任务附加到执行它们的 Bot 上——“每天早上总结我的收件箱”就紧挨着负责它的 Bot。
该面板只在 Bots 标签页激活时停靠在聊天旁边，当你切回 Sessions 时会自动让开（较旧的桌面版保持始终可见）。
一个结构化的日程选择器构建日程（先选频率，再选真正重要的细节），高级字段暴露原始的 Hermes 日程字符串。

例行任务就是普通的 Hermes cron 任务，命名空间为 [bot:<name>] <routine>——它们也会出现在 hermes cron list 和核心 Cron 页面中。
运行结果会落入 Bot 自己的聊天历史中，因此结果就在你本来就会与该 Bot 交谈的地方。

5. 群组与群聊

右键点击本地 Bot → 管理群组（Manage groups），将其加入或移出任意数量的群聊。
可独立选择现有群组，或就地创建一个。
本地成员关系存储在 Bot 的后端同步配置元数据中，因此它会跟随该配置跨桌面端；带有旧式单一群组的旧配置继续可用。
连接型 Bot 通过“新建群聊”选择器加入，并在房间的共享状态中保持来源限定（source-qualified）。

房间跟随你的网关，而不是某一台桌面端。
每个房间的近期记录、成员、图片和名称都会镜像到你的桌面端所连接的每个网关的共享配置元数据中，并带有按网关的版本控制，因此两个桌面端同时写入时会合并而不是互相覆盖。
在另一台机器上针对同一网关打开 Hermes Desktop（局域网、Tailscale、任何地方），房间就会连同其历史出现；仅限网关的客户端也能看到它。
房间带有持久的内部身份，因此重命名一个房间只会在所有地方改变其显示名称；解散一个房间会在每个客户端上永久移除它——即使是当时离线的客户端——而重建一个同名群组会开启一个真正全新的房间。
如果某个网关宕机或被移除，什么都不会丢失：每个已连接的桌面端都会在本地保留完整的房间，并在重新连接时重新播种任何网关。
（完整的编排日志留在每个桌面端的本地存储中；共享镜像是有限的最新历史投影。）

群组是与 Bot 私信相同的活动排序花名册中的独立行。
一个 Bot 即使属于多个群组也保持一个私信行，而每个群组都有自己的房间行，带有成员数、最新消息预览、时间戳和“需要你”（needs-you）状态。

在任意群组行（2–6 个 Bot）上打开聊天，会打开一个所有成员共同协作的共享房间：

• 你的消息最多触发三轮串行的成员回合。
  被 @提及的 Bot 会回复（没人被提及则所有人回复）；每个 Bot 要么简短回复，要么跳过，当一整轮都保持沉默时房间便安定下来。
• Bot 用 @name 互相拉入，并用 @user 把真正需要判断的请求升级给你——发生这种情况时，群组行会显示一个 需要你（needs you） 徽章。
• 硬上限（每次发送 10 条消息、3 轮）防止房间失控旋转。
• 每个成员都保留自己持久的 Group: <name> 会话，因此房间上下文像任何其他对话一样存续。
• 不是每个 Bot 都会回复每条消息。
  发言是每个成员自己的选择——Bot 只有在有新的内容要补充时才回复，否则跳过；而 @提及特定成员会把该轮限定在他们身上。
  预期你点名的成员（或任何有话说的人）发言，其余的人保持安静。
• 房间可以跨越机器。
  “新建群聊”选择器可以把来自任何已注册连接的 Bot 安排进来；每个成员的回合在自己的机器上、在它自己的 Group: <name> 会话中运行。
  跨机器成员在房间中和在其他成员记录中带有设备徽章（dixie · Mac Mini），消歧后的 @名称-设备 句柄在房间提及中可用——因此两台机器上同名代理绝不会混为一谈。

6. Bot 之间的消息传递

Bot 之间以署名方式互相发消息，你也可以从任何聊天中移交工作：

• @提及——在任何聊天中键入 @researcher 看一下这个，composer 的 @ 自动补全会帮你选对 Bot。
  发送时，该提及会对照实时花名册解析，并准确告诉活动 Bot 你指的是谁（配置文件、友好名称，以及跨连接 Bot 的设备）。
  然后该 Bot 自己撰写消息并通过 message_agent 发送——你的文本绝不会被原样转发，回复会以该代理的署名返回。
  邮箱地址或未知的 @ 会原样通过。
  其他已连接机器上的 Bot 可以用相同方式触达：桌面端通过该连接自己的套接字中继消息（见下文跨机器 Bot）。
• 重命名后的 Bot 保持标签同步——给 Bot 一个友好名称（其聊天标题中的铅笔图标，或 hermes profile rename），它就可以用该名称被 @提及：标题为 Research Buddy 的 Bot 会对 @research-buddy（和 @researchbuddy）响应，无论在普通聊天还是群组房间中都是如此。
  composer 的 @ 自动补全会提供重命名后的标签，并且在你键入旧配置名称时也会匹配，旧名称继续有效。
• 直接消息——每个 Bot 聊天都携带 message_agent 工具：一个 Bot 通过调用 message_agent(target="researcher", message="…") 给队友发消息。
  该工具会对照实时花名册验证目标，自动添加发送者的 Message from 🤖 <sender> (@<sender>): 署名前缀，并投递到队友的规范 Bot 聊天中。
  投递是即发即弃（fire-and-forget）的：发送者会收到一个确认，结束自己的回合，回复稍后作为后台完成通知到达。
  消息作为真实参数传输（不做任何 shell 解释——引号、$(...) 和反引号原样到达），并且 Bot 自己撰写消息而不是转发你的话。
  队友花名册——每个配置的标题/描述中的名称和角色——是每个 Bot 聊天系统提示的一部分，因此 Bot 在选择收件人之前就知道谁负责什么。
  该工具只存在于 Bot 模式管理的安装上的规范 Bot 聊天会话中；普通聊天、群组房间成员会话和 CLI 会话永远看不到它。

后端在提示构建时会自动把消息传递协议教给每个 Bot 的规范 Bot 聊天会话——包括当队友从 CLI 无头打开它时。
只有规范 Bot 聊天会获得协议部分；你的普通会话和 SOUL.md 保持不动。
这由 config.yaml 中的 agent.bot_mode_protocol 控制（默认：开）：

agent:
  bot_mode_protocol: true   # inject the bot-to-bot messaging protocol into canonical Bot Chats

[!secondary] 备注

Bot 之间的投递是按调用进行的：接收的 Bot 会在它下次运行时拾取消息。
在对话中途实时打断 Bot 是未来的工作。

6.1. 失败的回合安全重试

一次失败的投递回合最多重试一次，并且只在重试确实有帮助时才重试。
瞬时故障（目标运行时离线、投递超时、提供商速率限制或服务器错误）会以不变的方式重新运行同一个 Bot 聊天会话。
上下文溢出失败也会重新运行同一会话——重试的回合会在调用模型之前，通过标准上下文压缩流程压缩超限的记录，因此重试在原始回合失败的地方得以成功。
认证、配额和配置故障绝不会自动重试：第二次尝试无法修复它们，只会浪费配额，因此故障会立即呈现。
重试的回合绝不会开启新会话——你的 Bot 聊天历史和上下文保持完整。

6.2. 投递失败时：类型化原因

一次失败的 Bot 回合或中继投递会携带一个机器可读的 reason 代码，以及人类可读的错误文本，贯穿端到端：
目标网关对故障进行分类（provider_auth_or_access、provider_quota_limit、provider_rate_limit、provider_server_error、context_overflow、missing_config、model_unavailable、runtime_offline、queued_expired、delivery_timeout、target_busy、unknown），桌面端转发它，发送代理的完成通知在错误文本前带有 [reason: <code>] 标记。
调用代理可以根据代码分支——“重新登录” vs “稍后重试”——而不是解析提供商的叙述。
桌面端的“需要关注”徽章使用相同的代码。

6.3. 跨已连接机器消息传递（桌面端中继）

你在 设置 → 连接 中注册的每个网关——本地、远程 URL、SSH、Hermes Cloud、docker——都是桌面端保持打开的持久线路，Bot 模式自动使用这些线路进行消息传递。
无需额外设置：

• 花名册自动传播。
  桌面端运行时，它会定期告诉每个已连接的网关，其他连接上存在哪些代理。
  每个 Bot 聊天的队友花名册随后会列出它们（“其他已连接机器上的队友”），带有名称、角色以及它们所在的机器——并且当代理出现、消失或被重命名时，花名册会刷新（能力纪元）。
• message_agent 直接触达它们。
  你笔记本电脑上的 Bot 可以像本地队友一样用 message_agent(target="moxie", …) 给云代理发消息。
  如果同一句柄存在于多台机器上，用 target="moxie@<connection>" 消歧（工具的报错会告诉 Bot 准确形式）。
  投递经由桌面端：发送网关对消息排队，桌面端把它中继到目标连接的网关，目标 Bot 在其规范 Bot 聊天中运行一个回合，回复作为与本地私信相同的后台完成通知回到发送者。
• 桌面端是信使。
  当知道两个连接的桌面端运行时，跨连接投递即可工作（它持有套接字和凭证——网关永远不会看到彼此的认证）。
  如果桌面端在投递中途关闭，发送者的 Bot 会被告知回复没有到达，而不是被挂起。
  对于始终在线的、无需桌面端参与的机器对机器消息传递，请注册一个对等端（hermes peer，见下文）——两条路由并存。

6.4. 跨机器 Bot 主动发起的私信（hermes peer）

一台机器上的 Bot 可以给另一台机器的网关上的 Bot 发消息，无需任何桌面端参与。
把另一个网关注册为对等端（peer）（其 API 服务器 URL + API_SERVER_KEY）：

hermes peer add spark --url http://spark.lan:8377 --key <API_SERVER_KEY>
hermes peer list
hermes peer dm spark < /tmp/dm.txt        # message body from a file (nothing shell-interpreted)
hermes peer dm spark/researcher < /tmp/dm.txt   # named profile on a multiplexed peer
hermes peer run spark --idempotency-key ticket-123 < /tmp/long-task.txt
hermes peer status spark run_abc123
hermes peer stop spark run_abc123

hermes peer dm 通过对等端现有的 API 服务器投递到远程代理的规范 Bot 聊天，在那里运行一个代理回合，并在 stdout 上打印回复——这正是本地 hermes -p <bot> chat 命令的跨机器孪生。

peer dm 只用于简短查询和回执，因为它在回合结束前会持有一个 HTTP 连接。
对于长回合，peer run 会立即返回一个 run_id；用 peer status 轮询它。
该 run 继承规范 Bot 聊天的记录，稳定的 --idempotency-key 使重试返回原始 run 而不是启动重复工作。
用 peer stop 加上那个确切的 run ID 来打断它，而不会误伤其他回合。

一旦注册了对等端，教给每个 Bot 聊天（agent.bot_mode_protocol）的消息传递协议会自动包含对等端花名册，并且 message_agent 直接接受对等端目标——message_agent(target="spark/researcher", …)，或对等端主代理用 target="spark"——因此你的 Bot 会自己学到其他机器上存在队友以及如何触达它们。
注册或移除对等端会在下次消息时刷新每个 Bot 聊天的协议（能力纪元）。

要求：对等端机器运行 api_server 网关平台，并带有强 API_SERVER_KEY；可达性是你网络的事（LAN、Tailscale、VPN）。
该密钥是一种凭证，以 HERMES_PEER_<NAME>_KEY 的形式存在于 ~/.hermes/.env 中；对等端名称/URL 存在于 config.yaml 的 bot_peers 下。

[!secondary] 单向可达性（NAT）

跨网关链路是网关到网关的直接连接——桌面端是查看器，不是中继。
位于家庭 NAT 后面的网关可以向外拨号到公共对等端（笔记本 → VPS 可行），但反向没有入站路由（VPS → 家庭不可行），除非你的网络提供一条。
如果你的群聊跨越 NAT 边界，请把房间的权威放在每个参与者都能到达的主机上（通常是公共 VPS），或用 Tailscale/VPN 桥接网络。

7. 跨机器 Bot

当你在 设置 → 连接 中注册多个后端时——本地运行时、远程网关、SSH 主机、Hermes Cloud 实例——花名册会持久地显示每个已连接来源的 Bot：
SSH 来源会在远程机器上不产生任何进程的情况下被盘点，暂时不可达的机器会保留它们最后已知的行而不是消失。
当同一配置名称存在于多个来源时，句柄以 @名称-设备 消歧（例如 @research-homelab）。
一个 Bot 的聊天、会话、记忆和例行任务驻留在拥有该配置的机器上。

点击连接型 Bot 不会把你的窗口跳到那台机器上——留在你的聊天里并 @提及 它，把它安排进群聊，或者直接用 在何处创建（Create on） 选择器在它上面创建新代理。
云代理和本地代理以这种方式共享一个花名册：注册你的 Hermes Cloud 实例和你的桌面端（比如通过 Tailscale 或 SSH），它们的 Bot 就能互相发消息并坐在同一个房间里，每个代理的工作在自己机器上运行。
跨这些机器的 Bot 间私信会自动经过桌面端中继（见上文跨已连接机器消息传递）。

完整的多连接指南参见 将桌面端连接到多个 Hermes 实例。

8. 关闭 Bot 模式

Bot 模式是一个捆绑的桌面插件。
在 设置 → 插件 → Bots 中关闭它——花名册、Routines 面板和 composer 中间件会实时注销，无需重启。
无论怎样，你的配置、会话和 cron 任务都不受影响；Bot 模式从不拥有你的数据，它只是渲染它。

还有一个偏好设置，可以把规范的 Bot 聊天从常规侧边栏会话列表中隐藏，使它们只出现在 Bots 面板内。
（这使用核心的隐藏会话标志；在较旧的网关上，这些聊天只是保持可见。）

9. CLI 对等性

因为 Bot 就是配置，一切都有终端等价物：

底层原语参见 配置（Profiles），完整的 CLI 参考参见 配置命令（Profile Commands）。