OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Providers

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)

Primeros pasos

  • Iniciar inferrs con un modelo

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

  • Verificar que se pueda acceder al servidor

    bash
    curl http://127.0.0.1:8080/healthcurl 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:

    json5
    {  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:

    json5
    {  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.

    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:

    json5
    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:

    bash
    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}'
    bash
    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.

    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.
    Was this useful?
    On this page

    On this page