Saltar al contenido principal

​
vLLM

vLLM puede servir modelos de código abierto (y algunos modelos personalizados) mediante una API HTTP compatible con OpenAI. OpenClaw se conecta a vLLM usando la API openai-completions. OpenClaw también puede descubrir automáticamente los modelos disponibles desde vLLM cuando activas esta opción con VLLM_API_KEY (cualquier valor funciona si tu servidor no exige autenticación) y no defines una entrada explícita models.providers.vllm.
PropiedadValor
ID del proveedorvllm
APIopenai-completions (compatible con OpenAI)
AutenticaciónVariable de entorno VLLM_API_KEY
Base URL predeterminadahttp://127.0.0.1:8000/v1

​
Primeros pasos

1

Start vLLM with an OpenAI-compatible server

Tu base URL debe exponer endpoints /v1 (por ejemplo, /v1/models, /v1/chat/completions). vLLM suele ejecutarse en:
http://127.0.0.1:8000/v1
2

Set the API key environment variable

Cualquier valor funciona si tu servidor no exige autenticación:
export VLLM_API_KEY="vllm-local"
3

Select a model

Sustitúyelo por uno de los IDs de modelo de tu vLLM:
{
  agents: {
    defaults: {
      model: { primary: "vllm/your-model-id" },
    },
  },
}
4

Verify the model is available

openclaw models list --provider vllm

​
Descubrimiento de modelos (proveedor implícito)

Cuando VLLM_API_KEY está configurado (o existe un perfil de autenticación) y no defines models.providers.vllm, OpenClaw consulta: 
GET http://127.0.0.1:8000/v1/models
y convierte los IDs devueltos en entradas de modelo.
Si configuras explícitamente models.providers.vllm, se omite el descubrimiento automático y debes definir los modelos manualmente.

​
Configuración explícita (modelos manuales)

Usa configuración explícita cuando:
  • vLLM se ejecuta en otro host o puerto
  • Quieres fijar los valores de contextWindow o maxTokens
  • Tu servidor requiere una clave API real (o quieres controlar los encabezados)
{
  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 vLLM local",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

​
Notas avanzadas

vLLM se trata como un backend /v1 compatible con OpenAI de estilo proxy, no como un endpoint nativo de OpenAI. Esto significa:
Comportamiento¿Se aplica?
Modelado nativo de solicitudes de OpenAINo
service_tierNo se envía
Responses storeNo se envía
Sugerencias de caché de promptNo se envían
Modelado de payload de compatibilidad de razonamiento de OpenAINo se aplica
Encabezados ocultos de atribución de OpenClawNo se inyectan en base URLs personalizadas
Si tu servidor vLLM se ejecuta en un host o puerto no predeterminado, establece baseUrl en la configuración explícita del proveedor:
{
  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 vLLM remoto",
            reasoning: false,
            input: ["text"],
            contextWindow: 64000,
            maxTokens: 4096,
          },
        ],
      },
    },
  },
}

​
Solución de problemas

Comprueba que el servidor vLLM esté en ejecución y sea accesible:
curl http://127.0.0.1:8000/v1/models
Si ves un error de conexión, verifica el host, el puerto y que vLLM se haya iniciado en modo de servidor compatible con OpenAI.
Si las solicitudes fallan con errores de autenticación, establece un VLLM_API_KEY real que coincida con la configuración de tu servidor, o configura explícitamente el proveedor en models.providers.vllm.
Si tu servidor vLLM no exige autenticación, cualquier valor no vacío para VLLM_API_KEY funciona como señal de activación para OpenClaw.
El descubrimiento automático requiere que VLLM_API_KEY esté configurado y que no exista una entrada explícita de configuración models.providers.vllm. Si has definido manualmente el proveedor, OpenClaw omite el descubrimiento y usa solo los modelos declarados.
Más ayuda: Solución de problemas y FAQ.

​
Relacionado

Model selection

Elegir proveedores, referencias de modelos y comportamiento de failover.

OpenAI

Proveedor nativo de OpenAI y comportamiento de rutas compatibles con OpenAI.

OAuth and auth

Detalles de autenticación y reglas de reutilización de credenciales.

Troubleshooting

Problemas comunes y cómo resolverlos.