Codex 入門指南：提升產出的最佳實踐

如果你剛開始接觸 @OpenAI Codex 或一般的程式碼 Agent，這份指南能幫助你更快獲得更好的成果。它涵蓋了讓 Codex 在 CLI、IDE 擴充功能和 Codex App 中更有效的核心習慣，從提示與規劃，到驗證、MCP、技能和自動化。

當你少把它當成一個一次性的助手，更像是把它當成一個可以隨著時間不斷調整和優化的隊友，Codex 的表現會最好。

一個有用的思考模型是：從正確的任務上下文開始，用 AGENTS.md 提供持久的指導，配置 Codex 以符合你的工作流程，用 MCP 連接外部系統，將重複的工作變成技能，並將穩定的工作流程自動化。

1. 透過清晰的上下文和提示，為 Codex 的第一次使用做好準備

即使你的提示並不完美，Codex 也已經足夠強大，能夠發揮作用。你通常可以直接交給它一個難題，無需太多設定，就能獲得強勁的結果。清晰的提示並非獲得價值的必要條件，但它確實能讓結果更可靠，特別是在較大的程式碼庫或高風險任務中。

如果你在一個龐大或複雜的儲存庫中工作，最大的解鎖關鍵通常是給 Codex 正確的任務上下文，以及一個清晰的結構來告訴它你想要做什麼。

一個好的預設做法是在你的提示中包含四項內容：

• 目標： 你想要改變或建置什麼？
• 上下文： 哪些檔案、資料夾、文件、範例或錯誤與此任務相關？你可以用 @ 提及特定檔案作為上下文。
• 限制條件： Codex 應該遵循哪些標準、架構、安全要求或慣例？
• 完成條件： 在任務完成前，應該滿足什麼條件，例如測試通過、行為改變或錯誤修復？

這有助於 Codex 保持範圍聚焦，減少假設，並產生更容易審查和驗證的成果。

根據任務的難度選擇推理程度，並測試哪種設定最適合你的工作流程。不同的使用者和任務會從不同的設定中受益。

• 低：適用於較快、範圍明確的任務
• 中或高：適用於更複雜的變更或除錯
• 極高：適用於長時間、自主性強、推理密集的任務

給新用戶的提示

：大多數人最快上手的方式是從一些基本的小勝利開始，例如向 Codex 詢問關於程式碼庫的問題，或使用它進行一個小範圍的修復。強烈建議在 Codex App 中使用語音輸入來加快迭代速度。

Codex 推理程度

2. 讓 Codex 先規劃，減少困難任務中的錯誤

如果任務複雜、模糊或難以清楚描述，請要求 Codex 在開始寫程式碼之前先進行規劃。

有幾種好的方法可以做到這點：

使用規劃模式： 對大多數使用者來說，這是最簡單且最有效的選擇。規劃模式讓 Codex 收集上下文、提出澄清問題，並在實作之前建立更完善的規劃。使用 /plan 或 Shift+Tab 切換。

要求 Codex 訪談你： 如果你對自己想要的東西有一個粗略的想法，但不確定如何清楚地描述它，可以要求 Codex 先向你提問。告訴它要挑戰你的假設，並將模糊的想法變成具體的東西，然後再寫程式碼。

使用 PLANS.md 模板： 對於更進階的工作流程，你可以配置 Codex 遵循 PLANS.md 或執行計畫模板，用於較長時間或多步驟的工作。更多細節，請參閱我們的執行計畫指南。

規劃模式

3. 使用 AGENTS.md 讓成功的指導原則可重複使用

一旦某個提示模式奏效，下一步就是不再手動重複它。這就是 AGENTS.md 的用武之地。

你可以把 AGENTS.md 想像成給 Agent 的 README。它是一個簡單、開放的格式，會自動載入到上下文中，也是編碼你和你的團隊希望 Codex 如何在儲存庫中工作的最佳位置。

一個好的 AGENTS.md 通常涵蓋：

• 儲存庫佈局和重要目錄
• 如何運行專案
• 建置、測試和 lint 命令
• 工程慣例和 PR 期望
• 限制條件和禁止規則
• 完成意味著什麼以及如何驗證工作

CLI 中的 /init 斜線命令是在當前目錄中快速建立初始 AGENTS.md 的快捷命令。它是一個很好的起點，但你應該編輯結果，以符合你的團隊實際建置、測試、審查和交付程式碼的方式。

你可以在多個層級建立 AGENTS.md 檔案：一個位於 ~/.codex 的全局 AGENTS.md 用於個人預設值，一個儲存庫層級的檔案用於共享標準，以及在子目錄中用於本地規則的更特定檔案。如果存在一個更接近你當前目錄的特定檔案，則該指導原則優先。

保持實用性。一個簡短而準確的 AGENTS.md 比一個充滿模糊規則的長檔案更有用。從基礎開始，只有在你注意到反覆出現的錯誤時才添加新規則。

如果 AGENTS.md 開始變得太大，請保持主檔案簡潔，並引用任務特定的 Markdown 檔案來處理規劃、程式碼審查或架構等事項。

提示

：當 Codex 犯同樣的錯誤兩次時，要求它進行回顧並更新 AGENTS.md。這樣指導原則就能保持實用性，並基於實際遇到的摩擦。

AGENTS.md 網站

4. 透過配置 Codex 以符合你的工作流程，獲得更一致的行為

配置是讓 Codex 在不同會話和介面上表現更一致的主要方法之一。例如，你可以設定模型選擇、推理程度、沙箱模式、批准策略、個人檔案和 MCP 設定的預設值。

一個好的起手模式是：

• 將個人預設值保留在 ~/.codex/config.toml（從 Codex App 的設定 → 配置 → 開啟 config.toml）
• 將儲存庫特定的行為保留在 .codex/config.toml
• 僅在一次性情況下使用命令列覆蓋（如果你使用 CLI）

Config.toml 是你定義持久偏好設定（例如 MCP 伺服器、個人檔案、多 Agent 設定和實驗性功能）的地方。你可以直接編輯它，或要求 Codex 為你更新它。

Codex 內建了作業層級的沙箱功能，並有兩個你可以控制的關鍵旋鈕。批准模式決定 Codex 何時需要你的許可才能執行命令，而沙箱模式則決定 Codex 是否可以讀取或寫入目錄，以及 Agent 可以存取哪些檔案。

如果你是完全的程式碼 Agent 新手，建議從保守的預設權限開始。預設情況下保持嚴格的批准和沙箱設定，只有在需求明確時，才為受信任的儲存庫或特定工作流程放寬權限。

請注意，CLI、IDE 和 Codex App 共享相同的配置層。更多資訊請參閱我們的範例配置文件頁面。

提示

：及早為你的真實環境配置 Codex。許多品質問題實際上是設定問題，例如錯誤的工作目錄、缺少寫入權限、錯誤的模型預設值，或缺少工具和連接器。

5. 讓 Codex 測試、驗證和審查工作，以提升可靠性

不要只停留在要求 Codex 做出改變。要求它在需要時建立測試、執行相關檢查、驗證結果，並在你接受之前審查工作。

Codex 可以為你執行這個循環，但前提是它知道「好」的標準是什麼。這個指導可以來自提示或 AGENTS.md。

這可以包括：

• 為變更編寫或更新測試
• 執行正確的測試套件
• 檢查 lint、格式化或型別檢查
• 確認最終行為符合要求
• 審查 diff 以找出錯誤、回歸或有風險的模式

提示：

在 Codex App 中切換 diff 面板，可以直接在本地

審查變更 。點擊特定行以提供反饋，這些反饋將作為上下文提供給 Codex 的下一個回合。

這裡有一個有用的選項是斜線命令 /review，它提供幾種不同的程式碼審查方式：

• 針對基礎分支進行 PR 風格的審查
• 審查未提交的變更
• 審查一個提交
• 使用自訂審查說明

如果你和你的團隊有一個在 AGENTS.md 中被引用的 code_review.md 檔案，Codex 也可以在審查時遵循該指導。對於希望審查行為在跨儲存庫和貢獻者之間保持一致性的團隊來說，這是一個強大的模式。

Codex 不應該只是生成程式碼。有了正確的指導，它還可以幫助測試它、驗證它和審查它。

如果你使用 GitHub Cloud，可以輕鬆設定 Codex 來為你的 PR 執行程式碼審查。我們在 OpenAI 使用 Codex 審查 100% 的 PR。你可以選擇啟用自動審查，或讓 Codex 在透過 @Codex 被叫用時進行反應式審查。

Codex CLI 中的 /review

6. 使用 MCP 將外部工具和即時上下文引入 Codex

當 Codex 需要的上下文存在於儲存庫之外時，請使用 MCP。它讓 Codex 能夠連接到你已在使用中的工具和系統，這樣你就不必不斷地將即時資訊複製貼上到提示中。

模型上下文協議（Model Context Protocol），簡稱 MCP，是一個開放標準，用於將 Codex 連接到外部工具和系統。

在以下情況使用 MCP：

• 需要的上下文存在於儲存庫之外
• 資料變化頻繁
• 你希望 Codex 使用工具，而不是依賴於貼上的指令
• 你需要跨使用者或專案的可重複整合

Codex 支援 STDIO 和帶有 OAuth 的 Streamable HTTP 伺服器。

在 Codex App 中，前往設定 → MCP 伺服器，查看自訂和推薦的伺服器。通常，Codex 可以幫助你安裝所需的伺服器。你只需要提出要求。你也可以在 CLI 中使用 codex mcp add 命令，透過名稱、URL 和任何額外資訊來添加你的自訂伺服器。

提示

：僅在工具能解鎖真正的工作流程時才添加它們。不要一開始就連接你使用的每個工具。從一兩個能明顯消除你經常手動執行的循環的工具開始，然後再從那裡擴展。

MCP 伺服器管理

7. 將重複的工作流程轉換為可重複使用的技能

一旦工作流程變得可重複，就不要再依賴冗長的提示或反覆來回。使用技能將指令（SKILL.md 檔案）、上下文和支援邏輯打包成一個 Codex 應一致應用的套件。技能可以在 CLI、IDE 擴充功能和 Codex App 中使用。

讓每個技能嚴格限定在一個任務上。從 2 到 3 個具體的使用案例開始，定義清晰的輸入和輸出，並編寫描述，清楚說明技能的作用以及何時使用它。包含使用者可能會實際說出的那種觸發短語。

不要試圖在一開始就涵蓋所有邊緣情況。從一個代表性任務開始，讓它順利運作，然後將該工作流程轉變為技能，並從那裡開始改進。僅在它們能有意義地提高可靠性時，才包含腳本或額外資源。

一個好的經驗法則是：如果你不斷重複使用同一個提示或修正同一個工作流程，那麼它很可能應該成為一個技能。

技能對於諸如以下的重複性工作特別有用：

• 日誌分類
• 發布說明草稿
• 針對檢查清單進行 PR 審查
• 遷移規劃
• 遙測或事件摘要
• 標準除錯流程

$skill-creator 技能是最好的起點，可用於搭建技能的第一個版本，並使用 $skill-installer 技能在本地安裝它。技能最重要的部分之一是描述。它應該清楚說明技能的作用以及何時使用它。

提示

：個人技能儲存在

$HOME /.agents/skills，共享的團隊技能可以簽入到儲存庫中的 .agents/skills 目錄。這對於新隊友的入職特別有幫助。

技能創建與安裝

Codex App 技能 UI

8. 透過自動化節省重複性工作的時間

一旦工作流程穩定下來，你可以安排 Codex 在背景為你執行它。在 Codex App 中，自動化功能讓你可以為重複性任務選擇專案、提示、執行頻率和執行環境。

一旦某個任務對你來說變得重複，你可以輕鬆地在 Codex App 的「自動化」標籤中建立一個自動化。你可以選擇它運行的專案、運行的提示（你可以調用技能），以及運行的頻率。你還可以選擇自動化是在專用的 git worktree 中執行，還是在你的本地環境中執行。了解更多關於 git worktrees 的資訊。

好的候選任務包括：

• 總結最近的提交
• 掃描潛在的錯誤
• 起草發布說明
• 檢查 CI 失敗
• 產生站立會議摘要
• 按計劃執行可重複的分析工作流程

一個有用的規則是：技能定義方法，自動化定義時間表。如果一個工作流程仍然需要大量引導，先將其轉變為技能。一旦它變得可預測，自動化就會成為一個力量倍增器。

提示

：將自動化用於反思和維護，而不僅僅是執行。審查最近的會話，總結重複出現的摩擦，並隨著時間改進提示、指令或工作流程設定。

Codex App 自動化創建

9. 使用會話控制來管理長時間運行的工作

Codex 會話不僅僅是聊天記錄。它們是隨著時間累積上下文、決策和行動的工作線程，因此良好的管理對品質有很大影響。

在 Codex App UI 中管理多個線程最為容易，因為可以固定線程和建立 worktree。但如果你使用 CLI，這些斜線命令特別有用：

• /experimental 用於切換實驗性功能並添加到你的 config.toml
• /resume 用於恢復已保存的對話
• /fork 用於創建一個新線程，同時保留原始記錄
• /compact 當線程變長，你想要一個前期上下文的摘要版本時使用。請注意，Codex 會自動為你壓縮對話
• /agent 當你運行多個 Agent 並想在活動的 Agent 線程之間切換時使用
• /theme 用於選擇語法高亮主題
• /apps 用於直接在 Codex 中使用 ChatGPT 應用程式
• /status 用於檢查當前會話狀態

為每個連貫的工作單元保留一個線程。如果工作仍然是同一個問題的一部分，通常留在同一個線程中更好，因為它保留了推理軌跡。只有當工作真正分支時才進行 Fork。

提示：

使用 Codex 的

多 Agent 工作流程，將有邊界的工作從主線程中卸載。讓主 Agent 專注於核心問題，並使用子 Agent 來處理探索、測試或分類等任務。

10. 應避免的常見錯誤

首次使用 Codex 時應避免的一些常見錯誤：

• 將持久性規則塞進提示中，而不是把它們移到 AGENTS.md 或技能中
• 不讓 Agent 看到它的工作成果，即不提供如何最佳運行建置和測試命令的詳細資訊
• 在多步驟和複雜任務上跳過規劃
• 在工作流程尚未完全理解之前，就授予 Codex 對你電腦的完全權限
• 在同一檔案上運行多個活動線程，而不使用 git worktrees
• 在一個重複性任務尚未可靠地手動完成時，就將其轉為自動化
• 將 Codex 與你自己的作業平行使用，而不是將其視為需要逐步監控的事物

入門檢查清單

1. 為 Codex 提供正確的目標、上下文、限制條件和完成條件
2. 對於困難的任務，要求 Codex 先規劃
3. 創建一個初始的 AGENTS.md
4. 告訴 Codex 如何建置、測試、驗證和審查
5. 設定符合你工作流程的配置預設值
6. 為高價值的外部工具添加 MCP
7. 將重複的工作流程轉變為技能
8. 一旦工作流程穩定，就使用自動化

你越是將你的工作流程、標準和上下文轉化為 Codex 可以使用的形式，你就越能看到這個 Agent 的真正能力。今天就開始吧！