Codex CLI：權威技術參考指南

重點摘要：Codex是跨介面的程式設計代理：能讀取您的程式碼庫、在作業系統層級的沙箱中執行命令、修補檔案，並將工作委派至雲端。掌握5個系統——config.toml、沙箱／核准模型、AGENTS.md、MCP與skills——它就能成為事半功倍的利器。建議預設使用GPT-5.6 Sol（「Power」設定、中等推理）；前一代旗艦GPT-5.5在Codex中提供400K context，在API中則提供1M。⁸³¹¹⁷第一次使用嗎？可直接前往安裝與快速開始。想追蹤版本發布？最新穩定版是v0.147.0（2026年8月7日）——近期版本的重點脈絡請參閱版本亮點，所有更新則請查看變更日誌。¹¹⁶

Codex的運作方式是跨介面的程式設計代理，而非單純撰寫程式碼的聊天機器人。CLI會讀取您的程式碼庫、在沙箱中執行命令、修補檔案、透過MCP連接外部服務，並將長時間執行的工作委派至雲端。它在本機執行，卻能全局思考；同一套智慧會依您的工作方式驅動5種不同介面，其中包括新的Chrome extension，讓Codex可在瀏覽器中運作而不會接管它。⁹⁰

隨意使用與有效運用Codex之間的差異，取決於5個核心系統。掌握這些系統後，Codex便能成為事半功倍的利器：

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

我花了數個月，在正式環境的程式碼庫、CI/CD pipelines與團隊工作流程中，讓Codex與Claude Code並行運作。本指南將這些經驗濃縮為我剛開始使用時最希望能找到的完整參考資料。每項功能都包含實際語法、真實設定範例，以及連資深使用者都容易踩到的邊界案例。

重點摘要

• 5個介面、同一個核心：CLI、桌面應用程式、IDE擴充功能、雲端任務與全新的Chrome擴充功能，皆共用相同的GPT-5.x-Codex智慧，因此可依工作流程選擇最合適的介面。⁹⁰
• 作業系統層級沙箱機制：Codex會在核心層級強制執行檔案系統與網路限制（macOS使用Seatbelt，Linux使用Landlock+seccomp），而非在容器內執行。
• AGENTS.md可跨工具使用：您的專案指示可在Codex、Cursor、Copilot、Amp、Jules、Gemini CLI、Windsurf、Cline、Aider、Zed，以及60,000多個開放原始碼專案中運作。一次撰寫，到處使用。
• Profiles減少切換情境的負擔：定義具名稱的設定預設值（fast、careful、auto），再透過--profile於不同預設值之間切換。
• Context管理至關重要：GPT-5.6系列（Sol、Terra、Luna）採用272K Context window；前一代旗艦GPT-5.5則在Codex提供400K、在API提供1M。善用/compact、聚焦的提示詞與@file參照，主動管理Token預算。⁸³¹¹²

如何使用本指南

這是一份超過3,300行的參考指南——請依您的經驗程度開始閱讀：

文末的快速參考卡提供所有主要命令的一覽式摘要。

版本亮點：近期有哪些變更

以下依版本敘述，適合追蹤Codex發布進度的讀者。剛開始使用嗎？可先略過此節，完成快速入門後再回來閱讀——其中沒有任何內容是開始高效使用所必需的。

GPT-5.6 Sol是Codex建議的預設選項——預設為採用中等推理強度的「Power」設定，也可調整為更聰明或更快速；GPT-5.5（2026年4月23日：Codex中為400K Context、API中為1M、每MTok為$5/$30、Terminal-Bench 2.0 SOTA達82.7%）則是前一代旗艦模型。⁸³¹¹⁷ 自CLIv0.147.0（穩定版，2026年8月7日）起，codex exec --full-auto已移除（自v0.128起已棄用）——仍傳入此參數的指令碼現在會發生錯誤；請改用--sandbox workspace-write搭配核准旗標或profile。v0.147.0亦推出--approve-for-me（由自動審查程序裁決核准提示）、可攜式Agent Plugins，並可搜尋本機、個人、工作區與遠端目錄；選用加入的MCP2026-07-28通訊協定（分頁探索、多輪請求、非阻塞伺服器啟動），以及用於整理冗長逐字稿的對話區段。¹¹⁶v0.146.0（穩定版，7月29日）讓已設定的Proxy涵蓋所有傳輸層，新增Agent Plugins資訊清單、Amazon Bedrock與Claude Code市集、可釘選執行緒的工作階段命名，以及由executor提供的skills；v0.146.1（8月5日）則強化了具網路安全能力模型的自動審查預設值。¹¹⁴¹¹⁵自CLIv0.145.0（穩定版，2026年7月21日）起，/import除了Claude Code外，也可從Cursor遷移——包括設定、MCP伺服器、plugins、工作階段、命令與專案範圍記憶——語音以串流realtime V3對話形式回歸，支援音訊輸入與常見本機格式的音訊工具輸出；選用加入的multi-agentv2體驗已穩定化，可設定sub-agent模型、推理層級與並行數；實驗性的分頁執行緒歷史記錄帶來高效率的繼續作業、搜尋、持久化名稱、sub-agent支援與記憶；實驗性的Amazon Bedrock登入支援自訂端點與驗證（GPT-5.6 Sol為預設Bedrock模型）；且內建的GPT-5.4模型選項改為GPT-5.6 Terra與Luna變體；v0.144.6（7月18日）將GPT-5.6 Sol/Terra/Luna的Context window更正為272,000Token。¹¹¹¹¹²自CLIv0.140.0（穩定版，2026年6月15日）起，/usage會顯示每日／每週／累積帳戶Token活動；可透過codex delete／/delete永久刪除工作階段（附確認防護）；/import可選擇性地從Claude Code遷移設定、專案設定與近期聊天記錄；輸入@預設會開啟涵蓋檔案、plugins與skills的統一提及選單；受管理的Amazon Bedrock API-key驗證隨之推出，並為CLI與MCP OAuth認證資料提供加密本機儲存；實驗性的/realtime語音控制已從TUI移除（語音後於v0.145.0以串流realtime V3形式回歸）。¹⁰²¹¹²自CLIv0.139.0（穩定版，2026年6月9日）起，code mode可直接呼叫獨立網頁搜尋（包含從巢狀JavaScript工具呼叫中執行），並接收純文字結果；工具／connector輸入schema現在會保留oneOf／allOf結構，以提升大型schema與MCP相容性；codex doctor新增editor與pager環境詳細資料（會在JSON中遮蔽敏感值）；plugin市集則透過codex plugin marketplace list --json公開來源，並加快快取目錄清單的速度。¹²²v0.138.0（6月8日）新增/app，可在macOS與Windows將CLI工作階段交接給桌面應用程式；向模型公開本機影像路徑；使推理強度選擇更具彈性；並為plugin自動化提供結構化JSON輸出。它也開始在multi-agentv2中加密父agent傳給sub-agent的任務文字，因此委派指示不再以純文字出現在本機工作階段記錄中（請參閱Multi-Agent）。¹²³¹⁰⁸v0.137.0（6月4日）推出multi-agentv2（每個執行緒保留runtime、更簡潔的後續操作與metadata預設值、hide_spawn_agent_metadata預設為true）、F13–F24TUI快速鍵，以及每回合解析目錄的v1skills擴充功能。¹²⁴自CLIv0.135.0（2026年5月28日）起，codex doctor會回報更豐富的環境、Git、terminal、app-server與thread清單；當TUI透過遠端連線時，/status會顯示遠端連線詳細資料與伺服器版本；vim mode新增text-object編輯、改進word／line-end行為，以及可設定的interrupt-turn；/permissions現在可辨識具名稱的permission profiles並顯示自訂profile；已封裝的Codex建置版本可在支援的macOS上探索並使用隨附、已修補的zsh helper；且Python SDK為thread與turn API提供易懂的Sandbox預設值。¹²⁶v0.134.0（2026年5月26日）導入跨本機對話歷史記錄搜尋，支援不分大小寫的內容比對與結果預覽；使--profile成為CLI、TUI permissions與sandbox流程中的主要profile選擇器（舊版profile設定會遭拒絕並提供遷移指引）；透過每台伺服器的環境指定與串流HTTP伺服器的OAuth選項改善MCP設定；藉由保留本機$ref／$defs並壓縮過大的schema，使connector工具schema更可靠；允許唯讀MCP工具在宣告readOnlyHint時並行執行；並為extension與hook提供更豐富的Context，包括供extension工具使用的對話歷史記錄。¹⁰¹v0.133.0（2026年5月21日）預設啟用goals，並提供專屬儲存空間與進度追蹤；codex remote-control新增前景就緒／狀態，以及daemon式啟動／停止；permission profiles新增清單API、繼承、受管理的requirements.toml、runtime重新整理與更強的Windows sandbox整合；plugin探索會顯示已安裝版本、市集根目錄與遠端集合；extensions可觀察subagent啟動／停止、工具執行、turn metadata，以及非同步核准／turn處理。2026年5月21日的Codex app更新新增前景Mac視窗的Appshots、跨app／IDE／CLI的Goal mode GA、應用程式內browser註解改善，以及符合資格Mac使用者可選擇啟用的鎖定Computer Use。⁹⁹¹⁰⁰v0.132.0（2026年5月20日）新增Python SDK第一級驗證、更簡潔的純文字turn API、更豐富的TurnResult、codex exec resume --output-schema、更快的TUI啟動、以驗證為基礎的遠端executor註冊，以及app-serverturn中的影像保真度保留。請使用明確的sandbox／approval旗標或permission profiles——舊版--full-auto已於v0.147.0移除；js_repl仍維持移除狀態。^{86878991969798116}

穩定性注意事項：標示為[EXPERIMENTAL]或under development的功能可能會在不同版本間變更。自v0.133.0（2026年5月21日）起，goals預設啟用，permission profiles成為第一級受管理介面，plugin探索更容易檢視，且remote-control更容易以前景或daemon化app-server命令執行。Codex Cloud與code mode仍屬實驗性或開發中；核心CLI、sandboxing、AGENTS.md、config.toml、Skills、hooks、multi-agent工具、plugins、Browser、Computer Use與Appshots則依平台與方案，屬於穩定或已有文件說明的使用者介面。v0.132.0補足Python SDK驗證與結構化繼續作業自動化；v0.131.0新增codex doctor、統一的@提及搜尋、市集CLI命令、可感知版本的plugin分享、由daemon管理且可於runtime啟用／停用的remote-control、由registry支援的environments，以及額外的Windows sandbox強化。⁹⁶⁹⁷⁹⁸舊版--full-auto已於v0.147.0移除（自v0.128起已棄用），而js_repl仍維持移除狀態。^8687116

Codex的運作方式：心智模型

在深入瞭解各項功能前，先理解Codex的架構如何形塑您使用它的一切。此系統由共用的智慧層支援，橫跨五個介面：

┌─────────────────────────────────────────────────────────┐
│                    CODEX SURFACES                       │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐   │
│  │   CLI    │  │ Desktop  │  │   IDE    │  │ Cloud  │   │
│  │ Terminal │  │   App    │  │Extension │  │  Tasks │   │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘   │
│  Local exec     Multi-task    Editor-native  Async      │
│  + scripting    + worktrees   + inline edits detached   │
│  ┌──────────┐                                           │
│  │  Chrome  │  Signed-in browser workflows              │
│  │Extension │  (launched May 2026)                      │
│  └──────────┘                                           │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                        │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐     │
│  │   MCP   │  │ Skills  │  │  Apps   │  │  Search │     │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘     │
│  External tools, reusable expertise, ChatGPT            │
│  connectors, web search (cached + live)                 │
├─────────────────────────────────────────────────────────┤
│  SECURITY LAYER                                         │
│  ┌─────────────────────────────────────────────────┐    │
│  │    Sandbox (Seatbelt / Landlock / seccomp)      │    │
│  │    + Approval Policy (untrusted → 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-5.x模型系列驅動所有功能。截至2026年8月，gpt-5.6-sol是建議的預設選擇——採用「Power」設定與中等推理強度；Terra適合日常使用，Luna則快速且實惠；gpt-5.5是上一代旗艦模型（在Codex中提供400K context，在API中提供1M），而gpt-5.4將於2026年8月31日從Codex退役。⁸³¹¹⁷它能讀取檔案、撰寫修補程式、執行shell指令，並針對您的程式碼庫進行推理。當context填滿時，Codex會壓縮對話以釋放空間。此層會消耗token。

安全層：Codex執行的每個指令都會通過作業系統層級的sandbox。在macOS上，Apple的Seatbelt framework會強制執行核心層級的限制。在Linux上，Landlock與seccomp會篩選檔案系統及syscall存取權。sandbox在核心層級運作，而非在container內部。接著，approval policy決定何時要求人工確認。

擴充層：MCP可連接外部服務（GitHub、Figma、Sentry）。skills會封裝可重複使用的工作流程，讓Codex依需求載入。apps可連接ChatGPT connectors。Web search則從網際網路加入即時context。

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

關鍵洞見：多數使用者只會使用其中一個介面。進階使用者則會善用全部五個：以Cloud處理長時間執行的任務、以CLI執行可確定的repo操作、以IDE extension進行緊密的程式開發迴圈、以desktop app規劃與協調，以及透過Chrome進行已登入的瀏覽器工作流程。

目錄

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

如何安裝 Codex？

套件管理工具

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

# Homebrew (macOS)
brew install --cask codex

# winget (Windows)
winget install OpenAI.Codex

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

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

自v0.128.0起，Codex提供自我更新指令；其餘操作則透過當初安裝時使用的套件管理工具執行。⁸⁶ 自v0.146.0起，發行成品、頻道中繼資料與安裝程式別名皆由OpenAI託管的發行基礎架構提供，並以GitHub作為備援。¹¹⁴ 若您的網路針對Codex安裝與更新將GitHub列入允許清單，也請加入OpenAI發行主機——備援機制代表允許清單遺漏時會悄然降級，而非明確失敗。

# Check what you are running
codex --version                          # -> codex-cli 0.147.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會在Environment下明確標示此問題）。

解除安裝套件不會移除您的狀態。驗證資訊、設定與工作階段歷程皆位於~/.codex/。若要在重新安裝後保留登入狀態與歷程，請保留該資料夾；只有確實需要完全重設時才刪除它——rm -rf ~/.codex也會捨棄config.toml、auth.json及所有儲存的工作階段。

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

macOS與Linux可使用一行安裝指令碼，它是GitHub發行資產：⁶⁰

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

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

二進位檔下載

若環境未安裝npm或Homebrew，請從GitHub Releases¹下載特定平台的二進位檔：

系統需求

• macOS：Apple Silicon或Intel（透過Seatbelt提供完整sandbox支援）
• Linux：x86_64或arm64（透過Landlock+seccomp提供sandbox）
• Windows：使用受限權杖的原生sandbox（於v0.100.0從實驗性功能升級）。也支援WSL²

驗證

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

有兩種驗證方式：

1. ChatGPT帳戶（建議）：使用既有的Plus、Pro、Team、Business、Edu或Enterprise訂閱登入。可完整使用功能，包括cloud tasks。
2. API Key：透過CODEX_API_KEY環境變數或codex login --with-api-key設定。部分功能（cloud threads）可能無法使用。

專家提示：可透過config.toml中的cli_auth_credentials_store設定認證資料儲存方式。選項包括：file（預設）、keyring（OS keychain）或auto（可用時使用keyring，否則改用檔案）。

Amazon Bedrock登入（v0.145.0，實驗性）：模型存取透過Amazon Bedrock進行的團隊，可使用支援自訂端點與驗證的實驗性登入途徑；此途徑與既有的受管理API-key驗證（v0.140.0+）及AWS認證鏈並存（請參閱Custom Model Providers）。GPT-5.6 Sol是預設的Bedrock模型。¹¹²

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.147.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才會修補檔案；sandbox與approval policy則決定何時必須先徵詢您的同意。

5. 進行變更：

> Add input validation to the login endpoint

Codex會以diff形式提出編輯建議。請以y檢閱並核准，或以n拒絕。

6. 使用slash command：

> /plan Refactor the database layer to use connection pooling

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

7. 檢查您的工作：

> /diff

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

接下來：

• 使用專案指示設定AGENTS.md（請參閱AGENTS.md如何運作？）
• 為您的工作流程設定設定檔（請參閱Profiles）
• 嘗試以codex exec進行非互動式自動化（請參閱Non-Interactive Mode）

核心互動介面

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

1. 互動式CLI（Terminal UI）

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

Terminal UI是一個全螢幕應用程式，包含：

• 撰寫區：輸入提示、使用@附加檔案、以!前綴執行殼層命令
• 輸出窗格：串流顯示模型回應、工具呼叫與命令輸出
• 狀態列：模型、token用量、git分支、sandbox模式

重要TUI快速鍵：

狀態列變更（v0.121.0）：狀態列原有的內容視窗量表，已改為顯示內容視窗使用程度的內容百分比指示器。若有指令碼或hooks會剖析狀態列，請檢查此格式變更。⁸²當有新版本可用時，Codex也會顯示CLI更新公告。

TUI中可用的Slash commands：

工作流程選擇器重新設計（v0.129.0）：現在可從重新設計的選擇器更輕鬆地使用resume與fork；新的原始捲動回溯模式讓您能在需要逐字複製命令或模型輸出時，捲動查看未渲染的逐字稿。這在分流冗長的除錯工作階段，或將輸出傳送至其他工具時相當實用。⁸⁹

統一的@提及選單（v0.140.0）：現在於撰寫區輸入@時，預設會開啟涵蓋檔案、plugins與skills的單一提及選單，取代僅能附加檔案的流程——按一次鍵即可參照任何專案資源。¹⁰²

2. Codex Desktop App（macOS＋Windows）

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

Desktop App新增了CLI沒有的能力：

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

由GPT-Live驅動的ChatGPT Voice（desktop 26.715，2026年7月23日）：Desktop App現在可透過語音操作——不必打字，即可討論工作並協調Chat、Work與Codex之間的任務。在macOS上，啟用Screen context會將最前景視窗的appshot分享給對話，因此可直接詢問眼前所見，而不必描述畫面。適用於Plus、Pro、Business、Edu與Enterprise，可在Desktop App及iOS上的Remote使用。這是desktop介面的語音功能；CLI自身的空白鍵語音轉錄則是另一項實驗性功能。¹¹³

何時使用app或CLI：當您需要協調多個工作串流或進行視覺化diff審查時，請使用Desktop App。若需要終端機可組合性、指令碼化或CI/CD整合，則使用CLI。

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

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

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

可從VS Code Marketplace或Cursor/Windsurf extension stores安裝。³

4. Codex Cloud[EXPERIMENTAL]

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

• Fire and forget：佇列任務，讓其獨立於本機運作
• 平行執行：同時執行多個cloud tasks
• 建立PR：Codex會依已完成的工作建立pull requests
• 本機套用：使用codex apply <TASK_ID>將cloud結果拉入本機repo

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

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

5. Codex for Chrome[NEW]

Codex以Chrome瀏覽器擴充功能形式推出，成為繼CLI、desktop app、IDE extension與cloud之外的第5種介面。此擴充功能設計為配合您平常的瀏覽工作，而非接管瀏覽：Codex會在背景平行處理各個分頁，您仍可掌控它可操作哪些網站。⁹⁰

• 平行分頁執行：Codex可同時操作多個分頁，而不會鎖定前景分頁。
• 依網站控管：您可將Codex可互動的網站加入允許清單；預設不具任何存取權。
• 以瀏覽器作為工作平台：此擴充功能最適合頁面即為真實來源的app與網站工作——管理主控台、內部儀表板、內容管理UI、ticket systems——並非要取代本機repo上的CLI。
• 相同核心能力：Codex for Chrome使用與其他介面相同的GPT-5.x-Codex智慧能力，因此可在CLI中運作的AGENTS.md或skills設定，也會將相同慣例帶入瀏覽器驅動的工作。

請從Codex Chrome extension docs安裝。⁹⁰

設定系統深入剖析

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桌面應用程式中的本機專案現在可涵蓋多個相關資料夾，其中一個會指定為主要資料夾（專案選單→Edit project）。config.toml的自動探索僅會針對主要資料夾執行；次要資料夾仍可用於檔案搜尋、讀取與編輯，但不會提供任何設定。位於次要資料夾中的.codex/config.toml只是Codex可讀取的檔案，不是它會載入的設定。這是桌面應用程式的專案範圍設定，並非變更上述優先順序規則——CLI仍會從目前工作目錄向上走訪來解析專案設定。¹¹³

完整設定參考

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

# ─── Model Selection ───────────────────────────────────
model = "gpt-5.6-sol"                  # Recommended default (the "Power" setting)
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-5.5"               # 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"          # untrusted|on-request|never

[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)

# ─── 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
log_dir = ""                            # Custom log directory
sqlite_home = ""                        # Override SQLite-backed resumable state location

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

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

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

# ─── Feature Flags ─────────────────────────────────────
# Use `codex features list` for current names/stages/defaults.
[features]
shell_tool = true                       # Shell command execution (stable)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
enable_request_compression = true       # zstd request compression where supported (stable)
fast_mode = true                        # Service-tier selection and Fast-tier commands (stable)
goals = true                            # Goal mode; stable and on by default in v0.133.0+
hooks = true                            # Lifecycle hooks (stable)
multi_agent = true                      # Enable multi-agent collaboration tools (stable)
personality = true                      # Personality selection (stable)
plugins = true                          # Plugin system (stable)
plugin_hooks = true                     # Plugin-bundled hooks (stable)
plugin_sharing = true                   # Workspace plugin sharing (stable)
browser_use = true                      # In-app browser automation (stable)
browser_use_external = true             # Chrome 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 networking proxy (experimental)
prevent_idle_sleep = true               # Keep machine awake during active turns (experimental)
terminal_resize_reflow = true           # Terminal reflow improvements (experimental)

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

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

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

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

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

Profiles

適用於不同工作模式的具名設定預設集：

# Define profiles in ~/.codex/config.toml

[profiles.fast]
model = "gpt-5.6-luna"
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

[profiles.careful]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.auto]
model = "gpt-5.6-sol"
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

啟用Profile：

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

專家提示：在設定的頂層加入profile = "fast"，即可設定預設Profile。每個工作階段可透過--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"

警告：OpenAI代管模型的chat/completionswire API（wire_api = "chat"）已遭棄用，OpenAI並宣布將於2026年2月移除。³⁴本機供應商（Ollama、LM Studio）可能仍接受此格式。若使用OpenAI端點，請改用wire_api = "responses"。

使用--oss旗標搭配本機模型：

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

或在設定中指定：

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

內嵌設定覆寫

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

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

應該選擇哪個模型？

可用模型（2026年8月）

GPT-5.5（2026年4月23日）推出時是OpenAI針對多數Codex任務的建議選擇：複雜程式設計、電腦操作、知識工作及研究工作流程。4月23日起，ChatGPT Plus／Pro／Business／Enterprise／Edu／Go使用者可在Codex CLI／網頁／桌面版使用；4月24日起可在OpenAI API使用。Context window：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（44種職業）為84.9%、OSWorld-Verified為78.7%、Tau2-bench Telecom為98.0%（未進行prompt tuning）。OpenAI在推出前，於內部使用GPT-5.5＋Codex重寫服務基礎架構，使token生成速度提升20%。⁸³

GPT-5.4與GPT-5.4 mini將於2026年8月31日自Codex退役。¹¹⁷ 在此之前，GPT-5.4仍可在各Codex介面中選用。⁶⁴ 確切的模型清單會因帳戶與推出進度而異。請檢查本機快取：~/.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在2026年7月23日停止服務前，仍可透過API與CLI使用。⁷¹⁸⁸

免費方案說明（2026年5月5日）：GPT-5.5 Instant於2026年5月5日向ChatGPT免費方案推出。此舉讓GPT-5.5模型家族的受眾擴及付費方案以外，但使用Codex CLI仍需符合資格的Plus／Pro／Business／Enterprise／Edu／Go訂閱，或API key。⁹²

GPT-5.4 mini（2026年3月17日）：GPT-5.4較小、更快的變體，具備400K Context，每MTok價格為$0.75／$4.50——僅使用GPT-5.4配額的30%。非常適合進行subagent委派：讓GPT-5.4負責規劃與協調，同時由GPT-5.4 mini subagent平行處理較聚焦的子任務（程式碼庫搜尋、檔案審查、文件處理）。⁷⁶

Bedrock GPT-5.6（Sol、Terra、Luna）（v0.143.0，2026年7月8日）：Codex新增對託管於Amazon Bedrock的3個GPT-5.6模型變體之第一級支援，包括max推理強度等級。若團隊的模型存取透過Bedrock provider執行，便能如同其他自訂provider模型一樣選取這些模型（請參閱Custom Model Providers）；max強度等級適用於最困難的推理與agentic工作負載。¹⁰⁶ v0.144.6（2026年7月18日）更新了Sol、Terra與Luna的隨附指示，並將其Context window更正為272,000 tokens。¹¹¹ v0.145.0（2026年7月21日）新增具備自訂endpoint與驗證支援的實驗性Bedrock登入功能，將GPT-5.6 Sol設為預設Bedrock模型，並把隨附的GPT-5.4模型選項遷移至對應的Terra與Luna變體。¹¹²

模型選擇流程圖

Is this a quick fix or simple question?
├─ Yes → gpt-5.6-luna (fastest, most affordable)
└─ No
   ├─ Do you need real-time pairing speed?
   │  ├─ Yes → gpt-5.3-codex-spark (near-instant, Pro only)
   │  └─ No
   │     ├─ Subagent or parallel subtask (search, review, processing)?
   │     │  ├─ Yes → gpt-5.6-luna (the bundled subagent pick since v0.145.0)
   │     │  └─ No
   │     │     ├─ Everyday coding task (refactor, migration, feature build)?
   │     │     │  ├─ Yes → gpt-5.6-terra (everyday model, 272K context)
   │     │     │  └─ No → gpt-5.6-sol (flagship — the default "Power" setting)
   └─ Still unsure? → gpt-5.6-sol

推理強度

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

支援的等級取決於模型。minimal僅適用於GPT-5模型。並非所有模型都支援每一種等級。

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

專家提示：對相同prompt而言，xhigh推理所使用的token可能是medium的3至5倍。請保留給真正困難、額外思考確實值得投入的問題。

TUI快速推理控制（v0.124.0+）。⁸⁵ 在互動式TUI工作階段中，Alt+,會將推理強度降低一級，而Alt+.會提高一級——當工作階段進行到一半的棘手問題需要暫時依序從medium → high → xhigh提升時，無須使用/effort或-c。若在工作階段中接受模型升級，推理強度會重設為新模型的預設值，而不會沿用先前的等級。

切換模型

使用/model slash command可在工作階段中切換模型，或透過--model／-m為每次執行設定：

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

Codex 的費用是多少？

另請參閱模型選擇以瞭解功能，以及決策框架以針對各項任務選擇合適模型。

透過 ChatGPT 方案存取

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

2026年4月定價更新：Business 年繳價格從每席位每月$25降至$20。Business 與 Enterprise 工作區現在可使用採隨用隨付定價的僅 Codex 席位——無固定席位費用，依 Token 用量計費。⁷⁹定價頁面現在以依模型分級的方式公布用量限制（見上表），不再沿用2026年2月 Codex Desktop App 推出時的推廣性2倍乘數。¹⁶¹¹⁹

2026年5月用量限制提升（已於2026年5月31日到期）：Plus 方案的 Codex 在該期間採用25倍、5小時用量限制（相較於標準的20倍提升），且$100/月方案級別的額度翻倍。⁸⁹

點數費用

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

實際上，「GPT-5.6 每則訊息平均使用5-40點」；在支援的模型上，快速模式會以較高費率消耗點數，而影像生成消耗內含額度的速度比相近的純文字回合快3-5倍。¹¹⁹

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

API 計費

透過 API 使用 Codex 時，OpenAI 會依所選模型的標準 OpenAI API 定價，按 Token 計收用量費用（加上適用的 Prompt 快取折扣）。請查看官方 API 定價頁面以取得目前費率。²⁰

成本最佳化策略

1. 使用設定檔：建立使用 gpt-5.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，並檢查組織的計費儀表板。

實際成本範例

常見任務的代表性 API 成本（2026年中 gpt-5.3-codex 定價快照，中等推理強度——相對大小可套用至各模型）：

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

隱藏的 Token 額外負擔

每次工具呼叫都會在您可見的 Prompt 之外增加 Token：

專家提示：請透過 TUI 中的 /status 監控實際用量。Token 計數包含所有額外負擔，而不只是您可見的訊息。若成本出乎意料，請檢查已連線的 MCP 伺服器數量——每一個都會為每次 API 呼叫新增工具定義。

團隊成本管理

團隊成本控管策略：

• 設定 requirements.toml，在全組織範圍強制執行模型與推理強度限制。
• CI/CD 使用 gpt-5.6-luna——自動化管線鮮少需要最高推理強度。
• 依設定檔編列預算——定義 ci、review 與 dev 設定檔，並設定適當的成本上限。
• 透過 OpenTelemetry 監控——Enterprise 部署可將用量遙測資料匯出至既有的可觀測性技術堆疊。

決策框架

何時使用各種介面

何時使用各種 Sandbox 模式

何時使用各種推理層級

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

該選擇哪個設定檔？

請依工作內容選擇預先設定的設定檔：

config.toml 設定：

# Default profile
profile = "default"

[profiles.fast]
model = "gpt-5.6-luna"
model_reasoning_effort = "low"

[profiles.careful]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"

[profiles.pair]
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"

[profiles.ci]
model = "gpt-5.6-luna"
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

每個工作階段切換設定檔：codex --profile careful

Sandbox 與核准系統如何運作？

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

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

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

各平台的強制執行機制：

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

這點為何重要：不同於容器式 sandbox（Docker），作業系統層級的 sandbox 速度更快、負擔更輕，也更難逃逸。Codex 甚至尚未收到系統呼叫前，核心便已強制執行限制。

安全性修正： - zsh-fork sandbox 繞過漏洞（v0.106.0）： 修正透過 zsh 分叉執行 shell 時可能繞過 sandbox 限制的漏洞。⁶⁰ 若您仍使用較舊版本，請立即升級。 - 輸入大小上限（v0.106.0）： Codex 現在將輸入限制在約100萬個字元，以免過大的承載資料導致程式無回應。⁶⁰ - 安全的 devcontainer 設定檔（v0.121.0）： 新增強化的 Docker devcontainers 客戶設定檔，使用 Bubblewrap 在容器內提供 sandbox。支援 WSL2；明確拒絕 WSL1（Bubblewrap 與 WSL1 的核心轉接層不相容）。⁸² - Guardian 審查與 hooks（v0.121.0）： Guardian 審查工作階段期間會停用 hooks，避免工具執行前後的 hooks 干擾 Guardian 子代理程式的決策。⁸² 若您仰賴 hooks 進行記錄或驗證，請留意 Guardian 審查會略過這些機制；如需完整稽核軌跡，請改用應用程式伺服器的可觀測性功能。 - 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。⁸⁷

個別核准 ID（v0.104.0+）

Codex 現在會為多步驟 shell 執行中的每個指令指派不同的核准 ID。這表示核准作業可細分至單一指令——核准序列中的一個指令，不會自動核准同一次 shell 呼叫中的後續指令。⁴⁹

彈性的核准控制（v0.105.0+）

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

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

執行階段權限要求（v0.113.0+）

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

App 核准模式 writes（v0.144.0+）

Apps 與 connectors 新增中間層級的核准方式：writes app 核准模式允許 app 宣告的唯讀操作直接執行而不顯示提示，但遇到任何寫入操作時仍會暫停。¹⁰⁷ 在此之前，app 核准接近全有或全無；writes 更符合多數管理者真正期望的整合信任模式——可自由查看，若要修改則先詢問。

自動審查的核准：--approve-for-me（v0.147.0+）

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

權限設定檔（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。若只是單次指令的例外情況，建議優先使用規則，避免大幅放寬整個設定檔。⁸⁷

舊版 --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 = "untrusted"

社群普遍認為這項組合是最理想的平衡點：提供最大能力，但每個指令都需要核准。⁸

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"。

強化 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 才真正讓「所有傳輸層」名副其實。 設定的 proxies 現在會套用至驗證、plugin 下載、MCP 授權、遠端執行、WebSocket 連線、HTTP 重新導向及 LM Studio 連線——變更記錄指出，這7條路徑過去都會忽略 proxy。¹¹⁴ 如果您在 v0.146.0 之前透過企業 proxy 執行 Codex，並遇到登入或 plugin 安裝失敗、一般模型呼叫卻正常運作的情況，這項缺口很可能就是原因。

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

桌面版多資料夾專案（26.715，2026年7月23日）：上述走訪方式描述的是 CLI，所有內容都以目前工作目錄為基準解析。ChatGPT 桌面版應用程式現在允許一個本機專案涵蓋數個相關資料夾，但探索作業只會以其中一個資料夾為準：「新對話、Git 操作，以及 AGENTS.md、skills 和 config.toml 的自動探索，均使用主要資料夾。次要資料夾仍可供檔案搜尋、讀取及編輯使用。」您可以透過專案選單中的編輯專案，選擇要設為主要資料夾的項目。¹¹³

這一項設定會同時管理 Codex 五大核心系統中的三項：指令、skills 與設定都會以主要資料夾為準。實務上，次要資料夾中的 AGENTS.md 只是 Codex 能夠開啟的檔案，而非會自動載入的運作規範。如果包含規則的儲存庫是您第二個附加的資料夾，請將它提升為主要資料夾，或在主要資料夾的 AGENTS.md 中重新載明這些規則；您原本預期會被自動載入的儲存庫 skill 資料夾亦同。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。適合公開分享的經驗，是暴露面分布與驗收標準，而非私人權杖值、確切路徑或偵測器內部機制。⁹⁵

覆寫機制

任何目錄層級中的 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 導入 hooks（AfterAgent），並於 v0.100.0 加入 AfterToolUse；之後又在 v0.114.0 推出實驗性的 hooks 引擎，提供 SessionStart 與 Stop 事件。⁷⁰ 自 v0.124.0（2026年4月23日）起，hooks 已進入穩定階段。⁸⁵現在可直接在 config.toml 和 requirements.toml 中設定 hooks，不再需要獨立的 hook 指令碼檔案；除了 apply_patch 與長時間執行的 Bash 工作階段外，它們也會監看 MCP 工具。這套系統如今涵蓋工作階段生命週期與工具層級的自動化，補足了與 Claude Code hook 模型之間的差距。

可用的 Hook 事件

Hook 設定

Hooks 設定於 .codex/config.toml：

[[hooks]]
event = "AfterToolUse"
command = "echo 'Tool completed' >> /tmp/codex-log.txt"

[[hooks]]
event = "SessionStart"
command = "echo 'Current date: $(date +%Y-%m-%d)'"

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

重現 Claude Code Hook 模式

若要從 Claude Code 遷移，可透過下列方式實現類似的自動化：

專家提示：自 v0.124.0（2026年4月23日）起，hooks 引擎已進入穩定階段。新 hook 事件仍會隨版本推出，請查看 Codex 變更記錄。

TUI 內建 hook 瀏覽器（v0.129.0）：在 TUI 中執行 /hooks，即可探索可用的 hooks、查看目前啟用的項目，並在不編輯 config.toml 的情況下切換個別 hook。若要排解外掛內附 hook 的異常行為，或在專心編輯期間暫時停用 AfterToolUse linter，此功能格外實用。⁸⁹

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

MCP可透過連接外部工具與服務，擴展Codex的能力。codex mcp命令群組目前標示為experimental，命令與設定格式可能會隨版本發行而變動。Codex支援兩種傳輸類型：STDIO（本機程序）與Streamable HTTP（遠端伺服器）。¹¹

v0.121.0 MCP變更：工具現在會以namespace註冊，因此清單中的工具名稱會顯示為<server>:<tool>，而非單獨名稱——請更新任何依未限定工具名稱進行grep的指令碼或提示。新的supports_parallel_tool_calls旗標已傳遞至隨附的MCP，讓宣告支援的伺服器可平行執行。sandbox狀態中繼資料現在會透過MCP工具中繼資料傳遞，使伺服器得以調整行為（例如在read-only sandbox下執行時發出警告）。自訂codex/sandbox-state請求已移除——請改用中繼資料路徑。MCP Apps推出計畫的第3階段在此推出工具呼叫支援；採用deferred-call模式的伺服器現在也支援扁平化deferred tool calls。⁸²

v0.142.2 MCP變更（2026年6月25日）：MCP工具現在在支援時會預設使用tool search——Codex不再預先載入每個工具定義，而是視需要探索工具。在工具繁多的設定中，這可改善探索體驗，同時維持與較舊模型及providers的相容性。遠端stdio MCP伺服器也接受以遠端平台路徑格式撰寫的絕對工作目錄（例如macOS用戶端傳送Windows風格路徑，反之亦然）。¹⁰⁵

v0.147.0 MCP變更（2026年8月7日）：Codex新增選擇啟用的MCP 2026-07-28協定修訂版支援——分頁探索（大型工具目錄會分頁串流傳送，而非以單一過大的清單傳送）、multi-round requests（伺服器可在一項邏輯請求中保留多步驟交換），以及non-blocking server startup；伺服器完成啟動前便會公開快取的MCP工具，因此緩慢的伺服器不再拖慢工作階段啟動。此功能採選擇啟用，因此使用較舊修訂版的伺服器仍可維持原樣運作。¹¹⁶

設定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工具可在無需experimental opt-in的情況下互動式要求驗證——若伺服器在工作階段中需要驗證，會透過一般流程提示，而非在您先以codex mcp login完成預先驗證前失敗。¹⁰⁷

Plugin MCP載入功能（v0.123.0+）同時接受標準mcpServersschema與.mcp.json中的頂層伺服器對應，因此依任一慣例撰寫的plugins都能順利載入。⁸⁴

將Codex作為MCP伺服器執行

Codex可將自身公開為MCP伺服器，以進行multi-agent orchestration：¹²

codex mcp-server                        # Start as MCP server (stdio transport)

該伺服器提供兩項工具： 1. codex()：以prompt、sandbox、model與approval參數啟動新的工作階段 2. codex-reply()：以threadId與prompt延續既有工作階段

搭配Agents SDK（Python）使用：

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

async with MCPServerStdio(
    name="Codex CLI",
    params={"command": "npx", "args": ["-y", "codex", "mcp-server"]},
    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與您的framework文件搭配使用，讓Codex始終擁有最新的API參考資料：

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

模式2：輸出限制——MCP工具回應預設會在約25K個字元處截斷。對於傳回大型payload的工具（資料庫查詢、日誌擷取），請使用enabled_tools限制為特定工具，讓回應保持聚焦。

模式2a：多模態工具輸出（v0.107.0）——自訂工具現在可在文字之外傳回多模態輸出（圖片、rich content）。這讓能產生視覺成品的工具——螢幕截圖、圖表、圖表轉譯結果——可直接將其交給模型分析。⁶²

模式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中identity的伺服器都會在啟動時遭到封鎖。完整政策設定請參閱Enterprise Deployment。

Code Mode [EXPERIMENTAL]

Code mode（v0.114.0）透過將agent的範圍限制於以程式碼為核心的操作，提供更為隔離的程式開發工作流程。⁷⁰啟用後，agent會專注於讀取、撰寫及測試程式碼，而不進行更廣泛的系統互動。

自v0.139.0起，code mode可直接呼叫standalone web search——包括從巢狀JavaScript工具呼叫中——並接收純文字結果，因此code-mode流程可在不離開sandboxed coding context的情況下取得即時資訊。¹²²v0.146.0將standalone web search延伸至相容的自訂model providers，因此此能力不再僅限於OpenAI代管模型。¹¹⁴

v0.146.0讓app-server可透過WebSocket連接至遠端Code Mode hosts，因此code-mode runtime不再必須與用戶端位於同一部機器。¹¹⁴

此功能仍屬experimental。請查看release notes以掌握更新。

JavaScript REPL Runtime [REMOVED]

Codex v0.100.0新增experimental JavaScript REPL runtime（js_repl），並在v0.106.0透過/experimental介面將其推廣。⁶⁰該指引如今僅具歷史意義。在v0.128.0中，release changelog包含「Remove js_repl feature」，而目前的功能清單將js_repl與js_repl_tools_only都標示為已移除。⁸⁶

請勿在新的設定中加入features.js_repl = true。如需可重複執行的邏輯，請使用shell commands、checked-in scripts、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與app connectors整合為單一可安裝套件（v0.110.0+）。⁶⁵ 自v0.117.0起，plugins成為一級功能：產品範圍的plugins會在啟動時自動同步，而/plugins提供可在TUI中探索與管理的瀏覽器。⁷⁵ v0.128.0透過marketplace安裝、遠端套件快取、遠端解除安裝API、plugin隨附hooks、hook啟用狀態，以及外部agent設定匯入，擴充了plugin工作流程。⁸⁶ v0.129.0（2026年5月7日）新增plugin workspace分享（可將一組plugin推送給團隊成員，無須重新發布）、分享存取控制（可針對各收件者啟用／停用與撤銷）、來源篩選（限制workspace可擷取的marketplace），以及可直接從/plugins瀏覽器呼叫、無須透過CLI的marketplace操作。⁸⁹ v0.133.0（2026年5月21日）讓plugin探索更容易稽核：清單輸出可辨識marketplace、可查看已安裝版本、會列出marketplace根目錄，並可顯示遠端plugin集合，不必猜測結果來自哪個registry。⁹⁸ v0.130.0（2026年5月8日）讓plugin封裝更透明，也讓分享工作流程更容易掌控：⁹¹

• 在plugin詳細資料中顯示隨附hooks。/plugins詳細檢視現在會列出plugin隨附的每個生命週期hook（SessionStart、UserPromptSubmit、Stop等）。安裝plugin前，即可確切知道它會對您的session註冊哪些hooks——不再因為只信任plugin的tools，而遭遇意料之外的hook副作用。
• shareContext中的plugin分享中繼資料。從workspace分享plugin時，分享連結payload現在會公開連結中繼資料（建立者、範圍、新鮮度），讓接收端session可顯示來源資訊並決定是否接受。
• 分享設定中的可探索性控制。分享設定提供可探索性切換功能，讓團隊可將plugins發布至特定workspaces或收件者清單，而無須讓它們在組織內普遍可列出。

v0.143.0（2026年7月8日）預設啟用遠端plugins。遠端plugins現在不需要opt-in旗標即可啟用，/plugins目錄加入更豐富的列項（npm marketplace來源可與git及本機來源並列），每個項目同時顯示遠端與本機安裝版本，版本差異一目了然。¹⁰⁶ 對於要將團隊標準化為共用plugin集合的團隊而言，遠端預設啟用移除了過去會阻礙推行的逐台機器啟用步驟。

Plugin來源

自v0.147.0起，plugin搜尋可透過一次查詢涵蓋本機、個人、workspace與遠端目錄——搜尋的是功能，而不是恰好存放該功能的目錄。搭配可攜式Agent Plugin套件，在一個環境建置的plugin可在另一個環境順利安裝，不再綁定其撰寫所在的機器或workspace。¹¹⁶

Plugin探索

Codex會在session啟動時告知model哪些plugins已啟用（v0.111.0），改善已安裝MCP、apps與skills的探索體驗。⁶⁵ model可根據任務情境，在session進行期間建議相關plugins。v0.117.0會在啟動時同步產品範圍的plugins，確保無須手動介入即可使用最新plugin目錄。⁷⁵ 自v0.142.0起，/plugins選單將遠端plugins整理為OpenAI Curated、Workspace與Shared with me區段，且符合資格的turn可內嵌推薦並安裝相關plugins。¹⁰⁴

@plugin提及（v0.112.0+）

可在聊天中透過@plugin-name直接參照任何已安裝plugin。⁶⁸ 提及plugin時，其情境資訊（capabilities、tools、configuration）會自動納入model的context window——無須說明plugin的功能。

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

這適用於任何已安裝plugin，包括自訂skills、MCP servers與app connectors。

Plugin Marketplace（v0.113.0+）

plugin marketplace現在提供更豐富的探索功能，包括中繼資料、分類與評分。⁶⁹ 安裝期間的auth檢查會驗證需要API keys或OAuth的plugins，在安裝前是否具有有效credentials。解除安裝端點會完整移除plugins及其相關configuration。

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

目前OpenAI Codex文件將marketplace來源管理置於codex plugin marketplace之下。這使第三方plugin發行正式化，超越OpenAI第一方marketplace，並支援GitHub repo簡寫、HTTP(S) Git URLs、SSH URLs，以及本機marketplace根目錄；使用--ref釘選Git ref，並僅針對Git支援的marketplace repos重複使用--sparse PATH。⁹³

# 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一同出現在/plugins瀏覽器中。App-server呼叫端（IDE／desktop integrations）也有對應端點，可透過程式註冊marketplaces。⁸²

安全性考量：第三方marketplaces會以您的Codex權限執行任意plugin程式碼。新增前請審查來源，並建議在首次執行時採用sandboxed execution。

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

「Agent Plugins」不只是Codex功能名稱——它是一項開放、供應商中立的封裝標準，於2026年8月6日發布Agent Plugins 1.0.0；官方網站將其概述為「用於可重複使用元件的可攜式套件格式，可擴充AI agents」。¹¹⁸ plugin是一個目錄，包含必要的plugin.jsonmanifest（封閉schema，頂層僅允許十個欄位——$schema、name、version、description、author、homepage、repository、license、keywords、extensions——其中規定「Clients MUST report and ignore each unknown field」）、可選的skills/資料夾（每個含有SKILL.md的直接子目錄即為一個skill）、可選的mcp.json（宣告stdio、Streamable HTTP或舊版HTTP+SSE伺服器），以及可選的反向網域client-namespace目錄，其他clients「MUST ignore」。其規範範圍在於封裝：spec「defines the canonical Agent Plugins Specification v1.0.0 for packaging reusable components that extend AI agents into distributable plugins」——底層的Agent Skills與MCP仍各自遵循其規格。¹¹⁸

治理架構才是重點。Vercel發起提案，並與Amazon、Anysphere（Cursor）、GitHub、Microsoft及OpenAI共同制定1.0規格；spec repository的維護者名單涵蓋Amazon、Cursor、Microsoft、OpenAI與Vercel，而Google在發布當日宣布加入核心維護者。¹¹⁸ 已具名的發布clients涵蓋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 manifests、workspace plugin publishing，以及另外兩個plugin marketplaces——Amazon Bedrock與Claude Code¹¹⁴——而v0.147.0則以可攜式Agent Plugins安裝與跨本機、個人、workspace、遠端目錄的搜尋完成整個流程。¹¹⁶ 對團隊而言，workspace publishing是營運上更實用的一半：將plugins發布至自己的workspace，而非架設公開marketplace，或要求每位developer手動新增Git來源。

發行說明公布了Codex介面，但未發布其configuration keys或CLI語法。本條目記錄此功能已推出及該標準的規定，而非說明如何從Codex操作——在OpenAI文件涵蓋之前，請將manifest撰寫工作流程與任何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

在TUI中，使用/plugins（v0.117.0+）即可互動式瀏覽、安裝與移除個別plugins，無須離開目前session。⁷⁵

專家提示：Plugins整合了過去需要分別設定的MCP config、skill安裝與app connector設定。單一plugin可同時包含三者——加快團隊onboarding，並提高configuration的可攜性。

Plan Mode 與協作

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

進入 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 對話。¹¹²

其他改進： - 即使長連結因跨越 TUI 行而換行，現在仍可點選（v0.105.0）⁶¹ - 本機檔案連結的呈現格式有所改善（v0.106.0）⁶⁰ - TUI markdown 透過 OSC 8 中繼資料讓網頁連結保持可點選；空間不足的表格則會改以易讀的鍵值記錄呈現，同時保留連結目標（v0.136.0）¹²⁵ - 修正 sub-agents 的 Ctrl+C 處理機制，現在能正確終止子程序（v0.106.0）⁶⁰

記憶系統

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

記憶指令

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

適合儲存的內容

記憶最適合用來保存長期偏好與專案事實：

• 專案慣例：「此專案使用定位字元，不使用空格」，或「API 回應一律包含 meta 欄位」
• 工具偏好：「使用 pnpm，不要使用 npm」，或「使用 pytest -x --tb=short 執行測試」
• 架構決策：「驗證模組位於 src/core/auth/，而非 src/middleware/」
• 工作流程偏好：「向我顯示差異前，一律先執行 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 的逐字記錄提煉為可長期保存的事實；此次模型變更可在相同 token 成本下提升回想品質。⁸²
• TUI 記憶選單（v0.121.0）：新的工作階段內 UI 提供記憶模式、個別記憶刪除及重設按鈕。重設記憶現在會保留過去的執行記錄，而非使其失效。因此，重設會清除未來可回想的內容，同時不影響工作階段重播。⁸²

記憶與 AGENTS.md 的比較

提示：對於應無限期保留的事實，請使用 /m_update。若是工作階段特有的背景資訊，直接在對話中告知 Codex 即可。團隊共享的背景資訊則應使用 AGENTS.md。

工作階段管理

Codex會將工作階段持續儲存在~/.codex/sessions/下，讓您可在CLI與桌面介面之間繼續工作、分支及進行多執行緒工作流程。

v0.146.0讓執行緒可定址。/new與/clear現在可接受工作階段名稱，重要執行緒可釘選，而側邊對話會保持開啟，不再需要關閉一個對話才能存取另一個。¹¹⁴實際效果是，長期進行的專案不再只是一串必須靠日期辨識的時間戳記。v0.147.0新增對話區段：對話可整理為持續存在、可手動排序的區段，且長篇逐字稿會以漸進方式瀏覽，而非一次載入全部內容。¹¹⁶

繼續工作

從上次中斷處接續：

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內的/resumeslash command會開啟相同且支援搜尋的互動式選擇器。

分頁執行緒歷程（v0.145.0）[EXPERIMENTAL]：實驗性的分頁執行緒歷程為工作階段管理帶來高效率的繼續工作、跨歷程搜尋、持續儲存的執行緒名稱、sub-agent支援與記憶功能——歷程會逐頁載入，而非一次全部載入；對於擁有數百個工作階段的長期工作目錄而言尤其重要。此功能仍屬實驗性質：各版本之間的介面可能會變動。¹¹²

分支

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

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

分支會建立彼此獨立的執行緒，並共享截至分支點為止的相同歷程。自v0.146.0起，分支歷程採用分頁方式，且可建立為暫時性分支——暫時性分支不會出現在執行緒清單中，能讓一次性的實驗不干擾您實際瀏覽的執行緒清單。¹¹⁴其中一個分支的變更不會影響另一個。這適合用於比較不同做法（例如「分支後嘗試以Redis取代Memcached」），或安全地探索高風險變更。

將執行緒分支為sub-agent（v0.107.0）：現在可將執行緒分支為獨立的sub-agent，使對話能產生可自主執行的平行工作流。這延伸了既有的分支模型——不只是分支對話，分支出的執行緒還會成為擁有自身執行環境的sub-agent。⁶²自v0.117.0起，sub-agent使用路徑式位址（例如/root/agent_a）與結構化的agent間訊息傳遞，使多agent協作更明確且更易於偵錯。⁷⁵

加密的agent間訊息（v0.138.0+）：Multi-agentv2現在會加密父agent在產生或傳訊給sub-agent時所傳送的任務文字。spawn_agent、send_message與followup_task的訊息參數會標示為已加密：當父模型發出工具呼叫時，Responses API會加密承載資料；本機執行的Codex只會處理密文（InterAgentCommunication.encrypted_content，純文字內容為空）；而API在將內容交給接收模型時，會於伺服器端解密。¹⁰⁸這有3項實務影響：

• 您的本機工作階段日誌不再包含委派內容的純文字。您仍可看見父agent產生了sub-agent及其回傳結果，但無法看見傳送的確切指示。若您從工作階段歷程稽核或偵錯multi-agent執行，該紀錄已不存在；截至2026年7月中旬，追蹤此問題的公開回歸issue尚未連結修正方案。¹⁰⁹Extension生命週期事件（subagent啟動／停止、工具執行、回合中繼資料——v0.133.0+）與app-server可觀測性，是重建執行過程的其餘切入點。⁹⁸
• 自訂provider模型可能失敗。未設定加密工具使用的模型端點，會以400拒絕加密的spawn_agentschema（"declares encrypted parameters but is not configured for encrypted tool use"）。若custom provider上的multi-agent委派因該錯誤而失敗，原因是加密變更，而非您的設定。¹⁰⁹
• Codex產生的通知仍可讀取。子工作完成通知由Codex本身產生，因此仍為純文字，且現在會呈現為具型別的agent_message項目，而非序列化的JSONenvelopes。¹⁰⁸

OpenAI尚未公開說明這項變更背後的威脅模型；PR描述了密文流程，但未說明其防護目標。

Multi-agentv2已穩定（v0.145.0，選擇加入）：在v0.137.0首次推出、並於v0.138.0加入加密委派的multi-agentv2體驗，現在已穩定為選擇加入功能。v0.145.0新增可設定的sub-agent模型、各sub-agent的推理層級、可設定的並行數、恢復的multi-agent角色，以及改善後的agent導覽。若您在v0.137／v0.138的調整期暫緩使用v2，這個版本便是設定介面趨於穩定的版本——sub-agent模型與推理選項現在位於config中，而非由runtime固定。¹¹²

執行緒清單

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

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

在桌面app中，執行緒會顯示於側邊欄，並提供完整歷程與diff預覽。

工作階段生命週期

工作階段會在CLI與桌面app之間同步——可在其中一端開始，並於另一端繼續。

非互動模式（codex exec）

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

基本用法

codex exec "summarize the repository structure"
codex exec --sandbox workspace-write --ask-for-approval on-request "fix the CI failure"
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.

若您正在建構需要列舉大量執行緒歷史記錄，且不希望一次將每個回合全部載入記憶體的UI，請搭配使用codex remote-control與下方的app-server分頁API。

App-Server執行緒分頁（v0.130.0以上版本）

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

搭配v0.121.0導入的ThreadStore介面使用分頁功能，即可有效率地瀏覽長時間執行的執行緒。這尤其適用於遠端控制部署，因為協調器可能與rollout檔案位於不同機器。⁸² v0.143.0擴充了控制器可檢查的內容：app-server用戶端現在可以列舉可用環境、列出執行緒的後代執行緒，並從特定回合建立歷史分支。UI可運用這些基礎功能，從較早的時間點建立執行分支，而不必重新向前執行。¹⁰⁶

即時App-Server設定重新整理（v0.130.0以上版本）

即時app-server執行緒現在無須重新啟動，即可套用config.toml的變更。編輯設定並儲存後，執行中的執行緒會在下一個回合反映新值。這是codex remote-control的配套錯誤修正：長時間執行的無頭伺服器現在可直接重新設定，不必先關閉。⁹¹

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

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

Codex Cloud與背景任務[EXPERIMENTAL]

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

Codex Cloud會在OpenAI管理的環境中以非同步方式執行任務。⁴ 若要將Codex整合至CI管線，另請參閱GitHub Action與CI/CD。

運作方式

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. 至少已設定1個雲端環境 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 沙箱。⁶⁶

安裝

codex app                      # Auto-downloads and installs on first run

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

主要功能

Appshots、瀏覽器註解與 Computer Use

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

進行網頁與前端工作時，若頁面無須登入，請優先使用應用程式內瀏覽器：它讓您與 Codex 共用實際呈現的預覽畫面，支援點擊、螢幕截圖、下載素材及透過 JavaScript 進行唯讀檢查等瀏覽器操作，也能讓您在頁面區域加上註解，交由 Codex 在下一回合處理。⁹⁹ 對於已登入的網站，請繼續使用 Chrome 擴充功能。

只有在結構化整合或瀏覽器預覽無法驗證任務時，才使用 Computer Use。它能檢查及操作獲准的 Mac 應用程式，但進行檔案編輯與 shell 命令時，仍須遵循 Codex 的核准機制與沙箱規則。鎖定後使用的範圍相當嚴格：Mac 鎖定後，Codex 僅能在進行中的可信任 Computer Use 回合期間暫時存取獲准的應用程式，並設有重新鎖定防護措施與本機輸入偵測。⁹⁹

執行緒模式

每個執行緒都會以3種模式之一執行，您可在建立時選擇：

Worktree 隔離機制：

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

這表示多個 Worktree 執行緒可同時在同一個儲存庫上執行而不會發生衝突。每個執行緒都有自己的分支與工作目錄。

自動化

自動化會在應用程式內於本機執行，因此應用程式必須保持開啟，且專案須可從磁碟存取：

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

設定自動化： 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 沙箱，且完整提供 skills、自動化及 worktrees 等功能，無須使用 WSL。⁶⁶

GitHub Action 與 CI/CD

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

基本用法

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

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

設定選項

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

安全性策略

存取控制

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

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

Codex SDK

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

安裝

npm install @openai/codex-sdk

基本用法

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

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

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

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

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

進階SDK功能

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

Thread與Client設定

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

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

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

執行階段：Node.js 18+。

效能最佳化

Context管理

Context視窗會因模型而異。目前的GPT-5.6系列（Sol、Terra、Luna）採用272K視窗；前一代旗艦GPT-5.5在Codex提供400K（在API中為1M）；GPT-5.4／GPT-5.4-mini（將於2026年8月31日自Codex退役）提供1M／400K；舊版GPT-5.3-Codex系列採用272K輸入＋128K輸出（總預算400K）。它們填滿的速度比您想像中更快，因此應主動管理：

1. 定期使用/compact：摘要化對話歷程以釋放token
2. 提供本機文件：高品質的AGENTS.md與本機文件可降低探索負擔（會消耗context）
3. 使用@附加特定檔案：直接參照檔案，而非要求Codex尋找它們
4. 讓提示保持聚焦：具明確範圍及指定檔案的提示，比開放式探索消耗更少context

Token效率

速度最佳化

1. gpt-5.3-codex-spark：適合互動式結對作業的低延遲變體
2. --profile fast：預先設定為低推理的gpt-5.6-luna
3. 平行Tool執行：Codex會並行執行獨立的讀取／檢查，因此請設計提示以啟用此能力
4. 以成果為導向的迴圈：要求「實作、測試、修正，通過後停止」，而非提供逐步指示

如何偵錯問題？

常見問題與解決方式

錯誤訊息參考

codex doctor的作用是什麼？

codex doctor是在回報bug或偵錯損毀的安裝前，應先執行的單一指令。它會將本機執行階段、設定、驗證、terminal、網路及狀態 彙整為一份報告；專案本身的issue template也會要求您貼上其輸出內容。¹²⁰

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

這份報告會依穩定的區段組織，因此可快速瀏覽需要的部分：¹²⁰

每項檢查都帶有狀態標記——✓正常、✗失敗、⚠警告、○閒置——以及一行摘要。 --json會以穩定識別碼為每項檢查建立key，因此除了目視檢查外，也可用於CI或 support script。¹²⁰

此指令隨版本持續擴充：它於v0.131.0推出，於v0.135.0新增environment、Git、 terminal、app-server及thread-inventory報告，並於v0.139.0新增editor與pager 詳細資料（JSON中的敏感值會經過遮蔽）。^96126122

請優先使用，而非最後才使用。大多數「Codex壞掉了」的回報，最後都可歸因於doctor 已指出的問題：過期的驗證mode、無法剖析的config.toml，或另一個安裝版本遮蔽了 您PATH中的版本。

診斷工具

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

Session內TUI診斷：

/status                                # Token/session overview
/config                                # Inspect effective config values and sources
/compact                               # Summarize history to reclaim context

注意：codex --verbose不是有效的頂層flag。請使用上述debug subcommands與TUI診斷。

乾淨重新安裝

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

會保留~/.codex/（auth、config、sessions）。若要固定為特定版本、在不良版本釋出後降級， 或完整清除狀態，請參閱 更新、降級或解除安裝Codex CLI。

Debug Mode

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

回報問題

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

或在github.com/openai/codex/issues提交issue。¹

Codex Security[PREVIEW]

Codex Security於2026年3月6日進入research preview，將具備Context感知能力的應用程式安全性審查帶入Codex stack。⁷⁷ChatGPT Pro、Enterprise、Business及Edu客戶可透過Codex web使用。

運作方式：Codex Security會分析repositories以建立專案專屬的threat model，依據真實世界影響識別分類後的vulnerabilities，並在Sandboxed環境中對發現結果進行壓力測試以驗證它們。此agent會呈現信心較高、附帶修正方法的發現結果，減少不重要bug造成的雜訊。

效能：在research preview期間，Codex Security掃描了120萬筆commits，並找出10,561個high-severity vulnerabilities。準確度隨時間提升——雜訊減少84%、過度回報的嚴重性降低90%以上，false positive rate也減半。系統已在OpenSSH、GnuTLS與Chromium中發現真實vulnerabilities，並已分配14個CVE。⁷⁷

注意：Codex Security與CLI內建的Sandbox security model相互獨立。Sandbox會保護您的機器免於Codex影響；Codex Security則保護您的codebase免受vulnerabilities侵害。

企業部署

管理員控制項（requirements.toml）

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

v0.146.0新增企業方案辨識功能，以及管理員對應用程式內更新的控制權。¹¹⁴ 在受管理的裝置群中，這決定了開發人員是否能在注意到新版本時自行更新 CLI，或由管理員決定版本的推出時機。發行說明公布了這項控制功能，但未公開其 requirements.toml 金鑰——在OpenAI完成文件化之前，應將確切的設定名稱視為尚未驗證。

# /etc/codex/requirements.toml

# Restrict which approval policies users can select
allowed_approval_policies = ["untrusted", "on-request", "never"]

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

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

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

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

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

與用於設定偏好的使用者層級 config.toml 不同，requirements.toml 是硬性限制層，可限制使用者能選擇的值，且使用者無法覆寫。管理員需求規則只能提示或禁止（絕不會靜默允許）。

macOS MDM 設定

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

優先順序（由高至低）：

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

雲端需求設定只會填入尚未設定的需求欄位，因此優先順序較高的受管理層一律優先。雲端需求設定採盡力而為；若擷取失敗或逾時，Codex會在沒有雲端層的情況下繼續執行。

OpenTelemetry 整合

Codex支援將標準OTel環境變數中的OpenTelemetry追蹤內容脈絡傳播至OpenAI API 呼叫。請在啟動Codex前設定標準環境變數：

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

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

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

企業存取

• ChatGPT Business / Enterprise / Edu：由組織管理員控管存取權，並自動套用雲端擷取的需求設定。透過您的身分識別提供者（Okta、Entra ID等）支援SAML/OIDC SSO
• API：標準 API 驗證、計費及組織／專案控制。OpenAI發布SOC 2 Type II與SOC 3報告；Enterprise級別提供HIPAA BAA
• Codex SDK：嵌入內部工具與工作流程
• 大規模政策強制執行：使用由MDM散發的 requirements_toml_base64，或檔案系統層級的 /etc/codex/requirements.toml

資料處理與合規： - 根據OpenAI的Business/Enterprise/API 條款，API 輸入／輸出不會用於訓練 - 就資料落地而言，OpenAI API 流量預設會經由位於美國的基礎架構路由；如有EU資料落地需求，請洽詢OpenAI Enterprise銷售團隊 - 工作階段文字記錄會儲存在本機；只有 API 呼叫會離開裝置 - ChatGPT Enterprise支援包括SOC 2、GDPR與CCPA在內的合規框架

推出策略

建議組織採用分階段推出：

1. 試行（第1至2週）：向3至5位資深工程師部署，並以 requirements.toml 強制使用 untrusted sandbox模式與 cached 網頁搜尋。蒐集關於AGENTS.md模式及 MCP 伺服器需求的意見回饋。
2. 團隊擴大（第3至4週）：推廣至整個團隊。透過MDM或repo散發團隊標準 config.toml。針對受信任的儲存庫啟用 workspace-write sandbox。
3. CI整合（第5至6週）：將 codex-action 新增至CI/CD管線，用於自動化PR審查與測試產生。使用 --ephemeral 讓成本維持可預測。
4. 全組織部署（第2個月起）：透過MDM部署，並以 requirements.toml 強制執行已核准的 MCP 伺服器、sandbox政策及模型允許清單。

稽核模式

追蹤Codex使用情況並強制執行合規要求：

• OpenTelemetry追蹤：依團隊監控 API 呼叫量、token使用量及延遲
• 工作階段持續保存：稽核 ~/.codex/sessions/ 以進行合規審查（在敏感情境中使用 --ephemeral 停用）
• MCP 身分識別強制執行：requirements.toml 會記錄遭封鎖的伺服器嘗試——檢視是否有未經授權的工具使用情形
• Git稽核軌跡：所有Codex檔案變更皆會經過標準git——透過分支歷程與PR差異檢視

最佳實務與反模式

提示模式

1. 以限制為導向的提示：先說明邊界。「不要變更 API 合約。僅重構內部實作。」
2. 結構化重現步驟：編號步驟比模糊描述更能產生有效的錯誤修正
3. 驗證要求：結尾加上「執行 lint 與最小的相關測試套件。回報指令與結果。」
4. 檔案參照：使用 @filename 將特定檔案附加至內容脈絡
5. 以成果為導向的迴圈：「實作、執行測試、修正失敗項目，僅在所有測試通過時停止。」Codex會持續迭代直到完成

測試理念

社群逐漸形成以測試驅動的AI協作共識：²²

• 預先定義測試，作為完成訊號
• 讓Codex持續迭代至測試通過（紅燈→綠燈→重構）
• 採用Tiger Style程式設計模式
• 要求修補程式時，提供精確的檔案文字。Codex採用嚴格比對，而非模糊的AST式修補

內容脈絡管理最佳實務

• 提供高品質的本機文件，而非依賴網路搜尋
• 維護具目錄與進度檔案的結構化Markdown（「漸進式揭露」）
• 在追蹤的檔案間統一行結尾（LF與CRLF），以避免修補失敗
• 保持AGENTS.md精簡，因為過長的指示會被擠出內容脈絡

Git工作流程

• 在不熟悉的儲存庫中執行Codex前，務必先建立新分支
• 使用以修補為基礎的工作流程（git diff／git apply），而非直接編輯
• 如同審查程式碼PR般檢閱Codex的建議
• 提交前使用/diff驗證變更

社群skills與提示

feiskyer/codex-settings儲存庫提供由社群維護的設定：²³

可重複使用的提示（位於~/.codex/prompts/）： - deep-reflector：從開發工作階段萃取學習成果 - github-issue-fixer [issue-number]：系統化錯誤分析與PR建立 - github-pr-reviewer [pr-number]：程式碼審查工作流程 - ui-engineer [requirements]：正式環境等級的前端開發

社群skills： - claude-skill：以權限模式將工作交接給Claude Code - autonomous-skill：具備進度追蹤的多工作階段任務自動化 - deep-research：平行子任務編排 - kiro-skill：需求→設計→任務→執行流程

反模式

常見錯誤會浪費token、產生不佳結果，或造成令人挫折的工作流程。

成本反模式

內容脈絡反模式

工作流程反模式

提示反模式

工作流程範例

常見開發情境的端對端模式。

範例1：新專案設定

mkdir my-app && cd my-app && git init
codex

> Create a FastAPI project with: main.py, requirements.txt, Dockerfile,
  basic health endpoint, and a README. Use async throughout.

> /init

檢閱產生的AGENTS.md，編輯使其符合您的慣例，然後：

> Run the health endpoint test and confirm it passes

範例2：日常開發流程

cd ~/project && git checkout -b feature/user-auth
codex

> @src/models/user.py @src/api/auth.py
  Add password reset functionality. Requirements:
  1. POST /api/auth/reset-request (email → sends token)
  2. POST /api/auth/reset-confirm (token + new password)
  3. Tests for both endpoints
  Run tests when done.

使用/diff檢閱後，再提交。

範例3：使用Plan Mode進行複雜重構

codex

> /plan Migrate the database layer from raw SQL to SQLAlchemy ORM.
  Constraints: don't change any API contracts, keep all existing tests passing.

檢閱計畫。核准或引導：

[Tab] Also add a migration script using Alembic

Codex執行後，進行驗證：

> Run the full test suite and report results
> /diff

範例4：使用codex exec進行PR審查

codex exec --model gpt-5.6-luna \
  "Review the changes in this branch against main. \
   Flag security issues, missed edge cases, and style violations. \
   Format as a markdown checklist." \
  -o review.md

範例5：使用Cloud Tasks除錯[EXPERIMENTAL]

codex cloud exec --env my-env "Diagnose why the /api/orders endpoint returns 500 \
  for orders with > 100 line items. Check the serializer, database query, \
  and pagination logic. Propose a fix with tests."

稍後檢查進度：

codex cloud status <TASK_ID>
codex cloud diff <TASK_ID>

完成後，在本機套用修正：

codex apply <TASK_ID>

遷移指南

從 Claude Code

需要理解的主要差異：

• Sandbox 位於 OS 層級：Codex 使用 Seatbelt/Landlock，而非容器。限制會在核心層級運作，位於應用程式層之下。
• Hooks 正持續擴充：Codex 現在支援 5 種 hook 事件：SessionStart、Stop 與 UserPromptSubmit（v0.114.0–v0.116.0，實驗性功能），以及 AfterAgent（v0.99.0）和 AfterToolUse（v0.100.0）。此系統涵蓋工作階段生命週期、提示攔截與工具層級自動化；不過，Claude Code 的 12+ 種生命週期事件仍提供更廣泛的涵蓋範圍。對於尚未涵蓋的自動化模式，請使用 AGENTS.md 指示或 skills。
• 子代理 v2（v0.117.0）：子代理現在使用路徑式位址（例如 /root/agent_a），並具備結構化的代理間訊息傳遞與代理列舉功能。⁷⁵這擴充了既有機制（最多 6 個並行代理，於 v0.91.0 從 12 個下修）。多代理角色仍可透過設定自訂（v0.104.0+）。⁴⁷v0.105.0 新增 spawn_agents_on_csv，可跨列扇出執行，並提供進度追蹤與 ETA。⁶¹Codex 仍缺少 Claude Code 明確的 Task 工具 UX，無法讓使用者直接指派工作；請使用 cloud tasks 或 SDK orchestration 實作委派模式。
• AGENTS.md 可跨工具使用：您的 AGENTS.md 可在 Cursor、Copilot、Amp、Jules、Gemini CLI 與 60,000+ 個開放原始碼專案中使用。CLAUDE.md 僅限 Claude 使用。
• Profiles 取代手動切換：與其每次執行都變更旗標，不如在 config.toml 中定義 profiles。

從 GitHub Copilot

您將獲得： - OS 層級的 sandboxing（Seatbelt/Landlock——由核心強制執行，而非以容器為基礎） - 可透過 codex apply 委派 cloud task - 可用於切換工作流程的 config profiles - 具備 worktree 隔離功能的桌面應用程式

從 Cursor

快速參考卡

╔═══════════════════════════════════════════════════════════════╗
║                    CODEX CLI QUICK REFERENCE                  ║
╠═══════════════════════════════════════════════════════════════╣
║                                                               ║
║  LAUNCH                                                       ║
║  codex                      Interactive TUI                   ║
║  codex "prompt"             TUI with initial prompt           ║
║  codex exec "prompt"        Non-interactive mode              ║
║  codex app                  Desktop app                       ║
║  codex resume               Resume previous session           ║
║  codex fork                 Fork a session                    ║
║                                                               ║
║  FLAGS                                                        ║
║  -m, --model <model>        Select model                      ║
║  -p, --profile <name>       Load config profile               ║
║  -s, --sandbox <mode>       Sandbox mode                      ║
║  -C, --cd <dir>             Working directory                 ║
║  -i, --image <file>         Attach image(s)                   ║
║  -c, --config <key=value>   Override config                   ║
║  --ask-for-approval <p>     Approval policy                   ║
║  --oss                      Use local models (Ollama)         ║
║  --search                   Enable live web search            ║
║                                                               ║
║  SLASH COMMANDS (in TUI)                                      ║
║  /compact      Free tokens   /diff        Git diff            ║
║  /review       Code review   /plan        Plan mode           ║
║  /model        Switch model  /status      Session info        ║
║  /fork         Fork thread   /goal        Persisted goal      ║
║  /vim          Modal Vim     /hooks       Browse/toggle hooks ║
║  /init         AGENTS.md scaffold                             ║
║  /mcp          MCP tools     /skills      Invoke skills       ║
║  /ps           Background    /personality Style               ║
║  /permissions  Approval mode /statusline  Footer config       ║
║  /fast         Toggle fast mode (default: on)                 ║
║  /copy         Copy last response to clipboard                ║
║  /clear        Clear screen  /theme       Syntax highlighting ║
║                                                               ║
║  TUI SHORTCUTS                                                ║
║  @              Fuzzy file search                             ║
║  !command       Run shell command                             ║
║  Ctrl+G         External editor                               ║
║  Ctrl+L         Clear screen                                  ║
║  Enter          Inject instructions (while running)           ║
║  Esc Esc        Edit previous messages                        ║
║                                                               ║
║  EXEC MODE (CI/CD)                                            ║
║  codex exec --sandbox workspace-write "task" Sandboxed auto   ║
║  codex exec --json -o out.txt "task"    JSON + file output    ║
║  codex exec --output-schema s.json      Structured output     ║
║  codex exec resume --last "continue"    Resume session        ║
║                                                               ║
║  MCP MANAGEMENT [EXPERIMENTAL]                                ║
║  codex mcp add <name> -- <cmd>    Add STDIO server            ║
║  codex mcp add <name> --url <u>   Add HTTP server             ║
║  codex mcp list                    List servers               ║
║  codex mcp login <name>           OAuth flow                  ║
║  codex mcp remove <name>          Delete server               ║
║                                                               ║
║  PLUGINS                                                      ║
║  codex plugin marketplace add <src>     Add marketplace       ║
║  codex plugin marketplace upgrade       Upgrade marketplaces  ║
║                                                               ║
║  CLOUD [EXPERIMENTAL]                                         ║
║  codex cloud exec --env <ID> Start cloud task                 ║
║  codex cloud status <ID>     Check task progress              ║
║  codex cloud diff <ID>       View task diff                   ║
║  codex cloud list            List tasks                       ║
║  codex apply <TASK_ID>       Apply cloud diff locally         ║
║                                                               ║
║  CONFIG FILES                                                 ║
║  ~/.codex/config.toml        User config                      ║
║  .codex/config.toml          Project config                   ║
║  ~/.codex/AGENTS.md          Global instructions              ║
║  AGENTS.md                   Project instructions             ║
║  requirements.toml           Enterprise policy constraints    ║
║                                                               ║
║  SANDBOX MODES                                                ║
║  read-only          Read files only, no mutations             ║
║  workspace-write    Read/write in workspace + /tmp            ║
║  danger-full-access Full machine access                       ║
║                                                               ║
║  APPROVAL POLICIES                                            ║
║  untrusted     Prompt for all mutations                       ║
║  on-request    Prompt for boundary violations                 ║
║  never         No prompts                                     ║
║                                                               ║
║  MODELS (Aug 2026)                                            ║
║  gpt-5.6-sol           Recommended default ("Power", 272K)    ║
║  gpt-5.6-terra         Everyday model (272K)                  ║
║  gpt-5.6-luna          Fast + affordable (272K)               ║
║  gpt-5.5               Previous-gen flagship (400K in Codex)  ║
║  gpt-5.4 / -mini       Retire from Codex Aug 31, 2026         ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

變更記錄