vLLM - OpenClaw

vLLM può servire modelli open-source (e alcuni personalizzati) tramite un’API HTTP compatibile con OpenAI. OpenClaw si connette a vLLM usando l’API openai-completions. OpenClaw può anche scoprire automaticamente i modelli disponibili da vLLM quando acconsenti con VLLM_API_KEY (qualsiasi valore funziona se il tuo server non applica l’autenticazione). Usa vllm/* in agents.defaults.models per mantenere dinamica la scoperta quando configuri anche un URL di base vLLM personalizzato. OpenClaw tratta vllm come un provider locale compatibile con OpenAI che supporta la contabilizzazione dell’uso in streaming, quindi i conteggi dei token di stato/contesto possono aggiornarsi dalle risposte stream_options.include_usage.

Proprietà	Valore
ID provider	`vllm`
API	`openai-completions` (compatibile con OpenAI)
Autenticazione	variabile d’ambiente `VLLM_API_KEY`
URL di base predefinito	`http://127.0.0.1:8000/v1`

Per iniziare

Avvia vLLM con un server compatibile con OpenAI

Il tuo URL di base deve esporre endpoint /v1 (ad esempio /v1/models, /v1/chat/completions). vLLM di solito viene eseguito su:

http://127.0.0.1:8000/v1

Imposta la variabile d'ambiente della chiave API

Qualsiasi valore funziona se il tuo server non applica l’autenticazione:

export VLLM_API_KEY="vllm-local"

Seleziona un modello

Sostituisci con uno degli ID modello vLLM:

{
  agents: {
    defaults: {
      model: { primary: "vllm/your-model-id" },
    },
  },
}

Verifica che il modello sia disponibile

openclaw models list --provider vllm

Scoperta dei modelli (provider implicito)

Quando VLLM_API_KEY è impostato (o esiste un profilo di autenticazione) e non definisci models.providers.vllm, OpenClaw interroga:

GET http://127.0.0.1:8000/v1/models

e converte gli ID restituiti in voci di modello.

Se imposti esplicitamente models.providers.vllm, OpenClaw usa per impostazione predefinita i modelli dichiarati. Aggiungi "vllm/*": {} a agents.defaults.models quando vuoi che OpenClaw interroghi l’endpoint /models di quel provider configurato e includa tutti i modelli vLLM pubblicizzati.

Configurazione esplicita (modelli manuali)

Usa la configurazione esplicita quando:

vLLM viene eseguito su un host o una porta diversi
Vuoi fissare i valori contextWindow o maxTokens
Il tuo server richiede una chiave API reale (o vuoi controllare gli header)
Ti connetti a un endpoint vLLM loopback, LAN o Tailscale attendibile

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

Per mantenere dinamico questo provider senza elencare manualmente ogni modello, aggiungi un carattere jolly del provider al catalogo dei modelli visibile:

{
  agents: {
    defaults: {
      models: {
        "vllm/*": {},
      },
    },
  },
}

Configurazione avanzata

Comportamento in stile proxy

vLLM viene trattato come backend /v1 in stile proxy compatibile con OpenAI, non come endpoint OpenAI nativo. Ciò significa:

Comportamento	Applicato?
Modellazione delle richieste OpenAI native	No
`service_tier`	Non inviato
Responses `store`	Non inviato
Suggerimenti per la cache dei prompt	Non inviati
Modellazione del payload di compatibilità reasoning OpenAI	Non applicata
Header di attribuzione OpenClaw nascosti	Non iniettati su URL di base personalizzati

Controlli di thinking Qwen

Per i modelli Qwen serviti tramite vLLM, imposta compat.thinkingFormat: "qwen-chat-template" sulla riga del modello del provider configurato quando il server si aspetta kwargs del template chat Qwen. I modelli configurati in questo modo espongono un profilo /think binario (off, on) perché il thinking del template Qwen è un flag di richiesta on/off, non una scala di effort in stile OpenAI.

{
  models: {
    providers: {
      vllm: {
        models: [
          {
            id: "Qwen/Qwen3-8B",
            name: "Qwen3 8B",
            reasoning: true,
            compat: { thinkingFormat: "qwen-chat-template" },
          },
        ],
      },
    },
  },
}

OpenClaw mappa /think off a:

{
  "chat_template_kwargs": {
    "enable_thinking": false,
    "preserve_thinking": true
  }
}

I livelli di thinking diversi da off inviano enable_thinking: true. Se il tuo endpoint si aspetta invece flag di primo livello in stile DashScope, usa compat.thinkingFormat: "qwen" per inviare enable_thinking alla radice della richiesta.

Controlli di thinking Nemotron 3

vLLM/Nemotron 3 può usare kwargs del template chat per controllare se il reasoning viene restituito come reasoning nascosto o testo di risposta visibile. Quando una sessione OpenClaw usa vllm/nemotron-3-* con thinking disattivato, il Plugin vLLM in bundle invia:

{
  "chat_template_kwargs": {
    "enable_thinking": false,
    "force_nonempty_content": true
  }
}

Per personalizzare questi valori, imposta chat_template_kwargs nei parametri del modello. Se imposti anche params.extra_body.chat_template_kwargs, quel valore ha precedenza finale perché extra_body è l’ultimo override del corpo della richiesta.

{
  agents: {
    defaults: {
      models: {
        "vllm/nemotron-3-super": {
          params: {
            chat_template_kwargs: {
              enable_thinking: false,
              force_nonempty_content: true,
            },
          },
        },
      },
    },
  },
}

Le chiamate agli strumenti Qwen appaiono come testo

Per prima cosa assicurati che vLLM sia stato avviato con il parser per le chiamate agli strumenti e il template chat corretti per il modello. Ad esempio, vLLM documenta hermes per i modelli Qwen2.5 e qwen3_xml per i modelli Qwen3-Coder.Sintomi:

Skills o strumenti non vengono mai eseguiti
l’assistente stampa JSON/XML grezzo come {"name":"read","arguments":...}
vLLM restituisce un array tool_calls vuoto quando OpenClaw invia tool_choice: "auto"

Alcune combinazioni Qwen/vLLM restituiscono chiamate agli strumenti strutturate solo quando la richiesta usa tool_choice: "required". Per quelle voci di modello, forza il campo della richiesta compatibile con OpenAI con params.extra_body:

{
  agents: {
    defaults: {
      models: {
        "vllm/Qwen-Qwen2.5-Coder-32B-Instruct": {
          params: {
            extra_body: {
              tool_choice: "required",
            },
          },
        },
      },
    },
  },
}

Sostituisci Qwen-Qwen2.5-Coder-32B-Instruct con l’ID esatto restituito da:

openclaw models list --provider vllm

Puoi applicare lo stesso override dalla CLI:

openclaw config set agents.defaults.models '{"vllm/Qwen-Qwen2.5-Coder-32B-Instruct":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge

Questa è una soluzione di compatibilità opt-in. Fa sì che ogni turno del modello con strumenti richieda una chiamata a uno strumento, quindi usala solo per una voce di modello locale dedicata in cui quel comportamento è accettabile. Non usarla come default globale per tutti i modelli vLLM e non usare un proxy che converte alla cieca testo arbitrario dell’assistente in chiamate a strumenti eseguibili.

URL di base personalizzato

Se il tuo server vLLM viene eseguito su un host o una porta non predefiniti, imposta baseUrl nella configurazione esplicita del provider:

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

Risoluzione dei problemi

Prima risposta lenta o timeout del server remoto

Per modelli locali grandi, host LAN remoti o collegamenti tailnet, imposta un timeout di richiesta con ambito provider:

{
  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 si applica solo alle richieste HTTP dei modelli vLLM, inclusi configurazione della connessione, header di risposta, streaming del corpo e l’abort totale del guarded-fetch. Preferiscilo prima di aumentare agents.defaults.timeoutSeconds, che controlla l’intera esecuzione dell’agente.

Server non raggiungibile

Controlla che il server vLLM sia in esecuzione e accessibile:

curl http://127.0.0.1:8000/v1/models

Se vedi un errore di connessione, verifica host, porta e che vLLM sia stato avviato con la modalità server compatibile con OpenAI. Per endpoint loopback, LAN o Tailscale espliciti, OpenClaw considera attendibile l’origine esatta models.providers.vllm.baseUrl configurata per le richieste di modello protette. Le origini metadata/link-local restano bloccate senza opt-in esplicito. Imposta models.providers.vllm.request.allowPrivateNetwork: true solo quando le richieste vLLM devono raggiungere un’altra origine privata, e impostalo su false per disattivare l’attendibilità dell’origine esatta.

Errori di autenticazione nelle richieste

Se le richieste falliscono con errori di autenticazione, imposta una VLLM_API_KEY reale che corrisponda alla configurazione del server, oppure configura esplicitamente il provider in models.providers.vllm.

Se il tuo server vLLM non applica l’autenticazione, qualsiasi valore non vuoto per VLLM_API_KEY funziona come segnale opt-in per OpenClaw.

Nessun modello scoperto

La scoperta automatica richiede che VLLM_API_KEY sia impostato. Se hai definito models.providers.vllm, OpenClaw usa solo i modelli dichiarati a meno che agents.defaults.models non includa "vllm/*": {}.

Gli strumenti vengono renderizzati come testo grezzo

Se un modello Qwen stampa sintassi JSON/XML degli strumenti invece di eseguire una skill, controlla la guida Qwen nella Configurazione avanzata sopra. La correzione abituale è:

avviare vLLM con il parser/template corretto per quel modello
confermare l’ID modello esatto con openclaw models list --provider vllm
aggiungere un override dedicato per modello params.extra_body.tool_choice: "required" solo se tool_choice: "auto" restituisce ancora chiamate agli strumenti vuote o solo testuali

Altra assistenza: Risoluzione dei problemi e FAQ.

Correlati

Selezione del modello

Scelta dei provider, dei riferimenti ai modelli e del comportamento di failover.

OpenAI

Provider OpenAI nativo e comportamento delle route compatibili con OpenAI.

OAuth e autenticazione

Dettagli dell’autenticazione e regole di riutilizzo delle credenziali.

Risoluzione dei problemi

Problemi comuni e come risolverli.

​Per iniziare

​Scoperta dei modelli (provider implicito)

​Configurazione esplicita (modelli manuali)

​Configurazione avanzata

​Risoluzione dei problemi

​Correlati

Selezione del modello

OpenAI

OAuth e autenticazione

Risoluzione dei problemi

Per iniziare

Scoperta dei modelli (provider implicito)

Configurazione esplicita (modelli manuali)

Configurazione avanzata

Risoluzione dei problemi

Correlati