---
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="/zh-Hant/docs/codex/official/05-cloud-remote/18-cloud-runtime" description="另一類非本機執行入口：託管雲端" />
  <Card title="網路許可權" href="/zh-Hant/docs/codex/official/05-cloud-remote/19-network-permissions" description="遠端訪問外網時的邊界" />
  <Card title="App 設定" href="/zh-Hant/docs/codex/official/01-products/34-app-settings" description="Connections 面板入口在這裡" />
  <Card title="App 排障" href="/zh-Hant/docs/codex/official/01-products/41-app-troubleshoot" description="遠端連線失敗時的分層定位" />
  <Card title="Auth 認證" href="/zh-Hant/docs/codex/official/00-getting-started/02-auth" description="遠端 codex 也要走同一套登入" />
</Cards>
