Penyelesaian chat OpenAI

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

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

​

Autentikasi

• autentikasi rahasia bersama (gateway.auth.mode="token" atau "password"): Authorization: Bearer <token-or-password>
• autentikasi HTTP pembawa identitas tepercaya (gateway.auth.mode="trusted-proxy"): rutekan melalui proxy sadar-identitas yang dikonfigurasi dan biarkan ia menyisipkan header identitas yang diperlukan
• autentikasi terbuka ingress privat (gateway.auth.mode="none"): tidak memerlukan header autentikasi

• 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 yang sama memerlukan gateway.auth.trustedProxy.allowLoopback = true secara eksplisit.
• Jika gateway.auth.rateLimit dikonfigurasi dan terjadi terlalu banyak kegagalan autentikasi, endpoint mengembalikan 429 dengan Retry-After.

​

Batas keamanan (penting)

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

• gateway.auth.mode="token" atau "password" + Authorization: Bearer ...
  • membuktikan kepemilikan rahasia operator gateway bersama
  • mengabaikan x-openclaw-scopes yang lebih sempit
  • memulihkan kumpulan 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 pengirim-pemilik
• mode HTTP pembawa identitas tepercaya (misalnya autentikasi proxy tepercaya, atau gateway.auth.mode="none" pada ingress privat)
  • mengautentikasi sebagian identitas tepercaya luar atau batas deployment
  • menghormati x-openclaw-scopes saat header ada
  • kembali ke kumpulan cakupan default operator normal saat header tidak ada
  • hanya kehilangan semantik pemilik saat pemanggil secara eksplisit mempersempit cakupan dan menghilangkan operator.admin

​

Kontrak model yang mengutamakan agen

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

• x-openclaw-model: <provider/model-or-bare-id> menimpa model backend untuk agen yang dipilih.
• x-openclaw-agent-id: <agentId> tetap didukung sebagai penimpaan kompatibilitas.
• x-openclaw-session-key: <sessionKey> sepenuhnya mengontrol routing sesi.
• x-openclaw-message-channel: <channel> menetapkan konteks kanal ingress sintetis untuk prompt dan kebijakan yang sadar kanal.

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

​

Mengaktifkan endpoint

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

​

Menonaktifkan endpoint

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

​

Perilaku sesi

​

Mengapa permukaan ini penting

• 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 makin sering memilih /v1/responses.

​

Daftar model dan routing agen

​

Streaming (SSE)

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

​

Kontrak alat chat

​

Kolom permintaan yang didukung

• tools: array dari { "type": "function", "function": { ... } }
• tool_choice: "auto", "none"
• giliran lanjutan messages[*].role: "tool"
• messages[*].tool_call_id untuk mengikat hasil alat kembali ke panggilan alat sebelumnya
• max_completion_tokens: angka; batas per panggilan untuk total token completion (termasuk token reasoning). Nama kolom OpenAI Chat Completions saat ini; diprioritaskan saat max_completion_tokens dan max_tokens sama-sama dikirim.
• max_tokens: angka; alias lama yang diterima untuk kompatibilitas ke belakang. Diabaikan saat max_completion_tokens juga ada.

​

Varian yang tidak didukung

• tools non-array
• entri alat non-fungsi
• tool.function.name yang hilang
• varian tool_choice seperti allowed_tools dan custom
• tool_choice: "required" (belum ditegakkan saat runtime; akan didukung setelah penegakan keras diimplementasikan)
• tool_choice: { "type": "function", "function": { "name": "..." } } (alasan yang sama seperti required)
• nilai tool_choice.function.name yang tidak cocok dengan tools yang disediakan

​

Bentuk respons alat non-streaming

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

​

Bentuk respons alat streaming

• delta peran asisten awal
• delta komentar asisten opsional
• satu atau beberapa potongan delta.tool_calls yang membawa identitas alat dan fragmen argumen
• potongan akhir dengan finish_reason: "tool_calls"
• data: [DONE]

​

Loop tindak lanjut alat

• pesan panggilan alat asisten sebelumnya
• satu atau beberapa pesan role: "tool" dengan tool_call_id yang cocok

​

Setup cepat Open WebUI

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

• GET /v1/models harus mencantumkan openclaw/default
• Open WebUI harus menggunakan openclaw/default sebagai id model chat
• Jika Anda menginginkan provider/model backend tertentu untuk agen tersebut, atur model default normal agen atau kirim x-openclaw-model

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

​

Contoh

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

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

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

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

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/models mengembalikan target agen OpenClaw, bukan katalog penyedia mentah.
• openclaw/default selalu tersedia sehingga satu id stabil dapat digunakan di berbagai lingkungan.
• Override penyedia/model backend harus berada di x-openclaw-model, bukan di kolom model OpenAI.
• /v1/embeddings mendukung input sebagai string atau array string.

​

Terkait

• Referensi konfigurasi
• OpenAI