OpenCode-Wrap, OpenCode'un ücretsiz modelini OpenAI uyumlu yerel bir API'nin arkasına taşıyor

Ne geliştirildi

Bir geliştirici, OpenCode'un sunucu modununun önüne OpenAI uyumlu bir chat-completions API'si yerleştiren açık kaynak bir Node sunucu olan OpenCode-Wrap'ı yayımladı. Yazarın dev.to'daki gönderisine göre motivasyon, bir dizi küçük işti — oturumları yeniden adlandırma, compaction çıktısını özetleme, tek kullanımlık bağlayıcı script'ler — ve bu işler için token başına ödeme yapmak israf gibi geliyordu; mevcut ücretsiz katmanlar ise hep kayıt, anahtar ve panel gerektiriyordu.

Bu arada OpenCode, muse-spark-1.3-contributor-free adlı ücretsiz bir model sunmuştu; ancak dev.to gönderisi bu modele yalnızca OpenCode CLI üzerinden erişilebildiğini, diğer araçların çağırabileceği bir HTTP endpoint'i bulunmadığını belirtiyor. OpenCode-Wrap bu boşluğu dolduruyor: bir tarafta OpenAI'nin /v1/chat/completions protokolünü konuşan, diğer taraftan opencode serve'ın oturum tabanlı modeline bağlanan bir shim.

Bilinçli olarak ince bir mimari

Pipeline kısa: çağıran taraf OpenCode-Wrap'a 8000 portundan istek gönderir, wrapper isteği çevirip 4100 portundaki opencode serve'a iletir, o da ücretsiz modele bağlanır. Her şey tek bir Node süreci olarak, sıfır npm bağımlılığıyla çalışır, npx opencode-wrap ile başlar ve yerel opencode CLI'sının zaten elinde tuttuğu kimlik bilgilerini yeniden kullanır; böylece yönetilecek ayrı bir API anahtarı ya da yazılacak bir yapılandırma yoktur. Erişilebilir bir opencode serve örneği yoksa, wrapper kendi örneğini başlatır.

Asıl iş nerede yatıyor

dev.to gönderisi, protokol çevirisinin zor kısım olduğunu açıkça söylüyor; çünkü OpenAI'nin istek biçimi ile opencode'un oturum ve olay tabanlı modeli oldukça farklı.

Oturumlar istek başına ele alınıyor. Wrapper hiçbir durum tutmuyor: gelen her çağrı taze bir opencode oturumu oluşturuyor, tüm mesaj geçmişini içine yeniden oynatıyor ve oturumu ardından siliyor. Yazar bunun israf göründüğünü kabul ediyor ama sunucuyu bozulacak oturum durumu olmadığı için çökme konusunda son derece güvenli kıldığını savunuyor.

Akış (streaming) canlı aktarılıyor. Bir istek stream'i true yaptığında, backend'in message.part.delta olayları, tamponlanmak yerine geldikleri anda OpenAI tarzı SSE parçaları olarak iletiliyor. Olay veriyoluna erişilemezse, wrapper tamponlu yeniden oynatmaya düşüyor. Daha ince bir uç durum: akış başlıkları bir kez gönderildikten sonra HTTP durum kodu artık değişemez; bu yüzden akış ortasında ölen bir backend'in hatası, akışın içinde bir hata parçası olarak teslim ediliyor.

Tool calling en az şeffaf alan. opencode serve özel araçlar için geçiş (passthrough) sunmadığından, wrapper çağıran tarafın verdiği araçları prompt içinde tanımlıyor ve modelin yanıtındaki çitle çevrili (fenced) tool call'ları ayrıştırıp bunları düzgün OpenAI tool_calls olarak döndürüyor. bash, read ve edit gibi OpenCode'a özgü araçlar ise doğrudan sunucu tarafında çalışıyor. Belgelenmiş bir tuhaflık: tool_choice auto olarak ayarlandığında model ara sıra araç çağırmak yerine genel bilgiden yanıtlıyor; bu yüzden çağıranlar required'ı zorlamalı ya da belirli bir aracı adlandırmalı.

Hatalar OpenAI kurallarına göre normalize ediliyor. Ücretsiz katmanın geçici 500 hataları fırlattığı bildiriliyor; bu yüzden wrapper taze oturumlarla üç kez backoff'lu yeniden deneme yapıyor ve kalıcı hataları 429 ya da 502 olarak yüzeye çıkarıyor, böylece çağıranlar tanıdık yeniden deneme ve fallback mantığını uygulayabiliyor. Model ID'leri kırpılıp takma adlara bağlanıyor, bariz yazım hataları 400 ve bir öneriyle hızlıca başarısız oluyor, boş ve içeriksiz yanıtlar ise olduğu gibi sunulmak yerine yeniden deneniyor.

Daha geniş bir yığınla nasıl birleşiyor

Yazar ayrıca abonelikleri birden çok sağlayıcıya yayan bir gateway olan Lynkr'ı da sürdürüyor. İki entegrasyon deseni tanımlanıyor: Lynkr'ı yerel endpoint'e yönlendirmek, böylece ücretsiz modelin yönlendirme katmanında sıradan bir sağlayıcı hâline gelmesi; ya da wrapper'ı opencode.c içinde small_model olarak kaydederek gateway'i tamamen atlamak — böylece oturum başlıkları ve compaction özetleri ücretsiz backend'e giderken ana model ücretli yönlendirmede kalıyor.

Güvenlik sınırları ve yazarın değiştireceği şeyler

Paylaşımlı bir ücretsiz katmanın önünde bulunduğu için wrapper adil kullanım davranışı dayatıyor: yalnızca kişisel ve hafif kullanım, backend yavaşlama sinyali verdiğinde 429 yanıtıyla otomatik backoff, 8MB ile sınırlı istek gövdeleri ve kendi anahtarlarını yayınlamak yerine CLI kimlik bilgilerini yeniden kullandığı için yalnızca localhost'a açık olma.

Kabul edilen zayıf nokta, istek başına oturum yeniden oynatma. Artımlı geçmişli bir oturum havuzu, konuşkan iş yüklerinde gecikmeyi düşürürdi; ama yazar eklenen durum tutmanın hata ayıklamayı zorlaştıracağına ve kişisel ölçekli kullanım için basitliğin daha değerli olduğuna karar verdi.

Neden önemli

OpenAI chat-completions API'si, LLM araç ekosisteminin fiili ortak dili hâline geldi ve bu proje ince bir çeviri shim'inin ne kadar kaldıraç sağlayabileceğini gösteriyor: standartlara uymayan bir backend'i bu protokole sarın, ve uyumlu her script, agent çerçevesi ile editör bir gecede yeni bir backend kazanır. Aynı zamanda makul bir maliyet desenini de sergiliyor — başlıklandırma ve özetleme gibi yüksek hacimli, düşük riskli arka plan işlerini ücretsiz bir yerel backend'e yönlendirirken, asıl işler için ücretli modelleri saklamak. Yol boyunca yapılan ödünler — prompt içine enjekte edilen tool calling'den katı adil kullanım sınırlarına ve yalnızca localhost'a açık kimlik bilgilerine kadar — bu tür shim'lerin nerede görünmez olmaktan çıktığının faydalı bir haritasını sunuyor.