Yerel modeller

Yerel modeller çalışır, ancak donanım, bağlam boyutu ve istem enjeksiyonuna karşı savunma gereksinimlerini yükseltir: küçük veya agresif biçimde nicemlenmiş modeller bağlamı keser ve sağlayıcı tarafındaki güvenlik filtrelerini atlar. Bu sayfa, üst düzey yerel yığınları ve özel OpenAI uyumlu sunucuları ele alır. En sorunsuz yol için LM Studio veya Ollama ile openclaw onboard kullanarak başlayın.

Yalnızca seçilen bir model bunlara ihtiyaç duyduğunda başlatılması gereken yerel sunucular için Yerel model hizmetleri bölümüne bakın.

Asgari donanım

Rahat bir ajan döngüsü için 2 veya daha fazla tam donanımlı Mac Studio ya da eşdeğer bir GPU sistemi (~30 bin ABD doları veya üzeri) hedefleyin. Tek bir 24 GB GPU, yalnızca daha hafif istemleri daha yüksek gecikmeyle işleyebilir. Her zaman barındırabileceğiniz en büyük / tam boyutlu varyantı çalıştırın; küçük veya yoğun biçimde nicemlenmiş denetim noktaları istem enjeksiyonu riskini artırır (Güvenlik bölümüne bakın).

Bir arka uç seçin

Arka uç destekliyorsa api: "openai-responses" kullanın (LM Studio destekler). Aksi takdirde api: "openai-completions" kullanın. baseUrl içeren özel bir sağlayıcıda api belirtilmezse OpenClaw varsayılan olarak openai-completions kullanır.

LM Studio + büyük yerel model (Responses API)

Bu, şu anda en iyi yerel yığındır. LM Studio'ya büyük bir model (tam boyutlu bir Qwen, DeepSeek veya Llama derlemesi) yükleyin, yerel sunucuyu etkinleştirin (varsayılan http://127.0.0.1:1234) ve akıl yürütmeyi nihai metinden ayrı tutmak için Responses API'yi kullanın.

{  agents: {    defaults: {      model: { primary: "lmstudio/my-local-model" },      models: {        "anthropic/claude-opus-4-6": { alias: "Opus" },        "lmstudio/my-local-model": { alias: "Local" },      },    },  },  models: {    mode: "merge",    providers: {      lmstudio: {        baseUrl: "http://127.0.0.1:1234/v1",        apiKey: "lmstudio",        api: "openai-responses",        models: [          {            id: "my-local-model",            name: "Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 196608,            maxTokens: 8192,          },        ],      },    },  },}

Kurulum kontrol listesi:

• LM Studio'yu yükleyin: https://lmstudio.ai
• Mevcut en büyük model derlemesini indirin ("küçük"/yoğun biçimde nicemlenmiş varyantlardan kaçının), sunucuyu başlatın ve http://127.0.0.1:1234/v1/models adresinin modeli listelediğini doğrulayın.
• my-local-model değerini LM Studio'da gösterilen gerçek model kimliğiyle değiştirin.
• Modeli yüklü tutun; soğuk yükleme başlangıç gecikmesini artırır.
• LM Studio derlemeniz farklıysa contextWindow/maxTokens değerlerini ayarlayın.
• WhatsApp için yalnızca nihai metnin gönderilmesi amacıyla Responses API'yi kullanmaya devam edin.
• Barındırılan modellerin yedek olarak kullanılabilir kalması için models.mode: "merge" ayarını koruyun.

Hibrit yapılandırma: barındırılan birincil model, yerel yedek model

{  agents: {    defaults: {      model: {        primary: "anthropic/claude-sonnet-4-6",        fallbacks: ["lmstudio/my-local-model", "anthropic/claude-opus-4-6"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "lmstudio/my-local-model": { alias: "Local" },        "anthropic/claude-opus-4-6": { alias: "Opus" },      },    },  },  models: {    mode: "merge",    providers: {      lmstudio: {        baseUrl: "http://127.0.0.1:1234/v1",        apiKey: "lmstudio",        api: "openai-responses",        models: [          {            id: "my-local-model",            name: "Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 196608,            maxTokens: 8192,          },        ],      },    },  },}

Barındırılan bir güvenlik ağıyla yerel öncelikli kullanım için primary/fallbacks sırasını değiştirin ve aynı providers bloğu ile models.mode: "merge" ayarını koruyun.

Bölgesel barındırma / veri yönlendirme

Barındırılan MiniMax/Kimi/GLM varyantları, bölgeye sabitlenmiş uç noktalarla (örneğin ABD'de barındırılan) OpenRouter üzerinde de bulunur. Anthropic/OpenAI yedekleri için models.mode: "merge" ayarını korurken trafiği seçtiğiniz yargı alanında tutmak için bölgesel varyantı seçin. Yalnızca yerel kullanım hâlâ en güçlü gizlilik yoludur; sağlayıcı özelliklerine ihtiyaç duyduğunuz ancak veri akışı üzerinde denetim istediğiniz durumlarda barındırılan bölgesel yönlendirme orta yolu sunar.

Diğer OpenAI uyumlu yerel proxy'ler

MLX (mlx_lm.server), vLLM, SGLang, LiteLLM, OAI-proxy veya herhangi bir özel Gateway, OpenAI tarzı bir /v1/chat/completions uç noktası sunuyorsa çalışır. Arka uç /v1/responses desteğini açıkça belgelemediği sürece openai-completions kullanın.

{  agents: {    defaults: {      model: { primary: "local/my-local-model" },    },  },  models: {    mode: "merge",    providers: {      local: {        baseUrl: "http://127.0.0.1:8000/v1",        apiKey: "sk-local",        api: "openai-completions",        timeoutSeconds: 300,        models: [          {            id: "my-local-model",            name: "Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 120000,            maxTokens: 8192,          },        ],      },    },  },}

Özel/yerel sağlayıcı girdileri; local loopback, LAN, tailnet ve özel DNS ana makineleri dâhil olmak üzere, korumalı model istekleri için tam olarak yapılandırılmış baseUrl kaynağına güvenir. Meta veri/bağlantı-yerel kaynakları ne olursa olsun her zaman engellenir. Diğer özel kaynaklara yönelik istekler için yine models.providers.<id>.request.allowPrivateNetwork: true gerekir; tam kaynak güvenini devre dışı bırakmak için güven bayrağını false olarak ayarlayın.

models.providers.<id>.models[].id sağlayıcıya özeldir; sağlayıcı önekini eklemeyin. mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit ile başlatılan bir MLX sunucusu için:

• models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"
• agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"

Görüntü eklerinin ajan turlarına dâhil edilmesi için yerel veya proxy üzerinden kullanılan görüntü modellerinde input: ["text", "image"] ayarını yapın. Etkileşimli özel sağlayıcı başlangıç yapılandırması, yaygın görüntü modeli kimliklerini çıkarır ve yalnızca bilinmeyen adlar hakkında soru sorar; etkileşimsiz başlangıç yapılandırması da aynı çıkarımı kullanır ve bunu geçersiz kılmak için --custom-image-input / --custom-text-input seçeneklerini sunar.

agents.defaults.timeoutSeconds değerini yükseltmeden önce yavaş yerel/uzak model sunucuları için models.providers.<id>.timeoutSeconds kullanın. Sağlayıcı zaman aşımı yalnızca model HTTP istekleri için bağlantıyı, üstbilgileri, gövde akışını ve korumalı getirme işleminin toplam iptal süresini kapsar; ajan/çalıştırma zaman aşımı daha düşükse onu da yükseltin, çünkü sağlayıcı zaman aşımı tüm çalıştırmanın süresini uzatamaz.

Yerel/proxy üzerinden kullanılan /v1 arka uçları için davranış notları:

• OpenClaw bunları yerel OpenAI uç noktaları olarak değil, proxy tarzı OpenAI uyumlu yollar olarak ele alır.
• Yalnızca yerel OpenAI için kullanılan istek biçimlendirmesi uygulanmaz: service_tier yoktur, Responses store yoktur, OpenAI akıl yürütme uyumluluğu yük biçimlendirmesi yoktur, istem önbelleği ipuçları yoktur.
• Gizli OpenClaw atıf üstbilgileri (originator, version, User-Agent) özel proxy URL'lerine eklenmez.

Daha katı OpenAI uyumlu arka uçlar için uyumluluk geçersiz kılmaları:

• Yalnızca dize içerik: Bazı sunucular yapılandırılmış içerik parçası dizilerini değil, yalnızca dize türündeki messages[].content değerlerini kabul eder. models.providers.<provider>.models[].compat.requiresStringContent: true ayarını yapın.

• Katı ileti anahtarları: Sunucu role/content dışında anahtarlar içeren ileti girdilerini reddediyorsa compat.strictMessageKeys: true ayarını yapın.

• Köşeli ayraçlı araç metni: Bazı yerel modeller, JSON ve [END_TOOL_REQUEST] tarafından takip edilen [tool_name] gibi bağımsız köşeli ayraçlı araç isteklerini metin olarak üretir. OpenClaw bunları yalnızca ad, ilgili tur için kaydedilmiş bir araçla tam olarak eşleştiğinde gerçek araç çağrılarına dönüştürür; aksi takdirde gizli ve desteklenmeyen metin olarak kalır.

• Yapılandırılmamış, araç çağrısına benzeyen metin: Bir model yapılandırılmış bir çağrı olmadığı hâlde araç çağrısına benzeyen JSON/XML/ReAct tarzı metin üretirse OpenClaw bunu metin olarak bırakır ve kullanılabildiğinde çalıştırma kimliği, sağlayıcı/model, algılanan desen ve araç adıyla birlikte bir uyarı günlüğe kaydeder. Bu, tamamlanmış bir araç çalıştırması değil, sağlayıcı/model uyumsuzluğudur.

• Araç kullanımını zorlama: Araçlar asistan metni olarak görünüyorsa (ham JSON/XML/ReAct veya boş bir tool_calls dizisi), önce sunucunun sohbet şablonunun/ayrıştırıcısının araç çağrılarını desteklediğini doğrulayın. Ayrıştırıcı yalnızca araç kullanımı zorlandığında çalışıyorsa varsayılan proxy değeri olan tool_choice: "auto" ayarını model bazında geçersiz kılın:

  {  agents: {    defaults: {      models: {        "local/my-local-model": {          params: {            extra_body: {              tool_choice: "required",            },          },        },      },    },  },}

  Bunu yalnızca her normal turun bir araç çağırması gereken durumlarda kullanın. local/my-local-model değerini openclaw models list çıktısındaki tam referansla değiştirin veya CLI aracılığıyla ayarlayın:

  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge

• Ek akıl yürütme düzeyleri: Özel bir OpenAI uyumlu model, yerleşik profilin ötesindeki OpenAI akıl yürütme düzeylerini kabul ediyorsa bunları modelin uyumluluk bloğunda bildirin. "xhigh" eklemek, bu model referansı için /think xhigh, oturum seçicileri, Gateway doğrulaması ve llm-task doğrulamasında bu düzeyi kullanılabilir hâle getirir:

  {  models: {    providers: {      local: {        baseUrl: "http://127.0.0.1:8000/v1",        apiKey: "sk-local",        api: "openai-responses",        models: [          {            id: "gpt-5.4",            name: "GPT 5.4 via local proxy",            reasoning: true,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 196608,            maxTokens: 8192,            compat: {              supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],              reasoningEffortMap: { xhigh: "xhigh" },            },          },        ],      },    },  },}

Daha küçük veya daha katı arka uçlar

Model sorunsuz biçimde yükleniyor ancak tam ajan turları hatalı davranıyorsa yukarıdan aşağıya ilerleyin: önce aktarımı doğrulayın, ardından kapsamı daraltın.

1. Yerel modelin yanıt verdiğini doğrulayın - araç yok, ajan bağlamı yok:

   openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json

2. Gateway yönlendirmesini doğrulayın - yalnızca istemi gönderir; transkripti, AGENTS önyüklemesini, bağlam motoru derlemesini, araçları ve paketlenmiş MCP sunucularını atlar, ancak yine de Gateway yönlendirmesini, kimlik doğrulamayı ve sağlayıcı seçimini sınar:

   openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json

3. Her iki yoklama da başarılı olduğu hâlde gerçek ajan dönüşleri hatalı biçimlendirilmiş araç çağrıları veya aşırı büyük istemler nedeniyle başarısız oluyorsa yalın modu deneyin: agents.defaults.experimental.localModelLean: true olarak ayarlayın. Açıkça gerekmedikçe ağır tarayıcı, cron, mesajlaşma, medya oluşturma, ses ve PDF araçlarını kaldırır; exec aracını doğrudan görünür tutarken daha büyük araç kataloglarını varsayılan olarak yapılandırılmış Araç Arama denetimlerinin arkasına alır. Ayrıntılar ve etkin olduğunu nasıl doğrulayacağınız için Deneysel Özellikler -> Yerel model yalın modu bölümüne bakın.

4. Son çare olarak araçları tamamen devre dışı bırakın; ilgili model için models.providers.<provider>.models[].compat.supportsTools: false ayarını yapın; ardından ajan, araç çağrıları olmadan çalışır.

5. Bu noktadan sonra darboğaz üst sistemdedir. Yalın mod ve supportsTools: false sonrasında arka uç hâlâ yalnızca daha büyük OpenClaw çalıştırmalarında başarısız oluyorsa kalan sorun genellikle OpenClaw'ın aktarım katmanı değil, modelin veya sunucunun kendisidir: bağlam penceresi, GPU belleği, kv-cache tahliyesi ya da bir arka uç hatası.

Sorun giderme

• Gateway proxy'ye ulaşamıyor mu? curl http://127.0.0.1:1234/v1/models.
• LM Studio modeli bellekten kaldırılmış mı? Yeniden yükleyin; soğuk başlatma, "takılmanın" yaygın bir nedenidir.
• Yerel sunucu terminated veya ECONNRESET mı bildiriyor ya da dönüşün ortasında akışı kapatıyor mu? OpenClaw, tanılamalarda düşük kardinaliteli bir model.call.error.failureKind değerini ve OpenClaw işleminin RSS/heap anlık görüntüsünü kaydeder. LM Studio/Ollama bellek baskısı için model sunucusunun sonlandırılıp sonlandırılmadığını doğrulamak üzere bu zaman damgasını sunucu günlüğüyle veya bir macOS çökme/jetsam günlüğüyle eşleştirin.
• Bağlam hataları mı var? OpenClaw, bağlam penceresi ön kontrol eşiklerini algılanan model penceresinden (veya agents.defaults.contextTokens bunu düşürdüğünde sınırlandırılmış pencereden) türetir; %20'nin altında en az 8k eşiğiyle uyarır ve %10'un altında en az 4k eşiğiyle kesin olarak engeller (aşırı büyük model meta verilerinin geçerli bir kullanıcı sınırını reddedememesi için etkin bağlam penceresiyle sınırlandırılır). contextWindow değerini düşürün veya sunucu/model bağlam sınırını yükseltin.
• messages[].content ... expected a string mı görüyorsunuz? İlgili model girdisine compat.requiresStringContent: true ekleyin.
• validation.keys veya "message entries only allow role and content" mı görüyorsunuz? İlgili model girdisine compat.strictMessageKeys: true ekleyin.
• Doğrudan /v1/chat/completions çağrıları çalışıyor ancak openclaw infer model run --local, Gemma veya başka bir yerel modelde başarısız mı oluyor? Önce sağlayıcı URL'sini, model referansını, kimlik doğrulama işaretçisini ve sunucu günlüklerini kontrol edin; model run, ajan araçlarını tamamen atlar. model run başarılı oluyor ancak daha büyük ajan dönüşleri başarısız oluyorsa araç yüzeyini localModelLean veya compat.supportsTools: false ile azaltın.
• Araç çağrıları ham JSON/XML/ReAct metni olarak mı görünüyor veya sağlayıcı boş bir tool_calls dizisi mi döndürüyor? Asistan metnini körü körüne araç çalıştırmaya dönüştüren bir proxy eklemeyin; önce sunucunun sohbet şablonunu/ayrıştırıcısını düzeltin. Model yalnızca araç kullanımı zorunlu kılındığında çalışıyorsa yukarıdaki params.extra_body.tool_choice: "required" geçersiz kılma ayarını ekleyin ve bu model girdisini yalnızca her dönüşte bir araç çağrısının beklendiği oturumlarda kullanın.
• Güvenlik: Yerel modeller, sağlayıcı tarafındaki filtreleri atlar. İstem enjeksiyonunun etki alanını sınırlamak için ajanların kapsamını dar tutun ve Compaction özelliğini açık bırakın.

İlgili

• Yapılandırma başvurusu
• Model yük devretmesi