2026年2月4日

解鎖 Codex 的運作機制：我們如何打造 App Server

由技術人員 Celia Chen 撰寫

載入中…

OpenAI 的程式設計智慧體 Codex 存在於多種不同的介面：網頁應用程式⁠(在新視窗中開啟)、CLI⁠(在新視窗中開啟)、IDE 擴充功能⁠(在新視窗中開啟)，以及全新的 Codex macOS 應用程式。從底層來看，它們都由同一個 Codex 框架驅動，即所有 Codex 體驗的基礎智慧體循環與邏輯。它們之間的關鍵連結是什麼？Codex App Server⁠(在新視窗中開啟) 是一款對用戶端友善的雙向 JSON-RPC¹ API。

本文將介紹 Codex App Server，分享我們迄今為止的心得，說明如何將 Codex 的功能整合到你的產品，幫助使用者大幅提升工作流程效率。我們將介紹 App Server 的架構與通訊協定，以及它如何與不同的 Codex 介面整合，並分享使用 Codex 的技巧 (無論你想將 Codex 變成程式碼審查員、SRE 智慧體，或是程式設計助理)。

App Server 的起源

在深入探討架構之前，了解 App Server 的背景故事會很有幫助。App Server 最初只是用來在不同產品間重複使用 Codex 運作框架的實用方式，隨著時間逐步演變為我們的標準通訊協定。

Codex CLI 最初是一個 TUI (終端機使用者介面)，這表示 Codex 是透過終端機存取的。開發 VS Code 擴充功能 (一種與 Codex 智慧體互動的更適合 IDE 的方式) 時，我們需要一種方法來使用相同的工具，以便在不重新實作的情況下，從 IDE 的使用者介面驅動相同的智慧體循環。這表示需要支援要求/回應以外的豐富互動模式，例如探索工作區、在智慧體推理時串流進度，以及輸出差異。我們最初嘗試將 Codex 公開為 MCP 伺服器⁠(在新視窗中開啟)，但事實證明，以對 VS Code 有意義的方式保持 MCP 語義是困難的。我們反而引進一個與 TUI 循環相對應的 JSON-RPC 通訊協定，這成為 App Server 的非官方第一版⁠(在新視窗中開啟)。當時，我們並未預期其他客戶會依賴 App Server，因此並未將其設計為穩定的 API。

隨著 Codex 在接下來幾個月的採用率成長，內部團隊和外部合作夥伴希望能在產品中嵌入相同的工具，以加速使用者的軟體開發流程。例如，JetBrains 和 Xcode 希望獲得 IDE 等級的智慧體體驗，而 Codex 桌面應用程式需要並行協調多個 Codex 智慧體。這些需求促使我們設計一個平台介面，以供產品和合作夥伴整合長期安全地依賴。它必須易於整合且具備向後相容性，這表示我們可以在不破壞現有用戶端的情況下改善通訊協定。

接下來，我們將逐步說明我們如何設計架構和通訊協定，以便不同的用戶端使用相同的工具。

Codex 的運作機制內幕

首先，一起深入瞭解 Codex 運作機制的內部結構，以及 Codex App Server 如何將其呈現給用戶端。我們的上一篇 Codex 部落格解析了協調使用者、模型與工具之間互動的核心智慧體循環。這是 Codex 運作機制的核心邏輯，但完整的智慧體體驗遠不止於此：

1. 對話串的生命週期與持續性。Thread 是使用者與智慧體之間的 Codex 對話。Codex 會建立、還原、分支及封存對話串，並保留事件歷程，讓用戶端能重新連線並呈現一致的時間軸。

2. 設定與驗證。Codex 會載入設定、管理預設值，並執行驗證流程，例如「使用 ChatGPT 登入」，包括憑證狀態。

3. 工具執行與擴充。Codex 會在沙箱中執行 shell/file 工具，並連接 MCP 伺服器和技能等整合項目，讓它們在一致的原則模型下參與智慧體運作循環。

我們在此提到的所有智慧體邏輯 (包括核心智慧體循環)，都位於 Codex CLI 程式碼庫中名為「Codex core⁠(在新視窗中開啟)」的部分。Codex core 既是存放所有智慧體程式碼的程式庫，也是可啟動以運行智慧體循環並管理單一 Codex 對話串 (對話) 持續性的執行階段。

若要發揮作用，Codex 運作機制就必須供用戶端存取。這就是 App Server 派上用場的地方。

標題為《App server process flow》的圖表。用戶端將 JSON-RPC 訊息發送到 stdio 讀取器，該讀取器將要求分派給 Codex 訊息處理器。處理器透過查詢對話串、對話串控制代碼、提交的要求和事件/更新，與對話串管理器和核心對話串互動，然後將回應返回給用戶端。

App Server 同時是用戶端與伺服器之間的 JSON-RPC 通訊協定，也是託管 Codex 核心對話串的長期運行程序。如上圖所示，App Server 程序包含四個主要元件：stdio 讀取器、Codex 訊息處理器、對話串管理器，以及核心對話串。對話串管理器會為每個對話串啟動一個核心工作階段，然後 Codex 訊息處理器會直接與每個核心工作階段通訊，以提交用戶端要求並接收更新事項。

一個用戶端要求可能會導致多次事件更新，而正是這些詳細事件使我們在 App Server 上建立豐富的使用者介面。此外，stdio 讀取器和 Codex 訊息處理器作為客戶端與 Codex 核心對話串之間的翻譯層。它們將客戶端的 JSON-RPC 要求轉換為 Codex 核心作業，監聽 Codex 核心的內部事件流，然後將這些低層事件轉化為一小組穩定、可供使用者介面使用的 JSON-RPC 通知。

用戶端與 App Server 之間的 JSON-RPC 通訊協定是完全雙向的。典型的對話串包含一個用戶端要求和多個伺服器通知。此外，當智慧體需要輸入 (例如核准) 時，伺服器可以主動發起要求，然後暫停該回合，直到用戶端做出回應。

對話基本要素

接下來，我們將解析對話的基本要素，這是 App Server 通訊協定的基本要素。為智慧體的運作循環設計 API 很棘手，因為使用者與智慧體的互動並非簡單的要求與回應。一個使用者要求可能會展開成一連串結構化的動作序列，用戶端必須忠實呈現：使用者的輸入、智慧體的逐步進展，以及過程中產生的工件 (例如：差異)。為了讓該互動串流易於整合，並在各種使用者介面中保持韌性，我們確立了三個核心基本要素，並為其劃定清晰的邊界和生命週期：

1. 項目：項目是 Codex 中輸入/輸出的基本單位。項目依類型劃分 (例如：使用者訊息、智慧體訊息、工具執行、核准要求、差異) 且每個都有明確的生命週期：

item/started 當項目開始時
可選的 item/*/delta 事件作為內容串流 (適用於串流項目類型)
item/completed 當項目以其最終負載完成定稿時

此生命週期讓用戶端在 started 時立即開始渲染，在 delta 時串流增量更新，並在 completed 時完成。

2. 回合：回合是由使用者輸入啟動的智慧體工作單位。它從用戶端提交一個輸入內容（例如「運行測試並彙整失敗項目」）開始，並在智慧體完成針對該輸入內容產生輸出內容時結束。一個回合包含一系列項目，用來表示過程中產生的中間步驟與最終輸出。

3. 對話串：對話串是用來保存使用者與智慧體之間 Codex 工作階段的結構，該結構會持續存在，且包含多個回合。對話串可以建立、還原、分支和封存。對話串歷程會持久保存，使用戶端能重新連線並呈現一致的時間軸。

現在來瞧瞧一段簡化的用戶端與智慧體之間的對話，其中對話以基本元素表示：

標示為「用戶端-伺服器通訊協定訊息流程：初始化交握」的示意圖。用戶端將包含 clientInfo 的初始化要求傳送到伺服器。伺服器會以包含 userAgent 字串「my_client/1.0」的結果事件回應。

在對話開始時，用戶端與伺服器需要建立初始化交握。用戶端必須在執行其他方法之前先傳送單一初始化要求，伺服器會透過回應進行確認。這讓伺服器有機會宣傳其功能，並讓雙方在正式工作開始前，就通訊協定版本控制、功能標誌和預設值達成共識。以下是 OpenAI 的 VS Code 擴充功能提供的範例負載：

JSON

1{
2  "method": "initialize",
3  "id": 0,
4  "params": {
5    "clientInfo": {
6      "name": "codex_vscode",
7      "title": "Codex VS Code Extension",
8      "version": "0.1.0"
9    }
10  }
11}

以下是伺服器回傳的內容：

JSON

1{
2  "id": 0,
3  "result": {
4    "userAgent": "codex_vscode/0.94.0-alpha.7 (Mac OS 26.2.0; arm64) vscode/2.4.22 (codex_vscode; 0.1.0)"
5  }
6}

標題為「用戶端-伺服器通訊協定訊息流程：執行緒與回合生命週期」的示意圖。客戶端會將 thread/start 和 turn/start 要求傳送至伺服器。伺服器會發出事件—thread/started、turn/started、item/started，以及 item/completed—顯示一個回合，其中使用者訊息是「運行測試並彙整失敗項目。」

用戶端提出新的要求時，它會先建立一個對話串，然後建立一個回合。伺服器會回傳進度通知 (thread/started 和 turn/started)。它也會將註冊為項目的輸入傳回，例如這裡的使用者訊息。

標題為「用戶端-伺服器通訊協定訊息流程：工具執行 (可選核准)」的圖表。在工具呼叫期間，伺服器會發出 item/started，接著發出 item/commandExecution/requestApproval，並附上原因 (「run tests」)。用戶端會傳回核准事件 (允許/拒絕)。伺服器接著會發出 item/completed，顯示命令執行 (「pnpm test」)。

工具呼叫也會以項目的形式傳回用戶端。此外，伺服器可能會傳送要求，在執行動作前先要求用戶端核准。核准將暫停此回合，直到用戶端以「allow」或「deny」回覆。這是 VS Code 擴充功能中的核准流程：

深色主題介面中的權限提示詞詢問：「你是否允許我為此工作區執行 pnpm test？」它列出選項：1) 是，2) 是，且不再詢問以 pnpm test 開頭的命令，3) 否，底部有一個提交按鈕。

標題為「用戶端-伺服器協定訊息流程：串流智慧體訊息流程」的圖表。伺服器會將 assistant 訊息分段串流：item/started、兩個 agentMessage/delta 事件（「ran 3 tests.」、「all passed」），然後 item/completed。以 turn/completed 結束回合。

最後，伺服器會傳送一則智慧體訊息，然後以 turn/completed 結束回合。智慧體訊息 delta 事件會以串流方式將訊息片段回傳，直到訊息以 item/completed 完成定稿。

為了方便閱讀，圖中的資訊已簡化。如果想查看完整一個回合的 JSON，可以從 Codex CLI 儲存庫執行測試用戶端：

Bash

1codex debug app-server send-message-v2 "run tests and summarize failures"

與用戶端的整合

現在讓我們看看不同的用戶端介面如何透過 App Server 嵌入 Codex。我們將介紹三種模式：本機應用程式和 IDE、Codex 網頁執行階段，以及 TUI。

標題為「透過應用程式伺服器將 Codex 用戶端與 Codex 運作機制整合」的圖表。第一方用戶端 (Codex Desktop App、TUI/CLI、Web Runtime) 和第三方整合 (JetBrains IDE、VS Code、Xcode) 透過 JSON-RPC 呼叫與 Codex 運作機制進行通訊。

在這三者中，傳輸方式都是透過 STDIO 的 JSON-RPC (JSONL)。JSON-RPC 可讓你輕鬆地用所選的語言建立用戶端綁定。Codex 介面與合作夥伴整合已在 Go、Python、TypeScript、Swift 和 Kotlin 等語言中實作 App Server 用戶端。對於 TypeScript，你可以執行以下指令，直接從 Rust 通訊協定產生定義：

Bash

1codex app-server generate-ts

對於其他語言，你可以生成 JSON 結構描述套件，然後執行以下指令將其輸入到你偏好的程式碼生成器：

Bash

1codex app-server generate-json-schema

本機應用程式與 IDE

顯示正在執行 Codex 擴充功能的 VS Code 螢幕截圖。一個 Rust 測試檔案已開啟，其下方的 Codex 面板描述僅執行 fmt 和 cargo test -p codex-app-server，並回報格式化與測試正在進行中，同時等待最終的通過或失敗結果。

本機用戶端通常會隨附或下載符合平台的 App Server 二進位檔，將其啟動為長時間執行的子行程，並維持一個用於 JSON-RPC 的雙向 stdio 通道。例如，在我們的 VS Code 擴充功能和桌面應用程式中，隨附的成品包含平台專屬的 Codex 二進位檔，並固定在經過測試的版本上，確保用戶端始終執行我們已驗證的完全相同的程式碼。

並非每個整合都能頻繁地發布用戶端更新。有些合作夥伴 (例如 Xcode) 透過保持用戶端穩定，並在需要時允許其指向較新的 App Server 二進位檔，來解耦發行週期。如此一來，他們就能採用伺服器端的改進 (例如 Codex 核心中的更佳自動壓縮或新支援的配置鍵)，並在不必等待用戶端版本發佈的情況下推出錯誤修正。App Server 的 JSON-RPC 介面設計為向後相容，因此舊版用戶端可以安全地與新版伺服器通訊。

Codex Web

Codex 網頁介面的螢幕截圖，顯示一則標題為「Update login success message」的更新。左側面板摘要顯示變更、測試與已修改的檔案，而右側面板顯示 login.rs 的程式碼差異，並更新了登入成功訊息的措辭。

Codex Web 使用 Codex 運作機制，但在容器環境中執行。工作程序會使用已簽出的工作區來佈建容器，啟動 App Server 二進位檔，並透過 stdio² 通道維持長時間運作的 JSON-RPC。網頁應用程式 (在使用者的瀏覽器分頁中執行) 透過 HTTP 和 SSE 與 Codex 後端通訊，串流由工作者產生的任務事件。這讓瀏覽器端的 UI 保持輕量，同時仍能在桌面和網頁上提供一致的運行時環境。

由於網頁工作階段是短暫的 (分頁會關閉，網路會中斷)，網頁應用程式無法作為長時間運行任務的可靠來源。在伺服器上保留狀態和進度，表示即使分頁消失，工作也會繼續進行。串流通訊協定和已儲存的對話串會話，使新的工作階段能輕鬆重新連線、從中斷的地方繼續，而無需在客戶端重建狀態。

TUI/Codex CLI

顯示 Codex CLI 執行於終端機的螢幕截圖。它顯示了帶有模型 gpt-5.2-codex 的 OpenAI Codex 橫幅中等、使用者指令「explain app server to me」，以及「Working」狀態。下方會出現一則建議：「為 @filename 撰寫測試」，並提供捷徑選項。

歷史上，TUI 是一個「原生」用戶端，與智慧體循環在同一個進程中運行，直接與 Rust 核心類型通訊，而不是通過應用程式伺服器通訊協定。這讓早期的迭代速度很快，但也使 TUI 成為一個特殊案例的介面。

既然 App Server 已經存在，我們計畫重構 TUI⁠(在新視窗中開啟) 加以使用，使其行為如同其他用戶端：啟動 App Server 子程序，透過 stdio 使用 JSON-RPC 通訊，並呈現相同的串流事件與核准。這樣一來，TUI 就可以連線到遠端電腦上運行的 Codex 伺服器，使智慧體靠近運算環境，即使筆記型電腦進入睡眠狀態或中斷連線，也能繼續工作，同時還能在本機提供即時更新和控制。

選擇合適的通訊協定

Codex App Server 將會是我們未來維護的首要整合方式，但也有其他功能較有限的方法。預設情況下，我們建議客戶使用 Codex App Server 來整合 Codex，但也值得看看不同的整合方法，瞭解它們的優缺點。以下是最常見的幾種驅動 Codex 的方式，以及各自適合的情境。

JSON-RPC 通訊協定

Codex 作為 MCP 伺服器

執行 codex mcp-server⁠(在新視窗中開啟)，然後從任何支援 stdio 伺服器的 MCP 用戶端連線 (例如：OpenAI Agents SDK⁠(在新視窗中開啟))。如果你已經有 MCP 為基礎的工作流程，並想將 Codex 作為可呼叫的工具來使用，這會是個不錯的選擇。缺點是你只能取得 MCP 所公開的內容，因此依賴更豐富的工作階段語意 (例如差異更新) 的 Codex 特定互動，可能無法透過 MCP 端點順利對應。

跨供應商智慧體運作機制通訊協定

某些生態系統提供可攜式介面，能夠針對多個模型供應商和執行環境。如果你想要一個能協調多個智慧體的抽象層，這可能會是個好選擇。取捨在於，這些通訊協定往往會集中在共同的能力子集，這可能會讓較豐富的互動更難以表達，供應商特定的工具與工作階段語意很重要的情況下更是如此。這個領域正在快速演進，我們預期在釐清用來呈現現實智慧體工作流程的最佳基本要素後，會出現更多通用標準 (skills⁠(在新視窗中開啟) 就是個很好的例子)。

Codex App Server

當你想要將完整的 Codex 運作機制以穩定且使用者介面友善的事件串流形式公開時，請選擇 App Server。你可以同時獲得智慧體運作循環的完整功能，以及其他支援功能，例如使用 ChatGPT 登入、模型探索和設定管理。主要成本在於整合工作，因為必須用你的語言建構用戶端的 JSON-RPC 綁定。然而，在實務上，只要你提供 JSON 結構描述和文件，Codex 就能完成大量繁重的工作。我們合作過的許多團隊都能夠使用 Codex 快速實現有效的整合。

嵌入 Codex 的其他方式

Codex 執行⁠(在新視窗中開啟)

用於一次性任務和 CI 執行的輕量級、可編寫指令碼的 CLI 模式。它非常適合自動化和管道應用，在這些應用中，您需要一個命令以非互動方式執行到完成、為日誌串流結構化輸出，並在結束時以明確的成功或失敗訊號退出。

Codex SDK⁠(在新視窗中開啟)

一個 TypeScript 程式庫，可讓你在自己的應用程式中以程式方式控制本機 Codex 智慧體。當你想要為伺服器端工具和工作流程使用原生程式庫介面，而不需要另外建置獨立的 JSON-RPC 用戶端時，這是最佳選擇。由於它比 App Server 發布得更早，目前支援的語言較少，涵蓋範圍也較小。如果開發者有興趣，我們可能會新增更多封裝 App Server 通訊協定的 SDK，讓團隊無需撰寫 JSON-RPC 綁定，就能涵蓋更多的應用範圍。

繼續推進

這篇文章分享了我們如何設計與智慧體互動的新標準，以及如何將 Codex 運作機制轉化為穩定且對用戶端友好的通訊協定。我們介紹了 App Server 如何公開 Codex 核心，讓用戶端驅動完整的智慧體循環，並支援多種介面，包括 TUI、本機 IDE 整合和網頁執行環境。

如果這激發了你將 Codex 整合到自己工作流程中的想法，那麼不妨試試 App Server。所有原始碼都位於 Codex CLI 的開源儲存庫⁠(在新視窗中開啟)。歡迎分享你的意見回饋與功能需求。我們很期待聽到你的意見，並持續讓智慧體更容易讓每個人使用。

作者

Celia Chen

致謝

特別感謝 Michael Bolin、Owen Lin、Eric Traut 和 Rasmus Rygaard 對這篇文章的貢獻，以及整個參與 App Server 開發的 Codex 團隊。

註腳

1
我們使用「JSON‑RPC lite」變體：它保留 request/response/notification 的形式，但省略 「jsonrpc」:「2.0」標頭以 JSONL 格式透過 stdio 呈現，而非嚴格的 JSON‑RPC 2.0。
2
「stdio」指的是容器內部應用伺服器的標準輸入/輸出 (stdin/stdout)。在託管式部署中，這些串流通常會透過持久的網路連線 (例如類似 WebSocket) 隧道傳輸到容器執行階段，因此即使它不是字面上的本機管道，也會表現得像 Stdio。

繼續閱讀

檢視全部

用 Codex 建立可自我改進的報稅智慧體

工程2026年5月27日

打造安全且有效的沙箱，讓 Codex 能在 Windows 上運作

工程2026年5月13日

Supercomputer networking to accelerate large scale AI training

工程2026年5月5日