API OpenResponses

Gateway dapat menyediakan endpoint POST /v1/responses yang kompatibel dengan OpenResponses. Endpoint ini dinonaktifkan secara default dan menggunakan port yang sama dengan Gateway (multipleks WS + HTTP): http://<gateway-host>:<port>/v1/responses.

Permintaan dijalankan sebagai eksekusi agen Gateway normal (jalur kode yang sama dengan openclaw agent), sehingga perutean, izin, dan konfigurasi sesuai dengan Gateway Anda.

Aktifkan atau nonaktifkan dengan gateway.http.endpoints.responses.enabled. Saat diaktifkan, permukaan kompatibilitas yang sama juga menyediakan GET /v1/models, GET /v1/models/{id}, POST /v1/embeddings, dan POST /v1/chat/completions.

Autentikasi, keamanan, dan perutean

Perilaku operasional sesuai dengan OpenAI Chat Completions:

• Jalur autentikasi sesuai dengan gateway.auth.mode: rahasia bersama (token/password) menggunakan Authorization: Bearer <token-or-password>; proksi tepercaya menggunakan header proksi berbasis identitas (proksi local loopback pada host yang sama memerlukan gateway.auth.trustedProxy.allowLoopback = true, dengan fallback langsung pada host yang sama melalui gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD ketika tidak ada header Forwarded/X-Forwarded-*/X-Real-IP); none pada ingress privat tidak memerlukan header autentikasi. Lihat Autentikasi proksi tepercaya.
• Perlakukan endpoint ini sebagai akses operator penuh ke instans Gateway.
• Mode autentikasi rahasia bersama mengabaikan x-openclaw-scopes yang dideklarasikan bearer dengan cakupan lebih sempit dan memulihkan kumpulan cakupan operator default penuh: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write. Giliran percakapan pada endpoint ini diperlakukan sebagai giliran pengirim pemilik.
• Mode HTTP berbasis identitas tepercaya (proksi tepercaya, atau gateway.auth.mode="none") mematuhi x-openclaw-scopes jika ada; jika tidak, mode tersebut menggunakan kumpulan cakupan operator default sebagai fallback. Semantik pemilik hanya hilang ketika pemanggil secara eksplisit mempersempit cakupan dan tidak menyertakan operator.admin.
• Pilih agen dengan model: "openclaw", "openclaw/default", "openclaw/<agentId>", atau header x-openclaw-agent-id.
• Gunakan x-openclaw-model untuk mengganti model backend agen yang dipilih (memerlukan operator.admin pada jalur autentikasi berbasis identitas).
• Gunakan x-openclaw-session-key untuk perutean sesi eksplisit (ditolak dengan 400 invalid_request_error jika menggunakan namespace yang dicadangkan: subagent:, cron:, acp:).
• Gunakan x-openclaw-message-channel untuk konteks saluran ingress sintetis non-default.

Untuk penjelasan kanonis mengenai model target agen, openclaw/default, penerusan embeddings, dan penggantian model backend, lihat OpenAI Chat Completions.

Lihat Cakupan operator dan Keamanan.

Perilaku sesi

Secara default, endpoint ini tanpa status untuk setiap permintaan (kunci sesi baru dibuat pada setiap pemanggilan).

Jika permintaan menyertakan string user OpenResponses, Gateway memperoleh kunci sesi stabil darinya sehingga pemanggilan berulang dapat berbagi sesi agen.

previous_response_id menggunakan kembali sesi respons sebelumnya ketika permintaan tetap berada dalam cakupan agen/pengguna/sesi-yang-diminta yang sama (dicocokkan berdasarkan subjek autentikasi, ID agen, dan x-openclaw-session-key).

Bentuk permintaan

Item (masukan)

message

Peran: system, developer, user, assistant.

• system dan developer ditambahkan ke prompt sistem.
• Item user atau function_call_output terbaru menjadi "pesan saat ini".
• Pesan pengguna/asisten sebelumnya disertakan sebagai riwayat untuk konteks.

function_call_output (alat berbasis giliran)

Kirim kembali hasil alat ke model:

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

reasoning dan item_reference

Diterima untuk kompatibilitas skema, tetapi diabaikan saat membuat prompt.

Alat (alat fungsi sisi klien)

Sediakan alat dengan tools: [{ type: "function", name, description?, parameters? }].

Jika agen memanggil alat, respons akan mengembalikan item keluaran function_call. Kirim permintaan lanjutan dengan function_call_output untuk melanjutkan giliran.

Untuk tool_choice: "required" dan tool_choice yang disematkan ke fungsi, endpoint mempersempit kumpulan alat fungsi klien yang diekspos, menginstruksikan runtime untuk memanggil alat klien sebelum merespons, dan menolak giliran jika tidak menyertakan pemanggilan alat klien terstruktur yang cocok, sesuai dengan kontrak /v1/chat/completions. Permintaan non-streaming mengembalikan 502 dengan api_error; permintaan streaming memancarkan peristiwa response.failed.

Gambar (input_image)

Mendukung sumber base64 atau URL:

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

Jenis MIME yang diizinkan (default): image/jpeg, image/png, image/gif, image/webp, image/heic, image/heif. Ukuran maksimum (default): 10MB.

File (input_file)

Mendukung sumber base64 atau URL:

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

Jenis MIME yang diizinkan (default): text/plain, text/markdown, text/html, text/csv, application/json, application/pdf. Ukuran maksimum (default): 5MB.

Perilaku saat ini:

• Konten file didekode dan ditambahkan ke prompt sistem, bukan pesan pengguna, sehingga tetap bersifat sementara (tidak dipertahankan dalam riwayat sesi).
• Teks file yang didekode dibungkus sebagai konten eksternal yang tidak tepercaya sebelum ditambahkan, sehingga byte file diperlakukan sebagai data, bukan instruksi tepercaya. Blok yang disisipkan menggunakan penanda batas eksplisit (<<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>>) dan baris metadata Source: External. Blok tersebut sengaja tidak menyertakan banner panjang SECURITY NOTICE: untuk menghemat anggaran prompt; penanda batas dan metadata tetap berlaku.
• PDF terlebih dahulu diurai untuk mengekstrak teks. Jika hanya sedikit teks yang ditemukan, halaman-halaman pertama dirasterisasi menjadi gambar dan diteruskan ke model, serta blok file yang disisipkan menggunakan placeholder [PDF content rendered to images].

Penguraian PDF disediakan oleh plugin bawaan document-extract, yang menggunakan clawpdf dan runtime WebAssembly PDFium terkemasnya untuk ekstraksi teks dan perenderan halaman.

Default pengambilan URL:

• files.allowUrl: true
• images.allowUrl: true
• maxUrlParts: 8 (jumlah total bagian input_file + input_image berbasis URL per permintaan)
• Permintaan dilindungi (resolusi DNS, pemblokiran IP privat, batas pengalihan, batas waktu).
• Daftar izin nama host opsional didukung untuk setiap jenis masukan (files.urlAllowlist, images.urlAllowlist): host persis ("cdn.example.com") atau subdomain wildcard ("*.assets.example.com", tidak cocok dengan domain puncak). Daftar izin yang kosong atau tidak dicantumkan berarti tidak ada pembatasan daftar izin nama host.
• Untuk menonaktifkan pengambilan berbasis URL sepenuhnya, tetapkan files.allowUrl: false dan/atau images.allowUrl: false.

Batas file + gambar (konfigurasi)

Default dapat disesuaikan di bawah 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: 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,          },        },      },    },  },}

Default jika tidak dicantumkan:

Sumber input_image HEIC/HEIF dinormalisasi menjadi JPEG sebelum dikirimkan ke penyedia melalui pemroses gambar bersama OpenClaw (Rastermill), yang menggunakan konverter sistem (sips, ImageMagick, GraphicsMagick, atau ffmpeg) sebagai fallback untuk format yang memerlukan dukungan codec eksternal.

Catatan keamanan: daftar izin URL diberlakukan sebelum pengambilan dan pada setiap tahap pengalihan. Memasukkan nama host ke daftar izin tidak melewati pemblokiran IP privat/internal. Untuk Gateway yang terekspos ke internet, terapkan kontrol lalu lintas keluar jaringan selain perlindungan tingkat aplikasi. Lihat Keamanan.

Streaming (SSE)

Tetapkan stream: true untuk menerima Peristiwa yang Dikirim Server:

• Content-Type: text/event-stream
• Setiap baris peristiwa adalah event: <type> dan data: <json>
• Aliran berakhir dengan data: [DONE]

Jenis peristiwa yang saat ini dipancarkan: 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 (saat terjadi kesalahan).

Penggunaan

usage diisi ketika penyedia yang mendasarinya melaporkan jumlah token. OpenClaw menormalisasi alias umum bergaya OpenAI sebelum penghitung tersebut mencapai antarmuka status/sesi hilir, termasuk input_tokens / output_tokens dan prompt_tokens / completion_tokens.

Kesalahan

Kesalahan menggunakan objek JSON seperti:

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

Kasus umum: 400 isi permintaan tidak valid, 401 autentikasi tidak ada/tidak valid, 403 cakupan operator tidak ada, 405 metode salah, 429 terlalu banyak upaya autentikasi yang gagal (dengan Retry-After).

Contoh

Tanpa aliran:

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

Dengan aliran:

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

Terkait

• Penyelesaian percakapan OpenAI
• Cakupan operator
• OpenAI