Fornitori di modelli

Riferimento per provider LLM/modelli (non canali di chat come WhatsApp/Telegram). Per le regole di selezione dei modelli, consulta Modelli.

# Regole rapide

# Comportamento dei provider di proprieta del Plugin

La maggior parte della logica specifica del provider risiede nei Plugin del provider (registerProvider(...)), mentre OpenClaw mantiene il ciclo di inferenza generico. I Plugin possiedono onboarding, cataloghi dei modelli, mappatura delle variabili d'ambiente di autenticazione, normalizzazione di trasporto/configurazione, pulizia degli schemi degli strumenti, classificazione del failover, refresh OAuth, reporting dell'utilizzo, profili di thinking/reasoning e altro ancora.

L'elenco completo degli hook SDK dei provider e degli esempi di Plugin in bundle si trova in Plugin dei provider. Un provider che necessita di un executor di richiesta completamente personalizzato e una superficie di estensione separata e piu profonda.

# Rotazione delle chiavi API

# Provider integrati (catalogo pi-ai)

OpenClaw include il catalogo pi-ai. Questi provider non richiedono nessuna configurazione models.providers; imposta solo l'autenticazione e scegli un modello.

# OpenAI

• Provider: openai
• Auth: OPENAI_API_KEY
• Rotazione opzionale: OPENAI_API_KEYS, OPENAI_API_KEY_1, OPENAI_API_KEY_2, piu OPENCLAW_LIVE_OPENAI_KEY (singola sostituzione)
• Modelli di esempio: openai/gpt-5.5, openai/gpt-5.4-mini
• Verifica la disponibilita dell'account/modello con openclaw models list --provider openai se una specifica installazione o chiave API si comporta in modo diverso.
• CLI: openclaw onboard --auth-choice openai-api-key
• Il trasporto predefinito e auto (prima WebSocket, fallback SSE)
• Sostituisci per modello tramite agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket" o "auto")
• Il warm-up WebSocket di OpenAI Responses e abilitato per impostazione predefinita tramite params.openaiWsWarmup (true/false)
• L'elaborazione prioritaria OpenAI puo essere abilitata tramite agents.defaults.models["openai/<model>"].params.serviceTier
• /fast e params.fastMode mappano le richieste Responses dirette openai/* a service_tier=priority su api.openai.com
• Usa params.serviceTier quando vuoi un tier esplicito invece del toggle condiviso /fast
• Le intestazioni di attribuzione OpenClaw nascoste (originator, version, User-Agent) si applicano solo al traffico OpenAI nativo verso api.openai.com, non ai proxy generici compatibili con OpenAI
• Le route OpenAI native mantengono anche Responses store, suggerimenti per la prompt-cache e shaping del payload compatibile con il reasoning OpenAI; le route proxy no
• openai/gpt-5.3-codex-spark e intenzionalmente soppresso in OpenClaw perche le richieste API OpenAI live lo rifiutano e il catalogo Codex corrente non lo espone

{
  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
}

# Anthropic

• Provider: anthropic
• Auth: ANTHROPIC_API_KEY
• Rotazione opzionale: ANTHROPIC_API_KEYS, ANTHROPIC_API_KEY_1, ANTHROPIC_API_KEY_2, piu OPENCLAW_LIVE_ANTHROPIC_KEY (singola sostituzione)
• Modello di esempio: anthropic/claude-opus-4-6
• CLI: openclaw onboard --auth-choice apiKey
• Le richieste Anthropic pubbliche dirette supportano il toggle condiviso /fast e params.fastMode, incluso il traffico autenticato con chiave API e OAuth inviato a api.anthropic.com; OpenClaw lo mappa su service_tier Anthropic (auto rispetto a standard_only)
• La configurazione Claude CLI preferita mantiene canonico il riferimento al modello e seleziona separatamente il backend CLI: anthropic/claude-opus-4-7 con agents.defaults.agentRuntime.id: "claude-cli". I riferimenti legacy claude-cli/claude-opus-4-7 continuano a funzionare per compatibilita.

{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

# OpenAI Codex OAuth

• Provider: openai-codex
• Auth: OAuth (ChatGPT)
• Riferimento modello PI: openai-codex/gpt-5.5
• Riferimento harness app-server Codex nativo: openai/gpt-5.5 con agents.defaults.agentRuntime.id: "codex"
• Documentazione dell'harness app-server Codex nativo: Harness Codex
• Riferimenti modello legacy: codex/gpt-*
• Confine del Plugin: openai-codex/* carica il Plugin OpenAI; il Plugin app-server Codex nativo viene selezionato solo dal runtime dell'harness Codex o dai riferimenti legacy codex/*.
• CLI: openclaw onboard --auth-choice openai-codex oppure openclaw models auth login --provider openai-codex
• Il trasporto predefinito e auto (prima WebSocket, fallback SSE)
• Sostituisci per modello PI tramite agents.defaults.models["openai-codex/<model>"].params.transport ("sse", "websocket" o "auto")
• Anche params.serviceTier viene inoltrato sulle richieste native Codex Responses (chatgpt.com/backend-api)
• Le intestazioni di attribuzione OpenClaw nascoste (originator, version, User-Agent) vengono allegate solo al traffico Codex nativo verso chatgpt.com/backend-api, non ai proxy generici compatibili con OpenAI
• Condivide la stessa configurazione del toggle /fast e di params.fastMode delle route dirette openai/*; OpenClaw la mappa su service_tier=priority
• openai-codex/gpt-5.5 usa il contextWindow = 400000 nativo del catalogo Codex e il runtime predefinito contextTokens = 272000; sostituisci il limite del runtime con models.providers.openai-codex.models[].contextTokens
• Nota sulla policy: OpenAI Codex OAuth e esplicitamente supportato per strumenti/workflow esterni come OpenClaw.
• Per la route comune con abbonamento piu runtime Codex nativo, accedi con l'autenticazione openai-codex ma configura openai/gpt-5.5 piu agents.defaults.agentRuntime.id: "codex".
• Usa openai-codex/gpt-5.5 solo quando vuoi la route Codex OAuth/abbonamento tramite PI; usa openai/gpt-5.5 senza la sostituzione del runtime Codex quando la tua configurazione con chiave API e il catalogo locale espongono la route API pubblica.
• I riferimenti precedenti openai-codex/gpt-5.1*, openai-codex/gpt-5.2* e openai-codex/gpt-5.3* sono soppressi perche gli account ChatGPT/Codex OAuth li rifiutano; usa invece openai-codex/gpt-5.5 o la route del runtime Codex nativo.

{
  plugins: { entries: { codex: { enabled: true } } },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.5" },
      agentRuntime: { id: "codex" },
    },
  },
}

{
  models: {
    providers: {
      "openai-codex": {
        models: [{ id: "gpt-5.5", contextTokens: 160000 }],
      },
    },
  },
}

# Altre opzioni ospitate in stile abbonamento

# OpenCode

• Auth: OPENCODE_API_KEY (o OPENCODE_ZEN_API_KEY)
• Provider runtime Zen: opencode
• Provider runtime Go: opencode-go
• Modelli di esempio: opencode/claude-opus-4-6, opencode-go/kimi-k2.6
• CLI: openclaw onboard --auth-choice opencode-zen oppure openclaw onboard --auth-choice opencode-go

{
  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },
}

# Google Gemini (chiave API)

• Provider: google
• Auth: GEMINI_API_KEY
• Rotazione facoltativa: GEMINI_API_KEYS, GEMINI_API_KEY_1, GEMINI_API_KEY_2, fallback GOOGLE_API_KEY e OPENCLAW_LIVE_GEMINI_KEY (override singolo)
• Modelli di esempio: google/gemini-3.1-pro-preview, google/gemini-3-flash-preview
• Compatibilità: la configurazione legacy di OpenClaw che usa google/gemini-3.1-flash-preview viene normalizzata in google/gemini-3-flash-preview
• Alias: google/gemini-3.1-pro è accettato e normalizzato nell'id API Gemini live di Google, google/gemini-3.1-pro-preview
• CLI: openclaw onboard --auth-choice gemini-api-key
• Thinking: /think adaptive usa il thinking dinamico di Google. Gemini 3/3.1 omette un thinkingLevel fisso; Gemini 2.5 invia thinkingBudget: -1.
• Le esecuzioni Gemini dirette accettano anche agents.defaults.models["google/<model>"].params.cachedContent (o il legacy cached_content) per inoltrare un handle nativo del provider cachedContents/...; gli hit della cache Gemini emergono come cacheRead di OpenClaw

# Google Vertex e Gemini CLI

• Provider: google-vertex, google-gemini-cli
• Auth: Vertex usa gcloud ADC; Gemini CLI usa il proprio flusso OAuth

Gemini CLI OAuth viene fornito come parte del Plugin google incluso in bundle.

brew install gemini-cli

npm install -g @google/gemini-cli

openclaw plugins enable google

openclaw models auth login --provider google-gemini-cli --set-default

Le risposte JSON di Gemini CLI vengono analizzate da response; l'utilizzo ripiega su stats, con stats.cached normalizzato in cacheRead di OpenClaw.

# Z.AI (GLM)

• Provider: zai
• Auth: ZAI_API_KEY
• Modello di esempio: zai/glm-5.1
• CLI: openclaw onboard --auth-choice zai-api-key
  • Alias: z.ai/* e z-ai/* vengono normalizzati in zai/*
  • zai-api-key rileva automaticamente l'endpoint Z.AI corrispondente; zai-coding-global, zai-coding-cn, zai-global e zai-cn forzano una superficie specifica

# Vercel AI Gateway

• Provider: vercel-ai-gateway
• Auth: AI_GATEWAY_API_KEY
• Modelli di esempio: vercel-ai-gateway/anthropic/claude-opus-4.6, vercel-ai-gateway/moonshotai/kimi-k2.6
• CLI: openclaw onboard --auth-choice ai-gateway-api-key

# Kilo Gateway

• Provider: kilocode
• Auth: KILOCODE_API_KEY
• Modello di esempio: kilocode/kilo/auto
• CLI: openclaw onboard --auth-choice kilocode-api-key
• URL base: https://api.kilo.ai/api/gateway/
• Il catalogo statico di fallback include kilocode/kilo/auto; il rilevamento live di https://api.kilo.ai/api/gateway/models può ampliare ulteriormente il catalogo runtime.
• Il routing upstream esatto dietro kilocode/kilo/auto è di proprietà di Kilo Gateway, non codificato rigidamente in OpenClaw.

Vedi /providers/kilocode per i dettagli di configurazione.

# Altri Plugin provider inclusi in bundle

# Particolarità da conoscere

# Provider tramite models.providers (URL personalizzato/di base)

Usa models.providers (o models.json) per aggiungere provider personalizzati o proxy compatibili con OpenAI/Anthropic.

Molti dei plugin provider inclusi qui sotto pubblicano già un catalogo predefinito. Usa voci esplicite models.providers.<id> solo quando vuoi sovrascrivere l'URL di base predefinito, le intestazioni o l'elenco dei modelli.

I controlli delle capacità dei modelli del Gateway leggono anche i metadati espliciti models.providers.<id>.models[]. Se un modello personalizzato o proxy accetta immagini, imposta input: ["text", "image"] su quel modello, così WebChat e i percorsi degli allegati originati dal nodo passano le immagini come input nativi del modello invece che come riferimenti multimediali solo testo.

# Moonshot AI (Kimi)

Moonshot viene distribuito come plugin provider incluso. Usa il provider integrato per impostazione predefinita e aggiungi una voce esplicita models.providers.moonshot solo quando devi sovrascrivere l'URL di base o i metadati del modello:

• Provider: moonshot
• Autenticazione: MOONSHOT_API_KEY
• Modello di esempio: moonshot/kimi-k2.6
• CLI: openclaw onboard --auth-choice moonshot-api-key o openclaw onboard --auth-choice moonshot-api-key-cn

ID dei modelli Kimi K2:

• moonshot/kimi-k2.6
• moonshot/kimi-k2.5
• moonshot/kimi-k2-thinking
• moonshot/kimi-k2-thinking-turbo
• moonshot/kimi-k2-turbo

{
  agents: {
    defaults: { model: { primary: "moonshot/kimi-k2.6" } },
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [{ id: "kimi-k2.6", name: "Kimi K2.6" }],
      },
    },
  },
}

# Kimi coding

Kimi Coding usa l'endpoint compatibile con Anthropic di Moonshot AI:

• Provider: kimi
• Autenticazione: KIMI_API_KEY
• Modello di esempio: kimi/kimi-code

{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: { model: { primary: "kimi/kimi-code" } },
  },
}

kimi/k2p5 legacy rimane accettato come id modello di compatibilità.

# Volcano Engine (Doubao)

Volcano Engine (火山引擎) fornisce accesso a Doubao e ad altri modelli in Cina.

• Provider: volcengine (coding: volcengine-plan)
• Auth: VOLCANO_ENGINE_API_KEY
• Modello di esempio: volcengine-plan/ark-code-latest
• CLI: openclaw onboard --auth-choice volcengine-api-key

{
  agents: {
    defaults: { model: { primary: "volcengine-plan/ark-code-latest" } },
  },
}

L'onboarding usa per impostazione predefinita la superficie di coding, ma il catalogo generale volcengine/* viene registrato contemporaneamente.

Nei selettori di modello di onboarding/configurazione, la scelta di autenticazione Volcengine preferisce sia le righe volcengine/* sia volcengine-plan/*. Se quei modelli non sono ancora caricati, OpenClaw ripiega sul catalogo non filtrato invece di mostrare un selettore limitato al provider vuoto.

# BytePlus (internazionale)

BytePlus ARK fornisce accesso agli stessi modelli di Volcano Engine per gli utenti internazionali.

• Provider: byteplus (coding: byteplus-plan)
• Auth: BYTEPLUS_API_KEY
• Modello di esempio: byteplus-plan/ark-code-latest
• CLI: openclaw onboard --auth-choice byteplus-api-key

{
  agents: {
    defaults: { model: { primary: "byteplus-plan/ark-code-latest" } },
  },
}

L'onboarding usa per impostazione predefinita la superficie di coding, ma il catalogo generale byteplus/* viene registrato contemporaneamente.

Nei selettori di modello di onboarding/configurazione, la scelta di autenticazione BytePlus preferisce sia le righe byteplus/* sia byteplus-plan/*. Se quei modelli non sono ancora caricati, OpenClaw ripiega sul catalogo non filtrato invece di mostrare un selettore limitato al provider vuoto.

# Synthetic

Synthetic fornisce modelli compatibili con Anthropic dietro il provider synthetic:

• Provider: synthetic
• Auth: SYNTHETIC_API_KEY
• Modello di esempio: synthetic/hf:MiniMaxAI/MiniMax-M2.5
• CLI: openclaw onboard --auth-choice synthetic-api-key

{
  agents: {
    defaults: { model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" } },
  },
  models: {
    mode: "merge",
    providers: {
      synthetic: {
        baseUrl: "https://api.synthetic.new/anthropic",
        apiKey: "${SYNTHETIC_API_KEY}",
        api: "anthropic-messages",
        models: [{ id: "hf:MiniMaxAI/MiniMax-M2.5", name: "MiniMax M2.5" }],
      },
    },
  },
}

# MiniMax

MiniMax viene configurato tramite models.providers perché usa endpoint personalizzati:

• MiniMax OAuth (Global): --auth-choice minimax-global-oauth
• MiniMax OAuth (CN): --auth-choice minimax-cn-oauth
• Chiave API MiniMax (Global): --auth-choice minimax-global-api
• Chiave API MiniMax (CN): --auth-choice minimax-cn-api
• Auth: MINIMAX_API_KEY per minimax; MINIMAX_OAUTH_TOKEN o MINIMAX_API_KEY per minimax-portal

Consulta /providers/minimax per i dettagli di configurazione, le opzioni dei modelli e gli snippet di configurazione.

Suddivisione delle capacità di proprietà del plugin:

• I valori predefiniti di testo/chat restano su minimax/MiniMax-M2.7
• La generazione di immagini è minimax/image-01 o minimax-portal/image-01
• La comprensione delle immagini è MiniMax-VL-01, di proprietà del plugin, su entrambi i percorsi di autenticazione MiniMax
• La ricerca web resta sull'id provider minimax

# LM Studio

LM Studio viene fornito come Plugin provider incluso che usa l'API nativa:

• Provider: lmstudio
• Auth: LM_API_TOKEN
• URL di base predefinito per l'inferenza: http://localhost:1234/v1

Poi imposta un modello (sostituiscilo con uno degli ID restituiti da http://localhost:1234/api/v1/models):

{
  agents: {
    defaults: { model: { primary: "lmstudio/openai/gpt-oss-20b" } },
  },
}

OpenClaw usa /api/v1/models e /api/v1/models/load nativi di LM Studio per discovery + caricamento automatico, con /v1/chat/completions per l'inferenza per impostazione predefinita. Se vuoi che il caricamento JIT, TTL e l'espulsione automatica di LM Studio gestiscano il ciclo di vita del modello, imposta models.providers.lmstudio.params.preload: false. Consulta /providers/lmstudio per configurazione e risoluzione dei problemi.

# Ollama

Ollama viene fornito come Plugin provider incluso e usa l'API nativa di Ollama:

• Provider: ollama
• Auth: non richiesta (server locale)
• Modello di esempio: ollama/llama3.3
• Installazione: https://ollama.com/download

# Install Ollama, then pull a model:
ollama pull llama3.3

{
  agents: {
    defaults: { model: { primary: "ollama/llama3.3" } },
  },
}

Ollama viene rilevato localmente su http://127.0.0.1:11434 quando acconsenti esplicitamente con OLLAMA_API_KEY, e il Plugin provider incluso aggiunge Ollama direttamente a openclaw onboard e al selettore di modelli. Consulta /providers/ollama per onboarding, modalità cloud/locale e configurazione personalizzata.

# vLLM

vLLM viene fornito come Plugin provider incluso per server locali/self-hosted compatibili con OpenAI:

• Provider: vllm
• Auth: opzionale (dipende dal tuo server)
• URL di base predefinito: http://127.0.0.1:8000/v1

Per acconsentire esplicitamente alla discovery automatica locale (qualsiasi valore funziona se il tuo server non applica l'autenticazione):

export VLLM_API_KEY="vllm-local"

Poi imposta un modello (sostituiscilo con uno degli ID restituiti da /v1/models):

{
  agents: {
    defaults: { model: { primary: "vllm/your-model-id" } },
  },
}

Consulta /providers/vllm per i dettagli.

# SGLang

SGLang viene fornito come Plugin provider incluso per server compatibili con OpenAI veloci e self-hosted:

• Provider: sglang
• Auth: opzionale (dipende dal tuo server)
• URL di base predefinito: http://127.0.0.1:30000/v1

Per acconsentire esplicitamente alla discovery automatica locale (qualsiasi valore funziona se il tuo server non applica l'autenticazione):

export SGLANG_API_KEY="sglang-local"

Poi imposta un modello (sostituiscilo con uno degli ID restituiti da /v1/models):

{
  agents: {
    defaults: { model: { primary: "sglang/your-model-id" } },
  },
}

Consulta /providers/sglang per i dettagli.

# Proxy locali (LM Studio, vLLM, LiteLLM, ecc.)

Esempio (compatibile con OpenAI):

{
  agents: {
    defaults: {
      model: { primary: "lmstudio/my-local-model" },
      models: { "lmstudio/my-local-model": { alias: "Local" } },
    },
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "${LM_API_TOKEN}",
        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: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

# Esempi CLI

openclaw onboard --auth-choice opencode-zen
openclaw models set opencode/claude-opus-4-6
openclaw models list

Vedi anche: Configurazione per esempi completi di configurazione.

# Correlati

• Riferimento di configurazione - chiavi di configurazione dei modelli
• Failover dei modelli - catene di fallback e comportamento dei tentativi
• Modelli - configurazione e alias dei modelli
• Provider - guide alla configurazione per provider