Configurazione — strumenti e provider personalizzati

Voce provider (type: "provider" oppure omessa):

• provider: id del provider API (openai, anthropic, google/gemini, groq, ecc.)
• model: sovrascrittura dell'id modello
• profile / preferredProfile: selezione del profilo auth-profiles.json

Voce CLI (type: "cli"):

• command: eseguibile da avviare
• args: argomenti basati su template (supporta {{MediaPath}}, {{Prompt}}, {{MaxChars}}, ecc.; openclaw doctor --fix migra i placeholder deprecati {input} a {{MediaPath}})

Campi comuni:

• capabilities: elenco facoltativo (image, audio, video). Valori predefiniti: openai/anthropic/minimax → immagine, google → immagine+audio+video, groq → audio.
• prompt, maxChars, maxBytes, timeoutSeconds, language: sovrascritture per voce.
• Anche tools.media.image.timeoutSeconds e le voci timeoutSeconds dei modelli immagine corrispondenti si applicano quando l'agente chiama lo strumento image esplicito.
• Gli errori ripiegano sulla voce successiva.

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

Campi di completamento asincrono:

• asyncCompletion.directSend: flag di compatibilità deprecato. Le attività media asincrone completate restano mediate dalla sessione del richiedente, così l'agente riceve il risultato, decide come comunicarlo all'utente e usa lo strumento messaggio quando la consegna della sorgente 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 esegui sessioni per mittente con lo stesso id agente).
• all: qualsiasi sessione. L'indirizzamento tra agenti richiede comunque tools.agentToAgent.
• Limitazione sandbox: quando la sessione corrente è in sandbox e agents.defaults.sandbox.sessionToolsVisibility="spawned", la visibilità viene forzata a tree anche se tools.sessions.visibility="all".

• Gli allegati sono supportati solo per runtime: "subagent". Il runtime ACP li rifiuta.
• I file vengono materializzati nello spazio di lavoro figlio in .openclaw/attachments/<uuid>/ con un .manifest.json.
• Il contenuto degli allegati viene automaticamente oscurato dalla persistenza della trascrizione.
• Gli input Base64 vengono convalidati con controlli rigorosi di alfabeto/padding e una protezione sulla dimensione prima della decodifica.
• I permessi dei file sono 0700 per le directory e 0600 per i file.
• La pulizia 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.
• Esegui l'override della radice della configurazione dell'agente con OPENCLAW_AGENT_DIR (o PI_CODING_AGENT_DIR, un alias legacy di variabile d'ambiente).
• Precedenza del merge per ID provider corrispondenti:
  • Vincono i valori baseUrl non vuoti di models.json dell'agente.
  • I valori apiKey non vuoti dell'agente vincono solo quando quel provider non è gestito da SecretRef nel contesto corrente di configurazione/profilo di autenticazione.
  • I valori apiKey dei provider gestiti da SecretRef vengono aggiornati dai marker sorgente (ENV_VAR_NAME per i riferimenti env, secretref-managed per i riferimenti file/exec) invece di persistere i segreti risolti.
  • I valori degli header dei provider gestiti da SecretRef vengono aggiornati dai marker sorgente (secretref-env:ENV_VAR_NAME per i riferimenti env, secretref-managed per i riferimenti file/exec).
  • apiKey/baseUrl dell'agente vuoti o mancanti ricadono su models.providers nella configurazione.
  • contextWindow/maxTokens del modello corrispondente usano il valore più alto tra la configurazione esplicita e i valori impliciti del catalogo.
  • contextTokens del modello corrispondente conserva un limite runtime esplicito quando presente; usalo per limitare il contesto effettivo senza modificare i metadati nativi del modello.
  • Usa models.mode: "replace" quando vuoi che la configurazione riscriva completamente models.json.
  • La persistenza dei marker è autorevole rispetto alla sorgente: i marker vengono scritti dallo snapshot della configurazione sorgente attiva (prima della risoluzione), non dai valori dei segreti risolti a runtime.

• models.mode: comportamento del catalogo provider (merge o replace).
• models.providers: mappa di provider personalizzati 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 additivi. config set rifiuta sostituzioni distruttive salvo che tu passi --replace.

• models.providers.*.api: adattatore della richiesta (openai-completions, openai-responses, anthropic-messages, google-generative-ai, ecc.). Per backend self-hosted /v1/chat/completions 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/sostituzione env).
• models.providers.*.auth: strategia di autenticazione (api-key, token, oauth, aws-sdk).
• models.providers.*.contextWindow: finestra di contesto nativa predefinita per i modelli sotto questo provider quando la voce del modello non imposta contextWindow.
• models.providers.*.contextTokens: limite di contesto runtime effettivo predefinito per i modelli sotto questo provider quando la voce del modello non imposta contextTokens.
• models.providers.*.maxTokens: limite predefinito di token di output per i modelli sotto questo provider quando la voce del modello non imposta maxTokens.
• models.providers.*.timeoutSeconds: timeout opzionale, per provider, della richiesta HTTP del modello in secondi, inclusi connessione, header, body e gestione dell'annullamento totale della richiesta.
• models.providers.*.injectNumCtxForOpenAICompat: per Ollama + openai-completions, inietta options.num_ctx nelle richieste (predefinito: true).
• models.providers.*.authHeader: forza il trasporto della credenziale nell'header Authorization quando richiesto.
• models.providers.*.baseUrl: URL di base dell'API upstream.
• models.providers.*.headers: header statici extra per routing proxy/tenant.

models.providers.*.request: override del trasporto per le richieste HTTP al provider di modelli.

• request.headers: header extra (uniti ai valori predefiniti del provider). I valori accettano SecretRef.
• request.auth: override della strategia di autenticazione. Modalità: "provider-default" (usa l'autenticazione integrata del provider), "authorization-bearer" (con token), "header" (con headerName, value, prefix opzionale).
• request.proxy: override 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 opzionale.
• request.tls: override TLS per connessioni dirette. Campi: ca, cert, key, passphrase (tutti accettano SecretRef), serverName, insecureSkipVerify.
• request.allowPrivateNetwork: quando true, consente HTTPS verso baseUrl quando il DNS si risolve in intervalli privati, CGNAT o simili, tramite la protezione fetch HTTP del provider (opt-in dell'operatore per endpoint compatibili con OpenAI self-hosted attendibili). Gli URL di stream dei provider di modelli local loopback come localhost, 127.0.0.1 e [::1] sono consentiti automaticamente salvo che questo sia esplicitamente impostato su false; gli host LAN, tailnet e DNS privati richiedono comunque opt-in. WebSocket usa lo stesso request per header/TLS, ma non quel gate SSRF di fetch. Predefinito false.

• models.providers.*.models: voci esplicite del catalogo modelli del provider.
• models.providers.*.models.*.input: modalità di input del modello. Usa ["text"] per modelli solo testo e ["text", "image"] per modelli immagine/visione nativi. Gli allegati immagine vengono iniettati nei turni dell'agente solo quando il modello selezionato è marcato come capace di gestire immagini.
• models.providers.*.models.*.contextWindow: metadati della finestra di contesto nativa del modello. Questo esegue l'override di contextWindow a livello provider per quel modello.
• models.providers.*.models.*.contextTokens: limite di contesto runtime opzionale. Questo esegue l'override di contextTokens a livello provider; usalo quando vuoi un budget di contesto effettivo più piccolo rispetto al contextWindow nativo del modello; openclaw models list mostra entrambi i valori quando differiscono.
• models.providers.*.models.*.compat.supportsDeveloperRole: suggerimento di compatibilità opzionale. Per api: "openai-completions" con un baseUrl non nativo e non vuoto (host diverso da api.openai.com), OpenClaw lo forza a false a runtime. baseUrl vuoto/omesso mantiene il comportamento OpenAI predefinito.
• models.providers.*.models.*.compat.requiresStringContent: suggerimento di compatibilità opzionale per endpoint chat compatibili con OpenAI solo stringa. Quando true, OpenClaw appiattisce gli array di puro testo messages[].content in stringhe semplici prima di inviare la richiesta.
• models.providers.*.models.*.compat.strictMessageKeys: suggerimento di compatibilità opzionale per endpoint chat compatibili con OpenAI rigorosi. Quando true, OpenClaw riduce gli oggetti messaggio Chat Completions in uscita a role e content prima di inviare la richiesta.
• models.providers.*.models.*.compat.thinkingFormat: suggerimento opzionale per il payload di ragionamento. Usa "qwen" per enable_thinking di primo livello, oppure "qwen-chat-template" per chat_template_kwargs.enable_thinking su server compatibili con OpenAI della famiglia Qwen che supportano kwargs del chat template a livello di richiesta, come vLLM.

• plugins.entries.amazon-bedrock.config.discovery: radice delle impostazioni di discovery automatica Bedrock.
• plugins.entries.amazon-bedrock.config.discovery.enabled: attiva/disattiva la discovery implicita.
• plugins.entries.amazon-bedrock.config.discovery.region: regione AWS per la discovery.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: filtro opzionale per ID provider per discovery mirata.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: intervallo di polling per l'aggiornamento della discovery.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: finestra di contesto di fallback per i modelli scoperti.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: token di output massimi di fallback per i modelli scoperti.

Il Plugin provider cerebras incluso può configurarlo tramite openclaw onboard --auth-choice cerebras-api-key. Usa la configurazione esplicita del provider solo quando sovrascrivi 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 Z.AI diretto.

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

Compatibile con Anthropic, provider integrato. Scorciatoia: openclaw onboard --auth-choice kimi-code-api-key.

Vedi Modelli locali. TL;DR: esegui un modello locale di grandi dimensioni tramite la Responses API di LM Studio su hardware serio; mantieni i modelli ospitati uniti come fallback.

{  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M2.7" },      models: {        "minimax/MiniMax-M2.7": { alias: "Minimax" },      },    },  },  models: {    mode: "merge",    providers: {      minimax: {        baseUrl: "https://api.minimax.io/anthropic",        apiKey: "${MINIMAX_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "MiniMax-M2.7",            name: "MiniMax M2.7",            reasoning: true,            input: ["text"],            cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },            contextWindow: 204800,            maxTokens: 131072,          },        ],      },    },  },}

Imposta MINIMAX_API_KEY. Scorciatoie: openclaw onboard --auth-choice minimax-global-api o openclaw onboard --auth-choice minimax-cn-api. Il catalogo dei modelli predefinito include solo M2.7. Nel percorso di streaming compatibile con Anthropic, OpenClaw disabilita il thinking di MiniMax per impostazione predefinita, a meno che tu non imposti esplicitamente thinking. /fast on o params.fastMode: true riscrive MiniMax-M2.7 in 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 Cina: baseUrl: "https://api.moonshot.cn/v1" o openclaw onboard --auth-choice moonshot-api-key-cn.

Gli endpoint Moonshot nativi dichiarano compatibilità con l'uso dello streaming sul trasporto condiviso openai-completions, e OpenClaw lo determina in base alle capacità dell'endpoint anziché al solo ID del provider integrato.

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

Imposta OPENCODE_API_KEY (o OPENCODE_ZEN_API_KEY). Usa i riferimenti opencode/... per il catalogo Zen oppure i riferimenti opencode-go/... per il catalogo Go. Scorciatoia: openclaw onboard --auth-choice opencode-zen o 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. z.ai/* e z-ai/* sono alias accettati. Scorciatoia: openclaw onboard --auth-choice zai-api-key.

• Endpoint generale: https://api.z.ai/api/paas/v4
• Endpoint di codifica (predefinito): https://api.z.ai/api/coding/paas/v4
• Per l'endpoint generale, definisci un provider personalizzato con override dell'URL di base.