Configurazione — strumenti e provider personalizzati

Voce del provider (type: "provider" oppure omesso):

• provider: ID del provider API (openai, anthropic, google/gemini, groq e così via)
• model: sostituzione dell'ID del modello
• profile / preferredProfile: selezione del profilo di auth-profiles.json

Voce CLI (type: "cli"):

• command: eseguibile da avviare
• args: argomenti basati su modello (supportano {{MediaPath}}, {{Prompt}}, {{MaxChars}} e così via; openclaw doctor --fix migra i segnaposto deprecati {input} a {{MediaPath}})

Campi comuni:

• capabilities: elenco facoltativo (image, audio, video). Ogni Plugin del provider dichiara il proprio insieme predefinito di funzionalità; ad esempio, il provider openai incluso utilizza per impostazione predefinita immagine+audio, anthropic/minimax immagine, google immagine+audio+video e groq audio.
• prompt, maxChars, maxBytes, timeoutSeconds, language: sostituzioni per singola voce.
• tools.media.image.timeoutSeconds e le corrispondenti voci timeoutSeconds del modello di immagini si applicano anche quando l'agente chiama esplicitamente lo strumento image. Per la comprensione delle immagini, questo timeout si applica alla richiesta stessa e non viene ridotto dal precedente lavoro di preparazione.
• In caso di errore, si passa alla voce successiva.

L'autenticazione del provider segue l'ordine standard: auth-profiles.json → variabili di ambiente → models.providers.*.apiKey.

Campi del completamento asincrono:

• asyncCompletion.directSend: flag di compatibilità deprecato. Le attività multimediali asincrone completate restano mediate dalla sessione del richiedente, in modo che l'agente riceva il risultato, decida come comunicarlo all'utente e utilizzi lo strumento per i messaggi quando la consegna all'origine lo richiede.

• self: solo la chiave della sessione corrente.
• tree: sessione corrente + sessioni generate dalla sessione corrente (sottoagenti).
• agent: qualsiasi sessione appartenente all'ID dell'agente corrente (può includere altri utenti se si eseguono sessioni per mittente con lo stesso ID agente).
• all: qualsiasi sessione. La selezione tra agenti richiede comunque tools.agentToAgent.
• Limitazione della sandbox: quando la sessione corrente è in una sandbox e agents.defaults.sandbox.sessionToolsVisibility="spawned" (valore predefinito), la visibilità viene forzata a tree anche se tools.sessions.visibility="all".
• Quando il valore non è all, sessions_list include un campo compatto visibility che descrive la modalità effettiva e un avviso che alcune sessioni al di fuori dell'ambito corrente potrebbero essere omesse.

• Gli allegati richiedono enabled: true.
• Gli allegati dei sottoagenti vengono materializzati nell'area di lavoro figlia in .openclaw/attachments/<uuid>/ con un file .manifest.json.
• Gli allegati ACP sono limitati alle immagini e vengono inoltrati in linea al runtime ACP dopo aver superato gli stessi limiti relativi al numero di file, ai byte per file e ai byte totali.
• Il contenuto degli allegati viene automaticamente oscurato nella persistenza della trascrizione.
• Gli input Base64 vengono convalidati mediante controlli rigorosi dell'alfabeto e del riempimento, oltre a una protezione sulle dimensioni prima della decodifica.
• I permessi dei file allegati dei sottoagenti sono 0700 per le directory e 0600 per i file.
• La pulizia dei sottoagenti segue la policy cleanup: delete rimuove sempre gli allegati; keep li conserva solo quando retainOnSessionKeep: true.

• Usa authHeader: true + headers per esigenze di autenticazione personalizzate.
• Sovrascrivi la radice della configurazione dell'agente con OPENCLAW_AGENT_DIR.
• Precedenza di unione per gli ID provider corrispondenti:
  • I valori baseUrl non vuoti del file models.json dell'agente hanno la precedenza.
  • I valori apiKey non vuoti dell'agente hanno la precedenza solo quando il provider non è gestito tramite SecretRef nel contesto corrente di configurazione/profilo di autenticazione.
  • I valori apiKey dei provider gestiti tramite SecretRef vengono aggiornati dagli indicatori di origine (ENV_VAR_NAME per i riferimenti alle variabili d'ambiente, secretref-managed per i riferimenti a file/exec), anziché rendere persistenti i segreti risolti.
  • I valori delle intestazioni dei provider gestiti tramite SecretRef vengono aggiornati dagli indicatori di origine (secretref-env:ENV_VAR_NAME per i riferimenti alle variabili d'ambiente, secretref-managed per i riferimenti a file/exec).
  • Se apiKey/baseUrl dell'agente sono vuoti o mancanti, vengono usati come ripiego i valori di models.providers nella configurazione.
  • Per contextWindow/maxTokens di un modello corrispondente, il valore esplicito della configurazione ha la precedenza quando è presente e valido (un numero finito positivo); altrimenti viene usato il valore implicito/generato del catalogo.
  • contextTokens di un modello corrispondente segue la stessa regola: il valore esplicito ha la precedenza, altrimenti viene usato quello implicito; usalo per limitare il contesto effettivo senza modificare i metadati nativi del modello.
  • I cataloghi dei Plugin provider vengono archiviati come frammenti di catalogo generati e di proprietà del Plugin nello stato dei Plugin dell'agente.
  • Usa models.mode: "replace" quando vuoi che la configurazione riscriva completamente models.json e ignori l'unione dei frammenti di catalogo di proprietà dei Plugin.
  • La persistenza degli indicatori è determinata dall'origine: gli indicatori vengono scritti dall'istantanea attiva della configurazione di origine (prima della risoluzione), non dai valori segreti risolti in fase di esecuzione.

• models.mode: comportamento del catalogo dei provider (merge o replace).
• models.providers: mappa personalizzata dei provider indicizzata per ID provider.
  • Modifiche sicure: usa openclaw config set models.providers.<id> '<json>' --strict-json --merge oppure openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge per aggiornamenti incrementali. config set rifiuta le sostituzioni distruttive, a meno che non venga specificato --replace.

• models.providers.*.api: adattatore delle richieste (openai-completions, openai-responses, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, azure-openai-responses). Per backend /v1/chat/completions con hosting autonomo, come MLX, vLLM, SGLang e la maggior parte dei server locali compatibili con OpenAI, usa openai-completions. Un provider personalizzato con baseUrl ma senza api usa per impostazione predefinita openai-completions; imposta openai-responses solo quando il backend supporta /v1/responses.
• models.providers.*.apiKey: credenziale del provider (preferisci SecretRef o la sostituzione tramite variabili d'ambiente).
• models.providers.*.auth: strategia di autenticazione (api-key, token, oauth, aws-sdk).
• models.providers.*.contextWindow: finestra di contesto nativa predefinita per i modelli di questo provider quando la voce del modello non imposta contextWindow.
• models.providers.*.contextTokens: limite effettivo predefinito del contesto in fase di esecuzione per i modelli di questo provider quando la voce del modello non imposta contextTokens.
• models.providers.*.maxTokens: limite predefinito dei token di output per i modelli di questo provider quando la voce del modello non imposta maxTokens.
• models.providers.*.timeoutSeconds: timeout facoltativo, specifico per provider e espresso in secondi, per le richieste HTTP al modello; include connessione, intestazioni, corpo e gestione dell'interruzione complessiva della richiesta.
• models.providers.*.injectNumCtxForOpenAICompat: per Ollama + openai-completions, inserisce options.num_ctx nelle richieste (impostazione predefinita: true).
• models.providers.*.authHeader: forza il trasporto delle credenziali nell'intestazione Authorization quando necessario.
• models.providers.*.baseUrl: URL di base dell'API upstream.
• models.providers.*.headers: intestazioni statiche aggiuntive per l'instradamento tramite proxy/tenant.

models.providers.*.request: sovrascritture del trasporto per le richieste HTTP al provider del modello.

• request.headers: intestazioni aggiuntive (unite alle impostazioni predefinite del provider). I valori accettano SecretRef.
• request.auth: sovrascrittura della strategia di autenticazione. Modalità: "provider-default" (usa l'autenticazione integrata del provider), "authorization-bearer" (con token), "header" (con headerName, value e prefix facoltativo).
• request.proxy: sovrascrittura del proxy HTTP. Modalità: "env-proxy" (usa le variabili d'ambiente HTTP_PROXY/HTTPS_PROXY), "explicit-proxy" (con url). Entrambe le modalità accettano un sotto-oggetto tls facoltativo.
• request.tls: sovrascrittura TLS per le connessioni dirette. Campi: ca, cert, key, passphrase (tutti accettano SecretRef), serverName, insecureSkipVerify.
• request.allowPrivateNetwork: quando è true, consente alle richieste HTTP al provider del modello di raggiungere intervalli privati, CGNAT o simili attraverso la protezione delle richieste HTTP del provider. Gli URL di base dei provider personalizzati/locali considerano già attendibile l'origine esatta configurata, tranne le origini di metadati/link-local, che rimangono bloccate senza consenso esplicito. Imposta questo valore su false per disattivare l'attendibilità dell'origine esatta. WebSocket usa la stessa configurazione request per intestazioni/TLS, ma non quella protezione SSRF delle richieste. Valore predefinito: false.

• models.providers.*.models: voci esplicite del catalogo dei modelli del provider.
• models.providers.*.models.*.input: modalità di input del modello. Usa ["text"] per i modelli di solo testo e ["text", "image"] per i modelli nativi con supporto di immagini/visione. Gli allegati immagine vengono inseriti nei turni dell'agente solo quando il modello selezionato è contrassegnato come compatibile con le immagini.
• models.providers.*.models.*.contextWindow: metadati della finestra di contesto nativa del modello. Per questo modello, sostituisce contextWindow a livello di provider.
• models.providers.*.models.*.contextTokens: limite facoltativo del contesto in fase di esecuzione. Sostituisce contextTokens a livello di provider; usalo quando vuoi un budget di contesto effettivo inferiore rispetto a contextWindow nativo del modello; openclaw models list mostra entrambi i valori quando sono diversi.
• models.providers.*.models.*.compat.supportsDeveloperRole: indicazione facoltativa di compatibilità. Per api: "openai-completions" con un baseUrl non vuoto e non nativo (host diverso da api.openai.com), OpenClaw forza questo valore su false in fase di esecuzione. Un baseUrl vuoto/omesso mantiene il comportamento predefinito di OpenAI.
• models.providers.*.models.*.compat.requiresStringContent: indicazione facoltativa di compatibilità per gli endpoint di chat compatibili con OpenAI che accettano solo stringhe. Quando è true, OpenClaw appiattisce gli array messages[].content contenenti solo testo in semplici stringhe prima di inviare la richiesta.
• models.providers.*.models.*.compat.strictMessageKeys: indicazione facoltativa di compatibilità per gli endpoint di chat compatibili con OpenAI con requisiti rigidi. Quando è true, OpenClaw riduce gli oggetti dei messaggi Chat Completions in uscita ai soli campi role e content prima di inviare la richiesta.
• models.providers.*.models.*.compat.thinkingFormat: indicazione facoltativa sul payload di ragionamento. Usa "together" per reasoning.enabled in stile Together, "qwen" per enable_thinking di primo livello oppure "qwen-chat-template" per chat_template_kwargs.enable_thinking sui server compatibili con OpenAI della famiglia Qwen che supportano gli argomenti della chat template a livello di richiesta, come vLLM. I modelli Qwen vLLM configurati espongono scelte binarie /think (off, on) per questi formati.
• models.providers.*.models.*.compat.requiresReasoningContentOnAssistantMessages: indicazione facoltativa di compatibilità per i backend Chat Completions in stile DeepSeek che richiedono che i messaggi precedenti dell'assistente mantengano reasoning_content durante la riproduzione. Quando è true, OpenClaw conserva tale campo nei messaggi dell'assistente in uscita. Usalo quando colleghi un proxy personalizzato compatibile con DeepSeek che rifiuta le richieste dopo la rimozione del ragionamento. Valore predefinito: false.

• plugins.entries.amazon-bedrock.config.discovery: radice delle impostazioni di rilevamento automatico di Bedrock.
• plugins.entries.amazon-bedrock.config.discovery.enabled: attiva/disattiva il rilevamento implicito.
• plugins.entries.amazon-bedrock.config.discovery.region: regione AWS per il rilevamento.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: filtro facoltativo per ID provider per il rilevamento mirato.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: intervallo di polling per l'aggiornamento del rilevamento.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: finestra di contesto di ripiego per i modelli rilevati.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: numero massimo di token di output di ripiego per i modelli rilevati.

Il Plugin provider esterno ufficiale cerebras può configurarlo tramite openclaw onboard --auth-choice cerebras-api-key. Usa una configurazione esplicita del provider solo per sostituire le impostazioni predefinite.

{  env: { CEREBRAS_API_KEY: "sk-..." },  agents: {    defaults: {      model: {        primary: "cerebras/zai-glm-4.7",        fallbacks: ["cerebras/gpt-oss-120b"],      },      models: {        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },        "cerebras/gpt-oss-120b": { alias: "GPT OSS 120B (Cerebras)" },      },    },  },  models: {    mode: "merge",    providers: {      cerebras: {        baseUrl: "https://api.cerebras.ai/v1",        apiKey: "${CEREBRAS_API_KEY}",        api: "openai-completions",        models: [          { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },          { id: "gpt-oss-120b", name: "GPT OSS 120B (Cerebras)" },        ],      },    },  },}

Usa cerebras/zai-glm-4.7 per Cerebras; zai/glm-4.7 per l'accesso diretto a Z.AI.

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

Provider integrato compatibile con Anthropic. Scorciatoia: openclaw onboard --auth-choice kimi-code-api-key.

Consulta Modelli locali. In breve: esegui un modello locale di grandi dimensioni tramite l'API Responses di LM Studio su hardware potente; mantieni integrati i modelli ospitati come soluzione di riserva.

{  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M3" },      models: {        "minimax/MiniMax-M3": { alias: "Minimax" },      },    },  },  models: {    mode: "merge",    providers: {      minimax: {        baseUrl: "https://api.minimax.io/anthropic",        apiKey: "${MINIMAX_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "MiniMax-M3",            name: "MiniMax M3",            reasoning: true,            input: ["text", "image"],            cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 },            contextWindow: 1000000,            maxTokens: 131072,          },        ],      },    },  },}

Imposta MINIMAX_API_KEY. Scorciatoie: openclaw onboard --auth-choice minimax-global-api oppure openclaw onboard --auth-choice minimax-cn-api. Il catalogo dei modelli usa M3 come valore predefinito e include anche le varianti M2.7. Nel percorso di streaming compatibile con Anthropic, OpenClaw disabilita per impostazione predefinita il ragionamento di MiniMax M2.x, a meno che tu non imposti esplicitamente thinking; MiniMax-M3 (e M3.x) mantiene invece per impostazione predefinita il percorso di ragionamento omesso/adattivo del provider. /fast on oppure params.fastMode: true sostituisce MiniMax-M2.7 con MiniMax-M2.7-highspeed.

{  env: { MOONSHOT_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "moonshot/kimi-k2.6" },      models: { "moonshot/kimi-k2.6": { alias: "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",            reasoning: false,            input: ["text", "image"],            cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },            contextWindow: 262144,            maxTokens: 262144,          },        ],      },    },  },}

Per l'endpoint cinese: baseUrl: "https://api.moonshot.cn/v1" oppure openclaw onboard --auth-choice moonshot-api-key-cn.

Gli endpoint nativi di Moonshot dichiarano la compatibilità dell'utilizzo in streaming sul trasporto condiviso openai-completions e OpenClaw la determina in base alle funzionalità dell'endpoint, anziché basarsi esclusivamente sull'ID integrato del provider.

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

Imposta OPENCODE_API_KEY (oppure OPENCODE_ZEN_API_KEY). Usa riferimenti opencode/... per il catalogo Zen oppure riferimenti opencode-go/... per il catalogo Go. Scorciatoia: openclaw onboard --auth-choice opencode-zen oppure openclaw onboard --auth-choice opencode-go.

{  env: { SYNTHETIC_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "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",            reasoning: true,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 192000,            maxTokens: 65536,          },        ],      },    },  },}

L'URL di base deve omettere /v1 (il client Anthropic lo aggiunge). Scorciatoia: openclaw onboard --auth-choice synthetic-api-key.

{  agents: {    defaults: {      model: { primary: "zai/glm-4.7" },      models: { "zai/glm-4.7": {} },    },  },}

Imposta ZAI_API_KEY. I riferimenti ai modelli usano l'ID canonico del provider zai/*. Scorciatoia: openclaw onboard --auth-choice zai-api-key.

• Endpoint generale: https://api.z.ai/api/paas/v4
• Endpoint per la programmazione: https://api.z.ai/api/coding/paas/v4
• L'opzione di autenticazione predefinita zai-api-key verifica la chiave e rileva automaticamente a quale endpoint appartiene; se il rilevamento non è conclusivo, mostra una richiesta, con Global come valore predefinito. Sono disponibili anche opzioni di autenticazione dedicate per CN e Coding-Plan, per una selezione esplicita.
• Per l'endpoint generale, definisci un provider personalizzato sostituendo l'URL di base.