OpenAI

OpenClaw は、直接の API キー認証と ChatGPT/Codex サブスクリプション認証の両方に、単一のプロバイダー 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 モデル参照とプロファイル ID は、openclaw doctor --fix によって openai/* に修復されます。

OpenAI は、OpenClaw のような外部ツールやワークフローでのサブスクリプション OAuth の使用を明示的にサポートしています。

使用量とコストの追跡

OpenClaw は、サブスクリプションのクォータと Platform API の課金を区別して扱います。

• ChatGPT/Codex OAuth では、サブスクリプションプラン、クォータ期間、クレジット残高が表示されます。
• OPENAI_ADMIN_KEY を使用すると、プロバイダーから報告された過去 30 日間の組織コストと completions 使用量が Control UI の 使用量 に表示されます。これには、日別支出、リクエスト数とトークン数の合計、上位モデル、コストカテゴリが含まれます。
• 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 モデル参照、レガシー 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 を認識します。現在のカタログでは、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 互換の埋め込みエンドポイントを使用できます。

{  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 app-server の認証

ネイティブ Codex app-server ハーネスは、対象となる正確な公式 HTTPS ルートによって暗黙的に選択された場合、 またはプロバイダー／モデルの agentRuntime.id: "codex" によって明示的に選択された場合に、 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 は生成された stdio app-server 子プロセスに CODEX_API_KEY と OPENAI_API_KEY を渡さず、代わりに選択された認証情報を 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 参照を維持します。 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参照を含みます）。OpenRouterやopencodeルートなど、GPT-5ファミリーのモデルIDも提供する他のプロバイダーには、このオーバーレイは適用されません。これはモデルIDだけでなく、プロバイダーIDopenaiによって制限されます。以前のGPT-4.xモデルには適用されません。

ネイティブCodex app-serverハーネスは、開発者指示を通じてペルソナ／ツール規律の動作契約や親しみやすい対話スタイルのオーバーレイを受け取りません。ネイティブ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

音声と発話

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

• 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 値）が拒否される場合や、特定のモデル バージョンでのみ公開される場合があります。これらの違いは Azure と基盤モデルに由来するもので、 OpenClaw によるものではありません。Azure リクエストが検証エラーで失敗した場合は、 Azure ポータルで、対象のデプロイメントと API バージョンがサポートするパラメーターセットを 確認してください。

高度な設定

以下のモデルごとの params の例は、OpenClaw に組み込まれたプロバイダーリクエストの 形式を定めます。これらの設定は明示的に作成されたリクエスト動作となるため、それ以外の条件では 対象となる auto ルートでも、暗黙的に Codex を選択せず OpenClaw 上に留まります。 ネイティブ Codex app-server ハーネスは、独自のトランスポートとリクエスト設定を管理します。 明示的な agentRuntime.id: "codex" は、有効なルートが 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" },    },  },}

関連項目