Codex 實戰使用手冊

繁體中文版本。本手冊根據 OpenAI 官方文件內與 Codex 使用相關的連結頁面重新編寫，並按實際任務流程整理。內容不是逐頁複製，而是加入可直接修改和使用的指令、設定、提示詞、審查及排錯範例。

Codex 任務流程：檢查、規劃、實作、驗證 — 適合程式碼庫任務重複使用的四階段工作流程。

1. 選擇合適的 Codex 使用介面

介面	適合工作	開始方式
ChatGPT 桌面應用程式	規劃、審閱修改、平行對話、瀏覽器測試、長時間任務	開啟專案或資料夾，再建立 Codex 對話
Codex CLI	終端機優先的程式碼工作、本機檢查及自動化	`codex`
IDE 擴充功能	利用已開啟檔案及選取範圍進行精準修改	在編輯器開啟 Codex 面板
Codex 雲端	在隔離的託管環境委派任務	連接程式碼庫並設定環境

2. 快速開始

開啟真正的程式碼庫，不要選擇過大的上層目錄。
先要求 Codex 檢查現況，再進行修改。
說明期望結果，以及完成時必須提供的驗證證據。
最後檢查差異並執行相關測試。

CLI 範例

# 安裝後進入專案並啟動
npm install -g @openai/codex
cd ~/projects/example-app
codex

# 常用互動指令
/init
/status
/permissions
/model
/review

3. 編寫可以完成的提示詞

穩定的任務說明應包含四部分：目標、相關背景、限制，以及可驗證的完成條件。路徑、錯誤日誌、螢幕截圖、重現步驟或失敗測試，都能減少誤解。

過於含糊

修正設定頁面。

可執行版本

目標：修正個人資料表格，讓已儲存的顯示名稱在重新載入後仍然保留。

背景：
- 介面：src/pages/Profile.tsx
- API：src/api/profile.ts
- 重現：儲存名稱後重新整理，舊名稱再次出現

限制：
- 保留現有 API 合約
- 不新增狀態管理套件
- 不覆蓋與本任務無關的修改

完成條件：
- 重現步驟不再失敗
- 相關測試通過
- 說明根本原因及已修改檔案

只要求規劃

檢查登入流程並提出簡短實作方案。現在不要修改檔案。
列出假設、風險、可能涉及的資料遷移，以及用來證明結果的測試。
等待我確認後才開始實作。

4. 採用「檢查 → 規劃 → 實作 → 驗證」

檢查：找出入口、既有慣例、測試及未提交修改。
規劃：把高風險或跨檔案工作拆成可驗證步驟。
實作：完成最小而完整的修改，同時保留其他人的工作。
驗證：執行針對性測試、查看真實畫面或輸出，並審閱差異。

先執行最小範圍的相關測試；通過後再執行較完整的測試套件。
介面修改必須開啟實際流程，檢查可見內容和互動，不可以只確認 HTTP 200。
若有測試無法執行，請說明原因。

5. 使用 AGENTS.md 保存程式碼庫規則

AGENTS.md 適合保存需要長期重複遵守的指引，例如建置及測試指令、目錄責任、格式要求和交付標準。內容應短小、具體並可執行；子目錄可用更具體的檔案覆蓋上層規則。

# 程式碼庫指引

## 指令
- 安裝：npm ci
- 單元測試：npm test
- 介面測試：npm run test:e2e
- 程式碼檢查：npm run lint

## 工作規則
- 保留要求範圍以外的使用者修改。
- 沿用 src/styles/tokens.css 的設計變數。
- 每個錯誤修正必須加入或更新回歸測試。
- 交付時列出修改檔案及實際執行過的指令。

6. 模型、批准與沙箱設定

Codex 只可在目前工作階段的權限範圍內讀取、編輯及執行指令。先採用能完成任務的最小權限；只有在安裝依賴、存取外部服務等具體需要下才擴大權限。

# .codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

批准要求範例

需要網絡存取以下載此專案鎖定的依賴套件。
允許指令：npm ci
範圍：只限此程式碼庫
完成後：執行單元測試並回報結果。

7. Skills、插件與 MCP

擴充方式	使用時機	典型內容
Skill	把工作流程變成可重用的專業能力	`SKILL.md`、參考資料、指令稿、素材
插件	把多項能力組合成可安裝套件	Skills、工具、指令、MCP、應用程式
MCP	需要獲授權的即時資料或外部操作	伺服器連線及工具定義

最小 Skill 範例

release-check/
└── SKILL.md

---
name: release-check
description: 部署前驗證網站版本。
---

# 版本檢查
1. 執行單元及整合測試。
2. 建立正式版本套件。
3. 用瀏覽器檢查主要使用流程。
4. 回報阻礙；未獲明確要求不得部署。

MCP 設定範例

[mcp_servers.docs]
command = "npx"
args = ["-y", "@example/docs-mcp"]

[mcp_servers.docs.env]
DOCS_SPACE = "engineering"

8. CLI 與非互動模式

一次性任務

codex exec "檢查失敗的結帳測試，修正最小根本原因，執行相關測試並總結差異。"

供 CI 讀取的輸出

codex exec --json \
  "審閱目前修改的正確性及保安風險；不要編輯檔案。" \
  > codex-review.jsonl

恢復最近工作階段

codex resume --last

自動化任務必須清楚指定工作目錄、允許動作、輸出格式及失敗處理；不要假設無人值守工作可取得廣泛權限。

9. IDE、桌面端、瀏覽器及雲端範例

IDE 精準修改

根據目前選取的函式和相關測試，移除重複網絡請求。
保留公開函式簽名；修改呼叫端之前先展示建議差異。

瀏覽器驗證

開啟本機管理頁面，以開發帳戶登入，再進入工具編輯器。
確認四張富文字卡片均已載入，並檢查標題、可編輯內容、圖片控制及主控台錯誤。
HTTP 200 並不足以證明頁面正確。

雲端委派

在隔離的雲端環境更新依賴並執行完整測試。
不要發佈或合併；交回修補內容、相容性說明及測試證據。

10. 把程式碼審閱視為獨立任務

審閱相對於 main 的修改。
優先檢查正確性、保安、資料遺失及回歸風險。
每項發現包括嚴重程度、檔案與行數、失敗情境及簡短修正方向。
若沒有發現問題，也要列出仍未覆蓋的測試風險。

11. Worktree、平行對話及長時間工作

Git worktree 讓每項平行工作擁有獨立的程式碼副本，同時共用 Git 中繼資料。兩項任務可能修改相同檔案或需要獨立分支時，應使用 worktree；若必須立即看見本機未提交修改，則使用本機對話。

Worktree A	Worktree B	本機目錄
升級 API 用戶端及測試	改善介面錯誤狀態	整合、處理衝突及執行端到端測試

目標：分三個檢查點遷移測試套件。
檢查點 1：盤點範圍及風險。
檢查點 2：遷移一個代表模組並驗證。
檢查點 3：完成其他模組並執行完整測試。
每個檢查點後回報進度和阻礙；不要部署。

12. 遠端與定時任務

遠端功能適合在離開原本電腦後延續工作；定時任務適合可重複、可觀察的週期性檢查。兩者都不會自動擴大授權。

每個工作日上午 09:00 檢查此程式碼庫的依賴警示。
產生簡短報告，包含套件、嚴重程度、受影響版本及建議行動。
不要安裝套件、建立拉取要求或向外部使用者發送訊息。

13. 排錯清單

確認目前專案及工作目錄。
查看畫面錯誤、終端機輸出及相關日誌。
執行 /status，檢查模型、批准及沙箱狀態。
分別驗證登入、帳戶／工作區權限與 API 金鑰。
插件或 MCP 故障時，檢查安裝、啟用、授權、設定、重新啟動要求及工作區政策。
介面卡住時檢查實際畫面和瀏覽器主控台，不可只看狀態碼。
先以最小任務重現，再考慮擴大權限或修改全域設定。

只進行診斷，不要修改檔案。
重現問題、記錄確實失敗步驟、檢查最接近日誌及設定，
並以證據指出最可能的根本原因。清楚分開已確認事實和假設。

14. 官方資料來源

本手冊使用了 OpenAI 官方的完整文件索引，並逐頁整理最佳實務、CLI、IDE、桌面應用程式、雲端、批准與保安、AGENTS.md、Skills、插件、MCP、程式碼審閱、Worktree、非互動模式、瀏覽器、定時任務及排錯等頁面。

編輯日期：2026 年 8 月 11 日。對版本敏感的指令、模型名稱、供應情況或政策，使用前應重新核對官方頁面。