OpenAI

OpenAI 提供 GPT 模型的開發者 API，而 Codex 也可透過 OpenAI 的 Codex 用戶端，作為 ChatGPT 方案的程式碼代理程式使用。OpenClaw 會將這些介面分開，讓設定保持可預測。

OpenClaw 使用 openai/* 作為標準 OpenAI 模型路由。OpenAI 模型上的內嵌代理程式 回合預設會透過原生 Codex app-server 執行環境執行；直接 OpenAI API 金鑰驗證仍可用於 非代理程式 OpenAI 介面，例如圖片、嵌入、語音和即時功能。

• 代理程式模型 - 透過 Codex 執行環境使用 openai/* 模型；若要使用 ChatGPT/Codex 訂閱，請以 openai-codex 驗證登入，或在你有意使用 API 金鑰驗證時設定 openai-codex API 金鑰設定檔。
• 非代理程式 OpenAI API - 透過 OPENAI_API_KEY 或 OpenAI API 金鑰導引設定，直接使用 OpenAI Platform 並採用用量計費。
• 舊版設定 - openai-codex/* 模型參照會由 openclaw doctor --fix 修復為 openai/* 加上 Codex 執行環境。

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

提供者、模型、執行環境和通道是不同層級。如果這些標籤被混在一起，請先閱讀 代理程式執行環境，再變更設定。

# 快速選擇

# 命名對照表

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

這表示設定可以有意同時包含 openai/* 模型參照和 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 會將 這些作為提供者專屬的 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" },
      agentRuntime: { id: "codex" },
    },
  },
}

openclaw models status
openclaw models auth list --provider openai-codex
openclaw config get agents.defaults.model --json
openclaw config get agents.defaults.agentRuntime --json

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

openclaw doctor --fix
openclaw config validate

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

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

# 原生 Codex app-server 驗證

原生 Codex app-server 控管器使用 openai/* 模型參照加上省略的執行階段設定或 agentRuntime.id: "codex"，但其驗證仍以帳戶為基礎。OpenClaw 會依此順序選擇驗證：

1. 綁定到 agent 的明確 OpenClaw openai-codex 驗證 profile。
2. app-server 的既有帳戶，例如本機 Codex CLI ChatGPT 登入。
3. 僅限本機 stdio app-server 啟動，當 app-server 回報沒有帳戶且仍需要 OpenAI 驗證時，使用 CODEX_API_KEY，然後 OPENAI_API_KEY。

這表示本機 ChatGPT/Codex 訂閱登入不會只因為 gateway 程序也有用於直接 OpenAI 模型或 embeddings 的 OPENAI_API_KEY 就被取代。Env API-key fallback 只適用於本機 stdio 無帳戶路徑；不會傳送到 WebSocket app-server 連線。選取訂閱式 Codex profile 時，OpenClaw 也會讓 CODEX_API_KEY 和 OPENAI_API_KEY 不進入產生的 stdio app-server child，並透過 app-server login RPC 傳送所選認證。

# 影像生成

隨附的 openai plugin 會透過 image_generate 工具註冊影像生成。 它透過相同的 openai/gpt-image-2 模型參照，同時支援 OpenAI API-key 影像生成與 Codex OAuth 影像生成。

{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "openai/gpt-image-2" },
    },
  },
}

gpt-image-2 是 OpenAI text-to-image 生成與影像編輯兩者的預設值。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 應以 model: "openai/gpt-image-1.5"、outputFormat: "png" 或 "webp"，以及 background: "transparent" 呼叫 image_generate；較舊的 openai.background provider option 仍會被接受。OpenClaw 也會保護公開 OpenAI 與 OpenAI Codex OAuth 路由，將預設 openai/gpt-image-2 透明請求改寫為 gpt-image-1.5；Azure 與自訂 OpenAI-compatible endpoints 則保留其已設定的 deployment/model 名稱。

相同設定也會暴露給 headless 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

從輸入檔開始時，請將相同的 --output-format 與 --background flags 搭配 openclaw infer image edit 使用。 --openai-background 仍可作為 OpenAI-specific alias 使用。

對於 Codex OAuth 安裝，請保留相同的 openai/gpt-image-2 參照。設定 openai-codex OAuth profile 時，OpenClaw 會解析該已儲存的 OAuth access token，並透過 Codex Responses backend 傳送影像請求。它不會先嘗試 OPENAI_API_KEY，也不會針對該請求無聲 fallback 到 API key。當你想改用直接 OpenAI Images API 路由時，請明確設定 models.providers.openai 搭配 API key、自訂 base URL 或 Azure endpoint。 如果該自訂影像 endpoint 位於受信任的 LAN/private address，也請設定 browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true；除非存在此 opt-in，否則 OpenClaw 會持續封鎖 private/internal OpenAI-compatible image endpoints。

生成：

/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 工具註冊影片生成。

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

# GPT-5 prompt contribution

OpenClaw 會為跨 provider 的 GPT-5-family 執行加入共用 GPT-5 prompt contribution。它會依 model id 套用，因此 openai/gpt-5.5、舊版修復前參照例如 openai-codex/gpt-5.5、openrouter/openai/gpt-5.5、opencode/gpt-5.5，以及其他相容 GPT-5 參照，都會收到相同的 overlay。較舊的 GPT-4.x 模型則不會。

隨附的原生 Codex 控管器會透過 Codex app-server developer instructions 使用相同的 GPT-5 行為與 Heartbeat overlay，因此強制透過 agentRuntime.id: "codex" 的 openai/gpt-5.x session 仍會保留相同的 follow-through 與主動 Heartbeat 指引，即使 Codex 擁有控管器 prompt 的其餘部分。

GPT-5 貢獻新增了一組帶標籤的行為合約，涵蓋 persona 持久性、執行安全性、工具紀律、輸出形態、完成檢查與驗證。特定通道的回覆與靜默訊息行為仍保留在共用的 OpenClaw 系統提示與外送政策中。GPT-5 指引一律會針對相符模型啟用。友善互動風格層是獨立且可設定的。

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

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

# 語音與語音辨識

{
  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 preview 或 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="A clean poster" 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 版本支援的參數集。

# 進階設定

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

// Disable warm-up
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { openaiWsWarmup: false },
        },
      },
    },
  },
}

{
  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" },
    },
  },
}

# 相關