连接机器

将本地工作和远程智能体放在同一个 Herdr 窗口中。SSH 机器只需保存一次，就能在它的工作区与 Local 之间切换，无需再开一个客户端。智能体列表汇总已连接的机器，让你看到工作在哪里运行，以及谁在等待回答。

每台机器保留自己的 Herdr 服务器、会话和进程。一台机器断线不会影响其他连接。

连接前的准备

你需要能够通过普通 SSH 访问远程机器。先验证：

ssh workbox

workbox 可以是 SSH 配置中的主机名，也可以使用 ssh://you@server:2222 这样的目标。

多机器连接支持 Linux 和 macOS 客户端，连接目标为 x86_64 或 aarch64 的 Linux 和 macOS 服务器。Windows 上的多机器连接尚未验证，也暂不受支持；独立连接命令 herdr --remote 仍支持 Windows。原生 Windows 服务器不能作为 SSH 目标。有关 SSH 配置、认证和自定义二进制文件，请参阅通过 SSH 远程连接。

添加机器

请在交互式终端中运行，以便 Herdr 在安装或替换内容之前询问：

herdr machine add workbox --label "Build machine"

这会使用远程默认会话。一个机器配置只对应一个远程会话，不会汇总该主机的所有会话。

如需命名会话，再添加可选的 --remote-session：

herdr machine add workbox --label "Build machine" --remote-session agents

Herdr 分别检查已安装的二进制文件和运行中的服务器，并在保存配置之前启动目标后台服务器。客户端和服务器版本只要兼容，就不必一致。未安装或不兼容时会进入需要批准的设置流程。如果必须替换运行中的服务器，会先询问是否停止它及其窗格进程，再启动兼容的服务器。默认回答为 No；同时需要安装和替换时，一次确认涵盖两项操作。machine add 不使用实验性的实时交接。取消或设置失败时，不会保存配置。

运行 herdr 打开 UI。如果本地客户端已经打开，新增或启用的机器通常会在一秒内出现并在后台连接，不改变当前选择。切换机器期间的配置变化会在切换完成后应用。设置结束后，远程服务器仍会运行。

切换机器

在侧边栏选择机器或其工作区。只有选中的机器接收窗格输入和终端尺寸，并提供可见的终端内容和图形。其他已连接机器仍会更新工作区信息、智能体状态和通知，但不传输窗格画面。

启动时会立即打开 Local，不等待 SSH 连接。一台机器无响应不会阻塞其他机器的输入。多个 Herdr 客户端也可以独立查看同一服务器上的不同标签页；共享标签页的尺寸规则见客户端与服务器。

断线后，最后的工作区和智能体状态仍然可见，但会变暗。这是缓存，不是实时状态。在新连接和对应画面到达前，不能输入或导航到这些缓存窗格。重连不会从正在使用的机器抢走选择。

重命名、禁用或移除

从列表读取配置 ID，不要根据标签或主机名推测：

herdr machine list
herdr machine rename <profile-id> --label "New name"
herdr machine disable <profile-id>
herdr machine enable <profile-id>
herdr machine remove <profile-id>

用于脚本时，可给 machine list 添加 --json。

重命名只修改显示标签，不会重连。禁用会保留配置供以后使用，移除则会忘记该配置。两者都只从客户端断开该机器，即使主机无法访问也可以操作；远程会话和智能体仍会运行。

移除或禁用正在查看的机器会返回 Local。如果 Local 不可用，Herdr 会显示该状态并重试连接，而不是选择其他远程机器。有已启用的保存机器时，即使 Local 失败或重启，客户端仍可继续使用。

连接问题

• Reconnecting： 网络中断、睡眠或 SSH 故障后，Herdr 会以有上限的退避间隔重试。SSH 连接会监测应用层活动并在空闲时探测，避免已断开的连接一直显示 Online。Local 使用本地连接关闭或失败来判断断线，而不是远程健康探测。
• Attention： 目标需要无法在后台完成的操作，例如批准主机密钥、认证或准备兼容服务器。其他机器仍可使用。
• 保存机器文件错误： 目录文件无法读取或内容无效时，当前连接保持不变。Herdr 会显示通知并自动重试读取。

后台连接不会回答提示，也不会安装、更新、重启或交接服务器。对于 Attention，请在交互式终端运行 Herdr 显示的独立设置命令，例如：

herdr --remote workbox

使用配置中的目标。如果添加时选择了命名会话，再加上可选的 --session <name>。完成批准提示后，重启客户端以重试 Attention 连接。不要仅因为版本与客户端不同就停止运行中的服务器。

认证失败时，先检查普通 SSH。对于有口令的私钥，请在启动 Herdr 的非交互式后台连接前用 ssh-add 加载。

设置与自动化

UI 默认使用客户端本地的主题、侧边栏设置和按键绑定。选中服务器公布的自定义命令和插件仍在那里运行。Herdr 不会将本地插件、配置、可执行文件或机密复制到 SSH 主机。远程缺少命令时会明确报错。编辑客户端设置后，使用 UI 中的 reload config；参见配置。

有多台机器时，默认智能体行会显示 machine token。已有的自定义行保持不变；需要机器标签时请显式加入 machine。侧边栏行布局还支持按机器标签设置条件颜色。

工作区、标签页、窗格 ID 和智能体名称仅在所属服务器内有效。两台机器可能都有 w1:p1 或名为 reviewer 的智能体。在 UI 中选择机器不会改变已有窗格中 CLI 命令的目标，它们仍使用继承的会话和 socket。远程自动化应在目标主机上针对目标会话执行命令，并在那里读取 ID。

更新与保存的数据

配置只保存不透明 ID、标签、SSH 目标、明确的远程会话名和启用状态。Herdr 不会将密码、私钥、智能体票据或 SSH 控制套接字存入机器目录。认证仍由 OpenSSH 处理。

客户端与服务器协商兼容性，不要求版本完全相同。保存机器的连接还需要服务器支持 surface_interest 和 health_check 能力。缺少这些能力的旧服务器，即使能独立连接，也会显示 Attention，直到明确更新。其他缺失的方法只禁用对应操作。

更新兼容客户端不会替换远程服务器或停止其智能体。需要新的服务器行为时，请明确更新该服务器。正常替换会在停止服务器及其窗格进程之前询问。

实时交接是实验性的，需要明确选择。独立设置过程中需要替换受支持的服务器时，可为 herdr --remote 显式添加 --handoff；正常连接或认证修复不需要它。有关重启和交接的选择，请参阅更新及会话状态与恢复。