--- read_when: - Ajuster les valeurs par défaut de l’agent (modèles, raisonnement, espace de travail, Heartbeat, médias, Skills) - Configurer le routage et les liaisons multi-agents - Ajuster le comportement des sessions, de la remise des messages et du mode de conversation summary: Paramètres par défaut de l’agent, routage multi-agent, session, messages et configuration de conversation title: Configuration — agents x-i18n: generated_at: "2026-05-13T02:53:11Z" model: gpt-5.5 provider: openai source_hash: 08ddc1b36f4b9408ebaa5f071693b1c1333cedc9b00f75df93f12e73081e1033 source_path: gateway/config-agents.md workflow: 16 --- Clés de configuration au périmètre des agents sous `agents.*`, `multiAgent.*`, `session.*`, `messages.*` et `talk.*`. Pour les canaux, outils, runtime Gateway et autres clés de premier niveau, consultez la [référence de configuration](/fr/gateway/configuration-reference). ## Valeurs par défaut des agents ### `agents.defaults.workspace` Par défaut : `~/.openclaw/workspace`. ```json5 { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, } ``` ### `agents.defaults.repoRoot` Racine de dépôt facultative affichée dans la ligne Runtime du prompt système. Si elle n’est pas définie, OpenClaw la détecte automatiquement en remontant depuis l’espace de travail. ```json5 { agents: { defaults: { repoRoot: "~/Projects/openclaw" } }, } ``` ### `agents.defaults.skills` Liste d’autorisation de Skills par défaut facultative pour les agents qui ne définissent pas `agents.list[].skills`. ```json5 { agents: { defaults: { skills: ["github", "weather"] }, list: [ { id: "writer" }, // inherits github, weather { id: "docs", skills: ["docs-search"] }, // replaces defaults { id: "locked-down", skills: [] }, // no skills ], }, } ``` - Omettez `agents.defaults.skills` pour autoriser les Skills sans restriction par défaut. - Omettez `agents.list[].skills` pour hériter des valeurs par défaut. - Définissez `agents.list[].skills: []` pour n’autoriser aucune Skill. - Une liste non vide `agents.list[].skills` est l’ensemble final pour cet agent ; elle n’est pas fusionnée avec les valeurs par défaut. ### `agents.defaults.skipBootstrap` Désactive la création automatique des fichiers de bootstrap de l’espace de travail (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). ```json5 { agents: { defaults: { skipBootstrap: true } }, } ``` ### `agents.defaults.skipOptionalBootstrapFiles` Ignore la création de certains fichiers facultatifs de l’espace de travail tout en écrivant les fichiers de bootstrap requis. Valeurs valides : `SOUL.md`, `USER.md`, `HEARTBEAT.md` et `IDENTITY.md`. ```json5 { agents: { defaults: { skipOptionalBootstrapFiles: ["SOUL.md", "USER.md"], }, }, } ``` ### `agents.defaults.contextInjection` Contrôle le moment où les fichiers de bootstrap de l’espace de travail sont injectés dans le prompt système. Par défaut : `"always"`. - `"continuation-skip"` : les tours de continuation sûrs (après une réponse d’assistant terminée) ignorent la réinjection du bootstrap de l’espace de travail, ce qui réduit la taille du prompt. Les exécutions Heartbeat et les nouvelles tentatives après Compaction reconstruisent toujours le contexte. - `"never"` : désactive l’injection du bootstrap de l’espace de travail et des fichiers de contexte à chaque tour. Utilisez cette option uniquement pour les agents qui gèrent entièrement le cycle de vie de leur prompt (moteurs de contexte personnalisés, runtimes natifs qui construisent leur propre contexte ou workflows spécialisés sans bootstrap). Les tours Heartbeat et de récupération après Compaction ignorent aussi l’injection. ```json5 { agents: { defaults: { contextInjection: "continuation-skip" } }, } ``` ### `agents.defaults.bootstrapMaxChars` Nombre maximal de caractères par fichier de bootstrap de l’espace de travail avant troncature. Par défaut : `12000`. ```json5 { agents: { defaults: { bootstrapMaxChars: 12000 } }, } ``` ### `agents.defaults.bootstrapTotalMaxChars` Nombre total maximal de caractères injectés sur l’ensemble des fichiers de bootstrap de l’espace de travail. Par défaut : `60000`. ```json5 { agents: { defaults: { bootstrapTotalMaxChars: 60000 } }, } ``` ### `agents.defaults.bootstrapPromptTruncationWarning` Contrôle l’avis visible par l’agent dans le prompt système lorsque le contexte de bootstrap est tronqué. Par défaut : `"once"`. - `"off"` : n’injecte jamais de texte d’avis de troncature dans le prompt système. - `"once"` : injecte un avis concis une seule fois par signature de troncature unique (recommandé). - `"always"` : injecte un avis concis à chaque exécution lorsqu’une troncature existe. Les décomptes bruts/injectés détaillés et les champs d’ajustement de configuration restent dans les diagnostics tels que les rapports et journaux de contexte/statut ; le contexte utilisateur/runtime WebChat de routine ne reçoit que l’avis de récupération concis. ```json5 { agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // off | once | always } ``` ### Carte de propriété des budgets de contexte OpenClaw dispose de plusieurs budgets de prompt/contexte à volume élevé, et ils sont intentionnellement répartis par sous-système au lieu de passer tous par un même réglage générique. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars` : injection normale du bootstrap de l’espace de travail. - `agents.defaults.startupContext.*` : préambule ponctuel de lancement/réinitialisation d’exécution du modèle, incluant les fichiers récents quotidiens `memory/*.md`. Les commandes de chat nues `/new` et `/reset` sont acquittées sans invoquer le modèle. - `skills.limits.*` : la liste compacte des Skills injectée dans le prompt système. - `agents.defaults.contextLimits.*` : extraits runtime bornés et blocs injectés détenus par le runtime. - `memory.qmd.limits.*` : extrait de recherche mémoire indexée et dimensionnement d’injection. Utilisez la substitution par agent correspondante uniquement lorsqu’un agent nécessite un budget différent : - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` Contrôle le préambule de démarrage du premier tour injecté lors des exécutions de modèle de réinitialisation/démarrage. Les commandes de chat nues `/new` et `/reset` acquittent la réinitialisation sans invoquer le modèle, elles ne chargent donc pas ce préambule. ```json5 { agents: { defaults: { startupContext: { enabled: true, applyOn: ["new", "reset"], dailyMemoryDays: 2, maxFileBytes: 16384, maxFileChars: 1200, maxTotalChars: 2800, }, }, }, } ``` #### `agents.defaults.contextLimits` Valeurs par défaut partagées pour les surfaces de contexte runtime bornées. ```json5 { agents: { defaults: { contextLimits: { memoryGetMaxChars: 12000, memoryGetDefaultLines: 120, toolResultMaxChars: 16000, postCompactionMaxChars: 1800, }, }, }, } ``` - `memoryGetMaxChars` : limite d’extrait `memory_get` par défaut avant l’ajout des métadonnées de troncature et de l’avis de continuation. - `memoryGetDefaultLines` : fenêtre de lignes `memory_get` par défaut lorsque `lines` est omis. - `toolResultMaxChars` : limite des résultats d’outil en direct utilisée pour les résultats persistés et la récupération après dépassement. - `postCompactionMaxChars` : limite d’extrait AGENTS.md utilisée lors de l’injection de rafraîchissement après Compaction. #### `agents.list[].contextLimits` Substitution par agent pour les réglages partagés `contextLimits`. Les champs omis héritent de `agents.defaults.contextLimits`. ```json5 { agents: { defaults: { contextLimits: { memoryGetMaxChars: 12000, toolResultMaxChars: 16000, }, }, list: [ { id: "tiny-local", contextLimits: { memoryGetMaxChars: 6000, toolResultMaxChars: 8000, }, }, ], }, } ``` #### `skills.limits.maxSkillsPromptChars` Limite globale pour la liste compacte des Skills injectée dans le prompt système. Cela n’affecte pas la lecture à la demande des fichiers `SKILL.md`. ```json5 { skills: { limits: { maxSkillsPromptChars: 18000, }, }, } ``` #### `agents.list[].skillsLimits.maxSkillsPromptChars` Substitution par agent pour le budget de prompt des Skills. ```json5 { agents: { list: [ { id: "tiny-local", skillsLimits: { maxSkillsPromptChars: 6000, }, }, ], }, } ``` ### `agents.defaults.imageMaxDimensionPx` Taille maximale en pixels du côté le plus long de l’image dans les blocs image de transcript/outil avant les appels au fournisseur. Par défaut : `1200`. Des valeurs plus faibles réduisent généralement l’utilisation de jetons vision et la taille de la charge utile des requêtes pour les exécutions riches en captures d’écran. Des valeurs plus élevées préservent davantage de détails visuels. ```json5 { agents: { defaults: { imageMaxDimensionPx: 1200 } }, } ``` ### `agents.defaults.userTimezone` Fuseau horaire pour le contexte du prompt système (pas pour les horodatages des messages). Se rabat sur le fuseau horaire de l’hôte. ```json5 { agents: { defaults: { userTimezone: "America/Chicago" } }, } ``` ### `agents.defaults.timeFormat` Format de l’heure dans le prompt système. Par défaut : `auto` (préférence du système d’exploitation). ```json5 { agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24 } ``` ### `agents.defaults.model` ```json5 { agents: { defaults: { models: { "anthropic/claude-opus-4-6": { alias: "opus" }, "minimax/MiniMax-M2.7": { alias: "minimax" }, }, model: { primary: "anthropic/claude-opus-4-6", fallbacks: ["minimax/MiniMax-M2.7"], }, imageModel: { primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free", fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"], }, imageGenerationModel: { primary: "openai/gpt-image-2", fallbacks: ["google/gemini-3.1-flash-image-preview"], }, videoGenerationModel: { primary: "qwen/wan2.6-t2v", fallbacks: ["qwen/wan2.6-i2v"], }, pdfModel: { primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, params: { cacheRetention: "long" }, // global default provider params pdfMaxBytesMb: 10, pdfMaxPages: 20, thinkingDefault: "low", verboseDefault: "off", toolProgressDetail: "explain", reasoningDefault: "off", elevatedDefault: "on", timeoutSeconds: 600, mediaMaxMb: 5, contextTokens: 200000, maxConcurrent: 3, }, }, } ``` - `model` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`). - La forme chaîne définit uniquement le modèle principal. - La forme objet définit le modèle principal ainsi que les modèles de basculement ordonnés. - `imageModel` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`). - Utilisé par le chemin de l’outil `image` comme configuration de son modèle de vision. - Également utilisé comme routage de secours lorsque le modèle sélectionné/par défaut ne peut pas accepter d’entrée image. - Préférez les références explicites `provider/model`. Les identifiants nus sont acceptés pour compatibilité ; si un identifiant nu correspond de façon unique à une entrée configurée compatible avec les images dans `models.providers.*.models`, OpenClaw le qualifie avec ce fournisseur. Les correspondances configurées ambiguës nécessitent un préfixe de fournisseur explicite. - `imageGenerationModel` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`). - Utilisé par la capacité partagée de génération d’images et toute future surface d’outil/plugin qui génère des images. - Valeurs typiques : `google/gemini-3.1-flash-image-preview` pour la génération d’images Gemini native, `fal/fal-ai/flux/dev` pour fal, `openai/gpt-image-2` pour OpenAI Images, ou `openai/gpt-image-1.5` pour la sortie OpenAI PNG/WebP avec arrière-plan transparent. - Si vous sélectionnez directement un fournisseur/modèle, configurez aussi l’authentification du fournisseur correspondant (par exemple `GEMINI_API_KEY` ou `GOOGLE_API_KEY` pour `google/*`, `OPENAI_API_KEY` ou OpenAI Codex OAuth pour `openai/gpt-image-2` / `openai/gpt-image-1.5`, `FAL_KEY` pour `fal/*`). - Si omis, `image_generate` peut toujours déduire un fournisseur par défaut adossé à une authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération d’images enregistrés dans l’ordre des identifiants de fournisseur. - `musicGenerationModel` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`). - Utilisé par la capacité partagée de génération de musique et l’outil intégré `music_generate`. - Valeurs typiques : `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` ou `minimax/music-2.6`. - Si omis, `music_generate` peut toujours déduire un fournisseur par défaut adossé à une authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération de musique enregistrés dans l’ordre des identifiants de fournisseur. - Si vous sélectionnez directement un fournisseur/modèle, configurez aussi l’authentification/la clé d’API du fournisseur correspondant. - `videoGenerationModel` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`). - Utilisé par la capacité partagée de génération vidéo et l’outil intégré `video_generate`. - Valeurs typiques : `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` ou `qwen/wan2.7-r2v`. - Si omis, `video_generate` peut toujours déduire un fournisseur par défaut adossé à une authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération vidéo enregistrés dans l’ordre des identifiants de fournisseur. - Si vous sélectionnez directement un fournisseur/modèle, configurez aussi l’authentification/la clé d’API du fournisseur correspondant. - Le fournisseur intégré de génération vidéo Qwen prend en charge jusqu’à 1 vidéo de sortie, 1 image d’entrée, 4 vidéos d’entrée, une durée de 10 secondes, ainsi que les options de niveau fournisseur `size`, `aspectRatio`, `resolution`, `audio` et `watermark`. - `pdfModel` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`). - Utilisé par l’outil `pdf` pour le routage du modèle. - Si omis, l’outil PDF se rabat sur `imageModel`, puis sur le modèle de session/par défaut résolu. - `pdfMaxBytesMb` : limite de taille PDF par défaut pour l’outil `pdf` lorsque `maxBytesMb` n’est pas passé au moment de l’appel. - `pdfMaxPages` : nombre maximal de pages prises en compte par défaut par le mode de secours d’extraction dans l’outil `pdf`. - `verboseDefault` : niveau verbeux par défaut pour les agents. Valeurs : `"off"`, `"on"`, `"full"`. Par défaut : `"off"`. - `toolProgressDetail` : mode de détail pour les résumés d’outils `/verbose` et les lignes d’outils de brouillon de progression. Valeurs : `"explain"` (par défaut, libellés humains compacts) ou `"raw"` (ajoute la commande/le détail brut lorsqu’il est disponible). `agents.list[].toolProgressDetail` par agent remplace cette valeur par défaut. - `reasoningDefault` : visibilité du raisonnement par défaut pour les agents. Valeurs : `"off"`, `"on"`, `"stream"`. `agents.list[].reasoningDefault` par agent remplace cette valeur par défaut. Les valeurs par défaut de raisonnement configurées ne sont appliquées qu’aux propriétaires, expéditeurs autorisés ou contextes Gateway administrateur-opérateur lorsqu’aucun remplacement de raisonnement par message ou par session n’est défini. - `elevatedDefault` : niveau de sortie élevée par défaut pour les agents. Valeurs : `"off"`, `"on"`, `"ask"`, `"full"`. Par défaut : `"on"`. - `model.primary` : format `provider/model` (par exemple `openai/gpt-5.5` pour un accès par clé d’API OpenAI ou Codex OAuth). Si vous omettez le fournisseur, OpenClaw essaie d’abord un alias, puis une correspondance unique de fournisseur configuré pour cet identifiant exact de modèle, et seulement ensuite se rabat sur le fournisseur par défaut configuré (comportement de compatibilité obsolète ; préférez donc `provider/model` explicite). Si ce fournisseur n’expose plus le modèle par défaut configuré, OpenClaw se rabat sur le premier fournisseur/modèle configuré au lieu d’exposer une valeur par défaut périmée d’un fournisseur supprimé. - `models` : catalogue de modèles configuré et liste d’autorisation pour `/model`. Chaque entrée peut inclure `alias` (raccourci) et `params` (spécifiques au fournisseur, par exemple `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`). - Utilisez des entrées `provider/*` telles que `"openai-codex/*": {}` ou `"vllm/*": {}` pour afficher tous les modèles découverts pour les fournisseurs sélectionnés sans lister manuellement chaque identifiant de modèle. - Modifications sûres : utilisez `openclaw config set agents.defaults.models '' --strict-json --merge` pour ajouter des entrées. `config set` refuse les remplacements qui supprimeraient des entrées existantes de la liste d’autorisation, sauf si vous passez `--replace`. - Les flux de configuration/d’intégration limités au fournisseur fusionnent les modèles de fournisseur sélectionnés dans cette map et préservent les fournisseurs sans rapport déjà configurés. - Pour les modèles OpenAI Responses directs, la Compaction côté serveur est activée automatiquement. Utilisez `params.responsesServerCompaction: false` pour arrêter l’injection de `context_management`, ou `params.responsesCompactThreshold` pour remplacer le seuil. Voir [Compaction côté serveur OpenAI](/fr/providers/openai#server-side-compaction-responses-api). - `params` : paramètres globaux par défaut du fournisseur appliqués à tous les modèles. Définis dans `agents.defaults.params` (par exemple `{ cacheRetention: "long" }`). - Priorité de fusion de `params` (configuration) : `agents.defaults.params` (base globale) est remplacé par `agents.defaults.models["provider/model"].params` (par modèle), puis `agents.list[].params` (identifiant d’agent correspondant) remplace par clé. Voir [Mise en cache des prompts](/fr/reference/prompt-caching) pour plus de détails. - `params.extra_body`/`params.extraBody` : JSON avancé transmis tel quel et fusionné dans les corps de requête `api: "openai-completions"` pour les proxys compatibles OpenAI. En cas de collision avec des clés de requête générées, le corps supplémentaire l’emporte ; les routes de complétion non natives suppriment toujours ensuite `store`, propre à OpenAI. - `params.chat_template_kwargs` : arguments de modèle de discussion compatibles vLLM/OpenAI fusionnés dans les corps de requête de niveau supérieur `api: "openai-completions"`. Pour `vllm/nemotron-3-*` avec la réflexion désactivée, le plugin vLLM intégré envoie automatiquement `enable_thinking: false` et `force_nonempty_content: true` ; les `chat_template_kwargs` explicites remplacent les valeurs par défaut générées, et `extra_body.chat_template_kwargs` garde la priorité finale. Pour les contrôles de réflexion Qwen vLLM, définissez `params.qwenThinkingFormat` sur `"chat-template"` ou `"top-level"` dans cette entrée de modèle. - `compat.thinkingFormat` : style de charge utile de réflexion compatible OpenAI. Utilisez `"qwen"` pour `enable_thinking` de niveau supérieur de style Qwen, ou `"qwen-chat-template"` pour `chat_template_kwargs.enable_thinking` sur les backends de la famille Qwen qui prennent en charge les kwargs de modèle de discussion au niveau de la requête, comme vLLM. OpenClaw associe la réflexion désactivée à `false` et la réflexion activée à `true`. - `compat.supportedReasoningEfforts` : liste d’efforts de raisonnement compatibles OpenAI par modèle. Incluez `"xhigh"` pour les endpoints personnalisés qui l’acceptent réellement ; OpenClaw expose alors `/think xhigh` dans les menus de commandes, les lignes de session Gateway, la validation des correctifs de session, la validation de la CLI d’agent et la validation `llm-task` pour ce fournisseur/modèle configuré. Utilisez `compat.reasoningEffortMap` lorsque le backend attend une valeur propre au fournisseur pour un niveau canonique. - `params.preserveThinking` : activation explicite propre à Z.AI pour la réflexion préservée. Lorsque cette option est activée et que la réflexion est active, OpenClaw envoie `thinking.clear_thinking: false` et rejoue le `reasoning_content` précédent ; voir [Réflexion Z.AI et réflexion préservée](/fr/providers/zai#thinking-and-preserved-thinking). - `localService` : gestionnaire de processus facultatif au niveau fournisseur pour les serveurs de modèles locaux/auto-hébergés. Lorsque le modèle sélectionné appartient à ce fournisseur, OpenClaw sonde `healthUrl` (ou `baseUrl + "/models"`), démarre `command` avec `args` si l’endpoint est indisponible, attend jusqu’à `readyTimeoutMs`, puis envoie la requête de modèle. `command` doit être un chemin absolu. `idleStopMs: 0` garde le processus actif jusqu’à la fermeture d’OpenClaw ; une valeur positive arrête le processus lancé par OpenClaw après ce nombre de millisecondes d’inactivité. Voir [Services de modèles locaux](/fr/gateway/local-model-services). - La politique d’exécution appartient aux fournisseurs ou aux modèles, pas à `agents.defaults`. Utilisez `models.providers..agentRuntime` pour les règles à l’échelle du fournisseur ou `agents.defaults.models["provider/model"].agentRuntime` / `agents.list[].models["provider/model"].agentRuntime` pour les règles propres au modèle. Les modèles d’agent OpenAI sur le fournisseur OpenAI officiel sélectionnent Codex par défaut. - Les rédacteurs de configuration qui modifient ces champs (par exemple `/models set`, `/models set-image` et les commandes d’ajout/suppression de secours) enregistrent la forme objet canonique et préservent les listes de secours existantes lorsque c’est possible. - `maxConcurrent` : nombre maximal d’exécutions d’agents parallèles entre les sessions (chaque session reste sérialisée). Par défaut : 4. ### Politique d’exécution ```json5 { models: { providers: { openai: { agentRuntime: { id: "codex" }, }, }, }, agents: { defaults: { model: "openai/gpt-5.5", models: { "anthropic/claude-opus-4-7": { agentRuntime: { id: "claude-cli" }, }, }, }, }, } ``` - `id` : `"auto"`, `"pi"`, un identifiant de harnais de plugin enregistré ou un alias de backend CLI pris en charge. Le plugin Codex intégré enregistre `codex` ; le plugin Anthropic intégré fournit le backend CLI `claude-cli`. - `id: "auto"` permet aux harnais de plugin enregistrés de réclamer les tours pris en charge et utilise PI lorsqu’aucun harnais ne correspond. Une exécution de plugin explicite comme `id: "codex"` exige ce harnais et échoue fermement s’il est indisponible ou échoue. - Les clés d’exécution au niveau de l’agent entier sont héritées. `agents.defaults.agentRuntime`, `agents.list[].agentRuntime`, les épingles d’exécution de session et `OPENCLAW_AGENT_RUNTIME` sont ignorés par la sélection d’exécution. Exécutez `openclaw doctor --fix` pour supprimer les valeurs obsolètes. - Les modèles d’agent OpenAI utilisent le harnais Codex par défaut ; `agentRuntime.id: "codex"` au niveau fournisseur/modèle reste valide lorsque vous voulez le rendre explicite. - Pour les déploiements Claude CLI, préférez `model: "anthropic/claude-opus-4-7"` avec `agentRuntime.id: "claude-cli"` limité au modèle. Les références de modèle héritées `claude-cli/claude-opus-4-7` fonctionnent toujours pour compatibilité, mais les nouvelles configurations doivent conserver la sélection fournisseur/modèle canonique et placer le backend d’exécution dans la politique d’exécution fournisseur/modèle. - Cela ne contrôle que l’exécution des tours d’agent texte. La génération de médias, la vision, PDF, la musique, la vidéo et TTS continuent d’utiliser leurs paramètres fournisseur/modèle. **Raccourcis d’alias intégrés** (s’appliquent uniquement lorsque le modèle se trouve dans `agents.defaults.models`) : | Alias | Modèle | | ------------------- | -------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | | `gpt` | `openai/gpt-5.5` | | `gpt-mini` | `openai/gpt-5.4-mini` | | `gpt-nano` | `openai/gpt-5.4-nano` | | `gemini` | `google/gemini-3.1-pro-preview` | | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | Vos alias configurés prévalent toujours sur les valeurs par défaut. Les modèles Z.AI GLM-4.x activent automatiquement le mode de réflexion, sauf si vous définissez `--thinking off` ou `agents.defaults.models["zai/"].params.thinking` vous-même. Les modèles Z.AI activent `tool_stream` par défaut pour le streaming des appels d’outils. Définissez `agents.defaults.models["zai/"].params.tool_stream` sur `false` pour le désactiver. Les modèles Anthropic Claude 4.6 utilisent par défaut la réflexion `adaptive` lorsqu’aucun niveau de réflexion explicite n’est défini. ### `agents.defaults.cliBackends` Backends CLI facultatifs pour les exécutions de repli en texte uniquement (sans appels d’outils). Utile comme solution de secours lorsque les fournisseurs d’API échouent. ```json5 { agents: { defaults: { cliBackends: { "codex-cli": { command: "/opt/homebrew/bin/codex", }, "my-cli": { command: "my-cli", args: ["--json"], output: "json", modelArg: "--model", sessionArg: "--session", sessionMode: "existing", systemPromptArg: "--system", // Or use systemPromptFileArg when the CLI accepts a prompt file flag. systemPromptWhen: "first", imageArg: "--image", imageMode: "repeat", }, }, }, }, } ``` - Les backends CLI donnent la priorité au texte ; les outils sont toujours désactivés. - Les sessions sont prises en charge lorsque `sessionArg` est défini. - La transmission d’images est prise en charge lorsque `imageArg` accepte les chemins de fichiers. - `reseedFromRawTranscriptWhenUncompacted: true` permet à un backend de récupérer des sessions invalidées sûres à partir d’une fin bornée de transcript OpenClaw brut avant que le premier résumé de compaction n’existe. Les changements de profil d’authentification ou d’époque d’identifiants ne relancent toujours jamais depuis le brut. ### `agents.defaults.systemPromptOverride` Remplacez l’intégralité du prompt système assemblé par OpenClaw par une chaîne fixe. Définissez-le au niveau par défaut (`agents.defaults.systemPromptOverride`) ou par agent (`agents.list[].systemPromptOverride`). Les valeurs par agent sont prioritaires ; une valeur vide ou composée uniquement d’espaces est ignorée. Utile pour les expériences de prompt contrôlées. ```json5 { agents: { defaults: { systemPromptOverride: "You are a helpful assistant.", }, }, } ``` ### `agents.defaults.promptOverlays` Surcouches de prompt indépendantes du fournisseur appliquées par famille de modèles. Les identifiants de modèles de la famille GPT-5 reçoivent le contrat de comportement partagé entre fournisseurs ; `personality` contrôle uniquement la couche conviviale de style d’interaction. ```json5 { agents: { defaults: { promptOverlays: { gpt5: { personality: "friendly", // friendly | on | off }, }, }, }, } ``` - `"friendly"` (par défaut) et `"on"` activent la couche conviviale de style d’interaction. - `"off"` désactive uniquement la couche conviviale ; le contrat de comportement GPT-5 balisé reste activé. - L’ancien `plugins.entries.openai.config.personality` est toujours lu lorsque ce réglage partagé n’est pas défini. ### `agents.defaults.heartbeat` Exécutions Heartbeat périodiques. ```json5 { agents: { defaults: { heartbeat: { every: "30m", // 0m disables model: "openai/gpt-5.4-mini", includeReasoning: false, includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) skipWhenBusy: false, // default: false; true also waits for this agent's subagent/nested lanes session: "main", to: "+15555550123", directPolicy: "allow", // allow (default) | block target: "none", // default: none | options: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, timeoutSeconds: 45, }, }, }, } ``` - `every` : chaîne de durée (ms/s/m/h). Par défaut : `30m` (authentification par clé API) ou `1h` (authentification OAuth). Définissez sur `0m` pour désactiver. - `includeSystemPromptSection` : lorsque la valeur est false, omet la section Heartbeat du prompt système et ignore l’injection de `HEARTBEAT.md` dans le contexte d’amorçage. Par défaut : `true`. - `suppressToolErrorWarnings` : lorsque la valeur est true, supprime les charges utiles d’avertissement d’erreur d’outil pendant les exécutions Heartbeat. - `timeoutSeconds` : durée maximale en secondes autorisée pour un tour d’agent Heartbeat avant son abandon. Laissez non défini pour utiliser `agents.defaults.timeoutSeconds`. - `directPolicy` : politique de livraison directe/DM. `allow` (par défaut) autorise la livraison à une cible directe. `block` supprime la livraison à une cible directe et émet `reason=dm-blocked`. - `lightContext` : lorsque la valeur est true, les exécutions Heartbeat utilisent un contexte d’amorçage léger et ne conservent que `HEARTBEAT.md` parmi les fichiers d’amorçage de l’espace de travail. - `isolatedSession` : lorsque la valeur est true, chaque Heartbeat s’exécute dans une nouvelle session sans historique de conversation antérieur. Même modèle d’isolation que cron `sessionTarget: "isolated"`. Réduit le coût en jetons par Heartbeat d’environ 100 000 à environ 2 000-5 000 jetons. - `skipWhenBusy` : lorsque la valeur est true, les exécutions Heartbeat sont différées sur les voies d’activité supplémentaires de cet agent : son propre sous-agent indexé par clé de session ou son travail de commande imbriqué. Les voies Cron diffèrent toujours les Heartbeats, même sans cet indicateur. - Par agent : définissez `agents.list[].heartbeat`. Lorsqu’un agent définit `heartbeat`, **seuls ces agents** exécutent des Heartbeats. - Les Heartbeats exécutent des tours d’agent complets — des intervalles plus courts consomment davantage de jetons. ### `agents.defaults.compaction` ```json5 { agents: { defaults: { compaction: { mode: "safeguard", // default | safeguard provider: "my-provider", // id of a registered compaction provider plugin (optional) timeoutSeconds: 900, reserveTokensFloor: 24000, keepRecentTokens: 50000, identifierPolicy: "strict", // strict | off | custom identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom qualityGuard: { enabled: true, maxRetries: 1 }, midTurnPrecheck: { enabled: false }, // optional Pi tool-loop pressure check postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction maxActiveTranscriptBytes: "20mb", // optional preflight local compaction trigger notifyUser: true, // send brief notices when compaction starts and completes (default: false) memoryFlush: { enabled: true, model: "ollama/qwen3:8b", // optional memory-flush-only model override softThresholdTokens: 6000, systemPrompt: "Session nearing compaction. Store durable memories now.", prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", }, }, }, }, } ``` - `mode` : `default` ou `safeguard` (résumé par morceaux pour les longs historiques). Consultez [Compaction](/fr/concepts/compaction). - `provider` : identifiant d’un Plugin fournisseur de Compaction enregistré. Lorsqu’il est défini, le `summarize()` du fournisseur est appelé à la place du résumé LLM intégré. Se rabat sur l’intégration en cas d’échec. Définir un fournisseur force `mode: "safeguard"`. Consultez [Compaction](/fr/concepts/compaction). - `timeoutSeconds` : nombre maximal de secondes autorisé pour une opération de Compaction unique avant qu’OpenClaw ne l’abandonne. Par défaut : `900`. - `keepRecentTokens` : budget de point de coupure Pi pour conserver mot pour mot la fin la plus récente du transcript. `/compact` manuel respecte ce réglage lorsqu’il est explicitement défini ; sinon, la Compaction manuelle est un point de contrôle strict. - `identifierPolicy` : `strict` (par défaut), `off` ou `custom`. `strict` ajoute en préfixe les instructions intégrées de conservation des identifiants opaques pendant le résumé de Compaction. - `identifierInstructions` : texte personnalisé facultatif de préservation des identifiants utilisé lorsque `identifierPolicy=custom`. - `qualityGuard` : vérifications avec nouvelle tentative en cas de sortie mal formée pour les résumés de sauvegarde. Activé par défaut en mode sauvegarde ; définissez `enabled: false` pour ignorer l’audit. - `midTurnPrecheck` : vérification facultative de pression de boucle d’outils Pi. Lorsque `enabled: true`, OpenClaw vérifie la pression du contexte après l’ajout des résultats d’outils et avant l’appel de modèle suivant. Si le contexte ne tient plus, il abandonne la tentative en cours avant de soumettre le prompt et réutilise le chemin de récupération de pré-vérification existant pour tronquer les résultats d’outils ou compacter puis réessayer. Fonctionne avec les deux modes de Compaction, `default` et `safeguard`. Par défaut : désactivé. - `postCompactionSections` : noms de sections H2/H3 facultatifs d’AGENTS.md à réinjecter après la Compaction. La valeur par défaut est `["Session Startup", "Red Lines"]` ; définissez `[]` pour désactiver la réinjection. Lorsque le réglage est absent ou explicitement défini sur cette paire par défaut, les anciens titres `Every Session`/`Safety` sont aussi acceptés comme repli hérité. - `model` : remplacement facultatif `provider/model-id` pour le résumé de Compaction uniquement. Utilisez-le lorsque la session principale doit conserver un modèle, mais que les résumés de Compaction doivent s’exécuter sur un autre ; lorsqu’il n’est pas défini, la Compaction utilise le modèle principal de la session. - `maxActiveTranscriptBytes` : seuil facultatif en octets (`number` ou chaînes comme `"20mb"`) qui déclenche une Compaction locale normale avant une exécution lorsque le JSONL actif dépasse le seuil. Nécessite `truncateAfterCompaction` afin qu’une Compaction réussie puisse basculer vers un transcript successeur plus petit. Désactivé lorsque non défini ou `0`. - `notifyUser` : lorsque `true`, envoie de brèves notifications à l’utilisateur lorsque la Compaction commence et lorsqu’elle se termine (par exemple, « Compactage du contexte... » et « Compaction terminée »). Désactivé par défaut pour garder la Compaction silencieuse. - `memoryFlush` : tour agentique silencieux avant la Compaction automatique pour stocker des mémoires durables. Définissez `model` sur un fournisseur/modèle exact tel que `ollama/qwen3:8b` lorsque ce tour de maintenance doit rester sur un modèle local ; le remplacement n’hérite pas de la chaîne de repli de la session active. Ignoré lorsque l’espace de travail est en lecture seule. ### `agents.defaults.runRetries` Bornes d’itération de nouvelle tentative de la boucle d’exécution externe pour le runner Pi intégré afin d’éviter les boucles d’exécution infinies pendant la récupération après échec. Notez que ce réglage ne s’applique actuellement qu’au runtime d’agent intégré, et non aux runtimes ACP ou CLI. ```json5 { agents: { defaults: { runRetries: { base: 24, perProfile: 8, min: 32, max: 160, }, }, list: [ { id: "main", runRetries: { max: 50 }, // optional per-agent overrides }, ], }, } ``` - `base` : nombre de base d’itérations de nouvelle tentative d’exécution pour la boucle d’exécution externe. Par défaut : `24`. - `perProfile` : itérations de nouvelle tentative d’exécution supplémentaires accordées par profil de repli candidat. Par défaut : `8`. - `min` : limite absolue minimale pour les itérations de nouvelle tentative d’exécution. Par défaut : `32`. - `max` : limite absolue maximale pour les itérations de nouvelle tentative d’exécution afin d’éviter une exécution incontrôlée. Par défaut : `160`. ### `agents.defaults.contextPruning` Supprime les **anciens résultats d’outils** du contexte en mémoire avant l’envoi au LLM. Ne modifie **pas** l’historique de session sur disque. ```json5 { agents: { defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl ttl: "1h", // duration (ms/s/m/h), default unit: minutes keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, tools: { deny: ["browser", "canvas"] }, }, }, }, } ``` - `mode: "cache-ttl"` active les passes d’élagage. - `ttl` contrôle la fréquence à laquelle l’élagage peut s’exécuter de nouveau (après le dernier accès au cache). - L’élagage réduit d’abord les résultats d’outils trop volumineux de façon souple, puis efface entièrement les résultats d’outils plus anciens si nécessaire. **La réduction souple** conserve le début + la fin et insère `...` au milieu. **L’effacement complet** remplace tout le résultat de l’outil par l’espace réservé. Remarques : - Les blocs d’images ne sont jamais tronqués ni effacés. - Les ratios sont basés sur les caractères (approximatifs), pas sur des nombres exacts de jetons. - S’il existe moins de `keepLastAssistants` messages d’assistant, l’élagage est ignoré. Consultez [Élagage de session](/fr/concepts/session-pruning) pour les détails de comportement. ### Streaming par blocs ```json5 { agents: { defaults: { blockStreamingDefault: "off", // on | off blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) }, }, } ``` - Les canaux autres que Telegram nécessitent `*.blockStreaming: true` explicite pour activer les réponses par blocs. - Remplacements par canal : `channels..blockStreamingCoalesce` (et variantes par compte). Signal/Slack/Discord/Google Chat utilisent par défaut `minChars: 1500`. - `humanDelay` : pause aléatoire entre les réponses par blocs. `natural` = 800 à 2500 ms. Remplacement par agent : `agents.list[].humanDelay`. Consultez [Streaming](/fr/concepts/streaming) pour les détails de comportement et de découpage en fragments. ### Indicateurs de saisie ```json5 { agents: { defaults: { typingMode: "instant", // never | instant | thinking | message typingIntervalSeconds: 6, }, }, } ``` - Valeurs par défaut : `instant` pour les conversations directes/mentions, `message` pour les discussions de groupe sans mention. - Remplacements par session : `session.typingMode`, `session.typingIntervalSeconds`. Consultez [Indicateurs de saisie](/fr/concepts/typing-indicators). ### `agents.defaults.sandbox` Mise en sandbox facultative pour l’agent intégré. Consultez [Mise en sandbox](/fr/gateway/sandboxing) pour le guide complet. ```json5 { agents: { defaults: { sandbox: { mode: "non-main", // off | non-main | all backend: "docker", // docker | ssh | openshell scope: "agent", // session | agent | shared workspaceAccess: "none", // none | ro | rw workspaceRoot: "~/.openclaw/sandboxes", docker: { image: "openclaw-sandbox:bookworm-slim", containerPrefix: "openclaw-sbx-", workdir: "/workspace", readOnlyRoot: true, tmpfs: ["/tmp", "/var/tmp", "/run"], network: "none", user: "1000:1000", capDrop: ["ALL"], env: { LANG: "C.UTF-8" }, setupCommand: "apt-get update && apt-get install -y git curl jq", pidsLimit: 256, memory: "1g", memorySwap: "2g", cpus: 1, ulimits: { nofile: { soft: 1024, hard: 2048 }, nproc: 256, }, seccompProfile: "/path/to/seccomp.json", apparmorProfile: "openclaw-sandbox", dns: ["1.1.1.1", "8.8.8.8"], extraHosts: ["internal.service:10.0.0.5"], binds: ["/home/user/source:/source:rw"], }, ssh: { target: "user@gateway-host:22", command: "ssh", workspaceRoot: "/tmp/openclaw-sandboxes", strictHostKeyChecking: true, updateHostKeys: true, identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", // SecretRefs / inline contents also supported: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, }, browser: { enabled: false, image: "openclaw-sandbox-browser:bookworm-slim", network: "openclaw-sandbox-browser", cdpPort: 9222, cdpSourceRange: "172.21.0.1/32", vncPort: 5900, noVncPort: 6080, headless: false, enableNoVnc: true, allowHostControl: false, autoStart: true, autoStartTimeoutMs: 12000, }, prune: { idleHours: 24, maxAgeDays: 7, }, }, }, }, tools: { sandbox: { tools: { allow: [ "exec", "process", "read", "write", "edit", "apply_patch", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status", ], deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"], }, }, }, } ``` **Backend :** - `docker` : runtime Docker local (par défaut) - `ssh` : runtime distant générique basé sur SSH - `openshell` : runtime OpenShell Lorsque `backend: "openshell"` est sélectionné, les paramètres propres au runtime sont déplacés vers `plugins.entries.openshell.config`. **Configuration du backend SSH :** - `target` : cible SSH au format `user@host[:port]` - `command` : commande du client SSH (par défaut : `ssh`) - `workspaceRoot` : racine distante absolue utilisée pour les espaces de travail par portée - `identityFile` / `certificateFile` / `knownHostsFile` : fichiers locaux existants transmis à OpenSSH - `identityData` / `certificateData` / `knownHostsData` : contenus en ligne ou SecretRefs qu’OpenClaw matérialise en fichiers temporaires au runtime - `strictHostKeyChecking` / `updateHostKeys` : réglages de politique de clé d’hôte OpenSSH **Priorité de l’authentification SSH :** - `identityData` prévaut sur `identityFile` - `certificateData` prévaut sur `certificateFile` - `knownHostsData` prévaut sur `knownHostsFile` - Les valeurs `*Data` basées sur SecretRef sont résolues depuis l’instantané actif du runtime de secrets avant le démarrage de la session sandbox **Comportement du backend SSH :** - initialise l’espace de travail distant une fois après création ou recréation - conserve ensuite l’espace de travail SSH distant comme canonique - achemine `exec`, les outils de fichiers et les chemins de médias via SSH - ne synchronise pas automatiquement les modifications distantes vers l’hôte - ne prend pas en charge les conteneurs de navigateur sandbox **Accès à l’espace de travail :** - `none` : espace de travail sandbox par portée sous `~/.openclaw/sandboxes` - `ro` : espace de travail sandbox dans `/workspace`, espace de travail de l’agent monté en lecture seule dans `/agent` - `rw` : espace de travail de l’agent monté en lecture/écriture dans `/workspace` **Portée :** - `session` : conteneur + espace de travail par session - `agent` : un conteneur + espace de travail par agent (par défaut) - `shared` : conteneur et espace de travail partagés (sans isolation entre sessions) **Configuration du Plugin OpenShell :** ```json5 { plugins: { entries: { openshell: { enabled: true, config: { mode: "mirror", // mirror | remote from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", gateway: "lab", // optional gatewayEndpoint: "https://lab.example", // optional policy: "strict", // optional OpenShell policy id providers: ["openai"], // optional autoProviders: true, timeoutSeconds: 120, }, }, }, }, } ``` **Mode OpenShell :** - `mirror` : initialise le distant depuis le local avant `exec`, puis synchronise en retour après `exec` ; l’espace de travail local reste canonique - `remote` : initialise le distant une fois lors de la création de la sandbox, puis conserve l’espace de travail distant comme canonique En mode `remote`, les modifications locales à l’hôte effectuées en dehors d’OpenClaw ne sont pas synchronisées automatiquement dans la sandbox après l’étape d’initialisation. Le transport utilise SSH vers la sandbox OpenShell, mais le Plugin possède le cycle de vie de la sandbox et la synchronisation miroir facultative. **`setupCommand`** s’exécute une fois après la création du conteneur (via `sh -lc`). Nécessite une sortie réseau, une racine inscriptible et l’utilisateur root. **Les conteneurs utilisent par défaut `network: "none"`** — définissez `"bridge"` (ou un réseau bridge personnalisé) si l’agent a besoin d’un accès sortant. `"host"` est bloqué. `"container:"` est bloqué par défaut sauf si vous définissez explicitement `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (mesure d’urgence). **Les pièces jointes entrantes** sont placées dans `media/inbound/*` dans l’espace de travail actif. **`docker.binds`** monte des répertoires hôte supplémentaires ; les montages globaux et par agent sont fusionnés. **Navigateur sandbox** (`sandbox.browser.enabled`) : Chromium + CDP dans un conteneur. URL noVNC injectée dans le prompt système. Ne nécessite pas `browser.enabled` dans `openclaw.json`. L’accès observateur noVNC utilise l’authentification VNC par défaut et OpenClaw émet une URL à jeton de courte durée (au lieu d’exposer le mot de passe dans l’URL partagée). - `allowHostControl: false` (par défaut) empêche les sessions sandbox de cibler le navigateur de l’hôte. - `network` utilise par défaut `openclaw-sandbox-browser` (réseau bridge dédié). Définissez `bridge` uniquement lorsque vous voulez explicitement une connectivité bridge globale. - `cdpSourceRange` limite éventuellement l’entrée CDP au bord du conteneur à une plage CIDR (par exemple `172.21.0.1/32`). - `sandbox.browser.binds` monte des répertoires hôte supplémentaires uniquement dans le conteneur de navigateur sandbox. Lorsqu’il est défini (y compris `[]`), il remplace `docker.binds` pour le conteneur de navigateur. - Les valeurs par défaut de lancement sont définies dans `scripts/sandbox-browser-entrypoint.sh` et adaptées aux hôtes de conteneurs : - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` - `--no-first-run` - `--no-default-browser-check` - `--disable-3d-apis` - `--disable-gpu` - `--disable-software-rasterizer` - `--disable-dev-shm-usage` - `--disable-background-networking` - `--disable-features=TranslateUI` - `--disable-breakpad` - `--disable-crash-reporter` - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - `--disable-extensions` (activé par défaut) - `--disable-3d-apis`, `--disable-software-rasterizer` et `--disable-gpu` sont activés par défaut et peuvent être désactivés avec `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` si l’utilisation de WebGL/3D l’exige. - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` réactive les extensions si votre workflow en dépend. - `--renderer-process-limit=2` peut être modifié avec `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` ; définissez `0` pour utiliser la limite de processus par défaut de Chromium. - plus `--no-sandbox` lorsque `noSandbox` est activé. - Les valeurs par défaut constituent la base de l’image de conteneur ; utilisez une image de navigateur personnalisée avec un point d’entrée personnalisé pour modifier les valeurs par défaut du conteneur. La mise en sandbox du navigateur et `sandbox.docker.binds` sont réservés à Docker. Construire les images (depuis un checkout source) : ```bash scripts/sandbox-setup.sh # main sandbox image scripts/sandbox-browser-setup.sh # optional browser image ``` Pour les installations npm sans checkout source, consultez [Mise en sandbox § Images et configuration](/fr/gateway/sandboxing#images-and-setup) pour les commandes `docker build` en ligne. ### `agents.list` (remplacements par agent) Utilisez `agents.list[].tts` pour donner à un agent son propre fournisseur TTS, sa voix, son modèle, son style ou son mode TTS automatique. Le bloc de l’agent est fusionné en profondeur par-dessus la configuration globale `messages.tts`, ce qui permet de conserver les identifiants partagés au même endroit tandis que les agents individuels ne redéfinissent que les champs de voix ou de fournisseur dont ils ont besoin. La redéfinition de l’agent actif s’applique aux réponses vocales automatiques, à `/tts audio`, à `/tts status` et à l’outil d’agent `tts`. Consultez [Synthèse vocale](/fr/tools/tts#per-agent-voice-overrides) pour des exemples de fournisseurs et les règles de précédence. ```json5 { agents: { list: [ { id: "main", default: true, name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } thinkingDefault: "high", // per-agent thinking level override reasoningDefault: "on", // per-agent reasoning visibility override fastModeDefault: false, // per-agent fast mode override params: { cacheRetention: "none" }, // overrides matching defaults.models params by key tts: { providers: { elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL" }, }, }, skills: ["docs-search"], // replaces agents.defaults.skills when set identity: { name: "Samantha", theme: "helpful sloth", emoji: "🦥", avatar: "avatars/samantha.png", }, groupChat: { mentionPatterns: ["@openclaw"] }, sandbox: { mode: "off" }, runtime: { type: "acp", acp: { agent: "codex", backend: "acpx", mode: "persistent", cwd: "/workspace/openclaw", }, }, subagents: { allowAgents: ["*"] }, tools: { profile: "coding", allow: ["browser"], deny: ["canvas"], elevated: { enabled: true }, }, }, ], }, } ``` - `id` : identifiant d’agent stable (obligatoire). - `default` : lorsque plusieurs valeurs sont définies, la première l’emporte (un avertissement est journalisé). Si aucune valeur n’est définie, la première entrée de la liste est utilisée par défaut. - `model` : la forme chaîne définit un primaire strict par agent sans solution de repli de modèle ; la forme objet `{ primary }` est également stricte sauf si vous ajoutez `fallbacks`. Utilisez `{ primary, fallbacks: [...] }` pour activer les solutions de repli pour cet agent, ou `{ primary, fallbacks: [] }` pour rendre le comportement strict explicite. Les tâches Cron qui redéfinissent uniquement `primary` héritent toujours des solutions de repli par défaut, sauf si vous définissez `fallbacks: []`. - `params` : paramètres de flux par agent fusionnés par-dessus l’entrée de modèle sélectionnée dans `agents.defaults.models`. Utilisez-les pour des redéfinitions propres à l’agent comme `cacheRetention`, `temperature` ou `maxTokens` sans dupliquer tout le catalogue de modèles. - `tts` : redéfinitions facultatives de synthèse vocale par agent. Le bloc est fusionné en profondeur par-dessus `messages.tts`; conservez donc les identifiants de fournisseur partagés et la politique de repli dans `messages.tts`, puis définissez ici uniquement les valeurs propres à la personnalité, comme le fournisseur, la voix, le modèle, le style ou le mode automatique. - `skills` : liste d’autorisation facultative de Skills par agent. Si elle est omise, l’agent hérite de `agents.defaults.skills` lorsque cette valeur est définie ; une liste explicite remplace les valeurs par défaut au lieu de les fusionner, et `[]` signifie aucune Skills. - `thinkingDefault` : niveau de réflexion par défaut facultatif par agent (`off | minimal | low | medium | high | xhigh | adaptive | max`). Remplace `agents.defaults.thinkingDefault` pour cet agent lorsqu’aucune redéfinition par message ou par session n’est définie. Le profil de fournisseur/modèle sélectionné contrôle les valeurs valides ; pour Google Gemini, `adaptive` conserve la réflexion dynamique gérée par le fournisseur (`thinkingLevel` omis sur Gemini 3/3.1, `thinkingBudget: -1` sur Gemini 2.5). - `reasoningDefault` : visibilité du raisonnement par défaut facultative par agent (`on | off | stream`). Remplace `agents.defaults.reasoningDefault` pour cet agent lorsqu’aucune redéfinition de raisonnement par message ou par session n’est définie. - `fastModeDefault` : valeur par défaut facultative par agent pour le mode rapide (`true | false`). S’applique lorsqu’aucune redéfinition de mode rapide par message ou par session n’est définie. - `models` : redéfinitions facultatives du catalogue de modèles/de l’exécution par agent, indexées par les identifiants complets `provider/model`. Utilisez `models["provider/model"].agentRuntime` pour les exceptions d’exécution par agent. - `runtime` : descripteur d’exécution facultatif par agent. Utilisez `type: "acp"` avec les valeurs par défaut de `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) lorsque l’agent doit utiliser par défaut des sessions du harnais ACP. - `identity.avatar` : chemin relatif à l’espace de travail, URL `http(s)` ou URI `data:`. - `identity` dérive des valeurs par défaut : `ackReaction` depuis `emoji`, `mentionPatterns` depuis `name`/`emoji`. - `subagents.allowAgents` : liste d’autorisation des identifiants d’agent pour les cibles explicites `sessions_spawn.agentId` (`["*"]` = n’importe lequel ; valeur par défaut : même agent uniquement). Incluez l’identifiant du demandeur lorsque les appels `agentId` qui se ciblent eux-mêmes doivent être autorisés. - Garde d’héritage du bac à sable : si la session demandeuse est dans un bac à sable, `sessions_spawn` rejette les cibles qui s’exécuteraient hors bac à sable. - `subagents.requireAgentId` : lorsque cette valeur est vraie, bloque les appels `sessions_spawn` qui omettent `agentId` (force la sélection explicite du profil ; valeur par défaut : faux). --- ## Routage multi-agent Exécutez plusieurs agents isolés dans un seul Gateway. Consultez [Multi-agent](/fr/concepts/multi-agent). ```json5 { agents: { list: [ { id: "home", default: true, workspace: "~/.openclaw/workspace-home" }, { id: "work", workspace: "~/.openclaw/workspace-work" }, ], }, bindings: [ { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } }, { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } }, ], } ``` ### Champs de correspondance des liaisons - `type` (facultatif) : `route` pour le routage normal (un type manquant utilise route par défaut), `acp` pour les liaisons de conversations ACP persistantes. - `match.channel` (obligatoire) - `match.accountId` (facultatif ; `*` = n’importe quel compte ; omis = compte par défaut) - `match.peer` (facultatif ; `{ kind: direct|group|channel, id }`) - `match.guildId` / `match.teamId` (facultatif ; propre au canal) - `acp` (facultatif ; uniquement pour `type: "acp"`) : `{ mode, label, cwd, backend }` **Ordre de correspondance déterministe :** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (exact, sans pair/guilde/équipe) 5. `match.accountId: "*"` (à l’échelle du canal) 6. Agent par défaut Dans chaque niveau, la première entrée `bindings` correspondante l’emporte. Pour les entrées `type: "acp"`, OpenClaw résout par identité exacte de conversation (`match.channel` + compte + `match.peer.id`) et n’utilise pas l’ordre des niveaux de liaison de route ci-dessus. ### Profils d’accès par agent ```json5 { agents: { list: [ { id: "personal", workspace: "~/.openclaw/workspace-personal", sandbox: { mode: "off" }, }, ], }, } ``` ```json5 { agents: { list: [ { id: "family", workspace: "~/.openclaw/workspace-family", sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" }, tools: { allow: [ "read", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status", ], deny: ["write", "edit", "apply_patch", "exec", "process", "browser"], }, }, ], }, } ``` ```json5 { agents: { list: [ { id: "public", workspace: "~/.openclaw/workspace-public", sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" }, tools: { allow: [ "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status", "whatsapp", "telegram", "slack", "discord", "gateway", ], deny: [ "read", "write", "edit", "apply_patch", "exec", "process", "browser", "canvas", "nodes", "cron", "gateway", "image", ], }, }, ], }, } ``` Consultez [Bac à sable et outils multi-agent](/fr/tools/multi-agent-sandbox-tools) pour les détails de précédence. --- ## Session ```json5 { session: { scope: "per-sender", dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer identityLinks: { alice: ["telegram:123456789", "discord:987654321012345678"], }, reset: { mode: "daily", // daily | idle atHour: 4, idleMinutes: 60, }, resetByType: { thread: { mode: "daily", atHour: 4 }, direct: { mode: "idle", idleMinutes: 240 }, group: { mode: "idle", idleMinutes: 120 }, }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, resetArchiveRetention: "30d", // duration or false maxDiskBytes: "500mb", // optional hard budget highWaterBytes: "400mb", // optional cleanup target }, threadBindings: { enabled: true, idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) maxAgeHours: 0, // default hard max age in hours (`0` disables) }, mainKey: "main", // legacy (runtime always uses "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], default: "allow", }, }, } ``` - **`scope`** : stratégie de regroupement de session de base pour les contextes de discussion de groupe. - `per-sender` (par défaut) : chaque expéditeur obtient une session isolée dans un contexte de canal. - `global` : tous les participants d’un contexte de canal partagent une seule session (à utiliser uniquement lorsqu’un contexte partagé est voulu). - **`dmScope`** : mode de regroupement des DM. - `main` : tous les DM partagent la session principale. - `per-peer` : isolation par identifiant d’expéditeur sur l’ensemble des canaux. - `per-channel-peer` : isolation par canal + expéditeur (recommandé pour les boîtes de réception multi-utilisateurs). - `per-account-channel-peer` : isolation par compte + canal + expéditeur (recommandé pour les configurations multicomptes). - **`identityLinks`** : mappe les identifiants canoniques vers des pairs préfixés par fournisseur pour le partage de session entre canaux. Les commandes de dock telles que `/dock_discord` utilisent la même mappe pour basculer la route de réponse de la session active vers un autre pair de canal lié ; voir [Ancrage de canal](/fr/concepts/channel-docking). - **`reset`** : politique de réinitialisation principale. `daily` réinitialise à l’heure locale `atHour` ; `idle` réinitialise après `idleMinutes`. Lorsque les deux sont configurés, le premier qui expire l’emporte. La fraîcheur de la réinitialisation quotidienne utilise le `sessionStartedAt` de la ligne de session ; la fraîcheur de la réinitialisation après inactivité utilise `lastInteractionAt`. Les écritures d’arrière-plan ou d’événements système telles que les heartbeat, les réveils cron, les notifications d’exécution et la tenue interne du Gateway peuvent mettre à jour `updatedAt`, mais elles ne maintiennent pas la fraîcheur des sessions quotidiennes ou inactives. - **`resetByType`** : remplacements par type (`direct`, `group`, `thread`). L’ancien `dm` est accepté comme alias de `direct`. - **`mainKey`** : champ hérité. À l’exécution, `"main"` est toujours utilisé pour le bucket principal de discussion directe. - **`agentToAgent.maxPingPongTurns`** : nombre maximal de tours de réponse aller-retour entre agents pendant les échanges agent-à-agent (entier, plage : `0`-`20`, valeur par défaut : `5`). `0` désactive l’enchaînement ping-pong. - **`sendPolicy`** : correspondance par `channel`, `chatType` (`direct|group|channel`, avec l’alias hérité `dm`), `keyPrefix` ou `rawKeyPrefix`. Le premier refus l’emporte. - **`maintenance`** : contrôles de nettoyage et de rétention du magasin de sessions. - `mode` : `warn` émet uniquement des avertissements ; `enforce` applique le nettoyage. - `pruneAfter` : seuil d’âge pour les entrées obsolètes (par défaut `30d`). - `maxEntries` : nombre maximal d’entrées dans `sessions.json` (par défaut `500`). À l’exécution, le nettoyage par lots est écrit avec un petit tampon de niveau haut pour les plafonds de taille production ; `openclaw sessions cleanup --enforce` applique le plafond immédiatement. - `rotateBytes` : obsolète et ignoré ; `openclaw doctor --fix` le retire des anciennes configurations. - `resetArchiveRetention` : rétention des archives de transcription `*.reset.`. Par défaut, utilise `pruneAfter` ; définir sur `false` pour désactiver. - `maxDiskBytes` : budget disque facultatif pour le répertoire des sessions. En mode `warn`, consigne des avertissements ; en mode `enforce`, supprime d’abord les artefacts/sessions les plus anciens. - `highWaterBytes` : cible facultative après nettoyage du budget. Par défaut, `80%` de `maxDiskBytes`. - **`threadBindings`** : valeurs globales par défaut pour les fonctionnalités de session liées aux fils. - `enabled` : interrupteur principal par défaut (les fournisseurs peuvent le remplacer ; Discord utilise `channels.discord.threadBindings.enabled`) - `idleHours` : inactivité par défaut avant auto-désépinglage, en heures (`0` désactive ; les fournisseurs peuvent le remplacer) - `maxAgeHours` : âge maximal absolu par défaut, en heures (`0` désactive ; les fournisseurs peuvent le remplacer) - `spawnSessions` : garde par défaut pour créer des sessions de travail liées à un fil à partir de `sessions_spawn` et des créations de fils ACP. Vaut `true` par défaut lorsque les liaisons de fils sont activées ; les fournisseurs/comptes peuvent le remplacer. - `defaultSpawnContext` : contexte de sous-agent natif par défaut pour les créations liées à un fil (`"fork"` ou `"isolated"`). Vaut `"fork"` par défaut. --- ## Messages ```json5 { messages: { responsePrefix: "🦞", // or "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, queue: { mode: "steer", // steer | queue (legacy one-at-a-time) | followup | collect | steer-backlog | steer+backlog | interrupt debounceMs: 500, cap: 20, drop: "summarize", // old | new | summarize byChannel: { whatsapp: "steer", telegram: "steer", }, }, inbound: { debounceMs: 2000, // 0 disables byChannel: { whatsapp: 5000, slack: 1500, }, }, }, } ``` ### Préfixe de réponse Remplacements par canal/compte : `channels..responsePrefix`, `channels..accounts..responsePrefix`. Résolution (le plus spécifique l’emporte) : compte → canal → global. `""` désactive et arrête la cascade. `"auto"` dérive `[{identity.name}]`. **Variables de modèle :** | Variable | Description | Exemple | | ----------------- | --------------------------- | --------------------------- | | `{model}` | Nom court du modèle | `claude-opus-4-6` | | `{modelFull}` | Identifiant complet du modèle | `anthropic/claude-opus-4-6` | | `{provider}` | Nom du fournisseur | `anthropic` | | `{thinkingLevel}` | Niveau de réflexion actuel | `high`, `low`, `off` | | `{identity.name}` | Nom d’identité de l’agent | (identique à `"auto"`) | Les variables ne sont pas sensibles à la casse. `{think}` est un alias de `{thinkingLevel}`. ### Réaction d’accusé de réception - Par défaut, utilise `identity.emoji` de l’agent actif, sinon `"👀"`. Définir `""` pour désactiver. - Remplacements par canal : `channels..ackReaction`, `channels..accounts..ackReaction`. - Ordre de résolution : compte → canal → `messages.ackReaction` → repli sur l’identité. - Portée : `group-mentions` (par défaut), `group-all`, `direct`, `all`. - `removeAckAfterReply` : supprime l’accusé après la réponse sur les canaux prenant en charge les réactions, comme Slack, Discord, Telegram, WhatsApp et iMessage. - `messages.statusReactions.enabled` : active les réactions de statut de cycle de vie sur Slack, Discord et Telegram. Sur Slack et Discord, une valeur non définie maintient les réactions de statut activées lorsque les réactions d’accusé sont actives. Sur Telegram, définissez-la explicitement sur `true` pour activer les réactions de statut de cycle de vie. ### Anti-rebond entrant Regroupe les messages textuels rapides du même expéditeur en un seul tour d’agent. Les médias/pièces jointes déclenchent un envoi immédiat. Les commandes de contrôle contournent l’anti-rebond. ### TTS (synthèse vocale) ```json5 { messages: { tts: { auto: "always", // off | always | inbound | tagged mode: "final", // final | all provider: "elevenlabs", summaryModel: "openai/gpt-4.1-mini", modelOverrides: { enabled: true }, maxTextLength: 4000, timeoutMs: 30000, prefsPath: "~/.openclaw/settings/tts.json", providers: { elevenlabs: { apiKey: "elevenlabs_api_key", baseUrl: "https://api.elevenlabs.io", voiceId: "voice_id", modelId: "eleven_multilingual_v2", seed: 42, applyTextNormalization: "auto", languageCode: "en", voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0, }, }, microsoft: { voice: "en-US-AvaMultilingualNeural", lang: "en-US", outputFormat: "audio-24khz-48kbitrate-mono-mp3", }, openai: { apiKey: "openai_api_key", baseUrl: "https://api.openai.com/v1", model: "gpt-4o-mini-tts", voice: "alloy", }, }, }, }, } ``` - `auto` contrôle le mode auto-TTS par défaut : `off`, `always`, `inbound` ou `tagged`. `/tts on|off` peut remplacer les préférences locales, et `/tts status` affiche l’état effectif. - `summaryModel` remplace `agents.defaults.model.primary` pour le résumé automatique. - `modelOverrides` est activé par défaut ; `modelOverrides.allowProvider` vaut `false` par défaut (activation explicite). - Les clés API se replient sur `ELEVENLABS_API_KEY`/`XI_API_KEY` et `OPENAI_API_KEY`. - Les fournisseurs vocaux intégrés appartiennent aux plugins. Si `plugins.allow` est défini, incluez chaque plugin de fournisseur TTS que vous voulez utiliser, par exemple `microsoft` pour Edge TTS. L’ancien identifiant de fournisseur `edge` est accepté comme alias de `microsoft`. - `providers.openai.baseUrl` remplace le point de terminaison OpenAI TTS. L’ordre de résolution est la configuration, puis `OPENAI_TTS_BASE_URL`, puis `https://api.openai.com/v1`. - Lorsque `providers.openai.baseUrl` pointe vers un point de terminaison non OpenAI, OpenClaw le traite comme un serveur TTS compatible OpenAI et assouplit la validation du modèle/de la voix. --- ## Talk Valeurs par défaut pour le mode Talk (macOS/iOS/Android). ```json5 { talk: { provider: "elevenlabs", providers: { elevenlabs: { voiceId: "elevenlabs_voice_id", voiceAliases: { Clawd: "EXAVITQu4vr4xnSDxMaL", Roger: "CwhRBWXzGAHq8TQ4Fs17", }, modelId: "eleven_v3", outputFormat: "mp3_44100_128", apiKey: "elevenlabs_api_key", }, mlx: { modelId: "mlx-community/Soprano-80M-bf16", }, system: {}, }, consultThinkingLevel: "low", consultFastMode: true, speechLocale: "ru-RU", silenceTimeoutMs: 1500, interruptOnSpeech: true, realtime: { provider: "openai", providers: { openai: { model: "gpt-realtime-2", voice: "cedar", }, }, instructions: "Speak warmly and keep answers brief.", mode: "realtime", transport: "webrtc", brain: "agent-consult", }, }, } ``` - `talk.provider` doit correspondre à une clé dans `talk.providers` lorsque plusieurs fournisseurs Talk sont configurés. - Les anciennes clés Talk plates (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) sont uniquement destinées à la compatibilité. Exécutez `openclaw doctor --fix` pour réécrire la configuration persistée vers `talk.providers.`. - Les identifiants de voix se replient sur `ELEVENLABS_VOICE_ID` ou `SAG_VOICE_ID`. - `providers.*.apiKey` accepte les chaînes en clair ou les objets SecretRef. - Le repli `ELEVENLABS_API_KEY` ne s’applique que lorsqu’aucune clé API Talk n’est configurée. - `providers.*.voiceAliases` permet aux directives Talk d’utiliser des noms conviviaux. - `providers.mlx.modelId` sélectionne le dépôt Hugging Face utilisé par l’assistant MLX local macOS. S’il est omis, macOS utilise `mlx-community/Soprano-80M-bf16`. - La lecture macOS MLX passe par l’assistant intégré `openclaw-mlx-tts` lorsqu’il est présent, ou par un exécutable sur `PATH` ; `OPENCLAW_MLX_TTS_BIN` remplace le chemin de l’assistant pour le développement. - `consultThinkingLevel` contrôle le niveau de réflexion pour l’exécution complète de l’agent OpenClaw derrière les appels `openclaw_agent_consult` en temps réel de Control UI Talk. Laissez non défini pour préserver le comportement normal de session/modèle. - `consultFastMode` définit un remplacement ponctuel du mode rapide pour les consultations en temps réel Control UI Talk sans modifier le paramètre de mode rapide normal de la session. - `speechLocale` définit l’identifiant de locale BCP 47 utilisé par la reconnaissance vocale Talk iOS/macOS. Laissez non défini pour utiliser la valeur par défaut de l’appareil. - `silenceTimeoutMs` contrôle la durée pendant laquelle le mode Talk attend après le silence de l’utilisateur avant d’envoyer la transcription. Une valeur non définie conserve la fenêtre de pause par défaut de la plateforme (`700 ms on macOS and Android, 900 ms on iOS`). - `realtime.instructions` ajoute des instructions système destinées au fournisseur au prompt en temps réel intégré d’OpenClaw, afin que le style vocal puisse être configuré sans perdre le guidage par défaut de `openclaw_agent_consult`. --- ## Associés - [Référence de configuration](/fr/gateway/configuration-reference) — toutes les autres clés de configuration - [Configuration](/fr/gateway/configuration) — tâches courantes et configuration rapide - [Exemples de configuration](/fr/gateway/configuration-examples)