OpenClawのOpenResponses API

OpenResponsesのサーフェスは、OpenClaw gatewayへの2つ目のHTTPの入り口です。ポート、認証ルール、エージェント優先のモデル契約をchat completionsエンドポイントと共有していますが、アイテムベースの入力を受け取り、関数呼び出しを出力アイテムとして返し、ファイルを受け付けます。ここでは、ドキュメントに記載されている動作を、適用される上限とともに紹介します。

有効化と信頼

• responsesエンドポイントの設定を有効にすると、gatewayのポート上でresponsesルートが有効になり、それとともにモデル一覧、単一モデルの参照、embeddingsも有効になります。chat completionsは別途有効にします。すべてのリクエストは通常のgatewayのエージェント実行として動くため、ルーティング、権限、設定はgatewayと一致します。
• 認証はgatewayのモードに従います。共有シークレット方式のモードではbearerトークンまたはパスワード、trusted-proxyではアイデンティティを認識するプロキシのヘッダー（同一ホストのループバックプロキシにはループバックのオプトインが必要で、転送ヘッダーがない場合は直接のパスワードフォールバックがあります）、プライベートなイングレス上のnoneではヘッダーなしです。このエンドポイントはオペレーターのフルアクセスです。共有シークレット方式のモードでは、より狭いスコープを宣言したヘッダーは無視されてデフォルトのオペレータースコープセットが復元され、アイデンティティを伴うモードでは、ヘッダーが存在すればそれが尊重されます。
• エージェントは、modelをopenclaw、openclaw/default、openclaw/にエージェントIDを付けたものに設定するか、agent-idヘッダーで選択します。modelヘッダーはバックエンドのモデルを上書きし（アイデンティティを伴う経路ではadminが必要）、session-keyヘッダーは明示的にルーティングし、予約されたsubagent、cron、acpの名前空間では400で拒否されます。message-channelヘッダーは合成のイングレスチャネルを設定します。
• このエンドポイントはデフォルトでリクエストごとにステートレスです。user文字列から安定したセッションキーが導出され、previous_response_idは、リクエストが同じエージェント、ユーザー、要求されたセッションのスコープ内にとどまる場合に以前のresponseのセッションを再利用します。照合は認証の主体、エージェントID、session-keyヘッダーで行われます。incognitoセッションを明示的に継続するには実効的なadmin権限が必要で、それがなければ対象を隠した403 forbiddenが返されます。

ファイルの内容はデコードされてユーザーメッセージではなくシステムプロンプトに追加されるため、一時的なものにとどまります（セッション履歴には保存されません）。

アイテム、ツール、ファイル

inputフィールドは文字列またはアイテムの配列です。メッセージアイテムはsystem、developer、user、assistantのロールを持ちます。systemとdeveloperはシステムプロンプトに追加され、最新のuserまたはfunction_call_outputアイテムが現在のメッセージになり、それより前のターンは履歴になります。instructionsはシステムプロンプトにマージされます。toolsはクライアントの関数ツールで、tool choiceはauto、none、required、または名前付きの関数を取ります。出力トークンの上限はベストエフォートで、temperatureとtop_pもベストエフォートであり、ChatGPTベースのCodex Responsesバックエンドでは無視されます。ツール呼び出しの上限、reasoning、metadata、store、truncationは受け付けられますが無視されます。エージェントがツールを呼び出すと、レスポンスはfunction_call出力アイテムを返し、クライアントは呼び出しIDを含むfunction_call_outputでターンを続けます。出力が空でも呼び出しは完了します。独自に履歴を保持するクライアントは、レスポンスの出力をそのまま次の入力に追加するか、previous_response_idと新しいアイテムだけを送ります。requiredまたは固定されたtool choiceで一致する呼び出しが得られなかった場合は502 api_errorが返され、ストリーミング時にはfailedのresponseイベントになります。

ファイル、画像、上限

• 画像アイテムはbase64またはURLのソースを受け付け、デフォルトでJPEG、PNG、GIF、WebP、HEIC、HEIFが許可され、1画像あたり10 MBで、HEICとHEIFはJPEGに正規化されます。ファイルアイテムはbase64またはURLを受け付け、デフォルトでプレーンテキスト、Markdown、HTML、CSV、JSON、PDFが許可され、上限は5 MBと6万文字です。テキストは検出されたエンコーディングでデコードされ、PDFはまずテキストが解析され、テキストがほとんど見つからない場合は最初の数ページが画像にラスタライズされます（デフォルトで4ページ、400万ピクセル、最小200文字）。
• デコードされたファイルのテキストは、プロンプトに入る前に、明示的な境界マーカーとソース行を伴う信頼できない外部コンテンツとしてラップされるため、ファイルのバイト列は命令ではなくデータとして扱われます。URLの取得はファイルと画像でデフォルトで有効で、1リクエストあたり8つのURLパーツまでです。DNS解決、プライベートアドレスのブロック、リダイレクト回数の上限、タイムアウト、そして任意のタイプ別ホスト名許可リストで保護されます。この許可リストは完全一致のホストかワイルドカードのサブドメインを取り、取得の前とリダイレクトのたびに適用されます。
• リクエストボディの上限は20 MBです。ストリーミングを有効にすると、イベントは型付き（created、in progress、output item added、content part added、output text deltaとdone、output item done、completed、出力予算で切り詰められたときのincomplete、エラー時のfailed）になり、DONEで終わります。出力トークンの予算で途切れた返信はmax output tokensを理由とするincompleteステータスを返し、プロバイダーがトークン数を報告する場合はusageが設定されます。エラーは400、401、スコープ不足の場合の403、405、そして認証の失敗が多すぎた後のretryヘッダー付きの429です。

このエンドポイントがモデル契約を再利用している兄弟エンドポイントについてはOpenClawのOpenAI互換HTTP APIを、両者が復元または絞り込むスコープセットについてはOpenClawのオペレータースコープをご覧ください。

使いどころ

アイテムモデルは、すでに独自の会話履歴を保持していてそれをそのまま再生したいクライアントや、ファイルや画像をセッションに保存せずにエージェントへ渡す必要があるクライアントに適しています。chat completionsエンドポイントは、古い形式しか知らないツールに適しています。どちらも内部では同じエージェント実行が動くため、選択はエージェントではなくクライアントで決まります。より広いgateway APIについてはOpenClawのAPIで、リクエストが届いた後にエージェント自身がURLをどう扱うかについてはOpenClawのweb fetchで解説しています。

Dialiでは

Dialiでは、gatewayはプラットフォームのイングレスの背後にあり、ランタイムの設定はダッシュボードから生成されてリリースごとに置き換えられます。そのため、どちらのHTTPサーフェスを有効にするかは、開くポートの問題ではなく設定の判断です。ホスト型のアシスタントについてはDialiのマネージドOpenClawホスティングを、それが含まれるプランについてはDialiの料金をご覧ください。

• アイテムを入力し、関数呼び出しを出力し、結果はfunction_call_outputで返します。
• ファイルは信頼できないコンテンツとしてシステムプロンプトに入ります。
• chat completionsと同じポート、同じ認証、同じオーナーレベルの信頼です。