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 dans auth-profiles.json

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

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

Champs communs :

• capabilities : liste facultative (image, audio, video). Chaque Plugin de fournisseur déclare son propre ensemble de capacités par défaut ; par exemple, le fournisseur openai intégré utilise par défaut l’image et l’audio, anthropic/minimax l’image, google l’image, l’audio et la vidéo, et groq l’audio.
• prompt, maxChars, maxBytes, timeoutSeconds, language : remplacements propres à chaque entrée.
• tools.media.image.timeoutSeconds et les entrées timeoutSeconds correspondantes du modèle d’image s’appliquent également lorsque l’agent appelle explicitement l’outil image. Pour la compréhension des images, ce délai d’expiration s’applique à la requête elle-même et n’est pas réduit par le travail de préparation effectué auparavant.
• En cas d’échec, l’entrée suivante est utilisée.

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

Champs de finalisation asynchrone :

• asyncCompletion.directSend : indicateur de compatibilité obsolète. Les tâches multimédias asynchrones terminées restent traitées par l’intermédiaire de la session du demandeur afin que l’agent reçoive le résultat, décide comment le communiquer à l’utilisateur et utilise l’outil de messagerie lorsque la remise à la source l’exige.

• self : uniquement la clé de la session actuelle.
• tree : session actuelle et sessions créées par celle-ci (sous-agents).
• agent : toute session appartenant à l’identifiant de l’agent actuel (cela 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 entre agents nécessite toujours tools.agentToAgent.
• Limitation du bac à sable : lorsque la session actuelle est exécutée dans un bac à sable et que agents.defaults.sandbox.sessionToolsVisibility="spawned" (valeur par défaut), la visibilité est forcée à tree, même si tools.sessions.visibility="all".
• Lorsque la valeur n’est pas all, sessions_list inclut un champ visibility compact décrivant le mode effectif ainsi qu’un avertissement indiquant que certaines sessions peuvent être omises si elles se trouvent hors de la portée actuelle.

• Les pièces jointes nécessitent enabled: true.
• Les pièces jointes des sous-agents sont matérialisées dans l’espace de travail enfant sous .openclaw/attachments/<uuid>/, avec un fichier .manifest.json.
• Les pièces jointes ACP sont limitées aux images et transmises directement à l’environnement d’exécution ACP après validation des mêmes limites concernant le nombre de fichiers, la taille de chaque fichier et la taille totale.
• Le contenu des pièces jointes est automatiquement expurgé lors de la conservation de la transcription.
• Les entrées Base64 sont validées par des contrôles stricts de l’alphabet et du remplissage, ainsi que par une vérification de taille avant décodage.
• Les autorisations des fichiers joints des sous-agents sont 0700 pour les répertoires et 0600 pour les fichiers.
• Le nettoyage des sous-agents suit la stratégie cleanup : delete supprime toujours les pièces jointes ; keep ne les conserve que 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.
• Priorité de fusion pour les identifiants de fournisseurs correspondants :
  • Les valeurs baseUrl non vides du fichier models.json de l’agent sont prioritaires.
  • Les valeurs apiKey non vides de l’agent sont prioritaires 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 à partir des marqueurs de source (ENV_VAR_NAME pour les références d’environnement, secretref-managed pour les références de fichier/exécution) au lieu de conserver les secrets résolus.
  • Les valeurs d’en-tête des fournisseurs gérés par SecretRef sont actualisées à partir des marqueurs de source (secretref-env:ENV_VAR_NAME pour les références d’environnement, secretref-managed pour les références de fichier/exécution).
  • Si les valeurs apiKey/baseUrl de l’agent sont vides ou absentes, celles de models.providers dans la configuration sont utilisées.
  • Pour les valeurs contextWindow/maxTokens d’un modèle correspondant : la valeur explicite de la configuration est prioritaire lorsqu’elle est présente et valide (un nombre fini positif) ; sinon, la valeur implicite/générée du catalogue est utilisée.
  • La valeur contextTokens d’un modèle correspondant suit la même règle donnant la priorité à la valeur explicite, puis à la valeur implicite ; utilisez-la pour limiter le contexte effectif sans modifier les métadonnées natives du modèle.
  • Les catalogues des Plugins de fournisseurs sont stockés sous forme de fragments de catalogue générés et détenus par le Plugin dans l’état des Plugins de l’agent.
  • Utilisez models.mode: "replace" lorsque vous souhaitez que la configuration réécrive entièrement models.json et ignore la fusion des fragments de catalogue détenus par les Plugins.
  • La persistance des marqueurs fait autorité sur la source : les marqueurs sont écrits depuis l’instantané actif de la configuration source (avant résolution), et non depuis les valeurs de secrets résolues à l’exécution.

• models.mode : comportement du catalogue de fournisseurs (merge ou replace).
• models.providers : table personnalisée de fournisseurs 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 destructifs, sauf si vous transmettez --replace.

• models.providers.*.api : adaptateur de requête (openai-completions, openai-responses, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, azure-openai-responses). Pour les services auto-hébergés /v1/chat/completions tels que MLX, vLLM, SGLang et la plupart des serveurs locaux compatibles avec 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 service prend en charge /v1/responses.
• models.providers.*.apiKey : identifiant d’accès du fournisseur (préférez SecretRef ou la substitution de variable d’environnement).
• 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 : limite effective de contexte à l’exécution par défaut pour les modèles de ce fournisseur lorsque l’entrée du modèle ne définit pas contextTokens.
• models.providers.*.maxTokens : limite par défaut du nombre de jetons en 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, en secondes et propre à chaque fournisseur, pour les requêtes de modèle, 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 (valeur par défaut : true).
• models.providers.*.authHeader : force, lorsque cela est requis, le transport de l’identifiant d’accès dans l’en-tête Authorization.
• models.providers.*.baseUrl : URL de base de l’API en amont.
• models.providers.*.headers : en-têtes statiques supplémentaires pour le routage par proxy ou locataire.

models.providers.*.request : remplacements du transport pour les requêtes HTTP adressées aux fournisseurs 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 : remplacement de la stratégie d’authentification. Modes : "provider-default" (utilise l’authentification intégrée du fournisseur), "authorization-bearer" (avec token), "header" (avec headerName, value et, facultativement, prefix).
• request.proxy : remplacement du 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 de TLS pour les connexions directes. Champs : ca, cert, key, passphrase (tous acceptent SecretRef), serverName, insecureSkipVerify.
• request.allowPrivateNetwork : lorsque la valeur est true, autorise les requêtes HTTP adressées aux fournisseurs de modèles vers des plages privées, CGNAT ou similaires via la protection de récupération HTTP du fournisseur. Les URL de base des fournisseurs personnalisés/locaux font déjà confiance à l’origine exacte configurée, à l’exception des origines de métadonnées ou locales au lien, qui restent bloquées sans autorisation explicite. Définissez cette valeur sur false pour désactiver la confiance accordée à l’origine exacte. WebSocket utilise le même objet request pour les en-têtes/TLS, mais pas cette protection 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.*.input : modalités d’entrée du modèle. Utilisez ["text"] pour les modèles uniquement textuels et ["text", "image"] pour les modèles prenant nativement en charge les images/la vision. Les pièces jointes contenant des images ne sont injectées dans les tours de l’agent que lorsque le modèle sélectionné est indiqué comme prenant en charge les images.
• models.providers.*.models.*.contextWindow : métadonnées de la fenêtre de contexte native du modèle. Cette valeur remplace contextWindow au niveau du fournisseur pour ce modèle.
• models.providers.*.models.*.contextTokens : limite facultative du contexte à l’exécution. Cette valeur remplace contextTokens au niveau du fournisseur ; utilisez-la lorsque vous souhaitez un budget de contexte effectif inférieur à la valeur contextWindow native du modèle ; openclaw models list affiche les deux valeurs lorsqu’elles diffèrent.
• models.providers.*.models.*.compat.supportsDeveloperRole : indication de compatibilité facultative. Pour api: "openai-completions" avec une valeur baseUrl non vide et non native (hôte différent de api.openai.com), OpenClaw force cette valeur à false lors de l’exécution. Une valeur baseUrl vide ou omise conserve le comportement par défaut d’OpenAI.
• models.providers.*.models.*.compat.requiresStringContent : indication de compatibilité facultative pour les points de terminaison de conversation compatibles avec OpenAI qui n’acceptent que des chaînes. Lorsque la valeur est true, OpenClaw convertit les tableaux messages[].content exclusivement textuels en chaînes simples avant l’envoi de la requête.
• models.providers.*.models.*.compat.strictMessageKeys : indication de compatibilité facultative pour les points de terminaison de conversation stricts compatibles avec OpenAI. Lorsque la valeur est true, OpenClaw réduit les objets de message Chat Completions sortants à role et content avant l’envoi de la requête.
• models.providers.*.models.*.compat.thinkingFormat : indication facultative sur la charge utile de réflexion. Utilisez "together" pour reasoning.enabled au format Together, "qwen" pour enable_thinking au premier niveau ou "qwen-chat-template" pour chat_template_kwargs.enable_thinking sur les serveurs compatibles avec OpenAI de la famille Qwen qui prennent en charge les arguments nommés de modèle de conversation au niveau de la requête, tels que vLLM. Les modèles Qwen vLLM configurés proposent des choix binaires /think (off, on) pour ces formats.
• models.providers.*.models.*.compat.requiresReasoningContentOnAssistantMessages : indication de compatibilité facultative pour les services Chat Completions au format DeepSeek qui exigent que les messages antérieurs de l’assistant conservent reasoning_content lors de la relecture. Lorsque la valeur est true, OpenClaw conserve ce champ dans les messages sortants de l’assistant. Utilisez cette option lors de la connexion d’un proxy personnalisé compatible avec DeepSeek qui rejette les requêtes après suppression du raisonnement. Valeur par défaut : false.

• plugins.entries.amazon-bedrock.config.discovery : racine des paramètres de découverte automatique de Bedrock.
• plugins.entries.amazon-bedrock.config.discovery.enabled : active ou désactive 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 secours pour les modèles découverts.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens : nombre maximal de jetons en sortie de secours pour les modèles découverts.

Le Plugin de fournisseur externe officiel cerebras peut effectuer cette configuration via openclaw onboard --auth-choice cerebras-api-key. Utilisez une configuration explicite du fournisseur uniquement pour remplacer les 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 un accès direct à Z.AI.

{  env: { KIMI_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "kimi/kimi-for-coding" },      models: { "kimi/kimi-for-coding": { 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 une machine puissante ; conservez les modèles hébergés fusionnés comme solution de repli.

{  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M3" },      models: {        "minimax/MiniMax-M3": { alias: "Minimax" },      },    },  },  models: {    mode: "merge",    providers: {      minimax: {        baseUrl: "https://api.minimax.io/anthropic",        apiKey: "${MINIMAX_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "MiniMax-M3",            name: "MiniMax M3",            reasoning: true,            input: ["text", "image"],            cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 },            contextWindow: 1000000,            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 M3 par défaut et comprend également les variantes M2.7. Sur le chemin de diffusion en continu compatible avec Anthropic, OpenClaw désactive par défaut le raisonnement de MiniMax M2.x, sauf si vous définissez explicitement thinking vous-même ; MiniMax-M3 (et M3.x) conserve par défaut le mode de raisonnement omis/adaptatif du fournisseur. /fast on ou params.fastMode: true remplace MiniMax-M2.7 par 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 chinois : baseUrl: "https://api.moonshot.cn/v1" ou openclaw onboard --auth-choice moonshot-api-key-cn.

Les points de terminaison Moonshot natifs annoncent la compatibilité de l’utilisation en diffusion continue sur le transport partagé openai-completions, et OpenClaw active cette fonctionnalité selon les capacités du point de terminaison plutôt qu’en fonction du seul identifiant de 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. Les références de modèles utilisent l’identifiant de fournisseur canonique zai/*. 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 programmation : https://api.z.ai/api/coding/paas/v4
• Le choix d’authentification zai-api-key par défaut teste votre clé et détecte automatiquement le point de terminaison auquel elle appartient (en affichant une invite, avec Global comme valeur par défaut, si la détection n’est pas concluante). Des choix d’authentification dédiés à CN et Coding-Plan sont également disponibles pour une sélection explicite.
• Pour le point de terminaison général, définissez un fournisseur personnalisé en remplaçant l’URL de base.