Modeller CLI

Model ref'leri bir sağlayıcı ve model seçer. Genellikle düşük seviyeli ajan çalışma zamanını seçmezler. OpenAI ajan ref'leri ana istisnadır: openai/gpt-5.5, resmi OpenAI sağlayıcısında varsayılan olarak Codex app-server çalışma zamanı üzerinden çalışır. Abonelik Copilot ref'leri (github-copilot/*) ayrıca harici GitHub Copilot ajan çalışma zamanı Plugin'ine dahil edilebilir; bu yol açık kalır (auto yedeği yoktur). Açık çalışma zamanı geçersiz kılmaları tüm ajan veya oturum üzerinde değil, sağlayıcı/model ilkesi üzerinde yer alır. Codex çalışma zamanı modunda, openai/gpt-* ref'i API anahtarı faturalandırması anlamına gelmez; kimlik doğrulama bir Codex hesabından veya openai OAuth profilinden gelebilir. Bkz. Ajan çalışma zamanları ve GitHub Copilot ajan çalışma zamanı.

Model seçimi nasıl çalışır

OpenClaw modelleri şu sırayla seçer:

Seçim kaynağı ve yedek davranışı

Aynı provider/model, nereden geldiğine bağlı olarak farklı şeyler ifade edebilir:

• Yapılandırılmış varsayılanlar (agents.defaults.model.primary ve ajana özgü birinciller) normal başlangıç noktasıdır ve agents.defaults.model.fallbacks kullanır.
• Otomatik yedek seçimleri geçici kurtarma durumudur. Sonraki turların bilinen bozuk bir birincili her seferinde yoklamadan yedek zincirini kullanmaya devam edebilmesi için modelOverrideSource: "auto" ile saklanırlar; OpenClaw özgün birincili düzenli olarak tekrar yoklar, toparlandığında otomatik seçimi temizler ve yedek/toparlanma geçişlerini durum değişikliği başına bir kez duyurur.
• Kullanıcı oturum seçimleri kesindir. /model, model seçici, session_status(model=...) ve sessions.patch, modelOverrideSource: "user" saklar; seçilen sağlayıcı/model erişilemezse OpenClaw başka bir yapılandırılmış modele düşmek yerine görünür şekilde başarısız olur.
• agents.defaults.model.primary değiştirmek mevcut oturum seçimlerini yeniden yazmaz. Durum This session is pinned to X; config primary Y will apply to new/unpinned sessions. diyorsa, geçerli oturum seçimini /model default ile temizleyin; böylece yapılandırılmış birincili tekrar devralır.
• Cron --model / yük model, iş başına bir birincildir. İş açık yük fallbacks sağlamadığı sürece yapılandırılmış yedekleri kullanmaya devam eder (katı bir cron çalıştırması için fallbacks: [] kullanın).
• CLI varsayılan model ve izin listesi seçicileri, tam yerleşik kataloğu yüklemek yerine açık models.providers.*.models değerlerini listeleyerek models.mode: "replace" ayarına uyar.
• Control UI model seçici, Gateway'den yapılandırılmış model görünümünü ister: varsa sağlayıcı genelinde provider/* girdileri dahil agents.defaults.models, yoksa açık models.providers.*.models artı kullanılabilir kimlik doğrulamaya sahip sağlayıcılar. Tam yerleşik katalog, view: "all" ile models.list veya openclaw models list --all gibi açık göz atma görünümleri için ayrılmıştır.

Hızlı model ilkesi

• Birincilinizi erişebildiğiniz en güçlü en yeni nesil modele ayarlayın.
• Maliyet/gecikme duyarlı görevler ve daha düşük riskli sohbet için yedekleri kullanın.
• Araç etkin ajanlar veya güvenilmeyen girdiler için daha eski/zayıf model katmanlarından kaçının.

İlk kurulum (önerilir)

Yapılandırmayı elle düzenlemek istemiyorsanız ilk kurulumu çalıştırın:

openclaw onboard

Yaygın sağlayıcılar için model + kimlik doğrulama kurabilir; buna OpenAI Code (Codex) aboneliği (OAuth) ve Anthropic (API anahtarı veya Claude CLI) dahildir.

Yapılandırma anahtarları (genel bakış)

• agents.defaults.model.primary ve agents.defaults.model.fallbacks
• agents.defaults.imageModel.primary ve agents.defaults.imageModel.fallbacks
• agents.defaults.pdfModel.primary ve agents.defaults.pdfModel.fallbacks
• agents.defaults.imageGenerationModel.primary ve agents.defaults.imageGenerationModel.fallbacks
• agents.defaults.videoGenerationModel.primary ve agents.defaults.videoGenerationModel.fallbacks
• agents.defaults.models (izin listesi + takma adlar + sağlayıcı parametreleri + provider/* dinamik sağlayıcı girdileri)
• models.providers (models.json içine yazılan özel sağlayıcılar)

Güvenli izin listesi düzenlemeleri

agents.defaults.models değerini elle güncellerken eklemeli yazmaları kullanın:

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge

"Model is not allowed" (ve yanıtların neden durduğu)

agents.defaults.models ayarlanırsa /model ve oturum geçersiz kılmaları için izin listesi haline gelir. Bir kullanıcı bu izin listesinde olmayan bir model seçtiğinde OpenClaw şunu döndürür:

Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

Reddedilen komut /model openai/gpt-5.5 --runtime codex gibi bir çalışma zamanı geçersiz kılması içeriyorsa önce izin listesini düzeltin, ardından aynı /model ... --runtime ... komutunu tekrar deneyin. Yerel Codex yürütmesi için seçilen model yine openai/gpt-5.5 olur; codex çalışma zamanı harness'i seçer ve Codex kimlik doğrulamasını ayrı kullanır.

Yerel/GGUF modeller için izin listesinde tam sağlayıcı önekli ref'i saklayın; örneğin ollama/gemma4:26b, lmstudio/Gemma4-26b-a4-it-gguf veya openclaw models list --provider <provider> tarafından gösterilen tam sağlayıcı/model. İzin listesi etkinken çıplak yerel dosya adları veya görünen adlar yeterli değildir.

Her modeli elle listelemeden sağlayıcıları sınırlamak istiyorsanız agents.defaults.models değerine provider/* girdileri ekleyin:

{  agents: {    defaults: {      models: {        "openai/*": {},        "vllm/*": {},      },    },  },}

Bu ilkeyle /model, /models ve model seçiciler yalnızca bu sağlayıcılar için keşfedilen kataloğu gösterir. Seçilen sağlayıcılardan gelen yeni modeller izin listesini düzenlemeden görünebilir. Başka bir sağlayıcıdan tek bir belirli modele ihtiyaç duyduğunuzda tam provider/model girdileri provider/* girdileriyle karıştırılabilir.

Örnek izin listesi yapılandırması:

{  agents: {    defaults: {      model: { primary: "anthropic/claude-sonnet-4-6" },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "anthropic/claude-opus-4-6": { alias: "Opus" },      },    },  },}

Sohbette model değiştirme (/model)

Yeniden başlatmadan geçerli oturum için modelleri değiştirebilirsiniz:

/model/model list/model 3/model openai/gpt-5.4/model default/model status

Tam komut davranışı/yapılandırması: Slash komutları.

CLI komutları

openclaw models listopenclaw models statusopenclaw models set <provider/model>openclaw models set-image <provider/model> openclaw models aliases listopenclaw models aliases add <alias> <provider/model>openclaw models aliases remove <alias> openclaw models fallbacks listopenclaw models fallbacks add <provider/model>openclaw models fallbacks remove <provider/model>openclaw models fallbacks clear openclaw models image-fallbacks listopenclaw models image-fallbacks add <provider/model>openclaw models image-fallbacks remove <provider/model>openclaw models image-fallbacks clear

openclaw models (alt komut olmadan), models status için bir kısayoldur.

models list

Varsayılan olarak yapılandırılmış/kimlik doğrulamayla kullanılabilir modelleri gösterir. Yararlı bayraklar:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> Sağlayıcı kimliğine göre filtreler, örneğin moonshot. Etkileşimli seçicilerdeki görüntü etiketleri kabul edilmez.

models status

Çözümlenen birincil modeli, fallback'leri, görüntü modelini ve yapılandırılmış sağlayıcıların kimlik doğrulama özetini gösterir. Ayrıca kimlik doğrulama deposunda bulunan profiller için OAuth süre sonu durumunu yüzeye çıkarır (varsayılan olarak 24 saat içinde uyarır). --plain yalnızca çözümlenen birincil modeli yazdırır.

Örnek (Claude CLI):

claude auth loginopenclaw models status

Tarama (OpenRouter ücretsiz modelleri)

openclaw models scan, OpenRouter'ın ücretsiz model kataloğunu inceler ve isteğe bağlı olarak modelleri araç ve görüntü desteği için yoklayabilir.

Tarama sonuçları şuna göre sıralanır:

1. Görüntü desteği
2. Araç gecikmesi
3. Bağlam boyutu
4. Parametre sayısı

Girdi:

• OpenRouter /models listesi (filtre :free)
• Canlı yoklamalar, kimlik doğrulama profillerinden veya OPENROUTER_API_KEY içinden OpenRouter API anahtarı gerektirir (bkz. Ortam değişkenleri)
• İsteğe bağlı filtreler: --max-age-days, --min-params, --provider, --max-candidates
• İstek/yoklama denetimleri: --timeout, --concurrency

Canlı yoklamalar bir TTY içinde çalıştığında, fallback'leri etkileşimli olarak seçebilirsiniz. Etkileşimsiz modda varsayılanları kabul etmek için --yes iletin. Yalnızca meta veri sonuçları bilgilendirme amaçlıdır; --set-default ve --set-image, OpenClaw'ın kullanılamaz anahtarsız bir OpenRouter modeli yapılandırmaması için canlı yoklamalar gerektirir.

Modeller kayıt defteri (models.json)

models.providers içindeki özel sağlayıcılar, aracı dizini altında models.json içine yazılır (varsayılan ~/.openclaw/agents/<agentId>/agent/models.json). Sağlayıcı-Plugin katalogları, aracının Plugin durumu altında oluşturulmuş Plugin'e ait katalog parçaları olarak saklanır ve otomatik yüklenir. Bu dosya, models.mode replace olarak ayarlanmadığı sürece varsayılan olarak birleştirilir.

İlgili

• Aracı çalışma zamanları — OpenClaw, Codex ve diğer aracı döngüsü çalışma zamanları
• Yapılandırma başvurusu — model yapılandırma anahtarları
• Görüntü oluşturma — görüntü modeli yapılandırması
• Model devretme — fallback zincirleri
• Model sağlayıcıları — sağlayıcı yönlendirme ve kimlik doğrulama
• Müzik oluşturma — müzik modeli yapılandırması
• Video oluşturma — video modeli yapılandırması