Configuration — outils et fournisseurs personnalisés

Entrée de fournisseur (type: "provider" ou omis) :

• provider : identifiant du fournisseur d’API (openai, anthropic, google/gemini, groq, etc.)
• model : remplacement de l’identifiant du modèle
• profile / preferredProfile : sélection du profil auth-profiles.json

Entrée CLI (type: "cli") :

• command : exécutable à lancer
• args : arguments modélisés (prend en charge {{MediaPath}}, {{Prompt}}, {{MaxChars}}, etc. ; openclaw doctor --fix migre les placeholders {input} obsolètes vers {{MediaPath}})

Champs communs :

• capabilities : liste facultative (image, audio, video). Valeurs par défaut : openai/anthropic/minimax → image, google → image+audio+video, groq → audio.
• prompt, maxChars, maxBytes, timeoutSeconds, language : remplacements par entrée.
• tools.media.image.timeoutSeconds et les entrées timeoutSeconds correspondantes du modèle d’image s’appliquent aussi lorsque l’agent appelle l’outil explicite image.
• Les échecs basculent vers l’entrée suivante.

L’authentification du fournisseur suit l’ordre standard : auth-profiles.json → variables d’environnement → models.providers.*.apiKey.

Champs d’achèvement asynchrone :

• asyncCompletion.directSend : indicateur de compatibilité obsolète. Les tâches de média asynchrones terminées restent médiées par la session demandeuse afin que l’agent reçoive le résultat, décide comment en informer l’utilisateur et utilise l’outil de message lorsque la livraison source l’exige.

• self : uniquement la clé de session actuelle.
• tree : session actuelle + sessions lancées par la session actuelle (sous-agents).
• agent : toute session appartenant à l’identifiant de l’agent actuel (peut inclure d’autres utilisateurs si vous exécutez des sessions par expéditeur sous le même identifiant d’agent).
• all : toute session. Le ciblage inter-agents nécessite toujours tools.agentToAgent.
• Limitation du bac à sable : lorsque la session actuelle est en bac à sable et que agents.defaults.sandbox.sessionToolsVisibility="spawned", la visibilité est forcée à tree même si tools.sessions.visibility="all".

• 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 à .openclaw/attachments/<uuid>/ avec un .manifest.json.
• Le contenu des pièces jointes est automatiquement expurgé de la persistance des transcriptions.
• Les entrées Base64 sont validées avec des contrôles stricts de l’alphabet et du remplissage, ainsi qu’une garde de taille avant décodage.
• Les permissions de fichiers sont 0700 pour les répertoires et 0600 pour les fichiers.
• Le nettoyage suit la stratégie cleanup : delete supprime toujours les pièces jointes ; keep les conserve uniquement lorsque retainOnSessionKeep: true.

• Utilisez authHeader: true + headers pour les besoins d’authentification personnalisés.
• Remplacez la racine de configuration de l’agent avec OPENCLAW_AGENT_DIR (ou PI_CODING_AGENT_DIR, un alias hérité de variable d’environnement).
• Priorité de fusion pour les ID de fournisseurs correspondants :
  • Les valeurs baseUrl non vides du models.json de l’agent 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 des fournisseurs gérés par SecretRef sont actualisées depuis les marqueurs sources (ENV_VAR_NAME pour les références d’environnement, secretref-managed pour les références de fichier/exec) au lieu de persister les secrets résolus.
  • Les valeurs d’en-tête des fournisseurs gérés par SecretRef sont actualisées depuis les marqueurs sources (secretref-env:ENV_VAR_NAME pour les références d’environnement, secretref-managed pour les références de fichier/exec).
  • Les valeurs apiKey/baseUrl vides ou manquantes de l’agent se rabattent sur models.providers dans la configuration.
  • Les modèles correspondants contextWindow/maxTokens utilisent la valeur la plus élevée entre la configuration explicite et les valeurs implicites du catalogue.
  • Le modèle correspondant contextTokens conserve un plafond d’exécution explicite lorsqu’il est présent ; utilisez-le pour limiter le contexte effectif sans modifier les métadonnées natives du modèle.
  • Utilisez models.mode: "replace" lorsque vous voulez que la configuration réécrive entièrement models.json.
  • La persistance des marqueurs fait autorité côté source : les marqueurs sont écrits depuis l’instantané de configuration source actif (avant résolution), pas depuis les valeurs de secrets résolues à l’exécution.

• models.mode : comportement du catalogue de fournisseurs (merge ou replace).
• models.providers : carte des fournisseurs personnalisés indexée par identifiant 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 les mises à jour additives. config set refuse les remplacements destructeurs sauf si vous passez --replace.

• models.providers.*.api : adaptateur de requête (openai-completions, openai-responses, anthropic-messages, google-generative-ai, etc.). Pour les backends /v1/chat/completions auto-hébergés tels que MLX, vLLM, SGLang et la plupart des serveurs locaux compatibles OpenAI, utilisez openai-completions. Un fournisseur personnalisé avec baseUrl mais sans api utilise par défaut openai-completions ; définissez openai-responses uniquement lorsque le backend prend en charge /v1/responses.
• models.providers.*.apiKey : identifiant secret du fournisseur (préférez la substitution SecretRef/env).
• models.providers.*.auth : stratégie d’authentification (api-key, token, oauth, aws-sdk).
• models.providers.*.contextWindow : fenêtre de contexte native par défaut pour les modèles de ce fournisseur lorsque l’entrée du modèle ne définit pas contextWindow.
• models.providers.*.contextTokens : plafond de contexte effectif par défaut à l’exécution pour les modèles de ce fournisseur lorsque l’entrée du modèle ne définit pas contextTokens.
• models.providers.*.maxTokens : plafond par défaut de jetons de sortie pour les modèles de ce fournisseur lorsque l’entrée du modèle ne définit pas maxTokens.
• models.providers.*.timeoutSeconds : délai d’expiration HTTP facultatif, par fournisseur et par modèle, en secondes, incluant la connexion, les en-têtes, le corps et la gestion de l’abandon total de la requête.
• 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 des identifiants secrets dans l’en-tête Authorization lorsque cela est requis.
• 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 : substitutions de transport pour les requêtes HTTP du fournisseur de modèles.

• request.headers : en-têtes supplémentaires (fusionnés avec les valeurs par défaut du fournisseur). Les valeurs acceptent SecretRef.
• request.auth : substitution de stratégie d’authentification. Modes : "provider-default" (utiliser l’authentification intégrée du fournisseur), "authorization-bearer" (avec token), "header" (avec headerName, value, prefix facultatif).
• request.proxy : substitution du proxy HTTP. Modes : "env-proxy" (utiliser les variables d’environnement HTTP_PROXY/HTTPS_PROXY), "explicit-proxy" (avec url). Les deux modes acceptent un sous-objet tls facultatif.
• request.tls : substitution TLS pour les connexions directes. Champs : ca, cert, key, passphrase (acceptent tous SecretRef), serverName, insecureSkipVerify.
• request.allowPrivateNetwork : lorsque true, autorise HTTPS vers baseUrl lorsque DNS se résout vers des plages privées, CGNAT ou similaires, via la garde HTTP fetch du fournisseur (opt-in opérateur pour les points de terminaison auto-hébergés compatibles OpenAI et approuvés). Les URL de flux du fournisseur de modèles en local loopback, telles que localhost, 127.0.0.1 et [::1], sont autorisées automatiquement sauf si cette valeur est explicitement définie sur false ; les hôtes LAN, tailnet et DNS privés nécessitent toujours un opt-in. WebSocket utilise le même request pour les en-têtes/TLS, mais pas cette garde SSRF de fetch. Par défaut false.

• models.providers.*.models : entrées explicites du catalogue de modèles du fournisseur.
• models.providers.*.models.*.input : modalités d’entrée du modèle. Utilisez ["text"] pour les modèles texte uniquement et ["text", "image"] pour les modèles natifs image/vision. Les pièces jointes image ne sont injectées dans les tours d’agent que lorsque le modèle sélectionné est marqué comme compatible image.
• models.providers.*.models.*.contextWindow : métadonnées de fenêtre de contexte native du modèle. Cela remplace le contextWindow au niveau du fournisseur pour ce modèle.
• models.providers.*.models.*.contextTokens : plafond de contexte facultatif à l’exécution. Cela remplace le contextTokens au niveau du fournisseur ; utilisez-le lorsque vous voulez un budget de contexte effectif plus petit que le contextWindow natif du modèle ; openclaw models list affiche les deux valeurs lorsqu’elles diffèrent.
• models.providers.*.models.*.compat.supportsDeveloperRole : indice de compatibilité facultatif. Pour api: "openai-completions" avec une baseUrl non native et non vide (hôte différent de api.openai.com), OpenClaw force cette valeur à false à l’exécution. Une baseUrl vide/omise 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 acceptant uniquement des chaînes. Lorsque true, OpenClaw aplatit les tableaux messages[].content de texte pur en chaînes simples avant d’envoyer la requête.

• plugins.entries.amazon-bedrock.config.discovery : racine des paramètres de découverte automatique 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 par identifiant de fournisseur pour une découverte ciblée.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval : intervalle d’interrogation pour l’actualisation 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 jetons de sortie de repli pour les modèles découverts.

Le Plugin fournisseur cerebras inclus peut configurer cela via openclaw onboard --auth-choice cerebras-api-key. Utilisez une configuration explicite du fournisseur uniquement lors de la substitution des valeurs par défaut.

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

Utilisez cerebras/zai-glm-4.7 pour Cerebras ; zai/glm-4.7 pour Z.AI direct.

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

Fournisseur intégré compatible avec Anthropic. Raccourci : openclaw onboard --auth-choice kimi-code-api-key.

Consultez Modèles locaux. En bref : exécutez un grand modèle local via l’API Responses de LM Studio sur du matériel sérieux ; conservez les modèles hébergés fusionnés pour le repli.

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

Définissez MINIMAX_API_KEY. Raccourcis : openclaw onboard --auth-choice minimax-global-api ou openclaw onboard --auth-choice minimax-cn-api. Le catalogue de modèles utilise M2.7 uniquement par défaut. Sur le chemin de streaming compatible avec Anthropic, OpenClaw désactive la réflexion MiniMax par défaut, sauf si vous définissez explicitement thinking vous-même. /fast on ou params.fastMode: true réécrit MiniMax-M2.7 en 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,
          },
        ],
      },
    },
  },
}

Pour le point de terminaison Chine : baseUrl: "https://api.moonshot.cn/v1" ou openclaw onboard --auth-choice moonshot-api-key-cn.

Les points de terminaison natifs Moonshot annoncent la compatibilité d’utilisation en streaming sur le transport partagé openai-completions, et OpenClaw s’appuie sur les capacités du point de terminaison plutôt que sur le seul identifiant du fournisseur intégré.

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

Définissez OPENCODE_API_KEY (ou OPENCODE_ZEN_API_KEY). Utilisez les références opencode/... pour le catalogue Zen ou les références opencode-go/... pour le catalogue Go. Raccourci : openclaw onboard --auth-choice opencode-zen ou 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 de base doit omettre /v1 (le client Anthropic l’ajoute). Raccourci : openclaw onboard --auth-choice synthetic-api-key.

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

Définissez ZAI_API_KEY. z.ai/* et z-ai/* sont des alias acceptés. Raccourci : openclaw onboard --auth-choice zai-api-key.

• Point de terminaison général : https://api.z.ai/api/paas/v4
• Point de terminaison de codage (par défaut) : https://api.z.ai/api/coding/paas/v4
• Pour le point de terminaison général, définissez un fournisseur personnalisé avec le remplacement de l’URL de base.