企业官网建设流程全解析

Herdr 如何在一个窗口里管理多台 SSH 机器？machine add 到切换、禁用、删除全流程

【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdr

Herdr 的多机模式让你把 Local（本机会话）和若干台 SSH 机器放进同一个 Herdr 窗口：每台机器保留自己独立的 Herdr 服务器、会话和运行中的进程，互不干扰，某一台掉线不会牵连其他机器。本文按"添加 → 验证 → 切换 → 重命名/禁用/删除 → 处理连接问题"的顺序，给出文档中完整的操作流程。

适用环境：多机连接目前支持 Linux 和 macOS 客户端，连接 x86_64 或 aarch64 的 Linux 或 macOS 服务器。Windows 客户端尚未验证多机连接（独立的herdr --remote在 Windows 上仍可用）；原生 Windows 服务器不能作为 SSH 目标。

前提：先确认普通 SSH 可达

添加机器之前，先验证你对远程机器的普通 SSH 访问没有问题：

ssh workbox

workbox可以是 SSH config 里配置好的 Host 别名，也可以是ssh://you@server:2222这类目标。对重复使用的目标，建议写进 SSH config（文档示例）：

Host workbox HostName server.example.com User you Port 2222

用 machine add 添加机器

在交互式终端里运行 setup，这样 Herdr 在安装或替换任何东西之前都可以先征求你的确认：

herdr machine add workbox --label "Build machine"

该命令默认使用远程机的默认会话。一个机器 profile 只指向一个远程会话，不会把主机上所有会话都拉进来。要挂到命名会话上，加可选的--remote-session参数：

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

执行时 Herdr 会同时检查远程已安装的 binary 和正在运行的服务器，并在保存 profile 之前启动所请求的后台服务器。客户端和服务器的版本不要求一致，兼容即可。安装缺失或不兼容时会走基于审批的 setup；如果需要替换正在运行的服务器，setup 会在先停止它及其 pane 进程之前询问，默认答案是 No，安装和替换都缺省时一次确认即可覆盖。machine add不会启用实验性的 live handoff。setup 被取消或失败时，profile 不会被保存。

验证机器已添加

添加完成后运行herdr打开 UI 检查。如果本地已经有 Herdr 客户端开着，新添加并处于启用状态的机器通常在一秒内出现，并在后台连接，不会改变你当前的选择；进行中的机器切换会先完成，profile 变更才生效。远程服务器在 setup 退出后继续运行。

也可以用列表命令核对已保存的 profile，脚本场景可加--json：

herdr machine list

在侧边栏里切换机器和工作区

在侧边栏选择某台机器或它名下的工作区即可切换。被选中的机器接收你的 pane 输入和终端尺寸，并提供可见的终端内容与图形；其他已连接的机器不流式传输 pane 画面，但会持续更新各自的工作区信息、agent 状态和通知。

几个文档明确的行为边界：

• Local 在启动时立即打开，不等待 SSH 连接；某台机器卡住不会阻塞另一台机器的输入。
• 连接丢失后，最后一个工作区和 agent 状态仍会显示但变暗——那是缓存信息，不是实时状态。在新的连接和匹配的屏幕到来之前，对这些缓存 pane 的输入和导航保持禁用。
• 重连永远不会把选择权从你正在使用的机器上拿走。

重命名、禁用与删除

profile ID 必须从列表里读取，不要自己根据 label 或主机名推导：

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>

各命令的效果（文档原文语义）：

• rename：只改显示用的 label，不触发重连。
• disable：保留 profile 以便以后重新启用；enable恢复启用。
• remove：忘掉该 profile。
• 禁用和删除都只断开客户端到该机器的那条连接，远程机器上的会话和 agent 继续运行，即使主机不可达也是如此。

如果你删除或禁用的正好是当前正在查看的机器，客户端会回到 Local；Local 不可用时 Herdr 会明确提示并持续重试 Local 连接，而不是悄悄选一台别的远程机器顶上。在有已启用保存机器的情况下，即使 Local 失败或重启，客户端仍可用。

连接问题：Reconnecting 与 Attention

机器状态大致对应文档中的几类现象：

• Reconnecting：网络中断、休眠或 SSH 失败后，Herdr 按有界退避重试。SSH 连接会检查应用层活动并在静默时探测，坏掉的连接不会一直显示 Online。
• Attention：目标机器需要后台连接无法完成的动作，比如 host-key 审批、认证，或需要一台兼容的服务器。其他机器此时仍可正常使用。
• Saved-machine file error：目录文件不可读或非法时，现有连接保持不变，Herdr 给出提示并自动重试读取。

后台连接永远不会回答提示，也不会安装、更新、重启或交接服务器。出现 Attention 时，在交互式终端里运行 Herdr 打印出的独立 setup 命令，例如：

herdr --remote workbox

使用你 profile 对应的目标；如果添加时选了命名会话，这里也要带上--session <name>。跟随审批提示完成 setup 后，重启客户端重试 Attention 连接。认证失败时先按普通 SSH 排查；如果密钥带 passphrase，在启动 Herdr 的非交互式后台连接之前先用ssh-add把密钥加载进 agent。另外，不要仅因为版本不同就停止正在运行的服务器。

限制与保存数据边界

• 保存的 profile 只包含不透明 ID、label、SSH 目标、显式远程会话和启用状态；Herdr 不存储密码、私钥、agent ticket 或 SSH control socket，认证始终交给 OpenSSH。
• 客户端和服务器协商兼容性而不是要求版本一致。但已保存机器的连接额外要求服务器具备surface_interest和health_check能力；没有这些能力的旧服务器会一直显示 Attention，直到显式更新，即使独立 attach 能工作也一样。
• 更新兼容的客户端不会替换正在运行的远程服务器，也不会停止它的 agent；需要新的服务器端行为时要显式更新那台服务器。
• UI 使用客户端本地的主题、侧边栏设置和键位；Herdr 不会把本地命令插件、配置、可执行文件或密钥拷贝到 SSH 主机上，远程缺失的命令会显式失败。编辑客户端设置后用 UI 的reload config动作生效，参见 Configuration。
• workspace、tab、pane ID 和 agent 名都限定在单个服务器内，两台机器可以都有w1:p1或同名 agent；在 UI 里选择机器不会改变已有 pane 中 CLI 命令继承的会话与 socket，远程自动化应在目标主机上针对目标会话执行命令并在那里读取 ID。

下一步

需要单台远程机器的独立 attach（tmux 风格 SSH 后运行herdr、herdr --remote、命名远程会话、--handoff等）时，参见 Persistence and remote access；三种连接路径（本地、SSH 内运行、remote attach）的对比在 How to work with Herdr；各命令的完整列表见 CLI reference。

【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdr