SSH 工作树：把 Agent 放到远程机器

添加 SSH 目标

Settings → SSH → Add Target：

• 填 host、user、port、可选 identity file
• 或打开 OpenSSH config 选择器：搜索 ~/.ssh/config（含 Include 文件），挑一个主机预填表单；已保存的主机显示 In Orca 徽标
• 密钥带口令时首次连接会提示
• Test 验证连通后再 Save
• Host key 校验：默认策略下首次联系接受并记住主机与指纹；StrictHostKeyChecking yes 拒绝未知主机；密钥类型变化会在询问口令前被拒

高级连接选项

展开 Advanced Connection：

• proxy / jump host / SSH multiplexing 覆盖
• Reuse SSH connection 默认开（macOS/Linux 用 OpenSSH 连接复用），setup 命令不必每次重新握手；主机拒绝多路复用会话时关掉
• Passphrase 会话期内保存在内存，关 Orca 即清；可设更长 TTL

使用与状态

创建工作时在 Run on 里选 SSH 目标：远程建 worktree、远程跑 Agent、文件事件同步回本地。远程工作树显示实时状态 chip：绿=已连接、黄=重连中、红=断开。

• 断连不杀 Agent：Orca 重连并重挂，回放滚动输出、恢复全屏面板
• 跨 App 关闭：远程终端会话通过远程主机上的 relay 租约持有，笔记本关掉 Orca 也不会被杀；重开自动恢复到 attached 状态，滚动缓冲完整（默认 5 分钟宽限，可配置）

远程文件与编辑器

• 右键远程文件 Download / 远程文件夹 Download Folder（连接支持递归传输时，通常是完整 SFTP）
• 工作树菜单 Open in → VS Code：用 --remote ssh-remote+<host> <path> 交给 VS Code Remote-SSH
• Ports 标签（右栏，Cmd+Shift+I / Ctrl+Shift+I）做端口转发

两个常见坑

1. Linux 主机缺 C/C++ 工具链：首连时 Orca 会在远端装一个小 relay，远程终端需要原生 node-pty。缺 make / C++ 编译器 / python3 时，文件/git/编辑器仍可用，但远程终端不可用——装好构建工具再重连（Debian: sudo apt-get install -y build-essential python3）
2. FIDO2 / 安全密钥（ed25519-sk 等）：走系统 OpenSSH 而非内置 ssh2 客户端，以支持触摸/PIN 提示；GSSAPI 主机同理

落地练习：跑通第一个远程工作树

1. 在一台远程主机上确认 git 与你的 Agent CLI 已装
2. Settings → SSH 添加目标（从 config 导入或手填），Test 通过
3. 新建工作树，Run on 选该主机
4. 远程启动一个 Agent，观察状态 chip 与实时输出
5. 下载一个远程文件，验证文件事件同步

怎么判断做对了？——工作树创建时 git worktree 建在远端，Agent 在远端跑，本地 diff/编辑器照常工作。

卡住了怎么办？ 终端不可用：检查远端构建工具；断连后空白：确认 Reuse SSH connection / 租约机制，必要时查状态 chip。

小结

1. Settings → SSH 添加目标，支持 OpenSSH config 导入与 host key 校验
2. Run on 选主机：远端建 worktree、跑 Agent，本地渲染 UI
3. 断连不杀 Agent，App 关闭会话由远端 relay 租约持有
4. 文件下载、VS Code Remote-SSH、端口转发
5. 远端缺 C/C++ 工具链会禁用远程终端，装好重连

下一节，Remote Orca Servers 与 orca serve。