Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

I modelli locali sono realizzabili. Alzano anche l’asticella per hardware, dimensione del contesto e difesa dalla prompt injection: schede piccole o quantizzate in modo aggressivo troncano il contesto e riducono la sicurezza. Questa pagina è la guida orientata per stack locali di fascia alta e server locali personalizzati compatibili con OpenAI. Per l’onboarding con meno attrito, inizia con LM Studio o Ollama e openclaw onboard. Per i server locali che dovrebbero avviarsi solo quando un modello selezionato ne ha bisogno, vedi Servizi di modelli locali.

​
Soglia hardware minima

Punta in alto: ≥2 Mac Studio al massimo della configurazione o un rig GPU equivalente (~$30k+) per un ciclo dell’agente confortevole. Una singola GPU da 24 GB funziona solo per prompt più leggeri con latenza più alta. Esegui sempre la variante più grande / a dimensione piena che puoi ospitare; checkpoint piccoli o fortemente quantizzati aumentano il rischio di prompt injection (vedi Sicurezza).

​
Scegli un backend

BackendDa usare quando
LM StudioPrima configurazione locale, loader GUI, API Responses nativa
OllamaFlusso di lavoro CLI, libreria di modelli, servizio systemd senza interventi
MLX / vLLM / SGLangServing self-hosted ad alto throughput con endpoint HTTP compatibile con OpenAI
LiteLLM / OAI-proxy / proxy personalizzato compatibile con OpenAIHai davanti un’altra API di modelli e devi fare in modo che OpenClaw la tratti come OpenAI
Usa Responses API (api: "openai-responses") quando il backend la supporta (LM Studio lo fa). Altrimenti resta su Chat Completions (api: "openai-completions").
Utenti WSL2 + Ollama + NVIDIA/CUDA: l’installer Linux ufficiale di Ollama abilita un servizio systemd con Restart=always. Nelle configurazioni GPU su WSL2, l’avvio automatico può ricaricare l’ultimo modello durante il boot e bloccare la memoria dell’host. Se la tua VM WSL2 si riavvia ripetutamente dopo aver abilitato Ollama, vedi loop di crash WSL2.

​
Consigliato: LM Studio + modello locale grande (Responses API)

Il miglior stack locale attuale. Carica un modello grande in LM Studio (per esempio, una build full-size di Qwen, DeepSeek o Llama), abilita il server locale (predefinito http://127.0.0.1:1234) e usa Responses API per mantenere il ragionamento separato dal testo finale. 
{
  agents: {
    defaults: {
      model: { primary: "lmstudio/my-local-model" },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "lmstudio/my-local-model": { alias: "Local" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}
Checklist di configurazione
  • Installa LM Studio: https://lmstudio.ai
  • In LM Studio, scarica la build di modello più grande disponibile (evita varianti “small”/fortemente quantizzate), avvia il server, conferma che http://127.0.0.1:1234/v1/models la elenchi.
  • Sostituisci my-local-model con l’ID modello effettivo mostrato in LM Studio.
  • Mantieni il modello caricato; il caricamento a freddo aggiunge latenza all’avvio.
  • Regola contextWindow/maxTokens se la tua build di LM Studio è diversa.
  • Per WhatsApp, resta su Responses API in modo che venga inviato solo il testo finale.
Mantieni configurati i modelli ospitati anche quando esegui in locale; usa models.mode: "merge" in modo che i fallback restino disponibili.

​
Configurazione ibrida: primario ospitato, fallback locale

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["lmstudio/my-local-model", "anthropic/claude-opus-4-6"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "lmstudio/my-local-model": { alias: "Local" },
        "anthropic/claude-opus-4-6": { alias: "Opus" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

​
Local-first con rete di sicurezza ospitata

Scambia l’ordine di primario e fallback; mantieni lo stesso blocco providers e models.mode: "merge" in modo da poter ricorrere a Sonnet o Opus quando la macchina locale non è disponibile.

​
Hosting regionale / routing dei dati

  • Varianti ospitate di MiniMax/Kimi/GLM esistono anche su OpenRouter con endpoint vincolati alla regione (ad esempio, ospitati negli Stati Uniti). Scegli lì la variante regionale per mantenere il traffico nella giurisdizione scelta usando comunque models.mode: "merge" per i fallback Anthropic/OpenAI.
  • Solo locale resta il percorso con la privacy più forte; il routing regionale ospitato è la via intermedia quando hai bisogno delle funzionalità del provider ma vuoi controllare il flusso dei dati.

​
Altri proxy locali compatibili con OpenAI

MLX (mlx_lm.server), vLLM, SGLang, LiteLLM, OAI-proxy o Gateway personalizzati funzionano se espongono un endpoint /v1/chat/completions in stile OpenAI. Usa l’adapter Chat Completions a meno che il backend non documenti esplicitamente il supporto per /v1/responses. Sostituisci il blocco provider sopra con il tuo endpoint e l’ID modello: 
{
  agents: {
    defaults: {
      model: { primary: "local/my-local-model" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      local: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "sk-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 120000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}
Se api viene omesso su un provider personalizzato con un baseUrl, OpenClaw usa per impostazione predefinita openai-completions. Gli endpoint di loopback come 127.0.0.1 sono considerati attendibili automaticamente; gli endpoint LAN, tailnet e DNS privati richiedono comunque request.allowPrivateNetwork: true. Il valore models.providers.<id>.models[].id è locale al provider. Non includere lì il prefisso del provider. Per esempio, un server MLX avviato con mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit dovrebbe usare questo ID di catalogo e riferimento modello:
  • models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"
  • agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"
Imposta input: ["text", "image"] sui modelli di visione locali o proxati in modo che gli allegati immagine vengano inseriti nei turni dell’agente. L’onboarding interattivo di provider personalizzati inferisce gli ID dei modelli di visione comuni e chiede solo i nomi sconosciuti. L’onboarding non interattivo usa la stessa inferenza; usa --custom-image-input per ID di visione sconosciuti o --custom-text-input quando un modello che sembra noto è solo testo dietro il tuo endpoint. Mantieni models.mode: "merge" in modo che i modelli ospitati restino disponibili come fallback. Usa models.providers.<id>.timeoutSeconds per server di modelli locali o remoti lenti prima di aumentare agents.defaults.timeoutSeconds. Il timeout del provider si applica solo alle richieste HTTP del modello, inclusi connessione, header, streaming del corpo e abort guarded-fetch totale.
Per provider personalizzati compatibili con OpenAI, la persistenza di un indicatore locale non segreto come apiKey: "ollama-local" è accettata quando baseUrl si risolve su loopback, una LAN privata, .local o un hostname semplice. OpenClaw lo tratta come una credenziale locale valida invece di segnalare una chiave mancante. Usa un valore reale per qualsiasi provider che accetta un hostname pubblico.
Nota di comportamento per backend /v1 locali/proxati:
  • OpenClaw li tratta come rotte compatibili con OpenAI in stile proxy, non come endpoint OpenAI nativi
  • lo shaping delle richieste solo OpenAI native non si applica qui: niente service_tier, niente Responses store, niente shaping del payload di compatibilità per il reasoning OpenAI e niente suggerimenti per la cache dei prompt
  • gli header di attribuzione nascosti di OpenClaw (originator, version, User-Agent) non vengono iniettati su questi URL di proxy personalizzati
Note di compatibilità per backend compatibili con OpenAI più rigorosi:
  • Alcuni server accettano solo messages[].content stringa su Chat Completions, non array strutturati di parti di contenuto. Imposta models.providers.<provider>.models[].compat.requiresStringContent: true per quegli endpoint.
  • Alcuni modelli locali emettono richieste di strumenti tra parentesi quadre autonome come testo, ad esempio [tool_name] seguito da JSON e [END_TOOL_REQUEST]. OpenClaw le promuove a vere chiamate strumento solo quando il nome corrisponde esattamente a uno strumento registrato per il turno; altrimenti il blocco viene trattato come testo non supportato ed è nascosto dalle risposte visibili all’utente.
  • Se un modello emette JSON, XML o testo in stile ReAct che sembra una chiamata strumento ma il provider non ha emesso un’invocazione strutturata, OpenClaw lo lascia come testo e registra un avviso con l’ID esecuzione, provider/modello, pattern rilevato e nome dello strumento quando disponibile. Consideralo un’incompatibilità delle chiamate strumento del provider/modello, non un’esecuzione dello strumento completata.
  • Se gli strumenti appaiono come testo dell’assistente invece di essere eseguiti, per esempio JSON grezzo, XML, sintassi ReAct o un array tool_calls vuoto nella risposta del provider, verifica prima che il server stia usando un template/parser chat capace di chiamate strumento. Per backend Chat Completions compatibili con OpenAI il cui parser funziona solo quando l’uso degli strumenti è forzato, imposta un override di richiesta per modello invece di fare affidamento sul parsing del testo: 
    {
  agents: {
    defaults: {
      models: {
        "local/my-local-model": {
          params: {
            extra_body: {
              tool_choice: "required",
            },
          },
        },
      },
    },
  },
}
    Usalo solo per modelli/sessioni in cui ogni turno normale dovrebbe chiamare uno strumento. Sostituisce il valore proxy predefinito di OpenClaw di tool_choice: "auto". Sostituisci local/my-local-model con il riferimento provider/modello esatto mostrato da openclaw models list. 
    openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
  • Se un modello personalizzato compatibile con OpenAI accetta livelli di impegno di reasoning OpenAI oltre il profilo integrato, dichiarali nel blocco compat del modello. Aggiungere "xhigh" qui fa sì che /think xhigh, i selettori di sessione, la validazione del Gateway e la validazione di llm-task espongano il livello per quel riferimento provider/modello configurato: 
    {
  models: {
    providers: {
      local: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "sk-local",
        api: "openai-responses",
        models: [
          {
            id: "gpt-5.4",
            name: "GPT 5.4 via local proxy",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
            compat: {
              supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
              reasoningEffortMap: { xhigh: "xhigh" },
            },
          },
        ],
      },
    },
  },
}

​
Backend più piccoli o più rigorosi

Se il modello si carica correttamente ma i turni completi dell’agente si comportano male, procedi dall’alto verso il basso: conferma prima il trasporto, poi restringi la superficie.
  1. Conferma che il modello locale risponda. Nessuno strumento, nessun contesto dell’agente: 
    openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json
  2. Conferma il routing del Gateway. Invia solo il prompt fornito: salta transcript, bootstrap AGENTS, assemblaggio del context-engine, strumenti e server MCP inclusi, ma esercita comunque routing del Gateway, autenticazione e selezione del provider: 
    openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
  3. Prova la modalità lean. Se entrambe le sonde passano ma i turni reali dell’agente falliscono con chiamate a strumenti malformate o prompt troppo grandi, abilita agents.defaults.experimental.localModelLean: true. Rimuove i tre strumenti predefiniti più pesanti (browser, cron, message) così la forma del prompt è più piccola e meno fragile. Vedi Funzionalità sperimentali → Modalità lean per modello locale per la spiegazione completa, quando usarla e come confermare che sia attiva.
  4. Disabilita completamente gli strumenti come ultima risorsa. Se la modalità lean non basta, imposta models.providers.<provider>.models[].compat.supportsTools: false per quella voce di modello. L’agente opererà quindi senza chiamate a strumenti su quel modello.
  5. Oltre questo punto, il collo di bottiglia è upstream. Se il backend continua a fallire solo su esecuzioni OpenClaw più grandi dopo la modalità lean e supportsTools: false, il problema restante è di solito la capacità del modello o del server upstream: finestra di contesto, memoria GPU, espulsione dalla kv-cache o un bug del backend. A quel punto non è il livello di trasporto di OpenClaw.

​
Risoluzione dei problemi

  • Il Gateway può raggiungere il proxy? curl http://127.0.0.1:1234/v1/models.
  • Modello LM Studio scaricato? Ricaricalo; l’avvio a freddo è una causa comune di “blocco”.
  • Il server locale segnala terminated, ECONNRESET o chiude lo stream a metà turno? OpenClaw registra un model.call.error.failureKind a bassa cardinalità più lo snapshot RSS/heap del processo OpenClaw nella diagnostica. Per pressione di memoria di LM Studio/Ollama, confronta quel timestamp con il log del server o con il log di crash / jetsam di macOS per confermare se il server del modello è stato terminato.
  • OpenClaw deriva le soglie di preflight della finestra di contesto dalla finestra del modello rilevata, o dalla finestra del modello senza limite quando agents.defaults.contextTokens abbassa la finestra effettiva. Avvisa sotto il 20% con un minimo di 8k. I blocchi rigidi usano la soglia del 10% con un minimo di 4k, limitata alla finestra di contesto effettiva così metadati del modello sovradimensionati non possono rifiutare un limite utente altrimenti valido. Se incontri quel preflight, aumenta il limite di contesto del server/modello o scegli un modello più grande.
  • Errori di contesto? Abbassa contextWindow o aumenta il limite del server.
  • Un server compatibile con OpenAI restituisce messages[].content ... expected a string? Aggiungi compat.requiresStringContent: true a quella voce di modello.
  • Un server compatibile con OpenAI restituisce validation.keys o dice che le voci dei messaggi consentono solo role e content? Aggiungi compat.strictMessageKeys: true a quella voce di modello.
  • Le chiamate minuscole dirette a /v1/chat/completions funzionano, ma openclaw infer model run --local fallisce su Gemma o su un altro modello locale? Controlla prima URL del provider, riferimento del modello, marker di autenticazione e log del server; model run locale non include strumenti dell’agente. Se model run locale riesce ma i turni dell’agente più grandi falliscono, riduci la superficie degli strumenti dell’agente con localModelLean o compat.supportsTools: false.
  • Le chiamate a strumenti compaiono come testo JSON/XML/ReAct grezzo, o il provider restituisce un array tool_calls vuoto? Non aggiungere un proxy che converte alla cieca il testo dell’assistente in esecuzione di strumenti. Correggi prima il template/parser chat del server. Se il modello funziona solo quando l’uso degli strumenti è forzato, aggiungi l’override per modello params.extra_body.tool_choice: "required" sopra e usa quella voce di modello solo per sessioni in cui è prevista una chiamata a strumenti a ogni turno.
  • Sicurezza: i modelli locali saltano i filtri lato provider; mantieni gli agenti mirati e Compaction attiva per limitare il raggio d’azione della prompt injection.

​
Correlati