OpenAI sohbet tamamlamaları

Gateway, OpenAI uyumlu küçük bir Chat Completions yüzeyi sunabilir. Bu özellik varsayılan olarak devre dışıdır.

Etkinleştirildiğinde, bunların tümünü Gateway ile aynı bağlantı noktasında sunar (WS + HTTP çoklama):

İstekler normal bir Gateway ajan çalıştırması olarak (openclaw agent ile aynı kod yolu üzerinden) yürütülür; dolayısıyla yönlendirme, izinler ve yapılandırma Gateway'inizle eşleşir.

Uç noktayı etkinleştirme

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

Devre dışı bırakmak için enabled: false olarak ayarlayın (veya bu ayarı atlayın).

Güvenlik sınırı (önemli)

Bu uç noktayı Gateway örneğine tam operatör erişimi sağlıyor olarak değerlendirin:

• Bu uç nokta için geçerli bir Gateway belirteci/parolası, kullanıcı başına dar kapsamlı bir kimlik bilgisine değil, sahip/operatör kimlik bilgisine eşdeğerdir.
• İstekler, güvenilir operatör eylemleriyle aynı denetim düzlemi ajan yolundan geçer; dolayısıyla hedef ajanın ilkesi hassas araçlara izin veriyorsa bu uç nokta bunları kullanabilir.
• Yalnızca local loopback/tailnet/özel giriş üzerinde tutun. Genel internete açmayın.

Kimlik doğrulama matrisi:

Bkz. Operatör kapsamları, Güvenlik ve Uzaktan erişim.

Kimlik doğrulama

Gateway kimlik doğrulama yapılandırmasını kullanır (bu modun ayrıntıları için bkz. Güvenilir proxy kimlik doğrulaması):

Notlar:

• trusted-proxy Gateway'inde proxy'yi atlayan aynı makinedeki çağıranlar, doğrudan gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD kullanımına geri dönebilir. Herhangi bir Forwarded, X-Forwarded-* veya X-Real-IP üstbilgisi kanıtı, isteği bunun yerine trusted-proxy yolunda tutar.
• gateway.auth.rateLimit yapılandırılmışsa ve çok fazla kimlik doğrulama girişimi başarısız olursa uç nokta, Retry-After üstbilgisiyle birlikte 429 döndürür.

Bu uç nokta ne zaman kullanılmalı?

• Entegrasyonunuz aynı Gateway için yalnızca başka bir operatör/istemci yüzeyiyse yeni bir yerleşik kanal eklemek yerine bunu tercih edin.
• Uzak bir Gateway'e doğrudan bağlanan yerel mobil istemcilerde, cihazın paylaşılan bir HTTP belirtecine/parolasına ihtiyaç duymaması için eşleştirilmiş cihaz önyükleme/cihaz belirteci akışıyla WebChat veya Gateway Protokolü kullanmayı tercih edin.
• Kendi kullanıcıları, odaları, Webhook teslimatı veya giden aktarımı olan harici bir mesajlaşma ağıyla entegrasyon yaparken bunun yerine bir kanal Plugin'i oluşturun. Bkz. Plugin oluşturma.

Ajan öncelikli model sözleşmesi

OpenClaw, OpenAI model alanını ham sağlayıcı model kimliği olarak değil, bir ajan hedefi olarak değerlendirir.

İsteğe bağlı istek üstbilgileri:

/v1/models, arka uç sağlayıcı modellerini veya alt ajanları değil, üst düzey ajan hedeflerini (openclaw, openclaw/default, openclaw/<agentId>) listeler; alt ajanlar iç yürütme topolojisinde kalır. x-openclaw-model değerini atlarsanız seçilen ajan normal yapılandırılmış modeliyle çalışır.

/v1/embeddings aynı ajan hedefi model kimliklerini kullanır. Belirli bir gömme modeli seçmek için x-openclaw-model gönderin (paylaşılan gizli bilgi kullanan bir çağırandan veya operator.admin kapsamına sahip kimlik taşıyan bir çağırandan); aksi hâlde istek, seçilen ajanın normal gömme yapılandırmasını kullanır.

Oturum davranışı

Uç nokta varsayılan olarak her istek için durum bilgisizdir (her çağrıda yeni bir oturum anahtarı oluşturulur).

İstek bir OpenAI user dizesi içeriyorsa Gateway, yinelenen çağrıların bir ajan oturumunu paylaşabilmesi için bu değerden kararlı bir oturum anahtarı türetir. Özel uygulamalarda her konuşma dizisi için aynı user değerini yeniden kullanın; birden fazla konuşmanın/cihazın tek bir OpenClaw oturumunu paylaşmasını istemiyorsanız hesap düzeyindeki tanımlayıcılardan kaçının. x-openclaw-session-key değerini yalnızca birden fazla istemci/dizi arasında açık yönlendirme denetimine ihtiyaç duyduğunuzda, yukarıdaki ayrılmış ad alanlarından kaçınan uygulamaya ait anahtarlarla kullanın.

İstek sınırları (yapılandırma)

Varsayılan değerler gateway.http.endpoints.chatCompletions altında ayarlanabilir:

{  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,          },        },      },    },  },}

Atlandığında kullanılan varsayılanlar:

HEIC/HEIF image_url kaynakları kabul edilir ve sağlayıcıya teslim edilmeden önce paylaşılan OpenClaw görüntü işlemcisi (Rastermill) aracılığıyla JPEG'e dönüştürülür; harici codec desteği gerektiren biçimler için işlemci, sistem dönüştürücüsüne (sips, ImageMagick, GraphicsMagick veya ffmpeg) geri döner.

Güvenlik notu: Bir ana bilgisayar adını izin verilenler listesine eklemek, özel/dahili IP engellemesini atlamaz. İnternete açık Gateway'ler için uygulama düzeyindeki korumalara ek olarak ağ çıkış denetimleri uygulayın. Bkz. Güvenlik.

Sohbet aracı sözleşmesi

/v1/chat/completions, yaygın OpenAI Chat istemcileriyle uyumlu bir işlev aracı alt kümesini destekler.

Desteklenen istek alanları

Tüm örnekleme ve belirteç üst sınırı alanları aynı ajan akış parametresi kanalı üzerinden taşınır ve mümkün olan en iyi şekilde iletilir:

• Belirteç üst sınırı: İletişim alanının adı sağlayıcı aktarımı tarafından seçilir: OpenAI ailesi uç noktaları için max_completion_tokens, yalnızca eski adı kabul eden sağlayıcılar (Mistral, Chutes) için max_tokens.
• stop, aktarımın durdurma alanına eşlenir: Chat Completions arka uçları için stop, Anthropic için stop_sequences. OpenAI Responses API'de durdurma parametresi bulunmadığından stop, Responses tabanlı modellerde uygulanmaz.
• ChatGPT tabanlı Codex Responses arka ucu, sabit sunucu tarafı örnekleme kullanır ve istek bu arka uca ulaşmadan önce temperature/top_p alanlarını (max_output_tokens, metadata, prompt_cache_retention, service_tier ile birlikte) kaldırır.

Desteklenmeyen değişkenler

Şu durumlarda 400 invalid_request_error döndürür:

• dizi olmayan tools, işlev olmayan araç girdileri veya eksik tool.function.name
• allowed_tools ve custom gibi tool_choice değişkenleri
• sağlanan bir araçla eşleşmeyen tool_choice.function.name değerleri

tool_choice: "required" ve işleve sabitlenmiş tool_choice için uç nokta, kullanıma sunulan istemci işlev aracı kümesini daraltır, çalışma zamanına yanıt vermeden önce bir istemci aracını çağırma talimatı verir ve ajan yanıtında eşleşen yapılandırılmış bir istemci aracı çağrısı yoksa hata verir. Bu, tüm dahili OpenClaw ajan araçlarına değil, çağıran tarafından sağlanan HTTP tools listesine uygulanır.

Akışsız araç yanıtı biçimi

Ajan araçları çağırdığında yanıt şunları kullanır:

• choices[0].finish_reason = "tool_calls"
• id, type: "function", function.name, function.arguments (JSON dizesi) içeren choices[0].message.tool_calls[] girdileri
• Araç çağrısından önceki yardımcı açıklaması, choices[0].message.content içinde (boş olabilir)

Akışlı araç yanıtı biçimi

stream: true olduğunda araç çağrıları artımlı SSE parçaları olarak gelir: başlangıçta yardımcı rol deltası, isteğe bağlı yardımcı açıklaması deltaları, araç kimliği ve bağımsız değişken parçalarını taşıyan bir veya daha fazla delta.tool_calls parçası, ardından finish_reason: "tool_calls" içeren son parça ve data: [DONE].

stream_options.include_usage=true ise [DONE] öncesinde sondaki bir kullanım parçası yayınlanır.

Araç takip döngüsü

tool_calls alındıktan sonra istenen işlevleri yürütün ve önceki yardımcı araç çağrısı iletisiyle birlikte eşleşen tool_call_id değerlerine sahip bir veya daha fazla role: "tool" iletisi içeren bir takip isteği gönderin. Bu işlem, nihai yanıtı üretmek için aynı ajan akıl yürütme döngüsünü sürdürür.

Akış (SSE)

Sunucu Tarafından Gönderilen Olayları almak için stream: true ayarlayın:

• Content-Type: text/event-stream
• Her olay satırı data: <json> biçimindedir
• Akış data: [DONE] ile sona erer

Open WebUI hızlı kurulumu

• Temel URL: http://127.0.0.1:18789/v1
• macOS'ta Docker temel URL'si: http://host.docker.internal:18789/v1
• API anahtarı: Gateway taşıyıcı belirteciniz
• Model: openclaw/default

Beklenen davranış: GET /v1/models, openclaw/default değerini listeler ve Open WebUI bunu sohbet modeli kimliği olarak kullanır. Belirli bir arka uç sağlayıcısı/modeli için ajanın normal varsayılan modelini ayarlayın veya x-openclaw-model gönderin (paylaşılan gizli anahtar kullanan çağıran ya da operator.admin yetkisine sahip kimlik taşıyan çağıran).

Hızlı duman testi:

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

Bu komut openclaw/default döndürürse çoğu Open WebUI kurulumu aynı temel URL ve belirteçle bağlanabilir.

Örnekler

Tek bir uygulama konuşması için kararlı oturum:

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

Aynı ajan oturumunu sürdürmek için bu konuşmaya yönelik sonraki çağrılarda aynı user değerini yeniden kullanın.

Akışsız:

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

Akışlı:

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

Modelleri listeleme:

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

Tek bir modeli getirme:

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

Gömme vektörleri oluşturma:

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, input için dizeyi veya dize dizisini destekler.

İlgili

• Yapılandırma başvurusu
• Operatör kapsamları
• OpenAI