vLLM

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

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.

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

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.

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

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.

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.

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.

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/*": {}.

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.