SSH 项目与跨主机 Handoff

SSH 项目使用远程主机的文件系统和 shell。先验证普通 SSH 和远程 Codex 能运行，再连接桌面应用；本地安装成功不能证明远程环境已经准备好。

配置与验证 SSH

在运行桌面应用的机器上，为 ~/.ssh/config 添加具体 alias，例如：

Host devbox
  HostName devbox.example.com
  User you
  IdentityFile ~/.ssh/id_ed25519

替换主机和用户名，再用 ssh devbox 验证访问。Codex 通过 OpenSSH 解析具体 alias，忽略只有模式的 host 条目。

准备远程 Codex

在远程安装并认证 Codex，确保 codex 出现在远程用户 login shell 的 PATH。桌面应用会经 SSH 从该 shell 启动 App Server。

然后在 Settings > Connections 添加或启用 SSH host，选择远程项目目录。命令、读取与编辑在该主机完成，适用其依赖和安全策略。

跨主机交接聊天

目标主机必须已连接，并保存同一 Git 仓库的项目；若项目是仓库子目录，两端应保存相同子目录。只有匹配的项目才会作为目标出现。

在聊天底部选择运行位置与目标主机，检查目标和分支后 Hand off。Codex 在目标创建或复用 worktree，传递聊天及 Git 状态；正在运行的响应会先中断。

也可在另一聊天里请求交接指定聊天。发起请求的聊天不能交接自己，且该流程不支持交接到 Codex Cloud。Local 与 Worktree 之间的同主机移动见Worktrees。

网络暴露

SSH 工作流通过 SSH 管理 App Server，不要求把 App Server listener 暴露到公共网络。跨网络访问可使用 VPN 或 mesh 网络。若连接失败，先排查 SSH 密钥、远程 login shell 的 PATH、认证以及目标仓库权限，再检查应用设置。