# Come configurare OpenClaw con OmniaKey: Provider e allowlist dei modelli > Aggiungi OmniaKey come Provider OpenAI-compatible in OpenClaw. Configura openclaw.json, allowlist dei modelli, doctor e l'errore model not allowed. - Canonical HTML: https://omniakey.com/it/blog/openclaw-setup - Markdown: https://omniakey.com/it/blog/openclaw-setup.md - Published: 2026-05-19 (updated 2026-10-30) - Author: Kiki, COO at OmniaKey - Language: it - Category: Guide - Reading time: 5 min - All posts: https://omniakey.com/blog/llms.txt --- Aggiornato il 30 ottobre 2026: qui sotto trovi quattro errori di configurazione comuni, ciascuno con sintomo, causa e soluzione presa dalla documentazione di OpenClaw. Chi cerca **configurare OpenClaw con OmniaKey** deve distinguere due passaggi: definire il Provider e autorizzare i modelli. OpenClaw fornisce il loop dell'agente e gli strumenti; il Provider fornisce il modello che risponde. ## Aggiungere OmniaKey come Provider La configurazione si trova in `~/.openclaw/openclaw.json`. Aggiungi OmniaKey sotto `models.providers`: ```json { "models": { "mode": "merge", "providers": { "omniakey": { "baseUrl": "https://api.omniakey.com/v1", "apiKey": "your-omniakey-api-key", "api": "openai-completions", "models": [ { "id": "claude-opus-4-8" }, { "id": "gpt-5.5" }, { "id": "gemini-3.1-pro-preview" }, { "id": "grok-4.5" } ] } } } } ``` `mode: merge` aggiunge il Provider senza sostituire la configurazione esistente. Usa la tua chiave reale, ma non committarla né condividerla. Un solo Provider compatibile con OpenAI copre quattro famiglie di modelli: OmniaKey cerca il modello tramite l'ID, quindi `claude-opus-4-8`, `gpt-5.5`, `gemini-3.1-pro-preview` e `grok-4.5` passano tutti dalla stessa voce. ## Il passaggio spesso dimenticato: allowlist Definire il Provider non basta. OpenClaw richiede che il modello sia anche nella allowlist. Nello stesso file aggiungi `agents` allo stesso livello di `models`: ```json { "agents": { "defaults": { "models": ["omniakey/claude-opus-4-8", "omniakey/gpt-5.5", "omniakey/gemini-3.1-pro-preview", "omniakey/grok-4.5"], "model": "omniakey/claude-opus-4-8" } } } ``` Il request body usa il model ID; `provider/model-id` è il riferimento interno di OpenClaw. Servono entrambe le voci. Senza allowlist puoi ricevere `model not allowed` anche con una chiave corretta. ## Verificare la configurazione di OpenClaw con OmniaKey ```bash openclaw doctor ``` `doctor` controlla file, Provider, formato della chiave, connessione live e accesso al modello. Poi puoi impostare `omniakey/gpt-5.5` in `agents.defaults`. > Non modificare manualmente `~/.openclaw/agents/main/agent/models.json`: viene rigenerato da `openclaw.json`. ## Errori di configurazione comuni - `Model override "provider/model" is not allowed by agents.defaults.modelPolicy.allow.` Il ref scelto non è in una lista `agents.defaults.modelPolicy.allow` non vuota, e OpenClaw controlla proprio quella lista per `/model`, per le sostituzioni dentro la sessione e per `--model`. Aggiungi il ref esatto o un jolly di Provider come `omniakey/*`, svuota la lista, oppure scegli un modello da `/model list` ([FAQ sui modelli di OpenClaw](https://docs.openclaw.ai/help/faq-models#why-do-i-see-model-is-not-allowed-and-then-no-reply)). - `model_not_found` o un 404, mentre una chiamata diretta con lo stesso model ID funziona. Una voce personalizzata viene risolta solo se `baseUrl` termina con `/v1`, `api` vale `"openai-completions"` e il catalogo tiene l'ID senza prefisso mentre tu lo selezioni con il prefisso del Provider. Controlla questi tre punti, seleziona il modello una volta con il prefisso e rilancia la stessa richiesta ([risoluzione dei problemi con backend locale](https://docs.openclaw.ai/gateway/troubleshooting/skills-and-model-providers#local-openai-compatible-backend-passes-direct-checks-but-agent-runs-fail)). - Un 403 nudo con "Your request was blocked" nel corpo della risposta. Quel testo di solito arriva da uno strato di sicurezza davanti all'endpoint — CDN, WAF, regola anti-bot o reverse proxy — e non da `openclaw.json`; `openclaw logs --follow` mostra se più modelli dello stesso Provider falliscono allo stesso modo. Sistema prima il lato Provider con una regola di permesso che copra solo il percorso chiamato da OpenClaw, e lascia attiva la protezione sul resto del sito ([risoluzione dei problemi del 403 a monte](https://docs.openclaw.ai/gateway/troubleshooting/skills-and-model-providers#upstream-403-blocked-responses)). - `messages[...].content: invalid type: sequence, expected a string` a ogni esecuzione dell'agente. Il backend rifiuta le parti di content strutturate in stile OpenAI. Imposta `compat.requiresStringContent: true` sulla voce di quel modello e rilancia la stessa richiesta. ## Perché usare OmniaKey Una chiave e un saldo per Claude, GPT, Gemini e Grok, con tariffazione a token. L'ID autorizzato è quello che viene eseguito, senza sostituzioni silenziose. Il [catalogo dei modelli](https://omniakey.com/it/models) elenca tutti gli id autorizzabili, e [i prezzi](https://omniakey.com/it/pricing) mostrano la tariffa per token. - **OpenAI-compatible**: - **Anthropic-native**: - **Gemini-native**: La [guida agli agenti di coding](https://docs.omniakey.com/it/coding) copre gli altri strumenti. Per la configurazione passo passo, vedi le guide [Configurare Hermes Agent](https://omniakey.com/it/blog/hermes-setup), [Chiave API personalizzata in Cline](https://omniakey.com/it/blog/cline-custom-api-key) e [Configurare Claude Code](https://omniakey.com/it/blog/claude-code-setup). ## Domande frequenti ### Dove va il blocco Provider di OmniaKey? In `~/.openclaw/openclaw.json`, sotto `models.providers`. Lascia `"mode": "merge"` così il blocco si aggiunge ai Provider che hai già invece di sostituirli. ### Perché OpenClaw dice che un modello non è consentito? Il Provider è definito, ma il ref del modello non è nella allowlist di OpenClaw, quindi l'esecuzione fallisce anche con la chiave giusta. Aggiungi il ref completo `omniakey/model-id`, poi esegui `openclaw doctor`. ### Una sola chiave OmniaKey può eseguire Claude, GPT, Gemini e Grok in OpenClaw? Sì. Una sola voce di Provider con `api: "openai-completions"` raggiunge tutte e quattro le famiglie, e il model ID nella richiesta decide quale viene eseguita. ### Come verifico che OpenClaw raggiunga OmniaKey? `openclaw doctor` controlla il file di configurazione, il Provider, il formato della chiave, una connessione live e l'accesso al modello. Poi `openclaw models list` mostra i modelli OmniaKey che hai autorizzato. ### Devo modificare \~/.openclaw/agents/main/agent/models.json? No. Quel file viene rigenerato da `openclaw.json`, quindi le modifiche a Provider e allowlist di OpenClaw con OmniaKey vanno fatte in `openclaw.json`. ## Fonti verificate - [OpenClaw: FAQ su modelli e autenticazione](https://docs.openclaw.ai/help/faq-models) - [OpenClaw: Skills e Provider di modelli](https://docs.openclaw.ai/gateway/troubleshooting/skills-and-model-providers)