OpenResponses API (HTTP)

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

エンドポイントはデフォルトで無効になっています。まず設定で有効にします。

- ''POST /v1/responses''

- ゲートウェイと同じポート（WS + HTTP 多重化）：''http://<gateway-host>:<port>/v1/responses''

内部では、リクエストは通常のゲートウェイプロキシとして実行されます（''openclaw agent'' と同じコードパス）、したがってルーティング/権限/設定はゲートウェイと一致します。

ゲートウェイ認証設定を使用します。ベアラートークンを送信します：

- ''Authorization: Bearer <token>''

Notes:

- ''gateway.auth.mode="token"'' の場合、''gateway.auth.token''（または ''OPENCLAW_GATEWAY_TOKEN''）を使用します。

- ''gateway.auth.mode="password"'' の場合、''gateway.auth.password''（または ''OPENCLAW_GATEWAY_PASSWORD''）を使用します。

カスタムヘッダーは不要：OpenResponses ''model'' フィールドでエージェント ID をエンコードします：

- ''model: "openclaw:<agentId>"'' (example: ''"openclaw:main"'', ''"openclaw:beta"'')

- ''model: "agent:<agentId>"''（エイリアス）

またはヘッダーで特定の OpenClaw エージェントをターゲットにします：

- ''x-openclaw-agent-id: <agentId>''（デフォルト：''main''）

Advanced:

- ''x-openclaw-session-key: '''' でセッションルーティングを完全に制御します。

''gateway.http.endpoints.responses.enabled'' を ''true'' に設定します：

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

''gateway.http.endpoints.responses.enabled'' を ''false'' に設定します：

{
  gateway: {
    http: {
      endpoints: {
        responses: { enabled: false },
      },
    },
  },
}

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

リクエストに OpenResponses ''user'' 文字列が含まれている場合、ゲートウェイはそこから安定したセッションキーを派生するため、繰り返しの呼び出しでエージェントセッションを共有できます。

リクエストはアイテムベースの入力で OpenResponses API に従います。現在サポートされています：

- ''input''：アイテムオブジェクトの文字列または配列。

- ''instructions''：システムプロンプトにマージされます。

- ''tools''：クライアントツール定義（関数ツール）。

- ''tool_choice''：クライアントツールをフィルタリングまたは必須にします。

- ''stream''：SSE ストリーミングを有効にします。

- ''max_output_tokens''：ベストエフォート出力制限（プロバイダー依存）。

- ''user''：安定したセッションルーティング。

受け入れられますが現在は無視されます：

- ''max_tool_calls''

- ''reasoning''

- ''metadata''

- ''store''

- ''previous_response_id''

- ''truncation''

#

ロール：''system''、''developer''、''user''、''assistant''。

- ''system'' と ''developer'' はシステムプロンプトの後に追加されます。

- 最新の ''user'' または ''function_call_output'' アイテムが「現在のメッセージ」になります。

- 以前のユーザー/アシスタントメッセージはコンテキスト履歴として含まれます。

#

ツールの結果をモデルに送り返します：

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

#

互換性のために受け入れられますが、プロンプトを構築するときに無視されます。

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

エージェントがツールを呼び出すことを決定した場合、応答は ''function_call'' 出力アイテムを返します。

その後、''function_call_output'' 経由でフォローアップリクエストを送信してターンを継続します。

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

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

許可される MIME タイプ（現在）：''image/jpeg''、''image/png''、''image/gif''、''image/webp''。

最大サイズ（現在）：10MB。

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。

現在の動作：

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

- PDF はテキストとして解析されます。テキストが少ない場合、最初のページが画像にラスタライズされ、モデルに渡されます。

- PDF 解析には、ノードフレンドリーな ''pdfjs-dist'' のレガシーバージョン（ワーカーなし）を使用します。最新の PDF.js ビルドにはブラウザワーカー/DOM グローバルが必要なため、ゲートウェイでは使用されません。

URL フェッチのデフォルト：

- ''files.allowUrl''：''true''

- ''images.allowUrl''：''true''

- リクエストは保護されています（DNS 解決、プライベート IP ブロッキング、リダイレクト制限、タイムアウト）。

''gateway.http.endpoints.responses'' でデフォルトを調整できます：

{
  gateway: {
    http: {
      endpoints: {
        responses: {
          enabled: true,
          maxBodyBytes: 20000000,
          files: {
            allowUrl: true,
            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,
            allowedMimes: ["image/jpeg", "image/png", "image/gif", "image/webp"],
            maxBytes: 10485760,
            maxRedirects: 3,
            timeoutMs: 10000,
          },
        },
      },
    },
  },
}

省略時のデフォルト：

- ''maxBodyBytes''：20MB

- ''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

''stream: true'' を設定してサーバー送信イベント (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"
  }