Skip to content
实验室知识库

Codex 远程连接 SSH 使用教程

摘要

本文整理 Codex App 通过 SSH 连接远程主机的配置方法，适用于代码仓库、编译环境、凭据或服务主要位于远程服务器上的开发场景。Codex 远程连接目前仍属于 alpha 功能，需要在本地配置文件中手动启用；启用后，Codex App 可以通过 SSH 在远程文件系统和远程 shell 中启动线程、读取文件、运行命令并写入代码改动。

关键词

Codex, Codex App, SSH, remote connections, 远程开发, OpenSSH, app server, config.toml, 远程主机

正文

一、功能背景

Codex 远程连接的核心作用是：让本地 Codex App 操作远程服务器上的项目，而不是把项目同步到本地再开发。

适合使用的场景包括：

  • 项目仓库只放在远程开发机或实验室服务器上。
  • 依赖的 GPU、编译工具链、数据库、容器环境只在远程主机上可用。
  • 本地机器性能不足，只希望作为 Codex App 的交互入口。
  • 希望 Codex 的命令执行、文件读取和代码修改都发生在远程主机上。

需要注意的是，该功能仍处于 alpha 阶段，设置流程、可用性和支持环境可能随 Codex 版本变化。遇到问题时，应优先确认本地 Codex App、远程 Codex CLI、SSH 配置和认证状态是否一致。

二、前置条件

准备工作分为本地机器和远程主机两部分。

本地机器需要满足：

  • 已安装 Codex App。
  • 已配置可用的 OpenSSH 客户端。
  • 可以通过 ssh <HostAlias> 正常登录远程主机。
  • ~/.codex/config.toml 可以正常编辑。

远程主机需要满足：

  • 已安装 Codex CLI。
  • 远程用户的登录 shell 中可以找到 codex 命令。
  • Codex CLI 已完成认证，或已按你的模型服务商配置好 API 访问方式。
  • 项目目录对远程用户具有合适的读写权限。

社区反馈中提到，远程机 Codex CLI 版本建议不低于 0.121.0。如果功能入口存在但远程线程启动失败，建议先升级本地 App 和远程 CLI。

三、配置 SSH 主机别名

Codex App 会从本地 ~/.ssh/config 读取具体的 SSH host alias，并通过 OpenSSH 解析连接参数。因此建议先为远程主机配置一个稳定别名。

编辑本地 ~/.ssh/config：

Host devbox
    HostName devbox.example.com
    User <USERNAME>
    IdentityFile ~/.ssh/id_ed25519
    Port 22

配置说明：

字段 作用
Host 本地使用的连接别名，例如 devbox
HostName 远程主机域名或 IP 地址
User 远程登录用户
IdentityFile SSH 私钥路径
Port SSH 端口，默认是 22

完成后先在终端验证 SSH 是否可用：

ssh devbox

如果这里无法正常登录，应先修复 SSH 连接问题，再继续配置 Codex。

四、在远程主机安装并验证 Codex CLI

登录远程主机后，确认 codex 命令在远程用户的登录 shell 中可用：

which codex
codex --version

如果 which codex 没有输出，说明 Codex App 通过 SSH 启动远程 app server 时也很可能找不到 codex。需要把 Codex CLI 所在目录加入远程用户 shell 的 PATH，例如写入 ~/.bashrc、~/.zshrc 或系统环境配置。

然后在远程主机上单独运行一次 Codex CLI，确认认证和模型配置正常：

codex

如果远程 CLI 本身不能正常对话，Codex App 的远程连接通常也无法正常工作。

五、启用 Codex 远程连接功能

在运行 Codex App 的本地机器上，编辑 ~/.codex/config.toml，加入功能开关：

[features]
remote_connections = true

保存后重启 Codex App。正常情况下，可以在设置中看到 Settings > Connections 或类似的“连接”配置项。

Codex App Connections 设置页面

图 1：启用 remote_connections 后，Codex App 设置中的 Connections 页面会显示可用的 SSH 连接。

如果没有看到入口，按以下顺序检查：

  1. 确认 Codex App 已更新到较新版本。
  2. 确认修改的是本地机器的 ~/.codex/config.toml。
  3. 确认 TOML 语法没有错误。
  4. 完全退出并重新打开 Codex App。

六、在 Codex App 中添加远程项目

启用功能后，进入 Codex App：

  1. 打开 Settings > Connections。
  2. 添加或启用 SSH 主机，例如前面配置的 devbox。
  3. 选择远程主机上的项目文件夹。
  4. 在该远程目录中创建或打开 Codex thread。

远程 thread 的执行位置在远程主机上。也就是说，Codex 读取的是远程项目文件，运行的是远程 shell 命令，写入的也是远程文件系统。

可以让 Codex 在远程 thread 中执行以下命令验证位置：

hostname
pwd
whoami
git status --short

如果输出对应远程主机、远程项目目录和预期用户，说明远程连接基本正常。

七、第三方 API 或自定义模型服务配置

如果本地和远程都使用第三方 API 或自定义模型服务，需要分别确认本地 Codex App、远程 Codex CLI 都能单独工作。

一个常见配置思路如下，具体字段应以当前 Codex 版本和服务商要求为准：

model_provider = "custom"
model = "gpt-5.4"
disable_response_storage = true
model_reasoning_effort = "medium"

[model_providers.custom]
name = "custom"
wire_api = "responses"
base_url = "https://<PROVIDER_BASE_URL>"

如果服务商仍要求 OpenAI 形式的 API key，可以在 ~/.codex/auth.json 中使用占位符形式记录：

{
  "OPENAI_API_KEY": "<YOUR_API_KEY>"
}

安全注意事项：

  • 不要把真实 API key 写入公开文档、截图或仓库。
  • auth.json 应只允许当前用户读取，建议权限设置为 600。
  • 本地和远程如果都需要访问模型服务，应分别配置，不要假设本地配置会自动传到远程。

设置权限：

chmod 600 ~/.codex/auth.json

八、常见问题排查

1. 设置中没有 Connections 入口

可能原因：

  • 没有启用 [features] remote_connections = true。
  • Codex App 没有重启。
  • App 版本较旧。
  • 配置文件路径写错，尤其是在 Windows、WSL、多用户环境中。

处理方法：

[features]
remote_connections = true

保存后完全重启 Codex App，并确认使用的是当前系统用户的 ~/.codex/config.toml。

2. SSH 主机没有被识别

Codex 依赖本地 ~/.ssh/config 中的具体 host alias。只包含通配模式的配置可能被忽略。

建议保留明确的主机配置：

Host devbox
    HostName devbox.example.com
    User <USERNAME>
    IdentityFile ~/.ssh/id_ed25519

并用以下命令验证：

ssh devbox

3. 远程 thread 能创建但无法对话

可能原因：

  • 远程主机上找不到 codex 命令。
  • 远程 Codex CLI 没有完成认证。
  • 远程 shell 的 PATH 与交互式终端不同。
  • 自定义模型服务配置只在本地存在，远程没有配置。
  • API key、base URL 或 provider 名称不一致。

建议在远程主机执行：

which codex
codex --version
codex

如果远程 CLI 单独不可用，应先修复远程 CLI。

4. 提示 access token 无法刷新

社区反馈中有人遇到过类似报错：

Your access token could not be refreshed because you have since logged out or signed in to another account. Please sign in again.

排查方向：

  • 本地 App 与远程 CLI 是否登录了不同账号。
  • 本地和远程是否都使用了第三方 API，但 provider 配置不一致。
  • model_provider 是否在配置文件顶层正确指向已定义的 provider。
  • 是否误用了当前服务商不需要的认证字段。

如果使用自定义服务，建议先分别验证：

codex

本地和远程都能单独工作后，再测试远程连接。

5. API key 没有被远程 Codex 正确读取

社区经验中提到，某些组合下远程 Codex 可能没有按预期读取远程 ~/.codex/auth.json 中的 OPENAI_API_KEY。这种情况与系统、shell、Codex 版本或自定义服务配置有关。

建议排查：

  • ~/.codex/auth.json 是否位于远程用户家目录。
  • 文件权限是否正确。
  • 远程 shell 是否能读取相关环境变量或配置文件。
  • provider 配置中的 base_url、wire_api、认证要求是否与服务商一致。

九、安全建议

远程连接本质上会让 Codex 在远程主机上读取文件、执行命令和修改代码，应按照普通 SSH 远程开发的安全标准管理。

建议：

  • 使用 SSH key 登录，不要暴露密码登录。
  • 为 Codex 使用最小权限账户，不要直接使用 root。
  • 不要把未认证的 app server 监听器暴露到公网或共享网络。
  • 跨网络访问优先使用 VPN、Tailscale 等安全通道。
  • 项目中的密钥、Token、Cookie 和内部地址不要放入公开仓库。
  • 对远程改动保持 Git 版本管理，重要操作前先查看 git status --short。

十、回滚与关闭

如果需要关闭 Codex 远程连接功能，在本地 ~/.codex/config.toml 中删除或注释功能开关：

# [features]
# remote_connections = true

然后重启 Codex App。

如果需要撤销远程项目改动，应在远程项目目录中通过 Git 检查并按需回滚：

git status --short
git diff

谨慎使用破坏性命令。只有确认需要丢弃改动时，才执行对应的 Git 回滚操作。

参考文档

更新日期: 2026-05-06