Configuration

Chaque canal possède sa propre section de configuration sous channels.<provider>. Consultez la page dédiée au canal pour connaître les étapes de configuration :

• Discord - channels.discord
• Feishu - channels.feishu
• Google Chat - channels.googlechat
• iMessage - channels.imessage
• Mattermost - channels.mattermost
• Microsoft Teams - channels.msteams
• Signal - channels.signal
• Slack - channels.slack
• Telegram - channels.telegram
• WhatsApp - channels.whatsapp

Tous les canaux partagent le même modèle de politique pour les messages privés :

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // uniquement pour allowlist/open    },  },}

Définissez le modèle principal et les modèles de secours facultatifs :

{  agents: {    defaults: {      model: {        primary: "anthropic/claude-sonnet-4-6",        fallbacks: ["openai/gpt-5.4"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "openai/gpt-5.4": { alias: "GPT" },      },    },  },}

• agents.defaults.models définit le catalogue de modèles et sert de liste d’autorisation pour /model ; les entrées provider/* limitent /model, /models et les sélecteurs de modèles aux fournisseurs sélectionnés tout en continuant à utiliser la découverte dynamique des modèles.
• Utilisez openclaw config set agents.defaults.models '<json>' --strict-json --merge pour ajouter des entrées à la liste d’autorisation sans supprimer les modèles existants. Les remplacements simples qui supprimeraient des entrées sont rejetés, sauf si vous transmettez --replace.
• Les références de modèles utilisent le format provider/model (par exemple anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx contrôle la réduction des images des transcriptions et des outils (valeur par défaut : 1200) ; des valeurs inférieures réduisent généralement l’utilisation des jetons de vision pour les exécutions comportant de nombreuses captures d’écran.
• Consultez la CLI des modèles pour changer de modèle dans la conversation et le basculement de modèle pour la rotation de l’authentification et le comportement de secours.
• Pour les fournisseurs personnalisés ou auto-hébergés, consultez Fournisseurs personnalisés dans la référence.

L’accès aux messages privés est contrôlé pour chaque canal via dmPolicy (valeur par défaut : "pairing") :

• "pairing" : les expéditeurs inconnus reçoivent un code d’association à usage unique à approuver
• "allowlist" : uniquement les expéditeurs figurant dans allowFrom (ou dans le registre des associations autorisées)
• "open" : autoriser tous les messages privés entrants (nécessite allowFrom: ["*"])
• "disabled" : ignorer tous les messages privés

Pour les groupes, utilisez groupPolicy ("allowlist" | "open" | "disabled") avec groupAllowFrom ou les listes d’autorisation propres au canal.

Consultez la référence complète pour obtenir les détails propres à chaque canal.

Par défaut, les messages de groupe nécessitent une mention. Configurez les motifs de déclenchement pour chaque agent. Les réponses normales dans les groupes et les canaux sont publiées automatiquement ; activez explicitement le chemin de l’outil de messagerie pour les salons partagés où l’agent doit décider quand intervenir :

{  messages: {    visibleReplies: "automatic", // définir sur "message_tool" pour exiger des envois via l’outil de messagerie partout    groupChat: {      visibleReplies: "message_tool", // activation explicite ; la sortie visible nécessite message(action=send)      unmentionedInbound: "room_event", // les échanges permanents sans mention dans le groupe servent de contexte silencieux    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Mentions dans les métadonnées : mentions @ natives (mention par toucher dans WhatsApp, @bot dans Telegram, etc.)
• Motifs textuels : motifs d’expressions régulières sûrs dans mentionPatterns
• Réponses visibles : messages.visibleReplies peut exiger globalement des envois via l’outil de messagerie ; messages.groupChat.visibleReplies remplace ce réglage pour les groupes et les canaux.
• Consultez la référence complète pour les modes de réponse visible, les remplacements propres à chaque canal et le mode de conversation avec soi-même.

Utilisez agents.defaults.skills comme base commune, puis remplacez-la pour des agents spécifiques avec agents.list[].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 skill    ],  },}

• Omettez agents.defaults.skills pour ne pas restreindre les Skills par défaut.
• Omettez agents.list[].skills pour hériter des valeurs par défaut.
• Définissez agents.list[].skills: [] pour n’autoriser aucun skill.
• Consultez Skills, la configuration des Skills et la référence de configuration.

Contrôlez avec quelle agressivité le Gateway redémarre les canaux qui semblent obsolètes :

{  gateway: {    channelHealthCheckMinutes: 5,    channelStaleEventThresholdMinutes: 30,    channelMaxRestartsPerHour: 10,  },  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• Les valeurs affichées sont les valeurs par défaut. Définissez gateway.channelHealthCheckMinutes: 0 pour désactiver globalement les redémarrages déclenchés par la surveillance de l’état.
• channelStaleEventThresholdMinutes doit être supérieur ou égal à l’intervalle de vérification.
• Utilisez channels.<provider>.healthMonitor.enabled ou channels.<provider>.accounts.<id>.healthMonitor.enabled pour désactiver les redémarrages automatiques d’un canal ou d’un compte sans désactiver la surveillance globale.
• Consultez les vérifications d’état pour le diagnostic opérationnel et la référence complète pour tous les champs.

Accordez davantage de temps aux clients locaux pour terminer la négociation WebSocket préalable à l’authentification sur les hôtes très sollicités ou peu puissants :

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• La valeur par défaut est de 15000 millisecondes.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS reste prioritaire pour les remplacements ponctuels dans un service ou un shell.
• Corrigez d’abord les blocages au démarrage ou dans la boucle d’événements ; ce réglage est destiné aux hôtes sains mais lents pendant la mise en route.

Les sessions contrôlent la continuité et l’isolation des conversations :

{  session: {

    dmScope: "per-channel-peer",  // recommandé pour plusieurs utilisateurs

    threadBindings: {

      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },

    reset: {      mode: "daily",      atHour: 4,      idleMinutes: 120,    },  },}

• dmScope : main (partagée) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings : valeurs par défaut globales pour le routage des sessions liées à un fil. /focus, /unfocus, /agents, /session idle et /session max-age permettent de lier, délier, répertorier et ajuster ce paramètre pour chaque session (Discord lie les fils, Telegram lie les sujets/conversations).
• Consultez Gestion des sessions pour la portée, les liens d’identité et la politique d’envoi.
• Consultez la référence complète pour tous les champs.

Exécutez les sessions d’agent dans des environnements d’exécution isolés :

{  agents: {    defaults: {      sandbox: {        mode: "non-main",  // off | non-main | all        scope: "agent",    // session | agent | shared      },    },  },}

Créez d’abord l’image : depuis une copie de travail des sources, exécutez scripts/sandbox-setup.sh ; depuis une installation npm, consultez la commande docker build intégrée dans Bac à sable § Images et configuration.

Consultez l’isolation en bac à sable pour le guide complet et la référence complète pour toutes les options.

Les notifications push via relais pour les versions publiques de l’App Store utilisent le relais OpenClaw hébergé : https://ios-push-relay.openclaw.ai.

Les déploiements de relais personnalisés nécessitent un processus de compilation et de déploiement iOS délibérément distinct, dont l’URL du relais correspond à celle du relais du Gateway. Si vous utilisez une version avec relais personnalisé, définissez ceci dans la configuration du Gateway :

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Facultatif. Valeur par défaut : 10000          timeoutMs: 10000,        },      },    },  },}

Équivalent en CLI :

openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com

Fonctionnement :

• Permet au Gateway d’envoyer push.test, des sollicitations de réveil et des réveils de reconnexion par l’intermédiaire du relais externe.
• Utilise une autorisation d’envoi limitée à l’inscription, transmise par l’application iOS appairée. Le Gateway n’a pas besoin d’un jeton de relais valable pour l’ensemble du déploiement.
• Lie chaque inscription reposant sur le relais à l’identité du Gateway avec lequel l’application iOS a été appairée, afin qu’un autre Gateway ne puisse pas réutiliser l’inscription enregistrée.
• Maintient les builds iOS locaux/manuels sur une connexion APNs directe. Les envois reposant sur le relais s’appliquent uniquement aux builds officiels distribués qui se sont inscrits par l’intermédiaire du relais.
• Doit correspondre à l’URL de base du relais intégrée au build iOS, afin que le trafic d’inscription et d’envoi atteigne le même déploiement du relais.

Flux de bout en bout :

1. Installez l’application iOS officielle.
2. Facultatif : configurez gateway.push.apns.relay.baseUrl sur le Gateway uniquement si vous utilisez intentionnellement un build personnalisé avec un relais distinct.
3. Appairez l’application iOS avec le Gateway et laissez les sessions du Node et de l’opérateur se connecter.
4. L’application iOS récupère l’identité du Gateway, s’inscrit auprès du relais à l’aide d’App Attest et du reçu de l’application, puis publie la charge utile push.apns.register reposant sur le relais auprès du Gateway appairé.
5. Le Gateway enregistre l’identifiant du relais et l’autorisation d’envoi, puis les utilise pour push.test, les sollicitations de réveil et les réveils de reconnexion.

Notes opérationnelles :

• Si vous associez l’application iOS à un autre Gateway, reconnectez l’application afin qu’elle puisse publier une nouvelle inscription auprès du relais, liée à ce Gateway.
• Si vous publiez un nouveau build iOS qui pointe vers un autre déploiement du relais, l’application actualise son inscription au relais mise en cache au lieu de réutiliser l’ancienne origine du relais.

Remarque sur la compatibilité :

• OPENCLAW_APNS_RELAY_BASE_URL et OPENCLAW_APNS_RELAY_TIMEOUT_MS fonctionnent toujours comme substitutions temporaires par variables d’environnement.
• Les URL de relais personnalisées du Gateway doivent correspondre à l’URL de base du relais intégrée au build iOS ; le canal de publication public de l’App Store rejette les substitutions d’URL de relais iOS personnalisées.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true reste un mécanisme de contournement réservé au développement en boucle locale ; n’enregistrez pas d’URL de relais HTTP dans la configuration.

Consultez Application iOS pour le flux de bout en bout et Flux d’authentification et de confiance pour le modèle de sécurité du relais.

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last",      },    },  },}

• every : chaîne de durée (30m, 2h). Définissez-la sur 0m pour désactiver cette fonction. Valeur par défaut : 30m.
• target : last | none | <channel-id> (par exemple discord, matrix, telegram ou whatsapp)
• directPolicy : allow (par défaut) ou block pour les cibles de Heartbeat de type message privé
• Consultez Heartbeat pour le guide complet.

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // valeur par défaut ; répartition Cron + exécution isolée des tours d’agent Cron    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention : supprime les sessions d’exécution isolées terminées des lignes de session SQLite (valeur par défaut : 24h ; définissez sur false pour désactiver cette suppression).
• runLog : supprime, pour chaque tâche, les lignes conservées de l’historique des exécutions Cron. L’historique est stocké dans SQLite ; maxBytes (valeur par défaut : 2_000_000) est conservé à des fins de compatibilité avec les anciens journaux d’exécution stockés dans des fichiers, et keepLines vaut 2000 par défaut.
• Consultez Tâches Cron pour une présentation de la fonctionnalité et des exemples de CLI.

Activez les points de terminaison HTTP de Webhook sur le Gateway :

{  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",    defaultSessionKey: "hook:ingress",    allowRequestSessionKey: false,    allowedSessionKeyPrefixes: ["hook:"],    mappings: [      {        match: { path: "gmail" },        action: "agent",        agentId: "main",        deliver: true,      },    ],  },}

Remarque de sécurité :

• Traitez tout le contenu des charges utiles de hook/Webhook comme une entrée non fiable.
• Utilisez un hooks.token dédié ; ne réutilisez pas les secrets d’authentification actifs du Gateway (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN ou gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
• L’authentification des hooks s’effectue uniquement par en-tête (Authorization: Bearer ... ou x-openclaw-token) ; les jetons dans la chaîne de requête sont refusés.
• hooks.path ne peut pas être / ; conservez l’entrée des Webhooks sur un sous-chemin dédié tel que /hooks.
• Laissez désactivés les indicateurs de contournement du filtrage de contenu dangereux (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), sauf lors d’un débogage au périmètre strictement limité.
• Si vous activez hooks.allowRequestSessionKey, définissez également hooks.allowedSessionKeyPrefixes afin de limiter les clés de session sélectionnées par l’appelant.
• Pour les agents pilotés par des hooks, privilégiez des niveaux de modèles modernes et performants ainsi qu’une politique d’outils stricte (par exemple, messagerie uniquement, avec mise en bac à sable lorsque cela est possible).

Consultez la référence complète pour toutes les options de mappage et l’intégration Gmail.

Exécutez plusieurs agents isolés avec des espaces de travail et des sessions distincts :

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

Consultez Multi-agent et la référence complète pour les règles de liaison et les profils d’accès propres à chaque agent.

Utilisez $include pour organiser les configurations volumineuses :

// ~/.openclaw/openclaw.json{  gateway: { port: 18789 },  agents: { $include: "./agents.json5" },  broadcast: {    $include: ["./clients/a.json5", "./clients/b.json5"],  },}

• Fichier unique : remplace l’objet conteneur
• Tableau de fichiers : fusion profonde dans l’ordre (le dernier prévaut), jusqu’à 10 niveaux d’imbrication
• Clés sœurs : fusionnées après les inclusions (elles remplacent les valeurs incluses)
• Chemins relatifs : résolus par rapport au fichier qui effectue l’inclusion
• Format des chemins : les chemins d’inclusion ne doivent pas contenir d’octets nuls et doivent comporter strictement moins de 4096 caractères avant et après leur résolution
• Écritures effectuées par OpenClaw : lorsqu’une écriture ne modifie qu’une seule section de premier niveau reposant sur l’inclusion d’un fichier unique, telle que plugins: { $include: "./plugins.json5" }, OpenClaw met à jour ce fichier inclus et laisse openclaw.json intact
• Écriture propagée non prise en charge : les inclusions à la racine, les tableaux d’inclusions et les inclusions comportant des remplacements par des clés sœurs échouent de manière sécurisée pour les écritures effectuées par OpenClaw au lieu d’aplatir la configuration
• Confinement : les chemins $include doivent être résolus sous le répertoire contenant openclaw.json. Pour partager une arborescence entre plusieurs machines ou utilisateurs, définissez OPENCLAW_INCLUDE_ROOTS sur une liste de chemins (: sous POSIX, ; sous Windows) vers des répertoires supplémentaires auxquels les inclusions peuvent faire référence. Les liens symboliques sont résolus puis vérifiés à nouveau : un chemin situé lexicalement dans un répertoire de configuration, mais dont la cible réelle se trouve en dehors de toutes les racines autorisées, est donc tout de même refusé.
• Gestion des erreurs : messages d’erreur clairs pour les fichiers manquants, les erreurs d’analyse, les inclusions circulaires, les formats de chemin non valides et les longueurs excessives