vLLM - OpenClaw

vLLM може обслуговувати open-source (і деякі користувацькі) моделі через OpenAI-сумісний HTTP API. OpenClaw підключається до vLLM за допомогою API openai-completions. OpenClaw також може автоматично виявляти доступні моделі з vLLM, коли ви вмикаєте це через VLLM_API_KEY (будь-яке значення працює, якщо ваш сервер не вимагає автентифікації). Використовуйте vllm/* в agents.defaults.models, щоб зберегти виявлення динамічним, коли ви також налаштовуєте користувацький базовий URL vLLM. OpenClaw розглядає vllm як локального OpenAI-сумісного провайдера, що підтримує потоковий облік використання, тому лічильники токенів статусу/контексту можуть оновлюватися з відповідей stream_options.include_usage.

Властивість	Значення
ID провайдера	`vllm`
API	`openai-completions` (OpenAI-сумісний)
Автентифікація	змінна середовища `VLLM_API_KEY`
Базовий URL за замовчуванням	`http://127.0.0.1:8000/v1`

Початок роботи

Start vLLM with an OpenAI-compatible server

Ваш базовий URL має відкривати endpoints /v1 (наприклад, /v1/models, /v1/chat/completions). vLLM зазвичай працює на:

http://127.0.0.1:8000/v1

Set the API key environment variable

Будь-яке значення працює, якщо ваш сервер не вимагає автентифікації:

export VLLM_API_KEY="vllm-local"

Select a model

Замініть на один із ваших ID моделей vLLM:

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

Verify the model is available

openclaw models list --provider vllm

Виявлення моделей (неявний провайдер)

Коли VLLM_API_KEY задано (або існує профіль автентифікації), і ви не визначаєте models.providers.vllm, OpenClaw надсилає запит до:

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

і перетворює повернуті ID на записи моделей.

Якщо ви явно задаєте models.providers.vllm, OpenClaw за замовчуванням використовує оголошені вами моделі. Додайте "vllm/*": {} до agents.defaults.models, коли хочете, щоб OpenClaw опитував endpoint /models цього налаштованого провайдера й включав усі оголошені моделі vLLM.

Явна конфігурація (моделі вручну)

Використовуйте явну конфігурацію, коли:

vLLM працює на іншому хості або порту
Ви хочете зафіксувати значення contextWindow або maxTokens
Ваш сервер потребує справжнього API-ключа (або ви хочете керувати заголовками)
Ви підключаєтеся до довіреного loopback, LAN або Tailscale endpoint vLLM

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

Щоб зберегти цього провайдера динамічним без ручного переліку кожної моделі, додайте wildcard провайдера до видимого каталогу моделей:

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

Розширена конфігурація

Proxy-style behavior

vLLM розглядається як proxy-style OpenAI-сумісний backend /v1, а не як нативний endpoint OpenAI. Це означає:

Поведінка	Застосовується?
Нативне формування запитів OpenAI	Ні
`service_tier`	Не надсилається
Responses `store`	Не надсилається
Підказки prompt-cache	Не надсилаються
Формування payload для OpenAI reasoning-compat	Не застосовується
Приховані заголовки атрибуції OpenClaw	Не додаються для користувацьких базових URL

Qwen thinking controls

Для моделей Qwen, що обслуговуються через vLLM, задайте compat.thinkingFormat: "qwen-chat-template" у рядку налаштованої моделі провайдера, коли сервер очікує kwargs chat-template Qwen. Моделі, налаштовані так, відкривають бінарний профіль /think (off, on), тому що thinking у шаблоні Qwen є прапорцем запиту увімкнено/вимкнено, а не сходинками effort у стилі OpenAI.

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

OpenClaw зіставляє /think off з:

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

Рівні thinking, відмінні від off, надсилають enable_thinking: true. Якщо ваш endpoint натомість очікує прапорці верхнього рівня у стилі DashScope, використовуйте compat.thinkingFormat: "qwen", щоб надсилати enable_thinking у корені запиту.

Nemotron 3 thinking controls

vLLM/Nemotron 3 може використовувати kwargs chat-template, щоб керувати тим, чи reasoning повертається як прихований reasoning або як видимий текст відповіді. Коли сесія OpenClaw використовує vllm/nemotron-3-* з вимкненим thinking, вбудований Plugin vLLM надсилає:

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

Щоб налаштувати ці значення, задайте chat_template_kwargs у параметрах моделі. Якщо ви також задаєте params.extra_body.chat_template_kwargs, це значення має остаточний пріоритет, тому що extra_body є останнім override тіла запиту.

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

Qwen tool calls appear as text

Спершу переконайтеся, що vLLM запущено з правильним parser tool-call і chat template для моделі. Наприклад, vLLM документує hermes для моделей Qwen2.5 і qwen3_xml для моделей Qwen3-Coder.Симптоми:

Skills або інструменти ніколи не запускаються
асистент друкує сирий JSON/XML, як-от {"name":"read","arguments":...}
vLLM повертає порожній масив tool_calls, коли OpenClaw надсилає tool_choice: "auto"

Деякі комбінації Qwen/vLLM повертають структуровані виклики інструментів лише тоді, коли запит використовує tool_choice: "required". Для таких записів моделей примусово задайте OpenAI-сумісне поле запиту через params.extra_body:

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

Замініть Qwen-Qwen2.5-Coder-32B-Instruct на точний id, повернутий командою:

openclaw models list --provider vllm

Ви можете застосувати той самий override з CLI:

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

Це opt-in workaround для сумісності. Він змушує кожен хід моделі з інструментами вимагати виклик інструмента, тому використовуйте його лише для окремого запису локальної моделі, де така поведінка прийнятна. Не використовуйте його як глобальне значення за замовчуванням для всіх моделей vLLM і не використовуйте proxy, який сліпо перетворює довільний текст асистента на виконувані виклики інструментів.

Custom base URL

Якщо ваш сервер vLLM працює на нестандартному хості або порту, задайте baseUrl у явній конфігурації провайдера:

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

Усунення несправностей

Slow first response or remote server timeout

Для великих локальних моделей, віддалених хостів LAN або посилань tailnet задайте timeout запиту в області провайдера:

{
  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 застосовується лише до HTTP-запитів моделей vLLM, включно з налаштуванням з’єднання, заголовками відповіді, потоковою передачею тіла та загальним перериванням guarded-fetch. Надавайте перевагу цьому перед збільшенням agents.defaults.timeoutSeconds, який керує всім запуском агента.

Server not reachable

Перевірте, що сервер vLLM запущений і доступний:

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

Якщо бачите помилку з’єднання, перевірте хост, порт і те, що vLLM запущено в OpenAI-сумісному серверному режимі. Для явних loopback, LAN або Tailscale endpoints OpenClaw довіряє точному origin налаштованого models.providers.vllm.baseUrl для guarded-запитів моделей. Metadata/link-local origins залишаються заблокованими без явного opt-in. Задавайте models.providers.vllm.request.allowPrivateNetwork: true лише коли запити vLLM мають досягати іншого приватного origin, і задавайте false, щоб відмовитися від довіри до точного origin.

Auth errors on requests

Якщо запити завершуються помилками автентифікації, задайте справжній VLLM_API_KEY, який відповідає конфігурації вашого сервера, або явно налаштуйте провайдера в models.providers.vllm.

Якщо ваш сервер vLLM не вимагає автентифікації, будь-яке непорожнє значення VLLM_API_KEY працює як opt-in сигнал для OpenClaw.

No models discovered

Автоматичне виявлення вимагає, щоб VLLM_API_KEY було задано. Якщо ви визначили models.providers.vllm, OpenClaw використовує лише оголошені вами моделі, якщо agents.defaults.models не містить "vllm/*": {}.

Tools render as raw text

Якщо модель Qwen друкує синтаксис інструментів JSON/XML замість виконання Skills, перегляньте настанови щодо Qwen у розділі розширеної конфігурації вище. Звичайне виправлення:

запустіть vLLM з правильним parser/template для цієї моделі
підтвердьте точний id моделі за допомогою openclaw models list --provider vllm
додайте окремий override params.extra_body.tool_choice: "required" для конкретної моделі лише якщо tool_choice: "auto" усе ще повертає порожні або лише текстові виклики інструментів

Більше допомоги: Усунення несправностей і FAQ.

Пов’язане

Вибір моделі

Вибір провайдерів, посилань на моделі та поведінки резервного перемикання.

OpenAI

Власний провайдер OpenAI і поведінка маршруту, сумісного з OpenAI.

OAuth і автентифікація

Відомості про автентифікацію та правила повторного використання облікових даних.

Усунення несправностей

Поширені проблеми та способи їх вирішення.

​Початок роботи

​Виявлення моделей (неявний провайдер)

​Явна конфігурація (моделі вручну)

​Розширена конфігурація

​Усунення несправностей

​Пов’язане

Вибір моделі

OpenAI

OAuth і автентифікація

Усунення несправностей

Початок роботи

Виявлення моделей (неявний провайдер)

Явна конфігурація (моделі вручну)

Розширена конфігурація

Усунення несправностей

Пов’язане