Ana içeriğe atla

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.

vLLM, açık kaynaklı (ve bazı özel) modelleri OpenAI uyumlu bir HTTP API aracılığıyla sunabilir. OpenClaw, openai-completions API kullanarak vLLM’ye bağlanır. OpenClaw, VLLM_API_KEY ile dahil olduğunuzda vLLM’den kullanılabilir modelleri de otomatik keşfedebilir (sunucunuz kimlik doğrulamayı zorunlu kılmıyorsa herhangi bir değer çalışır). Özel bir vLLM temel URL’si de yapılandırdığınızda keşfi dinamik tutmak için agents.defaults.models içinde vllm/* kullanın. OpenClaw, vllm değerini akışlı kullanım muhasebesini destekleyen yerel OpenAI uyumlu bir sağlayıcı olarak ele alır; böylece durum/bağlam token sayıları stream_options.include_usage yanıtlarından güncellenebilir.
ÖzellikDeğer
Sağlayıcı Kimliğivllm
APIopenai-completions (OpenAI uyumlu)
Kimlik doğrulamaVLLM_API_KEY ortam değişkeni
Varsayılan temel URLhttp://127.0.0.1:8000/v1

​
Başlarken

1

vLLM'yi OpenAI uyumlu bir sunucuyla başlatın

Temel URL’niz /v1 uç noktalarını sunmalıdır (ör. /v1/models, /v1/chat/completions). vLLM genellikle şu adreste çalışır:
http://127.0.0.1:8000/v1
2

API anahtarı ortam değişkenini ayarlayın

Sunucunuz kimlik doğrulamayı zorunlu kılmıyorsa herhangi bir değer çalışır:
export VLLM_API_KEY="vllm-local"
3

Bir model seçin

Kendi vLLM model kimliklerinizden biriyle değiştirin:
{
  agents: {
    defaults: {
      model: { primary: "vllm/your-model-id" },
    },
  },
}
4

Modelin kullanılabilir olduğunu doğrulayın

openclaw models list --provider vllm

​
Model keşfi (örtük sağlayıcı)

VLLM_API_KEY ayarlandığında (veya bir kimlik doğrulama profili bulunduğunda) ve models.providers.vllm tanımlamadığınızda OpenClaw şu sorguyu yapar: 
GET http://127.0.0.1:8000/v1/models
ve dönen kimlikleri model girdilerine dönüştürür.
models.providers.vllm değerini açıkça ayarlarsanız OpenClaw varsayılan olarak bildirdiğiniz modelleri kullanır. OpenClaw’ın yapılandırılmış sağlayıcının /models uç noktasını sorgulamasını ve ilan edilen tüm vLLM modellerini dahil etmesini istediğinizde agents.defaults.models içine "vllm/*": {} ekleyin.

​
Açık yapılandırma (manuel modeller)

Açık yapılandırmayı şu durumlarda kullanın:
  • vLLM farklı bir ana makinede veya bağlantı noktasında çalışıyorsa
  • contextWindow veya maxTokens değerlerini sabitlemek istiyorsanız
  • Sunucunuz gerçek bir API anahtarı gerektiriyorsa (veya üst bilgileri kontrol etmek istiyorsanız)
  • Güvenilir bir loopback, LAN veya Tailscale vLLM uç noktasına bağlanıyorsanız
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        request: { allowPrivateNetwork: true },
        timeoutSeconds: 300, // Optional: extend connect/header/body/request timeout for slow local models
        models: [
          {
            id: "your-model-id",
            name: "Local vLLM Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}
Her modeli manuel olarak listelemeden bu sağlayıcıyı dinamik tutmak için görünür model kataloğuna bir sağlayıcı joker karakteri ekleyin: 
{
  agents: {
    defaults: {
      models: {
        "vllm/*": {},
      },
    },
  },
}

​
Gelişmiş yapılandırma

vLLM, yerel bir OpenAI uç noktası olarak değil, proxy tarzı OpenAI uyumlu bir /v1 arka ucu olarak ele alınır. Bunun anlamı:
DavranışUygulandı mı?
Yerel OpenAI istek şekillendirmesiHayır
service_tierGönderilmez
Responses storeGönderilmez
İstem önbelleği ipuçlarıGönderilmez
OpenAI reasoning uyumluluk yükü şekillendirmesiUygulanmaz
Gizli OpenClaw atıf üst bilgileriÖzel temel URL’lerde enjekte edilmez
vLLM üzerinden sunulan Qwen modelleri için, sunucu Qwen sohbet şablonu kwargs beklediğinde model girdisinde params.qwenThinkingFormat: "chat-template" ayarlayın. OpenClaw /think off değerini şuna eşler:
{
  "chat_template_kwargs": {
    "enable_thinking": false,
    "preserve_thinking": true
  }
}
off dışındaki düşünme düzeyleri enable_thinking: true gönderir. Uç noktanız bunun yerine DashScope tarzı üst düzey bayraklar bekliyorsa istek kökünde enable_thinking göndermek için params.qwenThinkingFormat: "top-level" kullanın. Snake-case params.qwen_thinking_format da kabul edilir.
vLLM/Nemotron 3, reasoning’in gizli reasoning veya görünür yanıt metni olarak döndürülüp döndürülmeyeceğini kontrol etmek için sohbet şablonu kwargs kullanabilir. Bir OpenClaw oturumu düşünme kapalıyken vllm/nemotron-3-* kullandığında, paketli vLLM Plugin şunu gönderir:
{
  "chat_template_kwargs": {
    "enable_thinking": false,
    "force_nonempty_content": true
  }
}
Bu değerleri özelleştirmek için model parametreleri altında chat_template_kwargs ayarlayın. Ayrıca params.extra_body.chat_template_kwargs ayarlarsanız, extra_body son istek gövdesi geçersiz kılması olduğundan bu değer son önceliğe sahip olur.
{
  agents: {
    defaults: {
      models: {
        "vllm/nemotron-3-super": {
          params: {
            chat_template_kwargs: {
              enable_thinking: false,
              force_nonempty_content: true,
            },
          },
        },
      },
    },
  },
}
Önce vLLM’nin model için doğru araç çağrısı ayrıştırıcısı ve sohbet şablonuyla başlatıldığından emin olun. Örneğin vLLM, Qwen2.5 modelleri için hermes ve Qwen3-Coder modelleri için qwen3_xml belgeler.Belirtiler:
  • skills veya araçlar hiç çalışmaz
  • asistan {"name":"read","arguments":...} gibi ham JSON/XML yazdırır
  • OpenClaw tool_choice: "auto" gönderdiğinde vLLM boş bir tool_calls dizisi döndürür
Bazı Qwen/vLLM kombinasyonları yapılandırılmış araç çağrılarını yalnızca istek tool_choice: "required" kullandığında döndürür. Bu model girdileri için OpenAI uyumlu istek alanını params.extra_body ile zorlayın:
{
  agents: {
    defaults: {
      models: {
        "vllm/Qwen-Qwen2.5-Coder-32B-Instruct": {
          params: {
            extra_body: {
              tool_choice: "required",
            },
          },
        },
      },
    },
  },
}
Qwen-Qwen2.5-Coder-32B-Instruct değerini şu komutun döndürdüğü tam kimlikle değiştirin:
openclaw models list --provider vllm
Aynı geçersiz kılmayı CLI üzerinden uygulayabilirsiniz:
openclaw config set agents.defaults.models '{"vllm/Qwen-Qwen2.5-Coder-32B-Instruct":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
Bu, isteğe bağlı bir uyumluluk geçici çözümüdür. Araçlarla yapılan her model turunun bir araç çağrısı gerektirmesine neden olur; bu yüzden yalnızca bu davranışın kabul edilebilir olduğu özel bir yerel model girdisi için kullanın. Bunu tüm vLLM modelleri için genel varsayılan olarak kullanmayın ve rastgele asistan metnini körü körüne çalıştırılabilir araç çağrılarına dönüştüren bir proxy kullanmayın.
vLLM sunucunuz varsayılan olmayan bir ana makinede veya bağlantı noktasında çalışıyorsa açık sağlayıcı yapılandırmasında baseUrl ayarlayın:
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://192.168.1.50:9000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        request: { allowPrivateNetwork: true },
        timeoutSeconds: 300,
        models: [
          {
            id: "my-custom-model",
            name: "Remote vLLM Model",
            reasoning: false,
            input: ["text"],
            contextWindow: 64000,
            maxTokens: 4096,
          },
        ],
      },
    },
  },
}

​
Sorun giderme

Büyük yerel modeller, uzak LAN ana makineleri veya tailnet bağlantıları için sağlayıcı kapsamlı bir istek zaman aşımı ayarlayın:
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://192.168.1.50:8000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        request: { allowPrivateNetwork: true },
        timeoutSeconds: 300,
        models: [{ id: "your-model-id", name: "Local vLLM Model" }],
      },
    },
  },
}
timeoutSeconds yalnızca bağlantı kurulumu, yanıt üst bilgileri, gövde akışı ve toplam korumalı fetch iptali dahil olmak üzere vLLM model HTTP isteklerine uygulanır. Tüm agent çalışmasını kontrol eden agents.defaults.timeoutSeconds değerini artırmadan önce bunu tercih edin.
vLLM sunucusunun çalıştığını ve erişilebilir olduğunu kontrol edin:
curl http://127.0.0.1:8000/v1/models
Bir bağlantı hatası görürseniz ana makineyi, bağlantı noktasını ve vLLM’nin OpenAI uyumlu sunucu moduyla başlatıldığını doğrulayın. Açık loopback, LAN veya Tailscale uç noktaları için ayrıca models.providers.vllm.request.allowPrivateNetwork: true ayarlayın; sağlayıcı açıkça güvenilir olarak işaretlenmedikçe sağlayıcı istekleri varsayılan olarak özel ağ URL’lerini engeller.
İstekler kimlik doğrulama hatalarıyla başarısız olursa, sunucu yapılandırmanızla eşleşen gerçek bir VLLM_API_KEY ayarlayın veya sağlayıcıyı models.providers.vllm altında açıkça yapılandırın.
vLLM sunucunuz kimlik doğrulamayı zorunlu kılmıyorsa VLLM_API_KEY için boş olmayan herhangi bir değer OpenClaw için isteğe bağlı dahil olma sinyali olarak çalışır.
Otomatik keşif için VLLM_API_KEY ayarlanmış olmalıdır. models.providers.vllm tanımladıysanız, agents.defaults.models "vllm/*": {} içermediği sürece OpenClaw yalnızca bildirdiğiniz modelleri kullanır.
Bir Qwen modeli bir skill çalıştırmak yerine JSON/XML araç söz dizimi yazdırıyorsa yukarıdaki Gelişmiş yapılandırma bölümündeki Qwen yönergelerini kontrol edin. Olağan düzeltme şudur:
  • vLLM’yi o model için doğru ayrıştırıcı/şablonla başlatın
  • tam model kimliğini openclaw models list --provider vllm ile onaylayın
  • yalnızca tool_choice: "auto" hâlâ boş veya yalnızca metin araç çağrıları döndürüyorsa özel model başına params.extra_body.tool_choice: "required" geçersiz kılmasını ekleyin
Daha fazla yardım: Sorun giderme ve SSS.

​
İlgili

Model seçimi

Sağlayıcıları, model referanslarını ve yük devretme davranışını seçme.

OpenAI

Yerel OpenAI sağlayıcısı ve OpenAI uyumlu rota davranışı.

OAuth ve kimlik doğrulama

Kimlik doğrulama ayrıntıları ve kimlik bilgisi yeniden kullanım kuralları.

Sorun giderme

Yaygın sorunlar ve bunların nasıl çözüleceği.