Codex CLI：權威技術參考指南

TL;DR：Codex 是跨介面的程式設計代理：它會讀取您的程式碼庫、在作業系統層級的沙箱中執行命令、修補檔案，並將任務委派至雲端。掌握五大系統 – config.toml、沙箱／核准模型、AGENTS.md、MCP 與 skills – 就能讓它成為事半功倍的利器。模型選擇：OpenAI 的模型文件目前建議將日常與複雜的程式設計工作交給 GPT-6 Sol（gpt-6-sol，自 v0.156.1 起已列入 CLI 選擇器），最艱鉅的端對端工作交給 GPT-6-Astra（未設定模型時，它仍是 CLI 內建的預設選項），而目標明確的大量任務則交給 GPT-6 Luna。可用情況取決於方案、工作區設定與推出進度；在此期間，GPT-5.6 系列模型仍可使用。透過 ChatGPT 登入 Codex 時，GPT-5.5 將於 2026年10月14日停止提供。¹⁴³¹⁶⁸ 初次使用嗎？請直接前往安裝與快速開始。想追蹤版本發布嗎？最新穩定版為 v0.157.1（2026年9月26日）；版本亮點會先概述目前狀態（哪些功能預設啟用、哪些仍處於實驗階段），再逐一介紹各版本；變更日誌則列出本指南的每次更新。¹¹⁶¹⁷¹

Codex 是跨介面的程式設計代理，而非只會撰寫程式碼的聊天機器人。CLI 會讀取您的程式碼庫、在沙箱中執行命令、修補檔案、透過 MCP 連接外部服務，並將耗時任務委派至雲端。它在本機執行，卻能通盤思考；同一套智慧會依據您的工作方式支援五種不同介面，其中包括瀏覽器擴充功能（支援 Chrome、Edge、Brave、Opera 與 Vivaldi），讓 Codex 在瀏覽器中運作，卻不會接管瀏覽器。⁹⁰¹²⁷

能否有效運用 Codex，而非僅止於淺嘗輒止，關鍵就在五大核心系統。掌握這些系統，Codex 就能成為事半功倍的利器：

1. 設定系統：透過 config.toml 控制行為
2. 沙箱與核准模型：限制 Codex 可執行的操作
3. AGENTS.md：定義專案層級的作業契約
4. MCP 協定：將功能延伸至外部服務
5. Skills 系統：封裝可重複使用的領域專業知識

我花了數個月，在正式環境的程式碼庫、CI/CD 管線與團隊工作流程中，同時運用 Codex 與 Claude Code。本指南將這些經驗濃縮為一份完整參考資料，也正是我初次使用時最希望能取得的指南。每項功能都附有實際語法、真實設定範例，以及連經驗豐富的使用者也容易踩到的陷阱。

重點摘要

• 5種介面，同一個核心：CLI、桌面應用程式、IDE 擴充功能、雲端任務，以及瀏覽器擴充功能（Chrome、Edge、Brave、Opera 和 Vivaldi）全都使用相同的模型系列，請選擇最符合您工作流程的介面。⁹⁰
• 作業系統層級的沙箱機制：Codex 在核心層級實施檔案系統與網路限制（macOS 使用 Seatbelt，Linux 使用 Landlock + seccomp），而非在容器內執行限制。
• AGENTS.md 可跨工具使用：您的專案指示可在 Codex、Cursor、Copilot、Amp、Jules、Gemini CLI、Windsurf、Cline、Aider、Zed，以及超過60,000個開放原始碼專案中使用。撰寫一次，處處適用。
• 設定檔可省去切換情境的負擔：定義具名設定預設值（fast、careful、auto），並透過 --profile 在各設定檔之間切換。
• 情境管理至關重要：隨附的 Codex 目錄為 GPT-6 Astra、Sol、Luna 及 GPT-5.6 系列提供272K情境視窗（API 將 GPT-6 Sol 與 Luna 列為1.05M）；GPT-5.5 在 Codex 中提供400K情境視窗，直到2026年10月14日停止支援為止。請善用 /compact、聚焦明確的提示詞與 @file 參照，主動管理 token 預算。⁸³¹¹²

本指南的使用方式

這是一份超過3,300行的參考指南，請從符合自身經驗程度的部分開始：

文末的快速參考卡提供所有主要命令一目瞭然的摘要。

發行重點：近期變更

以下按版本逐一記錄 Codex 的發行進程，並由新到舊排列。初次接觸？請直接前往「快速入門」；以下內容不影響您開始有效運用 Codex。驗證細節（版本比較、提交清單、文件檢查）收錄於註腳。

目前狀態

截至2026年9月26日的Codex CLI

• 穩定版：v0.157.1，於9月26日發布（npm latest）；這是在v0.157.0（9月25日）之上的Windows修補版本。
• Alpha版：npm alpha目前為0.159.0-alpha.4。0.158系列並未推出穩定版本。
• 自v0.157.0起預設啟用：全螢幕逐字稿、背景伺服器自動啟動，以及Guardian執行緒情境。若要停用其中一項，請在[tui]下設定fullscreen_transcript = false、在[features]下設定daemon_auto_start = false（或以--no-daemon啟動），或在[features.guardianv2]下設定thread_context = false。
• 自v0.156.0起預設啟用：/voice、受管理的worktrees，以及Guardian父層壓縮重用（[features]鍵值為realtime_conversation、worktrees、guardian_reuse_parent_compaction）。
• 仍須選擇啟用或屬於實驗性功能：實驗性情境管理、Codex Cloud，以及code mode。
• 模型：GPT-6 Sol（gpt-6-sol）適合日常與複雜的程式開發工作，GPT-6-Astra適合最艱鉅的端對端工作（未設定模型時，仍是CLI內建的預設模型），GPT-6 Luna則適合大量作業。使用ChatGPT登入Codex時，GPT-5.5將於2026年10月14日退出。
• 鎖定版本：npm install -g @openai/codex@0.157.1，接著以codex --version確認。¹⁷¹¹⁷²

v0.157.1（2026年9月26日）

這是從main反向移植4項修正的Windows修補版本。Codex啟動code-mode主機或本機stdio MCP伺服器時，不再開啟主控台視窗。當Windows將處理程序置於外層作業物件中時，背景伺服器仍可啟動；分離的背景伺服器也不再持續占用啟動器的輸出管線，以免啟動器退出後，呼叫它的命令仍停滯等待。GitHub發行說明與變更日誌項目只表示「無法確定」重點；以上清單來自該版本的提交記錄。

建議做法：若您在Windows上執行Codex，請升級。這4項修正僅適用於Windows。¹⁷¹

v0.157.0（2026年9月25日）

此版本將另外3項功能改為預設啟用。

• 全螢幕逐字稿預設啟用。v0.156.0透過/tui提供的全螢幕UI，現在成為工作階段開啟時的預設介面，即使設定中沒有[tui]區段亦然。若要保留終端機回捲內容，請在/tui中選擇Scrollback，或在[tui]下設定fullscreen_transcript = false；--no-alt-screen與tui.alternate_screen = "never"仍具有優先權。現在按住Shift並按一下，可延伸逐字稿的選取範圍。
• 背景伺服器會自動啟動，適用於符合條件的互動式啟動方式，而且此選項已移出/experimental。使用--no-daemon、--oss、--profile或大多數-c覆寫值啟動時，不會使用背景伺服器。若執行中伺服器的設定與工作階段不符，Codex會提供3種選擇：不使用伺服器繼續執行、依所需設定重新啟動，或取消（預設選項）。若要停用自動啟動，請在[features]下設定daemon_auto_start = false。
• Guardian執行緒情境預設啟用，同步與非同步審查皆適用，且不受Guardian v2的enabled切換設定影響。若要停用，請在[features.guardianv2]下設定thread_context = false。

模型方面：最初隨v0.156.1推出的GPT-6 Sol與Luna也包含在此版本中；Amazon Bedrock目錄現已納入兩者，並由GPT-6 Sol取代GPT-5.6 Sol成為Bedrock預設模型。GPT-5.6 Sol不再提供ultrafast服務層級，只保留Fast。內建目錄也不再將GPT-6-Astra標示為支援實驗性情境管理（請參閱情境管理）。

其他新增項目：快捷鍵f可分支在其他應用程式中開啟的對話，並保留草稿與佇列中的提示詞；/import可用於遠端和背景伺服器工作階段；終端機可呈現Unicode項目符號、核取方塊及對齊的方程式。修正項目包括：切換執行緒時維持語音對話、回合結束時復原尚未送出的回答、遵循tmux滑鼠設定、透過已設定的Proxy路由即時連線與獨立網頁搜尋、以5分鐘逾時重試暫時失敗的檔案上傳，以及在重新導向、開放式HTTP和WebSocket連線中全面強制執行網路限制。在Windows上，沙箱物件的存取範圍僅限於執行器的登入工作階段。¹⁷¹

v0.156.1（2026年9月23日）

這是僅含一項變更的修補版本，將GPT-6 Sol與GPT-6 Luna帶入穩定版CLI。兩者現在會出現在/model選擇器中，排列於GPT-6-Astra之後；GPT-6-Astra仍位居第一，且在config.toml未設定模型時，繼續作為內建預設模型。選擇器將GPT-5.6系列重新標示為舊款模型（GPT-5.6 Sol顯示為「適用於複雜工作的舊款程式開發模型」），並將GPT-5.5標示為「舊版程式開發模型」。當您接近速率限制時，切換提示現在會建議gpt-6-luna，而非gpt-5.6-luna。

若設定指定的是舊款模型，將出現一次性的移轉提示：已儲存的gpt-5.6-sol、gpt-5.6-terra、gpt-5.5及gpt-5.4選項會改指向GPT-6 Sol，而gpt-5.6-luna與gpt-5.4-mini則改指向GPT-6 Luna。Amazon Bedrock目錄在此版本中沒有變更：其中不含GPT-6 Sol或Luna，GPT-5.6 Sol仍是Bedrock預設模型。

文件未提及的一項成本細節：內建目錄將Fast（priority）設為GPT-6 Sol與Luna的預設服務層級。因此，未設定service_tier的TUI工作階段可能以Fast模式啟動；使用ChatGPT登入時，其計費為Standard點數的2.5倍。請使用/fast status檢查；/fast off可切換至Standard。

建議做法：升級後，在熟悉的工作上試用codex -m gpt-6-sol。可用性取決於您的方案、工作區設定及推出進度；Enterprise管理員必須先啟用新模型。¹⁶⁸

v0.156.0（2026年9月22日）

此版本一次將3項功能改為預設啟用；文件變更日誌也在同一天公布前2項。

• 語音預設啟用。在支援的版本中，/voice可直接啟動即時對話，無須先前往/experimental。同步新增的功能包括：可設定的F8切換快捷鍵、用於選擇後續對話語音的/voice settings選擇器、Linux與Windows適用的內建語音執行階段，以及減少動態效果支援。
• 受管理的worktrees預設啟用。--worktree與/worktree不再需要功能旗標。Worktree工作階段可連接既有的本機daemon，也可從代理程式總覽建立。
• Guardian父層壓縮重用預設啟用：Guardian重新啟動審查工作階段時，可重用父執行緒的加密壓縮內容。

各項功能的停用方式，請參閱斜線命令表中的/voice與/worktree列，以及Guardian章節。

其他新增項目：透過/tui選用的全螢幕TUI，具備逐字稿搜尋、滑鼠選取與複製、按右鍵複製、可點選連結，以及警告檢視器；/theme選擇器內含6款主題；/usage分析儀表板；在終端機中呈現Mermaid圖表與TeX數學式，兩者各有獨立切換設定；/daemon選單與--no-daemon旗標；以及新TUI執行緒預設停用推理摘要。安全性修正彌補Windows沙箱在傳入流量、特殊權限Socket及唯讀檔案控制代碼方面的缺口，且codex doctor不再於錯誤中回顯設定值。錯誤修正則可在回合失敗或中斷後保留串流回答、修復tmux與SSH中的剪貼簿轉送、於繼續工作階段時還原Plan mode，並讓登入流程可透過系統Proxy復原。¹⁶⁶

v0.155.1（2026年9月18日）

這是僅含一項修正的緊急修補版本。在0.155.0中，若新的本機TUI執行緒未於設定內指定model_reasoning_summary，系統會要求detailed摘要；不支援推理摘要的供應商則會直接拒絕該要求。0.155.1恢復以none作為備援值，因此未設定此鍵時不會要求摘要。明確設定的auto、concise及detailed向來都會生效，現在亦然。相同的單行變更也已併入main，並隨0.156.0發布。

建議做法：若0.155.0的新TUI工作階段在非OpenAI或自行託管的供應商上失敗，請升級。若需要摘要，請明確設定此鍵（請參閱設定參考資料）。¹⁵⁵

v0.155.0（2026年9月17日）

語音以實驗性選擇啟用功能之姿進入穩定版TUI：在支援的版本中，透過/experimental啟用後，/voice可開啟含串流逐字稿與麥克風控制項的即時對話，另有可設定的靜音快捷鍵，且macOS套件內含已簽署的語音資源。5天後，v0.156.0將此功能改為預設啟用。此版本的受管理worktrees仍預設停用。

0.155.0亦包含：

• MCP使用者驗證：在支援的Mac本機TUI工作階段中，使用由Secure Enclave簽署的Touch ID驗證MCP要求，並具備工作區範圍的身分限制，以及MCP工具接續流程中的原生驗證。
• 移除Windows的/sandbox-add-read-dir斜線命令。
• Worktree管理：在代理程式總覽中隱藏、封存及刪除worktree工作階段、查看擁有權詳細資料，並在刪除乾淨的受管理worktree前要求確認。
• 即時推理摘要會串流顯示於TUI狀態列，已完成的工作則會顯示完成時間戳記。
• Daemon：可設定更新排程、codex app-server daemon update命令，以及daemon重新啟動後的執行緒復原。
• Amazon Bedrock AWS憑證命令，以及與穩定版CLI發行同步的Python SDK發布作業。

安全性修正封堵WSL互通逸出與Shell快照憑證暴露問題。Memory v2目前僅提供儲存與整併的基礎能力，尚非可用功能。¹⁵³

v0.154.0（2026年9月9日）

此版本約在0.154.0-alpha.6的時間點切出，因此首次出現在alpha.7的所有項目（即時TUI語音、MCP使用者驗證、Memory v2、daemon自動更新設定、推理強度鎖定）皆延至0.155。

已移除：codex mcp-server與獨立的codex-mcp-server二進位檔。請將整合移至app-server通訊協定或Claude Code適用的Codex plugin；用於將Codex連接至外部MCP伺服器的codex mcp不受影響（請參閱「將Codex作為MCP伺服器執行」）。舊版Guardian核准審查路徑也已移除；當新的使用者指示使核准失效時，系統現在會拒絕核准。

新增項目：

• 實驗性受管理worktrees，可透過--worktree或/worktree使用，並支援codex exec及TUI worktree瀏覽器。
• 非同步使用者訊息：Codex持續工作時，您可以回答內嵌問題，且不會遺失草稿。
• Windows服務支援：沙箱佈建、Windows上的app-server daemon，以及受管理的daemon更新。
• 遠端權限設定檔：由應用程式伺服器探索，並可在TUI中依名稱選取。
• Vim R取代模式、即時情境壓縮狀態，以及在工作階段啟動時依模型能力控管的實驗性情境管理。

安全性方面：PATH輔助工具不再於建立工作區信任前執行，macOS沙箱也已強化，可防範終端機輸入注入。MCP連線會協調OAuth權杖重新整理；遠端繼續與分支操作會保留已儲存的權限；繼續在其他應用程式中開啟的對話時，則會顯示唯讀逐字稿。語音僅以執行階段基礎架構的形式發布，最早一批Daybreak程式碼參照也已加入，但尚無公開文件。¹⁴⁹¹⁵⁰

v0.153.3與v0.153.4（2026年9月4日）

這兩個同日推出的修補版本將GPT-6-Astra正式帶入CLI。v0.153.3將Astra加入Amazon Bedrock目錄（GPT-5.6 Sol仍是Bedrock預設模型），並修正Astra的非同步釐清指引。v0.153.4則將Astra加入模型選擇器，使其成為未設定模型時的內建預設模型，並依工具可用性限定非同步問題指引的適用範圍。

建議做法：自v0.153.1起，可使用-m gpt-6-astra執行Astra；自v0.153.4起，Astra會出現在選擇器中。由於文件未載明最低CLI版本，請將這兩個版本分別視為最低門檻。若您的帳戶無權使用內建預設值所選的模型，請在config.toml中明確設定model，不要仰賴預設值。^142143144145

v0.153.1與v0.153.2（2026年9月3日）

v0.153.1讓Guardian的Computer Use評分遵循模型需求：只有在作用中模型的中繼資料設定node_repl_auto_review_required時，才會執行僅限Computer Use的評分與快速核准決策。若切換模型後略過評分，先前或進行中的分數都會失效，因此切換回原模型也無法恢復過時的核准。發行說明僅列出一項反向移植的GPT-6-Astra目錄項目，可透過API設定；選擇器與預設值直到v0.153.4才變更。v0.153.2將Astra Fast層級的說明由「1.5倍」修正為「2倍速度、提高用量」（僅變更顯示文字）。¹³⁹¹⁴⁰

v0.153.0（2026年9月3日）

• Vim復原與重做：u及Ctrl+R可還原完整的編輯器草稿，包括貼上的內容與圖片附件；vim_normal.redo是可設定的按鍵對應動作。
• 遠端plugin市集：plugin CLI可列出、安裝及移除遠端plugins，而codex plugin list會顯示來源、版本、安裝政策及驗證政策。
• tui.auto_recap = false可停用自動回顧；手動/recap仍可使用。
• Plus與Team的速率限制警告會更早出現，在約5小時的時間窗內，剩餘額度低於一半時即發出警告；其他方案仍採用75/90/95%的門檻。
• Guardian範圍會遵循核准模式：Full Access會略過僅需確認之動作的Guardian審查，而User核准模式則會略過背景評分與預熱。
• features.context_management.experimental_mode（預設停用）可為Codex後端上符合資格的Plus、Pro及Pro Lite工作階段啟用權杖預算情境、歷史記錄附註及new_context工具。
• tui.disable_paste_burst取代頂層鍵值，後者仍可作為備援。

修正項目：app-server中斷連線後，TUI工作階段可重新連線並保留草稿；Guardian審查歷程可在壓縮、重新啟動及分支後保留；記住的MCP核准則會限定於所選帳戶。¹³⁷

v0.152.0與v0.152.1（2026年9月1日）

update_plan改為選擇啟用：tools.update_plan.enabled預設為false；停用時，內建的update_plan指引會從模型、協作模式、多代理程式、壓縮、預熱及目標接續提示詞中移除（請參閱「Plan Mode與協作」）。其他新增項目包括：使用/與?進行Vim搜尋，搭配n/N並可與操作指令組合，新草稿則以Insert模式開始；可採取行動的速率限制橫幅；憑證重新整理進度，包括Amazon Bedrock重新驗證；套件樣式的MCP伺服器名稱（允許使用:、@、/及.）；MCP openai/elicitation表單要求；各工具專屬的MCP output_token_limit；雲端任務憑證僅限受信任來源；可設定的thread/shellCommand逾時；以及透過模型中繼資料預設啟用的權杖預算。v0.152.1讓Guardian核准審查可從模型中繼資料取得Node REPL政策。¹³⁵¹³⁶

v0.151.0（2026年8月29日）

• /recap可依需求摘要對話，Codex也會自動回顧符合條件且處於閒置、未聚焦狀態的對話。
• Code-mode主機移除WebSocket傳輸方式（僅保留stdio與gRPC）。
• 在儲存區支援的情況下，持久執行緒預設使用分頁歷程。
• persistent推理強度隨時鐘工具與內建主動性指引一同推出。
• Guardian v2預設使用含圖片的Computer Use審查。
• Vim新增f/F/t/T尋找與移至前一字元動作，以及gg/G。
• 輸入至已提升權限的終端機時，可要求重新核准（write_stdin_approval，預設停用）。
• 可設定選用MCP伺服器的寬限期（mcp_optional_startup_grace_ms，預設1,000毫秒），且擴充功能可檢查或取代MCP工具結果。

修正項目可防止/cd削弱沙箱限制，也可避免過時的Guardian分類在權限變更後授權動作。發行說明只列出最後幾項PR；完整變更集請參閱版本比較。[^221]¹³²

v0.150.0與v0.150.1（2026年8月26日至27日）

Hooks新增Interrupt事件，當作用中的頂層回合中斷時執行（預設逾時1秒，上限3秒，絕不套用於子代理程式）。/copy會開啟選擇器，可選擇完整回答、個別程式碼區塊或區塊引文。任務可透過@提及方式指定，代理程式可讀取、建立及傳訊給任務，而/rename會建議可編輯的標題。Markdown連結會呈現為可點選標籤，快捷鍵可循環切換權限模式，Vim新增.重複動作，而且不受信任的專案不再提供專案層級AGENTS.md指示。features.network_proxy.credential_broker與Guardian v2的review_scope.computer_use_only成為可設定且預設停用的功能。v0.150.1會將保留的圖片計入遠端壓縮的權杖預算。[^218][^219]

v0.149.0與v0.149.1（2026年8月20日至24日）

untrusted核准政策已退役；設定中若使用此名稱，請改為on-request。新增項目包括：互動式codex agents儀表板、/cd、/pwd及/cwd、用於向既有本機或遠端工作階段傳訊的codex queue、更多Vim變更動作、更全面的codex doctor（端點保護、網路與Proxy失敗、桌面應用程式狀態、更新連線能力），以及SDK中的max/ultra推理強度。繼續及分支的執行緒會還原其權限設定檔。v0.149.1新增codex exec --thread-source <SOURCE>（user、subagent、memory_consolidation或功能名稱；TypeScript SDK中為threadSource）。

同一期間的定價變更：OpenAI自8月21日起將GPT-5.6 Sol價格調降超過20%，為期3個月（至少持續至2026年11月21日）；Sol每100萬個輸入、快取及輸出權杖的Codex點數費率，也從125/12.5/750降至100/10/500。^120121126

v0.147.0與v0.148.0（2026年8月7日至18日）

v0.147.0移除codex exec --full-auto（自v0.128起已棄用）；請改用--sandbox workspace-write搭配核准旗標或設定檔。此版本也新增--approve-for-me、可攜式Agent Plugins及跨目錄搜尋、選擇啟用的MCP 2026-07-28通訊協定，以及對話區段。v0.148.0新增以/export匯出至Markdown、codex exec fork、/status中的預估點數或成本、作為內建供應商的Amazon Bedrock Runtime、非同步及會叫用MCP的hooks，以及在路徑遭拒絕或無法讀取時依安全原則拒絕的沙箱限制。¹¹⁶¹¹⁸

較早版本（2026年5月至7月）

• v0.146.0與v0.146.1（7月29日、8月5日）：已設定的Proxy涵蓋所有傳輸方式；Agent Plugins資訊清單，以及Amazon Bedrock與Claude Code市集；可命名工作階段並釘選執行緒；由執行器提供的skills；針對具備網路能力的模型，強化自動審查的預設設定。¹¹⁴¹¹⁵
• v0.145.0（7月21日）：除了Claude Code之外，也支援從Cursor使用/import；語音以串流即時V3對話回歸；選擇啟用的多代理程式v2體驗趨於穩定；實驗性分頁執行緒歷程與Amazon Bedrock登入；內建GPT-5.4選項移轉至GPT-5.6 Terra與Luna。v0.144.6將GPT-5.6情境視窗設為272,000個權杖。¹¹¹¹¹²
• v0.140.0（6月15日）：/usage、codex delete與/delete、從Claude Code使用/import、統一的@提及選單、Amazon Bedrock API金鑰驗證，以及用於CLI和MCP OAuth憑證的加密本機儲存空間；舊版/realtime語音控制項已移除。¹⁰²
• v0.139.0（6月9日）：code mode可直接呼叫網頁搜尋，工具結構描述會保留oneOf/allOf，codex doctor會回報編輯器與分頁器詳細資料，市集來源則會出現在JSON輸出中。¹⁶²
• v0.138.0（6月8日）：/app會將CLI工作階段交給桌面應用程式，而且多代理程式v2會加密父層傳至子代理程式的任務文字。¹⁶³¹⁰⁸
• v0.137.0（6月4日）：多代理程式v2、F13-F24 TUI按鍵繫結，以及v1 skills擴充功能。¹⁶⁴
• v0.132.0至v0.135.0（5月20日至28日）：本機對話歷程搜尋、以--profile作為主要設定檔選擇器、預設啟用目標、權限設定檔繼承與受管理的requirements.toml、codex remote-control啟動與停止、更豐富的codex doctor和/status、Vim文字物件、/permissions中的具名權限設定檔、Python SDK驗證與Sandbox預設集，以及codex exec resume --output-schema。5月21日的應用程式更新新增Appshots、正式推出Goal mode，以及選擇啟用的鎖定Computer Use。^{96979899100101173}

舊版--full-auto已於v0.147.0移除，js_repl也仍處於移除狀態。^86878991116

穩定性說明：穩定且已有文件記載的功能包括：核心CLI與TUI、沙箱與核准政策、config.toml、AGENTS.md、skills、hooks、plugins、多代理程式工具、目標、權限設定檔、/voice與受管理的worktrees（自v0.156.0起為預設），以及全螢幕逐字稿與背景伺服器自動啟動（自v0.157.0起為預設）。Browser、Computer Use及Appshots是已有文件記載的使用者功能，其可用性取決於平台與方案。實驗中或開發中的項目包括：Codex Cloud、code mode、實驗性情境管理、Memory v2、本機代理程式留言板，以及本指南中標示為[EXPERIMENTAL]或列於/experimental下的所有項目；這些功能可能隨版本變更。已移除項目：--full-auto（v0.147.0）、untrusted核准政策（v0.149.0）、codex mcp-server（v0.154.0）及js_repl。

Alpha頻道：alpha版本每天會發布數次，alpha系列的發行說明內容只是預留文字，且經常出現從較舊基礎版本切出的頻外組建（最近包括0.155.0-alpha.16.4、0.157.0-alpha.11.1、0.158.0-alpha.15.1及0.158.0-alpha.2.1）。npm alpha標籤至少曾有2次指向其中一個版本，導致@alpha安裝的組建比latest更舊。0.158系列從0.158.0-alpha.2（9月23日）推進至alpha.15（9月25日），但未發布穩定版本；9月25日，alpha標籤移至0.159系列，目前為0.159.0-alpha.4。若您追蹤alpha版本，請檢查npm view @openai/codex dist-tags，並安裝確切版本，不要使用@alpha。¹⁶⁹¹⁷²近期alpha系列如何演變為穩定版本的日期歷程收錄於¹⁷⁰。

Codex 的運作方式：心智模型

在深入探討各項功能之前，請先瞭解 Codex 的架構如何影響您的每一項操作。此系統由共用智慧層提供支援，並橫跨 5 個操作介面：

┌─────────────────────────────────────────────────────────┐
│                    CODEX SURFACES                       │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐   │
│  │   CLI    │  │ Desktop  │  │   IDE    │  │ Cloud  │   │
│  │ Terminal │  │   App    │  │Extension │  │  Tasks │   │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘   │
│  Local exec     Multi-task    Editor-native  Async      │
│  + scripting    + worktrees   + inline edits detached   │
│  ┌──────────┐                                           │
│  │ Browser  │  Signed-in browser workflows              │
│  │Extension │  (launched May 2026)                      │
│  └──────────┘                                           │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                        │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐     │
│  │   MCP   │  │ Skills  │  │  Apps   │  │  Search │     │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘     │
│  External tools, reusable expertise, ChatGPT            │
│  connectors, web search (cached + live)                 │
├─────────────────────────────────────────────────────────┤
│  SECURITY LAYER                                         │
│  ┌─────────────────────────────────────────────────┐    │
│  │    Sandbox (Seatbelt / Landlock / seccomp)      │    │
│  │    + Approval Policy (on-request → never)       │    │
│  └─────────────────────────────────────────────────┘    │
│  OS-level filesystem + network restrictions             │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                             │
│  ┌─────────────────────────────────────────────────┐    │
│  │         GPT-5.x-Codex Intelligence              │    │
│  │   Tools: Shell, Patch, Read, Web Search         │    │
│  │   (legacy artifact, read_file, grep_files       │    │
│  │    removed in v0.117.0)                         │    │
│  └─────────────────────────────────────────────────┘    │
│  Shared model across all surfaces; costs tokens         │
└─────────────────────────────────────────────────────────┘

核心層：所有功能皆由 GPT 模型系列驅動。截至2026年9月23日，目前這一代為 GPT-6：gpt-6-sol 適合日常與複雜的程式設計、gpt-6-astra 適合最艱鉅的端對端工作（未設定模型時，也是隨附 CLI 的預設模型），而 gpt-6-luna 則適合範圍明確的大量任務。GPT-5.6 模型（Sol、Terra、Luna）在推行期間仍可使用；gpt-5.5（在 Codex 中具備 400K 上下文，在 API 中則為 1M）將於2026年10月14日停止供透過 ChatGPT 登入的 Codex 使用，而 gpt-5.4 已於2026年8月31日退出 Codex。^{83117143145146168} 它會讀取檔案、寫入修補程式、執行 shell 命令，並針對您的程式碼庫進行推理。當上下文容量用盡時，Codex 會壓縮對話以釋出空間。此層會消耗 token。

安全層：Codex 執行的每個命令都會通過作業系統層級的沙箱。在 macOS 上，由 Apple 的 Seatbelt 框架強制執行核心層級的限制。在 Linux 上，Landlock + seccomp 會篩選檔案系統與系統呼叫的存取權。沙箱是在核心層級運作，而非容器內部。接著，核准原則會決定何時要求人工確認。

擴充層：MCP 可連接外部服務（GitHub、Figma、Sentry）。skills 將可重複使用的工作流程封裝起來，供 Codex 視需要載入。Apps 可連接至 ChatGPT connectors。網頁搜尋則可從網際網路加入即時上下文。

操作介面層：CLI 適合終端機進階使用者與自動化作業。Desktop app 適合多執行緒專案管理。IDE extension 適合編輯、編譯、測試的緊密循環。Cloud 則用於獨立執行的非同步任務。

關鍵觀念：多數使用者只會使用一種操作介面。進階使用者則會運用全部 5 種：以 Cloud 處理長時間執行的任務、透過 CLI 進行可預期的儲存庫操作、運用 IDE extension 建立緊密的程式設計循環、使用 desktop app 規劃與協調工作，並透過 browser extension 執行需要登入的瀏覽器工作流程。

目錄

1. 如何安裝 Codex？
2. 快速開始：您的第一個工作階段
3. 核心互動介面
4. 深入解析設定系統
5. 該選擇哪個模型？
6. Codex 的費用是多少？
7. 決策框架
8. 沙箱與核准系統如何運作？
9. AGENTS.md 如何運作？
10. Hooks
11. 什麼是 MCP（Model Context Protocol）？
12. Code Mode
13. JavaScript REPL 執行階段
14. 什麼是 Skills？
15. Plugins
16. Plan Mode 與 Collaboration
17. 記憶系統
18. 工作階段管理
19. 非互動模式（codex exec）
20. Codex Cloud 與背景任務
21. Codex Desktop App
22. GitHub Action 與 CI/CD
23. Codex SDK
24. 效能最佳化
25. 如何偵錯問題？——包括 codex doctor
26. 企業部署
27. 最佳實務與反模式
28. 工作流程範例
29. 遷移指南
30. 快速參考卡
31. 變更記錄
32. 參考資料

如何安裝 Codex？

套件管理工具

# npm (recommended)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# winget (Windows)
winget install OpenAI.Codex

# Upgrade to latest
npm install -g @openai/codex@latest

如何更新、降級或解除安裝 Codex CLI？

自v0.128.0起，Codex內建自我更新命令；其餘操作皆須透過原先安裝它的 套件管理工具執行。⁸⁶ 自v0.146.0起，發行成品、通道中繼資料與安裝程式別名皆由OpenAI代管的發行基礎設施提供，並以GitHub作為備援。¹¹⁴ 若您的網路允許清單已納入GitHub，以供Codex安裝與更新，請一併加入OpenAI發行主機。備援機制會讓允許清單遺漏的問題悄然降級，而非明確失敗。

# Check what you are running
codex --version                          # -> codex-cli 0.157.1
npm view @openai/codex version           # Latest published version

# Update
codex update                             # Built-in self-update (v0.128.0+)
npm install -g @openai/codex@latest      # Or update via npm
brew upgrade --cask codex                # Or via Homebrew

# Pin or downgrade to an exact version
npm install -g @openai/codex@0.144.6

# Uninstall
npm uninstall -g @openai/codex
brew uninstall --cask codex
winget uninstall OpenAI.Codex

當某個版本造成系統故障時，固定版本才是正確做法。 Codex採用快速更新的穩定版本線，因此 安裝確切版本是最快的回復方式——回報問題、固定版本，然後繼續工作。 請使用codex --version確認回復成功，因為若另一個安裝項目在 PATH中遮蔽了目前版本，系統仍會悄悄執行舊版二進位檔（codex doctor會在 Environment項目下明確標示此問題）。

解除安裝套件並不會移除您的狀態資料。 驗證資訊、設定與工作階段記錄 位於~/.codex/。若要在重新安裝後保留登入資訊與記錄，請將其留在原處； 只有在確實需要全新環境時才刪除——rm -rf ~/.codex也會一併捨棄config.toml、 auth.json及所有已儲存的工作階段。

直接安裝指令碼（v0.106.0以上）

macOS與Linux提供一行式安裝指令碼，可從GitHub發行資產取得：⁶⁰

curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | sh

此指令碼會自動偵測平台與架構、下載正確的二進位檔，並將其加入PATH。

下載二進位檔

若環境中沒有npm或Homebrew，請從GitHub Releases下載適用於各平台的二進位檔：¹

系統需求

• macOS：Apple Silicon或Intel（透過Seatbelt提供完整沙箱支援）
• Linux：x86_64或arm64（透過Landlock與seccomp提供沙箱）
• Windows：採用受限權杖的原生沙箱（自v0.100.0起由實驗性功能升格）。亦支援WSL²

驗證

codex login                  # Interactive OAuth (recommended)
codex login --device-auth    # OAuth device code flow (headless)
codex login --with-api-key   # API key from stdin
codex login status           # Check auth state (exit 0 = logged in)
codex logout                 # Clear stored credentials

有兩種驗證方式：

1. ChatGPT帳號（建議）：使用現有的Plus、Pro、Team、Business、Edu或Enterprise訂閱登入。可完整使用包括雲端任務在內的所有功能。
2. API金鑰：透過CODEX_API_KEY環境變數或codex login --with-api-key設定。部分功能（雲端執行緒）可能無法使用。

專家提示：可在config.toml中透過cli_auth_credentials_store設定憑證儲存方式。選項包括：file（預設）、keyring（作業系統鑰匙圈），或auto（若可用則採用鑰匙圈，否則改用檔案）。

Amazon Bedrock登入（v0.145.0，實驗性）： 對於透過Amazon Bedrock存取模型的團隊，除了既有的受管理API金鑰驗證（v0.140.0以上）與AWS憑證鏈之外，另提供支援自訂端點及驗證的實驗性登入方式（請參閱「自訂模型供應商」）。GPT-5.6 Sol是預設的Bedrock模型。¹¹² v0.150.0修正Amazon Bedrock模型的對話壓縮與多代理程式相容性。[^218] v0.151.0在符合資格的TUI登入流程中加入受功能旗標控管的Amazon Bedrock選項：新手引導會探索現有的AWS設定檔與環境憑證，並針對設定檔、存取金鑰、環境變數及Bedrock API金鑰提供手動設定方式；流程也會收集AWS區域、在輸入時遮蔽機密資訊，並在供應商變更後重新啟動內嵌伺服器。¹³² v0.152.0會顯示憑證重新整理進度：當模型供應商重新整理過期憑證時，TUI與codex exec會顯示進度，其中包括Amazon Bedrock工作階段的重新驗證。此功能由穩定的modelProvider/authRecoveryStarted與modelProvider/authRecoveryCompleted應用程式伺服器通知支援，通知中會包含執行緒、回合、供應商及使用者可見的訊息。¹³⁵

Shell自動補全

# Generate completions for your shell
codex completion bash > /etc/bash_completion.d/codex
codex completion zsh > ~/.zsh/completions/_codex
codex completion fish > ~/.config/fish/completions/codex.fish

驗證安裝

codex --version
# codex-cli 0.157.1

快速開始：您的第一個工作階段

只需5分鐘，即可從零開始投入實際工作。

1. 安裝並完成驗證：

npm i -g @openai/codex          # Install
codex login                      # Log in with your OpenAI account

2. 前往專案：

cd ~/my-project                  # Any git repo works

3. 啟動Codex：

codex

畫面會顯示互動式TUI。Codex會自動讀取您的專案結構。

4. 提出問題：

> What does this project do? Summarize the architecture.

Codex會讀取關鍵檔案並說明程式碼庫。這類問題不會造成任何變更——只有在您要求修改時，Codex才會修補檔案；是否必須事先詢問，則由沙箱與核准政策決定。

5. 進行變更：

> Add input validation to the login endpoint

Codex會以差異內容提出編輯建議。請檢閱後按y核准，或按n拒絕。

6. 使用slash command：

> /plan Refactor the database layer to use connection pooling

Codex會建立計畫，但不會執行。請先檢閱計畫，再核准開始執行。

7. 檢查成果：

> /diff

查看Codex在目前工作階段中所做的所有變更。

後續步驟： - 使用專案指示設定AGENTS.md（請參閱AGENTS.md如何運作？） - 為您的工作流程設定設定檔（請參閱設定檔） - 嘗試使用codex exec進行非互動式自動化（請參閱非互動模式）

核心互動介面

Codex 提供5種由相同智慧核心支援的不同介面。每個介面都針對不同的工作流程模式進行最佳化。

1. 互動式 CLI（終端機 UI）

codex                        # Launch TUI
codex "fix the failing tests" # Launch with initial prompt
codex -m gpt-6-sol          # Specify model
codex --sandbox workspace-write --ask-for-approval on-request

終端機 UI 是一套全螢幕應用程式，包含：

• 輸入框：輸入提示、使用 @ 附加檔案，或加上 ! 前綴執行 shell 命令
• 輸出窗格：串流顯示模型回應、工具呼叫及命令輸出
• 狀態列：顯示模型、token 使用量、git 分支及 sandbox 模式

主要 TUI 快捷鍵：

狀態列變更（v0.121.0）：狀態列中原有的情境視窗計量表，已改為顯示情境視窗使用程度的情境百分比指標。如果有指令碼或 hooks 會剖析狀態列，請留意這項格式變更。⁸² 當有新版本可用時，Codex 也會顯示 CLI 更新通知。

TUI 中可用的 Slash commands：

工作流程選擇器重新設計（v0.129.0）：重新設計的選擇器讓繼續與分支功能更容易找到；新的原始 scrollback 模式則可在需要逐字複製命令或模型輸出時，捲動瀏覽未經算繪的逐字稿。這在分流處理冗長的偵錯工作階段，或將輸出導向其他工具時格外實用。⁸⁹

統一的 @ mentions 選單（v0.140.0）：現在於輸入框中輸入 @，預設會開啟整合檔案、plugins 與 skills 的單一 mentions 選單，取代僅能附加檔案的流程——只需按1個按鍵，即可引用任何專案資源。¹⁰²

2. Codex Desktop App（macOS + Windows）

codex app                    # Launch desktop app (auto-installs if missing)

桌面版 app 提供 CLI 所沒有的功能：

• 多工處理：同時在不同專案中執行多個平行 agents
• Git worktree 隔離：每個執行緒都在 repo 的隔離副本上運作
• 行內 diff 審查：無須離開 app，即可暫存、還原及提交變更
• 整合式終端機：每個執行緒皆有可執行命令的終端機
• 對話分支：建立對話分支以探索不同方案
• 浮動彈出式視窗：將對話分離成可移動的視窗
• Automations：排程週期性任務（議題分流、CI 監控、警示回應）
• Appshots：將最前方的 Mac app 視窗附加至執行緒，並包含螢幕截圖及可用文字
• App 內瀏覽器留言：預覽本機或公開頁面、留下元件／區域留言，並讓 Codex 處理精確的視覺回饋
• Computer Use：讓 Codex 操作獲准的 Mac apps，以執行範圍明確的 GUI 工作；符合資格的遠端 Mac Computer Use 輪次可選擇啟用鎖定使用模式

由 GPT-Live 驅動的 ChatGPT Voice（desktop 26.715，2026年7月23日）：現在可透過語音操作桌面版 app——無須打字，即可一邊討論工作，一邊協調 Chat、Work 與 Codex 中的任務。在 macOS 上，開啟 Screen context 後，系統會將最前方視窗的 appshot 分享至對話，讓您直接詢問眼前所見，不必費心描述。此功能適用於 Plus、Pro、Business、Edu 及 Enterprise，可在桌面版 app 及 iOS 上的 Remote 使用。這是桌面介面的語音功能。CLI 另有獨立的語音功能：TUI 中的 /voice 即時對話（自 v0.156.0 起預設開啟），以及空白鍵聽寫（於 v0.105.0 以實驗性質新增）。¹¹³¹⁶⁶

共享執行緒快照（2026年8月20日）：在所有 Codex 方案中，macOS 桌面版 app 都能分享本機 Codex 執行緒的唯讀快照。原始執行緒變更時，快照不會隨之更新；個人帳戶產生的連結可供任何持有連結的人開啟，工作區帳戶產生的連結則僅限來源工作區的成員存取。Codex 會在分享前遮蔽已知的機密模式，但 OpenAI 仍提醒您審查共享內容，因為其中可能殘留敏感資訊。您可在 ChatGPT 資料控制項的 Shared links 下檢視或撤銷連結。¹²⁸

何時使用 app 或 CLI：需要協調多條工作線，或進行視覺化 diff 審查時，請使用桌面版 app。需要終端機可組合性、指令碼或 CI/CD 整合時，則使用 CLI。

3. IDE Extension（VS Code、Cursor、Windsurf）

Codex IDE extension 可直接整合至編輯器：

• 預設使用 Agent 模式：讀取檔案、進行編輯及執行命令
• 行內編輯：在使用中的檔案內提供情境感知建議
• 共享工作階段：工作階段會在 CLI 與 IDE extension 之間同步
• 相同的驗證方式：使用 ChatGPT 帳戶或 API key 登入

請從 VS Code Marketplace 或 Cursor／Windsurf extension 商店安裝。³

4. Codex Cloud [EXPERIMENTAL]

Cloud 任務會在 OpenAI 管理的環境中非同步執行：

• 送出後無須等待：將任務加入佇列，使其獨立於本機電腦執行
• 平行執行：同時執行多個 cloud 任務
• 建立 PR：Codex 會根據完成的工作建立 pull requests
• 套用至本機：使用 codex apply <TASK_ID> 將 cloud 結果拉取至本機 repo

codex cloud list             # List recent cloud tasks
codex apply <TASK_ID>        # Apply diff from a specific cloud task

也可從 chatgpt.com/codex 存取 Cloud 任務。⁴

5. Browser Extension（Chrome、Edge、Brave、Opera、Vivaldi）

Codex 提供適用於 Google Chrome、Microsoft Edge、Brave、Opera 及 Vivaldi 的 browser extension，與 CLI、桌面版 app、IDE extension 及 cloud 並列為第5種介面。此 extension 於2026年5月率先在 Chrome 推出；2026年8月25日的變更記錄新增其他4種瀏覽器，可從 ChatGPT 桌面版 app 的 Settings > Computer Use 進行設定。這5種瀏覽器皆支援分頁 mentions 及瀏覽器控制；Opera 不支援側邊聊天，因此其任務需從桌面版 app 啟動。此 extension 的設計宗旨是在您平常瀏覽網頁時從旁協助，而不是接管瀏覽器：Codex 會在背景跨分頁平行工作，而哪些網站可供其操作，始終由您掌控。⁹⁰¹²⁷

• 平行分頁執行：Codex 可同時操作多個分頁，且不會鎖定前景分頁。
• 個別網站控制：您可將允許 Codex 互動的網站加入許可清單；預設不開放任何存取權限。
• 以瀏覽器作為工作台：此 extension 最適合將頁面視為單一事實來源的 app 與網站工作，例如管理控制台、內部儀表板、內容管理 UI 及工單系統；它並非用來取代 CLI 處理本機 repos。
• 相同的智慧核心：browser extension 採用與其他介面相同的 GPT-5.x-Codex 智慧核心，因此，在 CLI 中有效的 AGENTS.md 或 skills 設定，也會將相同慣例帶入瀏覽器驅動的工作。

請從 browser extension 文件安裝；該頁面原名為 Codex for Chrome。¹²⁷

設定系統深入解析

Codex 使用 TOML 進行設定。理解優先順序至關重要，因為它決定設定發生衝突時，最終採用哪一項。

優先順序（由高至低）

1. 工作階段覆寫（最高）：CLI 旗標（--model、--sandbox、--ask-for-approval、--search、--enable/--disable、--profile）以及 -c key=value 覆寫
2. 專案設定（.codex/config.toml，從 CWD 向上搜尋至專案根目錄；以最近的目錄為準）
3. 使用者設定（$CODEX_HOME/config.toml，預設為 ~/.codex/config.toml）
4. 系統設定（Unix 上的 /etc/codex/config.toml）
5. 內建預設值（最低）

requirements.toml 是一個原則限制層，會在一般設定合併完成後，限制使用者可選取的值。請參閱企業部署。

設定檔位置

專家提示：CODEX_HOME 環境變數會覆寫預設的 ~/.codex 目錄，適合用於 CI/CD 或多帳號設定。

桌面版多資料夾專案（26.715，2026年7月23日）：ChatGPT 桌面應用程式中的本機專案現在可以橫跨數個相關資料夾，並將其中一個指定為主要資料夾（專案選單 → 編輯專案）。config.toml 的自動探索只會針對主要資料夾執行；次要資料夾仍可用於搜尋、讀取及編輯檔案，但不會提供任何設定。位於次要資料夾中的 .codex/config.toml 只是 Codex 能夠讀取的檔案，並非它會載入的設定。這是桌面應用程式的專案範圍界定，並未改變上述優先順序規則——CLI 仍會從目前工作目錄開始向上尋找，以解析專案設定。¹¹³

完整設定參考

# ~/.codex/config.toml — annotated reference

# ─── Model Selection ───────────────────────────────────
model = "gpt-6-sol"                    # Docs' example default; unset = bundled default (gpt-6-astra)
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_context_window = 272000           # Token count available to active model (override)
model_auto_compact_token_limit = 200000 # Threshold triggering automatic history compaction
model_reasoning_effort = "medium"       # minimal|low|medium|high|xhigh (model-dependent)
model_reasoning_summary = "auto"        # auto|concise|detailed|none
model_verbosity = "medium"              # low|medium|high
personality = "pragmatic"               # none|friendly|pragmatic
review_model = "gpt-6-sol"             # Optional model for /review command
service_tier = "fast"                  # Preferred service tier for new turns
oss_provider = "lmstudio"              # lmstudio|ollama (used with --oss)

# ─── Sandbox & Approval ───────────────────────────────
sandbox_mode = "workspace-write"        # read-only|workspace-write|danger-full-access
approval_policy = "on-request"          # on-request|never (untrusted retired in v0.149.0)

[sandbox_workspace_write]
writable_roots = []                     # Additional writable paths
network_access = false                  # Allow outbound network
exclude_tmpdir_env_var = false          # Exclude $TMPDIR from sandbox
exclude_slash_tmp = false               # Exclude /tmp from sandbox

# ─── Web Search ────────────────────────────────────────
web_search = "live"                     # Web search mode (constrained by allowed modes)

# ─── Tools ─────────────────────────────────────────────
tools.update_plan.enabled = false       # Planning tool opt-in (v0.152.0); exposes update_plan when true

# ─── Instructions ──────────────────────────────────────
developer_instructions = ""             # Additional injected instructions
model_instructions_file = ""            # Custom instructions file path
compact_prompt = ""                     # Custom history compaction prompt

# ─── Shell Environment ─────────────────────────────────
allow_login_shell = false               # Allow login shell semantics (loads .profile/.zprofile)

[shell_environment_policy]
inherit = "all"                         # all|core|none
ignore_default_excludes = false         # Set true to keep KEY/SECRET/TOKEN vars
exclude = []                            # Glob patterns to exclude
set = {}                                # Explicit overrides
include_only = []                       # Whitelist patterns

# ─── Authentication ────────────────────────────────────
cli_auth_credentials_store = "file"     # file|keyring|auto
forced_login_method = "chatgpt"         # chatgpt|api
mcp_oauth_callback_port = 0            # Fixed port for MCP OAuth callback (0 = random)
mcp_oauth_credentials_store = "auto"   # auto|file|keyring

# ─── History & Storage ─────────────────────────────────
[history]
persistence = "save-all"                # save-all|none
max_bytes = 0                           # Cap size (0 = unlimited)

tool_output_token_limit = 10000         # Max tokens per tool output (global; per-tool MCP overrides in v0.152.0)
log_dir = ""                            # Custom log directory
sqlite_home = ""                        # Override SQLite-backed resumable state location

# ─── UI & Display ──────────────────────────────────────
file_opener = "vscode"                  # vscode|vscode-insiders|windsurf|cursor|none
hide_agent_reasoning = false
show_raw_agent_reasoning = false
check_for_update_on_startup = true

[tui]
notifications = false                   # Enable notifications
notification_method = "auto"            # auto|osc9|bel
animations = true
show_tooltips = true
alternate_screen = "auto"               # auto|always|never
status_line = ["model", "context-remaining", "git-branch"]

# ─── Project Trust ─────────────────────────────────────
project_doc_max_bytes = 32768           # Max AGENTS.md size (32 KiB)
project_doc_fallback_filenames = []     # Alternative instruction filenames
project_root_markers = [".git"]         # Project root detection

# ─── Feature Flags ─────────────────────────────────────
# Use `codex features list` for current names/stages/defaults.
[features]
shell_tool = true                       # Shell command execution (stable)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
enable_request_compression = true       # zstd request compression where supported (stable)
fast_mode = true                        # Service-tier selection and Fast-tier commands (stable)
goals = true                            # Goal mode; stable and on by default in v0.133.0+
hooks = true                            # Lifecycle hooks (stable)
multi_agent = true                      # Enable multi-agent collaboration tools (stable)
personality = true                      # Personality selection (stable)
plugins = true                          # Plugin system (stable)
plugin_hooks = true                     # Plugin-bundled hooks (stable)
plugin_sharing = true                   # Workspace plugin sharing (stable)
browser_use = true                      # In-app browser automation (stable)
browser_use_external = true             # Browser-extension browser use (stable)
computer_use = true                     # macOS Computer Use (stable, plan/region gated)
in_app_browser = true                   # Shared rendered-page preview (stable)
image_generation = true                 # Image-generation tool (stable)
guardian_approval = true                # Auto-review approval path (stable)
skill_mcp_dependency_install = true     # Prompt/install missing skill MCP deps (stable)
tool_suggest = true                     # Tool/plugin suggestion surface (stable)
workspace_dependencies = true           # Workspace dependency discovery (stable)
memories = true                         # Memories (experimental)
network_proxy = false                   # Sandboxed-command network proxy (experimental); boolean or table, see below
prevent_idle_sleep = true               # Keep machine awake during active turns (experimental)
terminal_resize_reflow = true           # Terminal reflow improvements (experimental)

# Removed or deprecated feature names still appear in `codex features list`
# for migration diagnostics. Do not set removed flags such as
# `collaboration_modes`, `request_rule`, `codex_git_commit`,
# `apply_patch_freeform`, `search_tool`, or `js_repl` in new configs.

# ─── Multi-Agent Roles (v0.102.0+) ───────────────────
[agents]
max_threads = 4                         # Maximum concurrent agent threads

[agents.explorer]
description = "Read-only codebase navigator"
config_file = "~/.codex/profiles/explorer.toml"

# ─── Notifications ────────────────────────────────────
notify = ["terminal-notifier", "-title", "Codex"]  # Command for notifications

# ─── Per-Project Overrides ────────────────────────────
[projects."/absolute/path/to/repo"]
trust_level = "trusted"                 # Per-project trust override

features.network_proxy 的型別為 boolean | table。布林形式只會啟動或停止 Proxy；表格形式則包含原則。此 Proxy 負責對沙箱化命令強制執行權限設定檔中的網域規則：若將其關閉，[permissions.<name>.network] 網域規則便不會生效，命令將直接存取網路。它不會篩選網頁搜尋、應用程式、MCP servers 或其他託管工具。¹³⁰

[features.network_proxy]
enabled = true
allow_local_binding = false
proxy_url = "http://127.0.0.1:3128"

[features.network_proxy.domains]
"api.github.com" = "allow"
"*.npmjs.org" = "allow"          # subdomains only
"**.example.com" = "deny"        # apex plus subdomains; deny wins on conflicts

requirements.toml 中由管理員管理的 experimental_network 要求，無須 features.network_proxy 即可啟動 Proxy。¹³⁰

設定檔

為不同工作模式命名的設定預設組合。自 Codex 0.134.0 起，每個設定檔都是獨立檔案——~/.codex/<name>.config.toml，且只包含頂層鍵——而 --profile <name> 會將該檔案疊加至 ~/.codex/config.toml。系統不再讀取 config.toml 中舊有的 [profiles.<name>] 表格與頂層 profile = "<name>" 選擇器；若仍殘留 [profiles.<name>] 表格，--profile <name> 將拒絕啟動，直到您將其中的鍵移至設定檔為止。¹²²

# ~/.codex/fast.config.toml
model = "gpt-6-luna"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

# ~/.codex/careful.config.toml
model = "gpt-6-astra"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"   # `untrusted` retired in v0.149.0
sandbox_mode = "read-only"

# ~/.codex/auto.config.toml
model = "gpt-6-sol"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

設定檔位於基礎使用者設定之上、專案與 CLI 設定之下，因此只需包含與基礎設定不同的值。¹²²

啟用設定檔：

codex --profile fast "quick refactor"
codex --profile careful "security audit"
codex -p auto "fix CI"

專家提示：在設定的頂層加入 profile = "fast"，即可設定預設設定檔。若要針對個別工作階段覆寫，請使用 --profile。

自訂模型提供者

連線至 Azure、AWS Bedrock、本機模型或 Proxy 服務：

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
wire_api = "responses"
query_params = { api-version = "2025-04-01-preview" }
env_key = "AZURE_OPENAI_API_KEY"

# Built-in amazon-bedrock provider (v0.123.0+, first-class in v0.124.0+)
# AWS SigV4 signing + credential-based auth; AWS profile selectable via the
# nested `aws.profile` field (NOT a top-level `aws_profile` key).
# v0.130.0+ also accepts credentials from `aws login` (the AWS console-login
# flow) — Codex resolves the cached console-login session for the chosen
# profile if static keys are absent.
# v0.140.0+ adds managed Amazon Bedrock API-key authentication, and stores
# CLI and MCP OAuth credentials in encrypted local storage.[^184]
[model_providers.amazon-bedrock]
name = "Amazon Bedrock"

[model_providers.amazon-bedrock.aws]
profile = "default"                   # any profile from ~/.aws/credentials
# Region/credential resolution otherwise follows the standard AWS chain;
# v0.130.0 added support for `aws login` console-login profiles in addition
# to static access keys and IAM role assumption.[^168]

[model_providers.ollama]
name = "Ollama (Local)"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

警告：chat/completions 有線 API（wire_api = "chat"）已不建議用於 OpenAI 託管的模型，OpenAI 並已宣布將於2026年2月移除。³⁴ 本機提供者（Ollama、LM Studio）可能仍接受此格式。對於 OpenAI 端點，請改用 wire_api = "responses"。

使用 --oss 旗標來使用本機模型：

codex --oss "explain this function"               # Uses default OSS provider
codex --oss --local-provider lmstudio "explain"   # Explicit LM Studio
codex --oss --local-provider ollama "explain"      # Explicit Ollama

或在設定中指定：

model_provider = "oss"
oss_provider = "lmstudio"   # or "ollama"

行內設定覆寫

從命令列覆寫任意設定值：

codex -c model="gpt-5.5" "refactor the API"
codex -c 'sandbox_workspace_write.network_access=true' "install dependencies"
codex -c model_reasoning_effort="xhigh" "debug the race condition"

我該選擇哪個模型？

可用模型（2026年9月）

GPT-5.5（2026年4月23日）推出時，是 OpenAI 建議多數 Codex 任務採用的模型：複雜程式設計、電腦操作、知識工作與研究工作流程。自4月23日起，ChatGPT Plus／Pro／Business／Enterprise／Edu／Go 使用者可在 Codex CLI／網頁／桌面版中使用；4月24日起則可在 OpenAI API中使用。上下文視窗：Codex 中為400K，API中為1M——Codex 將視窗上限設為400K，以兼顧各訂閱層級的吞吐量與成本；API則提供完整的1M。定價（API）：每MTok輸入$5／輸出$30（GPT-5.4費率的2倍；OpenAI 表示，考量權杖效率提升後，實際增幅約為20%）。基準測試：Terminal-Bench 2.0為82.7%（當時公開可用模型中的最新頂尖成績）、GDPval為84.9%（44種職業）、OSWorld-Verified為78.7%、Tau2-bench Telecom為98.0%（未進行提示詞調校）。OpenAI 在推出前曾於內部使用 GPT-5.5 + Codex 重寫服務基礎架構，讓權杖產生速度提升20%。⁸³

透過 ChatGPT 登入時，GPT-5.5將於2026年10月14日從 Codex 退役——模型文件將退役範圍界定為所有方案中的 ChatGPT、ChatGPT Work 與 Codex（包括消費者、Business、Enterprise 與 Edu），並明確指出不影響 OpenAI API。¹⁵² GPT-6 推出後，替代指引亦有所調整：Plus、Pro、Business、Enterprise 與 Edu 方案應選擇gpt-6-sol；Free 與 Go 方案則在桌面應用程式中選擇gpt-6-luna，兩者皆須視「何時可用」而定。請在工作區預設值、已儲存的模型設定、受管理設定、自訂代理、排程任務與指令碼中取代gpt-5.5。¹⁶⁸

透過 ChatGPT 登入時，GPT-5.4與 GPT-5.4 mini 已於2026年8月31日從 Codex 退役。¹¹⁷ 模型文件目前指定gpt-6-sol與gpt-6-luna為替代模型（Enterprise 與 Edu 須先由管理員啟用 Luna）；使用API金鑰則不受影響。⁶⁴¹⁶⁸ 實際模型清單會因帳戶與推出進度而異。請檢查本機快取：~/.codex/models_cache.json。

淘汰說明（2026年3月11日）：ChatGPT 已不再提供 GPT-5.1 模型。現有對話會自動改由 GPT-5.3 Instant、GPT-5.4 Thinking 或 GPT-5.4 Pro 繼續。GPT-5.1-Codex-Mini 仍可透過API與CLI使用，直至2026年7月23日停止服務為止。⁷¹⁸⁸

免費層級說明（2026年5月5日）：GPT-5.5 Instant 已於2026年5月5日向 ChatGPT 免費層級推出。這讓 GPT-5.5 家族的適用對象從付費方案擴及更多使用者，但 Codex CLI存取仍須具備符合資格的 Plus／Pro／Business／Enterprise／Edu／Go 訂閱或API金鑰。⁹²

GPT-5.4 mini（2026年3月17日）：GPT-5.4 的較小型、更快速變體，具備400K上下文，每MTok費率為$0.75/$4.50，且僅使用 GPT-5.4 配額的30%。非常適合委派給子代理：由 GPT-5.4 負責規劃與協調，GPT-5.4 mini 子代理則平行處理範圍較窄的子任務（搜尋程式碼庫、審查檔案、處理文件）。⁷⁶

Bedrock GPT-5.6（Sol、Terra、Luna）（v0.143.0，2026年7月8日）：Codex 新增對 Amazon Bedrock 託管的3種 GPT-5.6 模型變體的一級支援，包括max推理強度層級。若團隊透過 Bedrock 提供者存取模型，可以比照其他自訂提供者模型選用這些模型（請參閱自訂模型提供者）；max強度層級專為最艱鉅的推理與代理式工作負載而設。¹⁰⁶ v0.144.6（2026年7月18日）更新了 Sol、Terra 與 Luna 的隨附指示，並將其上下文視窗修正為272,000個權杖。¹¹¹ v0.145.0（2026年7月21日）新增具備自訂端點與驗證支援的實驗性 Bedrock 登入功能、將GPT-5.6 Sol 設為 Bedrock 預設模型，並將隨附的 GPT-5.4 模型選項遷移至相對應的Terra 與 Luna變體。¹¹²

GPT-6-Astra（2026年9月3日推出；透過v0.153.1至v0.153.4進入 Codex）：明確日期的時序如下：v0.153.1於2026年9月3日預先加入僅限API的目錄項目；OpenAI 同日宣布 GPT-6-Astra；v0.153.4則於9月4日新增選擇器項目，並將隨附CLI的預設模型改為 Astra。公告描述分階段推出流程：首先開放給少數組織（以網路安全計畫合作夥伴為優先），接著在「未來數日內」擴及 ChatGPT Plus、Pro、Business 與 Enterprise，以及 OpenAI API和 AWS——推出資訊來自媒體報導（CNBC、Axios、Forbes、Al Jazeera、9to5Mac）。¹⁴² 以下資訊已於9月4日被取代：OpenAI 在 X 宣布 GPT-6 Astra「目前已提供給 ChatGPT Work 與 Codex 中所有 Pro、Enterprise 及 Business Premium 使用者」，並且「已在API上線」；Plus 與 Business 預計數日內開放。Codex 負責人 Tibo Sottiaux 當晚進一步表示：「Astra 現在也已向所有 Plus 與 Business 使用者推出。」實際權限仍不一致——9月5日的社群回報顯示，部分 Plus 帳戶在 Codex 中仍只能看到 GPT-5.6 模型——而下方引用的模型文件可用性說明並未變更，因此仍應以該第一方聲明為準。¹⁴⁶ 第一方文件已上線：API模型頁面將gpt-6-astra列為旗艦模型，稱其為「我們能力最強的模型，專為最艱鉅的端到端工作打造」——標準短上下文費率為輸入每MTok $10、輸出每MTok $50，上下文視窗為1.05M個權杖，輸入上限922,000個權杖，輸出上限128K，知識截止日期為2026年4月30日——另有明載的長上下文層級：輸入超過272K個權杖的提示詞，整個請求的輸入價格為2倍、輸出價格為1.5倍；定價頁面列出的費率為輸入每MTok $20、輸出每MTok $75——定位高於 GPT-5.6 Terra（均衡型）與 Luna（經濟型）。Codex 文件將 Astra 稱為建議使用的 Codex 模型，並指出其可用性「取決於推出進度、登入方式與用戶端」，符合資格的帳戶包括 Pro、Business（$100）與 Enterprise。Astra 明載的 Codex 推理層級為：Low、Medium、High、Extra High、Max、Ultra——模型文件頁面將 Medium 標示為預設值，但v0.153.4隨附目錄把default_reasoning_level設為low，因此應將實際預設值視為依操作介面而定，並在工作階段中使用/status確認；9月15日重新存取時，此層級架構維持不變，並新增各層級的選擇器說明（Ultra 原文：「Maximum reasoning with automatic task delegation」）。Max 與 Ultra 層級帶有SDK確認——Python SDK 0.154.0版本（2026年9月10日）新增max與ultra推理強度值（#39662）。^143145150 在CLI中，Astra 自v0.153.1起可透過API設定（-m gpt-6-astra）；v0.153.3將其加入 Amazon Bedrock 目錄（GPT-5.6 Sol 仍是 Bedrock 預設模型，直至v0.157.0改為 GPT-6 Sol¹⁷¹）；自v0.153.4起則出現在模型選擇器中，並成為未明確設定模型時的隨附預設模型——由於文件未載明最低CLI版本，可將上述版本視為實際下限。該預設值變更是隨附CLI目錄的既有情況，並非適用於所有操作介面——不過 cloud 的缺口後來已經補上：9月4日與9月7日存取時，Astra 被標示為不適用於 Codex cloud（GPT-5.6 Sol 則可用）；9月15日重新存取時，可用性矩陣顯示 Astra 也可用於 Codex cloud。該頁面仍註明：「目前無法變更 Codex cloud 對話的預設模型。」推出注意事項：權限因帳戶而異，而CLI 0.153.4+中尚未納入推出範圍的帳戶，會帶有無法實際提供服務的隨附預設模型——若要確保模型選擇一致，請在config.toml中固定模型（或傳入-m）；自v0.156.1起，文件本身的範例為model = "gpt-6-sol"。儘管模型頁面未列出 Fast 層級，文件仍載明 Astra 的 Fast 模式計費方式：Codex 速度文件表示，使用 ChatGPT 登入時，其費用為Standard 點數的2.5倍（「如有提供」）；API定價頁面則將 Fast 模式費率設為適用 Standard 費率的正好2倍（短上下文輸入／輸出每MTok $20/$100，長上下文為$40/$150）。v0.153.2目錄字串中的「2倍速度」仍僅為目錄顯示文字——速度頁面並未說明 Astra 的速度倍數。^142143144145 部分內容已於2026年9月23日被取代：模型文件不再將 Astra 稱為建議使用的 Codex 模型。「建議模型」一節目前以 GPT-6 Sol 與 Luna 為首，僅將 Astra 保留給「最艱鉅的端到端工作」，並將 Astra 標示為不適用於 Codex cloud；其起始推理強度則設為 Light（low），與隨附目錄一致。未設定模型時，Astra 仍是隨附CLI的預設模型。¹⁶⁸

Astra 下的 Power 預設組合（文件新增內容，最晚於2026年9月6日加入）：Codex 模型文件的模型選擇器段落，目前將選擇器中的 Power 選項對應至 GPT-6-Astra 推理層級——這是文件首次將 Power 預設組合對應至 Astra。該段落尚未出現在¹⁴³於9月5日重新存取的版本中，但已確認於9月7日上線。原文：「For eligible Pro, Business ($100), and Enterprise accounts, the Astra rollout updates the Power options to Terra Light, Sol Light, Sol Medium, Astra Light, Astra Medium, and Astra Extra High. Options can differ by plan and rollout stage.」前一個文件句子指出，選擇器圖示仍顯示 GPT-5.6 控制項。搭配上方模型表解讀：「Power」先前表示採用 medium 推理強度的 GPT-5.6 Sol；對已有權限的帳戶而言，同一組預設層級如今會以固定推理強度橫跨 Terra、Sol 與 Astra，且選項仍會因方案與推出階段而異。2026年9月15日重新存取時，該段落原文保持不變。¹⁴³ 2026年9月23日更新：GPT-6 Sol 與 Luna 推出後，文件列出的6個 Power 預設組合為「Luna High、Sol Light（起始預設組合）、Sol Medium、Astra Light、Astra Medium 與 Astra Extra High」，並註明部分付費方案不提供 Astra Extra High；文件建議 Sol 從 Medium 開始、Luna 從 High 開始、Astra 則從 Light（low）開始。¹⁶⁸

實驗性跨上下文附註（Astra、已發布於文件、須自行選擇加入）：Codex 模型文件頁面包含標題為「Experimental context management」的一節，原文：「On supported Codex clients, users signed in with ChatGPT Plus or Pro can opt in to experimental context management. Astra keeps notes across context windows and can search earlier messages and tool results from the same task. This experiment is off by default and isn’t available with Business, Enterprise, or API-key sign-in at launch.」選擇加入機制的原文為：「To opt in, set features.context_management.experimental_mode = true in your config.toml, then start a new task.」這與v0.153.0推出的features.context_management.experimental_mode操作介面相同（請參閱上下文管理）——模型文件如今明確將此功能與 Astra，以及 Plus 與 Pro 登入方式連結；此前v0.153.0版本資訊則將符合資格的對象列為 Plus、Pro 與 Pro Lite 工作階段。v0.154.0進一步收緊程式碼端的限制：實驗資格現在會在工作階段啟動時，依據現用模型的能力進行控管（#43147）。2026年9月15日重新存取時，該文件章節原文保持不變。此功能屬於實驗性質，且預設關閉；其行為與資格預期仍會變動。^137143149 v0.157.0：隨附模型目錄不再將 GPT-6-Astra 或任何其他隨附模型標示為支援實驗性上下文（#47397），而CLI只會為具有此標記的模型啟用實驗。因此，使用隨附目錄時，選擇加入並不會產生作用；提供給已登入帳戶的目錄是否不同，文件並未說明。截至2026年9月26日，模型文件仍有描述此選擇加入機制。¹⁷¹

模型選擇流程圖

Is this a quick fix, extraction, or other well-defined repeatable task?
├─ Yes → gpt-6-luna (most efficient; docs suggest starting at High)
└─ No
   ├─ Do you need real-time pairing speed?
   │  ├─ Yes → gpt-5.3-codex-spark (near-instant, Pro only)
   │  └─ No
   │     ├─ Hardest end-to-end work across many steps and tools?
   │     │  ├─ Yes → gpt-6-astra (strongest; bundled default when no model is set)
   │     │  └─ No → gpt-6-sol (everyday and complex coding; start at Medium)
   └─ GPT-6 not yet available on your account? → gpt-5.6-sol

推理強度

控制模型在回應前「思考」的程度：

支援的層級依模型而異。minimal僅適用於 GPT-5 模型。並非所有模型都支援每個層級。

persistent詳細資訊（v0.151.0）：以persistent強度執行的回合，預設會開啟目前時間提醒與可中斷的clock.sleep工具（明確設定的features.current_time_reminder與受管理需求會予以保留），並隨附主動性與後續追蹤指引；模型中繼資料可透過persistent_instructions覆寫或停用這些指引。¹³²

codex -c model_reasoning_effort="xhigh" "find the race condition"

專家提示：對於相同的提示詞，xhigh推理所使用的權杖可能比medium多3至5倍。請只在真正艱鉅、額外思考確實物有所值的問題上使用。

TUI 快速推理控制項（v0.124.0+）。⁸⁵ 在互動式 TUI 工作階段中，按下Alt+,可將推理強度降低一級，按下Alt+.則可提高一級——若在工作階段中途遇到難題，可暫時依medium → high → xhigh逐步提高強度，而無須使用/effort或-c。若在工作階段中途接受模型升級，推理強度會重設為新模型的預設值，不會沿用先前層級。

切換模型

使用/model slash command即可在工作階段中途切換模型，也可透過--model／-m為單次執行指定模型：

codex -m gpt-5.3-codex-spark "pair with me on this component"

Codex 的費用是多少？

另請參閱模型選擇以瞭解各模型的能力，以及決策框架以針對不同工作選擇合適的模型。

透過 ChatGPT 方案使用

Codex 的可用性取決於您的 ChatGPT 方案與組織設定：⁵¹

2026年4月定價更新：Business 年繳價格從每席位每月 $25 降至 $20。Business 與 Enterprise 工作區現已提供隨用隨付的 Codex 專用席位，無固定席位費用，並依 token 用量計費。⁷⁹定價頁面目前以各模型的範圍公布限制（請參閱上表），不再採用2026年2月 Desktop App 推出時宣傳的 2x 倍數。¹⁶¹⁵⁹

2026年5月使用量上調（已於2026年5月31日到期）：Plus 方案的 Codex 採用 25× 的5小時限制（標準上調幅度為 20×），且同一期間的每月 $100 方案層級額度加倍。⁸⁹

TUI 中的使用量限制 UX（v0.152.0–v0.153.0）：觸及限制後不再無路可走。v0.152.0 會在輸入區上方顯示可採取行動的使用量限制橫幅，提供檢查用量、管理點數、重設限制、通知工作區擁有者及管理方案等操作，並依已驗證的帳戶與使用者篩選；發生限制錯誤後會重新整理用量。當橫幅提示時，Codex 也會切換至第一個可用的備援模型，同時保持討論串的其他設定不變。¹³⁵v0.153.0 為 Plus 與 Team 方案新增更早的警告：在約5小時的使用時段中，剩餘額度低於一半時便會發出警告；其他方案與不同長度的時段則維持既有的 75%、90% 及 95% 門檻。¹³⁷

點數成本

Codex 操作會消耗方案配額中的點數：

以上為 Standard 速度的費率。定價頁面表示，GPT-6 推出後，GPT-5.6 Sol、Terra 與 Luna 的費率「維持不變」。實際上，「GPT-5.6 每則訊息平均使用5–30點」（8月開放使用時頁面標示為5–40點）；在「可用」的情況下，GPT-6 Astra、Sol 與 Luna 的 Fast 模式費用是 Standard 點數費率的2.5倍。此外，套裝目錄會讓 Fast 成為 TUI 中 GPT-6 Sol 與 Luna 的預設層級，除非您設定 service_tier。若點數消耗速度超乎預期，請檢查 /fast status。影像生成所消耗的內含額度，比同等的純文字互動快3–5倍。¹⁵⁹¹⁶⁸

Enterprise 與 Edu 方案的點數會隨合約配額調整。請在 TUI 中使用 /status 查看目前用量。

API 計費

透過 API 使用 Codex 時，OpenAI 會依所選模型的標準 OpenAI API 定價按 token 計費（另加任何適用的提示快取折扣）。目前每100萬個 token 的 API 費率如下：GPT-6 Sol 的輸入／輸出分別為 $2／$10，GPT-6 Luna 為 $0.10／$0.50，GPT-6 Astra 為 $10／$50；這3個模型的輸入提示一旦超過272K個 token，整筆請求的輸入費用會變成2倍，輸出費用則為1.5倍，而 Fast 模式費用為2倍。¹⁴³¹⁶⁸ChatGPT 點數倍數不適用於透過 API 金鑰登入的情況。最新費率請參閱官方 API 定價頁面。²⁰

成本最佳化策略

1. 使用設定檔：為例行工作建立採用 gpt-6-luna 且設為 model_reasoning_effort = "low" 的 fast 設定檔
2. 保留高推理強度：僅將 xhigh 用於真正困難的問題，因為它會多耗費3–5倍的 token
3. 使用 --ephemeral：在 CI/CD 中略過工作階段持久化，以減少額外負擔
4. 精簡推理摘要：不需要說明時，將 model_reasoning_summary = "none" 設為 none
5. 以 exec 模式批次處理：codex exec 可讓自動化工作流程避免 TUI 的額外負擔
6. 監控用量：在 TUI 中查看 /status，並檢查組織的計費儀表板；自 v0.148.0 起，符合資格的工作區會在 /status、狀態列與終端機標題中顯示討論串的預估點數或成本¹¹⁸

實際成本範例

常見工作的代表性 API 成本（以2026年中期的 gpt-5.3-codex 定價快照為準，採中等推理強度；不同模型間的相對規模大致相同）：

成本會因推理強度、快取與對話長度而異。例行工作可使用 gpt-5.6-luna，大幅降低相關支出。快取的輸入 token 可享折扣費率。

隱藏的 Token 額外用量

每次工具呼叫都會消耗可見提示以外的 token：

專家提示：請在 TUI 中透過 /status 監控實際用量。token 數量包含所有額外用量，而非只有可見訊息。若成本出乎預期，請檢查已連線的 MCP 伺服器數量；每個伺服器都會在每次 API 呼叫中加入工具定義。

團隊成本管理

團隊成本控管策略： - 設定 requirements.toml，在整個組織中強制套用模型與推理強度限制 - 在 CI/CD 中使用 gpt-5.6-luna——自動化管線鮮少需要最高推理強度 - 依設定檔編列預算——定義 ci、review 與 dev 設定檔，並配置合適的成本上限 - 透過 OpenTelemetry 監控——企業部署可將使用量遙測資料匯出至現有的可觀測性技術堆疊

決策框架

各操作介面的使用時機

各 Sandbox 模式的使用時機

各推理層級的使用時機

Plan 模式與直接執行

Will Codex need to change more than 3 files?
│
├── YES → Use Plan Mode (/plan)
│         Codex designs the approach BEFORE making changes.
│         You review and approve the plan.
│         Best for: refactors, new features, migrations
│
└── NO → Is the change well-defined?
         │
         ├── YES → Direct execution
         │         Just describe the task. Codex executes immediately.
         │         Best for: bug fixes, small features, test additions
         │
         └── NO → Use Plan Mode (/plan)
                  Let Codex explore and propose an approach first.
                  Best for: unfamiliar codebases, ambiguous requirements

Steer 模式：Enter 與 Tab

經驗法則：Enter＝「停下來，現在先聽這項指示。」Tab＝「完成目前工作後，也請處理這件事。」

Desktop App 與 CLI

How do you prefer to work?
│
├── Terminal-first → Use CLI
│   │
│   ├── Single focused task → codex (interactive TUI)
│   ├── Scripted automation → codex exec (non-interactive)
│   └── Quick one-shot → codex exec "prompt" -o result.txt
│
└── Visual/multi-project → Use Desktop App
    │
    ├── Multiple parallel tasks → Multi-thread with worktree isolation
    ├── Visual diff review → Built-in Git diff viewer
    ├── Scheduled automation → Automations tab
    └── Voice-driven → Ctrl+M for voice dictation

該選擇哪個設定檔？

依照任務選用預先設定的設定檔：

設定檔檔案（每個預設各有一個，位於 ~/.codex/；自 0.134.0 起，不再讀取舊版的單一檔案 profile = "default" + [profiles.*] 配置¹²²）：

# ~/.codex/fast.config.toml
model = "gpt-6-luna"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "low"

# ~/.codex/careful.config.toml
model = "gpt-6-astra"
model_reasoning_effort = "xhigh"

# ~/.codex/pair.config.toml
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"

# ~/.codex/ci.config.toml
model = "gpt-6-luna"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

針對個別工作階段切換設定檔：codex --profile careful

Sandbox 與核准系統如何運作？

Codex 採用雙層安全模型，將技術上可執行的操作與Codex 何時要求人工核准分開處理。此方式與 Claude Code 的權限系統截然不同——Codex 在作業系統核心層級強制執行限制。⁵ 另請參閱企業部署，瞭解管理員可在整個組織內強制執行的 requirements.toml 限制。

v0.148.0 強化措施：現在，Linux 與 Windows 上的 sandbox 限制都會採取失效封閉（fail closed）機制——遭拒絕或無法讀取的路徑會視為已封鎖，不再默許存取。¹¹⁸

第1層：Sandbox（可執行哪些操作）

Sandbox 使用作業系統原生機制控制檔案系統與網路存取：

各平台的強制執行方式：

• macOS：透過 sandbox-exec 使用 Apple 的 Seatbelt 框架，在執行階段編譯各模式專用的設定檔，並由核心強制執行。⁶ 自 v0.121.0 起，macOS sandbox 設定檔可將特定 Unix sockets（例如 docker.sock、編輯器 IPC sockets）加入允許清單，且預設不再封鎖私人 DNS 解析。⁸²
• Linux：使用 Landlock 限制檔案系統，並以 seccomp 篩選系統呼叫。獨立的輔助程序（codex-linux-sandbox）提供縱深防禦隔離。⁵ Bubblewrap（bwrap）已隨附於 Linux 建置中並一併編譯（自 v0.100.0 起由選用項目提升為正式項目）。⁷ v0.117.0 改善了採用舊版核心設定之較舊發行版上的 sandbox 可靠性。⁷⁵ v0.129.0 強化 Linux 的 sandbox 啟動流程，並將隨附的 Bubblewrap 升級至 0.11.2，以納入上游安全性修補；v0.130.0 則進一步強化啟動流程。⁸⁹⁹¹
• Windows：採用具有受限權杖的原生 sandbox（自 v0.100.0 起由實驗性功能提升為正式功能）。亦支援 WSL（沿用 Linux 的 Landlock 與 seccomp）。v0.117.0 改善受限權杖 sandbox，以提供更完善的程序隔離。⁷⁵ v0.130.0 允許 sandbox 使用者存取桌面執行階段的二進位檔快取，使 Windows sandbox 能為工作區 sandbox 使用者可靠地解析執行階段二進位檔。⁹¹

為何這一點至關重要：與容器式 sandbox（Docker）不同，作業系統層級的 sandbox 速度更快、負擔更低，也更難突破。甚至在 Codex 看到系統呼叫之前，核心就已強制執行限制。

安全性修正： - zsh-fork sandbox 繞過問題（v0.106.0）：修正透過 zsh 分支執行 shell 時可能繞過 sandbox 限制的漏洞。⁶⁰ 若您使用的是更早版本，請立即升級。 - 輸入大小上限（v0.106.0）：Codex 現在會將輸入限制在約 100 萬個字元，以免過大的承載資料導致系統停滯。⁶⁰ - 安全的 devcontainer 設定檔（v0.121.0）：新增強化的客戶設定檔，供 Docker devcontainers 在容器內使用 Bubblewrap 建立 sandbox。支援 WSL2；明確拒絕 WSL1（Bubblewrap 與 WSL1 的核心轉接層不相容）。⁸² - Guardian 審查與 hooks（v0.121.0）：Guardian 審查工作階段期間會停用 hooks，避免工具執行前後的 hooks 干擾 Guardian 子代理程式的決策。⁸² 若您仰賴 hooks 進行記錄或驗證，請注意 Guardian 審查會略過這些 hooks——如需完整稽核軌跡，請改用應用程式伺服器的可觀測性功能。 - Linux /dev 檔案系統（v0.105.0）：Linux 上於 sandbox 內執行的命令現在會取得最精簡的 /dev 檔案系統，提升與預期存在裝置節點之工具的相容性。⁶¹

ReadOnlyAccess 原則（v0.100.0 以上版本）：這是一種可設定的原則結構，用於細部控管讀取權限。即使處於 workspace-write 模式，也能用它限制 Codex 可讀取的目錄：

[sandbox_workspace_write]
read_only_access = ["/etc", "/usr/local/share"]  # Only these paths readable outside workspace

第2層：核准原則（何時詢問）

核准原則決定 Codex 何時暫停並要求人工確認：

on-failure 仍出現在部分較舊的範例與相容性路徑中，但目前 OpenAI 設定文件已將其標示為淘汰。互動式執行請優先使用 on-request；對於已有外部安全邊界的非互動式執行，則使用 never。⁸⁷

自 v0.150.0 起，您可以綁定鍵盤快速鍵，直接從輸入區循環切換權限模式——請透過 /keymap 設定。[^218]

個別核准 ID（v0.104.0 以上版本）

Codex 現在會為多步驟 shell 執行中的每項命令指派個別核准 ID。這代表核准可細分處理——核准序列中的某項命令，不會自動核准同一次 shell 呼叫內的後續命令。⁴⁹

彈性核准控制（v0.105.0 以上版本）

核准流程現在支援額外的 sandbox 權限與細部拒絕：⁶¹

• 額外的 sandbox 權限：當命令需要目前 sandbox 模式範圍外的存取權時，Codex 可要求特定的額外權限，無須全面變更模式
• 細部拒絕：拒絕個別工具呼叫時可提供意見，讓 Codex 調整處理方式，而非直接重試相同命令

執行階段權限要求（v0.113.0 以上版本）

Codex 現已內建 request_permissions 工具，模型可在執行階段要求額外權限。⁶⁹ 當模型遇到需要提高權限的工作時，可透過 TUI 核准流程正式要求特定權限（檔案系統路徑、網路存取等），不會無聲失敗，也不需要使用者以不同旗標重新啟動。

應用程式核准模式 writes（v0.144.0 以上版本）

應用程式與連接器新增中間層級的核准選項：writes 應用程式核准模式允許應用程式宣告的唯讀操作直接執行，無須提示；任何寫入操作仍會暫停並等待核准。¹⁰⁷ 在此之前，應用程式核准較接近全有或全無；writes 更貼近多數操作者對整合功能的實際信任模式——查看不受限，動手前先詢問。

自動審查核准：--approve-for-me（v0.147.0 以上版本）

新的 --approve-for-me CLI 旗標會將核准提示轉為自動審查的核准：每項要求不再打斷您，而是交由審查程序代為判定並核准或拒絕。¹¹⁶ 此模式介於「全部核准」（已移除的 --full-auto 過去鼓勵採取的作法）與「每項操作都中斷詢問」之間——提示仍是決策點，但由審查者代為回答。此旗標會沿用 v0.146.1 針對具備網路攻防能力模型所提供的較安全自動審查預設值。請將其視為任何其他權限委派：適合長時間無人值守、受到中斷便會停滯的執行工作；若工作階段會接觸憑證或正式環境狀態，且您希望親自審查，則不宜使用。

提高權限之終端機輸入的核准機制（v0.151.0）

write_stdin_approval 功能旗標預設停用；啟用後，任何非空白輸入傳送至已提高權限的 unified-exec 終端機前，都必須重新取得核准。這類審查會以 writeStdin 核准的形式，經由 hooks、Guardian、應用程式伺服器與 TUI 路由處理；終端機的環境、啟動目錄及權限提升狀態會跨回合保留，並於核准後、寫入任何位元組之前重新驗證程序身分。完整格式化後的操作與核准理由必須能容納於 8,000 位元組內——過大或遭截斷的操作，會在要求核准或將任何內容送達終端機前遭到拒絕。¹³²

權限設定檔（v0.113.0 以上版本，於 v0.128.0 與 v0.133.0 擴充）

權限設定檔會將檔案系統與網路 sandbox 原則拆分成具名且可重複使用的區段。請將 default_permissions 設為 :read-only、:workspace 等內建設定檔，或指向自訂的 [permissions.<name>] 資料表。⁸⁷ v0.133.0 將設定檔提升為受管理的介面：清單 APIs 會公開可用的設定檔中繼資料；設定檔可彼此繼承；受管理的 requirements.toml 可宣告權限需求；使用中的設定檔會在執行階段重新整理；Windows sandbox 設定現在也會採用解析後的設定檔，不再使用個別的臨時原則。⁹⁸

default_permissions = "project-safe"

[permissions.project-safe.filesystem]
"/usr/local" = "read"
glob_scan_max_depth = 3

[permissions.project-safe.filesystem.":project_roots"]
"." = "write"
"**/*.env" = "none"

[permissions.project-safe.network]
enabled = true
mode = "limited"

[permissions.project-safe.network.domains]
"api.github.com" = "allow"
"registry.npmjs.org" = "allow"

對於即使專案根目錄可寫入也不應讀取的敏感檔案與 glob 模式，請使用 none。若只是為單一命令設定例外，建議使用規則，不要大幅放寬整份設定檔。⁸⁷

v0.151.0：還原的應用程式伺服器執行緒會保留其權限設定檔，不再被扁平化為舊式的逐回合 sandbox 覆寫——設定檔可在回合路由以及相容的 /cd 目錄變更後繼續保留；若某次 /cd 無法透過舊式 sandbox 模式安全呈現還原後的設定檔，系統會拒絕該操作，而不會悄然放寬限制。[^221]

舊版 --full-auto 指引

較舊的指南將 --full-auto 描述為下列設定的便利別名：

codex --sandbox workspace-write --ask-for-approval on-request

在 v0.128.0 中，版本資訊已將 --full-auto 標示為淘汰，而目前的 CLI 說明也不再為互動式執行列出此旗標。請改用上述明確旗標或具名權限設定檔。⁸⁶

v0.147.0 正式完成移除：codex exec --full-auto 已不存在。仍傳入此旗標的指令碼現在會直接報錯，不再執行。移轉方式十分明確——將其替換為 --sandbox workspace-write（若舊版呼叫依賴 --full-auto 的核准行為，請再加上核准旗標或設定檔）。升級前，請稽核所有透過 shell 呼叫 codex exec 的自動化作業：此問題會以管線中斷的形式出現，而非淘汰警告。¹¹⁶

Sandbox 可靠性（v0.129.0）：Linux sandbox 啟動強化可減少慢速檔案系統或使用符號連結之簽出目錄上的競爭情況；Windows sandbox 的可靠性改善則修正了長時間執行期間的多種邊界案例當機問題；隨附的 Bubblewrap 也已升級至 0.11.2，納入上游安全性修補。無須變更設定。請執行 codex update 取得這些更新。⁸⁹

建議設定

日常開發（安全的預設值）：

sandbox_mode = "workspace-write"
approval_policy = "on-request"

進階使用者（完整存取權，人工參與決策）：

sandbox_mode = "danger-full-access"
approval_policy = "on-request"   # `untrusted` retired in v0.149.0

社群文章將此組合推薦為「最佳平衡點」⁸；不過，在重複採用此建議前，務必先瞭解其實際行為：當命令需要離開 sandbox 或存取網路時，才會觸發核准提示，而 danger-full-access 會移除這兩項邊界，因此 on-request 幾乎無事可升級處理。這代表最高權限搭配最少詢問，並非每項命令都由人工檢查的最高權限模式；若您需要後者，請保留 workspace-write，讓 sandbox 邊界負責觸發提示。¹²³

CI/CD 自動化：

sandbox_mode = "workspace-write"
approval_policy = "never"

使用 Guardian 子代理程式進行智慧核准（v0.115.0 以上版本）

智慧核准可將審查要求交由 Guardian 子代理程式處理，無須每項操作都取得人工核准。Guardian 工作階段會在多次核准之間持續存在，以重複使用提示快取並避免啟動負擔。每次審查都會取得乾淨的歷程記錄（先前決策不會滲入後續審查）。⁷³

在 config.toml 中設定審查者：

approvals_reviewer = "guardian_subagent"   # "user" (default) or "guardian_subagent"

這特別適合 CI/CD 工作流程，讓您能取得具備推理過程的自動化審查，而非一概採用 approval_policy = "never"。

Guardian v2 預設值翻轉（v0.151.0）：Guardian v2 現在預設使用包含影像的電腦操作審查。features.guardianv2.review_scope.computer_use_only 預設為 true——設為 false 可保留較廣泛的工具審查範圍——而 features.guardianv2.transcript.include_images 預設為 true——設為 false 則不在 Guardian 逐字記錄中納入影像。這兩項介面在 v0.150.0 推出時皆可設定且預設關閉；到了 v0.151.0，預設值才改為開啟。¹³²

Guardian 範圍會跟隨核准模式（v0.153.0）：現在有兩種模式會略過無法改變結果的 Guardian 工作。在 Full Access（已結合 approvalPolicy: "never" 與不受限權限）中，僅需確認的 Guardian 與 MCP 要求會直接獲得核准，不進行同步審查、取樣器預熱或背景評分——待處理、失敗或受限的環境不會被視為 Full Access，且系統會在每個回合重新評估目前的權限狀態，確保既有執行緒能安全進入或離開 Full Access。在使用者核准模式（approvals_reviewer = "user"）中，系統會略過 Guardian 預熱與非同步評分，並自動接受一般的 node_repl.js 執行確認；敏感操作檢查與要求使用者輸入則維持原有行為。¹³⁷ 這項變更只會縮小 Guardian 的執行時機，不會改變人工核准層：本指南針對 on-request 下 danger-full-access 所述的提示行為屬於核准原則，是另一套獨立機制。v0.152.1 另允許 Guardian 核准審查從模型中繼資料（auto_review.node_repl_policy）取得 Node REPL 原則；若該欄位不存在，則改用隨附的原則。¹³⁶

Guardian 電腦操作評分會遵循模型需求（v0.153.1）：只有當使用中的模型在其中繼資料內設定 node_repl_auto_review_required 時，才會執行僅限電腦操作的 Guardian 評分與快速核准決策；若模型切換導致略過評分，先前或執行中的分數都會失效——因此切回受審查的模型時，無法重新啟用過期的核准決策。這是 v0.153.1 修補程式的重點，但未列於版本說明正文：#42422（38ba8cdc 的 cherry-pick）只能透過 rust-v0.153.0…rust-v0.153.1 的比較結果加以證實。¹³⁹

預設啟用 Guardian 父執行緒壓縮重複使用功能（v0.156.0）：#46522 將 guardian_reuse_parent_compaction 提升為穩定功能並預設啟用，使 Guardian 在重新啟動審查工作階段時，可重複使用父執行緒已加密的壓縮內容。依據該 PR 的測試，父執行緒歷程變更時，快取的審查工作階段仍會失效。若要恢復先前行為：請在 config.toml 的 [features] 下設定 guardian_reuse_parent_compaction = false，或執行 codex features disable guardian_reuse_parent_compaction。¹⁶⁶¹⁶⁸

預設啟用 Guardian 執行緒情境（v0.157.0）：#47275 將 guardianv2.thread_context 提升為穩定功能，並為同步及非同步 Guardian 審查啟用此功能，使審查採用執行緒所擁有的情境。此功能與 Guardian v2 的 enabled 開關互相獨立，且明確設定與設定檔覆寫都會保留。若要關閉：請在 config.toml 的 [features.guardianv2] 下設定 thread_context = false。¹⁷¹

收緊 PowerShell 分類器（v0.142.2）：若 PowerShell 命令含有安全分類器無法檢查的可執行 AST 區域，現在會要求核准，不再放任其通過自動核准——藉此補上 Windows 中經過混淆或動態建構的 PowerShell 可能規避分類的漏洞。¹⁰⁵

擴大危險命令偵測範圍（v0.144.5）：偵測功能現在可辨識更多強制執行的 rm 形式，遭拒絕的命令也會傳回更清楚的拒絕理由，不再只顯示語意不明的拒絕訊息——當您調整核准原則並需要瞭解命令遭封鎖的原因時，格外實用。¹¹⁰

啟用網路存取

Codex 預設會在 workspace-write 模式下封鎖網路存取。需要時可啟用：

# Per-run
codex -c 'sandbox_workspace_write.network_access=true' "install the packages"

# In config.toml
[sandbox_workspace_write]
network_access = true
writable_roots = ["/path/to/extra/dir"]   # Additional writable directories
exclude_slash_tmp = false                  # Prevent /tmp from being writable
exclude_tmpdir_env_var = false             # Prevent $TMPDIR from being writable

WebSocket Proxy 支援（v0.104.0 以上版本）

對於透過 Proxy 路由 WebSocket 流量的企業環境，Codex 現在支援 WS_PROXY 與 WSS_PROXY 環境變數：⁴⁹

export WSS_PROXY="https://proxy.corp.example.com:8443"
codex "update the README"

這些功能補足了既有的 HTTPS_PROXY 與 SOCKS5 Proxy 支援（v0.93.0 以上版本）。

v0.146.0 才真正實現「所有傳輸層」的完整支援。設定的 Proxy 現在會套用至驗證、外掛程式下載、MCP 授權、遠端執行、WebSocket 連線、HTTP 重新導向及 LM Studio 連線——變更記錄指出，這7條路徑先前都會忽略 Proxy。¹¹⁴ 若您在 v0.146.0 之前透過企業 Proxy 執行 Codex，並曾遇到登入或外掛程式安裝失敗，但一般模型呼叫仍可運作，此缺口很可能就是原因。

macOS 上的系統 Proxy（v0.142.2 以上版本）：啟用 respect_system_proxy 後，macOS 驗證用戶端會遵循系統 Proxy、PAC 與 WPAD 設定——因此，透過設定描述檔推送 Proxy 設定的企業 Mac，不再需要為驗證流量逐一設定 shell Proxy 環境變數。¹⁰⁵ 自 v0.143.0 起，此支援擴展至 Windows 與 Responses API 流量：Codex 會透過 macOS 或 Windows 系統 Proxy 路由驗證與 Responses API 呼叫，包括 PAC 與 WPAD 自動設定，補上兩種作業系統在嚴格管制企業網路中的最後一項缺口。¹⁰⁶

測試 Sandbox

請先驗證 sandbox 行為，再決定是否信任其運作：

codex sandbox macos --permissions-profile :workspace -- ls /etc/passwd   # macOS test
codex sandbox linux --permissions-profile :workspace -- cat /etc/shadow  # Linux test

若 sandbox 運作正常，在工作區範圍的設定檔下，這兩項命令都應因權限遭拒而失敗。若任一命令執行成功，就需要進一步檢查 sandbox 設定。

AGENTS.md 如何運作？

AGENTS.md 是 Codex 的專案指令系統，也是一項現由 Linux Foundation 的 Agentic AI Foundation 管理的開放標準⁹。Codex、Cursor、Copilot、Amp、Jules（Google）、Gemini CLI、Windsurf、Cline、Aider、Zed、Factory、RooCode，以及超過60,000個開放原始碼專案皆支援此標準。它定義了 Codex 在特定儲存庫或目錄中的運作方式。如需瞭解可與 AGENTS.md 相輔相成、重複使用的專業能力套件，請參閱技能。

探索階層

Codex 會在工作階段開始時逐層走訪目錄樹，建立指令鏈：

1. 全域（~/.codex/）：AGENTS.override.md > AGENTS.md
2. 專案（從 git 根目錄到目前目錄）：逐層依序檢查 AGENTS.override.md > AGENTS.md > 備援檔名
3. 合併：檔案從根目錄往下串接；越接近目前目錄的檔案越晚出現在提示詞中，因此會覆寫較早的指引

~/.codex/AGENTS.md                     ← Global defaults
  └─ /repo/AGENTS.md                   ← Project-wide rules
      └─ /repo/services/AGENTS.md      ← Service-specific rules
          └─ /repo/services/payments/
               AGENTS.override.md      ← Overrides everything above for this dir

不受信任的專案會略過專案 AGENTS.md（v0.150.0）：上述走訪流程以專案已受信任為前提。自 v0.150.0 起，「不受信任的專案不再提供專案層級的 AGENTS.md 指令，而且管理式拒絕讀取規則在權限變更後仍會持續生效」——在保留使用者層級 ~/.codex/AGENTS.md 指令的同時，略過專案範圍的探索。因此，不受信任的簽出內容無法在您信任它之前注入作業規範。[^218]

Desktop 多資料夾專案（26.715，2026年7月23日）：上述走訪流程描述的是 CLI，所有內容皆以目前工作目錄為基準解析。ChatGPT 桌面應用程式現在能讓一個本機專案涵蓋數個相關資料夾，但只會針對其中一個資料夾進行探索解析：「新聊天、Git 操作，以及 AGENTS.md、skills 和 config.toml 的自動探索，都會使用主要資料夾。次要資料夾仍可供檔案搜尋、讀取與編輯。」您可以從專案選單選取 Edit project，指定主要資料夾。¹¹³

這項設定會同時管理 Codex 五大核心系統中的三項——指令、skills 與設定皆以主要資料夾為準。實際上，次要資料夾中的 AGENTS.md 只是 Codex 能開啟的檔案，而不是會載入的作業規範。如果承載規則的儲存庫是第二個附加的資料夾，請將其升級為主要資料夾，或在主要資料夾的 AGENTS.md 中重新陳述這些規則；您原先預期會被自動載入的儲存庫 skills 資料夾亦同。CLI 的目錄走訪機制並未改變——這只是桌面應用程式的專案範圍界定方式。

優秀的 AGENTS.md 應具備哪些特質

以下原則源自 Codex 本身的直接指引與社群慣例¹⁰：

應該： - 明確具體："Use rg --files for discovery" 勝過 "search efficiently" - 定義完成條件：「完成」代表什麼？（測試通過、lint 無誤等） - 納入指令：建置、測試、lint、格式化（提供確切的執行方式） - 依任務分類：程式開發、審查、發布、事件處理／偵錯等章節 - 定義升級處理方式：受阻或遇到非預期狀態時該如何處理

不應該： - 塞入整份風格指南，卻未提供執行規則 - 使用含糊不清的指示（「小心處理」、「最佳化」） - 混用互相矛盾的優先事項（追求速度＋全面驗證＋不提供執行時間預算） - 撰寫敘述性文件（AGENTS.md 是作業政策，不是 README）

範例：正式環境使用的 AGENTS.md

# Repository Guidelines

## Build, Test, and Development Commands
- Run API (dev): `python3 -m uvicorn main:app --reload`
- Install deps: `pip install -r requirements.txt`
- Lint: `python3 -m ruff check .` (auto-fix: `--fix`)
- Format: `python3 -m ruff format .`
- Tests: `python3 -m pytest -v`
- Coverage: `python3 -m pytest --cov=app --cov-report=term-missing`

## Coding Style & Naming Conventions
- Python 3.11+. Type hints on all functions.
- Ruff enforced: 88-char lines, double quotes, spaces for indent.
- Naming: modules `snake_case.py`, classes `PascalCase`, functions `snake_case`.

## Commit & Pull Request Guidelines
- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `test:`
- Commits should be small and focused.
- PRs must include: description, test plan, and screenshots for UI changes.

## Security
- Never commit secrets. Use `.env` for local config.
- Validate all external API calls with proper error handling.

Agent 工作階段中的機密處理

請將 Codex 可見的歷史記錄視為安全性範疇，而不僅是原始程式碼。Codex 發行說明記載了 shell 快照與環境變數遮蔽的相關改進，記憶系統也會掃描寫入記憶體的內容是否含有機密。然而，這些防護措施並不代表您可以放心在指令輸出、工作階段逐字記錄、shell 快照、本機日誌或輔助指令碼中輸出憑證。³⁷⁵⁵⁹⁵

作業規則很簡單：不要輸出機密供模型檢視；將輔助工具憑證保存在環境要求的設定中；稽核時，應分開處理可執行原始碼、文件、產生的快取、工作階段逐字記錄、shell 快照、日誌，以及刻意設置的機密儲存區；若本機歷史記錄中出現高度可信的機密格式，應加以遮蔽；只有在人工衛生檢查流程證實可靠後，才將預防性 hooks 提升為正式機制。適合公開分享的是安全範疇圖與驗收標準，而不是私密 token 值、確切路徑或偵測器內部機制。⁹⁵

覆寫機制

任一目錄層級中的 AGENTS.override.md，都會取代該範圍內一般的 AGENTS.md。適用情境包括：

• 發布凍結：「不新增功能，只修正問題」
• 事件處理模式：「所有變更都必須由值班人員審查」
• 暫時性強化：「本次衝刺期間不更新相依套件」

設定

# Custom fallback filenames (in addition to AGENTS.md)
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

# Increase max size for large instruction files
project_doc_max_bytes = 65536    # 64 KiB (default: 32 KiB)

產生初始架構

codex                           # Launch TUI
/init                           # Generate AGENTS.md scaffold

或驗證您的指令鏈：

codex --ask-for-approval never "Summarize your current instructions"

Hooks

Codex 在 v0.99.0 與 v0.100.0 中，以舊版 AfterAgent 和 AfterToolUse 名稱導入 hooks；v0.114.0 新增實驗性的 hooks 引擎，包含 SessionStart 與 Stop；⁷⁰並於 v0.124.0（2026年4月23日）將 hooks 正式轉為穩定功能。⁸⁵ rust-v0.150.0 隨附的引擎註冊了 12 個事件（位於 codex-rs/hooks/src/lib.rs 的 HOOK_EVENT_NAMES）——v0.149.1 時有 11 個，v0.150.0 加入 Interrupt 作為第 12 個事件[^218]——舊版名稱也已從可設定介面中移除：原始碼樹中已完全找不到 AfterToolUse，而 AfterAgent 僅作為舊版 notify 橋接器的內部承載資料名稱保留下來。¹²⁴ Hooks 會在代理迴圈期間執行指令碼或 MCP 工具。多個檔案中符合條件的 hooks 都會執行；同一事件有多個相符的指令 hooks 時，會並行啟動；每個非受管理的 hook 都必須先經過審查並設為信任，才能執行。¹²⁴ v0.148.0 擴充了此引擎：hooks 能以非同步方式執行命令，也能叫用 MCP 工具——在命令處理常式上設定 async = true，即可讓它在背景執行而 Codex 繼續運作；也可使用 mcp_tool 處理常式，存取代理所使用的相同 MCP servers。¹¹⁸¹²⁴

可用的 Hook 事件

WebSearch 等託管工具不會經過 hook 路徑，部分特殊工具路徑也可選擇不套用；OpenAI 對此的說法是：「這是一道實用的防護措施，但並非完整的強制執行邊界。」¹²⁴

Hook 設定

Hooks 分為三個層級——事件、matcher 群組，以及一或多個處理常式——並存放於 hooks.json（~/.codex/hooks.json、<repo>/.codex/hooks.json，或 plugin 的 hooks/hooks.json），或直接寫入 config.toml 與 requirements.toml。只有在專案的 .codex/ 層受到信任時，才會載入專案本機 hooks。¹²⁴ 行內 TOML 格式如下：

# ~/.codex/config.toml or <repo>/.codex/config.toml
[[hooks.SessionStart]]
matcher = "startup|resume"

[[hooks.SessionStart.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/session_start.py"
additionalContextLimit = 5000

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

[[hooks.PostToolUse]]
matcher = "^Bash$"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/post_tool_use_review.py"
async = true
timeout = 120

處理常式欄位：type（command 或 mcp_tool；prompt 與 agent 處理常式會被剖析，但會略過）、command、以秒為單位的 timeout（預設 600；SessionEnd 為 1 秒，上限 3 秒）、statusMessage、additionalContextLimit（在 Codex 將完整文字儲存至磁碟並傳送預覽前，可有多少 additionalContext 傳入模型）、commandWindows（僅限 Windows 的覆寫設定），以及 async。命令會以工作階段的 cwd 作為工作目錄，因此儲存庫本機 hooks 應從 git rev-parse --show-toplevel 解析路徑，而非使用相對的 .codex/hooks/... 路徑。¹²⁴

審查與信任。 Codex 會根據每個非受管理 hook 的目前雜湊值記錄信任狀態；新增或變更的 hooks 會標示為待審查，並在設為信任前略過。執行 /hooks 即可檢查 hook 來源、進行審查、設為信任，或停用個別 hooks；若啟動時有 hooks 需要審查，Codex 會顯示警告並引導您前往 /hooks。來自系統、MDM、雲端或 requirements.toml 來源的受管理 hooks 會依政策獲得信任，且無法從使用者 hook 瀏覽器停用。--dangerously-bypass-hook-trust 可在單次執行中，讓已啟用的 hooks 不必具備持久化信任即可執行，適用於由其他機制審核 hook 來源的自動化作業。¹²⁴

SessionStart hook 的 stdout 會送入模型情境，非常適合在工作階段啟動時注入動態資訊（日期、分支名稱、環境變數）。

重現 Claude Code Hook 模式

對於 Codex 已實作的事件，其事件名稱與 Claude Code 相同。因此，多數 hook 設定只需將 JSON 移至 hooks.json，再透過 /hooks 設為信任，即可完成移植：

專家提示：新 hook 事件仍會隨版本持續推出——v0.150.0 新增了 Interrupt 事件（[^218]）——因此，請查看 codex-rs/hooks/src/lib.rs 中的 HOOK_EVENT_NAMES 與 Codex 變更記錄，以取得目前的事件清單。

TUI 內建 hook 瀏覽器（v0.129.0）：在 TUI 中執行 /hooks，即可探索可用的 hooks、查看目前啟用的項目，並在不編輯 config.toml 的情況下切換個別 hooks。當您要排查 plugin 隨附但運作異常的 hook，或在專心編輯期間暫時停用 PostToolUse linter 時，特別實用。⁸⁹

什麼是 MCP（Model Context Protocol）？ [EXPERIMENTAL]

MCP 透過連接外部工具與服務來擴充 Codex 的能力。codex mcp 指令群組目前標示為實驗性，指令與設定格式可能在不同版本之間變動。Codex 支援兩種傳輸類型：STDIO（本機行程）與 Streamable HTTP（遠端伺服器）。¹¹

v0.121.0 MCP 變更：工具現在會以命名空間註冊，因此列表中的工具名稱會顯示為 <server>:<tool>，而非單純的名稱——請更新任何以未限定工具名稱進行 grep 的指令稿或提示。新的 supports_parallel_tool_calls 旗標會傳遞至所納入的 MCPs，讓宣告支援的伺服器得以平行執行。沙箱狀態中繼資料現在會透過 MCP 工具中繼資料流動，讓伺服器能調整行為（例如在唯讀沙箱下執行時發出警告）。自訂的 codex/sandbox-state 請求已移除——請改用中繼資料路徑。MCP Apps 推出的第三階段在此登場，帶來工具呼叫支援；採用延遲呼叫模式的伺服器現在也支援扁平化的延遲工具呼叫。⁸²

v0.142.2 MCP 變更（2026年6月25日）：MCP 工具現在在支援的情況下預設使用工具搜尋——Codex 不再預先載入每一項工具定義，而是按需探索工具，在工具繁多的環境中改善探索體驗，同時維持與較舊模型和供應商的相容性。遠端 stdio MCP 伺服器也接受以遠端平台路徑格式撰寫的絕對工作目錄（例如從 macOS 用戶端傳入 Windows 風格的路徑，反之亦然）。¹⁰⁵

v0.147.0 MCP 變更（2026年8月7日）：Codex 新增可選擇啟用的 MCP 2026-07-28 通訊協定修訂版支援——分頁探索（龐大的工具目錄會分頁串流傳入，而非一次回傳超大列表）、多輪請求（伺服器可在單一邏輯請求內進行多步驟交換），以及非阻斷式伺服器啟動，在伺服器尚未完成啟動前就先提供已快取的 MCP 工具，如此一來，啟動緩慢的伺服器不再拖延工作階段的啟動。此為可選啟用機制，因此沿用舊修訂版的伺服器仍可照常運作。¹¹⁶

v0.151.0 MCP 變更（2026年8月29日）：選用的 MCP 伺服器獲得可設定的啟動寬限期——mcp_optional_startup_grace_ms（預設 1,000 毫秒）控制工具目錄擷取要等待選用伺服器多久，設為 0 則停用共用寬限期，選用伺服器將回退至各自設定的 startup_timeout_sec，而更新後的數值會在執行期間與 MCP 設定重新整理時生效。擴充功能也能在 MCP 工具結果送達模型之前檢查或替換結果：ToolLifecycleContributor::on_mcp_tool_result 會在 MCP 完成事件發布之前、以及結果準備交給模型之前執行，成功與錯誤結果一視同仁，透過 Code Mode 亦然。[^221]

v0.152.0 MCP 變更（2026年9月1日）：三項增補式變更。openai/elicitation 表單請求正式登場：當用戶端宣告物件值的 form 能力時，Codex 會通告表單支援、處理 openai/elicitation/create 請求，並透過 app server 以 openaiForm 轉發其中繼資料與不透明結構描述（保留 x-openai-* 註解）；既有的 openai/form 處理維持獨立運作，而 TUI 會自動拒絕無法呈現的表單請求。逐工具輸出上限：MCP 伺服器 tools 設定底下的每一個項目都可接受正值的 output_token_limit（例如 [mcp_servers.context7.tools.search] 搭配 output_token_limit = 2000）；當外掛與使用者政策重疊時，以最嚴格的上限為準，而實際生效的額度會記錄在對話歷史中，讓工具輸出、工具後掛鉤回應與恢復的工作階段都在同一上限截斷——此機制與全域的 tool_output_token_limit 並行增補。套件風格的伺服器名稱：MCP 伺服器名稱現在可包含 :、@、/ 與 .（因此 npm:@modelcontextprotocol/server-sequential.thinking 是合法名稱），並在 mcp add/get/list/remove、執行期工具命名空間與 OAuth 憑證查詢之間完整保留，非單純名稱在產生的 config.toml 復原提示中會加上引號。¹³⁵

設定 MCP 伺服器

STDIO 伺服器（本機行程）：

# In ~/.codex/config.toml or .codex/config.toml

[mcp_servers.context7]
enabled = true
required = true                         # Fail startup if unavailable
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { "MY_VAR" = "value" }            # Static env vars
env_vars = ["PATH", "HOME"]             # Forward host env vars
cwd = "/path/to/project"                # Optional working directory
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled_tools = ["search", "summarize"]  # Tool allowlist
disabled_tools = ["slow-tool"]           # Tool denylist

HTTP 伺服器（遠端）：

[mcp_servers.figma]
enabled = true
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
env_http_headers = { "X-Org-Id" = "FIGMA_ORG_ID" }  # Headers from env vars
startup_timeout_sec = 10
tool_timeout_sec = 60

CLI 管理

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add context7 --env API_KEY=... -- npx -y @upstash/context7-mcp   # With env vars
codex mcp add figma --url https://mcp.figma.com/mcp --bearer-token-env-var FIGMA_OAUTH_TOKEN
codex mcp list                          # List all configured servers
codex mcp list --json                   # JSON output
codex mcp get context7                  # Show server config
codex mcp get context7 --json           # JSON output
codex mcp login <server>                # OAuth flow for HTTP servers
codex mcp logout <server>               # Remove OAuth credentials
codex mcp remove <server>               # Delete server definition

工作階段內：/mcp 會顯示使用中的伺服器與可用工具。/mcp verbose（v0.123.0+）⁸⁴ 會回傳完整的伺服器診斷資訊、資源與資源範本——當伺服器載入失敗或工具未出現在預期位置時特別有用。單純的 /mcp 則維持快速回應。自 v0.144.0 起，MCP 工具可以互動式請求驗證，無需實驗性選擇加入——需要驗證的伺服器會在工作階段中途透過正常流程提示，而不是在您以 codex mcp login 預先驗證之前持續失敗。¹⁰⁷

外掛的 MCP 載入機制（v0.123.0+）同時接受標準的 mcpServers 結構描述與 .mcp.json 中的頂層伺服器對應表，因此依照任一慣例撰寫的外掛都能順利載入。⁸⁴

MCP 使用者驗證（v0.155.0，支援的 Mac）：在支援的 Mac 上，本機 TUI 工作階段可以透過 Touch ID 驗證 MCP 請求，並由 Secure Enclave 簽署（#43624、#43712、#43715）。驗證身分僅限於註冊時所在的工作區（#43524），且驗證狀態會原生延續至 MCP 工具的後續呼叫（#44346）。此項目最早出現在 v2.68 的推出檢查清單上，隨 alpha.7 叢集自 0.154.0 移出，最終在 0.155.0 推出。¹⁵³

將 Codex 作為 MCP 伺服器執行

已移除（v0.154.0，2026年9月9日）。codex mcp-server 指令與獨立的 codex-mcp-server 執行檔自穩定版 0.154.0 起已不復存在（#42993），為 2026 年 8 月 24 日的棄用畫下句點。官方變更日誌（2026年9月5日）寫道：「codex mcp-server 指令與獨立的 codex-mcp-server 執行檔在 2026 年 8 月 24 日棄用後已移除。請在升級 Codex 之前更新任何會啟動這兩個指令的整合。」整合方應改為對接 app-server 通訊協定，也就是 VS Code 擴充功能與桌面應用程式背後的介面（驗證、對話歷史、核准、串流代理事件）——不過移除說明本身也將其標示為實驗性，並註明「不支援用於正式環境工作負載」——或者從 Claude Code 出發，採用 Claude Code 適用的 Codex 外掛：「從 Claude Code 使用 Codex 來審查程式碼或委派任務。」將 Codex 連接「至」外部 MCP 伺服器（codex mcp ...、/mcp）則不受影響。^125149150

在 CLI 0.153.4 及更早版本中，該指令仍然存在（自 2026 年 8 月 24 日起棄用；自 v0.149.0 起會先向 stderr 輸出 warning: `codex mcp-server` is deprecated and will be removed in a future release.，然後照樣啟動，PR #39657），因此若某項整合無法立即遷移，將版本鎖定為 npm install -g @openai/codex@0.153.4 是權宜之計：^12125145149

codex mcp-server                        # REMOVED in 0.154.0; works only on 0.153.x and earlier (deprecated, warns)

在 0.153.x 及更早版本中，伺服器會提供兩項工具： 1. codex()：以提示、沙箱、模型與核准參數啟動新的工作階段 2. codex-reply()：以 threadId 與提示延續既有的工作階段

搭配 Agents SDK（Python）使用——僅限 CLI 0.153.4 或更早版本：

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="Codex CLI",
    params={"command": "npx", "args": ["-y", "@openai/codex@0.153.4", "mcp-server"]},  # pin: removed in 0.154.0
    client_session_timeout_seconds=360000,
) as codex_mcp_server:
    agent = Agent(name="Developer", mcp_servers=[codex_mcp_server])
    result = await Runner.run(agent, "Fix the failing tests")

值得關注的 MCP 伺服器

實用模式

模式 1：情境感知開發——將 Context7 與您的框架文件搭配使用，讓 Codex 隨時掌握最新的 API 參考資料：

[mcp_servers.context7]
enabled = true
required = true
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

模式 2：輸出上限——MCP 工具回應預設會在約 25K 字元處截斷。對於會回傳大量內容的工具（資料庫查詢、日誌擷取），不妨使用 enabled_tools 限定特定工具，讓回應維持聚焦。

模式 2a：多模態工具輸出（v0.107.0）——自訂工具現在可以在文字之外回傳多模態輸出（圖片、豐富內容）。這讓會產生視覺成品的工具——螢幕擷取、圖表、圖形算繪——能夠直接將成品交給模型分析。⁶²

模式 3：企業級 MCP 治理——透過 requirements.toml 鎖定開發者可使用的 MCP 伺服器：

# In /etc/codex/requirements.toml — only approved servers allowed
[mcp_servers.approved-internal]
identity = { command = "npx @company/internal-mcp" }

任何與 requirements.toml 中身分不符的伺服器都會在啟動時遭到封鎖。完整的政策設定請參閱企業部署。

Code Mode [EXPERIMENTAL]

Code Mode（v0.114.0）會將代理程式的範圍限制在以程式碼為主的操作，提供更為隔離的程式設計工作流程。⁷⁰ 啟用後，代理程式會專注於讀取、撰寫及測試程式碼，不會進行更廣泛的系統互動。

自v0.139.0起，Code Mode可直接呼叫獨立網頁搜尋——包括從巢狀的JavaScript工具呼叫中使用——並接收純文字結果。因此，Code Mode流程無須離開沙箱化的程式設計環境，即可擷取即時資訊。¹⁶² v0.146.0進一步將獨立網頁搜尋擴充至相容的自訂模型供應商，不再僅限於由OpenAI託管的模型。¹¹⁴

v0.146.0讓app-server可連線至遠端Code Mode主機，因此Code Mode執行階段不必再與用戶端位於同一台機器上——最初透過WebSocket連線。¹¹⁴ v0.151.0移除了WebSocket傳輸方式（#40692）：app server的--code-mode-host連線僅接受http://與https:// gRPC端點，而獨立Code Mode主機則僅限使用stdio與gRPC接聽器——在rust-v0.151.0標籤中，其接聽器文件原文為「Transport endpoint: stdio, stdio://, or grpc://IP:PORT.」WebSocket如今僅作為選用端點，用於串流原始OTLP追蹤批次，不再作為工作階段傳輸方式。¹³²

此功能仍處於實驗階段。請查看版本資訊以掌握最新動態。

JavaScript REPL執行階段[REMOVED]

Codex v0.100.0新增了實驗性的JavaScript REPL執行階段（js_repl），v0.106.0則透過/experimental介面正式開放此功能。⁶⁰ 這項指引如今僅供歷史參考。v0.128.0的版本變更記錄包含「Remove js_repl feature」，目前的功能清單也將js_repl與js_repl_tools_only標示為已移除。⁸⁶

請勿在新的設定中加入features.js_repl = true。需要可重複執行的邏輯時，請使用shell命令、納入版本控制的指令碼、MCP工具，或具有scripts/目錄的Codex skill。

什麼是skills？

skills是可重複使用、針對特定任務設計的能力套件，由Codex視需要載入。它們遵循開放式代理程式skills標準。¹³

Skill結構

my-skill/
  SKILL.md           (required: instructions)
  scripts/           (optional: executable scripts)
  references/        (optional: reference docs)
  assets/            (optional: images, icons)
  agents/openai.yaml (optional: metadata, UI, dependencies)

探索位置

Codex會將使用者安裝的skills儲存在$CODEX_HOME/skills（預設為~/.codex/skills），其中也包含位於.system/下的內建系統skills。Codex支援以符號連結連接的skill資料夾。

建立skill

SKILL.md格式：

---
name: security-audit
description: Run a thorough security audit on the codebase.
---

## Security Audit Procedure

1. Scan for hardcoded secrets using `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Check for SQL injection: look for string interpolation in queries
3. Verify input validation on all API endpoints
4. Check dependency vulnerabilities: `pip audit` or `npm audit`
5. Review authentication and authorization patterns
6. Report findings with severity levels (Critical/High/Medium/Low)

中繼資料（agents/openai.yaml）：

interface:
  display_name: "Security Audit"
  short_description: "Full codebase security review"
  icon_small: "./assets/shield.svg"
  brand_color: "#DC2626"
  default_prompt: "Run a security audit on this repository"

policy:
  allow_implicit_invocation: false    # Require explicit $skill

dependencies:
  tools:
    - type: "mcp"
      value: "snyk"
      transport: "streamable_http"
      url: "https://mcp.snyk.io/mcp"

呼叫skills

• 明確呼叫：透過/skills選單，或在提示中提及$skill-name
• 隱含呼叫：Codex會根據任務說明，自動偵測相符的skills（若allow_implicit_invocation: true）
• 建立工具：使用$skill-creator，以互動方式建立新的skill
• 安裝工具：使用$skill-installer install <name>安裝社群skills
• 由執行器提供（v0.146.0）：Codex會探索執行器提供的skills，並讀取其相關資源，包括您明確選取的skills¹¹⁴

上下文預算會截斷skill目錄。 v0.146.0可在上下文空間有限時保留更多可用skills，並會在目錄必須截斷時發出警告。¹¹⁴ 在此之前，大型skill程式庫可能會在沒有提示的情況下遭到裁減，導致您預期應在範圍內的skill根本未被提供。若您仰賴大量skills的隱含呼叫，請留意這項警告。

啟用／停用

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Skills與Slash Commands的比較

偵錯skills

如果skill未啟用：

1. 檢查探索結果：TUI中的/skills應列出該skill
2. 驗證路徑：確認skill資料夾位於可辨識的位置（~/.codex/skills/、專案根目錄或/etc/codex/skills/）
3. 檢查enabled：在config.toml中設定為enabled = false的skills不會載入
4. 檢查隱含啟用：若仰賴自動偵測，請確認agents/openai.yaml中已設定allow_implicit_invocation: true
5. 使用關鍵字：在提示中加入該skill的description用語，以提高隱含比對的成功率

正式環境範例：部署skill

以下是一個完整的多檔案skill，展示參考資料與指令碼如何協同運作：

deploy-skill/
  SKILL.md
  references/
    runbook.md
    rollback-checklist.md
  scripts/
    pre-deploy-check.sh
    smoke-test.sh
  agents/openai.yaml

SKILL.md：

---
name: deploy
description: Deploy the application to staging or production. Runs pre-flight checks, executes deployment, and verifies with smoke tests.
---

## Deployment Procedure

### Pre-flight
1. Run `scripts/pre-deploy-check.sh` to verify:
   - All tests pass
   - No uncommitted changes
   - Branch is up to date with remote
2. Review the runbook at `references/runbook.md` for environment-specific steps.

### Deploy
3. Execute the deployment command for the target environment.
4. Monitor logs for errors during rollout.

### Verify
5. Run `scripts/smoke-test.sh <environment-url>` to confirm critical paths.
6. If smoke tests fail, follow `references/rollback-checklist.md`.

呼叫方式：$deploy to staging或$deploy production with canary rollout

Plugins

Plugins 將 skills、MCP 項目、hooks 與應用程式連接器整合為單一可安裝套件（v0.110.0+）。⁶⁵ 自 v0.117.0 起，plugins 已成為第一級功能：產品範圍的 plugins 會在啟動時自動同步，而 /plugins 則提供 TUI 內建瀏覽器，方便探索與管理。[ ^80] v0.128.0 擴充了 plugin 工作流程，新增 marketplace 安裝、遠端套件快取、遠端解除安裝 API、plugin 內含 hooks、hook 啟用狀態，以及匯入外部代理程式設定等功能。[ ^163] v0.129.0（2026年5月7日）新增 plugin 工作區共享（無須重新發布，即可將一組 plugins 推送給團隊成員）、共享存取控制（可針對個別接收者啟用、停用或撤銷）、來源篩選（限制工作區從哪些 marketplaces 取得內容），以及可直接從 /plugins 瀏覽器呼叫的 marketplace 操作，無須透過 CLI。[ ^166] v0.133.0（2026年5月21日）讓 plugin 探索結果更容易稽核：清單輸出會標示 marketplace、顯示已安裝版本、列出 marketplace 根目錄，並可呈現遠端 plugin 集合，不必猜測結果來自哪個登錄來源。[ ^175] v0.130.0（2026年5月8日）提升 plugin 封裝透明度，也讓共享工作流程更容易掌控：[ ^168]

• 在 plugin 詳細資料中顯示內含 hooks。 /plugins 詳細資料檢視現在會列出 plugin 內含的所有生命週期 hooks（SessionStart、UserPromptSubmit、Stop 等）。安裝 plugin 前，即可清楚查看它會在工作階段中註冊哪些 hooks，不再因為只信任其工具，卻意外遭遇 hook 的副作用。
• shareContext 中的 plugin 共享中繼資料。 從工作區共享 plugin 時，共享連結的承載資料現在會揭露連結中繼資料（建立者、範圍、時效性），讓接收端工作階段得以顯示來源，並決定是否接受。
• 共享設定中的可探索性控制。 共享設定提供可探索性切換選項，團隊可將 plugins 發布至特定工作區或接收者清單，而不必讓整個組織都能在一般清單中找到它們。

v0.143.0（2026年7月8日）預設啟用遠端 plugins。 現在無須使用選擇性啟用旗標，即可使用遠端 plugins；/plugins 目錄也加入資訊更豐富的資料列（除了 git 與本機來源，也會顯示 npm marketplace 來源）。每個項目都會同時顯示遠端版本與本機已安裝版本，版本差異一目瞭然。[ ^188] 對於採用共用 plugin 組合做為標準的團隊，預設啟用遠端功能省去了以往阻礙部署、必須在每台機器上逐一啟用的步驟。

Plugin 來源

自 v0.147.0 起，一次 plugin 搜尋即可涵蓋本機、個人、工作區與遠端目錄；搜尋的是所需功能，而非碰巧收錄它的目錄。搭配可攜式 Agent Plugin 套件，在某個環境中建置的 plugin 能順利安裝至另一個環境，不再受限於建立它的機器或工作區。[ ^200]

Plugin 探索

Codex 會在工作階段開始時告知模型已啟用哪些 plugins（v0.111.0），讓模型更容易探索已安裝的 MCP、應用程式與 skills。[ ^67] 模型可在工作階段中依據任務情境建議相關 plugins。在 v0.117.0 中，產品範圍的 plugins 會於啟動時同步，確保無須人工介入即可取得最新的 plugin 目錄。[ ^80] 自 v0.142.0 起，/plugins 選單會將遠端 plugins 分為 OpenAI 精選、工作區與與我共享區段；符合條件的對話回合也能直接在行內推薦並安裝相關 plugins。[ ^186] 自 v0.151.0 起，plugin/list 與 plugin/installed 會針對每個要求的 cwd 載入有效的 plugin 設定——本機 marketplaces 依要求順序合併，已安裝與啟用狀態會跨儲存庫整合，而無效的專案設定則透過 marketplaceLoadErrors 回報，同時保留有效的本機目錄與全域啟用的遠端目錄。[ ^221]

@plugin 提及功能（v0.112.0+）

在聊天中使用 @plugin-name，即可直接引用任何已安裝的 plugin。[ ^70] 提及 plugin 時，其情境資訊（功能、工具、設定）會自動納入模型的情境視窗，無須另行說明該 plugin 的用途。

@deploy push this branch to staging with canary rollout
@linter check for unused imports in src/

此功能適用於任何已安裝的 plugin，包括自訂 skills、MCP 伺服器與應用程式連接器。

Plugin Marketplace（v0.113.0+）

plugin marketplace 現在提供更豐富的探索功能，包括中繼資料、分類與評分。[ ^71] 安裝時的驗證檢查會確認需要 API 金鑰或 OAuth 的 plugins 是否具備有效憑證。解除安裝端點則能完整移除 plugins 及其相關設定。

新增第三方 Marketplaces（v0.121.0+）

目前的 OpenAI Codex 文件將 marketplace 來源管理置於 codex plugin marketplace 之下。這使 OpenAI 第一方 marketplace 之外的第三方 plugin 發布方式正式化，並支援 GitHub 儲存庫簡寫、HTTP(S) Git URL、SSH URL，以及本機 marketplace 根目錄；若要固定 Git ref，請使用 --ref，而 --sparse PATH 僅可對以 Git 為基礎的 marketplace 儲存庫重複使用。[ ^170]

# GitHub repository (shorthand)
codex plugin marketplace add owner/repo

# Arbitrary git URL
codex plugin marketplace add https://git.example.com/team/plugins.git

# SSH Git URL
codex plugin marketplace add git@example.com:team/plugins.git

# Local directory
codex plugin marketplace add /path/to/local/marketplace

# Upgrade or remove a configured marketplace
codex plugin marketplace upgrade <marketplace-name>
codex plugin marketplace remove <marketplace-name>

新增後，該 marketplace 的 plugins 會與預設項目一同出現在 /plugins 瀏覽器中。App-server 呼叫端（IDE／桌面整合）也有對應端點，可透過程式註冊 marketplaces。[ ^151]

安全性考量：第三方 marketplaces 會以您的 Codex 權限執行任意 plugin 程式碼。新增前請審慎查核來源，首次執行時則建議採用沙箱環境。

Agent Plugins：跨供應商標準（v0.146.0–v0.147.0）

「Agent Plugins」不只是 Codex 的功能名稱，也是開放且不受特定供應商限制的封裝標準。它於2026年8月6日以 Agent Plugins 1.0.0 之名發布，官方網站將其概括為「一種可攜式套件格式，用於封裝可重複使用、能擴充 AI 代理程式的元件」。[ ^203] plugin 是一個含有必要 plugin.json 資訊清單的目錄（採封閉式結構描述，頂層僅允許十個欄位：$schema、name、version、description、author、homepage、repository、license、keywords、extensions；其中「用戶端必須回報並忽略每個未知欄位」），也可包含選用的 skills/ 資料夾（每個直接子目錄只要含有 SKILL.md，即代表一項 skill）、選用的 mcp.json（用於宣告 stdio、Streamable HTTP 或舊版 HTTP+SSE 伺服器），以及選用的反向網域用戶端命名空間目錄，其他用戶端「必須忽略」這些目錄。其規範範圍著重於封裝：此規格「定義正式的 Agent Plugins Specification v1.0.0，用於將可重複使用、能擴充 AI 代理程式的元件封裝為可發布的 plugins」；Agent Skills 與 MCP 則仍各自沿用其底層規格。[ ^203]

治理模式才是關鍵所在。Vercel 發起此提案，並與 Amazon、Anysphere（Cursor）、GitHub、Microsoft 及 OpenAI 共同制定 1.0 規格；規格儲存庫的維護者名單涵蓋 Amazon、Cursor、Microsoft、OpenAI 與 Vercel，而 Google 也在發布當天宣布加入核心維護者行列。[ ^203] 公布的首發用戶端包括 ChatGPT、Codex、Cursor、GitHub Copilot、Kiro 與 VS Code。其中有個顯眼的缺席者：Anthropic 建立了底層 Agent Skills 格式與 MCP，卻不在維護者之列。Claude Code 仍採用自己的 plugin 格式，而 Codex 則從自身端透過 Claude Code marketplace 來源（v0.146.0）與 /import 彌合差距。[ ^203]

以 Codex 而言：v0.146.0 新增 Agent Plugins 資訊清單、工作區 plugin 發布，以及另外兩個 plugin marketplaces——Amazon Bedrock 與 Claude Code¹¹⁴；v0.147.0 則透過可攜式 Agent Plugins 安裝，以及橫跨本機、個人、工作區與遠端目錄的搜尋功能，完成整套流程。[ ^200] 對團隊而言，工作區發布是更具實務效益的一環：可將 plugins 發布至自己的工作區，無須另建公開 marketplace，也不必要求每位開發人員逐一手動新增 Git 來源。

發行說明公布了 Codex 的相關操作介面，但未公開其設定鍵或 CLI 語法。此處僅記錄此功能已推出，以及標準所規範的內容；在 OpenAI 文件正式說明前，資訊清單編寫流程與任何 codex plugin publish 呼叫方式均應視為尚未驗證。

管理 Plugins

codex plugin marketplace add <src>       # Add a marketplace source
codex plugin marketplace upgrade [name]  # Upgrade one marketplace or all
codex plugin marketplace remove <name>   # Remove a configured marketplace
codex plugin list                        # List plugins; includes remote catalog entries (v0.153.0)
codex plugin list --json                 # JSON adds source, version, install + auth policy (v0.153.0)

v0.153.0 將 plugin CLI 的功能從 marketplace 管理擴充至針對遠端 marketplaces 的 plugin 層級操作：codex plugin list 會納入遠端目錄項目（在 JSON 輸出中包含其來源、版本、安裝政策與驗證政策），並可透過既有的 plugin CLI 新增或移除遠端 plugins。遠端目錄會依範圍與集合進行快取——優先採用仍有效的快取結果；若新增要求未在快取中找到 plugin，則會重新擷取一次；未經篩選的遠端清單載入失敗時，也會保留本機精選目錄（若明確選取遠端 marketplace，錯誤仍會顯示）。[ ^226]

在 TUI 中，可使用 /plugins（v0.117.0+）以互動方式瀏覽、安裝及移除個別 plugins，全程無須離開目前的工作階段。[ ^80]

專家提示：Plugins 整合了過去必須分別設定 MCP、安裝 skill 與設定應用程式連接器才能完成的工作。單一 plugin 即可一次封裝這三者，讓團隊成員更快上手，設定也更便於移植。

規劃模式與協作

規劃模式讓Codex在執行變更前先設計方法。此模式自v0.94.0起預設啟用。¹⁴如需「規劃模式與直接執行」的決策樹，請參閱決策框架。

規劃模式與update_plan工具（v0.152.0）：兩者是不同的功能，而且只有其中一項預設啟用。規劃模式是本節所述的協作模式，Codex會先提出方案再執行；此模式自v0.94.0起預設啟用，至今未變。update_plan則是模型可在單次回合中呼叫，用來維護結構化計畫的規劃工具。它在v0.152.0推出時採用選擇性啟用：tools.update_plan.enabled預設為false。停用期間，Codex也會從模型、協作模式、多代理程式、內容壓縮、預熱與目標延續提示中移除內建的update_plan指引（即使自訂基礎指示、模型目錄指示、協作政策與使用者目標文字提及規劃，仍會予以保留）。若要啟用，請在config.toml中明確設定tools.update_plan.enabled = true。¹³⁵

進入規劃模式

/plan                              # Switch to plan mode
/plan "redesign the API layer"     # Plan mode with initial prompt

在規劃模式中，Codex會： - 讀取檔案並分析程式碼庫 - 提出實作計畫 - 在您核准前不會進行變更 - 在專用的TUI檢視畫面中串流顯示計畫

引導模式

引導模式自v0.98.0起預設啟用，可讓您在Codex積極工作時加入新指示，而不會中斷目前的工作。¹⁴

指示有兩種加入方式：

實際範例：

# Codex is refactoring the auth module...

[Enter] "Use bcrypt instead of argon2 — we already have it as a dependency"
→ Codex adjusts immediately, mid-turn

[Tab] "Once auth is done, update the migration script too"
→ Codex finishes auth refactor, then starts the migration

引導模式在TUI中一律保持啟用。若您希望等Codex完成後再提供指示，只需在該回合結束後照常輸入即可，無須切換至特殊模式。

TUI強化功能（v0.105.0–v0.106.0）

語法醒目提示（v0.105.0）：TUI現在會直接為圍欄式程式碼區塊與差異內容加上語法醒目提示。使用/theme即可選擇配色主題。⁶¹

新增TUI命令（v0.105.0+）：⁶¹

語音轉錄（v0.105.0，實驗性）：按下空白鍵，即可透過語音轉錄口述提示。此功能仍屬實驗性質，可能需要麥克風權限。⁶¹自v0.107.0起，即時語音工作階段支援選擇麥克風與揚聲器裝置，讓您能指定音訊輸入／輸出硬體。⁶²在v0.140.0移除，並於v0.145.0恢復：實驗性的/realtime語音控制及其音訊相依套件已在v0.140.0從TUI移除（空白鍵語音轉錄不受影響）。¹⁰²v0.145.0以全新形式恢復語音功能：支援常見本機音訊格式的音訊輸入與音訊工具輸出，以及串流即時V3對話。¹¹²v0.155.0與v0.156.0：即時語音對話。v0.155.0（2026年9月17日）新增實驗性、選擇性啟用的/voice功能：這是一項具備串流逐字稿與麥克風控制的即時對話功能，可在支援的版本中透過/experimental啟用（#43581、#43651、#44331），並提供可設定的靜音快速鍵（#43690），macOS套件中也含有已簽署的語音資源（#43983）。v0.156.0（2026年9月22日）將此功能轉為穩定版並預設啟用（#44921），文件變更記錄也在同日公告：「語音對話現已預設啟用，並提供F8切換鍵、/voice settings選擇器，以及適用於Linux與Windows的內建音訊執行階段。」若要關閉，請在config.toml的[features]下設定realtime_conversation = false。CLI slash-command參考資料仍未列出/voice，而文件中的語音功能頁面介紹的是桌面版應用程式中的ChatGPT Voice，兩者屬於不同介面。¹⁵³¹⁶⁶

其他改進： - 長連結即使跨越多行TUI文字換行，仍可點選（v0.105.0）⁶¹ - 本機檔案連結採用更完善的格式顯示（v0.106.0）⁶⁰ - TUI markdown透過OSC 8中繼資料維持網頁連結的可點選性；空間不足的表格則改用易讀的鍵／值記錄呈現，同時保留連結目標（v0.136.0）¹⁶⁵ - 在支援的終端機中，Markdown連結會顯示為可點選的標籤；其他環境則會保留可見的URL（v0.150.0）[^218] - 已修正sub-agents的Ctrl+C處理方式，可正確終止子行程（v0.106.0）⁶⁰

記憶系統

Codex具備持久性記憶系統（v0.100.0+），可跨工作階段儲存事實、偏好設定與專案背景資訊。²⁴

記憶命令

記憶會儲存在~/.codex/memory/下的markdown檔案中。Codex會在工作階段開始時載入這些記憶，並在日後所有工作階段中據此調整行為。

適合儲存的內容

記憶最適合用於持久性偏好設定與專案事實：

• 專案慣例：「此專案使用定位字元，而非空格」或「API回應一律包含meta欄位」
• 工具偏好設定：「使用pnpm而非npm」或「使用pytest -x --tb=short執行測試」
• 架構決策：「驗證模組位於src/core/auth/，而非src/middleware/」
• 工作流程偏好設定：「向我顯示差異內容前，一律先執行程式碼檢查工具」

管線中的記憶

執行codex exec時，記憶會自動載入。這表示CI/CD管線與指令碼也能受益於互動式工作階段所使用的相同背景資訊，無須在每次呼叫時重複輸入指示。

記憶功能改良（v0.101.0–v0.107.0）

• 機密資訊清理：記憶寫入磁碟前，系統會自動掃描是否含有機密資訊
• CWD感知：記憶檔案現在會包含工作目錄背景資訊，以便回想特定專案內容
• 排除開發者訊息：第1階段的記憶輸入會排除開發者／系統訊息，將重點放在使用者互動上，藉此提升記憶品質
• 以差異為基礎的遺忘機制（v0.106.0）：記憶現在會根據差異移除過時事實，讓記憶儲存庫長期保持精簡且切合所需⁶⁰
• 感知使用情況的選取機制（v0.106.0）：擷取記憶時，現在會考量使用情況，優先選取經常存取及近期相關的記憶⁶⁰
• 可設定的記憶功能（v0.107.0）：記憶功能現在可完整設定。使用codex debug clear-memories即可重設所有已儲存的記憶，重新開始；這在切換至互不相關的專案，或記憶狀態已逐漸偏離現況時特別實用⁶²
• 第2階段模型升級（v0.121.0）：第2階段的記憶整併模型現已升級為gpt-5.4（高於先前的預設模型）。第2階段管線會在工作階段之間執行，將第1階段逐字稿提煉為持久性事實；此次模型變更能以相同的token成本提升回想品質。⁸²
• TUI記憶選單（v0.121.0）：新增工作階段內使用者介面，提供記憶模式、刪除個別記憶及重設按鈕。重設記憶現在會保留過往rollouts，不再使其失效。因此，重設會清除日後可回想的內容，但不會破壞工作階段重播。⁸²

記憶與AGENTS.md的比較

提示：應永久保留的事實，請使用/m_update。若是特定工作階段的背景資訊，只需在對話中直接告訴Codex。若是團隊共享的背景資訊，請使用AGENTS.md。

工作階段管理

Codex 會將工作階段保存在 ~/.codex/sessions/，讓您能在 CLI 與桌面介面之間恢復、分岔工作階段，並進行多執行緒工作流程。

v0.146.0 讓執行緒可直接定址。 /new 與 /clear 現在可接受工作階段名稱；重要執行緒可以釘選，旁支對話也能持續開啟，不必為了切換至另一段對話而先關閉目前對話。¹¹⁴ 實際效果是：長期執行的專案不再只是一串必須靠日期辨認的時間戳記。v0.147.0 新增對話區段：對話可整理至持久保存、能手動排序的區段中；瀏覽長篇逐字記錄時也會逐步載入，不再一次載入全部內容。¹¹⁶ v0.148.0 新增 /export 與命令列分岔功能：/export 可將完整對話寫入 Markdown（複製到剪貼簿或建立新檔案）；codex exec fork 能以非互動方式分岔工作階段；恢復選擇器則可封存及還原工作階段。¹¹⁸ v0.149.0 新增 codex queue——可從命令列將訊息傳送至既有的本機或遠端工作階段——並修正已恢復或分岔的執行緒，使其能還原啟用中的權限設定檔。¹²⁰ v0.150.0 新增自動標題：未命名的終端機任務會自動取得描述性標題，而 /rename 會根據對話建議可編輯的標題。[^218] v0.151.0 新增 /recap：可隨時要求簡短摘要，掌握對話的近期進度與後續步驟；對於符合條件、閒置且未聚焦的對話，Codex 也會自動產生相同摘要並加入逐字記錄。這些要求彼此隔離且範圍受限，並只會在自動要求失敗時重試。¹³² v0.153.0 讓自動功能可選擇停用：tui.auto_recap = false 會取消排定的自動摘要檢查並捨棄待處理的自動摘要結果，手動執行 /recap 則不受影響。¹³⁷

codex agents（v0.149.0）是管理電腦上所有作用中代理工作階段的互動式儀表板：可在單一畫面搜尋、啟動、開啟、重新命名及停止任務，並能自訂快速鍵。在工作階段內，/agents 可切換所有作用中的代理工作階段，/subagents 則可切換目前工作階段的子代理。¹²⁰¹²⁹ v0.150.0 讓您能從對話中直接定址任務：使用 @ 提及其他 Codex 任務，並從終端機要求代理讀取、建立任務或向任務傳送訊息。[^218]

恢復

從上次中斷處繼續：

codex resume                          # Interactive picker (sorted by recency)
codex resume <SESSION_ID>             # Resume a specific session
codex exec resume --last "continue"   # Non-interactive: resume most recent

TUI 內的 /resume slash commands 會開啟同一個具備搜尋功能的互動式選擇器。

分頁載入的執行緒記錄（v0.145.0，於 v0.151.0 正式採用）： 分頁載入的執行緒記錄讓工作階段管理能有效率地恢復工作、搜尋歷史記錄、保存執行緒名稱、支援子代理與記憶功能——歷史記錄會逐頁載入，而非一次載入全部內容。對於累積數百個工作階段的長期工作目錄而言，這一點至關重要。此功能在 v0.145.0 首次以實驗性功能推出；v0.151.0 將這些 APIs 移出實驗階段（thread/turns/list、thread/items/list 與 thread/revert 不再需要實驗性的 API 功能），而且只有當持久執行緒的儲存區支援 thread/turns/list 與 thread/items/list，且 thread/start 未指定 historyMode 時，分頁模式才會成為解析後的預設值。暫時性執行緒，以及由不支援這些 APIs 的儲存區所支援的執行緒，仍會預設採用舊版模式；明確指定的選項也會維持原有行為。此外，在 rust-v0.151.0 標籤中，協定層級的 ThreadHistoryMode 列舉仍預設為 Legacy（protocol.rs:755-758）——這只是針對受支援持久執行緒所解析出的預設值，並非全面切換。¹¹²¹³²

分岔

分岔對話以探索替代方案，同時保留目前進度：

/fork                              # Fork current conversation
/fork "try a different approach"   # Fork with new prompt

分岔會建立彼此獨立的執行緒，並共享截至分岔點為止的相同歷史記錄。自 v0.146.0 起，分岔記錄採用分頁載入，且分岔可建立為暫時性——暫時性分岔不會出現在執行緒清單中，避免一次性實驗混入實際瀏覽的執行緒清單。¹¹⁴ 一個分岔中的變更不會影響另一個分岔。這很適合用來比較不同做法（例如「分岔後改用 Redis，不用 Memcached」），或安全地探索高風險變更。

將執行緒分岔為子代理（v0.107.0）： 現在可將執行緒分岔為獨立的子代理，讓對話衍生出能自主執行的平行工作流程。這項功能擴充了既有的分岔模型——不再只是建立對話分支，分岔後的執行緒會成為擁有自身執行環境的子代理。⁶² 自 v0.117.0 起，子代理採用路徑式位址（例如 /root/agent_a）以及結構化的代理間訊息，使多代理協作更明確，也更容易偵錯。⁷⁵

加密的代理間訊息（v0.138.0+）： Multi-agent v2 現在會加密父代理在建立子代理或向其傳送訊息時所送出的任務文字。spawn_agent、send_message 與 followup_task 的訊息參數均標示為加密：父模型發出工具呼叫時，Responses API 會加密承載資料；本機執行的 Codex 只會攜帶密文（InterAgentCommunication.encrypted_content，純文字內容為空）；接著由 API 在伺服器端解密，再交給接收訊息的模型。¹⁰⁸ 這會帶來3項實際影響：

• 本機工作階段記錄不再包含委派指示的純文字。 您能看到父代理建立了子代理以及子代理傳回的內容，卻無法查看父代理送出的確切指示。若透過工作階段歷史記錄稽核或偵錯多代理執行流程，這項記錄已不復存在；截至2026年7月中旬，追蹤此問題的未結案件仍未連結任何修正。¹⁰⁹ 擴充功能生命週期事件（子代理啟動／停止、工具執行、輪次中繼資料——v0.133.0+）以及 app-server 可觀測性，是目前用來重建事件經過的其餘管道。⁹⁸
• 自訂供應商的模型可能失效。 未設定為支援加密工具使用的模型端點，會以 400 錯誤拒絕加密的 spawn_agent 結構描述（"declares encrypted parameters but is not configured for encrypted tool use"）。若自訂供應商上的多代理委派因這項錯誤而失敗，原因在於加密機制變更，而非您的設定。¹⁰⁹
• Codex 產生的通知仍可直接閱讀。 子代理完成通知由 Codex 自行產生，因此仍是純文字；目前會呈現為具型別的 agent_message 項目，而非序列化的 JSON 封套。¹⁰⁸

OpenAI 尚未公布此變更背後的威脅模型；PR 僅描述密文流程，並未說明其防護對象。

Multi-agent v2 趨於穩定（v0.145.0，需選擇啟用）： Multi-agent v2 體驗最初於 v0.137.0 亮相，並在 v0.138.0 加入加密委派；如今已成為穩定的選擇啟用功能。v0.145.0 新增可設定的子代理模型、個別子代理的推理層級、可設定的並行數、恢復多代理角色，以及改良的代理導覽功能。若您曾在 v0.137/v0.138 的磨合期暫緩採用 v2，這個版本已讓設定介面趨於穩定——子代理模型與推理選項現在位於設定中，不再由執行階段固定指定。¹¹²

執行緒清單

檢視及管理作用中的工作階段：

/status                            # Current session info and token usage
/ps                                # Show background terminals in session

在桌面應用程式中，執行緒會顯示於側邊欄，並提供完整歷史記錄與差異預覽。

工作階段生命週期

工作階段會在 CLI 與桌面應用程式之間同步——可在其中一端開始，再到另一端繼續。

非互動模式（codex exec）

codex exec以非互動方式執行Codex，適用於指令碼、CI/CD與自動化作業。¹⁵

基本用法

codex exec "summarize the repository structure"
codex exec --sandbox workspace-write -c approval_policy=on-request "fix the CI failure"   # exec has no -a flag; set the policy via -c or config
codex exec --json "triage open bugs" -o result.txt

預設情況下，codex exec會將進度／事件寫入stderr，並將代理程式的最終訊息寫入stdout。此設計可與標準Unix管線靈活搭配。

工作階段封存（v0.136.0）

您可以封存工作階段，讓繼續／分支清單保持簡潔，同時保留歷史記錄。可在TUI中使用/archive封存，也可從shell執行：¹⁶⁵

codex archive <session-id>     # archive a session
codex unarchive <session-id>   # restore it

封存後的工作階段無法繼續或建立分支，直到您將其取消封存為止。這項防護措施可避免意外接續原本打算結束的工作階段。同一版本中，codex app-server --stdio可透過stdio模式啟動app-server，以便整合編輯器／主機；此外，/diff現已禁止執行儲存庫提供的Git輔助工具（命令安全性修正）。在Windows上，管理員可透過新增的Alpha佈建流程執行codex sandbox setup --elevated。¹⁶⁵

JSON Lines輸出

使用--json後，stdout會成為JSONL事件串流：

codex exec --json "fix the tests" | jq

事件類型：thread.started、turn.started/completed/failed、item.started/completed、error

{"type":"thread.started","thread_id":"019c5c94-..."}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"..."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122}}

結構化輸出

使用JSON Schema強制規範回應格式：

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

-o／--output-last-message會將最終訊息寫入檔案。

繼續與檢閱工作階段

codex exec resume --last "continue where you left off"
codex exec resume <SESSION_ID> "fix the remaining issues"
codex exec review --base main           # Code review against a branch

主要旗標

CI驗證

codex exec支援在自動化環境中使用CODEX_API_KEY進行非互動式驗證。

codex exec啟動橫幅（v0.130.0）。codex exec啟動橫幅不再顯示舊版的「research preview」字樣。如果您的CI會擷取啟動輸出，現在的橫幅文字更為精簡；結構化的--json事件維持不變。⁹¹

codex remote-control（v0.130.0+）

codex remote-control是頂層命令，可啟動供其他程序驅動的無頭app-server，例如IDE擴充功能、自訂協調器或遠端控制平面。它取代了許多整合開發者過去手動拼湊的多旗標codex app-server叫用方式，並為第三方工具提供單一且穩定的進入點，以存取桌面與IDE介面所搭載的同一套app-server執行階段。⁹¹ v0.133.0改善了此命令的執行方式：它能像前景命令一樣執行、等待就緒、回報機器狀態，同時仍提供明確的常駐程式式start／stop命令，供長期運作的控制器設定使用。⁹⁸ v0.143.0新增codex remote-control pair，可從正在執行的常駐程式產生手動配對碼，讓控制器無須自動探索交握即可連線。當控制程序與常駐程式位於不同主機或網路區段時，這項功能格外實用。¹⁰⁶

# Start a headless, remotely controllable app-server
codex remote-control

# Generate a manual pairing code for an out-of-band controller (v0.143.0+)
codex remote-control pair

# Same lifecycle as a TUI session: thread store, hooks, plugins, MCP, sandbox
# all initialize from your normal config.toml.

如果您正在建置需要列舉大量執行緒歷史記錄、又不希望一次將每個turn載入記憶體的UI，請將codex remote-control與下方的app-server分頁API搭配使用。

App-Server執行緒分頁（v0.130.0+）

app-server用戶端現在可透過3種不同的turn項目檢視，分頁瀏覽大型執行緒：⁹¹

將分頁功能與v0.121.0推出的ThreadStore介面搭配使用，即可有效率地巡覽長時間執行的執行緒；尤其適合協調器與rollout檔案可能位於不同機器的遠端控制部署。⁸² v0.143.0擴大了控制器可檢查的範圍：app-server用戶端現在能列舉可用環境、列出執行緒的後代執行緒，並從特定turn建立歷史分支。這些是UI從較早節點分支執行作業，而不必向前重播所需的基礎功能。¹⁰⁶ v0.151.0將分頁執行緒歷史記錄API移出實驗階段；對於具備支援儲存區的持久執行緒，若thread/start省略historyMode，預設會使用分頁歷史記錄（暫時性執行緒及不支援的儲存區仍沿用舊版模式）；分頁執行緒的完整歷史載入功能已棄用（#40676）。¹³²

即時重新整理App-Server設定（v0.130.0+）

即時app-server執行緒現在無須重新啟動，即可套用config.toml的變更。編輯並儲存設定後，正在執行的執行緒會在下一個turn反映新值。這是與codex remote-control相輔相成的錯誤修正：長時間執行的無頭伺服器可以就地重新設定，無須關閉重建。⁹¹

即時turn範圍設定（v0.151.0）：正在執行的turn現在可在運作途中變更設定。實驗性app-server方法turn/settings/update會更新特定即時turn後續步驟的model、effort、summary及serviceTier，但不影響未來的turn；它也會回報更新是已套用、遭拒，或已失去目標。發布更新後的設定快照前，系統會重新驗證受管理的限制，並保留該turn已准許的核准與Guardian安全屬性。turn/start也接受serviceTierForTurn，讓單一新turn能覆寫服務層級，而不變更執行緒儲存的層級（"default"代表標準速度；省略或設為null則繼承執行緒層級）。¹³²

加密的遠端執行器（v0.141.0）

自v0.141.0（穩定版，2026年6月18日）起，遠端執行器會透過經過驗證、端對端加密的Noise-relay通道連線。控制平面與執行器不再需要信任兩者之間的relay；當協調器跨越網路邊界驅動app-server時，這點至關重要。同一版本也讓跨平台遠端執行保留執行器原生的工作目錄與shell，因此某個作業系統上的控制器驅動另一作業系統上的執行器時，底層不會再改寫路徑或shell語意。TLS現在也接受P-521憑證簽章，以相容企業proxy。¹⁰³

Codex Cloud 與背景任務 [EXPERIMENTAL]

GitLab 支援（Beta，2026年8月19日）：Codex cloud 現已可在所有 ChatGPT 方案中連接 GitLab 專案——連結專案、建立環境、從議題與合併請求啟動任務，以及要求審查；Self-Managed GitLab 需為 19.0 以上版本。¹¹⁹

狀態：Codex Cloud 是一項實驗性功能。介面、定價與可用性可能有所變動。雲端環境由 OpenAI 管理，您無法控制其基礎架構。

Codex Cloud 會在 OpenAI 管理的環境中非同步執行任務。⁴ 自 CLI v0.150.0 起，也能從終端機對話中操作任務：使用 @ 提及其他 Codex 任務，並要求代理程式讀取、建立任務，或向任務傳送訊息。[^218] 若要將 Codex 整合至 CI 管線，另請參閱 GitHub Action 與 CI/CD。

強化雲端任務憑證安全性（v0.152.0）：雲端任務請求可能會攜帶已儲存的 ChatGPT 憑證，因此現在會在載入驗證資訊前限制其目的地——系統會驗證 CODEX_CLOUD_TASKS_BASE_URL 是否為使用連接埠 443 的受信任 ChatGPT HTTPS 來源（若 URL 含有使用者資訊、查詢字串或片段，將遭拒絕），並停用雲端任務後端與環境探索用戶端的重新導向，確保憑證絕不會轉送至重新導向的目的地。¹³⁵

運作方式

1. 提交任務（透過 chatgpt.com/codex、Slack 整合或 CLI）
2. Codex 將您的程式碼儲存庫複製至隔離的雲端沙箱
3. 代理程式獨立作業：讀取程式碼、執行測試並進行變更
4. 完成後，Codex 會建立 PR，或提供差異供您審查
5. 使用 codex apply <TASK_ID> 在本機套用結果

雲端環境的網際網路存取

代理程式的網際網路存取預設為關閉，並依各環境分別設定：

• 關閉：代理程式無法存取網際網路（預設）
• 開啟：可選用網域允許清單及 HTTP 方法限制

Allowed domains: pypi.org, npmjs.com, github.com
Allowed methods: GET, HEAD, OPTIONS

即使代理程式的網際網路存取已關閉，設定指令碼仍可使用網際網路安裝相依套件。

Slack 整合

在 Slack 頻道或討論串中提及 @Codex，即可啟動雲端任務。

必要條件： 1. 符合資格的 ChatGPT 方案（Plus、Pro、Business、Enterprise 或 Edu） 2. 已連接的 GitHub 帳戶 3. 至少已設定一個雲端環境 4. 已為您的工作區安裝 Slack 應用程式

Codex 會回覆任務連結，並在完成後發布結果。

雲端 CLI

codex cloud exec --env <ENV_ID> "Fix failing tests"  # Start a cloud task
codex cloud status <TASK_ID>                          # Check task progress
codex cloud diff <TASK_ID>                            # View task diff
codex cloud list                                      # List recent tasks
codex cloud list --json                               # JSON output
codex cloud apply <TASK_ID>                           # Apply from cloud subcommand
codex apply <TASK_ID>                                 # Apply diff (top-level shortcut)

Codex Desktop App

Codex Desktop App（macOS 與 Windows）提供針對多專案管理最佳化的圖形介面。¹⁶ Windows 版本於2026年3月4日推出，支援原生 PowerShell 與原生 Windows sandbox。⁶⁶

安裝

codex app                      # Auto-downloads and installs on first run

或直接下載：Codex.dmg（macOS）｜可從 Microsoft Store 取得（Windows）

主要功能

Appshots、瀏覽器註解與 Computer Use

5月21日的 App 更新讓 Desktop App 不再只是執行緒管理工具，而是更強大的情境資訊介面。當 Codex 必須先掌握另一個 Mac App 的狀態才能執行工作時，請使用 Appshots：Codex 會擷取最前方的視窗，以及該 App 提供的可見與畫面外文字，並將附件儲存在本機工作階段歷程中。⁹⁹

進行網頁與前端工作時，若頁面不需驗證，請優先使用 App 內瀏覽器：它可提供您與 Codex 共用的實際呈現預覽，支援點擊、螢幕截圖、素材下載與唯讀檢查JavaScript等瀏覽器操作，還能讓您在頁面區域加上註解，交由 Codex 在下一回合處理。⁹⁹ 對於已登入的網站，請繼續使用瀏覽器擴充功能（Chrome、Edge、Brave、Opera 或 Vivaldi；Opera 不提供側邊對話）。網站工具（WebMCP，2026年8月25日）：在 Desktop App 的內建瀏覽器中，ChatGPT Work 與 Codex 可使用網站提供的工具與頁面互動；請在最新版 Desktop App 中使用 GPT-5.6 Sol 或 GPT-5.6 Terra，因為 GPT-5.6 Luna 以及 Enterprise 或 Edu 工作區不支援網站工具。¹²⁷

僅在結構化整合或瀏覽器預覽無法驗證任務時，才使用 Computer Use。它可以檢查並操作獲准的 Mac App，但檔案編輯與 shell 指令仍受 Codex 核准機制及 sandbox 規則約束。鎖定後使用的範圍也十分嚴格：Mac 鎖定後，Codex 僅能在進行中的受信任 Computer Use 回合內暫時存取獲准的 App，並設有重新鎖定防護與本機輸入偵測。⁹⁹

執行緒模式

每個執行緒皆會以3種模式之一執行，並在建立時選定：

Worktree 隔離機制：

啟動 Worktree 執行緒時，Desktop App 會： 1. 在暫存目錄中建立新的 git worktree（git worktree add） 2. 從目前的 HEAD 簽出全新分支 3. 在 worktree 內執行代理程式——所有檔案變更皆相互隔離 4. 完成後顯示差異檢閱——由您選擇要合併回原專案的變更

因此，多個 Worktree 執行緒可在同一個儲存庫中同時執行而不發生衝突。每個執行緒都有自己的分支與工作目錄。

Worktree 設定與執行緒擁有權（v0.151.0）：受管理的 worktree 行為由專用設定剖析器依現有的[desktop]設定解析——worktree 根目錄預設為$CODEX_HOME/worktrees、自動清理預設為啟用，並保留15個 worktree；設定的根目錄、清理旗標與保留數量都會在使用前進行驗證。每個受管理的連結 worktree 也可在其 Git 中繼資料內包含具版本控制的codex-thread.json擁有權紀錄，將其綁定至特定執行緒：寫入作業具原子性且不會覆寫既有資料（重複綁定具冪等性，擁有者衝突則會遭拒），而主要、巢狀及未受管理的簽出都會在接觸擁有權中繼資料前遭到拒絕。¹³²

受管理的 worktrees 於 v0.154.0 進入CLI（實驗性功能）：啟動時使用--worktree，或在 TUI 中使用/worktree，即可為新工作階段或分支工作階段建立隔離簽出；codex exec支援受管理的 worktrees 以執行自動化；TUI 工作階段指令與 worktree 瀏覽器則可讓您列出、瀏覽及繼續 worktree 工作階段（#42196、#42366、#42652、#43069、#43120、#43286）。v0.155.0 新增相關管理功能，但 worktrees 仍非預設啟用：代理程式總覽可以隱藏、封存及刪除 worktree 工作階段，也會顯示擁有權詳細資訊；刪除乾淨的受管理 worktree 時，系統會要求確認（#43942、#44424、#44433）。預設啟用變更（#44870）雖已於9月11日合併，但未納入穩定版0.155.0；此結論已依 rust-v0.155.0 標籤檢查提交譜系。¹⁴⁹¹⁵³

受管理的 worktrees 自 v0.156.0 起預設啟用：#44870 將worktrees提升為穩定功能、設為預設啟用，並從/experimental中移除。同時推出的功能包括：worktree 工作階段可連接至既有的本機常駐程式，無須自行啟動（#46498）；也可直接從代理程式總覽建立 worktree 工作階段（#45276），該總覽另新增狀態篩選分頁（#46839）。若您的指令碼或設定是假設 worktrees 僅在明確要求時才會啟用，0.156.0 正是改變此行為的版本。若要停用：請在config.toml的[features]下設定worktrees = false（單次執行：--disable worktrees）。較舊的本機常駐程式：若建立 worktree 或執行/cd時遭到封鎖，並顯示「The local Codex service cannot check background terminals」，請執行codex app-server daemon update，然後重新啟動 Codex。¹⁶⁶¹⁶⁸

自動化

自動化會在 App 本機執行，因此 App 必須保持執行，且專案必須可從磁碟存取：

• 在 Git 儲存庫中，自動化會使用專用的背景 worktrees（與您的工作目錄隔離）
• 在非 Git 專案中，執行作業會直接在專案目錄內進行
• 自動化會採用您的預設 sandbox 設定

設定自動化： 1. 在 Desktop App 中開啟專案 2. 按一下側邊欄中的「Automations」分頁 3. 定義觸發條件（排程、webhook 或手動） 4. 撰寫提示詞並選擇執行模式（local 或 worktree） 5. 設定自動化執行的推理層級（App v26.312）⁷² 6. 自動化會依排程執行，並將結果排入佇列以供檢閱

使用案例： - 問題分類處理：自動分類新問題並排定優先順序 - CI 監控：監看建置失敗並提出修正建議 - 警示回應：針對監控警示執行診斷分析 - 相依套件更新：檢查並套用安全性修補程式

結果會顯示於檢閱佇列中，等待人工核准。

Windows 支援

Codex Desktop App 於2026年3月4日在 Windows 上推出（App v26.304），提供原生 PowerShell 支援、原生 Windows sandbox，以及包括 skills、自動化與 worktrees 在內的完整功能，無須使用 WSL。⁶⁶

GitHub Action 與 CI/CD

官方 GitHub Action 可將 Codex 整合至 CI/CD 管線中。¹⁸

基本用法

# .github/workflows/codex.yml
name: Codex
on:
  pull_request:
    types: [opened]

jobs:
  codex:
    runs-on: ubuntu-latest
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          sandbox: workspace-write
          safety-strategy: drop-sudo

設定選項

輸出：final-message，供後續步驟／作業使用的 Codex 最終回應文字。

安全策略

存取控制

with:
  allow-users: "admin,maintainer"     # Limit who can trigger
  allow-bots: false                   # Block bot-triggered runs

預設：只有具備寫入權限的協作者才能觸發 Codex 工作流程。

Codex SDK

TypeScript SDK 可將 Codex 的 Agent 能力嵌入自訂應用程式。¹⁹

安裝

npm install @openai/codex-sdk

基本用法

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();

// Multi-turn conversation
const turn1 = await thread.run("Diagnose CI failures and propose a fix");
console.log(turn1.finalResponse);

const turn2 = await thread.run("Implement the fix and add tests");
console.log(turn2.items);

// Resume a previous session
const resumed = codex.resumeThread("<thread-id>");
await resumed.run("Continue from previous work");

進階 SDK 功能

• runStreamed(...)：提供中間更新的非同步事件串流
• Python SDK 驗證（v0.132.0+）：以 API 金鑰登入、ChatGPT 瀏覽器／裝置代碼流程、帳戶檢查及登出，皆已成為第一級 SDK 路徑。⁹⁷
• 純文字回合便利功能（v0.132.0+）：Python 回合的 API 可接受純字串，並傳回資訊更豐富的 TurnResult 中繼資料，包含已收集的項目、時間資訊與用量。⁹⁷
• outputSchema：強制最終輸出符合 JSON 結構
• 多模態輸入：傳入文字與本機圖片（{ type: "local_image", path: "..." }）
• 圖片工作流程（v0.117.0）：view_image 會傳回 URL、產生的圖片可重新開啟，且恢復工作階段後仍會保留圖片歷程⁷⁵
• 多環境 view_image（v0.130.0）：對於橫跨多個環境的工作階段（v0.124.0 導入每回合的環境與工作目錄選擇，v0.125.0 再加入固定沿用環境的機制），view_image 現在會透過所選環境解析檔案路徑，而非透過協調器的本機檔案系統。從遠端環境附加的圖片，會以該環境的工作目錄為基準擷取，而不是以執行 SDK 的主機為基準。⁹¹

Thread 與 Client 設定

// Custom working directory, skip git check
const thread = codex.startThread({
  workingDirectory: "/path/to/project",
  skipGitRepoCheck: true,
});

// Custom environment and config overrides
const codex = new Codex({
  env: { CODEX_API_KEY: process.env.MY_KEY },
  config: { model: "gpt-5.5" },
});

工作階段會保存在 ~/.codex/sessions。

執行環境：Node.js 18+。

效能最佳化

Context 管理

Context window 會因模型而異。目前的 GPT-5.6 系列（Sol、Terra、Luna）採用 272K 視窗；上一代旗艦模型 GPT-5.5 在 Codex 中提供 400K（在 API 中為 1M）；GPT-5.4／GPT-5.4-mini（將於 2026年8月31日退出 Codex）則分別提供 1M／400K；舊版 GPT-5.3-Codex 系列則為272K 輸入 + 128K 輸出（總預算 400K）。這些容量都會比預期更快用完，因此應主動管理：

1. 定期使用 /compact：摘要對話歷程以釋出 token
2. 提供本機文件：高品質的 AGENTS.md 與本機文件可減少探索負擔（探索會占用 context）
3. 使用 @ 附加特定檔案：直接引用檔案，不必要求 Codex 尋找
4. 讓提示聚焦：指定明確檔案與範圍的提示，比開放式探索耗用更少 context

實驗性 context 管理（v0.153.0，預設停用）：features.context_management.experimental_mode 會為符合資格、使用 Codex 後端的 ChatGPT Plus、Pro 與 Pro Lite 工作階段，啟用一套協同運作的 context 堆疊——包含 token 預算 context、歷程筆記與 new_context 工具。使用 API 金鑰的工作階段、自訂供應商、非 Codex 端點及暫時性結構化 thread 均不適用。此旗標仍明確處於開發階段：請將其視為 context 處理未來走向的預覽，不宜據此建立工作流程。¹³⁷ v0.154.0 新增能力閘門：系統會在工作階段啟動時，根據作用中模型的能力判定是否符合資格（#43147）——這正是 Codex 模型文件中，針對 Plus 與 Pro 登入方式以 Astra 為名所描述的同一項功能介面（請參閱「我該選擇哪個模型？」下方的跨 context 說明）。¹⁴³¹⁴⁹ 截至 v0.157.0，隨附目錄中的模型皆未標示為支援此功能（#47397），因此使用該目錄時，此設定不會產生任何效果。¹⁷¹

Token 效率

速度最佳化

1. gpt-5.3-codex-spark：適合互動式協作的低延遲變體
2. --profile fast：預先設定的 gpt-5.6-luna，採用低推理強度
3. 平行執行工具：Codex 會同時執行彼此獨立的讀取／檢查作業，因此可據此設計提示結構
4. 成果導向迴圈：要求「實作、測試、修正，全部通過後停止」，而非逐步下達指示

如何偵錯問題？

常見問題與解決方法

錯誤訊息參考

codex doctor有什麼作用？

codex doctor是在提交錯誤報告或偵錯損壞的安裝之前，應先執行的單一命令。 它會將本機執行階段、設定、驗證、終端機、網路與狀態彙整至一份報告中， 而專案本身的issue範本也會要求您貼上其輸出內容。¹⁶⁰

codex doctor                           # Full human-readable report (the default)
codex doctor --summary                 # Compact view
codex doctor --json                    # Redacted structured JSON, for bug reports
codex doctor --all                     # Expand truncated lists
codex doctor --no-color                # Strip ANSI color

報告分為數個固定區段，方便您快速瀏覽所需資訊：¹⁶⁰

每項檢查都會附上狀態標記——✓正常、✗失敗、⚠警告、○閒置——以及摘要 行。--json會以固定識別碼作為每項檢查的索引，因此除了供人眼閱讀， 也能用於CI或支援指令碼。¹⁶⁰

此命令的功能隨版本逐步擴充：最初於v0.131.0推出；v0.135.0新增環境、Git、 終端機、應用程式伺服器與執行緒清單報告；v0.139.0則新增編輯器與分頁器 詳細資料（JSON中的敏感值會經過遮蔽）。^96173162

請優先使用，而非最後才用。多數「Codex壞掉了」的回報，其實都能歸結為doctor 已明確指出的問題：過期的驗證模式、無法剖析的config.toml，或另一個安裝版本 遮蔽了PATH中的版本。

診斷工具

codex doctor                           # Full local diagnostic (start here)
codex --version                        # Check CLI version
codex login status                     # Verify authentication
codex mcp list                         # Check MCP server status
codex debug app-server --help          # Debug app server issues

工作階段內的TUI診斷：

/status                                # Token/session overview
/debug-config                          # Show config layers and requirement sources
/compact                               # Summarize history to reclaim context

注意：codex --verbose並非有效的頂層旗標。請使用上述偵錯子命令與TUI診斷。

全新重新安裝

npm uninstall -g @openai/codex && npm install -g @openai/codex@latest

這會保留~/.codex/（驗證、設定、工作階段）。如需鎖定特定版本、在有問題的版本發布 後降級，或完整清除狀態，請參閱 更新、降級或解除安裝。

偵錯模式

codex debug app-server send-message-v2  # Test app-server client

回報問題

/feedback                              # Send logs to Codex maintainers (in TUI)

您也可以前往github.com/openai/codex/issues提交issue。¹

Codex Security［預覽］

Codex Security於2026年3月6日進入研究預覽階段，將具備內容脈絡感知能力的應用程式安全審查帶入Codex技術堆疊。⁷⁷ ChatGPT Pro、Enterprise、Business與Edu客戶可透過Codex網頁版使用。

運作方式：Codex Security會分析程式碼儲存庫，建立專案專屬的威脅模型；依實際影響辨識並分類弱點，再於沙箱環境中進行壓力測試以驗證發現。代理程式會優先呈現可信度較高的發現及其修正方法，減少無關痛癢的錯誤所造成的雜訊。

效能：研究預覽期間，Codex Security掃描了120萬次commit，並找出10,561個高嚴重性弱點。精準度持續提升——雜訊減少84%、嚴重性高估情形降低逾90%，誤判率更減半。此系統已在OpenSSH、GnuTLS與Chromium中發現真實弱點，其中14項獲指派CVE編號。⁷⁷

注意：Codex Security與CLI內建的沙箱安全模型彼此獨立。沙箱會保護您的電腦免受Codex影響；Codex Security則保護您的程式碼庫免受弱點威脅。

企業部署

管理員控制（requirements.toml）

管理員可透過requirements.toml強制執行企業政策。這是由管理員控管的設定檔，用於限制使用者無法覆寫的安全性敏感設定：²¹

v0.146.0 新增企業方案辨識功能，以及管理員對應用程式內更新的控制。¹¹⁴ 對受管理的裝置群而言，這決定了是由開發人員在發現新版本時自行更新 CLI，還是由管理員決定版本的推出時程。版本資訊雖然公布了這項控制功能，卻未公開其 requirements.toml 鍵；在 OpenAI 提供文件之前，應將確切的設定名稱視為尚未驗證。

# /etc/codex/requirements.toml

# Restrict which approval policies users can select
allowed_approval_policies = ["on-request", "never"]   # `untrusted` retired in v0.149.0

# Limit available sandbox modes
allowed_sandbox_modes = ["read-only", "workspace-write"]

# Control web search capabilities
allowed_web_search_modes = ["cached"]

# Allowlist MCP servers by identity (both name and identity must match)
[mcp_servers.approved-server]
identity = { command = "npx approved-mcp-server" }

# Admin-enforced command restrictions
[[rules.prefix_rules]]
pattern = [{ token = "rm" }, { any_of = ["-rf", "-fr"] }]
decision = "forbidden"
justification = "Recursive force-delete is prohibited by IT policy"

[[rules.prefix_rules]]
pattern = [{ token = "sudo" }]
decision = "prompt"
justification = "Elevated commands require explicit approval"

使用者層級的 config.toml 用於設定偏好；相較之下，requirements.toml 是強制約束層，會限制使用者可選擇的值，且使用者無法覆寫。管理員需求規則只能設定為提示或禁止（絕不會在未告知的情況下允許）。

macOS MDM 設定

使用 com.openai.codex 偏好設定網域，透過 MDM 進行發布。²¹ Codex 支援標準 macOS MDM 承載資料（Jamf Pro、Fleet、Kandji 等）。請將 TOML 編碼為不換行的 base64：

優先順序（由高至低）：

1. macOS 受管理偏好設定（MDM）
2. 從雲端擷取的要求（ChatGPT Business / Enterprise）
3. /etc/codex/requirements.toml（本機檔案系統）

雲端要求只會填入尚未設定的要求欄位，因此優先層級較高的受管理設定一律優先。雲端要求採盡力而為模式；若擷取失敗或逾時，Codex 會在不套用雲端設定層的情況下繼續運作。

OpenTelemetry 整合

Codex 支援將標準 OTel 環境變數中的追蹤情境一路傳遞至 OpenAI API 呼叫。請在啟動 Codex 前設定標準環境變數：

# Point Codex at your OTel collector
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-collector.internal:4318"
export OTEL_SERVICE_NAME="codex-cli"
export OTEL_RESOURCE_ATTRIBUTES="team=platform,env=production"

# Launch Codex — trace context propagates to all OpenAI API calls
codex

• 支援標準 OTEL_* 環境變數（端點、服務名稱、資源屬性）
• 追蹤情境會透過 Codex 傳遞至 API 呼叫，實現端對端可觀測性
• 使用資源屬性，依團隊、環境或專案標記追蹤資料
• 啟用提示詞／工具記錄時，請留意隱私要求；追蹤資料可能包含程式碼片段
• 可設定的 OpenTelemetry 追蹤中繼資料（v0.130.0+）。 除了標準的 OTEL_RESOURCE_ATTRIBUTES 封裝之外，codex-otel crate 現在也提供可設定的追蹤中繼資料，讓管理員能以組織專屬維度（成本中心、專案 ID、工單參照）標記追蹤資料，無須在每次呼叫時從頭重建 OTEL_RESOURCE_ATTRIBUTES。搭配同一版本推出的強化審查／意見回饋分析功能，即可跨 CLI、app-server 與 remote-control 工作階段進行統一的偵錯與分流處理。⁹¹