OpenClawのOpenAI互換HTTP API

OpenAI Chat Completionsプロトコルを話すものなら何でも、OpenClawのエージェントと通信できます。gatewayが、WebSocketと同じポートで小さな互換インターフェースを提供しているからです。デフォルトではオフで、オンにするとフルのオペレーターアクセスになり、そのmodelフィールドはクライアントが想定しているものとは別の意味を持ちます。ドキュメントに書かれている仕様を紹介します。

何を提供し、誰を信頼するか

• gateway.http.endpoints.chatCompletionsを有効にすると、gatewayはgatewayのポートでPOST /v1/chat/completions、GET /v1/models、単一のモデルIDに対するGET、POST /v1/embeddingsを提供します。responsesエンドポイントは別途有効にします。すべてのリクエストは、agentコマンドと同じコードパスで通常のgatewayエージェント実行として処理されるため、ルーティング、権限、設定はgatewayと一致します。
• このエンドポイントに対する有効なgatewayトークンまたはパスワードは、ユーザー単位のスコープではなく、オーナーまたはオペレーターの認証情報と同等です。共有シークレットのbearer認証はx-openclaw-scopesヘッダーをすべて無視してデフォルトのオペレータースコープ一式を完全に復元し、チャットのターンをオーナーが送信したターンとして扱います。trusted-proxyやプライベートな認証なしのイングレスでは、x-openclaw-scopesがあればそれに従い、オーナーレベルの操作にはoperator.adminが必要です。
• 認証はgatewayのモードに従います。設定または環境変数によるbearerトークンかパスワード、trusted-proxyモードでのID認識プロキシ（同一ホストのループバックプロキシにはallowLoopbackが必要）、またはプライベートなイングレスでのヘッダーなしのいずれかです。trusted proxyを迂回する同一ホストの呼び出し元は、転送ヘッダーの証拠によってプロキシ経路にとどめられない限り、パスワードにフォールバックすることがあります。また、レート制限が設定されている場合、失敗が多すぎるとRetry-After付きの429が返されます。
• ドキュメントは、その連携が単なる別のオペレーター向けインターフェースであるなら、新しい組み込みチャネルよりもこのエンドポイントを推奨しています。ネイティブのモバイルクライアントには、デバイスに共有トークンを載せずに済むよう、ペアリング済みデバイスのフローを備えたWebChatまたはgatewayプロトコルを推奨し、独自のユーザー、ルーム、トランスポートを持つ外部のメッセージングネットワークを連携する場合はチャネルプラグインを推奨しています。

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

modelはエージェント、セッションはuserから

openclawとopenclaw/defaultは設定済みのデフォルトエージェントにルーティングされ、openclaw/またはagent:の後にエージェントIDを続けると、特定のエージェントにルーティングされます。/v1/modelsが一覧表示するのはこうしたエージェントのターゲットで、プロバイダーのモデルでもサブエージェントでもありません。x-openclaw-modelヘッダーは選択したエージェントのバックエンドモデルを上書きします。共有シークレットの呼び出し元なら直接、IDを持つ呼び出し元ならoperator.adminがある場合に限り有効です。x-openclaw-session-keyは明示的にルーティングし、subagent、cron、acpなどの予約済み名前空間を使うと400で拒否されます。x-openclaw-message-channelは、チャネルを意識するプロンプトのために合成のイングレスチャネルを設定します。デフォルトでは各リクエストはステートレスで、毎回新しいセッションキーが使われます。OpenAIのuser文字列を指定すると安定したキーが導出され、繰り返しの呼び出しが1つのセッションを共有します。そのため、会話スレッドごとに1つの値を使い回し、複数のデバイスで1つのセッションを共有したい場合を除いて、アカウントレベルの識別子は避けてください。incognitoセッションを明示的に継続するには実効的なoperator.adminが必要で、プロファイルに基づくレスポンスでは、そのターゲットはnot-foundのforbiddenエラーとして隠されます。

ツール、制限、ストリーミング

• 関数ツールとtool_choice（auto、none、required、または特定の関数の固定）に対応しており、tool-roleのフォローアップメッセージはtool_call_idで紐付けられます。現在の上限指定はmax_completion_tokensで、max_tokensは従来のエイリアスです。temperature、top_p、各種ペナルティ、seed、最大4つのstopシーケンスは検証されたうえでベストエフォートで転送され、送信時のパラメーター名はプロバイダーのトランスポートが決めます。
• リクエストの上限は、ボディが20MB、最新のユーザーメッセージからのimage_urlパーツが8つ、デコード後の画像データが20MBです。URLから取得する画像は、images.allowUrlがオンでない限り拒否されます。デフォルトでは、ホストの許可リスト、許可されたMIMEタイプ、画像1枚あたり10MB、リダイレクト3回、10秒のタイムアウトが適用され、HEICとHEIFはJPEGに正規化されます。また、許可リストにあるホスト名であっても、プライベートIPのブロックを回避することは決してありません。
• streamがtrueの場合、イベントはDONEで終わるdata行として届きます。ツール呼び出しは増分のdeltaチャンクとして届いた後、tool_callsのfinish reasonで終わり、include_usageが設定されていればusageチャンクも届きます。失敗した実行はcompletionではなくエラーを返し、ストリーミング中の失敗はerrorオブジェクトを送った後にDONEを送ります。クライアントが切断すると、ソースのダウンロードとエージェントの実行はキャンセルされます。

gateway APIの全体像はOpenClaw APIの解説で、このエンドポイントが復元または絞り込むオペレータースコープ一式はOpenClawのオペレータースコープの解説で説明しています。

Open WebUIの設定手順

手早く設定するには、ベースURLにgatewayのホストとポートに/v1を付けたもの（macOSのDockerからはhost.docker.internal）、APIキーにgatewayのbearerトークン、モデルにopenclaw/defaultを指定します。bearerを付けて/v1/modelsをcurlで呼び出し、openclaw/defaultが返ってくれば、たいていのOpen WebUI環境は同じベースURLとトークンで接続できます。続く例では、conv接頭辞付きのuser値による安定したセッション、x-openclaw-modelでプロバイダーモデルを固定したストリーミング呼び出し、スラッシュをURLエンコードした1つのモデルの取得、そしてヘッダーでembeddingモデルを指定し、エージェントのメモリの出力次元数を上書きする任意のdimensions整数を付けたembeddingsを示しています。ポートに安全に到達する方法についてはOpenClawのリモートアクセスを、それを守る制御についてはOpenClawのgatewayセキュリティ制御を参照してください。

Dialiでは

Dialiでは、gatewayはプラットフォームのイングレスの背後にあり、実行時の設定はダッシュボードから生成されます。そのため、このインターフェースを公開するかどうかは、ポートを開けることではなく設定上の判断になります。DialiのマネージドOpenClawホスティングではホスティングされるアシスタントについて、Dialiの料金ではそれが含まれるプランについて説明しています。

• デフォルトはオフ。オンにすると、トークンはオーナーアクセスになります。
• modelフィールドはエージェントを、userはセッションを指定します。
• ループバック、tailnet、プライベートなイングレスのいずれかで使い、公開インターネットには決して出さないでください。