SSH worktree
DevAgent 可以通过 SSH 在远程机器上驱动 agent —— 这对于长时间运行的构建、GPU 主机，或任何你不适合在自己笔记本上运行任务的环境都很有用。
四种运行模式之一
SSH 只是将 agent 部署到远程算力的一种方式。关于本地、自托管服务器和临时 VM，参见 运行 DevAgent 的多种方式。
添加 SSH 目标
- 打开 设置 → SSH。
- 点击 Add Target。主机表单会在一个模态框中打开（而非在列表下方内联展开），因此即使主机列表很长，Host、Advanced 和 Save 也都能够到。编辑使用同一个对话框，并显示目标标签以及
user@host:port。 - 填写主机、用户、端口和可选的身份文件 —— 或者在同一对话框中打开 OpenSSH config 选择器来搜索
~/.ssh/config（包括Include引入的文件），选择一个主机并预填表单。已在 DevAgent 中保存的主机会显示 In DevAgent 徽标。当该流程可用时，你仍可从配置批量导入主机。 - 如果密钥有口令短语保护，DevAgent 会在首次连接时提示输入。
- 点击 Test 验证连通性，然后点 Save。
已修改（dirty）的添加/编辑表单会忽略外部点击，避免误点别处丢失你的字段；请用 Escape、Cancel 或 × 来放弃。
使用一个目标
创建 worktree 时，选择一个 SSH 目标而非 Local。DevAgent 将会：
- 在远程主机上创建 git worktree。
- 通过 SSH 连接在远程运行 agent。
- 同步文件事件，使编辑器、diff 和浏览器仍感觉像在本地。
高级连接选项
打开 设置 → SSH，编辑一个目标，当主机需要代理、跳板主机或 SSH 复用覆盖时展开 Advanced Connection。DevAgent 默认启用 Reuse SSH connection for faster setup，它在 macOS 和 Linux 上使用 OpenSSH 连接复用，这样设置命令就不必各自付出一次全新的 SSH 握手。仅当某主机的 SSH 策略拒绝复用会话时才关闭它。
口令短语
口令短语会在 DevAgent 会话的生命周期内保存在内存中。关闭 DevAgent 会清除它们。你可以在 SSH 设置中选择一个更长的 TTL。
状态
远程 worktree 会显示一个带实时 SSH 状态的 chip —— 绿色为已连接、黄色为重连中、红色为已断开。当某个 SSH 主机仍在连接时，DevAgent 可以从持久化的本地元数据列出工作区，这样在实时提供方就绪之前侧边栏不会为空；这些行会在连接稳定后刷新为权威的远程状态。断开连接不会杀死正在运行的 agent；DevAgent 会重连并重新挂接。当某主机掉线时，受影响的工作区卡片可显示一个内联的 Connect / 重连控件，让你无需打开终端浮层或翻找状态栏即可恢复。如果某个 SSH 中继以 "Multiplexer disposed" 之类的失败掉线，DevAgent 会自动恢复，而不会让 窗格 卡住直到你重启。Agent 状态（工作中 / 空闲 / 阻塞）会像在本地一样通过 SSH 传播，因此侧边栏和 Agents 动态流 会实时反映远程 agent。
应用关闭后的会话
关闭桌面应用不再杀死你的远程 PTY 会话。远程终端会话通过运行在远程主机上的中继进行租用，因此当你笔记本上的 DevAgent 关闭时它们仍然存活。当你重新打开应用并重连到目标时，被租用的 PTY 会以已挂接状态恢复到它们的标签页中，且滚动回放内容完好无损。一段短暂的宽限期（默认 5 分钟，可按目标配置）给中继留出时间以应对快速重连，然后再拆除已分离的会话。
下载远程文件和文件夹
在 SSH worktree 的文件浏览器中右键：
- File → Download —— 原生保存对话框；将文件复制到你的笔记本。
- Folder → Download Folder —— 递归下载到你选择的文件夹中（仅桌面端）。
DevAgent 使用与连接相同的 SSH 传输路径。仅当连接宣告支持递归文件夹传输时（通常是完整 SFTP）才会出现文件夹下载。停留在仅系统 OpenSSH 传输的连接仍可下载文件，但不会显示 Download Folder。
这是一个仅桌面端的操作 —— web 客户端不提供 Download，因为它依赖 Electron 的保存对话框。
在 VS Code 中打开远程工作区
对于 SSH worktree，当你配置的应用是 VS Code 或 VS Code Insiders（code / code-insiders，或指向这些启动器的直接路径）时，worktree 菜单的 Open in 列表可以把远程路径交给 VS Code Remote-SSH。
- 配置 设置 → 常规 → Open in menu，让 VS Code 出现在列表中（预设或自定义命令）。
- 右键点击 SSH worktree（或使用 worktree 溢出菜单）→ Open in → VS Code。
- DevAgent 会针对该主机和 worktree 路径启动 VS Code Remote-SSH（
--remote ssh-remote+<host> <path>）。该菜单项可能会显示一个 Remote SSH 徽标。
此远程路径不支持： Cursor、Zed、复合 shell 命令，或通过 Remote DevAgent Server 活动运行时打开（这些仍为 Local only）。Finder/Explorer 项仅用于本地路径。
Kerberos / GSSAPI
如果 OpenSSH 配置中的某个主机设置了 GSSAPIAuthentication yes，DevAgent 会为该目标优先选择系统 OpenSSH 传输（内置的 ssh2 客户端不支持 GSSAPI）。连接前请保持一张有效的 Kerberos 票据（kinit / 你组织的 SSO）。手动目标在为系统 SSH 配置后也可以启用 GSSAPI。
对于从配置导入的主机，你无需单独拨动一个 “Kerberos mode” 开关 —— 导入 / ssh -G 会把该标志一并带过来。
FIDO2 / 安全密钥
硬件支持的 OpenSSH 身份（ed25519-sk、ecdsa-sk，包括 agent 支持的安全密钥）也使用系统 OpenSSH，而非内置的 ssh2 客户端。DevAgent 会从你的身份文件中检测密钥类型，并把连接交给操作系统的 OpenSSH 二进制程序，这样触摸 / PIN 提示就能照常工作。普通的 Ed25519、ECDSA 和 RSA 密钥仍停留在内置传输上。如果机器上没有 OpenSSH，那些 FIDO2 目标在它被安装并加入 PATH（或位于 Windows/macOS/Linux 的常见位置）之前无法认证。
没有 C/C++ 工具链的 Linux 主机
首次连接时，DevAgent 会在远程安装一个小型中继。远程终端需要一个原生 node-pty 模块。Linux 软件包通常在主机上编译；macOS/Windows 中继使用预构建二进制。
如果远程缺少 make、C++ 编译器和 python3，DevAgent 仍会完成针对文件、git 和编辑器的连接，但在安装构建工具之前，远程终端将无法工作。DevAgent 可能给出的安装提示示例：
- Debian/Ubuntu：
sudo apt-get install -y build-essential python3 - Fedora/RHEL：
sudo dnf install -y make gcc gcc-c++ python3 - Alpine：
sudo apk add build-base python3 - Arch：
sudo pacman -S --needed base-devel python
安装好工具后重新连接，这样中继就能安装原生模块。
端口转发
对于远程 worktree，右侧边栏会显示一个 Ports 标签（用 Cmd+Shift+I 切换）。DevAgent 会扫描远程的 /proc/net/tcp，并在 Detected 下列出正在监听的端口 —— 一键即可把它们转发到你的笔记本。你也可以手动添加、编辑或移除转发。转发会在应用重启和 SSH 重连后保留，且特权远程端口会自动重映射到本地（例如远程 80 → 本地 10080）。