Configuration — agents

​

Valeurs par défaut de l’agent

​

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" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

• Omettez agents.defaults.skills pour des Skills non restreintes par défaut.
• Omettez agents.list[].skills pour hériter des valeurs par défaut.
• Définissez agents.list[].skills: [] pour n’avoir aucune Skill.
• Une liste agents.list[].skills non vide constitue l’ensemble final pour cet agent ; elle ne fusionne pas avec les valeurs par défaut.

​

agents.defaults.skipBootstrap

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

​

agents.defaults.contextInjection

• "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.

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

​

agents.defaults.bootstrapMaxChars

{
  agents: { defaults: { bootstrapMaxChars: 12000 } },
}

​

agents.defaults.bootstrapTotalMaxChars

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

​

agents.defaults.bootstrapPromptTruncationWarning

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

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

​

Carte de propriété du budget de contexte

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars : injection bootstrap normale de l’espace de travail.
• agents.defaults.startupContext.* : prélude de démarrage ponctuel pour /new et /reset, y compris les fichiers récents memory/*.md quotidiens.
• skills.limits.* : la liste compacte des Skills injectée dans le prompt système.
• agents.defaults.contextLimits.* : extraits d’exécution bornés et blocs injectés appartenant à l’exécution.
• memory.qmd.limits.* : dimensionnement des extraits et de l’injection pour la recherche en mémoire indexée.

• agents.list[].skillsLimits.maxSkillsPromptChars
• 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,
        toolResultMaxChars: 16000,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars : limite par défaut de l’extrait memory_get avant l’ajout des métadonnées de troncature et de l’avis de continuation.
• memoryGetDefaultLines : fenêtre de lignes par défaut de memory_get lorsque lines est omis.
• toolResultMaxChars : limite des résultats d’outils en direct utilisée pour les résultats conservés et la récupération après dépassement.
• postCompactionMaxChars : limite d’extrait d’AGENTS.md utilisée pendant l’injection d’actualisation après Compaction.

​

agents.list[].contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        toolResultMaxChars: 16000,
      },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000,
        },
      },
    ],
  },
}

​

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.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" }, // global default provider params
      embeddedHarness: {
        runtime: "auto", // auto | pi | registered harness id, e.g. codex
        fallback: "pi", // pi | none
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "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 ne définit que le modèle principal.
  • La forme objet définit le modèle principal plus des 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 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.
• 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, ou openai/gpt-image-2 pour OpenAI Images.
  • Si vous sélectionnez directement un fournisseur/modèle, configurez aussi l’authentification du fournisseur correspondante (par exemple GEMINI_API_KEY ou GOOGLE_API_KEY pour google/*, OPENAI_API_KEY ou OAuth OpenAI Codex pour openai/gpt-image-2, FAL_KEY pour fal/*).
  • S’il est omis, image_generate peut toujours déduire une valeur par défaut de fournisseur soutenue par 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.5+.
  • S’il est omis, music_generate peut toujours déduire une valeur par défaut de fournisseur soutenue par 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é API du 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.
  • S’il est omis, video_generate peut toujours déduire une valeur par défaut de fournisseur soutenue par 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é API du fournisseur correspondante.
  • Le fournisseur groupé 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 au niveau du 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.
  • S’il est 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 transmis au moment de l’appel.
• pdfMaxPages : nombre maximal de pages pris 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".
• 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.4 pour l’accès par clé API ou openai-codex/gpt-5.5 pour OAuth Codex). Si vous omettez le fournisseur, OpenClaw essaie d’abord un alias, puis une correspondance unique de fournisseur configuré pour cet identifiant de modèle exact, et seulement ensuite se rabat sur le fournisseur par défaut configuré (comportement de compatibilité déprécié, donc préférez 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 obsolète 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).
  • 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 transmettez --replace.
  • Les flux de configuration/d’onboarding à portée fournisseur fusionnent les modèles du fournisseur sélectionné dans cette map et préservent les autres fournisseurs déjà configurés.
  • Pour les modèles directs OpenAI Responses, la Compaction côté serveur est activée automatiquement. Utilisez params.responsesServerCompaction: false pour arrêter d’injecter context_management, ou params.responsesCompactThreshold pour remplacer le seuil. Voir Compaction côté serveur OpenAI.
• params : paramètres par défaut globaux du fournisseur appliqués à tous les modèles. À définir 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 les détails.
• embeddedHarness : politique par défaut de l’exécuteur embarqué de bas niveau. Utilisez runtime: "auto" pour laisser les harnais Plugin enregistrés revendiquer les modèles pris en charge, runtime: "pi" pour forcer le harnais PI intégré, ou un identifiant de harnais enregistré tel que runtime: "codex". Définissez fallback: "none" pour désactiver le repli automatique vers PI.
• Les écrivains de configuration qui modifient ces champs (par exemple /models set, /models set-image et les commandes d’ajout/suppression de repli) enregistrent la forme canonique objet et préservent les listes de repli existantes lorsque c’est possible.
• maxConcurrent : nombre maximal d’exécutions d’agents en parallèle entre les sessions (chaque session reste sérialisée). Par défaut : 4.

​

agents.defaults.embeddedHarness

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      embeddedHarness: {
        runtime: "codex",
        fallback: "none",
      },
    },
  },
}

• runtime : "auto", "pi" ou un identifiant de harnais Plugin enregistré. Le Plugin Codex groupé enregistre codex.
• fallback : "pi" ou "none". "pi" conserve le harnais PI intégré comme repli de compatibilité lorsqu’aucun harnais Plugin n’est sélectionné. "none" fait échouer la sélection d’un harnais Plugin manquant ou non pris en charge au lieu d’utiliser silencieusement PI. Les échecs du harnais Plugin sélectionné sont toujours remontés directement.
• Remplacements d’environnement : OPENCLAW_AGENT_RUNTIME=<id|auto|pi> remplace runtime ; OPENCLAW_AGENT_HARNESS_FALLBACK=none désactive le repli vers PI pour ce processus.
• Pour les déploiements Codex uniquement, définissez model: "openai/gpt-5.5", embeddedHarness.runtime: "codex" et embeddedHarness.fallback: "none".
• Le choix du harnais est épinglé par identifiant de session après la première exécution embarquée. Les changements de configuration/d’environnement affectent les nouvelles sessions ou les sessions réinitialisées, pas une transcription existante. Les sessions héritées avec historique de transcription mais sans épinglage enregistré sont traitées comme épinglées à PI. /status affiche les identifiants de harnais non-PI tels que codex à côté de Fast.
• Cela contrôle uniquement le harnais de chat embarqué. La génération de médias, la vision, les PDF, la musique, la vidéo et le TTS utilisent toujours leurs paramètres fournisseur/modèle.

​

agents.defaults.cliBackends

{
  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",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• Les backends CLI sont d’abord orientés texte ; les outils sont toujours désactivés.
• Les sessions sont prises en charge lorsque sessionArg est défini.
• Le passage direct d’image est pris en charge lorsque imageArg accepte des chemins de fichier.

​

agents.defaults.systemPromptOverride

{
  agents: {
    defaults: {
      systemPromptOverride: "You are a helpful assistant.",
    },
  },
}

​

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 toujours lu lorsque ce paramètre 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)
        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 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 bootstrap. 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 interruption. Laissez non défini pour utiliser agents.defaults.timeoutSeconds.
• 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 bootstrap léger et ne conservent que HEARTBEAT.md parmi les fichiers bootstrap de l’espace de travail.
• isolatedSession : lorsque true, chaque Heartbeat s’exécute dans une nouvelle session sans historique de conversation antérieur. Même modèle d’isolation que le cron sessionTarget: "isolated". Réduit le coût en jetons par Heartbeat d’environ ~100K à ~2-5K jetons.
• Par agent : définissez agents.list[].heartbeat. Lorsqu’un agent quelconque 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

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id of a registered compaction provider plugin (optional)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
        postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
        model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
        notifyUser: true, // send brief notices when compaction starts and completes (default: false)
        memoryFlush: {
          enabled: true,
          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 blocs pour les longs historiques). Voir Compaction.
• provider : identifiant d’un Plugin fournisseur de Compaction enregistré. Lorsqu’il est défini, la méthode summarize() du fournisseur est appelée à la place du résumé LLM intégré. Revient à l’intégration en cas d’échec. Définir un fournisseur force mode: "safeguard". Voir Compaction.
• timeoutSeconds : durée maximale en secondes autorisée pour une opération unique de Compaction avant qu’OpenClaw ne l’abandonne. Par défaut : 900.
• identifierPolicy : strict (par défaut), off ou custom. strict ajoute au début des indications intégrées de conservation des identifiants opaques pendant le résumé de Compaction.
• identifierInstructions : texte facultatif personnalisé de conservation des identifiants utilisé lorsque identifierPolicy=custom.
• postCompactionSections : noms facultatifs de sections H2/H3 d’AGENTS.md à réinjecter après la Compaction. Par défaut : ["Session Startup", "Red Lines"] ; définissez [] pour désactiver la réinjection. Lorsqu’il est non défini ou explicitement défini sur cette paire par défaut, les anciens en-têtes Every Session/Safety sont également acceptés comme solution de secours héritée.
• 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.
• notifyUser : lorsque true, envoie de brefs avis à l’utilisateur quand la Compaction commence et quand elle se termine (par exemple, « Compacting context… » et « Compaction complete »). Désactivé par défaut pour garder la Compaction silencieuse.
• memoryFlush : tour agentique silencieux avant la Compaction automatique pour stocker les mémoires durables. Ignoré lorsque l’espace de travail est en lecture seule.

​

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 non-Telegram nécessitent *.blockStreaming: true explicite pour activer les réponses par blocs.
• Remplacements 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–2500ms. Remplacement 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 discussions directes/mentions, message pour les discussions de groupe sans mention.
• Remplacements 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
        embeddedHarness: { runtime: "auto", fallback: "pi" },
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        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 stable de l’agent (obligatoire).
• default : lorsque plusieurs sont définis, le premier l’emporte (un avertissement est journalisé). Si aucun n’est défini, la première entrée de la liste est celle par défaut.
• model : la forme chaîne remplace uniquement primary ; la forme objet { primary, fallbacks } remplace les deux ([] désactive les replis globaux). 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-les pour des remplacements spécifiques à un agent comme cacheRetention, temperature ou maxTokens sans dupliquer tout le catalogue de modèles.
• skills : liste d’autorisation facultative des Skills par agent. Si elle est omise, l’agent hérite de agents.defaults.skills lorsqu’elle est définie ; une liste explicite remplace les valeurs par défaut au lieu de fusionner, et [] signifie aucune Skill.
• 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.
• reasoningDefault : visibilité du raisonnement par défaut facultative par agent (on | off | stream). S’applique 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 (true | false). S’applique lorsqu’aucun remplacement de mode rapide par message ou par session n’est défini.
• embeddedHarness : remplacement facultatif par agent de la politique de harnais de bas niveau. Utilisez { runtime: "codex", fallback: "none" } pour rendre un agent uniquement Codex tandis que les autres agents conservent le repli PI par défaut.
• 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 par défaut utiliser des sessions de 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 à partir de emoji, mentionPatterns à partir de name/emoji.
• subagents.allowAgents : liste d’autorisation des identifiants d’agent pour sessions_spawn (["*"] = n’importe lequel ; par défaut : même agent uniquement).
• Garde-fou d’héritage du sandbox : si la session demandeuse est sandboxée, sessions_spawn rejette les cibles qui s’exécuteraient sans sandbox.
• subagents.requireAgentId : lorsque true, bloque les appels sessions_spawn qui omettent agentId (force une sélection explicite de profil ; par défaut : false).

​

Routage multi-agents

{
  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 (l’absence de type vaut route par défaut), acp pour les liaisons persistantes de conversation ACP.
• 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 ; spécifique 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",
    parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      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: "collect", // steer | followup | collect | steer-backlog | steer+backlog | queue | interrupt
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

Préfixe de réponse

​

Réaction d’accusé

• Prend 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 d’identité.
• Portée : group-mentions (par défaut), group-all, direct, all.
• removeAckAfterReply : supprime l’accusé après la réponse sur Slack, Discord et Telegram.
• messages.statusReactions.enabled : active les réactions d’état du cycle de vie sur Slack, Discord et Telegram. Sur Slack et Discord, une valeur non définie conserve les réactions d’état activées lorsque les réactions d’accusé sont actives. Sur Telegram, définissez-le explicitement à true pour activer les réactions d’état du cycle de vie.

​

Antirebond entrant

​

TTS (synthèse vocale)

{
  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",
      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,
        },
      },
      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 par défaut false (activation explicite).
• Les clés API se rabattent sur ELEVENLABS_API_KEY/XI_API_KEY et OPENAI_API_KEY.
• openai.baseUrl remplace l’endpoint TTS OpenAI. L’ordre de résolution est : configuration, puis OPENAI_TTS_BASE_URL, puis https://api.openai.com/v1.
• Lorsque openai.baseUrl pointe vers un endpoint non OpenAI, OpenClaw le traite comme un serveur TTS compatible OpenAI et assouplit la validation du modèle/de la voix.

​

Talk

{
  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",
      },
    },
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
  },
}

• 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 conservées pour compatibilité et sont automatiquement migrées vers 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 ne s’applique que lorsqu’aucune clé API Talk n’est configurée.
• providers.*.voiceAliases permet aux directives Talk d’utiliser des noms conviviaux.
• silenceTimeoutMs contrôle combien de temps 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 sur macOS et Android, 900 ms sur iOS).

​

Voir aussi

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