Exemples de configuration

Les exemples ci-dessous sont conformes au schéma de configuration actuel. Pour consulter la référence exhaustive et les remarques propres à chaque champ, voir Configuration.

Démarrage rapide

Minimum absolu

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Enregistrez dans ~/.openclaw/openclaw.json pour pouvoir envoyer un message privé au bot depuis ce numéro.

Configuration initiale recommandée

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "anthropic/claude-sonnet-4-6" },
    },
    list: [
      {
        id: "main",
        identity: {
          name: "Clawd",
          theme: "assistant utile",
          emoji: "🦞",
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  messages: {
    visibleReplies: "automatic",
    groupChat: {
      visibleReplies: "message_tool", // activation explicite ; la sortie visible nécessite message(action=send)
      unmentionedInbound: "room_event",
    },
  },
}

Exemple étendu (options principales)

JSON5 permet d’utiliser des commentaires et des virgules finales. Le JSON standard fonctionne également.

{
  // Environnement + shell
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },

  // Métadonnées des profils d’authentification (les secrets se trouvent dans auth-profiles.json)
  auth: {
    profiles: {
      "anthropic:default": { provider: "anthropic", mode: "api_key" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai:default": { provider: "openai", mode: "api_key" },
      "openai:personal": { provider: "openai", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:default", "anthropic:work"],
      openai: ["openai:personal", "openai:default"],
    },
  },

  // L’identité est propre à chaque agent — définissez-la dans agents.list[].identity ci-dessous.

  // Journalisation
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",
  },

  // Mise en forme des messages
  messages: {
    messagePrefix: "[openclaw]",
    visibleReplies: "automatic",
    responsePrefix: ">",
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
    groupChat: {
      historyLimit: 50,
      visibleReplies: "message_tool", // à activer pour les salons partagés avec des modèles utilisant les outils de manière fiable
      unmentionedInbound: "room_event",
    },
    queue: {
      mode: "followup",
      debounceMs: 500,
      cap: 20,
      drop: "summarize",
      byChannel: {
        whatsapp: "followup",
        telegram: "followup",
        discord: "collect",
        slack: "collect",
        signal: "followup",
        imessage: "followup",
        webchat: "followup",
      },
    },
  },

  // Outils
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        models: [
          { provider: "openai", model: "gpt-4o-transcribe" },
          // Solution de secours facultative via la CLI (binaire Whisper) :
          // { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }
        ],
        timeoutSeconds: 120,
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },

  // Comportement des sessions
  session: {
    scope: "per-sender",
    dmScope: "per-channel-peer", // recommandé pour les boîtes de réception multiutilisateurs
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 60,
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 10080 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/main/sessions/sessions.json",
    maintenance: {
      mode: "warn",
      pruneAfter: "30d",
      maxEntries: 500,
      resetArchiveRetention: "30d", // durée ou false
      maxDiskBytes: "500mb", // facultatif
      highWaterBytes: "400mb", // facultatif (80 % de maxDiskBytes par défaut)
    },
    typingIntervalSeconds: 5,
    sendPolicy: {
      default: "allow",
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
    },
  },

  // Canaux
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15555550123"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },

    telegram: {
      enabled: true,
      botToken: "YOUR_TELEGRAM_BOT_TOKEN",
      allowFrom: ["123456789"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["123456789"],
      groups: { "*": { requireMention: true } },
    },

    discord: {
      enabled: true,
      token: "YOUR_DISCORD_BOT_TOKEN",
      dm: { enabled: true, allowFrom: ["123456789012345678"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          channels: {
            general: { enabled: true },
            help: { enabled: true, requireMention: true },
          },
        },
      },
    },

    slack: {
      enabled: true,
      botToken: "xoxb-REPLACE_ME",
      appToken: "xapp-REPLACE_ME",
      channels: {
        "#general": { enabled: true, requireMention: true },
      },
      dm: { enabled: true, allowFrom: ["U123"] },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
    },
  },

  // Environnement d’exécution des agents
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      userTimezone: "America/Chicago",
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.4"],
      },
      imageModel: {
        primary: "openrouter/anthropic/claude-sonnet-4-6",
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
        "openai/gpt-5.4": { alias: "gpt" },
      },
      skills: ["github", "weather"], // héritées par les agents qui omettent list[].skills
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "off",
      elevatedDefault: "on",
      blockStreamingDefault: "off",
      blockStreamingBreak: "text_end",
      blockStreamingChunk: {
        minChars: 800,
        maxChars: 1200,
        breakPreference: "paragraph",
      },
      blockStreamingCoalesce: {
        idleMs: 1000,
      },
      humanDelay: {
        mode: "natural",
      },
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      typingIntervalSeconds: 5,
      maxConcurrent: 3,
      heartbeat: {
        every: "30m",
        model: "anthropic/claude-sonnet-4-6",
        target: "last",
        directPolicy: "allow", // allow (par défaut) | block
        to: "+15555550123",
        prompt: "HEARTBEAT",
        ackMaxChars: 300,
      },
      memorySearch: {
        provider: "gemini",
        model: "gemini-embedding-001",
        remote: {
          apiKey: "${GEMINI_API_KEY}",
        },
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
      sandbox: {
        mode: "non-main",
        scope: "session", // préférable à l’ancien perSession: true
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
        },
        browser: {
          enabled: false,
        },
      },
    },
    list: [
      {
        id: "main",
        default: true,
        identity: {
          name: "Samantha",
          theme: "paresseux serviable",
          emoji: "🦥",
        },
        // hérite de defaults.skills -> github, weather
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
        thinkingDefault: "high", // remplacement du niveau de réflexion propre à l’agent
        reasoningDefault: "on", // visibilité du raisonnement propre à l’agent
        fastModeDefault: false, // mode rapide propre à l’agent
      },
      {
        id: "quick",
        skills: [], // aucune Skills pour cet agent
        fastModeDefault: true, // cet agent fonctionne toujours en mode rapide
        thinkingDefault: "off",
      },
    ],
  },

  tools: {
    allow: ["exec", "process", "read", "write", "edit", "apply_patch"],
    deny: ["browser", "canvas"],
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
    },
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        telegram: ["123456789"],
        discord: ["123456789012345678"],
        slack: ["U123"],
        signal: ["+15555550123"],
        imessage: ["user@example.com"],
        webchat: ["session:demo"],
      },
    },
  },

  // Fournisseurs de modèles personnalisés
  models: {
    mode: "merge",
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-responses",
        authHeader: true,
        headers: { "X-Proxy-Region": "us-west" },
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            api: "openai-responses",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },

  // Tâches Cron
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 8, // valeur par défaut ; distribution Cron + exécution isolée d’un tour d’agent Cron
    sessionRetention: "24h",
  },

  // Webhooks
  hooks: {
    enabled: true,
    path: "/hooks",
    token: "shared-secret",
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks/transforms",
    mappings: [
      {
        id: "gmail-hook",
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "De : {{messages[0].from}}\nObjet : {{messages[0].subject}}",
        textTemplate: "{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        to: "+15555550123",
        thinking: "low",
        timeoutSeconds: 300,
        transform: {
          module: "gmail.js",
          export: "transformGmail",
        },
      },
    ],
    gmail: {
      account: "openclaw@gmail.com",
      label: "INBOX",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },
    },
  },

  // Gateway + réseau
  gateway: {
    mode: "local",
    port: 18789,
    bind: "loopback",
    controlUi: { enabled: true, basePath: "/openclaw" },
    auth: {
      mode: "token",
      token: "gateway-token",
      allowTailscale: true,
    },
    tailscale: { mode: "serve", resetOnExit: false },
    remote: { url: "ws://gateway-host.ts.net:18789", token: "remote-token" },
    reload: { mode: "hybrid", debounceMs: 300 },
  },

  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun
      allowUploadedArchives: false,
    },
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
    },
  },
}

Dépôt frère de Skills lié symboliquement

Utilisez ceci lorsqu’une racine de Skills intégrée contient un lien symbolique vers un dépôt frère, par exemple ~/.agents/skills/manager -> ~/Projects/manager/skills.

{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}

extraDirs analyse le dépôt frère en tant que racine de Skills explicite.
allowSymlinkTargets permet aux dossiers de Skills liés symboliquement d’être résolus dans cette racine cible réelle de confiance sans autoriser de sorties arbitraires par lien symbolique.
Pour permettre à Skill Workshop d’écrire via la même cible de lien symbolique de confiance, définissez skills.workshop.allowSymlinkTargetWrites: true.

Modèles courants

Base de Skills partagée avec un remplacement

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      skills: ["github", "weather"],
    },
    list: [
      { id: "main", default: true },
      { id: "docs", workspace: "~/.openclaw/workspace-docs", skills: ["docs-search"] },
    ],
  },
}

agents.defaults.skills est la base de référence partagée.
agents.list[].skills remplace cette base de référence pour un agent.
Utilisez skills: [] lorsqu’un agent ne doit voir aucune compétence.

Configuration multiplateforme

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: {
    whatsapp: { allowFrom: ["+15555550123"] },
    telegram: {
      enabled: true,
      botToken: "YOUR_TOKEN",
      allowFrom: ["123456789"],
    },
    discord: {
      enabled: true,
      token: "YOUR_TOKEN",
      dm: { allowFrom: ["123456789012345678"] },
    },
  },
}

Approbation automatique sur un réseau de nœuds de confiance

Conservez l’association manuelle des appareils, sauf si vous contrôlez le chemin réseau. Pour un laboratoire dédié ou un sous-réseau du tailnet, vous pouvez activer l’approbation automatique des appareils de nœud lors de leur première connexion à l’aide d’adresses IP ou de blocs CIDR exacts :

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
      },
    },
  },
}

Cette fonctionnalité reste désactivée lorsqu’elle n’est pas définie. Elle s’applique uniquement aux nouvelles associations role: node sans portées demandées. Les clients opérateur/navigateur ainsi que les mises à niveau de rôle, de portée, de métadonnées ou de clé publique nécessitent toujours une approbation manuelle.

Mode sécurisé pour les messages privés (boîte de réception partagée / messages privés multi-utilisateurs)

Si plusieurs personnes peuvent envoyer des messages privés à votre bot (plusieurs entrées dans allowFrom, des approbations d’association pour plusieurs personnes ou dmPolicy: "open"), activez le mode sécurisé pour les messages privés afin que les messages privés provenant de différents expéditeurs ne partagent pas un même contexte par défaut :

{
  // Mode sécurisé pour les messages privés (recommandé pour les agents multi-utilisateurs ou traitant des messages privés sensibles)
  session: { dmScope: "per-channel-peer" },

  channels: {
    // Exemple : boîte de réception WhatsApp multi-utilisateurs
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123", "+15555550124"],
    },

    // Exemple : boîte de réception Discord multi-utilisateurs
    discord: {
      enabled: true,
      token: "YOUR_DISCORD_BOT_TOKEN",
      dm: { enabled: true, allowFrom: ["123456789012345678", "987654321098765432"] },
    },
  },
}

Pour Discord/Google Chat/IRC/Mattermost/Microsoft Teams/Slack, l’autorisation des expéditeurs repose par défaut en priorité sur l’identifiant. N’activez la correspondance directe avec des noms/adresses e-mail/pseudonymes modifiables au moyen du paramètre dangerouslyAllowNameMatching: true de chaque canal que si vous acceptez explicitement ce risque.

Clé API Anthropic avec MiniMax comme solution de repli

{
  auth: {
    profiles: {
      "anthropic:api": {
        provider: "anthropic",
        mode: "api_key",
      },
    },
    order: {
      anthropic: ["anthropic:api"],
    },
  },
  models: {
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        api: "anthropic-messages",
        apiKey: "${MINIMAX_API_KEY}",
      },
    },
  },
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
    },
  },
}

Bot professionnel (accès restreint)

{
  agents: {
    defaults: {
      workspace: "~/work-openclaw",
      elevatedDefault: "off",
    },
    list: [
      {
        id: "main",
        identity: {
          name: "WorkBot",
          theme: "professional assistant",
        },
      },
    ],
  },
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      channels: {
        "#engineering": { enabled: true, requireMention: true },
        "#general": { enabled: true, requireMention: true },
      },
    },
  },
}

Modèles locaux uniquement

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "lmstudio/my-local-model" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

Conseils

Si vous définissez dmPolicy: "open", la liste allowFrom correspondante doit inclure "*".
Les identifiants des fournisseurs diffèrent (numéros de téléphone, identifiants utilisateur, identifiants de canal). Consultez la documentation du fournisseur pour confirmer le format.
Sections facultatives à ajouter ultérieurement : web, browser, ui, discovery, plugins, talk, signal, imessage.
Consultez Fournisseurs et Dépannage pour obtenir des informations de configuration plus détaillées.

Gateway

Remote access

Security

Nodes and media

Web interfaces

Exemples de configuration

Démarrage rapide

Minimum absolu

Configuration initiale recommandée

Exemple étendu (options principales)

Dépôt frère de Skills lié symboliquement

Modèles courants

Base de Skills partagée avec un remplacement

Configuration multiplateforme

Approbation automatique sur un réseau de nœuds de confiance

Mode sécurisé pour les messages privés (boîte de réception partagée / messages privés multi-utilisateurs)

Clé API Anthropic avec MiniMax comme solution de repli

Bot professionnel (accès restreint)

Modèles locaux uniquement

Conseils

Pages connexes

​Démarrage rapide

​Minimum absolu

​Configuration initiale recommandée

​Exemple étendu (options principales)

​Dépôt frère de Skills lié symboliquement

​Modèles courants

​Base de Skills partagée avec un remplacement

​Configuration multiplateforme

​Approbation automatique sur un réseau de nœuds de confiance

​Mode sécurisé pour les messages privés (boîte de réception partagée / messages privés multi-utilisateurs)

​Clé API Anthropic avec MiniMax comme solution de repli

​Bot professionnel (accès restreint)

​Modèles locaux uniquement

​Conseils

​Pages connexes

Démarrage rapide

Minimum absolu

Configuration initiale recommandée

Exemple étendu (options principales)

Dépôt frère de Skills lié symboliquement

Modèles courants

Base de Skills partagée avec un remplacement

Configuration multiplateforme

Approbation automatique sur un réseau de nœuds de confiance

Mode sécurisé pour les messages privés (boîte de réception partagée / messages privés multi-utilisateurs)

Clé API Anthropic avec MiniMax comme solution de repli

Bot professionnel (accès restreint)

Modèles locaux uniquement

Conseils

Pages connexes