​

Référence de configuration

• openclaw config schema affiche le schéma JSON actif utilisé pour la validation et l’interface Control UI, avec les métadonnées groupées/plugin/canal fusionnées lorsqu’elles sont disponibles
• config.schema.lookup renvoie un nœud de schéma limité à un chemin pour les outils d’exploration détaillée
• pnpm config:docs:check / pnpm config:docs:gen valident le hachage de référence des documents de configuration par rapport à la surface actuelle du schéma

• Référence de configuration de la mémoire pour agents.defaults.memorySearch.*, memory.qmd.*, memory.citations et la configuration de rêverie sous plugins.entries.memory-core.config.dreaming
• Commandes Slash pour le catalogue actuel des commandes intégrées + groupées
• pages du canal/plugin propriétaire pour les surfaces de commandes spécifiques au canal

​

Canaux

​

Accès aux messages privés et aux groupes

​

Remplacements de modèle par canal

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-4.1",
      },
      telegram: {
        "-1001234567890": "openai/gpt-4.1-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}

​

Valeurs par défaut des canaux et heartbeat

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      contextVisibility: "all", // all | allowlist | allowlist_quote
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

• channels.defaults.groupPolicy : politique de groupe de repli lorsqu’un groupPolicy au niveau fournisseur n’est pas défini.
• channels.defaults.contextVisibility : mode de visibilité du contexte supplémentaire par défaut pour tous les canaux. Valeurs : all (par défaut, inclure tout le contexte cité/de fil/d’historique), allowlist (inclure uniquement le contexte des expéditeurs autorisés), allowlist_quote (identique à allowlist mais conserve le contexte explicite de citation/réponse). Remplacement par canal : channels.<channel>.contextVisibility.
• channels.defaults.heartbeat.showOk : inclure les états de canal sains dans la sortie du heartbeat.
• channels.defaults.heartbeat.showAlerts : inclure les états dégradés/en erreur dans la sortie du heartbeat.
• channels.defaults.heartbeat.useIndicator : afficher une sortie de heartbeat compacte de type indicateur.

​

WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // coches bleues (false en mode auto-discussion)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

​

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all | batched
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• Jeton du bot : channels.telegram.botToken ou channels.telegram.tokenFile (fichier ordinaire uniquement ; les liens symboliques sont rejetés), avec TELEGRAM_BOT_TOKEN comme solution de repli pour le compte par défaut.
• channels.telegram.defaultAccount facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré.
• Dans les configurations multi-comptes (2 ID de compte ou plus), définissez un compte par défaut explicite (channels.telegram.defaultAccount ou channels.telegram.accounts.default) pour éviter le routage de repli ; openclaw doctor avertit lorsque cela est manquant ou invalide.
• configWrites: false bloque les écritures de configuration initiées par Telegram (migrations d’ID de supergroupe, /config set|unset).
• Les entrées bindings[] de niveau supérieur avec type: "acp" configurent des liaisons ACP persistantes pour les sujets de forum (utilisez le format canonique chatId:topic:topicId dans match.peer.id). La sémantique des champs est partagée dans Agents ACP.
• Les aperçus de flux Telegram utilisent sendMessage + editMessageText (fonctionne dans les conversations directes et de groupe).
• Politique de nouvelle tentative : voir Politique de nouvelle tentative.

​

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 100,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all | batched
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: "off", // off | partial | block | progress (progress maps to partial on Discord)
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true })
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["987654321098765432"],
        agentFilter: ["default"],
        sessionFilter: ["discord:"],
        target: "dm", // dm | channel | both
        cleanupAfterResolve: false,
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• Jeton : channels.discord.token, avec DISCORD_BOT_TOKEN comme solution de repli pour le compte par défaut.
• Les appels sortants directs qui fournissent un token Discord explicite utilisent ce jeton pour l’appel ; les paramètres de nouvelle tentative/politique du compte proviennent toujours du compte sélectionné dans l’instantané d’exécution actif.
• channels.discord.defaultAccount facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré.
• Utilisez user:<id> (DM) ou channel:<id> (canal de serveur) pour les cibles de livraison ; les ID numériques seuls sont rejetés.
• Les slugs de serveur sont en minuscules avec les espaces remplacés par - ; les clés de canal utilisent le nom slugifié (sans #). Préférez les ID de serveur.
• Les messages rédigés par des bots sont ignorés par défaut. allowBots: true les active ; utilisez allowBots: "mentions" pour n’accepter que les messages de bots qui mentionnent le bot (les propres messages restent filtrés).
• channels.discord.guilds.<id>.ignoreOtherMentions (et les remplacements de canal) supprime les messages qui mentionnent un autre utilisateur ou rôle mais pas le bot (à l’exclusion de @everyone/@here).
• maxLinesPerMessage (17 par défaut) découpe les messages hauts même lorsqu’ils font moins de 2000 caractères.
• channels.discord.threadBindings contrôle le routage lié aux fils Discord :
  • enabled : remplacement Discord pour les fonctionnalités de session liées aux fils (/focus, /unfocus, /agents, /session idle, /session max-age, et la livraison/le routage liés)
  • idleHours : remplacement Discord pour le retrait automatique du focus après inactivité, en heures (0 désactive)
  • maxAgeHours : remplacement Discord pour l’âge maximal strict, en heures (0 désactive)
  • spawnSubagentSessions : option d’activation pour la création/liaison automatique de fil par sessions_spawn({ thread: true })
• Les entrées bindings[] de niveau supérieur avec type: "acp" configurent des liaisons ACP persistantes pour les canaux et les fils (utilisez l’ID du canal/fil dans match.peer.id). La sémantique des champs est partagée dans Agents ACP.
• channels.discord.ui.components.accentColor définit la couleur d’accentuation pour les conteneurs Discord components v2.
• channels.discord.voice active les conversations dans les canaux vocaux Discord ainsi que les remplacements facultatifs d’auto-jonction + TTS.
• channels.discord.voice.daveEncryption et channels.discord.voice.decryptionFailureTolerance sont transmis aux options DAVE de @discordjs/voice (true et 24 par défaut).
• OpenClaw tente en outre une récupération de réception vocale en quittant puis en rejoignant à nouveau une session vocale après des échecs de déchiffrement répétés.
• channels.discord.streaming est la clé canonique du mode de flux. Les anciennes valeurs booléennes streamMode et streaming sont migrées automatiquement.
• channels.discord.autoPresence mappe la disponibilité d’exécution à la présence du bot (healthy => online, degraded => idle, exhausted => dnd) et autorise des remplacements facultatifs du texte de statut.
• channels.discord.dangerouslyAllowNameMatching réactive la correspondance par nom/tag modifiable (mode de compatibilité de dernier recours).
• channels.discord.execApprovals : livraison native Discord des approbations d’exécution et autorisation des approbateurs.
  • enabled : true, false ou "auto" (par défaut). En mode auto, les approbations d’exécution s’activent lorsque des approbateurs peuvent être résolus depuis approvers ou commands.ownerAllowFrom.
  • approvers : ID d’utilisateurs Discord autorisés à approuver des demandes d’exécution. Utilise commands.ownerAllowFrom comme solution de repli si omis.
  • agentFilter : liste d’autorisations facultative d’ID d’agent. Omettez-la pour transférer les approbations pour tous les agents.
  • sessionFilter : motifs facultatifs de clé de session (sous-chaîne ou regex).
  • target : emplacement d’envoi des invites d’approbation. "dm" (par défaut) les envoie aux DM des approbateurs, "channel" les envoie au canal d’origine, "both" les envoie aux deux. Lorsque la cible inclut "channel", les boutons ne sont utilisables que par les approbateurs résolus.
  • cleanupAfterResolve : lorsqu’il vaut true, supprime les DM d’approbation après approbation, refus ou expiration.

​

Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• JSON du compte de service : en ligne (serviceAccount) ou basé sur un fichier (serviceAccountFile).
• SecretRef du compte de service est également pris en charge (serviceAccountRef).
• Solutions de repli d’environnement : GOOGLE_CHAT_SERVICE_ACCOUNT ou GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• Utilisez spaces/<spaceId> ou users/<userId> pour les cibles de livraison.
• channels.googlechat.dangerouslyAllowNameMatching réactive la correspondance par principal e-mail modifiable (mode de compatibilité de dernier recours).

​

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all | batched
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: {
        mode: "partial", // off | partial | block | progress
        nativeTransport: true, // use Slack native streaming API when mode=partial
      },
      mediaMaxMb: 20,
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["U123"],
        agentFilter: ["default"],
        sessionFilter: ["slack:"],
        target: "dm", // dm | channel | both
      },
    },
  },
}

• Le mode socket nécessite botToken et appToken (SLACK_BOT_TOKEN + SLACK_APP_TOKEN pour la solution de repli d’environnement du compte par défaut).
• Le mode HTTP nécessite botToken plus signingSecret (à la racine ou par compte).
• botToken, appToken, signingSecret et userToken acceptent des chaînes en texte brut ou des objets SecretRef.
• Les instantanés de compte Slack exposent des champs de source/état par identifiant comme botTokenSource, botTokenStatus, appTokenStatus et, en mode HTTP, signingSecretStatus. configured_unavailable signifie que le compte est configuré via SecretRef, mais que le chemin de commande/d’exécution actuel n’a pas pu résoudre la valeur secrète.
• configWrites: false bloque les écritures de configuration initiées par Slack.
• channels.slack.defaultAccount facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré.
• channels.slack.streaming.mode est la clé canonique du mode de flux Slack. channels.slack.streaming.nativeTransport contrôle le transport de flux natif de Slack. Les anciennes valeurs streamMode, booléennes streaming et nativeStreaming sont migrées automatiquement.
• Utilisez user:<id> (DM) ou channel:<id> pour les cibles de livraison.

• Le flux natif Slack ainsi que l’état de fil Slack de type assistant « is typing… » nécessitent une cible de réponse dans un fil. Les DM de niveau supérieur restent hors fil par défaut ; ils utilisent donc typingReaction ou la livraison normale au lieu de l’aperçu de style fil.
• typingReaction ajoute une réaction temporaire au message Slack entrant pendant l’exécution d’une réponse, puis la supprime à la fin. Utilisez un shortcode d’emoji Slack tel que "hourglass_flowing_sand".
• channels.slack.execApprovals : livraison native Slack des approbations d’exécution et autorisation des approbateurs. Même schéma que Discord : enabled (true/false/"auto"), approvers (ID d’utilisateurs Slack), agentFilter, sessionFilter et target ("dm", "channel" ou "both").

​

Mattermost

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
      commands: {
        native: true, // opt-in
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Optional explicit URL for reverse-proxy/public deployments
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

• commands.callbackPath doit être un chemin (par exemple /api/channels/mattermost/command), et non une URL complète.
• commands.callbackUrl doit résoudre vers le point de terminaison de passerelle OpenClaw et être accessible depuis le serveur Mattermost.
• Les rappels slash natifs sont authentifiés avec les jetons par commande renvoyés par Mattermost lors de l’enregistrement de la commande slash. Si l’enregistrement échoue ou si aucune commande n’est activée, OpenClaw rejette les rappels avec Unauthorized: invalid command token.
• Pour les hôtes de rappel privés/tailnet/internes, Mattermost peut exiger que ServiceSettings.AllowedUntrustedInternalConnections inclue l’hôte/domaine de rappel. Utilisez des valeurs hôte/domaine, et non des URL complètes.
• channels.mattermost.configWrites : autorise ou refuse les écritures de configuration initiées par Mattermost.
• channels.mattermost.requireMention : exige une @mention avant de répondre dans les canaux.
• channels.mattermost.groups.<channelId>.requireMention : remplacement par canal du filtrage par mention ("*" pour la valeur par défaut).
• channels.mattermost.defaultAccount facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré.

​

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // optional account binding
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

• channels.signal.account : épingle le démarrage du canal à une identité de compte Signal spécifique.
• channels.signal.configWrites : autorise ou refuse les écritures de configuration initiées par Signal.
• channels.signal.defaultAccount facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré.

​

BlueBubbles

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, group controls, and advanced actions:
      // see /channels/bluebubbles
    },
  },
}

• Chemins de clés principaux couverts ici : channels.bluebubbles, channels.bluebubbles.dmPolicy.
• channels.bluebubbles.defaultAccount facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré.
• Les entrées bindings[] de niveau supérieur avec type: "acp" peuvent lier des conversations BlueBubbles à des sessions ACP persistantes. Utilisez un handle BlueBubbles ou une chaîne cible (chat_id:*, chat_guid:*, chat_identifier:*) dans match.peer.id. Sémantique de champ partagée : Agents ACP.
• La configuration complète du canal BlueBubbles est documentée dans BlueBubbles.

​

iMessage

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

• channels.imessage.defaultAccount facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré.
• Nécessite un accès complet au disque pour la base de données Messages.
• Préférez les cibles chat_id:<id>. Utilisez imsg chats --limit 20 pour lister les conversations.
• cliPath peut pointer vers un wrapper SSH ; définissez remoteHost (host ou user@host) pour la récupération SCP des pièces jointes.
• attachmentRoots et remoteAttachmentRoots restreignent les chemins des pièces jointes entrantes (par défaut : /Users/*/Library/Messages/Attachments).
• SCP utilise une vérification stricte des clés d’hôte ; assurez-vous donc que la clé d’hôte du relais existe déjà dans ~/.ssh/known_hosts.
• channels.imessage.configWrites : autorise ou refuse les écritures de configuration initiées par iMessage.
• Les entrées bindings[] de niveau supérieur avec type: "acp" peuvent lier des conversations iMessage à des sessions ACP persistantes. Utilisez un handle normalisé ou une cible de conversation explicite (chat_id:*, chat_guid:*, chat_identifier:*) dans match.peer.id. Sémantique de champ partagée : Agents ACP.

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

​

Matrix

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
      encryption: true,
      initialSyncLimit: 20,
      defaultAccount: "ops",
      accounts: {
        ops: {
          name: "Ops",
          userId: "@ops:example.org",
          accessToken: "syt_ops_xxx",
        },
        alerts: {
          userId: "@alerts:example.org",
          password: "secret",
          proxy: "http://127.0.0.1:7891",
        },
      },
    },
  },
}

• L’authentification par jeton utilise accessToken ; l’authentification par mot de passe utilise userId + password.
• channels.matrix.proxy achemine le trafic HTTP Matrix via un proxy HTTP(S) explicite. Les comptes nommés peuvent le remplacer avec channels.matrix.accounts.<id>.proxy.
• channels.matrix.network.dangerouslyAllowPrivateNetwork autorise les homeservers privés/internes. proxy et cette activation réseau sont des contrôles indépendants.
• channels.matrix.defaultAccount sélectionne le compte préféré dans les configurations multi-comptes.
• channels.matrix.autoJoin vaut par défaut off, donc les salons invités et les nouvelles invitations de type DM sont ignorés jusqu’à ce que vous définissiez autoJoin: "allowlist" avec autoJoinAllowlist ou autoJoin: "always".
• channels.matrix.execApprovals : livraison native Matrix des approbations d’exécution et autorisation des approbateurs.
  • enabled : true, false ou "auto" (par défaut). En mode auto, les approbations d’exécution s’activent lorsque des approbateurs peuvent être résolus depuis approvers ou commands.ownerAllowFrom.
  • approvers : ID d’utilisateurs Matrix (par ex. @owner:example.org) autorisés à approuver des demandes d’exécution.
  • agentFilter : liste d’autorisations facultative d’ID d’agent. Omettez-la pour transférer les approbations pour tous les agents.
  • sessionFilter : motifs facultatifs de clé de session (sous-chaîne ou regex).
  • target : emplacement d’envoi des invites d’approbation. "dm" (par défaut), "channel" (salon d’origine) ou "both".
  • Remplacements par compte : channels.matrix.accounts.<id>.execApprovals.
• channels.matrix.dm.sessionScope contrôle la manière dont les DM Matrix sont regroupés en sessions : per-user (par défaut) partage par pair routé, tandis que per-room isole chaque salon DM.
• Les sondes d’état Matrix et les consultations de répertoire en direct utilisent la même politique de proxy que le trafic d’exécution.
• La configuration complète de Matrix, les règles de ciblage et les exemples d’installation sont documentés dans Matrix.

​

Microsoft Teams

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, team/channel policies:
      // see /channels/msteams
    },
  },
}

• Chemins de clés principaux couverts ici : channels.msteams, channels.msteams.configWrites.
• La configuration complète de Teams (identifiants, webhook, politique DM/groupe, remplacements par équipe/par canal) est documentée dans Microsoft Teams.

​

IRC

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "bot@example.com",
      },
    },
  },
}

• Chemins de clés principaux couverts ici : channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
• channels.irc.defaultAccount facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré.
• La configuration complète du canal IRC (hôte/port/TLS/canaux/listes d’autorisations/filtrage par mention) est documentée dans IRC.

​

Multi-compte (tous les canaux)

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

• default est utilisé lorsque accountId est omis (CLI + routage).
• Les jetons d’environnement s’appliquent uniquement au compte default.
• Les paramètres de canal de base s’appliquent à tous les comptes sauf remplacement par compte.
• Utilisez bindings[].match.accountId pour router chaque compte vers un agent différent.
• Si vous ajoutez un compte non par défaut via openclaw channels add (ou l’intégration du canal) alors que vous utilisez encore une configuration de canal de niveau supérieur à compte unique, OpenClaw promeut d’abord les valeurs de niveau supérieur à compte unique limitées au compte dans la map de comptes du canal afin que le compte d’origine continue de fonctionner. La plupart des canaux les déplacent vers channels.<channel>.accounts.default ; Matrix peut à la place conserver une cible nommée/par défaut existante correspondante.
• Les liaisons existantes limitées au canal (sans accountId) continuent de correspondre au compte par défaut ; les liaisons limitées au compte restent facultatives.
• openclaw doctor --fix répare également les formes mixtes en déplaçant les valeurs de niveau supérieur à compte unique limitées au compte vers le compte promu choisi pour ce canal. La plupart des canaux utilisent accounts.default ; Matrix peut à la place conserver une cible nommée/par défaut existante correspondante.

​

Autres canaux d’extension

​

Filtrage par mention dans les discussions de groupe

• Mentions de métadonnées : @-mentions natives de la plateforme. Ignorées en mode auto-discussion WhatsApp.
• Modèles de texte : modèles regex sûrs dans agents.list[].groupChat.mentionPatterns. Les modèles invalides et les répétitions imbriquées non sûres sont ignorés.
• Le filtrage par mention n’est appliqué que lorsque la détection est possible (mentions natives ou au moins un modèle).

{
  messages: {
    groupChat: { historyLimit: 50 },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

​

Limites d’historique des DM

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

​

Mode auto-discussion

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    ],
  },
}

​

Commandes (gestion des commandes de chat)

{
  commands: {
    native: "auto", // register native commands when supported
    nativeSkills: "auto", // register native skill commands when supported
    text: true, // parse /commands in chat messages
    bash: false, // allow ! (alias: /bash)
    bashForegroundMs: 2000,
    config: false, // allow /config
    mcp: false, // allow /mcp
    plugins: false, // allow /plugins
    debug: false, // allow /debug
    restart: true, // allow /restart + gateway restart tool
    ownerAllowFrom: ["discord:123456789012345678"],
    ownerDisplay: "raw", // raw | hash
    ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

​

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: [] }, // aucun Skills
    ],
  },
}

• Omettez agents.defaults.skills pour des Skills non restreints par défaut.
• Omettez agents.list[].skills pour hériter des valeurs par défaut.
• Définissez agents.list[].skills: [] pour aucun Skills.
• Une liste non vide dans agents.list[].skills 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.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 compactage reconstruisent toujours le contexte.

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

​

agents.defaults.bootstrapMaxChars

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

​

agents.defaults.bootstrapTotalMaxChars

{
  agents: { defaults: { bootstrapTotalMaxChars: 150000 } },
}

​

agents.defaults.bootstrapPromptTruncationWarning

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

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

​

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-1",
        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 globaux par défaut
      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 définit uniquement le modèle principal.
  • La forme objet définit le modèle principal ainsi que des modèles de bascule ordonnés.
• imageModel : accepte soit une chaîne ("provider/model"), soit un objet ({ primary, fallbacks }).
  • Utilisé par le chemin de l’outil image comme configuration de son modèle de vision.
  • Également utilisé comme routage de repli 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-1 pour OpenAI Images.
  • Si vous sélectionnez directement un provider/modèle, configurez également l’authentification/la clé API du provider correspondant (par exemple GEMINI_API_KEY ou GOOGLE_API_KEY pour google/*, OPENAI_API_KEY pour openai/*, FAL_KEY pour fal/*).
  • Si omis, image_generate peut tout de même déduire une valeur par défaut de provider avec authentification. Il essaie d’abord le provider par défaut actuel, puis les autres providers de génération d’images enregistrés dans l’ordre des ID de provider.
• 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+.
  • Si omis, music_generate peut tout de même déduire une valeur par défaut de provider avec authentification. Il essaie d’abord le provider par défaut actuel, puis les autres providers de génération musicale enregistrés dans l’ordre des ID de provider.
  • Si vous sélectionnez directement un provider/modèle, configurez également l’authentification/la clé API du provider correspondant.
• videoGenerationModel : accepte soit une chaîne ("provider/model"), soit un objet ({ primary, fallbacks }).
  • Utilisé par la capacité partagée de génération vidéo et l’outil intégré video_generate.
  • Valeurs typiques : qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash, ou qwen/wan2.7-r2v.
  • Si omis, video_generate peut tout de même déduire une valeur par défaut de provider avec authentification. Il essaie d’abord le provider par défaut actuel, puis les autres providers de génération vidéo enregistrés dans l’ordre des ID de provider.
  • Si vous sélectionnez directement un provider/modèle, configurez également l’authentification/la clé API du provider correspondant.
  • Le provider 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 de niveau provider size, aspectRatio, resolution, audio et watermark.
• pdfModel : accepte soit une chaîne ("provider/model"), soit un objet ({ primary, fallbacks }).
  • Utilisé par l’outil pdf pour le routage du modèle.
  • Si omis, l’outil PDF se replie 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 par défaut pris en compte 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".
• 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). Si vous omettez le provider, OpenClaw essaie d’abord un alias, puis une correspondance unique de provider configuré pour cet ID de modèle exact, et seulement ensuite revient au provider par défaut configuré (comportement de compatibilité obsolète, donc préférez provider/model explicite). Si ce provider n’expose plus le modèle par défaut configuré, OpenClaw se replie sur le premier provider/modèle configuré au lieu d’exposer une valeur par défaut obsolète d’un provider supprimé.
• models : catalogue de modèles configuré et liste d’autorisations pour /model. Chaque entrée peut inclure alias (raccourci) et params (spécifiques au provider, par exemple temperature, maxTokens, cacheRetention, context1m).
• params : paramètres provider 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 (ID d’agent correspondant) remplace par clé. Consultez Mise en cache des prompts pour plus de détails.
• Les outils d’écriture de configuration qui mutent 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 c’est possible.
• maxConcurrent : nombre maximal d’exécutions d’agent parallèles entre les sessions (chaque session reste sérialisée). Par défaut : 4.

​

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 orientés texte ; les outils sont toujours désactivés.
• Les sessions sont prises en charge lorsque sessionArg est défini.
• Le passage 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.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,
      },
    },
  },
}

• 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.
• directPolicy : politique de livraison directe/DM. allow (par défaut) autorise la livraison à cible directe. block supprime la livraison à 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 exécution heartbeat se fait dans une session fraîche sans historique de conversation préalable. Même schéma d’isolation que le cron sessionTarget: "isolated". Réduit le coût en jetons par heartbeat d’environ 100K à environ 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 plus 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 a brief notice when compaction starts (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és par blocs pour les longs historiques). Voir Compaction.
• provider : ID d’un plugin provider de compaction enregistré. Lorsqu’il est défini, le summarize() du provider est appelé à la place du résumé LLM intégré. Revient à l’implémentation intégrée en cas d’échec. Définir un provider force mode: "safeguard". Voir Compaction.
• timeoutSeconds : nombre maximal de secondes autorisé pour une seule opération de compaction avant qu’OpenClaw l’abandonne. Par défaut : 900.
• identifierPolicy : strict (par défaut), off ou custom. strict ajoute en préambule les 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.
• postCompactionSections : noms facultatifs de sections H2/H3 de AGENTS.md à réinjecter après compaction. Par défaut : ["Session Startup", "Red Lines"] ; définissez [] pour désactiver la réinjection. Lorsqu’il n’est pas défini ou qu’il est explicitement défini sur cette paire par défaut, les anciens titres Every Session/Safety sont également acceptés comme solution de repli 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 un bref avis à l’utilisateur au démarrage de la compaction (par exemple « Compactage du contexte… »). Désactivé par défaut pour garder la compaction silencieuse.
• memoryFlush : tour agentique silencieux avant l’auto-compaction pour stocker des souvenirs 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 autres que Telegram nécessitent *.blockStreaming: true explicite pour activer les réponses par blocs.
• Remplacements par 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. 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 conversations 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           # image principale du sandbox
scripts/sandbox-browser-setup.sh   # image navigateur facultative

​

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
        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 : ID d’agent stable (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 l’agent 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 au-dessus de l’entrée de modèle sélectionnée dans agents.defaults.models. Utilisez-les pour des remplacements spécifiques à l’agent comme cacheRetention, temperature ou maxTokens sans dupliquer tout le catalogue de modèles.
• skills : liste d’autorisations 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 d’être fusionnée, et [] signifie aucun Skills.
• thinkingDefault : niveau de réflexion facultatif par défaut par agent (off | minimal | low | medium | high | xhigh | adaptive). Remplace agents.defaults.thinkingDefault pour cet agent lorsqu’aucun remplacement par message ou par session n’est défini.
• reasoningDefault : visibilité facultative du raisonnement par défaut 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.
• runtime : descripteur d’exécution facultatif par agent. Utilisez type: "acp" avec les valeurs par défaut de runtime.acp (agent, backend, mode, cwd) lorsque l’agent doit utiliser par défaut des sessions 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’autorisations des ID 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 : lorsqu’il vaut true, bloque les appels sessions_spawn qui omettent agentId (force une sélection de profil explicite ; 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 des liaisons

• type (facultatif) : route pour le routage normal (type absent = 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 les entrées type: "acp") : { mode, label, cwd, backend }

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (exact, sans pair/serveur/équipe)
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é 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 identité.
• Portée : group-mentions (par défaut), group-all, direct, all.
• removeAckAfterReply : supprime l’accusé de réception après 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, l’absence de valeur conserve les réactions d’état activées lorsque les réactions d’accusé de réception sont actives. Sur Telegram, définissez explicitement cette valeur à true pour activer les réactions d’état du cycle de vie.

​

Anti-rebond des messages entrants

​

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 utilisent comme solution de repli ELEVENLABS_API_KEY/XI_API_KEY et OPENAI_API_KEY.
• openai.baseUrl remplace le point de terminaison 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 point de terminaison non OpenAI, OpenClaw le traite comme un serveur TTS compatible OpenAI et assouplit la validation du modèle/de la voix.

​

Talk

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