Codex App SSH 远程开发配置指南
更新说明：本文基于 2026 年 5 月的 Codex App 版本撰写。SSH Remote 功能目前仍处于 alpha 阶段，配置方式和界面入口可能随版本更新发生变化。如果发现内容已过期，请参考官方文档获取最新信息。
Codex App 已经支持通过 SSH 连接远程机器，目前该功能处于 alpha 阶段。
对于需要在远程服务器上开发、训练模型、运行环境的人来说，这是一个值得尝试的功能。它能让你直接在 Codex 里连接远程服务器，在远程文件系统和 shell 中工作，不再需要在本地终端、VSCode Remote、SSH、tmux 之间来回切换。
一、这个功能适合谁？
以下场景可以重点关注：
- 本地写代码，服务器跑模型，需要连实验室或公司 GPU 服务器
- 后端项目依赖远程部署环境（代码、依赖、数据库、服务都在远程 devbox 上）
- 平时大量使用
ssh + tmux + vim或 VSCode Remote-SSH - 需要在多台机器之间切换开发环境
以往这类工作流通常是：
ssh devbox
cd project
tmux attach
# 然后手动编辑、运行脚本现在 Codex 开始将"远程开发环境"作为一等公民接入进来。
二、开启 SSH Remote 功能
目前该功能仍在 alpha 阶段，需要手动开启 feature flag。
编辑本地 Codex 配置文件 ~/.codex/config.toml，加入以下配置：
[features]
remote_control = true
remote_connections = true保存后重启 Codex App。
三、配置 SSH Host
官方推荐先将远程机器写入本地 SSH config，这样 Codex 可以自动发现已配置的 SSH Host。
编辑 ~/.ssh/config：
Host devbox
HostName your_server_ip_or_domain
User your_username
Port 22
IdentityFile ~/.ssh/id_ed25519配置完成后，先在本地终端验证连通性：
ssh devbox如果这里连不上，Codex 里大概率也连不上。请先排查：
- 网络是否可达（
ping或telnet测试端口） - 密钥是否正确（
ssh -v devbox查看详细日志） - 用户名和端口是否匹配
四、远程机器环境准备
Codex App 连接远程项目时，会通过 SSH 在远程机器上启动 Codex app server。因此远程机器上需要满足以下条件：
- 已安装 Codex —— 远程端也需要安装 Codex CLI
- 已完成认证 —— 远程端需要登录并授权
- PATH 可用 ——
codex命令在远程登录 shell 的 PATH 中可访问
SSH 到远程机器后进行检查：
which codex
codex --version如果 which codex 没有输出，说明远程 shell 找不到 Codex。常见原因和解决方法：
| 问题 | 解决方法 |
|---|---|
| Codex 未安装 | 参考官方安装文档进行安装 |
| 安装了但 PATH 找不到 | 检查 ~/.bashrc / ~/.zshrc / ~/.profile 中是否正确添加了 PATH，注意 SSH non-interactive shell 可能不会加载所有配置文件 |
| 权限问题 | 确认 Codex 二进制文件有执行权限（chmod +x） |
~/.bash_profile 或 ~/.profile，不会加载 ~/.bashrc。如果你的 PATH 配置写在 ~/.bashrc 里，可能需要在 ~/.bash_profile 中加入 source ~/.bashrc，或者直接将 PATH 写到 ~/.profile 中。五、在 Codex App 中添加远程项目
重启 Codex App 后，按以下步骤操作：
- 打开 Codex App
- 进入 Settings
- 找到 Connections（连接管理）
- 添加或启用已配置的 SSH Host
- 选择远程机器上的项目目录
- 创建或打开远程项目线程
完成配置后，Codex 的读文件、写文件、运行命令等操作都会直接在远程机器上执行。它不是简单地"查看远程代码"，而是在远程环境中完整工作。
六、常见问题排查
连接超时或失败
# 在本地终端逐步排查
ssh -v devbox # 查看 SSH 连接详细日志
ssh devbox "which codex" # 确认远程 PATH 是否正常
ssh devbox "codex --version" # 确认远程 Codex 可用远程 Codex 版本不兼容
Codex 的本地客户端和远程 server 端版本需要匹配。如果遇到版本不兼容的错误，尝试将两端都更新到最新版本。
连接后操作异常
- 确认远程机器的磁盘空间充足
- 确认远程 Codex 有权限访问目标项目目录
- 查看 Codex App 的日志输出（通常在
~/.codex/logs/目录下）
七、与 VSCode Remote-SSH 的对比
| 特性 | VSCode Remote-SSH | Codex SSH Remote |
|---|---|---|
| 成熟度 | 稳定，生产可用 | Alpha 阶段 |
| 编辑方式 | 本地 UI + 远程文件系统 | AI Agent 直接在远程执行 |
| 适用场景 | 需要手动编辑代码 | AI 辅助编码、批量操作 |
| 扩展支持 | 丰富的扩展生态 | 功能还在建设中 |
目前建议将 Codex SSH Remote 作为辅助工具使用，与现有开发流程配合，而非完全替代。
小结
Codex SSH Remote 功能虽然还在 alpha 阶段，但对于需要频繁在远程环境中使用 AI 辅助开发的场景来说，已经可以提升不少效率。核心配置步骤可以概括为：
- 本地
~/.codex/config.toml开启 feature flag ~/.ssh/config配置好 SSH Host- 远程机器安装 Codex 并确保 PATH 可用
- 在 Codex App 中添加连接并选择项目目录
配置过程中如果遇到问题，可以参考上方排查步骤逐一确认。
