Provider di modelli

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

Regole rapide

Comportamento dei provider di proprieta dei Plugin

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

L'elenco completo degli hook provider-SDK e degli esempi di Plugin in bundle si trova in Plugin provider. Un provider che necessita di un esecutore di richieste totalmente personalizzato e una superficie di estensione separata e piu profonda.

Rotazione delle chiavi API

Plugin provider ufficiali

I Plugin provider ufficiali pubblicano le proprie righe di catalogo modelli. Questi provider non richiedono voci modello in models.providers; abilita il Plugin provider, imposta l'autenticazione e scegli un modello. Usa models.providers solo per provider personalizzati espliciti o impostazioni di richiesta ristrette, come i timeout.

OpenAI

• Provider: openai
• Autenticazione: OPENAI_API_KEY
• Rotazione opzionale: OPENAI_API_KEYS, OPENAI_API_KEY_1, OPENAI_API_KEY_2, piu OPENCLAW_LIVE_OPENAI_KEY (override singolo)
• Modelli di esempio: openai/gpt-5.5, openai/gpt-5.4-mini
• Verifica la disponibilita di account/modello con openclaw models list --provider openai se una specifica installazione o chiave API si comporta diversamente.
• CLI: openclaw onboard --auth-choice openai-api-key
• Il trasporto predefinito e auto; OpenClaw passa la scelta del trasporto al runtime modello condiviso.
• Override per modello tramite agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket" o "auto")
• 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
• Gli header nascosti di attribuzione OpenClaw (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 store di Responses, suggerimenti per la cache dei prompt e shaping del payload di compatibilita con il reasoning OpenAI; le route proxy no
• openai/gpt-5.3-codex-spark e disponibile tramite autenticazione OAuth dell'abbonamento ChatGPT/Codex quando l'account con cui hai effettuato l'accesso lo espone; OpenClaw continua a sopprimere le route dirette con chiave API OpenAI e chiave API Azure per questo modello perche quei trasporti lo rifiutano

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

Anthropic

• Provider: anthropic
• Autenticazione: ANTHROPIC_API_KEY
• Rotazione opzionale: ANTHROPIC_API_KEYS, ANTHROPIC_API_KEY_1, ANTHROPIC_API_KEY_2, piu OPENCLAW_LIVE_ANTHROPIC_KEY (override singolo)
• 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 con chiave API e autenticato OAuth inviato a api.anthropic.com; OpenClaw lo mappa su service_tier di 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-8 con agentRuntime.id: "claude-cli" con scope modello. I riferimenti legacy claude-cli/claude-opus-4-7 continuano a funzionare per compatibilita.

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

OAuth OpenAI ChatGPT/Codex

• Provider: openai
• Autenticazione: OAuth (ChatGPT)
• Riferimento legacy al modello OpenAI Codex: openai/gpt-5.5
• Riferimento all'harness app-server Codex nativo: openai/gpt-5.5
• Documentazione dell'harness app-server Codex nativo: Harness Codex
• Riferimenti modello legacy: codex/gpt-*
• Confine Plugin: openai/* carica il Plugin OpenAI; il Plugin app-server Codex nativo viene selezionato dal runtime dell'harness Codex.
• CLI: openclaw onboard --auth-choice openai o openclaw models auth login --provider openai
• Il trasporto predefinito e auto (prima WebSocket, fallback SSE)
• Override per modello OpenAI Codex tramite agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket" o "auto")
• Anche params.serviceTier viene inoltrato sulle richieste Responses Codex native (chatgpt.com/backend-api)
• Gli header nascosti di attribuzione OpenClaw (originator, version, User-Agent) vengono allegati solo al traffico Codex nativo verso chatgpt.com/backend-api, non ai proxy generici compatibili con OpenAI
• Condivide lo stesso toggle /fast e la stessa configurazione params.fastMode di openai/* diretto; OpenClaw li mappa a service_tier=priority
• openai/gpt-5.5 usa il contextWindow = 400000 nativo del catalogo Codex e il runtime predefinito contextTokens = 272000; sovrascrivi il limite runtime con models.providers.openai.models[].contextTokens
• Nota di policy: OAuth OpenAI Codex e esplicitamente supportato per strumenti/workflow esterni come OpenClaw.
• Per la route comune con abbonamento piu runtime Codex nativo, accedi con autenticazione openai e configura openai/gpt-5.5; i turni agente OpenAI selezionano Codex per impostazione predefinita.
• Usa provider/modello agentRuntime.id: "openclaw" solo quando vuoi la route OpenClaw integrata; altrimenti mantieni openai/gpt-5.5 sull'harness Codex predefinito.
• i riferimenti legacy GPT Codex sono stato legacy, non una route provider live. Usa openai/gpt-5.5 sul runtime Codex nativo per la nuova configurazione agente ed esegui openclaw doctor --fix per migrare i vecchi riferimenti legacy ai modelli Codex nei riferimenti canonici openai/*.

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

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

Altre opzioni hosted in stile abbonamento

OpenCode

• Autenticazione: 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 o openclaw onboard --auth-choice opencode-go

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

Google Gemini (chiave API)

• Fornitore: google
• Autenticazione: GEMINI_API_KEY
• Rotazione opzionale: 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 OpenClaw legacy 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 omettono 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 fornitore cachedContents/...; gli hit della cache Gemini emergono come OpenClaw cacheRead

Google Vertex e Gemini CLI

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

Gemini CLI OAuth viene distribuito come parte del plugin google incluso.

brew install gemini-cli

npm install -g @google/gemini-cli

openclaw plugins enable google

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

Gemini CLI usa stream-json per impostazione predefinita. OpenClaw legge i messaggi dello stream dell'assistente e normalizza stats.cached in cacheRead; gli override legacy --output-format json continuano a leggere il testo della risposta da response.

Z.AI (GLM)

• Fornitore: zai
• Autenticazione: ZAI_API_KEY
• Modello di esempio: zai/glm-5.2
• CLI: openclaw onboard --auth-choice zai-api-key
  • I riferimenti ai modelli usano l'ID fornitore canonico 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

• Fornitore: vercel-ai-gateway
• Autenticazione: 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

Altri plugin di fornitori inclusi

Particolarità utili da conoscere

Fornitori tramite models.providers (URL custom/base)

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

Molti dei Plugin provider inclusi nel pacchetto 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 di origine Node passano le immagini come input nativi del modello invece che come riferimenti multimediali solo testuali.

agents.defaults.models["provider/model"] controlla solo la visibilità dei modelli, gli alias e i metadati per modello per gli agenti. Non registra da solo un nuovo modello runtime. Per i modelli di provider personalizzati, aggiungi anche models.providers.<provider>.models[] con almeno l'id corrispondente.

Moonshot AI (Kimi)

Installa @openclaw/moonshot-provider prima dell'onboarding. Aggiungi una voce esplicita models.providers.moonshot solo quando devi sovrascrivere l'URL di base o i metadati del modello:

• Provider: moonshot
• Auth: 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.7-code
• 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" }],      },    },  },}

Coding con Kimi

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

• Provider: kimi
• Auth: KIMI_API_KEY
• Modello di esempio: kimi/kimi-for-coding

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

I valori legacy kimi/kimi-code e kimi/k2p5 restano accettati come ID modello di compatibilità e vengono normalizzati all'ID modello API stabile di Kimi.

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 programmazione, ma il catalogo generale volcengine/* viene registrato nello stesso momento.

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

BytePlus (internazionale)

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

• Provider: byteplus (programmazione: byteplus-plan)
• Autenticazione: 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 programmazione, ma il catalogo generale byteplus/* viene registrato nello stesso momento.

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

Synthetic

Synthetic fornisce modelli compatibili con Anthropic tramite il provider synthetic:

• Provider: synthetic
• Autenticazione: 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 (globale): --auth-choice minimax-global-oauth
• MiniMax OAuth (CN): --auth-choice minimax-cn-oauth
• Chiave API MiniMax (globale): --auth-choice minimax-global-api
• Chiave API MiniMax (CN): --auth-choice minimax-cn-api
• Autenticazione: MINIMAX_API_KEY per minimax; MINIMAX_OAUTH_TOKEN o MINIMAX_API_KEY per minimax-portal

Consulta /providers/minimax per dettagli di configurazione, opzioni dei modelli e frammenti di configurazione.

Suddivisione delle capacità di proprietà del Plugin:

• I predefiniti per testo/chat rimangono su minimax/MiniMax-M3
• 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 rimane sull'ID provider minimax

LM Studio

LM Studio viene distribuito come Plugin provider in bundle che usa l'API nativa:

• Provider: lmstudio
• Autenticazione: LM_API_TOKEN
• URL base di inferenza predefinito: 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 e caricamento automatico, con /v1/chat/completions per impostazione predefinita per l'inferenza. Se vuoi che caricamento JIT, TTL ed 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 distribuito come Plugin provider in bundle e usa l'API nativa di Ollama:

• Provider: ollama
• Autenticazione: nessuna 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 con OLLAMA_API_KEY, e il Plugin provider in bundle aggiunge Ollama direttamente a openclaw onboard e al selettore di modello. Consulta /providers/ollama per onboarding, modalità cloud/locale e configurazione personalizzata.

vLLM

vLLM viene distribuito come Plugin provider in bundle per server locali/self-hosted compatibili con OpenAI:

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

Per abilitare l'auto-discovery localmente (qualsiasi valore va bene 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 distribuito come Plugin provider in bundle per server self-hosted veloci compatibili con OpenAI:

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

Per abilitare l'auto-discovery localmente (qualsiasi valore va bene 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-zenopenclaw models set opencode/claude-opus-4-6openclaw models list

Vedi anche: Configurazione per esempi completi di configurazione.

Correlati

• Riferimento di configurazione - chiavi di configurazione del modello
• Failover dei modelli - catene di fallback e comportamento di retry
• Modelli - configurazione e alias dei modelli
• Provider - guide di configurazione per provider