Codex CLI：完整技術參考指南

重點摘要：Codex是跨介面的程式開發代理：能讀取您的程式碼庫、在作業系統層級的沙箱中執行命令、修改檔案，並將任務委派至雲端。掌握五大系統——config.toml、沙箱與核准模型、AGENTS.md、MCP和skills——就能讓工作事半功倍。模型怎麼選：OpenAI的模型文件目前建議，複雜的程式開發與代理工作使用GPT-6.1 Sol（gpt-6.1-sol，自v0.159.1起為CLI內建的預設模型），最艱難的端到端工作使用GPT-6-Astra，範圍明確且需反覆執行的任務則使用GPT-6 Luna。可用模型取決於方案、用戶端和工作區設定；GPT-6 Sol與GPT-5.6系列模型仍保留在模型選單中，而透過ChatGPT登入使用Codex的使用者，將自2026年10月14日起無法再使用GPT-5.5。^146171178初次使用？請直接前往安裝和快速入門。想追蹤版本更新？最新穩定版為v0.164.0（2026年10月23日）：提供10個/presets欄位以儲存可重複使用的提示詞、支援行內/model與/permissions引數、在全螢幕對話記錄中顯示圖片預覽、支援企業管理的MCP登入，並預設啟用Bedrock設定精靈；版本更新重點先概述目前狀態（哪些功能預設啟用、哪些仍屬實驗性質），再逐一介紹各版本，而變更紀錄則列出本指南的每次更新。^116178182183

Codex是跨介面的程式開發代理，而非僅能撰寫程式碼的聊天機器人。CLI會讀取您的程式碼庫、在沙箱中執行命令、修改檔案、透過MCP連接外部服務，並將耗時較長的任務委派至雲端。它在本機執行，卻能綜觀全局；同一套智慧能力支援五種不同介面，配合您的工作方式。其中包括瀏覽器擴充功能（Chrome、Edge、Brave、Opera和Vivaldi），讓Codex在瀏覽器中運作，無須接管瀏覽器。⁹⁰¹²⁷

隨手使用Codex與有效運用Codex的差別，在於是否掌握五大核心系統。掌握這些系統，就能讓Codex成為提升工作效能的助力：

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

我花了數個月，在正式環境的程式碼庫、CI/CD流程和團隊工作流程中，並用Codex與Claude Code。這份指南將這些經驗整理成完整的參考資料，也是我剛開始使用時希望能找到的指南。每項功能都附有實際語法、真實設定範例，以及連資深使用者也容易踩到的邊界情況。

重點摘要

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

如何使用本指南

這是一份超過 3,300 行的參考指南——請從符合您經驗程度的位置開始：

文末的快速參考卡彙整所有主要指令，方便快速瀏覽。

版本更新重點：近期變更

以下依版本列出更新紀錄，由新到舊排列，方便讀者追蹤Codex的發行進度。第一次使用？請直接跳至快速入門；無須閱讀以下內容，也能開始上手。驗證細節（版本比較、提交清單、文件檢查）請見註腳。

目前狀態

截至2026年10月23日的Codex CLI

• 穩定版：v0.164.0（10月23日，npm latest），以0.164.0-alpha.11加上1筆發行提交為基礎（alpha.12包含穩定版未納入的9筆提交），比v0.163.0多出330筆提交：提供10個編號的/presets儲存欄位，可儲存重複使用的提示詞與slash commands；支援直接輸入/model [model] --reasoning <level> --speed <tier>及/permissions <profile-id>；在Kitty或Sixel終端機的全螢幕對話紀錄中預覽圖片；為MCP連線提供企業管理的授權；為支援的遠端Bash命令提供憑證遮罩（由credential_masking旗標控制）；並預設啟用Amazon Bedrock設定精靈。前一版為v0.163.0（10月15日），新增可搜尋的/config面板、前導鍵，並預設啟用Daybreak。
• Alpha版：npm alpha為0.165.0-alpha.1（10月23日，穩定版發布後數小時）。在該標籤中，reasoning_effort_override已列為穩定功能並啟用；guardianv3、guardian_recorded_items及tui_multi_backend則為新增功能，預設關閉。0.164系列從alpha.1（10月16日）一路發布至alpha.12（10月22日），期間另有常規發行流程之外的建置版本0.163.0-alpha.11.1與11.2（10月21日至22日），以及0.164.0-alpha.11.1（10月23日）。
• 自v0.159.1起的預設模型：GPT-6.1 Sol取代GPT-6-Astra，Amazon Bedrock亦同。若要維持使用其他模型，請在config.toml中設定model。v0.164.0隨附的模型目錄與v0.162.1及v0.163.0逐位元組完全相同，列出的模型也與v0.159.1相同。
• 自v0.164.0起預設啟用：Amazon Bedrock設定精靈（bedrock_setup_wizard，穩定功能；在[features]下設定bedrock_setup_wizard = false即可關閉）、增量工具更新（incremental_tools，穩定功能），以及MCP OAuth更新協調（mcp_oauth_refresh_coordination，穩定功能）。受管理的worktrees與即時對話已永久啟用：其旗標標記為已移除，功能則維持開啟。
• 自v0.163.0起預設啟用：Daybreak（cli_daybreak，現已列為穩定功能；在[features]下設定cli_daybreak = false可隱藏控制項）與程式碼模式中斷（code_mode_interrupt，穩定功能），因此後續訊息也會停止正在執行的Code Mode儲存格；使用API金鑰的工作階段預設可使用Cyber存取方案（api_key_cyber_access_programs）。已移除：shell_zsh_fork與unified_exec_zsh_fork，系統會忽略這些設定並顯示遷移通知。
• 自v0.162.0起預設啟用：instant_interrupt，新輸入會搶先中斷模型回應（在[features]下設定instant_interrupt = false即可關閉）；此旗標仍標記為開發中。
• 自v0.161.0起預設啟用：API金鑰模型探索（在[features]下設定api_key_model_discovery = false即可關閉）。
• 自v0.158.0起預設啟用：向已提升權限的終端機輸入內容時須取得核准（在[features]下設定write_stdin_approval = false即可關閉），以及全螢幕TUI中的選取即複製與按右鍵貼上（可在[tui]下設定copy_on_select = "never"、right_click_paste = "off"）。Guardian討論串上下文一律啟用；thread_context設定會被忽略。
• 自v0.157.0起預設啟用：全螢幕對話紀錄（可在[tui]下設定fullscreen_transcript = false）與背景伺服器自動啟動（可在[features]下設定daemon_auto_start = false，或使用--no-daemon）。
• 自v0.156.0起預設啟用：/voice、受管理的worktrees，以及Guardian重複使用父層壓縮結果。
• 須自行啟用或實驗性功能：Codex Cloud、程式碼模式及其依相關性排序的工具搜尋（code_mode_tool_search，v0.162.0）、Guardian歷程擷取（guardian_conversation_history_tools，v0.160.0），以及v0.164.0發布時預設關閉的開發中旗標（自v0.163.0起：async_compaction、credential_masking、output_token_replay、retain_client_tool_outputs、subagent_default_context_limits、code_mode_host_grpc、code_mode_tool_description_first、guardian_trust_orchestrator_connectors；v0.164.0新增：app_server_websocket_compression、executor_capability_discovery_v2、mcp_tool_list_changed、multi_env_copy_file、runtime_agent_instances、subagent_thread_environments、wake_on_agent_messages）。實驗性上下文管理目前尚未開放使用。
• 模型：GPT-6.1 Sol適用於複雜的程式設計工作，GPT-6-Astra適用於最棘手的工作，GPT-6 Luna適用於可重複執行的任務。GPT-6 Sol與Luna啟動時預設使用Fast（耗用2.5倍點數）；GPT-6.1 Sol則不會。GPT-5.5於2026年10月14日退出Codex。
• 固定版本：執行npm install -g @openai/codex@0.164.0，再執行codex --version。^{176178186187188189192193194195}

v0.164.0（2026年10月23日）

0.164系列以自身的alpha版本為基礎發布穩定版。v0.164.0於10月23日發布（UTC 04:48；UTC 04:52成為npm latest），以0.164.0-alpha.11加上1筆發行提交為基礎；alpha.12（10月22日）比該基準多出9筆提交，而常規發行流程之外的0.164.0-alpha.11.1（10月23日，UTC 01:58）則在alpha.11基礎上新增4筆提交。與v0.163.0相比，共有330筆提交。3個旗標改為預設啟用，並標記為穩定功能：bedrock_setup_wizard（Amazon Bedrock設定精靈；偵測到憑證時，API金鑰輸入選項會與其他AWS登入方式列在同一組）、incremental_tools及mcp_oauth_refresh_coordination。worktrees與realtime_conversation旗標標記為已移除，功能則維持啟用，因此受管理的worktrees與即時對話已無法切換開關；stable_environment_tools與transcript_v2也已移除。新增7個開發中旗標，預設皆為關閉。隨附的模型目錄沿用v0.162.1發布時的同一份blob。¹⁹⁴¹⁹⁵

TUI新增功能。/presets提供10個編號的儲存欄位，搭配鍵盤選單，可儲存重複使用的提示詞與slash commands；預設組合可由編輯區文字建立，也可依目前的模型、推理強度與速度建立，並持續儲存在目前生效的使用者設定中，位置為tui.presets（#54380、#54381）。/model [model] --reasoning <level> --speed <tier>會將模型、推理強度與速度套用至目前的工作階段，不會變更已儲存的預設值；旗標值可用空格或=分隔。省略模型時，設定會套用至目前的模型；單獨輸入/model仍會開啟選擇器（#54378）。/permissions <profile-id>可直接選取內建或自訂的權限設定檔，例如/permissions :read-only，並提供:ask-for-approval與:approve-for-me作為別名（#54383）。在支援Kitty或Sixel圖形的終端機上，全螢幕對話紀錄會以尺寸受限的縮圖預覽已檢視及產生的圖片；遠端工作區、不支援的終端機及過大的圖片則維持純文字項目（#54216）。¹⁹⁴

連線與憑證。直接設定的MCP伺服器可透過儲存在金鑰圈中的帳號範圍企業授權，或專用登入流程進行驗證，也支援需要密鑰的OAuth用戶端；企業管理的授權擴充功能會透過2026-07-28協定協商，當帳號擁有者變更，或企業登入取代該授權時，原授權便會撤銷（#55334、#55859、#56001）。憑證遮罩已涵蓋支援的遠端Bash命令與zsh快照工作階段，也包含自訂供應商提供的憑證：命令只會看見預留位置，執行器本機的代理伺服器則會針對符合的目的地注入實際憑證；若無法使用遮罩，便會退回未遮罩的執行方式並顯示警告。該標籤中的credential_masking旗標仍預設關閉（#54309、#54432、#56049）。¹⁹⁴¹⁹⁵

修正與維護。壓縮失敗時，不再將不完整的摘要留在對話歷程中；背景壓縮失敗時，也會採取備援處理，不會觸發panic（#53932、#55581）。恢復工作階段時，能找到已壓縮的歷程，並還原已儲存的討論串設定，不再以全域預設值覆蓋（#54008、#55923）。在Windows上，HTTPS與WebSocket連線會使用已登入使用者的Negotiate或NTLM憑證，回應代理伺服器的驗證要求（#55994、#56000）。在多個子命令層級指定-c或--config時，所有覆寫設定都會保留（#56022）；佇列中的提示詞會等待待處理的權限選擇完成（#55682）；沙箱也會檢查macOS上大小寫不同的中繼資料路徑，以及用於尋找執行檔、可遭替換的符號連結（#54273、#55384）。磁碟用量亦有所降低：系統會刪除未使用的安裝版本（保留目前與前一次選用的常駐程式版本）、清理已棄用的市集簽出目錄，並限制常駐程式日誌的大小（#53827、#55149、#55689、#55690、#55856）；內嵌的JavaScript執行階段也為最佳化的Array.sort新增安全檢查（#54519）。¹⁹⁴ 建議行動：升級。除非您是首次設定Bedrock，否則不會察覺預設行為有任何變化。Bedrock設定精靈現在會自動執行（在[features]下設定bedrock_setup_wizard = false即可關閉）；若您曾在[features]下設定worktrees或realtime_conversation，這些設定鍵現在會被忽略。¹⁹⁴¹⁹⁵

v0.163.0（2026年10月15日）

0.163系列正式推出穩定版，取自獨立分支。 v0.163.0於10月15日發布（UTC 21:30；npm的latest於UTC 21:37更新），以0.163.0-alpha.10.2為基礎，再加上1筆發布提交；該版本是在alpha.10基礎上獨立建置的版本。主線的alpha.11（10月14日）包含穩定版未納入的23筆提交，再次沿用0.158的模式。與v0.162.1相比，共有232筆提交。2個功能旗標改為啟用，且都標記為穩定：cli_daybreak（Daybreak控制項、/daybreak切換功能，以及為符合資格的OpenAI帳號自動選用Cyber存取方案；當伺服器提供存取權限時，codex exec可使用OpenAI API金鑰選用此方案）與code_mode_interrupt（中斷回合時，也會停止執行中的Code Mode儲存格及其巢狀工具呼叫）。已標記為穩定的api_key_cyber_access_programs也改為啟用。instant_interrupt維持啟用，仍處於開發階段。¹⁹²¹⁹³

TUI新增功能。 /config會開啟可搜尋的偏好設定面板，分為外觀、通知、輸入、工作階段與文字選取等分頁；支援即時套用的變更會立即生效，面板會指出哪些變更需要重新啟動，編輯結果則會儲存至所選的本機設定檔（#52990、#53429）。/keymap可設定前導鍵：tui.keymap.global.leader預設為ctrl-x，接著可按下leader c等組合鍵；快捷鍵提示會保持開啟，直到您選擇或取消，而語音靜音快捷鍵則從Ctrl+X改為F9（#52273）。/daemon可重新啟動受管理的背景伺服器，事前會警告哪些工作可能因此中斷，並在重新啟動後再次連線（#53173）。Codex會平行執行彼此獨立的唯讀工具：查詢skills、記憶與對話記錄，列出外掛程式與代理程式，以及取得目前時間、剩餘上下文與get_goal（#52245）。在Codex回應期間傳送後續訊息，會立即引導其調整方向（#51812、#51835）。¹⁹²

修正與平台更新。 繼續已儲存的討論串時，會還原其權限與網路核准，但仍受明確覆寫設定及受管理政策約束（#53150、#53419、#53424）。網路代理會在DNS查詢前檢查權限、拒絕重複的Host標頭，並防止憑證別名繞過檢查hooks（#51650、#52661、#53506）。切換討論串後，/side會返回既有的旁支對話，而待回覆提示的答案也會送回提出問題的討論串（#52184、#53436）。在Windows上，Ctrl+V與Shift+Insert可貼上文字及圖片；在WSL上，重複貼上會重複使用剪貼簿讀取器，複製作業則會在逾時後結束，不再停滯（#53224、#52967、#53453）。即使子程序持續開啟輸出管線，本機命令仍能及時結束；遠端命令會保留較晚到達的輸出，供最後一次輪詢取得；codex exec也不再於執行無關命令後重複顯示檔案差異（#52652、#53331、#53622、#53444）。¹⁹²

已移除修補版zsh。 Codex改用標準shell執行器，不再隨附修補版zsh；codex-execve-wrapper與shell-escalation crate也一併移除。shell_zsh_fork與unified_exec_zsh_fork會被忽略，並顯示遷移通知；受管理需求若仍指定這些設定，則會顯示警告（#52160、#52213）。Linux與macOS套件已縮小，發行的二進位檔已移除符號資訊（#52178）。Linux沙箱crate的名稱與README現在如實說明沙箱既有的運作方式：使用bubblewrap隔離檔案系統與命名空間，以seccomp篩選系統呼叫，並保留Landlock實作作為舊版機制；實際強制執行方式並未改變（#52610）。隨附的OpenAI Docs指引涵蓋遷移至GPT-6系列的說明（#51768）。¹⁹²¹⁹³

建議行動：升級。若config.toml或requirements.toml指定了shell_zsh_fork或unified_exec_zsh_fork，請移除該設定；若曾手動啟用Daybreak，現在已不再需要該旗標；若原本使用Ctrl+X將/voice靜音，現在請改用F9。¹⁹²

v0.162.1（2026年10月9日）

在v0.162.0基礎上新增3筆提交，帶來2項修正。 已修正多行非同步問題導致TUI當機的問題，並保留換行與完整的超連結目標網址。部分v0.162.0使用者遇到的啟動失敗也已解決：先前的原因是執行中的背景伺服器功能設定與CLI的預設值不同，現在相容性檢查僅針對命令列明確覆寫的功能設定。預設值、設定鍵與模型均無變更。

建議行動：升級，尤其是當舊版背景伺服器執行時，v0.162.0曾無法啟動的情況。¹⁸⁸

v0.162.0（2026年10月8日）

instant_interrupt預設啟用。 此旗標在v0.159.0推出時需自行啟用，可讓新輸入中斷模型回應，或讓長時間執行的code-mode呼叫交出控制權。從本版起，所有使用者都預設啟用（PR #51812，於10月7日合併）；其狀態仍標記為開發中。在[features]下設定instant_interrupt = false即可恢復舊行為，讓輸入內容等待回應完成後再處理。

TUI新增功能：啟用worktrees功能時，可透過工具在受信任的本機專案中建立及列出受管理的Git worktrees，讓模型自行開啟worktree（#50148）；在代理程式Command Center中按p即可釘選，伺服器支援時，釘選的任務會保留在共用的「已釘選」群組中（#51500）；/copy可瀏覽對話記錄區塊，Ctrl+Insert可複製選取內容，tui.mouse_scroll_speed（有限正數，預設為1.0）則可調整滑鼠滾輪捲動速度（#50434、#50215、#50209）；核准標題、問題、MCP提示、警告與橫幅中的網址皆可點選，包括跨行連結。新的TUI討論串會遵循伺服器的模型與推理摘要預設值，同時保留啟動時明確指定的覆寫設定。codex doctor會回報已設定的TUI模式，而帳號更新後，/status也會再次顯示帳號電子郵件地址。

供應商與模型：自訂且相容於Responses的供應商，可在[model_providers.<name>.capabilities]下宣告external_web_access與remote_compaction（#50459）。ultrafast_mode功能預設啟用，因此模型目錄若列有Ultra Fast層級（Amazon Bedrock的Astra模型，#50472），便能獨立於Fast模式提供此選項；此版本標籤隨附的目錄並未列出這類層級。Code mode新增JavaScript輔助工具，可串流傳回Promise結果，並提供需自行啟用的排序工具搜尋（code_mode_tool_search）。apply_patch一律保留既有的CRLF換行字元，並移除apply_patch_preserve_line_endings旗標。可重試的Responses與WebSocket失敗會遵循伺服器的Retry-After建議。

沙箱與平台：已修正Linux沙箱在多個檔案遭拒絕存取時的啟動問題，拒絕使用可寫入的沙箱建置執行檔，且ripgrep設定不再能削弱glob拒絕規則；Windows 10恢復一般磁碟機代號的檔案存取，沙箱暫存權限與子程序一致，封存檔總和檢查碼驗證可搭配PowerShell 7模組路徑正常運作，Windows發行版也隨附已簽署的PowerShell安裝程式。

建議行動：升級；若您習慣預先輸入內容而不中斷模型，請設定instant_interrupt = false。¹⁸⁷¹⁸⁹

v0.161.0（2026年10月7日）

以0.161.0-alpha.13.1為基礎，再加上1筆發布提交，比v0.160.1多155筆提交。版本說明將GPT-6.1 Sol列為新的預設模型（#49318、#49339），但這些目錄變更已隨v0.159.1推出：此版本標籤隨附的models.json與v0.160.1的檔案逐位元組完全相同，因此使用0.159.1或更新版本的使用者不會有任何變化。

新增功能：/mcp login <name>可從執行中的終端機工作階段登入MCP伺服器（#49290）。語音裝置選擇：可為/voice對話選擇麥克風、喇叭與麥克風輸入聲道，偏好設定會儲存於本機（#49437、#49836）。透過API金鑰探索模型的功能預設啟用（api_key_model_discovery，已升級為穩定功能，#49807）：使用OpenAI API金鑰登入支援此功能的端點後，Codex會透過API重新整理模型目錄，不再僅依賴隨附清單；在[features]下設定api_key_model_discovery = false即可關閉，變更會在新的工作階段生效。Amazon Bedrock在相容模型上支援多代理程式V2與Ultra推理，Bedrock Mantle也支援AWS GovCloud區域（#49345、#49813）。 Daybreak（選擇性啟用）。新增的cli_daybreak旗標預設關閉，仍在開發中，可在CLI中加入Daybreak控制功能：/daybreak切換指令、狀態指示，以及自動Cyber存取方案路由。適用對象為透過OpenAI提供者以ChatGPT登入，且帳號與模型目錄均標示支援的使用者。使用--enable cli_daybreak，或在[features]下設定cli_daybreak = true即可啟用；僅儲存daybreak = true偏好設定不會產生作用。另外，無論是否啟用此旗標，codex exec --cyber-access-program <standard|daybreak_blue|daybreak_red>（以及TypeScript SDK的cyberAccessProgram）都能為單一回合要求使用Cyber存取方案，且不會變更已儲存的選擇（#49856至#49861、#49939、#51207）。內附目錄已有隱藏的gpt-daybreak-blue-latest與gpt-daybreak-red-latest項目。自v0.163.0起預設啟用，並標示為穩定功能。¹⁹³

修正項目：經核准的檔案系統權限提升，可授予更廣泛的寫入權限，同時保留讀取拒絕規則與網路限制；背景任務會沿用啟動該任務之回合的權限；明確指定的啟動權限在終端機重新連線後仍會保留；以提升權限執行的Windows終端機工作階段可搭配內嵌伺服器啟動；貼上偵測結束後，按Enter即可送出緩衝的輸入內容，Vim插入模式也適用；恢復對話串時會納入最新已提交的歷程，啟動時也會更早偵測可復原的SQLite損毀，並將受損資料庫保留為備份；Responses重試與WebSocket轉用HTTP的備援機制，均會遵循伺服器的重試指引。驗證文件現已說明，憑證可能儲存在金鑰圈中，不一定存放於auth.json。

建議操作：升級。本次沒有會讓您明顯察覺的預設行為變更；若使用API金鑰登入，請在/model中查看探索取得的目錄。¹⁸⁶¹⁸⁹

v0.160.1（2026年10月5日）

修正Windows遠端MCP伺服器問題。當macOS或Linux主機上的Codex在遠端Windows執行器啟動stdio MCP伺服器，且該伺服器的設定明確指定遠端環境變數時，Codex現在也會一併傳遞SYSTEMROOT、TEMP與TMP，讓Windows處理程序保有所需的啟動環境。未要求傳遞的變數仍會排除在外，包括機密資訊。此版本是在v0.160.0基礎上回移一項修正，未變更任何預設值、設定鍵或模型。

建議操作：若您從Unix主機在Windows執行器上執行遠端stdio MCP伺服器，請升級。¹⁸³

v0.160.0（2026年10月1日）

0.160系列的穩定版本，以0.160.0-alpha.6.1加上一項回移變更建置而成。預設值沒有變更。此標籤版本的內附模型目錄與v0.159.1及v0.159.2逐位元組完全相同，因此GPT-6.1 Sol仍為預設模型，2個新功能旗標也維持關閉。這項回移變更（#49763）讓在v0.159.1之前分支、已凍結的0.160候選版本與0.159維護系列同步：納入GPT-6.1 Sol的內附目錄與Amazon Bedrock目錄，以及v0.159.3的帳號安全提醒。若沒有這項變更，0.160發布時將不含GPT-6.1 Sol。

選擇性啟用的Guardian新增功能（兩者皆仍在開發中，預設關閉）：

• Guardian可讀取較早的使用者訊息。在[features]下設定guardian_conversation_history_tools = true。啟用Apps後，審查器會透過父工作階段本身的Apps連線，取得user_message.search_messages與user_message.read_messages，以便在核准會產生副作用的動作前，檢查先前的指示、限制與已撤銷的權限。每次呼叫都會重新檢查父工作階段目前的應用程式與工具政策。回應預設以估計4,000個token為上限（auto_review.conversation_history_max_output_tokens）；auto_review.experimental_conversation_history_prompt則可取代內建的檢索指示。
• 可掌握交接情況的根層級上下文（guardian_root_handoff_context）：Guardian審查工作代理的動作時，會選取每次交接給該工作代理或其上層代理之前的3則根層級訊息，再加上最新的3則根層級訊息，確保近期的取消指示仍然可見。

一律啟用：加密的代理訊息現在會依序出現在Guardian對話記錄中，不再被捨棄。

TUI變更：若資料夾沒有專案設定，也未儲存信任決定，新工作階段可使用workspace-write權限與細粒度核准機制啟動，但前提是本機執行環境、您的設定及受管理政策皆允許。恢復工作階段時會還原已儲存的權限，除非您另行覆寫；/cd也可要求確認資料夾信任，並提供「保留目前目錄」選項。代理指揮中心新增「顯示更多」列，每次載入10個較早的任務。在本機Linux X11終端機上（不含Wayland、SSH、tmux、WSL或VS Code），全螢幕對話記錄中選取的內容會存入主要選取區，按滑鼠中鍵則會貼入輸入區。全螢幕狀態列在空間足夠時會顯示Plan mode (shift+tab to cycle)。Pro方案級別現在於/status與分析資料中顯示為「Pro 100」、「Pro 200」與「Pro 500」。啟動提示會指向適用於您平台的桌面應用程式，不再宣傳方案或Fast模式；排入佇列但尚未送出的訊息，會在重新連線後繼續傳送，且不會重複。

提供者與連線：TUI會保留應用程式伺服器的提供者、推理摘要與詳細程度設定，在恢復與分支歷程中顯示正確的工作階段，並在連接伺服器時隱藏/status中的推理摘要設定。明確指定模型目錄（model_catalog_url）的提供者，現在只會使用該目錄：不會合併內附模型，中繼資料會精確對應模型ID，重新整理失敗時會捨棄快取項目而非沿用；若啟動時沒有可用模型，則會回報設定錯誤，除非已設定model。當內容篩選器中止回應時，重試會指示模型說明限制、提供允許的替代方案，並繼續處理其他工作。

修正項目：修正Windows沙箱的PowerShell備援機制、較長執行階段路徑的ACL修復，以及背景輔助程式彈出主控台視窗的問題；子代理會保留仍在啟動中的環境；SQLite不再於建立連線時停滯，並會回報初始化錯誤，而非逾時。記錄資料庫會在背景回收未使用的空間，外掛載入程序則會快取已解析的資訊清單，並重複使用HTTP連線。提供者文件現已說明，requires_openai_auth憑證使用cli_auth_credentials_store選定的後端，而env_key則指定存放API金鑰的環境變數名稱。

建議操作：升級。若自訂提供者設定了model_catalog_url，請確認其目錄列出您會選用的每個模型。¹⁸²

v0.159.3（2026年9月30日）

選擇性的帳號安全提醒。透過OpenAI提供者以ChatGPT登入的本機TUI工作階段，可顯示可關閉的橫幅，提醒您完成帳號安全設定，並提供開啟chatgpt.com的按鈕。由伺服器決定向哪些使用者顯示；CLI會在背景擷取通知，不會阻塞回合，狀態未知時不顯示任何內容，也會略過遠端工作區與FedRAMP帳號，並在不同對話串與重新連線後記住關閉狀態。用量橫幅會優先顯示。這是此版本唯一的變更，v0.160.0也包含相同的程式碼。

建議操作：無須操作。此提醒為選擇性功能。¹⁸⁴

v0.159.2（2026年9月29日）

修正Windows主控台視窗閃現問題。在Windows上，Codex不再於每次啟動背景處理程序時開啟主控台視窗。涵蓋範圍包括shell工具命令、hooks、Git與npm呼叫、未使用終端機執行的Amazon Bedrock憑證更新、doctor檢查、沙箱設定更新，以及舊版Windows沙箱中的命令。需要使用您終端機的命令，仍會繼承其主控台。此版本將main中的2項修正合併為一項回移變更，約在v0.159.1發布3個半小時後推出。它未變更任何預設值、設定鍵或模型，新的啟動輔助程式在macOS與Linux上的行為也與先前相同。

建議操作：Windows使用者若在Codex運作時看到主控台視窗閃現，請升級，尤其是已安裝背景伺服器的情況。¹⁸⁰

v0.159.1（2026年9月29日）

GPT-6.1 Sol成為預設模型。當config.toml未設定模型時，CLI現在會以GPT-6.1 Sol（gpt-6.1-sol）啟動，取代GPT-6-Astra；GPT-6.1 Sol也取代GPT-6 Sol，成為Amazon Bedrock Mantle與Runtime目錄中的預設模型。/model選擇器將其列在首位，說明為「適合程式開發與日常工作的最新主力模型」，後面依序為GPT-6-Astra、GPT-6 Sol（現標示為「上一代主力模型」）、GPT-6 Luna及較舊的模型。已儲存的選擇不會遷移：設定中若指定gpt-6-sol或gpt-6-astra，仍會沿用該模型；較舊GPT-5選項的遷移提示，也仍指向GPT-6 Sol或GPT-6 Luna。 OpenAI的文件也在同一天加入此模型，目前建議將其用於複雜的程式設計與代理工作流程：「處理複雜工作時，能以低於Astra的成本，提供接近Astra的效能。」每100萬個輸入token需50點額度（快取輸入為2.5點，輸出為250點），Plus的訊息額度範圍為15–160則。模型目錄中有2項細節與GPT-6 Sol不同：它沒有預設服務層級，因此工作階段會以Standard速度啟動，而非Fast；預設推理強度則為low，而非medium。本次推出涵蓋Plus、Pro、Business、Enterprise和Edu；Enterprise與Edu預設停用，須由管理員啟用，Free與Go則不在首波支援範圍內。

建議操作：升級後，透過/status確認模型。如果您的帳號尚未取得GPT-6.1 Sol，可在config.toml中使用model，或透過-m指定帳號已可使用的模型。¹⁷⁸

v0.159.0（2026年9月29日）

此版本以0.159.0-alpha.13為基礎發布，距離v0.158.0約27小時。版本說明中的多個項目已透過向後移植，提前在v0.158.0推出：Windows主控台視窗與啟動器修正、保留Markdown格式的複製功能、歡迎畫面與回合提示，以及登入修正。說明中列為已移除的tui.prompt_suggestions設定，從未出現在穩定版本中。

此版本新增功能：

• instant_interrupt（須自行啟用，開發中）：新輸入會中斷模型回應，或讓長時間執行的程式碼模式呼叫交出控制權。在[features]下設定instant_interrupt = true即可試用。自v0.162.0起預設啟用。
• 警告檢視器關閉時，會清除您已看過的警告；按k可保留某則警告，稍後再處理。
• 決定是否實作計畫時，也能捲動對話紀錄。
• Mermaid算繪支援更多流程圖連線、標籤與節點群組。
• 切換任務時，空白工作階段會保留草稿；討論串也能在第一個回合開始前封存。
• /status以無框線方式顯示，較長的值會自動換行。
• App-server用戶端可從指定項目開始，分頁讀取討論串歷程。

沙箱變更：已核准的命令仍須遵守明確設定的檔案系統存取禁止規則；可寫入根目錄下的.aws目錄預設受到保護（明確規則仍可覆寫）；啟用網路的macOS沙箱允許TLS信任評估；需要代理伺服器的執行環境現在也會取得代理伺服器。隨附的plugin-creator skill已移除。

建議操作：如果沙箱中的任務需要寫入.aws下的內容，除非新增明確規則，否則寫入將遭到封鎖。¹⁷⁷

v0.158.0（2026年9月28日）

0.158系列的穩定版本，以0.158.0-alpha.15.4為基礎發布：包含alpha.15及16項向後移植修正，其中包括v0.157.1的4項Windows修正。相較於v0.157.0，此版本新增207次提交。

預設行為變更：

• 終端機輸入核准預設啟用。當Codex向正在執行且具有提升權限的命令傳送輸入時（包括額外授予權限、略過沙箱限制，或命令啟動後政策有所變更），必須先核准該輸入。僅在執行階段授予的權限，例如外掛程式收集指標所用的權限，不再觸發審查。若要停用，請在[features]下設定write_stdin_approval = false。
• 全螢幕對話紀錄中的選取即複製：使用滑鼠選取文字後，放開按鈕便會複製。預設值auto會略過自行轉送複製快捷鍵的直接連線終端機（Ghostty 1.2+、macOS上的Kitty、Windows Terminal，以及Windows上的VS Code）。複製時會保留Markdown格式。可在[tui]下設定copy_on_select = "never"（或"always"）。
• Windows、WSL與Linux上的全螢幕TUI支援按右鍵貼上。可在[tui]下設定right_click_paste = "off"，或設為"on"以一併支援macOS。
• Guardian討論串上下文一律啟用。v0.157.0的停用開關已移除：[features.guardianv2]下的thread_context會被忽略，設定檔中的同名設定也不例外，Codex會顯示通知，請您移除此設定。

模型與方案：GPT-5.4已從隨附模型目錄與Bedrock模型目錄中移除；先前儲存的GPT-5.4選擇仍會觸發移轉至GPT-6 Sol的提示。Codex可辨識Pro Max方案，並將Pro各層級標示為「Pro」、「Pro (More)」與「Pro (Max)」。推理強度快捷操作現在可選到Max。

其他新增功能：支援需要預先註冊OAuth用戶端密鑰的MCP伺服器（codex mcp add --oauth-client-secret）、exec-server WebSocket連線的Bearer權杖、生成圖片的透明背景，以及/ps中的多行命令預覽。修正範圍包括Windows沙箱失敗（一般Windows 10路徑、遭拒的已儲存認證、大型權限政策）、具有巢狀可寫入根目錄的Linux沙箱啟動、跨可寫入根目錄的Git中繼資料保護，以及修補程式核准中的macOS路徑別名。若您在Guardian審查途中傳送訊息，審查現在會重試，而不會直接中止。

建議操作：如果自動化流程會向提升權限的命令傳送按鍵輸入，請預期會出現核准提示，或停用此功能；並從設定中移除thread_context。¹⁷⁶

v0.157.1（2026年9月26日）

此Windows修補版本包含從主分支向後移植的4項修正。Codex啟動程式碼模式主機或本機stdio MCP伺服器時，不再開啟主控台視窗。當Windows讓處理程序留在外層作業物件中時，背景伺服器現在也能啟動。與啟動器分離的背景伺服器也不再讓啟動器的輸出管線維持開啟；先前這可能導致啟動器結束後，呼叫它的命令仍持續等待。GitHub版本說明與變更紀錄項目僅表示「無法判定」重點內容；上述清單是根據此版本的提交紀錄整理而成。

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

v0.157.0（2026年9月25日）

此版本再變更3項預設行為。

• 全螢幕對話紀錄預設啟用。v0.156.0透過/tui提供的全螢幕介面，現在會在工作階段開啟時直接使用，即使設定中沒有[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模型目錄現在也提供這2個模型，並由GPT-6 Sol取代GPT-5.6 Sol，成為Bedrock的預設模型。GPT-5.6 Sol已移除ultrafast服務層級，僅保留Fast。隨附模型目錄不再將GPT-6-Astra標記為支援實驗性上下文管理（請參閱上下文管理）。

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

v0.156.1（2026年9月23日）

此修補版本只有1項變更：將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的預設模型。

文件未提及的1項費用細節：隨附模型目錄將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工作階段可連接至現有的本機常駐程式，也能從代理總覽建立。
• Guardian預設啟用父執行緒壓縮內容重用： Guardian重新啟動審查工作階段時，可重用父執行緒的加密壓縮內容。

各項功能的停用方式，請參閱slash commands表格中的/voice與/worktree項目，以及Guardian章節。

其他新增功能包括：可透過/tui選用的全螢幕TUI，支援對話記錄搜尋、滑鼠選取與複製、按右鍵複製、可點選連結及警告檢視器；/theme選單內附的6款佈景主題；/usage分析儀表板；可在終端機中呈現的Mermaid圖表與TeX數學式，兩者各有獨立開關；/daemon選單與--no-daemon旗標；以及新TUI執行緒預設停用推理摘要。安全性修正補上了Windows傳入流量、特權通訊端及唯讀檔案控制代碼的沙箱漏洞，codex doctor也不再於錯誤訊息中輸出設定值。錯誤修正則讓失敗或中斷的回合保留已串流輸出的回答、修復tmux與SSH中的剪貼簿轉送、在繼續工作階段時還原Plan模式，並讓登入流程可透過系統代理伺服器恢復運作。¹⁶⁹

v0.155.1（2026年9月18日）

僅包含1項修正的緊急修補版本。在0.155.0中，若設定未指定model_reasoning_summary，新的本機TUI執行緒會要求detailed摘要，導致不支援推理摘要的供應商直接拒絕請求。0.155.1將備援值還原為none，因此未設定此鍵時就不會要求摘要。明確指定的auto、concise與detailed設定過去一直有效，現在也維持不變。同一項單行變更也已合併至main，並隨0.156.0發布。

建議操作：若您在0.155.0中使用非OpenAI或自行託管的供應商時，新的TUI工作階段無法運作，請升級。若需要摘要，請明確設定此鍵（請參閱設定參考）。¹⁵⁸

v0.155.0（2026年9月17日）

語音功能以需自行啟用的實驗性功能形式，加入穩定版TUI：在支援的組建中，透過/experimental啟用後，即可使用/voice開啟即時對話，並提供串流逐字稿與麥克風控制項。此功能支援可設定的靜音快捷鍵，macOS套件也包含已簽署的語音資源。5天後發布的v0.156.0將其改為預設啟用。此版本中的受管理worktrees仍預設停用。

0.155.0也包含：

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

安全性修正封堵了透過WSL互通功能逃逸的漏洞，以及殼層快照的憑證外洩問題。Memory v2此次僅加入儲存與整合的基礎架構，尚非可用功能。¹⁵⁶

v0.154.0（2026年9月9日）

此版本約以0.154.0-alpha.6的進度為基準發布，因此所有首度出現在alpha.7的功能（TUI即時語音、MCP使用者驗證、Memory v2、常駐程式自動更新設定、推理強度固定設定）都延至0.155才推出。

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

新增功能：

• 透過--worktree或/worktree使用的實驗性受管理worktrees，支援codex exec，並提供TUI worktree瀏覽器。
• 非同步使用者訊息： Codex持續工作時，您可直接回答行內問題，且不會遺失草稿。
• Windows服務支援： 沙箱佈建、Windows上的app-server常駐程式，以及受管理的常駐程式更新。
• 遠端權限設定檔，可從應用程式伺服器探索，並在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，不要依賴預設值。^145146147148

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

v0.153.1讓Guardian的電腦操作評分遵循模型要求：只有在目前模型的中繼資料設定了node_repl_auto_review_required時，才會執行僅針對電腦操作的評分與快速核准決策。若切換至略過評分的模型，先前或進行中的評分都會失效，因此即使切回原模型，也無法恢復過時的核准。版本說明內文僅列出一項向後移植的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是可設定的按鍵對應動作。
• 遠端外掛程式市集： 外掛程式CLI可列出、安裝及移除遠端外掛程式，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取代了頂層設定鍵，舊鍵仍可作為備援設定使用。

修正：TUI工作階段在app-server連線中斷後可重新連線，並完整保留草稿；Guardian審查記錄在壓縮、重新啟動與建立分支後仍會保留；已記住的MCP核准則限定於所選帳號。¹⁴⁰

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

update_plan改為需主動啟用：tools.update_plan.enabled預設為false。停用時，內建的update_plan指引會從模型、協作模式、多代理、壓縮、預熱及目標延續提示中移除（請參閱計畫模式與協作）。其他新增功能包括：Vim支援以/和?搜尋，搭配n/N跳轉，並可與運算子組合使用，新草稿則從插入模式開始；提供可採取行動的速率限制橫幅；顯示憑證更新進度，包括Amazon Bedrock重新驗證；支援套件風格的MCP伺服器名稱（允許使用:、@、/及.）；MCP openai/elicitation表單請求；各工具可個別設定的MCP output_token_limit；雲端任務憑證僅限用於受信任的來源；可設定thread/shellCommand逾時時間；以及透過模型中繼資料預設啟用token預算管理。v0.152.1讓Guardian核准審查能從模型中繼資料取得Node REPL政策。¹³⁸¹³⁹

v0.151.0（2026年8月29日）

• /recap可依需求摘要對話，Codex也會自動摘要符合條件、閒置且未處於焦點的對話。
• 程式碼模式主機移除WebSocket傳輸方式（僅保留stdio與gRPC）。
• 儲存系統支援時，持久化執行緒預設採用分頁歷史紀錄。
• 新增persistent推理強度，並搭配時鐘工具與內建的主動執行指引。
• Guardian v2預設對電腦操作進行含影像的審查。
• Vim新增f/F/t/T尋找與移至目標前一字元的移動指令，以及gg/G。
• 向已提升權限的終端機輸入內容時，可要求重新核准（write_stdin_approval，預設關閉）。
• 可設定選用MCP伺服器的寬限期（mcp_optional_startup_grace_ms，預設1,000毫秒），擴充功能也可檢查或取代MCP工具結果。

修正了/cd可能削弱沙箱限制的問題，也避免權限變更後，過時的Guardian分類仍用來授權動作。版本說明內文僅列出最後幾個PR；完整變更集請參閱版本比較。¹³⁴¹³⁵

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會將保留的影像計入遠端壓縮的token預算。¹³²¹³³

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

untrusted核准政策已停用；請將指定此政策的設定改為on-request。新增功能包括：互動式codex agents儀表板、/cd、/pwd與/cwd、可傳送訊息至現有本機或遠端工作階段的codex queue、更多Vim變更操作的移動指令、檢查範圍更廣的codex doctor（端點防護、網路與代理伺服器故障、桌面應用程式狀態、更新連線能力），以及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的Codex點數費率也從每100萬個輸入、快取與輸出token分別收取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日）：已設定的代理伺服器涵蓋所有傳輸方式；Agent Plugins資訊清單，以及Amazon Bedrock與Claude Code市集；工作階段命名與執行緒釘選；由執行器提供的skills；針對具備網路安全能力的模型，強化自動審查的預設設定。¹¹⁴¹¹⁵
• v0.145.0（7月21日）：/import除了Claude Code之外，也支援從Cursor匯入；語音功能以串流即時V3對話形式回歸；需主動啟用的多代理v2體驗已趨穩定；實驗性分頁執行緒歷史紀錄與Amazon Bedrock登入；內建GPT-5.4選項遷移至GPT-5.6 Terra與Luna。v0.144.6將GPT-5.6的上下文視窗設為272,000個token。¹¹¹¹¹²
• v0.140.0（6月15日）：/usage、codex delete與/delete、從Claude Code進行/import、統一的@提及選單、Amazon Bedrock API金鑰驗證，以及CLI與MCP OAuth憑證的本機加密儲存；舊版/realtime語音控制已移除。¹⁰²
• v0.139.0（6月9日）：程式碼模式可直接呼叫網頁搜尋，工具結構描述保留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、正式推出的目標模式，以及需主動啟用的鎖定式Computer Use。^{96979899100101196}

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

穩定性說明：穩定且已有文件說明的功能範圍包括：核心CLI與TUI、沙箱隔離與核准政策、config.toml、AGENTS.md、skills、hooks、外掛程式、多代理工具、目標、權限設定檔、/voice與受管理的worktrees（自v0.156.0起預設啟用）、全螢幕對話記錄與自動在背景啟動伺服器（自v0.157.0起預設啟用）、終端機輸入核准、選取即複製與按右鍵貼上（自v0.158.0起預設啟用）、即時中斷（自v0.162.0起預設啟用，仍標示為開發中）、Daybreak與程式碼模式中斷（cli_daybreak、code_mode_interrupt；自v0.163.0起穩定且啟用），以及Bedrock設定精靈、增量工具更新與MCP OAuth更新協調機制（自v0.164.0起穩定且啟用）。自v0.164.0起，受管理的worktrees與即時對話已成為永久功能：其旗標標示為已移除，功能則保持啟用。Browser、Computer Use與Appshots是已有文件說明、供使用者操作的功能，是否可用取決於平台與方案。實驗性或開發中的功能包括：Codex Cloud、程式碼模式與程式碼模式工具搜尋、Memory v2、本機代理留言板、Guardian歷史記錄與交接情境旗標（v0.160.0），以及本指南中標示為[EXPERIMENTAL]或列於/experimental下的所有功能；這些功能可能隨版本變更。根據設定參考文件，實驗性情境管理「目前尚未提供」。已移除的項目包括：--full-auto（v0.147.0）、untrusted核准政策（v0.149.0）、codex mcp-server（v0.154.0）、Guardian的thread_context停用選項（v0.158.0）、shell_zsh_fork與unified_exec_zsh_fork旗標及修補版zsh本身（v0.163.0），以及js_repl。

Alpha發布管道：alpha建置版本每天發布數次，alpha版本系列的發布說明僅有簡略內容，也經常出現以較舊版本為基礎、在常規發布流程之外產生的建置版本。npm的alpha標籤至少有2次指向這類版本，導致透過@alpha安裝的建置版本比latest還舊。0.158系列從0.158.0-alpha.2（9月23日）發展至alpha.15（9月25日）；其穩定版v0.158.0（9月28日）以常規流程之外的建置版本0.158.0-alpha.15.4為基礎發布，也就是alpha.15加上16項回溯移植的變更，並維持為npm的latest，直到27小時後v0.159.0發布。0.159系列從alpha.1（9月25日）發展至alpha.13（9月28日），並以alpha.13為基礎發布v0.159.0。0.160系列推進至0.160.0-alpha.6（9月29日）後便凍結於此；0.161.0-alpha.1與alpha.6相同，僅變更版本號碼。9月30日，0.160.0-alpha.6.1在alpha.6中補入其缺少的那項v0.159.2 Windows主控台修正。同日，0.159系列又發布了一個修補版本v0.159.3。隨後，0.160系列以alpha.6.1加上1項回溯移植的變更為基礎，發布穩定版v0.160.0（10月1日），接著發布v0.160.1（10月5日）。0.161系列已產生多個alpha版本，以及常規流程之外的回溯移植版本，最新為0.161.0-alpha.13.1（10月6日），但尚無穩定版；由於尚未發布更高版本的穩定版，因此不能稱為跳過此版本。alpha目前指向0.162.0-alpha.16。若您持續使用alpha版本，請先檢查npm view @openai/codex dist-tags，並指定確切版本安裝，避免使用@alpha。^176179181185近期各alpha系列如何演進為穩定版的歷程與日期，詳見¹⁷³。0.161系列於10月7日以0.161.0-alpha.13.1為基礎發布v0.161.0（其上僅新增1筆發布提交）；v0.162.0接著於10月8日以0.162.0-alpha.18.1為基礎發布，而0.162.0-alpha.20比該穩定版的基礎版本多出52筆提交；v0.162.1於10月9日新增3筆提交；alpha在10月10日為0.163.0-alpha.5，10月13日依序推進至alpha.8、alpha.9與alpha.10，並於10月14日到達0.163.0-alpha.11。0.163系列於10月15日發布穩定版：v0.163.0以常規流程之外的0.163.0-alpha.10.2為基礎（其上新增1筆發布提交），而alpha.11比該基礎版本多出23筆提交。0.164系列於10月16日以alpha.1與alpha.2展開，至10月17日推進至0.164.0-alpha.3，10月22日推進至alpha.12；期間也另外發布了常規流程之外的建置版本0.163.0-alpha.11.1與11.2（10月21日至22日），以及0.164.0-alpha.11.1（10月23日）。0.164系列於10月23日發布穩定版v0.164.0，以alpha.11加上1筆發布提交為基礎（alpha.12比該基礎版本多出9筆提交）；同日，alpha移至0.165.0-alpha.1。^{189190191193195}

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 / bubblewrap / 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月29日，目前最新一代為 GPT-6：gpt-6.1-sol 適用於複雜的程式開發與代理式工作（自 v0.159.1 起，未設定模型時即為隨附的 CLI 預設模型）、gpt-6-astra 適用於難度最高的端對端工作、gpt-6-luna 適用於目標明確的大量任務，而 gpt-6-sol 則是上一代模型。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 退役。^{83117146148149171178} 此層會讀取檔案、寫入修補程式、執行 shell 指令，並針對您的程式碼庫進行推理。內容空間用盡時，Codex 會壓縮對話以騰出空間。此層會耗用 token。

安全層：Codex 執行的每個指令都會經過作業系統層級的沙箱。在 macOS 上，Apple 的 Seatbelt 框架會強制執行核心層級的限制。在 Linux 上，Bubblewrap 會隔離檔案系統與命名空間，seccomp 則會篩選系統呼叫；較舊的 Landlock 實作仍保留為舊版機制。沙箱是在作業系統核心層級運作，而非在容器內部。接著，核准政策會決定何時要求使用者確認。

擴充層：MCP 可連接外部服務（GitHub、Figma、Sentry）。skills 封裝可重複使用的工作流程，Codex 會依需求載入。Apps 可連接至 ChatGPT 連接器。網頁搜尋則能從網際網路加入即時資訊。

介面層：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 與協作
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？

Codex 自 v0.128.0 起提供自我更新指令；其餘操作則透過當初安裝時使用的 套件管理工具完成。⁸⁶自 v0.146.0 起，發行檔案、通道中繼資料及安裝程式別名均由 OpenAI 託管的發行基礎設施提供，並以 GitHub 作為備援。¹¹⁴若您的網路允許清單已納入 GitHub，供 Codex 安裝與更新使用，請一併加入 OpenAI 的發行主機。備援機制會在允許清單遺漏主機時自動接手，因此問題可能不易察覺，而不會直接報錯。

# Check what you are running
codex --version                          # -> codex-cli 0.164.0
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 會在 環境項目下明確指出此問題）。

解除安裝套件不會移除您的狀態資料。驗證資訊、設定與工作階段歷程 儲存在 ~/.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（透過 bubblewrap + 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

有 2 種驗證方式：

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 模型的對話壓縮與多代理相容性問題。¹³²v0.151.0 在符合條件的 TUI 登入流程中，新增由功能開關控制的 Amazon Bedrock 選項：初始設定流程會偵測既有的 AWS 設定檔與環境憑證，提供設定檔、存取金鑰、環境變數及 Bedrock API 金鑰的手動設定方式，要求填寫 AWS 區域，在輸入時遮蔽機密資訊，並於供應商變更時重新啟動內嵌伺服器。¹³⁵v0.152.0 開始顯示憑證更新進度：當模型供應商更新已過期的憑證時，TUI 與 codex exec 會顯示進度，也涵蓋 Amazon Bedrock 工作階段的重新驗證。此功能由穩定版的 modelProvider/authRecoveryStarted 與 modelProvider/authRecoveryCompleted app-server 通知支援，通知包含對話串、回合、供應商及顯示給使用者的訊息。¹³⁸

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.164.0

快速入門：您的第一個工作階段

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 commands：

> /plan Refactor the database layer to use connection pooling

Codex 會擬定計畫，但不會執行。檢閱計畫後，核准即可開始執行。

7. 檢查工作成果：

> /diff

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

接下來： - 在 AGENTS.md 中設定專案指示（請參閱 AGENTS.md 如何運作？） - 依工作流程設定專用設定檔（請參閱設定檔） - 嘗試使用 codex exec 進行非互動式自動化（請參閱非互動模式）

核心互動介面

Codex提供5種不同的介面，皆由相同的智慧能力支援。每種介面都針對不同的工作流程最佳化。

1. 互動式CLI（終端機介面）

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

終端機介面是一個全螢幕應用程式，包含：

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

主要TUI快捷鍵：

狀態列變更（v0.121.0）：狀態列中原有的上下文視窗計量表已替換為上下文使用百分比指標，顯示上下文視窗已使用的比例。若您的指令碼或hooks會解析狀態列，請確認是否需配合此格式變更調整。⁸²有新版本可用時，Codex也會顯示CLI更新公告。

TUI中可用的slash commands：

工作流程選擇器重新設計（v0.129.0）：重新設計的選擇器讓繼續對話及建立分支更容易操作。新的原始回捲模式則讓您在需要原樣複製命令或模型輸出時，捲動瀏覽未經呈現處理的對話記錄。適合梳理冗長的偵錯工作階段，或將輸出透過管線傳送至其他工具。⁸⁹

統一的@提及選單（v0.140.0）：現在於輸入區輸入@，預設會開啟涵蓋檔案、外掛程式及skills的單一提及選單，取代原先只能附加檔案的流程——只需按一次鍵，即可引用任何專案資源。¹⁰²

2. Codex Desktop App（macOS + Windows）

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

桌面應用程式新增了CLI未提供的能力：

• 多工處理：在不同專案中同時執行多個平行代理
• Git worktree隔離：每個討論串都在儲存庫的獨立副本上工作
• 行內差異審查：無須離開應用程式，即可暫存、還原及提交變更
• 整合式終端機：每個討論串都有可執行命令的終端機
• 對話分支：建立對話分支以探索其他方案
• 浮動彈出視窗：將對話分離為可自由移動的視窗
• 自動化：排程執行週期性任務（議題分類、CI監控、警示回應）
• Appshots：將最前方的Mac應用程式視窗以螢幕截圖及可取得的文字附加至討論串
• 應用程式內瀏覽器註解：預覽本機或公開頁面，針對元素或區域留下註解，讓Codex處理精確的視覺回饋
• Computer Use：讓Codex操作獲准的Mac應用程式，執行限定範圍的GUI工作；符合資格的遠端Mac Computer Use回合可自行啟用鎖定狀態下的使用功能

由GPT-Live驅動的ChatGPT Voice（桌面版26.715，2026年7月23日）：現在可透過語音操作桌面應用程式，無須打字，即可口述工作內容，並在Chat、Work及Codex之間協調任務。在macOS上，開啟螢幕上下文會將最前方視窗的appshot分享至對話，因此可直接詢問眼前畫面的內容，無須先加以描述。此功能適用於Plus、Pro、Business、Edu及Enterprise，可在桌面應用程式中使用，也可透過iOS上的Remote使用。這是桌面介面的語音功能。CLI另有獨立的語音功能：TUI中的/voice即時對話（自v0.156.0起預設啟用），以及空白鍵語音輸入（於v0.105.0以實驗性功能加入）。¹¹³¹⁶⁹

共用討論串快照（2026年8月20日）：所有Codex方案皆可透過macOS桌面應用程式，分享本機Codex討論串的唯讀快照。原始討論串變更時，快照不會隨之更新；個人帳戶的連結可供任何持有連結的人開啟，工作區帳戶的連結則僅限原工作區成員存取。Codex會在分享前遮蔽符合已知機密模式的內容，但OpenAI仍要求使用者檢查分享內容，因為其中可能留有敏感資訊。可在ChatGPT資料控制項的「共用連結」中檢視或撤銷連結。¹²⁸

何時使用應用程式或CLI：需要協調多條工作流程或以視覺方式審查差異時，請使用桌面應用程式。需要終端機組合能力、指令碼操作或CI/CD整合時，請使用CLI。

3. IDE擴充功能（VS Code、Cursor、Windsurf）

Codex IDE擴充功能直接整合至編輯器：

• 預設採用代理模式：讀取檔案、進行編輯及執行命令
• 行內編輯：在目前使用的檔案中提供考量上下文的建議
• 共用工作階段：工作階段會在CLI與IDE擴充功能之間同步
• 相同的驗證方式：使用ChatGPT帳戶或API金鑰登入

可從VS Code Marketplace或Cursor／Windsurf擴充功能商店安裝。³

4. Codex Cloud [EXPERIMENTAL]

雲端任務會在OpenAI管理的環境中以非同步方式執行：

• 提交後即可放手：將任務排入佇列，獨立於本機電腦執行
• 平行執行：同時執行多個雲端任務
• 建立PR：Codex根據已完成的工作建立提取請求
• 套用至本機：使用codex apply <TASK_ID>將雲端結果拉取至本機儲存庫

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

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

5. 瀏覽器擴充功能（Chrome、Edge、Brave、Opera、Vivaldi）

Codex提供Google Chrome、Microsoft Edge、Brave、Opera及Vivaldi瀏覽器擴充功能，在CLI、桌面應用程式、IDE擴充功能及雲端之外，新增第5種介面。此擴充功能於2026年5月率先在Chrome推出；2026年8月25日的更新記錄新增了另外4款瀏覽器，可從ChatGPT桌面應用程式的設定 > Computer Use進行設定。5款瀏覽器皆支援分頁提及及瀏覽器控制；Opera不支援側邊對話，因此需從桌面應用程式啟動其任務。此擴充功能的設計旨在配合日常瀏覽，而非接管瀏覽過程：Codex會在背景跨分頁平行工作，而您仍可掌控它能存取哪些網站。⁹⁰¹²⁷

• 平行操作分頁：Codex同時操作多個分頁，不會鎖住前景分頁。
• 個別網站控制：由您設定允許Codex互動的網站清單；預設不允許存取任何網站。
• 以瀏覽器為工作台：此擴充功能最適合以頁面為資訊依據的應用程式與網站工作，例如管理主控台、內部儀表板、內容管理介面及工單系統；它並非用於取代處理本機儲存庫的CLI。
• 相同的智慧核心：瀏覽器擴充功能使用與其他介面相同的GPT-5.x-Codex智慧能力，因此在CLI中適用的AGENTS.md或skills設定，也能將相同慣例帶入瀏覽器操作工作。

請從瀏覽器擴充功能文件安裝，該頁面原名為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 或多帳號設定相當實用。

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

完整設定參考

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

# ─── Model Selection ───────────────────────────────────
model = "gpt-6.1-sol"                  # Docs' example; unset = bundled default (gpt-6.1-sol since v0.159.1)
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"]
mouse_scroll_speed = 1.0                # Mouse-wheel scroll multiplier, a finite positive number (v0.162.0)

# ─── 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)
instant_interrupt = true                # New input preempts the model's response; on by default since v0.162.0 (under development)
api_key_model_discovery = true          # Fetch the model catalog when signed in with an OpenAI API key; on by default since v0.161.0 (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)
guardian_conversation_history_tools = false  # Guardian reads earlier user messages (under development, v0.160.0)

# 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.

# ─── Guardian Auto-Review (v0.160.0 history keys) ─────
[auto_review]
conversation_history_max_output_tokens = 4000   # Per history-tool response, estimated tokens (default 4,000)
experimental_conversation_history_prompt = ""   # Blank = built-in retrieval instructions

# ─── 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

即使未設定 features.network_proxy，由管理員在 requirements.toml 中管理的 experimental_network 要求仍可啟動 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.1-sol"
# GPT-6.1 Sol starts at Standard speed; /fast toggles Fast (2.5x credits)
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"

env_key 指定儲存供應商 API 金鑰的環境變數；金鑰本身絕不會寫入 config.toml。設定 requires_openai_auth = true 的供應商會在首次執行時顯示登入畫面，並將憑證儲存在 cli_auth_credentials_store 所選的後端（file、keyring 或 auto），不一定會存入 auth.json。自 v0.160.0 起，設定 model_catalog_url 的供應商只會取得該目錄中的模型，不會合併任何內建模型；若目錄重新整理失敗，系統會捨棄快取項目，而非沿用過期資料。¹⁸² 自 v0.162.0 起，自訂的 Responses 相容供應商也能在 [model_providers.<name>.capabilities] 下宣告支援的功能：external_web_access = false 會禁止該供應商的託管網頁搜尋存取即時網路；remote_compaction = "v2" 則會選擇採用 Responses compaction_trigger 通訊協定。否則，只有 OpenAI 與 Azure Responses 供應商能使用該通訊協定（"unsupported" 會讓壓縮作業保留在本機執行）。¹⁸⁷

警告：OpenAI 已宣布於 2026年2月移除適用於 OpenAI 託管模型的 chat/completions 線路 API（wire_api = "chat"），因此此介面已遭棄用。³⁴ 本機供應商（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任務建議的選擇：複雜程式設計、電腦操作、知識工作及研究工作流程。ChatGPT Plus／Pro／Business／Enterprise／Edu／Go使用者可自4月23日起在Codex CLI／網頁版／桌面版使用；OpenAI API則自4月24日起提供。上下文視窗：Codex中為400K，API中為1M——Codex將視窗上限設為400K，以平衡各訂閱層級的吞吐量與成本；API則開放完整的1M。定價（API）：每MTok輸入$5／輸出$30（GPT-5.4費率的2倍；OpenAI表示，經token效率改善後，實際增幅約為20%）。基準測試：Terminal-Bench 2.0為82.7%（目前所有公開可用模型中的SOTA）、GDPval為84.9%（涵蓋44種職業）、OSWorld-Verified為78.7%、Tau2-bench Telecom為98.0%（未進行提示詞調校）。OpenAI在推出前於內部使用GPT-5.5與Codex重寫服務基礎架構，使token產生速度提升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日）：GPT-5.1模型已無法在ChatGPT中使用。既有對話會自動改由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個token。¹¹¹ 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「現已開放所有Pro、Enterprise及Business Premium使用者在ChatGPT Work與Codex中使用」，且「已在API上線」，Plus與Business預計在數日內開放；Codex負責人Tibo Sottiaux當晚接著表示：「Astra現在也已向所有Plus與Business使用者推出。」實際權限仍不一致——9月5日的社群回報顯示，部分Plus帳戶在Codex中仍只看得到GPT-5.6模型——而且下方引用的模型文件可用性說明並未改變，因此仍應視為有效的第一方聲明。¹⁴⁹第一方文件已上線：API模型頁面將gpt-6-astra列為旗艦模型，稱其為「我們能力最強的模型，專為最艱鉅的端對端工作打造」——標準短上下文費率為每MTok輸入$10、輸出$50；上下文視窗為1.05M個token，最大輸入922,000個token，最大輸出128K，知識截止日期為2026年4月30日——並記載長上下文費率層級：輸入提示超過272K個token時，整個請求的輸入價格按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）。^146148153在CLI中，自v0.153.1起可透過API設定Astra（-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的速度倍數。^145146147148 部分資訊已於2026年9月23日被取代：模型文件不再將Astra描述為建議的Codex模型。「建議的模型」章節現在以GPT-6 Sol與Luna為首，將Astra保留給「最艱鉅的端對端工作」，標示Astra不適用於Codex cloud，並將Astra的起始推理強度設為Light（low），與內建目錄一致。未設定模型時，Astra仍為內建CLI預設模型。¹⁷¹ 已於2026年9月29日被取代：v0.159.1將GPT-6.1 Sol設為內建預設模型，並把Astra移至選擇器第2位；模型文件目前建議以GPT-6.1 Sol處理複雜的程式設計工作，並保留Astra用於最艱鉅的端對端工作；文件中的設定範例現在使用gpt-6.1-sol。¹⁷⁸

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日重新存取時，文件章節原文保持不變。此功能仍屬實驗性且預設關閉；其行為與資格可能會有所變動。^140146152 v0.157.0：內建模型目錄不再將GPT-6-Astra或任何其他內建模型標示為支援實驗性上下文（#47397），而CLI只會為具備該標記的模型啟用實驗功能。因此，使用內建目錄時，選擇加入並無效果；提供給已登入帳戶的目錄是否有所不同，文件並未說明。截至2026年9月26日，模型文件仍有描述此選擇加入功能。¹⁷⁴ 2026年9月29日：模型頁面已移除該章節；設定參考將features.context_management.experimental_mode描述為「實驗性上下文管理設定。此功能目前無法使用」，且GPT-6.1 Sol也未標示為支援此功能。¹⁷⁸

模型選擇流程圖

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; most expensive)
   │     │  └─ No → gpt-6.1-sol (near-Astra at lower cost; default since v0.159.1)
   └─ GPT-6.1 Sol not yet available on your account? → gpt-6-sol, then 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推理所使用的token可能是medium的3至5倍。請只在真正艱難且額外思考確有回報的問題上使用。

TUI快速推理控制項（v0.124.0以上版本）。⁸⁵在互動式TUI工作階段中，Alt+,會將推理強度降低1級，Alt+.則會提高1級——若工作階段途中遇到難題，需要暫時採用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 中的速率限制使用體驗（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.1 Sol、GPT-6 Astra、Sol 與 Luna 在「可用的情況下」，Fast 模式的點數費率為 Standard 的 2.5 倍。此外，隨附模型目錄會將 Fast 設為 TUI 中 GPT-6 Sol 與 Luna（但不包括 GPT-6.1 Sol）的預設級距，除非您設定 service_tier。若點數消耗速度超出預期，請查看 /fast status。相較於類似的純文字互動，產生圖片會以快 3–5 倍的速度消耗內含額度。^162171178

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

API 計費

透過 API 使用 Codex 時，OpenAI 會依所選模型的標準 OpenAI API 費率按 token 計費（另套用適用的提示快取折扣）。目前每 100 萬個 token 的 API 費率如下：GPT-6.1 Sol 的輸入為 $2、輸出為 $10（快取輸入為 $0.10）；GPT-6 Sol 為 $2 / $10；GPT-6 Luna 為 $0.10 / $0.50；GPT-6 Astra 為 $10 / $50。這 4 款模型若提示的輸入 token 超過 272K，整筆請求的輸入費用為 2 倍、輸出費用為 1.5 倍；Fast 模式則為 2 倍。^146171178使用 API 金鑰登入時，不適用 ChatGPT 點數倍率。最新費率請查閱官方 API 價格頁面。²⁰

成本最佳化策略

1. 使用設定檔：為例行任務建立使用 gpt-6-luna 並設定 model_reasoning_effort = "low" 的 fast 設定檔
2. 保留高推理強度：僅在問題確實艱難時使用 xhigh，因為它會多消耗 3–5 倍的 token
3. 使用 --ephemeral：在 CI/CD 中略過工作階段持久化，以降低額外負擔
4. 盡量減少推理摘要：不需要說明時，將 model_reasoning_summary = "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 監控——Enterprise 部署可將用量遙測資料匯出至現有的可觀測性技術堆疊

決策框架

各種操作介面的適用時機

各種 Sandbox Mode 的適用時機

各種推理層級的適用時機

Plan Mode 與直接執行

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 Mode：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

該選擇哪個 Profile？

請依工作選擇預先設定的 Profile：

Profile 檔案（每個預設各一個，位於 ~/.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"

針對個別工作階段切換 Profile：codex --profile careful

Sandbox 與核准系統如何運作？

Codex 採用雙層安全模型，將技術上可執行的操作與何時由 Codex 要求人員核准分開處理。此方法與 Claude Code 的權限系統有根本差異——Codex 會在作業系統核心層級強制執行限制。⁵ 另請參閱企業部署，瞭解管理員在整個組織中強制套用的 requirements.toml 限制。

v0.148.0 強化措施：在 Linux 與 Windows 上，sandbox 限制現在都會採取失敗即關閉原則——遭拒絕或無法讀取的路徑將視為封鎖，不再默許存取。¹¹⁸

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

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

各平台的強制執行方式：

• macOS：透過 sandbox-exec 使用 Apple 的 Seatbelt 框架；系統會在執行階段編譯各模式專用的設定檔，並由核心強制執行。⁶ 自 v0.121.0 起，macOS sandbox 設定檔可將特定 Unix socket 加入允許清單（例如 docker.sock、編輯器 IPC socket），且預設不再封鎖私有 DNS 解析。⁸²
• Linux：使用 bubblewrap（bwrap）隔離檔案系統與命名空間，並以 seccomp 篩選系統呼叫；這些機制會透過獨立的輔助處理程序（codex-linux-sandbox）執行。Landlock 實作則保留為舊版機制，而 v0.163.0 重新命名了 crate 中以 Landlock 命名的命令型別與系統呼叫模組，但未變更強制執行行為。⁵¹⁹³ Codex 會優先使用工作目錄以外 PATH 中找到的第一個 bwrap，否則改用隨附的 codex-resources/bwrap（自 v0.100.0 起內附）。⁷ 若缺少 bwrap 或無法建立使用者命名空間，啟動時會顯示警告。v0.117.0 改善了採用舊版核心設定之較舊發行版上的 sandbox 可靠性。⁷⁵ v0.129.0 強化 Linux 上的 sandbox 啟動流程，並將內附的 Bubblewrap 升級至 0.11.2，納入上游安全性修補；v0.130.0 則進一步強化啟動流程。⁸⁹⁹¹
• Windows：使用具有限制權杖的原生 sandbox（於 v0.100.0 從實驗性功能升格）。亦支援 WSL（沿用 Linux 的 bubblewrap 與 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 devcontainer 內使用 Bubblewrap 執行 sandbox。支援 WSL2；明確拒絕 WSL1（Bubblewrap 與 WSL1 的核心轉接層不相容）。⁸² - Guardian 審查與 hooks（v0.121.0）：Guardian 審查工作階段期間會停用 hooks，避免工具執行前後的 hooks 干擾 Guardian 子代理程式的決策。⁸² 若您依賴 hooks 記錄或驗證，請注意 Guardian 審查會略過它們；如需完整稽核軌跡，請改用應用程式伺服器的可觀測性功能。 - 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 設定。¹³²

獨立的核准 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；自 v0.158.0 起預設開啟）

write_stdin_approval 功能旗標在 v0.151.0 推出時預設關閉，自 v0.158.0 起則預設開啟。將非空白輸入傳送至已提升權限的 unified-exec 終端機之前，此功能會要求重新核准。這些審查會透過 hooks、Guardian、應用程式伺服器及 TUI，以 writeStdin 核准的形式進行；終端機的環境、啟動目錄及權限提升狀態會跨回合保留，而且核准後、寫入任何位元組之前，系統會重新驗證處理程序身分。完整格式化後的動作與核准理由必須在8,000位元組以內——若動作過大或遭截斷，系統會在要求核准或將任何內容傳入終端機前予以拒絕。¹³⁵ v0.158.0 會開啟此旗標（#47799），並停止針對僅限執行階段的授權（例如外掛程式用於指標的授權）觸發審查；額外的代理程式權限、sandbox 繞過，以及啟動後的原則變更仍會觸發審查（#48073）。若要關閉：請在 config.toml 的 [features] 下設定 write_stdin_approval = false。¹⁷⁶

權限設定檔（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 模式，系統會拒絕該操作，而不會悄然放寬限制。¹³⁴

舊版 --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——若不希望 Guardian 逐字記錄包含影像，請設為 false。這兩項功能在 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 的執行時機，而非人員核准層：本指南所述 danger-full-access 搭配 on-request 時的提示行為屬於核准原則，是另一套獨立機制。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 開關互不相依。在 v0.157.0 中，您可在 [features.guardianv2] 下設定 thread_context = false 將其關閉；v0.158.0 已移除此選項。¹⁷⁴

Guardian 執行緒內容永遠開啟（v0.158.0）：#47686 與 #47689 讓 Guardian 工作階段擷取及子代理程式歷程分支一律採用執行緒所擁有的內容。Codex 會忽略 [features.guardianv2] 下的 thread_context，包括設定檔覆寫與受管理需求，並顯示淘汰通知，要求您將其從 config.toml 移除。目前沒有替代的關閉開關。¹⁷⁶

Guardian 可讀取較早的使用者訊息（v0.160.0，須選擇啟用）：Guardian 審查的逐字記錄可能遺漏較早的指示、限制或已撤銷權限。在 [features] 下設定 guardian_conversation_history_tools = true 並啟用 Apps 後，審查者會取得 user_message.search_messages 與 user_message.read_messages 兩項工具；這些工具透過父工作階段本身的 Apps 連線與身分提供。每次呼叫都會重新檢查父工作階段目前的應用程式與工具原則；若工具已停用或需要核准，便會採取失敗即關閉原則。可透過兩個 [auto_review] 索引鍵進行調整：conversation_history_max_output_tokens 限制每次回應的大小（預設估計為4,000個 token；父工作階段較嚴格的限制仍會套用），experimental_conversation_history_prompt 則會取代內建擷取指示（留白時使用預設值）。另一個須選擇啟用的旗標 guardian_root_handoff_context，會將工作代理程式審查所使用的根對話證據，縮限為每次將工作交付給它前後的訊息，以及最新3則訊息。這兩個旗標仍在開發中，預設皆為關閉；設定參考文件尚未列出它們。¹⁸²

[features]
guardian_conversation_history_tools = true

[auto_review]
conversation_history_max_output_tokens = 4000

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。現在，已設定的 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 指令的同時，略過專案範圍的探索。因此，不受信任的簽出內容無法在您信任它之前注入作業規範。¹³²

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 個事件¹³²——舊版名稱也已從可設定介面中移除：原始碼樹中已完全找不到 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 事件（¹³²）——因此，請查看 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 亦然。¹³⁴

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）則不受影響。^125152153

在 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 是權宜之計：^12125148152

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 內建瀏覽器，方便探索與管理。⁷⁵ v0.128.0 擴充了 plugin 工作流程，新增 marketplace 安裝、遠端套件快取、遠端解除安裝 API、plugin 內含 hooks、hook 啟用狀態，以及匯入外部代理程式設定等功能。⁸⁶ v0.129.0（2026年5月7日）新增 plugin 工作區共享（無須重新發布，即可將一組 plugins 推送給團隊成員）、共享存取控制（可針對個別接收者啟用、停用或撤銷）、來源篩選（限制工作區從哪些 marketplaces 取得內容），以及可直接從 /plugins 瀏覽器呼叫的 marketplace 操作，無須透過 CLI。⁸⁹ v0.133.0（2026年5月21日）讓 plugin 探索結果更容易稽核：清單輸出會標示 marketplace、顯示已安裝版本、列出 marketplace 根目錄，並可呈現遠端 plugin 集合，不必猜測結果來自哪個登錄來源。⁹⁸ v0.130.0（2026年5月8日）提升 plugin 封裝透明度，也讓共享工作流程更容易掌控：⁹¹

• 在 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 來源）。每個項目都會同時顯示遠端版本與本機已安裝版本，版本差異一目瞭然。¹⁰⁶ 對於採用共用 plugin 組合做為標準的團隊，預設啟用遠端功能省去了以往阻礙部署、必須在每台機器上逐一啟用的步驟。

Plugin 來源

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

Plugin 探索

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

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

在聊天中使用 @plugin-name，即可直接引用任何已安裝的 plugin。⁶⁸ 提及 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 現在提供更豐富的探索功能，包括中繼資料、分類與評分。⁶⁹ 安裝時的驗證檢查會確認需要 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 儲存庫重複使用。⁹³

# 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。⁸²

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

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

「Agent Plugins」不只是 Codex 的功能名稱，也是開放且不受特定供應商限制的封裝標準。它於2026年8月6日以 Agent Plugins 1.0.0 之名發布，官方網站將其概括為「一種可攜式套件格式，用於封裝可重複使用、能擴充 AI 代理程式的元件」。¹⁶¹ 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 則仍各自沿用其底層規格。¹⁶¹

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

以 Codex 而言：v0.146.0 新增 Agent Plugins 資訊清單、工作區 plugin 發布，以及另外兩個 plugin marketplaces——Amazon Bedrock 與 Claude Code¹¹⁴；v0.147.0 則透過可攜式 Agent Plugins 安裝，以及橫跨本機、個人、工作區與遠端目錄的搜尋功能，完成整套流程。¹¹⁶ 對團隊而言，工作區發布是更具實務效益的一環：可將 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，錯誤仍會顯示）。¹⁴⁰

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

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

Plan Mode 與協作

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

Plan Mode 與 update_plan 工具（v0.152.0）：兩者並不相同，而且只有其中一項預設啟用。Plan Mode 是本節所述的協作模式，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 Mode

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

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

Steer Mode

Steer Mode 自 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

Steer Mode 在 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，而文件中的 Voice 功能頁面介紹的是桌面應用程式內的 ChatGPT Voice，屬於另一個獨立介面。¹⁵⁶¹⁶⁹

其他改進： - 長連結即使跨越多行 TUI 文字換行，現在仍可點選（v0.105.0）⁶¹ - 本機檔案連結採用更完善的格式呈現（v0.106.0）⁶⁰ - TUI markdown 會透過 OSC 8 中繼資料維持網頁連結的可點選狀態；空間不足的表格則會改用易讀的鍵／值記錄呈現，同時保留連結目標（v0.136.0）¹⁶⁸ - 在支援的終端機中，Markdown 連結會顯示為可點選的標籤；其他環境仍會保留可見的 URL（v0.150.0）¹³² - 已修正子代理的 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/」
• 工作流程偏好：「向我顯示差異前，一律先執行 linter」

管線中的記憶

執行 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 階段的對話記錄提煉為持久事實；此次模型變更以相同的權杖成本提升了記憶喚回品質。⁸²
• TUI 記憶選單（v0.121.0）：新增工作階段內的使用者介面，可設定記憶模式、刪除個別記憶及執行重設。記憶重設現在會保留過往執行記錄，不再使其失效；因此，重設操作會清除未來可喚回的記憶，但不會破壞工作階段重播。⁸²

記憶與 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 會根據對話建議可編輯的標題。¹³² v0.151.0 新增 /recap：可隨時要求簡短摘要，掌握對話的近期進度與後續步驟；對於符合條件、閒置且未聚焦的對話，Codex 也會自動產生相同摘要並加入逐字記錄。這些要求彼此隔離且範圍受限，並只會在自動要求失敗時重試。¹³⁵ v0.153.0 讓自動功能可選擇停用：tui.auto_recap = false 會取消排定的自動摘要檢查並捨棄待處理的自動摘要結果，手動執行 /recap 則不受影響。¹⁴⁰

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

恢復

從上次中斷處繼續：

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 任務，並要求代理程式讀取、建立任務，或向任務傳送訊息。¹³² 若要將 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）：專用設定剖析器會從現有的[desktop]設定解析受管理worktree的行為——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工作階段可連接至現有的本機daemon，不必自行啟動一個（#46498）；也能直接從代理程式總覽建立worktree工作階段（#45276），而該總覽也新增狀態篩選分頁（#46839）。如果您的指令碼或設定是以「除非明確要求，否則worktrees不會啟用」為前提撰寫，0.156.0便是改變此行為的版本。若要停用：請在config.toml的[features]下設定worktrees = false（單次執行可使用--disable worktrees）。較舊的本機daemons：如果建立worktree或執行/cd時遭到封鎖，並顯示「The local Codex service cannot check background terminals」，請執行codex app-server daemon update，再重新啟動Codex。¹⁶⁹¹⁷¹

供模型使用的Worktree工具（v0.162.0）：在啟用此功能的受信任本機專案中，模型本身可透過新工具建立及列出受管理的worktrees（#50148），而新對話與分支建立提示詞也會說明worktree選項（#50416）。¹⁸⁷

自動化

自動化會在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，且無須使用WSL即可享有完整功能，包括skills、自動化與worktrees。⁶⁶

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");