Pular para o conteúdo principal

​
vLLM

O vLLM pode servir modelos open-source (e alguns modelos personalizados) por meio de uma API HTTP compatível com OpenAI. O OpenClaw se conecta ao vLLM usando a API openai-completions. O OpenClaw também pode descobrir automaticamente os modelos disponíveis no vLLM quando você optar por isso com VLLM_API_KEY (qualquer valor funciona se o seu servidor não exigir auth) e você não definir uma entrada explícita models.providers.vllm.
PropriedadeValor
ID do provedorvllm
APIopenai-completions (compatível com OpenAI)
Authvariável de ambiente VLLM_API_KEY
Base URL padrãohttp://127.0.0.1:8000/v1

​
Primeiros passos

1

Inicie o vLLM com um servidor compatível com OpenAI

Sua base URL deve expor endpoints /v1 (por exemplo, /v1/models, /v1/chat/completions). O vLLM costuma ser executado em:
http://127.0.0.1:8000/v1
2

Defina a variável de ambiente da chave de API

Qualquer valor funciona se o seu servidor não exigir auth:
export VLLM_API_KEY="vllm-local"
3

Selecione um modelo

Substitua por um dos IDs de modelo do seu vLLM:
{
  agents: {
    defaults: {
      model: { primary: "vllm/your-model-id" },
    },
  },
}
4

Verifique se o modelo está disponível

openclaw models list --provider vllm

​
Descoberta de modelos (provedor implícito)

Quando VLLM_API_KEY está definido (ou existe um perfil de auth) e você não define models.providers.vllm, o OpenClaw consulta: 
GET http://127.0.0.1:8000/v1/models
e converte os IDs retornados em entradas de modelo.
Se você definir models.providers.vllm explicitamente, a descoberta automática será ignorada e você precisará definir os modelos manualmente.

​
Configuração explícita (modelos manuais)

Use configuração explícita quando:
  • o vLLM estiver em execução em outro host ou porta
  • você quiser fixar valores de contextWindow ou maxTokens
  • o seu servidor exigir uma chave de API real (ou você quiser controlar cabeçalhos)
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "your-model-id",
            name: "Modelo local do vLLM",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

​
Observações avançadas

O vLLM é tratado como um backend /v1 compatível com OpenAI no estilo proxy, não como um endpoint nativo da OpenAI. Isso significa:
ComportamentoAplicado?
Formatação nativa de solicitação da OpenAINão
service_tierNão é enviado
Responses storeNão é enviado
Dicas de cache de promptNão são enviadas
Formatação de payload de compatibilidade de reasoning da OpenAINão é aplicada
Cabeçalhos ocultos de atribuição do OpenClawNão são injetados em base URLs personalizadas
Se o seu servidor vLLM estiver em execução em um host ou porta fora do padrão, defina baseUrl na configuração explícita do provedor:
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://192.168.1.50:9000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "my-custom-model",
            name: "Modelo remoto do vLLM",
            reasoning: false,
            input: ["text"],
            contextWindow: 64000,
            maxTokens: 4096,
          },
        ],
      },
    },
  },
}

​
Solução de problemas

Verifique se o servidor vLLM está em execução e acessível:
curl http://127.0.0.1:8000/v1/models
Se você vir um erro de conexão, verifique o host, a porta e se o vLLM foi iniciado no modo de servidor compatível com OpenAI.
Se as solicitações falharem com erros de auth, defina um VLLM_API_KEY real que corresponda à configuração do seu servidor ou configure o provedor explicitamente em models.providers.vllm.
Se o seu servidor vLLM não exigir auth, qualquer valor não vazio para VLLM_API_KEY funciona como sinal de ativação para o OpenClaw.
A descoberta automática exige que VLLM_API_KEY esteja definido e que não exista uma entrada de configuração explícita models.providers.vllm. Se você definiu o provedor manualmente, o OpenClaw ignora a descoberta e usa apenas os modelos declarados por você.
Mais ajuda: Solução de problemas e FAQ.

​
Relacionado

Seleção de modelo

Escolha de provedores, refs de modelo e comportamento de failover.

OpenAI

Provedor nativo da OpenAI e comportamento de rotas compatíveis com OpenAI.

OAuth e auth

Detalhes de auth e regras de reutilização de credenciais.

Solução de problemas

Problemas comuns e como resolvê-los.