vLLM

vLLM expose des modèles open source (ainsi que certains modèles personnalisés) via une API HTTP compatible avec OpenAI. OpenClaw se connecte à l’aide de l’API openai-completions et peut détecter automatiquement les modèles lorsque vous activez cette fonctionnalité avec VLLM_API_KEY.

Propriété	Valeur
Identifiant du fournisseur	`vllm`
API	`openai-completions` (compatible avec OpenAI)
Authentification	Variable d’environnement `VLLM_API_KEY`
URL de base par défaut	`http://127.0.0.1:8000/v1`
Utilisation en streaming	Prise en charge (`stream_options.include_usage`)

Bien démarrer

Démarrer vLLM avec un serveur compatible avec OpenAI

Votre URL de base doit exposer les points de terminaison /v1 (/v1/models, /v1/chat/completions). vLLM s’exécute généralement à l’adresse suivante :

http://127.0.0.1:8000/v1

Définir la variable d’environnement de la clé API

Toute valeur non vide convient si votre serveur n’impose pas d’authentification :

export VLLM_API_KEY="vllm-local"

Sélectionner un modèle

Remplacez l’identifiant par celui de l’un de vos modèles vLLM :

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

Vérifier que le modèle est disponible

openclaw models list --provider vllm

Pour une configuration non interactive (CI, scripts), transmettez directement l’URL de base, la clé et le modèle :

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"

Détection des modèles (fournisseur implicite)

Lorsque VLLM_API_KEY est défini (ou qu’un profil d’authentification existe) et que models.providers.vllm n’est pas défini, OpenClaw interroge GET http://127.0.0.1:8000/v1/models et convertit les identifiants renvoyés en entrées de modèle.

Si vous définissez explicitement models.providers.vllm, OpenClaw utilise uniquement les modèles que vous avez déclarés. Ajoutez "vllm/*": {} à agents.defaults.models pour qu’OpenClaw interroge également le point de terminaison /models de ce fournisseur configuré et inclue tous les modèles vLLM annoncés.

Configuration explicite

Utilisez une configuration explicite lorsque vLLM s’exécute sur un autre hôte ou port, lorsque vous souhaitez fixer contextWindow/maxTokens, lorsque votre serveur exige une véritable clé API ou lorsque vous vous connectez à un point de terminaison de boucle locale, du réseau local ou Tailscale de confiance :

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

Pour conserver un fournisseur dynamique sans répertorier chaque modèle, ajoutez un caractère générique au catalogue des modèles visibles :

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

Configuration avancée

Comportement de type proxy

vLLM est traité comme un service principal /v1 compatible avec OpenAI et fonctionnant comme un proxy, et non comme un point de terminaison OpenAI natif :

Comportement	Appliqué ?
Mise en forme native des requêtes OpenAI	Non
`service_tier`	Non envoyé
`store` des réponses	Non envoyé
Indications de cache des prompts	Non envoyées
Mise en forme de la charge utile compatible avec le raisonnement OpenAI	Non appliquée
En-têtes d’attribution OpenClaw masqués	Non injectés pour les URL de base personnalisées

Contrôles de réflexion de Qwen

Pour les modèles Qwen, définissez compat.thinkingFormat: "qwen-chat-template" sur la ligne du modèle lorsque le serveur attend les arguments nommés du modèle de discussion Qwen. Ces modèles exposent un profil /think binaire (off, on), car la réflexion du modèle de discussion Qwen est une option activée ou désactivée, et non une échelle d’effort de type OpenAI.

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

OpenClaw associe /think off à :

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

Les niveaux de réflexion autres que off envoient enable_thinking: true. Si votre point de terminaison attend plutôt des indicateurs de premier niveau de type DashScope, utilisez compat.thinkingFormat: "qwen" pour envoyer enable_thinking à la racine de la requête.

Contrôles de réflexion de Nemotron 3

Pour les modèles vllm/nemotron-3-* dont la réflexion est désactivée, le Plugin intégré envoie :

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

Pour personnaliser ces valeurs, définissez chat_template_kwargs dans les paramètres du modèle. Si vous définissez également params.extra_body.chat_template_kwargs, cette valeur prévaut, car extra_body constitue la dernière substitution du corps de la requête.

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

Les appels d’outils Qwen apparaissent sous forme de texte

Vérifiez d’abord que vLLM a été démarré avec l’analyseur d’appels d’outils et le modèle de discussion appropriés au modèle. La documentation de vLLM indique hermes pour les modèles Qwen2.5 et qwen3_xml pour les modèles Qwen3-Coder.Symptômes : les Skills/outils ne s’exécutent jamais, l’assistant affiche du JSON/XML brut tel que {"name":"read","arguments":...}, ou vLLM renvoie un tableau tool_calls vide lorsqu’OpenClaw envoie tool_choice: "auto".Certaines combinaisons Qwen/vLLM renvoient des appels d’outils structurés uniquement lorsque la requête utilise tool_choice: "required". Forcez cette valeur pour chaque modèle avec params.extra_body :

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

Remplacez l’identifiant du modèle par l’identifiant exact fourni par openclaw models list --provider vllm, ou appliquez la même substitution depuis la CLI :

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

Il s’agit d’une solution de contournement facultative : elle force chaque tour comportant des outils à effectuer un appel d’outil. Utilisez-la donc uniquement pour une entrée de modèle dédiée lorsque ce comportement est acceptable. Ne la définissez pas comme valeur globale par défaut pour tous les modèles vLLM et ne l’associez pas à un proxy qui convertit arbitrairement le texte de l’assistant en appels d’outils exécutables.

URL de base personnalisée

Si votre serveur vLLM s’exécute sur un hôte ou un port différent de celui par défaut, définissez baseUrl dans la configuration explicite du fournisseur :

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

Résolution des problèmes

Première réponse lente ou expiration du délai du serveur distant

Pour les grands modèles locaux, les hôtes distants du réseau local ou les liaisons de réseau Tailscale, définissez un délai d’expiration des requêtes propre au fournisseur :

{
  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 s’applique uniquement aux requêtes HTTP des modèles vLLM : établissement de la connexion, en-têtes de réponse, diffusion en streaming du corps et abandon total de la récupération protégée. Il relève également le plafond du mécanisme de surveillance de l’inactivité et du streaming du LLM au-delà de la valeur implicite par défaut d’environ 120 secondes pour ce fournisseur. Préférez cette option à l’augmentation de agents.defaults.timeoutSeconds, qui contrôle l’intégralité de l’exécution de l’agent.

Serveur inaccessible

Vérifiez que le serveur vLLM est en cours d’exécution et accessible :

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

Si une erreur de connexion s’affiche, vérifiez l’hôte, le port et que vLLM a été démarré en mode serveur compatible avec OpenAI. OpenClaw fait confiance à l’origine exacte configurée dans models.providers.vllm.baseUrl pour les requêtes de modèle protégées sur les points de terminaison de boucle locale, du réseau local et Tailscale. Les origines de métadonnées ou locales au lien restent bloquées sans activation explicite. Définissez models.providers.vllm.request.allowPrivateNetwork: true uniquement lorsque les requêtes vLLM doivent atteindre une autre origine privée, ou false pour désactiver la confiance accordée à l’origine exacte.

Erreurs d’authentification lors des requêtes

Si les requêtes échouent avec des erreurs d’authentification, définissez une véritable valeur VLLM_API_KEY correspondant à la configuration de votre serveur, ou configurez explicitement le fournisseur dans models.providers.vllm.

Si votre serveur vLLM n’impose pas d’authentification, toute valeur non vide de VLLM_API_KEY sert de signal d’activation pour OpenClaw.

Aucun modèle détecté

La détection automatique exige que VLLM_API_KEY soit défini. Si vous avez défini models.providers.vllm, OpenClaw utilise uniquement les modèles que vous avez déclarés, sauf si agents.defaults.models inclut "vllm/*": {}.

Les outils s’affichent sous forme de texte brut

Si un modèle Qwen affiche la syntaxe JSON/XML des outils au lieu d’exécuter une Skill :

Démarrez vLLM avec l’analyseur et le modèle appropriés à ce modèle.
Vérifiez l’identifiant exact du modèle avec openclaw models list --provider vllm.
Ajoutez une substitution params.extra_body.tool_choice: "required" dédiée à ce modèle uniquement si tool_choice: "auto" renvoie toujours des appels d’outils vides ou sous forme de texte uniquement.

Aide supplémentaire : Résolution des problèmes et FAQ.

Rubriques connexes

Sélection des modèles

Choix des fournisseurs, des références de modèles et du comportement de basculement.

OpenAI

Fournisseur OpenAI natif et comportement des routes compatibles avec OpenAI.

OAuth et authentification

Détails de l’authentification et règles de réutilisation des identifiants.

Résolution des problèmes

Problèmes courants et méthodes pour les résoudre.

Overview

Concepts and configuration

Providers

Bien démarrer

Détection des modèles (fournisseur implicite)

Configuration explicite

Configuration avancée

Résolution des problèmes

Rubriques connexes

Sélection des modèles

OpenAI

OAuth et authentification

Résolution des problèmes

​Bien démarrer

​Détection des modèles (fournisseur implicite)

​Configuration explicite

​Configuration avancée

​Résolution des problèmes

​Rubriques connexes

Sélection des modèles

OpenAI

OAuth et authentification

Résolution des problèmes

Bien démarrer

Détection des modèles (fournisseur implicite)

Configuration explicite

Configuration avancée

Résolution des problèmes

Rubriques connexes