Naar hoofdinhoud gaan

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 kan open-source (en sommige aangepaste) modellen aanbieden via een OpenAI-compatibele HTTP-API. OpenClaw maakt verbinding met vLLM via de openai-completions-API. OpenClaw kan beschikbare modellen ook automatisch ontdekken vanuit vLLM wanneer je je hiervoor aanmeldt met VLLM_API_KEY (elke waarde werkt als je server geen auth afdwingt) en je geen expliciete models.providers.vllm-vermelding definieert. OpenClaw behandelt vllm als een lokale OpenAI-compatibele provider die gestreamde gebruiksadministratie ondersteunt, zodat status-/contexttokentellingen kunnen worden bijgewerkt vanuit stream_options.include_usage-antwoorden.
EigenschapWaarde
Provider-IDvllm
APIopenai-completions (OpenAI-compatibel)
Authomgevingsvariabele VLLM_API_KEY
Standaardbasis-URLhttp://127.0.0.1:8000/v1

​
Aan de slag

1

Start vLLM met een OpenAI-compatibele server

Je basis-URL moet /v1-eindpunten aanbieden (bijv. /v1/models, /v1/chat/completions). vLLM draait vaak op:
http://127.0.0.1:8000/v1
2

Stel de omgevingsvariabele voor de API-sleutel in

Elke waarde werkt als je server geen auth afdwingt:
export VLLM_API_KEY="vllm-local"
3

Selecteer een model

Vervang dit door een van je vLLM-model-ID’s:
{
  agents: {
    defaults: {
      model: { primary: "vllm/your-model-id" },
    },
  },
}
4

Controleer of het model beschikbaar is

openclaw models list --provider vllm

​
Modeldetectie (impliciete provider)

Wanneer VLLM_API_KEY is ingesteld (of er een auth-profiel bestaat) en je geen models.providers.vllm definieert, vraagt OpenClaw het volgende op: 
GET http://127.0.0.1:8000/v1/models
en zet het de geretourneerde ID’s om naar modelvermeldingen.
Als je models.providers.vllm expliciet instelt, wordt automatische detectie overgeslagen en moet je modellen handmatig definiëren.

​
Expliciete configuratie (handmatige modellen)

Gebruik expliciete configuratie wanneer:
  • vLLM op een andere host of poort draait
  • Je contextWindow- of maxTokens-waarden wilt vastzetten
  • Je server een echte API-sleutel vereist (of je headers wilt beheren)
  • Je verbinding maakt met een vertrouwd local loopback-, LAN- of Tailscale-vLLM-eindpunt
{
  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,
          },
        ],
      },
    },
  },
}

​
Geavanceerde configuratie

vLLM wordt behandeld als een proxy-achtige OpenAI-compatibele /v1-backend, niet als een native OpenAI-eindpunt. Dit betekent:
GedragToegepast?
Native OpenAI-aanvraagvormingNee
service_tierNiet verzonden
Responses storeNiet verzonden
Prompt-cachehintsNiet verzonden
OpenAI-vorming van reasoning-compatibele payloadNiet toegepast
Verborgen OpenClaw-attributieheadersNiet geïnjecteerd op aangepaste basis-URL’s
Voor Qwen-modellen die via vLLM worden aangeboden, stel je params.qwenThinkingFormat: "chat-template" in op de modelvermelding wanneer de server Qwen chat-template-kwargs verwacht. OpenClaw wijst /think off toe aan:
{
  "chat_template_kwargs": {
    "enable_thinking": false,
    "preserve_thinking": true
  }
}
Niet-off denkniveaus verzenden enable_thinking: true. Als je eindpunt in plaats daarvan DashScope-achtige top-level-vlaggen verwacht, gebruik dan params.qwenThinkingFormat: "top-level" om enable_thinking in de requestroot te verzenden. Snake-case params.qwen_thinking_format wordt ook geaccepteerd.
vLLM/Nemotron 3 kan chat-template-kwargs gebruiken om te bepalen of reasoning wordt geretourneerd als verborgen reasoning of als zichtbare antwoordtekst. Wanneer een OpenClaw-sessie vllm/nemotron-3-* gebruikt met denken uit, verzendt de meegeleverde vLLM-Plugin:
{
  "chat_template_kwargs": {
    "enable_thinking": false,
    "force_nonempty_content": true
  }
}
Om deze waarden aan te passen, stel je chat_template_kwargs in onder de modelparams. Als je ook params.extra_body.chat_template_kwargs instelt, heeft die waarde uiteindelijke voorrang omdat extra_body de laatste override voor de requestbody is.
{
  agents: {
    defaults: {
      models: {
        "vllm/nemotron-3-super": {
          params: {
            chat_template_kwargs: {
              enable_thinking: false,
              force_nonempty_content: true,
            },
          },
        },
      },
    },
  },
}
Zorg er eerst voor dat vLLM is gestart met de juiste tool-call-parser en chat- template voor het model. vLLM documenteert bijvoorbeeld hermes voor Qwen2.5- modellen en qwen3_xml voor Qwen3-Coder-modellen.Symptomen:
  • Skills of tools worden nooit uitgevoerd
  • de assistent drukt ruwe JSON/XML af, zoals {"name":"read","arguments":...}
  • vLLM retourneert een lege tool_calls-array wanneer OpenClaw tool_choice: "auto" verzendt
Sommige Qwen/vLLM-combinaties retourneren gestructureerde toolaanroepen alleen wanneer de aanvraag tool_choice: "required" gebruikt. Forceer voor die modelvermeldingen het OpenAI-compatibele aanvraagveld met params.extra_body:
{
  agents: {
    defaults: {
      models: {
        "vllm/Qwen-Qwen2.5-Coder-32B-Instruct": {
          params: {
            extra_body: {
              tool_choice: "required",
            },
          },
        },
      },
    },
  },
}
Vervang Qwen-Qwen2.5-Coder-32B-Instruct door de exacte id die wordt geretourneerd door:
openclaw models list --provider vllm
Je kunt dezelfde override toepassen via de CLI:
openclaw config set agents.defaults.models '{"vllm/Qwen-Qwen2.5-Coder-32B-Instruct":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
Dit is een opt-in compatibiliteitsoplossing. Hierdoor vereist elke modelbeurt met tools een toolaanroep, dus gebruik dit alleen voor een specifieke lokale modelvermelding waarbij dat gedrag acceptabel is. Gebruik dit niet als globale standaard voor alle vLLM-modellen, en gebruik geen proxy die willekeurige assistenttekst blind omzet in uitvoerbare toolaanroepen.
Als je vLLM-server op een niet-standaardhost of -poort draait, stel dan baseUrl in de expliciete providerconfiguratie in:
{
  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,
          },
        ],
      },
    },
  },
}

​
Probleemoplossing

Stel voor grote lokale modellen, externe LAN-hosts of tailnet-koppelingen een providergebonden requesttime-out in:
{
  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 is alleen van toepassing op HTTP-aanvragen voor vLLM-modellen, inclusief het opzetten van de verbinding, responseheaders, bodystreaming en de totale guarded-fetch-afbreking. Geef hier de voorkeur aan voordat je agents.defaults.timeoutSeconds verhoogt, dat de volledige agentrun beheert.
Controleer of de vLLM-server draait en toegankelijk is:
curl http://127.0.0.1:8000/v1/models
Als je een verbindingsfout ziet, controleer dan de host, poort en of vLLM is gestart met de OpenAI-compatibele servermodus. Voor expliciete local loopback-, LAN- of Tailscale-eindpunten stel je ook models.providers.vllm.request.allowPrivateNetwork: true in; provider- aanvragen blokkeren standaard URL’s op privénetwerken, tenzij de provider expliciet wordt vertrouwd.
Als aanvragen mislukken met auth-fouten, stel dan een echte VLLM_API_KEY in die overeenkomt met je serverconfiguratie, of configureer de provider expliciet onder models.providers.vllm.
Als je vLLM-server geen auth afdwingt, werkt elke niet-lege waarde voor VLLM_API_KEY als opt-in-signaal voor OpenClaw.
Automatische detectie vereist dat VLLM_API_KEY is ingesteld en dat er geen expliciete models.providers.vllm-configuratievermelding is. Als je de provider handmatig hebt gedefinieerd, slaat OpenClaw detectie over en gebruikt het alleen je gedeclareerde modellen.
Als een Qwen-model JSON/XML-toolsyntaxis afdrukt in plaats van een Skill uit te voeren, controleer dan de Qwen-richtlijnen in Geavanceerde configuratie hierboven. De gebruikelijke oplossing is:
  • start vLLM met de juiste parser/template voor dat model
  • bevestig de exacte model-id met openclaw models list --provider vllm
  • voeg alleen een specifieke per-model-override params.extra_body.tool_choice: "required" toe als tool_choice: "auto" nog steeds lege of tekst-only toolaanroepen retourneert
Meer hulp: Probleemoplossing en FAQ.

​
Gerelateerd

Modelselectie

Providers, modelrefs en failovergedrag kiezen.

OpenAI

Native OpenAI-provider en OpenAI-compatibel routegedrag.

OAuth en auth

Auth-details en regels voor hergebruik van referenties.

Probleemoplossing

Veelvoorkomende problemen en hoe je ze oplost.