Codex App Remote SSH 实战:让 macOS 上的 OpenAI Codex 远程接管 Ubuntu 开发环境

我最近在折腾一套更接近真实生产环境的 AI Coding 工作流。

本机是 macOS。

项目代码、运行环境、依赖服务、代理出口，都在远程 Ubuntu 服务器上。

我希望达到的效果很明确：

在 macOS 上使用 Codex App 的图形化体验，但实际让 Codex 在远程 Ubuntu 上读代码、改代码、跑命令、访问 API。

这件事看起来只是“Remote SSH”。

真正配置起来，核心不是 SSH 本身，而是三件事的边界要非常清楚：

Codex App 在本机。

Codex CLI 在远程。

代理环境也必须在远程生效。

OpenAI 官方对 Remote connections 的定义也非常直接：Codex 可以通过 SSH 处理位于另一台机器上的项目，适合代码库、凭据、服务或构建环境都在远程主机上的场景。Codex App 会通过 SSH 启动远程 Codex app server，因此远程用户登录 shell 中必须能找到 codex 命令。

这就是本文的核心。

不是“把 Codex 装上”。

而是让 Codex App、SSH、远程 Linux 执行环境形成一个稳定闭环。

零、原汁原味：Codex是什么

Codex

One agent for everywhere you code

Codex is OpenAI’s coding agent for software development. ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. It can help you:

Write code: Describe what you want to build, and Codex generates code that matches your intent, adapting to your existing project structure and conventions.
Understand unfamiliar codebases: Codex can read and explain complex or legacy code, helping you grasp how teams organize systems.
Review code: Codex analyzes code to identify potential bugs, logic errors, and unhandled edge cases.
Debug and fix problems: When something breaks, Codex helps trace failures, diagnose root causes, and suggest targeted fixes.
Automate development tasks: Codex can run repetitive workflows such as refactoring, testing, migrations, and setup tasks so you can focus on higher-level engineering work.

一、先讲清楚：这套方案到底解决什么问题

很多人第一次使用 AI Coding 工具时，会默认在本机跑。

这在小项目里没问题。

但真实开发环境经常不是这样。

代码可能在远程服务器。

数据库、Redis、内部服务、Docker、GPU、编译链路，也可能都在远程服务器。

更麻烦的是，远程 Ubuntu 可能无法直接访问 OpenAI 的相关服务，需要通过代理出口访问。

这时候就不能只在 macOS 上配置代理。

因为 Codex 真正执行命令的地方，是远程 Ubuntu。

OpenAI 官方文档里有一句非常关键：Remote project threads 会在远程主机上运行命令、读取文件、写入变更。

所以这套方案的核心判断是：

Codex App 只是入口，远程 Ubuntu 才是执行现场。

也就是说：

macOS 负责 UI、会话入口、选择远程项目。

SSH 负责连接和启动远程 Codex 服务。

Ubuntu 负责项目文件、命令执行、Node/npm、Codex CLI、代理访问。

这就是我称之为“三位一体”的边界感。

二、三位一体的配置边界

这套配置可以分成三层。

1. macOS：Codex App 的控制端

macOS 上安装 Codex App。

它负责提供图形化交互界面。

你在 App 里选择远程 SSH Host，再选择远程 Linux 上的项目目录。

2. SSH：本机与远程之间的连接层

Codex App 不是凭空发现远程机器。

它读取本机的 ~/.ssh/config。

OpenAI 官方 Remote connections 文档明确要求：需要先把远程主机加入 SSH config，让 Codex 可以自动发现这个 Host；Codex 会从 ~/.ssh/config 读取具体的 Host alias，并通过 OpenSSH 解析。

3. Ubuntu：真正的执行层

Ubuntu 上必须安装 Codex CLI，并完成登录认证。

Codex CLI 是可以在终端运行的 coding agent，能够读取、修改并运行当前目录里的代码。官方 npm 安装方式是：

npm i -g @openai/codex

升级方式是：

npm i -g @openai/codex@latest

对本文这个场景来说，还要加一层：

Ubuntu 上的 codex 命令必须带代理环境变量启动。

否则 macOS App 能连上远程，但远程 Codex 访问 OpenAI 服务时仍然可能失败。

三、远程 Ubuntu：先安装 Node 和 npm

Codex CLI 当前可以通过 npm 安装，所以远程 Ubuntu 上要先准备 Node.js 和 npm。

我这里使用 nvm。

nvm 是 Node.js 的版本管理工具，按用户安装、按 shell 生效，支持 Unix、macOS、WSL 等 POSIX shell 环境。

npm 建议使用 Node version manager 来安装 Node.js 和 npm，因为直接使用系统安装器可能导致全局 npm 包权限问题。

在远程 Ubuntu 上执行：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

安装脚本会把 nvm 克隆到 ~/.nvm，并尝试向 ~/.bashrc、~/.bash_profile、~/.zshrc 或 ~/.profile 等 shell profile 文件写入加载逻辑。

如果你的远程 Ubuntu 使用 zsh，可以执行：

source ~/.zshrc

如果使用 bash，通常是：

source ~/.bashrc

或者重新打开一个 SSH 终端，让 shell 自动加载 nvm 配置。

然后安装 Node 22：

nvm install 22nvm use 22

验证版本：

node -vnpm -vnvm current

四、远程 Ubuntu：安装 Codex CLI

这里需要先把一个概念讲准确。远程 Ubuntu 上需要安装 Codex CLI。但在 Codex App Remote SSH 场景里，我们并不是手动在远程终端里长期运行一个 CLI 交互界面，而是让 macOS 上的 Codex App 通过 SSH 调用远程 Ubuntu 上的 codex 命令。这个 codex 命令来自 Codex CLI 的安装结果。Codex App 会借助它在远程主机上启动 remote Codex app server，然后在远程项目目录中读取文件、修改代码、执行命令。因此，远程 Ubuntu 的关键要求不是“装一个普通命令行工具就完事”，而是：codex 命令必须已经安装、已经完成认证，并且必须出现在远程 login shell 的 PATH 中。

node 和 npm 准备好后，在远程 Ubuntu 上安装 Codex CLI：

npm install -g @openai/codex@latest

首次基础安装命令是：

npm i -g @openai/codex

升级到最新版则使用：

npm i -g @openai/codex@latest

安装完成后检查：

codex --version

然后登录：

codex login --device-auth

这里建议使用 device auth。

原因很简单：

远程 Ubuntu 通常没有浏览器，或者浏览器回调地址无法从本地直接完成。

OpenAI 官方认证文档也明确提到：在远程或无头环境中，如果浏览器登录 UI 不可用，推荐使用 device code authentication，也就是直接运行：

codex login --device-auth

然后在浏览器中打开链接，登录并输入一次性 code。

这一步完成后，远程 Ubuntu 上的 Codex CLI 就具备了认证能力。

五、最关键的一步：给远程 Codex 包一层代理启动脚本

如果你的远程 Ubuntu 不能直接访问 OpenAI 服务，那么只安装 Codex CLI 还不够。

因为 Codex App 通过 SSH 到远程后，会在远程 shell 里启动 codex。

它启动的是远程机器上的 codex 命令。

所以代理必须在远程 codex 命令启动前就注入。

这里采用一个非常稳的办法：

写一个 codex-agent-proxy 包装脚本。

创建目录：

mkdir -p $HOME/.bin

编辑脚本：

vi ~/.bin/codex-agent-proxy

写入内容：

#!/bin/bashexport HTTP_PROXY=http://127.0.0.1:port1export HTTPS_PROXY=http://127.0.0.1:port1export http_proxy=http://127.0.0.1:port1export https_proxy=http://127.0.0.1:port1export ALL_PROXY=socks5://127.0.0.1:port2export all_proxy=socks5://127.0.0.1:port2exec $HOME/.nvm/versions/node/v22.22.0/bin/codex "$@"

赋予执行权限：

chmod +x ~/.bin/codex-agent-proxy

这段脚本做了三件事。

它把 HTTP / HTTPS 代理注入到当前进程环境。

它把 SOCKS 代理也注入到当前进程环境。

它用 exec 把当前 shell 进程替换成真正的 Codex CLI 进程。

这意味着：

Codex 不是在普通环境下启动，而是在已经带好代理变量的环境下启动。

这里有一个很重要的小细节。

我这里写死了路径：

$HOME/.nvm/versions/node/v22.22.0/bin/codex

在我当前的机器上是可用的。

但如果未来 Node 小版本变化，例如变成 v22.22.1，这个路径就可能失效。

更稳的写法可以是：

#!/bin/bashexport HTTP_PROXY=http://127.0.0.1:port1export HTTPS_PROXY=http://127.0.0.1:port1export http_proxy=http://127.0.0.1:port1export https_proxy=http://127.0.0.1:port1export ALL_PROXY=socks5://127.0.0.1:port2export all_proxy=socks5://127.0.0.1:port2export NVM_DIR="$HOME/.nvm"[ -s"$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"exec codex "$@"

不过，在 Remote SSH 场景里，我使用绝对路径是有原因的。

因为 OpenAI 官方 Remote connections 文档强调，Codex App 是通过 SSH 使用远程用户的 login shell 启动远程 Codex app server，必须确保 codex 命令在那个 shell 的 PATH 中可用。

而实际环境里，nvm 的 PATH 经常只在交互式 shell 里加载。

Codex App 通过 SSH 启动时，未必完全等同于你手动打开的终端环境。

所以：

写死绝对路径，稳定性更强。

动态加载 nvm，可维护性更好。

我自己的建议是：

生产环境优先稳定。

如果你当前验证通过，就先用绝对路径。

等后续要升级 Node 或迁移服务器时，再把脚本改成动态加载 nvm 的版本。

六、把系统里的 codex 命令切到代理脚本

写完包装脚本后，要确认当前系统到底会执行哪个 codex。

执行：

type -a codex

如果发现有多个路径，例如：

就要明确一个事实：

Codex App 通过 SSH 启动时，不一定会优先使用 nvm 里的 codex。

为了让它稳定走代理脚本，可以把 /usr/local/bin/codex 替换成指向包装脚本的软链接。

先备份原来的 codex：

sudo mv /usr/local/bin/codex /usr/local/bin/codex.bak

再创建软链接：

sudo ln -s /home/lzt/.bin/codex-agent-proxy /usr/local/bin/codex

验证：

which codextype -a codexcodex --version

这一步的本质是：

把远程 Ubuntu 上“系统优先找到的 codex 命令”，变成一个带代理环境变量的 Codex 启动入口。

注意：node 和 npm 的安装方式会影响全局包权限和路径，因此推荐使用版本管理器安装 node/npm。

而 npm 包本身如果提供 bin 命令，全局安装后通常会把命令链接到全局 bin 目录中。这个机制也解释了为什么你会看到 codex 出现在不同目录下。

这里最容易踩的坑是：

你在 SSH 终端里执行 codex 没问题。

但 Codex App 远程连接时仍然失败。

这通常说明：

手动 shell 的 PATH 和 Codex App 通过 SSH 启动时的 PATH 不一致。

所以本文这套 /usr/local/bin/codex -> $HOME/.bin/codex-agent-proxy 的方案，本质上是在消除 PATH 不确定性。

七、macOS 本机：配置 SSH Host

远程 Ubuntu 配好后，回到 macOS。

编辑本机 SSH 配置：

vi $HOME/.ssh/config

增加：

Host 212lzt    HostName 你的ubuntu服务器ip    User 你的ubuntu服务器用户名    Port 你的ubuntu服务器sshd端口号    IdentityFile ~/.ssh/id_rsa

SSH 客户端会按顺序读取命令行参数、用户配置文件 ~/.ssh/config、系统配置文件 /etc/ssh/ssh_config；配置文件使用 Host 段落匹配主机。

OpenAI Codex Remote connections 也使用了同样的结构：

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

并要求确认本机可以通过 SSH 连上该 Host。

测试：

ssh 212lzt

再进一步验证远程 codex 是否可见：

ssh 212lzt 'which codex; echo $PATH'

如果输出类似：

说明 Codex App 大概率也能通过 SSH 找到这个命令。

这一条验证非常关键。因为远程 host 上必须能在该登录 shell 的 PATH 中找到 codex 命令。

八、macOS 本机：开启 Codex App 的 Remote Connections

如果 Codex App 里还看不到 Remote Connections，需要打开配置文件：

vi ~/.codex/config.toml

写入：

[features]remote_connections = true

注意：如果 remote connections 没有出现，可以在 ~/.codex/config.toml 里启用这个 alpha feature flag（目前该功能还是Codex App的alpha版本）。

同时，Codex 的用户级配置位于：

~/.codex/config.toml

项目级配置可以放在仓库内的：

.codex/config.toml

并且 CLI 和 IDE extension 共享同一套配置层。

所以这个配置不是随便写的。

它属于 Codex 用户级配置。

打开 Codex App：

Settings

→ Connections

→ Add / Enable SSH Host

→ 选择 212lzt

→ 选择远程 Linux 上的项目目录

到这里，macOS Codex App 就可以通过 SSH 进入远程 Ubuntu 项目目录。

九、完整配置顺序：按这个走，小白也不容易乱

下面是我建议的最终执行顺序。

A. 远程 Ubuntu：安装 Node.js / npm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bashsource ~/.zshrc# orsource ~/.bashrcnvm install 22nvm use 22node-vnpm-v

B. 远程 Ubuntu：安装 Codex CLI

npm install -g @openai/codex@latestcodex --versioncodex login --device-auth

C. 远程 Ubuntu：创建代理包装脚本

mkdir -p $HOME/.binvi ~/.bin/codex-agent-proxy

写入：

#!/bin/bashexport HTTP_PROXY=http://127.0.0.1:port1export HTTPS_PROXY=http://127.0.0.1:port1export http_proxy=http://127.0.0.1:port1export https_proxy=http://127.0.0.1:port1export ALL_PROXY=socks5://127.0.0.1:port2export all_proxy=socks5://127.0.0.1:port2exec$HOME/.nvm/versions/node/v22.22.0/bin/codex "$@"

授权：

chmod+x ~/.bin/codex-agent-proxy

D. 远程 Ubuntu：把系统 codex 指向包装脚本

type -a codexsudo mv /usr/local/bin/codex /usr/local/bin/codex.baksudo ln -s /home/lzt/.bin/codex-agent-proxy /usr/local/bin/codexwhich codextype -a codexcodex --version

E. macOS 本机：配置 SSH Host

vi ~/.ssh/config

写入：

Host 212lztHostName 你的ubuntu服务器ipUser 你的ubuntu服务器用户名Port 你的ubuntu服务器sshd端口号IdentityFile ~/.ssh/id_rsa

测试：

ssh 212lztssh 212lzt 'which codex; echo $PATH'

F. macOS 本机：开启 Codex App Remote Connections

vi ~/.codex/config.toml

写入：

[features]remote_connections = true

然后打开 Codex App：

Settings

→ Connections

→ Add / Enable SSH Host

→ 212lzt

→ 选择远程项目目录

十、这套配置里真正重要的不是命令，而是执行链路

这套方案表面上看，是安装 Node、安装 Codex、配置 SSH、写代理脚本。

但真正的技术核心是：

让 Codex App 启动的那个远程 codex 命令，必然带着代理环境变量运行。

如果只在终端里临时执行：

export HTTPS_PROXY=http://127.0.0.1:port

然后再手动运行：

codex

这种方式只对当前 shell 有效。

Codex App 通过 SSH 再启动一个远程进程时，不一定继承你手动 shell 里的临时变量。

所以我更推荐包装脚本方案。

它把代理逻辑固定在 codex 命令入口上。

只要 App 调用的是 /usr/local/bin/codex，就必然进入代理脚本。

这比反复猜测 .bashrc、.zshrc、login shell、interactive shell 的加载顺序更稳。

十一、常见问题判断

1. SSH 能连，但 Codex App 找不到远程项目

先确认 macOS 本机是否能识别 Host：

ssh 212lzt

再确认 Host 写在 ~/.ssh/config，不是只靠命令行临时参数连接。

2. Codex App 能连远程，但发送任务失败

优先检查远程：

ssh 212lzt 'which codex; codex --version'

如果这里失败，说明 App 通过 SSH 启动时也大概率失败。

3. 手动 codex 正常，App 里不正常

这通常是 PATH 差异。

检查：

ssh 212lzt 'which codex; echo $PATH'

如果不是 /usr/local/bin/codex，或者没有走代理脚本，就需要重新检查软链接。

4. 登录失败或远程无浏览器

使用：

codex login --device-auth

注意：远程或无头环境优先使用 device code authentication。

5. 代理端口到底用 HTTP 还是 SOCKS

我上面的配置里：

HTTP_PROXY=http://127.0.0.1:port1HTTPS_PROXY=http://127.0.0.1:port1ALL_PROXY=socks5://127.0.0.1:port2

这是典型的双代理变量配置。

如果你的 v2ray / clash / sing-box 同时提供 HTTP 和 SOCKS 入口，这样写可以提高兼容性。

但前提是端口真实存在。

可以在远程 Ubuntu 上测试：

ss -lntp | grep -E 'port1|port2'

以及：

curl -I -x http://127.0.0.1:port1 https://api.openai.com

如果 HTTP 代理端口不通，就不要指望 Codex 靠这个端口访问成功。

十二、我的最终判断

这套配置的价值，不在于“能跑通一次”。

而在于它把 Codex Remote SSH 的几个关键边界固定住了。

macOS 上的 Codex App 负责交互。

OpenSSH 负责连接。

远程 Ubuntu 上的 Codex CLI 负责真实执行。

代理包装脚本负责保证远程 Codex 出口稳定。

这比在各种 shell 配置文件里反复追加 export HTTP_PROXY=... 更清晰，也更接近工程化配置的思路。

OpenAI 官方对 Remote connections 的设计，本质上就是让 Codex 去处理远程主机上的真实项目环境。

而本文这套方案补上的，是很多国内开发者都会遇到的一块现实拼图：

远程 Linux 需要代理访问 Codex API。

只要这个入口处理干净，Codex App + Remote SSH 就不再只是一个“能连上”的功能，而是一套可以长期使用的 AI Coding 远程开发工作流。