agentDir) et son propre historique de sessions stocké dans SQLite, ainsi que plusieurs comptes de canal (par exemple, deux numéros WhatsApp). Les messages entrants sont acheminés vers l’agent approprié au moyen de liaisons.
Un agent représente le périmètre complet d’une persona : fichiers de l’espace de travail, profils d’authentification, registre de modèles et stockage des sessions. Une liaison associe un compte de canal (un espace de travail Slack, un numéro WhatsApp, etc.) à l’un de ces agents.
Qu’est-ce qu’un agent
Chaque agent possède ses propres éléments :- Espace de travail : fichiers,
AGENTS.md/SOUL.md/USER.md, notes locales, règles de persona. - Répertoire d’état (
agentDir) : profils d’authentification, registre de modèles, configuration propre à l’agent. - Stockage des sessions : historique des conversations et état du routage dans
~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.
sessions_history est la méthode la plus sûre pour récupérer des informations entre les sessions : elle renvoie une vue limitée et expurgée, et non une copie brute de la transcription. Elle supprime les signatures des blocs de réflexion, les détails des charges utiles des résultats d’outils, la structure <relevant-memories>, les balises XML d’appel d’outil (<tool_call>, <function_call> et leurs formes plurielles ou rétrogradées) ainsi que le XML d’appel d’outil MiniMax, puis tronque et limite la sortie en fonction de sa taille en octets.~/.openclaw/skills, puis filtrées selon la liste d’autorisation de Skills effective de l’agent. Utilisez agents.defaults.skills pour définir une base de référence partagée et agents.list[].skills pour effectuer un remplacement propre à chaque agent (les entrées explicites remplacent la valeur par défaut, elles ne sont pas fusionnées). Consultez Skills : propres à chaque agent ou partagées et Skills : listes d’autorisation des agents.
Le stockage géré par un Plugin suit la configuration de ce Plugin ; l’ajout d’un second agent ne sépare pas automatiquement tous les stockages globaux des Plugins. Par exemple, configurez des coffres Memory Wiki propres à chaque agent lorsque les personas ne doivent pas partager les connaissances de wiki compilées.
Remarque sur l’espace de travail : l’espace de travail de chaque agent est le répertoire de travail actuel par défaut, et non un bac à sable strict. Les chemins relatifs sont résolus dans l’espace de travail, mais les chemins absolus peuvent accéder à d’autres emplacements de l’hôte, sauf si l’isolation en bac à sable est activée. Consultez Isolation en bac à sable.
Chemins
Mode agent unique (par défaut)
Si vous ne configurez rien, OpenClaw exécute un seul agent :- La valeur par défaut de
agentIdestmain. - Les sessions utilisent des clés de la forme
agent:main:<mainKey>(la valeur par défaut demainKeyestmain). - L’espace de travail par défaut est
~/.openclaw/workspace(ouworkspace-<profile>lorsqueOPENCLAW_PROFILEest défini sur une valeur autre quedefault). - L’état est stocké par défaut dans
~/.openclaw/agents/main/agent.
Assistant de gestion des agents
Ajoutez un nouvel agent isolé :--workspace <dir>, --model <id>, --agent-dir <dir>, --bind <channel[:accountId]> (répétable), --non-interactive (nécessite --workspace).
Ajoutez des bindings pour acheminer les messages entrants (l’assistant vous propose de le faire), puis vérifiez :
Démarrage rapide
1
Créer l’espace de travail de chaque agent
SOUL.md, AGENTS.md et éventuellement USER.md, ainsi que d’un agentDir dédié et d’un stockage de sessions sous ~/.openclaw/agents/<agentId>.2
Créer les comptes de canal
Créez un compte par agent sur les canaux de votre choix :Consultez les guides des canaux : Discord, Telegram, WhatsApp.
- Discord : un bot par agent, activez Message Content Intent et copiez chaque jeton.
- Telegram : un bot par agent via BotFather, puis copiez chaque jeton.
- WhatsApp : associez chaque numéro de téléphone au compte correspondant.
3
Ajouter les agents, les comptes et les liaisons
Ajoutez les agents sous
agents.list, les comptes de canal sous channels.<channel>.accounts, puis reliez-les avec bindings (voir les exemples ci-dessous).4
Redémarrer et vérifier
Plusieurs agents, plusieurs personas
ChaqueagentId configuré constitue une limite de persona distincte pour l’état principal de l’agent :
- Comptes différents par canal (selon
accountId). - Personnalités différentes (
AGENTS.md/SOUL.mdpropres à chaque agent). - Authentification et sessions séparées, l’accès entre agents n’étant activé que par des fonctionnalités explicites ou par la configuration d’un Plugin.
Coffres Memory Wiki propres à chaque agent
Memory Wiki utilise par défaut un coffre global unique. Pour séparer les connaissances compilées d’un agent d’assistance de celles d’un agent marketing, définissezplugins.entries.memory-wiki.config.vault.scope sur agent :
~/.openclaw/wiki/support et ~/.openclaw/wiki/marketing. Les opérations de la CLI et du Gateway limitées à un agent nécessitent de spécifier explicitement un agent lorsque plusieurs agents sont configurés. Consultez Coffres Memory Wiki propres à chaque agent pour plus de détails sur le filtrage du pont, la migration et les limites de confiance.
Recherche de mémoire QMD entre agents
Pour permettre à un agent de rechercher les transcriptions de sessions QMD d’un autre agent, ajoutez des collections supplémentaires sousagents.list[].memorySearch.qmd.extraCollections. Utilisez agents.defaults.memorySearch.qmd.extraCollections lorsque tous les agents doivent partager les mêmes collections.
name reste explicite lorsque le chemin se trouve hors de l’espace de travail de l’agent. Les chemins situés dans l’espace de travail restent propres à l’agent afin que chacun conserve son propre ensemble de recherche de transcriptions.
Un numéro WhatsApp, plusieurs personnes (répartition des messages privés)
Acheminez différents messages privés WhatsApp vers différents agents sur un seul compte WhatsApp en faisant correspondre l’expéditeur au format E.164 (+15551234567) avec peer.kind: "direct". Les réponses proviennent toujours du même numéro WhatsApp : il n’existe pas d’identité d’expéditeur propre à chaque agent.
Par défaut, les conversations directes sont regroupées sous la clé de session principale de l’agent ; une isolation réelle nécessite donc un agent par personne.
Règles de routage
Les liaisons sont déterministes et la correspondance la plus spécifique l’emporte. Consultez Routage des canaux pour connaître l’ordre complet des niveaux (pair exact, pair parent, caractère générique de pair, serveur+rôles, serveur, équipe, compte, canal, agent par défaut). Voici quelques règles importantes :- Si plusieurs liaisons correspondent au même niveau, la première dans l’ordre de la configuration l’emporte.
- Si une liaison définit plusieurs champs de correspondance (par exemple
peer+guildId), tous les champs spécifiés doivent correspondre (sémantiqueAND). - Une liaison qui omet
accountIdcorrespond uniquement au compte par défaut, et non à tous les comptes. UtilisezaccountId: "*"pour définir une solution de repli à l’échelle du canal, ouaccountId: "<name>"pour un compte précis. L’ajout de la même liaison avec un identifiant de compte explicite met à niveau la liaison existante limitée au canal au lieu de la dupliquer.
Plusieurs comptes / numéros de téléphone
Les canaux qui prennent en charge plusieurs comptes (par exemple WhatsApp) utilisentaccountId pour identifier chaque connexion. Chaque accountId est acheminé vers son propre agent, ce qui permet à un serveur d’héberger plusieurs numéros de téléphone sans mélanger les sessions.
Définissez channels.<channel>.defaultAccount pour choisir le compte utilisé lorsque accountId est omis. Si cette valeur n’est pas définie, OpenClaw utilise default s’il existe ; sinon, il utilise le premier identifiant de compte configuré selon l’ordre de tri.
Canaux prenant en charge plusieurs comptes : discord, feishu, googlechat, imessage, irc, line, mattermost, matrix, nextcloud-talk, nostr, signal, slack, telegram, whatsapp, zalo, zalouser.
Concepts
agentId: un « cerveau » (espace de travail, authentification propre à l’agent, stockage de sessions propre à l’agent).accountId: une instance de compte de canal (par exemple, le compte WhatsApppersonalpar rapport àbiz).binding: achemine les messages entrants vers unagentIdselon(channel, accountId, peer), et éventuellement selon les identifiants de serveur/d’équipe.- Les conversations directes sont regroupées dans
agent:<agentId>:<mainKey>(session « principale » propre à l’agent ; voirsession.mainKey).
Exemples par plateforme
Bots Discord par agent
Bots Discord par agent
Chaque compte de bot Discord correspond à un
accountId unique. Associez chaque compte à un agent et conservez des listes d’autorisation propres à chaque bot.- Invitez chaque bot sur le serveur et activez Message Content Intent.
- Les jetons se trouvent dans
channels.discord.accounts.<id>.token(le compte par défaut peut utiliserDISCORD_BOT_TOKEN).
Bots Telegram par agent
Bots Telegram par agent
- Créez un bot par agent avec BotFather et copiez chaque jeton.
- Les jetons se trouvent dans
channels.telegram.accounts.<id>.botToken(le compte par défaut peut utiliserTELEGRAM_BOT_TOKEN). - Pour plusieurs bots dans le même groupe Telegram, invitez chaque bot et mentionnez celui qui doit répondre.
- Désactivez Privacy Mode de BotFather pour chaque bot de groupe (
/setprivacy-> Disable), puis supprimez et ajoutez de nouveau le bot afin que Telegram applique le paramètre. - Autorisez les groupes avec
channels.telegram.groups, ou utilisezgroupPolicy: "open"uniquement pour les déploiements de groupes de confiance. - Placez les identifiants utilisateur des expéditeurs dans
groupAllowFrom. Les identifiants de groupe et de supergroupe doivent figurer danschannels.telegram.groups, et non dansgroupAllowFrom. - Associez selon
accountIdafin que chaque bot achemine les messages vers son propre agent.
Numéros WhatsApp par agent
Numéros WhatsApp par agent
Associez chaque compte avant de démarrer le Gateway :
~/.openclaw/openclaw.json (JSON5) :Modèles courants
- WhatsApp au quotidien + travail approfondi sur Telegram
- Même canal, une pair vers Opus
- Agent familial associé à un groupe WhatsApp
Répartissez par canal : acheminez WhatsApp vers un agent rapide pour les tâches quotidiennes et Telegram vers un agent Opus.Ces exemples utilisent
accountId: "*" afin que les associations continuent de fonctionner si vous ajoutez des comptes ultérieurement. Pour acheminer un seul message direct/groupe vers Opus tout en conservant le reste sur l’agent de conversation, ajoutez une association match.peer pour cette pair — les correspondances de pair l’emportent toujours sur les règles couvrant l’ensemble du canal.Configuration du bac à sable et des outils par agent
Chaque agent peut disposer de ses propres restrictions de bac à sable et d’outils :setupCommand se trouve sous sandbox.docker et s’exécute une fois lors de la création du conteneur. Les remplacements sandbox.docker.* propres à l’agent sont ignorés lorsque la portée résolue est "shared".- Isolation de sécurité : restreignez les outils pour les agents non fiables.
- Contrôle des ressources : placez certains agents dans un bac à sable tout en conservant les autres sur l’hôte.
- Politiques flexibles : définissez des autorisations différentes pour chaque agent.
tools.elevated comporte à la fois une porte globale (tools.elevated.enabled/allowFrom) et une porte propre à l’agent (agents.list[].tools.elevated.enabled/allowFrom). La porte propre à l’agent peut uniquement restreindre davantage la porte globale : les deux doivent autoriser un expéditeur pour que les commandes avec privilèges élevés puissent s’exécuter. Pour cibler un groupe, utilisez agents.list[].groupChat.mentionPatterns afin que les @mentions correspondent clairement à l’agent prévu.Rubriques associées
- Agents ACP — exécution de harnais de programmation externes
- Routage des canaux — acheminement des messages vers les agents
- Présence — présence et disponibilité des agents
- Session — isolation et routage des sessions
- Sous-agents — lancement d’exécutions d’agents en arrière-plan