Configuration — outils et fournisseurs personnalisés

​

Outils

​

Profils d’outils

​

Groupes d’outils

​

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

• Le remplacement par agent (agents.list[].tools.elevated) ne peut que restreindre davantage.
• /elevated on|off|ask|full stocke l’état par session ; les directives en ligne s’appliquent à un seul message.
• exec Elevated contourne le sandboxing et utilise le chemin d’échappement configuré (gateway par défaut, ou node lorsque la cible d’exécution est 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 : historique maximal des appels d’outils conservé pour l’analyse de boucle.
• warningThreshold : seuil de motif répétitif sans progression pour les avertissements.
• criticalThreshold : seuil répétitif plus élevé pour bloquer les boucles critiques.
• globalCircuitBreakerThreshold : seuil d’arrêt forcé pour toute exécution sans progression.
• detectors.genericRepeat : avertit en cas d’appels répétés du même outil avec les mêmes arguments.
• detectors.knownPollNoProgress : avertit/bloque sur les outils de polling connus (process.poll, command_status, etc.).
• detectors.pingPong : avertit/bloque sur les motifs alternés par paires sans progression.
• Si warningThreshold >= criticalThreshold ou criticalThreshold >= globalCircuitBreakerThreshold, la validation échoue.

​

tools.web

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key", // ou env BRAVE_API_KEY
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        provider: "firecrawl", // facultatif ; omettre pour auto-détection
        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, // adhésion explicite : envoyer directement au canal la musique/vidéo asynchrone terminée
      },
      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 : uniquement la clé de session actuelle.
• tree : session actuelle + sessions engendrées par la session actuelle (sous-agents).
• agent : toute session appartenant à l’ID d’agent actuel (peut inclure d’autres utilisateurs si vous exécutez des sessions par expéditeur sous le même ID d’agent).
• all : toute session. Le ciblage inter-agents exige toujours tools.agentToAgent.
• Restriction sandbox : lorsque la session actuelle est sandboxée et que agents.defaults.sandbox.sessionToolsVisibility="spawned", la visibilité est forcée à tree même si tools.sessions.visibility="all".

​

tools.sessions_spawn

{
  tools: {
    sessions_spawn: {
      attachments: {
        enabled: false, // adhésion explicite : définir true pour autoriser les pièces jointes de fichier inline
        maxTotalBytes: 5242880, // 5 MB au total pour tous les fichiers
        maxFiles: 50,
        maxFileBytes: 1048576, // 1 MB par fichier
        retainOnSessionKeep: false, // conserver les pièces jointes lorsque cleanup="keep"
      },
    },
  },
}

• Les pièces jointes ne sont prises en charge que pour runtime: "subagent". Le runtime ACP les rejette.
• Les fichiers sont matérialisés dans l’espace de travail enfant sous .openclaw/attachments/<uuid>/ avec un .manifest.json.
• Le contenu des pièces jointes est automatiquement caviardé dans la persistance des transcriptions.
• Les entrées Base64 sont validées avec des vérifications strictes d’alphabet/remplissage et une garde de taille avant décodage.
• Les permissions de fichier sont 0700 pour les répertoires et 0600 pour les fichiers.
• Le nettoyage suit la politique cleanup : delete supprime toujours les pièces jointes ; keep ne les conserve que lorsque retainOnSessionKeep: true.

​

tools.experimental

{
  tools: {
    experimental: {
      planTool: true, // activer l’outil expérimental update_plan
    },
  },
}

• planTool : active l’outil structuré update_plan pour le suivi des travaux non triviaux en plusieurs étapes.
• Valeur par défaut : false sauf si agents.defaults.embeddedPi.executionContract (ou un remplacement par agent) est défini sur "strict-agentic" pour une exécution GPT-5 de la famille OpenAI ou OpenAI Codex. Définissez true pour forcer l’activation de l’outil hors de ce périmètre, ou false pour le garder désactivé même pour les exécutions GPT-5 strict-agentic.
• Lorsqu’il est activé, le prompt système ajoute aussi des indications d’usage afin que le modèle ne l’utilise que pour des travaux substantiels et conserve au plus une étape in_progress.

​

agents.defaults.subagents

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

• model : modèle par défaut pour les sous-agents engendrés. S’il est omis, les sous-agents héritent du modèle de l’appelant.
• allowAgents : liste blanche par défaut des ID d’agents cibles pour sessions_spawn lorsque l’agent demandeur ne définit pas sa propre valeur subagents.allowAgents (["*"] = n’importe lequel ; par défaut : même agent uniquement).
• runTimeoutSeconds : délai d’expiration par défaut (secondes) pour sessions_spawn lorsque l’appel d’outil omet runTimeoutSeconds. 0 signifie aucun délai d’expiration.
• Politique d’outils par sous-agent : tools.subagents.tools.allow / tools.subagents.tools.deny.

​

Fournisseurs personnalisés et URL de base

{
  models: {
    mode: "merge", // merge (par défaut) | 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,
          },
        ],
      },
    },
  },
}

• Utilisez authHeader: true + headers pour des besoins d’authentification personnalisés.
• Remplacez la racine de configuration de l’agent avec OPENCLAW_AGENT_DIR (ou PI_CODING_AGENT_DIR, alias hérité de variable d’environnement).
• Priorité de fusion pour les ID de fournisseur correspondants :
  • Les valeurs baseUrl non vides de l’agent dans models.json l’emportent.
  • Les valeurs apiKey non vides de l’agent l’emportent uniquement lorsque ce fournisseur n’est pas géré par SecretRef dans le contexte actuel de configuration/profil d’authentification.
  • Les valeurs apiKey de fournisseur gérées par SecretRef sont actualisées à partir de marqueurs de source (ENV_VAR_NAME pour les références d’environnement, secretref-managed pour les références fichier/exec) au lieu de persister des secrets résolus.
  • Les valeurs d’en-tête de fournisseur gérées par SecretRef sont actualisées à partir de marqueurs de source (secretref-env:ENV_VAR_NAME pour les références d’environnement, secretref-managed pour les références fichier/exec).
  • Les valeurs apiKey/baseUrl d’agent vides ou absentes reviennent à models.providers dans la configuration.
  • Les valeurs contextWindow/maxTokens de modèle correspondant utilisent la plus élevée entre les valeurs explicites de configuration et les valeurs implicites du catalogue.
  • Les valeurs contextTokens de modèle correspondant conservent un plafond d’exécution explicite lorsqu’il est présent ; utilisez-le pour limiter le contexte effectif sans changer les métadonnées natives du modèle.
  • Utilisez models.mode: "replace" lorsque vous voulez que la configuration réécrive complètement models.json.
  • La persistance des marqueurs fait autorité sur la source : les marqueurs sont écrits depuis l’instantané actif de configuration source (avant résolution), pas depuis les valeurs secrètes résolues à l’exécution.

​

Détails des champs de fournisseur

• models.mode : comportement du catalogue de fournisseurs (merge ou replace).
• models.providers : map de fournisseurs personnalisés indexée par ID de fournisseur.
  • Modifications sûres : utilisez openclaw config set models.providers.<id> '<json>' --strict-json --merge ou openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge pour des mises à jour additives. config set refuse les remplacements destructifs sauf si vous passez --replace.
• models.providers.*.api : adaptateur de requête (openai-completions, openai-responses, anthropic-messages, google-generative-ai, etc.).
• models.providers.*.apiKey : identifiant du fournisseur (préférez SecretRef/substitution par variable d’environnement).
• models.providers.*.auth : stratégie d’authentification (api-key, token, oauth, aws-sdk).
• models.providers.*.injectNumCtxForOpenAICompat : pour Ollama + openai-completions, injecte options.num_ctx dans les requêtes (par défaut : true).
• models.providers.*.authHeader : force le transport de l’identifiant dans l’en-tête Authorization lorsque nécessaire.
• models.providers.*.baseUrl : URL de base de l’API amont.
• models.providers.*.headers : en-têtes statiques supplémentaires pour le routage proxy/locataire.
• models.providers.*.request : remplacements de transport pour les requêtes HTTP de fournisseur de modèle.
  • request.headers : en-têtes supplémentaires (fusionnés avec les valeurs par défaut du fournisseur). Les valeurs acceptent SecretRef.
  • request.auth : remplacement de stratégie d’authentification. Modes : "provider-default" (utilise l’authentification intégrée du fournisseur), "authorization-bearer" (avec token), "header" (avec headerName, value, prefix facultatif).
  • request.proxy : remplacement de proxy HTTP. Modes : "env-proxy" (utilise les variables d’environnement HTTP_PROXY/HTTPS_PROXY), "explicit-proxy" (avec url). Les deux modes acceptent un sous-objet tls facultatif.
  • request.tls : remplacement TLS pour les connexions directes. Champs : ca, cert, key, passphrase (tous acceptent SecretRef), serverName, insecureSkipVerify.
  • request.allowPrivateNetwork : lorsque true, autorise HTTPS vers baseUrl lorsque le DNS se résout vers des plages privées, CGNAT ou similaires, via la garde SSRF de récupération HTTP du fournisseur (adhésion explicite de l’opérateur pour des points de terminaison auto-hébergés compatibles OpenAI de confiance). WebSocket utilise la même request pour les en-têtes/TLS mais pas cette garde SSRF de récupération. Valeur par défaut false.
• models.providers.*.models : entrées explicites du catalogue de modèles du fournisseur.
• models.providers.*.models.*.contextWindow : métadonnées de fenêtre de contexte native du modèle.
• models.providers.*.models.*.contextTokens : plafond de contexte d’exécution facultatif. Utilisez-le lorsque vous voulez un budget de contexte effectif plus petit que le contextWindow natif du modèle.
• models.providers.*.models.*.compat.supportsDeveloperRole : indice de compatibilité facultatif. Pour api: "openai-completions" avec un baseUrl non natif non vide (hôte différent de api.openai.com), OpenClaw force cette valeur à false à l’exécution. Un baseUrl vide/omis conserve le comportement OpenAI par défaut.
• models.providers.*.models.*.compat.requiresStringContent : indice de compatibilité facultatif pour les points de terminaison de chat compatibles OpenAI à contenu texte uniquement. Lorsque true, OpenClaw aplatit les tableaux messages[].content purement textuels en chaînes simples avant d’envoyer la requête.
• plugins.entries.amazon-bedrock.config.discovery : racine des paramètres d’auto-discovery Bedrock.
• plugins.entries.amazon-bedrock.config.discovery.enabled : activer/désactiver la découverte implicite.
• plugins.entries.amazon-bedrock.config.discovery.region : région AWS pour la découverte.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter : filtre facultatif d’ID de fournisseur pour une découverte ciblée.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval : intervalle d’interrogation pour le rafraîchissement de la découverte.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow : fenêtre de contexte de repli pour les modèles découverts.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens : nombre maximal de tokens de sortie de repli pour les modèles découverts.

​

Exemples de fournisseurs

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

​

Lié

• Référence de configuration — autres clés de niveau supérieur
• Configuration — agents
• Configuration — canaux
• Outils et plugins