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 擴充功能（更適合 IDE 的方式來與 Codex 智能代理互動）時，我們需要一種使用相同工具的方法，以便從 IDE UI 驅動相同的智能代理迴圈，而無需重新落實。這意味著要支援超越請求/回覆的豐富互動模式，例如探索工作區、在智能代理推理時串流進度，以及輸出差異。我們最初嘗試將 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. 對話串生命週期與持久性。對話串是 Codex 中用戶與智能代理之間的對話。Codex 會建立、恢復、分支複製及封存對話串，並保留事件歷史記錄，讓客戶端可重新連接並呈現一致的時間軸。

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

3. 工具執行與擴展。Codex 會在沙盒中執行 shell/file 工具，並串聯 MCP 伺服器和技能等整合項目，讓它們能在一致的政策模型下參與智能代理迴圈。

我們在此提到的所有智能代理邏輯，包括核心智能代理迴圈，均位於 Codex CLI 程式碼庫中名為「Codex core⁠（在新視窗中開啟）」的部分。Codex core 既是存放所有智能代理程式碼的程式庫，也是可啟動的運行時間，用於運行智能代理迴圈並管理單一 Codex 執行緒（對話）的持久性。

為了發揮作用，Codex 工具需要讓客戶能夠存取。這就是 App Server 發揮作用的地方。

標題為「App Server 過程流程」的圖表。客戶端將 JSON-RPC 訊息發送到 stdio 讀取器，該讀取器將請求分派到 Codex 訊息處理器。處理器透過查詢對話串、處理對話串、提交的請求和事件/更新，與對話串管理器及核心對話串互動，然後將回應覆回客戶端。

App Server 既是客戶端與伺服器之間的 JSON-RPC 協定，亦是一個長時間運行的程序，託管 Codex 核心對話串。從上方圖表可見，App Server 程序有四個主要元件：stdio 讀取器、Codex 訊息處理器、對話串管理器，以及 Core 對話串。對話串管理器會為每個對話串啟動一個核心工作階段，而 Codex 訊息處理器則會直接與每個核心工作階段通訊，以提交客戶端請求並接收更新。

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

客戶端與 App Server 之間的 JSON-RPC 協定是完全雙向的。一般的對話串包含一個客戶端請求和多個伺服器通知。此外，伺服器可以在智能代理需要輸入（例如批准）時發起請求，然後暫停該回合，直到客戶端回應為止。

對話基本元素

接下來，我們會拆解對話基礎，即 App Server 協定的構建基本元素。為智能代理迴圈設計 API 相當棘手，因為用戶/智能代理的互動並非簡單的請求/回應。一個用戶請求可以展開為客戶端需要忠實呈現結構化動作序列：用戶的輸入、智能代理的逐步進展，以及過程中產生的工件（例如差異）。為了讓該互動串流易於整合並在不同 UI 中保持穩定，我們確立了三個具有明確邊界和生命週期的核心基本元素：

1. 項目：項目是 Codex 中輸入/輸出的原子單位。項目按類型（例如，用戶訊息、智能代理訊息、工具執行、核准請求、差異）分類，每個項目都有明確的生命週期：

item/started 當項目開始時
可選的 item/*/delta 事件作為內容串流（適用於串流項目類型）
item/completed 出現在項目以其終端負載完成時

此生命週期讓客戶端可在 started 時立即開始呈現，在 delta 時串流增量更新，並在 completed 時最終處理。

2. 回合：回合是由用戶輸入觸發的智能代理工作單位。當客戶端提交輸入（例如「執行測試並總結失敗項目」）時，回合就會開始；當智能代理完成該輸入所對應的所有輸出時，回合就算結束。一個回合包含一系列項目，用以表示過程中的中間步驟與最終產出。

3. 對話串：對話串是用於承載使用者與智能代理之間持續 Codex 工作階段的長期容器。一個對話串包含多個回合。對話串可被建立、恢復、分支複製和封存。其歷史記錄會被持久保存，令客戶端可重新連接並呈現一致的時間軸。

現在，我們將看看一段客戶端與智能代理之間的簡化對話，其中對話以基本元素表示：

標題為「客戶端伺服器協定訊息流程：初始化握手」的圖表。客戶端向伺服器發送包含 clientInfo 的初始化請求。伺服器會以包含 userAgent 字串「my_client/1.0」的結果事件回應。

在對話開始時，客戶端和伺服器需要建立 initialize 握手。客戶端必須在任何其他方法之前發送單一 initialize 請求，伺服器會以回覆確認。這讓伺服器有機會宣傳其功能，並讓雙方在真正工作開始之前協議協定版本、功能標誌和預設值。以下是 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 — 顯示一個回合，其中用戶訊息是「run tests and summarize failures.」

當客戶端提出新請求時，會先建立一個對話串，然後建立一個回合。伺服器會傳回進度通知（thread/started 和 turn/started）。它還會將其登記為項目的輸入傳回，例如此處的用戶訊息。

標題為「客戶端-伺服器協定訊息流程：工具執行（可選核准）」的圖表。在工具調用期間，伺服器會發出 item/started，然後發出 item/commandExecution/requestApproval，並附上原因（「運行測試」）。客戶端會回傳核准事件 (allow/deny)。然後，伺服器會發出 item/completed，顯示指令執行（「pnpm 測試」）。

工具調用亦會以項目形式傳回客戶端。此外，伺服器在執行某些操作前，可能會透過發送請求要求客戶端批准。在客戶端回覆「允許」或「拒絕」之前，該回合會暫停。以下為此核准流程在 VS Code 擴充功能中的呈現方式：

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

標題為「用戶端-伺服器協定訊息流程：串流智能代理訊息流程」的圖表。伺服器會將助理訊息分段串流傳送：item/started、兩個 agentMessage/delta 事件（「執行了 3 次測試。」、「全部通過」），然後 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 Web 運行時間，以及 TUI。

標題為「透過應用程式伺服器將 Codex 客戶端與 Codex 工具整合」的圖表。第一方客戶端（Codex 桌面應用程式、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

VS Code 的螢幕截圖，顯示 Codex 擴充功能正在運行。一個 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 網頁介面的螢幕截圖，顯示一項標題為「更新登入成功訊息」的更新。左側面板總結了變更、測試和已修改的檔案，而右側面板顯示 login.rs 的程式碼差異，並更新了登入成功訊息的措辭。

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

由於網頁工作階段是短暫的（分頁會關閉，網絡亦會中斷），網頁應用程式不能作為長時間運行任務的可靠來源。在伺服器上保留狀態和進度，即使分頁消失，工作仍會繼續。串流協定和已儲存的執行緒工作階段，讓新工作階段能輕鬆重新連接、從中斷處繼續，並在無需於重建客戶端狀態的情況下追上進度。

TUI/Codex CLI

顯示終端機運行 Codex CLI 的螢幕截圖。其顯示 OpenAI Codex 橫幅，使用模型 GPT-5.2-codex medium，一個用戶指令「explain app server to me」，以及一個「工作中」狀態。下方會顯示一個建議：「為 @filename 編寫測試」，並提供快捷鍵選項。

過往，TUI 是一個「原生」客戶端，與智能代理迴圈在同一個進程中運行，並直接與 Rust 核心類型交談，而非使用 app-server 協定。這讓早期迭代變得很快，但也使 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 應用程式伺服器

當你想要將完整的 Codex 工具以穩定且適合 UI 的事件串流方式公開時，請選擇 App Server。你可以同時獲得智能代理迴圈的完整功能，以及其他支援功能，例如使用 ChatGPT 登入、模型探索和配置管理。主要成本在於整合工作，因為你需要以你的語言建立客戶端的 JSON-RPC 綁定。不過，在實務上，只要你向 Codex 提供 JSON 結構定義和文件，Codex 就能完成大量繁重的工作。我們合作過的許多團隊都能夠使用 Codex 快速完成運作中的整合。

嵌入 Codex 的其他方式

Codex Exec⁠（在新視窗中開啟）

用於一次性任務和 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」變體：其保留了請求/回應/通知的結構，但省略了 "jsonrpc": "2.0"標題並以 JSONL 格式透過 stdio 傳輸，而非嚴格的 JSON‑RPC 2.0。
2
「stdio」指容器內 app-server 的 stdin/stdout。在託管設置中，這些串流通常會透過持久的網絡連接（例如類似 WebSocket）隧道傳輸到容器運行時間，因此，即使其不是字面意義上的本機管道，亦會像 stdio 一樣運行。

繼續閲讀

查看全部

用 Codex 建立可自我改進的報稅智能代理

工程2026年5月27日

在 Windows 上建構安全而有效的沙盒以支援 Codex

工程2026年5月13日

哥布林從何而來

工程2026年5月5日