Inferrs

inferrs sirve modelos locales mediante una API /v1 compatible con OpenAI. OpenClaw se comunica con él a través del adaptador genérico openai-completions.

Propiedad	Valor
Id. del proveedor	`inferrs` (personalizado; se configura en `models.providers.inferrs`)
Plugin	ninguno — no es un plugin de proveedor incluido con OpenClaw
Variable de entorno de autenticación	no es necesaria; cualquier valor funciona si el servidor de inferrs no tiene autenticación
API	Compatible con OpenAI (`openai-completions`)
URL base sugerida	`http://127.0.0.1:8080/v1` (o donde escuche el servidor de inferrs)

inferrs es un backend personalizado, autoalojado y compatible con OpenAI, no un plugin de proveedor dedicado de OpenClaw: se configura en models.providers.inferrs en lugar de elegir una opción de autenticación durante la incorporación. Para usar un plugin incluido con detección automática, consulte SGLang o vLLM.

Primeros pasos

Iniciar inferrs con un modelo

inferrs serve google/gemma-4-E2B-it \
  --host 127.0.0.1 \
  --port 8080 \
  --device metal

Verificar que se pueda acceder al servidor

curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/v1/models

Añadir una entrada de proveedor de OpenClaw

Añada una entrada de proveedor explícita y dirija el modelo predeterminado a ella. Consulte el ejemplo de configuración siguiente.

Ejemplo de configuración completa

Gemma 4 en un servidor inferrs local:

{
  agents: {
    defaults: {
      model: { primary: "inferrs/google/gemma-4-E2B-it" },
      models: {
        "inferrs/google/gemma-4-E2B-it": {
          alias: "Gemma 4 (inferrs)",
        },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      inferrs: {
        baseUrl: "http://127.0.0.1:8080/v1",
        apiKey: "inferrs-local",
        api: "openai-completions",
        models: [
          {
            id: "google/gemma-4-E2B-it",
            name: "Gemma 4 E2B (inferrs)",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 131072,
            maxTokens: 4096,
            compat: {
              requiresStringContent: true,
            },
          },
        ],
      },
    },
  },
}

Inicio bajo demanda

OpenClaw puede iniciar inferrs por sí mismo únicamente cuando se selecciona un modelo inferrs/.... Añada localService a la misma entrada de proveedor:

{
  models: {
    providers: {
      inferrs: {
        baseUrl: "http://127.0.0.1:8080/v1",
        apiKey: "inferrs-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        localService: {
          command: "/opt/homebrew/bin/inferrs",
          args: [
            "serve",
            "google/gemma-4-E2B-it",
            "--host",
            "127.0.0.1",
            "--port",
            "8080",
            "--device",
            "metal",
          ],
          healthUrl: "http://127.0.0.1:8080/v1/models",
          readyTimeoutMs: 180000,
          idleStopMs: 0,
        },
        models: [
          {
            id: "google/gemma-4-E2B-it",
            name: "Gemma 4 E2B (inferrs)",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 131072,
            maxTokens: 4096,
            compat: {
              requiresStringContent: true,
            },
          },
        ],
      },
    },
  },
}

command debe ser una ruta absoluta. Ejecute which inferrs en el host del Gateway y utilice esa ruta. Referencia completa de los campos: Servicios de modelos locales.

Configuración avanzada

Por qué requiresStringContent es importante

Algunas rutas de Chat Completions de inferrs solo aceptan messages[].content de tipo cadena, no matrices estructuradas de partes de contenido.

Si las ejecuciones de OpenClaw fallan con:

messages[1].content: tipo no válido: secuencia; se esperaba una cadena

establezca compat.requiresStringContent: true en la entrada del modelo. OpenClaw convierte entonces las partes que contienen únicamente texto en cadenas simples antes de enviar la solicitud.

Advertencia sobre Gemma y el esquema de herramientas

Algunas combinaciones de inferrs y Gemma aceptan solicitudes directas pequeñas de /v1/chat/completions, pero fallan en turnos completos del entorno de ejecución de agentes de OpenClaw. Pruebe primero a desactivar la superficie del esquema de herramientas:

compat: {
  requiresStringContent: true,
  supportsTools: false
}

Esto reduce la presión del prompt sobre los backends locales más estrictos. Si las solicitudes directas pequeñas siguen funcionando, pero los turnos normales de agentes de OpenClaw continúan bloqueándose dentro de inferrs, considérelo una limitación del modelo o servidor ascendente, no un problema del transporte de OpenClaw.

Prueba rápida manual

Pruebe ambas capas después de configurarlas:

curl http://127.0.0.1:8080/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"google/gemma-4-E2B-it","messages":[{"role":"user","content":"¿Cuánto es 2 + 2?"}],"stream":false}'

openclaw infer model run \
  --model inferrs/google/gemma-4-E2B-it \
  --prompt "¿Cuánto es 2 + 2? Responde con una frase breve." \
  --json

Si el primer comando funciona, pero el segundo falla, consulte Solución de problemas más adelante.

Comportamiento de tipo proxy

Debido a que inferrs utiliza el adaptador genérico openai-completions (no openai-responses), nunca se aplica la conformación de solicitudes exclusiva de OpenAI nativo: no se envían service_tier, store de Responses, indicaciones de caché de prompts ni conformación de cargas útiles de compatibilidad de razonamiento de OpenAI.

Solución de problemas

curl /v1/models falla

inferrs no se está ejecutando, no es accesible o no está vinculado al host o puerto configurado. Confirme que el servidor esté iniciado y escuchando en esa dirección.

messages[].content esperaba una cadena

Establezca compat.requiresStringContent: true en la entrada del modelo (consulte la sección anterior).

Las llamadas directas a /v1/chat/completions funcionan, pero openclaw infer model run falla

Establezca compat.supportsTools: false para desactivar la superficie del esquema de herramientas (consulte la advertencia sobre Gemma anterior).

inferrs sigue bloqueándose en turnos de agente más grandes

Si los errores de esquema han desaparecido, pero inferrs sigue bloqueándose en turnos de agente más grandes, considérelo una limitación de inferrs ascendente o del modelo. Reduzca la presión del prompt o cambie de backend o modelo.

Para obtener ayuda general, consulte Solución de problemas y Preguntas frecuentes.

Relacionado

Modelos locales

Ejecución de OpenClaw con servidores de modelos locales.

Servicios de modelos locales

Inicio bajo demanda de servidores de modelos locales para los proveedores configurados.

Solución de problemas del Gateway

Depuración de backends locales compatibles con OpenAI que superan las pruebas, pero fallan en las ejecuciones de agentes.

Selección de modelos

Descripción general de todos los proveedores, las referencias de modelos y el comportamiento de conmutación por error.

Overview

Concepts and configuration

Providers

Primeros pasos

Ejemplo de configuración completa

Inicio bajo demanda

Configuración avanzada

Solución de problemas

Relacionado

Modelos locales

Servicios de modelos locales

Solución de problemas del Gateway

Selección de modelos

​Primeros pasos

​Ejemplo de configuración completa

​Inicio bajo demanda

​Configuración avanzada

​Solución de problemas

​Relacionado

Modelos locales

Servicios de modelos locales

Solución de problemas del Gateway

Selección de modelos

Primeros pasos

Ejemplo de configuración completa

Inicio bajo demanda

Configuración avanzada

Solución de problemas

Relacionado