OpenResponses API

​

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

• 認証パスは gateway.auth.mode と同じです。共有シークレット（token/password）では Authorization: Bearer <token-or-password> を使用します。trusted-proxy では ID 対応プロキシヘッダーを使用します（同一ホストのループバックプロキシには gateway.auth.trustedProxy.allowLoopback = true が必要です。Forwarded/X-Forwarded-*/X-Real-IP ヘッダーが存在しない場合は、gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD による同一ホストの直接フォールバックを使用します）。プライベートイングレスの none には認証ヘッダーは不要です。信頼済みプロキシ認証を参照してください。
• このエンドポイントは、Gateway インスタンスへの完全なオペレーターアクセスとして扱ってください。
• 共有シークレット認証モードでは、Bearer で宣言されたより狭い x-openclaw-scopes は無視され、完全なデフォルトのオペレータースコープセット（operator.admin、operator.approvals、operator.pairing、operator.read、operator.talk.secrets、operator.write）が復元されます。このエンドポイントでのチャットターンは、所有者が送信したターンとして扱われます。
• 信頼済みの ID 保持 HTTP モード（trusted-proxy または gateway.auth.mode="none"）では、x-openclaw-scopes が存在する場合はそれを尊重し、存在しない場合はデフォルトのオペレータースコープセットにフォールバックします。所有者のセマンティクスが失われるのは、呼び出し元が明示的にスコープを狭め、かつ operator.admin を省略した場合のみです。
• model: "openclaw"、"openclaw/default"、"openclaw/<agentId>"、または x-openclaw-agent-id ヘッダーを使用してエージェントを選択します。
• 選択したエージェントのバックエンドモデルを上書きするには x-openclaw-model を使用します（ID 保持認証パスでは operator.admin が必要です）。
• 明示的なセッションルーティングには x-openclaw-session-key を使用します（予約済み名前空間 subagent:、cron:、acp: を使用すると、400 invalid_request_error で拒否されます）。
• デフォルト以外の合成イングレスチャネルコンテキストには x-openclaw-message-channel を使用します。

​

セッションの動作

​

リクエスト形式

​

アイテム（入力）

​

message

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

​

function_call_output（ターンベースのツール）

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

​

reasoning と item_reference

​

ツール（クライアント側の関数ツール）

​

画像（input_image）

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

​

ファイル（input_file）

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

• ファイルの内容はデコードされ、ユーザーメッセージではなくシステムプロンプトに追加されるため、一時的なままです（セッション履歴には永続化されません）。
• デコードされたファイルテキストは、追加される前に信頼されていない外部コンテンツとしてラップされるため、ファイルのバイト列は信頼済みの指示ではなくデータとして扱われます。挿入されるブロックでは、明示的な境界マーカー（<<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>）と Source: External メタデータ行が使用されます。プロンプトの容量を確保するため、長い SECURITY NOTICE: バナーは意図的に省略されますが、境界マーカーとメタデータは引き続き適用されます。
• PDF は最初にテキスト抽出のために解析されます。テキストがほとんど見つからない場合、最初の数ページが画像にラスタライズされてモデルに渡され、挿入されるファイルブロックではプレースホルダー [PDF content rendered to images] が使用されます。

• 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: {
          enabled: true,
          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: 60000,
            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,
          },
        },
      },
    },
  },
}

​

ストリーミング（SSE）

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

​

使用量

​

エラー

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

​

例

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

​

関連項目

• OpenAI チャット補完
• オペレータースコープ
• OpenAI