Configurazione — strumenti e provider personalizzati

​

Strumenti

​

Profili degli strumenti

​

Gruppi di strumenti

​

tools.allow / tools.deny

{
  tools: { deny: ["browser", "canvas"] },
}

​

tools.byProvider

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
      "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

​

tools.elevated

{
  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 a un singolo messaggio.
• exec elevato aggira la sandbox e usa il percorso di escape configurato (gateway per impostazione predefinita, oppure node quando la destinazione exec è node).

​

tools.exec

{
  tools: {
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
      notifyOnExit: true,
      notifyOnExitEmptySuccess: false,
      applyPatch: {
        enabled: false,
        allowModels: ["gpt-5.5"],
      },
    },
  },
}

​

tools.loopDetection

{
  tools: {
    loopDetection: {
      enabled: true,
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}

• historySize: cronologia massima delle chiamate agli strumenti mantenuta per l’analisi del loop.
• warningThreshold: soglia del pattern ripetuto senza avanzamento per gli avvisi.
• criticalThreshold: soglia ripetuta più alta per bloccare i loop critici.
• globalCircuitBreakerThreshold: soglia di arresto rigido per qualsiasi esecuzione senza avanzamento.
• detectors.genericRepeat: avvisa sulle chiamate ripetute stesso-strumento/stessi-argomenti.
• detectors.knownPollNoProgress: avvisa/blocca sugli strumenti di polling noti (process.poll, command_status, ecc.).
• detectors.pingPong: avvisa/blocca sui pattern alternati a coppie senza avanzamento.
• Se warningThreshold >= criticalThreshold o criticalThreshold >= globalCircuitBreakerThreshold, la validazione fallisce.

​

tools.web

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key", // oppure env BRAVE_API_KEY
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        provider: "firecrawl", // facoltativo; ometti per auto-detect
        maxChars: 50000,
        maxCharsCap: 50000,
        maxResponseBytes: 2000000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        readability: true,
        userAgent: "custom-ua",
      },
    },
  },
}

​

tools.media

{
  tools: {
    media: {
      concurrency: 2,
      asyncCompletion: {
        directSend: false, // opt-in: invia direttamente al canale musica/video asincroni completati
      },
      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}}"] },
        ],
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },
}

​

tools.agentToAgent

{
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },
}

​

tools.sessions

{
  tools: {
    sessions: {
      // "self" | "tree" | "agent" | "all"
      visibility: "tree",
    },
  },
}

• self: solo la chiave della sessione corrente.
• tree: sessione corrente + sessioni generate dalla sessione corrente (sotto-agenti).
• agent: qualsiasi sessione appartenente all’id agente corrente (può includere altri utenti se esegui sessioni per mittente sotto lo stesso id agente).
• all: qualsiasi sessione. Il targeting cross-agent richiede comunque tools.agentToAgent.
• Limitazione sandbox: quando la sessione corrente è sandboxed e agents.defaults.sandbox.sessionToolsVisibility="spawned", la visibilità viene forzata a tree anche se tools.sessions.visibility="all".

​

tools.sessions_spawn

{
  tools: {
    sessions_spawn: {
      attachments: {
        enabled: false, // opt-in: imposta true per consentire allegati di file inline
        maxTotalBytes: 5242880, // 5 MB totali su tutti i file
        maxFiles: 50,
        maxFileBytes: 1048576, // 1 MB per file
        retainOnSessionKeep: false, // mantiene gli allegati quando 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/<uuid>/ con un .manifest.json.
• Il contenuto degli allegati viene automaticamente redatto dalla persistenza della trascrizione.
• Gli input base64 vengono convalidati con controlli rigorosi su alfabeto/padding e una guardia sulla dimensione prima della decodifica.
• I permessi dei file sono 0700 per le directory e 0600 per i file.
• La pulizia segue il criterio cleanup: delete rimuove sempre gli allegati; keep li conserva solo quando retainOnSessionKeep: true.

​

tools.experimental

{
  tools: {
    experimental: {
      planTool: true, // abilita l'`update_plan` sperimentale
    },
  },
}

• planTool: abilita lo strumento strutturato update_plan per il tracciamento del lavoro non banale a più fasi.
• Predefinito: false a meno che agents.defaults.embeddedPi.executionContract (o un override per agente) sia impostato su "strict-agentic" per un’esecuzione OpenAI o OpenAI Codex della famiglia GPT-5. Imposta true per forzare l’attivazione dello strumento fuori da tale ambito, oppure false per mantenerlo disattivato anche per esecuzioni strict-agentic GPT-5.
• Quando abilitato, il prompt di sistema aggiunge anche indicazioni d’uso in modo che il modello lo usi solo per lavoro sostanziale e mantenga al massimo una fase in_progress.

​

agents.defaults.subagents

{
  agents: {
    defaults: {
      subagents: {
        allowAgents: ["research"],
        model: "minimax/MiniMax-M2.7",
        maxConcurrent: 8,
        runTimeoutSeconds: 900,
        archiveAfterMinutes: 60,
      },
    },
  },
}

• model: modello predefinito per i sotto-agenti generati. Se omesso, i sotto-agenti ereditano il modello del chiamante.
• allowAgents: allowlist predefinita degli id agente 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 allo strumento omette runTimeoutSeconds. 0 significa nessun timeout.
• Criterio degli strumenti per sotto-agente: tools.subagents.tools.allow / tools.subagents.tools.deny.

​

Provider personalizzati e base URL

{
  models: {
    mode: "merge", // merge (predefinito) | 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 (oppure PI_CODING_AGENT_DIR, alias legacy della variabile d’ambiente).
• Precedenza di merge per ID provider corrispondenti:
  • I valori baseUrl non vuoti in models.json dell’agente hanno la precedenza.
  • I valori apiKey non vuoti dell’agente hanno la precedenza solo quando quel provider non è gestito da SecretRef nel contesto attuale di config/profilo auth.
  • I valori apiKey dei provider gestiti da SecretRef vengono aggiornati dai marker di origine (ENV_VAR_NAME per ref env, secretref-managed per ref file/exec) invece di persistere i segreti risolti.
  • I valori header dei provider gestiti da SecretRef vengono aggiornati dai marker di origine (secretref-env:ENV_VAR_NAME per ref env, secretref-managed per ref file/exec).
  • apiKey/baseUrl dell’agente vuoti o mancanti usano come fallback models.providers nella configurazione.
  • I valori contextWindow/maxTokens dei modelli corrispondenti usano il valore più alto tra configurazione esplicita e valori impliciti del catalogo.
  • contextTokens del modello corrispondente preserva un limite runtime esplicito quando presente; usalo per limitare il contesto effettivo senza cambiare 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 fonte: i marker vengono scritti dall’istantanea della configurazione sorgente attiva (pre-risoluzione), non dai valori dei segreti runtime risolti.

​

Dettagli dei campi del provider

• models.mode: comportamento del catalogo provider (merge o replace).
• models.providers: mappa dei 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 incrementali. config set rifiuta sostituzioni distruttive a meno che tu non passi --replace.
• models.providers.*.api: adattatore di richiesta (openai-completions, openai-responses, anthropic-messages, google-generative-ai, ecc).
• models.providers.*.apiKey: credenziale del provider (preferisci SecretRef/sostituzione env).
• models.providers.*.auth: strategia auth (api-key, token, oauth, aws-sdk).
• models.providers.*.injectNumCtxForOpenAICompat: per Ollama + openai-completions, inserisce options.num_ctx nelle richieste (predefinito: true).
• models.providers.*.authHeader: forza il trasporto della credenziale nell’header Authorization quando richiesto.
• models.providers.*.baseUrl: URL base dell’API upstream.
• models.providers.*.headers: header statici aggiuntivi per instradamento proxy/tenant.
• models.providers.*.request: override di trasporto per le richieste HTTP del provider di modelli.
  • request.headers: header aggiuntivi (uniti ai valori predefiniti del provider). I valori accettano SecretRef.
  • request.auth: override della strategia auth. Modalità: "provider-default" (usa l’auth integrata del provider), "authorization-bearer" (con token), "header" (con headerName, value, prefix facoltativo).
  • request.proxy: override del proxy HTTP. Modalità: "env-proxy" (usa le variabili env HTTP_PROXY/HTTPS_PROXY), "explicit-proxy" (con url). Entrambe le modalità accettano un sotto-oggetto tls facoltativo.
  • 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 risolve verso intervalli privati, CGNAT o simili, tramite la guardia fetch HTTP del provider (opt-in dell’operatore per endpoint self-hosted attendibili compatibili con OpenAI). WebSocket usa la stessa request per header/TLS ma non quella guardia SSRF della fetch. Predefinito false.
• models.providers.*.models: voci esplicite del catalogo modelli del provider.
• models.providers.*.models.*.contextWindow: metadati della finestra di contesto nativa del modello.
• models.providers.*.models.*.contextTokens: limite facoltativo del contesto runtime. Usalo quando vuoi un budget di contesto effettivo più piccolo della contextWindow nativa del modello.
• models.providers.*.models.*.compat.supportsDeveloperRole: suggerimento facoltativo di compatibilità. Per api: "openai-completions" con baseUrl non nativo 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 facoltativo di compatibilità per endpoint chat compatibili con OpenAI che accettano solo stringhe. Quando true, OpenClaw appiattisce gli array messages[].content di puro testo in stringhe semplici prima di inviare la richiesta.
• plugins.entries.amazon-bedrock.config.discovery: radice delle impostazioni di auto-discovery di Bedrock.
• plugins.entries.amazon-bedrock.config.discovery.enabled: attiva/disattiva il discovery implicito.
• plugins.entries.amazon-bedrock.config.discovery.region: regione AWS per il discovery.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: filtro facoltativo per id provider per discovery mirato.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: intervallo di polling per l’aggiornamento del discovery.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: finestra di contesto di fallback per i modelli rilevati.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: token massimi di output di fallback per i modelli rilevati.

​

Esempi di provider

{
  env: { CEREBRAS_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: {
        primary: "cerebras/zai-glm-4.7",
        fallbacks: ["cerebras/zai-glm-4.6"],
      },
      models: {
        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
        "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (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: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" },
        ],
      },
    },
  },
}

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

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

{
  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,
          },
        ],
      },
    },
  },
}

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

{
  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,
          },
        ],
      },
    },
  },
}

{
  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", "image"],
            cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
            contextWindow: 204800,
            maxTokens: 131072,
          },
        ],
      },
    },
  },
}

​

Correlati

• Configuration reference — altre chiavi di primo livello
• Configuration — agents
• Configuration — channels
• Strumenti e Plugin