vLLM

vLLM espone modelli open source (e alcuni modelli personalizzati) tramite un’API HTTP compatibile con OpenAI. OpenClaw si connette usando l’API openai-completions e può rilevare automaticamente i modelli quando si abilita questa funzionalità con VLLM_API_KEY.

Proprietà	Valore
ID provider	`vllm`
API	`openai-completions` (compatibile con OpenAI)
Autenticazione	Variabile di ambiente `VLLM_API_KEY`
URL di base predefinito	`http://127.0.0.1:8000/v1`
Utilizzo in streaming	Supportato (`stream_options.include_usage`)

Per iniziare

Avviare vLLM con un server compatibile con OpenAI

L’URL di base deve esporre endpoint /v1 (/v1/models, /v1/chat/completions). In genere vLLM viene eseguito su:

http://127.0.0.1:8000/v1

Impostare la variabile di ambiente della chiave API

Se il server non impone l’autenticazione, è sufficiente qualsiasi valore non vuoto:

export VLLM_API_KEY="vllm-local"

Selezionare un modello

Sostituire il valore con uno degli ID modello di vLLM:

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

Verificare che il modello sia disponibile

openclaw models list --provider vllm

Per la configurazione non interattiva (CI, scripting), passare direttamente l’URL di base, la chiave e il modello:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice vllm \
  --custom-base-url "http://127.0.0.1:8000/v1" \
  --custom-api-key "vllm-local" \
  --custom-model-id "your-model-id"

Rilevamento dei modelli (provider implicito)

Quando VLLM_API_KEY è impostata (o esiste un profilo di autenticazione) e models.providers.vllm non è definito, OpenClaw interroga GET http://127.0.0.1:8000/v1/models e converte gli ID restituiti in voci di modello.

Se si imposta esplicitamente models.providers.vllm, OpenClaw usa soltanto i modelli dichiarati. Aggiungere "vllm/*": {} a agents.defaults.models affinché OpenClaw interroghi anche l’endpoint /models del provider configurato e includa tutti i modelli vLLM pubblicizzati.

Configurazione esplicita

Eseguire una configurazione esplicita quando vLLM è in esecuzione su un host o una porta diversi, si desidera fissare contextWindow/maxTokens, il server richiede una vera chiave API oppure ci si connette a un endpoint 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 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 il provider senza elencare ogni modello, aggiungere un carattere jolly al catalogo dei modelli visibili:

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

Configurazione avanzata

Comportamento in stile proxy

vLLM viene trattato come un backend /v1 in stile proxy compatibile con OpenAI, non come un endpoint OpenAI nativo:

Comportamento	Applicato?
Formattazione nativa delle richieste OpenAI	No
`service_tier`	Non inviato
`store` delle Responses	Non inviato
Indicazioni per la cache dei prompt	Non inviate
Formattazione del payload per compatibilità con il ragionamento OpenAI	Non applicata
Intestazioni nascoste di attribuzione OpenClaw	Non inserite negli URL di base personalizzati

Controlli del ragionamento di Qwen

Per i modelli Qwen, impostare compat.thinkingFormat: "qwen-chat-template" nella riga del modello quando il server si aspetta gli argomenti del modello di chat Qwen. Questi modelli espongono un profilo binario /think (off, on) perché il ragionamento del modello di chat Qwen è un’opzione attivata/disattivata, non una scala di intensità in stile OpenAI.

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

OpenClaw associa /think off a:

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

I livelli di ragionamento diversi da off inviano enable_thinking: true. Se l’endpoint si aspetta invece opzioni di primo livello in stile DashScope, usare compat.thinkingFormat: "qwen" per inviare enable_thinking nella radice della richiesta.

Controlli del ragionamento di Nemotron 3

Per i modelli vllm/nemotron-3-* con il ragionamento disattivato, il Plugin incluso invia:

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

Per personalizzare questi valori, impostare chat_template_kwargs nei parametri del modello. Se si imposta anche params.extra_body.chat_template_kwargs, tale valore ha la precedenza perché extra_body è l’ultima sostituzione applicata al 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 di Qwen vengono visualizzate come testo

Verificare innanzitutto che vLLM sia stato avviato con il parser delle chiamate agli strumenti e il modello di chat corretti per il modello. La documentazione di vLLM indica hermes per i modelli Qwen2.5 e qwen3_xml per i modelli Qwen3-Coder.Sintomi: le Skills/gli strumenti non vengono mai eseguiti, l’assistente stampa JSON/XML non elaborato come {"name":"read","arguments":...} oppure vLLM restituisce un array tool_calls vuoto quando OpenClaw invia tool_choice: "auto".Alcune combinazioni di Qwen/vLLM restituiscono chiamate agli strumenti strutturate solo quando la richiesta usa tool_choice: "required". Forzarne l’uso per singolo modello tramite params.extra_body:

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

Sostituire l’ID del modello con l’ID esatto restituito da openclaw models list --provider vllm, oppure applicare la stessa sostituzione 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 alternativa facoltativa: forza ogni turno che include strumenti a effettuare una chiamata a uno strumento, quindi va usata solo per una voce di modello dedicata in cui tale comportamento sia accettabile. Non impostarla come valore predefinito globale per tutti i modelli vLLM e non abbinarla a un proxy che converte testo arbitrario dell’assistente in chiamate eseguibili agli strumenti.

URL di base personalizzato

Se il server vLLM è in esecuzione su un host o una porta non predefiniti, impostare 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 di grandi dimensioni, host LAN remoti o collegamenti tailnet, impostare un timeout delle richieste specifico del 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 soltanto alle richieste HTTP dei modelli vLLM: configurazione della connessione, intestazioni della risposta, streaming del corpo e interruzione complessiva del recupero protetto. Aumenta inoltre il limite del watchdog di inattività/streaming dell’LLM oltre il valore predefinito implicito di circa 120 secondi per questo provider. È preferibile usare questa opzione anziché aumentare agents.defaults.timeoutSeconds, che controlla l’intera esecuzione dell’agente.

Server non raggiungibile

Verificare che il server vLLM sia in esecuzione e accessibile:

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

Se viene visualizzato un errore di connessione, verificare l’host, la porta e che vLLM sia stato avviato in modalità server compatibile con OpenAI. OpenClaw considera attendibile l’origine esatta configurata in models.providers.vllm.baseUrl per le richieste protette ai modelli su endpoint loopback, LAN e Tailscale. Le origini di metadati/link-local rimangono bloccate senza un’abilitazione esplicita. Impostare models.providers.vllm.request.allowPrivateNetwork: true solo quando le richieste vLLM devono raggiungere un’altra origine privata, oppure false per disattivare l’attendibilità dell’origine esatta.

Errori di autenticazione nelle richieste

Se le richieste non riescono a causa di errori di autenticazione, impostare una vera VLLM_API_KEY che corrisponda alla configurazione del server oppure configurare esplicitamente il provider in models.providers.vllm.

Se il server vLLM non impone l’autenticazione, qualsiasi valore non vuoto di VLLM_API_KEY funziona come segnale di abilitazione per OpenClaw.

Nessun modello rilevato

Il rilevamento automatico richiede che VLLM_API_KEY sia impostata. Se è stato definito models.providers.vllm, OpenClaw usa soltanto i modelli dichiarati, a meno che agents.defaults.models non includa "vllm/*": {}.

Gli strumenti vengono visualizzati come testo non elaborato

Se un modello Qwen stampa la sintassi JSON/XML degli strumenti invece di eseguire una Skill:

Avviare vLLM con il parser/modello corretto per quel modello.
Verificare l’ID esatto del modello con openclaw models list --provider vllm.
Aggiungere una sostituzione dedicata per modello params.extra_body.tool_choice: "required" solo se tool_choice: "auto" continua a restituire chiamate agli strumenti vuote o composte esclusivamente da testo.

Ulteriore assistenza: Risoluzione dei problemi e Domande frequenti.

Contenuti 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 sull’autenticazione e regole per il riutilizzo delle credenziali.

Risoluzione dei problemi

Problemi comuni e relative soluzioni.

Overview

Concepts and configuration

Providers

Per iniziare

Rilevamento dei modelli (provider implicito)

Configurazione esplicita

Configurazione avanzata

Risoluzione dei problemi

Contenuti correlati

Selezione del modello

OpenAI

OAuth e autenticazione

Risoluzione dei problemi

​Per iniziare

​Rilevamento dei modelli (provider implicito)

​Configurazione esplicita

​Configurazione avanzata

​Risoluzione dei problemi

​Contenuti correlati

Selezione del modello

OpenAI

OAuth e autenticazione

Risoluzione dei problemi

Per iniziare

Rilevamento dei modelli (provider implicito)

Configurazione esplicita

Configurazione avanzata

Risoluzione dei problemi

Contenuti correlati