Penyelesaian chat OpenAI

Gateway OpenClaw dapat menyajikan endpoint Chat Completions kecil yang kompatibel dengan OpenAI.

Endpoint ini dinonaktifkan secara default. Aktifkan terlebih dahulu di konfigurasi.

• POST /v1/chat/completions
• Port yang sama dengan Gateway (multiplex WS + HTTP): http://<gateway-host>:<port>/v1/chat/completions

Saat permukaan HTTP Gateway yang kompatibel dengan OpenAI diaktifkan, Gateway juga menyajikan:

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/responses

Di balik layar, permintaan dieksekusi sebagai proses agent Gateway normal (codepath yang sama dengan openclaw agent), sehingga routing/izin/konfigurasi cocok dengan Gateway Anda.

Autentikasi

Menggunakan konfigurasi auth Gateway.

Jalur auth HTTP yang umum:

• auth shared-secret (gateway.auth.mode="token" atau "password"): Authorization: Bearer <token-or-password>
• auth HTTP tepercaya yang membawa identitas (gateway.auth.mode="trusted-proxy"): rutekan melalui proxy sadar-identitas yang dikonfigurasi dan biarkan proxy itu menyuntikkan header identitas yang diperlukan
• auth terbuka private-ingress (gateway.auth.mode="none"): tidak memerlukan header auth

Catatan:

• Saat gateway.auth.mode="token", gunakan gateway.auth.token (atau OPENCLAW_GATEWAY_TOKEN).
• Saat gateway.auth.mode="password", gunakan gateway.auth.password (atau OPENCLAW_GATEWAY_PASSWORD).
• Saat gateway.auth.mode="trusted-proxy", permintaan HTTP harus berasal dari sumber proxy tepercaya yang dikonfigurasi; proxy loopback host-sama memerlukan gateway.auth.trustedProxy.allowLoopback = true secara eksplisit.
• Pemanggil internal host-sama yang melewati proxy dapat menggunakan gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD sebagai fallback langsung lokal. Bukti header Forwarded, X-Forwarded-*, atau X-Real-IP apa pun membuat permintaan tetap berada di jalur trusted-proxy.
• Jika gateway.auth.rateLimit dikonfigurasi dan terjadi terlalu banyak kegagalan auth, endpoint mengembalikan 429 dengan Retry-After.

Batas keamanan (penting)

Perlakukan endpoint ini sebagai permukaan akses operator penuh untuk instance gateway.

• Auth bearer HTTP di sini bukan model cakupan sempit per pengguna.
• Token/kata sandi Gateway yang valid untuk endpoint ini harus diperlakukan seperti kredensial pemilik/operator.
• Permintaan berjalan melalui jalur agent control-plane yang sama seperti tindakan operator tepercaya.
• Tidak ada batas tool non-pemilik/per pengguna yang terpisah pada endpoint ini; begitu pemanggil lolos auth Gateway di sini, OpenClaw memperlakukan pemanggil itu sebagai operator tepercaya untuk gateway ini.
• Untuk mode auth shared-secret (token dan password), endpoint memulihkan default operator penuh normal meskipun pemanggil mengirim header x-openclaw-scopes yang lebih sempit.
• Mode HTTP tepercaya yang membawa identitas (misalnya auth trusted proxy atau gateway.auth.mode="none") menghormati x-openclaw-scopes saat ada dan jika tidak, fallback ke set cakupan default operator normal.
• Jika kebijakan agent target mengizinkan tool sensitif, endpoint ini dapat menggunakannya.
• Pertahankan endpoint ini hanya di loopback/tailnet/private ingress; jangan paparkan langsung ke internet publik.

Matriks auth:

• gateway.auth.mode="token" atau "password" + Authorization: Bearer ...
  • membuktikan kepemilikan shared gateway operator secret
  • mengabaikan x-openclaw-scopes yang lebih sempit
  • memulihkan set cakupan operator default penuh: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • memperlakukan giliran chat pada endpoint ini sebagai giliran owner-sender
• mode HTTP tepercaya yang membawa identitas (misalnya auth trusted proxy, atau gateway.auth.mode="none" pada private ingress)
  • mengautentikasi identitas tepercaya luar atau batas deployment tertentu
  • menghormati x-openclaw-scopes saat header ada
  • fallback ke set cakupan default operator normal saat header tidak ada
  • hanya kehilangan semantik pemilik saat pemanggil secara eksplisit mempersempit cakupan dan menghilangkan operator.admin
  • memerlukan operator.admin untuk kontrol permintaan tingkat pemilik seperti x-openclaw-model

Lihat Keamanan dan Akses jarak jauh.

Kapan menggunakan endpoint ini

Gunakan /v1/chat/completions saat Anda mengintegrasikan tooling atau backend sisi aplikasi tepercaya dengan gateway yang sudah ada dan dapat menyimpan kredensial operator gateway dengan aman.

• Lebih pilih ini daripada menambahkan channel bawaan baru saat integrasi Anda hanyalah permukaan operator/klien lain untuk gateway yang sama.
• Untuk klien mobile native yang terhubung langsung ke gateway jarak jauh, lebih pilih WebChat atau Protokol Gateway dan implementasikan alur bootstrap perangkat-terpasang/token-perangkat agar perangkat tidak memerlukan token/kata sandi HTTP bersama.
• Bangun Plugin channel sebagai gantinya saat Anda mengintegrasikan jaringan pesan eksternal dengan pengguna, room, pengiriman Webhook, atau transport keluar miliknya sendiri. Lihat Membangun plugin.

Kontrak model agent-first

OpenClaw memperlakukan field OpenAI model sebagai target agent, bukan id model provider mentah.

• model: "openclaw" merutekan ke agent default yang dikonfigurasi.
• model: "openclaw/default" juga merutekan ke agent default yang dikonfigurasi.
• model: "openclaw/<agentId>" merutekan ke agent tertentu.

Header permintaan opsional:

• x-openclaw-model: <provider/model-or-bare-id> mengganti model backend untuk agent yang dipilih. Pemanggil bearer shared-secret dapat menggunakan header ini. Pemanggil yang membawa identitas, seperti trusted-proxy atau permintaan private no-auth ingress dengan x-openclaw-scopes, memerlukan operator.admin; pemanggil write-only mendapatkan 403 missing scope: operator.admin.
• x-openclaw-agent-id: <agentId> tetap didukung sebagai override kompatibilitas.
• x-openclaw-session-key: <sessionKey> secara eksplisit mengontrol routing sesi. Nilai tidak boleh menggunakan namespace sesi internal yang dicadangkan seperti subagent:, cron:, atau acp:; permintaan tersebut ditolak dengan 400 invalid_request_error.
• x-openclaw-message-channel: <channel> menetapkan konteks channel ingress sintetis untuk prompt dan kebijakan yang sadar-channel.

Alias kompatibilitas yang masih diterima:

• model: "openclaw:<agentId>"
• model: "agent:<agentId>"

Mengaktifkan endpoint

Setel gateway.http.endpoints.chatCompletions.enabled ke true:

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

Menonaktifkan endpoint

Setel gateway.http.endpoints.chatCompletions.enabled ke false:

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

Perilaku sesi

Secara default endpoint ini stateless per permintaan (kunci sesi baru dibuat pada setiap panggilan).

Jika permintaan menyertakan string OpenAI user, Gateway menurunkan kunci sesi stabil darinya, sehingga panggilan berulang dapat berbagi sesi agent.

Untuk aplikasi kustom, default paling aman adalah menggunakan ulang nilai user yang sama per thread percakapan. Hindari pengidentifikasi tingkat akun kecuali Anda secara eksplisit ingin beberapa percakapan atau perangkat berbagi satu sesi OpenClaw. Gunakan x-openclaw-session-key hanya saat Anda memerlukan kontrol routing eksplisit di beberapa klien atau thread, dan pilih kunci milik aplikasi yang tidak diawali dengan namespace internal yang dicadangkan seperti subagent:, cron:, atau acp:.

Mengapa permukaan ini penting

Ini adalah set kompatibilitas dengan leverage tertinggi untuk frontend self-hosted dan tooling:

• Sebagian besar setup Open WebUI, LobeChat, dan LibreChat mengharapkan /v1/models.
• Banyak sistem RAG mengharapkan /v1/embeddings.
• Klien chat OpenAI yang sudah ada biasanya dapat memulai dengan /v1/chat/completions.
• Klien yang lebih agent-native semakin memilih /v1/responses.

Daftar model dan routing agent

Streaming (SSE)

Setel stream: true untuk menerima Server-Sent Events (SSE):

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

Kontrak tool chat

/v1/chat/completions mendukung subset function-tool yang kompatibel dengan klien Chat OpenAI umum.

Field permintaan yang didukung

• tools: array dari { "type": "function", "function": { ... } }
• tool_choice: "auto", "none", "required", atau { "type": "function", "function": { "name": "..." } }
• giliran tindak lanjut messages[*].role: "tool"
• messages[*].tool_call_id untuk mengikat hasil tool kembali ke panggilan tool sebelumnya
• max_completion_tokens: angka; batas per panggilan untuk total token penyelesaian (termasuk token reasoning). Nama field OpenAI Chat Completions saat ini; lebih disukai saat max_completion_tokens dan max_tokens dikirim bersamaan.
• max_tokens: angka; alias legacy diterima untuk kompatibilitas mundur. Diabaikan saat max_completion_tokens juga ada.
• temperature: angka; suhu sampling best-effort diteruskan ke provider upstream melalui channel stream-param agent.
• top_p: angka; sampling nucleus best-effort diteruskan ke provider upstream melalui channel stream-param agent.
• frequency_penalty: angka; penalti frekuensi best-effort diteruskan ke provider upstream melalui channel stream-param agent. Rentang tervalidasi: -2.0 hingga 2.0. Mengembalikan 400 invalid_request_error untuk nilai di luar rentang.
• presence_penalty: angka; penalti presence best-effort diteruskan ke provider upstream melalui channel stream-param agent. Rentang tervalidasi: -2.0 hingga 2.0. Mengembalikan 400 invalid_request_error untuk nilai di luar rentang.
• seed: angka (integer); seed best-effort diteruskan ke provider upstream melalui channel stream-param agent. Mengembalikan 400 invalid_request_error untuk nilai non-integer.
• stop: string atau array hingga 4 string; rangkaian stop best-effort diteruskan ke provider upstream melalui channel stream-param agent. Mengembalikan 400 invalid_request_error untuk lebih dari 4 rangkaian atau entri non-string/kosong.

Ketika salah satu field batas token diatur, nilainya diteruskan ke penyedia upstream melalui kanal stream-param agent. Nama field wire aktual yang dikirim ke penyedia upstream dipilih oleh transport penyedia: max_completion_tokens untuk endpoint keluarga OpenAI, dan max_tokens untuk penyedia yang hanya menerima nama legacy (seperti Mistral dan Chutes). Field sampling (temperature, top_p, frequency_penalty, presence_penalty, seed) mengikuti kanal stream-param yang sama; backend Codex Responses berbasis ChatGPT menghapusnya di sisi server karena menggunakan sampling tetap. stop juga melewati kanal stream-param dan dipetakan ke field stop milik transport (stop untuk backend Chat Completions, stop_sequences untuk Anthropic); OpenAI Responses API tidak memiliki parameter stop, sehingga stop tidak diterapkan pada model berbasis Responses.

Varian yang tidak didukung

Endpoint mengembalikan 400 invalid_request_error untuk varian tool yang tidak didukung, termasuk:

• tools yang bukan array
• entri tool yang bukan function
• tool.function.name yang hilang
• varian tool_choice seperti allowed_tools dan custom
• nilai tool_choice.function.name yang tidak cocok dengan tools yang diberikan

Untuk tool_choice: "required" dan tool_choice yang dipasangkan ke function, endpoint mempersempit set function-tool klien yang diekspos, menginstruksikan runtime untuk memanggil tool klien sebelum merespons, dan mengembalikan error jika respons agent tidak menyertakan panggilan client-tool terstruktur yang cocok. Kontrak ini berlaku untuk daftar HTTP tools yang diberikan pemanggil, bukan setiap tool agent internal OpenClaw.

Bentuk respons tool non-streaming

Ketika agent memutuskan untuk memanggil tool, respons menggunakan:

• entri choices[0].finish_reason = "tool_calls"
• choices[0].message.tool_calls[] dengan:
  • id
  • type: "function"
  • function.name
  • function.arguments (string JSON)

Komentar assistant sebelum panggilan tool dikembalikan di choices[0].message.content (mungkin kosong).

Bentuk respons tool streaming

Ketika stream: true, panggilan tool dipancarkan sebagai chunk SSE inkremental:

• delta role assistant awal
• delta komentar assistant opsional
• satu atau lebih chunk delta.tool_calls yang membawa identitas tool dan fragmen argumen
• chunk akhir dengan finish_reason: "tool_calls"
• data: [DONE]

Jika stream_options.include_usage=true, chunk penggunaan penutup dipancarkan sebelum [DONE].

Loop tindak lanjut tool

Setelah menerima tool_calls, klien harus menjalankan function yang diminta dan mengirim permintaan tindak lanjut yang menyertakan:

• pesan tool-call assistant sebelumnya
• satu atau lebih pesan role: "tool" dengan tool_call_id yang cocok

Ini memungkinkan eksekusi agent gateway melanjutkan loop penalaran yang sama dan menghasilkan jawaban assistant final.

Penyiapan cepat Open WebUI

Untuk koneksi Open WebUI dasar:

• 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 harus mencantumkan openclaw/default
• Open WebUI harus menggunakan openclaw/default sebagai id model chat
• Jika Anda menginginkan penyedia/model backend tertentu untuk agent tersebut, atur model default normal milik agent atau kirim x-openclaw-model dari pemanggil shared-secret atau pemanggil dengan identitas yang memiliki operator.admin

Smoke cepat:

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

Jika itu mengembalikan openclaw/default, sebagian besar penyiapan Open WebUI dapat tersambung 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 panggilan berikutnya untuk percakapan itu agar melanjutkan sesi agent yang sama.

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

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

Catatan:

• /v1/models mengembalikan target agent OpenClaw, bukan katalog penyedia mentah.
• openclaw/default selalu ada sehingga satu id stabil berfungsi di berbagai lingkungan.
• Override penyedia/model backend berada di x-openclaw-model, bukan field OpenAI model. Pada jalur autentikasi HTTP dengan identitas, header ini memerlukan operator.admin.
• /v1/embeddings mendukung input sebagai string atau array string.

Terkait

• Referensi konfigurasi
• OpenAI