API HTTP OpenClaw yang kompatibel dengan OpenAI

Apa pun yang berbicara dengan protokol OpenAI Chat Completions dapat berkomunikasi dengan agen OpenClaw, karena gateway melayani permukaan kompatibel yang kecil di port yang sama dengan WebSocket-nya. Permukaan ini nonaktif secara default, memberikan akses operator penuh saat aktif, dan kolom model-nya berarti sesuatu yang berbeda dari yang dikira klien Anda. Berikut kontraknya sebagaimana dijelaskan dokumentasi.

Apa yang dilayaninya dan siapa yang dipercayainya

• Setelah gateway.http.endpoints.chatCompletions diaktifkan, gateway melayani POST /v1/chat/completions, GET /v1/models, GET pada satu id model, dan POST /v1/embeddings di port gateway; endpoint responses diaktifkan secara terpisah, dan setiap permintaan berjalan sebagai eksekusi agen gateway biasa di jalur kode yang sama dengan perintah agent, jadi routing, izin, dan konfigurasi sesuai dengan gateway Anda.
• Token atau kata sandi gateway yang valid untuk endpoint ini setara dengan kredensial pemilik atau operator, bukan scope per pengguna: autentikasi bearer shared-secret mengabaikan header x-openclaw-scopes apa pun, memulihkan set scope operator default secara penuh, dan memperlakukan giliran chat sebagai giliran dari pengirim pemilik; ingress trusted-proxy atau ingress privat tanpa autentikasi menghormati x-openclaw-scopes jika ada dan memerlukan operator.admin untuk kontrol tingkat pemilik.
• Autentikasi mengikuti mode gateway: token bearer atau kata sandi dari konfigurasi atau variabel lingkungan, proxy yang sadar identitas dalam mode trusted-proxy (proxy loopback di host yang sama memerlukan allowLoopback), atau tanpa header di ingress privat; pemanggil di host yang sama yang melewati trusted proxy dapat jatuh kembali ke kata sandi kecuali bukti forwarded-header mempertahankan mereka di jalur proxy, dan terlalu banyak percobaan gagal mengembalikan 429 dengan Retry-After jika batas laju dikonfigurasi.
• Dokumentasi lebih menyarankan endpoint ini daripada saluran bawaan baru jika integrasinya hanyalah permukaan operator lain, lebih menyarankan WebChat atau protokol gateway dengan alur perangkat yang disandingkan untuk klien seluler native agar tidak ada token bersama yang ikut terpasang di perangkat, dan menyarankan plugin saluran saat mengintegrasikan jaringan pesan eksternal dengan pengguna, ruangan, dan transport-nya sendiri.

OpenClaw memperlakukan kolom model OpenAI sebagai target agen, bukan id model penyedia mentah.

Model adalah agen, sesi berasal dari user

openclaw dan openclaw/default dirutekan ke agen default yang dikonfigurasi, openclaw/ diikuti id agen atau agent: diikuti id tersebut dirutekan ke agen tertentu, dan /v1/models mencantumkan target agen tersebut, bukan model penyedia dan bukan sub-agen. Header x-openclaw-model mengganti model backend untuk agen yang dipilih, langsung bagi pemanggil shared-secret dan hanya dengan operator.admin bagi pemanggil yang membawa identitas; x-openclaw-session-key merutekan secara eksplisit dan ditolak dengan 400 jika menggunakan namespace yang dicadangkan seperti subagent, cron, atau acp; x-openclaw-message-channel menetapkan saluran ingress sintetis untuk prompt yang sadar saluran. Secara default, setiap permintaan bersifat stateless dengan kunci sesi baru; string user OpenAI menurunkan kunci yang stabil sehingga panggilan berulang berbagi satu sesi, jadi gunakan ulang satu nilai per utas percakapan dan hindari pengenal tingkat akun kecuali beberapa perangkat memang harus berbagi satu sesi. Melanjutkan sesi incognito secara eksplisit memerlukan operator.admin yang efektif, dan respons yang didukung profil menyembunyikan target di balik error forbidden berbentuk not-found.

Alat, batasan, dan streaming

• Function tools dan tool_choice (auto, none, required, atau fungsi yang dipatok) didukung, dengan pesan lanjutan berperan tool yang diikat oleh tool_call_id; max_completion_tokens adalah batas yang berlaku saat ini dengan max_tokens sebagai alias lama, dan temperature, top_p, parameter penalti, seed, serta hingga empat stop sequence divalidasi lalu diteruskan secara best-effort, dengan nama wire yang dipilih oleh transport penyedia.
• Permintaan dibatasi hingga body 20 MB, 8 bagian image_url dari pesan pengguna terbaru, dan 20 MB data gambar yang sudah didekode; gambar bersumber URL ditolak kecuali images.allowUrl aktif, dengan daftar izin host, tipe MIME yang diizinkan, 10 MB per gambar, 3 pengalihan, dan batas waktu 10 s secara default, HEIC dan HEIF dinormalisasi ke JPEG, dan hostname yang masuk daftar izin tidak pernah melewati pemblokiran IP privat.
• Dengan stream bernilai true, peristiwa datang sebagai baris data yang diakhiri DONE, panggilan alat sebagai potongan delta inkremental lalu finish reason tool_calls, dan potongan usage jika include_usage disetel; eksekusi yang gagal mengembalikan error, bukan completion, kegagalan streaming memancarkan objek error lalu DONE, dan klien yang terputus membatalkan unduhan sumber dan eksekusi agen.

API OpenClaw adalah artikel tentang API gateway secara lebih luas dan scope operator OpenClaw menjelaskan set scope operator yang dipulihkan atau dipersempit oleh endpoint ini.

Resep Open WebUI

Penyiapan cepatnya adalah base URL berupa host dan port gateway dengan /v1, host.docker.internal dari Docker di macOS, token bearer gateway sebagai kunci API, dan openclaw/default sebagai model; jika curl ke /v1/models dengan bearer tersebut mengembalikan openclaw/default, sebagian besar penyiapan Open WebUI dapat terhubung dengan base URL dan token yang sama. Contoh-contohnya kemudian menunjukkan sesi stabil dengan nilai user berawalan conv, panggilan streaming dengan x-openclaw-model yang mematok model penyedia, pengambilan satu model dengan garis miring yang di-encode URL, dan embeddings dengan model embedding di header serta bilangan bulat dimensions opsional yang mengganti dimensionalitas output memori agen. Akses jarak jauh OpenClaw membahas cara menjangkau port tersebut dengan aman dan kontrol keamanan gateway OpenClaw membahas kontrol yang menjaganya.

Di Diali

Di Diali, gateway berada di balik ingress platform dengan konfigurasi runtime yang dibuat dari dasbor, jadi mengekspos permukaan ini adalah keputusan konfigurasi, bukan port yang harus dibuka. OpenClaw yang di-hosting di Diali menjelaskan asisten yang di-hosting dan harga Diali menjelaskan paket yang menyertakannya.

• Nonaktif secara default; saat aktif, token berarti akses pemilik.
• Kolom model menyebut agen; user menyebut sesi.
• Loopback, tailnet, atau ingress privat, jangan pernah internet publik.