Penyelesaian percakapan OpenAI

Gateway dapat menyediakan antarmuka Chat Completions kecil yang kompatibel dengan OpenAI. Fitur ini dinonaktifkan secara default.

Setelah diaktifkan, Gateway menyediakan semua endpoint berikut pada port yang sama dengan Gateway (multipleks WS + HTTP):

Permintaan dijalankan seperti proses agen Gateway biasa (jalur kode yang sama dengan openclaw agent), sehingga perutean, izin, dan konfigurasi sesuai dengan Gateway Anda.

Mengaktifkan endpoint

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

Tetapkan enabled: false (atau hilangkan) untuk menonaktifkannya.

Batas keamanan (penting)

Perlakukan endpoint ini sebagai akses operator penuh ke instans Gateway:

• Token/kata sandi Gateway yang valid untuk endpoint ini setara dengan kredensial pemilik/operator, bukan cakupan sempit per pengguna.
• Permintaan dijalankan melalui jalur agen bidang kontrol yang sama dengan tindakan operator tepercaya. Oleh karena itu, jika kebijakan agen target mengizinkan alat sensitif, endpoint ini dapat menggunakannya.
• Batasi akses hanya melalui local loopback/tailnet/akses masuk privat. Jangan mengeksposnya ke internet publik.

Matriks autentikasi:

Lihat Cakupan operator, Keamanan, dan Akses jarak jauh.

Autentikasi

Menggunakan konfigurasi autentikasi Gateway (lihat Autentikasi proksi tepercaya untuk detail mode tersebut):

Catatan:

• Pemanggil pada host yang sama yang melewati proksi pada Gateway trusted-proxy dapat langsung menggunakan gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD sebagai alternatif. Adanya header Forwarded, X-Forwarded-*, atau X-Real-IP membuat permintaan tetap menggunakan jalur trusted-proxy.
• Jika gateway.auth.rateLimit dikonfigurasi dan terlalu banyak upaya autentikasi gagal, endpoint mengembalikan 429 dengan header Retry-After.

Kapan menggunakan endpoint ini

• Pilih endpoint ini daripada menambahkan kanal bawaan baru jika integrasi Anda hanya merupakan antarmuka operator/klien lain untuk Gateway yang sama.
• Untuk klien seluler native yang terhubung langsung ke Gateway jarak jauh, pilih WebChat atau Protokol Gateway dengan alur bootstrap perangkat yang dipasangkan/token perangkat, agar perangkat tidak memerlukan token/kata sandi HTTP bersama.
• Sebagai gantinya, buat Plugin kanal saat mengintegrasikan jaringan perpesanan eksternal yang memiliki pengguna, ruang, pengiriman Webhook, atau transportasi keluar sendiri. Lihat Membangun Plugin.

Kontrak model yang mengutamakan agen

OpenClaw memperlakukan bidang model OpenAI sebagai target agen, bukan ID model penyedia mentah.

Header permintaan opsional:

/v1/models mencantumkan target agen tingkat atas (openclaw, openclaw/default, openclaw/<agentId>), bukan model penyedia backend dan bukan subagen; subagen tetap menjadi topologi eksekusi internal. Jika Anda menghilangkan x-openclaw-model, agen yang dipilih berjalan dengan model normal yang dikonfigurasikan untuknya.

/v1/embeddings menggunakan ID model target agen yang sama. Kirim x-openclaw-model (dari pemanggil dengan rahasia bersama, atau pemanggil dengan identitas yang memiliki operator.admin) untuk memilih model embedding tertentu; jika tidak, permintaan menggunakan konfigurasi embedding normal milik agen yang dipilih.

Perilaku sesi

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

Jika permintaan menyertakan string user OpenAI, Gateway memperoleh kunci sesi stabil darinya sehingga panggilan berulang dapat berbagi sesi agen. Untuk aplikasi khusus, gunakan kembali nilai user yang sama untuk setiap utas percakapan; hindari pengidentifikasi tingkat akun kecuali Anda ingin beberapa percakapan/perangkat berbagi satu sesi OpenClaw. Gunakan x-openclaw-session-key hanya jika Anda memerlukan kontrol perutean eksplisit di beberapa klien/utas, dengan kunci milik aplikasi yang menghindari namespace yang dicadangkan di atas.

Batas permintaan (konfigurasi)

Nilai default dapat disesuaikan di bawah gateway.http.endpoints.chatCompletions:

{  gateway: {    http: {      endpoints: {        chatCompletions: {          enabled: true,          maxBodyBytes: 20000000,          maxImageParts: 8,          maxTotalImageBytes: 20000000,          images: {            allowUrl: false,            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],            allowedMimes: [              "image/jpeg",              "image/png",              "image/gif",              "image/webp",              "image/heic",              "image/heif",            ],            maxBytes: 10485760,            maxRedirects: 3,            timeoutMs: 10000,          },        },      },    },  },}

Nilai default jika dihilangkan:

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

Catatan keamanan: memasukkan nama host ke daftar yang diizinkan tidak melewati pemblokiran IP privat/internal. Untuk Gateway yang terekspos ke internet, terapkan kontrol lalu lintas keluar jaringan selain perlindungan tingkat aplikasi. Lihat Keamanan.

Kontrak alat obrolan

/v1/chat/completions mendukung subset alat fungsi yang kompatibel dengan klien OpenAI Chat umum.

Kolom permintaan yang didukung

Semua kolom pengambilan sampel dan batas token menggunakan kanal parameter aliran agen yang sama dan diteruskan dengan upaya terbaik:

• Batas token: nama kolom pada protokol dipilih oleh transpor penyedia: max_completion_tokens untuk endpoint keluarga OpenAI, max_tokens untuk penyedia yang hanya menerima nama lama (Mistral, Chutes).
• stop dipetakan ke kolom penghentian transpor: stop untuk backend Chat Completions, stop_sequences untuk Anthropic. OpenAI Responses API tidak memiliki parameter penghentian, sehingga stop tidak diterapkan pada model yang didukung Responses.
• Backend Codex Responses berbasis ChatGPT menggunakan pengambilan sampel tetap di sisi server dan menghapus temperature/top_p (bersama dengan max_output_tokens, metadata, prompt_cache_retention, service_tier) sebelum permintaan mencapai backend tersebut.

Varian yang tidak didukung

Mengembalikan 400 invalid_request_error untuk:

• tools yang bukan larik, entri alat yang bukan fungsi, atau tool.function.name yang tidak ada
• varian tool_choice seperti allowed_tools dan custom
• nilai tool_choice.function.name yang tidak cocok dengan alat yang disediakan

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 menghasilkan galat jika respons agen tidak memiliki pemanggilan alat klien terstruktur yang cocok. Ini berlaku untuk daftar HTTP tools yang diberikan pemanggil, bukan untuk setiap alat internal agen OpenClaw.

Bentuk respons alat non-streaming

Ketika agen memanggil alat, respons menggunakan:

• choices[0].finish_reason = "tool_calls"
• Entri choices[0].message.tool_calls[] dengan id, type: "function", function.name, function.arguments (string JSON)
• Komentar asisten sebelum pemanggilan alat, dalam choices[0].message.content (mungkin kosong)

Bentuk respons alat streaming

Ketika stream: true, pemanggilan alat diterima sebagai potongan SSE bertahap: delta awal peran asisten, delta komentar asisten opsional, satu atau beberapa potongan delta.tool_calls yang membawa identitas alat dan fragmen argumen, lalu potongan terakhir dengan finish_reason: "tool_calls" dan data: [DONE].

Jika stream_options.include_usage=true, potongan penggunaan penutup dikirim sebelum [DONE].

Perulangan tindak lanjut alat

Setelah menerima tool_calls, jalankan fungsi yang diminta dan kirim permintaan tindak lanjut yang menyertakan pesan pemanggilan alat asisten sebelumnya ditambah satu atau beberapa pesan role: "tool" dengan tool_call_id yang cocok. Ini melanjutkan perulangan penalaran agen yang sama untuk menghasilkan jawaban akhir.

Streaming (SSE)

Tetapkan stream: true untuk menerima Server-Sent Events:

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

Penyiapan cepat Open WebUI

• URL dasar: http://127.0.0.1:18789/v1
• URL dasar Docker di macOS: http://host.docker.internal:18789/v1
• Kunci API: token bearer Gateway Anda
• Model: openclaw/default

Perilaku yang diharapkan: GET /v1/models mencantumkan openclaw/default, dan Open WebUI menggunakannya sebagai ID model obrolan. Untuk penyedia/model backend tertentu, tetapkan model default normal agen, atau kirim x-openclaw-model (pemanggil dengan rahasia bersama, atau pemanggil beridentitas dengan operator.admin).

Uji cepat:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

Jika perintah tersebut mengembalikan openclaw/default, sebagian besar penyiapan Open WebUI dapat terhubung dengan URL dasar dan token yang sama.

Contoh

Sesi stabil untuk satu percakapan aplikasi:

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "user": "conv:YOUR_CONVERSATION_ID",    "messages": [{"role":"user","content":"Summarize my tasks for today"}]  }'

Gunakan kembali nilai user yang sama pada pemanggilan berikutnya untuk percakapan tersebut agar sesi agen yang sama berlanjut.

Non-streaming:

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "messages": [{"role":"user","content":"hi"}]  }'

Streaming:

curl -N http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/gpt-5.4' \  -d '{    "model": "openclaw/research",    "stream": true,    "messages": [{"role":"user","content":"hi"}]  }'

Cantumkan model:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

Ambil satu model:

curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \  -H 'Authorization: Bearer YOUR_TOKEN'

Buat embedding:

curl -sS http://127.0.0.1:18789/v1/embeddings \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/text-embedding-3-small' \  -d '{    "model": "openclaw/default",    "input": ["alpha", "beta"]  }'

/v1/embeddings mendukung input sebagai string atau larik string.

Terkait

• Referensi konfigurasi
• Cakupan operator
• OpenAI