OpenAI Codex CLI 代理循環技術概述

OpenAI 詳細說明了 Codex CLI 代理循環的內部架構，這是管理使用者、LLM 與本地軟體工具之間互動的核心協調邏輯。此系統旨在透過反覆執行工具呼叫並管理不斷增長的對話上下文，以維持效能與穩定性，產生可靠的軟體變更。

代理循環架構

代理循環是協調使用者與模型之間資訊流的核心機制。對話中的單一「回合」包含多次推論與工具執行的迭代，直至達成最終狀態。

迭代過程

Input and Prompting: 代理取得使用者輸入，並為模型準備文字提示。
Inference: 提示被分詞後送至模型，以產生回應。
Decision Point: 模型要麼產生最終的助理訊息（結束此回合），要麼請求 tool call（例如執行像 ls 這樣的 shell 指令）。
Execution and Feedback: 若呼叫工具，代理會執行該指令，將輸出附加至提示，並重新向模型查詢。

此循環會持續重複，直到模型發出助理訊息，表示工作已完成，控制權應回到使用者手中。

模型推論與提示建構

Codex CLI 使用 Responses API 來驅動其代理循環。根據設定，它會連接到各種端點，包括 ChatGPT 登入、透過 API 金鑰的 OpenAI 託管模型，或使用 gpt-oss 搭配 Ollama 或 LM Studio 的本地實例。

建構初始提示

Codex 並非直接傳送逐字的提示，而是發送包含特定輸入類型的 JSON 負載。Responses API 伺服器會根據角色將其構造成提示，優先順序（由高到低）為 system、developer、user 與 assistant。

初始提示的關鍵組件包括：

Instructions: 插入至上下文的系統或開發者訊息。
Tools: 依據 schema 定義的工具清單，包含 Codex 提供的 shell 工具、Responses API 工具，以及透過 MCP（Model Context Protocol）伺服器提供的使用者工具。
Input: 聚合的文字、影像或檔案。包括來自 config.toml 的開發者指示，以及在專案根目錄或 $CODEX_HOME 中找到的 AGENTS.md 或 AGENTS.override.md 檔案中的使用者指示。

處理對話回合

每個回合皆以 Server-Sent Events（SSE）串流方式處理。當模型產生推理或函式呼叫時，會將其附加至 input 欄位以供後續請求使用。為了最佳化效能，Codex 確保舊的提示是新提示的完整前綴，這對啟用提示快取至關重要。

效能與上下文管理

隨著對話的增長，提示長度會變長，可能耗盡模型的上下文視窗並增加延遲。Codex 採用兩項主要策略來緩解此問題：提示快取與對話壓縮。

提示快取

為避免傳送不斷增長的 JSON 負載所帶來的二次方成本，Codex 依賴提示快取。快取命中僅在完全前綴匹配時發生。為維持這些命中，Codex 不會修改對話中較早的訊息，而是透過新增訊息來反映變更：

Configuration Changes: 沙箱設定或批准模式的變更會以新的 role=developer 訊息加入。
Environment Changes: 目前工作目錄的變更會以新的 role=user 訊息加入。

若未能維持工具的順序一致性（例如早期 MCP 工具實作），可能導致快取未命中，效能下降。

上下文視窗壓縮

當代幣數量超過 auto_compact_limit 時，Codex 會使用 Responses API 的 /responses/compact 端點。此過程會以較小且具代表性的項目清單取代龐大的對話歷史。其包含一個特殊的 type=compaction 項目，內含 encrypted_content，可在不需要完整代幣歷史的情況下保留模型對對話的潛在理解。