Provider di modelli

Riferimento per i 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 proprietà 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 dei modelli, mapping delle variabili d'ambiente per l'autenticazione, normalizzazione di trasporto/configurazione, pulizia degli schemi degli strumenti, classificazione del failover, refresh OAuth, report di utilizzo, profili di pensiero/ragionamento e altro.

L'elenco completo degli hook del provider SDK e degli esempi di Plugin in bundle si trova in Plugin provider. Un provider che richiede un esecutore di richieste totalmente personalizzato è una superficie di estensione separata e più profonda.

Rotazione delle chiavi API

Provider integrati (catalogo pi-ai)

OpenClaw viene fornito con il catalogo pi-ai. Questi provider non richiedono alcuna configurazione models.providers; basta impostare l'autenticazione e scegliere un modello.

OpenAI

• Provider: openai
• Auth: OPENAI_API_KEY
• Rotazione opzionale: OPENAI_API_KEYS, OPENAI_API_KEY_1, OPENAI_API_KEY_2, più OPENCLAW_LIVE_OPENAI_KEY (override singolo)
• Modelli di esempio: openai/gpt-5.5, openai/gpt-5.4-mini
• Verifica la disponibilità 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 è auto; OpenClaw passa la scelta del trasporto a pi-ai.
• Override per modello tramite agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket" o "auto")
• L'elaborazione prioritaria di OpenAI può essere abilitata tramite agents.defaults.models["openai/<model>"].params.serviceTier
• /fast e params.fastMode mappano le richieste Responses dirette openai/* su service_tier=priority su api.openai.com
• Usa params.serviceTier quando vuoi un tier esplicito invece del toggle condiviso /fast
• Le intestazioni di attribuzione nascoste di 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 prompt-cache e shaping del payload compatibile con il ragionamento OpenAI; le route proxy no
• openai/gpt-5.3-codex-spark è intenzionalmente soppresso in OpenClaw perché 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, più 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 autenticato con chiave API e OAuth inviato a api.anthropic.com; OpenClaw lo mappa su service_tier di Anthropic (auto vs standard_only)
• La configurazione Claude CLI preferita mantiene canonico il riferimento al modello e seleziona il backend CLI separatamente: anthropic/claude-opus-4-7 con agentRuntime.id: "claude-cli" nello scope del modello. I riferimenti legacy claude-cli/claude-opus-4-7 funzionano ancora per compatibilità.

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

OpenAI Codex OAuth

• Provider: openai-codex
• Auth: OAuth (ChatGPT)
• Riferimento modello PI legacy: openai-codex/gpt-5.5
• Riferimento 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-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 o openclaw models auth login --provider openai-codex
• Il trasporto predefinito è auto (prima WebSocket, fallback SSE)
• Override per modello PI tramite agents.defaults.models["openai-codex/<model>"].params.transport ("sse", "websocket" o "auto")
• Anche params.serviceTier viene inoltrato sulle richieste Responses Codex native (chatgpt.com/backend-api)
• Le intestazioni di attribuzione nascoste di OpenClaw (originator, version, User-Agent) vengono allegate 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 su service_tier=priority
• openai-codex/gpt-5.5 usa il catalogo Codex nativo contextWindow = 400000 e il runtime predefinito contextTokens = 272000; sovrascrivi il limite runtime con models.providers.openai-codex.models[].contextTokens
• Nota di policy: OpenAI Codex OAuth è esplicitamente supportato per strumenti/workflow esterni come OpenClaw.
• Per la route comune con abbonamento più runtime Codex nativo, accedi con autenticazione openai-codex ma configura openai/gpt-5.5; i turni agente OpenAI selezionano Codex per impostazione predefinita.
• Usa agentRuntime.id: "pi" di provider/modello solo quando vuoi una route di compatibilità tramite PI; altrimenti mantieni openai/gpt-5.5 sull'harness Codex predefinito.
• I riferimenti meno recenti openai-codex/gpt-5.1*, openai-codex/gpt-5.2* e openai-codex/gpt-5.3* sono soppressi perché gli account OAuth ChatGPT/Codex li rifiutano; usa invece openai-codex/gpt-5.5 o la route runtime Codex nativa.

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

{  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 o openclaw onboard --auth-choice opencode-go

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

Google Gemini (chiave API)

• Provider: google
• Autenticazione: GEMINI_API_KEY
• Rotazione facoltativa: fallback GEMINI_API_KEYS, GEMINI_API_KEY_1, GEMINI_API_KEY_2, 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 omette un thinkingLevel fisso; Gemini 2.5 invia thinkingBudget: -1.
• Le esecuzioni dirette di Gemini 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 OpenClaw cacheRead

Google Vertex e Gemini CLI

• Provider: google-vertex, google-gemini-cli
• Autenticazione: Vertex usa ADC di gcloud; 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

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

Z.AI (GLM)

• Provider: zai
• Autenticazione: 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
• 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

Kilo Gateway

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

Consulta /providers/kilocode per i dettagli di configurazione.

Altri Plugin provider inclusi

Particolarità utili da conoscere

Fornitori tramite models.providers (personalizzati/URL di base)

Usa models.providers (o models.json) per aggiungere fornitori 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.

Anche i controlli delle capacità dei modelli del Gateway leggono 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.

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

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:

• Fornitore: 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:

• Fornitore: kimi
• Autenticazione: KIMI_API_KEY
• Modello di esempio: kimi/kimi-for-coding

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

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

• Fornitore: volcengine (coding: volcengine-plan)
• Autenticazione: 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 come predefinita la superficie di coding, ma il catalogo generale volcengine/* viene registrato nello stesso momento.

Nei selettori di modello di onboarding/configurazione, 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 limitato al fornitore.

BytePlus (internazionale)

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

• Fornitore: byteplus (coding: 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 come predefinita la superficie di coding, ma il catalogo generale byteplus/* viene registrato nello stesso momento.

Nei selettori di modello di onboarding/configurazione, 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 limitato al fornitore.

Synthetic

Synthetic fornisce modelli compatibili con Anthropic dietro il fornitore synthetic:

• Fornitore: 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 è 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 i dettagli di configurazione, le opzioni dei modelli e gli snippet di configurazione.

Suddivisione delle capability di proprietà del Plugin:

• I predefiniti per 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 fornitore minimax

LM Studio

LM Studio è distribuito come Plugin fornitore incluso che usa l'API nativa:

• Fornitore: lmstudio
• Autenticazione: 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 i nativi /api/v1/models e /api/v1/models/load di LM Studio per discovery + caricamento automatico, con /v1/chat/completions per l'inferenza per impostazione predefinita. Se vuoi che il caricamento JIT, il TTL e l'auto-evict 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 è distribuito come Plugin fornitore incluso e usa l'API nativa di Ollama:

• Fornitore: ollama
• Autenticazione: nessuna richiesta (server locale)
• Modello di esempio: ollama/llama3.3
• Installazione: https://ollama.com/download

# Installa Ollama, poi scarica un modello:ollama pull llama3.3

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

Ollama viene rilevato localmente su http://127.0.0.1:11434 quando abiliti esplicitamente con OLLAMA_API_KEY, e il Plugin fornitore 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 è distribuito come Plugin fornitore incluso per server locali/self-hosted compatibili con OpenAI:

• Fornitore: vllm
• Autenticazione: facoltativa (dipende dal tuo server)
• URL di base predefinito: http://127.0.0.1:8000/v1

Per abilitare esplicitamente la discovery automatica locale (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 è distribuito come Plugin fornitore incluso per server self-hosted veloci compatibili con OpenAI:

• Fornitore: sglang
• Autenticazione: facoltativa (dipende dal tuo server)
• URL di base predefinito: http://127.0.0.1:30000/v1

Per abilitare esplicitamente la discovery automatica locale (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 dei modelli e alias
• Fornitori - guide di configurazione per fornitore