OpenClawでOpenAI APIとCodexを5分で設定する

新しいプロジェクトを立ち上げる際、API のセットアップや認証情報の管理に意外と時間がかかってしまうことはありませんか？特に OpenAI のような強力なモデルを利用する場合、開発環境では API キーを使い、個人の検証ではサブスクリプションを活用したいといった、柔軟な使い分けが必要になる場面も多いはずです。

OpenClaw を使えば、こうした認証周りの設定をスムーズに完了させ、すぐに本来の開発作業に集中できます。今回は、OpenAI を OpenClaw で利用するための 2 つのセットアップ方法について解説します。

OpenAI

OpenAI は GPT モデル向けの開発者用 API を提供しています。Codex では、サブスクリプションによるアクセスのための ChatGPT sign-in、または使用量に基づいたアクセスのための API key によるサインインをサポートしています。Codex cloud を利用するには ChatGPT sign-in が必要です。OpenAI は、OpenClaw のような外部ツールやワークフローにおけるサブスクリプション OAuth の利用を公式にサポートしています。

Option A: OpenAI API key (OpenAI Platform)

おすすめのケース: 直接 API にアクセスしたい場合や、従量課金（usage-based billing）を利用したい場合。 API キーは OpenAI のダッシュボードから取得してください。

CLI setup

openclaw onboard --auth-choice openai-api-key
# or non-interactive
openclaw onboard --openai-api-key "$OPENAI_API_KEY"

Config snippet

{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
}

OpenAI の現在の API モデルドキュメントには、直接的な OpenAI API 利用向けに gpt-5.4 と gpt-5.4-pro がリストされています。OpenClaw はこれら両方を openai/* の Responses パス経由で転送します。OpenClaw では、古くなった openai/gpt-5.3-codex-spark の行を意図的に抑制しています。これは、実際のトラフィックにおいて直接的な OpenAI API コールがこのモデルを拒否するためです。

OpenClaw は、直接的な OpenAI API パスにおいて openai/gpt-5.3-codex-spark を公開しません。pi-ai には依然としてそのモデル用の組み込み行が含まれていますが、現在の OpenAI API リクエストでは拒否されます。OpenClaw において Spark は Codex 専用として扱われます。

Option B: OpenAI Code (Codex) subscription

おすすめのケース: API キーの代わりに ChatGPT/Codex のサブスクリプションアクセスを利用したい場合。 Codex cloud には ChatGPT sign-in が必要ですが、Codex CLI は ChatGPT または API key によるサインインをサポートしています。

CLI setup (Codex OAuth)

# Run Codex OAuth in the wizard
openclaw onboard --auth-choice openai-codex

# Or run OAuth directly
openclaw models auth login --provider openai-codex

Config snippet (Codex subscription)

{
  agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
}

OpenAI の現在の Codex ドキュメントでは、gpt-5.4 が現在の Codex モデルとしてリストされています。OpenClaw は ChatGPT/Codex OAuth 利用のために、これを openai-codex/gpt-5.4 にマッピングします。

お使いの Codex アカウントに Codex Spark の権限がある場合、OpenClaw は以下もサポートします：

• openai-codex/gpt-5.3-codex-spark

OpenClaw は Codex Spark を Codex 専用として扱います。直接的な openai/gpt-5.3-codex-spark という API key パスは提供しません。

また、OpenClaw は pi-ai が openai-codex/gpt-5.3-codex-spark を検出した際、それを保持します。これについては、権限に依存する実験的なものとして扱ってください。Codex Spark は GPT-5.4 /fast とは別物であり、利用可能かどうかはサインインしている Codex / ChatGPT アカウントに依存します。

Transport default

OpenClaw はモデルのストリーミングに pi-ai を使用します。openai/* と openai-codex/* の両方において、デフォルトの transport は "auto"（WebSocket 優先、その後に SSE へフォールバック）です。

agents.defaults.models.<provider/model>.params.transport で設定を変更できます：

• "sse": SSE を強制
• "websocket": WebSocket を強制
• "auto": WebSocket を試し、失敗した場合は SSE にフォールバック

openai/*（Responses API）の場合、WebSocket transport が使用されると、OpenClaw はデフォルトで WebSocket warm-up を有効にします（openaiWsWarmup: true）。

関連する OpenAI ドキュメント：

• Realtime API with WebSocket
• Streaming API responses (SSE)

{
  agents: {
    defaults: {
      model: { primary: "openai-codex/gpt-5.4" },
      models: {
        "openai-codex/gpt-5.4": {
          params: {
            transport: "auto",
          },
        },
      },
    },
  },
}

OpenAI WebSocket warm-up

OpenAI のドキュメントでは warm-up はオプションとされています。OpenClaw では、WebSocket transport 使用時の初回ターンのレイテンシを削減するため、openai/* に対してデフォルトでこれを有効にしています。

Disable warm-up

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            openaiWsWarmup: false,
          },
        },
      },
    },
  },
}

Enable warm-up explicitly

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            openaiWsWarmup: true,
          },
        },
      },
    },
  },
}

OpenAI and Codex priority processing

OpenAI の API は service_tier=priority を通じて優先処理を公開しています。OpenClaw では、agents.defaults.models["<provider>/<model>"].params.serviceTier を設定することで、ネイティブの OpenAI/Codex Responses エンドポイントにそのフィールドを渡すことができます。

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            serviceTier: "priority",
          },
        },
        "openai-codex/gpt-5.4": {
          params: {
            serviceTier: "priority",
          },
        },
      },
    },
  },
}

サポートされている値は auto, default, flex, priority です。

OpenClaw は、モデルがネイティブの OpenAI/Codex エンドポイントを指している場合、直接的な openai/* Responses リクエストと openai-codex/* Codex Responses リクエストの両方に params.serviceTier を転送します。

重要な動作：

• 直接的な openai/* は api.openai.com をターゲットにする必要があります
• openai-codex/* は chatgpt.com/backend-api をターゲットにする必要があります
• いずれかのプロバイダーを別のベース URL やプロキシ経由でルーティングする場合、OpenClaw は service_tier を変更しません

OpenAI fast mode

OpenClaw は、openai/* と openai-codex/* セッションの両方で共有される fast-mode 切り替え機能を提供しています：

• Chat/UI: /fast status|on|off
• Config: agents.defaults.models["<provider>/<model>"].params.fastMode

fast mode が有効な場合、OpenClaw はそれを OpenAI の優先処理にマッピングします：

• api.openai.com への直接的な openai/* Responses コールは service_tier = "priority" を送信します
• chatgpt.com/backend-api への openai-codex/* Responses コールも service_tier = "priority" を送信します
• ペイロードに既存の service_tier 値がある場合は保持されます
• fast mode は reasoning や text.verbosity を書き換えません

例：

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            fastMode: true,
          },
        },
        "openai-codex/gpt-5.4": {
          params: {
            fastMode: true,
          },
        },
      },
    },
  },
}

セッションによる上書きは設定よりも優先されます。Sessions UI でセッションの上書きをクリアすると、セッションは設定されたデフォルトに戻ります。

OpenAI Responses server-side compaction

直接的な OpenAI Responses モデル（api: "openai-responses" を使用し、baseUrl が api.openai.com の openai/*）について、OpenClaw は OpenAI サーバーサイド compaction のペイロードヒントを自動有効化するようになりました：

• store: true を強制します（モデル互換性で supportsStore: false が設定されている場合を除く）
• context_management: [{ type: "compaction", compact_threshold: ... }] を注入します

デフォルトでは、compact_threshold はモデルの contextWindow の 70%（取得できない場合は 80000）に設定されます。

Enable server-side compaction explicitly

互換性のある Responses モデル（例：Azure OpenAI Responses）に対して context_management の注入を強制したい場合に使用します：

{
  agents: {
    defaults: {
      models: {
        "azure-openai-responses/gpt-5.4": {
          params: {
            responsesServerCompaction: true,
          },
        },
      },
    },
  },
}

Enable with a custom threshold

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            responsesServerCompaction: true,
            responsesCompactThreshold: 120000,
          },
        },
      },
    },
  },
}

Disable server-side compaction

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            responsesServerCompaction: false,
          },
        },
      },
    },
  },
}

responsesServerCompaction は context_management の注入のみを制御します。直接的な OpenAI Responses モデルは、互換性設定で supportsStore: false となっていない限り、引き続き store: true を強制します。

注意事項

• モデルの参照には常に provider/model を使用します（/concepts/models を参照）。
• 認証の詳細と再利用ルールについては /concepts/oauth を確認してください。

AI Setup Assistant

次のステップ

• モデルの概念について詳しく学ぶ
• OAuth 認証の仕組みを理解する