---
title: "连接远程开发环境"
description: "SSH remote connections 当前处于 alpha。"
verifiedAt: "2026-05-07"
---

> [!NOTE]
> **这一篇用 8 分钟换什么**：把 SSH remote connections 从"远端跑命令"重新理解成**把执行机器换到 SSH host**——远端能读什么、能写什么、能连哪里，Codex 就影响哪里。读完后你会先用三条命令（`ssh devbox` / `command -v codex` / `codex --version`）做最小验证，再去碰 Codex 配置。

> [!WARNING]
> remote connections 是 alpha feature。安全配置应和正常 SSH access 同标准：trusted keys、最小权限账号、不暴露 unauthenticated public listener。

SSH remote connections 当前处于 alpha。

如果今天要启用，在 `~/.codex/config.toml` 的 `[features]` table 中设置：

```toml
remote_connections = true
```

availability、setup flows 和 supported environments 可能会随着 feature 改进而变化。

remote connections 让 Codex 可以处理位于另一台 SSH-accessible machine 上的 projects。

当你需要的 codebase、credentials、services 或 build environment 在 remote host 而不是 local machine 上时，可以使用它。

remote host 的安全配置应和正常 SSH access 保持同等标准：

- trusted keys。
- least-privilege accounts。
- 不暴露 unauthenticated public listeners。

## 什么时候应该用 remote connections

适合使用的场景：

- 项目只能在远端机器构建，例如依赖 Linux 服务、GPU、本地数据库或内网资源。
- 凭据只允许存在远端，不能复制到本机。
- 代码仓库很大，本机同步成本高。
- 团队已经有固定 devbox，希望 Codex 直接在同一环境中读写文件和跑命令。

不适合使用的场景：

- 只是想让 Codex 访问 GitHub 仓库。Cloud tasks 或本地 clone 通常更简单。
- 远端 SSH 权限过大，账号可以无约束改生产环境。
- 远端 shell 环境不可复现，`codex` 命令依赖交互式配置才可用。
- 需要把 app server 暴露到公网才能连上。官方建议走 SSH port forwarding、VPN 或 mesh networking。

先把远端当成“Codex 实际执行机器”来评估：它能读什么、能写什么、能连哪里，Codex 就可能影响哪里。

## Codex App

在 Codex app 中，你可以从 SSH host 添加 remote projects，并让 threads 针对 remote filesystem 和 shell 运行。

1. 把 host 添加到 SSH config，让 Codex 可以 auto-discover。

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

Codex 会从 `~/.ssh/config` 读取 concrete host aliases，通过 OpenSSH resolve，并忽略 pattern-only hosts。

2. 确认运行 Codex app 的这台机器可以 SSH 到该 host。

```bash
ssh devbox
```

3. 在 remote host 上安装并登录 Codex。

app 会通过 SSH 启动 remote Codex app server，使用 remote user's login shell。

请确认 remote host 的该 shell 中，`codex` command 在 `PATH` 内可用。

4. 在 Codex app 中打开 **Settings > Connections**，添加或启用 SSH host，然后选择 remote project folder。

如果 remote connections 还没有出现，请在 `~/.codex/config.toml` 中启用 alpha feature flag：

```toml
[features]
remote_connections = true
```

remote project threads 会在 remote host 上运行 commands、读取 files，并写入 changes。

截图：

- light mode：[https://developers.openai.com/images/codex/app/remote-connections-light.webp](https://developers.openai.com/images/codex/app/remote-connections-light.webp)
- dark mode：[https://developers.openai.com/images/codex/app/remote-connections-dark.webp](https://developers.openai.com/images/codex/app/remote-connections-dark.webp)

## 启用前检查

连接失败多数不是 Codex 本身问题，而是 SSH、PATH 或远端登录态问题。先用命令行做最小检查：

```bash
ssh devbox
command -v codex
codex --version
```

如果 `ssh devbox` 能进，但 `command -v codex` 找不到，说明 Codex app 通过 login shell 启动 remote app server 时也大概率找不到 `codex`。修法是在远端用户的 login shell 初始化文件里补 PATH，或用官方安装方式重新安装 Codex。

`~/.ssh/config` 中要使用 concrete host alias：

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

Codex 会忽略 pattern-only host。也就是说，`Host *` 这类通用段可以提供默认值，但不能作为可选择的远程连接入口。

## 常见故障

| 现象 | 优先检查 |
| --- | --- |
| Settings 中看不到 remote connections | `~/.codex/config.toml` 是否启用 `[features] remote_connections = true`，并重启 app。 |
| 看不到某个 SSH host | `~/.ssh/config` 是否有 concrete alias，OpenSSH 是否能 resolve。 |
| 连接后远端启动失败 | 远端 login shell 下 `codex` 是否在 `PATH`。 |
| 命令运行位置不对 | 确认选择的是 remote project folder，而不是本机 project。 |
| 本地文件没变化 | remote project threads 在远端读写文件，本地 clone 不会自动同步。 |
| 安全审查不清楚 | 用最小权限账号，限制远端凭据和网络访问，避免把生产账号直接暴露给日常开发线程。 |

排查时不要一开始就改 Codex 配置。先把 `ssh devbox`、远端 `codex --version`、远端项目路径这三件事跑通。

## 认证和网络暴露

使用 SSH port forwarding，并配合 local-host WebSocket listeners。

不要在 shared 或 public network 上暴露 unauthenticated app-server listener。

如果你需要访问当前 network 之外的 remote machine，请使用 VPN 或 Tailscale 这类 mesh networking tool，而不是把 app server 直接暴露到 internet。

## 团队使用边界

团队启用 remote connections 时，最好把环境责任分清：

- SSH host 命名、账号权限和密钥轮换由运维或仓库维护者负责。
- 远端 Codex 安装、版本更新和 PATH 由 devbox bootstrap 脚本负责。
- 项目级 instructions、rules、skills 继续放在仓库中，让本地和远端行为一致。
- 不把生产数据库、生产密钥直接放进日常 Codex 远程开发账号。

远程连接本身不是部署系统。它只是让 Codex 把执行位置切到 SSH host。最终发布仍应经过仓库 CI、PR review、deployment gate 或现有上线流程。

## 官方资料

- [Remote connections](https://developers.openai.com/codex/remote-connections)
- [Codex app settings](https://developers.openai.com/codex/app/settings)
- [Command line options](https://developers.openai.com/codex/cli/reference)
- [Authentication](https://developers.openai.com/codex/auth)

## 接下来去哪

<Cards>
  <Card title="Cloud 运行时" href="/docs/codex/official/05-cloud-remote/18-cloud-runtime" description="另一类非本机执行入口：托管云端" />
  <Card title="网络权限" href="/docs/codex/official/05-cloud-remote/19-network-permissions" description="远端访问外网时的边界" />
  <Card title="App 设置" href="/docs/codex/official/01-products/34-app-settings" description="Connections 面板入口在这里" />
  <Card title="App 排障" href="/docs/codex/official/01-products/41-app-troubleshoot" description="远端连接失败时的分层定位" />
  <Card title="Auth 认证" href="/docs/codex/official/00-getting-started/02-auth" description="远端 codex 也要走同一套登录" />
</Cards>
