實戰手冊 / 18 CLI + 06 ARCHIVE
十八堂 CLI 課，加上 API archive。
完整主要軌道教你在真實 repository 操作 Codex；獨立編號 archive 保留 API/SDK 架構航圖。
Codex CLI 核心
Codex CLI 完整課程
依序完成 01–18：從安裝與權限到 automation、Cloud、sandbox policy 與 diagnostics。
- 01 閱讀指南↗
基礎 / 10 分鐘 / Stable
安裝 Codex 並證明工具鏈正常
可靠的 Codex 工作流從第一個 prompt 之前就開始。使用官方 standalone installer，確認實際執行的 binary 與版本，刻意更新，並用內建診斷報告處理 config、auth、Git 或 terminal 問題，而不是猜測。
- 02 閱讀指南↗
基礎 / 11 分鐘 / Stable
選擇登入方式而不洩漏憑證
Codex 支援 ChatGPT subscription login 與依用量計費的 API-key login。安全做法是刻意選擇 flow、透過 stdin 傳入 secret、確認 active method，並把本機 auth storage 當成密碼。
- 03 閱讀指南↗
基礎 / 12 分鐘 / Stable
像工程師一樣執行第一次 terminal session
第一次有效 session 要在正確 repository、明確 permission mode 下開始，prompt 說明 goal、context、constraints 與 done condition。Codex 可以探索、修改與執行檢查，但任務邊界必須可觀察。
- 04 閱讀指南↗
安全 / 14 分鐘 / Stable
先設定權限，再給自主性
Codex security 是 OS-enforced sandbox 加 approval policy。workspace-write 搭配 on-request 是實用 local default，read-only 適合分析與規劃；web search 不會自動讓 spawned command 上網。
- 05 閱讀指南↗
工作流 / 13 分鐘 / Stable
控制長時間 CLI session
Codex CLI 同時提供 live work 的 keyboard-first controls，以及 persisted session 的 top-level lifecycle commands。Plan/status/diff/compact/review 控制當前工作；resume、fork、archive、unarchive 與永久 delete 則讓保存的工作狀態清楚可管。
- 06 閱讀指南↗
Repository 設定 / 15 分鐘 / Stable
用 AGENTS.md 保存 repository 知識
Codex 工作前會組成 instruction chain：global guidance，再由 repo root 走到 cwd。越近的 guidance 越晚出現並覆蓋廣泛規則；同一層 AGENTS.override.md 優先，combined project guidance 有預設 size limit。
- 07 閱讀指南↗
Repository 設定 / 22 分鐘 / Stable
依模型、effort 與 scope 規劃 Codex 工作
Model-aware planning 不只是選最大模型。先保留已掌握 repository 與對話內容的 CLI，依任務角色選模型，只使用該模型公告支援的 native effort，並把 subagent orchestration 與單一任務深度分開。Codex 設定仍依 scope 解析，而模型存取權會隨 release、account、登入方式、quota 與 rollout 漂移。
- 08 閱讀指南↗
工作流 / 14 分鐘 / Stable
把變更轉成可 review 的證據
Codex 能實作、跑 checks、顯示 working-tree diff 並啟動 dedicated reviewer。Review scope 互斥：uncommitted、base branch、commit 或 custom instructions；reviewer 回報 findings 而不修改 tree。
- 09 閱讀指南↗
擴充 / 16 分鐘 / Stable
透過 MCP 連接外部系統
Codex 支援 local STDIO 與 Streamable HTTP MCP。CLI、IDE extension、desktop app 共享 host config。可靠連線要先命名 transport、auth source、timeouts、required status、enabled tools 與 approval behavior。
- 10 閱讀指南↗
擴充 / 15 分鐘 / Stable
把重複工作封裝成 Skills
Skills 封裝 instructions、references、scripts 與 assets，Codex 選中後才載入完整內容。Plugins 透過已配置 marketplace 分發 skills 與可選 MCP；安裝前先列出並檢查 marketplace，再選明確 plugin。
- 11 閱讀指南↗
Guardrails / 17 分鐘 / Mixed: hooks stable; rules experimental
用 Hooks 與 Rules 加入 guardrails
Hooks 在 PreToolUse、PostToolUse、Stop、SessionStart 等 event 執行 trusted command handlers。Rules 決定 matching command prefix 在 sandbox 外 allow、prompt 或 forbidden。Hooks stable；rules experimental，最嚴格 matching decision 優先。
- 12 閱讀指南↗
自動化 / 19 分鐘 / Stable core; custom-agent authoring may evolve
從 Subagents 擴展到安全 Automation
Subagents 把 noisy exploration 移出 main thread，適合平行 independent read-heavy work。codex exec 預設 read-only，progress 到 stderr、final message 到 stdout；JSONL/schema 支援 machine consumer。GitHub Actions 應使用官方 action 與最小權限。
- 13 閱讀指南↗
自動化 / 12 分鐘 / Runtime-confirmed in Codex 0.147.0
用 codex exec 執行可重複的 headless 工作
codex exec 是 script 與 CI 的非互動入口。它可從 argument 或 stdin 讀取 prompt，沿用 repository guidance 與 sandbox 模型，回傳 process status，也能延續已保存的 exec session。可靠性不來自「自動化」三個字，而來自固定 working directory、明確權限、隔離 credential，以及不依賴對話語氣的驗證。
- 14 閱讀指南↗
自動化 / 11 分鐘 / Runtime-confirmed in Codex 0.147.0
串流 JSONL，並約束最終結果
codex exec --json 會把 newline-delimited JSON events 寫到 stdout；--output-schema 用 JSON Schema 約束最終 response，--output-last-message 則把最後訊息另存到指定檔案。事件串流用於 progress/diagnostics，最終 artifact 用於穩定 consumer contract；兩者都不能單獨證明 code change 正確。
- 15 閱讀指南↗
營運 / 10 分鐘 / Runtime-confirmed in Codex 0.147.0
Resume、fork、archive 與 restore Codex sessions
Codex 會保存 interactive 與 exec sessions。resume 延續 lineage；fork 建立分支；archive/unarchive 提供可逆整理；delete 則永久移除指定 session。安全的 continuation unit 是「精確 session + 相容 repository state」，而不是模糊的最近一次。
- 16 閱讀指南↗
Cloud 營運 / 12 分鐘 / Experimental Cloud surface; commands runtime-confirmed
套用前先審查 Codex Cloud tasks
Experimental cloud command 可向指定 environment 提交 task、列出或檢查狀態、顯示特定 attempt 的 unified diff，再把它套用到 local working tree。Apply 不等於 merge，也不證明 patch 適合目前 branch；接受前要確認 task、attempt、local status 與 tests。
- 17 閱讀指南↗
安全 / 13 分鐘 / Sandbox command stable; execpolicy is evolving
在 sandbox 測試命令並稽核 execpolicy
codex sandbox 會在 Codex 提供的 sandbox 中執行命令，可解析 permission profile、限制 readable roots/network，並在 macOS 記錄 denials。execpolicy check 會依 rule files 評估 argv 並解釋 decision。它們用來診斷 authority，不會讓危險 command 自動變安全，也不取代 OS enforcement。
- 18 閱讀指南↗
營運 / 10 分鐘 / Runtime-confirmed in Codex 0.147.0
診斷 Codex、檢視 features 並產生 completions
Codex 的 doctor 檢查 installation/runtime layers，features 顯示 feature stage/effective state，completion 產生 shell integration，debug utilities 則提供特定 evidence，例如 bundled model catalog。應先 read-only inspection，保留 version context，並在放進 ticket 或 startup file 前 review output。
OpenAI Platform / API
OpenAI Platform / API archive
不列入 CLI curriculum 的獨立 companion archive。
- A01 閱讀指南↗
平台架構 / 9 分鐘 / Stable
把 Responses 當成系統邊界
Responses API 是 OpenAI 新專案建議的起點。不要把它當成文字生成薄包裝；把 message、tool call、tool result 與未來輸入型態保留成明確事件。
- A02 閱讀指南↗
平台架構 / 11 分鐘 / Stable
為每個工具建立窄契約
OpenAI tools 可以搜尋、檢索檔案、執行程式、透過 MCP 連線，或呼叫自訂函式。可靠性來自每個 action 周圍的邊界：小 schema、明確權限、idempotency 與模型可理解的結果。
- A03 閱讀指南↗
平台架構 / 8 分鐘 / Stable
把 Schema 當成使用者體驗
Structured Outputs 能讓回應遵守指定 JSON Schema，消除一類 parsing failure；但不代表值真實、有用、被授權或可以安全套用。
- A04 閱讀指南↗
平台架構 / 12 分鐘 / Stable
決定誰擁有 Agent Loop
Agent 會規劃、呼叫 tools、攜帶 state，也可能 handoff 給 specialist。關鍵不是 agent 數量，而是誰擁有 run loop、tool policy、state、approvals 與 trace。
- A05 閱讀指南↗
平台架構 / 10 分鐘 / Stable
把 Realtime 當成即時系統
Realtime sessions 用於低延遲 live interaction。Production voice 不只 streaming audio；還需要適合 client 的 transport、明確 session state、interruption behavior、tool latency budget 與 partial turn recovery。
- A06 閱讀指南↗
平台架構 / 9 分鐘 / Stable
把模型選擇留在系統邊緣
OpenAI model catalog 會持續改變。產品程式應要求測試過的 capability profile——quality、latency、modalities、tool support 與 budget——再由 configuration 與 evaluations 解析。