---
title: "連線 Codex App Server"
description: "理解 Codex App Server 適合遠端 TUI 和富客戶端整合，不要把它誤用成普通 CI 自動化入口。"
verifiedAt: "2026-05-07"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

Codex App Server 是更底層的服務介面，適合遠端 TUI、自研富客戶端和需要即時事件流的整合。它不是新手自動化首選；如果只是跑一次任務，優先用 `codex exec` 或 Codex SDK。

> [!WARNING]
> App Server 會暴露能操作 workspace 的入口。跨機器使用前必須先處理認證、TLS、token 保管、日誌脫敏和 sandbox / approval 邊界。

<Cards>
  <Card title="Codex App Server" href="https://developers.openai.com/codex/app-server">
    檢視官方 App Server 協議和使用說明。
  </Card>
  <Card title="Remote TUI" href="https://developers.openai.com/codex/cli/features#connect-the-tui-to-a-remote-app-server">
    學習如何把本地 TUI 連線到遠端執行環境。
  </Card>
  <Card title="Non-interactive mode" href="/zh-Hant/docs/codex/official/01-products/28-non-interactive">
    一次性自動化任務優先看 `codex exec`。
  </Card>
</Cards>

## 它解決什麼問題

```mermaid
flowchart TB
    AppServer["Codex App Server"]
    Remote["遠端 TUI<br/>本地操作，遠端執行"]
    Client["自研客戶端<br/>展示 thread、turn、diff、approval"]
    Events["即時事件流<br/>item started/completed、工具呼叫、審批"]

    AppServer --> Remote
    AppServer --> Client
    AppServer --> Events
```

適合：

- 程式碼和憑據必須留在遠端機器，但使用者想在本地操作。
- 你要做自己的 IDE 外掛、內部程式碼平臺或審查介面。
- 需要即時展示 agent 正在做什麼。
- 需要處理 thread、turn、item、approval、diff 和事件流。

不適合：

- 新手學習 Codex。
- CI 中跑一次檢查。
- 批次文件處理。
- 沒有認證和許可權模型的遠端訪問。

## 和 exec、SDK 的邊界

`codex exec`：

- 適合一次性自動化。
- 適合 CI、scheduled jobs、批處理和結構化輸出。
- 比 App Server 更簡單。

Codex SDK：

- 適合在後端程式裡控制 Codex。
- 比 `exec` 更適合長期整合。
- 不要求你自己做完整富客戶端協議。

App Server：

- 適合客戶端級體驗。
- 需要處理即時事件、審批、狀態同步和連線安全。
- 複雜度最高。

學習順序建議：CLI -> `codex exec` -> SDK -> App Server。

## 安全路線

最小風險路線：

```mermaid
flowchart LR
    Local["本機 TUI"] --> Loopback["127.0.0.1 app-server"]
```

遠端但受控路線：

```mermaid
flowchart LR
    Local["本地 TUI"] --> Tunnel["SSH tunnel"]
    Tunnel --> Remote["遠端 app-server"]
```

高風險路線：

```mermaid
flowchart LR
    Client["網路客戶端"] --> TLS["TLS + auth"]
    TLS --> Server["非本機 app-server"]
```

如果要跨網路直接連線，至少需要：

- WebSocket 認證。
- TLS。
- token 檔案許可權控制。
- 日誌脫敏。
- 失敗重試和超時處理。
- 明確 sandbox 與 approval。

不要裸露監聽在公網地址。

## 心智模型

App Server 中常見物件：

- Thread：一段會話。
- Turn：一次使用者請求。
- Item：turn 中的工作單元，例如訊息、工具呼叫、命令、diff、審批請求。

客戶端要做的不只是“發 prompt 等回答”，而是持續消費事件流：

- turn 開始。
- item 開始。
- 工具呼叫。
- 審批請求。
- 檔案變化。
- item 完成。
- turn 完成。

如果客戶端只顯示最終回答，而不顯示過程事件，就很難做可信審查。

## 常見坑

- 把 App Server 當普通 HTTP API。
- 不處理事件順序和斷線重連。
- 只顯示最終結果，不顯示審批和 diff。
- 遠端暴露但沒有 TLS 和認證。
- 把 token 放進命令列、日誌或儲存庫。
- 忽略 shell 命令和 sandbox 的邊界差異。
- 沒有 overloaded / timeout / retry 策略。

這些問題不是實現細節，而是產品安全邊界。

## CLI 入口和引數

官方 CLI reference 將 `codex app-server` 標記為 Experimental，用途是為 local development 或 debugging 啟動 Codex app server。

預設監聽方式：

```bash
codex app-server --listen stdio://
```

WebSocket 監聽方式：

```bash
codex app-server --listen ws://127.0.0.1:PORT
```

WebSocket 相關引數包括：

| 引數 | 用途 |
| --- | --- |
| `--listen` | 監聽 `stdio://` 或 `ws://IP:PORT` |
| `--ws-auth` | WebSocket client 認證模式 |
| `--ws-token-file` | capability token 檔案 |
| `--ws-shared-secret-file` | signed bearer token 的 HMAC secret 檔案 |
| `--ws-issuer` | signed bearer token 的 expected `iss` |
| `--ws-audience` | signed bearer token 的 expected `aud` |
| `--ws-max-clock-skew-seconds` | 校驗 `exp` / `nbf` 的 clock skew |

如果 `--listen ws://IP:PORT` 暴露給非本機客戶端，必須把認證、TLS termination 和日誌脫敏當成前置條件。

## Remote TUI 最小流程

1. 在遠端機器啟動 app server。
2. 透過 SSH tunnel 或安全代理暴露到本機。
3. 本機用 `codex --remote ws://host:port` 連線。
4. 如果 server 要求 bearer token，用 `--remote-auth-token-env` 從環境變數讀取。
5. 連線後確認命令實際在遠端 workspace 執行。
6. 先跑 `pwd`、`git status` 這類只讀命令驗證環境。

token 不要放在命令列引數裡。命令列歷史、程序列表和日誌都可能洩露它。

## 除錯方式

官方 CLI reference 提供了 `codex debug app-server send-message-v2`，用於透過內建 test client 向 app-server 傳送一條 V2 message，並觀察 thread / turn flow。

適合除錯：

- app-server 是否能啟動。
- client 是否能建立 thread。
- turn event 是否能正常流出。
- approval 或 tool event 是否按預期出現。
- 客戶端消費事件是否遺漏。

不適合除錯業務任務成功率。業務任務失敗時，仍要看 workspace、sandbox、approval、model、prompt 和專案命令。

## 最小驗收清單

用對 App Server，至少應能證明：

- 命令在哪臺機器執行。
- workspace 在哪裡。
- token 存在哪裡，如何輪換。
- 非本機連線如何認證和加密。
- 客戶端能顯示審批請求和 diff。
- 使用者能拒絕高風險動作。
- 失敗時能區分認證、連線、sandbox、模型和客戶端消費問題。

如果這些問題說不清，不要把 App Server 用到真實專案裡。

## 官方資料

- [Command line options](https://developers.openai.com/codex/cli/reference)
- [Codex CLI features: remote app-server](https://developers.openai.com/codex/cli/features#connect-the-tui-to-a-remote-app-server)
- [Codex app features](https://developers.openai.com/codex/app/features)
