OpenAI

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

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

OpenAI 明確支援在外部工具以及 OpenClaw 這類工作流程中使用訂閱 OAuth。

用量與成本追蹤

OpenClaw 會區分訂閱配額與 Platform API 計費：

• ChatGPT/Codex OAuth 會顯示訂閱方案、配額週期和點數餘額。
• OPENAI_ADMIN_KEY 會在控制介面的 用量 中顯示提供者回報的 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 模型參照、舊版 Codex 驗證 設定檔 ID 和舊版 Codex 驗證順序項目移轉至標準 openai 路由。新的驗證順序設定請使用 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 索引與查詢嵌入：

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

對於需要非對稱嵌入標籤的 OpenAI 相容端點，請在 memorySearch 下設定 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.5", contextTokens: 160000 }],      },    },  },}

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

當符合資格的確切官方 HTTPS 路由隱含選取原生 Codex 應用程式伺服器控制框架，或提供者／模型的 agentRuntime.id: "codex" 明確選取它時，該控制框架會使用 openai/* 模型參照。其驗證仍以帳戶為基礎。OpenClaw 依下列順序選取驗證：

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

即使閘道程序也有供直接 OpenAI 模型或嵌入使用的 OPENAI_API_KEY，本機 ChatGPT/Codex 訂閱登入也不會因此被取代。環境變數 API 金鑰備援僅適用於本機 stdio 的無帳戶路徑；絕不會透過 WebSocket 應用程式伺服器連線傳送。選取訂閱型 Codex 設定檔時，OpenClaw 也不會將 CODEX_API_KEY 與 OPENAI_API_KEY 傳入所產生的 stdio 應用程式伺服器子程序，而是透過應用程式伺服器登入 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"。

若要提出透明背景要求，請呼叫 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 相容端點則會保留其設定的部署／模型名稱。

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

openclaw infer image generate \  --model openai/gpt-image-1.5 \  --output-format png \  --background transparent \  --prompt "透明背景上的簡潔紅色圓形貼紙" \  --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 參照。設定 openai OAuth 設定檔後，OpenClaw 會解析該已儲存的 OAuth 存取權杖，並透過 Codex Responses 後端傳送影像要求；它不會先嘗試 OPENAI_API_KEY，也不會悄悄備援至 API 金鑰。若要改用直接 OpenAI Images API 路由，請使用 API 金鑰、自訂基底 URL 或 Azure 端點明確設定 models.providers.openai。如果該自訂影像端點位於受信任的區域網路／私人位址，也請設定 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 提示詞貢獻

OpenClaw 會為 openai 供應商上的 GPT-5 系列模型加入共用 GPT-5 提示詞貢獻 （包括修復前的舊版 Codex 參照，這些參照會正規化為 openai/*）。其他同樣提供 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

語音與話音

{  messages: {    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 相容代理）會維持標準 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 提供者 路由的 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" },    },  },}

相關內容