OpenAI

OpenClaw は、直接の API キー認証と ChatGPT/Codex サブスクリプション認証の両方に、1 つのプロバイダー 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 の 使用量 に、プロバイダーから報告された組織のコストと completions 使用量の過去 30 日分を表示します。これには、日別支出、リクエスト数とトークン数の合計、上位モデル、コストカテゴリーが含まれます。
• OPENAI_PROJECT_ID を使用すると、Admin API の履歴を任意で 1 つのプロジェクトに限定できます。
• 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 を認識します。現在のカタログでは、3 つすべてが 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 は、memory_search のインデックス作成とクエリ埋め込みに、 OpenAI または OpenAI 互換の埋め込みエンドポイントを使用できます。

{  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 ルートによって暗黙的に選択された場合、またはプロバイダー／モデルの agentRuntime.id: "codex" によって明示的に選択された場合、ネイティブ Codex app-server ハーネスは openai/* モデル参照を使用します。その認証は引き続きアカウントベースです。 OpenClaw は次の順序で認証を選択します。

1. エージェント用に順序付けられた OpenAI 認証プロファイル。できるだけ auth.order.openai の下に配置してください。古い従来の Codex 認証プロファイル ID と認証順序を 移行するには、openclaw doctor --fix を実行します。
2. ローカル Codex CLI の ChatGPT サインインなど、app-server の既存アカウント。 デフォルトの分離されたエージェントホームでは、OpenClaw はそのネイティブ CLI アカウントを ログイン RPC を介して app-server に橋渡しします。CLI の設定、plugins、スレッドストアは共有しません。
3. ローカル stdio app-server の起動時のみ、かつ app-server がアカウントなしと 報告した場合のみ、CODEX_API_KEY、続いて OPENAI_API_KEY。

Gateway プロセスに、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 が通知したリセット時刻までプロファイルをブロック済みとしてマークし、選択したモデルを 変更したり Codex ハーネスから外れたりすることなく、認証順序に従って次の openai:* プロファイルに切り替えます。リセット時刻を過ぎると、 サブスクリプションプロファイルは再び使用可能になります。

画像生成

バンドルされた 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 "透明な背景上のシンプルな赤い円形ステッカー" \  --json

入力ファイルから開始する場合は、openclaw infer image edit で同じ --output-format および --background フラグを使用します。 --openai-background は、OpenAI 固有のエイリアスとして引き続き利用できます。 OpenAI Images の品質とコストを制御するには、--quality low|medium|high|auto を使用します。 image generate または image edit から OpenAI のモデレーションヒントを 渡すには、--openai-moderation low|auto を使用します。

ChatGPT/Codex OAuth インストールでは、同じ openai/gpt-image-2 ref を維持します。 openai 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="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 Plugin は、video_generate ツールを通じて 動画生成を登録します。

OpenAI の画像から動画へのリクエストでは、画像 input_reference とともに POST /v1/videos を使用します。単一動画の編集では、 アップロードした動画を video フィールドに指定して POST /v1/videos/edits を使用します。

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

GPT-5 プロンプトへの追加

OpenClaw は、openai プロバイダー上の GPT-5 ファミリーモデルに対して、 共有 GPT-5 プロンプト追加要素を加えます（openai/* に正規化される、 修復前の従来の Codex ref を含む）。OpenRouter や opencode ルートなど、 GPT-5 ファミリーのモデル ID も提供する他のプロバイダーには、このオーバーレイは適用されません。 これはモデル ID だけではなく、プロバイダー ID openai によって制限されます。 古い GPT-4.x モデルには適用されません。

ネイティブ Codex app-server ハーネスは、developer instructions を通じて ペルソナ/ツール規律の動作コントラクトや、親しみやすい対話スタイルのオーバーレイを受け取りません。 ネイティブ Codex は Codex が所有するベース、モデル、プロジェクトドキュメントの動作を維持し、 OpenClaw はネイティブスレッドで Codex の組み込みパーソナリティを無効にするため、 エージェントワークスペースのパーソナリティファイルが引き続き基準となります。 OpenClaw がネイティブ Codex スレッドに追加するのは、実行時コンテキストのみです。 これには、チャネル配信、OpenClaw 動的ツール、ACP 委任、ワークスペースコンテキスト、 OpenClaw Skills が含まれます。同じ追加要素に含まれる Heartbeat ガイダンステキストだけは例外です。 ネイティブ Codex の Heartbeat ターンにはこのテキストが適用されますが、 共有プロンプト追加フックではなく、専用のコラボレーション指示として注入されます。

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 は次の処理を行います。

• Authorization: Bearer の代わりに api-key ヘッダーを送信する
• デプロイメントスコープのパス（/openai/deployments/{deployment}/...）を使用する
• 各リクエストに ?api-version=... を追加する
• Azure 画像生成呼び出しでは、デフォルトのリクエストタイムアウトとして 600s を使用する。 呼び出しごとの 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 プロバイダーを介してルーティングされる Azure 画像生成リクエストでは、 OpenClaw の model フィールドに、公開 OpenAI モデル ID ではなく、 Azure ポータルで設定した Azure デプロイメント名 を指定する必要があります。

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

/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 値）を拒否したり、特定のモデルバージョンでのみ公開したりする場合があります。 こうした相違は OpenClaw ではなく、Azure と基盤モデルに起因します。Azure リクエストが 検証エラーで失敗した場合は、Azure ポータルで、使用しているデプロイメントと API バージョンが サポートするパラメーターセットを確認してください。

高度な設定

以下のモデルごとの params の例は、OpenClaw の組み込みプロバイダーリクエストを 形成します。これらの設定は作成者が指定するリクエスト動作であるため、通常は対象となる auto ルートでも、Codex が暗黙的に選択されるのではなく OpenClaw 上に維持されます。 ネイティブ 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" },    },  },}

関連項目