OpenClawDocs
In questa pagina

In questa pagina

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

Inizia

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?