在许多工程实践中，编译依赖、大型数据集与执行环境通常托管在远程服务器中。根据官方文档《Remote Connections》（官方文档地址：https://learn.chatgpt.com/docs/remote-connections.md，核实日期：2026 年 10 月 25 日），ChatGPT 桌面客户端支持直接添加基于 SSH 协议的远程项目。连接建立后，对话将直接挂载到远程主机的文件系统与 Shell 环境中运行，覆盖执行终端命令、读取工程文件与写入代码变更的全流程。同时，远程主机必须遵循标准 SSH 安全基线：配置受信任的密钥对、遵循最小权限账户原则，并禁止暴露未授权的公共监听端口。
本指南基于官方技术规范，梳理从底层 SSH 设置到本地与远端主机之间会话交接（Hand off）的完整可复现步骤与边界条件。
步骤一：在本地 SSH 配置中定义具体 Host 别名
Codex 桌面端通过读取本地系统的 ~/.ssh/config 配置文件自动发现可用主机，并依托系统 OpenSSH 完成解析。此处存在一项明确的机制限制：Codex 仅识别具体的主机别名（concrete host aliases），会自动忽略仅包含通配符或模式匹配（pattern-only hosts）的配置块。
打开本地终端的 ~/.ssh/config，添加具有明确名称的具体主机定义：
Host devbox
HostName devbox.example.com
User you
IdentityFile ~/.ssh/id_ed25519
配置完成后，必须在运行桌面应用的本地机器上通过终端执行常规 SSH 连接测试，确保公钥认证顺畅且无多余交互阻碍：
ssh devbox
步骤二：远端安装认证 Codex 与检查登录 Shell 的 PATH
基础网络与密钥握手调通后，需要在目标远程主机上完成服务组件与运行环境准备：
- 在远端主机上安装并完成 Codex 的登录与授权认证。
- 检查关键环境变量：桌面应用连接远端时，会通过 SSH 启动远端用户的登录 Shell（login shell）以唤起后台服务。因此，必须确保
codex可执行命令已正确写入远端登录 Shell 读取的PATH路径中。若命令仅临时写入非登录交互式 Shell 环境，客户端发起连接时会报找不到服务错误。
步骤三：在桌面端关联连接并打开远程项目
远端环境就绪后，在桌面端完成项目载入：
- 启动 ChatGPT 桌面应用，点击进入
Settings > Connections。 - 在列表中找到由配置文件自动解析出的 SSH 主机别名（如
devbox），执行添加或启用操作。 - 选择远端主机上的目标代码文件夹以加载工程。
加载成功后，对话底部的执行位置会明确标识为远端主机，所有命令执行和文件读写均在远端环境独立完成。关于客户端界面的各项交互特性与本地协同体验，可以参阅Codex桌面端评测与上手解析。在需要高强度调用模型处理大型远程工程时，若需进一步扩展对话额度或升级套餐，可前往 PayForChat 套餐与充值中心 了解各级用量支持。
步骤四：主机间会话交接（Hand off）与限制条件
Codex 提供了会话交接（Hand off）功能，支持在本地电脑与已连接的远端主机之间双向迁移正在进行的对话上下文与其对应的 Git 状态。该模式适合在本地快速梳理构思，随后交接给远端开发机运行复杂验证，之后再带回本地继续完善。更多工程流演进也可参考Codex 实战技巧与配置指南。
执行会话交接需满足以下硬性条件与流转规则：
- 仓库与目录一致性：目标主机必须已建立连接，且已在目标主机上预先保存了指向同一个 Git 仓库的项目。如果项目属于仓库的某个子目录，则两端保存的子目录路径必须完全一致。若缺少匹配的已保存项目，目标主机不会出现在交接列表中。
- 界面操作流程：在桌面应用中打开需要迁移的对话，点击底部的当前运行位置（run location），在弹出的列表中选定目标主机（若从远程交接回本地，则选择“This computer”）。核对目标位置与分支信息后，点击“Hand off”。
- Worktree 与中断机制：Codex 会在目标主机上自动创建或复用一个 Git worktree，将对话及 Git 状态转移过去并切换运行环境。若触发交接时对话正在运行，系统会在转移前先中断（interrupt）当前的响应。
- 指令交接与云端限制：你可以在另一个对话中通过自然语言指示 Codex 将某个指定名称的对话交接到目标主机，但Codex 无法交接当前正在发起请求的这个对话自身。同时，Hand off 功能不支持交接到 Codex 云端环境（Codex cloud environment）。
常见问题解答
Q: 为什么在桌面端的 Connections 列表中无法识别 SSH 配置文件里的部分主机？
A: Codex 依托系统 OpenSSH 读取 ~/.ssh/config，但官方规范明确规定其仅识别具体的主机别名（concrete host aliases）。如果配置项使用了通配符或模式主机定义（例如 Host *.example.com），Codex 会自动忽略该配置段落。必须在配置文件中显式声明具体名称的 Host 块。
Q: 远程终端手动能运行 codex，为什么桌面端连入时依然无法启动远程服务？
A: 桌面应用通过 SSH 启动远端服务时调用的是远程用户的登录 Shell（login shell）。若 codex 安装路径仅写入了交互式非登录脚本中，登录 Shell 无法加载该路径。请检查远端用户的启动文件（如 .bash_profile 或对应登录 Shell 配置），确保 codex 所在目录已正确注入至 PATH。
Q: 为什么在对话底部点击交接（Hand off）时，看不到已连接的远程服务器？
A: Codex 仅在目标主机预先保存了匹配的 Git 项目时才会显示该选项。必须先在目标主机上打开并保存过与当前会话完全相同的 Git 仓库；若项目属于仓库子目录，两端保存的子目录相对路径也必须保持一致。
Q: 会话正在生成回复或执行终端命令时点击 Hand off 会怎样？官方是否保证状态绝不受损？
A: 本次取得的文档说明，运行中的会话会在转移前中断当前响应，再迁移会话与 Git 状态，并在目标主机创建或复用 worktree。这些材料不足以作出“状态绝不受损”的保证，也不能据此断言其他官方说明没有任何可靠性承诺。重要变更仍应保留可恢复记录，并核对交接后的状态。
Q: 是否可以在对话中直接让 Codex 把当前正在聊天的会话转移到远程服务器？
A: 不能。虽然支持在一个对话中通过指令交接另一个指定名称的会话，但官方限制禁止交接当前正在发起请求的会话本身。若要迁移当前对话，请直接在对话底部点击运行位置菜单手动操作。
Q: 能否将本地或 SSH 远程主机的项目会话直接 Hand off 交接到 Codex Cloud 云端沙盒？
A: 不能。官方文档明确说明，当前 Hand off 会话交接机制仅支持在本地设备与已通过 SSH 绑定的自建远程主机之间双向迁移，不支持交接到 Codex 云端环境（Codex cloud environment）。