连接远程开发环境
SSH remote connections 当前处于 alpha。
这一篇用 8 分钟换什么：把 SSH remote connections 从"远端跑命令"重新理解成把执行机器换到 SSH host——远端能读什么、能写什么、能连哪里，Codex 就影响哪里。读完后你会先用三条命令（ssh devbox / command -v codex / codex --version）做最小验证，再去碰 Codex 配置。
remote connections 是 alpha feature。安全配置应和正常 SSH access 同标准：trusted keys、最小权限账号、不暴露 unauthenticated public listener。
SSH remote connections 当前处于 alpha。
如果今天要启用，在 ~/.codex/config.toml 的 [features] table 中设置：
remote_connections = trueavailability、setup flows 和 supported environments 可能会随着 feature 改进而变化。
remote connections 让 Codex 可以处理位于另一台 SSH-accessible machine 上的 projects。
当你需要的 codebase、credentials、services 或 build environment 在 remote host 而不是 local machine 上时，可以使用它。
remote host 的安全配置应和正常 SSH access 保持同等标准：
- trusted keys。
- least-privilege accounts。
- 不暴露 unauthenticated public listeners。
什么时候应该用 remote connections
适合使用的场景：
- 项目只能在远端机器构建，例如依赖 Linux 服务、GPU、本地数据库或内网资源。
- 凭据只允许存在远端，不能复制到本机。
- 代码仓库很大，本机同步成本高。
- 团队已经有固定 devbox，希望 Codex 直接在同一环境中读写文件和跑命令。
不适合使用的场景：
- 只是想让 Codex 访问 GitHub 仓库。Cloud tasks 或本地 clone 通常更简单。
- 远端 SSH 权限过大，账号可以无约束改生产环境。
- 远端 shell 环境不可复现，
codex命令依赖交互式配置才可用。 - 需要把 app server 暴露到公网才能连上。官方建议走 SSH port forwarding、VPN 或 mesh networking。
先把远端当成“Codex 实际执行机器”来评估：它能读什么、能写什么、能连哪里，Codex 就可能影响哪里。
Codex App
在 Codex app 中，你可以从 SSH host 添加 remote projects，并让 threads 针对 remote filesystem 和 shell 运行。
- 把 host 添加到 SSH config，让 Codex 可以 auto-discover。
Host devbox
HostName devbox.example.com
User you
IdentityFile ~/.ssh/id_ed25519Codex 会从 ~/.ssh/config 读取 concrete host aliases，通过 OpenSSH resolve，并忽略 pattern-only hosts。
- 确认运行 Codex app 的这台机器可以 SSH 到该 host。
ssh devbox- 在 remote host 上安装并登录 Codex。
app 会通过 SSH 启动 remote Codex app server，使用 remote user's login shell。
请确认 remote host 的该 shell 中，codex command 在 PATH 内可用。
- 在 Codex app 中打开 Settings > Connections，添加或启用 SSH host，然后选择 remote project folder。
如果 remote connections 还没有出现，请在 ~/.codex/config.toml 中启用 alpha feature flag：
[features]
remote_connections = trueremote project threads 会在 remote host 上运行 commands、读取 files，并写入 changes。
截图：
- light mode：https://developers.openai.com/images/codex/app/remote-connections-light.webp
- dark mode：https://developers.openai.com/images/codex/app/remote-connections-dark.webp
启用前检查
连接失败多数不是 Codex 本身问题，而是 SSH、PATH 或远端登录态问题。先用命令行做最小检查：
ssh devbox
command -v codex
codex --version如果 ssh devbox 能进，但 command -v codex 找不到，说明 Codex app 通过 login shell 启动 remote app server 时也大概率找不到 codex。修法是在远端用户的 login shell 初始化文件里补 PATH，或用官方安装方式重新安装 Codex。
~/.ssh/config 中要使用 concrete host alias：
Host devbox
HostName devbox.example.com
User you
IdentityFile ~/.ssh/id_ed25519Codex 会忽略 pattern-only host。也就是说，Host * 这类通用段可以提供默认值，但不能作为可选择的远程连接入口。
常见故障
| 现象 | 优先检查 |
|---|---|
| Settings 中看不到 remote connections | ~/.codex/config.toml 是否启用 [features] remote_connections = true，并重启 app。 |
| 看不到某个 SSH host | ~/.ssh/config 是否有 concrete alias，OpenSSH 是否能 resolve。 |
| 连接后远端启动失败 | 远端 login shell 下 codex 是否在 PATH。 |
| 命令运行位置不对 | 确认选择的是 remote project folder，而不是本机 project。 |
| 本地文件没变化 | remote project threads 在远端读写文件，本地 clone 不会自动同步。 |
| 安全审查不清楚 | 用最小权限账号，限制远端凭据和网络访问，避免把生产账号直接暴露给日常开发线程。 |
排查时不要一开始就改 Codex 配置。先把 ssh devbox、远端 codex --version、远端项目路径这三件事跑通。
认证和网络暴露
使用 SSH port forwarding，并配合 local-host WebSocket listeners。
不要在 shared 或 public network 上暴露 unauthenticated app-server listener。
如果你需要访问当前 network 之外的 remote machine，请使用 VPN 或 Tailscale 这类 mesh networking tool，而不是把 app server 直接暴露到 internet。
团队使用边界
团队启用 remote connections 时，最好把环境责任分清：
- SSH host 命名、账号权限和密钥轮换由运维或仓库维护者负责。
- 远端 Codex 安装、版本更新和 PATH 由 devbox bootstrap 脚本负责。
- 项目级 instructions、rules、skills 继续放在仓库中，让本地和远端行为一致。
- 不把生产数据库、生产密钥直接放进日常 Codex 远程开发账号。
远程连接本身不是部署系统。它只是让 Codex 把执行位置切到 SSH host。最终发布仍应经过仓库 CI、PR review、deployment gate 或现有上线流程。