如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

最佳做法

開始使用 Codex,掌握經過驗證的做法,取得更好的成果

如果你剛開始使用 Codex,或是第一次接觸程式設計智慧體,這份指南能幫你更快取得好成果。無論你使用的是 CLI、IDE 擴充功能 還是 ChatGPT 桌面應用程式,都可以運用這些做法,從撰寫提示詞、規劃任務到驗證成果,再到使用 MCP、技能和排程任務。

把 Codex 當成長期合作的隊友,依照合作經驗持續調整設定,比起只在有事時請它幫一次忙,更能發揮它的能力。

你可以從任務所需的上下文著手,用 AGENTS.md 記下長期適用的指引,再依照自己的工作流程設定 Codex。透過 MCP 連接外部系統,把重複的工作整理成技能,等流程穩定後再將其自動化。

第一次使用:提供上下文,寫好提示詞

即使提示詞不夠完善,Codex 也能派上用場。通常只要稍作準備,就能把難題交給它,得到不錯的結果。寫出清楚的提示詞並非使用 Codex 的先決條件,但能讓結果更可靠,尤其是處理大型程式碼庫或影響重大的任務時。

如果你的程式碼庫規模大或結構複雜,最有幫助的做法是提供與任務相關的上下文,並有條理地說明希望 Codex 完成哪些工作。

撰寫提示詞時,可以先交代四件事:

  • 目標: 你想修改或建置什麼?
  • 上下文: 哪些檔案、資料夾、文件、範例或錯誤與這項任務有關?你可以用 @ 提及特定檔案,將其加入上下文。
  • 限制: Codex 應遵循哪些標準、架構、安全要求或慣例?
  • 完成條件: 要符合哪些條件,才算完成任務?例如測試通過、程式行為已按要求變更,或無法再重現某個錯誤。

交代清楚這四件事,有助於 Codex 在指定範圍內工作,減少自行假設,也讓你更容易審查成果。

如果你的帳戶和用戶端都能使用 GPT-6.1 Sol,請選用這個模型,先採用用戶端預設的推理強度。使用 GPT-6 Luna 時,先選 高;使用 GPT-6 Astra 時,先選 輕度(設定值為 low)。接著依任務和結果調整。可用的推理等級請參閱模型。

  • 低:適合範圍明確、需要快速完成的任務
  • 中或高:適合較複雜的變更或除錯工作
  • 極高:適合耗時較長、需要智慧體自主執行並深入推理的任務

想更快提供上下文,可以使用 ChatGPT 桌面應用程式的語音聽寫功能,直接說出希望 Codex 做什麼,省去打字的時間。

困難的任務先規劃

如果任務複雜、需求不明確,或你很難描述清楚,可以請 Codex 先規劃,再開始寫程式碼。

你可以採用以下做法:

使用規劃模式: 對多數使用者來說,這是最簡單也最有效的選擇。在規劃模式下,Codex 可以先收集上下文、提問釐清需求,再擬定更周全的計畫。使用 /plan 或 Shift+Tab 即可切換模式。

請 Codex 向你提問: 如果你大致知道想做什麼,卻不確定該怎麼描述,可以請 Codex 先問你幾個問題。請它檢視你的假設、提出質疑,等想法具體成形後再寫程式碼。

使用 PLANS.md 範本: 對於較進階的工作流程,你可以設定 Codex,讓它依照 PLANS.md 或執行計畫範本處理耗時較長或需要多個步驟的工作。詳情請參閱執行計畫指南。

使用 AGENTS.md 重複運用指引

找到有效的提示詞寫法後,就不必每次都手動重述相同的指示。你可以把這些指示寫進 AGENTS.md。

你可以把 AGENTS.md 視為寫給智慧體的開放格式 README。它的內容會自動載入上下文,最適合用來記錄你和團隊希望 Codex 如何在程式碼庫中工作。

實用的 AGENTS.md 會涵蓋以下內容:

  • 程式碼庫的結構與重要目錄
  • 如何執行專案
  • 建置、測試與 lint 指令
  • 工程慣例與 PR 要求
  • 限制與禁止事項
  • 工作的完成條件與驗證方式

在 CLI 中執行 /init 斜線指令,就能在目前目錄快速建立一份初始的 AGENTS.md。你可以從這份檔案開始編輯,讓內容符合團隊實際建置、測試、審查及發布程式碼的方式。

你可以在不同層級建立 AGENTS.md 檔案:將記錄個人預設做法的全域 AGENTS.md 放在 ~/.codex,在程式碼庫層級的檔案中訂定共用標準,再於子目錄中放置檔案,記錄該處適用的具體規則。如果更靠近目前目錄的位置有更具體的指引,就優先採用該指引。

內容以實用為主。一份簡短、準確的 AGENTS.md,比一長串模糊的規則更有用。先寫下基本做法,等到同樣的錯誤反覆出現,再加入新規則。

如果 AGENTS.md 開始變得太長,可以把規劃、程式碼審查或架構等特定任務的細節移到各自的 Markdown 檔案,再從主檔案引用,讓主檔案保持精簡。

如果 Codex 犯了兩次相同的錯誤,請它回顧原因,再根據回顧結果更新 AGENTS.md。這樣整理出的指引能解決實際遇到的問題。

設定 Codex,讓行為保持一致

要讓 Codex 在不同工作階段和介面中的行為更一致,設定是主要方法之一。例如,你可以預先設定模型、推理強度、沙盒模式、核准政策、設定檔和 MCP 連線。

建議先從以下做法開始:

  • 將個人預設值存放在 ~/.codex/config.toml(在 ChatGPT 桌面應用程式中選擇 設定 > 組態設定 > 開啟 config.toml)
  • 將程式碼庫專用的設定存放在 .codex/config.toml
  • 如果你使用 CLI,只在單次執行需要不同設定時,才從指令列覆寫預設值

你可以在 config.toml 中定義長期適用的偏好設定,例如 MCP 伺服器、多智慧體設定和功能旗標。各設定檔專用的覆寫值則存放在各自的 $CODEX_HOME/profile-name.config.toml 檔案中。

Codex 內建作業系統層級的沙盒機制,有兩項主要設定可供調整。核准模式決定 Codex 在哪些情況下會先徵求你的許可,再執行指令。沙盒模式則決定 Codex 能否在目錄中讀寫,以及智慧體可以存取哪些檔案。

如果你剛開始使用程式設計智慧體,請先採用預設權限。平時對核准與沙盒採取較嚴格的設定,等到有明確需求,再針對信任的程式碼庫或特定工作流程放寬權限。

CLI、IDE 擴充功能和 ChatGPT 桌面應用程式都共用相同的設定層級。詳情請參閱設定範例。

一開始就依照實際工作環境設定 Codex。許多看似成果品質不佳的問題,其實源自設定,例如工作目錄不正確、缺少寫入權限、預設模型選錯,或缺少必要的工具與連接器。

透過測試與審查提高可靠性

除了請 Codex 修改程式碼,也請它視需要撰寫測試、執行相關檢查並確認結果。在你接受變更之前,先請它審查自己的工作。

Codex 可以替你完成這整套流程,前提是它知道什麼樣的成果才算合格。你可以在提示詞或 AGENTS.md 中提供這些指引。

你可以要求它:

  • 針對變更撰寫或更新測試
  • 執行適當的測試套件
  • 執行 lint、格式或型別檢查
  • 確認最終行為符合需求
  • 審查程式碼差異,找出錯誤、回歸問題或有風險的寫法

在 ChatGPT 桌面應用程式中開啟差異面板,即可直接在本機審查變更。點選特定一行即可提供意見,這些意見會納入 Codex 下一輪對話的上下文。

你也可以使用斜線指令 /review,選擇以下程式碼審查方式:

  • 與基準分支比較,像審查 PR 一樣審查變更
  • 審查尚未提交的變更
  • 審查某次提交
  • 使用自訂審查指示

如果團隊已有 code_review.md 檔案,並在 AGENTS.md 中引用它,Codex 在審查時也能遵循其中的指引。這種做法適合希望在不同程式碼庫、不同貢獻者之間維持一致審查方式的團隊。

Codex 的用途不限於產生程式碼。只要指示得當,它也能協助你測試、檢查及審查程式碼。

如果你使用 GitHub Cloud,可以設定 Codex 為你的 PR 執行程式碼審查。在 OpenAI,Codex 會審查 100% 的 PR。你可以啟用自動審查,也可以在需要審查時以 @Codex 提及它,請它審查。

使用 MCP 取得外部上下文

當 Codex 所需的上下文位於程式碼庫之外時,可以使用 MCP,讓 Codex 連接你已經在用的工具和系統。這樣就不必反覆將最新資訊複製貼上到提示詞中。

模型上下文協定(MCP)是一項開放標準,可用來將 Codex 連接至外部工具和系統。

以下情況適合使用 MCP:

  • 所需的上下文位於程式碼庫之外
  • 資料經常變動
  • 你希望 Codex 直接使用工具,而無須依賴貼到提示詞中的指示
  • 你需要讓不同使用者或專案重複使用同一種整合方式

Codex 支援 STDIO 伺服器,也支援搭配 OAuth 的 Streamable HTTP 伺服器。

在 ChatGPT 桌面應用程式中,前往 設定 > MCP 伺服器 即可查看自訂和推薦的伺服器。通常只要開口請 Codex 幫忙,它就能協助你安裝所需的伺服器。你也可以在 CLI 中使用 codex mcp add 指令,指定名稱、URL 和其他詳細資料,新增自訂伺服器。

有實際工作流程需要時,再加入工具。不必一開始就連接所有工具。先選一兩項能省去日常重複手動操作的工具,再逐步擴充。

將可重複執行的工作整理成技能

一旦工作流程可以重複執行,就不必再依賴冗長的提示詞或來回溝通。你可以建立技能,把指示寫進 SKILL.md 檔案,再連同上下文和輔助邏輯一起封裝,讓 Codex 每次都依照相同方式執行。技能可在 CLI、IDE 擴充功能和 ChatGPT 桌面應用程式中使用。

每項技能只負責一件事。先列出 2 到 3 個具體使用情境,明確定義輸入和輸出,再撰寫說明,交代技能的用途和使用時機。說明中應包含使用者實際會用來觸發技能的說法。

不必一開始就涵蓋所有特殊情況。先挑一項具代表性的任務,把流程調整到能順利執行,再將它整理成技能,持續改進。只有在指令碼或額外資源能提高可靠性時,才將其加入技能。

如果你經常重複使用同一個提示詞,或反覆修正同一套工作流程,就值得考慮把它做成技能。

技能特別適合這類經常要做的工作:

  • 分析記錄檔並依問題分類
  • 草擬版本資訊
  • 依檢查清單審查 PR
  • 規劃遷移作業
  • 撰寫遙測資料或事件摘要
  • 執行標準除錯流程

要建立技能的初版,最好從 $skill-creator 技能著手。先在本機反覆調整初版,等到準備好與更多人分享時,再將它封裝成外掛程式。技能說明是最重要的部分之一,應清楚寫出技能的用途與使用時機。

個人技能存放在 $HOME/.agents/skills 中。團隊共用的技能可以放在程式碼庫內的 .agents/skills 目錄,納入版本控制。這對協助新成員上手特別有幫助。

使用排程任務處理重複工作

工作流程穩定後,你可以安排 Codex 定時在背景執行。在 ChatGPT 桌面應用程式中,你可以透過排程任務為週期性工作選擇專案、提示詞、執行頻率和執行環境。

在 排程 頁面建立排程任務。選擇專案、提示詞與執行頻率,並決定要在專用的 Git 工作樹還是本機環境中執行任務。提示詞可以呼叫技能。詳情請參閱 Git 工作樹。

適合排程的工作包括:

  • 彙整近期的提交
  • 掃描程式碼,找出可能的錯誤
  • 草擬版本資訊
  • 檢查 CI 失敗的情況
  • 產生站立會議摘要
  • 定時執行可重複使用的分析流程

技能定義工作該怎麼做,排程任務則決定何時執行。如果某個流程仍需要你經常介入指導,先將它做成技能。等到執行結果可以預期,再設定排程就能節省時間。

除了定時執行工作,也可以用排程任務定期回顧與維護流程。例如回顧近期對話、整理反覆遇到的問題,並逐步改善提示詞、指示或工作流程設定。

整理長時間進行的對話

隨著對話持續進行,上下文、決策和操作紀錄會不斷累積,因此對話的管理方式會大幅影響成果品質。

在 ChatGPT 桌面應用程式中,你可以釘選對話及建立工作樹。如果你使用 CLI,以下斜線指令特別實用:

  • /experimental 可開啟或關閉實驗性功能,並將設定加入 config.toml
  • /resume 可繼續已儲存的對話
  • /fork 可建立新對話,同時保留原始對話紀錄
  • /compact 適合在對話變長、你希望將先前的上下文整理成摘要時使用。Codex 也會自動壓縮對話
  • /subagents 可在目前對話的子代理程式執行緒之間切換
  • /theme 可選擇語法醒目提示的佈景主題
  • /apps 可在 Codex 中直接使用 ChatGPT 應用程式
  • /status 可查看目前的工作階段狀態

每項可以獨立完成的工作使用一個對話。如果後續工作仍在處理同一個問題,通常最好留在同一個對話中,這樣才能保留先前的推理脈絡。等工作確實分成不同方向時,再建立對話分支。

使用 Codex 的子代理程式工作流程,將範圍明確的工作從主執行緒交給子代理程式處理。讓主要智慧體專注於核心問題,再由子代理程式負責探索、測試或問題分類等任務。

常見錯誤

初次使用 Codex 時,請避免以下常見錯誤:

  • 在提示詞中塞入太多長期適用的規則,沒有將它們移到 AGENTS.md 或技能中
  • 沒有說清楚該如何執行建置和測試指令,導致智慧體無法驗證自己的成果
  • 處理多步驟或複雜任務時跳過規劃
  • 還沒弄清楚工作流程,就授予 Codex 對電腦的完整存取權
  • 同時在相同檔案上執行多項任務,卻沒有使用 Git 工作樹
  • 手動執行任務時結果還不可靠,就設定為週期性排程
  • 以為必須盯著 Codex 的每個步驟,沒有在它執行任務時同步處理自己的工作
  • 整個專案都使用同一個對話,沒有依照各項可獨立交付的成果分開對話。久而久之,上下文會變得過於龐雜,成果也會變差