Skip to content
OpenClaw Docs

OpenAI

OpenAI 提供 GPT 模型的開發者 API，並且透過 OpenAI 的 Codex 用戶端，Codex 也可作為 ChatGPT 方案的程式撰寫代理程式使用。OpenClaw 使用一個提供者 ID，即 openai，來處理這兩種驗證形態。

OpenClaw 使用 openai/* 作為標準的 OpenAI 模型路由。嵌入式代理程式預設會透過原生 Codex 應用程式伺服器執行階段來啟動 OpenAI 模型；對於非代理程式的 OpenAI 介面（例如圖片、嵌入、語音與即時功能），則仍可使用直接的 OpenAI API 金鑰驗證。

  • 代理程式模型 - 透過 Codex 執行階段使用 openai/* 模型；登入 Codex 驗證以使用 ChatGPT/Codex 訂閱，或者當您刻意想要使用 API 金鑰驗證時，設定相容 Codex 的 OpenAI API 金鑰備援。
  • 非代理程式 OpenAI API - 透過 OPENAI_API_KEY 或 OpenAI API 金鑰加入，直接存取 OpenAI Platform 並依使用量計費。
  • 舊版設定 - 舊版 Codex 模型參照會由 openclaw doctor --fix 修復為 openai/* 並加上 Codex 執行階段。

OpenAI 明確支援在外部工具和工作流程（如 OpenClaw）中使用訂閱 OAuth。

提供者、模型、執行階段與管道是分層的。如果這些標籤混淆在一起，請在變更設定前先閱讀 代理程式執行階段。

快速選擇

Section titled “快速選擇”
目標使用備註
使用原生 Codex 執行時的 ChatGPT/Codex 訂閱openai/gpt-5.5預設的 OpenAI 代理設定。使用 Codex 驗證登入。
代理模型的直接 API 金鑰計費openai/gpt-5.5 加上相容 Codex 的 API 金鑰設定檔使用 auth.order.openai 將備份放在訂閱驗證之後。
透過明確的 OpenClaw 直接使用 API 金鑰計費openai/gpt-5.5 加上提供者/模型運行時 openclaw選擇標準的 openai API 金鑰設定檔。
最新的 ChatGPT Instant API 別名openai/chat-latest僅限直接 API 金鑰。用於實驗的變動別名，非預設值。
透過 OpenClaw 使用 ChatGPT/Codex 訂閱驗證openai/gpt-5.5 加上提供者/模型運行時 openclaw為相容性路由選取一個 openai OAuth 設定檔。
圖片生成或編輯openai/gpt-image-2可與 OPENAI_API_KEY 或 OpenAI Codex OAuth 搭配使用。
透明背景圖片openai/gpt-image-1.5使用 outputFormat=png 或 webp 和 openai.background=transparent。

命名對照

Section titled “命名對照”

名稱相似但不可互換：

您看到的名稱層級含義
openai供應商前綴標準的 OpenAI 模型路由；代理回合使用 Codex 執行時。
legacy OpenAI Codex prefixLegacy prefix舊版模型/設定檔命名空間。openclaw doctor --fix 會將其遷移至 openai。
codex 插件外掛內建的 OpenClaw 插件，提供原生 Codex 應用伺服器執行時和 /codex 聊天控制。
provider/model agentRuntime.id: codex代理執行時為匹配的內嵌回合強制使用原生 Codex 應用伺服器框架。
/codex ...聊天指令集從對話中綁定/控制 Codex 應用伺服器執行緒。
runtime: "acp", agentId: "codex"ACP 會話路由透過 ACP/acpx 執行 Codex 的明確備援路徑。

這意味著設定檔可以刻意包含 openai/* 模型參照，同時驗證設定檔指向 API 金鑰或 ChatGPT/Codex OAuth 憑證。請使用 auth.order.openai 進行設定；openclaw doctor --fix 會將舊版 Codex 模型參照、舊版 Codex 驗證設定檔 ID 和舊版 Codex 驗證順序重寫為標準 OpenAI 路由。

OpenClaw 功能支援

Section titled “OpenClaw 功能支援”
OpenAI 功能OpenClaw 介面狀態
聊天 / 回應openai/<model> 模型提供者是
Codex 訂閱模型openai/<model> 搭配 OpenAI OAuth是
傳統 Codex 模型參照舊版 Codex 模型參照或 codex-cli/<model>由 doctor 修復為 openai/<model>
Codex app-server 掛接openai/<model> 搭配省略的執行時或提供者/模型 agentRuntime.id: codex是
伺服器端網路搜尋原生 OpenAI Responses 工具是，當啟用網路搜尋且未釘選提供者時
圖片image_generate是
影片video_generate是
文字轉語音messages.tts.provider: "openai" / tts是
批次語音轉文字tools.media.audio / 媒體理解是
串流語音轉文字語音通話 streaming.provider: "openai"是
即時語音語音通話 realtime.provider: "openai" / 控制介面對話 talk.realtime.provider: "openai"是（需要 OpenAI Platform 點數，而非 Codex/ChatGPT 訂閱）
嵌入向量記憶體嵌入向量提供者是

記憶嵌入

Section titled “記憶嵌入”

OpenClaw 可以使用 OpenAI 或相容 OpenAI 的嵌入端點來進行 memory_search 索引和查詢嵌入：

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
      },
    },
  },
}

對於需要非對稱嵌入標籤的 OpenAI 相容端點，請在 memorySearch 下設定 queryInputType 和 documentInputType。OpenClaw 會將這些作為供應商特定的 input_type 請求欄位轉發：查詢嵌入使用 queryInputType；已索引的記憶區塊和批次索引則使用 documentInputType。請參閱 Memory configuration reference 以取得完整範例。

開始使用

Section titled “開始使用”

選擇您偏好的驗證方式並依照設定步驟操作。

最適合用於： 直接存取 API 與依用量計費。

  1. 取得您的 API 金鑰

    從 OpenAI Platform 儀表板 建立或複製 API 金鑰。

  2. 執行導覽設定

    Terminal window
    openclaw onboard --auth-choice openai-api-key

    或直接傳入金鑰：

    Terminal window
    openclaw onboard --openai-api-key "$OPENAI_API_KEY"

  3. 驗證模型是否可用

    Terminal window
    openclaw models list --provider openai

路由摘要

Section titled “路由摘要”
模型參照執行時期設定路由驗證
openai/gpt-5.5省略 / provider/model agentRuntime.id: "codex"Codex app-server harness相容 Codex 的 OpenAI 設定檔
openai/gpt-5.4-mini省略 / provider/model agentRuntime.id: "codex"Codex app-server harness相容 Codex 的 OpenAI 設定檔
openai/gpt-5.5provider/model agentRuntime.id: "openclaw"OpenClaw embedded runtime選定的 openai 設定檔

設定範例

Section titled “設定範例”
{
  env: { OPENAI_API_KEY: "example-openai-key-not-real" },
  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
}

若要透過 OpenAI API 嘗試 ChatGPT 目前的 Instant 模型，請將模型設定為 openai/chat-latest：

{
  env: { OPENAI_API_KEY: "example-openai-key-not-real" },
  agents: { defaults: { model: { primary: "openai/chat-latest" } } },
}

chat-latest 是一個動態別名。OpenAI 將其記錄為 ChatGPT 中使用的最新 Instant 模型，並建議在正式環境 API 使用中採用 gpt-5.5，因此除非您明確需要該別名行為，否則請將 openai/gpt-5.5 保持為穩定的預設值。該別名目前僅接受 medium 文本細緻度，因此 OpenClaw 會針對此模型正規化不相容的 OpenAI 文本細緻度覆寫。

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

Section titled “原生 Codex 應用程式伺服器驗證”

原生 Codex 應用程式伺服器配接器使用 openai/* 模型引用加上省略的執行時期組態或提供者/模型 agentRuntime.id: "codex"，但其身分驗證仍然是基於帳戶的。OpenClaw 會按以下順序選擇身分驗證：

  1. 為代理程式排序的 OpenAI 身分驗證設定檔，最好位於 auth.order.openai 之下。執行 openclaw doctor --fix 以遷移較舊的 舊版 Codex 身分驗證設定檔 ID 和舊版 Codex 身分驗證順序。
  2. 應用程式伺服器的現有帳戶，例如本機 Codex CLI ChatGPT 登入。
  3. 僅限於本地 stdio 應用程式伺服器啟動，CODEX_API_KEY，然後是 OPENAI_API_KEY，當應用程式伺服器回報沒有帳戶但仍需要 OpenAI 身分驗證時。

這意味著本地的 ChatGPT/Codex 訂閱登入不會僅僅因為閘道程序也有用於直接 OpenAI 模型或嵌入的 OPENAI_API_KEY 而被取代。環境變數 API 金鑰後備僅是本地 stdio 無帳戶路徑；它不會被傳送到 WebSocket 應用程式伺服器連線。當選擇了訂閱式的 Codex 設定檔時，OpenClaw 也會將 CODEX_API_KEY 和 OPENAI_API_KEY 排除在產生的 stdio 應用程式伺服器子程序之外，並透過應用程式伺服器登入 RPC 傳送選定的認證。當該訂閱設定檔被 Codex 使用限制封鎖時，OpenClaw 可以輪替到下一個排序的 openai:* API 金鑰設定檔，而無需變更選定的模型或退出 Codex 配接器。一旦訂閱重設時間通過，訂閱設定檔便再次有資格使用。

影像生成

Section titled “影像生成”

內建的 openai 外掛程式透過 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 仍可作為明確的模型覆寫使用。使用 openai/gpt-image-1.5 以取得透明背景的 PNG/WebP 輸出；目前的 gpt-image-2 API 會拒絕 background: "transparent"。

對於透明背景請求，代理程式應呼叫 image_generate 並搭配 model: "openai/gpt-image-1.5"、outputFormat: "png" 或 "webp"，以及 background: "transparent"；較舊的 openai.background 提供者選項仍被接受。OpenClaw 也透過將預設的 openai/gpt-image-2 透明請求重寫為 gpt-image-1.5，來保護公開的 OpenAI 和 OpenAI Codex OAuth 路由；Azure 和自訂的 OpenAI 相容端點會保留其設定的部署/模型名稱。

相同的設定也會公開給無頭 CLI 執行使用：

Terminal window
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

當從輸入檔案開始時，請將相同的 --output-format 和 --background 旗標與 openclaw infer image edit 搭配使用。--openai-background 仍可作為 OpenAI 專用的別名使用。

對於 ChatGPT/Codex OAuth 安裝，請保留相同的 openai/gpt-image-2 參照。當設定 openai 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

視訊生成

Section titled “視訊生成”

隨附的 openai 外掛程式透過 video_generate 工具註冊影片生成功能。

功能數值
預設模型openai/sora-2
模式文字轉視訊、圖像轉視訊、單一視訊編輯
參考輸入1 張圖像或 1 個視訊
尺寸覆寫支援文字轉視訊和圖像轉視訊
其他覆寫aspectRatio、resolution、audio、watermark 將被忽略，並顯示工具警告

OpenAI 影片轉影片請求會使用帶有影像 input_reference 的 POST /v1/videos。單一影片編輯會使用帶有上傳影片在 video 欄位中的 POST /v1/videos/edits。

{
  agents: {
    defaults: {
      videoGenerationModel: { primary: "openai/sora-2" },
    },
  },
}

GPT-5 提示詞貢獻

Section titled “GPT-5 提示詞貢獻”

OpenClaw 為 OpenClaw 組合的提示介面上執行的 GPT-5 系列模型，新增了共享的 GPT-5 提示貢獻。此貢獻依模型 ID 套用，因此 OpenClaw/提供者路由（例如舊版修復前參照（舊版 Codex GPT-5.5 參照）、openrouter/openai/gpt-5.5、opencode/gpt-5.5 和其他相容的 GPT-5 參照）會收到相同的疊加層。舊版 GPT-4.x 模型則不會。

隨附的原生 Codex 鞍座不會透過 Codex app-server 開發者指令接收此 OpenClaw GPT-5 覆蓋層。原生 Codex 保留 Codex 擁有的基礎、模型和專案文件行為，而 OpenClaw 會對原生執行緒停用 Codex 的內建個性，以便代理程式工作區個性檔案保持權威性。OpenClaw 僅貢獻執行階段內容，例如管道交付、OpenClaw 動態工具、ACP 委派、工作區內容和 OpenClaw 技能。

GPT-5 貢獻會為個體持久性、執行安全性、工具紀律、輸出形狀、完成檢查以及對比符合 OpenClaw 組合提示的驗證，新增標記的行為合約。特定管道的回覆和無訊息行為保留在共用的 OpenClaw 系統提示和輸出交付原則中。友善的互動風格層是分開的，且可設定。

值效果
"friendly" (預設)啟用友善的互動風格層
"on""friendly" 的別名
"off"僅停用友善風格層
{
  agents: {
    defaults: {
      promptOverlays: {
        gpt5: { personality: "friendly" },
      },
    },
  },
}

語音和語音

Section titled “語音和語音”
語音合成 (TTS)

內建的 openai 外掛程式會為 messages.tts 介面註冊語音合成功能。

設定設定路徑預設值
模型messages.tts.providers.openai.modelgpt-4o-mini-tts
語音messages.tts.providers.openai.speakerVoicecoral
速度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 中，因此請將其用於需要額外金鑰的 OpenAI 相容端點，例如 lang。Prototype 金鑰會被忽略。

{
  messages: {
    tts: {
      providers: {
        openai: { model: "gpt-4o-mini-tts", speakerVoice: "coral" },
      },
    },
  },
}
語音轉文字

內建的 openai 外掛程式透過 OpenClaw 的媒體理解轉錄介面註冊批次語音轉文字。

  • 預設模型：gpt-4o-transcribe
  • 端點：OpenAI REST /v1/audio/transcriptions
  • 輸入路徑：多部分音訊檔案上傳
  • 在任何使用 tools.media.audio 的輸入音訊轉錄情境下皆受 OpenClaw 支援，包括 Discord 語音頻道片段與頻道音訊附件

若要針對輸入音訊轉錄強制使用 OpenAI：

{
  tools: {
    media: {
      audio: {
        models: [
          {
            type: "provider",
            provider: "openai",
            model: "gpt-4o-transcribe",
          },
        ],
      },
    },
  },
}

當共用音訊媒體設定或單次轉錄請求提供語言與提示提示時，這些資訊會轉發至 OpenAI。

即時轉錄

內建的 openai 外掛程式會為語音通話外掛程式註冊即時轉錄功能。

設定設定路徑預設值
模型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 OAuthAPI 金鑰會直接連線；OAuth 會建立即時轉錄用戶端密鑰
即時語音

內建的 openai 外掛程式會為 Voice Call 外掛程式註冊即時語音。

設定設定路徑預設值
模型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 OAuth瀏覽器 Talk 和非 Azure 後端橋接器可以使用 OpenAI OAuth

gpt-realtime-2 可用的內建即時語音：alloy、ash、 ballad、coral、echo、sage、shimmer、verse、marin、cedar。 OpenAI 建議使用 marin 和 cedar 以獲得最佳的即時品質。這是與上述文字轉語音不同的組合；請勿假設 TTS 語音（例如 fable、nova 或 onyx）對即時工作階段有效。

Azure OpenAI 端點

Section titled “Azure OpenAI 端點”

內建的 openai 提供者可以透過覆寫基礎 URL，將 Azure OpenAI 資源做為圖像生成的目標。在圖像生成路徑上，OpenClaw 會偵測 models.providers.openai.baseUrl 上的 Azure 主機名稱，並自動切換至 Azure 的請求格式。

使用 Azure OpenAI 的時機：

  • 您已經擁有 Azure OpenAI 訂閱、配額或企業協議
  • 您需要 Azure 提供的區域資料駐留或合規性控制
  • 您希望將流量保留在現有的 Azure 租用戶內

設定

Section titled “設定”

若要透過內建的 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 圖像請求格式。

API 版本

Section titled “API 版本”

設定 AZURE_OPENAI_API_VERSION 以釘選特定的 Azure 預覽或 GA 版本 給 Azure 圖像生成路徑：

Terminal window
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"

若未設定變數，預設值為 2024-12-01-preview。

模型名稱即為部署名稱

Section titled “模型名稱即為部署名稱”

Azure OpenAI 會將模型繫結至部署。對於透過內建 openai 提供者路由的 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 提供者路由的影像生成呼叫。

區域可用性

Section titled “區域可用性”

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

參數差異

Section titled “參數差異”

Azure OpenAI 與公開 OpenAI 並非總是接受相同的影像參數。Azure 可能會拒絕公開 OpenAI 允許的選項（例如 gpt-image-2 上的某些 background 值），或僅在特定模型版本中公開這些選項。這些差異來自 Azure 和基礎模型，而非 OpenClaw。如果 Azure 請求因驗證錯誤而失敗，請在 Azure 入口網站中檢查您的特定部署和 API 版本所支援的參數集。

進階設定

Section titled “進階設定”
傳輸 (WebSocket vs SSE)

OpenClaw 使用 WebSocket 優先並備援 SSE ("auto") 來處理 openai/*。

在 "auto" 模式下，OpenClaw：

  • 在備援至 SSE 前重試一次早期的 WebSocket 失敗
  • 失敗後，將 WebSocket 標記為降級約 60 秒，並在冷卻期間使用 SSE
  • 為重試和重新連線附加穩定的 session 和 turn 身份標頭
  • 跨傳輸變體正規化使用計數器 (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[”

/

“].params.fastMode`

啟用後，OpenClaw 會將快速模式對應到 OpenAI 優先處理 (`service_tier = "priority"`)。現有的 `service_tier` 值會被保留，且快速模式不會重寫 `reasoning` 或 `text.verbosity`。


```json5
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": { params: { fastMode: true } },
      },
    },
  },
}
```
優先處理 (service_tier)

OpenAI 的 API 透過 service_tier 公開優先處理功能。請在 OpenClaw 中為每個模型進行設定：

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": { params: { serviceTier: "priority" } },
      },
    },
  },
}

支援的值：auto、default、flex、priority。

伺服器端壓縮 (Responses API)

針對直接使用 OpenAI Responses 模型（api.openai.com 上的 openai/*），OpenAI 插件的 OpenClaw 串流包裝器會自動啟用伺服器端壓縮：

  • 強制啟用 store: true（除非模型相容性設定設為 supportsStore: false）
  • 注入 context_management: [{ type: "compaction", compact_threshold: ... }]
  • 預設 compact_threshold：contextWindow 的 70%（或在不可用時設為 80000）

這適用於內建的 OpenClaw 執行路徑，以及嵌入式執行所使用的 OpenAI 提供者掛鉤。原生的 Codex 應用伺服器透過 Codex 管理自己的上下文，並由 OpenAI 的預設代理路由或提供者/模型執行時期原則進行配置。

適用於相容的端點，例如 Azure OpenAI Responses：

{
  agents: {
    defaults: {
      models: {
        "azure-openai-responses/gpt-5.5": {
          params: { responsesServerCompaction: true },
        },
      },
    },
  },
}
嚴格代理 GPT 模式

針對在 openai/* 上執行的 GPT-5 系列運作，OpenClaw 可以使用更嚴格的嵌入式執行合約：

{
  agents: {
    defaults: {
      embeddedAgent: { executionContract: "strict-agentic" },
    },
  },
}

使用 strict-agentic 時，OpenClaw 會：

  • 當有工具動作可用時，不再將僅計劃的回合視為成功的進度
  • 使用立即行動引導重試該回合
  • 針對實質工作自動啟用 update_plan
  • 如果模型持續規劃而未行動，則顯示明確的封鎖狀態
Native vs OpenAI-compatible routes

OpenClaw 會將直接連線的 OpenAI、Codex 和 Azure OpenAI 端點，與一般的 OpenAI 相容 /v1 代理伺服器區分對待：

原生路由 (openai/*, Azure OpenAI):

  • 僅針對支援 OpenAI none 方案的模型保留 reasoning: { effort: "none" }
  • 針對拒絕 reasoning.effort: "none" 的模型或代理伺服器，省略停用的推理功能
  • 預設將工具架構設為嚴格模式
  • 僅在驗證過的原生主機上附加隱藏的歸因標頭
  • 保留 OpenAI 專用的請求塑形 (service_tier、store、reasoning-compat、prompt-cache hints)

代理伺服器/相容路由：

  • 使用較寬鬆的相容行為
  • 從非原生的 openai-completions 載荷中移除 Completions store
  • 接受 OpenAI 相容 Completions 代理伺服器的高階 params.extra_body/params.extraBody 透傳 JSON
  • 接受 OpenAI 相容 Completions 代理伺服器（如 vLLM）的 params.chat_template_kwargs
  • 不強制執行嚴格的工具架構或原生專用標頭

Azure OpenAI 使用原生傳輸和相容行為，但不會收到隱藏的歸因標頭。

相關

Section titled “相關”
Model selection

選擇供應商、模型參照與容錯移轉行為。

Image generation

共用的影像工具參數與供應商選擇。

Video generation

共用的影片工具參數與供應商選擇。

OAuth 和驗證

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