跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenAI 提供 GPT 模型的開發者 API，而 Codex 也可透過 OpenAI 的 Codex 用戶端，作為 ChatGPT 方案的程式碼代理使用。OpenClaw 將這些介面分開，讓設定保持可預期。 OpenClaw 使用 openai/* 作為標準 OpenAI 模型路由。OpenAI 模型上的內嵌代理回合預設會透過原生 Codex 應用程式伺服器執行階段執行；直接 OpenAI API 金鑰驗證仍可用於非代理的 OpenAI 介面，例如影像、嵌入、語音和即時功能。
  • 代理模型 - 透過 Codex 執行階段使用 openai/* 模型；若要使用 ChatGPT/Codex 訂閱，請使用 Codex 驗證登入；若你刻意想使用 API 金鑰驗證，則設定 Codex 相容的 OpenAI API 金鑰備援。
  • 非代理 OpenAI API - 透過 OPENAI_API_KEY 或 OpenAI API 金鑰導入，直接存取 OpenAI Platform 並採用依使用量計費。
  • 舊版設定 - openai-codex/* 模型參照會由 openclaw doctor --fix 修復為 openai/* 加上 Codex 執行階段。
OpenAI 明確支援在 OpenClaw 這類外部工具和工作流程中使用訂閱 OAuth。 Provider、模型、執行階段和 channel 是分離的層。如果這些標籤混在一起，請先閱讀 Agent runtimes，再變更設定。

​
快速選擇

目標使用備註
搭配原生 Codex 執行階段的 ChatGPT/Codex 訂閱openai/gpt-5.5預設 OpenAI 代理設定。使用 Codex 驗證登入。
代理模型的直接 API 金鑰計費openai/gpt-5.5 加上 Codex 相容的 API 金鑰設定檔使用 auth.order.openai 將備援排在訂閱驗證之後。
透過明確 PI 的直接 API 金鑰計費openai/gpt-5.5 加上 provider/model 執行階段 pi選取一般的 openai API 金鑰設定檔。
最新 ChatGPT Instant API 別名openai/chat-latest僅限直接 API 金鑰。用於實驗的移動別名，不是預設值。
透過明確 PI 的 ChatGPT/Codex 訂閱驗證openai/gpt-5.5 加上 provider/model 執行階段 pi為相容性路由選取 openai-codex 驗證設定檔。
影像生成或編輯openai/gpt-image-2可搭配 OPENAI_API_KEY 或 OpenAI Codex OAuth 使用。
透明背景影像openai/gpt-image-1.5使用 outputFormat=png 或 webp，並設定 openai.background=transparent。

​
命名對照

這些名稱相似，但不可互換：
你看到的名稱層級含義
openaiProvider 前綴標準 OpenAI 模型路由；代理回合使用 Codex 執行階段。
openai-codex舊版驗證/設定檔前綴較舊的 OpenAI Codex OAuth/訂閱設定檔命名空間。既有設定檔和 auth.order.openai-codex 仍可運作。
codex pluginPlugin內建的 OpenClaw Plugin，提供原生 Codex 應用程式伺服器執行階段和 /codex 聊天控制。
provider/model agentRuntime.id: codex代理執行階段強制為符合條件的內嵌回合使用原生 Codex 應用程式伺服器 harness。
/codex ...聊天命令集從對話中繫結/控制 Codex 應用程式伺服器執行緒。
runtime: "acp", agentId: "codex"ACP 工作階段路由明確的備援路徑，會透過 ACP/acpx 執行 Codex。
這表示設定可以刻意包含 openai/* 模型參照，同時驗證設定檔仍指向 Codex 相容的憑證。新設定請優先使用 auth.order.openai；既有的 openai-codex:* 設定檔和 auth.order.openai-codex 仍受支援。openclaw doctor --fix 會將舊版 openai-codex/* 模型參照改寫為標準 OpenAI 模型路由。
GPT-5.5 可透過直接 OpenAI Platform API 金鑰存取和訂閱/OAuth 路由使用。若要使用 ChatGPT/Codex 訂閱加上原生 Codex 執行，請使用 openai/gpt-5.5；未設定執行階段時，現在會為 OpenAI 代理回合選取 Codex harness。只有在你想為 OpenAI 代理模型使用直接 API 金鑰驗證時，才使用 OpenAI API 金鑰設定檔。
OpenAI 代理模型回合需要內建的 Codex 應用程式伺服器 Plugin。明確 PI 執行階段設定仍可作為選用的相容性路由。當 PI 搭配 openai-codex 驗證設定檔明確選取時，OpenClaw 會將公開模型參照保留為 openai/*，並在內部透過舊版 Codex 驗證傳輸路由 PI。執行 openclaw doctor --fix 以修復過期的 openai-codex/* 模型參照，或不是來自明確執行階段設定的舊 PI 工作階段釘選。

​
OpenClaw 功能涵蓋範圍

OpenAI 能力OpenClaw 介面狀態
Chat / Responsesopenai/<model> 模型 Provider是
Codex 訂閱模型搭配 openai-codex OAuth 的 openai/<model>是
舊版 Codex 模型參照openai-codex/<model>由 doctor 修復為 openai/<model>
Codex 應用程式伺服器 harness未指定執行階段或 provider/model agentRuntime.id: codex 的 openai/<model>是
伺服器端網頁搜尋原生 OpenAI Responses 工具是，當網頁搜尋已啟用且未釘選 Provider 時
影像image_generate是
影片video_generate是
文字轉語音messages.tts.provider: "openai" / tts是
批次語音轉文字tools.media.audio / 媒體理解是
串流語音轉文字Voice Call streaming.provider: "openai"是
即時語音Voice Call realtime.provider: "openai" / Control UI Talk是
嵌入記憶嵌入 Provider是

​
記憶嵌入

OpenClaw 可使用 OpenAI 或 OpenAI 相容的嵌入端點，為 memory_search 建立索引和查詢嵌入： 
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
      },
    },
  },
}
對於需要非對稱嵌入標籤的 OpenAI 相容端點，請在 memorySearch 底下設定 queryInputType 和 documentInputType。OpenClaw 會將它們作為 Provider 專屬的 input_type 請求欄位轉送：查詢嵌入使用 queryInputType；已建立索引的記憶片段和批次索引使用 documentInputType。完整範例請參閱記憶設定參考。

​
開始使用

選擇你偏好的驗證方式，並依照設定步驟操作。
最適合： 直接 API 存取和依使用量計費。
1

Get your API key

從 OpenAI Platform dashboard 建立或複製 API 金鑰。
2

Run onboarding

openclaw onboard --auth-choice openai-api-key
或直接傳入金鑰：
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
3

Verify the model is available

openclaw models list --provider openai

​
路由摘要

模型參照執行階段設定路由驗證
openai/gpt-5.5omitted / provider/model agentRuntime.id: "codex"Codex 應用程式伺服器 harnessCodex 相容的 OpenAI 設定檔
openai/gpt-5.4-miniomitted / provider/model agentRuntime.id: "codex"Codex 應用程式伺服器 harnessCodex 相容的 OpenAI 設定檔
openai/gpt-5.5provider/model agentRuntime.id: "pi"PI 內嵌執行階段openai 設定檔或所選的 openai-codex 設定檔
openai/* 代理模型使用 Codex 應用程式伺服器 harness。若要為代理模型使用 API 金鑰驗證，請建立 Codex 相容的 API 金鑰設定檔，並用 auth.order.openai 排序；OPENAI_API_KEY 仍是非代理 OpenAI API 介面的直接備援。較舊的 auth.order.openai-codex 項目仍可運作。

​
設定範例

{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
}
若要從 OpenAI API 試用 ChatGPT 目前的 Instant 模型，請將模型設為 openai/chat-latest：
{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/chat-latest" } } },
}
chat-latest 是移動別名。OpenAI 文件將其描述為 ChatGPT 使用的最新 Instant 模型，並建議生產 API 用途使用 gpt-5.5，因此除非你明確想要該別名行為，否則請保留 openai/gpt-5.5 作為穩定預設值。該別名目前只接受 medium 文字詳細程度，因此 OpenClaw 會針對此模型正規化不相容的 OpenAI 文字詳細程度覆寫。
OpenClaw 不會公開 openai/gpt-5.3-codex-spark。即時 OpenAI API 請求會拒絕該模型，目前的 Codex 目錄也不會公開它。

​
原生 Codex 應用程式伺服器驗證

原生 Codex 應用程式伺服器執行框架使用 openai/* 模型參照，加上省略的執行階段設定或 provider/model agentRuntime.id: "codex"，但其驗證仍以帳戶為基礎。OpenClaw 依下列順序選取驗證：
  1. Agent 的已排序 OpenAI 驗證設定檔，最好位於 auth.order.openai 底下。現有的 openai-codex:* 設定檔與 auth.order.openai-codex 對較舊安裝仍然有效。
  2. 應用程式伺服器的現有帳戶，例如本機 Codex CLI ChatGPT 登入。
  3. 僅限本機 stdio 應用程式伺服器啟動時，在應用程式伺服器回報沒有帳戶且仍需要 OpenAI 驗證時，使用 CODEX_API_KEY，接著使用 OPENAI_API_KEY。
這表示本機 ChatGPT/Codex 訂閱登入不會只因為 Gateway 程序也有用於直接 OpenAI 模型或嵌入的 OPENAI_API_KEY 而被取代。Env API 金鑰備援只適用於本機 stdio 無帳戶路徑；它不會傳送到 WebSocket 應用程式伺服器連線。選取訂閱樣式的 Codex 設定檔時，OpenClaw 也會將 CODEX_API_KEY 與 OPENAI_API_KEY 排除在衍生的 stdio 應用程式伺服器子程序之外，並透過應用程式伺服器登入 RPC 傳送選取的憑證。當該訂閱設定檔受到 Codex 使用量限制封鎖時，OpenClaw 可以輪替到下一個排序後的 openai:* API 金鑰設定檔，而不變更選取的模型，也不離開 Codex 執行框架。訂閱重設時間過後，訂閱設定檔會再次符合資格。

​
圖像生成

內建的 openai Plugin 透過 image_generate 工具註冊圖像生成。它透過相同的 openai/gpt-image-2 模型參照，同時支援 OpenAI API 金鑰圖像生成與 Codex OAuth 圖像生成。
能力OpenAI API 金鑰Codex OAuth
模型參照openai/gpt-image-2openai/gpt-image-2
驗證OPENAI_API_KEYOpenAI Codex OAuth 登入
傳輸OpenAI Images APICodex Responses 後端
每個請求的最大圖像數44
編輯模式已啟用（最多 5 張參考圖像）已啟用（最多 5 張參考圖像）
尺寸覆寫支援，包含 2K/4K 尺寸支援，包含 2K/4K 尺寸
長寬比 / 解析度不轉送至 OpenAI Images API安全時對應至支援的尺寸
{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "openai/gpt-image-2" },
    },
  },
}
請參閱圖像生成，了解共用工具參數、提供者選取與容錯移轉行為。
gpt-image-2 是 OpenAI 文字轉圖像生成與圖像編輯的預設值。gpt-image-1.5、gpt-image-1 與 gpt-image-1-mini 仍可用作明確模型覆寫。若要輸出透明背景 PNG/WebP，請使用 openai/gpt-image-1.5；目前的 gpt-image-2 API 會拒絕 background: "transparent"。 對於透明背景請求，Agent 應呼叫 image_generate，並使用 model: "openai/gpt-image-1.5"、outputFormat: "png" 或 "webp"，以及 background: "transparent"；較舊的 openai.background 提供者選項仍受支援。OpenClaw 也會保護公開 OpenAI 與 OpenAI Codex OAuth 路由，將預設的 openai/gpt-image-2 透明請求重寫為 gpt-image-1.5；Azure 與自訂 OpenAI 相容端點會保留其已設定的部署/模型名稱。 相同設定也公開給無頭 CLI 執行使用： 
openclaw infer image generate \
  --model openai/gpt-image-1.5 \
  --output-format png \
  --background transparent \
  --prompt "A simple red circle sticker on a transparent background" \
  --json
從輸入檔開始時，請搭配 openclaw infer image edit 使用相同的 --output-format 與 --background 旗標。--openai-background 仍可作為 OpenAI 專屬別名使用。 對於 Codex OAuth 安裝，請保持相同的 openai/gpt-image-2 參照。設定 openai-codex OAuth 設定檔時，OpenClaw 會解析該儲存的 OAuth 存取權杖，並透過 Codex Responses 後端傳送圖像請求。它不會先嘗試 OPENAI_API_KEY，也不會為該請求靜默退回 API 金鑰。若要改用直接 OpenAI Images API 路由，請使用 API 金鑰、自訂基礎 URL 或 Azure 端點明確設定 models.providers.openai。 如果該自訂圖像端點位於受信任的 LAN/私人位址，也請設定 browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true；除非存在此選擇加入，否則 OpenClaw 會持續封鎖私人/內部 OpenAI 相容圖像端點。 生成： 
/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1
生成透明 PNG： 
/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent
編輯： 
/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536

​
影片生成

內建的 openai Plugin 會透過 video_generate tool 註冊影片生成。
能力值
預設模型openai/sora-2
模式文字轉影片、圖片轉影片、單一影片編輯
參考輸入1 張圖片或 1 支影片
尺寸覆寫支援
其他覆寫aspectRatio、resolution、audio、watermark 會被忽略並產生 tool 警告
{
  agents: {
    defaults: {
      videoGenerationModel: { primary: "openai/sora-2" },
    },
  },
}
請參閱影片生成，了解共用 tool 參數、提供者選擇與故障轉移行為。

​
GPT-5 提示貢獻

OpenClaw 會為跨提供者的 GPT-5 系列執行新增共用的 GPT-5 提示貢獻。它會依模型 ID 套用，因此 openai/gpt-5.5、舊版修復前參照例如 openai-codex/gpt-5.5、openrouter/openai/gpt-5.5、opencode/gpt-5.5，以及其他相容的 GPT-5 參照都會收到相同的覆蓋層。較舊的 GPT-4.x 模型不會套用。 內建的原生 Codex harness 會透過 Codex app-server 開發者指示使用相同的 GPT-5 行為與 Heartbeat 覆蓋層，因此透過 Codex 路由的 openai/gpt-5.x 工作階段，即使 Codex 擁有其餘 harness 提示，仍會保留相同的後續執行與主動 Heartbeat 指引。 GPT-5 貢獻會新增帶標籤的行為合約，涵蓋人格持續性、執行安全、tool 紀律、輸出形狀、完成檢查與驗證。通道特定的回覆與靜默訊息行為會留在共用 OpenClaw 系統提示與出站傳遞政策中。GPT-5 指引一律會對相符模型啟用。友善互動風格層是獨立且可設定的。
值效果
"friendly"（預設）啟用友善互動風格層
"on""friendly" 的別名
"off"僅停用友善風格層
{
  agents: {
    defaults: {
      promptOverlays: {
        gpt5: { personality: "friendly" },
      },
    },
  },
}
值在執行階段不區分大小寫，因此 "Off" 和 "off" 都會停用友善風格層。
當共用的 agents.defaults.promptOverlays.gpt5.personality 設定未設定時，仍會讀取舊版 plugins.entries.openai.config.personality 作為相容性後援。

​
語音與 speech

內建的 openai Plugin 會為 messages.tts 介面註冊語音合成。
設定設定路徑預設值
模型messages.tts.providers.openai.modelgpt-4o-mini-tts
語音messages.tts.providers.openai.voicecoral
速度messages.tts.providers.openai.speed（未設定）
指示messages.tts.providers.openai.instructions（未設定，僅限 gpt-4o-mini-tts）
格式messages.tts.providers.openai.responseFormat語音備註使用 opus，檔案使用 mp3
API 金鑰messages.tts.providers.openai.apiKey後援至 OPENAI_API_KEY
基底 URLmessages.tts.providers.openai.baseUrlhttps://api.openai.com/v1
額外主體messages.tts.providers.openai.extraBody / extra_body（未設定）
可用模型：gpt-4o-mini-tts、tts-1、tts-1-hd。可用語音：alloy、ash、ballad、cedar、coral、echo、fable、juniper、marin、onyx、nova、sage、shimmer、verse。extraBody 會在 OpenClaw 產生的欄位之後合併到 /audio/speech 請求 JSON，因此可將它用於需要額外鍵（例如 lang）的 OpenAI 相容端點。Prototype 鍵會被忽略。
{
  messages: {
    tts: {
      providers: {
        openai: { model: "gpt-4o-mini-tts", voice: "coral" },
      },
    },
  },
}
設定 OPENAI_TTS_BASE_URL 可覆寫 TTS 基底 URL，且不影響聊天 API 端點。OpenAI TTS 仍透過 API 金鑰設定；若要使用僅 OAuth 的即時語音回覆，請使用 Realtime 語音路徑，而不是 agent 模式的 STT -> TTS speech。
內建的 openai Plugin 會透過 OpenClaw 的媒體理解轉錄介面註冊批次語音轉文字。
  • 預設模型：gpt-4o-transcribe
  • 端點：OpenAI REST /v1/audio/transcriptions
  • 輸入路徑：multipart 音訊檔案上傳
  • OpenClaw 中任何使用入站音訊轉錄的地方都支援， 包含 Discord 語音通道片段和通道 音訊附件，且會使用 tools.media.audio
若要強制入站音訊轉錄使用 OpenAI：
{
  tools: {
    media: {
      audio: {
        models: [
          {
            type: "provider",
            provider: "openai",
            model: "gpt-4o-transcribe",
          },
        ],
      },
    },
  },
}
當共用音訊媒體設定或每次呼叫的轉錄請求提供語言和提示提示時，這些內容會轉送給 OpenAI。
內建的 openai Plugin 會為 Voice Call Plugin 註冊即時轉錄。
設定設定路徑預設值
模型plugins.entries.voice-call.config.streaming.providers.openai.modelgpt-4o-transcribe
語言...openai.language(未設定)
提示...openai.prompt(未設定)
靜音持續時間...openai.silenceDurationMs800
VAD 閾值...openai.vadThreshold0.5
驗證...openai.apiKey、OPENAI_API_KEY 或 openai-codex OAuthAPI 金鑰會直接連線；OAuth 會鑄造 Realtime 轉錄用戶端密鑰
使用 WebSocket 連線至 wss://api.openai.com/v1/realtime，並採用 G.711 u-law (g711_ulaw / audio/pcmu) 音訊。當只設定了 openai-codex OAuth 時，Gateway 會先鑄造暫時性的 Realtime 轉錄用戶端密鑰，再開啟 WebSocket。這個串流提供者用於 Voice Call 的即時轉錄路徑；Discord 語音目前會錄製短片段，並改用批次 tools.media.audio 轉錄路徑。
內建的 openai Plugin 會為 Voice Call Plugin 註冊即時語音。
設定設定路徑預設值
模型plugins.entries.voice-call.config.realtime.providers.openai.modelgpt-realtime-2
語音...openai.voicealloy
溫度 (Azure 部署橋接)...openai.temperature0.8
VAD 閾值...openai.vadThreshold0.5
靜音持續時間...openai.silenceDurationMs500
前綴填補...openai.prefixPaddingMs300
推理強度...openai.reasoningEffort(未設定)
驗證...openai.apiKey、OPENAI_API_KEY 或 openai-codex OAuthBrowser Talk 和非 Azure 後端橋接可以使用 Codex OAuth
gpt-realtime-2 可用的內建 Realtime 語音：alloy、ash、 ballad、coral、echo、sage、shimmer、verse、marin、cedar。 OpenAI 建議使用 marin 和 cedar 以取得最佳 Realtime 品質。這 與上方的文字轉語音語音是不同集合；不要假設像 fable、 nova 或 onyx 這類 TTS 語音可用於 Realtime 工作階段。
後端 OpenAI 即時橋接使用 GA Realtime WebSocket 工作階段形態，不接受 session.temperature。Azure OpenAI 部署仍可透過 azureEndpoint 和 azureDeployment 使用，並保留與部署相容的工作階段形態。支援雙向工具呼叫和 G.711 u-law 音訊。
即時語音會在建立工作階段時選取。OpenAI 允許多數 工作階段欄位稍後變更，但模型在該工作階段中發出音訊後， 語音就無法再變更。OpenClaw 目前將內建 Realtime 語音 ID 以字串公開。
Control UI Talk 使用 OpenAI 瀏覽器即時工作階段，搭配 Gateway 鑄造的 暫時性用戶端密鑰，以及瀏覽器直接對 OpenAI Realtime API 進行的 WebRTC SDP 交換。未設定直接 OpenAI API 金鑰時， Gateway 可以使用所選的 openai-codex OAuth 設定檔鑄造該用戶端密鑰。Gateway 中繼和 Voice Call 後端即時 WebSocket 橋接 對原生 OpenAI 端點使用相同的 OAuth 後備。維護者可透過 OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts 進行即時驗證；OpenAI 分支會驗證後端 WebSocket 橋接和瀏覽器 WebRTC SDP 交換，且不記錄密鑰。

​
Azure OpenAI 端點

內建的 openai 提供者可以透過覆寫基底 URL，將影像 生成導向 Azure OpenAI 資源。在影像生成路徑上，OpenClaw 會偵測 models.providers.openai.baseUrl 上的 Azure 主機名稱，並自動切換為 Azure 的請求形態。
即時語音使用獨立的設定路徑 (plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint)， 且不受 models.providers.openai.baseUrl 影響。其 Azure 設定請參閱 語音與語音功能 下方的即時 語音摺疊區塊。
在下列情況使用 Azure OpenAI：
  • 你已經有 Azure OpenAI 訂閱、配額或企業合約
  • 你需要 Azure 提供的區域資料駐留或合規控制
  • 你想將流量保留在既有的 Azure 租用戶內

​
設定

若要透過內建的 openai 提供者使用 Azure 影像生成，請將 models.providers.openai.baseUrl 指向你的 Azure 資源，並將 apiKey 設為 Azure OpenAI 金鑰 (不是 OpenAI Platform 金鑰)： 
{
  models: {
    providers: {
      openai: {
        baseUrl: "https://<your-resource>.openai.azure.com",
        apiKey: "<azure-openai-api-key>",
      },
    },
  },
}
OpenClaw 會針對 Azure 影像生成路由辨識以下 Azure 主機尾碼：
  • *.openai.azure.com
  • *.services.ai.azure.com
  • *.cognitiveservices.azure.com
對於辨識出的 Azure 主機上的影像生成請求，OpenClaw 會：
  • 傳送 api-key 標頭，而不是 Authorization: Bearer
  • 使用部署範圍路徑 (/openai/deployments/{deployment}/...)
  • 將 ?api-version=... 附加至每個請求
  • 對 Azure 影像生成呼叫使用 600 秒的預設請求逾時。 每次呼叫的 timeoutMs 值仍會覆寫此預設值。
其他基底 URL (公開 OpenAI、OpenAI 相容代理) 會保留標準的 OpenAI 影像請求形態。
openai 提供者影像生成路徑的 Azure 路由需要 OpenClaw 2026.4.22 或更新版本。較早版本會將任何自訂 openai.baseUrl 視為公開 OpenAI 端點，並且在對 Azure 影像部署使用時失敗。

​
API 版本

設定 AZURE_OPENAI_API_VERSION，為 Azure 圖片生成路徑釘選特定的 Azure 預覽版或 GA 版本： 
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
未設定此變數時，預設值為 2024-12-01-preview。

​
模型名稱就是部署名稱

Azure OpenAI 會將模型繫結到部署。對於透過內建 openai provider 路由的 Azure 圖片生成請求，OpenClaw 中的 model 欄位必須是你在 Azure 入口網站中設定的 Azure 部署名稱，而不是公開的 OpenAI 模型 ID。 如果你建立了一個名為 gpt-image-2-prod、提供 gpt-image-2 服務的部署： 
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
相同的部署名稱規則也適用於透過內建 openai provider 路由的圖片生成呼叫。

​
區域可用性

Azure 圖片生成目前僅在部分區域可用（例如 eastus2、swedencentral、polandcentral、westus3、uaenorth）。建立部署前，請查看 Microsoft 目前的區域清單，並確認你的區域提供該特定模型。

​
參數差異

Azure OpenAI 和公開 OpenAI 並不一定接受相同的圖片參數。Azure 可能會拒絕公開 OpenAI 允許的選項（例如 gpt-image-2 上的某些 background 值），或僅在特定模型版本上公開這些選項。這些差異來自 Azure 和底層模型，而不是 OpenClaw。如果 Azure 請求因驗證錯誤而失敗，請在 Azure 入口網站中查看你的特定部署和 API 版本所支援的參數集合。
Azure OpenAI 使用原生傳輸與相容行為，但不會收到 OpenClaw 的隱藏歸因標頭 — 請參閱 進階設定 下的 原生與 OpenAI 相容路由 手風琴區塊。對於 Azure 上的聊天或 Responses 流量（圖片生成以外），請使用上線流程或專用的 Azure provider 設定 — 單獨設定 openai.baseUrl 不會套用 Azure API/驗證形式。另有一個獨立的 azure-openai-responses/* provider；請參閱下方的伺服器端 Compaction 手風琴區塊。

​
進階設定

OpenClaw 對 openai/* 採用 WebSocket 優先，並以 SSE 作為備援（"auto"）。在 "auto" 模式下，OpenClaw：
  • 在回退到 SSE 之前，會重試一次早期 WebSocket 失敗
  • 失敗後，將 WebSocket 標記為降級約 60 秒，並在冷卻期間使用 SSE
  • 為重試與重新連線附加穩定的工作階段與回合識別標頭
  • 在不同傳輸變體之間正規化用量計數器（input_tokens / prompt_tokens）
值行為
"auto"（預設）WebSocket 優先，SSE 備援
"sse"僅強制使用 SSE
"websocket"僅強制使用 WebSocket
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { transport: "auto" },
        },
      },
    },
  },
}
相關 OpenAI 文件：
OpenClaw 為 openai/* 公開共用的快速模式切換：
  • 聊天/UI： /fast status|on|off
  • 設定： agents.defaults.models["<provider>/<model>"].params.fastMode
啟用後，OpenClaw 會將快速模式對應到 OpenAI 優先處理（service_tier = "priority"）。現有的 service_tier 值會保留，且快速模式不會改寫 reasoning 或 text.verbosity。
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": { params: { fastMode: true } },
      },
    },
  },
}
工作階段覆寫會優先於設定。清除工作階段 UI 中的工作階段覆寫後，工作階段會回到已設定的預設值。
OpenAI 的 API 透過 service_tier 提供優先處理。在 OpenClaw 中為每個模型設定：
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": { params: { serviceTier: "priority" } },
      },
    },
  },
}
支援的值：auto、default、flex、priority。
serviceTier 只會轉送到原生 OpenAI 端點 (api.openai.com) 和原生 Codex 端點 (chatgpt.com/backend-api)。如果你透過代理路由任一提供者，OpenClaw 會讓 service_tier 保持不變。
對於直接 OpenAI Responses 模型（api.openai.com 上的 openai/*），OpenAI Plugin 的 Pi-harness 串流包裝器會自動啟用伺服器端 Compaction：
  • 強制 store: true（除非模型相容性設定 supportsStore: false）
  • 注入 context_management: [{ type: "compaction", compact_threshold: ... }]
  • 預設 compact_threshold：contextWindow 的 70%（無法取得時為 80000）
這適用於內建 Pi harness 路徑，以及嵌入式執行所使用的 OpenAI 提供者掛鉤。原生 Codex 應用程式伺服器 harness 會透過 Codex 管理自己的上下文，並由 OpenAI 的預設代理路由或提供者/模型執行階段政策設定。
適用於 Azure OpenAI Responses 等相容端點：
{
  agents: {
    defaults: {
      models: {
        "azure-openai-responses/gpt-5.5": {
          params: { responsesServerCompaction: true },
        },
      },
    },
  },
}
responsesServerCompaction 只控制 context_management 注入。直接 OpenAI Responses 模型仍會強制 store: true，除非相容性設定 supportsStore: false。
對於 openai/* 上的 GPT-5 系列執行，OpenClaw 可以使用更嚴格的嵌入式執行合約：
{
  agents: {
    defaults: {
      embeddedPi: { executionContract: "strict-agentic" },
    },
  },
}
使用 strict-agentic 時，OpenClaw 會：
  • 當工具動作可用時，不再將僅有計畫的回合視為成功進展
  • 以立即行動引導重試該回合
  • 對大量工作自動啟用 update_plan
  • 如果模型持續規劃而不行動，顯示明確的受阻狀態
僅限於 OpenAI 和 Codex GPT-5 系列執行。其他提供者和較舊的模型系列維持預設行為。
OpenClaw 對直接 OpenAI、Codex 和 Azure OpenAI 端點的處理方式，不同於通用 OpenAI 相容的 /v1 代理：原生路由（openai/*、Azure OpenAI）：
  • 只對支援 OpenAI none 推理 effort 的模型保留 reasoning: { effort: "none" }
  • 對拒絕 reasoning.effort: "none" 的模型或代理省略已停用的推理
  • 預設將工具結構描述設為嚴格模式
  • 只在已驗證的原生主機上附加隱藏的歸因標頭
  • 保留 OpenAI 專用的請求塑形（service_tier、store、推理相容性、提示快取提示）
代理/相容路由：
  • 使用較寬鬆的相容行為
  • 從非原生 openai-completions 酬載中移除 Completions store
  • 接受進階 params.extra_body/params.extraBody 直通 JSON，用於 OpenAI 相容的 Completions 代理
  • 接受 params.chat_template_kwargs，用於 vLLM 等 OpenAI 相容的 Completions 代理
  • 不強制使用嚴格工具結構描述或僅限原生的標頭
Azure OpenAI 使用原生傳輸和相容行為，但不會接收隱藏的歸因標頭。

​
相關內容

模型選擇

選擇提供者、模型參照和容錯移轉行為。

影像生成

共用影像工具參數和提供者選擇。

影片生成

共用影片工具參數和提供者選擇。

OAuth 與驗證

驗證詳細資料和憑證重複使用規則。