Configuration

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

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

Tous les canaux partagent le même modèle de stratégie DM :

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

Définissez le modèle principal et les solutions de repli facultatives :

{
  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.
• 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 passez --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 le redimensionnement des images de transcript/outils (valeur par défaut 1200) ; des valeurs plus basses réduisent généralement l’utilisation des tokens de vision dans les exécutions avec beaucoup de captures d’écran.
• Consultez CLI des modèles pour changer de modèle dans le chat et Basculement de modèle pour la rotation d’authentification et le comportement de repli.
• Pour les fournisseurs personnalisés/auto-hébergés, consultez Fournisseurs personnalisés dans la référence.

L’accès DM est contrôlé par canal via dmPolicy :

• "pairing" (par défaut) : les expéditeurs inconnus reçoivent un code d’association à usage unique à approuver
• "allowlist" : uniquement les expéditeurs dans allowFrom (ou dans le magasin d’autorisation appairé)
• "open" : autoriser tous les DM entrants (nécessite allowFrom: ["*"])
• "disabled" : ignorer tous les DM

Pour les groupes, utilisez groupPolicy + groupAllowFrom ou des listes d’autorisation propres au canal.

Consultez la référence complète pour les détails par canal.

Les messages de groupe exigent par défaut une mention obligatoire. Configurez les motifs de déclenchement par agent, et conservez les réponses visibles dans les salons sur le chemin par défaut de l’outil de message, sauf si vous voulez volontairement les réponses finales automatiques héritées :

{
  messages: {
    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere
    groupChat: {
      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

• Mentions de métadonnées : @-mentions natives (mention par appui WhatsApp, @bot Telegram, etc.)
• Motifs de texte : motifs regex sûrs dans mentionPatterns
• Réponses visibles : messages.visibleReplies peut exiger des envois par outil de message globalement ; messages.groupChat.visibleReplies remplace ce comportement pour les groupes/canaux.
• Consultez la référence complète pour les modes de réponse visible, les remplacements par canal et le mode self-chat.

Utilisez agents.defaults.skills pour une base partagée, puis remplacez des agents spécifiques avec agents.list[].skills :

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

• Omettez agents.defaults.skills pour des Skills non restreints par défaut.
• Omettez agents.list[].skills pour hériter des valeurs par défaut.
• Définissez agents.list[].skills: [] pour aucun Skills.
• Consultez Skills, 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 },
        },
      },
    },
  },
}

• Définissez gateway.channelHealthCheckMinutes: 0 pour désactiver globalement les redémarrages par surveillance de santé.
• 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 Contrôles de santé pour le débogage opérationnel et la référence complète pour tous les champs.

Donnez aux clients locaux plus de temps pour terminer la poignée de main WebSocket pré-authentification sur des hôtes chargés ou peu puissants :

{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}

• La valeur par défaut est 15000 millisecondes.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS reste prioritaire pour les remplacements ponctuels de service ou de shell.
• Préférez corriger d’abord les blocages du démarrage ou de la boucle d’événements ; ce réglage est destiné aux hôtes qui sont sains mais lents pendant le préchauffage.

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

{
  session: {
    dmScope: "per-channel-peer",  // recommended for multi-user
    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 (Discord prend en charge /focus, /unfocus, /agents, /session idle et /session max-age).
• Consultez Gestion des sessions pour la portée, les liens d’identité et la stratégie d’envoi.
• Consultez la référence complète pour tous les champs.

Exécutez les sessions d’agent dans des runtimes sandbox isolés :

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

Construisez d’abord l’image - depuis un checkout source, exécutez scripts/sandbox-setup.sh, ou depuis une installation npm, consultez la commande docker build intégrée dans Sandboxing § Images et configuration.

Consultez Sandboxing pour le guide complet et la référence complète pour toutes les options.

Les notifications push adossées à un relais sont configurées dans openclaw.json.

Définissez ceci dans la configuration du Gateway :

{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Optional. Default: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}

Équivalent CLI :

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

Ce que cela fait :

• Permet au Gateway d’envoyer push.test, les rappels de réveil et les réveils de reconnexion via le relais externe.
• Utilise une autorisation d’envoi limitée à l’inscription, transférée par l’app iOS jumelée. Le Gateway n’a pas besoin d’un jeton de relais couvrant tout le déploiement.
• Lie chaque inscription adossée au relais à l’identité du Gateway avec lequel l’app iOS a été jumelée, afin qu’un autre Gateway ne puisse pas réutiliser l’inscription stockée.
• Maintient les builds iOS locaux/manuels sur des APNs directs. Les envois adossés au relais s’appliquent uniquement aux builds distribués officiels enregistrés via le relais.
• Doit correspondre à l’URL de base du relais intégrée dans le build iOS officiel/TestFlight, afin que le trafic d’inscription et d’envoi atteigne le même déploiement de relais.

Flux de bout en bout :

1. Installez un build iOS officiel/TestFlight compilé avec la même URL de base de relais.
2. Configurez gateway.push.apns.relay.baseUrl sur le Gateway.
3. Jumelez l’app iOS au Gateway et laissez les sessions de nœud et d’opérateur se connecter.
4. L’app iOS récupère l’identité du Gateway, s’inscrit auprès du relais avec App Attest et le reçu de l’app, puis publie la charge utile push.apns.register adossée au relais vers le Gateway jumelé.
5. Le Gateway stocke le handle de relais et l’autorisation d’envoi, puis les utilise pour push.test, les rappels de réveil et les réveils de reconnexion.

Notes opérationnelles :

• Si vous basculez l’app iOS vers un autre Gateway, reconnectez l’app afin qu’elle puisse publier une nouvelle inscription au relais liée à ce Gateway.
• Si vous livrez un nouveau build iOS pointant vers un autre déploiement de relais, l’app actualise son inscription au relais mise en cache au lieu de réutiliser l’ancienne origine de relais.

Note de compatibilité :

• OPENCLAW_APNS_RELAY_BASE_URL et OPENCLAW_APNS_RELAY_TIMEOUT_MS fonctionnent toujours comme remplacements temporaires par variables d’environnement.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true reste une échappatoire de développement limitée au local loopback ; ne persistez 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.
• target : last | none | <channel-id> (par exemple discord, matrix, telegram ou whatsapp)
• directPolicy : allow (par défaut) ou block pour les cibles Heartbeat de type MP
• Consultez Heartbeat pour le guide complet.

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

• sessionRetention : élague les sessions d’exécution isolées terminées de sessions.json (par défaut 24h ; définissez false pour désactiver).
• runLog : élague cron/runs/<jobId>.jsonl par taille et nombre de lignes conservées.
• Consultez Tâches Cron pour l’aperçu de la fonctionnalité et des exemples 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 hook/Webhook comme une entrée non fiable.
• Utilisez un hooks.token dédié ; ne réutilisez pas le jeton Gateway partagé.
• L’authentification des hooks se fait 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 / ; gardez l’entrée Webhook sur un sous-chemin dédié comme /hooks.
• Gardez les indicateurs de contournement de contenu non sûr désactivés (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), sauf pour un débogage strictement limité.
• Si vous activez hooks.allowRequestSessionKey, définissez aussi hooks.allowedSessionKeyPrefixes afin de borner les clés de session choisies par l’appelant.
• Pour les agents pilotés par hook, privilégiez des niveaux de modèles modernes et robustes ainsi qu’une politique d’outils stricte (par exemple uniquement la messagerie, plus le sandboxing lorsque 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 par 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)
• Clés sœurs : fusionnées après les inclusions (remplacent les valeurs incluses)
• Inclusions imbriquées : prises en charge jusqu’à 10 niveaux de profondeur
• Chemins relatifs : résolus par rapport au fichier qui inclut
• Écritures appartenant à OpenClaw : lorsqu’une écriture ne modifie qu’une seule section de premier niveau adossée à une inclusion de fichier unique comme plugins: { $include: "./plugins.json5" }, OpenClaw met à jour ce fichier inclus et laisse openclaw.json intact
• Écriture traversante non prise en charge : les inclusions racine, les tableaux d’inclusions et les inclusions avec remplacements par clés sœurs échouent fermement pour les écritures appartenant à OpenClaw au lieu d’aplatir la configuration
• Confinement : les chemins $include doivent se résoudre sous le répertoire contenant openclaw.json. Pour partager une arborescence entre des machines ou des utilisateurs, définissez OPENCLAW_INCLUDE_ROOTS sur une liste de chemins (: sur POSIX, ; sur Windows) de répertoires supplémentaires que les inclusions peuvent référencer. Les liens symboliques sont résolus et revérifiés ; un chemin qui se trouve lexicalement dans un répertoire de configuration, mais dont la vraie cible s’échappe de chaque racine autorisée, est donc toujours rejeté.
• Gestion des erreurs : erreurs claires pour les fichiers manquants, les erreurs d’analyse et les inclusions circulaires