Come configurare OpenClaw con OmniaKey: Provider e allowlist dei modelli

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:

{
  "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:

{
  "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

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.

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).

• 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).

• 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).

• 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 elenca tutti gli id autorizzabili, e i prezzi mostrano la tariffa per token.

La guida agli agenti di coding copre gli altri strumenti. Per la configurazione passo passo, vedi le guide Configurare Hermes Agent, Chiave API personalizzata in Cline e Configurare Claude Code.

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
• OpenClaw: Skills e Provider di modelli