--- read_when: - Configurazione del criterio `tools.*`, degli elenchi consentiti o delle funzionalità sperimentali - Registrazione di provider personalizzati o override degli URL di base - Configurazione di endpoint auto-ospitati compatibili con OpenAI sidebarTitle: Tools and custom providers summary: Configurazione degli strumenti (criteri, opzioni sperimentali, strumenti supportati da provider) e configurazione di provider/URL di base personalizzati title: Configurazione — strumenti e provider personalizzati x-i18n: generated_at: "2026-05-11T20:28:54Z" model: gpt-5.5 provider: openai source_hash: c9ab0ec823da1e2e8598d9efb998a207c4486ba82dcf4dd65422c6bf90581b46 source_path: gateway/config-tools.md workflow: 16 --- Chiavi di configurazione `tools.*` e configurazione di provider personalizzati / URL di base. Per agenti, canali e altre chiavi di configurazione di primo livello, consulta il [Riferimento alla configurazione](/it/gateway/configuration-reference). ## Strumenti ### Profili degli strumenti `tools.profile` imposta una allowlist di base prima di `tools.allow`/`tools.deny`: L'onboarding locale imposta per default le nuove configurazioni locali su `tools.profile: "coding"` quando non è impostato (i profili espliciti esistenti vengono preservati). | Profilo | Include | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `minimal` | solo `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | | `full` | Nessuna restrizione (come se non fosse impostato) | ### Gruppi di strumenti | Gruppo | Strumenti | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | | `group:runtime` | `exec`, `process`, `code_execution` (`bash` è accettato come alias per `exec`) | | `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | | `group:memory` | `memory_search`, `memory_get` | | `group:web` | `web_search`, `x_search`, `web_fetch` | | `group:ui` | `browser`, `canvas` | | `group:automation` | `heartbeat_respond`, `cron`, `gateway` | | `group:messaging` | `message` | | `group:nodes` | `nodes` | | `group:agents` | `agents_list`, `update_plan` | | `group:media` | `image`, `image_generate`, `music_generate`, `video_generate`, `tts` | | `group:openclaw` | Tutti gli strumenti integrati (esclude i plugin del provider) | ### `tools.allow` / `tools.deny` Policy globale di allow/deny degli strumenti (deny prevale). Non distingue tra maiuscole e minuscole, supporta i caratteri jolly `*`. Applicata anche quando la sandbox Docker è disattivata. ```json5 { tools: { deny: ["browser", "canvas"] }, } ``` `write` e `apply_patch` sono ID di strumenti separati. `allow: ["write"]` abilita anche `apply_patch` per i modelli compatibili, ma `deny: ["write"]` non nega `apply_patch`. Per bloccare tutte le mutazioni dei file, nega `group:fs` o elenca esplicitamente ogni strumento che modifica: ```json5 { tools: { deny: ["write", "edit", "apply_patch"] }, } ``` ### `tools.byProvider` Limita ulteriormente gli strumenti per provider o modelli specifici. Ordine: profilo di base → profilo del provider → allow/deny. ```json5 { tools: { profile: "coding", byProvider: { "google-antigravity": { profile: "minimal" }, "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] }, }, }, } ``` ### `tools.toolsBySender` Limita gli strumenti per un'identità richiedente specifica. Questa è una difesa in profondità oltre al controllo di accesso del canale; i valori del mittente devono provenire dall'adapter del canale, non dal testo del messaggio. ```json5 { tools: { toolsBySender: { "channel:discord:1234567890123": { alsoAllow: ["group:fs"] }, "id:guest-user-id": { deny: ["group:runtime", "group:fs"] }, "*": { deny: ["exec", "process", "write", "edit", "apply_patch"] }, }, }, } ``` Le chiavi usano prefissi espliciti: `channel::`, `id:`, `e164:`, `username:`, `name:`, oppure `"*"`. Gli ID dei canali sono ID canonici OpenClaw; alias come `teams` vengono normalizzati in `msteams`. Le chiavi legacy senza prefisso sono accettate solo come `id:`. L'ordine di corrispondenza è channel+id, id, e164, username, name, poi carattere jolly. `agents.list[].tools.toolsBySender` per agente sostituisce la corrispondenza globale del mittente quando corrisponde, anche con una policy vuota `{}`. ### `tools.elevated` Controlla l'accesso exec elevato fuori dalla sandbox: ```json5 { tools: { elevated: { enabled: true, allowFrom: { whatsapp: ["+15555550123"], discord: ["1234567890123", "987654321098765432"], }, }, }, } ``` - L'override per agente (`agents.list[].tools.elevated`) può solo restringere ulteriormente. - `/elevated on|off|ask|full` memorizza lo stato per sessione; le direttive inline si applicano al singolo messaggio. - `exec` elevato bypassa la sandbox e usa il percorso di escape configurato (`gateway` per default, oppure `node` quando il target exec è `node`). ### `tools.exec` ```json5 { tools: { exec: { backgroundMs: 10000, timeoutSec: 1800, cleanupMs: 1800000, notifyOnExit: true, notifyOnExitEmptySuccess: false, commandHighlighting: false, applyPatch: { enabled: false, allowModels: ["gpt-5.5"], }, }, }, } ``` ### `tools.loopDetection` I controlli di sicurezza per i cicli degli strumenti sono **disabilitati per impostazione predefinita**. Imposta `enabled: true` per attivare il rilevamento. Le impostazioni possono essere definite globalmente in `tools.loopDetection` e sovrascritte per agente in `agents.list[].tools.loopDetection`. ```json5 { tools: { loopDetection: { enabled: true, historySize: 30, warningThreshold: 10, criticalThreshold: 20, globalCircuitBreakerThreshold: 30, detectors: { genericRepeat: true, knownPollNoProgress: true, pingPong: true, }, }, }, } ``` Cronologia massima delle chiamate agli strumenti conservata per l'analisi dei cicli. Soglia dello schema ripetuto senza avanzamento per gli avvisi. Soglia di ripetizione più alta per bloccare i cicli critici. Soglia di arresto rigida per qualsiasi esecuzione senza avanzamento. Avvisa in caso di chiamate ripetute con stesso strumento/stessi argomenti. Avvisa/blocca sugli strumenti di polling noti (`process.poll`, `command_status`, ecc.). Avvisa/blocca sugli schemi alternati a coppie senza avanzamento. Se `warningThreshold >= criticalThreshold` o `criticalThreshold >= globalCircuitBreakerThreshold`, la convalida non riesce. ### `tools.web` ```json5 { tools: { web: { search: { enabled: true, apiKey: "brave_api_key", // or BRAVE_API_KEY env maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, provider: "firecrawl", // optional; omit for auto-detect maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, timeoutSeconds: 30, cacheTtlMinutes: 15, maxRedirects: 3, readability: true, userAgent: "custom-ua", }, }, }, } ``` ### `tools.media` Configura la comprensione dei media in ingresso (immagine/audio/video): ```json5 { tools: { media: { concurrency: 2, asyncCompletion: { directSend: false, // deprecated: completions stay agent-mediated }, audio: { enabled: true, maxBytes: 20971520, scope: { default: "deny", rules: [{ action: "allow", match: { chatType: "direct" } }], }, models: [ { provider: "openai", model: "gpt-4o-mini-transcribe" }, { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }, ], }, image: { enabled: true, timeoutSeconds: 180, models: [{ provider: "ollama", model: "gemma4:26b", timeoutSeconds: 300 }], }, video: { enabled: true, maxBytes: 52428800, models: [{ provider: "google", model: "gemini-3-flash-preview" }], }, }, }, } ``` **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. ### `tools.agentToAgent` ```json5 { tools: { agentToAgent: { enabled: false, allow: ["home", "work"], }, }, } ``` ### `tools.sessions` Controlla quali sessioni possono essere indirizzate dagli strumenti di sessione (`sessions_list`, `sessions_history`, `sessions_send`). Predefinito: `tree` (sessione corrente + sessioni generate da essa, come i sottoagenti). ```json5 { tools: { sessions: { // "self" | "tree" | "agent" | "all" visibility: "tree", }, }, } ``` - `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"`. ### `tools.sessions_spawn` Controlla il supporto degli allegati inline per `sessions_spawn`. ```json5 { tools: { sessions_spawn: { attachments: { enabled: false, // opt-in: set true to allow inline file attachments maxTotalBytes: 5242880, // 5 MB total across all files maxFiles: 50, maxFileBytes: 1048576, // 1 MB per file retainOnSessionKeep: false, // keep attachments when cleanup="keep" }, }, }, } ``` - 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//` 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`. ### `tools.experimental` Flag sperimentali per gli strumenti integrati. Disattivati per impostazione predefinita, salvo quando si applica una regola di abilitazione automatica rigorosamente agentica per GPT-5. ```json5 { tools: { experimental: { planTool: true, // enable experimental update_plan }, }, } ``` - `planTool`: abilita lo strumento strutturato `update_plan` per il tracciamento di lavori multi-step non banali. - Predefinito: `false`, salvo che `agents.defaults.embeddedPi.executionContract` (o un override per agente) sia impostato su `"strict-agentic"` per un'esecuzione della famiglia GPT-5 di OpenAI o OpenAI Codex. Imposta `true` per forzare l'attivazione dello strumento fuori da tale ambito, oppure `false` per mantenerlo disattivato anche per esecuzioni GPT-5 rigorosamente agentiche. - Quando è abilitato, il prompt di sistema aggiunge anche indicazioni d'uso affinché il modello lo usi solo per lavori sostanziali e mantenga al massimo uno step `in_progress`. ### `agents.defaults.subagents` ```json5 { agents: { defaults: { subagents: { allowAgents: ["research"], model: "minimax/MiniMax-M2.7", maxConcurrent: 8, runTimeoutSeconds: 900, announceTimeoutMs: 120000, archiveAfterMinutes: 60, }, }, }, } ``` - `model`: modello predefinito per i sub-agenti generati. Se omesso, i sub-agenti ereditano il modello del chiamante. - `allowAgents`: allowlist predefinita degli ID degli agenti di destinazione per `sessions_spawn` quando l'agente richiedente non imposta il proprio `subagents.allowAgents` (`["*"]` = qualsiasi; predefinito: solo lo stesso agente). - `runTimeoutSeconds`: timeout predefinito (secondi) per `sessions_spawn` quando la chiamata dello strumento omette `runTimeoutSeconds`. `0` significa nessun timeout. - `announceTimeoutMs`: timeout per chiamata (millisecondi) per i tentativi di consegna dell'annuncio `agent` del gateway. Predefinito: `120000`. I ritentativi transitori possono rendere l'attesa totale dell'annuncio più lunga di un timeout configurato. - Policy degli strumenti per sub-agente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- ## Provider personalizzati e URL di base OpenClaw usa il catalogo di modelli integrato. Aggiungi provider personalizzati tramite `models.providers` nella configurazione o in `~/.openclaw/agents//agent/models.json`. ```json5 { models: { mode: "merge", // merge (default) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", apiKey: "LITELLM_KEY", api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai models: [ { id: "llama-3.1-8b", name: "Llama 3.1 8B", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 128000, contextTokens: 96000, maxTokens: 32000, }, ], }, }, }, } ``` - 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. ### Dettagli dei campi del provider - `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. '' --strict-json --merge` oppure `openclaw config set models.providers..models '' --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. L'onboarding interattivo di provider personalizzati deduce l'input di immagini per gli ID di modelli vision comuni come GPT-4o, Claude, Gemini, Qwen-VL, LLaVA, Pixtral, InternVL, Mllama, MiniCPM-V e GLM-4V, e salta la domanda aggiuntiva per le famiglie note come solo testo. Gli ID di modello sconosciuti richiedono comunque il supporto per le immagini. L'onboarding non interattivo usa la stessa inferenza; passa `--custom-image-input` per forzare metadati compatibili con le immagini oppure `--custom-text-input` per forzare metadati solo testo. ### Esempi di provider 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. ```json5 { 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. ```json5 { 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](/it/gateway/local-models). 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. ```json5 { 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`. ```json5 { 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. ```json5 { 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`. ```json5 { 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`. ```json5 { 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. --- ## Correlati - [Configurazione — agenti](/it/gateway/config-agents) - [Configurazione — canali](/it/gateway/config-channels) - [Riferimento di configurazione](/it/gateway/configuration-reference) — altre chiavi di primo livello - [Strumenti e plugins](/it/tools)