API OpenResponses OpenClaw

Permukaan OpenResponses adalah pintu HTTP kedua menuju gateway OpenClaw. Permukaan ini berbagi port, aturan autentikasi, dan kontrak model yang berorientasi agen dengan endpoint chat completions, tetapi menerima input berbasis item, mengembalikan panggilan fungsi sebagai item output, dan menerima file. Berikut apa yang dilakukannya menurut dokumentasi, beserta batas yang berlaku.

Mengaktifkan dan memercayainya

• Pengaturan endpoint responses mengaktifkan rute responses di port gateway dan, bersamanya, daftar model, pencarian satu model, dan embeddings; chat completions diaktifkan secara terpisah, dan setiap permintaan berjalan sebagai eksekusi agen gateway biasa sehingga routing, izin, dan konfigurasi sama dengan gateway.
• Autentikasi mengikuti mode gateway: bearer token atau kata sandi untuk mode dengan rahasia bersama, header proxy yang sadar identitas untuk trusted-proxy (proxy loopback di host yang sama memerlukan opt-in loopback, dengan fallback kata sandi langsung jika tidak ada header forwarded), tanpa header untuk none di ingress privat; endpoint ini memberi akses operator penuh, mode dengan rahasia bersama mengabaikan header scope yang dideklarasikan lebih sempit dan memulihkan set scope operator default, dan mode yang membawa identitas menghormati header tersebut jika ada.
• Agen dipilih dengan model yang diatur ke openclaw, openclaw/default, openclaw/ ditambah id agen, atau header agent-id; header model meng-override model backend (admin pada jalur yang membawa identitas), header session-key melakukan routing secara eksplisit dan ditolak dengan 400 di namespace yang dicadangkan untuk subagent, cron, dan acp, dan header message-channel menetapkan saluran ingress sintetis.
• Endpoint ini secara default stateless per permintaan; string user menurunkan session key yang stabil, dan previous_response_id menggunakan ulang sesi respons sebelumnya jika permintaan tetap berada dalam scope agen, pengguna, dan sesi yang diminta yang sama, dicocokkan berdasarkan subjek autentikasi, id agen, dan header session-key; melanjutkan sesi incognito secara eksplisit memerlukan otoritas admin yang efektif, dan jika tidak, akan mengembalikan 403 forbidden yang menyembunyikan targetnya.

Konten file didekode dan ditambahkan ke system prompt, bukan ke pesan pengguna, sehingga tetap sementara (tidak disimpan dalam riwayat sesi).

Item, alat, dan file

Kolom input berupa string atau array item. Item pesan membawa peran system, developer, user, dan assistant: system dan developer ditambahkan ke system prompt, item user atau function_call_output terbaru menjadi pesan saat ini, dan giliran sebelumnya menjadi riwayat. Instruksi digabungkan ke dalam system prompt; alat yang diterima adalah alat fungsi di sisi klien, pilihan alat menerima auto, none, required, atau fungsi bernama, batas token output bersifat best-effort, temperature dan top_p bersifat best-effort dan diabaikan oleh backend Codex Responses berbasis ChatGPT, dan batas panggilan alat, reasoning, metadata, store, serta truncation diterima tetapi diabaikan. Saat agen memanggil alat, respons mengembalikan item output function_call dan klien melanjutkan giliran dengan function_call_output yang membawa id panggilan; output kosong tetap menyelesaikan panggilan. Klien yang menyimpan riwayatnya sendiri menambahkan output respons ke input berikutnya tanpa mengubahnya, atau mengirim previous_response_id hanya dengan item baru. Pilihan alat required atau yang disematkan yang tidak menghasilkan panggilan yang cocok akan mengembalikan 502 api_error, atau peristiwa respons failed saat streaming.

File, gambar, dan batas

• Item gambar menerima sumber base64 atau URL dengan JPEG, PNG, GIF, WebP, HEIC, dan HEIF yang diizinkan secara default dan 10 MB per gambar, dengan HEIC dan HEIF dinormalisasi menjadi JPEG; item file menerima base64 atau URL dengan teks biasa, markdown, HTML, CSV, JSON, dan PDF yang diizinkan secara default, 5 MB dan 60k karakter, teks didekode dengan encoding yang terdeteksi, dan PDF diurai untuk teksnya terlebih dahulu, dengan halaman-halaman pertama dirasterisasi menjadi gambar jika teks yang ditemukan sedikit (secara default 4 halaman, 4 juta piksel, minimum 200 karakter).
• Teks file yang didekode dibungkus sebagai konten eksternal yang tidak tepercaya dengan penanda batas eksplisit dan baris sumber sebelum masuk ke prompt, sehingga byte file diperlakukan sebagai data, bukan instruksi; pengambilan URL aktif secara default untuk file dan gambar dengan 8 bagian URL per permintaan, dilindungi oleh resolusi DNS, pemblokiran alamat privat, batas redirect, dan timeout, serta daftar izin hostname opsional per jenis yang menerima host persis atau subdomain wildcard dan diberlakukan sebelum pengambilan dan pada setiap lompatan redirect.
• Body permintaan dibatasi 20 MB; saat streaming aktif, peristiwanya bertipe (created, in progress, output item added, content part added, output text delta dan done, output item done, completed, incomplete saat terpotong karena anggaran output, dan failed saat terjadi galat) dan diakhiri dengan DONE; balasan yang terpotong oleh anggaran token output mengembalikan status incomplete dengan alasan max output tokens, usage diisi jika penyedia melaporkan jumlahnya, dan galatnya adalah 400, 401, 403 untuk scope yang tidak ada, 405, dan 429 dengan header retry setelah terlalu banyak percobaan autentikasi yang gagal.

API HTTP OpenClaw yang kompatibel dengan OpenAI adalah endpoint saudara yang kontrak modelnya digunakan ulang oleh endpoint ini, dan scope operator OpenClaw menjelaskan set scope yang dipulihkan atau dipersempit oleh keduanya.

Kapan menggunakannya

Model item cocok untuk klien yang sudah menyimpan riwayat percakapannya sendiri dan ingin memutarnya ulang apa adanya, atau yang perlu menyerahkan file dan gambar ke agen tanpa menyimpannya di sesi. Endpoint chat completions cocok untuk alat yang hanya mengenal bentuk lama. Keduanya menjalankan eksekusi agen yang sama di baliknya, jadi pilihannya bergantung pada klien, bukan agen. API OpenClaw membahas API gateway yang lebih luas dan web fetch OpenClaw membahas apa yang dilakukan agen itu sendiri terhadap URL setelah permintaan sampai kepadanya.

Di Diali

Di Diali, gateway berada di belakang ingress platform dengan konfigurasi runtime yang dihasilkan dari dasbor dan diganti pada setiap rilis, sehingga mengaktifkan salah satu permukaan HTTP adalah keputusan konfigurasi, bukan soal membuka port. OpenClaw yang di-hosting di Diali menjelaskan asisten yang di-hosting dan harga Diali menjelaskan paket yang menyertakannya.

• Item masuk, panggilan fungsi keluar, hasil kembali sebagai function_call_output.
• File masuk ke system prompt sebagai konten tidak tepercaya.
• Port yang sama, autentikasi yang sama, kepercayaan setingkat pemilik yang sama seperti chat completions.