连接机器

Preview build 2026-10-14-fbd2ae23927f, published from fbd2ae23927f. Stable docs remain at /docs/.

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

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

Herdr 会请求 SSH 压缩，以减少受限连接上的屏幕更新流量。这适用于较旧的兼容 Herdr 服务器，也不会改变按键或其他输入的传送方式。Herdr 的 -C 选项会覆盖 SSH 配置中的 Compression no。如果 SSH 通过外部 ControlMaster 复用现有连接，该连接会保留原来的压缩设置。

恢复 SSH 认证

在 Linux 和 macOS 上，启用 remote.manage_ssh_config=true 后，添加机器、侧边栏和 API 操作共享已批准的 OpenSSH 连接。运行 herdr machine status [<label-or-id>] [--json] 可进行新的非交互式检查。reachable 表示远程 Herdr 当前可用，不代表每个 TUI 都已连接。在终端运行 herdr machine reconnect <label-or-id> 完成原生 SSH 认证并验证已保存的机器；该命令不会安装或更新 Herdr。已打开的客户端会在 30 秒内重试，无需重启。点击 ! auth、! error 或失败后的重连状态，会显示包含最新错误及 CLI 命令的通知，不会打开认证弹窗。机器行其余部分仍用于展开或折叠。

共享连接使用 ControlPersist 600，表示空闲 10 分钟，并不表示 MFA 有效期。活动连接可以继续保持，但企业策略、SSH 服务器或网络可能更早终止连接。Windows 本地恢复尚未支持。未受管理的 SSH 连接由你负责认证；单独运行 ssh 不会授予 Herdr 批准，除非它使用共享 ControlPath。主机密钥检查不会放宽；未知或已更改的主机密钥仍显示为 Attention。

连接前的准备

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

ssh workbox

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

多机器连接支持 Linux、macOS 和 Windows 客户端，连接目标可以是 x86_64 或 aarch64 的 Linux/macOS 服务器，也可以是 x86_64 的 Windows 服务器。交互式设置可在确认后安装或更新完整的远程软件包；后台重连只查找已安装的软件包。有关 SSH 配置、认证和自定义二进制文件，请参阅通过 SSH 远程连接。

添加机器

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

herdr machine add workbox

在交互式终端中，Herdr 会发现运行中的会话：只有一个会话运行时自动选择；有多个时，可用 Up/Down 选择并按 Enter 确认。按 Esc 或 Ctrl+C 取消。查询成功但没有运行中的会话时，设置使用 default。未找到 Herdr 安装时，设置会提议为 default 安装。如果已安装的二进制文件无法报告会话，设置会报告错误；可传入 --remote-session <name> 明确选择会话。

默认会话在侧边栏中显示为 workbox，即去掉所有 user@ 前缀的 SSH 主机名。添加 --label "Build machine" 可选择其他名称。一个机器配置只对应一个远程会话，不会汇总该主机的所有会话。非交互式命令使用 default，除非提供 --remote-session。

要跳过发现并使用指定会话，请添加 --remote-session：

herdr machine add workbox --remote-session agents

未提供 --label 时，这台机器显示为 workbox/agents。如果默认名称已被占用，machine add 会要求你传入 --label。

在 Windows 服务器上，设置还会检查 SSH 用户拥有的 Herdr 进程所使用的可执行文件。它会先验证其能力再复用，因此即使 SSH 的 PATH 指向较旧的安装，也能使用兼容的运行中构建。

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

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

切换机器

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

点击任意机器旁的箭头，可以折叠或展开其工作区列表，而不切换当前工作区。机器正在重连时也可以操作。

键盘导航先按 prefix+w，再使用工作区导航键（默认为 Up/Down），按侧边栏顺序高亮已连接机器上的工作区。Enter 确认切换；Esc 或前缀键取消，不切换机器。紧凑和展开的侧边栏都会显示高亮行，包括折叠机器内的行。桌面导航在两端循环，移动端切换器在首尾停止。已断开的机器会被跳过。

高亮其他机器的工作区后，请先按 Enter 再使用其他键盘操作，避免误对当前机器执行窗格、标签页、工作区或自定义命令。点击会取消桌面上的远程键盘导航预览。展开的侧边栏会保留每台机器的 worktree 分组折叠状态。

启动时会立即打开 Local，不等待 SSH 连接。选择 Local 也会立即取消尚未完成的远程切换，无需等待远程响应。如果 Local 自身正在重连，会在就绪后继续选中它。收到 Local 的新画面和终端设置后即可输入。一台机器无响应不会阻塞其他机器的输入。多个 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： 目标需要认证、批准主机密钥或准备兼容服务器等操作。其他机器仍可使用。! auth 表示认证失败，! error 表示其他问题。点击徽章可查看错误和 CLI 命令。侧边栏折叠时两者都显示为 !。
• 保存机器文件错误： 目录文件无法读取或内容无效时，当前连接保持不变。Herdr 会显示通知并自动重试读取。

当两端都支持空闲桥接清理时，连接 Linux/macOS 的保存机器会在双向均无流量一分钟后关闭远程桥接。睡眠时间也计入期限，并在唤醒时检查。正常的空闲连接会交换健康检查，持续查看输出无需键盘输入。清理不会停止远程 Herdr 服务器、会话或窗格进程。旧安装仍可兼容连接，只是不使用这项可选清理功能。

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

herdr --remote workbox

使用配置中的目标。如果添加时选择了命名会话，再加上 --session <name>。完成设置后，已打开的客户端会自动重试。machine reconnect 不会安装或更新 Herdr。不要仅因为版本与客户端不同就停止运行中的服务器。

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

如需在远程窗格中进行 Git 认证或 SSH 签名，请在 SSH 配置中为可信主机启用 ForwardAgent yes。Herdr 不会替你启用转发。如果会话启动时带有智能体，更新后的 Linux 和 macOS 服务器会为窗格提供稳定的智能体地址，因此在 --remote 或已保存机器重新连接后，现有窗格和新窗格都能使用转发的智能体。可用的继承智能体或较早的连接优先于后续客户端和临时设置检查；如果它消失，另一个实时连接可以提供智能体。

这需要更新远程服务器，而不只是本地客户端。未带智能体启动的本地会话不会更改 SSH_AUTH_SOCK。在服务器更新前或会话首次获得智能体前创建的窗格会保留原来的环境，需要重新创建一次才能继承稳定地址。较旧的兼容服务器和未转发智能体的连接仍可正常连接。

设置与自动化

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

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

工作区、标签页、窗格 ID 和智能体名称仅在所属服务器内有效。两台机器可能都有 w1:p1 或名为 reviewer 的智能体。在 UI 中选择机器不会改变已有窗格中 CLI 命令的目标，它们仍使用继承的会话和 socket。远程自动化可使用 herdr --machine <label-or-id> agent list 获取 ID，并在后续操作中使用同一前缀。CLI 直接使用保存的 SSH 目标和会话，不需要打开 TUI。省略 --machine 时现有行为不变。支持的命令、更新要求和远程路径规则见 CLI 参考。

更新与保存的数据

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

Herdr 会另外记住每台机器的远程操作系统和解析后的可执行文件路径，让重复的 --machine 命令可以跳过发现。现有配置会在首次使用时补充缺失信息。该缓存是可选的：缓存文件缺失、无效或不可写都不会妨碍命令运行。命令仍会检查实时服务器兼容性。如果缓存的可执行文件不存在或不再支持 API 转发，Herdr 会在最初的只读检查期间重新发现它；对于可能已经更改远程状态的命令，Herdr 绝不会自动重试。

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

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

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