OpenAI Codex 應用伺服器架構與整合

OpenAI 已發布 Codex 應用伺服器，一個標準化的 JSON-RPC 協議與長時間執行的程序，旨在將 Codex 代理程式框架公開給各種客戶端應用程式。此架構讓開發者能將高保真度的代理迴圈——包括工作區探索、即時進度串流與差異產生——整合至 IDE、桌面應用程式與網頁環境，而無需重新實作核心代理邏輯。

Codex 應用伺服器架構

Codex 應用伺服器充當客戶端與「Codex 核心」之間的翻譯層，後者包含代理迴圈、工具執行邏輯與執行緒管理。

核心元件

• Stdio Reader: 處理傳入的通訊通道。
• Codex Message Processor: 將客戶端的 JSON-RPC 請求轉換為 Codex 核心操作，並將內部事件串流轉換為穩定、可供 UI 使用的通知。
• Thread Manager: 管理核心會話的生命週期，為每個執行緒啟動一個核心會話。
• Core Threads: 代理迴圈執行的實際執行環境實例。

Codex 框架

除了代理迴圈之外，應用伺服器還公開完整的 Codex 框架，內容包括：

• Thread Lifecycle and Persistence（執行緒生命週期與持久性）: 能夠建立、恢復、分支與封存對話，確保客戶端重新連線時擁有一致的時間線。
• Configuration and Authentication（設定與驗證）: 管理預設值與驗證流程，例如「使用 ChatGPT 登入」。
• Tool Execution and Extensions（工具執行與擴充）: 為 shell 與檔案工具提供沙箱環境，並整合 MCP 伺服器與技能。

對話原語

為了處理代理互動的非線性特性，應用伺服器協議使用三個核心原語，以確保彈性並便於在不同使用者介面間整合。

1. Item（項目）

項目是輸入與輸出的原子單位。每個項目（例如使用者訊息、工具執行、差異）遵循特定的生命週期：

• item/started：項目開始。
• item/*/delta：內容逐步串流（針對串流類型）。
• item/completed：項目以最終負載完成。

2. Turn（回合）

回合代表由使用者輸入觸發的單一代理工作單位。它包含一系列項目，代表代理產生的中間步驟與最終輸出。

3. Thread（執行緒）

執行緒是會話的持久容器。它保存多個回合，使客戶端能重新連線至會話並呈現歷史記錄，而無需重新建構狀態。

客戶端整合模式

應用伺服器使用基於 stdio（JSONL）的 JSON-RPC，允許在多種語言（包括 Go、Python、TypeScript、Swift 與 Kotlin）中建立客戶端綁定。

本機應用與 IDE

本機客戶端（如 VS Code 擴充功能與 Codex 桌面應用）將平台特定的應用伺服器二進位檔作為子程序捆綁。某些合作夥伴，例如 Xcode，透過指向較新版本的應用伺服器二進位檔，將發布週期與客戶端解耦，以在不需完整客戶端更新的情況下採用伺服器端的改進與錯誤修正。

Codex 網頁版

在容器化環境中，工作者會配置帶有工作區的容器並啟動應用伺服器二進位檔。網頁應用透過 HTTP 與 SSE 與 Codex 後端通訊，從工作者串流事件。此機制確保即使瀏覽器分頁關閉，長時間執行的任務仍會持續。

TUI 與 Codex CLI

雖然 TUI 最初直接與 Rust 核心類型互動，但目前正重構為使用應用伺服器協議。這使得 TUI 能連接遠端 Codex 伺服器，將代理保持在計算資源附近，同時提供本機更新。

整合方式比較

OpenAI 建議需要完整框架的使用者採用應用伺服器，但也提供其他依據特定使用情境的選項：

方法	最佳使用情境	折衷
Codex App Server	完整框架、穩定的 UI 友好事件串流與驗證管理。	需要自行建立客戶端 JSON-RPC 綁定。
MCP Server	現有基於 MCP 的工作流程，將 Codex 作為可呼叫工具。	受限於 MCP 語意；缺乏如差異更新等豐富會話功能。
Cross-provider Protocols	協調不同模型提供者的多個代理。	通常僅限於共同的功能子集，缺乏特定提供者的語意。
CLI Mode	一次性任務、CI/CD 流程與非互動式自動化。	非互動式；設計為單指令完成。
TypeScript Library	在 TypeScript 應用程式中以程式方式控制本機代理。	目前支援的語言較少，功能範圍也較應用伺服器小。

應用伺服器的原始碼可在開源的 Codex CLI 倉庫中取得。