OpenClaw GatewayでOpenResponses APIを使う方法

AIアプリケーションを開発していると、複数のモデルやAPI形式を使い分けるのが大変に感じることがありますよね。特にセッション管理や認証の仕組みがバラバラだと、実装が複雑になり、メンテナンスも一苦労です。

OpenClawのGatewayでは、こうした開発者の悩みを解決するためにOpenResponses互換のエンドポイントを提供しています。これを使えば、既存のツールやワークフローを活かしながら、よりシンプルにエージェントを操作できるようになります。

OpenResponses API (HTTP)

OpenClawのGatewayは、OpenResponses互換の POST /v1/responses エンドポイントを提供できます。

このエンドポイントはデフォルトで無効になっています。利用を始める前に、まず設定で有効にしてください。

POST /v1/responses
Gatewayと同じポート（WS + HTTPマルチプレックス）: http://<gateway-host>:<port>/v1/responses

内部的には、リクエストは通常のGatewayエージェントの実行（openclaw agent と同じコードパス）として処理されます。そのため、ルーティング、権限、設定はGatewayの構成とそのまま一致します。

認証、セキュリティ、ルーティング

動作の詳細は OpenAI Chat Completions と共通しています。

通常のGateway認証設定に従い、Authorization: Bearer <token> を使用してください。
このエンドポイントは、Gatewayインスタンスへのフルオペレーターアクセスとして扱ってください。
共有シークレット認証モード（token および password）の場合、ヘッダーで宣言された狭い範囲の x-openclaw-scopes 値は無視され、通常のフルオペレーター権限が適用されます。
信頼されたIDを保持するHTTPモード（例：信頼されたプロキシ認証や gateway.auth.mode="none"）では、リクエストで宣言されたオペレータースコープが尊重されます。
エージェントの選択には、model: "openclaw", model: "openclaw/default", model: "openclaw/<agentId>", または x-openclaw-agent-id を使用します。
選択したエージェントのバックエンドモデルを上書きしたい場合は、x-openclaw-model を使用してください。
明示的なセッションルーティングには x-openclaw-session-key を使用します。
デフォルト以外の合成イングレスチャネルコンテキストが必要な場合は、x-openclaw-message-channel を使用してください。

認証マトリックス：

gateway.auth.mode="token" または "password" + Authorization: Bearer ...
- 共有Gatewayオペレーターシークレットの所有を証明します。
- より狭い x-openclaw-scopes を無視します。
- フルデフォルトオペレータースコープセットを復元します。
- このエンドポイントでのチャットターンをオーナー送信者のターンとして扱います。
信頼されたIDを保持するHTTPモード（例：信頼されたプロキシ認証、またはプライベートイングレスでの gateway.auth.mode="none"）
- 宣言された x-openclaw-scopes ヘッダーを尊重します。
- 宣言されたスコープ内に operator.admin が実際に存在する場合にのみ、オーナーセマンティクスを取得します。

このエンドポイントの有効化・無効化は gateway.http.endpoints.responses.enabled で設定します。

同じ互換性サーフェスには以下も含まれます：

GET /v1/models
GET /v1/models/{id}
POST /v1/embeddings
POST /v1/chat/completions

エージェントターゲットモデル、openclaw/default、embeddingsのパススルー、バックエンドモデルの上書きがどのように組み合わさるかの公式な解説については、OpenAI Chat Completions および Model list and agent routing を参照してください。

セッションの動作

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

リクエストにOpenResponsesの user 文字列が含まれている場合、Gatewayはそこから固定のセッションキーを派生させます。これにより、繰り返しの呼び出しで同じエージェントセッションを共有できるようになります。

リクエストの形式（サポート済み）

リクエストは、アイテムベースの入力を持つOpenResponses APIに従います。現在のサポート状況は以下の通りです：

input: 文字列またはアイテムオブジェクトの配列。
instructions: システムプロンプトにマージされます。
tools: クライアントツールの定義（関数ツール）。
tool_choice: クライアントツールのフィルタリングまたは必須化。
stream: SSEストリーミングを有効にします。
max_output_tokens: ベストエフォートの出力制限（プロバイダーに依存）。
user: 固定セッションルーティング。

受け入れられますが、現在は無視される項目：

max_tool_calls
reasoning
metadata
store
truncation

サポート済み：

previous_response_id: リクエストが同じエージェント/ユーザー/リクエストセッションの範囲内にある場合、OpenClawは以前のレスポンスセッションを再利用します。

アイテム（入力）

`message`

ロール: system, developer, user, assistant

system と developer はシステムプロンプトに追加されます。
最新の user または function_call_output アイテムが「現在のメッセージ」になります。
以前の user/assistant メッセージは、コンテキストの履歴として含まれます。

`function_call_output` (ターンベースのツール)

ツールの実行結果をモデルに返します：

{
  "type": "function_call_output",
  "call_id": "call_123",
  "output": "{\"temperature\": \"72F\"}"
}

`reasoning` と `item_reference`

スキーマ互換性のために受け入れられますが、プロンプト作成時には無視されます。

ツール（クライアントサイド関数ツール）

tools: [{ type: "function", function: { name, description?, parameters? } }] の形式でツールを提供します。

エージェントがツールの呼び出しを決定した場合、レスポンスは function_call 出力アイテムを返します。その後、function_call_output を含むフォローアップリクエストを送信してターンを続行してください。

画像（`input_image`）

base64またはURLソースをサポートしています：

{
  "type": "input_image",
  "source": { "type": "url", "url": "https://example.com/image.png" }
}

許可されるMIMEタイプ（現在）：image/jpeg, image/png, image/gif, image/webp, image/heic, image/heif 最大サイズ（現在）：10MB

ファイル（`input_file`）

base64またはURLソースをサポートしています：

{
  "type": "input_file",
  "source": {
    "type": "base64",
    "media_type": "text/plain",
    "data": "SGVsbG8gV29ybGQh",
    "filename": "hello.txt"
  }
}

許可されるMIMEタイプ（現在）：text/plain, text/markdown, text/html, text/csv, application/json, application/pdf

最大サイズ（現在）：5MB

現在の動作：

ファイルの内容はデコードされ、ユーザーメッセージではなくシステムプロンプトに追加されます。そのため、セッション履歴には保存されず、一時的な（ephemeral）情報として扱われます。
PDFはテキストが解析されます。テキストがほとんど見つからない場合は、最初の数ページが画像としてラスタライズされ、モデルに渡されます。

PDFの解析には、Node.jsフレンドリーな pdfjs-dist レガシービルド（ワーカーなし）を使用しています。最新の PDF.js ビルドはブラウザのワーカーやDOMグローバルを必要とするため、Gatewayでは使用されていません。

URL取得のデフォルト設定：

files.allowUrl: true
images.allowUrl: true
maxUrlParts: 8（リクエストあたりのURLベースの input_file + input_image の合計パーツ数）
リクエストは保護されています（DNS解決、プライベートIPブロック、リダイレクト制限、タイムアウト）。
入力タイプごとにオプションのホスト名許可リストがサポートされています（files.urlAllowlist, images.urlAllowlist）。
- 完全一致: "cdn.example.com"
- ワイルドカードサブドメイン: "*.assets.example.com"（apexには一致しません）
- 許可リストが空または省略されている場合は、ホスト名の制限はありません。
URLベースの取得を完全に無効にするには、files.allowUrl: false または images.allowUrl: false を設定してください。

ファイルと画像の制限（設定）

デフォルト設定は gateway.http.endpoints.responses で調整可能です：

{
  gateway: {
    http: {
      endpoints: {
        responses: {
          enabled: true,
          maxBodyBytes: 20000000,
          maxUrlParts: 8,
          files: {
            allowUrl: true,
            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],
            allowedMimes: [
              "text/plain",
              "text/markdown",
              "text/html",
              "text/csv",
              "application/json",
              "application/pdf",
            ],
            maxBytes: 5242880,
            maxChars: 200000,
            maxRedirects: 3,
            timeoutMs: 10000,
            pdf: {
              maxPages: 4,
              maxPixels: 4000000,
              minTextChars: 200,
            },
          },
          images: {
            allowUrl: true,
            urlAllowlist: ["images.example.com"],
            allowedMimes: [
              "image/jpeg",
              "image/png",
              "image/gif",
              "image/webp",
              "image/heic",
              "image/heif",
            ],
            maxBytes: 10485760,
            maxRedirects: 3,
            timeoutMs: 10000,
          },
        },
      },
    },
  },
}

省略時のデフォルト値：

maxBodyBytes: 20MB
maxUrlParts: 8
files.maxBytes: 5MB
files.maxChars: 200k
files.maxRedirects: 3
files.timeoutMs: 10s
files.pdf.maxPages: 4
files.pdf.maxPixels: 4,000,000
files.pdf.minTextChars: 200
images.maxBytes: 10MB
images.maxRedirects: 3
images.timeoutMs: 10s
HEIC/HEIF の input_image ソースは受け入れられ、プロバイダーに配信される前に JPEG に正規化されます。

セキュリティ上の注意：

URL許可リストは、取得前およびリダイレクトホップ時に適用されます。
ホスト名を許可リストに登録しても、プライベート/内部IPのブロックはバイパスされません。
インターネットに公開されているGatewayについては、アプリケーションレベルの保護に加えて、ネットワークの下り（egress）制御を適用してください。Security を参照してください。

ストリーミング（SSE）

stream: true を設定すると、Server-Sent Events (SSE) を受信できます：

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

現在発行されるイベントタイプ：

response.created
response.in_progress
response.output_item.added
response.content_part.added
response.output_text.delta
response.output_text.done
response.content_part.done
response.output_item.done
response.completed
response.failed（エラー時）

使用量

usage は、基盤となるプロバイダーがトークン数を報告した際に入力されます。

エラー

エラーは次のようなJSONオブジェクトで返されます：

{ "error": { "message": "...", "type": "invalid_request_error" } }

一般的なケース：

401 認証情報の不足または無効
400 無効なリクエストボディ
405 間違ったメソッド

例

ストリーミングなし：

curl -sS http://127.0.0.1:18789/v1/responses \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-agent-id: main' \
  -d '{
    "model": "openclaw",
    "input": "hi"
  }'

ストリーミングあり：

curl -N http://127.0.0.1:18789/v1/responses \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-agent-id: main' \
  -d '{
    "model": "openclaw",
    "stream": true,
    "input": "hi"
  }'

設定や導入でお困りの際は、AI Setup Assistant をぜひ活用してください。

次のステップ

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。