OpenAI

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，再變更設定。

快速選擇

命名對照

這些名稱相似，但不可互換：

這表示設定可以刻意包含 openai/* 模型參照，同時驗證設定檔仍指向 Codex 相容的憑證。新設定請優先使用 auth.order.openai；既有的 openai-codex:* 設定檔和 auth.order.openai-codex 仍受支援。openclaw doctor --fix 會將舊版 openai-codex/* 模型參照改寫為標準 OpenAI 模型路由。

OpenClaw 功能涵蓋範圍

記憶嵌入

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。完整範例請參閱記憶設定參考。

開始使用

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

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

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

openclaw models list --provider openai

{  env: { OPENAI_API_KEY: "sk-..." },  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },}

{  env: { OPENAI_API_KEY: "sk-..." },  agents: { defaults: { model: { primary: "openai/chat-latest" } } },}

openclaw onboard --auth-choice openai-codex

openclaw models auth login --provider openai-codex

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

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

openclaw models list --provider openai-codex

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

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.5" },    },  },  auth: {    order: {      openai: [        "openai-codex:[email protected]",        "openai:api-key-backup",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openai-codexopenclaw 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-codex

openclaw doctor --fixopenclaw config validate

openclaw models auth login --provider openai-codexopenclaw models status --probe --probe-provider openai-codex

{  models: {    providers: {      "openai-codex": {        models: [{ id: "gpt-5.5", contextTokens: 160000 }],      },    },  },}

原生 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 圖像生成。

{  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 註冊影片生成。

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

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 指引一律會對相符模型啟用。友善互動風格層是獨立且可設定的。

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

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

語音與 speech

{  messages: {    tts: {      providers: {        openai: { model: "gpt-4o-mini-tts", voice: "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 影像生成呼叫使用 600 秒的預設請求逾時。 每次呼叫的 timeoutMs 值仍會覆寫此預設值。

其他基底 URL (公開 OpenAI、OpenAI 相容代理) 會保留標準的 OpenAI 影像請求形態。

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 版本所支援的參數集合。

進階設定

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

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": { params: { fastMode: true } },      },    },  },}

{  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: {      embeddedPi: { executionContract: "strict-agentic" },    },  },}

相關內容