Configuration

Chaque canal possède sa propre section de configuration sous channels.<provider>. Consultez la page consacré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 de messages privés :

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // association | liste d’autorisation | ouvert | désactivé      allowFrom: ["tg:123"], // uniquement pour liste d’autorisation/ouvert    },  },}

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/* filtrent /model, /models et les sélecteurs de modèles afin de ne présenter que les fournisseurs sélectionnés, tout en continuant d’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 d’échelle des images de transcription et d’outils (valeur par défaut : 1200) ; des valeurs plus faibles réduisent généralement l’utilisation de jetons de vision lors des exécutions contenant de nombreuses captures d’écran.
• Consultez la CLI des modèles pour changer de modèle dans une 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 la section Fournisseurs personnalisés de 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 d’autorisation des associations)
• "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") ainsi que 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 ordinaires de groupe ou de canal sont publiées automatiquement ; activez le chemin de l’outil de messagerie dans les salons partagés où l’agent doit décider quand intervenir :

{  messages: {    visibleReplies: "automatic", // définir "message_tool" pour exiger partout les envois via l’outil de messagerie    groupChat: {      visibleReplies: "message_tool", // activation explicite ; la sortie visible nécessite message(action=send)      unmentionedInbound: "room_event", // les échanges de groupe permanents sans mention constituent un 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 appui 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 les 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 connaître 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 certains agents 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: [] }, // aucune compétence    ],  },}

• 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 aucune compétence.
• Consultez Skills, la configuration des Skills et la référence de configuration.

Contrôlez l’agressivité avec laquelle le Gateway redémarre les canaux qui semblent inactifs :

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

• Les valeurs indiquées sont celles par défaut. Définissez gateway.channelHealthCheckMinutes: 0 pour désactiver globalement les redémarrages effectués par le moniteur d’é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 le moniteur global.
• 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 au niveau du service ou du 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 le préchauffage.

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é) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings : valeurs par défaut globales pour le routage des sessions liées aux fils de discussion. /focus, /unfocus, /agents, /session idle et /session max-age permettent respectivement de lier, délier, répertorier et ajuster ce comportement par session (Discord lie les fils de discussion, 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 en bac à sable :

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

Construisez d’abord l’image : depuis un dépôt source extrait, exécutez scripts/sandbox-setup.sh ; depuis une installation npm, consultez la commande intégrée docker build dans Bac à sable § Images et configuration.

Consultez 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 chemin de compilation et de déploiement iOS volontairement distinct, dont l’URL de relais correspond à celle du relais du Gateway. Si vous utilisez une version personnalisée avec relais, 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 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’enregistrement, transmise par l’app iOS appairée. Le Gateway n’a pas besoin d’un jeton de relais couvrant l’ensemble du déploiement.
• Lie chaque enregistrement via relais à l’identité du Gateway avec lequel l’app iOS a été appairée, afin qu’un autre Gateway ne puisse pas réutiliser l’enregistrement stocké.
• Conserve l’utilisation directe d’APNs pour les versions iOS locales/manuelles. Les envois via relais s’appliquent uniquement aux versions officielles distribuées qui se sont enregistrées par l’intermédiaire du relais.
• Doit correspondre à l’URL de base du relais intégrée à la version iOS, afin que le trafic d’enregistrement et d’envoi atteigne le même déploiement de relais.

Flux de bout en bout :

1. Installez l’app iOS officielle.
2. Facultatif : configurez gateway.push.apns.relay.baseUrl sur le Gateway uniquement si vous utilisez une version personnalisée avec un relais volontairement distinct.
3. Appairez l’app iOS au Gateway et laissez les sessions du Node et de l’opérateur se connecter.
4. L’app iOS récupère l’identité du Gateway, s’enregistre auprès du relais à l’aide d’App Attest et du reçu de l’app, puis publie la charge utile push.apns.register via relais sur le Gateway appairé.
5. Le Gateway stocke 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 connectez l’app iOS à un autre Gateway, reconnectez l’app afin qu’elle puisse publier un nouvel enregistrement de relais lié à ce Gateway.
• Si vous distribuez une nouvelle version iOS qui pointe vers un autre déploiement de relais, l’app actualise son enregistrement de relais mis en cache au lieu de réutiliser l’ancienne origine du relais.

Note de compatibilité :

• OPENCLAW_APNS_RELAY_BASE_URL et OPENCLAW_APNS_RELAY_TIMEOUT_MS fonctionnent toujours comme remplacements temporaires par variables d’environnement.
• Les URL de relais personnalisées du Gateway doivent correspondre à l’URL de base du relais intégrée à la version iOS ; le canal de publication publique de l’App Store rejette les remplacements personnalisés de l’URL du relais iOS.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true reste une échappatoire de développement limitée à l’interface de bouclage ; ne conservez pas d’URL de relais HTTP dans la configuration.

Consultez App 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 0m pour désactiver. 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 d’un tour d’agent Cron    sessionRetention: "24h",  },}

• sessionRetention : supprime les sessions d’exécution isolées terminées des lignes de session SQLite (valeur par défaut : 24h ; définissez false pour désactiver).
• L’historique d’exécution conserve automatiquement les 2000 lignes terminales les plus récentes par tâche ; les lignes perdues conservent leur fenêtre de nettoyage de 24 heures.
• Consultez Tâches Cron pour une présentation de la fonctionnalité et des exemples de CLI.

Activez les points de terminaison Webhook HTTP 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,      },    ],  },}

Note 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 rejetés.
• hooks.path ne peut pas être / ; conservez l’entrée Webhook sur un sous-chemin dédié tel que /hooks.
• Maintenez désactivés les indicateurs de contournement du contenu non sécurisé (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), sauf pour un débogage strictement circonscrit.
• Si vous activez hooks.allowRequestSessionKey, définissez également hooks.allowedSessionKeyPrefixes afin de limiter les clés de session choisies par l’appelant.
• Pour les agents pilotés par des hooks, privilégiez des niveaux de modèles modernes et robustes ainsi qu’une politique stricte concernant les outils (par exemple, messagerie uniquement avec isolation 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 l’emporte), jusqu’à 10 niveaux d’imbrication
• Clés sœurs : fusionnées après les inclusions (remplacent les valeurs incluses)
• Chemins relatifs : résolus par rapport au fichier qui effectue l’inclusion
• Format du chemin : 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 appartenant à OpenClaw : lorsqu’une écriture ne modifie qu’une seule section de premier niveau reposant sur une inclusion de fichier unique telle que plugins: { $include: "./plugins.json5" }, OpenClaw met à jour ce fichier inclus et laisse openclaw.json intact
• Écriture transmise non prise en charge : les inclusions à la racine, les tableaux d’inclusions et les inclusions avec des remplacements par clés sœurs échouent de manière sécurisée pour les écritures appartenant à 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) de répertoires supplémentaires auxquels les inclusions peuvent faire référence. Les liens symboliques sont résolus puis vérifiés de nouveau ; ainsi, un chemin situé lexicalement dans un répertoire de configuration, mais dont la cible réelle échappe à toutes les racines autorisées, est tout de même rejeté.
• Gestion des erreurs : erreurs explicites en cas de fichiers manquants, d’erreurs d’analyse, d’inclusions circulaires, de format de chemin non valide et de longueur excessive