Traductions communautaires par veiseule.ai — Help improve them on Crowdin
Aller au contenu principal

Configuration đŸ”§Â¶

OpenClaw lit une configuration JSON5 optionnelle depuis ~/.openclaw/openclaw.json (commentaires + virgules finales autorisés).

Si le fichier est absent, OpenClaw utilise des valeurs par dĂ©faut relativement sĂ»res (agent Pi intĂ©grĂ© + sessions par expĂ©diteur + espace de travail ~/.openclaw/workspace). En gĂ©nĂ©ral, vous n’avez besoin d’une configuration que pour :

  • restreindre qui peut dĂ©clencher le bot (channels.whatsapp.allowFrom, channels.telegram.allowFrom, etc.)
  • contrĂŽler les listes d’autorisation de groupes + le comportement des mentions (channels.whatsapp.groups, channels.telegram.groups, channels.discord.guilds, agents.list[].groupChat)
  • personnaliser les prĂ©fixes de messages (messages)
  • dĂ©finir l’espace de travail de l’agent (agents.defaults.workspace ou agents.list[].workspace)
  • ajuster les paramĂštres par dĂ©faut de l’agent intĂ©grĂ© (agents.defaults) et le comportement des sessions (session)
  • dĂ©finir l’identitĂ© par agent (agents.list[].identity)

Nouveau dans la configuration ? Consultez le guide Configuration Examples pour des exemples complets avec des explications dĂ©taillĂ©es !

Validation stricte de la configuration¶

OpenClaw n’accepte que les configurations qui correspondent entiĂšrement au schĂ©ma. Les clĂ©s inconnues, les types mal formĂ©s ou les valeurs invalides amĂšnent la Gateway (passerelle) Ă  refuser de dĂ©marrer par mesure de sĂ©curitĂ©.

En cas d’échec de la validation :

  • La Gateway ne dĂ©marre pas.
  • Seules les commandes de diagnostic sont autorisĂ©es (par exemple : openclaw doctor, openclaw logs, openclaw health, openclaw status, openclaw service, openclaw help).
  • ExĂ©cutez openclaw doctor pour voir les problĂšmes exacts.
  • ExĂ©cutez openclaw doctor --fix (ou --yes) pour appliquer les migrations/rĂ©parations.

Doctor n’écrit jamais de modifications sauf si vous optez explicitement pour --fix/--yes.

Schéma + indications UI¶

La Gateway expose une reprĂ©sentation JSON Schema de la configuration via config.schema pour les Ă©diteurs d’interface. L’interface de contrĂŽle gĂ©nĂšre un formulaire Ă  partir de ce schĂ©ma, avec un Ă©diteur Raw JSON comme Ă©chappatoire.

Les plugins et extensions de canaux peuvent enregistrer un schéma + des indications UI pour leur configuration, afin que les paramÚtres de canaux restent pilotés par schéma dans toutes les applications sans formulaires codés en dur.

Les indications (libellés, regroupements, champs sensibles) accompagnent le schéma afin que les clients puissent rendre de meilleurs formulaires sans connaissance codée en dur de la configuration.

Appliquer + redémarrer (RPC)¶

Utilisez config.apply pour valider + écrire la configuration complÚte et redémarrer la Gateway en une seule étape. Cela écrit un marqueur de redémarrage et ping la derniÚre session active aprÚs le redémarrage de la Gateway.

Avertissement : config.apply remplace l’intĂ©gralitĂ© de la configuration. Si vous souhaitez ne modifier que quelques clĂ©s, utilisez config.patch ou openclaw config set. Conservez une sauvegarde de ~/.openclaw/openclaw.json.

Parametres :

  • raw (string) — charge utile JSON5 pour la configuration complĂšte
  • baseHash (optionnel) — hachage de configuration provenant de config.get (requis lorsqu’une configuration existe dĂ©jĂ )
  • sessionKey (optionnel) — clĂ© de la derniĂšre session active pour le ping de rĂ©veil
  • note (optionnel) — note Ă  inclure dans le marqueur de redĂ©marrage
  • restartDelayMs (optionnel) — dĂ©lai avant redĂ©marrage (par dĂ©faut 2000)

Exemple (via gateway call) :

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{\\n  agents: { defaults: { workspace: \\"~/.openclaw/workspace\\" } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

Mises à jour partielles (RPC)¶

Utilisez config.patch pour fusionner une mise Ă  jour partielle dans la configuration existante sans Ă©craser les clĂ©s non liĂ©es. Cela applique la sĂ©mantique de JSON merge patch :

  • les objets fusionnent rĂ©cursivement
  • null supprime une clĂ©
  • les tableaux sont remplacĂ©s
    Comme config.apply, la configuration est validée, écrite, un marqueur de redémarrage est stocké, puis le redémarrage de la Gateway est planifié (avec un réveil optionnel lorsque sessionKey est fourni).

Parametres :

  • raw (string) — charge utile JSON5 contenant uniquement les clĂ©s Ă  modifier
  • baseHash (requis) — hachage de configuration provenant de config.get
  • sessionKey (optionnel) — clĂ© de la derniĂšre session active pour le ping de rĂ©veil
  • note (optionnel) — note Ă  inclure dans le marqueur de redĂ©marrage
  • restartDelayMs (optionnel) — dĂ©lai avant redĂ©marrage (par dĂ©faut 2000)

Exemple :

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{\\n  channels: { telegram: { groups: { \\"*\\": { requireMention: false } } } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

Configuration minimale (point de départ recommandé)¶

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

Construisez l’image par dĂ©faut une seule fois avec :

scripts/sandbox-setup.sh

Mode auto-discussion (recommandé pour le contrÎle des groupes)¶

Pour empĂȘcher le bot de rĂ©pondre aux @-mentions WhatsApp dans les groupes (rĂ©pondre uniquement Ă  des dĂ©clencheurs textuels spĂ©cifiques) :

{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["@openclaw", "reisponde"] },
      },
    ],
  },
  channels: {
    whatsapp: {
      // Allowlist is DMs only; including your own number enables self-chat mode.
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
}

Inclusions de configuration ($include)¶

Scindez votre configuration en plusieurs fichiers à l’aide de la directive $include. Ceci est utile pour :

  • organiser de grandes configurations (p. ex. dĂ©finitions d’agents par client)
  • partager des paramĂštres communs entre environnements
  • conserver les configurations sensibles sĂ©parĂ©ment

Utilisation de base¶

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },

  // Include a single file (replaces the key's value)
  agents: { $include: "./agents.json5" },

  // Include multiple files (deep-merged in order)
  broadcast: {
    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
  },
}

// ~/.openclaw/agents.json5
{
  defaults: { sandbox: { mode: "all", scope: "session" } },
  list: [{ id: "main", workspace: "~/.openclaw/workspace" }],
}

Comportement de fusion¶

  • Fichier unique : remplace l’objet contenant $include
  • Tableau de fichiers : fusion profonde des fichiers dans l’ordre (les fichiers ultĂ©rieurs remplacent les prĂ©cĂ©dents)
  • Avec clĂ©s sƓurs : les clĂ©s sƓurs sont fusionnĂ©es aprĂšs les inclusions (elles remplacent les valeurs incluses)
  • ClĂ©s sƓurs + tableaux/primitifs : non pris en charge (le contenu inclus doit ĂȘtre un objet)
// Sibling keys override included values
{
  $include: "./base.json5", // { a: 1, b: 2 }
  b: 99, // Result: { a: 1, b: 99 }
}

Inclusions imbriquées¶

Les fichiers inclus peuvent eux-mĂȘmes contenir des directives $include (jusqu’à 10 niveaux de profondeur) :

// clients/mueller.json5
{
  agents: { $include: "./mueller/agents.json5" },
  broadcast: { $include: "./mueller/broadcast.json5" },
}

Résolution des chemins¶

  • Chemins relatifs : rĂ©solus par rapport au fichier incluant
  • Chemins absolus : UtilisĂ© tel quel
  • RĂ©pertoires parents : les rĂ©fĂ©rences ../ fonctionnent comme attendu
{ "$include": "./sub/config.json5" }      // relative
{ "$include": "/etc/openclaw/base.json5" } // absolute
{ "$include": "../shared/common.json5" }   // parent dir

Gestion des erreurs¶

  • Fichier manquant : erreur claire avec le chemin rĂ©solu
  • Erreur d’analyse : indique quel fichier inclus a Ă©chouĂ©
  • Inclusions circulaires : dĂ©tectĂ©es et signalĂ©es avec la chaĂźne d’inclusion

Exemple : configuration lĂ©gale multi‑clients¶

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789, auth: { token: "secret" } },

  // Common agent defaults
  agents: {
    defaults: {
      sandbox: { mode: "all", scope: "session" },
    },
    // Merge agent lists from all clients
    list: { $include: ["./clients/mueller/agents.json5", "./clients/schmidt/agents.json5"] },
  },

  // Merge broadcast configs
  broadcast: {
    $include: ["./clients/mueller/broadcast.json5", "./clients/schmidt/broadcast.json5"],
  },

  channels: { whatsapp: { groupPolicy: "allowlist" } },
}

// ~/.openclaw/clients/mueller/agents.json5
[
  { id: "mueller-transcribe", workspace: "~/clients/mueller/transcribe" },
  { id: "mueller-docs", workspace: "~/clients/mueller/docs" },
]

// ~/.openclaw/clients/mueller/broadcast.json5
{
  "120363403215116621@g.us": ["mueller-transcribe", "mueller-docs"],
}

Options courantes¶

Env vars + .env¶

OpenClaw lit les variables d’environnement depuis le processus parent (shell, launchd/systemd, CI, etc.).

De plus, il charge :

  • .env depuis le rĂ©pertoire de travail courant (s’il existe)
  • un repli global .env depuis ~/.openclaw/.env (alias $OPENCLAW_STATE_DIR/.env)

Aucun fichier .env ne remplace des variables d’environnement existantes.

Vous pouvez Ă©galement fournir des variables d’environnement en ligne dans la configuration. Elles ne sont appliquĂ©es que si la variable est absente de l’environnement du processus (mĂȘme rĂšgle de non‑remplacement) :

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

Voir /environment pour la priorité complÚte et les sources.

env.shellEnv (optionnel)¶

Option de confort : si activĂ©e et qu’aucune des clĂ©s attendues n’est encore dĂ©finie, OpenClaw exĂ©cute votre shell de connexion et importe uniquement les clĂ©s attendues manquantes (ne remplace jamais). Cela revient Ă  sourcer votre profil de shell.

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

Env var Ă©quivalent:

  • OPENCLAW_LOAD_SHELL_ENV=1
  • OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Substitution de variables d’environnement dans la configuration¶

Vous pouvez rĂ©fĂ©rencer des variables d’environnement directement dans toute valeur de chaĂźne de la configuration en utilisant la syntaxe ${VAR_NAME}. Les variables sont substituĂ©es au chargement de la configuration, avant validation.

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
}

Rùgles :

  • Seuls les noms de variables en majuscules sont reconnus : [A-Z_][A-Z0-9_]*
  • Il manque ou vide env vars lancer une erreur au chargement de la configuration
  • Échappez avec $${VAR} pour produire un ${VAR} littĂ©ral
  • Fonctionne avec $include (les fichiers inclus bĂ©nĂ©ficient aussi de la substitution)

Substitution en ligne :

{
  models: {
    providers: {
      custom: {
        baseUrl: "${CUSTOM_API_BASE}/v1", // → "https://api.example.com/v1"
      },
    },
  },
}

Stockage d’authentification (OAuth + clĂ©s API)¶

OpenClaw stocke des profils d’authentification par agent (OAuth + clĂ©s API) dans :

  • <agentDir>/auth-profiles.json (par dĂ©faut : ~/.openclaw/agents/<agentId>/agent/auth-profiles.json)

Voir aussi : /concepts/oauth

Imports OAuth hĂ©ritĂ©s :

  • ~/.openclaw/credentials/oauth.json (ou $OPENCLAW_STATE_DIR/credentials/oauth.json)

L’agent Pi intĂ©grĂ© maintient un cache d’exĂ©cution à :

  • <agentDir>/auth.json (gĂ©rĂ© automatiquement ; ne pas modifier manuellement)

RĂ©pertoire d’agent hĂ©ritĂ© (avant le multi‑agent) :

  • ~/.openclaw/agent/* (migrĂ© par openclaw doctor vers ~/.openclaw/agents/<defaultAgentId>/agent/*)

Remplacements :

  • RĂ©pertoire OAuth (import hĂ©ritĂ© uniquement) : OPENCLAW_OAUTH_DIR
  • RĂ©pertoire d’agent (remplacement de la racine par dĂ©faut) : OPENCLAW_AGENT_DIR (prĂ©fĂ©rĂ©), PI_CODING_AGENT_DIR (hĂ©ritĂ©)

Lors de la premiÚre utilisation, OpenClaw importe les entrées oauth.json dans auth-profiles.json.

auth¶

MĂ©tadonnĂ©es optionnelles pour les profils d’authentification. Cela ne stocke pas de secrets ; cela mappe les identifiants de profil vers un fournisseur + un mode (et un e‑mail optionnel) et dĂ©finit l’ordre de rotation des fournisseurs utilisĂ© pour le basculement.

{
  auth: {
    profiles: {
      "anthropic:me@example.com": { provider: "anthropic", mode: "oauth", email: "me@example.com" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
    },
    order: {
      anthropic: ["anthropic:me@example.com", "anthropic:work"],
    },
  },
}

agents.list[].identity¶

IdentitĂ© par agent optionnelle utilisĂ©e pour les valeurs par dĂ©faut et l’UX. Elle est Ă©crite par l’assistant de prise en main macOS.

Si dĂ©finie, OpenClaw dĂ©rive des valeurs par dĂ©faut (uniquement si vous ne les avez pas dĂ©finies explicitement) :

  • messages.ackReaction depuis l’identity.emoji de l’agent actif (repli sur 👀)
  • agents.list[].groupChat.mentionPatterns depuis l’identity.name/identity.emoji de l’agent (ainsi « @Samantha » fonctionne dans les groupes sur Telegram/Slack/Discord/Google Chat/iMessage/WhatsApp)
  • identity.avatar accepte un chemin d’image relatif Ă  l’espace de travail ou une URL distante/URL de donnĂ©es. Les fichiers locaux doivent se trouver dans l’espace de travail de l’agent.

identity.avatar accepte :

  • un chemin relatif Ă  l’espace de travail (doit rester dans l’espace de travail de l’agent)
  • une URL http(s)
  • un URI data:
{
  agents: {
    list: [
      {
        id: "main",
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "đŸŠ„",
          avatar: "avatars/samantha.png",
        },
      },
    ],
  },
}

wizard¶

Métadonnées écrites par les assistants CLI (onboard, configure, doctor).

{
  wizard: {
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local",
  },
}

journalisation¶

  • Fichier journal par dĂ©faut: /tmp/openclaw/openclaw-YYYYY-MM-DD.log
  • Si vous voulez un chemin stable, dĂ©finissez logging.file Ă  /tmp/openclaw/openclaw.log.
  • La sortie de la console peut ĂȘtre rĂ©glĂ©e sĂ©parĂ©ment via :
  • logging.consoleLevel (par dĂ©faut, info, bumps Ă  debug quand --verbose)
  • logging.consoleStyle (pretty | compact | json)
  • Les rĂ©sumĂ©s des outils peuvent ĂȘtre reproduits pour Ă©viter les fuites de secrets :
  • logging.redactSensitive (off | tools, default: tools)
  • logging.redactPatterns (tableau de chaĂźnes regex ; remplace les valeurs par dĂ©faut)
{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw. og",
    ConsoleLevel: "info",
    ConsoleStyle: "pretty",
    redactSensitive: "tools",
    redactPatterns: [
      // Exemple: remplacer les valeurs par défaut par vos propres rÚgles.
      "\\bTOKEN\\b\\s*[=:]\\s*([\"']? ([^\\s\"']+)\\1",
      "/\\bsk-[A-Za-z0-9_-]{8,}\\b/gi",
    ],
  },
}

channels.whatsapp.dmPolicy¶

ContrĂŽle la gestion des discussions directes sur WhatsApp (DMs) :

  • "appairage" (par dĂ©faut): les expĂ©diteurs inconnus obtiennent un code d'appairage ; le propriĂ©taire doit approuver
  • "allowlist": n'autoriser que les expĂ©diteurs dans channels.whatsapp.allowFrom (ou le magasin autorisĂ© par apparition)
  • "open": autorise toutes les DMs entrantes (requires channels.whatsapp.allowFrom Ă  inclure "*")
  • "dĂ©sactivĂ©": ignorer tous les MP entrants

Les codes d'appairage expirent aprĂšs 1 heure ; le bot n'envoie un code d'appairage que lorsqu'une nouvelle requĂȘte est crĂ©Ă©e. Les requĂȘtes d'appairage de DM en attente sont plafonnĂ©es Ă  3 par canal par dĂ©faut.

Approbations d'appairage :

  • liste d'appairage openclaw whatsapp
  • L'appairage openclaw approuve whatsapp <code>

channels.whatsapp.allowFrom¶

Liste des numéros de téléphone E.164 qui peuvent déclencher les réponses automatiques WhatsApp (MP seulement). Si vide et channels.whatsapp.dmPolicy="appairage", les expéditeurs inconnus recevront un code d'appairage. Pour les groupes, utilisez channels.whatsapp.groupPolicy + channels.whatsapp.groupAllowFrom.

{
  channels: {
    whatsapp: {
      dmPolicy: "appairage", // appairage | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000, // taille de chunk sortant optionnelle (caractĂšres)
      chunkMode : "length", // mode de chunking optionnel (longueur | newline)
      mediaMaxMb: 50, // capuche média entrante en option (MB)
    },
  },
}

channels.whatsapp.sendReadReadReceipts¶

ContrÎle si les messages WhatsApp entrants sont marqués comme lus (tickets bleus). Par défaut: true.

Le mode auto-chat saute toujours les reçus de lecture, mĂȘme lorsqu'il est activĂ©.

Surcharge par compte : channels.whatsapp.accounts.<id>.sendReadReadReceipts.

{
  canaux: {
    whatsapp: { sendReadReceipts: false },
  },
}

channels.whatsapp.accounts (multi-compte)¶

Exécutez plusieurs comptes WhatsApp dans une seule passerelle :

{
  channels: {
    whatsapp: {
      accouns: {
        default: {}, // optionnelle; garde l'id stable par défaut
        personal: {},
        biz: {
          // Substitution facultative. Par défaut: ~/.openclaw/credentials/whatsapp/biz
          // authDir: "~/. penclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

Notes :

  • Les commandes sortantes sont par dĂ©faut le compte default si elles sont prĂ©sentes; sinon le premier identifiant de compte configurĂ© (triĂ©).
  • L'ancien dossier d'authentification unique Baileys est migrĂ© par openclaw doctor vers whatsapp/default.

channels.telegram.accounts / channels.discord.accounts / channels.googlechat.accounts / channels.slack.accounts / channels.mattermost.accounts / channels.signal.accounts / channels.imessage.accounts¶

Exécutez plusieurs comptes par canal (chaque compte a son propre accountId et optionnel name) :

{
  channels: {
    telegram: {
      accouns: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC... ,
        },
        alertes: {
          nom: "Alertes bot",
          botToken: "987654:XYZ. .",
        },
      },
    },
  },
}

Remarques :

  • default est utilisĂ© lorsque accountId est omis (CLI + routing).
  • Les jetons d'Env ne s'appliquent qu'au compte default.
  • ParamĂštres du canal de base (politique de groupe, portail de mention etc.) s'appliquent Ă  tous les comptes sauf si surchargĂ© par compte.
  • Utilisez bindings[].match.accountId pour acheminer chaque compte vers un agents.defaults.

ClÎture de mention de groupe (agents.list[].groupChat + messages.groupChat)¶

Les messages de groupe sont par défaut require mention (soit la mention des métadonnées ou les schémas de regex ). S'applique aux discussions de groupe WhatsApp, Telegram, Discord, Google Chat et iMessage.

Types de mentions :

  • Mentions de mĂ©tadonnĂ©es : Plate-forme native @-mentions (par exemple, WhatsApp tap-to-mention). IgnorĂ© dans le mode WhatsApp auto-chat (voir channels.whatsapp.allowFrom).
  • ModĂšles de texte: ModĂšles de Regex dĂ©finis dans agents.list[].groupChat.mentionPatterns. Toujours vĂ©rifiĂ© indĂ©pendamment du mode auto-chat.
  • La mention de la barriĂšre n'est obligatoire que lorsque la dĂ©tection des mentions est possible (mentions natives ou au moins un mentionPattern).
{
  messages : {
    groupChat: { historyLimit: 50 },
  },
  agents : {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

messages.groupChat.historyLimit dĂ©finit la valeur par dĂ©faut globale pour le contexte de l'histoire du groupe. Les canaux peuvent ĂȘtre remplacĂ©s par channels.<channel>.historyLimit (ou channels.<channel>.accounts.*.historyLimit pour plusieurs comptes). DĂ©finissez 0 pour dĂ©sactiver le wrapping historique.

Limites de l'historique des DM¶

Les conversations DM utilisent un historique de session géré par l'agent. Vous pouvez limiter le nombre de tours d'utilisateurs retenus par session DM :

{
  canaux: {
    télégramme: {
      dmHistoryLimit: 30, // limite les sessions de DM Ă  30 devient
      dms: {
        "123456789": { historyLimit: 50 }, // surcharge par utilisateur (ID utilisateur)
      },
    },
  },
}

Ordre de resolution:

  1. Substitution par DM: channels.<provider>.dms[userId].historyLimit
  2. Fournisseur par défaut : channels.<provider>Limite de .dmHistory
  3. Aucune limite (tout historique retenu)

Fournisseurs supportés : telegram, whatsapp, discord, slack, signal, imessage, msteams.

Surcharge par agent (prend la prioritĂ© lorsque dĂ©fini, mĂȘme []):

{
  agents : {
    liste: [
      { id: "travail", groupChat: { mentionPatterns: ["@workbot", "\\+15555550123"] } },
      { id: "personnel", groupChat: { mentionPatterns: ["@homebot", "\\+15555550999"] } },
    ],
  },
}

Mentionnez les valeurs par défaut des gages en direct par canal (channels.whatsapp.groups, channels.telegram.groups, channels.imessage.groups, channels.discord.guilds). Lorsque *.groups est défini, il agit également comme une liste d'autorisations de groupe; inclure "*" pour autoriser tous les groupes.

Pour répondre seulement aux déclencheurs de texte spécifiques (ignorant les @-mentions natives) :

{
  channels: {
    whatsapp: {
      // Inclure votre propre numéro pour activer le mode auto-chat (ignorer les @-mentions natifs).
      permisDe: ["+15555550123"],
      groupes: { "*": { requireMention: true } },
    },
  },
  agents : {
    liste: [
      {
        id: "main",
        groupChat: {
          // Seules ces pratiques de texte déclencheront les réponses
          mentionPatterns: ["reisponde", "@openclaw"],
        },
      },
    ],
  },
}

RÚgles de groupe (par canal)¶

Utilisez channels.*.groupPolicy pour contrÎler si les messages de groupe/salle sont acceptés du tout:

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupeAllowDe: ["+15551234567"],
    },
    télégramme : {
      groupPolicy: "allowlist",
      groupAllowDe: ["tg:123456789", "@alice"],
    },
    signal: {
      groupPolicy: "allowlist",
      groupAllowDe: ["+15551234567"],
    },
    imitation : {
      groupPolicy: "allowlist",
      groupAllowDe: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["user@org. om"],
    },
    discord: {
      groupPolicy: "allowlist",
      guildes: {
        GUILD_ID: {
          canaux: { help: { allow: true } },
        },
      },
    },
    slack: {
      groupPolicy: "allowlist",
      canaux: { "#general": { allow: true } },
    },
  },
}

Notes :

  • "open": groupe de contourner les listes d'autorisations; mention-gating s'applique toujours.
  • "disabled": bloque tous les messages de groupe/salle.
  • "allowlist": n'autorise que les groupes/salles qui correspondent Ă  la liste d'autorisations configurĂ©e.
  • channels.defaults.groupPolicy dĂ©finit la valeur par dĂ©faut quand le groupPolicy d'un fournisseur est dĂ©dĂ©fini.
  • WhatsApp/Telegram/Signal/iMessage/Microsoft Teams utilisent groupAllowFrom (repli : explicite allowFrom).
  • Discord/Slack utilise des listes d'autorisations de canal (channels.discord.guilds.*.channels, channels.slack.channels).
  • Les DMs de groupe (Discord/Slack) sont toujours contrĂŽlĂ©s par dm.groupEnabled + dm.groupChannels.
  • La valeur par dĂ©faut est groupPolicy: "allowlist" (Ă  moins que channels.defaults.groupPolicy); si aucune liste d'autorisations n'est configurĂ©e, les messages de groupe sont bloquĂ©s.

Routage multi-agents (agents.list + bindings)¶

Exécutez plusieurs agents isolés (espace de travail séparé, agentDir, sessions) à l'intérieur d'une passerelle. Les messages entrants sont acheminés vers un agent via des liaisons.

  • gateway/configuration.md
  • id: id de l'agent stable (obligatoire).
  • default: optionnel; lorsque plusieurs sont dĂ©finis, le premier gagne et un avertissement est enregistrĂ©. Si aucun n'est dĂ©fini, la premiĂšre entrĂ©e dans la liste est l'agent par dĂ©faut.
  • name : affiche le nom de l'agent.
  • workspace: par dĂ©faut ~/.openclaw/workspace-<agentId> (pour main, tombe Ă  agents.defaults.workspace).
  • agentDir: default ~/.openclaw/agents/<agentId>/agent.
  • model: le modĂšle par dĂ©faut par agent remplace agents.defaults.model pour cet agent.
    • string form: "provider/model", remplace seulement agents.defaults.model.primary
    • forme de l'objet : { primary, fallbacks } (les replis remplacent agents.defaults.model.fallbacks; [] dĂ©sactive les replis globaux pour cet agent)
  • identity: nom de chaque agent / thĂšme/emoji (utilisĂ© pour les motifs de mention + rĂ©actions de ack).
  • groupChat: per-agent mention-gating (mentionPatterns).
  • sandbox: per-agent sandbox config (remplace agents.defaults.sandbox).
    • mode: "off" | "non-main" | "all"
    • workspaceAccess: "none" | "ro" | "rw"
    • scope: "session" | "agent" | "shared"
    • workspaceRoot: racine de l'espace de travail du sandbox personnalisĂ©
    • docker: le docker par agent remplace (par exemple image, network, env, setupCommand, limites; ignorĂ© quand scope: "shared")
    • browser: par agent sandboxed browser overrides (ignorĂ© lorsque scope: "shared")
    • prune: le nettoyage par agent du bac Ă  sable remplace (ignorĂ© lorsque scope: "shared")
  • sous-agents: par agent sous-agent par dĂ©faut.
    • allowAgents: autorise la liste des identifiants d'agents pour sessions_spawn de cet agent (["*"] = autorise n'importe ; par dĂ©faut: seulement le mĂȘme agent)
  • tools: restrictions par agent (appliquĂ©es avant la politique de l'outil sandbox).
    • profile: profil de l'outil de base (appliquĂ© avant autoriser/refuser)
    • allow: tableau de noms d'outils autorisĂ©s
    • niy: tableau de noms d'outils refusĂ©s (refuse gagne)
  • agents.defaults: agent partagĂ© par dĂ©faut (modĂšle, espace de travail, bac Ă  sable, etc.).
  • bindings[]: annule les messages entrants vers un agentId.
  • 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 (optional; channel-specific)

Ordre de correspondance déterministe :

  1. match.peer
  2. match.guildId
  3. match.teamId
  4. match.accountId (exact, pas de peer/guild/team)
  5. match.accountId: "*" (canal-wide, no peer/guild/team)
  6. agent par défaut (agents.list[].default, sinon premiÚre entrée de liste, sinon "main")

Dans chaque niveau de match, la premiÚre entrée correspondante dans bindings gagne.

Profils d’accĂšs par agent (multi‑agent)¶

Chaque agent peut porter sa propre politique de sandbox + outils. Utilisez ceci pour mélanger les niveaux d'accÚs dans une seule passerelle:

  • AccĂšs complet (agent personnel)
  • Outils en lecture seule + espace de travail
  • Aucun accĂšs au systĂšme de fichiers (outils de messagerie/session seulement)

Voir Sandbox & Outils multi-agents pour la priorité et des exemples supplémentaires.

AccĂšs complet (sans bac Ă  sable) :

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
    ],
  },
}

Outils en lecture seule + espace de travail en lecture seule :

{
  agents : {
    liste: [
      {
        id: "famille",
        espace de travail: "~/. penclaw/workspace-family",
        sandbox: {
          mode : "all",
          téles: "agent",
          workspaceAccess : "ro",
        },
        outils : {
          allow: [
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          : ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    ],
  },
}

Aucun accÚs au systÚme de fichiers (outils de messagerie/session activés) :

{
  agents : {
    liste: [
      {
        id: "public",
        espace de travail: "~/. penclaw/workspace-public",
        sandbox: {
          mode : "all",
          téles: "agent",
          workspaceAccess : "none",
        },
        outils : {
          allow: [
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "statut de session",
            "whatsapp",
            "télégramme",
            "slack",
            "discord",
            "passerelle",
          ],
          Ni : [
            "lu",
            "Ă©crire",
            "modifier",
            "apply_patch",
            "exec",
            "processus",
            "navigateur",
            "toile",
            "nƓuds",
            "cron",
            "passerelle",
            "image",
          ],
        },
      },
    ],
  },
}

Exemple: deux comptes WhatsApp → deux agents:

{
  agents : {
    liste: [
      { id: "maison", par défaut : true, workspace: "~/. penclaw/workspace-home" },
      { id: "work", workspace: "~/. penclaw/workspace-work" },
    ],
  },
  liaisons : [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
  salons : {
    whatsapp: {
      accouns: {
        personal: {},
        biz : {},
      },
    },
  },
}

tools.agentToAgent (facultatif)¶

La messagerie Agent-to-Agent est opt-in :

{
  tools: {
    agentToAgent: {
      activé: false,
      allow: ["home", "work"],
    },
  },
}

messages.queue¶

ContrÎle le comportement des messages entrants lorsqu'un agent est déjà actif.

{
  messages: {
    file d'attente: {
      mode : "collect", // va | suivi | collect | steer-backlog (steer+backlog ok) | interrupt (queue=legacy)
      debounceMs: 1000,
      majuscule : 20,
      drop: "résumer", // ancien | nouveau | résumé
      par Channel: {
        whatsapp: "collect",
        télégramme : "collecter",
        discord: "collecter",
        Impression : "collecter",
        webchat : "collecter",
      },
    },
  },
}

messages.inbound¶

Debouncez les messages entrants rapides du mĂȘme expĂ©diteur de sorte que les messages multiples deviennent un tour d'agent. Le debouncing est delimite par canal + conversation et utilise le message le plus recent pour le fil de reponse et les IDs.

{
  messages : {
    inbound: {
      debounceMs: 2000, // 0 désactive
      byChannel: {
        whatsapp: 5000,
        slack : 1500,
        discord: 1500,
      },
    },
  },
}

Notes :

  • Debounce batches text-only messages; media/attachments purge immĂ©diatement.
  • Les commandes de contrĂŽle (par exemple /queue, /new) contournent le dĂ©bouncement pour qu'ils restent autonomes.

commands (gestion des commandes de chat)¶

ContrÎle comment les commandes de chat sont activées entre les connecteurs.

{
  commandes: {
    natif : "auto", // registre les commandes natives lorsque supporté (auto)
    text: true, // analyse les commandes slash dans les messages de chat
    bash: false, // allow ! (alias: /bash) (HÎte seulement; nécessite des outils. listes d'autorisations levées)
    bashForegroundMs: 2000, // bash fenĂȘtre de premier plan (0 arriĂšre-plans immĂ©diatement)
    config: false, // autorise /config (Ă©crit sur le disque)
    debug: false, // autorise /debug (runtime-only overrides)
    redémarrage: false, // autorise /restart + outil de redémarrage de passerelle
    useAccessGroups: true, // force les listes d'autorisations de groupe d'accĂšs / politiques pour les commandes
  },
}

Notes :

  • Les commandes de texte doivent ĂȘtre envoyĂ©es en tant que message standalone et utiliser le / (aucun alias en texte brut).
  • commands.text: false dĂ©sactive l'analyse des messages de chat pour les commandes.
  • commands.native: "auto" (par dĂ©faut) active les commandes natives pour Discord/Telegram et laisse Slack Ă©teint ; les canaux non pris en charge ne restent que du texte.
  • DĂ©finissez commands.native: true|false pour forcer tous, ou remplacez par canal par channels.discord.commands.native, channels.telegram.commands.native, channels.slack.commands.native (bool ou "auto"). false efface les commandes prĂ©cĂ©demment enregistrĂ©es sur Discord/Telegram au dĂ©marrage; les commandes Slack sont gĂ©rĂ©es dans l'application Slack.
  • channels.telegram.customCommands ajoute des entrĂ©es de menu Telegram bot supplĂ©mentaires. Les noms sont normalisĂ©s ; les conflits avec les commandes natives sont ignorĂ©s.
  • commands.bash: true active ! <cmd> pour exĂ©cuter les commandes du shell hĂŽte (/bash <cmd> fonctionne aussi comme un alias). NĂ©cessite tools.elevated.enabled et autorise l'expĂ©diteur dans tools.elevated.allowFrom.<channel>.
  • commands.bashForegroundMs contrĂŽle combien de temps bash attend avant l'arriĂšre-plan. Pendant qu'une tĂąche de bash est en cours d'exĂ©cution, nouveau ! <cmd> les demandes sont rejetĂ©es (une Ă  la fois).
  • commands.config: true active /config (reads/writes openclaw.json).
  • canaux.<provider>.configWrites porte les mutations de configuration initiĂ©es par ce canal (par dĂ©faut : true). Ceci s'applique Ă  /config set|unset plus aux auto-migrations spĂ©cifiques au fournisseur (changements d'ID de super-groupe Telegram, changement d'ID de canal Slack).
  • commands.debug: true active /debug (overrides).
  • commands.restart: true active /restart et l'outil passerelle redĂ©marre l'action.
  • commands.useAccessGroups: false permet aux commandes de contourner les listes d'autorisations de groupe d'accĂšs/polices.
  • Les commandes slash et directives ne sont honorĂ©es que pour des expĂ©diteurs autorisĂ©s. L'autorisation est dĂ©rivĂ©e de channel allowlists/appairage plus commands.useAccessGroups.

web (Exécution du canal web WhatsApp)¶

WhatsApp passe par le canal web de la passerelle (Baileys Web). Il démarre automatiquement lorsqu'une session liée existe. Définissez web.enabled: false pour le garder désactivé par défaut.

{
  web: {
    activé: true,
    heartbeatSeconds: 60,
    reconnecté: {
      initialMs: 2000,
      maxMs : 120000,
      facteur : 1. ,
      jitter: 0. ,
      maxTentatives : 0,
    },
  },
}

channels.telegram (transport du bot)¶

OpenClaw démarre Telegram seulement quand une section de configuration channels.telegram existe. Le jeton de bot est résolu à partir de channels.telegram.botToken (ou channels.telegram.tokenFile), avec TELEGRAM_BOT_TOKEN comme secours pour le compte par défaut. Définir channels.telegram.enabled: false pour désactiver le démarrage automatique. La prise en charge des comptes multi-comptes se trouve sous channels.telegram.accounts (voir la section multi-comptes ci-dessus). Les jetons Env ne s'appliquent qu'au compte par défaut. Définissez channels.telegram.configWrites: false pour bloquer l'écriture de configuration initialisée par Telegram-initiated (incluant les migrations d'ID de supergroupe et /config set|unset).

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["tg:123456789"], // optional; "open" requires ["*"]
      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, // include last N group messages as context (0 disables)
      replyToMode: "first", // off | first | all
      linkPreview: true, // toggle outbound link previews
      streamMode: "partial", // off | partial | block (draft streaming; separate from block streaming)
      draftChunk: {
        // optional; only for streamMode=block
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph", // paragraph | newline | sentence
      },
      actions: { reactions: true, sendMessage: true }, // tool action gates (false disables)
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 5,
      retry: {
        // outbound retry policy
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        // transport overrides
        autoSelectFamily: false,
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook", // requires webhookSecret
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

Notes de streaming brouillon :

  • Utilise Telegram sendMessageDraft (bulle brouillon, pas un vrai message).
  • NĂ©cessite des sujets de chat privĂ©s (message_thread_id en DMs; le bot a activĂ© les sujets).
  • /reasoning stream envoie le raisonnement dans le brouillon, puis envoie la rĂ©ponse finale. La politique de rĂ©essai par dĂ©faut et le comportement sont documentĂ©s dans [Politique de rĂ©essai] (/concepts/retry).

channels.discord (transport du bot)¶

Configurer le bot Discord en définissant le jeton de bot et le portail facultatif : Le support multi-comptes vit sous channels.discord.accounts (voir la section multi-comptes ci-dessus). Les jetons Env ne s'appliquent qu'au compte par défaut.

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8, // clamp inbound media size
      allowBots: false, // allow bot-authored messages
      actions: {
        // tool action gates (false disables)
        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
      dm: {
        enabled: true, // disable all DMs when false
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["1234567890", "steipete"], // optional DM allowlist ("open" requires ["*"])
        groupEnabled: false, // enable group DMs
        groupChannels: ["openclaw-dm"], // optional group DM allowlist
      },
      guilds: {
        "123456789012345678": {
          // guild id (preferred) or slug
          slug: "friends-of-openclaw",
          requireMention: false, // per-guild default
          reactionNotifications: "own", // off | own | all | allowlist
          users: ["987654321098765432"], // optional per-guild user allowlist
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20, // include last N guild messages as context
      textChunkLimit: 2000, // optional outbound text chunk size (chars)
      chunkMode: "length", // optional chunking mode (length | newline)
      maxLinesPerMessage: 17, // soft max lines per message (Discord UI clipping)
      retry: {
        // outbound retry policy
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

OpenClaw dĂ©marre Discord uniquement quand une section de configuration channels.discord existe. Le jeton est rĂ©solu Ă  partir de channels.discord.token, avec DISCORD_BOT_TOKEN comme secours pour le compte par dĂ©faut (sauf si channels.discord.enabled est false). Utilisez user:<id> (DM) ou channel:<id> (canal de guilde) lorsque vous spĂ©cifiez des cibles de livraison pour les commandes cron/CLI ; les identifiants numĂ©riques nus sont ambigus et rejetĂ©s. Les identifiants de guilde sont en minuscule avec des espaces remplacĂ©s par -; les clĂ©s de canal utilisent le nom du canal slugged (aucun # en tĂȘte). PrĂ©fĂ©rez les identifiants de guilde comme des clĂ©s pour Ă©viter de renommer l'ambiguĂŻtĂ©. Les messages crĂ©Ă©s par le bot sont ignorĂ©s par dĂ©faut. Activer avec channels.discord.allowBots (les propres messages sont toujours filtrĂ©s pour Ă©viter les boucles d'auto-rĂ©ponse). Modes de notification de rĂ©action :

  • off : aucun evenement de reaction.
  • own : reactions sur les propres messages du bot (defaut).
  • all : toutes les reactions sur tous les messages.
  • allowlist : reactions provenant de guilds.<id>.users sur tous les messages (liste vide desactive). Le texte sortant est chunked par channels.discord.textChunkLimit (par dĂ©faut 2000). DĂ©finissez channels.discord.chunkMode="newline" Ă  sĂ©parer sur des lignes vides (limites du paragraphe) avant le chunking de longueur. Les clients Discord peuvent couper de trĂšs grands messages, donc channels.discord.maxLinesPerMessage (par dĂ©faut 17) divise les rĂ©ponses longues de plusieurs lignes mĂȘme si moins de 2000 caractĂšres. La politique de rĂ©essai par dĂ©faut et le comportement sont documentĂ©s dans [Politique de rĂ©essai] (/concepts/retry).

channels.googlechat (Chat API webhook)¶

Google Chat s'exécute sur des webhooks HTTP avec une authentification au niveau de l'application (compte de service). La prise en charge des comptes multi-comptes se trouve sous channels.googlechat.accounts (voir la section multi-comptes ci-dessus). Les variables Env ne s'appliquent qu'au compte par défaut.

{
  salons: {
    googlechat: {
      activé: vrai,
      serviceAccountFile: "/path/vers/service-account. son",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example. om/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // optional; améliore la détection des mentions
      dm: {
        activé: vrai,
        Politique : "appairage", // appairage | allowlist | open | disabled
        allowFrom: ["users/1234567890"], // optional; "open" requires ["*"]
      },
      groupPolicy: "allowlist",
      groupes: {
        "espaces/AAAA": { allow: true, requireMention: true },
      },
      actions : { reactions: true },
      indicateur de frappe: "message",
      mediaMaxMb: 20,
    },
  },
}

Notes :

  • Le compte de service JSON peut ĂȘtre en ligne (serviceAccount) ou basĂ© sur un fichier (serviceAccountFile).
  • Env fallbacks pour le compte par dĂ©faut : GOOGLE_CHAT_SERVICE_ACCOUNT ou GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
  • audienceType + audience doit correspondre Ă  la configuration d'authentification du webhook de l'application de Chat.
  • Utilisez spaces/<spaceId> ou users/<userId|email> lorsque vous dĂ©finissez des cibles de livraison.

channels.slack (mode socket)¶

Slack fonctionne en mode Socket et nécessite à la fois un jeton de bot et un jeton d'application:

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dm: {
        enabled: true,
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["U123", "U456", "*"], // optional; "open" requires ["*"]
        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, // include last N channel/group messages as context (0 disables)
      allowBots: false,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all
      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,
      },
      textChunkLimit: 4000,
      chunkMode: "length",
      mediaMaxMb: 20,
    },
  },
}

La prise en charge des comptes multi-comptes se trouve sous channels.slack.accounts (voir la section multi-comptes ci-dessus). Les jetons Env ne s'appliquent qu'au compte par défaut.

OpenClaw démarre Slack lorsque le fournisseur est activé et que les deux jetons sont définis (via config ou SLACK_BOT_TOKEN + SLACK_APP_TOKEN). Utilisez user:<id> (DM) ou channel:<id> lorsque vous spécifiez des cibles de livraison pour les commandes cron/CLI. Définissez channels.slack.configWrites: false pour bloquer l'écriture de la configuration Slack-initiated (y compris les migrations d'ID du canal et /config set|unset).

Les messages créés par le bot sont ignorés par défaut. Activer avec channels.slack.allowBots ou channels.slack.channels.<id>.allowBots.

Modes de notification de réaction :

  • off : aucun evenement de reaction.
  • own : reactions sur les propres messages du bot (defaut).
  • all : toutes les reactions sur tous les messages.
  • allowlist: les rĂ©actions de channels.slack.reactionAllowlist sur tous les messages (liste vide dĂ©sactive).

Isolation de la session de discussion :

  • channels.slack.thread.historyScope contrĂŽle si l'historique du thread est par thread (thread, default) ou partagĂ© sur le canal (channel).
  • channels.slack.thread.inheritParent contrĂŽle si les nouvelles sessions de thread hĂ©ritent de la transcription du canal parent (par dĂ©faut: false).

Groupes d'action Slack (actions de l'outil slack de portes):

Groupe d’actions Par dĂ©faut Remarques
reactions active React + lister les reactions
messages active Lire/envoyer/editer/supprimer
pins active Epingler/desepingler/lister
memberInfo active Informations de membres
emojiList active Liste d’emoji personnalises

channels.mattermost (jeton de bot)¶

Mattermost est distribue sous forme de plugin et n’est pas inclus dans l’installation de base. Installez d'abord : openclaw plugins install @openclaw/mattermost (ou ./extensions/mattermost depuis un checkout).

Le plus important nécessite un jeton de bot plus l'URL de base de votre serveur:

{
  channels: {
    mattermost: {
      activé: true,
      botToken: "mm-token",
      baseUrl: "https://chat. xample. om",
      dmPolicy: "appairage",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "! ],
      textChunkLimit: 4000,
      chunkMode : "length",
    },
  },
}

OpenClaw démarre le plus important lorsque le compte est configuré (jeton de bot + URL de base) et activé. Le jeton + l'URL de base sont résolus à partir de channels.mattermost.botToken + channels.mattermost.baseUrl ou MATTERMOST_BOT_TOKEN + MATTERMOST_URL pour le compte par défaut (sauf si channels.mattermost.enabled est false).

Modes de chat :

  • oncall (par dĂ©faut) : ne rĂ©pond aux messages du canal que lorsque @mentionnĂ©.
  • onmessage : repond a chaque message du canal.
  • onchar: rĂ©pond lorsqu'un message commence par un prĂ©fixe de dĂ©clenchement (channels.mattermost.oncharPrefixes, default [">", "!"]).

ContrĂŽle d'accĂšs :

  • DMs par dĂ©faut: channels.mattermost.dmPolicy="appairage" (les expĂ©diteurs inconnus obtiennent un code d'appairage).
  • Messages prives publics : channels.mattermost.dmPolicy="open" plus channels.mattermost.allowFrom=["*"].
  • Groupes : channels.mattermost.groupPolicy="allowlist" par dĂ©faut (mention-gated). Utilisez channels.mattermost.groupAllowFrom pour restreindre les expĂ©diteurs.

La prise en charge des comptes multi-comptes se trouve sous channels.mattermost.accounts (voir la section multi-comptes ci-dessus). Les variables Env ne s'appliquent qu'au compte par défaut. Utilisez channel:<id> ou user:<id> (ou @username) lorsque vous spécifiez des cibles de livraison; les identifiants natifs sont traités comme des identifiants de canal.

channels.signal (signal-cli)¶

Les réactions de signal peuvent émettre des événements systÚme (outils de réaction partagée) :

{
  channels: {
    signal: {
      reactionNotifications: "own", // off | propre | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50, // inclure les derniers N messages de groupe dans le contexte (0 désactivé)
    },
  },
}

Modes de notification de réaction :

  • off : aucun evenement de reaction.
  • own : reactions sur les propres messages du bot (defaut).
  • all : toutes les reactions sur tous les messages.
  • allowlist: les rĂ©actions de channels.signal.reactionAllowlist sur tous les messages (liste vide dĂ©sactive).

channels.imessage (imsg CLI)¶

OpenClaw fait apparaßtre imsg rpc (JSON-RPC sur stdio). Aucun démon ou port requis.

{
  salons: {
    imessage: {
      activé: vrai,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat. b",
      distantHĂŽte : "user@gateway-host", // SCP pour les piĂšces jointes distantes lors de l'utilisation du wrapper SSH
      dmPolicy: "appairage", // appairage | allowlist | open | disabled
      allowFrom: ["+15555550123", "user@example. om", "chat_id:123"],
      historyLimit: 50, // inclure les derniers N messages de groupe dans le contexte (0 désactivé)
      includeAttaches: false,
      mediaMaxMb: 16,
      service: "auto",
      région: "USA",
    },
  },
}

La prise en charge des comptes multi-comptes se trouve dans channels.imessage.accounts (voir la section multi-comptes ci-dessus).

Notes :

  • NĂ©cessite un accĂšs complet au disque dur de la base de donnĂ©es des messages.
  • Le premier envoi demandera l'autorisation d'automatiser les messages.
  • PrĂ©fĂ©rez les cibles chat_id:<id>. Utilisez imsg chats --limit 20 pour lister les chats.
  • channels.imessage.cliPath peut pointer vers un script de wrapper (par exemple ssh vers un autre Mac qui exĂ©cute imsg rpc); utilisez les clĂ©s SSH pour Ă©viter les instructions de mot de passe.
  • Pour les enveloppeurs SSH distants, dĂ©finissez channels.imessage.remoteHost pour rĂ©cupĂ©rer les piĂšces jointes via SCP lorsque includeAttachments est activĂ©.

Exemple de wrapper :

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

agents.defaults.workspace¶

Définit le répertoire de l'espace de travail global unique utilisé par l'agent pour les opérations de fichiers.

Par defaut : ~/.openclaw/workspace.

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

Si agents.defaults.sandbox est activé, les sessions non-principales peuvent remplacer cela avec leur leurs propres espaces de travail par portée sous agents.defaults.sandbox.workspaceRoot.

agents.defaults.repoRoot¶

Racine optionnelle du dĂ©pĂŽt Ă  afficher dans la ligne d'exĂ©cution de l'invite systĂšme. Si non dĂ©fini, OpenClaw tente de dĂ©tecter un rĂ©pertoire .git en marchant vers le haut depuis l'espace de travail (et le dossier de travail actuel). Le chemin doit exister pour ĂȘtre utilisĂ©.

{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
}

agents.defaults.skipBootstrap¶

Désactive la création automatique des fichiers de bootstrap de l'espace de travail (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, et BOOTSTRAP.md).

Utilisez ceci pour les dĂ©ploiements prĂ©configurĂ©s oĂč vos fichiers d'espace de travail proviennent d'un dĂ©pĂŽt.

{
  agents : { defaults: { skipBootstrap: true } },
}

agents.defaults.bootstrapMaxChars¶

Nombre maximum de caractÚres de chaque fichier de bootstrap de l'espace de travail injecté dans l'invite de systÚme avant troncation. Par défaut : 20000.

Lorsqu’un fichier dĂ©passe cette limite, OpenClaw consigne un avertissement et injecte un dĂ©but/fin tronquĂ© avec un marqueur.

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

agents.defaults.userTimezone¶

DĂ©finit le fuseau horaire de l’utilisateur pour le contexte du prompt systĂšme (pas pour les horodatages dans les enveloppes de messages). Si non dĂ©fini, OpenClaw utilise le fuseau horaire de l'hĂŽte Ă  l'exĂ©cution.

{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}

agents.defaults.timeFormat¶

ContrÎle le format horaire affiché dans la section Date et heure courante de l'invite du systÚme. Par défaut: auto (préférence de l'OS).

**Chemins absolus** : utilisĂ©s tels quels

messages¶

ContrÎle les préfixes entrants/sortants et les réactions d'ack optionnelles. Voir Messages pour la file d'attente, les sessions et le contexte de streaming.

{
  messages: {
    responsePrefix: "🩞", // ou "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
    removeAckAfterReply: false,
  },
}

responsePrefix est appliqué à toutes les réponses sortantes (résumés d'outils, bloc streaming, réponses finales) à travers les canaux sauf si déjà présents.

Les remplacements peuvent ĂȘtre configurĂ©s par canal et par compte :

  • `channels.PrĂ©fixe de rĂ©ponse
  • `channels..accounts.PrĂ©fixe de rĂ©ponse

Ordre de rĂ©solution (le plus spĂ©cifique l’emporte) :

  1. `channels..accounts.Préfixe de réponse
  2. `channels.Préfixe de réponse
  3. messages.responsePrefix

SĂ©mantiques:

  • undefined tombe au niveau suivant.
  • "" dĂ©sactive explicitement le prĂ©fixe et arrĂȘte la cascade.
  • "auto" dĂ©rive [{identity.name}] pour l'agent routĂ©.

Les remplacements s'appliquent à tous les canaux, y compris les extensions, et à chaque type de réponse sortante.

Si messages.responsePrefix est dĂ©dĂ©fini, aucun prĂ©fixe n'est appliquĂ© par dĂ©faut. Les rĂ©ponses Ă  WhatsApp auto-chat sont l'exception : elles sont par dĂ©faut [{identity.name}] lorsqu'elles sont dĂ©finies, sinon [openclaw], donc les conversations du mĂȘme tĂ©lĂ©phone restent lisibles. DĂ©finissez Ă  "auto" pour dĂ©river [{identity.name}] pour l'agent routĂ© (lorsqu'il est dĂ©fini).

Variables de modÚle¶

La chaßne responsePrefix peut inclure des variables de modÚle qui se résolvent dynamiquement :

Variable Description Exemple
{model} Nom du modĂšle court claude-opus-4-6, gpt-4o
{modelFull} Identifiant complet du modĂšle anthropique/claude-opus-4-6
{provider} Nom du fournisseur anthropique, openai
{thinkingLevel} Niveau de pensée actuel high, low, off
{identity.name} Nom d'identitĂ© de l'agent (mĂȘme que le mode "auto")

Les variables sont insensibles à la casse ({MODEL} = {model}). {think} est un alias pour {thinkingLevel}. Les variables non résolues restent en tant que texte littéral.

{
  messages : {
    responsePrefix: "[{model} | think:{thinkingLevel}]",
  },
}

Exemple de sortie: [claude-opus-4-6 | think:high] Voici ma réponse...

Le préfixe d'entrée WhatsApp est configuré via channels.whatsapp.messagePrefix (obsolÚte: messages.messagePrefix). La valeur par défaut reste inchangée: "[openclaw]" quand channels.whatsapp.allowFrom est vide, sinon "" (pas de préfixe). Lorsque vous utilisez "[openclaw]", OpenClaw utilisera à la place [{identity.name}] lorsque l'agent routé a défini identity.name.

ackReaction envoie une rĂ©action emoji du meilleur effort pour reconnaĂźtre les messages entrants sur les canaux qui supportent les rĂ©actions (Slack/Discord/Telegram/Google Chat). La valeur par dĂ©faut du identity.emoji de l'agent actif lorsqu'il est dĂ©fini, sinon "👀". DĂ©finir Ă  "" pour dĂ©sactiver.

ackReactionScope contrÎle quand les réactions se déclencheront :

  • group-mentions (par dĂ©faut) : seulement quand un groupe/salle nĂ©cessite des mentions et que le bot a Ă©tĂ© mentionnĂ©
  • group-all: tous les messages de groupe/salle
  • direct: messages directs uniquement
  • all: tous les messages

removeAckAfterReply supprime la rĂ©action d’accusĂ© de rĂ©ception du bot aprĂšs l’envoi d’une rĂ©ponse (Slack/Discord/Telegram/Google Chat uniquement). Par dĂ©faut: false.

messages.tts¶

Activer la synthÚse vocale pour les réponses sortantes. Lorsqu'activé, OpenClaw génÚre de l'audio en utilisant ElevenLabs ou OpenAI et l'attache aux réponses. Telegram utilise des notes vocales Opus ; les autres canaux envoient de l'audio MP3.

{
  messages: {
    tts: {
      auto: "toujours", // off | always | entrant | tagged
      mode : "final", // final | all (include tool/block replies)
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4. -mini",
      modĂšles: {
        enabled: true,
      },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/. penclaw/paramĂštres/tts. son",
      onze labs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api. levenlabs. o",
        voiceId : "voice_id",
        modelId: "eleven_multilingual_v2",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode : "fr",
        paramĂštres vocaux: {
          stabilité: 0. ,
          similarityBoost: 0. 5,
          style: 0. ,
          useSpeakerBoost : vrai,
          vitesse: 1. ,
        },
      },
      openai: {
        apiKey: "openai_api_key",
        modĂšle: "gpt-4o-mini-tts",
        voix: "alliage",
      },
    },
  },
}

Notes :

  • messages.tts.auto contrĂŽle auto‐TTS (off, always, inbound, tagged).
  • /tts off|toujours|inbound|tagged dĂ©finit le mode auto par session (remplace la config).
  • messages.tts.enabled est hĂ©ritĂ©; le mĂ©decin le migre vers messages.tts.auto.
  • prefsPath stocke les substitutions locales (provider/limit/summarize).
  • maxTextLength est un capuchon dur pour l'entrĂ©e TTS ; les rĂ©sumĂ©s sont tronquĂ©s pour s'adapter.
  • summaryModel remplace agents.defaults.model.primary pour auto-summary.
  • Accepte provider/model ou un alias de agents.defaults.models.
  • modelOverrides active les remplacements basĂ©s sur le modĂšle comme les balises [[tts:...]] (par dĂ©faut).
  • /tts limit et /tts summary contrĂŽlent les paramĂštres de synthĂšse par utilisateur.
  • Les valeurs apiKey reviennent Ă  ELEVENLABS_API_KEY/XI_API_KEY et OPENAI_API_KEY.
  • elevenlabs.baseUrl remplace l'URL de base de l'API ElevenLabs.
  • elevenlabs.voiceSettings supporte stability/similarityBoost/style (0..1), useSpeakerBoost, et speed (0.5..2.0).

parler¶

Par défaut pour le mode Talk (macOS/iOS/Android). Les identifiants vocaux sont remplacés par « ELEVENLABS_VOICE_ID» ou « SAG_VOICE_ID» lorsque le paramÚtre n'est pas défini. apiKey tombe à ELEVENLABS_API_KEY (ou le profil du shell de la passerelle) quand il n'est pas défini. voiceAliases permet aux directives Talk d'utiliser des noms conviviaux (par exemple "voice":"Clawd").

{
  talk: {
    voiceId: "elevenlabs_voice_id",
    voiceAliases: {
      Griffe : "EXAVITQu4vr4xnSDxMaL",
      Roger : "CwhRBWXzGAHq8TQ4Fs17",
    },
    modelId: "eleven_v3",
    outputFormat: "mp3_44100_128",
    apiKey: "elevenlabs_api_key",
    interruptOnSpeech: true,
  },
}

agents.defaults¶

ContrÎle le runtime de l'agent intégré (modÚle/pense/verbose/timeouts). agents.defaults.models définit le catalogue de modÚles configuré (et agit comme la liste d'autorisations pour /model). agents.defaults.model.primary définit le modÚle par défaut; agents.defaults.model.fallbacks sont des utilisateurs globaux. agents.defaults.imageModel est optionnel et n'est utilisé que si le modÚle principal manque d'entrée d'image. Chaque entrée agents.defaults.models peut inclure :

  • alias (raccourci du modĂšle optionnel, par exemple /opus).
  • params (des paramĂštres d'API optionnels spĂ©cifiques au fournisseur sont passĂ©s Ă  la requĂȘte du modĂšle).

params est également appliqué aux exécutions de streaming (agent embarqué + compaction). Clés supportées aujourd'hui: temperature, maxTokens. Celles-ci fusionnent avec les options de temps d'appel; les valeurs fournies par l'appelant gagnent. temperature est un bouton avancé, laisser vide à moins que vous ne connaissiez les valeurs par défaut du modÚle et que vous ayez besoin d'un changement.

Exemple :

{
  agents: {
    par défaut: {
      modĂšles: {
        "anthropic/claude-sonnet-4-5-20250929": {
          paramĂštres : { temperature: 0.6 },
        },
        "openai/gpt-5. ": {
          paramĂštres : { maxTokens: 8192 },
        },
      },
    },
  },
}

Les modÚles Z.AI GLM-4.x activent automatiquement le mode de pensée à moins que vous :

  • dĂ©finir --thinking off, ou
  • dĂ©finissez vous-mĂȘme agents.defaults.models["zai/<model>"].params.thinking.

OpenClaw fournit également quelques raccourcis d'alias intégrés. Les valeurs par défaut ne s'appliquent que lorsque le modÚle est déjà présent dans agents.defaults.models:

  • opus -> anthropic/claude-opus-4-6
  • sonnet -> anthropic/claude-sonnet-4-5
  • gpt -> openai/gpt-5.2
  • gpt-mini -> openai/gpt-5-mini
  • gemini -> google/gemini-3-pro-preview
  • gemini-flash -> google/gemini-3-flash-preview

Si vous configurez le mĂȘme nom d'alias (insensible Ă  la casse) vous-mĂȘme, votre valeur gagnera (par dĂ©faut, elle ne sera jamais remplacĂ©e).

Exemple : Opus 4.6 primaire avec MiniMax M2.1 (hébergé MiniMax) :

{
  agents: {
    par défaut: {
      modĂšles: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2. ": { alias : "minimax" },
      }, ModĂšle
      : {
        primaire : "anthropique/claude-opus-4-6",
        replis : ["minimax/MiniMax-M2. "],
      },
    },
  },
}

MiniMax auth: définir MINIMAX_API_KEY (env) ou configurer models.providers.minimax.

agents.defaults.cliBackends (CLI replié)¶

Backends CLI optionnels pour les exécutions de secours en mode texte (pas d'appels d'outils). Celles-ci sont utiles comme un chemin de sauvegarde lorsque les fournisseurs d'API échouent. Le passage de l'image est pris en charge lorsque vous configurez un imageArg qui accepte les chemins de fichier.

Notes :

  • Les backends CLI sont text-first ; les outils sont toujours dĂ©sactivĂ©s.
  • Les sessions sont prises en charge lorsque sessionArg est dĂ©fini; les identifiants de session sont persistĂ©s par backend.
  • Pour claude-cli, les valeurs par dĂ©faut sont cĂąblĂ©es. Remplacer le chemin de la commande si PATH est minimum (launchd/systemd).

Exemple :

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "mon-cli": {
          commande: "mon-cli",
          args: ["--json"],
          sortie : "json",
          modĂšle Arg: "--model",
          sessionArg: "--session",
          sessionMode : "existant",
          systemPromptArg : "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode : "répéter",
        },
      },
    },
  },
}

{
  agents: {
    par défaut: {
      modĂšles: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "anthropic/claude-sonnet-4-1": { alias: "Sonnet" },
        "openrouter/deepseek/deepseek-r1:free": {},
        "zai/glm-4. ": {
          alias : "GLM",
          paramĂštres : {
            pense: {
              type: "enabled",
              clear_thinking: false,
            },
          },
        },
      },
      modĂšle : {
        primaire : "anthropique/claude-opus-4-6",
        fallbacks: [
          "openrouter/deepseek/deepseek-r1:free",
          "openrouter/meta-llama/llama-3. -70b-instruct:gratuit",
        ],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2. -vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2. -vision flash: libre"],
      },
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      secondes de timeout: 600,
      mediaMaxMb: 5,
      heartbeat: {
        every: "30m",
        cible : "dernier",
      },
      maxConcurrent : 3,
      sous-agents : {
        model: "minimax/MiniMax-M2. ",
        maxConcurrent: 1,
        archiveAfterMinutes: 60,
      },
      exec: {
        backgroundMs: 10000,
        timeoutSec: 1800,
        nettoyageM: 1800000,
      },
      contextTokens : 200000,
    },
  },

agents.defaults.contextPruning (tool-result pruning)¶

agents.defaults.contextPruning supprime les rĂ©sultats de l'ancien outil du contexte en mĂ©moire juste avant qu'une requĂȘte ne soit envoyĂ©e au LLM. Il ne modifie pas l'historique de session sur le disque (*.jsonl reste terminĂ©).

Ceci est destiné à réduire l'utilisation de jetons pour les agents de chat qui accumulent des sorties de gros outils au fil du temps.

Niveau supérieur:

  • Ne touchez jamais les messages utilisateur/assistant.
  • ProtĂšge les derniers messages d'assistant keepLastAssistants (aucun rĂ©sultat d'outil aprĂšs que ce point soit supprimĂ©).
  • ProtĂšge le prĂ©fixe de bootstrap (rien avant que le premier message utilisateur soit effacĂ©).
  • Modes:
  • adaptive: soft-trims oversized tool results (keep head/tail) when the estimated context ratio crosses softTrimRatio. Puis hard-efface les rĂ©sultats les plus anciens outils Ă©ligibles lorsque le ratio contextuel estimĂ© traverse hardClearRatio et il y a assez de prunable tool-result bulk (minPrunableToolChars).
  • agressive: remplace toujours les rĂ©sultats des outils Ă©ligibles avant la coupure par le hardClear.placeholder (pas de vĂ©rifications de ratifs).

Soft vs hard pruning (quels changements dans le contexte envoyés au LLM):

  • Soft-trim: seulement pour les rĂ©sultats de l'outil surdimensionnĂ©s. Conserve le dĂ©but + la fin et insĂšre ... au milieu.
  • Before: toolResult("
very long output
")
  • AprĂšs: toolResult("HEAD
\n...\n
TAIL\n\n[RĂ©sultat de l'outil : 
]")
  • Hard-clear : remplace le rĂ©sultat de l'outil entier par le placeholder.
  • Before: toolResult("
very long output
")
  • AprĂšs: toolResult("[Ancien outil contenu de rĂ©sultat effacĂ©]")

Notes / Limites actuelles:

  • Les rĂ©sultats de l'outil contenant des blocs d'image sont ignorĂ©s (jamais tronquĂ©s/effacĂ©s) pour le moment.
  • Le “ratio contextuel” estimĂ© est basĂ© sur des caractĂšres (approximatifs), pas des jetons exacts.
  • Si la session ne contient pas encore au moins de messages d'assistant keepLastAssistants, la taille est ignorĂ©e.
  • En mode agressive, hardClear.enabled est ignorĂ© (les rĂ©sultats des outils Ă©ligibles sont toujours remplacĂ©s par hardClear.placeholder).

Par défaut (adaptatif) :

{
  Agents: { defaults: { contextPruning: { mode: "adaptive" } },
}

Pour désactiver:

{
  agents: { defaults: { contextPruning: { mode: "off" } },
}

Par défaut (lorsque mode est "adaptive" ou "agressive"):

  • keepLastAssistants : 3
  • softTrimRatio: 0.3 (adaptatif seulement)
  • hardClearRatio: 0.5 (adaptatif seulement)
  • minPrunableToolChars: 50000 (adaptatif seulement)
  • softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 } (adaptatif seulement)
  • hardClear : { enabled: true, placeholder: "[Old tool result content cleared]" }

Exemple (agressif, minimum) :

{
  agents: { defaults: { contextPruning: { mode: "agressive" } },
}

Exemple (ajusté adaptatif) :

{
  agents : {
    par défaut : {
      contextPruning: {
        mode : "adaptatif",
        keepLastAssistants: 3,
        softTrimRatio: 0. ,
        hardClearRatio : 0. ,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { activé: true, placeholder: "[Ancien outil contenu de résultat effacé]" },
        // Facultatif: restreindre la taille à des outils spécifiques (refuser les victoires; supporte les caractÚres génériques "*")
        outils: { deny: ["browser", "canvas"] },
      },
    },
  },
}

Voir /concepts/session-pruning pour plus de détails sur le comportement.

agents.defaults.compaction (réserve headroom + mémoire flush)¶

agents.defaults.compaction.mode sélectionne la stratégie de résumé de la compaction. Par défaut, default; définit safeguard pour activer la synthÚse des chunked pour les trÚs longues histoires. Voir /concepts/compaction.

agents.defaults.compaction.reserveTokensFloor impose une valeur minimale reserveTokens pour la compaction Pi (par défaut: 20000). Définissez-le à 0 pour désactiver le sol.

agents.defaults.compaction.memoryFlush exĂ©cute un tour agentique silencieux avant auto-compaction, instruction au modĂšle de stocker des mĂ©moires durables sur le disque (par exemple memory/YYYY-MM-DD.md). Il se dĂ©clenche lorsque l’estimation des jetons de session dĂ©passe un seuil souple infĂ©rieur Ă  la limite de compaction.

Défaut hérité :

  • memoryFlush.enabled: true
  • memoryFlush.softThresholdTokens: 4000
  • memoryFlush.prompt / memoryFlush.systemPrompt: valeurs par dĂ©faut intĂ©grĂ©es avec NO_REPLY
  • Note: la mĂ©moire vive est ignorĂ©e lorsque l'espace de travail de la session est en lecture seule (agents.defaults.sandbox.workspaceAccess: "ro" ou "none").

Exemple (ajusté) :

{
  agents: {
    par défaut : {
      compaction: {
        mode : "sauvegarde",
        réservoirTokensFloor: 24000,
        memoryFlush: {
          activé: true,
          softThresholdTokens : 6000,
          systemPrompt: "Session presque compact". Stockez des souvenirs durables.",
          : "Écrivez des notes durables Ă  la mĂ©moire/AAAA-MM-JJ. ; rĂ©pondez avec NO_REPLY si rien Ă  stocker. ,
        },
      },
    },
  },
}

Bloquer le streaming:

  • agents.defaults.blockStreamingDefault : "on"/"off" (dĂ©sactivĂ© par dĂ©faut).

  • Substitutions de canal : *.blockStreaming (et variantes par compte) pour forcer le blocage du streaming on/off. Les canaux non-Telegram nĂ©cessitent un *.blockStreaming: true explicite pour activer les rĂ©ponses de bloc.

  • agents.defaults.blockStreamingBreak: "text_end" ou "message_end" (par dĂ©faut: text_end).

  • agents.defaults.blockStreamingChunk: un chunking souple pour les blocs streamĂ©s. Par dĂ©faut, 800-1200 caractĂšres, prĂ©fĂšre les sauts de paragraphe (`\n\nA), puis les nouvelles lignes, puis les phrases. Exemple :

json5 { agents : { defaults: { blockStreamingChunk: { minChars: 800, maxChars: 1200 } } }, }

  • agents.defaults.blockStreamingCoalesce: fusionne les blocs avant l'envoi. Par dĂ©faut, { idleMs: 1000 } et hĂ©rite minChars de blockStreamingChunk avec la limite de texte de maxChars Signal/Slack/Discord/Google Chat par dĂ©faut Ă  minChars: 1500 sauf remplacement. Substitutions de canaux: channels.whatsapp.blockStreamingCoalesce, channels.telegram.blockStreamingCoalesce, channels.discord.blockStreamingCoalesce, channels.slack.blockStreamingCoalesce, channels.mattermost.blockStreamingCoalesce, channels.signal.blockStreamingCoalesce, channels.imessage.blockStreamingCoalesce, channels.msteams.blockStreamingCoalesce, channels.googlechat.blockStreamingCoalesce (et variantes de compte per).

  • agents.defaults.humanDelay: pause alĂ©atoire entre rĂ©ponses de bloc aprĂšs la premiĂšre. Modes: off (par dĂ©faut), natural (800–2500ms), custom (utilisez minMs/maxMs). Surcharge par agent : agents.list[].humanDelay. Exemple :

json5 { agents: { defaults: { humanDelay: { mode: "natural" } }, }

Voir /concepts/streaming pour plus de détails sur le comportement + le chunking.

Indicateurs d'Ă©criture :

  • agents.defaults.typingMode: "never" | "instant" | "thinking" | "message". Par dĂ©faut, instant pour les chats directs/mentions et message pour les chats de groupe non mentionnĂ©s.
  • session.typingMode: surcharge par session pour le mode.
  • agents.defaults.typingIntervalSeconds: Ă  quelle frĂ©quence le signal de saisie est actualisĂ© (par dĂ©faut: 6s).
  • session.typingIntervalSeconds: surcharge par session pour l'intervalle de rafraĂźchissement. Voir /concepts/typing-indicators pour plus de dĂ©tails sur le comportement.

agents.defaults.model.primary doit ĂȘtre dĂ©fini comme provider/model (par exemple anthropic/claude-opus-4-6). Les alias proviennent de agents.defaults.models.*.alias (par exemple Opus). Si vous omettez le fournisseur, OpenClaw assume actuellement anthropique comme un repli temporaire de la dĂ©prĂ©ciation . Les modĂšles Z.AI sont disponibles en tant que zai/<model> (par exemple zai/glm-4.7) et requiĂšrent ZAI_API_KEY (ou Z_AI_API_KEY) dans l'environnement.

agents.defaults.heartbeat configure les exécutions périodiques de pulsations cardiaques :

  • every: duration string (ms, s, m, h); default unit minutes. Par dĂ©faut: 30m. DĂ©finissez 0m pour dĂ©sactiver.
  • model: modĂšle optionnel de remplacement pour les exĂ©cutions de pulsations (provider/model).
  • includeReasoning: lorsque true, les pulsations du cƓur fourniront Ă©galement le message sĂ©parĂ© Raisoning: quand il est disponible (mĂȘme forme que /reasoning on). Par dĂ©faut: false.
  • session: clĂ© de session optionnelle pour contrĂŽler la session dans laquelle le rythme cardiaque s'exĂ©cute. Par dĂ©faut: main.
  • to : surcharge optionnelle du destinataire (id spĂ©cifique au canal, par exemple E.164 pour WhatsApp, ID de chat pour Telegram).
  • target: canal de livraison optionnel (last, whatsapp, telegram, discord, slack, msteams, signal, imessage, none). Par dĂ©faut: last.
  • prompt: surcharge optionnelle pour le corps du cƓur-beat (par dĂ©faut: Lire HEARTBEAT.md s'il existe (contexte d'espace de travail). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.). Les remplacements sont envoyĂ©s verbatim; inclure une ligne Lire HEARTBEAT.md si vous voulez toujours que le fichier soit lu.
  • ackMaxChars: max caractĂšres autorisĂ©s aprĂšs HEARTBEAT_OK avant la livraison (par dĂ©faut : 300).

Heartbeats par agent:

  • DĂ©finissez agents.list[].heartbeat pour activer ou outrepasser les paramĂštres de pulsations cardiaques pour un agent spĂ©cifique.
  • Si une entrĂ©e d'agent dĂ©finit heartbeat, only those agents run heartbeats; defaults devient la ligne de base partagĂ©e pour ces agents.

Les heartbeats exĂ©cutent des tours d’agent complets. Les intervalles plus courts brĂ»lent plus de jetons ; soyez attentif Ă  de tous, gardez petit HEARTBEAT.md et/ou choisissez un modĂšle moins cher.

tools.exec configure le fond par défaut exec :

  • backgroundMs: temps avant l'arriĂšre-plan automatique (ms, valeur par dĂ©faut 10000)
  • timeoutSec: auto-kill aprĂšs cette exĂ©cution (secondes, par dĂ©faut 1800)
  • cleanupMs: combien de temps pour conserver les sessions terminĂ©es en mĂ©moire (ms, 1800000)
  • notifyOnExit: mettre en file d'attente un Ă©vĂ©nement systĂšme + demander des pulsations cardiaques en arriĂšre-plan exec (valeur par dĂ©faut vraie)
  • applyPatch.enabled: active apply_patch expĂ©rimental (Codex OpenAI/OpenAI seulement; default false)
  • applyPatch.allowModels: optionel allowlist of model ids (e.g. gpt-5.2 or openai/gpt-5.2) Note: applyPatch is only under tools.exec.

tools.web configure la recherche web + les outils de recherche :

  • tools.web.search.enabled (par dĂ©faut : true lorsque la clĂ© est prĂ©sente)
  • tools.web.search.apiKey (recommandĂ©: dĂ©finir via openclaw configure --section web, ou utiliser BRAVE_API_KEY env var)
  • tools.web.search.maxResults (1–10, par dĂ©faut 5)
  • tools.web.search.timeoutSeconds (par dĂ©faut 30)
  • tools.web.search.cacheTtlMinutes (par dĂ©faut 15)
  • tools.web.fetch.enabled (par dĂ©faut true)
  • tools.web.fetch.maxChars (par dĂ©faut 50000)
  • tools.web.fetch.maxCharsCap (par dĂ©faut 50000; clampe maxChars des appels config/tool)
  • tools.web.fetch.timeoutSeconds (par dĂ©faut 30)
  • tools.web.fetch.cacheTtlMinutes (par dĂ©faut 15)
  • tools.web.fetch.userAgent (surcharge optionnelle)
  • tools.web.fetch.readability (par dĂ©faut true; disable to use basic HTML cleanup only)
  • tools.web.fetch.firecrawl.enabled (par dĂ©faut vrai quand une clĂ© API est dĂ©finie)
  • tools.web.fetch.firecrawl.apiKey (facultatif; par dĂ©faut FIRECRAWL_API_KEY)
  • tools.web.fetch.firecrawl.baseUrl (par dĂ©faut https://api.firecrawl.dev)
  • tools.web.fetch.firecrawl.onlyMainContent (par dĂ©faut true)
  • tools.web.fetch.firecrawl.maxAgeMs (optionnel)
  • tools.web.fetch.firecrawl.timeoutSeconds (optionnel)

tools.media configure la compréhension des médias entrants (image/audio/vidéo) :

  • tools.media.models: liste de modĂšles partagĂ©s (capability-tagged; utilisĂ©e aprĂšs les listes de capture).
  • tools.media.concurrency: capacitĂ© simultanĂ©e max exĂ©cutĂ©e (par dĂ©faut 2).
  • tools.media.image / tools.media.audio / tools.media.video :
  • enabled: opt-out switch (par dĂ©faut true lorsque les modĂšles sont configurĂ©s).
  • prompt: surcharge optionnelle de l'invite (image/vidĂ©o ajoute automatiquement un indice maxChars).
  • maxChars: nombre maximum de caractĂšres de sortie (par dĂ©faut 500 pour l'image/la vidĂ©o; annuler pour l'audio).
  • maxBytes: taille maximale du mĂ©dia Ă  envoyer (par dĂ©faut: image 10Mo, audio 20Mo, vidĂ©o 50Mo).
  • timeoutSeconds: demande de timeout (par dĂ©faut : image 60s, audio 60s, vidĂ©o 120).
  • language: indice audio optionnel.
  • attachments: politique d'attachement (mode, maxAttachments, prefer).
  • scope: portail optionnel (premier match gagne) avec match.channel, match.chatType, ou match.keyPrefix.
  • models: liste ordonnĂ©e des entrĂ©es du modĂšle; les Ă©checs ou les dĂ©passements de mĂ©dia tombent Ă  l'entrĂ©e suivante.
  • Chaque entrĂ©e models[] :
  • EntrĂ©e du fournisseur (type: "provider" ou omisĂ©) :
    • provider: ID de fournisseur API (openai, anthropic, google/gemini, groq, etc).
    • model: remplacement de l'id du modĂšle (requis pour l'image; valeur par dĂ©faut Ă  gpt-4o-mini-transcribe/whisper-large-v3-turbo pour les fournisseurs audio, et gemini-3-flash-preview pour la vidĂ©o).
    • profile / preferredProfile: sĂ©lection du profil d'authentification.
  • EntrĂ©e CLI (type: "cli"):
    • commande: exĂ©cutable Ă  exĂ©cuter.
    • args: gabarit args (supporte {{MediaPath}}, {{Prompt}}, {{MaxChars}}, etc).
  • capabilities: liste optionnelle (image, audio, video) pour ouvrir une entrĂ©e partagĂ©e. DĂ©faut quand omis : openai/anthropic/minimax → image, google → image+audio+video, groq → audio.
  • prompt, maxChars, maxBytes, timeoutSeconds, language peuvent ĂȘtre remplacĂ©s par entrĂ©e.

Si aucun modÚle n'est configuré (ou activé: false), la compréhension est ignorée; le modÚle reçoit toujours les piÚces jointes originales.

L'authentification du fournisseur suit l'ordre d'authentification standard des modĂšles (profils d'authentification, env vars comme OPENAI_API_KEY/GROQ_API_KEY/GEMINI_API_KEY, ou models.providers.*.apiKey).

Exemple :

{
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        scope: {
          default: "deny",
          rules: [{ action: "allow", match: { chatType: "direct" } }],
        },
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] },
        ],
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },
}

agents.defaults.subagents configure les valeurs par défaut des sous-agents :

  • model: modĂšle par dĂ©faut pour les sous-agents apparus (chaĂźne de caractĂšres ou { primary, fallbacks }). En cas d'omission, les sous-agents hĂ©ritent du modĂšle de l'appelant Ă  moins d'ĂȘtre remplacĂ©s par agent ou par appel.
  • maxConcurrent: nombre maximum de sous-agents simultanĂ©s exĂ©cutĂ©s (par dĂ©faut 1)
  • archiveAfterMinutes: archiver automatiquement les sessions de sous-agents aprĂšs N minutes (par dĂ©faut 60; dĂ©finir 0 pour dĂ©sactiver)
  • RĂšgle de l'outil par sous-agent : tools.subagents.tools.allow / tools.subagents.tools.deny (deny wins)

tools.profile définit un outil de base allowlist avant tools.allow/tools.deny:

  • minimal : session_status uniquement
  • coding : group:fs, group:runtime, group:sessions, group:memory, image
  • messaging : group:messaging, sessions_list, sessions_history, sessions_send, session_status
  • full : aucune restriction (identique Ă  non dĂ©fini)

Surcharge par agent : agents.list[].tools.profile.

Exemple (messagerie uniquement par défaut, autoriser aussi les outils Slack + Discord) :

{
  tools: {
    profile: "messaging",
    allow: ["slack", "discord"],
  },
}

Exemple (profil de codage, mais interdire exec/process partout) :

{
  tools: {
    profile: "coding",
    deny: ["group:runtime"],
  },
}

tools.byProvider vous permet de restreindre les outils pour des fournisseurs spécifiques (ou un seul provider/model). Surcharge par agent : agents.list[].tools.byProvider.

Commande : profil de base → profil du fournisseur → autoriser/refuser les politiques. Les clĂ©s du fournisseur acceptent soit provider (par exemple google-antigravity) soit provider/model (par exemple openai/gpt-5.2).

Exemple (conserver le profil de codage global, mais outils minimaux pour Google Antigravity) :

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}

Exemple (liste d'autorisations spécifique au fournisseur/modÚle) :

{
  tools: {
    allow: ["group:fs", "group:runtime", "sessions_list"],
    byProvider: {
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

tools.allow / tools.deny configure un outil global autoriser/deny policy (deny wins). La correspondance est insensible Ă  la casse et supporte les caractĂšres gĂ©nĂ©riques * ("*" signifie tous les outils). Ceci est appliquĂ© mĂȘme lorsque le sandbox Docker est dĂ©sactivĂ©.

Exemple (désactiver le navigateur/canvas partout):

{
  tools: { deny: ["browser", "canvas"] },
}

Les groupes d’outils (raccourcis) fonctionnent dans les politiques d’outils global et par agent :

  • group:runtime : exec, bash, process
  • group:fs : read, write, edit, apply_patch
  • group:sessions : sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
  • group:memory : memory_search, memory_get
  • group:web : web_search, web_fetch
  • group:ui : browser, canvas
  • group:automation : cron, gateway
  • group:messaging : message
  • group:nodes : nodes
  • group:openclaw : tous les outils OpenClaw intĂ©grĂ©s (exclut les plugins de fournisseurs)

tools.elevated contrÎle l'accÚs exec élevé (host) :

  • enabled : autorise le mode Ă©levĂ© (par dĂ©faut true)
  • allowFrom: per-channel allowlists (vide = dĂ©sactivĂ©)
  • whatsapp: nombre E.164
  • telegram : ID de chat ou nom d'utilisateur
  • discord: les identifiants des utilisateurs ou les noms d'utilisateur (tombe Ă  channels.discord.dm.allowFrom si omis)
  • signal: nombre E.164
  • imessage: gestion/ID de chat
  • webchat: ID de session ou nom d'utilisateur

Exemple :

{
  outils: {
    élévé: {
      activé: vrai,
      allowDe: {
        whatsapp: ["+155550123"],
        discord: ["steipete", "1234567890123"],
      },
    },
  },
}

Surcharge par agent (restriction supplémentaire):

{
  agents : {
    liste: [
      {
        id: "famille", Outils
        : {
          élevés : { enabled: false },
        },
      },
    ],
  },
}

Notes :

  • tools.elevated est la ligne de base globale. agents.list[].tools.elevated ne peut que restreindre davantage (les deux doivent autoriser).
  • /elevated on|off|ask|full stocke l'Ă©tat par clĂ© de session; les directives en ligne s'appliquent Ă  un seul message.
  • exec Ă©levĂ© fonctionne sur l'hĂŽte et contourne la sandboxing.
  • La politique des outils s'applique toujours; si exec est refusĂ©, il est impossible d'utiliser une politique Ă©levĂ©e.

agents.defaults.maxConcurrent définit le nombre maximum d'exécutions d'agents embarqués qui peuvent exécuter en parallÚle entre les sessions. Chaque session est toujours sérialisée (une fois exécutée par clé de session à la fois). Defaut : 1.

agents.defaults.sandbox¶

Optionnel sandboxing Docker pour l'agent embarqué. Destiné aux sessions non principales, elles ne peuvent donc pas accéder à votre systÚme hÎte.

DĂ©tails: Sandboxing

Par défaut (si activé) :

  • scope: "agent" (un conteneur + espace de travail par agent)
  • Image basĂ©e sur Debian bookworm-slim
  • agent workspace access: workspaceAccess: "none" (par dĂ©faut)
  • "none": utilise un espace de travail sandbox par portĂ©e sous ~/.openclaw/sandboxes
  • "ro": garde l'espace de travail sandbox Ă  /workspace, et monte l'espace de travail de l'agent en lecture seule Ă  /agent (dĂ©sactive write/edit/apply_patch)
  • "rw": monte l'espace de travail de l'agent en lecture/Ă©criture dans /workspace
  • auto-prune : inactif > 24 h OU Ăąge > 7 j
  • tool policy: allow only exec, process, read, write, edit, apply_patch, sessions_list, sessions_history, sessions_send, sessions_spawn, session_status (deny wins)
  • configurer via tools.sandbox.tools, remplacer par agent via agents.list[].tools.sandbox.tools
  • les groupes d'outils supportĂ©s dans la politique sandbox : group:runtime, group:fs, group:sessions, group:memory (voir Sandbox vs Tool Policy vs Elevated)
  • navigateur en boĂźte Ă  sable optionnel (Chromium + CDP, observateur noVNC)
  • boutons de durcissement : network, user, pidsLimit, memory, cpus, ulimits, seccompProfile, apparmorProfile

Attention: scope: "shared" signifie un conteneur partagĂ© et un espace de travail partagĂ©. Aucune isolation inter‑session. Utilisez scope: "session" pour l'isolement par session.

Legacy: perSession est toujours supportĂ© (true → scope: "session", false → scope: "shared").

setupCommand s'exécute une fois aprÚs que le conteneur soit créé (à l'intérieur du conteneur via sh -lc). Pour les installations de paquets, assurez-vous que le réseau est égal, un systÚme de gestion des droits en écriture et un utilisateur root.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent is default)
        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",
          // Per-agent override (multi-agent): agents.list[].sandbox.docker.*
          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: ["/var/run/docker.sock:/var/run/docker.sock", "/home/user/source:/source:rw"],
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          containerPrefix: "openclaw-sbx-browser-",
          cdpPort: 9222,
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          allowedControlUrls: ["http://10.0.0.42:18791"],
          allowedControlHosts: ["browser.lab.local", "10.0.0.42"],
          allowedControlPorts: [18791],
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24, // 0 disables idle pruning
          maxAgeDays: 7, // 0 disables max-age pruning
        },
      },
    },
  },
  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"],
      },
    },
  },
}

Construire l'image du sandbox par défaut une fois avec:

scripts/sandbox-setup.sh

Note: Les conteneurs sandbox sont par défaut network: "none"; définissez agents.defaults.sandbox.docker.network à "bridge" (ou votre réseau personnalisé) si l'agent a besoin d'un accÚs sortant.

Note: les piĂšces jointes entrantes sont mises en scĂšne dans l'espace de travail actif Ă  media/inbound/*. Avec workspaceAccess: "rw", cela signifie que les fichiers sont Ă©crits dans l'espace de travail de l'agent.

Note : docker.binds monte des répertoires d'hÎtes supplémentaires ; les liaisons globales et par agent sont fusionnées.

Construire l'image optionnelle du navigateur avec:

scripts/sandbox-browser-setup.sh

Lorsque agents.defaults.sandbox.browser.enabled=true, l'outil du navigateur utilise une instance de sandboxed Chromium (CDP). Si noVNC est activé (par défaut quand headless=false), l'URL noVNC est injectée dans l'invite systÚme pour que l'agent puisse la référentier. Cela ne nécessite pas browser.enabled dans la configuration principale; l'URL de contrÎle de bac à sable est injectée par session.

agents.defaults.sandbox.browser.allowHostControl (par défaut: false) permet à sandboxed sessions de cibler explicitement le host browser control server via l'outil navigateur (target: "host"). Laissez cette option désactivée si vous voulez une isolation stricte du bac à sable stricte.

Listes d'autorisations pour le contrĂŽle Ă  distance :

  • allowedControlUrls: URL de contrĂŽle exacte permise pour target: "custom".
  • allowedControlHosts: noms d'hĂŽtes autorisĂ©s (nom d'hĂŽte seulement, aucun port).
  • allowedControlPorts: ports autorisĂ©s (par dĂ©faut: http=80, https=443). Par dĂ©faut : toutes les listes d'autorisations sont non dĂ©finies (aucune restriction). allowHostControl est par dĂ©faut Ă  false.

models (fournisseurs personnalisés + URL de base)¶

OpenClaw utilise le modĂšle pi-coding-agent. Vous pouvez ajouter des fournisseurs personnalisĂ©s (LiteLLM, serveurs compatibles avec OpenAI, proxy Anthropique, etc.) en Ă©crivant ~/.openclaw/agents/<agentId>/agent/models.json ou en dĂ©finissant le mĂȘme schĂ©ma dans votre configuration OpenClaw sous models.providers. Aperçu du fournisseur par fournisseur + exemples : /concepts/model-providers.

Lorsque models.providers est présent, OpenClaw écrit / fusionne un models.json en ~/.openclaw/agents/<agentId>/agent/ au démarrage :

  • comportement par dĂ©faut : fusion (conserve les fournisseurs existants, remplace le nom)
  • dĂ©finir models.mode: "replace" pour Ă©craser le contenu du fichier

SĂ©lectionnez le modĂšle via agents.defaults.model.primary (provider/model).

{
  agents: {
    defaults: {
      model: { primary: "custom-proxy/llama-3. -8b" },
      modĂšles: {
        "custom-proxy/llama-3. -8b : {},
      },
    },
  }, ModĂšles
  : mode {
    : "fusion",
    Fournisseurs : {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey : "LITELLM_KEY",
        api : "openai-completions",
        modĂšles: [
          {
            id: "llama-3. -8b",
            nom: "Llama 3. 8B",
            raisonnement : faux, Entrée
            : ["texte"],
            coût : { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            fenĂȘtre contextuelle: 128000,
            maxTokens : 32000,
          },
        ],
      },
    },
  },
}

OpenCode Zen (proxy multi-modÚles)¶

OpenCode Zen est une passerelle multi-modÚles avec des points de terminaison par modÚle. OpenClaw utilise le fournisseur intégré opencode de pi-ai; définissez OPENCODE_API_KEY (ou OPENCODE_ZEN_API_KEY) de https://opencode.ai/auth.

Notes :

  • Les modĂšles utilisent opencode/<modelId> (exemple: opencode/claude-opus-4-6).
  • Si vous activez une liste d'autorisations via agents.defaults.models, ajoutez chaque modĂšle que vous prĂ©voyez utiliser.
  • Raccourci : openclaw Ă  la carte --auth-choice opencode-zen.
{
  agents: {
    par défaut: {
      model: { primary: "opencode/claude-opus-4-6" },
      modĂšles: { "opencode/claude-opus-4-6": { alias: "Opus" } },
    },
  },
}

Z.AI (GLM-4.7) — support des alias du fournisseur¶

Les modÚles Z.AI sont disponibles via le fournisseur intégré zai. Définissez ZAI_API_KEY dans votre environnement et référencez le modÚle par fournisseur/modÚle.

Raccourci : openclaw Ă  la carte --auth-choice zai-api-key.

{
  agents: {
    par défaut: {
      model: { primary: "zai/glm-4.7" },
      models: { "zai/glm-4.7": {} },
    },
  },
}

Notes :

  • z.ai/* et z-ai/* sont des alias acceptĂ©s et se normalisent en zai/*.
  • Si ZAI_API_KEY est manquant, les requĂȘtes vers zai/* Ă©choueront avec une erreur d'authentification au moment de l'exĂ©cution.
  • Erreur d'exemple : Aucune clĂ© API trouvĂ©e pour le fournisseur "zai".
  • Le point de terminaison gĂ©nĂ©ral de l'API de Z.AI est https://api.z.ai/api/paas/v4. Les requĂȘtes de codage GLM utilisent le point de terminaison dĂ©diĂ© https://api.z.ai/api/coding/paas/v4. Le fournisseur intĂ©grĂ© zai utilise le point de terminaison de Codage. Si vous avez besoin de l'extrĂ©mitĂ© gĂ©nĂ©rale , dĂ©finissez un fournisseur personnalisĂ© dans models.providers avec la substitution de l'URL de base (voir la section des fournisseurs personnalisĂ©s ci-dessus).
  • Utilisez un faux placeholder dans les docs/configs ; ne commettez jamais de vraies clĂ©s d'API.

Moonshot AI (Kimi)¶

Utiliser le point de terminaison compatible OpenAI de Moonshot:

{
  env: { MOONSHOT_API_KEY: "sk-... },
  agents: {
    defaults: {
      model: { primary: "moonshot/kimi-k2. " },
      modĂšles: { "lune/kimi-k2. ": { alias: "Kimi K2. " } },
    },
  },
  modĂšles: {
    mode : "fusion",
    Fournisseurs : {
      lune: {
        baseUrl: "https://api. oonshot. i/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        modĂšles: [
          {
            id: "kimi-k2. ",
            nom: "Kimi K2. ",
            raisonnement : faux, Entrée
            : ["texte"],
            coût : { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextFenĂȘtre : 256000,
            maxTokens : 8192,
          },
        ],
      },
    },
  },
}

Notes :

  • DĂ©finissez MOONSHOT_API_KEY dans l'environnement ou utilisez openclaw Ă  bord --auth-choice moonshot-api-key.
  • ModĂšle ref: moonshot/kimi-k2.5.
  • Pour le point de terminaison de la Chine:
  • ExĂ©cutez openclaw Ă  la carte --auth-choice moonshot-api-key-cn (l'assistant va dĂ©finir https://api.moonshot.cn/v1), ou
  • DĂ©finissez manuellement baseUrl: "https://api.moonshot.cn/v1" dans models.providers.moonshot.

Kimi Coding¶

Utiliser le point de terminaison du codage Kimi de Moonshot AI (fournisseur intégré et compatible Anthropique) :

{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "kimi-coding/k2p5" },
      models: { "kimi-coding/k2p5": { alias: "Kimi K2.5" } },
    },
  },
}

Notes :

  • DĂ©finissez KIMI_API_KEY dans l'environnement ou utilisez openclaw Ă  bord --auth-choice kimi-code-api-key.
  • ModĂšle ref: kimi-coding/k2p5.

Synthétique (compatible Anthropique)¶

Utiliser le point de terminaison Anthropique du synthétique:

{
  env: { SYNTHETIC_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.1" },
      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.1": { alias: "MiniMax M2.1" } },
    },
  },
  models: {
    mode: "merge",
    providers: {
      synthetic: {
        baseUrl: "https://api.synthetic.new/anthropic",
        apiKey: "${SYNTHETIC_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "hf:MiniMaxAI/MiniMax-M2.1",
            name: "MiniMax M2.1",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 192000,
            maxTokens: 65536,
          },
        ],
      },
    },
  },
}

Notes :

  • DĂ©finissez SYNTHETIC_API_KEY ou utilisez openclaw Ă  bord --auth-choice synthetic-api-key.
  • ModĂšle ref: synthĂ©tique/hf:MiniMaxAI/MiniMax-M2.1.
  • L'URL de base devrait omettre /v1 car le client anthropique l'ajoute.

ModĂšles locaux (LM Studio) — Configuration recommandĂ©e¶

Voir /gateway/local-models pour les conseils locaux actuels. TL;DR: exécutez MiniMax M2.1 via LM Studio Responses API sur un matériel sérieux; gardez les modÚles hébergés fusionnés pour une solution de repli.

MiniMax M2.1¶

Utiliser MiniMax M2.1 directement sans LM Studio :

{
  agent: {
    model: { primary: "minimax/MiniMax-M2. " },
    modĂšles: {
      "anthropique/claude-opus-4-6": { alias: "Opus" },
      "minimax/MiniMax-M2. ": { alias: "Minimax" },
    },
  }, ModĂšles
  : mode {
    : "fusion",
    Fournisseurs : {
      minimax: {
        baseUrl: "https://api. inimax. o/anthropique",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropique-messages",
        modĂšles: [
          {
            id: "MiniMax-M2. ",
            nom: "MiniMax M2. ",
            raisonnement : faux, Entrée
            : ["texte"],
            // Tarif: mise à jour dans les modÚles. si vous avez besoin d'un suivi exact des coûts.
            coût: { input: 15, output: 60, cacheRead: 2, cacheWrite: 10 },
            contextWindow: 200000,
            maxTokens : 8192,
          },
        ],
      },
    },
  },
}

Notes :

  • DĂ©finissez la variable d'environnement MINIMAX_API_KEY ou utilisez openclaw Ă  bord --auth-choice minimax-api.
  • ModĂšle disponible: MiniMax-M2.1 (par dĂ©faut).
  • Mettre Ă  jour les prix dans models.json si vous avez besoin de suivi exact des coĂ»ts.

Cérébraux (GLM 4.6 / 4.7)¶

Utilisez Cerebras via leur point de terminaison compatible OpenAI:

{
  env: { CEREBRAS_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: {
        primary: "cerebras/zai-glm-4.7",
        fallbacks: ["cerebras/zai-glm-4.6"],
      },
      models: {
        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
        "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (Cerebras)" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      cerebras: {
        baseUrl: "https://api.cerebras.ai/v1",
        apiKey: "${CEREBRAS_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },
          { id: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" },
        ],
      },
    },
  },
}

Notes :

  • Utilisez cerebras/zai-glm-4.7 pour Cerebras; utilisez zai/glm-4.7 pour Z.AI direct.
  • DĂ©finissez CEREBRAS_API_KEY dans l'environnement ou la configuration.

Notes :

  • APIs supportĂ©s : openai-completions, openai-respones, anthropic-messages, google-generative-ai
  • Utilisez authHeader: true + headers pour des besoins d'authentification personnalisĂ©s.
  • Remplacer la configuration root de l'agent avec OPENCLAW_AGENT_DIR (ou PI_CODING_AGENT_DIR) si vous voulez models.json stockĂ©s ailleurs (par dĂ©faut: ~/.openclaw/agents/main/agent).

session¶

ContrĂŽle la portĂ©e de la session, la politique de rĂ©initialisation, les dĂ©clencheurs de rĂ©initialisation et le lieu oĂč la boutique de session est Ă©crite.

{
  session: {
    scope: "per-sender",
    dmScope: "main",
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    // Default is already per-agent under ~/.openclaw/agents/<agentId>/sessions/sessions.json
    // You can override with {agentId} templating:
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    // Direct chats collapse to agent:<agentId>:<mainKey> (default: "main").
    mainKey: "main",
    agentToAgent: {
      // Max ping-pong reply turns between requester/target (0–5).
      maxPingPongTurns: 5,
    },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

Champs :

  • mainKey: clĂ© bucket direct-chat (par dĂ©faut: "main"). Utile lorsque vous voulez « renommer » le fil principal du DM sans changer « agentId ».
  • Note Sandbox : agents.defaults.sandbox.mode: "non-main" utilise cette clĂ© pour dĂ©tecter la session principale. N'importe quelle clĂ© de session qui ne correspond pas Ă  mainKey (groups/canaux) est en bac Ă  sable.
  • dmScope: comment les sessions DM sont regroupĂ©es (par dĂ©faut: "main").
  • main: tous les DMs partagent la session principale pour la continuitĂ©.
  • per-peer: isoler les DMs par l'id de l'expĂ©diteur Ă  travers les canaux.
  • per-channel-peer: isoler les DMs par canal + expĂ©diteur (recommandĂ© pour les boĂźtes de rĂ©ception multi-utilisateurs).
  • per-account-channel-peer: isoler les DMs par compte + canal + expĂ©diteur (recommandĂ© pour les boĂźtes de rĂ©ception multi-comptes).
  • Mode DM sĂ©curisĂ© (recommandĂ©) : dĂ©finir session.dmScope: "per-channel-peer" lorsque plusieurs personnes peuvent DM le bot (boĂźtes de rĂ©ception partagĂ©es, listes d'autorisations multi-personnes ou dmPolicy: "open").
  • identityLinks: mapper les identifiants canoniques aux pairs prĂ©fixĂ©s par le fournisseur afin que la mĂȘme personne partage une session DM Ă  travers les canaux lors de l'utilisation de per-peer, per-channel-peer, ou per-account-channel-peer.
  • Exemple: alice: ["telegram:123456789", "discord:987654321012345678"].
  • reset: politique de rĂ©initialisation primaire. La valeur par dĂ©faut de rĂ©initialisation quotidienne Ă  4:00 heure locale sur l'hĂŽte de la passerelle.
  • mode: daily ou idle (par dĂ©faut: daily quand reset est prĂ©sent).
  • atHour: heure locale (0-23) pour la limite quotidienne de rĂ©initialisation.
  • idleMinutes: glisser la fenĂȘtre inactive en quelques minutes. Lorsque quotidien + inactivite sont tous deux configures, celui qui expire en premier l’emporte.
  • resetByType: per-session overrides for direct, group, and thread. Legacy dm key is accepted as an alias for direct.
  • Si vous ne dĂ©finissez que les anciens session.idleMinutes sans aucun reset/resetByType, OpenClaw reste en mode idle-only pour une compatibilitĂ© ascendante.
  • heartbeatIdleMinutes: option de remplacement inactif pour les tests de pulsations cardiaques (rĂ©initialisation quotidienne s'applique toujours quand activĂ©).
  • agentToAgent.maxPingPongTurns: max reply-back turns between requester/target (0–5, default 5).
  • sendPolicy.default: allow ou deny quand aucune rĂšgle ne correspond.
  • sendPolicy.rules[]: correspond par channel, chatType (direct|group|room), ou keyPrefix (par exemple cron:). Premier refus gagne; sinon autoriser.

skills (configuration des compétences)¶

ContrÎle la liste d'autorisations groupée, les préférences d'installation, les dossiers de compétences supplémentaires et les dérogations par compétence . S'applique aux compétences groupées et ~/.openclaw/skills (compétences de l'espace de travail gagnent toujours en conflit de noms).

Champs :

  • allowBundled : liste blanche optionnelle pour les skills intĂ©grĂ©es uniquement. S’il est dĂ©fini, seules ces compĂ©tences groupĂ©es sont Ă©ligibles (les compĂ©tences gĂ©rĂ©es/de l’espace de travail ne sont pas affectĂ©es).
  • load.extraDirs : rĂ©pertoires de Skills supplĂ©mentaires Ă  analyser (prioritĂ© la plus basse).
  • install.preferBrew : privilĂ©gier les installateurs brew lorsqu’ils sont disponibles (par dĂ©faut : true).
  • install.nodeManager: prĂ©fĂ©rence de l'installateur de node (npm | pnpm | yarn, default: npm).
  • entries.<skillKey>: substitutions de configuration par compĂ©tence.

Champs par Skill :

  • enabled : dĂ©finir false pour dĂ©sactiver un Skill mĂȘme s’il est fourni/installĂ©.
  • env : variables d’environnement injectĂ©es pour l’exĂ©cution de l’agent (uniquement si elles ne sont pas dĂ©jĂ  dĂ©finies).
  • apiKey : commoditĂ© optionnelle pour les compĂ©tences qui dĂ©clarent une var env primaire (par exemple nano-banane pro → GEMINI_API_KEY).

Exemple :

{
  compétences: {
    allowBundled: ["gemini", "peekaboo"],
    charge: {
      extraDirs: ["~/Projects/agent-scripts/skills", "~/Projets/oss/some-skill-pack/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager : "npm",
    },
    entrées : {
      "nano-banana-pro": {
        apiKey: "GEMINI_KEY_HERE",
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
      },
      peekaboo: { enabled: true },
      Su : { enabled: false },
    },
  },
}

plugins (extensions)¶

ContrÎle la découverte de plugins, autoriser/refuser et la configuration par plugin. Les plugins sont chargés depuis ~/.openclaw/extensions, <workspace>/.openclaw/extensions, plus toutes les entrées plugins.load.paths. Les modifications de configuration nécessitent un redémarrage de la passerelle. Voir /plugin pour une utilisation complÚte.

Champs :

  • enabled: bascule maĂźtre pour le chargement du plugin (par dĂ©faut: true).
  • allow: option allowlist des identifiants de plugins; lorsque dĂ©fini, seul le chargement des plugins est listĂ©.
  • niy: refus optionnel des identifiants de plugins (refus de gagne).
  • load.paths: fichiers ou rĂ©pertoires supplĂ©mentaires Ă  charger (absolus ou ~).
  • entrĂ©es.<pluginId>: surcharge par plugin.
  • enabled: dĂ©finit false pour dĂ©sactiver.
  • config : objet de configuration spĂ©cifique au plugin (validĂ© par le plugin si fourni).

Exemple :

{
  plugins: {
    activé: true,
    allow: ["appel vocal"],
    charge: {
      chemins: ["~/Projects/oss/voice-call-extension"],
    },
    entrées : {
      "appel vocal" : {
        activé : vrai,
        config: {
          provider: "twilio",
        },
      },
    },
  },
}

browser (navigateur géré par openclaw)¶

OpenClaw peut dĂ©marrer une instance dĂ©diĂ©e, isolĂ©e Chrome/Brave/Edge/Chromium pour openclaw et exposer un petit service de contrĂŽle de bouclage. Les profils peuvent pointer vers un navigateur distant basĂ© sur Chromium via profils.<name>.cdpUrl. Les profils distants sont en piĂšces jointes uniquement (dĂ©marrer/arrĂȘter/rĂ©initialiser sont dĂ©sactivĂ©s).

browser.cdpUrl reste prĂ©sent pour les configurations mono‑profil hĂ©ritĂ©es et comme schĂ©ma/hĂŽte de base pour les profils qui ne dĂ©finissent que cdpPort.

Variables d’environnement + .env

  • activĂ©: true
  • evaluateEnabled: true (dĂ©finir false pour dĂ©sactiver act:evaluate et wait --fn)
  • service de contrĂŽle : loopback uniquement (port dĂ©rivĂ© de gateway.port, valeur par dĂ©faut 18791)
  • URL CDP: http://127.0.0.1:18792 (service de contrĂŽle + 1, profil unique hĂ©ritĂ©)
  • couleur du profil: #FF4500 (lobster-orange)
  • Note: le serveur de contrĂŽle est dĂ©marrĂ© par la passerelle en cours d'exĂ©cution (barre de menus OpenClaw.app ou passerelle openclaw).
  • Ordre de dĂ©tection automatique : navigateur par dĂ©faut si basĂ© sur Chromium ; sinon Chrome → Brave → Bord → Chromium → Canary Chrome.
{
  browser: {
    activé: vrai,
    evaluateEnabled: true,
    // cdpUrl: "http://127. 0.0. :18792", // héritage mono-profil surcharge
    defaultProfile: "chrome",
    profils : {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      fonctionne: { cdpPort: 18801, color: "#0066CC" },
      distante : { cdpUrl: "http://10. .0.42:9222", couleur: "#00AA00" },
    },
    couleur: "#FF4500",
    // Avancé:
    // sans tĂȘte: false,
    // noSandbox: false,
    // executablePath: "/Applications/Brave Browser. pp/Contents/MacOS/Brave Browser",
    // attachSeulement: false, // définit vrai lors du tunneling d'un CDP distant sur localhost
  },
}

ui (Apparence)¶

Couleur d'accentuation optionnelle utilisée par les applications natives pour le chrome de l'interface (ex: teinte de bulle Mode Talk).

Si non défini, les clients retombent à un bleu clair mis en sourdine.

{
  ui: {
    couture Color: "#FF4500", // hexadécimal (RRGGBB ou #RRGGBB)
    // Optionnel: ContrÎle de l'assistant d'identité de l'interface utilisateur.
    // Si non défini, l'interface de contrÎle utilise l'identité de l'agent actif (config ou IDENTITY. d).
    assistant : {
      name : "OpenClaw",
      avatar : "CB", // emoji, texte court, ou URI URI
    },
  },
}

passerelle (mode serveur Gateway + lier)¶

Utilisez gateway.mode pour déclarer explicitement si cette machine doit exécuter la passerelle.

Équivalent en variable d’environnement :

  • mode : unset (traitĂ© comme “ne pas dĂ©marrer automatique”)
  • bind: loopback
  • port: 18789 (port unique pour WS + HTTP)
{
  gateway: {
    mode : "local", // ou "remote"
    port: 18789, // WS + HTTP multiplex
    bind: "loopback",
    // controlUi: { enabled: true, basePath: "/openclaw" }
    // auth: { mode: "token", token: "votre-jeton" } // portes de jeton WS + Control UI access
    // tailscale: { mode: "off" | "serve" | "funnel" }
  },
}

ContrĂŽler le chemin de base de l'interface :

  • gateway.controlUi.basePath dĂ©finit le prĂ©fixe d'URL oĂč l'interface de contrĂŽle est servie.
  • Exemples: "/ui", "/openclaw", "/apps/openclaw".
  • Par dĂ©faut: root (/) (inchangĂ©).
  • gateway.controlUi.root dĂ©finit la racine du systĂšme de fichiers pour les assets de Control UI (par dĂ©faut: dist/control-ui).
  • gateway.controlUi.allowInsecureAuth autorise une authentification par jeton uniquement pour l’UI de contrĂŽle lorsque l’identitĂ© de l’appareil est omise (gĂ©nĂ©ralement via HTTP). Par dĂ©faut: false. PrĂ©fĂ©rez HTTPS (Tailscale Serve) ou 127.0.0.1.
  • gateway.controlUi.dangerouslyDisableDeviceAuth dĂ©sactive les vĂ©rifications d'identitĂ© du pĂ©riphĂ©rique pour Control UI (jeton/mot de passe uniquement). Par dĂ©faut: false. Verre de pause seulement.

Documentation connexe :

Proxys de confiance :

  • gateway.trustedProxies: liste des adresses IP de proxy inversĂ© qui terminent TLS devant la passerelle.
  • Quand une connexion provient d'un de ces IPs, OpenClaw utilise x-forwarded-for (ou x-real-ip) pour dĂ©terminer l'adresse IP du client pour les vĂ©rifications locales d'appairage et les vĂ©rifications HTTP auth/local.
  • Ne listez que les proxys que vous contrĂŽlez entiĂšrement et assurez-vous qu'ils Ă©crasent les x-forwarded-for.

Remarques :

  • openclaw gateway refuse de dĂ©marrer sauf si gateway.mode est dĂ©fini Ă  local (ou si vous passez le paramĂštre de remplacement).
  • gateway.port contrĂŽle le seul port multiplexĂ© utilisĂ© pour WebSocket + HTTP (control UI, hooks, A2UI).
  • Point de terminaison des complĂ©ments de chat OpenAI : dĂ©sactivĂ© par dĂ©faut; activez avec gateway.http.endpoints.chatCompletions.enabled: true.
  • PrĂ©cĂ©dent: --port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789.
  • L'authentification de la passerelle est requise par dĂ©faut (token/mot de passe ou identitĂ© de service en Ă©chelle de taille). Les liaisons non-loopback nĂ©cessitent un jeton/mot de passe partagĂ©.
  • L'assistant d'intĂ©gration gĂ©nĂšre un jeton de passerelle par dĂ©faut (mĂȘme sur le rebouclage).
  • gateway.remote.token est uniquement pour les appels CLI; il n'active pas l'authentification de la passerelle locale. gateway.token est ignorĂ©.

Auth and Tailscale :

  • gateway.auth.mode dĂ©finit les exigences d'Ă©tablissement de main (token ou password). Quand le jeton n'est pas dĂ©fini, l'authentification est utilisĂ©e.
  • gateway.auth.token stocke le jeton partagĂ© pour l'authentification des jetons (utilisĂ© par le CLI sur la mĂȘme machine).
  • Lorsque gateway.auth.mode est dĂ©fini, seule cette mĂ©thode est acceptĂ©e (plus des en-tĂȘtes optionnels d'Ă©chelle de queue).
  • gateway.auth.password peut ĂȘtre dĂ©fini ici, ou via OPENCLAW_GATEWAY_PASSWORD (recommandĂ©).
  • gateway.auth.allowTailscale permet aux Tailscale Serve des en-tĂȘtes d'identitĂ© (tailscale-user-login) de satisfaire l'authentification lorsque la requĂȘte arrive sur loopback avec x-forwarded-for, x-forwarded-proto, et x-forwarded-host. OpenClaw vĂ©rifie l'identitĂ© en rĂ©solvant l'adresse x-forwarded-for via tailscale whois avant de l'accepter. Lorsqu’il est dĂ©fini sur true, les requĂȘtes Serve n’ont pas besoin de jeton/mot de passe ; dĂ©finissez false pour exiger des identifiants explicites. Par dĂ©faut, true lorsque tailscale.mode = "serveur" et le mode d'authentification n'est pas password.
  • gateway.tailscale.mode: "serve" utilise Tailscale Serve (tailnet uniquement, lien loopback).
  • gateway.tailscale.mode: "funnel" expose le tableau de bord publiquement; nĂ©cessite auth.
  • gateway.tailscale.resetOnExit rĂ©initialise la configuration Serve/Funnel lors de l'extinction.

Client distant par défaut (CLI) :

  • gateway.remote.url dĂ©finit l'URL par dĂ©faut de passerelle WebSocket pour les appels CLI lorsque gateway.mode = "remote".
  • gateway.remote.transport sĂ©lectionne le transport Ă  distance macOS (ssh par dĂ©faut, direct pour ws/wss). Lorsque direct, gateway.remote.url doit ĂȘtre ws:// ou wss://. ws://host est par dĂ©faut le port 18789.
  • gateway.remote.token fournit le jeton pour les appels distants (laisser non dĂ©fini sans authentification).
  • gateway.remote.password fournit le mot de passe pour les appels distants (laisser vide sans authentification).

Comportement de l'application macOS :

  • OpenClaw.app surveille ~/.openclaw/openclaw.json et communique les modes en direct lorsque gateway.mode ou gateway.remote.url change.
  • Si gateway.mode est dĂ©sactivĂ©, mais gateway.remote.url est dĂ©fini, l'application macOS le traite comme mode distant.
  • Lorsque vous changez de mode de connexion dans l'application macOS, il Ă©crit gateway.mode (et gateway.remote.url + gateway.remote.transport en mode distant) dans le fichier de configuration.
{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://gateway.tailnet:18789",
      token: "votre-jeton",
      password: "votre-mot de passe",
    },
  },
}

Exemple de transport direct (application macOS) :

{
  gateway: {
    mode: "remote",
    remote: {
      transport: "direct",
      url: "wss://gateway.example.net",
      token: "your-token",
    },
  },
}

gateway.reload (Rechargement chaud de la configuration)¶

La passerelle surveille ~/.openclaw/openclaw.json (ou OPENCLAW_CONFIG_PATH) et applique les changements automatiquement.

Modes:

  • hybrid (par dĂ©faut) : appliquer des changements sĂ»rs Ă  chaud; redĂ©marrer la passerelle pour les changements critiques.
  • hot: n'appliquer que les changements Ă  chaud ; log quand un redĂ©marrage est nĂ©cessaire.
  • restart : redĂ©marrez la passerelle en cas de changement de configuration.
  • off: dĂ©sactive le rechargement chaud.
{
  gateway: {
    reload: {
      mode: "hybrid",
      debounceMs: 300,
    },
  },
}

Matrice de rechargement à chaud (fichiers + impact)¶

Fichiers surveillés :

  • ~/.openclaw/openclaw.json (ou OPENCLAW_CONFIG_PATH)

Appliqué à chaud (pas de redémarrage complet de la passerelle):

  • hooks (webhook auth/path/mappings) + hooks.gmail (Gmail watcher redĂ©marrĂ©)
  • browser (redĂ©marrage du serveur de contrĂŽle du navigateur)
  • cron (redĂ©marrage du service cron + mise Ă  jour simultanĂ©e)
  • agents.defaults.heartbeat (redĂ©marrage du runner du cƓur)
  • web (redĂ©marrage du canal web WhatsApp)
  • telegram, discord, signal, imessage (redĂ©marrage du canal)
  • agent, models, routing, messages, session, whatsapp, logging, skills, ui, talk, identity, wizard (lectures dynamiques)

Nécessite un redémarrage complet de la passerelle:

  • gateway (port/bind/auth/control UI/tailscale)
  • bridge (hĂ©ritĂ©)
  • dĂ©couverte
  • canvasHost
  • plugins
  • Tout chemin de configuration inconnu/non pris en charge (redĂ©marrage par dĂ©faut pour sĂ©curitĂ©)

Isolation multi-instance¶

Pour exécuter plusieurs passerelles sur un hÎte (pour redondance ou un robot de sauvetage), isoler l'état par instance + configuration et utiliser des ports uniques:

  • OPENCLAW_CONFIG_PATH (configuration par instance)
  • OPENCLAW_STATE_DIR (sessions/creds)
  • agents.defaults.workspace (souvenirs)
  • gateway.port (unique par instance)

Drapeaux de confort (CLI) :

  • openclaw --dev 
 → utilise ~/.openclaw-dev + dĂ©place les ports depuis la base 19001
  • openclaw --profile <name> 
 → utilise ~/.openclaw-<name> (port via config/env/flags)

Voir Carnet de passerelle pour le mapping de ports dérivé (passerelle/navigateur/canvas). Voir passerelles multiples pour plus de détails sur l'isolation du port par navigateur/CDP.

Exemple :

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
passerelle openclaw --port 19001

hooks (Gateway webhooks)¶

Activer un point de terminaison simple du webhook HTTP sur le serveur HTTP de la passerelle.

Paramùtres :

  • activĂ©: false
  • chemin : /hooks
  • maxBodyBytes: 262144 (256 KB)
{
  crochets : {
    activé: true,
    token: "shared-secret",
    chemin: "/hooks",
    presets: ["gmail"],
    transformsDir: "~/. penclaw/crochets",
    correspondances : [
      {
        correspondance: { path: "gmail" }, Action
        : "agent",
        wakeMode : "now",
        name : "Gmail",
        sessionKey: "crochete:gmail:{{messages[0].id}}",
        ModĂšle de message : "De: {{messages[0].from}}\nSujet : {{messages[0].subject}}\n{{messages[0].snippet}}",
        : vrai,
        canal: "last",
        modĂšle : "openai/gpt-5. -mini",
      },
    ],
  },
}

Les requĂȘtes doivent inclure le jeton de crochet :

  • Authorization: Bearer <token> ou
  • x-openclaw-token: <token>

Points de terminaison :

  • POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
  • POST /hooks/agent → { message, name?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
  • POST /hooks/<name> → rĂ©solu via hooks.mappings

/hooks/agent publie toujours un résumé dans la session principale (et peut éventuellement déclencher un pulsateur immédiat via `wakeMode: "now").

Mappage des notes :

  • match.path correspond au sous-chemin aprĂšs /hooks (par exemple /hooks/gmail → gmail).
  • match.source correspond Ă  un champ payload (par exemple { source: "gmail" }) afin que vous puissiez utiliser un chemin gĂ©nĂ©rique /hooks/ingest.
  • ModĂšles comme {{messages[0].subject}} lu depuis le payload.
  • transform peut pointer vers un module JS/TS qui retourne une action de crochet.
  • deliver: true envoie la rĂ©ponse finale Ă  un salon ; channel est par dĂ©faut last (tombe sur WhatsApp).
  • S'il n'y a pas de route de livraison prĂ©alable, dĂ©finissez explicitement channel + to (requis pour Telegram/Discord/Google Chat/Slack/Signal/iMessage/MS Teams).
  • model remplace le LLM pour ce hook run (provider/model ou alias; doit ĂȘtre autorisĂ© si agents.defaults.models est dĂ©fini).

Gmail helper config (utilisé par openclaw webhooks gmail setup / run):

{
  hooks: {
    gmail: {
      account: "openclaw@gmail.com",
      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" },

      // Optional: use a cheaper model for Gmail hook processing
      // Falls back to agents.defaults.model.fallbacks, then primary, on auth/rate-limit/timeout
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      // Optional: default thinking level for Gmail hooks
      thinking: "off",
    },
  },
}

Remplacer le modĂšle pour les crochets Gmail :

  • hooks.gmail.model spĂ©cifie un modĂšle Ă  utiliser pour le traitement du hook Gmail (par dĂ©faut pour la session primaire).
  • Accepte les refs provider/model ou les alias de agents.defaults.models.
  • Falls back to agents.defaults.model.fallbacks, then agents.defaults.model.primary, on auth/rate-limit/timeouts.
  • Si agents.defaults.models est dĂ©fini, inclure le modĂšle de crochets dans la liste d'autorisations.
  • Au dĂ©marrage, avertit si le modĂšle configurĂ© n'est pas dans le catalogue de modĂšles ou la liste d'autorisations.
  • hooks.gmail.thinking dĂ©finit le niveau de pensĂ©e par dĂ©faut pour les hooks Gmail et est Ă©crasĂ© par per-hook thinking.

DĂ©marrage automatique de la passerelle:

  • Si hooks.enabled=true et hooks.gmail.account sont dĂ©finis, la passerelle dĂ©marre gog gmail watch serve au dĂ©marrage et renouvelle automatiquement la montre.
  • DĂ©finissez OPENCLAW_SKIP_GMAIL_WATCHER=1 pour dĂ©sactiver le dĂ©marrage automatique (pour les exĂ©cutions manuelles).
  • Évitez d’exĂ©cuter un gog gmail watch serve sĂ©parĂ© en parallĂšle du Gateway ; cela Ă©chouera avec listen tcp 127.0.0.1:8788: bind: address already in use.

Note: lorsque tailscale.mode est activé, OpenClaw définit par défaut serve.path à / afin que Tailscale puisse proxy /gmail-pubsub correctement (il supprime le préfixe set-path). Si vous avez besoin du backend pour recevoir le chemin préfixé, définissez hooks.gmail.tailscale.target sur une URL complÚte (et alignez serve.path).

canvasHost (LAN/tailnet Canvas file server + reload)¶

La passerelle sert un rĂ©pertoire de HTML/CSS/JS via HTTP, donc les nƓuds iOS/Android peuvent simplement canvas.navigate vers lui.

Racine par défaut: ~/. penclaw/workspace/canvas
Port par défaut: 18793 (choisi pour éviter le port CDP du navigateur openclaw 18792)
Le serveur Ă©coute sur le gateway bind host (LAN ou Tailnet) afin que les nƓuds puissent l'atteindre.

Le serveur:

  • sert des fichiers dans canvasHost.root
  • injecte un minuscule client de rechargement en HTML servi
  • surveille le rĂ©pertoire et les diffusions se rechargent sur un point de terminaison WebSocket Ă  /__openclaw__/ws
  • auto-crĂ©e un dĂ©marrage index.html lorsque le rĂ©pertoire est vide (donc vous voyez quelque chose immĂ©diatement)
  • sert Ă©galement A2UI Ă  /__openclaw__/a2ui/ et est annoncĂ© aux nƓuds comme canvasHostUrl (toujours utilisĂ© par les nƓuds pour Canvas/A2UI)

Désactiver le rechargement en direct (et la surveillance des fichiers) si le répertoire est volumineux ou si vous appuyez sur EMFILE:

  • config: canvasHost: { liveReload: false }
{
  canvasHost: {
    root: "~/.openclaw/workspace/canvas",
    port: 18793,
    liveReload: true,
  },
}

Les modifications apportées à canvasHost.* nécessitent un redémarrage de la passerelle (le rechargement de la configuration va redémarrer).

DĂ©sactiver avec :

  • config: canvasHost: { enabled: false }
  • env: OPENCLAW_SKIP_CANVAS_HOST=1

bridge (pont TCP hérité, supprimé)¶

Les versions actuelles n'incluent plus l'Ă©couteur du pont TCP ; les clĂ©s de configuration bridge.* sont ignorĂ©es. Les nƓuds se connectent sur la passerelle WebSocket. Cette section est conservĂ©e pour rĂ©fĂ©rence historique.

Comportement hérité :

  • La passerelle pourrait exposer un pont TCP simple pour les nƓuds (iOS/Android), gĂ©nĂ©ralement sur le port 18790.

Paramùtres :

  • activĂ©: true
  • port : 18790
  • bind: lan (se lie Ă  0.0.0.0)

Bind modes:

  • lan: 0.0.0.0 (accessible sur n'importe quelle interface, incluant LAN/Wi‐Fi et Tailscale)
  • tailnet: se lier uniquement Ă  l'IP Tailscale de la machine (recommandĂ© pour Vienne Londres)
  • loopback: 127.0.0.1 (local seulement)
  • auto: prĂ©fĂšre tailnet IP si prĂ©sent, sinon lan

TLS:

  • bridge.tls.enabled: active TLS pour les connexions de passerelles (TLS-only quand activĂ©).
  • bridge.tls.autoGenerate: gĂ©nĂšre un certificat auto-signĂ© quand aucune clĂ© n'est prĂ©sente (par dĂ©faut: true).
  • bridge.tls.certPath / bridge.tls.keyPath: chemins PEM pour le certificat de pont + clĂ© privĂ©e.
  • bridge.tls.caPath: bundle PEM CA optionnel (racines personnalisĂ©es ou futur mTLS).

Lorsque TLS est activĂ©, la passerelle annonce bridgeTls=1 et bridgeTlsSha256 lors de la dĂ©couverte des enregistrements TXT afin que les nƓuds puissent Ă©pingler le certificat. Les connexions manuelles utilisent une utilisation de confiance en premiĂšre utilisation si aucune empreinte n'est encore enregistrĂ©e. Les certificats gĂ©nĂ©rĂ©s automatiquement nĂ©cessitent openssl sur PATH; si la gĂ©nĂ©ration Ă©choue, le pont de connexion ne dĂ©marrera pas.

{
  pont: {
    activé: vrai,
    port : 18790,
    liaison : "tailnet",
    tls : {
      activé : vrai,
      // Utilise ~/. penclaw/bridge/tls/bridge-{cert,key}. em quand omis.
      // certPath: "~/.openclaw/bridge/tls/bridge-cert.pem",
      // keyPath: "~/. penclaw/bridge/tls/bridge-key.pem"
    },
  },
}

discovery.mdns (mode diffusion Bonjour / mDNS)¶

ContrÎle les diffusions de découverte de LAN mDNS (_openclaw-gw._tcp).

  • minimal (par dĂ©faut) : omettre cliPath + sshPort des enregistrements TXT
  • full: inclure cliPath + sshPort dans les enregistrements TXT
  • off: dĂ©sactiver entiĂšrement les diffusions mDNS
  • Nom d'hĂŽte : openclaw par dĂ©faut (annonce openclaw.local). Remplacer par OPENCLAW_MDNS_HOSTNAME.
{
  découverte: { mdns: { mode: "minimal" } },
}

discovery.wideArea (Wide-Area Bonjour / unicast DNS‐SD)¶

Lorsqu'elle est activée, la passerelle écrit une zone DNS-SD unicast pour _openclaw-gw._tcp dans ~/.openclaw/dns/ en utilisant le domaine de découverte configuré (exemple: openclaw.internal.).

Pour faire découvrir iOS/Android à travers les réseaux (Vienne Londres), associez ceci avec :

  • un serveur DNS sur l'hĂŽte passerelle servant le domaine choisi (CoreDNS est recommandĂ©)
  • Facile Ă  diviser les DNS pour que les clients rĂ©solvent ce domaine via le serveur DNS de passerelle

Assistant de configuration unique (hĂŽte de passerelle):

openclaw dns setup --apply

{
  discovery: { wideArea: { enabled: true } },
}

Variables de modÚle de média¶

Les espaces réservés au modÚle sont étendus dans tools.media.*.models[].args et tools.media.models[].args (et dans tous les champs d'arguments modÚles futurs).

| Variable | Description | | ------------------------------------------------------------------------------- | -------- | ------- | ---------- | ----- | ----- | ------ | -------- | ------- | ------- | | --- | | {{Body}} | Corps du message entrant | | {{RawBody}} | Raw corps du message entrant (pas de enveloppe de l'historique/expĂ©diteur; best for command parsing) | | {{BodyStripped}} | Body with group mentions stripped (best default for agents) | | {{From}} | Sender identifiant (E. 64 pour WhatsApp ; peut diffĂ©rer par canal) | | {{To}} | Identifiant de destination | | {{MessageSid}} | ID de message de canal (lorsque disponible) | | {{SessionId}} | UUID de la session actuelle | | {{IsNewSession}} | "true" quand une nouvelle session a Ă©tĂ© crĂ©Ă©e | | {{MediaUrl}} | pseudo-URL du mĂ©dia entrant (si prĂ©sent) | | {{MediaPath}} | Chemin du mĂ©dia local (si tĂ©lĂ©chargĂ©) | | {{MediaType}} | Type de mĂ©dia (image/audio/document/
) | | {{Transcript}} | Transcription audio (lorsque activĂ©e) | | {{Prompt}} | Prompt mĂ©dia rĂ©solu pour les entrĂ©es CLI | | {{MaxChars}} | Nombre maximal de caractĂšres de sortie rĂ©solu pour les entrĂ©es CLI | | {{ChatType}} | "direct" ou "group" | | {{GroupSubject}} | Sujet du groupe (meilleur effort) | | {{GroupMembers}} | Aperçu des membres du groupe (meilleur effort) | | {{SenderName}} | Nom d’affichage de l’expĂ©diteur (meilleur effort) | | {{SenderE164}} | NumĂ©ro de tĂ©lĂ©phone de l’expĂ©diteur (meilleur effort) | | {{Provider}} | Indication du fournisseur (whatsapp | telegram | discord | googlechat | slack | signal | imessage | msteams | webchat | 
) |

Cron (Planificateur de Gateway)¶

Cron est un planificateur appartenant à la passerelle pour les réveils et les tùches planifiées. Voir Tùches Cron pour la vue d'ensemble des fonctionnalités et les exemples de CLI.

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
  },
}

Suivant : Agent Runtime 🩞

veiseule.ai — Community translations maintained by John Kelly. Improve translations on Crowdin.