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

Providers

Deduce

inferrs espone modelli locali tramite un'API /v1 compatibile con OpenAI. OpenClaw comunica con essa tramite l'adattatore generico openai-completions.

Proprietà Valore
ID del provider inferrs (personalizzato; configurare in models.providers.inferrs)
Plugin nessuno — non è un Plugin provider incluso in OpenClaw
Variabile env auth nessuna richiesta; qualsiasi valore funziona se il server inferrs non richiede auth
API compatibile con OpenAI (openai-completions)
URL base suggerito http://127.0.0.1:8080/v1 (o l'indirizzo su cui è in ascolto il server inferrs)

Guida introduttiva

  • Avviare inferrs con un modello

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

  • Verificare che il server sia raggiungibile

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

  • Aggiungere una voce provider di OpenClaw

    Aggiungere una voce esplicita per il provider e impostarla come destinazione del modello predefinito. Consultare l'esempio di configurazione seguente.

    • Esempio di configurazione completa

    Gemma 4 su un server inferrs locale:

    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,            },          },        ],      },    },  },}

    Avvio su richiesta

    OpenClaw può avviare autonomamente inferrs solo quando viene selezionato un modello inferrs/.... Aggiungere localService alla stessa voce del provider:

    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 deve essere un percorso assoluto. Eseguire which inferrs sull'host del Gateway e utilizzare il percorso restituito. Riferimento completo dei campi: Servizi per modelli locali.

    Configurazione avanzata

    Perché requiresStringContent è importante

    Alcune route Chat Completions di inferrs accettano solo valori stringa in messages[].content, non array strutturati di parti del contenuto.

    Avvertenza su Gemma e sullo schema degli strumenti

    Alcune combinazioni di inferrs e Gemma accettano piccole richieste dirette a /v1/chat/completions, ma non riescono a gestire turni completi del runtime dell'agente OpenClaw. Provare innanzitutto a disabilitare lo schema degli strumenti:

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

    Ciò riduce il carico del prompt sui backend locali più restrittivi. Se le piccole richieste dirette continuano a funzionare, ma i normali turni dell'agente OpenClaw continuano a causare arresti anomali in inferrs, considerare il problema una limitazione a monte del modello o del server, anziché un problema del trasporto di OpenClaw.

    Test rapido manuale

    Una volta completata la configurazione, verificare entrambi i livelli:

    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

    Se il primo comando funziona ma il secondo non riesce, consultare la sezione Risoluzione dei problemi seguente.

    Comportamento in stile proxy

    Poiché inferrs utilizza l'adattatore generico openai-completions (non openai-responses), non viene mai applicata la formattazione delle richieste specifica delle API native di OpenAI: non vengono inviati service_tier, il campo store dell'API Responses, suggerimenti per la cache dei prompt né payload di compatibilità per il ragionamento di OpenAI.

    Risoluzione dei problemi

    curl /v1/models non riesce

    inferrs non è in esecuzione, non è raggiungibile oppure non è associato all'host o alla porta configurati. Verificare che il server sia avviato e in ascolto su tale indirizzo.

    messages[].content richiede una stringa

    Impostare compat.requiresStringContent: true nella voce del modello (vedere sopra).

    Le chiamate dirette a /v1/chat/completions riescono, ma openclaw infer model run non funziona

    Impostare compat.supportsTools: false per disabilitare lo schema degli strumenti (consultare l'avvertenza su Gemma riportata sopra).

    inferrs continua a bloccarsi nei turni più grandi dell'agente

    Se gli errori dello schema sono stati risolti, ma inferrs continua a bloccarsi nei turni più grandi dell'agente, considerare il problema una limitazione a monte di inferrs o del modello. Ridurre il carico del prompt oppure cambiare backend o modello.

    Contenuti correlati

    Modelli locali

    Esecuzione di OpenClaw con server di modelli locali.
    Servizi per modelli locali

    Avvio su richiesta dei server di modelli locali per i provider configurati.
    Risoluzione dei problemi del Gateway

    Diagnosi dei backend locali compatibili con OpenAI che superano le verifiche ma non riescono a eseguire i turni degli agenti.
    Selezione del modello

    Panoramica di tutti i provider, dei riferimenti ai modelli e del comportamento di failover.
    Was this useful?
    On this page

    On this page