OpenAI

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

OpenClaw は正規の OpenAI モデルルートとして openai/* を使用します。OpenAI モデル上の埋め込みエージェントターンは、デフォルトではネイティブ Codex app-server runtime を通じて実行されます。直接の OpenAI API キー認証は、画像、埋め込み、音声、realtime など、エージェント以外の OpenAI サーフェスで引き続き利用できます。

• エージェントモデル - Codex runtime 経由の openai/* モデル。ChatGPT/Codex サブスクリプション利用では openai-codex 認証でサインインします。意図的に API キー認証を使う場合は、openai-codex API キープロファイルを設定します。
• エージェント以外の OpenAI API - OPENAI_API_KEY または OpenAI API キーのオンボーディングを通じた、使用量ベース課金の直接 OpenAI Platform アクセス。
• レガシー設定 - openai-codex/* モデル参照は、openclaw doctor --fix により、Codex runtime を伴う openai/* へ修復されます。

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

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

# クイック選択

# 名前の対応表

名前は似ていますが、互換ではありません。

これは、設定に openai/* モデル参照と 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" },
      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 アプリサーバー認証

ネイティブ Codex アプリサーバーハーネスは、openai/* モデル参照と省略された ランタイム設定、または agentRuntime.id: "codex" を使用しますが、その認証は引き続き アカウントベースです。OpenClaw は 次の順序で認証を選択します。

1. エージェントに紐付けられた明示的な OpenClaw 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 経由で送信します。

# 画像生成

バンドルされた 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 アプリサーバー開発者指示を通じて同じ GPT-5 動作と Heartbeat オーバーレイを使用するため、agentRuntime.id: "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 プロバイダー経由でルーティングされる 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 プロバイダー経由でルーティングされる画像生成呼び出しにも適用されます。

# リージョンでの提供状況

Azure 画像生成は現在、一部のリージョンでのみ利用できます (例: eastus2, swedencentral, polandcentral, westus3, uaenorth)。デプロイを作成する前に Microsoft の最新リージョン一覧を確認し、 特定のモデルが自分のリージョンで提供されていることを確認してください。

# パラメーター差分

Azure OpenAI と公開 OpenAI は、常に同じ画像パラメーターを受け付けるわけではありません。 Azure は、公開 OpenAI が許可するオプション (たとえば gpt-image-2 の特定の background 値) を拒否する場合や、特定のモデルバージョンでのみ公開する場合があります。 これらの差分は Azure と基盤モデルに由来するもので、OpenClaw によるものではありません。 Azure リクエストが検証エラーで失敗する場合は、自分の特定のデプロイと API バージョンでサポートされるパラメーターセットを Azure ポータルで確認してください。

# 高度な設定

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

# 関連