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

Providers

Infiere

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

Propiedad Valor
Id. del proveedor inferrs (personalizado; configúrelo en models.providers.inferrs)
Plugin ninguno; no es un plugin de proveedor incluido con OpenClaw
Variable de entorno de autenticación no se requiere ninguna; cualquier valor funciona si su servidor inferrs no tiene autenticación
API compatible con OpenAI (openai-completions)
URL base sugerida http://127.0.0.1:8080/v1 (o donde esté escuchando su servidor inferrs)

Primeros pasos

  • Start inferrs with a model

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

  • Verify the server is reachable

    bash
    curl http://127.0.0.1:8080/healthcurl http://127.0.0.1:8080/v1/models

  • Add an OpenClaw provider entry

    Añada una entrada explícita de proveedor y configure el modelo predeterminado para que la use. 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 use esa ruta. Referencia completa de los campos: Servicios de modelos locales.

    Configuración avanzada

    Why requiresStringContent matters

    Algunas rutas de finalización de chat de inferrs solo aceptan cadenas en messages[].content, no matrices estructuradas de partes de contenido.

    Gemma and tool-schema caveat

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

    json5
    compat: {  requiresStringContent: true,  supportsTools: false}

    Esto reduce la carga del prompt en los backends locales más estrictos. Si las solicitudes directas pequeñas siguen funcionando, pero los turnos normales del agente de OpenClaw continúan provocando errores en inferrs, considérelo una limitación del modelo o servidor de origen, no un problema de transporte de OpenClaw.

    Manual smoke test

    Pruebe ambas capas una vez configuradas:

    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":"What is 2 + 2?"}],"stream":false}'
    bash
    openclaw infer model run \  --model inferrs/google/gemma-4-E2B-it \  --prompt "What is 2 + 2? Reply with one short sentence." \  --json

    Si el primer comando funciona, pero el segundo falla, consulte la sección Solución de problemas siguiente.

    Proxy-style behavior

    Dado que inferrs usa el adaptador genérico openai-completions (no openai-responses), nunca se aplica la preparación de solicitudes exclusiva de OpenAI nativo: no se envían service_tier, el campo store de Responses, indicaciones de caché del prompt ni cargas útiles de compatibilidad con el razonamiento de OpenAI.

    Solución de problemas

    curl /v1/models fails

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

    messages[].content expected a string

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

    Direct /v1/chat/completions calls pass but openclaw infer model run fails

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

    inferrs still crashes on larger agent turns

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

    Contenido relacionado

    Local models

    Ejecución de OpenClaw con servidores de modelos locales.
    Local model services

    Inicio bajo demanda de servidores de modelos locales para proveedores configurados.
    Gateway troubleshooting

    Depuración de backends locales compatibles con OpenAI que superan las comprobaciones, pero fallan en las ejecuciones del agente.
    Model selection

    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