Configuration — agents

​

Valeurs par défaut des agents

​

agents.defaults.workspace

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

​

agents.defaults.repoRoot

{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
}

​

agents.defaults.skills

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" }, // hérite de github, weather
      { id: "docs", skills: ["docs-search"] }, // remplace les valeurs par défaut
      { id: "locked-down", skills: [] }, // aucune skill
    ],
  },
}

• 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 agents.list[].skills non vide constitue l’ensemble final pour cet agent ; elle n’est pas fusionnée avec les valeurs par défaut.

​

agents.defaults.skipBootstrap

{
  agents: { defaults: { skipBootstrap: true } },
}

​

agents.defaults.skipOptionalBootstrapFiles

{
  agents: {
    defaults: {
      skipOptionalBootstrapFiles: ["SOUL.md", "USER.md"],
    },
  },
}

​

agents.defaults.contextInjection

• "continuation-skip" : les tours de continuation sûrs (après une réponse d’assistant terminée) ignorent la réinjection de l’amorçage 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 tout de même le contexte.
• "never" : désactive l’injection de l’amorçage de l’espace de travail et des fichiers de contexte à chaque tour. Utilisez cette option uniquement pour les agents qui contrôlent 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 amorçage). Les tours Heartbeat et de récupération après Compaction ignorent également l’injection.

{
  agents: { defaults: { contextInjection: "continuation-skip" } },
}

​

agents.defaults.bootstrapMaxChars

{
  agents: { defaults: { bootstrapMaxChars: 20000 } },
}

​

agents.defaults.bootstrapTotalMaxChars

{
  agents: { defaults: { bootstrapTotalMaxChars: 60000 } },
}

​

Remplacements de profil d’amorçage par agent

{
  agents: {
    defaults: {
      contextInjection: "continuation-skip",
      bootstrapMaxChars: 20000,
      bootstrapTotalMaxChars: 60000,
    },
    list: [
      {
        id: "strict-worker",
        contextInjection: "always",
        bootstrapMaxChars: 50000,
        bootstrapTotalMaxChars: 300000,
      },
    ],
  },
}

​

agents.defaults.bootstrapPromptTruncationWarning

• "off" : n’injecte jamais de texte d’avis de troncature dans le prompt système.
• "once" : injecte un avis concis une fois par signature de troncature unique.
• "always" : injecte un avis concis à chaque exécution lorsqu’une troncature existe (recommandé).

{
  agents: { defaults: { bootstrapPromptTruncationWarning: "always" } }, // off | once | always
}

​

Carte de propriété des budgets de contexte

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars : injection normale de l’amorçage de l’espace de travail.
• agents.defaults.startupContext.* : préambule ponctuel de réinitialisation/démarrage pour l’exécution du modèle, incluant les fichiers memory/*.md quotidiens récents. Les commandes de chat simples /new et /reset sont accusées réception sans invoquer le modèle.
• skills.limits.* : la liste compacte de skills injectée dans le prompt système.
• agents.defaults.contextLimits.* : extraits runtime bornés et blocs injectés appartenant au runtime.
• memory.qmd.limits.* : extrait indexé de recherche mémoire et dimensionnement de l’injection.

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].contextInjection
• agents.list[].bootstrapMaxChars
• agents.list[].bootstrapTotalMaxChars
• agents.list[].contextLimits.*

​

agents.defaults.startupContext

{
  agents: {
    defaults: {
      startupContext: {
        enabled: true,
        applyOn: ["new", "reset"],
        dailyMemoryDays: 2,
        maxFileBytes: 16384,
        maxFileChars: 1200,
        maxTotalChars: 2800,
      },
    },
  },
}

​

agents.defaults.contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        memoryGetDefaultLines: 120,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars : plafond 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 : plafond avancé des résultats d’outils en direct utilisé pour les résultats persistés et la récupération en cas de dépassement. Laissez-le non défini pour le plafond automatique du contexte modèle : 16000 caractères sous 100 000 tokens, 32000 caractères à 100 000+ tokens et 64000 caractères à 200 000+ tokens. Les valeurs explicites jusqu’à 1000000 sont acceptées pour les modèles à long contexte, mais le plafond effectif reste limité à environ 30 % de la fenêtre de contexte du modèle. openclaw doctor --deep affiche le plafond effectif, et doctor n’émet un avertissement que lorsqu’un remplacement explicite est obsolète ou sans effet.
• postCompactionMaxChars : plafond d’extrait AGENTS.md utilisé pendant l’injection de rafraîchissement après Compaction.

​

agents.list[].contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
      },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000, // plafond avancé pour cet agent
        },
      },
    ],
  },
}

​

skills.limits.maxSkillsPromptChars

{
  skills: {
    limits: {
      maxSkillsPromptChars: 18000,
    },
  },
}

​

agents.list[].skillsLimits.maxSkillsPromptChars

{
  agents: {
    list: [
      {
        id: "tiny-local",
        skillsLimits: {
          maxSkillsPromptChars: 6000,
        },
      },
    ],
  },
}

​

agents.defaults.imageMaxDimensionPx

{
  agents: { defaults: { imageMaxDimensionPx: 1200 } },
}

​

agents.defaults.imageQuality

• auto : s’adapte aux limites du modèle et au nombre d’images.
• efficient : privilégie des images plus petites pour réduire l’utilisation de tokens et d’octets.
• balanced : utilise l’échelle standard intermédiaire.
• high : préserve davantage de détails pour les captures d’écran, les diagrammes et les images de documents.

{
  agents: { defaults: { imageQuality: "auto" } },
}

​

agents.defaults.userTimezone

{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}

​

agents.defaults.timeFormat

{
  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
}

​

agents.defaults.model

{
  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" }, // paramètres fournisseur par défaut globaux
      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 des modèles de basculement ordonnés.
• imageModel : accepte soit une chaîne ("provider/model"), soit un objet ({ primary, fallbacks }).
  • Utilisé par le chemin d’outil image comme configuration de modèle de vision.
  • Également utilisé comme routage de repli 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 par compatibilité ; si un identifiant nu correspond de manière unique à une entrée configurée compatible image 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 native Gemini, 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 fournisseur correspondante (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 une valeur par défaut de fournisseur adossée à 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 musicale 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 une valeur par défaut de fournisseur adossée à une authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération musicale 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 fournisseur correspondante.
• 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 une valeur par défaut de fournisseur adossée à 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 fournisseur correspondante.
  • Le Plugin officiel 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 de modèle.
  • Si omis, l’outil PDF se replie sur imageModel, puis sur le modèle résolu de session/par défaut.
• pdfMaxBytesMb : limite de taille PDF par défaut pour l’outil pdf lorsque maxBytesMb n’est pas transmis au moment de l’appel.
• pdfMaxPages : nombre maximal de pages considéré par défaut par le mode de repli d’extraction dans l’outil pdf.
• verboseDefault : niveau détaillé 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’outil de brouillon de progression. Valeurs : "explain" (par défaut, libellés humains compacts) ou "raw" (ajoute la commande/le détail brut lorsque 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 que pour les propriétaires, les expéditeurs autorisés ou les 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 ex. openai/gpt-5.5 pour un accès OpenAI par clé d’API 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 replie sur le fournisseur par défaut configuré (comportement de compatibilité obsolète, préférez donc un provider/model explicite). Si ce fournisseur n’expose plus le modèle par défaut configuré, OpenClaw se replie sur le premier fournisseur/modèle configuré au lieu de remonter une valeur par défaut de fournisseur supprimé obsolète.
• models : catalogue de modèles configuré et liste d’autorisation pour /model. Chaque entrée peut inclure alias (raccourci) et params (propres au fournisseur, par exemple temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, routage OpenRouter provider, chat_template_kwargs, extra_body/extraBody).
  • Utilisez des entrées provider/* comme "openai/*": {} ou "vllm/*": {} pour afficher tous les modèles découverts pour les fournisseurs sélectionnés sans lister manuellement chaque identifiant de modèle.
  • Ajoutez agentRuntime à une entrée provider/* lorsque chaque modèle découvert dynamiquement pour ce fournisseur doit utiliser le même runtime. La politique de runtime exacte provider/model prévaut toujours sur le joker.
  • Modifications sûres : utilisez openclaw config set agents.defaults.models '<json>' --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’onboarding limités à un fournisseur fusionnent les modèles de fournisseur sélectionnés dans cette carte 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.
• params : paramètres de fournisseur globaux par défaut appliqués à tous les modèles. Définis dans agents.defaults.params (par ex. { 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 pour plus de détails.
• models.providers.openrouter.params.provider : politique de routage fournisseur par défaut à l’échelle d’OpenRouter. OpenClaw la transmet à l’objet provider de la requête OpenRouter ; les paramètres par modèle agents.defaults.models["openrouter/<model>"].params.provider et les paramètres d’agent remplacent par clé. Voir routage fournisseur OpenRouter.
• params.extra_body/params.extraBody : JSON avancé de transmission directe fusionné dans les corps de requête api: "openai-completions" pour les proxys compatibles OpenAI. S’il entre en collision avec des clés de requête générées, le corps supplémentaire gagne ; les routes de complétions non natives retirent quand même ensuite le store propre à OpenAI.
• params.chat_template_kwargs : arguments de modèle de chat vLLM/compatibles OpenAI fusionnés dans les corps de requête de premier niveau api: "openai-completions". Pour vllm/nemotron-3-* avec la réflexion désactivée, le Plugin vLLM inclus 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 a toujours la priorité finale. Les modèles de réflexion vLLM Qwen et Nemotron configurés exposent des choix /think binaires (off, on) au lieu de l’échelle d’effort à plusieurs niveaux.
• compat.thinkingFormat : style de charge utile de réflexion compatible OpenAI. Utilisez "together" pour reasoning.enabled de style Together, "qwen" pour enable_thinking de premier niveau 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 chat au niveau requête, comme vLLM. OpenClaw mappe la réflexion désactivée à false et la réflexion activée à true, et les modèles vLLM Qwen configurés exposent des choix /think binaires pour ces formats.
• compat.supportedReasoningEfforts : liste d’efforts de raisonnement compatible 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 commande, les lignes de session Gateway, la validation des patchs 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 : option d’activation propre à Z.AI pour la réflexion préservée. Lorsqu’elle est activée et que la réflexion est active, OpenClaw envoie thinking.clear_thinking: false et rejoue le reasoning_content antérieur ; voir réflexion Z.AI et réflexion préservée.
• localService : gestionnaire de processus facultatif de 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.
• La politique de runtime appartient aux fournisseurs ou aux modèles, pas à agents.defaults. Utilisez models.providers.<provider>.agentRuntime pour des règles à l’échelle du fournisseur ou agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime pour des 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 repli) enregistrent la forme objet canonique et préservent les listes de repli existantes lorsque possible.
• maxConcurrent : nombre maximal d’exécutions d’agents parallèles entre sessions (chaque session reste sérialisée). Par défaut : 4.

​

Politique de runtime

{
  models: {
    providers: {
      openai: {
        agentRuntime: { id: "codex" },
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      models: {
        "anthropic/claude-opus-4-8": {
          agentRuntime: { id: "claude-cli" },
        },
        "vllm/*": {
          agentRuntime: { id: "openclaw" },
        },
      },
    },
  },
}

• id : "auto", "openclaw", un id 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 revendiquer les tours pris en charge et utilise OpenClaw lorsqu’aucun harnais ne correspond. Un runtime de plugin explicite comme id: "codex" exige ce harnais et échoue en mode fermé s’il est indisponible ou échoue.
• id: "pi" n’est accepté que comme alias obsolète de openclaw afin de préserver les configurations livrées avec v2026.5.22 et antérieures. Les nouvelles configurations doivent utiliser openclaw.
• La précédence du runtime est d’abord la politique exacte du modèle (agents.list[].models["provider/model"], agents.defaults.models["provider/model"] ou models.providers.<provider>.models[]), puis agents.list[] / agents.defaults.models["provider/*"], puis la politique à l’échelle du fournisseur dans models.providers.<provider>.agentRuntime.
• Les clés de runtime d’agent complet sont héritées. agents.defaults.agentRuntime, agents.list[].agentRuntime, les épinglages de runtime de session et OPENCLAW_AGENT_RUNTIME sont ignorés par la sélection du runtime. 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" pour le fournisseur/modèle reste valide lorsque vous voulez le rendre explicite.
• Pour les déploiements Claude CLI, privilégiez model: "anthropic/claude-opus-4-8" 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 garder la sélection fournisseur/modèle canonique et placer le backend d’exécution dans la politique de runtime fournisseur/modèle.
• Cela contrôle uniquement l’exécution des tours d’agent textuels. La génération de médias, la vision, les PDF, la musique, la vidéo et la synthèse vocale utilisent toujours leurs paramètres fournisseur/modèle.

​

agents.defaults.cliBackends

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "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 sont d’abord textuels ; 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 des chemins de fichiers.
• reseedFromRawTranscriptWhenUncompacted: true permet à un backend de récupérer des sessions invalidées sûres à partir d’une queue bornée de transcript OpenClaw brut avant que le premier résumé de Compaction existe. Les changements de profil d’authentification ou d’époque d’identifiants ne réensemencent toujours jamais à partir du brut.

​

agents.defaults.promptOverlays

{
  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 encore lu lorsque ce réglage partagé n’est pas défini.

​

agents.defaults.heartbeat

{
  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). Valeur par défaut : 30m (authentification par clé API) ou 1h (authentification OAuth). Définissez sur 0m pour désactiver.
• includeSystemPromptSection : lorsque false, omet la section Heartbeat du prompt système et ignore l’injection de HEARTBEAT.md dans le contexte de bootstrap. Valeur par défaut : true.
• suppressToolErrorWarnings : lorsque 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 lorsqu’il est défini, sinon la cadence Heartbeat plafonnée à 600 secondes.
• directPolicy : politique de livraison directe/DM. allow (par défaut) autorise la livraison vers une cible directe. block supprime la livraison vers une cible directe et émet reason=dm-blocked.
• lightContext : lorsque true, les exécutions Heartbeat utilisent un contexte de bootstrap léger et ne conservent que HEARTBEAT.md parmi les fichiers de bootstrap de l’espace de travail.
• isolatedSession : lorsque true, chaque Heartbeat s’exécute dans une session fraîche, sans historique de conversation antérieur. Même schéma d’isolation que le cron sessionTarget: "isolated". Réduit le coût en tokens par Heartbeat d’environ 100 K à environ 2 à 5 K tokens.
• skipWhenBusy : lorsque true, les exécutions Heartbeat sont différées sur les voies occupées 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 ce drapeau.
• 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 plus de tokens.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id of a registered compaction provider plugin (optional)
        timeoutSeconds: 180,
        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 tool-loop pressure check
        postCompactionSections: ["Session Startup", "Red Lines"], // opt in to AGENTS.md section 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). Voir Compaction.
• provider : identifiant d’un Plugin fournisseur de compaction enregistré. Lorsqu’il est défini, la fonction summarize() du fournisseur est appelée à la place du résumé LLM intégré. Revient au mécanisme intégré en cas d’échec. Définir un fournisseur force mode: "safeguard". Voir Compaction.
• timeoutSeconds : nombre maximal de secondes autorisées pour une seule opération de compaction avant qu’OpenClaw ne l’abandonne. Valeur par défaut : 180.
• keepRecentTokens : budget de point de coupure de l’agent pour conserver textuellement la fin la plus récente de la transcription. La commande manuelle /compact le respecte 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 préfixe des consignes 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 protection. Activé par défaut en mode de protection ; définissez enabled: false pour ignorer l’audit.
• midTurnPrecheck : vérification facultative de pression de la boucle d’outils. Lorsque enabled: true, OpenClaw vérifie la pression du contexte après l’ajout des résultats d’outils et avant le prochain appel au modèle. 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 modes de compaction default et safeguard. Valeur par défaut : désactivé.
• postCompactionSections : noms facultatifs de sections H2/H3 d’AGENTS.md à réinjecter après la compaction. La réinjection est désactivée lorsque cette option n’est pas définie ou vaut []. Définir explicitement ["Session Startup", "Red Lines"] active cette paire et conserve le repli hérité Every Session/Safety. Activez ceci uniquement lorsque le contexte supplémentaire vaut le risque de dupliquer des consignes de projet déjà capturées dans le résumé de compaction.
• model : provider/model-id facultatif ou alias simple issu de agents.defaults.models pour le résumé de compaction uniquement. Les alias simples sont résolus avant l’envoi ; les identifiants de modèles littéraux configurés gardent la priorité en cas de collision. Utilisez ceci 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 effectuer une rotation vers une transcription successeur plus petite. Désactivé lorsqu’il n’est pas défini ou vaut 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 que la compaction reste silencieuse.
• memoryFlush : tour agentique silencieux avant l’auto-compaction pour stocker des souvenirs durables. Définissez model sur un fournisseur/modèle exact comme ollama/qwen3:8b lorsque ce tour de maintenance doit rester sur un modèle local ; la substitution 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

{
  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. Valeur par défaut : 24.
• perProfile : itérations supplémentaires de nouvelle tentative d’exécution accordées par candidat de profil de repli. Valeur par défaut : 8.
• min : limite absolue minimale pour les itérations de nouvelle tentative d’exécution. Valeur 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. Valeur par défaut : 160.

​

agents.defaults.contextPruning

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

​

Streaming par blocs

{
  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.
• Substitutions de canal : channels.<channel>.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. Substitution par agent : agents.list[].humanDelay.

​

Indicateurs de saisie

{
  agents: {
    defaults: {
      typingMode: "instant", // never | instant | thinking | message
      typingIntervalSeconds: 6,
    },
  },
}

• Valeurs par défaut : instant pour les conversations directes/mentions, message pour les conversations de groupe sans mention.
• Substitutions par session : session.typingMode, session.typingIntervalSeconds.

​

agents.defaults.sandbox

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

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

scripts/sandbox-setup.sh           # main sandbox image
scripts/sandbox-browser-setup.sh   # optional browser image

​

agents.list (remplacements par agent)

{
  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: { speakerVoiceId: "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 sont définis, le premier gagne (avertissement journalisé). Si aucun n’est défini, la première entrée de liste est la valeur par défaut.
• model : la forme chaîne définit un modèle principal strict par agent sans modèle de secours ; la forme objet { primary } est également stricte sauf si vous ajoutez fallbacks. Utilisez { primary, fallbacks: [...] } pour inscrire cet agent au repli, ou { primary, fallbacks: [] } pour rendre explicite le comportement strict. Les tâches Cron qui ne remplacent que primary héritent toujours des replis 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 ceci pour les remplacements propres à l’agent comme cacheRetention, temperature ou maxTokens sans dupliquer tout le catalogue de modèles.
• tts : remplacements de synthèse vocale facultatifs par agent. Le bloc est fusionné en profondeur par-dessus messages.tts, donc conservez les identifiants de fournisseur partagés et la stratégie de repli dans messages.tts, et définissez ici uniquement les valeurs propres à la persona, comme le fournisseur, la voix, le modèle, le style ou le mode automatique.
• skills : liste d’autorisation Skills facultative par agent. Si elle est omise, l’agent hérite de agents.defaults.skills lorsque c’est défini ; 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’aucun remplacement par message ou par session n’est défini. Le profil fournisseur/modèle sélectionné contrôle les valeurs valides ; pour Google Gemini, adaptive conserve la réflexion dynamique possédé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’aucun remplacement de raisonnement par message ou par session n’est défini.
• fastModeDefault : valeur par défaut facultative par agent pour le mode rapide ("auto" | true | false). S’applique lorsqu’aucun remplacement de mode rapide par message ou par session n’est défini.
• models : remplacements facultatifs par agent du catalogue de modèles/de l’exécution, indexés par 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 runtime.acp (agent, backend, mode, cwd) lorsque l’agent doit utiliser par défaut des sessions de harnais ACP.
• identity.avatar : chemin relatif à l’espace de travail, URL http(s) ou URI data:.
• Les fichiers image identity.avatar locaux relatifs à l’espace de travail sont limités à 2 Mo. Les URL http(s) et les URI data: ne sont pas vérifiées avec la limite locale de taille de fichier.
• identity dérive les valeurs par défaut : ackReaction depuis emoji, mentionPatterns depuis name/emoji.
• subagents.allowAgents : liste d’autorisation d’identifiants d’agents configurés pour les cibles explicites sessions_spawn.agentId (["*"] = toute cible configurée ; par défaut : même agent uniquement). Incluez l’identifiant du demandeur lorsque les appels agentId ciblant lui-même doivent être autorisés. Les entrées obsolètes dont la configuration d’agent a été supprimée sont rejetées par sessions_spawn et omises de agents_list ; exécutez openclaw doctor --fix pour les nettoyer, ou ajoutez une entrée minimale agents.list[] si cette cible doit rester invocable tout en héritant des valeurs par défaut.
• Garde d’héritage du bac à sable : si la session demandeuse est en bac à sable, sessions_spawn rejette les cibles qui s’exécuteraient sans bac à sable.
• subagents.requireAgentId : lorsque vrai, bloque les appels sessions_spawn qui omettent agentId (force une sélection explicite de profil ; par défaut : false).

​

Routage multi-agent

{
  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 de liaison

• type (facultatif) : route pour le routage normal (un type manquant vaut par défaut route), acp pour les liaisons de conversation 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 }

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (exact, sans pair/guild/team)
5. match.accountId: "*" (à l’échelle du canal)
6. Agent par défaut

​

Profils d’accès par agent

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
    ],
  },
}

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

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

​

Session

{
  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: "enforce", // enforce (default) | warn
      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",
    },
  },
}

​

Messages

{
  messages: {
    responsePrefix: "🦞", // or "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "followup", // steer | followup | collect | interrupt
      debounceMs: 500,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "followup",
        telegram: "followup",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

Préfixe de réponse

​

Réaction d’accusé de réception

• Utilise par défaut identity.emoji de l’agent actif, sinon "👀". Définissez "" pour désactiver.
• Remplacements par canal : channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.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 tels que Slack, Discord, Signal, Telegram, WhatsApp et iMessage.
• messages.statusReactions.enabled : active les réactions d’état du cycle de vie sur Slack, Discord, Signal, Telegram et WhatsApp. Sur Slack et Discord, l’absence de valeur conserve les réactions d’état activées lorsque les réactions d’accusé sont actives. Sur Signal, Telegram et WhatsApp, définissez explicitement cette option sur true pour activer les réactions d’état du cycle de vie.
• messages.statusReactions.emojis : remplace les clés d’emoji du cycle de vie : queued, thinking, compacting, tool, coding, web, deploy, build, concierge, done, error, stallSoft et stallHard. Telegram n’autorise qu’un ensemble fixe de réactions ; les emoji configurés non pris en charge se replient donc sur la variante d’état prise en charge la plus proche pour cette discussion.

​

Anti-rebond entrant

​

TTS (synthèse vocale)

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-5.4-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      providers: {
        elevenlabs: {
          apiKey: "elevenlabs_api_key",
          baseUrl: "https://api.elevenlabs.io",
          speakerVoiceId: "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: {
          speakerVoice: "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",
          speakerVoice: "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 (opt-in).
• Les clés d’API se rabattent sur ELEVENLABS_API_KEY/XI_API_KEY et OPENAI_API_KEY.
• Les fournisseurs de synthèse vocale groupés appartiennent aux plugins. Si plugins.allow est défini, incluez chaque plugin 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 TTS OpenAI. 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 et de la voix.

​

Talk

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        speakerVoiceId: "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",
          speakerVoice: "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 clés Talk plates héritées (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 dans talk.providers.<provider>.
• Les identifiants de voix se rabattent sur ELEVENLABS_VOICE_ID ou SAG_VOICE_ID.
• providers.*.apiKey accepte des chaînes en clair ou des objets SecretRef.
• Le repli ELEVENLABS_API_KEY s’applique uniquement lorsqu’aucune clé d’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 MLX sur macOS passe par l’assistant groupé 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 Control UI Talk realtime openclaw_agent_consult. Laissez-le non défini pour préserver le comportement normal de la session/du modèle.
• consultFastMode définit un remplacement ponctuel du mode rapide pour les consultations Control UI Talk realtime sans modifier le réglage normal du mode rapide de la session.
• speechLocale définit l’identifiant de locale BCP 47 utilisé par la reconnaissance vocale Talk iOS/macOS. Laissez-le non défini pour utiliser la valeur par défaut de l’appareil.
• silenceTimeoutMs contrôle combien de temps le mode Talk attend après le silence de l’utilisateur avant d’envoyer la transcription. Non défini, il 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 realtime intégré d’OpenClaw, afin que le style vocal puisse être configuré sans perdre les instructions par défaut de openclaw_agent_consult.
• realtime.consultRouting contrôle le repli du relais Gateway lorsque le fournisseur realtime produit une transcription utilisateur finale sans openclaw_agent_consult : provider-direct préserve les réponses directes du fournisseur, tandis que force-agent-consult achemine la requête finalisée via OpenClaw.

​

Connexe

• Référence de configuration — toutes les autres clés de configuration
• Configuration — tâches courantes et configuration rapide
• Exemples de configuration