OpenAI チャット補完

Gateway は、小規模な OpenAI 互換 Chat Completions サーフェスを提供できます。これはデフォルトでは無効です。

有効にすると、Gateway と同じポート（WS + HTTP 多重化）で以下すべてを提供します。

リクエストは通常の Gateway エージェント実行として処理され（openclaw agent と同じコードパス）、ルーティング、権限、設定は使用中の Gateway と一致します。

エンドポイントの有効化

{  gateway: {    http: {      endpoints: {        chatCompletions: { enabled: true },      },    },  },}

無効にするには、enabled: false を設定します（または省略します）。

セキュリティ境界（重要）

このエンドポイントは、Gateway インスタンスへの完全なオペレーターアクセスとして扱ってください。

• このエンドポイントに対する有効な Gateway トークン／パスワードは、限定されたユーザー単位のスコープではなく、所有者／オペレーターの認証情報に相当します。
• リクエストは、信頼されたオペレーター操作と同じコントロールプレーンのエージェントパスを通じて実行されるため、対象エージェントのポリシーで機密性の高いツールが許可されている場合、このエンドポイントからそれらを使用できます。
• loopback／tailnet／プライベートイングレスのみに配置してください。公開インターネットに公開しないでください。

認証マトリクス：

オペレータースコープ、セキュリティ、リモートアクセスを参照してください。

認証

Gateway の認証設定を使用します（このモードの詳細については、信頼済みプロキシ認証を参照してください）。

注：

• trusted-proxy Gateway 上でプロキシを迂回する同一ホストの呼び出し元は、gateway.auth.password／OPENCLAW_GATEWAY_PASSWORD に直接フォールバックできます。Forwarded、X-Forwarded-*、または X-Real-IP のいずれかのヘッダー証拠がある場合、リクエストは代わりに trusted-proxy パスに維持されます。
• gateway.auth.rateLimit が設定されており、認証試行が何度も失敗した場合、エンドポイントは Retry-After ヘッダー付きで 429 を返します。

このエンドポイントを使用する場合

• 統合が同じ Gateway に対する別のオペレーター／クライアントサーフェスにすぎない場合は、新しい組み込みチャネルを追加するよりも、これを優先してください。
• リモート Gateway に直接接続するネイティブモバイルクライアントでは、デバイスが共有 HTTP トークン／パスワードを必要としないように、ペアリング済みデバイスのブートストラップ／デバイストークンフローを備えた WebChat または Gateway プロトコルを使用することを推奨します。
• 独自のユーザー、ルーム、Webhook 配信、または送信トランスポートを持つ外部メッセージングネットワークと統合する場合は、代わりにチャネル Plugin を構築してください。Plugin の構築を参照してください。

エージェント優先のモデル契約

OpenClaw は、OpenAI の model フィールドを生のプロバイダーモデル ID ではなく、エージェントの対象として扱います。

任意のリクエストヘッダー：

/v1/models は、バックエンドプロバイダーモデルやサブエージェントではなく、トップレベルのエージェント対象（openclaw、openclaw/default、openclaw/<agentId>）を一覧表示します。サブエージェントは内部の実行トポロジーに留まります。x-openclaw-model を省略した場合、選択されたエージェントは通常どおり設定済みのモデルで実行されます。

/v1/embeddings は、同じエージェント対象の model ID を使用します。特定の埋め込みモデルを選択するには、x-openclaw-model を送信します（共有シークレットの呼び出し元、または operator.admin を持つ ID 情報付きの呼び出し元から）。それ以外の場合、リクエストは選択されたエージェントの通常の埋め込み設定を使用します。

セッションの動作

デフォルトでは、エンドポイントはリクエストごとにステートレスです（呼び出しごとに新しいセッションキーが生成されます）。

リクエストに OpenAI の user 文字列が含まれている場合、Gateway はそこから安定したセッションキーを導出するため、繰り返し呼び出すことでエージェントセッションを共有できます。カスタムアプリでは、会話スレッドごとに同じ user 値を再利用してください。複数の会話／デバイスで 1 つの OpenClaw セッションを共有したい場合を除き、アカウントレベルの識別子は避けてください。複数のクライアント／スレッド間で明示的なルーティング制御が必要な場合にのみ、上記の予約済み名前空間を回避するアプリケーション所有のキーとともに x-openclaw-session-key を使用してください。

リクエスト制限

このエンドポイントには、リクエスト本文あたり 20 MB、最新のユーザーメッセージから 8 個の image_url パート、デコード済み画像データの累計 20 MB という組み込み制限があります。 画像ソースポリシーは、 gateway.http.endpoints.chatCompletions.images で引き続き設定できます。

{  gateway: {    http: {      endpoints: {        chatCompletions: {          enabled: true,          images: {            allowUrl: false,            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],            allowedMimes: [              "image/jpeg",              "image/png",              "image/gif",              "image/webp",              "image/heic",              "image/heif",            ],            maxBytes: 10485760,            maxRedirects: 3,            timeoutMs: 10000,          },        },      },    },  },}

画像設定のデフォルトは次のとおりです。

HEIC／HEIF の image_url ソースは受け入れられ、共有 OpenClaw 画像プロセッサ（Rastermill）を通じてプロバイダーに配信される前に JPEG に正規化されます。このプロセッサは、外部コーデックのサポートが必要な形式について、システムコンバーター（sips、ImageMagick、GraphicsMagick、または ffmpeg）にフォールバックします。

セキュリティ上の注意：ホスト名を許可リストに登録しても、プライベート／内部 IP のブロックは回避されません。インターネットに公開される Gateway では、アプリレベルのガードに加えて、ネットワークの外向き通信制御を適用してください。セキュリティを参照してください。

チャットツール契約

/v1/chat/completions は、一般的な OpenAI Chat クライアントと互換性のある関数ツールのサブセットをサポートします。

サポートされるリクエストフィールド

すべてのサンプリングフィールドとトークン上限フィールドは同じエージェントストリームパラメーターチャネルを通り、ベストエフォートで転送されます。

• トークン上限: ワイヤー上のフィールド名はプロバイダーのトランスポートによって選択されます。OpenAI 系エンドポイントでは max_completion_tokens、レガシー名のみを受け付けるプロバイダー（Mistral、Chutes）では max_tokens です。
• stop はトランスポートの停止フィールドにマッピングされます。Chat Completions バックエンドでは stop、Anthropic では stop_sequences です。OpenAI Responses API には停止パラメーターがないため、Responses ベースのモデルには stop が適用されません。
• ChatGPT ベースの Codex Responses バックエンドは、固定されたサーバー側サンプリングを使用し、リクエストがそのバックエンドに到達する前に temperature/top_p（および max_output_tokens、metadata、prompt_cache_retention、service_tier）を除去します。

サポートされていないバリアント

次の場合は 400 invalid_request_error を返します。

• 配列でない tools、関数でないツール項目、または tool.function.name の欠落
• allowed_tools や custom などの tool_choice バリアント
• 指定されたツールと一致しない tool_choice.function.name 値

tool_choice: "required" および関数が固定された tool_choice の場合、エンドポイントは公開されるクライアント関数ツールのセットを絞り込み、応答前にクライアントツールを呼び出すようランタイムに指示し、エージェント応答に一致する構造化クライアントツール呼び出しがない場合はエラーにします。これは呼び出し元が指定した HTTP tools リストに適用され、OpenClaw エージェントのすべての内部ツールに適用されるわけではありません。

非ストリーミングのツール応答形式

エージェントがツールを呼び出す場合、応答には以下が使用されます。

• choices[0].finish_reason = "tool_calls"
• id、type: "function"、function.name、function.arguments（JSON 文字列）を含む choices[0].message.tool_calls[] 項目
• ツール呼び出し前のアシスタントの解説。choices[0].message.content に格納されます（空の場合があります）

ストリーミングのツール応答形式

stream: true の場合、ツール呼び出しは増分 SSE チャンクとして到着します。最初にアシスタントロールの差分、任意のアシスタント解説の差分、次にツールの識別情報と引数の断片を伝える 1 個以上の delta.tool_calls チャンク、最後に finish_reason: "tool_calls" と data: [DONE] を含むチャンクが続きます。

stream_options.include_usage=true の場合、[DONE] の前に末尾の使用量チャンクが送出されます。

ツールの後続ループ

tool_calls を受信したら、要求された関数を実行し、以前のアシスタントのツール呼び出しメッセージと、一致する tool_call_id を持つ 1 個以上の role: "tool" メッセージを含めた後続リクエストを送信します。これにより、同じエージェント推論ループが継続され、最終回答が生成されます。

ストリーミング（SSE）

Server-Sent Events を受信するには stream: true を設定します。

• Content-Type: text/event-stream
• 各イベント行は data: <json> です
• ストリームは data: [DONE] で終了します

Open WebUI のクイックセットアップ

• ベース URL: http://127.0.0.1:18789/v1
• macOS 上の Docker のベース URL: http://host.docker.internal:18789/v1
• API キー: Gateway のベアラートークン
• モデル: openclaw/default

期待される動作: GET /v1/models は openclaw/default を一覧表示し、Open WebUI はこれをチャットモデル ID として使用します。特定のバックエンドプロバイダーやモデルを使用するには、エージェントの通常のデフォルトモデルを設定するか、x-openclaw-model を送信します（共有シークレットを使用する呼び出し元、または operator.admin を持つアイデンティティ付きの呼び出し元）。

簡単なスモークテスト:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

これが openclaw/default を返す場合、ほとんどの Open WebUI セットアップでは同じベース URL とトークンで接続できます。

例

1 つのアプリ会話で安定したセッションを使用する場合:

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "user": "conv:YOUR_CONVERSATION_ID",    "messages": [{"role":"user","content":"今日のタスクを要約してください"}]  }'

その会話の後続の呼び出しで同じ user 値を再利用すると、同じエージェントセッションを継続できます。

非ストリーミング:

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "messages": [{"role":"user","content":"こんにちは"}]  }'

ストリーミング:

curl -N http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/gpt-5.4' \  -d '{    "model": "openclaw/research",    "stream": true,    "messages": [{"role":"user","content":"こんにちは"}]  }'

モデル一覧:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

1 つのモデルを取得:

curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \  -H 'Authorization: Bearer YOUR_TOKEN'

埋め込みを作成:

curl -sS http://127.0.0.1:18789/v1/embeddings \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/text-embedding-3-small' \  -d '{    "model": "openclaw/default",    "input": ["alpha", "beta"]  }'

/v1/embeddings は、文字列または文字列の配列として input をサポートします。

関連項目

• 設定リファレンス
• オペレータースコープ
• OpenAI