【Codex Remote】 Codex App通过SSH连接远程Linux开发环境

前言

很多开发项目、模型和依赖都部署在远程 Linux 服务器上，但我们又希望在本地使用 Codex App 的图形化界面进行开发。

Codex App 支持通过 SSH 连接远程主机，并直接对远程文件系统进行读写、执行 Shell 命令。如果远程服务器不能直接访问 OpenAI，还可以通过反向 SSH 隧道复用本地代理。

本文将完成以下配置：

1. 配置 SSH 免密登录。
2. 创建反向 SSH 隧道，将本地代理转发给远程服务器。
3. 在远程服务器上配置代理环境变量。
4. 安装、认证并验证 Codex CLI。
5. 在 Codex App 中添加 SSH 主机和远程项目。

本文以 macOS 作为本地端、Linux 作为远程端进行演示。Windows 上的配置思路基本相同，可以使用 PowerShell 或 Git Bash 执行对应命令。

---

一、准备工作

开始前，请确保已准备：

• 已安装 Codex App 的本地电脑。
• 一台可通过 SSH 访问的 Linux 服务器。
• 远程服务器上的普通用户账号。
• 本地已启动的 HTTP 代理，本文示例端口为 7890。
• 远程主机已安装 Codex CLI。

本文使用下列占位符，请替换为你自己的信息：

占位符	含义	本文示例值
<REMOTE_USER>	远程 Linux 用户名	mayu
<REMOTE_HOST>	远程服务器 IP 或域名	192.0.2.10
dev-server	SSH 主机别名，可自行修改	dev-server
7890	本地 HTTP 代理端口	7890
17890	远程隧道监听端口	17890

---

二、配置 SSH 连接与反向代理隧道

2.1 配置 SSH 免密登录

2.1.1 检查本地 SSH 密钥

在 macOS 终端中执行：

ls ~/.ssh

本文使用 RSA 密钥，对应的私钥和公钥文件通常为 id_rsa 和 id_rsa.pub。如果尚未生成密钥，可以执行：

ssh-keygen -t rsa -b 4096

2.1.2 复制公钥到远程服务器

ssh-copy-id -i ~/.ssh/id_rsa.pub <REMOTE_USER>@<REMOTE_HOST>

例如，假设远程用户名为 mayu，服务器 IP 为 192.0.2.10：

ssh-copy-id -i ~/.ssh/id_rsa.pub mayu@192.0.2.10

192.0.2.10 是用于文档示例的保留 IP，实际使用时请替换为你的服务器 IP 或域名。

按提示输入一次远程用户密码后，再次连接时就不需要重复输入密码了。Windows 用户可以在 Git Bash 中执行同样的命令。

验证连接：

ssh <REMOTE_USER>@<REMOTE_HOST>

具体示例：

ssh mayu@192.0.2.10

2.2 建立反向 SSH 代理隧道

2.2.1 验证本地代理

先确认本地代理能够访问 OpenAI API：

curl -I --proxy http://127.0.0.1:7890 https://api.openai.com/v1/models

2.2.2 配置 SSH Host

编辑本地 ~/.ssh/config：

# Codex App 连接远程服务器时使用
Host dev-server
    HostName <REMOTE_HOST>
    User <REMOTE_USER>
    Port 22
    IdentityFile ~/.ssh/id_rsa
    IdentitiesOnly yes
    ServerAliveInterval 30
    ServerAliveCountMax 3

# 反向代理隧道
Host dev-server-proxy
    HostName <REMOTE_HOST>
    User <REMOTE_USER>
    Port 22
    IdentityFile ~/.ssh/id_rsa
    IdentitiesOnly yes
    RemoteForward 17890 127.0.0.1:7890
    ExitOnForwardFailure yes
    ServerAliveInterval 30
    ServerAliveCountMax 3
    TCPKeepAlive yes

将用户名和主机地址替换后，完整示例如下：

# Codex App 连接远程服务器时使用
Host dev-server
    HostName 192.0.2.10
    User mayu
    Port 22
    IdentityFile ~/.ssh/id_rsa
    IdentitiesOnly yes
    ServerAliveInterval 30
    ServerAliveCountMax 3

# 反向代理隧道
Host dev-server-proxy
    HostName 192.0.2.10
    User mayu
    Port 22
    IdentityFile ~/.ssh/id_rsa
    IdentitiesOnly yes
    RemoteForward 17890 127.0.0.1:7890
    ExitOnForwardFailure yes
    ServerAliveInterval 30
    ServerAliveCountMax 3
    TCPKeepAlive yes

RemoteForward 17890 127.0.0.1:7890 表示：在远程服务器的 127.0.0.1:17890 上建立监听，收到的流量通过 SSH 隧道转发到本地电脑的 127.0.0.1:7890。

2.2.3 启动隧道

在本地终端执行：

ssh -NT dev-server-proxy

参数说明：

• -N：不执行远程命令，只做端口转发。
• -T：不分配伪终端。

该命令持续阻塞属于正常现象，不要关闭这个窗口。

如果希望重启后自动连接，macOS 可以使用 launchd 或 autossh 托管该命令；Windows 可以使用任务计划程序实现类似效果。

---

三、配置远程服务器代理

3.1 连接服务器

ssh dev-server

3.2 检查当前代理配置

env | grep -i proxy

3.3 配置登录 Shell 环境变量

编辑远程服务器的 ~/.profile：

vim ~/.profile

加入：

export HTTP_PROXY=http://127.0.0.1:17890
export HTTPS_PROXY=http://127.0.0.1:17890
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"

使配置立即生效：

source ~/.profile

如果存在 ~/.bash_profile，请确保登录 Shell 会加载 ~/.profile：

[ -f "$HOME/.profile" ] && . "$HOME/.profile"

Codex App 会通过 SSH 启动远程 Codex App Server，使用的是远程用户的登录 Shell。因此，代理环境变量和 PATH 都应在登录 Shell 中正确加载。

3.4 验证远程代理

env | grep -i proxy
ss -lnt | grep 17890
curl -I --proxy http://127.0.0.1:17890 https://api.openai.com/v1/models

如果 curl 返回与下面类似的结果，说明网络已经能够到达 OpenAI API：

HTTP/1.1 200 Connection established
HTTP/2 401

401 Unauthorized 在这里并不表示代理失败，只是该次请求没有携带 API 认证信息。

---

四、安装与认证远程 Codex

4.1 在远程主机上认证 Codex

官方推荐在远程主机上安装并认证 Codex。请先确认当前用户和 Codex 状态：

whoami
command -v codex
codex --version
codex login status

如果尚未登录，请在远程主机上按 Codex CLI 提示完成认证。完成后再次检查：

codex login status

安全提醒： ~/.codex/auth.json 可能包含敏感的登录凭据。不要将它提交到 Git、发布到博客或复制到不可信的服务器。优先在远程主机上独立完成登录。

4.1.1 复用本机 auth.json 认证（建议，远程 Codex CLI 无需重新登录）

如果远程主机由你信任并且仅由你控制，可以将本机已登录状态的 auth.json 复制到远程主机。远程 Codex CLI 读取到有效凭据后，通常无需再执行 codex login。但远程主机仍然必须安装 Codex CLI；auth.json 只是认证凭据，不能代替 CLI 程序。以下命令均在本地机器上执行。

1. 首先确认 SSH 别名可用，并检查实际登录用户：

ssh dev-server 'whoami'

2. 在远程用户的家目录中创建 ~/.codex，并将目录权限设置为 700：

ssh dev-server 'mkdir -p ~/.codex && chmod 700 ~/.codex'

3. 将本机认证文件复制到远程用户的 ~/.codex/ 目录：

scp "$HOME/.codex/auth.json" dev-server:~/.codex/auth.json

4. 将文件权限设置为 600，然后验证远程 Codex 的登录状态：

ssh dev-server 'chmod 600 ~/.codex/auth.json && whoami && codex login status'

上述三条核心命令也可以合并查看：

ssh dev-server 'mkdir -p ~/.codex && chmod 700 ~/.codex'
scp "$HOME/.codex/auth.json" dev-server:~/.codex/auth.json
ssh dev-server 'chmod 600 ~/.codex/auth.json && whoami && codex login status'

如果不使用 SSH 别名，等价命令如下，请将 <REMOTE_USER> 和 <REMOTE_HOST> 替换为真实值：

ssh <REMOTE_USER>@<REMOTE_HOST> 'mkdir -p ~/.codex && chmod 700 ~/.codex'
scp "$HOME/.codex/auth.json" <REMOTE_USER>@<REMOTE_HOST>:~/.codex/auth.json
ssh <REMOTE_USER>@<REMOTE_HOST> 'chmod 600 ~/.codex/auth.json && whoami && codex login status'

预期最后两行输出类似：

<REMOTE_USER>
Logged in using ChatGPT

关键点：认证文件必须放在实际运行 Codex 的 SSH 用户 家目录中。~ 由 SSH 登录用户解析；如果 SSH 配置中的 User 不正确，即使文件已复制，Codex 也可能无法读取它。
凭据安全： auth.json 相当于登录凭据。只能复制到你信任和控制的服务器，不要发给他人或提交到 Git。对于多人共享或安全性不确定的主机，应在远程主机上独立完成登录。

4.2 Codex App Server 无法读取认证时的解决方案

先直接运行 Codex：

codex

如果能够正常对话，可以跳过本节后续内容，直接阅读第五节。

4.2.1 错误现象

如果直接执行 codex 失败，但指定文件凭据存储方式后可以正常工作：

codex -c 'cli_auth_credentials_store="file"'

这说明 Codex App 自动执行 codex app-server 时，也可能无法读取当前认证。可以创建一个包装脚本，统一添加该配置。

4.2.2 确认 Codex 真实路径

readlink -f "$(command -v codex)"

例如：

/usr/lib/node_modules/@openai/codex/bin/codex.js

确认文件存在：

ls -l /usr/lib/node_modules/@openai/codex/bin/codex.js

4.2.3 创建包装脚本

mkdir -p ~/bin
vim ~/bin/codex

写入以下内容，其中 Codex 路径需替换为你的实际路径：

#!/bin/sh
exec /usr/lib/node_modules/@openai/codex/bin/codex.js \
  -c 'cli_auth_credentials_store="file"' "$@"

添加执行权限：

chmod 755 ~/bin/codex

4.2.4 让登录 Shell 优先使用包装脚本

在 ~/.bash_profile 中加入：

export PATH="$HOME/bin:$PATH"

加载配置：

source ~/.bash_profile

验证：

command -v codex
codex --version
codex login status
codex exec --skip-git-repo-check '只回复：连接正常'

command -v codex 应优先返回：

/home/<REMOTE_USER>/bin/codex

本文示例用户对应的路径为：

/home/mayu/bin/codex

---

五、在 Codex App 中添加 SSH 主机

5.1 添加远程连接

打开 Codex App，依次进入：

用户头像 -> 设置 -> 连接 -> SSH -> 添加

如果已经在 ~/.ssh/config 中配置了 dev-server，Codex App 可以自动发现该别名。也可以手动填写：

连接名：dev-server
主机：<REMOTE_USER>@<REMOTE_HOST>
SSH 端口：22
身份文件：~/.ssh/id_rsa

具体示例：

连接名：dev-server
主机：mayu@192.0.2.10
SSH 端口：22
身份文件：~/.ssh/id_rsa

设置 -> 连接 ->

SSH

-> 添加

5.2 打开远程项目

按照下列步骤操作：

新建项目 -> 远程 -> 选择远程主机 -> 选择项目目录 -> 添加项目

选择项目目录

添加项目

连接成功后，Codex 会在远程主机上读写项目文件并执行命令，而对话和变更审查仍然在本地 Codex App 中完成。

---

六、常见问题排查

6.1 远程服务器上没有 17890 监听端口

先检查本地执行 ssh -NT dev-server-proxy 的终端是否仍在运行，然后在远程主机执行：

ss -lnt | grep 17890

如果 SSH 提示端口转发被拒绝，需要检查远程 SSH Server 是否允许 TCP 转发。

6.2 终端中可以运行 codex，Codex App 却找不到

这通常是登录 Shell 的 PATH 没有加载安装目录导致的。使用下面的命令模拟登录 Shell：

ssh dev-server 'command -v codex && codex --version'

如果没有输出 Codex 路径，请检查 ~/.profile、~/.bash_profile 或当前 Shell 对应的启动文件。

6.3 curl 返回 401 Unauthorized

如果响应中已出现 HTTP/2 401，通常代表网络和 TLS 连接已经建立，只是本次测试未携带 API 密钥。接下来应检查 Codex 的登录状态，而不是继续修改代理。

6.4 隧道经常断开

可以先确认 SSH 配置中已加入：

ServerAliveInterval 30
ServerAliveCountMax 3
TCPKeepAlive yes

对长期运行场景，建议使用 autossh 或操作系统自带的任务托管机制。

6.5 安全注意事项

• 为远程开发创建独立的普通用户，避免直接使用 root。
• SSH 私钥应妥善保管，并设置合理的文件权限。
• 不要对公网暴露 Codex App Server 的传输端口。
• 不要在博客截图中泄露真实 IP、用户名、Token 或项目隐私信息。
• 反向隧道默认只绑定远程的回环地址，不要为了方便而改成公网监听。
• 只在信任的远程主机上安装和认证 Codex。

---

总结

Codex App 通过 SSH 连接远程 Linux 项目的关键，可以归纳为三点：

1. 本地电脑能够通过 SSH 别名连接远程主机。
2. 远程用户的登录 Shell 能找到已认证的 codex 命令。
3. 远程环境能够正常访问 OpenAI；如果无法直连，可以通过反向 SSH 隧道复用本地代理。

完成配置后，就能在本地 Codex App 中使用远程服务器的文件、依赖和计算资源，将图形化交互与远程开发环境结合起来。

参考资料

• OpenAI 官方文档：Remote connections

本文为个人学习笔记，如有错误，欢迎指正。