OpenAI

OpenClaw 對直接 API 金鑰驗證與 ChatGPT/Codex 訂閱驗證使用同一個提供者 ID：openai。 openai/* 是標準模型路由。對於執行階段原則未設定或設為 auto 的內嵌代理程式回合，OpenAI 的路由資訊會決定 OpenClaw 是否可隱含選取隨附的 Codex app-server 執行階段。僅有 openai/* 前綴不會選取執行階段。

• 代理程式模型 - 透過明確的 agentRuntime 設定或 OpenAI 的隱含路由原則所選取的執行階段，使用 openai/*。若要使用 ChatGPT/Codex 訂閱，請以 Codex 驗證登入；若要採用金鑰計費，請設定 API 金鑰驗證設定檔。
• 非代理程式 OpenAI API - 透過 OPENAI_API_KEY 或 openai API 金鑰驗證設定檔直接存取 OpenAI Platform，並按用量計費。
• 舊版設定 - codex/* 和 openai-codex/* 參照會由 openclaw doctor --fix 修復為 openai/*，並加上模型範圍的 agentRuntime.id: "codex"。

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

用量與成本追蹤

OpenClaw 會將訂閱配額與 Platform API 計費分開處理：

• ChatGPT/Codex OAuth 會顯示訂閱方案、配額週期和點數餘額。
• OPENAI_ADMIN_KEY 會在 Control UI 的用量中顯示提供者回報的最近 30 天組織成本與 completions 用量，包括每日支出、請求／權杖總數、熱門模型和成本類別。
• OPENAI_PROJECT_ID 可選擇將 Admin API 歷程限定於單一專案。
• OpenClaw 絕不會將 OPENAI_API_KEY 或 openai 推論設定檔傳送至組織 API；這些認證資訊可能屬於自訂、Azure 或代理程式本機端點。

明確指定的 Admin 金鑰優先於 OAuth。提供者回報的歷程不會與 OpenClaw 根據工作階段推算的估計成本合併；其中可能包含其他用戶端的 API 活動及提供者端的計費調整。

OpenAI 的 API 用量儀表板文件說明了存取用量資料所需的組織擁有者身分，以及明確的 Usage Dashboard 權限要求。

提供者、模型、執行階段和頻道是彼此獨立的層級。如果這些標籤混淆在一起，請先閱讀代理程式執行階段，再變更設定。

快速選擇

名稱對照表

隱含代理程式執行階段

當提供者／模型 agentRuntime 原則未設定或設為 auto 時，由 OpenAI 提供者擁有的路由原則會根據實際端點和配接器選擇隱含執行階段：

明確指定的非預設提供者／模型 agentRuntime.id 仍具決定權。例如，agentRuntime.id: "openclaw" 會讓原本符合 Codex 資格的路由繼續使用 OpenClaw，而 agentRuntime.id: "codex" 則要求使用 Codex，並在實際路由未宣告與 Codex 相容時採取封閉式失敗。執行階段選擇不會變更認證資訊類型或計費方式：Platform API 金鑰驗證和 ChatGPT/Codex 訂閱驗證仍彼此獨立。

openclaw doctor --fix 會將舊版 codex/* 和 openai-codex/* 模型參照、舊版 Codex 驗證設定檔 ID，以及舊版 Codex 驗證順序項目遷移至標準 openai 路由。遷移後的模型參照會獲得模型範圍的 agentRuntime.id: "codex"；新的驗證順序設定請使用 auth.order.openai。

GPT-5.6 限量預覽

OpenClaw 可辨識確切的 openai/gpt-5.6-sol、openai/gpt-5.6-terra 和 openai/gpt-5.6-luna 模型 ID。在目前的目錄中，這三者都提供 xhigh 和 max 推理。OpenAI 將 Sol 描述為旗艦層級、Terra 為均衡層級，而 Luna 則為快速且成本較低的層級。請參閱 GPT-5.6 發布公告和存取指南。

使用直接 OpenAI API 金鑰驗證時，未限定的 openai/gpt-5.6 ID 是 Sol 的別名，也是全新設定的預設值。原生 Codex 目錄不會在用戶端套用此直接 API 別名；視工作區的存取權而定，它可能顯示確切的 Sol、Terra 和 Luna ID。因此，全新的 ChatGPT/Codex OAuth 設定會使用 openai/gpt-5.6-sol。請使用以下命令查看目前帳號：

openclaw models list --provider openai

API 組織與 Codex 工作區的存取權可能不同。如果 GPT-5.6 無法使用，請明確選取 GPT-5.5：

openclaw models set openai/gpt-5.5

OpenClaw 會顯示上游存取錯誤，不會無提示地將 GPT-5.6 選項替換為 GPT-5.5。

OpenClaw 功能涵蓋範圍

記憶嵌入

OpenClaw 可使用 OpenAI 或 OpenAI 相容的嵌入端點，為 memory_search 建立索引及產生查詢嵌入：

{  memory: {    search: {      provider: "openai",      model: "text-embedding-3-small",    },  },}

對於需要非對稱嵌入標籤的 OpenAI 相容端點，請在 memory.search 下設定 queryInputType 和 documentInputType。OpenClaw 會將其轉送為供應商特定的 input_type 請求欄位：查詢 嵌入使用 queryInputType；已建立索引的記憶區塊和批次索引則使用 documentInputType。完整範例請參閱 記憶設定參考。

開始使用

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

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

openclaw models list --provider openai

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

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

openclaw onboard --auth-choice openai

openclaw models auth login --provider openai

openclaw models auth login --provider openai --device-code

openclaw config set agents.defaults.model.primary openai/gpt-5.6-sol

openclaw models list --provider openai

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-sol" },    },  },}

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-sol" },    },  },  auth: {    order: {      openai: [        "openai:user@example.com",        "openai:api-key-backup",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openaiopenclaw config get agents.defaults.model --jsonopenclaw config get models.providers.openai.agentRuntime --json

openclaw models status --agent <id>openclaw models auth list --agent <id> --provider openai

openclaw doctor --fixopenclaw config validate

openclaw models auth login --provider openaiopenclaw models status --probe --probe-provider openai

openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

{  models: {    providers: {      openai: {        models: [          {            id: "gpt-5.6-terra",            name: "GPT-5.6 Terra",            contextWindow: 1050000,            contextTokens: 922000,            maxTokens: 128000,          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-terra" },      models: {        "openai/gpt-5.6-terra": {          agentRuntime: { id: "openclaw" },          params: {            responsesServerCompaction: true,            responsesCompactThreshold: 700000,          },        },      },    },  },}

原生 Codex app-server 驗證

當符合資格且完全相符的官方 HTTPS 路由隱含選取原生 Codex app-server 測試框架，或供應商／模型 agentRuntime.id: "codex" 明確選取它時，該框架會使用 openai/* 模型參照。其驗證仍以帳戶為基礎。OpenClaw 會依下列順序 選取驗證方式：

1. 代理程式的已排序 OpenAI 驗證設定檔，最好放在 auth.order.openai 下。執行 openclaw doctor --fix，以遷移較舊的舊版 Codex 驗證設定檔 ID 與驗證順序。
2. app-server 的現有帳戶，例如本機 Codex 命令列介面 ChatGPT 登入。對於預設的隔離代理程式主目錄，OpenClaw 會透過其登入 RPC 將該原生 命令列介面帳戶橋接至 app-server；它不會共用命令列介面的設定、外掛或執行緒儲存區。
3. 僅適用於本機 stdio app-server 啟動，且僅在 app-server 回報沒有帳戶時：CODEX_API_KEY，接著是 OPENAI_API_KEY。

即使閘道程序也有用於直接 OpenAI 模型或嵌入的 OPENAI_API_KEY， 本機 ChatGPT/Codex 訂閱登入也不會因此被取代。環境 API 金鑰備援僅適用於 本機 stdio 無帳戶路徑；絕不會透過 WebSocket app-server 連線傳送。選取 訂閱型 Codex 設定檔時，OpenClaw 也會阻止 CODEX_API_KEY 與 OPENAI_API_KEY 進入產生的 stdio app-server 子程序，並改透過 app-server 登入 RPC 傳送選取的認證資訊。

當該訂閱設定檔因 Codex 使用量限制而受阻時，OpenClaw 會將設定檔標記為 受阻，直到 Codex 宣告的重設時間，並讓驗證順序輪替至下一個 openai:* 設定檔，而不會變更選取的模型或退出 Codex 測試框架。 重設時間一過，該訂閱設定檔便會再次符合使用資格。

圖片生成

隨附的 openai 外掛會透過 image_generate 工具註冊圖片生成。 它支援透過相同的 openai/gpt-image-2 模型參照，使用 OpenAI API 金鑰與 Codex OAuth 進行圖片生成。

{  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"。

對於透明背景要求，請使用 model: "openai/gpt-image-1.5"、outputFormat: "png" 或 "webp"，以及 background: "transparent" 呼叫 image_generate； 較舊的 openai.background 供應商選項仍可使用。OpenClaw 也會將預設的 openai/gpt-image-2 透明要求重寫為 gpt-image-1.5，以保護公開的 OpenAI 與 OpenAI Codex OAuth 路由；Azure 與自訂 OpenAI 相容端點則會保留 其設定的部署／模型名稱。

無介面命令列介面執行也提供相同設定：

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 專用別名使用。使用 --quality low|medium|high|auto 控制 OpenAI Images 的品質與成本。 使用 --openai-moderation low|auto，從 image generate 或 image edit 傳遞 OpenAI 的內容審核提示。

對於 ChatGPT/Codex OAuth 安裝，請維持使用相同的 openai/gpt-image-2 ref。設定 openai OAuth 設定檔後，OpenClaw 會解析該已儲存的 OAuth 存取權杖，並透過 Codex Responses 後端傳送圖片請求；它 不會先嘗試 OPENAI_API_KEY，也不會無提示地改用 API 金鑰。 若要改用直接的 OpenAI Images API 路徑，請明確設定 models.providers.openai，並提供 API 金鑰、自訂基礎 URL 或 Azure 端點。如果該自訂圖片端點位於受信任的區域網路／私人位址， 也請設定 browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true；除非提供此明確選擇， 否則 OpenClaw 會持續封鎖私人／內部的 OpenAI 相容圖片端點。

生成：

/tool image_generate model=openai/gpt-image-2 prompt="適用於 macOS 上 OpenClaw 的精緻發表海報" size=3840x2160 count=1

生成透明 PNG：

/tool image_generate model=openai/gpt-image-1.5 prompt="透明背景上的簡單紅色圓形貼紙" outputFormat=png background=transparent

編輯：

/tool image_generate model=openai/gpt-image-2 prompt="保留物件形狀，將材質變更為半透明玻璃" image=/path/to/reference.png size=1024x1536

影片生成

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

OpenAI 圖片轉影片請求使用 POST /v1/videos，並附帶圖片 input_reference。單一影片編輯使用 POST /v1/videos/edits，並將 上傳的影片放在 video 欄位中。

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

GPT-5 提示貢獻

對於 openai 提供者上的 GPT-5 系列模型，OpenClaw 會加入共用的 GPT-5 提示貢獻（包括正規化為 openai/* 的修復前舊版 Codex ref）。 其他同樣提供 GPT-5 系列模型 ID 的提供者（例如 OpenRouter 或 opencode 路徑） 不會收到此覆寫層；其套用條件是提供者 ID openai， 而非僅依據模型 ID。較舊的 GPT-4.x 模型絕不會收到此覆寫層。

原生 Codex app-server 控制框架不會透過開發者指示收到角色／工具 紀律行為合約或友善互動風格覆寫層；原生 Codex 會保留由 Codex 擁有的基礎、 模型與專案文件行為，而 OpenClaw 會停用原生執行緒中 Codex 的內建個性， 以確保代理程式工作區的個性檔案維持最高優先權。 OpenClaw 僅會為原生 Codex 執行緒提供執行階段情境：頻道 傳遞、OpenClaw 動態工具、ACP 委派、工作區情境與 OpenClaw Skills。同一項貢獻中的心跳偵測指引文字是 唯一例外：原生 Codex 的心跳偵測回合確實會收到該文字，但它會以專用的 協作指示注入，而非透過共用提示貢獻 掛鉤。

GPT-5 貢獻會為符合條件且由 OpenClaw 組裝的提示加入帶標籤的行為合約， 涵蓋角色持續性、執行安全性、工具紀律、輸出形式、完成 檢查與驗證。頻道特定的回覆與靜默訊息行為仍由共用的 OpenClaw 系統 提示及對外傳遞政策負責。友善互動風格層 彼此獨立，且可進行設定。

{  agents: {    defaults: {      promptOverlays: {        gpt5: { personality: "friendly" },      },    },  },}

openclaw config set agents.defaults.promptOverlays.gpt5.personality off

語音與語音處理

{  tts: {    providers: {      openai: { model: "gpt-4o-mini-tts", speakerVoice: "coral" },    },  },}

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

Azure OpenAI 端點

內建的 openai 提供者可透過覆寫基底 URL，將影像 生成目標設為 Azure OpenAI 資源。在影像生成路徑上，OpenClaw 會偵測 models.providers.openai.baseUrl 上的 Azure 主機名稱，並自動切換為 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 影像生成呼叫的預設請求逾時時間為 600s。 各次呼叫的 timeoutMs 值仍會覆寫此預設值。

其他基底 URL（公開 OpenAI、OpenAI 相容 Proxy）會維持標準 OpenAI 影像請求格式。

API 版本

設定 AZURE_OPENAI_API_VERSION，即可為 Azure 影像生成路徑 鎖定特定 Azure 預覽版或正式版版本：

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

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

模型名稱即部署名稱

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="乾淨的海報" size=1024x1024 count=1

相同的部署名稱規則適用於透過 內建 openai 提供者路由的任何影像生成呼叫。

區域可用性

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

參數差異

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

進階設定

下方各模型的 params 範例會塑造 OpenClaw 的內嵌提供者 請求。設定這些參數屬於明確編寫的請求行為，因此原本符合資格的 auto 路由會留在 OpenClaw 上，而不會隱含選取 Codex。原生 Codex app-server 控制框架擁有自己的傳輸和請求設定；若有效路由 未宣告為與 Codex 相容，明確的 agentRuntime.id: "codex" 會採取封閉式失敗。

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: { transport: "auto" },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": { params: { fastMode: "auto", fastAutoOnSeconds: 30 } },      },    },  },}

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

{  agents: {    defaults: {      models: {        "azure-openai-responses/gpt-5.5": {          params: { responsesServerCompaction: true },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: {            responsesServerCompaction: true,            responsesCompactThreshold: 120000,          },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: { responsesServerCompaction: false },        },      },    },  },}

{  agents: {    defaults: {      embeddedAgent: { executionContract: "default" },    },  },}

相關內容