Yerel modeller

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Donanım tabanı

​

Bir arka uç seçin

​

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

{
  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,
          },
        ],
      },
    },
  },
}

• LM Studio’yu kurun: https://lmstudio.ai
• LM Studio’da mevcut en büyük model derlemesini indirin (“small”/yoğun biçimde nicemlenmiş varyantlardan kaçının), sunucuyu başlatın, http://127.0.0.1:1234/v1/models adresinin onu 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ıç gecikmesi ekler.
• LM Studio derlemeniz farklıysa contextWindow/maxTokens değerlerini ayarlayın.
• WhatsApp için yalnızca son metnin gönderilmesi amacıyla Responses API’ye bağlı kalın.

​

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

{
  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 güvenlik ağıyla yerel öncelikli

​

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

• Barındırılan MiniMax/Kimi/GLM varyantları OpenRouter üzerinde bölgeye sabitlenmiş uç noktalarla da bulunur (ör. ABD’de barındırılan). Trafiği seçtiğiniz yargı alanında tutmak ve yine de Anthropic/OpenAI yedekleri için models.mode: "merge" kullanmak üzere oradaki bölgesel varyantı seçin.
• Yalnızca yerel kullanım en güçlü gizlilik yoludur; sağlayıcı özelliklerine ihtiyaç duyduğunuz ancak veri akışı üzerinde kontrol istediğiniz durumlarda barındırılan bölgesel yönlendirme orta yoldur.

​

Diğer OpenAI uyumlu yerel proxy’ler

{
  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,
          },
        ],
      },
    },
  },
}

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

• OpenClaw bunları yerel OpenAI uç noktaları değil, proxy tarzı OpenAI uyumlu rotalar olarak ele alır
• yerel OpenAI’ye özgü istek şekillendirme burada uygulanmaz: service_tier yok, Responses store yok, OpenAI akıl yürütme uyumluluğu payload şekillendirmesi yok ve istem önbelleği ipuçları yok
• gizli OpenClaw atıf başlıkları (originator, version, User-Agent) bu özel proxy URL’lerine eklenmez

• Bazı sunucular Chat Completions üzerinde yapılandırılmış içerik parçası dizilerini değil, yalnızca string messages[].content kabul eder. Bu uç noktalar için models.providers.<provider>.models[].compat.requiresStringContent: true ayarlayın.
• Bazı yerel modeller, metin olarak tek başına köşeli parantezli araç istekleri üretir; örneğin [tool_name] ardından JSON ve [END_TOOL_REQUEST]. OpenClaw bunları yalnızca ad, o dönüş için kayıtlı bir araçla tam olarak eşleştiğinde gerçek araç çağrılarına yükseltir; aksi halde blok desteklenmeyen metin olarak ele alınır ve kullanıcıya görünen yanıtlardan gizlenir.
• Bir model araç çağrısı gibi görünen JSON, XML veya ReAct tarzı metin üretirse ancak sağlayıcı yapılandırılmış bir çağrı üretmediyse, OpenClaw bunu metin olarak bırakır ve mümkün olduğunda çalıştırma kimliği, sağlayıcı/model, algılanan örüntü ve araç adıyla bir uyarı günlüğe yazar. Bunu tamamlanmış bir araç çalıştırması değil, sağlayıcı/model araç çağrısı uyumsuzluğu olarak değerlendirin.
• Araçlar çalışmak yerine asistan metni olarak görünüyorsa, örneğin ham JSON, XML, ReAct söz dizimi veya sağlayıcı yanıtında boş bir tool_calls dizisi, önce sunucunun araç çağrısı destekli bir chat şablonu/ayrıştırıcısı kullandığını doğrulayın. Ayrıştırıcısı yalnızca araç kullanımı zorlandığında çalışan OpenAI uyumlu Chat Completions arka uçları için, metin ayrıştırmaya güvenmek yerine model başına istek geçersiz kılması ayarlayın:
  {
    agents: {
      defaults: {
        models: {
          "local/my-local-model": {
            params: {
              extra_body: {
                tool_choice: "required",
              },
            },
          },
        },
      },
    },
  }
  
  Bunu yalnızca her normal dönüşün bir araç çağırması gereken modeller/oturumlar için kullanın. OpenClaw’ın varsayılan proxy değeri olan tool_choice: "auto" değerini geçersiz kılar. local/my-local-model değerini openclaw models list tarafından gösterilen tam sağlayıcı/model referansıyla değiştirin.
  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
  
• Özel OpenAI uyumlu bir model, yerleşik profilin ötesinde OpenAI akıl yürütme çabalarını kabul ediyorsa, bunları model compat bloğunda bildirin. Buraya "xhigh" eklemek, yapılandırılmış sağlayıcı/model referansı için /think xhigh, oturum seçicileri, Gateway doğrulaması ve llm-task doğrulamasının bu düzeyi sunmasını sağlar:
  {
    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

1. Yerel modelin kendisinin 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 sağlanan istemi gönderir — transkripti, AGENTS önyüklemesini, context-engine derlemesini, araçları ve paketli MCP sunucularını atlar, ancak yine de Gateway yönlendirmesini, kimlik doğrulamayı ve sağlayıcı seçimini çalıştırır:
   openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
   
3. Yalın modu deneyin. Her iki deneme de geçiyor ancak gerçek ajan dönüşleri hatalı biçimlendirilmiş araç çağrıları veya aşırı büyük istemlerle başarısız oluyorsa, agents.defaults.experimental.localModelLean: true değerini etkinleştirin. İstem şeklinin daha küçük ve daha az kırılgan olması için en ağır üç varsayılan aracı (browser, cron, message) çıkarır. Tam açıklama, ne zaman kullanılacağı ve açık 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. Yalın mod yeterli değilse, o model girdisi için models.providers.<provider>.models[].compat.supportsTools: false ayarlayın. Ajan daha sonra o modelde araç çağrıları olmadan çalışır.
5. Bundan sonrası için dar boğaz yukarı akıştadır. Yalın mod ve supportsTools: false sonrasında arka uç yalnızca daha büyük OpenClaw çalıştırmalarında hâlâ başarısız oluyorsa, kalan sorun genellikle yukarı akış model veya sunucu kapasitesidir — bağlam penceresi, GPU belleği, kv-cache çıkarımı veya arka uç hatası. Bu noktada sorun OpenClaw’ın aktarım katmanı değildir.

​

Sorun giderme

• Gateway proxy’ye ulaşabiliyor mu? curl http://127.0.0.1:1234/v1/models.
• LM Studio modeli kaldırılmış mı? Yeniden yükleyin; soğuk başlatma yaygın bir “takılma” nedenidir.
• Yerel sunucu terminated, ECONNRESET diyor veya akışı dönüşün ortasında kapatıyor mu? OpenClaw, tanılarda düşük kardinaliteli bir model.call.error.failureKind ile birlikte 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 macOS çökme / jetsam günlüğüyle eşleştirin.
• OpenClaw, bağlam penceresi ön denetim eşiklerini algılanan model penceresinden veya agents.defaults.contextTokens etkin pencereyi düşürdüğünde sınırlandırılmamış model penceresinden türetir. %20’nin altında 8k tabanla uyarır. Katı engellemeler, 4k tabanla %10 eşiğini kullanır ve etkin bağlam penceresiyle sınırlandırılır; böylece aşırı büyük model meta verileri, aksi halde geçerli olan bir kullanıcı sınırını reddedemez. Bu ön denetime takılırsanız, sunucu/model bağlam sınırını yükseltin veya daha büyük bir model seçin.
• Bağlam hataları mı var? contextWindow değerini düşürün veya sunucu sınırınızı yükseltin.
• OpenAI uyumlu sunucu messages[].content ... expected a string döndürüyor mu? O model girdisine compat.requiresStringContent: true ekleyin.
• OpenAI uyumlu sunucu validation.keys döndürüyor veya ileti girdilerinin yalnızca role ve content alanlarına izin verdiğini mi söylüyor? O model girdisine compat.strictMessageKeys: true ekleyin.
• Doğrudan küçük /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; yerel model run ajan araçlarını içermez. Yerel model run başarılı oluyor ancak daha büyük ajan dönüşleri başarısız oluyorsa, ajan 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 ya da sağlayıcı boş bir tool_calls dizisi mi döndürüyor? Asistan metnini körlemesine araç yürütmeye dönüştüren bir proxy eklemeyin. Önce sunucu sohbet şablonunu/ayrıştırıcısını düzeltin. Model yalnızca araç kullanımı zorlandığında çalışıyorsa, yukarıdaki model başına params.extra_body.tool_choice: "required" geçersiz kılmasını ekleyin ve o 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ı filtreleri atlar; istem enjeksiyonu etki alanını sınırlamak için ajanları dar tutun ve Compaction açık olsun.

​

İlgili

• Yapılandırma referansı
• Model yük devri