OpenAI

OpenAI は GPT モデル向けの開発者 API を提供しており、Codex は OpenAI の Codex クライアントを通じて ChatGPT プランのコーディングエージェントとしても利用できます。OpenClaw は、設定を予測しやすく保つために、これらのサーフェスを分離しています。

OpenClaw は、正規の OpenAI モデルルートとして openai/* を使用します。OpenAI モデル上の埋め込みエージェントターンは、デフォルトでネイティブの Codex app-server ランタイムを通じて実行されます。直接の 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 利用を明示的にサポートしています。

プロバイダー、モデル、ランタイム、チャンネルは別々のレイヤーです。これらのラベルが混同されている場合は、設定を変更する前に エージェントランタイム を読んでください。

クイック選択

名前の対応表

名前は似ていますが、相互に置き換えられるものではありません。

つまり、設定には意図的に openai/* モデル参照を含めつつ、認証プロファイルは Codex 互換の認証情報を指すことができます。新しい設定では auth.order.openai を推奨します。既存の openai-codex:* プロファイルと auth.order.openai-codex は引き続きサポートされます。openclaw doctor --fix は、レガシーな openai-codex/* モデル参照を正規の OpenAI モデルルートへ書き換えます。

OpenClaw の機能対応範囲

メモリ埋め込み

OpenClaw は、memory_search のインデックス作成とクエリ埋め込みに OpenAI、または OpenAI 互換の埋め込みエンドポイントを使用できます。

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

{  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/* モデル参照と、省略された ランタイム設定またはプロバイダー/モデル agentRuntime.id: "codex" を使用しますが、その認証は 引き続きアカウントベースです。OpenClaw は次の順序で認証を選択します。

1. エージェント用の順序付き OpenAI 認証プロファイル。できれば auth.order.openai の下に置きます。既存の openai-codex:* プロファイルと auth.order.openai-codex は、古いインストールでも引き続き有効です。
2. ローカル Codex CLI ChatGPT サインインなど、アプリサーバーの既存アカウント。
3. ローカル stdio アプリサーバー起動の場合のみ、アプリサーバーがアカウントなしを報告し、なお OpenAI 認証を必要とする場合は、CODEX_API_KEY、その後 OPENAI_API_KEY。

つまり、Gateway プロセスにも直接 OpenAI モデルや 埋め込み用の OPENAI_API_KEY があるという理由だけで、ローカル ChatGPT/Codex サブスクリプションサインインが置き換えられることはありません。 環境変数 API キーフォールバックは、ローカル stdio のアカウントなしパスだけです。これは WebSocket アプリサーバー接続には送信されません。サブスクリプション形式の Codex プロファイルが選択されると、OpenClaw は生成した stdio アプリサーバー子プロセスから CODEX_API_KEY と OPENAI_API_KEY も除外し、選択された認証情報を アプリサーバーログイン RPC 経由で送信します。そのサブスクリプションプロファイルが Codex 使用量制限でブロックされると、OpenClaw は、選択されたモデルを変更したり Codex ハーネスから外れたりせずに、次の順序付き openai:* API キー プロファイルへローテーションできます。サブスクリプションのリセット時刻を過ぎると、サブスクリプションプロファイルは 再び対象になります。

画像生成

バンドル済み 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" を拒否します。

透過背景リクエストでは、エージェントは 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 互換エンドポイントは、 設定済みのデプロイ/モデル名を維持します。

同じ設定は、ヘッドレス 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 ツールを通じて動画生成を登録します。

{  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 ハーネスは、Codex app-server の開発者向け指示を通じて、同じ GPT-5 動作と Heartbeat オーバーレイを使用します。そのため、Codex を経由してルーティングされる openai/gpt-5.x セッションは、ハーネスプロンプトの残りを Codex が所有していても、同じフォロースルーとプロアクティブな Heartbeat ガイダンスを維持します。

GPT-5 寄与は、ペルソナの持続性、実行の安全性、ツール規律、出力形式、完了チェック、検証のためのタグ付き動作契約を追加します。チャンネル固有の返信とサイレントメッセージの動作は、共有 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 は次を行います。

• Authorization: Bearer の代わりに api-key ヘッダーを送信します
• デプロイメントスコープのパス (/openai/deployments/{deployment}/...) を使用します
• 各リクエストに ?api-version=... を追加します
• Azure 画像生成呼び出しには 600 秒のデフォルトリクエストタイムアウトを使用します。 呼び出しごとの timeoutMs 値は引き続きこのデフォルトを上書きします。

その他のベース URL (公開 OpenAI、OpenAI 互換プロキシ) は、標準の OpenAI 画像リクエスト形式を維持します。

API バージョン

Azure の画像生成パスで特定の Azure プレビュー版または GA 版に固定するには、AZURE_OPENAI_API_VERSION を設定します。

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

変数が未設定の場合、デフォルトは 2024-12-01-preview です。

モデル名はデプロイ名

Azure OpenAI はモデルをデプロイに紐付けます。バンドルされた openai provider 経由でルーティングされる Azure 画像生成リクエストでは、OpenClaw の model フィールドは、公開 OpenAI モデル ID ではなく、Azure ポータルで設定した Azure デプロイ名 である必要があります。

gpt-image-2 を提供する gpt-image-2-prod というデプロイを作成した場合:

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

関連