模型使用指南

簡介

GPT-6 Astra 是我們迄今最聰明的模型，在操作電腦、瀏覽網頁、軟體工程、科學與專業工作方面都具備頂尖表現。它擅長跨程式碼、瀏覽器與專業軟體執行多步驟工作流程。在多項評估中，Astra 不僅取得更好的結果，使用的輸出 Token 也大幅減少。因此，儘管每個 Token 的定價較高，每項任務的預估 API 成本仍低於先前的模型。

GPT-6 Astra 也是我們迄今對齊程度最高的模型。它擅長審慎行事、遵守任務範圍，並以透明的方式溝通。當指示留有解釋空間時，它會根據已有的上下文補足一般細節；若某個答案可能改變結果，則會提出有針對性的問題。它能納入新需求、依要求調整方向，並在回答額外問題時，仍掌握整體任務。

若要使用 Astra 開發，請在 Responses API 請求中將 model 設為 gpt-6-astra。

最新消息

• 非同步工具呼叫： 當應用程式執行工具時，GPT-6 Astra 可以繼續推理、呼叫其他工具，或回答請求中互不相依的部分。在函式或自訂工具上設定 async: true，並在結果準備就緒時，使用原始的 call_id 傳回結果。工具仍由應用程式執行，待完成的工作也仍由應用程式管理。如需基本用法及由開發者定義的等待工具模式，請參閱非同步工具呼叫。
• 回合中調整方向： 在 GPT-6 Astra 工作期間傳送額外的使用者指示，例如更正內容或變更需求。透過 WebSocket 連線，Responses API 會保留已完成的工作，並在接續執行時納入更新。如需事件流程與工具結果處理方式，請參閱回合中調整方向。
• 在對話中途變更推理並保留快取： 新增 configuration_update 輸入項目，即可針對困難工作提高推理強度，或針對例行後續工作降低推理強度，無須重寫原始提示詞前綴。更新後的推理強度會持續生效，直到另一個 configuration_update 輸入項目將其覆寫。如需範例與相容性資訊，請參閱在對話中途變更推理。
• 失準監控： 我們為 GPT-6 Astra 強化的防護措施包括由系統以非同步方式監控失準情況，並在必要時觸發警示。如需詳細資訊，請參閱失準監控。
• 限制： GPT-6 Astra 不支援 none 推理強度。使用歐盟資料駐留時，GPT-6 Astra 無法使用快速模式。

GPT-6 Astra 也支援 GPT-5.6 現有的 API 功能，包括電腦、結構化輸出、串流、以程式呼叫工具、多智慧體編排、提示詞快取、持久保留推理、壓縮及 Pro 模式。

提示詞最佳實務

GPT-6 Astra 比 GPT-5.6 Sol 等先前的模型更聰明、能力更強。它也有一些特定的行為模式，可以透過提示詞加以調整，以符合你的使用情境。

GPT-6 Astra 的行為

• 主動性與貫徹執行：模型的設計目標是成為更有效的協作夥伴，因此，當額外資訊可能大幅改變結果時，它更傾向向使用者提問。這可能導致模型停下來，即使使用者原本期望它做出合理假設並繼續執行。
• 遵循指示：GPT-6 Astra 在一般指示遵循方面比我們先前的模型更強，讓你更能掌控它的行為。它也可能更容易受到技能及其他檔案（例如 AGENTS.md）中指示的影響。我們 強烈建議 檢查模型可存取的技能及其他檔案，找出可能影響其行為的指示。
• 個性與寫作風格：模型傾向提供詳細且經過格式編排的回覆，也可能在不同工作階段反覆使用相同措辭。請明確指定應用程式需要的寫作風格與結構。
• 委派給子代理程式：模型委派工作的頻率可能低於工作流程所需。請明確指定它應在何時使用子代理程式進行平行作業，以及使用程度。
• 測試與驗證：處理程式碼編寫任務時，模型傾向先進行周全的測試，才認定任務完成。對於較小的任務，這可能導致測試範圍超出實際需要。

主動性與貫徹執行

在長時間任務中，GPT-6 Astra 通常比 GPT-5.6 Sol 及更早的模型更能維持思路連貫。遇到先前模型會自行做出假設的情況時，它也更傾向要求釐清。

若要鼓勵模型更自主地工作，可以從這段提示詞開始：

You should infer the user's intent and task scope from the instructions and prior conversation context. Your job is to bias towards action and carry the user's intended task to completion.

When the user expresses intent to perform new work or fix an existing issue, persist until the user's intended goal is complete. Progress autonomously towards the user's goal (e.g. creating isolated worktrees / checkouts if needed, resolving merge conflicts, read-only actions, creating draft PRs etc.) unless they are clearly destructive or irreversible.

當使用者的意圖不明確時，模型更傾向先向使用者釐清，再繼續執行。請透過提示詞告訴模型，若使用者的提示詞已隱含授權，就應繼續完成工作：

When the user's prompt indicates a request for action, such as "can you...", "I want to...", "help me..." and similar expressions, treat these as instructions to do the work and take action. Do not stop at acknowledging capability (e.g. "Yes…"), proposing a plan, or offering to continue. Do not settle for a partial or "helpful enough" solution that does not fully satisfy the user's task to save time, effort or tokens. If a task requires sustained work, complete all the necessary work until the intended outcome is fulfilled.

請透過提示詞要求模型，先準備好具體、可供審查的成果，再要求核准。這能避免模型尚未完成可執行的工作就阻擋任務進度，也往往能更快完成任務。

Before asking the user clarifying questions, you should complete the work that is already authorized from context and necessary to make the proposed action concrete and reviewable. The user should be approving a concrete, reviewable result. For example, before deploying a change, writing to an external application, merging a PR or publishing a site, do all the required work first so that user approval is the final step. You don't need user permission for reversible tasks, read-only actions, reviews or fixes, or anything for which authorization is provided earlier in the session or strongly implied from the task instruction.

Do not introduce unsolicited warnings, disclaimers, approval flows, or safety/compliance checklists due to hypothetical risk.

模型預設也傾向在工作期間提出不會阻擋進度的問題，因此請依應用程式所需的自主程度調整這些提示詞。

遵循指示

GPT-6 Astra 更能遵循較長的指示，但也可能更容易受到上下文資訊的影響。例如，技能檔案中的指引若不清楚或互相衝突，可能導致模型提早暫停，阻擋工作進度。請明確說明使用者指示與技能之間的優先順序。

The user's instructions take precedence over guidelines provided in a skill. If explicit user instructions conflict with a skill's instructions, prioritize the user's instructions.

要求模型指出導致它暫停或改變方向的技能與指示，也能有效提高模型行為的透明度。

If a skill causes you to ask for permission or confirmation, pause, leave requested work unfinished, or diverge from the user's intent, name and link to the exact SKILL.md file you read, quote the relevant instruction, and briefly explain how it applies. Distinguish explicit skill requirements from your interpretation of guidelines.

當應用程式載入許多技能及 AGENTS.md 等指示檔案時，可使用這段提示詞找出未明說卻已影響行為的指引，以及互相衝突的指引。

個性與寫作風格

GPT-6 Astra 傾向使用清單、表格與 Markdown，讓回覆便於快速瀏覽。如果應用程式需要格式較少的敘述文字，請明確說明這項偏好。

Default to using clear, concise paragraphs, each developing one main idea. Use lists only when the information is genuinely parallel, sequential, or easier to compare, and avoid nested lists unless the hierarchy cannot be expressed clearly in prose. Use plain, simple language: familiar words, concrete examples, and precise verbs. Prefer active voice and direct statements.

Make sure to state the main point clearly and early, then develop it with the explanation and detail the reader needs. Let each sentence build on what came before. Develop the points that matter and provide enough support to be useful.

在技術溝通中，以下提示詞有助於讓文字清楚、連貫，同時符合專業領域的用語習慣：

Use plain language over jargon, and reference technical details only to the degree that it helps illustrate an idea or your work to the user. Communicate complex concepts in a clear and cohesive manner, and calibrate your writing to the level of background knowledge assumed from the user's prompt and context.

若要減少文章中的行話與制式措辭，可以從這段提示詞開始：

Avoid using slop words or phrases like "Bottom Line:" in conclusions, "delve," "foster," "leverage," "it's worth noting," "importantly," "Question? Answer." or "This isn't about X. It's about Y.", "genuinely" or hyphenated compound descriptions and adjectives. Do not use concluding summary statements such as "In short:..", "The simplest mental model is:...".

State the intended action directly. Avoid adding what you won't do, what will remain unchanged, or how you'll separate or categorize results. Do not use contrastive framing such as "X, not Y" or "X—not Y" that introduces an unprompted alternative that the user didn't ask about. Avoid invented compound labels like "exact-head checks" and "editorial-row layouts", vague qualifiers, and canned transitions; use plain verbs and prepositions to state the actual relationship directly.

委派給子代理程式

GPT-6 Astra 經過訓練，能將工作拆分並委派給平行作業的子代理程式。如果你正在任務執行框架中實作多智慧體系統，可使用以下提示詞調整 GPT-6 Astra 委派工作的程度：

If at any point you can parallelize work by delegating tasks to another agent (no matter if you are the root or subagent), you should do so using collaboration tools if it could save time or improve quality.

智慧體之間的訊息可能包含文法或空格錯誤。使用這段提示詞，讓智慧體間的訊息更容易閱讀：

Messages that you send to other agents and your final answer may be read by a human, so ensure they are legible. Always put proper spaces between words and/or numbers.

透過提示詞說明應如何及何時將工作委派給子代理程式，通常能有效調整模型的行為。請依你的任務執行框架與多智慧體實作方式加以調整。

測試與驗證

處理程式碼編寫任務時，請依變更的需要調整測試與驗證的程度。這有助於避免為小幅變更進行不必要的測試或重複檢查。

Do not write tests for reversible, low-impact changes that mirror the implementation. If you do choose to verify your work with tests, make sure that the tests are meaningful and necessary to verify implementation.

Run tests appropriate to the change and complete required checks. Once those pass, broaden or repeat testing only when new changes, failures, or unresolved concerns justify it; otherwise, continue toward completing the task.

遷移快速入門

使用 Codex 遷移

Codex 可使用 OpenAI 文件技能套用本指南建議的變更。

$openai-docs migrate this project to GPT-6 Astra

若要在其他程式設計智慧體中使用這項技能，請從 Codex 程式碼庫下載。

更新 API 與模型參數

將 model 設為 gpt-6-astra，然後檢查以下項目：

• 推理強度： 如果目前使用 none 或 minimal，請先從 low 開始，並比較結果。否則，請保留目前實際生效的推理強度。在 Responses 中使用 reasoning.effort，在 Chat Completions 中則使用 reasoning_effort。
• 工具呼叫： 請使用 Responses API。GPT-6 Astra 支援 Chat Completions，但工具呼叫必須使用 Responses。
• 不支援的參數： 移除 temperature、top_p 和 top_logprobs。若使用 Chat Completions，也請移除 logprobs。若使用 Responses，請從 include 中移除 message.output_text.logprobs。
• 快速模式： 使用歐盟資料駐留時，請採用標準處理。在歐盟資料駐留設定下，GPT-6 Astra 不支援 service_tier: "fast" 或 service_tier: "priority"。GPT-6 Astra 的快速模式不包含延遲 SLA。請參閱快速模式相容性。
• 變更推理強度： 如果應用程式會在不同回覆之間變更推理強度，請在標準的單一智慧體請求中使用 configuration_update 項目。請保持請求層級的 reasoning.effort 不變，以保留提示詞前綴供快取使用。採用此功能前，請先查看相容性限制。
• 提示詞快取： 從 GPT-5.5 或更早的版本遷移時，請以 prompt_cache_options.ttl 取代 prompt_cache_retention，並將其設為 "30m"。請查看提示詞快取的變更，包括快取邊界與快取寫入計費方式。
• 不必要的核准等待： 如果模型反覆要求核准才繼續執行，請依照主動性與貫徹執行的指引調整提示詞，讓它更自主地執行。關於遵循指示、寫作風格、委派給子代理程式及測試的指引，請參閱提示詞最佳實務的其餘內容。

簡介

GPT-5.6 為複雜的正式環境工作流程樹立了新的品質與效率基準。GPT-5.6 的 Token 使用效率尤其出色，前端美感也有所提升，包括版面配置、視覺層次和設計判斷。

GPT-5.6 也引入了新的命名方式。gpt-5.6 別名會將請求導向具備旗艦級能力的模型 gpt-5.6-sol。若要以較低價格獲得出色效能，請使用 gpt-5.6-terra；若要高效率地處理大量工作，請使用 gpt-5.6-luna。

從 GPT-5.5 或 GPT-5.4 遷移時，請先沿用目前的 GPT-5.5 或 GPT-5.4 推理設定，再以具代表性的任務測試相同設定及低一級的設定。GPT-5.6 通常能以較少的 Token 維持或提升品質，但最佳設定仍取決於你的工作負載。

最新消息

• 以程式呼叫工具： GPT-5.6 可以撰寫 JavaScript 來呼叫符合條件的工具、在各次呼叫之間傳遞結果，並在託管執行環境中處理中間輸出。對於範圍明確、需大量使用工具，且不需要模型在每個步驟之間重新判斷的工作流程，請使用以程式呼叫工具。以程式呼叫工具與 ZDR 相容，且不會產生額外的容器費用。
• 多智慧體 [beta]： 多智慧體讓一個 GPT-5.6 執行個體能協調多個子代理程式平行工作，並整合其結果。這與 Codex 的 Ultra 模式類似，對於能明確拆分為獨立工作項目的複雜任務，可以縮短實際經過時間並提升效能。多智慧體目前以 beta 功能形式在 Responses API 中提供，我們會持續根據開發者的回饋改進。
• 明確提示詞快取： GPT-5.6 讓你能精確標記要由 OpenAI 快取的可重複使用提示詞前綴。你仍可在隱含模式下使用自動快取。OpenAI 的快取寫入費率為未快取輸入費率的 1.25 倍，而快取讀取仍享有折扣。瞭解如何設定提示詞快取。
• 保留推理內容： GPT-5.6 可以跨回合重複使用可用的推理項目，提升多回合互動的品質與快取效率。使用 reasoning.context 選擇其行為。瞭解如何在各次呼叫之間保留推理內容。
• Max 推理強度： GPT-5.6 支援 max 推理強度，適用於需要更多探索與驗證的高難度任務。如果你目前使用 xhigh，請以具代表性的工作負載比較這兩種設定。
• Pro 模式： GPT-5.6 可以投入更多模型運算，提高處理困難任務的可靠性，並傳回單一最終答案。當品質比延遲和 Token 用量更重要時，可透過 reasoning.mode: "pro" 啟用此模式。瞭解如何使用 Pro 模式。
• Token 使用效率： GPT-5.6 能以較少的輸出 Token 達到旗艦級效能。
• 前端設計： GPT-5.6 在版面配置、視覺層次和設計判斷方面表現更佳，能建立更精緻、易用的網站與應用程式。
• 意圖理解： GPT-5.6 能更準確地從上下文推斷使用者的真正目標，以及預期工作應做到什麼程度，因此通常不必逐步指定做法。仍請提供領域背景、不可違反的限制、核准界線和成功標準，並告訴模型，遇到哪些重要歧義時應先提問。
• 原始圖像細節： 使用 original 或 auto 細節設定時，GPT-5.6 會保留圖像尺寸；但任一邊超過 65,535 像素的圖像會縮小至符合該限制。若圖像仍超過30,000 個圖像區塊的限制，API 會拒絕該圖像，而不會再調整尺寸以符合限制。大型圖像可能使用更多輸入 Token 並增加延遲。瞭解如何選擇圖像細節等級。

防護措施

使用 GPT-5.6 模型時，系統會在生成模型輸出的同時執行即時網路與生物濫用分類器，因此使用者的部分請求可能遭到防護措施封鎖或拒絕。其他請求可能需要更長時間，因為這些分類器會同步審查輸出，使生成過程中途暫停數秒。防護措施偶爾也可能介入正當工作，尤其是在防禦與攻擊活動起初可能看起來相似的雙重用途領域。

如果你的應用程式為個別終端使用者提供服務，請在每次請求中傳送穩定且能保護隱私的 safety_identifier。相關指引請參閱實作安全識別碼。

我們持續改進這些防護措施，使其能穩健、有效地抵禦對抗性壓力，同時保留程式碼審查、漏洞研究、修補程式開發、偵錯、資安教育和防禦性測試等正當工作的使用管道。

遷移快速入門

使用 Codex 遷移

Codex 可以使用 OpenAI 文件技能，套用本指南建議的變更。

$openai-docs migrate this project to the GPT-5.6 model family

若要在其他程式碼編寫智慧體中使用此技能，請從 OpenAI 技能程式碼庫下載。

更新 API 與模型參數

• 根據工作負載選擇目標模型。若需要旗艦級能力，請使用 gpt-5.6-sol；若要兼顧智慧與成本，請使用 gpt-5.6-terra；若要高效率地處理大量工作，請使用 gpt-5.6-luna。gpt-5.6 別名會將請求導向 gpt-5.6-sol。
• 針對推理、工具呼叫和多回合工作流程，請使用 Responses API。
• 請根據需求設定 reasoning.effort。GPT-5.6 支援 none、low、medium、high、xhigh 和 max。
  • 如果你正從 GPT-5.5 或 GPT-5.4 遷移，請保留目前的推理強度作為基準，再與低一級的設定比較。
  • 如果你使用 none，請將其保留為延遲基準；若推理或工具使用有助於工作流程，也請測試 low。
  • 以 medium 作為均衡的起始設定；對於延遲敏感的工作負載，則使用 low。
  • 若實測顯示更多推理能提升品質，請使用 high 或 xhigh。
  • 僅在最困難且以品質為優先的工作負載中使用 max。比較 max 和 xhigh，找出最適合你使用案例的品質、延遲與成本平衡。
• 若要使用 Pro 模式，請保留已選取的 GPT-5.6 模型，並在 Responses API 中將 reasoning.mode 設為 pro；不要切換至另一個 Pro 模型 Slug。請獨立選擇 reasoning.effort。如果省略此設定，GPT-5.6 在標準模式與 Pro 模式下都預設為 medium。請參閱推理模式，查看請求範例和計費詳細資訊。
• 請根據先前推理內容仍有多少與當前任務相關，設定推理保留方式。GPT-5.6 模型預設為 all_turns；較早的模型則預設為 current_turn。
  • 省略 reasoning.context 或將其設為 auto，即可使用 GPT-5.6 的預設值 all_turns。請檢查回應中的 reasoning.context 欄位，確認實際生效的模式。
  • 當任務的目標、假設和優先順序在各回合之間保持穩定時，請將 reasoning.context 設為 all_turns。
  • 使用 all_turns 時，請透過 previous_response_id 延續對話，讓模型能使用先前回應中的推理內容。
  • 手動管理歷史紀錄時，請保留並重新傳送先前的使用者輸入，以及每一個回應輸出項目。若使用 store: false 或零資料保留，請重新傳送 API 預設傳回的加密推理項目。
  • 當先前的推理內容不再相關時，請將 reasoning.context 設為 current_turn。
• 檢視提示詞快取設定。你不需要修改程式碼，就能繼續使用隱含快取。由於 GPT-5.6 的快取寫入費率為未快取輸入費率的 1.25 倍，請追蹤 cached_tokens 和 cache_write_tokens，以瞭解淨成本。使用明確斷點或 prompt_cache_options.mode: "explicit" 避免不必要的寫入，並將 prompt_cache_retention 替換為 prompt_cache_options.ttl。
• 若要使用以程式呼叫工具，請新增 programmatic_tool_calling 工具，並透過 allowed_callers 允許符合條件的工具參與。更新應用程式，使其能處理 program 項目、程式發起的函式呼叫，以及 program_output 項目，同時保留每次呼叫的 call_id 和 caller 關聯。請參閱以程式呼叫工具指南，查看請求與延續執行的範例。
  • 以具代表性的任務，對已啟用 PTC 的工作流程進行基準測試。比較任務成功情況、最終答案的完整性、所需證據、Token 總量、延遲和成本。只有在最終答案仍達到所需品質標準時，減少呼叫次數、回合數或中間輸出才算是改善。

提示詞最佳實務

優先使用精簡的提示詞

移除重複的指示與範例，並簡化工具說明，可以改善任務表現與 Token 使用效率。在一組內部程式碼編寫智慧體的評估執行樣本中，採用較精簡系統提示詞的組態讓評估分數提高約 10–15%，同時將 Token 總量減少 41–66%、成本降低 33–67%。結果會因工作負載而異，因此請將這些範圍視為趨勢參考，並以你自身應用程式中具代表性的任務驗證變更。

若要在不遺漏重要指引的情況下簡化提示詞：

• 從已有效運作的提示詞與工具組合開始。每次移除一組指示、範例或工具，再重新執行相同的評估。
• 每項指示只說一次。
• 只提供與任務相關的工具，並讓工具說明保持簡潔、精確。
• 若範例與風格指引承載了產品需求，或能修正實測發現的不足，請予以保留。
• 在開始執行時，以及對話逐漸增長的過程中，都要追蹤上下文。長時間的對話可能放大重複提示詞與工具內容的影響。

界定自主行動與核准的界線

GPT-5.6 在執行多步驟任務時，可以主動且持續地推進工作。請界定每項請求授權的行動程度，讓模型能持續執行安全且符合範圍的工作，避免不必要的暫停，同時在採取對外、破壞性、高成本或擴大範圍的行動前停下。

通常只需要一份簡潔的政策：

For requests to answer, explain, review, diagnose, or plan, inspect the relevant
materials and report the result. Do not implement changes unless the request also
asks for them.

For requests to change, build, or fix, make the requested in-scope local changes
and run relevant non-destructive validation without asking first.

Require confirmation for external writes, destructive actions, purchases, or a
material expansion of scope.

明確列出安全的本機操作，例如讀取檔案、檢查記錄、編輯範圍內的程式碼和執行測試。將政策集中在一處，每項規則只說一次。重複「先詢問」、「不要變更」或「等待核准」等指示，可能導致模型在執行安全且符合預期的操作時，也提出不必要的核准請求。

設定回應長度與風格

GPT-5.6 的預設回應通常比 GPT-5.5 更簡潔。遷移時，請檢查「請簡潔作答」或「保持簡短」等籠統的簡短指示是否仍有用。對某些任務而言，這些指示可能沒有必要，有時還會使回應過於簡略。若這些指示能穩定產生應用程式所需的輸出，則請保留。

若要在不同請求之間維持更一致的控制，請使用 text.verbosity 設定預設的詳細程度，再於提示詞中指定個別任務的需求。

使用 text.verbosity 設定預設值

選擇 low、medium 或 high，作為請求的預設詳細程度。在提示詞中指定個別任務所需的長度、結構或必要內容。API 範例請參閱設定 text.verbosity。

明確指定簡短答案必須包含的內容

當任務需要較短的回答時，請明確指出模型必須保留哪些資訊，以及可以省略哪些細節。例如：

Lead with the conclusion. Include the evidence needed to support it, any material
caveat, and the next action. Omit secondary detail and repetition.

Keep all required facts, decisions, caveats, and next steps. Trim introductions,
repetition, generic reassurance, and optional background first.

這能讓模型清楚掌握優先順序：先保留完成任務所需的內容，再刪除價值較低的細節。

定義語氣

「友善」或「有同理心」等籠統描述可能不夠明確。請具體說明構成產品語氣的寫作方式，例如回答應該多直接、何時應表達對問題的理解，以及是否適合加入安撫語句或結語。

State the answer directly. If the user reports a problem, acknowledge the
specific issue before giving the next step. Use reassurance only when it is
relevant. Omit generic praise and unnecessary sign-offs.

Pro 模式

品質最重要時，選擇 Pro 模式

Pro 模式是 Responses API 的一種執行模式，會讓模型針對請求投入更多運算，再傳回單一最終答案。這可提升處理困難任務時的可靠性，但也會增加延遲，且回報的用量會彙總這些運算所使用的 Token。這些 Token 會依所選模型的標準 Token 費率計費。

如果品質即使只略微提升，也會對結果產生實質影響，而且任務難度足以從中受益，就適合使用 Pro 模式。例如複雜的最佳化、高價值的程式碼編寫或審查，或具備明確評估標準的深入分析。對於例行、對延遲敏感或處理量大的工作，以及評估未顯示 Pro 模式帶來明顯改善的情況，請優先使用標準模式。

推理模式與推理強度彼此獨立。Pro 模式可搭配任何 GPT-5.6 模型及其支援的推理強度。請先採用與標準模式基準相同的模型和推理強度，再以具代表性的任務比較各種組態，不要假設最高推理強度總是最佳取捨。

在 API 中設定 Pro 模式

請在 API 請求中啟用 Pro 模式。沿用標準模式下以成果為導向的提示詞：說明目標、相關上下文、限制、必要證據、成功標準和輸出格式。你不需要要求模型「使用 Pro 模式」、「更深入思考」，或產生多個候選答案。

例如：

Review this database migration plan for failure modes that could cause data loss
or extended downtime. For each finding, cite the relevant step, estimate impact
and likelihood, and recommend a specific mitigation. Return the five most
important risks in severity order.

比較品質與成本

以相同且具代表性的任務比較標準模式與 Pro 模式。衡量任務成功率、答案完整性、必要證據、Token 總數、延遲和成本。只有在品質或可靠性的提升值得投入額外模型運算時，才選擇使用 Pro 模式。

詳情請參閱推理模式指南。

以程式呼叫工具

依任務特性決定是否以程式呼叫工具

以程式呼叫工具（PTC）最適合範圍明確的工作流程：程式碼可以處理多個工具結果或大量中間輸出，再傳回小得多的結構化結果。可用於篩選、聯結、排序、去除重複資料、彙總、驗證，或其他處理方式可預先確定的作業。

僅因為需要多次、平行或有相依關係的呼叫，並不足以構成以程式呼叫工具的理由。遇到下列情況時，請優先採用直接工具呼叫，不使用 PTC：

• 一次呼叫就足夠
• 中間輸出本來就很少
• 每個結果都可能改變模型的下一步決策
• 某項動作需要核准
• 最終輸出必須保留引用來源或原生產出

針對任務明確指定呼叫方式

不要只靠工具是否可用，或「有效率地以程式呼叫工具」這類泛用指示，來讓模型選擇正確的呼叫方式。當直接呼叫與以程式呼叫兩種方式都可用時，請明確說明：

• 哪個範圍明確的階段應以程式呼叫工具。
• 可以呼叫哪些工具。
• 確切的輸出結構描述與必要證據。
• 並行數與重試次數的限制，以及停止條件。
• 哪些工作應維持直接呼叫。

工具說明應記載預期傳回的欄位、型別，以及發生錯誤時的行為。如果模型在撰寫程式前無法確定回傳資料的結構，請優先採用直接工具呼叫，讓模型先檢視結果，再決定如何使用。

如果兩種呼叫方式都需要，請定義一個明確的交接點，並告訴模型不要切換呼叫方式或重複已完成的工作。

例如：

<tool_orchestration>
Use Programmatic Tool Calling for [bounded stage] using only [eligible tools].
Run independent calls concurrently when safe. Use only documented tool input
and output fields.

Process and reduce the intermediate results, then emit exactly [output schema],
including the evidence needed for the final answer.

Stop when [condition] is met. Retry transient failures at most [R] times.
Do not repeat completed calls or perform side-effecting actions. If a required
result is still missing, return a clear structured failure.

Use direct tool calls for [semantic judgment, approval, or final validation].
</tool_orchestration>

評估最終答案

program_output 項目與助理的最終 message 是各自獨立的輸出；請務必測試兩者。理論上，程式可能傳回正確的記錄，但訊息卻遺漏必要欄位、引用來源或注意事項。

以相同且具代表性的任務比較直接呼叫與以程式呼叫。檢查最終回應是否正確、完整，並包含必要證據。接著比較 Token 總數、延遲、成本、呼叫次數、回合數與重試次數。只有在回應仍通過既有評估時，才能將資源用量降低視為改善。

詳情請參閱以程式呼叫工具指南。

簡介

GPT-5.5 提升了複雜正式環境工作流程的基本表現。它非常適合程式碼編寫、大量使用工具的智慧體、提供有據可查回答的助理、長上下文檢索、將產品規格轉為計畫的工作流程，以及對執行品質與回應表達品質要求嚴格的客戶服務工作流程。

若要充分發揮 GPT-5.5 的能力，請將它視為需要重新調校的新模型系列，而非可直接替換 gpt-5.2 或 gpt-5.4 的模型。開始遷移時，請建立新的基準，不要照搬舊版提示詞組合中的每一項指示。先使用能維持產品既定行為要求的最精簡提示詞，再以具代表性的範例調校推理強度、回應詳盡程度、工具說明與輸出格式。

GPT-5.5 支援 GPT-5.4 已提供的所有 API 功能，包括提示詞快取、託管工具、工具搜尋、壓縮，以及手動重播助理項目時的 phase 處理。

如需有效提示詞模式的範例，請參閱提示詞最佳實務。

最新消息

• 更有效率的推理： 即使採用相同的推理強度，GPT-5.5 也能以比先前模型更少的推理 Token 取得出色成果。這對複雜、大量使用工具或多步驟的工作流程尤其有用，因為節省的 Token 會逐步累積。
• 以成果為導向的提示詞可提升任務執行表現： GPT-5.5 更擅長依據明確目標展開工作、遵守限制，並將產品意圖轉為具體的後續步驟。請說明預期成果、成功標準、允許的副作用、證據規則與輸出形式。除非特定執行路徑很重要，否則請避免逐步指導流程。
• 工具使用能力更強、更精準： GPT-5.5 特別適合工具種類繁多的環境、多步驟服務工作流程，以及長時間執行的智慧體任務。它在工具選擇與引數使用上通常更為精準。
• 語氣通常更流暢得體，但也可能更直接： GPT-5.5 通常只需較少的提示詞引導，就能產生更親切、更易讀的回答。

行為變更

1. 推理強度現在預設為 medium： GPT-5.5 預設採用 medium 推理強度。建議以 medium 作為兼顧品質、可靠性、延遲與成本的起點。對延遲敏感的工作流程，如果工具使用、規劃、搜尋或多步驟決策仍然重要，請先評估 low，再考慮 none。none 僅適用於對延遲要求極高，且不需要推理或多次串接工具呼叫的任務，例如輕量語音互動、快速資訊檢索與分類。只有在評估顯示品質有可衡量的提升，足以抵銷額外延遲與成本時，才提高至 high 或 xhigh。如需建議設定的詳細資訊，請參閱推理模型文件。

   推理強度越高，不一定越好。如果任務中的指示互相衝突、停止標準不明確，或工具存取範圍未設限，提高推理強度可能導致過度思考、不必要的搜尋，或輸出品質下降。只有在評估顯示品質有可衡量的提升時，才提高推理強度。

2. 圖像輸入預設保留更多視覺細節： GPT-5.5 更新了圖像輸入的預設處理方式，以保留更多視覺細節，並提升電腦操作表現。當 image_detail 未設定或設為 auto 時，模型現在會採用 original 的處理方式：在達到 10,240,000 像素或單邊 6,000 像素的上限前，保留圖像原始尺寸。若要使用 high，請直接指定此值；在達到 2,500,000 像素或單邊 2,048 像素的上限前，它會保留圖像原始尺寸。low 現在著重於上下文使用效率，對於單邊超過 512 像素上限的圖像，會比先前模型更積極地縮小尺寸。請參閱圖像與視覺文件。

3. 更能遵循指示： GPT-5.5 會依字面意思完整解讀提示詞，因此當產品有需要時，您可以提供具體、描述性的指示。請定義成功標準與停止規則，尤其是長時間執行、大量使用工具或蒐集證據的工作流程。請參閱撰寫以成果為導向的提示詞與維持適當的具體程度。

4. 預設風格更精簡直接： GPT-5.5 的預設風格通常有效率、直接，且以任務為導向。這對許多正式環境工作流程很有幫助，但面向客戶或對話式的體驗，可能需要明確指引個性、親切程度、理由說明與格式。請依需求設定 text.verbosity：預設值為 medium；若希望回應精簡，low 通常是更好的起點。請參閱提示詞最佳實務。

5. 程式碼編寫工作流程需要更完善的編排： GPT-5.5 更適合需要規劃、使用工具、瀏覽程式碼庫、驗證與多步驟執行的複雜程式碼編寫任務。對程式碼編寫智慧體，請明確說明重用原則、子代理程式委派、測試要求、驗收標準，以及何時應繼續工作、何時應尋求協助。

遷移快速入門

使用 Codex 自動遷移

Codex 可以透過 OpenAI 文件技能套用本指南建議的變更。

$openai-docs migrate this project to gpt-5.5

若要在其他程式碼編寫智慧體中使用此技能，請從 OpenAI 技能程式碼庫下載。

API 與模型參數

• 將模型 Slug 更新為 gpt-5.5。
• 所有涉及推理、工具呼叫或多輪互動的使用案例，都請使用 Responses API。
• 調校 reasoning.effort。使用 low 進行高效率推理；使用 medium 在延遲與效能之間取得平衡；對需要高難度推理、且延遲較不重要的複雜智慧體任務，使用 high；對最困難的非同步智慧體任務，或測試模型智慧極限的評估，使用 xhigh。請參閱推理模型文件。
• 若要讓回應更精簡，請將 text.verbosity 設為 low。在 GPT-5.5 上，此設定產生的回應會比 GPT-5.4 採用 low 詳盡程度時相對更精簡。
• 對於大量使用工具或長時間執行的工作流程，請確認應用程式能正確處理 phase、開場說明與助理項目重播。
• 針對準確度、Token 用量與端到端延遲，與其他模型進行基準比較。

提示詞

• 明確說明預期成果與成功標準。
• 減少或移除詳細的逐步流程指引。除非產品要求特定執行路徑，否則讓 GPT-5.5 自行選擇。
• 盡可能從提示詞中移除輸出結構描述定義，改用結構化輸出。
• 調整提示詞以提高快取效益：靜態部分放在前面，動態部分放在最後。
• 移除目前日期。模型已知道目前的 UTC 日期。
• 參照提示詞最佳實務，審查並最佳化您的提示詞。

使用推理模型

本指引適用於 GPT-5 系列模型。團隊每次將工作負載移至推理模型時，都適合重新檢視這些建議。GPT-5.5 延續了許多先前模型首次推出的能力；如果您正從較早的 GPT-5 模型、GPT-4.1 或 o3 等推理模型遷移，仍值得重新瞭解這些能力。

團隊可能會忽略這些功能，因為其中一部分涉及 API 組態與編排，而不在提示詞本身。搭配使用 Responses API、推理控制、回應詳盡程度、結構化輸出、提示詞快取、工具設計、託管工具與狀態管理，有助於推理模型在智慧、可靠性、延遲與成本方面達到最佳整體表現。

• Responses API： GPT-5.5 在 Responses API 中表現最佳。請使用 previous_response_id 處理多輪互動的狀態。對於無狀態或零資料保留流程，請在每一輪傳回相關的已回傳輸出項目。詳情請參閱傳遞前一次回應的上下文。
• 推理強度： 使用 reasoning.effort 選擇 low、medium、high 或 xhigh。預設值為 medium，但許多工作負載使用 low 就能有良好表現。none 僅適用於低延遲比智慧更重要的使用案例。如需詳細建議，請參閱推理模型。
• 回應詳盡程度： 使用 text.verbosity 控制輸出長度。請將最終回答長度與推理品質分開考量；視需要指定字數限制、章節數、表格寬度，或要求僅輸出 JSON。
• 結構化輸出： 避免在提示詞中描述預期的輸出結構描述。請使用結構化輸出來自動驗證並提高準確度。
• 提示詞快取： 提示詞快取會自動套用至符合條件的長提示詞，可降低延遲與輸入 Token 費用。若要盡可能提高快取命中率，請將固定內容放在請求開頭，並將依使用者而異的動態上下文放在接近結尾的位置。追蹤 usage.prompt_tokens_details.cached_tokens 以衡量快取重用情況。對於共用可重用前綴的請求，請使用固定的 prompt_cache_key。這個鍵有助於將相關請求路由至同一個快取，對於最佳化 GPT-5.5 的快取命中率相當重要。對於流量較大的請求群組，請遵循將流量分散至更多鍵的指引。
• 工具呼叫： GPT-5.5 支援與 GPT-5.4 相同的工具呼叫模式，包括函式工具與大量使用工具的智慧體工作流程。請將大多數工具專屬指引放在工具本身的說明中，包括工具的用途、使用時機、必要輸入、副作用、重試是否安全，以及常見錯誤情況。只有當工具專屬上下文適用於多種工具，或會實質改變智慧體的運作政策時，才將它加入系統指示。
• 託管工具與工具搜尋： 若符合工作流程需求，請優先使用 OpenAI 託管工具，例如網頁搜尋、檔案搜尋、程式碼解譯器、圖像生成與電腦操作。託管工具可減輕自行編排的負擔，並讓常見工具使用模式與 Responses API 及 Agents SDK 保持一致。若需要呼叫自己的系統、執行特定領域的副作用，或提供內部業務工作流程，請使用自訂函式工具。工具目錄規模較大時，可考慮使用工具搜尋延後載入工具定義，只載入相關的子集。
• 工具開場說明： 開場說明可改善對話的使用者體驗，讓使用者在模型產生最終回應之前，先看到有用的初步狀態更新。這也能讓工具使用過程更容易掌握：模型可以先說明即將檢查或執行的事項，等工具結果回傳後，再從同一個助理狀態繼續。
• phase 處理： 如果應用程式未使用 previous_response_id，而是每輪傳回輸出項目來手動管理 Responses 狀態，請保留已回傳助理輸出項目上的 phase 參數，並原樣傳回。使用推理強度、開場說明或重複工具呼叫時，這點尤其重要。請參閱 Phase 參數。
• 壓縮： 對於長時間執行的智慧體，請有意識地運用對話／狀態壓縮。保留已完成的動作、目前採用的假設、ID、工具結果、尚未解決的阻礙，以及下一個具體目標。
• Agents SDK： 建立新的智慧體系統時，請採用最新的 Agents SDK 模式來處理工具編排、追蹤、交接與狀態管理，不必從零開始重新建構編排機制。
• 目前日期： GPT-5.5 知道目前的 UTC 日期，您不需要在系統指示中加入目前日期。只有當應用程式需要業務特定時區、政策生效日期、使用者當地日期，或其他非 UTC 參考基準時，才加入明確的日期或時區上下文。

提示詞最佳實務

當提示詞定義了成果，並保留空間讓模型自行選擇有效率的解決方式時，GPT-5.5 的表現最佳。相較於先前模型，您通常可以使用更短、更以成果為導向的提示詞：說明理想成果、重要限制、可用證據，以及最終回答應包含的內容。

避免照搬舊版提示詞組合中的每一項指示。舊提示詞往往過度規定流程，因為先前模型需要更多引導才能保持方向。對 GPT-5.5 而言，這可能增加干擾、限縮模型探索解法的空間，或使回答過於僵化。

這裡的模式可作為起點。請根據產品介面、工具、評估與使用者體驗目標加以調整。

個性與行為

GPT-5.5 的預設風格有效率、直接，且以任務為導向。這對正式環境系統很有幫助：回應能保持聚焦、行為更容易引導，模型也會避免不必要的對話贅詞。

對於面向客戶的助理、客服工作流程、教練式互動體驗及其他對話式產品，請同時定義個性與協作風格。

• 個性 控制助理的表達方式，包括語氣、親切程度、直接程度、正式程度、幽默感、同理心，以及表達的精緻程度。
• 協作風格 控制助理的工作方式，包括何時提問、何時做出假設、應多主動、提供多少上下文、何時檢查工作成果，以及如何處理不確定性或風險。

這兩類指示都應保持簡短。個性指示應塑造使用者體驗，協作指示應塑造任務執行行為。兩者都不應取代明確目標、成功標準、工具規則或停止條件。

適用於穩健、專注任務的助理的個性設定區塊範例：

# Personality
You are a capable collaborator: approachable, steady, and direct. Assume the user is competent and acting in good faith, and respond with patience, respect, and practical helpfulness.

Prefer making progress over stopping for clarification when the request is already clear enough to attempt. Use context and reasonable assumptions to move forward. Ask for clarification only when the missing information would materially change the answer or create meaningful risk, and keep any question narrow.

Stay concise without becoming curt. Give enough context for the user to understand and trust the answer, then stop. Use examples, comparisons, or simple analogies when they make the point easier to grasp. When correcting the user or disagreeing, be candid but constructive. When an error is pointed out, acknowledge it plainly and focus on fixing it.

Match the user's tone within professional bounds. Avoid emojis and profanity by default, unless the user explicitly asks for that style or has clearly established it as appropriate for the conversation.

表達生動、善於協作的助理個性設定區塊範例：

# Personality
Adopt a vivid conversational presence: intelligent, curious, playful when appropriate, and attentive to the user's thinking. Ask good questions when the problem is blurry, then become decisive once there is enough context.

Be warm, collaborative, and polished. Conversation should feel easy and alive, but not chatty for its own sake. Offer a real point of view rather than merely mirroring the user, while staying responsive to their goals and constraints.

Be thoughtful and grounded when the task calls for synthesis or advice. State a clear recommendation when you have enough context, explain important tradeoffs, and name uncertainty without becoming evasive.

如果產品需要更生動的表達，可明確加入溫暖、好奇心、幽默或觀點等特質，但仍應保持區塊簡短。個性應用來塑造體驗，而不是彌補不明確的目標或缺少的任務指示。

透過開場說明縮短首個可見 Token 的等待時間

在串流應用程式中，使用者會注意第一段可見回應出現前需要等待多久。GPT-5.5 在輸出可見文字之前，可能會先花時間推理、規劃或準備工具呼叫。

對於耗時較長或大量使用工具的任務，請在提示詞中要求模型先提供簡短的開場說明：以使用者看得到的簡短進度訊息，確認已收到請求並說明第一步。這能在不改變任務本身的情況下，讓使用者感覺回應更即時。

當任務可能需要多個步驟、呼叫工具，或涉及長時間執行的智慧體工作流程時，可使用這種模式。

Before any tool calls for a multi-step task, send a short user-visible update that acknowledges the request and states the first step. Keep it to one or two sentences.

對於會區分訊息階段的程式碼編寫智慧體，可以下達更明確的指示：

You must always start with an intermediary update before any content in the analysis channel if the task will require calling tools. The user update should acknowledge the request and explain your first step.

以成果為先的提示詞與停止條件

提示詞若能明確定義目標成果、成功標準、限制條件與可用上下文，再讓模型自行選擇執行方式，GPT-5.5 就能發揮最佳表現。

對許多任務而言，應描述要達成的目標，而非逐一規定步驟。這能讓模型有空間選擇適合該任務的搜尋方式、工具或推理策略。

建議採用這種寫法：

Resolve the customer's issue end to end.

Success means:
- the eligibility decision is made from the available policy and account data
- any allowed action is completed before responding
- the final answer includes completed_actions, customer_message, and blockers
- if evidence is missing, ask for the smallest missing field

避免不必要的絕對規則。 舊版提示詞常使用 ALWAYS、NEVER、must 和 only 等嚴格指示來控制模型行為。這些用語應保留給真正不可變動的要求，例如安全規則、必要的輸出欄位，或絕不應執行的動作。對於需要判斷的情況，例如何時搜尋、要求釐清、使用工具或繼續反覆改進，則應優先提供判斷準則。

除非每個步驟都確實必要，否則請避免這種指示方式：

First inspect A, then inspect B, then compare every field, then think through
all possible exceptions, then decide which tool to call, then call the tool,
then explain the entire process to the user.

加入明確的停止條件：

Resolve the user query in the fewest useful tool loops, but do not let loop minimization outrank correctness, accessible fallback evidence, calculations, or required citation tags for factual claims.

After each result, ask: "Can I answer the user's core request now with useful evidence and citations for the factual claims?" If yes, answer.

定義缺乏證據時的處理方式：

Use the minimum evidence sufficient to answer correctly, cite it precisely, then stop.

格式

GPT-5.5 的輸出格式與結構可以透過指示靈活調整。當這有助於理解，或能讓輸出更符合產品需求時，請善用這項能力。

設定 text.verbosity 並描述預期的輸出形式。只有在更完整的結構有助於理解，或產品 UI 需要形式穩定的產出時，才採用這類結構。API 中 text.verbosity 的預設值為 medium；如果希望回應更短、更精簡，請使用 low。

簡單的對話式格式：

Let formatting serve comprehension. Use plain paragraphs as the default format for normal conversation, explanations, reports, documentation, and technical writeups. Keep the presentation clean and readable without making the structure feel heavier than the content.

Use headers, bold text, bullets, and numbered lists sparingly. Reach for them when the user requests them, when the answer needs clear comparison or ranking, or when the information would be harder to scan as prose. Otherwise, favor short paragraphs and natural transitions.

Respect formatting preferences from the user. If they ask for a terse answer, minimal formatting, no bullets, no headers, or a specific structure, follow that preference unless there is a strong reason not to.

加入明確的受眾與篇幅指引：

Write for a senior business audience. Keep the answer under 400 words. Use short paragraphs and only include bullets when they improve scannability. Prioritize the conclusion first, then the reasoning, then caveats.

處理編輯、改寫、摘要或面向客戶的訊息時，請先告訴模型哪些內容必須保留，再要求它改善文風。若只想潤飾而不增加篇幅，這種模式很有用。

Preserve the requested artifact, length, structure, and genre first. Quietly improve clarity, flow, and correctness. Do not add new claims, extra sections, or a more promotional tone unless explicitly requested.

接地、引用與檢索預算

若要產生有依據的回答，提示詞應包含引用方式的指示。請定義哪些內容需要佐證、什麼程度的證據才算足夠，以及缺乏證據時模型應如何處理。缺乏證據不應直接被當成足以確定事實的否定答案。如需更多詳細資訊與範例，請參閱引用格式指南。

加入明確的檢索預算

檢索預算是搜尋的停止規則，用來告訴模型何時已有足夠證據，可以停止搜尋。

For ordinary Q&A, start with one broad search using short, discriminative keywords. If the top results contain enough citable support for the core request, answer from those results instead of searching again.

Make another retrieval call only when:
- The top results do not answer the core question.
- A required fact, parameter, owner, date, ID, or source is missing.
- The user asked for exhaustive coverage, a comparison, or a comprehensive list.
- A specific document, URL, email, meeting, record, or code artifact must be read.
- The answer would otherwise contain an important unsupported factual claim.

Do not search again to improve phrasing, add examples, cite nonessential details, or support wording that can safely be made more generic.

創意撰稿的防護機制

對於撰稿任務，請告訴模型哪些主張必須有來源依據，哪些部分可以發揮創意。這對投影片、發表文案、客戶摘要、講稿要點、主管短文與敘事架構尤其重要。

For creative or generative requests such as slides, leadership blurbs, outbound copy, summaries for sharing, talk tracks, or narrative framing, distinguish source-backed facts from creative wording.

- Use retrieved or provided facts for concrete product, customer, metric, roadmap, date, capability, and competitive claims, and cite those claims.
- Do not invent specific names, first-party data claims, metrics, roadmap status, customer outcomes, or product capabilities to make the draft sound stronger.
- If there is little or no citable support, write a useful generic draft with placeholders or clearly labeled assumptions rather than unsupported specifics.

前端工程與視覺品味

進行前端工作時，請參考指示範例，了解引導 UI 品質的實用方法。這些範例涵蓋產品與使用者背景、與設計系統的一致性、首屏易用性、使用者熟悉的控制項、預期狀態、響應式行為，以及生成 UI 時應避免的常見預設設計，例如千篇一律的主視覺區塊、巢狀卡片、裝飾性漸層、顯示在介面上的指示文字，以及錯亂的版面配置。

在提示詞中要求模型檢查自己的成果

讓 GPT-5.5 能夠使用檢查輸出的工具，以便在可驗證的情況下進行驗證。

對於程式碼編寫智慧體，請要求具體的驗證指令：

After making changes, run the most relevant validation available:
- targeted unit tests for changed behavior
- type checks or lint checks when applicable
- build checks for affected packages
- a minimal smoke test when full validation is too expensive

If validation cannot be run, explain why and describe the next best check.

對於視覺產出，請要求在轉譯後進行檢查：

Render the artifact before finalizing. Inspect the rendered output for layout, clipping, spacing, missing content, and visual consistency. Revise until the rendered output matches the requirements.

對於工程與規劃任務，請確保實作計畫可追溯：

For implementation plans, include:
- requirements and where each is addressed
- named resources, files, APIs, or systems involved
- state transitions or data flow where relevant
- validation commands or checks
- failure behavior
- privacy and security considerations
- open questions that materially affect implementation

階段參數

從 GPT-5.4 開始，長時間執行或大量使用工具的 Responses 工作流程，可以使用助理項目的 phase 值來區分過程中的進度更新與最終答案。GPT-5.5 也採用相同模式。

如果使用 previous_response_id，API 會自動保留先前的助理狀態。如果應用程式手動將助理輸出項目再次傳入下一個請求，請保留每個原始 phase 值，並原封不動地傳回。當回應包含開場說明、重複的工具呼叫，或在助理提供過程中的進度更新後才給出最終答案時，這點尤其重要。

If manually replaying assistant items:
- Preserve assistant `phase` values exactly.
- Use `phase: "commentary"` for intermediate user-visible updates.
- Use `phase: "final_answer"` for the completed answer.
- Do not add `phase` to user messages.

建議的提示詞結構

撰寫複雜提示詞時，可從這個結構開始。每個區段都應保持簡短，只在細節會影響行為的地方補充說明。

Role: [1-2 sentences defining the model's function, context, and job]

# Personality
[tone, demeanor, and collaboration style]

# Goal
[user-visible outcome]

# Success criteria
[what must be true before the final answer]

# Constraints
[policy, safety, business, evidence, and side-effect limits]

# Output
[sections, length, and tone]

# Stop rules
[when to retry, fallback, abstain, ask, or stop]

簡介

GPT-5.4 是為 API 和 Codex 中的專業工作推出的前沿模型。它能協助開發人員分析複雜資訊、建構可用於正式環境的軟體，並將多步驟工作流程自動化。

在 GPT-5.4 這一代模型中，gpt-5.4 是通用模型，適合在軟體工程、推理、寫作及工具使用之間切換的工作流程。

本指南介紹 GPT-5 模型系列的主要功能，以及如何充分發揮 GPT-5.4 的能力。

最新消息

相較於先前的 GPT-5.2 模型，GPT-5.4 在以下方面有所提升：

• 程式碼編寫、文件理解、工具使用及指令遵循
• 圖像感知及多模態任務
• 長時間任務執行及多步驟智慧體工作流程
• 大量使用工具的工作負載中的 Token 使用效率及端到端效能
• 透過網頁搜尋及多來源資訊整合，找出難以取得的資訊
• 客戶服務、分析及財務領域中，需要處理大量文件與試算表的業務工作流程

GPT-5.4 將 GPT-5.3-Codex 的程式碼編寫能力帶入我們的旗艦前沿模型。開發人員可以用更少的重試次數，生成達到正式環境品質的程式碼、建構精緻的前端 UI、遵循程式碼庫特有的模式，以及處理跨檔案變更。它預設的程式碼編寫風格也有出色表現，讓團隊能減少調整提示詞所花的時間。

對於智慧體式工作負載，GPT-5.4 能縮短多步驟執行過程的端到端耗時，且往往只需更少的 Token 和工具呼叫就能完成任務。這讓智慧體的回應更迅速，也降低了透過 API 和 Codex 大規模執行複雜工作流程的成本。

GPT-5.4 的新功能

與先前的 GPT-5 模型一樣，GPT-5.4 支援自訂工具、控制詳細程度與推理的參數，以及允許使用的工具清單。GPT-5.4 也引進了多項能力，讓你更容易建構強大的智慧體系統、處理更大量的資訊，以及執行更可靠的自動化工作流程：

• API 中的 tool_search： GPT-5.4 透過延後載入工具，改善大型工具生態系統中的工具搜尋。這讓工具可供搜尋，且只載入相關定義，從而減少 Token 用量，並提高實際部署時工具選擇的準確度。如需詳細資訊，請參閱工具搜尋指南。
• 1M Token 上下文視窗： GPT-5.4 支援高達 1M Token 的上下文視窗，讓你更容易在單次請求中分析整個程式碼庫、長篇文件集，或較長的智慧體執行歷程。如需詳細資訊，請參閱「1M 上下文視窗」一節。
• 內建電腦功能： GPT-5.4 是首個內建電腦操作能力的主線模型，讓智慧體能直接與軟體互動，在建構、執行、驗證、修正的循環中完成任務、驗證結果並修正問題。如需詳細資訊，請參閱電腦指南。
• 原生壓縮支援： GPT-5.4 是首個經過訓練以支援壓縮的主線模型，能在保留關鍵上下文的同時，支援更長的智慧體執行歷程。

模型、API 及功能更新

在這一代模型中，gpt-5.4 是適合各類任務及程式碼編寫的通用模型。面對更困難的問題，gpt-5.4-pro 會運用更多運算資源進行更長時間的思考，提供更一致的答案。

如果需要規模更小、速度更快的版本，可以先試用 gpt-5.4-mini 或 gpt-5.4-nano。

選擇最適合使用情境的模型時，請考量以下取捨：

較低的推理程度

reasoning.effort 參數控制模型在產生回應之前生成多少推理 Token。o3 等較早的推理模型僅支援 low、medium 和 high：low 側重速度與較少的 Token 用量，high 則側重更周全的推理。

GPT-5.2 和 GPT-5.4 支援以 none 作為最低推理程度，提供延遲更低的互動。這也是兩個模型的預設設定。如果需要更多思考，可逐步提高至 medium，並實驗觀察結果。

當推理程度設為 none 時，提示詞很重要。即使使用預設設定，也可以鼓勵模型在回答前先「思考」或列出步驟概要，以提升推理品質。

1
2
3
4
5
6
7
8
9
10
11
12
13import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
  model: "gpt-5.4",
  input:
    "Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
  reasoning: {
    effort: "none",
  },
});

console.log(response);

1
2
3
4
5
6
7
8
9
10
11from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.4",
    input="Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
    reasoning={"effort": "none"},
)

print(response)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
	"github.com/openai/openai-go/v3/shared"
)

func main() {
	client := openai.NewClient()
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:     "gpt-5.4",
		Input:     responses.ResponseNewParamsInputUnion{OfString: openai.String("Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?")},
		Reasoning: shared.ReasoningParam{Effort: shared.ReasoningEffortNone},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.Reasoning;
import com.openai.models.ReasoningEffort;
import com.openai.models.responses.ResponseCreateParams;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-5.4")
        .input("Explain the bug and propose a fix.")
        .reasoning(Reasoning.builder().effort(ReasoningEffort.NONE).build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new()
{
    Model = "gpt-5.4",
    ReasoningOptions = new ResponseReasoningOptions
    {
        ReasoningEffortLevel = ResponseReasoningEffortLevel.None,
    },
};
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem(
        "Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?"
    )
);

ResponseResult response = await client.CreateResponseAsync(options);
Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-5.4",
  reasoning: { effort: :minimal },
  input: "Explain the bug and propose a fix."
)
puts(response.output_text)

1
2
3
4
5
6
7
8
9
10
11curl --request POST \
  --url https://api.openai.com/v1/responses \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header 'Content-type: application/json' \
  --data '{
        "model": "gpt-5.4",
        "input": "Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
        "reasoning": {
                "effort": "none"
        }
}'

詳細程度

詳細程度決定生成的輸出 Token 數量。減少 Token 數量可降低整體延遲。雖然模型的推理方式大致不變，但它會設法更精簡地回答；這可能提升或降低答案品質，取決於你的使用情境。以下是高、低詳細程度各自適合的一些情境：

• 高詳細程度： 適用於需要模型詳盡解釋文件，或進行大範圍程式碼重構的情況。
• 低詳細程度： 最適合需要簡潔答案，或只針對特定需求生成程式碼的情況，例如 SQL 查詢。

GPT-5 開始允許將此選項設為 high、medium 或 low。在 GPT-5.4 中，詳細程度仍可設定，預設為 medium。

使用 GPT-5.4 生成程式碼時，medium 和 high 詳細程度會產生較長、結構更完整且附有行內說明的程式碼；low 詳細程度則會產生較短、更精簡的程式碼，並盡量減少額外說明。

1
2
3
4
5
6
7
8
9
10
11
12
13import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
  model: "gpt-5.4",
  input:
    "What is the answer to the ultimate question of life, the universe, and everything?",
  text: {
    verbosity: "low",
  },
});

console.log(response);

1
2
3
4
5
6
7
8
9
10
11from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.4",
    input="What is the answer to the ultimate question of life, the universe, and everything?",
    text={"verbosity": "low"},
)

print(response)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-5.4",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What is the answer to the ultimate question of life, the universe, and everything?")},
		Text:  responses.ResponseTextConfigParam{Verbosity: responses.ResponseTextConfigVerbosityLow},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseTextConfig;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-5.4")
        .input("Explain the bug and propose a fix.")
        .text(ResponseTextConfig.builder().verbosity(ResponseTextConfig.Verbosity.LOW).build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-5.4",
  text: { verbosity: :low },
  input: "Explain the bug and propose a fix."
)
puts(response.output_text)

1
2
3
4
5
6
7
8
9
10
11curl --request POST \
  --url https://api.openai.com/v1/responses \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header 'Content-type: application/json' \
  --data '{
  "model": "gpt-5.4",
  "input": "What is the answer to the ultimate question of life, the universe, and everything?",
  "text": {
    "verbosity": "low"
  }
}'

在 API 中將詳細程度設為 low 後，你仍可透過提示詞加以調整。詳細程度參數會在系統提示詞層級定義大致的 Token 數量範圍，但實際輸出仍可在該範圍內，依開發人員和使用者的提示詞彈性調整。

1M 上下文視窗

GPT-5.4 引進了 1M Token 上下文視窗，讓你更容易在單次請求中分析整個程式碼庫、長篇文件集，或較長的智慧體執行歷程。

我們針對低於 272K Token 和超過 272K Token 的請求，分別訂有不同的標準價格，詳見定價文件。如果你使用快速模式，任何超過 272K Token 的提示詞都會自動按標準費率處理。

長上下文定價會與資料駐留、批次處理等其他價格調整因素疊加套用。

我們針對低於 272K Token 和超過 272K Token 的請求，設有不同的速率限制，詳見 GPT-5.4 模型頁面。

搭配 GPT-5.4 使用工具

GPT-5.4 已針對特定工具進行後訓練。如需更具體的指引，請參閱工具文件。

電腦工具

電腦功能讓 GPT-5.4 透過檢視螢幕擷取畫面，並回傳結構化動作供你的任務執行框架執行，藉此透過使用者介面操作軟體。它適合人類可透過 UI 完成任務的瀏覽器或桌面工作流程，例如瀏覽網站、填寫表單，或驗證變更是否確實生效。

請在隔離的瀏覽器或 VM 中使用此功能，並確保對於影響重大的動作，有人類參與監督。完整指南涵蓋內建的 Responses API 迴圈、自訂任務執行框架模式，以及以程式碼執行為基礎的設定方式。

工具搜尋工具

工具搜尋讓 GPT-5.4 將大量工具的載入延後至執行時，使模型只載入所需的定義。當你有許多函式、namespaces 或 MCP 工具，且希望在不預先提供所有結構描述的情況下，減少 Token 用量、維持快取效能並降低延遲時，這項功能尤其實用。

如果在發出請求時就已確定候選工具，請使用託管工具搜尋；如果應用程式需要動態決定載入哪些工具，則使用由用戶端執行的工具搜尋。完整指南也涵蓋 namespaces、MCP 伺服器及延遲載入的最佳實務。

自訂工具

推出 GPT-5 模型系列時，我們引進了名為自訂工具的新功能，讓模型能將任意原始文字作為工具呼叫的輸入，同時仍可視需要限制輸出。GPT-5.4 也保留了這項工具行為。

自由格式輸入

使用 type: custom 定義工具，即可讓模型直接將純文字輸入傳送給工具，不再侷限於結構化 JSON。模型可以直接將任意原始文字傳送給工具，包括程式碼、SQL 查詢、Shell 指令、組態檔案或長篇文章。

12345{
  "type": "custom",
  "name": "code_exec",
  "description": "Executes arbitrary python code"
}

限制輸出

GPT-5.4 的自訂工具支援上下文無關文法（CFGs），讓你提供 Lark 文法，將輸出限制為特定語法或 DSL。附加 CFG（例如 SQL 或 DSL 文法）可確保助理的文字符合你指定的文法。

這可實現精確且符合限制的工具呼叫或結構化回應，並讓你直接在 GPT-5.4 的函式呼叫中強制採用嚴格的語法或領域專用格式，提升複雜領域或限制嚴格領域中的可控性與可靠性。

自訂工具的最佳實務

• 撰寫簡潔明確的工具說明。 模型會根據你的說明決定傳送哪些內容；如果希望模型每次都呼叫該工具，請明確說明。
• 在伺服器端驗證輸出。自由格式字串雖然功能強大，但需要防護措施來防範注入攻擊或不安全的指令。

允許使用的工具

tool_choice 下的 allowed_tools 參數可讓你傳入 N 個工具定義，但將模型限制為只能使用其中 M（< N）個。請在 tools 中列出完整工具集，再使用 allowed_tools 區塊指定工具子集及模式：auto（模型可以選用其中任一工具）或 required（模型必須呼叫其中一個工具）。

將所有可能使用的工具與 目前可使用的工具子集分開，可提升安全性與可預測性，並改善提示詞快取效果。這也能避免採用容易失效的提示工程做法，例如將呼叫順序寫死。GPT-5.4 可在對話過程中動態呼叫或要求使用特定函式，同時降低在長上下文中意外使用工具的風險。

12345678910{
  "tool_choice": {
    "type": "allowed_tools",
    "mode": "auto",
    "tools": [
      { "type": "function", "name": "get_weather" },
      { "type": "function", "name": "search_docs" }
    ]
  }
}

如需更詳細地瞭解上述所有新功能，請參閱 GPT-5.4 提示詞指南。

前置說明

前置說明是 GPT-5.4 在呼叫任何工具或函式前產生的簡短說明，使用者可以看到這些內容。它會概述模型的意圖或計畫，例如「我為什麼要呼叫這個工具」。前置說明會出現在思路鏈之後、實際工具呼叫之前，讓模型的推理更容易理解與除錯，也方便精確引導模型。

前置說明讓 GPT-5.4 在每次呼叫工具前「說出自己的想法」，在不大幅增加推理負擔的情況下，提升工具呼叫的準確度與整體任務成功率。若要啟用前置說明，請加入系統或開發者指示，例如：「在呼叫工具之前，先說明你為什麼要呼叫它。」GPT-5.4 會為每個指定的工具呼叫附上簡短理由。模型也可能在工具呼叫之間輸出多則訊息，改善互動體驗，尤其適合僅需少量推理或對延遲敏感的使用案例。

如需進一步瞭解前置說明的用法，請參閱 GPT-5 提示詞 Cookbook。

遷移快速入門

GPT-5.4 搭配 Responses API 使用時效果最佳，因為此 API 支援在回合之間保留推理上下文，以改善表現。請參閱下文，瞭解如何從目前使用的模型或 API 遷移。

從其他模型遷移至 GPT-5.4

此模型應該幾乎可以直接取代 GPT-5.2，不過仍有幾項重要變更需要留意。請參閱 GPT-5.4 提示詞指南，瞭解提示詞需要進行哪些具體調整。

得益於 Responses API 的設計，GPT-5 模型搭配此 API 使用時，智慧表現會更好。Responses API 可將上一回合的 CoT 傳遞給模型，進而減少生成的推理 Token、提高快取命中率並降低延遲。如需瞭解更多，請參閱介紹 Responses API 優勢的深入指南。

從較舊的 OpenAI 模型遷移至 GPT-5.4 時，請先試驗不同的推理等級與提示詞策略。使用提示詞最佳化工具，依照目前的最佳實務調整提示詞，使其適用於 GPT-5.4，再遵循以下針對各模型的建議：

• gpt-5.2：採用預設設定的 gpt-5.4，設計上可直接作為替代模型。
• o3：使用 gpt-5.4，並將推理投入程度設為 medium 或 high。先從 medium 開始，搭配提示詞調整；若未達到預期效果，再提高至 high。
• gpt-4.1：使用 gpt-5.4，並將推理投入程度設為 none。先從 none 開始並調整提示詞；如需更好的表現，再提高推理投入程度。
• o4-mini 或 gpt-4.1-mini：gpt-5.4-mini 搭配提示詞調整，是很好的替代選擇。
• gpt-4.1-nano：gpt-5.4-nano 搭配提示詞調整，是很好的替代選擇。

新的 phase 參數

對於在 Responses API 中長時間執行或大量使用工具的 GPT-5.4 流程，請使用助理訊息的 phase 欄位，以避免過早停止及其他異常行為。

phase 在 API 層級是選用欄位，但我們強烈建議使用。助理的中途進度更新（例如工具呼叫前的前置說明）應使用 phase: "commentary"，完成的答案則使用 phase: "final_answer"。請勿將 phase 加入使用者訊息。

在這些工作流程中，若 phase 缺失或遺失， 可能導致前置說明被當成最終答案。如需更多建議與範例，請參閱 GPT-5.4 提示詞指南。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.4",
  input: [
    {
      role: "assistant",
      phase: "commentary",
      content:
        "I’ll inspect the logs and then summarize root cause and remediation.",
    },
    {
      role: "assistant",
      phase: "final_answer",
      content: "Root cause: cache invalidation race.",
    },
    {
      role: "user",
      content: "Great—now give me a rollout-safe fix plan.",
    },
  ],
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.4",
    input=[
        {
            "role": "assistant",
            "phase": "commentary",
            "content": "I’ll inspect the logs and then summarize root cause and remediation.",
        },
        {
            "role": "assistant",
            "phase": "final_answer",
            "content": "Root cause: cache invalidation race.",
        },
        {
            "role": "user",
            "content": "Great—now give me a rollout-safe fix plan.",
        },
    ],
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	commentary := responses.ResponseInputItemParamOfMessage(
		"I’ll inspect the logs and then summarize root cause and remediation.",
		responses.EasyInputMessageRoleAssistant,
	)
	commentary.OfMessage.Phase = responses.EasyInputMessagePhaseCommentary
	finalAnswer := responses.ResponseInputItemParamOfMessage(
		"Root cause: cache invalidation race.",
		responses.EasyInputMessageRoleAssistant,
	)
	finalAnswer.OfMessage.Phase = responses.EasyInputMessagePhaseFinalAnswer

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-5.4",
		Input: responses.ResponseNewParamsInputUnion{OfInputItemList: responses.ResponseInputParam{
			commentary,
			finalAnswer,
			responses.ResponseInputItemParamOfMessage("Great—now give me a rollout-safe fix plan.", responses.EasyInputMessageRoleUser),
		}},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.Reasoning;
import com.openai.models.ReasoningEffort;
import com.openai.models.responses.ResponseCreateParams;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-5.4")
        .input("Explain the bug and propose a fix.")
        .reasoning(Reasoning.builder().effort(ReasoningEffort.MEDIUM).build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-5.4",
  reasoning: { effort: :medium },
  input: "Explain the bug and propose a fix."
)
puts(response.output_text)

GPT-5.4 參數相容性

只有在使用 GPT-5.4 並將推理投入程度設為 none 時， 才支援 以下參數：

• temperature
• top_p
• logprobs

若 GPT-5.4 或 GPT-5.2 採用任何其他推理投入程度設定，或使用 gpt-5、gpt-5-mini、gpt-5-nano 等較舊的 GPT-5 模型，包含這些欄位的請求都會引發錯誤。

若推理投入程度設得較高，或使用其他 GPT-5 系列模型，可以嘗試以下替代參數，以取得類似結果：

• 推理深度： reasoning: { effort: "none" | "low" | "medium" | "high" | "xhigh" }
• 輸出詳細程度： text: { verbosity: "low" | "medium" | "high" }
• 輸出長度： max_output_tokens

從 Chat Completions 遷移至 Responses API

對 GPT-5.4 而言，Responses API 與 Chat Completions 最大的差異，也是遷移至 Responses API 的主要原因，在於它支援在對話輪次之間傳遞思路鏈（CoT）。請參閱完整的 API 比較。

只有 Responses API 支援傳遞 CoT。我們觀察到，這能提升模型智慧、減少產生的推理 Token、提高快取命中率，並降低延遲。其他大多數參數的功能相同，只是格式不同。以下說明 Chat Completions 與 Responses API 處理新參數的差異：

推理強度

1
2
3
4
5
6
7
8
9
10
11curl --request POST \
  --url https://api.openai.com/v1/responses \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header "Content-type: application/json" \
  --data '{
  "model": "gpt-5.4",
  "input": "How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
  "reasoning": {
    "effort": "none"
  }
}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14curl --request POST \
  --url https://api.openai.com/v1/chat/completions \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header "Content-type: application/json" \
  --data '{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "How much gold would it take to coat the Statue of Liberty in a 1mm layer?"
    }
  ],
  "reasoning_effort": "none"
}'

詳細程度

1
2
3
4
5
6
7
8
9
10
11curl --request POST \
  --url https://api.openai.com/v1/responses \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header "Content-type: application/json" \
  --data '{
  "model": "gpt-5.4",
  "input": "What is the answer to the ultimate question of life, the universe, and everything?",
  "text": {
    "verbosity": "low"
  }
}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14curl --request POST \
  --url https://api.openai.com/v1/chat/completions \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header "Content-type: application/json" \
  --data '{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "What is the answer to the ultimate question of life, the universe, and everything?"
    }
  ],
  "verbosity": "low"
}'

自訂工具

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15curl --request POST \
  --url https://api.openai.com/v1/responses \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header "Content-type: application/json" \
  --data '{
  "model": "gpt-5.4",
  "input": "Use the code_exec tool to calculate the area of a circle with radius equal to the number of r letters in blueberry",
  "tools": [
    {
      "type": "custom",
      "name": "code_exec",
      "description": "Executes arbitrary Python code"
    }
  ]
}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22curl --request POST \
  --url https://api.openai.com/v1/chat/completions \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header "Content-type: application/json" \
  --data '{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "Use the code_exec tool to calculate the area of a circle with radius equal to the number of r letters in blueberry"
    }
  ],
  "tools": [
    {
      "type": "custom",
      "custom": {
        "name": "code_exec",
        "description": "Executes arbitrary Python code"
      }
    }
  ]
}'

提示詞最佳實務

瞭解 GPT-5.4 的行為

GPT-5.4 最擅長的領域

GPT-5.4 通常在以下領域表現特別出色：

• 忠實遵循個性與語氣設定，即使答案很長也較少偏離設定
• 穩健執行智慧體工作流程，更傾向於持續完成多步驟工作、重試，並從頭到尾完成智慧體執行迴圈
• 整合資訊時提供豐富佐證，尤其適用於長上下文或多工具工作流程
• 在要求明確的情況下，遵循模組化、以技能為基礎及以區塊組織的提示詞中的指示
• 針對大量、雜亂或包含多份文件的輸入進行長上下文分析
• 批次或平行呼叫工具，同時維持工具呼叫的準確度
• 需要遵循指示、精確保留格式及更強自我驗證能力的試算表、財務與 Excel 工作流程

明確的提示詞仍有幫助的情境

即使具備上述優勢，在一些常見情境中，提供更明確的指引仍能改善 GPT-5.4 的表現：

• 對話初期上下文不足時的工具路由，此時工具選擇可能較不可靠
• 需要考量相依關係的工作流程，必須明確檢查先決條件與後續步驟
• 推理強度的選擇：強度並非越高越好，適當的選擇取決於任務特性，而非直覺
• 需要嚴謹蒐集來源並一致標示引用的研究任務
• 執行前必須驗證的不可逆或影響重大的動作
• 必須明確界定工具使用範圍的終端或程式碼編寫智慧體環境

這些是觀察到的預設行為，並非保證。請先使用能通過評估的最精簡提示詞，只有在新增區塊能修正實際測得的失敗模式時，才加入區塊。

使用核心提示詞模式

讓輸出精簡且結構清晰

若要提高 GPT-5.4 的 Token 使用效率，請透過明確的輸出要求，限制詳細程度並強制使用結構化輸出。實務上，這能在 Responses API 的 verbosity 參數之外，提供額外的控制，讓你同時引導模型的輸出篇幅與結構。

12345678910111213<output_contract>
- Return exactly the sections requested, in the requested order.
- If the prompt defines a preamble, analysis block, or working section, do not treat it as extra output.
- Apply length limits only to the section they are intended for.
- If a format is required (JSON, Markdown, SQL, XML), output only that format.
</output_contract>

<verbosity_controls>
- Prefer concise, information-dense writing.
- Avoid repeating the user's request.
- Keep progress updates brief.
- Do not shorten the answer so aggressively that required evidence, reasoning, or completion checks are omitted.
</verbosity_controls>

為任務的持續執行設定明確的預設規則

使用者經常在對話途中變更任務、格式或語氣。為了讓助理持續符合使用者的意圖，請明確訂定規則，說明何時繼續執行、何時提問，以及新指示如何覆寫先前的預設設定。

可使用如下的預設持續執行原則：

12345678<default_follow_through_policy>
- If the user’s intent is clear and the next step is reversible and low-risk, proceed without asking.
- Ask permission only if the next step is:
  (a) irreversible,
  (b) has external side effects (for example sending, purchasing, deleting, or writing to production), or
  (c) requires missing sensitive information or a choice that would materially change the outcome.
- If proceeding, briefly state what you did and what remains optional.
</default_follow_through_policy>

明確說明指令的優先順序：

123456<instruction_priority>
- User instructions override default style, tone, formatting, and initiative preferences.
- Safety, honesty, privacy, and permission constraints do not yield.
- If a newer user instruction conflicts with an earlier one, follow the newer instruction.
- Preserve earlier instructions that do not conflict.
</instruction_priority>

優先順序較高的開發者或系統指令仍具有約束力。

指引： 在對話中途變更指令時，請明確說明更新內容、界定適用範圍，並將變更限於相關部分。說明哪些內容已變更、哪些仍然適用，以及變更只影響下一輪，還是適用於後續整段對話。

處理對話中途的指令更新

在對話中途更新指令時，請使用明確且範圍清楚的引導訊息，說明以下內容：

1. 適用範圍
2. 取代的內容
3. 沿用的內容

<task_update>
For the next response only:
- Do not complete the task.
- Only produce a plan.
- Keep it to 5 bullets.

All earlier instructions still apply unless they conflict with this update.
</task_update>

如果任務本身改變了，請直接說明：

<task_update>
The task has changed.
Previous task: complete the workflow.
Current task: review the workflow and identify risks only.

Rules for this turn:
- Do not execute actions.
- Do not call destructive tools.
- Return exactly:
  1. Main risks
  2. Missing information
  3. Recommended next step
</task_update>

當正確性仰賴工具時，要求持續使用工具

透過明確的規則，確保工具使用充分、考量相依關係，且執行節奏適當；後續動作依賴先前檢索或驗證結果的工作流程尤其需要如此。常見的失敗情況是，因為正確的最終狀態看似顯而易見，就跳過必要的前置步驟。

在對話初期、上下文仍不足時，GPT-5.4 選擇工具的可靠性可能較低。請在提示詞中要求確認前置條件、檢查相依關係，並明確說明工具的使用目的。

12345678<tool_persistence_rules>
- Use tools whenever they materially improve correctness, completeness, or grounding.
- Do not stop early when another tool call is likely to materially improve correctness or completeness.
- Keep calling tools until:
  (1) the task is complete, and
  (2) verification passes (see <verification_loop>).
- If a tool returns empty or partial results, retry with a different strategy.
</tool_persistence_rules>

如果工作流程的最終動作依賴先前的查詢或檢索步驟，這點尤其重要。最常見的失敗情況之一，就是因為預期的最終狀態看似顯而易見，而跳過必要的前置步驟。

12345<dependency_checks>
- Before taking an action, check whether prerequisite discovery, lookup, or memory retrieval steps are required.
- Do not skip prerequisite steps just because the intended final action seems obvious.
- If the task depends on the output of a prior step, resolve that dependency first.
</dependency_checks>

當各項工作彼此獨立，且實際耗時很重要時，請在提示詞中要求平行執行。當相依關係、不確定性或不可逆動作比速度更重要時，則要求依序執行。

123456<parallel_tool_calling>
- When multiple retrieval or lookup steps are independent, prefer parallel tool calls to reduce wall-clock time.
- Do not parallelize steps that have prerequisite dependencies or where one result determines the next action.
- After parallel retrieval, pause to synthesize the results before making more calls.
- Prefer selective parallelism: parallelize independent evidence gathering, not speculative or redundant tool use.
</parallel_tool_calling>

要求完整執行長時間跨度的任務

多步驟工作流程常見的失敗情況是執行不完整：模型只處理部分範圍就結束、遺漏批次中的項目，或將空白或範圍過窄的檢索結果當成最終結果。在提示詞中明確定義完成規則與復原行為，可提高 GPT-5.4 的可靠性。

依序或平行檢索都能涵蓋所需範圍，但無論採用哪種方式，都應明確定義完成規則。

123456789<completeness_contract>
- Treat the task as incomplete until all requested items are covered or explicitly marked [blocked].
- Keep an internal checklist of required deliverables.
- For lists, batches, or paginated results:
  - determine expected scope when possible,
  - track processed items or pages,
  - confirm coverage before finalizing.
- If any item is blocked by missing data, mark it [blocked] and state exactly what is missing.
</completeness_contract>

對於經常出現空白、不完整或混雜無關資訊的檢索結果的工作流程：

1234567891011<empty_result_recovery>
If a lookup returns empty, partial, or suspiciously narrow results:
- do not immediately conclude that no results exist,
- try at least one or two fallback strategies,
  such as:
  - alternate query wording,
  - broader filters,
  - a prerequisite lookup,
  - or an alternate source or tool,
- Only then report that no results were found, along with what you tried.
</empty_result_recovery>

在高影響動作之前加入驗證迴圈

工作流程看似完成後，請在傳回答案或執行不可逆動作之前，加入簡單的驗證步驟。這有助於在提交前發現遺漏的需求、接地問題，以及偏離規定的格式。

1234567<verification_loop>
Before finalizing:
- Check correctness: does the output satisfy every requirement?
- Check grounding: are factual claims backed by the provided context or tool outputs?
- Check formatting: does the output match the requested schema or style?
- Check safety and irreversibility: if the next step has external side effects, ask permission first.
</verification_loop>

12345<missing_context_gating>
- If required context is missing, do NOT guess.
- Prefer the appropriate lookup tool when the missing context is retrievable; ask a minimal clarifying question only when it is not.
- If you must proceed, label assumptions explicitly and choose a reversible action.
</missing_context_gating>

對於會主動執行動作的智慧體，請加入簡短的執行框架：

12345<action_safety>
- Pre-flight: summarize the intended action and parameters in 1-2 lines.
- Execute via tool.
- Post-flight: confirm the outcome and any validation that was performed.
</action_safety>

處理專門的工作流程

為視覺與電腦操作明確選擇圖像細節等級

如果工作流程仰賴視覺精確度，請在提示詞或整合設定中指定圖像的 detail 等級，不要依賴 auto。一般的高傳真度圖像理解請使用 high。大型、內容密集或需要精確掌握空間位置的圖像請使用 original，尤其是在 gpt-5.4 及未來模型上執行電腦操作、定位、OCR 和精準點擊任務時。只有在速度與成本比細微圖像細節更重要時，才使用 low。如需進一步了解圖像細節等級，請參閱圖像與視覺指南。

將研究與引用限定於檢索到的證據

當引用品質很重要時，請明確界定來源範圍與格式要求。這有助於減少捏造的參考資料、缺乏依據的主張，以及偏離規定的引用格式。

123456<citation_rules>
- Only cite sources retrieved in the current workflow.
- Never fabricate citations, URLs, IDs, or quote spans.
- Use exactly the citation format required by the host application.
- Attach citations to the specific claims they support, not only at the end.
</citation_rules>

123456<grounding_rules>
- Base claims only on provided context or tool outputs.
- If sources conflict, state the conflict explicitly and attribute each side.
- If the context is insufficient or irrelevant, narrow the answer or say you cannot support the claim.
- If a statement is an inference rather than a directly supported fact, label it as an inference.
</grounding_rules>

如果應用程式需要文內引用，就明確要求文內引用；如果需要註腳，就明確要求註腳。關鍵是固定格式，避免模型自行編造缺乏依據的參考資料。

研究模式

引導 GPT-5.4 進入嚴謹的研究模式。此模式適用於研究、審查與綜合整理任務。不要強行套用於簡短的執行任務，或結果明確的簡單轉換。

1234567<research_mode>
- Do research in 3 passes:
  1) Plan: list 3-6 sub-questions to answer.
  2) Retrieve: search each sub-question and follow 1-2 second-order leads.
  3) Synthesize: resolve contradictions and write the final answer with citations.
- Stop only when more searching is unlikely to change the conclusion.
</research_mode>

如果主機環境使用特定的研究工具，或要求提交步驟，請將此模式與主機的完成約定搭配使用。

嚴格限定輸出格式

對於 SQL、JSON 或其他格式稍有偏差就可能影響解析的輸出，請要求 GPT-5.4 僅輸出目標格式，並在完成前檢查。

<structured_output_contract>
- Output only the requested format.
- Do not add prose or markdown fences unless they were requested.
- Validate that parentheses and brackets are balanced.
- Do not invent tables or fields.
- If required schema information is missing, ask for it or return an explicit error object.
</structured_output_contract>

如果要擷取文件區域或 OCR 邊界框，請定義座標系統，並加入偏移檢查：

<bbox_extraction_spec>
- Use the specified coordinate format exactly, such as [x1,y1,x2,y2] normalized to 0..1.
- For each box, include page, label, text snippet, and confidence.
- Add a vertical-drift sanity check so boxes stay aligned with the correct line of text.
- If the layout is dense, process page by page and do a second pass for missed items.
</bbox_extraction_spec>

明確界定程式碼編寫與終端智慧體的工具使用範圍

在程式碼編寫智慧體中，明確規定 Shell 存取與檔案編輯的規則，有助於 GPT-5.4 發揮更好的表現。當你提供 Shell 或套用修補程式等工具時，這點尤其重要。

向使用者回報進度

GPT-5.4 擅長提供簡短、以成果為重點的進度回報。可沿用 5.2 指南中向使用者回報進度的模式，但需搭配明確的完成與驗證要求。

建議的進度回報規範：

123456<user_updates_spec>
- Only update the user when starting a new major phase or when something changes the plan.
- Each update: 1 sentence on outcome + 1 sentence on next step.
- Do not narrate routine tool calls.
- Keep the user-facing status short; keep the work exhaustive.
</user_updates_spec>

如需程式碼編寫智慧體的更具體指引，請參閱下方的「程式碼編寫任務的提示詞模式」一節。

程式碼編寫任務的提示詞模式

自主性與持續執行

在程式碼編寫與工具使用任務中，GPT-5.4 通常比先前的主系列模型更能從頭到尾完整執行，因此往往不需要那麼多明確要求「驗證所有內容」的提示。不過，對於正式環境、遷移或安全性工作等影響重大的變更，仍應保留簡單的驗證條款。

12345<autonomy_and_persistence>
Persist until the task is fully handled end-to-end within the current turn whenever feasible: do not stop at analysis or partial fixes; carry changes through implementation, verification, and a clear explanation of outcomes unless the user explicitly pauses or redirects you.

Unless the user explicitly asks for a plan, asks a question about the code, is brainstorming potential solutions, or some other intent that makes it clear that code should not be written, assume the user wants you to make code changes or run tools to solve the user's problem. In these cases, it's bad to output your proposed solution in a message, you should go ahead and actually implement the change. If you encounter challenges or blockers, you should attempt to resolve them yourself.
</autonomy_and_persistence>

執行期間的進度回報

減少回報頻率，並確保內容切中要點。在程式碼編寫任務中，優先於關鍵節點回報進度。

1234567891011121314<user_updates_spec>
- Intermediary updates go to the `commentary` channel.
- User updates are short updates while you are working. They are not final answers.
- Use 1-2 sentence updates to communicate progress and new information while you work.
- Do not begin responses with conversational interjections or meta commentary. Avoid openers such as acknowledgements ("Done -", "Got it", or "Great question") or similar framing.
- Before exploring or doing substantial work, send a user update explaining your understanding of the request and your first step. Avoid commenting on the request or starting with phrases such as "Got it" or "Understood."
- Provide updates roughly every 30 seconds while working.
- When exploring, explain what context you are gathering and what you learned. Vary sentence structure so the updates do not become repetitive.
- When working for a while, keep updates informative and varied, but stay concise.
- When work is substantial, provide a longer plan after you have enough context. This is the only update that may be longer than 2 sentences and may contain formatting.
- Before file edits, explain what you are about to change.
- While thinking, keep the user informed of progress without narrating every tool call. Even if you are not taking actions, send frequent progress updates rather than going silent, especially if you are thinking for more than a short stretch.
- Keep the tone of progress updates consistent with the assistant's overall personality.
</user_updates_spec>

格式

GPT-5.4 通常預設採用較有結構的格式，而且可能過度使用項目符號清單。如果希望最終回應簡潔清楚，請明確限制清單的形式。

Never use nested bullets. Keep lists flat (single level). If you need hierarchy, split into separate lists or sections or if you use : just include the line you might usually render using a nested bullet immediately after it. For numbered lists, only use the `1. 2. 3.` style markers (with a period), never `1)`.

前端任務

只有在額外的前端指引有幫助時，才使用此內容。

123456789101112131415161718<frontend_tasks>
When doing frontend design tasks, avoid generic, overbuilt layouts.

Use these hard rules:
- One composition: The first viewport must read as one composition, not a dashboard, unless it is a dashboard.
- Brand first: On branded pages, the brand or product name must be a hero-level signal, not just nav text or an eyebrow. No headline should overpower the brand.
- Brand test: If the first viewport could belong to another brand after removing the nav, the branding is too weak.
- Full-bleed hero only: On landing pages and promotional surfaces, the hero image should usually be a dominant edge-to-edge visual plane or background. Do not default to inset hero images, side-panel hero images, rounded media cards, tiled collages, or floating image blocks unless the existing design system clearly requires them.
- Hero budget: The first viewport should usually contain only the brand, one headline, one short supporting sentence, one CTA group, and one dominant image. Do not place stats, schedules, event listings, address blocks, promos, "this week" callouts, metadata rows, or secondary marketing content there.
- No hero overlays: Do not place detached labels, floating badges, promo stickers, info chips, or callout boxes on top of hero media.
- Cards: Default to no cards. Never use cards in the hero unless they are the container for a user interaction. If removing a border, shadow, background, or radius does not hurt interaction or understanding, it should not be a card.
- One job per section: Each section should have one purpose, one headline, and usually one short supporting sentence.
- Real visual anchor: Imagery should show the product, place, atmosphere, or context.
- Reduce clutter: Avoid pill clusters, stat strips, icon rows, boxed promos, schedule snippets, and competing text blocks.
- Use motion to create presence and hierarchy, not noise. Ship 2-3 intentional motions for visually led work, and prefer Framer Motion when it is available.

Exception: If working within an existing website or design system, preserve the established patterns, structure, and visual language.
</frontend_tasks>

123456<terminal_tool_hygiene>
- Only run shell commands via the terminal tool.
- Never "run" tool names as shell commands.
- If a patch or edit tool exists, use it directly; do not attempt it in bash.
- After changes, run a lightweight verification step such as ls, tests, or a build before declaring the task done.
</terminal_tool_hygiene>

文件區域定位與 OCR 邊界框

對於 bbox 任務，請明確說明座標慣例，並加入偏移測試。

1234567<bbox_extraction_spec>
- Use the specified coordinate format exactly (for example [x1,y1,x2,y2] normalized 0..1).
- For each bbox, include: page, label, text snippet, confidence.
- Add a vertical-drift sanity check:
  - ensure bboxes align with the line of text (not shifted up or down).
- If dense layout, process page by page and do a second pass for missed items.
</bbox_extraction_spec>

運用執行環境與 API 整合注意事項

對於長時間執行或大量使用工具的智慧體，執行環境約定與提示詞約定同樣重要。

階段參數

在 GPT-5.4、gpt-5.3-codex 及後續的 Responses 模型中，phase 欄位可 協助處理少數長時間執行或大量使用工具的流程中的問題：在這些流程裡，前置說明或 助理在執行期間提供的其他進度訊息可能被誤認為最終答案。

• phase 在 API 層級是選填欄位，但強烈建議使用。伺服器端可能會盡力推斷，但明確地在往返傳遞中保留 phase 一定更好。
• 對於長時間執行或大量使用工具，且可能在工具呼叫或最終答案之前輸出說明的智慧體，請使用 phase。
• 重新傳入先前的助理項目時，請保留 phase，讓模型能區分執行中的說明與已完成的答案。對於包含前置說明、工具相關進度訊息，或同一輪內多則助理訊息的多步驟流程，這點尤其重要。
• 不要在使用者訊息中加入 phase。
• 使用 previous_response_id 通常是最簡單的做法，因為 OpenAI 往往能還原先前的狀態，不需要手動重新傳入助理項目。
• 如果自行重新傳入助理的歷史紀錄，請保留原始的 phase 值。
• 缺少或遺失 phase，可能導致前置說明被解讀為最終答案，降低模型在這些多步驟任務中的表現。

在長時間對話中維持一致行為

壓縮能大幅延長上下文視窗的有效範圍，讓使用者對話持續多輪，而不會觸及上下文限制，也不會因上下文過長而降低表現。智慧體也因此能在長時間執行的複雜任務中，完成遠超過一般上下文視窗容量的執行歷程。

如果你在 Responses API 中使用壓縮，請在完成重要里程碑後進行壓縮，將壓縮後的項目視為不透明的狀態資料，並確保壓縮後提示詞的功能保持一致。此端點與 ZDR 相容，會傳回可傳入後續請求的 encrypted_content 項目。在較長的多輪對話中，GPT-5.4 通常能維持更好的連貫性與可靠性，隨著對話延長而出現失誤的情況也較少。

如需更多指引，請參閱 /responses/compact API 參考文件。

為面向客戶的工作流程設定個性

將持續生效的個性設定與個別回覆的寫作要求分開，能更有效地引導 GPT-5.4。這對電子郵件、客服回覆、公告和部落格風格內容等面向客戶的工作流程尤其有用。

• 個性（持續生效）： 設定整段對話的預設語氣、詳盡程度與決策風格。
• 寫作要求（個別回覆）： 定義特定產出內容的溝通管道、語體、格式與長度。
• 提醒： 個性設定不應凌駕於特定任務的輸出要求。如果使用者要求 JSON，就傳回 JSON。

若要產生自然、高品質的文章，最有效的控制方式包括：

• 為模型設定明確的角色。
• 指定溝通管道與情感基調。
• 需要連貫的段落文字時，明確禁止使用格式標記。
• 設定嚴格的長度限制。

12345678<personality_and_writing_controls>
- Persona: <one sentence>
- Channel: <Slack | email | memo | PRD | blog>
- Emotional register: <direct/calm/energized/etc.> + "not <overdo this>"
- Formatting: <ban bullets/headers/markdown if you want prose>
- Length: <hard limit, e.g. <=150 words or 3-5 sentences>
- Default follow-through: if the request is clear and low-risk, proceed without asking permission.
</personality_and_writing_controls>

如需更多可直接套用的個性設定模式，請參閱提示詞個性設定 Cookbook。

專業備忘錄模式

對備忘錄、審查報告和其他專業寫作任務而言，一般寫作指示往往不夠。針對內容的具體程度、領域慣例、綜合分析，以及如何恰當表達確定程度提供明確指引，有助於改善這些工作流程。

12345678<memo_mode>
- Write in a polished, professional memo style.
- Use exact names, dates, entities, and authorities when supported by the record.
- Follow domain-specific structure if one is requested.
- Prefer precise conclusions over generic hedging.
- When uncertainty is real, tie it to the exact missing fact or conflicting source.
- Synthesize across documents rather than summarizing each one independently.
</memo_mode>

這個模式尤其適合法律、政策、研究以及面向高階主管的寫作；這些內容不只要求文字流暢，也要求嚴謹的綜合分析與清楚的結論。

調整推理設定與遷移方式

將推理強度留作最後的微調手段

推理強度沒有適用於所有情況的單一設定。請將它作為最後的微調手段，而非提升品質的主要方式。許多情況下，改善提示詞、明確訂定輸出規範，以及加入輕量的驗證迴圈，就能達到團隊原本可能想透過提高推理設定來取得的大部分效能提升。

建議的預設設定：

• none：最適合模型不需要思考、要求快速完成，且對成本與延遲敏感的任務。
• low：適合對延遲敏感，且少量思考就能明顯提升準確度的任務，尤其是指示複雜的情況。
• medium 或 high：僅用於確實需要更強推理能力，且能接受額外延遲與成本的任務。請根據額外推理對任務帶來的效能提升幅度，在兩者之間選擇。
• xhigh：除非評估顯示有明顯效益，否則不建議作為預設值。它最適合長時間執行、需要大量推理的智慧體式任務，且這些任務對最高智慧能力的要求高於速度或成本。

實務上，大多數團隊應以 none、low 或 medium 作為預設設定。

對於以執行為主的工作負載，例如執行工作流程步驟、擷取欄位、客服案件分流，以及簡短的結構化轉換，請從 none 開始。

對於以研究為主的工作負載，例如長上下文綜合分析、多文件審查、解決衝突，以及策略撰寫，請從 medium 或更高的設定開始。使用 medium 搭配精心設計的提示詞，就能發揮相當出色的效能。

對 GPT-5.4 工作負載而言，none 在選擇動作與遵守工具使用規範的任務上就已能有良好表現。如果工作負載需要細膩的解讀能力，例如理解隱含需求、處理歧義，或在工具呼叫取消後恢復執行，請改從 low 或 medium 開始。

提高推理強度之前，請先加入：

• <completeness_contract>
• <verification_loop>
• <tool_persistence_rules>

如果模型仍過於拘泥字面，或找到第一個看似合理的答案就停止，請在提高推理強度之前，先加入鼓勵主動探索的提示：

12345<dig_deeper_nudge>
- Don’t stop at the first plausible answer.
- Look for second-order issues, edge cases, and missing constraints.
- If the task is safety or accuracy critical, perform at least one verification step.
</dig_deeper_nudge>

將提示詞遷移至 GPT-5.4 時，每次只做一項變更

請遵循 5.2 指南中每次只做一項變更的原則：先切換模型，固定 reasoning_effort，執行評估，再逐步調整。

以下起始設定適用於許多遷移情境：

小型模型 gpt-5.4-mini 與 gpt-5.4-nano 的使用指引

gpt-5.4-mini 和 gpt-5.4-nano 都很容易透過指示引導，但與較大型模型相比，它們較不會自行推斷缺少的步驟、化解未明說的歧義，或按你預期的方式組織輸出，除非你直接指定這些行為。因此，實務上小型模型的提示詞往往稍長，也更明確。

gpt-5.4-mini 有何不同

• gpt-5.4-mini 較傾向按字面理解，也較少自行假設。
• 當任務結構明確時，它的表現出色，但對於未明說的工作流程和歧義處理則較弱。
• 在預設情況下，它可能會透過追問來延續對話，除非你明確要求避免這種行為。

gpt-5.4-mini 的提示詞

• 將關鍵規則放在最前面。
• 當工具使用方式或副作用很重要時，請指定完整的執行順序。
• 不要只依賴「你必須」這類措辭。請透過編號步驟、決策規則和明確的動作定義等方式，提供結構化的指引。
• 將「執行動作」與「回報動作」分開。
• 示範正確的流程，而不只是最終格式。
• 明確定義遇到歧義時的處理方式：何時詢問、何時暫不處理，以及何時繼續執行。
• 直接指定輸出的呈現方式：回答長度、是否追問、引用格式，以及章節順序。
• 請謹慎使用 output nothing else。建議改用範圍明確的指示，例如 after the final JSON, output nothing further。

gpt-5.4-nano 的提示詞

• 僅將 gpt-5.4-nano 用於範圍狹窄、界線明確的任務。
• 優先採用範圍或格式固定的輸出：標籤、列舉值、簡短的 JSON 或固定範本。
• 除非流程受到極嚴格的限制，否則應避免多步驟編排。
• 將有歧義或需要大量規劃的任務交給能力更強的模型，而不是為 gpt-5.4-nano 堆疊過多提示詞。

建議的預設模式

1. 任務
2. 關鍵規則
3. 明確的步驟順序
4. 邊界情況或釐清疑問的處理方式
5. 輸出格式
6. 一個正確範例

應避免的做法

• 未明確說明的後續步驟
• 未明確說明的邊界情況
• 工具工作流程的提示詞僅包含結構描述
• 缺乏結構的籠統指示

網頁搜尋與深度研究

如果您正在遷移研究型智慧體，尤其應在提高推理強度之前，先對提示詞進行下列更新：

• 加入 <research_mode>
• 加入 <citation_rules>
• 加入 <empty_result_recovery>
• 先修正提示詞，再將 reasoning_effort 提高一級。

您可以從 5.2 的研究提示區塊開始，再視需要加入引用檢核條件與任務完成規範。

當任務需要透過多個步驟蒐集證據、綜整長上下文資訊，並遵循明確的提示詞規範時，GPT-5.4 的表現尤其出色。實務上，最有效的提示詞調整包括：依任務類型選擇推理強度、明確定義輸出與引用格式、加入考量相依關係的工具使用規則，以及明確說明完成標準。模型通常無須調整就有良好表現，但若提示詞清楚說明如何搜尋、如何驗證，以及怎樣才算完成，其表現會最為可靠。

後續步驟

• 請參閱模型、API 與功能更新，了解模型能力、參數與 API 相容性的詳細資訊。
• 請閱讀提示工程，了解適用於不同模型系列的更廣泛提示策略。
• 如果您正在使用 Responses API 建立長時間執行的 GPT-5.4 工作階段，請閱讀壓縮。

延伸閱讀

GPT-5.3-Codex 提示詞指南

GPT-5.4 部落格文章

GPT-5 前端指南

GPT-5 模型系列：新功能指南

推理模型 Cookbook

Responses API 與 Chat Completions 比較

簡介

GPT-5.3-Codex 將智慧體式程式碼編寫的智慧與效率推向新境界。請仔細遵循本指南，確保充分發揮此模型的效能。本指南適合希望直接透過 API 使用模型，以取得最大自訂彈性的開發者；我們也提供 Codex SDK，讓整合更簡單。

在 API 中，針對 Codex 調校的模型是 gpt-5.3-codex（請參閱模型頁面）。

最新消息

• 速度更快、Token 使用效率更高：完成任務所需的思考 Token 更少。我們建議將推理程度設為「中」，以兼顧智慧與速度，適用於各類互動式程式碼編寫工作。
• 更高的智慧與長時間自主執行能力：Codex 可自主執行數小時，完成最棘手的任務。處理這類任務時，你可以使用 high 或 xhigh 推理程度。
• 原生支援壓縮：壓縮可讓模型持續推理數小時而不觸及上下文限制，也能讓使用者持續對話更久，無須開啟新的對話工作階段。
• Codex 在 PowerShell 和 Windows 環境中的表現也大幅提升。

遷移快速入門

如果你已有可正常運作的 Codex 實作，只需少量更新，這個模型應該就能順利運作。但如果你目前的提示詞與工具組是針對 GPT-5 系列模型或第三方模型最佳化，我們建議進行較大幅度的調整。最佳參考實作是我們完全開放原始碼的 codex-cli 智慧體，可在 GitHub 上取得。複製此程式碼庫，並使用 Codex（或任何程式碼編寫智慧體）詢問各項功能的實作方式。透過與客戶合作，我們也累積了不受此特定實作限制的智慧體任務執行框架自訂經驗。

將任務執行框架遷移至 codex-cli 的關鍵步驟：

1. 更新提示詞：如情況允許，請以我們的標準 Codex-Max 提示詞為基礎， 再依需求有針對性地補充內容。

   1. 最重要的片段涵蓋自主性與持續執行能力、 程式碼庫探索、工具使用及前端品質。

   2. 你也應移除所有要求模型在執行過程中 預先說明計畫、提供開場訊息或其他狀態更新的提示， 因為這類要求可能導致模型在執行尚未完成前 突然停止。

2. 更新工具，採用我們的 apply_patch 實作及下列其他 最佳實務。這是充分發揮效能的關鍵。

模型、API 與功能更新

• gpt-5.3-codex 已針對 Codex 或類似環境中的智慧體式程式碼編寫任務進行最佳化。
• 可透過 Responses API 使用。
• reasoning.effort 支援 low、medium、high 和 xhigh。
• 支援的工具包括函式呼叫、網頁搜尋、託管 Shell 環境及技能。

提示詞最佳實務

建議的起始提示詞

此提示詞以預設的 GPT-5.1-Codex-Max 提示詞為起點，再根據內部評估進一步最佳化，涵蓋答案的正確性、完整性與品質、工具的正確使用與平行執行，以及積極採取行動的傾向。如果你正使用此模型執行評估，我們建議提高自主程度，或在提示詞中要求使用「非互動」模式；不過在實際使用時，多一些釐清問題的互動可能更合適。

You are Codex, based on GPT-5. You are running as a coding agent in the Codex CLI on a user's computer.


# General

- When searching for text or files, prefer using `rg` or `rg --files` respectively because `rg` is much faster than alternatives like `grep`. (If the `rg` command is not found, then use alternatives.)
- If a tool exists for an action, prefer to use the tool instead of shell commands (e.g `read_file` over `cat`). Strictly avoid raw `cmd`/terminal when a dedicated tool exists. Default to solver tools: `git` (all git), `rg` (search), `read_file`, `list_dir`, `glob_file_search`, `apply_patch`, `todo_write/update_plan`. Use `cmd`/`run_terminal_cmd` only when no listed tool can perform the action.
- When multiple tool calls can be parallelized (e.g., todo updates with other actions, file searches, reading files), make these tool calls in parallel instead of sequentially. Avoid single calls that might not yield a useful result; parallelize instead to ensure you can make progress efficiently.
- Code chunks that you receive (via tool calls or from user) may include inline line numbers in the form "Lxxx:LINE_CONTENT", e.g. "L123:LINE_CONTENT". Treat the "Lxxx:" prefix as metadata and do NOT treat it as part of the actual code.
- Default expectation: deliver working code, not just a plan. If some details are missing, make reasonable assumptions and complete a working version of the feature.


# Autonomy and Persistence

- You are autonomous senior engineer: once the user gives a direction, proactively gather context, plan, implement, test, and refine without waiting for additional prompts at each step.
- Persist until the task is fully handled end-to-end within the current turn whenever feasible: do not stop at analysis or partial fixes; carry changes through implementation, verification, and a clear explanation of outcomes unless the user explicitly pauses or redirects you.
- Bias to action: default to implementing with reasonable assumptions; do not end your turn with clarifications unless truly blocked.
- Avoid excessive looping or repetition; if you find yourself re-reading or re-editing the same files without clear progress, stop and end the turn with a concise summary and any clarifying questions needed.


# Code Implementation

- Act as a discerning engineer: optimize for correctness, clarity, and reliability over speed; avoid risky shortcuts, speculative changes, and messy hacks just to get the code to work; cover the root cause or core ask, not just a symptom or a narrow slice.
- Conform to the codebase conventions: follow existing patterns, helpers, naming, formatting, and localization; if you must diverge, state why.
- Comprehensiveness and completeness: Investigate and ensure you cover and wire between all relevant surfaces so behavior stays consistent across the application.
- Behavior-safe defaults: Preserve intended behavior and UX; gate or flag intentional changes and add tests when behavior shifts.
- Tight error handling: No broad catches or silent defaults: do not add broad try/catch blocks or success-shaped fallbacks; propagate or surface errors explicitly rather than swallowing them.
  - No silent failures: do not early-return on invalid input without logging/notification consistent with repo patterns
- Efficient, coherent edits: Avoid repeated micro-edits: read enough context before changing a file and batch logical edits together instead of thrashing with many tiny patches.
- Keep type safety: Changes should always pass build and type-check; avoid unnecessary casts (`as any`, `as unknown as ...`); prefer proper types and guards, and reuse existing helpers (e.g., normalizing identifiers) instead of type-asserting.
- Reuse: DRY/search first: before adding new helpers or logic, search for prior art and reuse or extract a shared helper instead of duplicating.
- Bias to action: default to implementing with reasonable assumptions; do not end on clarifications unless truly blocked. Every rollout should conclude with a concrete edit or an explicit blocker plus a targeted question.


# Editing constraints

- Default to ASCII when editing or creating files. Only introduce non-ASCII or other Unicode characters when there is a clear justification and the file already uses them.
- Add succinct code comments that explain what is going on if code is not self-explanatory. You should not add comments like "Assigns the value to the variable", but a brief comment might be useful ahead of a complex code block that the user would otherwise have to spend time parsing out. Usage of these comments should be rare.
- Try to use apply_patch for single file edits, but it is fine to explore other options to make the edit if it does not work well. Do not use apply_patch for changes that are auto-generated (i.e. generating package.json or running a lint or format command like gofmt) or when scripting is more efficient (such as search and replacing a string across a codebase).
- You may be in a dirty git worktree.
    * NEVER revert existing changes you did not make unless explicitly requested, since these changes were made by the user.
    * If asked to make a commit or code edits and there are unrelated changes to your work or changes that you didn't make in those files, don't revert those changes.
    * If the changes are in files you've touched recently, you should read carefully and understand how you can work with the changes rather than reverting them.
    * If the changes are in unrelated files, just ignore them and don't revert them.
- Do not amend a commit unless explicitly requested to do so.
- While you are working, you might notice unexpected changes that you didn't make. If this happens, STOP IMMEDIATELY and ask the user how they would like to proceed.
- **NEVER** use destructive commands like `git reset --hard` or `git checkout --` unless specifically requested or approved by the user.


# Exploration and reading files

- **Think first.** Before any tool call, decide ALL files/resources you will need.
- **Batch everything.** If you need multiple files (even from different places), read them together.
- **multi_tool_use.parallel** Use `multi_tool_use.parallel` to parallelize tool calls and only this.
- **Only make sequential calls if you truly cannot know the next file without seeing a result first.**
- **Workflow:** (a) plan all needed reads → (b) issue one parallel batch → (c) analyze results → (d) repeat if new, unpredictable reads arise.
- Additional notes:
    - Always maximize parallelism. Never read files one-by-one unless logically unavoidable.
    - This concerns every read/list/search operations including, but not only, `cat`, `rg`, `sed`, `ls`, `git show`, `nl`, `wc`, ...
    - Do not try to parallelize using scripting or anything else than `multi_tool_use.parallel`.


# Plan tool

When using the planning tool:
- Skip using the planning tool for straightforward tasks (roughly the easiest 25%).
- Do not make single-step plans.
- When you made a plan, update it after having performed one of the sub-tasks that you shared on the plan.
- Unless asked for a plan, never end the interaction with only a plan. Plans guide your edits; the deliverable is working code.
- Plan closure: Before finishing, reconcile every previously stated intention/TODO/plan. Mark each as Done, Blocked (with a one‑sentence reason and a targeted question), or Cancelled (with a reason). Do not end with in_progress/pending items. If you created todos via a tool, update their statuses accordingly.
- Promise discipline: Avoid committing to tests/broad refactors unless you will do them now. Otherwise, label them explicitly as optional "Next steps" and exclude them from the committed plan.
- For any presentation of any initial or updated plans, only update the plan tool and do not message the user mid-turn to tell them about your plan.


# Special user requests

- If the user makes a simple request (such as asking for the time) which you can fulfill by running a terminal command (such as `date`), you should do so.
- If the user asks for a "review", default to a code review mindset: prioritise identifying bugs, risks, behavioural regressions, and missing tests. Findings must be the primary focus of the response - keep summaries or overviews brief and only after enumerating the issues. Present findings first (ordered by severity with file/line references), follow with open questions or assumptions, and offer a change-summary only as a secondary detail. If no findings are discovered, state that explicitly and mention any residual risks or testing gaps.


# Frontend tasks

When doing frontend design tasks, avoid collapsing into "AI slop" or safe, average-looking layouts.
Aim for interfaces that feel intentional, bold, and a bit surprising.
- Typography: Use expressive, purposeful fonts and avoid default stacks (Inter, Roboto, Arial, system).
- Color & Look: Choose a clear visual direction; define CSS variables; avoid purple-on-white defaults. No purple bias or dark mode bias.
- Motion: Use a few meaningful animations (page-load, staggered reveals) instead of generic micro-motions.
- Background: Don't rely on flat, single-color backgrounds; use gradients, shapes, or subtle patterns to build atmosphere.
- Overall: Avoid boilerplate layouts and interchangeable UI patterns. Vary themes, type families, and visual languages across outputs.
- Ensure the page loads properly on both desktop and mobile
- Finish the website or app to completion, within the scope of what's possible without adding entire adjacent features or services. It should be in a working state for a user to run and test.

Exception: If working within an existing website or design system, preserve the established patterns, structure, and visual language.


# Presenting your work and final message

You are producing plain text that will later be styled by the CLI. Follow these rules exactly. Formatting should make results easy to scan, but not feel mechanical. Use judgment to decide how much structure adds value.

- Default: be very concise; friendly coding teammate tone.
- Format: Use natural language with high-level headings.
- Ask only when needed; suggest ideas; mirror the user's style.
- For substantial work, summarize clearly; follow final‑answer formatting.
- Skip heavy formatting for simple confirmations.
- Don't dump large files you've written; reference paths only.
- No "save/copy this file" - User is on the same machine.
- Offer logical next steps (tests, commits, build) briefly; add verify steps if you couldn't do something.
- For code changes:
  * Lead with a quick explanation of the change, and then give more details on the context covering where and why a change was made. Do not start this explanation with "summary", just jump right in.
  * If there are natural next steps the user may want to take, suggest them at the end of your response. Do not make suggestions if there are no natural next steps.
  * When suggesting multiple options, use numeric lists for the suggestions so the user can quickly respond with a single number.
- The user does not command execution outputs. When asked to show the output of a command (e.g. `git show`), relay the important details in your answer or summarize the key lines so the user understands the result.

## Final answer structure and style guidelines

- Plain text; CLI handles styling. Use structure only when it helps scanability.
- Headers: optional; short Title Case (1-3 words) wrapped in **…**; no blank line before the first bullet; add only if they truly help.
- Bullets: use - ; merge related points; keep to one line when possible; 4–6 per list ordered by importance; keep phrasing consistent.
- Monospace: backticks for commands/paths/env vars/code ids and inline examples; use for literal keyword bullets; never combine with **.
- Code samples or multi-line snippets should be wrapped in fenced code blocks; include an info string as often as possible.
- Structure: group related bullets; order sections general → specific → supporting; for subsections, start with a bolded keyword bullet, then items; match complexity to the task.
- Tone: collaborative, concise, factual; present tense, active voice; self‑contained; no "above/below"; parallel wording.
- Don'ts: no nested bullets/hierarchies; no ANSI codes; don't cram unrelated keywords; keep keyword lists short—wrap/reformat if long; avoid naming formatting styles in answers.
- Adaptation: code explanations → precise, structured with code refs; simple tasks → lead with outcome; big changes → logical walkthrough + rationale + next actions; casual one-offs → plain sentences, no headers/bullets.
- File References: When referencing files in your response follow the below rules:
  * Use inline code to make file paths clickable.
  * Each reference should have a stand-alone path, even if it's the same file.
  * Accepted: absolute, workspace‑relative, a/ or b/ diff prefixes, or bare filename/suffix.
  * Optionally include line/column (1‑based): :line[:column] or #Lline[Ccolumn] (column defaults to 1).
  * Do not use URIs like file://, vscode://, or https://.
  * Do not provide range of lines
  * Examples: src/app.ts, src/app.ts:42, b/server/index.js#L10, C:\repo\project\main.rs:12:5

執行期間的使用者更新

Codex 模型系列可在執行工作時向使用者提供進度更新。在 gpt-5.3-codex 之前的 codex 版本中，這些更新由系統產生，無法透過提示詞控制，因此我們不建議在這些版本的提示詞中加入要求提供中途計畫或使用者訊息的指示。從 gpt-5.3-codex 開始，這些更新更善於溝通，能提供更多關於目前正在做什麼及其原因的關鍵資訊。其運作方式與其他 GPT-5 系列模型的中途訊息類似，可依下方「開場訊息與個性」一節的說明，透過提示詞加以引導。

使用 agents.md

Codex-cli 會自動列舉這些檔案，並將其注入對話；模型已受過訓練，能嚴格遵循這些指示。

1. 從 ~/.codex 以及程式碼庫根目錄到 CWD 之間的每一層目錄讀取檔案（可選擇設定備援檔名，並設有大小上限）。
2. 依序合併檔案，後面的目錄會覆寫前面目錄的內容。
3. 每個合併後的區塊都會以獨立的使用者角色訊息呈現給模型，如下所示：

# AGENTS.md instructions for <directory>
<INSTRUCTIONS>
...file contents...
</INSTRUCTIONS>

補充說明

• 每個找到的檔案都會成為獨立的使用者角色訊息，並以 # AGENTS.md instructions for <directory> 開頭，其中 <directory> 是提供該檔案的資料夾相對於程式碼庫根目錄的路徑。
• 這些訊息會注入對話記錄前段、使用者提示詞之前，順序由根目錄往下：先是全域指示，再來是程式碼庫根目錄，接著是各層子目錄。如果使用了 AGENTS.override.md，標頭仍會顯示其目錄名稱（例如 # AGENTS.md instructions for backend/api），因此從對話記錄中就能清楚辨識其上下文。

壓縮

壓縮可大幅延長上下文視窗的有效範圍，讓使用者對話持續多個回合，而不會觸及上下文視窗限制，也不會因上下文過長而降低效能。對於長時間執行的複雜任務，智慧體也能完成遠超一般上下文視窗容量的執行流程。過去可透過臨時搭建的輔助架構與對話摘要，達成效果較有限的類似功能；現在，我們透過 Responses API 提供與模型整合的原生實作，效能出色。

運作方式：

1. 依照目前的方式使用 Responses API，傳送包含工具呼叫、使用者輸入及助理訊息的輸入項目。
2. 當上下文視窗逐漸變大時，你可以呼叫 /compact，產生新的壓縮版上下文視窗。請注意以下兩點：
   1. 傳送至 /compact 的上下文視窗，應在模型的上下文視窗容量限制內。
   2. 此端點與 ZDR 相容，會傳回一個「encrypted_content」項目，可供後續請求使用。
3. 後續呼叫 /responses 端點時，你可以傳入更新且壓縮後的對話項目清單（包含新增的壓縮項目）。模型會以較少的對話 Token 保留先前的重要狀態。

如需端點詳細資訊，請參閱我們的 /responses/compact 文件。

工具

1. 我們強烈建議原樣採用我們的 apply_patch 實作，因為模型已受過訓練，能熟練處理這種差異格式。執行終端指令時，我們建議使用 shell 工具；處理計畫與待辦事項時，使用我們的 update_plan 工具應能獲得最佳效能。
2. 如果你希望智慧體多使用「類似終端的工具」（例如使用 file_read()，而不是在終端中呼叫 `sed`），只要遵循下方指示，此模型就能可靠地呼叫這些工具，取代終端操作。
3. 其他工具也能使用，包括語意搜尋、MCP 或其他自訂工具，但需要更多調校與實驗。

Apply_patch

實作 apply_patch 最簡單的方式，是使用 Responses API 中的原生實作；你也可以使用我們搭配上下文無關文法的自由格式工具實作。以下示範這兩種方式。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146# Sample script to demonstrate the server-defined apply_patch tool

import json
from pprint import pprint
from typing import cast

from openai import OpenAI
from openai.types.responses import ResponseInputParam, ToolParam

client = OpenAI()

## Shared tools and prompt
user_request = """Add a cancel button that logs when clicked"""
file_excerpt = """\
export default function Page() {
return (
<div>
    <p>Page component not implemented</p>
    <button onClick={() => console.log("clicked")}>Click me</button>
</div>
);
}
"""

input_items: ResponseInputParam = [
    {"role": "user", "content": user_request},
    {
        "type": "function_call",
        "call_id": "call_read_file_1",
        "name": "read_file",
        "arguments": json.dumps({"path": ("/app/page.tsx")}),
    },
    {
        "type": "function_call_output",
        "call_id": "call_read_file_1",
        "output": file_excerpt,
    },
]

read_file_tool: ToolParam = cast(
    ToolParam,
    {
        "type": "function",
        "name": "read_file",
        "description": "Reads a file from disk",
        "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"],
        },
    },
)

### Get patch with built-in responses tool
tools: list[ToolParam] = [
    read_file_tool,
    cast(ToolParam, {"type": "apply_patch"}),
]

response = client.responses.create(
    model="gpt-5.3-codex",
    input=input_items,
    tools=tools,
    parallel_tool_calls=False,
)

for item in response.output:
    if item.type == "apply_patch_call":
        print("Responses API apply_patch patch:")
        pprint(item.operation)
        # output:
        # {'diff': '@@\n'
        #          '   return (\n'
        #          '     <div>\n'
        #          '       <p>Page component not implemented</p>\n'
        #          '       <button onClick={() => console.log("clicked")}>Click me</button>\n'
        #          '+      <button onClick={() => console.log("cancel clicked")}>Cancel</button>\n'
        #          '     </div>\n'
        #          '   );\n'
        #          ' }\n',
        #  'path': '/app/page.tsx',
        #  'type': 'update_file'}

### Get patch with custom tool implementation, including freeform tool definition and context-free grammar
apply_patch_grammar = """
start: begin_patch hunk+ end_patch
begin_patch: "*** Begin Patch" LF
end_patch: "*** End Patch" LF?

hunk: add_hunk | delete_hunk | update_hunk
add_hunk: "*** Add File: " filename LF add_line+
delete_hunk: "*** Delete File: " filename LF
update_hunk: "*** Update File: " filename LF change_move? change?

filename: /(.+)/
add_line: "+" /(.*)/ LF -> line

change_move: "*** Move to: " filename LF
change: (change_context | change_line)+ eof_line?
change_context: ("@@" | "@@ " /(.+)/) LF
change_line: ("+" | "-" | " ") /(.*)/ LF
eof_line: "*** End of File" LF

%import common.LF
"""

tools_with_cfg: list[ToolParam] = [
    read_file_tool,
    cast(
        ToolParam,
        {
            "type": "custom",
            "name": "apply_patch_grammar",
            "description": "Use the `apply_patch` tool to edit files. This is a FREEFORM tool, so do not wrap the patch in JSON.",
            "format": {
                "type": "grammar",
                "syntax": "lark",
                "definition": apply_patch_grammar,
            },
        },
    ),
]

response_cfg = client.responses.create(
    model="gpt-5.3-codex",
    input=input_items,
    tools=tools_with_cfg,
    parallel_tool_calls=False,
)

for item in response_cfg.output:
    if item.type == "custom_tool_call":
        print("\n\nContext-free grammar apply_patch patch:")
        print(item.input)
        #  Output
        # *** Begin Patch
        # *** Update File: /app/page.tsx
        # @@
        #      <div>
        #        <p>Page component not implemented</p>
        #        <button onClick={() => console.log("clicked")}>Click me</button>
        # +      <button onClick={() => console.log("cancel clicked")}>Cancel</button>
        #      </div>
        #    );
        #  }
        # *** End Patch

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60require "openai"

client = OpenAI::Client.new

input = <<~PROMPT
  Add a cancel button next to the save button in app/page.tsx.
  Current file contents:
  export default function Page() { return <button>Save</button>; }
PROMPT
response = client.responses.create(
  model: "gpt-5.3-codex", input: input,
  tools: [{ type: :apply_patch }], parallel_tool_calls: false
)
response.output.each do |item|
  pp(item.operation) if item.is_a?(OpenAI::Responses::ResponseApplyPatchToolCall)
end

APPLY_PATCH_GRAMMAR = <<~GRAMMAR

  start: begin_patch hunk+ end_patch
  begin_patch: "*** Begin Patch" LF
  end_patch: "*** End Patch" LF?

  hunk: add_hunk | delete_hunk | update_hunk
  add_hunk: "*** Add File: " filename LF add_line+
  delete_hunk: "*** Delete File: " filename LF
  update_hunk: "*** Update File: " filename LF change_move? change?

  filename: /(.+)/
  add_line: "+" /(.*)/ LF -> line

  change_move: "*** Move to: " filename LF
  change: (change_context | change_line)+ eof_line?
  change_context: ("@@" | "@@ " /(.+)/) LF
  change_line: ("+" | "-" | " ") /(.*)/ LF
  eof_line: "*** End of File" LF

  %import common.LF

GRAMMAR

response = client.responses.create(
  model: "gpt-5.3-codex", input: input,
  tools: [
    {
      type: :custom,
      name: "apply_patch",
      description: "Apply a patch to update files.",
      format: {
        type: :grammar,
        syntax: :lark,
        definition: APPLY_PATCH_GRAMMAR
      }
    }
  ],
  parallel_tool_calls: false
)
response.output.each do |item|
  puts(item.input) if item.is_a?(OpenAI::Responses::ResponseCustomToolCall)
end

你可以參考這個範例，實作 Responses API 工具修補物件的處理方式；自由格式工具產生的修補內容，則可透過我們標準 GPT-5 apply_patch.py 實作中的邏輯套用。

Shell_command

這是我們的預設 Shell 工具。請注意，我們觀察到，以「string」型別傳入指令，比傳入指令清單的效能更好。

1234567891011121314151617181920212223242526272829303132333435{
  "type": "function",
  "function": {
    "name": "shell_command",
    "description": "Runs a shell command and returns its output.\n- Always set the `workdir` param when using the shell_command function. Do not use `cd` unless absolutely necessary.",
    "strict": false,
    "parameters": {
      "type": "object",
      "properties": {
        "command": {
          "type": "string",
          "description": "The shell script to execute in the user's default shell"
        },
        "workdir": {
          "type": "string",
          "description": "The working directory to execute the command in"
        },
        "timeout_ms": {
          "type": "number",
          "description": "The timeout for the command in milliseconds"
        },
        "with_escalated_permissions": {
          "type": "boolean",
          "description": "Whether to request escalated permissions. Set to true if command needs to be run without sandbox restrictions"
        },
        "justification": {
          "type": "string",
          "description": "Only set if with_escalated_permissions is true. 1-sentence explanation of why we want to run this command."
        }
      },
      "required": ["command"],
      "additionalProperties": false
    }
  }
}

如果你使用 Windows PowerShell，請改用以下工具說明。

Runs a shell command and returns its output. The arguments you pass will be invoked via PowerShell (e.g., ["pwsh", "-NoLogo", "-NoProfile", "-Command", "<cmd>"]). Always fill in workdir; avoid using cd in the command string.

你可以參閱 codex-cli 中 exec_command 與 write_stdin 的實作。前者會在需要串流輸出、REPL 或互動式工作階段時啟動長時間存續的 PTY；後者則可向現有的 exec_command 工作階段傳送額外按鍵輸入，或僅輪詢輸出。

更新計畫

這是我們的預設待辦事項工具，你可以依喜好自訂。如需維持計畫條理與調整行為的更多指示，請參閱起始提示詞中的 ## Plan tool 一節。

123456789101112131415161718192021222324252627282930313233343536{
  "type": "function",
  "function": {
    "name": "update_plan",
    "description": "Updates the task plan.\nProvide an optional explanation and a list of plan items, each with a step and status.\nAt most one step can be in_progress at a time.",
    "strict": false,
    "parameters": {
      "type": "object",
      "properties": {
        "explanation": {
          "type": "string"
        },
        "plan": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "step": {
                "type": "string"
              },
              "status": {
                "type": "string",
                "description": "One of: pending, in_progress, completed"
              }
            },
            "additionalProperties": false,
            "required": ["step", "status"]
          },
          "description": "The list of steps"
        }
      },
      "additionalProperties": false,
      "required": ["plan"]
    }
  }
}

View_image

這是 codex-cli 中供模型檢視圖像的基本函式。

12345678910111213141516171819{
  "type": "function",
  "function": {
    "name": "view_image",
    "description": "Attach a local image (by filesystem path) to the conversation context for this turn.",
    "strict": false,
    "parameters": {
      "type": "object",
      "properties": {
        "path": {
          "type": "string",
          "description": "Local filesystem path to an image file"
        }
      },
      "additionalProperties": false,
      "required": ["path"]
    }
  }
}

封裝終端指令的專用工具

如果你希望 codex 智慧體使用封裝終端指令的工具（例如使用專用的 list_dir(‘.’) 工具，取代 terminal(‘ls .’)），通常也能有良好效果。我們發現，當工具名稱、引數與輸出盡可能接近底層指令時，效果最好，因為這最貼近模型的訓練資料分布；模型在訓練時主要使用的是專用終端工具。舉例來說，如果你注意到模型透過終端使用 git，卻希望它改用專用工具，我們發現只要建立相應工具，並在提示詞中明確要求 git 指令一律使用該工具，就能完全避免模型再透過終端執行 git 指令。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36GIT_TOOL = {
    "type": "function",
    "name": "git",
    "description": (
        "Execute a git command in the repository root. Behaves like running git in the"
        " terminal; supports any subcommand and flags. The command can be provided as a"
        " full git invocation (e.g., `git status -sb`) or just the arguments after git"
        " (e.g., `status -sb`)."
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "command": {
                "type": "string",
                "description": (
                    "The git command to execute. Accepts either a full git invocation or"
                    " only the subcommand/args."
                ),
            },
            "timeout_sec": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1800,
                "description": "Optional timeout in seconds for the git command.",
            },
        },
        "required": ["command"],
    },
}

TOOLS = [GIT_TOOL]

PROMPT_TOOL_USE_DIRECTIVE = (
    "- Strictly avoid raw `cmd`/terminal for Git operations. Use the dedicated "
    "`git` tool instead."
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28require "json"

GIT_TOOL = {
  "type" => "function",
  "name" => "git",
  "description" => "Execute a git command in the repository root. Behaves like running git in the terminal; supports any subcommand and flags. The command can be provided as a full git invocation (e.g., `git status -sb`) or just the arguments after git (e.g., `status -sb`).",
  "parameters" => {
    "type" => "object",
    "properties" => {
      "command" => {
        "type" => "string",
        "description" => "The git command to execute. Accepts either a full git invocation or only the subcommand/args."
      },
      "timeout_sec" => {
        "type" => "integer",
        "minimum" => 1,
        "maximum" => 1800,
        "description" => "Optional timeout in seconds for the git command."
      }
    },
    "required" => ["command"]
  }
}

TOOLS = [GIT_TOOL]
PROMPT_TOOL_USE_DIRECTIVE = "- Strictly avoid raw `cmd`/terminal for Git operations. Use the dedicated `git` tool instead."
puts(JSON.generate(TOOLS))
puts(PROMPT_TOOL_USE_DIRECTIVE)

其他自訂工具（網頁搜尋、語意搜尋、記憶等）

模型未必經過專門的後訓練來熟練使用這些工具，但我們也看過成功的案例。若要充分發揮這些工具的效用，我們建議：

1. 讓工具名稱和引數盡可能準確表達其語意。例如，「search」意義模糊，而「semantic_search」能清楚說明工具的用途，並與你可能提供的其他搜尋工具區分。「Query」則適合作為這個工具的參數名稱。
2. 在提示詞中明確說明何時、為何以及如何使用這些工具，並提供正確與錯誤的範例。
3. 讓結果的呈現方式有別於模型熟悉的其他工具輸出，也可能有所幫助。例如，ripgrep 結果與語意搜尋結果應有不同的呈現方式，以免模型又沿用舊有習慣。

平行工具呼叫

在 codex-cli 中啟用平行工具呼叫時，Responses API 請求會設定 parallel_tool_calls: true，並將下列片段加入系統指示：

## Exploration and reading files

- **Think first.** Before any tool call, decide ALL files/resources you will need.
- **Batch everything.** If you need multiple files (even from different places), read them together.
- **multi_tool_use.parallel** Use `multi_tool_use.parallel` to parallelize tool calls and only this.
- **Only make sequential calls if you truly cannot know the next file without seeing a result first.**
- **Workflow:** (a) plan all needed reads → (b) issue one parallel batch → (c) analyze results → (d) repeat if new, unpredictable reads arise.

**Additional notes**:
- Always maximize parallelism. Never read files one-by-one unless logically unavoidable.
- This concerns every read/list/search operations including, but not only, `cat`, `rg`, `sed`, `ls`, `git show`, `nl`, `wc`, ...
- Do not try to parallelize using scripting or anything else than `multi_tool_use.parallel`.

我們發現，依照下列方式排列平行工具呼叫項目及其回應，有助於模型運作，也更符合其訓練資料分布：

function_call
function_call
function_call_output
function_call_output

工具回應截斷

我們建議依照下列方式截斷工具呼叫回應，盡可能符合模型的訓練資料分布：

• 將上限設為 10,000 個 Token。你可以計算 num_bytes/4，以低成本估算 Token 數量。
• 若達到截斷上限，應將一半額度用於保留開頭，另一半用於保留結尾，並以 …3 tokens truncated… 標示中間截斷的部分。

GPT-5.3 Codex 的新功能

前導訊息

Responses API 提供 phase 參數，用來防止提示詞要求前導訊息時，模型提早停止或出現其他異常行為。使用 gpt-5.3-codex 時，必須正確實作此參數，否則模型表現可能大幅下降。

階段

為了更完善地支援 gpt-5.3-codex 的前導訊息，Responses API 提供 phase 欄位，用來防止模型在長時間執行的任務中提早停止或出現其他異常行為。

值

phase 為下列其中一個值：

• null
• "commentary"
• "final_answer"

出現位置

你會在助理輸出項目（例如 output_item.done）中收到 phase。你的整合實作必須儲存助理輸出項目及其 phase，並在後續請求中傳回這些助理項目。

重要： 只有助理項目支援 phase。請勿將 phase 加入使用者訊息。

後續處理方式

當模型使用下列值標記輸出項目時：

• phase: "commentary"：對應的助理訊息應視為進度說明或前導訊息類型的內容。
• phase: "final_answer"：對應的助理訊息應視為最終結語。

使用 gpt-5.3-codex 時，必須正確保留助理項目上的 phase。若在重建歷史紀錄時遺漏助理的 phase 中繼資料，模型表現可能大幅下降。

前導訊息與個性

前導訊息會隨工具呼叫一起傳送，在執行工作時向使用者提供最新進展。這些簡短易讀的訊息會說明目前進度與接下來的打算，讓使用者掌握狀況，又不至於讓對話紀錄變成工具呼叫日誌。GPT-5.3-Codex 的前導訊息經過調整，具備下列特點：

• 在任何工具呼叫之前，先回應使用者的需求，再說明計畫（用 1 句話回應，再用 1–2 句話說明計畫）。
• 大多數進度更新維持在 1–2 句，只有在真正的重要里程碑才使用較長的說明。
• 頻率：以每執行 1–3 個步驟更新一次為目標；最低要求是每 6 個步驟或 10 次工具呼叫內至少更新一次。
• 每次更新的內容：目前的成果與影響、接下來的 1–3 個步驟，以及尚待釐清的問題或新發現（如有）。
• 語氣：像真人夥伴一起協作，自然不拘形式；避免標題、狀態標籤和日誌式語氣。

個性（友善與務實）

個性決定整體互動氛圍與協作態度，層次高於前導訊息的具體機制（頻率、長度與接地）。它會影響用字遣詞、模型主動解釋取捨的程度，以及互動時的親切程度。

Codex App 和 CLI 內建支援兩種個性，這裡將它們作為實作範例，供你的任務執行框架參考。

友善

• 更有人情味，像夥伴般並肩協作。
• 會稍微多一些回應、安撫與背景說明。
• 適合使用者需要透過說明來掌握狀況的情境，例如初次上手、需求不明確的任務，或影響較大的變更。

codex-cli 的友善個性提示詞片段範例

你可以將這個片段加入系統提示詞，引導模型在結對程式設計時展現的個性。

# Personality

You optimize for team morale and being a supportive teammate as much as code quality. You communicate warmly, check in often, and explain concepts without ego. You excel at pairing, onboarding, and unblocking others. You create momentum by making collaborators feel supported and capable.

## Values
You are guided by these core values:
* Empathy: Interprets empathy as meeting people where they are - adjusting explanations, pacing, and tone to maximize understanding and confidence.
* Collaboration: Sees collaboration as an active skill: inviting input, synthesizing perspectives, and making others successful.
* Ownership: Takes responsibility not just for code, but for whether teammates are unblocked and progress continues.

## Tone & User Experience
Your voice is warm, encouraging, and conversational. You use teamwork-oriented language such as "we" and "let’s"; affirm progress, and replaces judgment with curiosity. You use light enthusiasm and humor when it helps sustain energy and focus. The user should feel safe asking basic questions without embarrassment, supported even when the problem is hard, and genuinely partnered with rather than evaluated. Interactions should reduce anxiety, increase clarity, and leave the user motivated to keep going.

You are NEVER curt or dismissive.

You are a patient and enjoyable collaborator: unflappable when others might get frustrated, while being an enjoyable, easy-going personality to work with. Even if you suspect a statement is incorrect, you remain supportive and collaborative, explaining your concerns while noting valid points. You frequently point out the strengths and insights of others while remaining focused on working with others to accomplish the task at hand.

## Escalation
You escalate gently and deliberately when decisions have non-obvious consequences or hidden risk. Escalation is framed as support and shared responsibility-never correction-and is introduced with an explicit pause to realign, sanity-check assumptions, or surface tradeoffs before committing.

務實

• 更精簡直接，著重完成並交付成果。
• 減少客套話，讓每個 Token 承載更多可付諸行動的資訊。
• 適合重視延遲或吞吐量的情境，或使用者已熟悉工作流程，只想看到進度與結果的情況。

疑難排解與元提示

我們持續專門追蹤的常見問題包括：

• 過度思考，或遲遲沒有採取第一個有用的行動（工具呼叫或具體計畫）。
• 狀態更新像日誌般生硬、不自然，缺乏結對程式設計夥伴的協作感。
• 前導訊息措辭彆扭，並反覆出現口頭禪（例如「你發現得好」、「啊哈」、「明白了……」等）。

使用元提示針對特定問題修正

上述問題通常可以透過元提示來解決。當某一輪的表現不如預期時，你可以在該輪結束後，詢問模型如何改善給它的指示。以下提示詞曾用來產生上述過度思考問題的部分解決方案，你可以依自己的需求修改。

That was a high quality response, thanks! It seemed like it took you a while to finish responding though. Is there a way to clarify your instructions so you can get to a response as good as this faster next time? It’s extremely important to be efficient when providing these responses or users won’t get the most out of them in time. Let’s see if we can improve!
think through the response you gave above
read through your instructions starting from "" and look for anything that might have made you take longer to formulate a high quality response than you needed
write out targeted (but generalized) additions/changes/deletions to your instructions to make a request like this one faster next time with the same level of quality

在特定上下文中使用元提示時，若情況允許，請務必多生成幾次回應，並留意這些回應的共同之處。模型提出的某些改善或變更可能過於針對當下情境，但通常可以加以簡化，整理出更通用的改善方式。我們建議建立評估，衡量特定提示詞變更對你的使用案例是有益還是有害。

範例

• 針對過度思考或起步緩慢的情況：請模型建議如何修改指示，以縮短首次工具呼叫或提出第一個具體計畫所需的時間。
• 針對過於像日誌的前導訊息：請模型改寫向使用者更新進度的指示，以符合你的特定偏好與限制。

簡介

GPT-5.2 推出時定位為通用旗艦模型，適用於一般任務與智慧體任務。相較於 GPT-5.1，它在下列方面有所提升：

• 通用智慧
• 指令遵循
• 準確度與 Token 使用效率
• 多模態能力，尤其是視覺能力
• 程式碼生成，尤其是前端 UI 建構
• API 中的工具呼叫與上下文管理
• 試算表理解與建立

相較於先前的 GPT-5.1 模型，GPT-5.2 新增了管理模型「知道」與「記得」哪些資訊的功能，以提升準確度。

本指南介紹 GPT-5 模型系列的主要功能，以及如何充分發揮 GPT-5.2 的能力。

探索程式設計範例

點選並試用幾個示範應用程式；它們完全由單一提示詞生成，無須手動撰寫任何程式碼。這些範例是由 GPT-5.2 或我們先前的旗艦模型 GPT-5 生成。

Explore

模型、API 與功能更新

GPT-5.2 這一代包含三款模型：gpt-5.2 適合需要廣泛世界知識的複雜任務，gpt-5.2-chat-latest 提供與 ChatGPT 一致的行為，而 gpt-5.2-pro 適合可藉由更多運算資源改善結果的問題。

若需要較小的模型，請使用 gpt-5-mini。

選擇最符合使用情境的模型時，請考量以下取捨：

GPT-5.2 的新功能

與 GPT-5.1 一樣，全新的 GPT-5.2 也提供自訂工具、控制詳細程度與推理的參數，以及允許使用的工具清單等 API 功能。5.2 新增了 xhigh 推理強度等級、精簡的推理摘要，以及運用 壓縮的新上下文管理方式。

本指南將介紹 GPT-5 模型系列的部分主要功能，並特別說明如何充分發揮 5.2 的能力。

針對程式設計任務，我們提供 GPT-5.2-Codex。這個版本經過程式設計最佳化，適用於 Codex 或類似 Codex 環境中的智慧體工作流程。

較低的推理強度

reasoning.effort 參數控制模型在產生回應之前生成多少推理 Token。o3 等較早期的推理模型僅支援 low、medium 和 high：low 著重速度與較少的 Token 用量，而 high 著重更周全的推理。

GPT-5.2 的最低設定為 none，可提供延遲更低的互動體驗。這也是 GPT-5.2 的預設設定。若需要更多思考，可逐步提高至 medium，並測試結果。

將推理強度設為 none 時，提示詞非常重要。即使使用預設設定，也可以鼓勵模型在回答前先「思考」或列出步驟，以提升推理品質。

1
2
3
4
5
6
7
8
9
10
11
12
13import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
  model: "gpt-5.2",
  input:
    "Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
  reasoning: {
    effort: "none",
  },
});

console.log(response);

1
2
3
4
5
6
7
8
9
10
11from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.2",
    input="Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
    reasoning={"effort": "none"},
)

print(response)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
	"github.com/openai/openai-go/v3/shared"
)

func main() {
	client := openai.NewClient()
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:     "gpt-5.2",
		Input:     responses.ResponseNewParamsInputUnion{OfString: openai.String("Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?")},
		Reasoning: shared.ReasoningParam{Effort: shared.ReasoningEffortNone},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.Reasoning;
import com.openai.models.ReasoningEffort;
import com.openai.models.responses.ResponseCreateParams;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-5.2")
        .input("Explain the bug and propose a fix.")
        .reasoning(Reasoning.builder().effort(ReasoningEffort.NONE).build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new()
{
    Model = "gpt-5.2",
    ReasoningOptions = new ResponseReasoningOptions
    {
        ReasoningEffortLevel = ResponseReasoningEffortLevel.None,
    },
};
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem(
        "Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?"
    )
);

ResponseResult response = await client.CreateResponseAsync(options);
Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-5.2",
  reasoning: { effort: :minimal },
  input: "Explain the bug and propose a fix."
)
puts(response.output_text)

1
2
3
4
5
6
7
8
9
10
11curl --request POST \
  --url https://api.openai.com/v1/responses \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header 'Content-type: application/json' \
  --data '{
        "model": "gpt-5.2",
        "input": "Think carefully and outline your steps before answering. How much gold would it take to coat the Statue of Liberty in a 1mm layer?",
        "reasoning": {
                "effort": "none"
        }
}'

詳細程度

詳細程度決定生成的輸出 Token 數量。減少 Token 數量可降低整體延遲。模型的推理方式大致不變，但會設法更精簡地回答；這可能提升或降低回答品質，取決於你的使用情境。以下是高、低詳細程度各自適合的情境：

• 高詳細程度： 適用於需要模型詳盡解釋文件或大幅重構程式碼的情境。
• 低詳細程度： 最適合需要精簡回答或針對特定目的生成程式碼的情境，例如 SQL 查詢。

GPT-5 開始允許將此選項設為 high、medium 或 low。在 GPT-5.2 中，詳細程度仍可設定，預設值為 medium。

使用 GPT-5.2 生成程式碼時，medium 和 high 詳細程度會產生較長、結構更清晰且附有行內說明的程式碼；low 詳細程度則會產生較短、更精簡的程式碼，並僅附少量說明。

1
2
3
4
5
6
7
8
9
10
11
12
13import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
  model: "gpt-5.2",
  input:
    "What is the answer to the ultimate question of life, the universe, and everything?",
  text: {
    verbosity: "low",
  },
});

console.log(response);

1
2
3
4
5
6
7
8
9
10
11from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.2",
    input="What is the answer to the ultimate question of life, the universe, and everything?",
    text={"verbosity": "low"},
)

print(response)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-5.2",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What is the answer to the ultimate question of life, the universe, and everything?")},
		Text:  responses.ResponseTextConfigParam{Verbosity: responses.ResponseTextConfigVerbosityLow},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseTextConfig;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-5.2")
        .input("Explain the bug and propose a fix.")
        .text(ResponseTextConfig.builder().verbosity(ResponseTextConfig.Verbosity.LOW).build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-5.2",
  text: { verbosity: :low },
  input: "Explain the bug and propose a fix."
)
puts(response.output_text)

1
2
3
4
5
6
7
8
9
10
11curl --request POST \
  --url https://api.openai.com/v1/responses \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header 'Content-type: application/json' \
  --data '{
  "model": "gpt-5.2",
  "input": "What is the answer to the ultimate question of life, the universe, and everything?",
  "text": {
    "verbosity": "low"
  }
}'

即使在 API 中將詳細程度設為 low，仍可透過提示詞加以調整。詳細程度參數會在系統提示詞層級定義大致的 Token 範圍，但實際輸出仍可在此範圍內，依開發者與使用者的提示詞彈性調整。

搭配 GPT-5.2 使用工具

GPT-5.2 已針對特定工具進行後訓練。如需更具體的指引，請參閱工具文件。

套用修補程式工具

apply_patch 工具可讓 GPT-5.2 使用結構化差異，在程式碼庫中建立、更新和刪除檔案。模型不只提供修改建議，還會輸出修補操作，由你的應用程式套用後回報結果，讓程式碼編輯工作流程能以多個步驟反覆進行。閱讀文件。

這項實作底層採用自由格式的函式呼叫，而非 JSON 格式。在測試中，這個具名函式讓 apply_patch 的失敗率降低了 35%。

Shell 工具

GPT-5.2 支援本機 Shell。Shell 工具可讓模型透過受控的指令列介面，與你的本機電腦互動。請閱讀文件以瞭解詳情。

自訂工具

GPT-5 模型系列推出時，我們引進了稱為「自訂工具」的新功能，讓模型能將任意原始文字作為工具呼叫的輸入，同時仍可視需要限制輸出。GPT-5.2 延續了這項工具行為。

自由格式輸入

使用 type: custom 定義工具，即可讓模型直接將純文字輸入傳送至工具，不再受限於結構化 JSON。模型可將任意原始文字直接傳送至工具，包括程式碼、SQL 查詢、Shell 指令、組態檔或長篇文章。

12345{
  "type": "custom",
  "name": "code_exec",
  "description": "Executes arbitrary python code"
}

限制輸出

GPT-5.2 的自訂工具支援上下文無關文法（CFGs），讓你能提供 Lark 文法，將輸出限制為特定語法或 DSL。附加 CFG（例如 SQL 或 DSL 文法）可確保助理的文字符合你定義的文法。

這可實現精確且受約束的工具呼叫或結構化回應，並讓你直接在 GPT-5.2 的函式呼叫中強制採用嚴格的語法或領域專用格式，提升複雜或受限領域中的可控性與可靠性。

自訂工具的最佳實務