實戰手冊 / 18 GUIDES
十八篇指南，一套 terminal-first 系統。
主要軌道教你在真實 repository 操作 Codex；次要軌道保留給直接使用 OpenAI APIs/SDKs 的架構航圖。
Codex CLI 核心
Codex CLI 核心課程
依序完成安裝、權限、repository guidance、擴充、subagents 與 CI。
- 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 設定 / 16 分鐘 / Stable
依 scope 配置 Codex，不靠偶然
Codex 依序解析 CLI override、trusted project layers、selected profile、user config、system config、built-in defaults。Profile 是獨立檔案；current model availability 應即時檢查，不凍結成 evergreen advice。
- 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 與最小權限。
OpenAI Platform / API
OpenAI Platform / API 筆記
給直接使用 OpenAI APIs 與 SDKs 開發者的 companion architecture guidance。
- 13 閱讀指南↗
平台架構 / 9 分鐘 / Stable
把 Responses 當成系統邊界
Responses API 是 OpenAI 新專案建議的起點。不要把它當成文字生成薄包裝；把 message、tool call、tool result 與未來輸入型態保留成明確事件。
- 14 閱讀指南↗
平台架構 / 11 分鐘 / Stable
為每個工具建立窄契約
OpenAI tools 可以搜尋、檢索檔案、執行程式、透過 MCP 連線，或呼叫自訂函式。可靠性來自每個 action 周圍的邊界：小 schema、明確權限、idempotency 與模型可理解的結果。
- 15 閱讀指南↗
平台架構 / 8 分鐘 / Stable
把 Schema 當成使用者體驗
Structured Outputs 能讓回應遵守指定 JSON Schema，消除一類 parsing failure；但不代表值真實、有用、被授權或可以安全套用。
- 16 閱讀指南↗
平台架構 / 12 分鐘 / Stable
決定誰擁有 Agent Loop
Agent 會規劃、呼叫 tools、攜帶 state，也可能 handoff 給 specialist。關鍵不是 agent 數量，而是誰擁有 run loop、tool policy、state、approvals 與 trace。
- 17 閱讀指南↗
平台架構 / 10 分鐘 / Stable
把 Realtime 當成即時系統
Realtime sessions 用於低延遲 live interaction。Production voice 不只 streaming audio；還需要適合 client 的 transport、明確 session state、interruption behavior、tool latency budget 與 partial turn recovery。
- 18 閱讀指南↗
平台架構 / 9 分鐘 / Stable
把模型選擇留在系統邊緣
OpenAI model catalog 會持續改變。產品程式應要求測試過的 capability profile——quality、latency、modalities、tool support 與 budget——再由 configuration 與 evaluations 解析。