--- read_when: - Vous souhaitez exécuter OpenClaw avec un serveur vLLM local - Vous souhaitez des points de terminaison `/v1` compatibles avec OpenAI pour vos propres modèles summary: Exécuter OpenClaw avec vLLM (serveur local compatible avec OpenAI) title: vLLM x-i18n: generated_at: "2026-07-12T03:02:35Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 98d1044c0a82efb6c9937e961d765d0cfcea8664cbaa043168921b457756512c source_path: providers/vllm.md workflow: 16 --- 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 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 : ```text http://127.0.0.1:8000/v1 ``` Toute valeur non vide convient si votre serveur n’impose pas d’authentification : ```bash export VLLM_API_KEY="vllm-local" ``` Remplacez l’identifiant par celui de l’un de vos modèles vLLM : ```json5 { agents: { defaults: { model: { primary: "vllm/your-model-id" }, }, }, } ``` ```bash openclaw models list --provider vllm ``` Pour une configuration non interactive (CI, scripts), transmettez directement l’URL de base, la clé et le modèle : ```bash 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 : ```json5 { 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 : ```json5 { agents: { defaults: { models: { "vllm/*": {}, }, }, }, } ``` ## Configuration avancée 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 | 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. ```json5 { models: { providers: { vllm: { models: [ { id: "Qwen/Qwen3-8B", name: "Qwen3 8B", reasoning: true, compat: { thinkingFormat: "qwen-chat-template" }, }, ], }, }, }, } ``` OpenClaw associe `/think off` à : ```json { "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. Pour les modèles `vllm/nemotron-3-*` dont la réflexion est désactivée, le Plugin intégré envoie : ```json { "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. ```json5 { agents: { defaults: { models: { "vllm/nemotron-3-super": { params: { chat_template_kwargs: { enable_thinking: false, force_nonempty_content: true, }, }, }, }, }, }, } ``` 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` : ```json5 { 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 : ```bash 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. 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 : ```json5 { 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 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 : ```json5 { 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. Vérifiez que le serveur vLLM est en cours d’exécution et accessible : ```bash 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. 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. 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/*": {}`. 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](/fr/help/troubleshooting) et [FAQ](/fr/help/faq). ## Rubriques connexes Choix des fournisseurs, des références de modèles et du comportement de basculement. Fournisseur OpenAI natif et comportement des routes compatibles avec OpenAI. Détails de l’authentification et règles de réutilisation des identifiants. Problèmes courants et méthodes pour les résoudre.