OpenAI sohbet tamamlamaları

OpenClaw'ın Gateway'i, küçük bir OpenAI uyumlu Chat Completions uç noktası sunabilir.

Bu uç nokta varsayılan olarak devre dışıdır. Önce yapılandırmada etkinleştirin.

• POST /v1/chat/completions
• Gateway ile aynı bağlantı noktası (WS + HTTP çoklama): http://<gateway-host>:<port>/v1/chat/completions

Gateway'in OpenAI uyumlu HTTP yüzeyi etkinleştirildiğinde, şunları da sunar:

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

Arka planda istekler normal bir Gateway ajan çalıştırması olarak yürütülür (openclaw agent ile aynı kod yolu), bu nedenle yönlendirme/izinler/yapılandırma Gateway'inizle eşleşir.

Kimlik Doğrulama

Gateway kimlik doğrulama yapılandırmasını kullanır.

Yaygın HTTP kimlik doğrulama yolları:

• paylaşılan gizli anahtar kimlik doğrulaması (gateway.auth.mode="token" veya "password"): Authorization: Bearer <token-or-password>
• güvenilir kimlik taşıyan HTTP kimlik doğrulaması (gateway.auth.mode="trusted-proxy"): yapılandırılmış kimlik farkında proxy üzerinden yönlendirin ve gerekli kimlik başlıklarını enjekte etmesine izin verin
• özel giriş açık kimlik doğrulaması (gateway.auth.mode="none"): kimlik doğrulama başlığı gerekmez

Notlar:

• gateway.auth.mode="token" olduğunda, gateway.auth.token (veya OPENCLAW_GATEWAY_TOKEN) kullanın.
• gateway.auth.mode="password" olduğunda, gateway.auth.password (veya OPENCLAW_GATEWAY_PASSWORD) kullanın.
• gateway.auth.mode="trusted-proxy" olduğunda, HTTP isteği yapılandırılmış bir güvenilir proxy kaynağından gelmelidir; aynı ana makinedeki loopback proxy'leri açıkça gateway.auth.trustedProxy.allowLoopback = true gerektirir.
• Proxy'yi atlayan dahili aynı ana makine çağırıcıları, yerel doğrudan yedek yol olarak gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD kullanabilir. Bunun yerine herhangi bir Forwarded, X-Forwarded-* veya X-Real-IP başlık kanıtı isteği güvenilir proxy yolunda tutar.
• gateway.auth.rateLimit yapılandırılmışsa ve çok fazla kimlik doğrulama hatası oluşursa, uç nokta Retry-After ile 429 döndürür.

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

Bu uç noktayı gateway örneği için tam operatör erişimli bir yüzey olarak ele alın.

• Buradaki HTTP bearer kimlik doğrulaması dar bir kullanıcı başına kapsam modeli değildir.
• Bu uç nokta için geçerli bir Gateway token/parolası, sahip/operatör kimlik bilgisi gibi ele alınmalıdır.
• İstekler, güvenilir operatör eylemleriyle aynı denetim düzlemi ajan yolundan geçer.
• Bu uç noktada ayrı bir sahip olmayan/kullanıcı başına araç sınırı yoktur; bir çağırıcı burada Gateway kimlik doğrulamasını geçtikten sonra, OpenClaw bu çağırıcıyı bu gateway için güvenilir operatör olarak ele alır.
• Paylaşılan gizli anahtar kimlik doğrulama modlarında (token ve password), çağırıcı daha dar bir x-openclaw-scopes başlığı gönderse bile uç nokta normal tam operatör varsayılanlarını geri yükler.
• Güvenilir kimlik taşıyan HTTP modları (örneğin güvenilir proxy kimlik doğrulaması veya gateway.auth.mode="none") mevcut olduğunda x-openclaw-scopes değerine uyar ve aksi halde normal operatör varsayılan kapsam kümesine geri döner.
• Hedef ajan ilkesi hassas araçlara izin veriyorsa, bu uç nokta onları kullanabilir.
• Bu uç noktayı yalnızca loopback/tailnet/özel giriş üzerinde tutun; doğrudan genel internete açmayın.

Kimlik doğrulama matrisi:

• gateway.auth.mode="token" veya "password" + Authorization: Bearer ...
  • paylaşılan gateway operatör sırrına sahip olunduğunu kanıtlar
  • daha dar x-openclaw-scopes değerini yok sayar
  • tam varsayılan operatör kapsam kümesini geri yükler: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • bu uç noktadaki sohbet dönüşlerini sahip gönderen dönüşleri olarak ele alır
• güvenilir kimlik taşıyan HTTP modları (örneğin güvenilir proxy kimlik doğrulaması veya özel girişte gateway.auth.mode="none")
  • bazı dış güvenilir kimliği veya dağıtım sınırını doğrular
  • başlık mevcut olduğunda x-openclaw-scopes değerine uyar
  • başlık yoksa normal operatör varsayılan kapsam kümesine geri döner
  • yalnızca çağırıcı kapsamları açıkça daraltıp operator.admin öğesini atladığında sahip semantiğini kaybeder
  • x-openclaw-model gibi sahip düzeyi istek denetimleri için operator.admin gerektirir

Bkz. Güvenlik ve Uzaktan erişim.

Bu uç nokta ne zaman kullanılmalı

Mevcut bir gateway ile araçları veya güvenilir bir uygulama tarafı arka ucu tümleştiriyorsanız ve gateway operatör kimlik bilgilerini güvenle tutabiliyorsanız /v1/chat/completions kullanın.

• 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 istemciler için WebChat veya Gateway Protocol tercih edin ve cihazın paylaşılan bir HTTP token/parolasına ihtiyaç duymaması için eşleştirilmiş cihaz önyükleme/cihaz token akışını uygulayın.
• Kendi kullanıcıları, odaları, Webhook teslimi veya giden aktarımı olan harici bir mesajlaşma ağıyla tümleştiriyorsanız 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 ele alır.

• model: "openclaw" yapılandırılmış varsayılan ajana yönlendirir.
• model: "openclaw/default" da yapılandırılmış varsayılan ajana yönlendirir.
• model: "openclaw/<agentId>" belirli bir ajana yönlendirir.

İsteğe bağlı istek başlıkları:

• x-openclaw-model: <provider/model-or-bare-id> seçilen ajan için arka uç modelini geçersiz kılar. Paylaşılan gizli anahtar bearer çağırıcıları bu başlığı kullanabilir. Güvenilir proxy veya x-openclaw-scopes içeren özel kimlik doğrulamasız giriş istekleri gibi kimlik taşıyan çağırıcılar operator.admin gerektirir; yalnızca yazma yetkili çağırıcılar 403 missing scope: operator.admin alır.
• x-openclaw-agent-id: <agentId> uyumluluk geçersiz kılması olarak desteklenmeye devam eder.
• x-openclaw-session-key: <sessionKey> oturum yönlendirmesini açıkça denetler. Değer subagent:, cron: veya acp: gibi ayrılmış dahili oturum ad alanlarını kullanmamalıdır; bu istekler 400 invalid_request_error ile reddedilir.
• x-openclaw-message-channel: <channel> kanal farkında istemler ve ilkeler için sentetik giriş kanalı bağlamını ayarlar.

Hâlâ kabul edilen uyumluluk takma adları:

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

Uç noktayı etkinleştirme

gateway.http.endpoints.chatCompletions.enabled değerini true olarak ayarlayın:

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

Uç noktayı devre dışı bırakma

gateway.http.endpoints.chatCompletions.enabled değerini false olarak ayarlayın:

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

Oturum davranışı

Varsayılan olarak uç nokta istek başına durumsuzdur (her çağrıda yeni bir oturum anahtarı oluşturulur).

İstek bir OpenAI user dizesi içeriyorsa, Gateway bundan kararlı bir oturum anahtarı türetir; böylece tekrarlanan çağrılar bir ajan oturumunu paylaşabilir.

Özel uygulamalar için en güvenli varsayılan, konuşma iş parçacığı başına aynı user değerini yeniden kullanmaktır. Birden çok konuşmanın veya cihazın tek bir OpenClaw oturumunu paylaşmasını açıkça istemiyorsanız hesap düzeyi tanımlayıcılardan kaçının. x-openclaw-session-key değerini yalnızca birden çok istemci veya iş parçacığı arasında açık yönlendirme denetimine ihtiyaç duyduğunuzda kullanın ve subagent:, cron: veya acp: gibi ayrılmış dahili ad alanlarıyla başlamayan, uygulamaya ait anahtarlar seçin.

Bu yüzey neden önemlidir

Bu, kendi barındırdığınız ön uçlar ve araçlar için en yüksek kaldıraçlı uyumluluk kümesidir:

• Çoğu Open WebUI, LobeChat ve LibreChat kurulumu /v1/models bekler.
• Birçok RAG sistemi /v1/embeddings bekler.
• Mevcut OpenAI sohbet istemcileri genellikle /v1/chat/completions ile başlayabilir.
• Daha ajan-yerel istemciler giderek daha fazla /v1/responses tercih eder.

Model listesi ve ajan yönlendirme

Akış (SSE)

Server-Sent Events (SSE) almak için stream: true ayarlayın:

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

Sohbet aracı sözleşmesi

/v1/chat/completions, yaygın OpenAI Chat istemcileriyle uyumlu bir function-tool alt kümesini destekler.

Desteklenen istek alanları

• tools: { "type": "function", "function": { ... } } dizisi
• tool_choice: "auto", "none", "required" veya { "type": "function", "function": { "name": "..." } }
• messages[*].role: "tool" takip dönüşleri
• messages[*].tool_call_id araç sonuçlarını önceki bir araç çağrısına geri bağlamak için
• max_completion_tokens: sayı; toplam tamamlama token'ları için çağrı başına üst sınır (akıl yürütme token'ları dahil). Geçerli OpenAI Chat Completions alan adı; hem max_completion_tokens hem de max_tokens gönderildiğinde tercih edilir.
• max_tokens: sayı; geriye dönük uyumluluk için kabul edilen eski takma ad. max_completion_tokens da mevcut olduğunda yok sayılır.
• temperature: sayı; agent stream-param kanalı üzerinden yukarı akış sağlayıcısına iletilen en iyi çaba örnekleme sıcaklığı.
• top_p: sayı; agent stream-param kanalı üzerinden yukarı akış sağlayıcısına iletilen en iyi çaba nucleus sampling.
• frequency_penalty: sayı; agent stream-param kanalı üzerinden yukarı akış sağlayıcısına iletilen en iyi çaba frequency penalty. Doğrulanan aralık: -2.0 ile 2.0 arası. Aralık dışı değerler için 400 invalid_request_error döndürür.
• presence_penalty: sayı; agent stream-param kanalı üzerinden yukarı akış sağlayıcısına iletilen en iyi çaba presence penalty. Doğrulanan aralık: -2.0 ile 2.0 arası. Aralık dışı değerler için 400 invalid_request_error döndürür.
• seed: sayı (tamsayı); agent stream-param kanalı üzerinden yukarı akış sağlayıcısına iletilen en iyi çaba seed. Tamsayı olmayan değerler için 400 invalid_request_error döndürür.
• stop: dize veya en fazla 4 dizeden oluşan dizi; agent stream-param kanalı üzerinden yukarı akış sağlayıcısına iletilen en iyi çaba durdurma dizileri. 4'ten fazla dizi veya dize olmayan/boş girdiler için 400 invalid_request_error döndürür.

Her iki token sınırı alanından biri ayarlandığında, değer agent stream-param kanalı üzerinden upstream sağlayıcıya iletilir. Upstream sağlayıcıya gönderilen gerçek wire alanı adı sağlayıcı transport'u tarafından seçilir: OpenAI ailesi endpoint'leri için max_completion_tokens, yalnızca eski adı kabul eden sağlayıcılar için (Mistral ve Chutes gibi) max_tokens. Örnekleme alanları (temperature, top_p, frequency_penalty, presence_penalty, seed) aynı stream-param kanalını izler; ChatGPT tabanlı Codex Responses backend'i, sabit örnekleme kullandığı için bunları sunucu tarafında çıkarır. stop da stream-param kanalı üzerinden gider ve transport'un stop alanına eşlenir (Chat Completions backend'leri için stop, Anthropic için stop_sequences); OpenAI Responses API'de stop parametresi yoktur, bu nedenle stop Responses destekli modellerde uygulanmaz.

Desteklenmeyen varyantlar

Endpoint, aşağıdakiler dahil desteklenmeyen araç varyantları için 400 invalid_request_error döndürür:

• dizi olmayan tools
• işlev olmayan araç girdileri
• eksik tool.function.name
• allowed_tools ve custom gibi tool_choice varyantları
• sağlanan tools ile eşleşmeyen tool_choice.function.name değerleri

tool_choice: "required" ve işleve sabitlenmiş tool_choice için endpoint, açığa çıkarılan istemci işlev-aracı kümesini daraltır, runtime'a yanıt vermeden önce bir istemci aracını çağırması talimatını verir ve agent yanıtı eşleşen yapılandırılmış bir istemci-aracı çağrısı içermiyorsa hata döndürür. Bu sözleşme, her dahili OpenClaw agent aracına değil, çağıranın sağladığı HTTP tools listesine uygulanır.

Streaming olmayan araç yanıtı şekli

Agent araçları çağırmaya karar verdiğinde yanıt şunu kullanır:

• choices[0].finish_reason = "tool_calls"
• Şunları içeren choices[0].message.tool_calls[] girdileri:
  • id
  • type: "function"
  • function.name
  • function.arguments (JSON dizesi)

Araç çağrısından önceki assistant yorumu choices[0].message.content içinde döndürülür (boş olabilir).

Streaming araç yanıtı şekli

stream: true olduğunda, araç çağrıları artımlı SSE parçaları olarak yayınlanır:

• ilk assistant rol deltası
• isteğe bağlı assistant yorum deltaları
• araç kimliğini ve argüman parçalarını taşıyan bir veya daha fazla delta.tool_calls parçası
• finish_reason: "tool_calls" içeren son parça
• data: [DONE]

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

Araç takip döngüsü

İstemci, tool_calls aldıktan sonra istenen işlevleri yürütmeli ve şunları içeren bir takip isteği göndermelidir:

• önceki assistant araç çağrısı mesajı
• eşleşen tool_call_id değerlerine sahip bir veya daha fazla role: "tool" mesajı

Bu, Gateway agent çalışmasının aynı muhakeme döngüsüne devam etmesini ve son assistant yanıtını üretmesini sağlar.

Open WebUI hızlı kurulum

Temel bir Open WebUI bağlantısı için:

• Temel URL: http://127.0.0.1:18789/v1
• macOS üzerinde Docker temel URL'si: http://host.docker.internal:18789/v1
• API anahtarı: Gateway bearer token'ınız
• Model: openclaw/default

Beklenen davranış:

• GET /v1/models, openclaw/default değerini listelemelidir
• Open WebUI, sohbet model kimliği olarak openclaw/default kullanmalıdır
• Bu agent için belirli bir backend sağlayıcı/model istiyorsanız, agent'ın normal varsayılan modelini ayarlayın veya paylaşılan gizli anahtarlı bir çağırandan ya da operator.admin içeren kimlik taşıyan bir çağırandan x-openclaw-model gönderin

Hızlı smoke testi:

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

Bu openclaw/default döndürürse, çoğu Open WebUI kurulumu aynı temel URL ve token ile 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ı agent oturumunu sürdürmek için bu konuşmanın sonraki çağrılarında aynı user değerini yeniden kullanın.

Streaming olmayan:

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

Modelleri listele:

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

Tek bir modeli getir:

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

Embedding oluştur:

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

Notlar:

• /v1/models, ham sağlayıcı kataloglarını değil OpenClaw agent hedeflerini döndürür.
• openclaw/default her zaman bulunur; böylece tek bir kararlı kimlik ortamlar arasında çalışır.
• Backend sağlayıcı/model geçersiz kılmaları OpenAI model alanında değil, x-openclaw-model içinde olmalıdır. Kimlik taşıyan HTTP kimlik doğrulama yollarında bu header operator.admin gerektirir.
• /v1/embeddings, input değerini dize veya dize dizisi olarak destekler.

İlgili

• Yapılandırma başvurusu
• OpenAI