Codex App 开启 SSH 远程开发：配置步骤、第三方 API 与常见报错
Codex App 内置的 SSH 远程开发能力默认关闭，需要在 config.toml 里打开 features 开关才会出现「连接」入口。本文整理开启步骤、设置里找不到菜单的排查思路、第三方 API 中转场景下的配置要点，以及连接远端后对话报错的常见原因与安全提醒。
Codex 除了命令行，还有桌面客户端。桌面端最近加入了一项默认隐藏的能力：通过 SSH 连接远端机器，直接在远端目录上创建会话、跑任务、看改动。开关不在图形界面里，而是藏在配置文件的 feature flag 后面，所以不少人升级了客户端也一直没发现。
这对两类场景比较有用：一是代码和依赖都在远端服务器或开发机上，本地只是操作入口；二是希望任务长时间挂在远端跑，不占用本地机器。下面把开启方式、踩坑点和分歧点整理成一份可操作的清单。
这个功能解决什么问题
开启后，桌面端会多出一个「连接 / Connections」设置项。你可以在里面登记远端主机（SSH 地址、端口、用户、密钥），把远端的某个目录挂到客户端里，然后在这个远程目录上新建会话。代码读取、命令执行都在远端完成，客户端主要承担界面、diff 展示和子任务状态查看。
和另外两种做法相比，它的定位是这样：
| 做法 | 特点 | 适合谁 |
|---|---|---|
| 桌面端 SSH 远程连接 | 有图形界面，看改动和子任务状态直观 | 想要 UI、又不想开 IDE 的人 |
| 编辑器插件远程开发 | 编辑器生态完整，调试链路成熟 | 本来就长期在编辑器里写代码的人 |
| 纯命令行 | 最轻量，脚本化方便 | 习惯终端、不需要可视化 diff 的人 |
| 对话中让模型自己 SSH | 不依赖 feature flag，粒度粗 | 只想临时在远端跑几条命令 |
开启步骤与检查清单
按顺序做，多数「设置里没有这个菜单」的问题都出在第 2 到第 4 步。
- 升级桌面客户端到最新版本，包括让后台更新真正装完，而不只是下载。
- 升级远端机器的 Codex CLI，在远端执行
codex --version，确认版本不低于 0.121。远端 CLI 才是真正干活的一端，版本太旧会连上但跑不起来。 - 编辑用户级配置文件：Linux / macOS 是
~/.codex/config.toml，Windows 是%USERPROFILE%\.codex\config.toml。加入：
[features]
remote_connections = true
- 完全退出客户端再启动。关窗口往往只是最小化到托盘，进程还在，配置不会重载。任务管理器或活动监视器里确认进程已结束后再打开。
- 进入设置，找到「连接」类目，添加远端主机与远程目录。
- 在远程目录下新建会话，先跑一条最简单的命令验证链路，再处理真实项目。
菜单还是不出来，按这几条查
- 配置文件位置写错：项目目录下也可能有
config.toml，但这里要改的是用户级的那一份。 - TOML 写坏了：
[features]表头下面缩进、拼写、重复表头都会导致整段被忽略。可以用任意 TOML 校验工具过一遍。 - 客户端与 CLI 只升级了一边：两边都要动。
- 平台更新节奏不同：Windows 与 macOS 客户端的版本推进并不完全同步，同一时间点可能一边有、一边还没有。遇到这种情况先确认自己客户端的具体版本号，再等更新，不要照搬别人的界面截图。
- 界面语言：中文界面下这一项叫「连接」，位置在设置里，不是主界面按钮。
社区里反馈在 26.415.40636 这个客户端版本上开启成功，但版本迭代很快，请以官方最新说明和实际界面为准。
第三方 API 与中转服务怎么配
这是讨论里分歧最大、也最容易卡住的部分。结论先说：远端连接和第三方 API 可以同时用，但要同时在本地和远端把 provider 配好，并且远端 CLI 必须能独立拿到可用的凭据。
远端机器的 ~/.codex/auth.json 里要有对应的 key：
{ "OPENAI_API_KEY": "替换为你的 key" }
然后在 config.toml 里定义 provider 并在文件靠前的位置指定当前使用的 provider：
model_provider = "MyProvider"
[model_providers.MyProvider]
name = "MyProvider"
base_url = "https://你的中转地址/v1"
env_key = "OPENAI_API_KEY"
两个容易翻车的细节：
model_provider是顶层键，必须写在任何[表名]之前。写在后面会被 TOML 解析成上一个表的字段，等于没设。- 部分 provider 定义里是否需要
requires_openai_auth之类的鉴权开关，各家中转要求不同，配错会表现为「CLI 单独跑正常、客户端连上去就报错」。
验证顺序建议固定下来：先在远端直接跑 codex 确认能对话，再在本地客户端直连确认能对话，最后才测远程连接。这样出问题时能立刻定位到是哪一层。
连上了但对话一直报错
讨论里出现频率最高的两类报错：
「access token 无法刷新 / 请重新登录」 通常是本地与远端登录了不同账号，或者客户端里残留的登录态与远端 CLI 的凭据不一致。处理办法：两边都清理登录态后重新认证，或者干脆统一改成 API key 模式，避免 OAuth 状态互相打架。
远端 CLI 单独可用，客户端发起对话就失败 表现为远端的 key 没有被正确带上。历史上确实存在过请求头在转发过程中丢失的问题，社区里有人通过在前面加一层不需要 api key 的 base_url 转发绕过去。这类做法能否奏效取决于你的中转实现，属于需要自行验证的范畴；更稳妥的顺序是先把客户端和 CLI 都升到最新、把配置精简到最小可用集合，再考虑加中间层。
如果反复失败，彻底清理一次 Codex 的本地配置目录再重配，往往比逐项猜要快。
安全与合规提醒
这个功能本质是让客户端通过 SSH 登录另一台机器。有几点必须说清楚：
- SSH 登录会在目标主机、跳板机和公司网络的审计日志里留下记录，不存在「连了但没痕迹」这回事。把它当成规避内部管理的工具，风险由自己承担。
- 不要共用账号或凭据，不要把生产环境的密钥放在随手可读的配置目录里。SSH 私钥权限收紧到仅本人可读，能不用密码登录就不用。
- 连接外部主机前，先确认公司安全策略是否允许，尤其是涉及代码外带的场景。
- 需要跨网络访问时，走企业提供的合规通道，不要自建穿透。
合规的替代思路是把开发环境本身放到可控的地方：由团队统一管理的远程开发机，或者按月租用的独享远程 Mac——整机在新加坡机房、远程连接使用、可长期在线，适合本地机器性能吃紧或需要让任务长时间挂着跑的场景，网络环境也相对稳定。选择哪一类，取决于你的合规边界和预算。
几个附带问题
- 修改代码也要逐个确认：沙箱与审批策略是两套配置，把只读类操作放开、仅对写入和执行保留确认，需要在配置里明确设置沙箱模式与审批策略，具体字段随版本变化，建议对照官方文档调整。
- 中文输入法导致界面卡顿：属于客户端层面的问题，和远程连接无关，先升级到最新版再观察，仍未解决可以向官方反馈。
- 想在手机上操作：桌面客户端本身没有移动端入口，社区里存在第三方远程控制面板类方案，接入前请自行评估其凭据管理与数据流向。
小结
这个功能的门槛不在使用，而在配置：客户端与远端 CLI 都要够新，[features] 开关要写在对的配置文件里，改完要真正重启进程。第三方 API 场景下，核心是让远端 CLI 能独立取到凭据，并把 model_provider 放在 TOML 的正确位置。遇到连不上、连上不能对话，按「远端 CLI → 本地客户端直连 → 远程连接」三层顺序逐段验证，比盲目改配置高效得多。
