連線 Codex App Server

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

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

Codex App Server

檢視官方 App Server 協議和使用說明。

Remote TUI

學習如何把本地 TUI 連線到遠端執行環境。

Non-interactive mode

一次性自動化任務優先看 codex exec。

它解決什麼問題

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。

安全路線

最小風險路線：

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

遠端但受控路線：

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

高風險路線：

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。

預設監聽方式：

codex app-server --listen stdio://

WebSocket 監聽方式：

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 最小流程

在遠端機器啟動 app server。
透過 SSH tunnel 或安全代理暴露到本機。
本機用 codex --remote ws://host:port 連線。
如果 server 要求 bearer token，用 --remote-auth-token-env 從環境變數讀取。
連線後確認命令實際在遠端 workspace 執行。
先跑 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 用到真實專案裡。