> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# vLLM
vLLM kan open-sourcemodellen (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 aanmeldt met `VLLM_API_KEY` (elke waarde werkt als je server geen authenticatie afdwingt). Gebruik `vllm/*` in `agents.defaults.models` om ontdekking dynamisch te houden wanneer je ook een aangepaste vLLM-basis-URL configureert.
OpenClaw behandelt `vllm` als een lokale OpenAI-compatibele provider die
gestreamde gebruiksboekhouding ondersteunt, zodat status-/contexttokentellingen kunnen worden bijgewerkt vanuit
`stream_options.include_usage`-reacties.
| Eigenschap | Waarde |
| ------------------ | ---------------------------------------- |
| Provider-ID | `vllm` |
| API | `openai-completions` (OpenAI-compatibel) |
| Authenticatie | `VLLM_API_KEY`-omgevingsvariabele |
| Standaardbasis-URL | `http://127.0.0.1:8000/v1` |
## Aan de slag
Je basis-URL moet `/v1`-eindpunten aanbieden (bijv. `/v1/models`, `/v1/chat/completions`). vLLM draait vaak op:
```
http://127.0.0.1:8000/v1
```
Elke waarde werkt als je server geen authenticatie afdwingt:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
export VLLM_API_KEY="vllm-local"
```
Vervang dit door een van je vLLM-model-ID's:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
agents: {
defaults: {
model: { primary: "vllm/your-model-id" },
},
},
}
```
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw models list --provider vllm
```
## Modelontdekking (impliciete provider)
Wanneer `VLLM_API_KEY` is ingesteld (of er een authenticatieprofiel bestaat) en je `models.providers.vllm` **niet** definieert, bevraagt OpenClaw:
```
GET http://127.0.0.1:8000/v1/models
```
en zet de geretourneerde ID's om in modelvermeldingen.
Als je `models.providers.vllm` expliciet instelt, gebruikt OpenClaw standaard je gedeclareerde modellen. Voeg `"vllm/*": {}` toe aan `agents.defaults.models` wanneer je wilt dat OpenClaw het `/models`-eindpunt van die geconfigureerde provider bevraagt en alle geadverteerde vLLM-modellen opneemt.
## 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 loopback-, LAN- of Tailscale-vLLM-eindpunt
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
models: {
providers: {
vllm: {
baseUrl: "http://127.0.0.1:8000/v1",
apiKey: "${VLLM_API_KEY}",
api: "openai-completions",
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,
},
],
},
},
},
}
```
Om deze provider dynamisch te houden zonder elk model handmatig te vermelden, voeg je een providerjokerteken toe aan de zichtbare modelcatalogus:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
agents: {
defaults: {
models: {
"vllm/*": {},
},
},
},
}
```
## Geavanceerde configuratie
vLLM wordt behandeld als een proxy-achtige OpenAI-compatibele `/v1`-backend, niet als een native
OpenAI-eindpunt. Dit betekent:
| Gedrag | Toegepast? |
| ----------------------------------------- | ------------------------------------------- |
| Native OpenAI-aanvraagvorming | Nee |
| `service_tier` | Niet verzonden |
| Responses `store` | Niet verzonden |
| Promptcache-hints | Niet verzonden |
| OpenAI-redeneercompatibele payloadvorming | Niet toegepast |
| Verborgen OpenClaw-toeschrijvingsheaders | Niet geïnjecteerd op aangepaste basis-URL's |
Stel voor Qwen-modellen die via vLLM worden aangeboden
`compat.thinkingFormat: "qwen-chat-template"` in op de geconfigureerde provider-
modelrij wanneer de server Qwen-chat-template-kwargs verwacht. Modellen
die op deze manier zijn geconfigureerd, tonen een binair `/think`-profiel (`off`, `on`), omdat
Qwen-template-denken een aan/uit-aanvraagvlag is, geen OpenAI-achtige inspanningsladder.
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
models: {
providers: {
vllm: {
models: [
{
id: "Qwen/Qwen3-8B",
name: "Qwen3 8B",
reasoning: true,
compat: { thinkingFormat: "qwen-chat-template" },
},
],
},
},
},
}
```
OpenClaw koppelt `/think off` aan:
```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
"chat_template_kwargs": {
"enable_thinking": false,
"preserve_thinking": true
}
}
```
Niet-`off` denkniveaus verzenden `enable_thinking: true`. Als je eindpunt
in plaats daarvan DashScope-achtige vlaggen op topniveau verwacht, gebruik dan
`compat.thinkingFormat: "qwen"` om `enable_thinking` in de root van de aanvraag te verzenden.
vLLM/Nemotron 3 kan chat-template-kwargs gebruiken om te bepalen of redeneren
wordt geretourneerd als verborgen redenering of zichtbare antwoordtekst. Wanneer een OpenClaw-sessie
`vllm/nemotron-3-*` gebruikt met denken uit, verzendt de gebundelde vLLM-Plugin:
```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
"chat_template_kwargs": {
"enable_thinking": false,
"force_nonempty_content": true
}
}
```
Om deze waarden aan te passen, stel je `chat_template_kwargs` in onder de modelparameters.
Als je ook `params.extra_body.chat_template_kwargs` instelt, heeft die waarde
de uiteindelijke voorrang omdat `extra_body` de laatste override voor de aanvraagbody is.
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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 print ruwe JSON/XML zoals `{"name":"read","arguments":...}`
* vLLM retourneert een lege `tool_calls`-array wanneer OpenClaw
`tool_choice: "auto"` verzendt
Sommige Qwen/vLLM-combinaties retourneren alleen gestructureerde tool calls wanneer de
aanvraag `tool_choice: "required"` gebruikt. Forceer voor die modelvermeldingen het
OpenAI-compatibele aanvraagveld met `params.extra_body`:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw models list --provider vllm
```
Je kunt dezelfde override toepassen vanuit de CLI:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 compatibiliteitsworkaround. Hierdoor vereist elke modelbeurt met
tools een tool call, dus gebruik dit alleen voor een specifieke lokale modelvermelding
waar 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 tool calls.
Als je vLLM-server op een niet-standaard host of poort draait, stel dan `baseUrl` in de expliciete providerconfiguratie in:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
models: {
providers: {
vllm: {
baseUrl: "http://192.168.1.50:9000/v1",
apiKey: "${VLLM_API_KEY}",
api: "openai-completions",
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 aanvraagtimeout in:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
models: {
providers: {
vllm: {
baseUrl: "http://192.168.1.50:8000/v1",
apiKey: "${VLLM_API_KEY}",
api: "openai-completions",
timeoutSeconds: 300,
models: [{ id: "your-model-id", name: "Local vLLM Model" }],
},
},
},
}
```
`timeoutSeconds` geldt alleen voor HTTP-aanvragen aan vLLM-modellen, inclusief
verbindingsopbouw, responsheaders, bodystreaming en de totale
guarded-fetch-afbreking. Geef hier de voorkeur aan voordat je
`agents.defaults.timeoutSeconds` verhoogt, dat de volledige agent-run beheert.
Controleer of de vLLM-server draait en toegankelijk is:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 loopback-, LAN- of Tailscale-eindpunten vertrouwt OpenClaw de
exact geconfigureerde `models.providers.vllm.baseUrl`-origin voor bewaakte modelaanvragen.
Metadata-/link-local-origins blijven geblokkeerd zonder expliciete
opt-in. Stel `models.providers.vllm.request.allowPrivateNetwork: true` alleen in
wanneer vLLM-aanvragen een andere private origin moeten bereiken, en stel dit in op `false`
om af te zien van vertrouwen op exacte origin.
Als aanvragen mislukken met authenticatiefouten, 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 authenticatie afdwingt, werkt elke niet-lege waarde voor `VLLM_API_KEY` als opt-in-signaal voor OpenClaw.
Automatische ontdekking vereist dat `VLLM_API_KEY` is ingesteld. Als je `models.providers.vllm` hebt gedefinieerd, gebruikt OpenClaw alleen je gedeclareerde modellen tenzij `agents.defaults.models` `"vllm/*": {}` bevat.
Als een Qwen-model JSON/XML-toolsyntaxis print 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 alleen-tekst-
tool calls retourneert
Meer hulp: [Probleemoplossing](/nl/help/troubleshooting) en [FAQ](/nl/help/faq).
## Gerelateerd
Providers, modelverwijzingen en failover-gedrag kiezen.
Native OpenAI-provider en OpenAI-compatibel routegedrag.
Auth-details en regels voor hergebruik van inloggegevens.
Veelvoorkomende problemen en hoe u ze oplost.