AIREITERBir modelin dosya okuması, kod çalıştırması, hatayı incelemesi ve sonunda bir çıktı dosyası üretmesi gerekiyorsa OpenRouter’ın shell akışı oldukça kullanışlı olabilir. Ancak openrouter:shell, container’lar ve Files API hâlâ beta aşamasında. Bu yüzden doğrudan üretim açısından kritik bir iş akışına bağlamak yerine, sınırları belli bir görevle başlamak daha doğru olur.
Özetle: OpenRouter shell ne zaman mantıklı?
OpenRouter’ın openrouter:shell aracı, tool calling destekli bir modelin barındırılan bir Linux ortamında komut çalıştırmasını sağlar. Model; stdout, stderr ve çıkış kodunu alıp çalışmasını buna göre düzeltebilir. Girdi ve çıktı dosyalarının taşınmasını ise Files API üstlenir.
Şu senaryolarda tercih edebilirsiniz:
- Uygulama sunucunuzdan bağımsız şekilde kod çalıştıran, modelden bağımsız bir agent oluşturmak istiyorsanız.
- CSV analizi, PDF’den veri çıkarma veya rapor üretimi gibi tekrarlanabilir dosya işleme görevleri çalıştıracaksanız.
- Kendi sandbox ortamınızı kurmadan sunucu tarafında tool çalıştırmak istiyorsanız.
Bunu yerel shell’in doğrudan alternatifi gibi düşünmeyin. Ağ erişimi varsayılan olarak kapalıdır, container’lar otomatik olarak kalıcı olmaz ve beta sürecinde API değişebilir.
Pratikte tasarımı belirleyen mimari
| Bileşen | Ne işe yarar? | Tasarımı etkileyen ayrıntı |
|---|---|---|
openrouter:shell | Tool destekli bir modelin komut çalıştırmasını sağlar | Responses API ve Anthropic Messages API üzerinden kullanılabilir (duyuru) |
| Container | Komutları izole bir Linux ortamında çalıştırır | Bir session veya container referansı yeniden kullanılmadıkça yeni container’lar temiz bir ortamla başlar |
| Files API | Girdileri ve kalıcı hâle getirilen çıktıları saklar | Doğrudan yüklenen dosyalar eklenebilir; ancak dokümana göre indirilemez (yükleme referansı) |
openrouter:bash, Anthropic uyumlu alternatiftir. Varsayılan çalıştırma yolu, komutları uygulamanın yerel olarak yürütmesini ister. Uzaktan çalıştırma gerekiyorsa engine: "openrouter" değerini ayarlayın; ayrıntılar shell duyurusunda yer alıyor.
Bir dosyanın sistem içindeki yolculuğu
1. Girdiyi yükleyip isteğe ekleyin
Dosyayı multipart form data olarak POST /api/v1/files endpoint’ine yükleyin. Yükleme referansında dosya başına en fazla 100 MB desteklendiği ve isteğe bağlı bir workspace_id query parametresinin kullanılabildiği belirtiliyor.
curl -X POST https://openrouter.ai/api/v1/files \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-F "file=@data/sales.csv"Yanıt; dosya kimliği, dosya adı, MIME türü, byte cinsinden boyut, oluşturulma zamanı ve downloadable bayrağı gibi metadata bilgileri döndürür. Dönen dosya kimliğini shell ortamının file_ids dizisine ekleyin.
Eklenen dosyalar container’a yazılabilir kopyalar olarak alınır. Shell duyurusuna göre bir container en fazla 20 dosya alabilir. Kopya üzerinde yapılan değişiklikler, workspace’teki orijinal dosyayı etkilemez.
Bir geliştiricinin, daha önce yaşanan PDF/OCR sorunlarını anlattıktan sonra Files API desteğini özellikle olumlu karşılaması da dosya işlemenin gerçek bir entegrasyon problemi olduğuna dair küçük ama somut bir işaret (paylaşım).
2. Çalıştırın, sonucu inceleyin, gerekirse tekrarlayın
Model, container’a bir grup komut gönderir. Her çalıştırmanın sonunda çıktı ve çıkış durumu döner. Böylece model, ilk prompt’tan tahmin yürütmek yerine başarısız olan script’i düzeltebilir (shell duyurusu).
Varsayılan ağ politikası tüm erişimi engeller. İşin paket indirmesi veya harici isteklere erişmesi gerekiyorsa container oluşturulurken bir allowlist tanımlayın. OpenRouter, allowlist’e alınan host’lar için 80 ve 443 portlarını dokümante ediyor; container başladıktan sonra bu politika değiştirilemiyor. Allowlist dışındaki alan adlarına yapılan istekler HTTP 520 hatasıyla sonuçlanabilir (shell duyurusu).
Shell sonuçlarında yalnızca /workspace/home altındaki dosyalar yakalanır. API’nin dosyayı raporlamasını istiyorsanız çıktıyı bu dizine yazın. Shell tarafından oluşturulan veya değiştirilen dosyalara cfile_ kimlikleri verilir (shell duyurusu).
3. Çıktıyı indirin veya kalıcı hâle getirin
Shell tarafından üretilen dosya, container dosya içeriği endpoint’i üzerinden alınabilir:
GET /api/v1/containers/{container_id}/files/{file_id}/contentcfile_ kimliği container’a aittir. Çıktının container yaşam döngüsünden sonra da saklanması gerekiyorsa workspace depolamasına aktarın. Bu işlem, daha sonraki bir çalıştırmaya eklenebilen yeni bir or_file_ kimliği oluşturur (shell duyurusu).
| Dosya türü | Tipik kimlik | Files API ile indirilebilir mi? | En uygun kullanım |
|---|---|---|---|
| Doğrudan yükleme | or_file_... | Hayır, indirme referansına göre | Daha sonraki bir çalıştırmanın girdisi |
| Container çıktısı | cfile_... | Container endpoint’i üzerinden | Geçici çıktı |
| Kalıcı hâle getirilmiş çıktı | or_file_... | Evet | Yeniden kullanılacak veya daha uzun süre saklanacak çıktı |
Container dosyaları 30 gün boyunca saklanır. Daha uzun süre tutulması gereken her şeyi workspace’e aktarın (shell duyurusu). Genel dosya indirme endpoint’i ham byte döndürür ve kullanıcı tarafından yüklenen dosyalar için HTTP 400 durumunu dokümante eder. Bu nedenle doğrudan yüklenen dosyaları genel amaçlı bir object storage nesnesi değil, girdi olarak değerlendirmek gerekir.
Tasarımı etkileyen maliyetler ve limitler
OpenRouter’ın shell duyurusuna göre aktif sandbox süresi saniyede $0.0001 olarak ücretlendirilir. Soğuk başlayan bir container için minimum süre 30 saniyedir; dolayısıyla hesaplandığında minimum sandbox ücreti $0.003 olur. Token ücretleri buna dahil değildir.
| Kısıt | Dokümante edilen değer | Tasarım açısından anlamı |
|---|---|---|
| Aktif sandbox süresi | $0.0001/saniye | Uzun komutlar sürekli maliyet oluşturur |
| Soğuk container minimumu | 30 saniye | Küçük işler bile minimum ücreti tetikleyebilir |
| Container uyku süresi | 5 dakika boşta | Uyku sonrasında yeniden kullanım yeni soğuk başlangıç minimumunu tetikleyebilir |
| Container başına dosya sayısı | 20 | Girdileri paketleyin veya aşamalı şekilde hazırlayın |
| Tek dosya yükleme boyutu | 100 MB | Daha büyük dosyaları bölün veya ön işleme tabi tutun |
| Workspace depolaması | 10 GiB | Eski çıktıları silin veya arşivleyin |
| Kalıcı hâle getirilmeyen container saklama süresi | 30 gün | Önemli çıktıları workspace’e aktarın |
İlişkili adımlarda sıcak bir container’ı yeniden kullanın, gereksiz model-tool döngülerinden kaçının ve token maliyetini sandbox maliyetinden ayrı kaydedin. Duyuruya göre Logs görünümünde model etkinliği ile sandbox çalıştırması ayrı zaman çizelgesi satırlarında gösterilir.
Temel istek yapısı
Beta sürecinde ortam şeması değişebilir; ancak dokümante edilen akışın temel yapısı şöyle: önce dosyayı yükleyin, ardından dönen dosya kimliğini shell destekli isteğe gönderin. Beta şeması değişirse hızlıca güncelleyebilmek için istek adaptörünü mümkün olduğunca küçük tutun.
{
"model": "your/tool-capable-model",
"tools": [
{
"type": "openrouter:shell",
"environment": {
"type": "container_auto",
"file_ids": ["or_file_your_uploaded_file_id"]
}
}
],
"input": "Analyze the attached CSV and write a summary to /workspace/home/report.md"
}Bu yapıyı duyuruda dokümante edilen Responses endpoint’ine gönderin. Üretimde kullanmadan önce güncel istek şemasını ve yanıt alanlarını canlı server-tools dokümantasyonuyla karşılaştırarak doğrulayın.
İlk entegrasyon için şu sırayı izleyin:
- Küçük bir girdi dosyası yükleyin ve dönen dosya kimliğini kaydedin.
toolsiçindeopenrouter:shellbulunan, tool destekli bir model için istek oluşturun.- Dosyayı
file_idsüzerinden açıkça ekleyin. - Modelden çıktıları
/workspace/homealtına yazmasını isteyin. - İşi başarılı kabul etmeden önce çıkış kodunu ve dosya listesini inceleyin.
- Container çıktısını indirin veya yeniden kullanılacaksa kalıcı hâle getirin.
- Token kullanımını ve sandbox süresini ayrı maliyet alanları olarak kaydedin.
Birden fazla istekten oluşan iş akışlarında session_id veya açık bir container referansı gönderin. Aksi durumda sonraki istek, önceki durumun hiçbirini taşımayan yeni bir container ile başlayabilir.
İlk nerede sorun çıkar ve nasıl önlem alınır?
| Sorun | Tasarımda alınacak önlem |
|---|---|
| Model tool’u çağıramıyor | Tool calling desteği olan bir model seçin; server tool tanımlamak bu yeteneği modele kendiliğinden kazandırmaz. |
| Komut internete erişemiyor | Deny-all ağ politikasıyla başlayın ve container başlatılmadan önce allowlist’i yapılandırın. |
| Çıktı kayboluyor | /workspace/home altına yazın ve dönen cfile_ kimliğini kullanın. Kalıcı çıktıları workspace’e aktarın. |
| Yüklenen dosya indirilemiyor | Doğrudan yüklenen dosyaları girdi olarak değerlendirin; shell çıktılarını container endpoint’i veya kalıcı hâle getirme akışı üzerinden alın. |
| İkinci istek projeyi kaybediyor | Session’ı veya container referansını yeniden kullanın. Varsayılan davranış yeni container oluşturmaktır. |
| Fatura beklenenden yüksek geliyor | Token ücretlerini sandbox süresinden ayrı takip edin ve 30 saniyelik soğuk başlangıç minimumunu hesaba katın. |
| Arayüz değişiyor | Beta entegrasyonunu bir adaptörün arkasında tutun; kimlikleri, indirilebilirliği ve yeniden kullanımı test edin. |
OpenRouter shell ve Files API hakkında sık sorulanlar
OpenRouter shell komutları benim bilgisayarımda mı çalıştırıyor?
Hayır. openrouter:shell, komutları OpenRouter tarafından barındırılan bir sandbox ortamında çalıştırmak üzere tasarlanmıştır. Anthropic uyumlu openrouter:bash farklı varsayılanlara sahiptir; uzaktan çalıştırma için engine: "openrouter" kullanın (shell duyurusu).
İstekler arasında dosyaları nasıl koruyabilirim?
Bir session’ı veya container referansını yeniden kullanın. Açıkça yeniden kullanım yapılmazsa sonraki istek temiz bir container ile başlayabilir.
or_file_ ile cfile_ arasındaki fark nedir?
or_file_, workspace Files API nesnesini tanımlar. cfile_ ise container içinde oluşturulan veya değiştirilen dosyayı belirtir. Kalıcı hâle getirme işlemi, container çıktısını yeni bir workspace dosya kimliğine dönüştürür.
Files API ayrı bir kullanım ücreti alıyor mu?
Shell duyurusuna göre Files API kullanımı için ayrı bir kullanım ücreti yok; ancak workspace depolaması 10 GiB ile sınırlı. Shell sandbox süresi ve model token kullanımı, geçerli oranlara göre ayrıca ücretlendirilir.
Shell tool üretime hazır mı?
Dokümantasyonda beta olarak belirtiliyor ve duyuruda API’nin değişebileceği konusunda uyarı yapılıyor. Denetimsiz bir üretim iş akışının arkasına koymadan önce açık limitler, sınırlandırılmış komutlar, uygulama seviyesinde kısıtlamalar ve bir geri dönüş yolu kullanın.
İş akışınız gerçek bir çıktı üretiyorsa tercih edin
OpenRouter shell ve Files API; temizlenmiş bir CSV, rapor, dönüştürülmüş görsel veya derlenmiş bir çıktı üreten aşamalı iş akışlarına uygun. Açık dosya kimlikleri, önceden tanımlanmış ağ politikası, container yeniden kullanımı ve kalıcı çıktılar için promotion akışını birlikte kullanın.
Görev yalnızca metin yanıtı üretmekten ibaretse ek sandbox maliyeti ve yaşam döngüsü yönetimi gereksizdir. Yerel kimlik bilgilerine, sınırsız ağ erişimine veya katı üretim garantilerine ihtiyaç duyuyorsa beta bu riskleri karşılayacak kadar olgunlaşana dek çalıştırmayı kontrolünüzdeki altyapıda tutun.
Kaynaklar: OpenRouter shell ve Files API duyurusu, Files API yükleme referansı, dosya içeriği indirme referansı.