Les agents OpenClaw : guide complet

Introduction

Les agents OpenClaw sont des assistants isolés servis par un même Gateway, chacun avec son workspace, son identité, son modèle et ses sessions. Ce modèle est utile pour séparer un assistant personnel, un agent support et un agent opérations tout en conservant un point de contrôle commun. Il ne faut pas les confondre avec des classes Python ni avec une équipe CrewAI qui exécute un pipeline de rôles. Si vous n’avez qu’un interlocuteur et une seule politique d’outils, ajouter plusieurs agents est souvent inutile : restez sur une approche plus simple. Ce guide explique leur création, leur routage et leurs vraies limites de sécurité.

Résumé rapide

1. Un agent OpenClaw est une frontière de persona, workspace, auth et sessions.
2. Le mode par défaut crée un agent main dans ~/.openclaw/workspace.
3. openclaw agents add ajoute un agent ; les bindings routent les canaux.
4. Les workspaces séparés évitent les collisions, mais ne sont pas des sandboxes.
5. Un Gateway commun reste une seule frontière de confiance.

Ce qu’est réellement un agent OpenClaw

OpenClaw est un assistant agentique self-hosted distribué comme application Node/TypeScript. Son centre de gravité est le Gateway : un processus durable qui relie le runtime d'agent aux interfaces de contrôle, aux canaux de messagerie et, si besoin, à des nodes mobiles ou headless. La CLI et la Control UI pilotent ce même système. Cette architecture diffère d'un framework Python intégré dans une application : on configure et exploite un service, on ne construit pas un pipeline en important une classe Agent.

Chaque agent possède un workspace. On y trouve ses instructions, son identité, ses fichiers de mémoire et ses skills. Les skills sont des dossiers documentaires contenant un SKILL.md ; ils apprennent à l'agent quand et comment employer des tools déjà disponibles. Une capacité runtime nouvelle relève plutôt d'un plugin, qui peut ajouter tools, providers, canaux ou hooks. Cette distinction évite de transformer un simple mode opératoire Markdown en faux SDK.

Le mode mono-agent suffit par défaut. Le multi-agent ajoute des workspaces, états et sessions séparés, puis des bindings déterministes pour router les messages. Il ne s'agit pas d'une équipe CrewAI qui se distribue spontanément des rôles : ce sont des assistants isolés servis par un Gateway commun. Les automations planifient des tours ou des événements à l'intérieur de ce Gateway.

Pour comprendre la différence avec un agent générique, consultez aussi l’architecture d’un agent IA. Dans OpenClaw, l’identité opérationnelle vient surtout des fichiers du workspace, de la configuration et du routage, pas d’une sous-classe écrite en Python.

Créer, isoler et router les agents

Le périmètre d’un agent

Un agent regroupe un workspace, un répertoire d’état, des profils d’authentification, un registre de modèles et un historique SQLite. Son workspace contient les fichiers qui cadrent son identité et son comportement. Son agentDir conserve l’état qui ne doit pas être partagé par erreur. Réutiliser le même répertoire d’état pour deux agents provoque des collisions de sessions et d’authentification.

Ajouter un agent

La voie officielle passe par la CLI :

openclaw agents add work
openclaw agents list

Pour une création non interactive, fournissez un workspace explicite :

openclaw agents add ops --workspace ~/.openclaw/workspace-ops --non-interactive

L’assistant de création peut aussi choisir un modèle et proposer un binding. Vérifiez toujours le résultat avec openclaw agents list --bindings. Pour poursuivre pas à pas, le tutoriel créer un agent OpenClaw part de ce flux réel.

Définir l’identité

Les fichiers SOUL.md, AGENTS.md, USER.md et éventuellement IDENTITY.md décrivent la personnalité, les règles de travail et le contexte utile. Les instructions doivent préciser la mission, les interdits, les formats attendus et les conditions d’escalade. Évitez de transformer ces fichiers en catalogue de tout ce que l’entreprise sait : gardez les connaissances détaillées dans des références ou la mémoire indexée.

Comprendre les bindings

Un binding associe un agent à un canal ou à un compte de canal. Le routage est déterministe : une règle spécifique sur un correspondant gagne sur un fallback plus large. Ajoutez un binding via la création de l’agent ou la commande dédiée, puis vérifiez la liste. L’objectif n’est pas de déléguer une sous-tâche à un collègue virtuel, mais de faire arriver chaque message dans le bon espace de travail.

Séparer les capacités

Les allowlists de skills peuvent être définies par défaut puis remplacées par agent. Les policies de tools et le sandbox doivent être configurés séparément. Un agent support peut lire sa base documentaire sans disposer d’un shell ; un agent opérations peut avoir un accès plus large mais réservé à des expéditeurs identifiés. Cette séparation réduit le rayon d’impact d’une instruction malveillante.

Exécuter un tour ciblé

Pour tester sans dépendre d’un canal :

openclaw agent --agent ops --message "Résume l’état des vérifications du jour"

Relisez la réponse et les effets produits. Une commande acceptée n’est pas une preuve que la bonne session, le bon modèle et les bons fichiers ont été utilisés. Contrôlez l’agent ciblé et l’état effectif du Gateway.

Multi-agent ou simple sous-tâche

Créez plusieurs agents pour séparer des identités durables, des comptes, des workspaces ou des politiques. Pour une sous-tâche éphémère, utilisez plutôt les mécanismes de sessions ou sous-agents disponibles au runtime. Multiplier les agents permanents augmente la maintenance des modèles, credentials, mémoires et bindings.

Repère opérationnel supplémentaire

Le Gateway doit rester le point de référence opérationnel. Il porte les sessions, les connexions aux canaux et le routage ; un redémarrage ou une panne affecte donc toutes les surfaces qui en dépendent. En production, supervisez le processus, conservez une procédure de redémarrage, puis vérifiez son état avec openclaw gateway status. Les automations exigent elles aussi un Gateway actif au moment prévu. Cette topologie est plus simple à exploiter qu'une collection de scripts dispersés, mais elle impose de traiter le Gateway comme un service durable et non comme une commande ponctuelle.

Repère opérationnel supplémentaire

Le workspace facilite l'organisation, mais ce n'est pas une frontière de sécurité. Il fournit le répertoire de travail, les instructions, les skills et les fichiers de mémoire ; sans sandbox, un outil autorisé peut encore atteindre d'autres chemins de l'hôte. Pour un assistant exposé à plusieurs personnes, limitez les outils, activez l'isolation adaptée et séparez les Gateway lorsque les utilisateurs ne partagent pas le même niveau de confiance. Une allowlist de skills réduit ce que le modèle voit, mais ne remplace jamais une politique d'exécution shell.

Repère opérationnel supplémentaire

La validation doit porter sur un effet observable. Après une modification, lancez une demande courte, vérifiez le fichier ou le message produit, puis consultez les logs et l'historique de session en cas d'écart. Évitez de conclure qu'une opération a réussi uniquement parce que la CLI n'a pas retourné d'erreur. Pour les actions avec effets de bord, ajoutez une étape de lecture après écriture, un identifiant d'exécution et une règle d'idempotence. Cela réduit les doublons lors d'un retry ou d'une reprise après interruption.

Repère opérationnel supplémentaire

Les coûts et la latence dépendent davantage du modèle, du volume de contexte et du nombre d'appels d'outils que du nombre de fichiers de configuration. Commencez avec une mission étroite, un petit jeu de skills et une session clairement délimitée. Mesurez ensuite le temps de réponse, les appels échoués et la qualité de la sortie avant d'ajouter des agents ou des automatisations. Un workflow déterministe reste préférable lorsque la tâche se résume à transformer une entrée connue selon des règles stables.

Repère opérationnel supplémentaire

Les changements de configuration méritent une discipline de maintenance. Modifiez une seule dimension à la fois, gardez une copie exploitable, lancez openclaw doctor, puis redémarrez le Gateway seulement lorsque le changement l'exige. Le fichier est validé strictement : une clé inconnue ou une structure invalide peut empêcher le démarrage. La Control UI et openclaw config get sont utiles pour lire l'état effectif au lieu de raisonner sur un extrait ancien ou une valeur supposée.

Repère opérationnel supplémentaire

La sécurité commence avant le prompt. Restreignez les expéditeurs autorisés, conservez l'écoute réseau sur loopback tant qu'un accès distant n'est pas nécessaire, protégez l'authentification du Gateway et auditez régulièrement l'installation avec openclaw security audit --deep. Les contenus reçus, les pages consultées et les résultats d'outils doivent être considérés comme non fiables. Donnez à chaque agent uniquement les capacités nécessaires et préférez des identifiants dédiés pour les services externes.

Repère opérationnel supplémentaire

La mémoire OpenClaw est explicite : les faits durables vivent dans MEMORY.md, les préférences stables dans USER.md et les notes courantes dans memory/. Cette lisibilité facilite l'audit et la correction, mais oblige à surveiller ce qui est conservé. Ne placez ni secret ni jeton dans ces fichiers. Une information sensible copiée dans une conversation peut aussi se retrouver dans un transcript ; appliquez donc une politique de rétention et nettoyez les données avant de partager des diagnostics.

Repère opérationnel supplémentaire

Dans un déploiement multi-agent, chaque agent doit conserver son propre workspace, son répertoire d'état et son historique. Les bindings choisissent l'agent à partir du canal, du compte ou du correspondant. Cette séparation évite les collisions de sessions et permet des identités distinctes, mais elle ne crée pas une isolation hostile à l'intérieur d'un même Gateway. Pour des équipes ou clients qui ne se font pas confiance, utilisez des Gateway et, si nécessaire, des utilisateurs système ou des hôtes séparés.

Exemple concret

Une agence veut séparer le support client des opérations internes. Elle conserve main pour l’usage personnel et crée support avec openclaw agents add support --workspace ~/.openclaw/workspace-support --non-interactive. Dans ce workspace, AGENTS.md impose des réponses fondées sur la documentation, interdit toute modification de production et décrit l’escalade vers un humain. Les skills visibles se limitent aux procédures support.

L’équipe associe ensuite le compte de messagerie support à cet agent, puis contrôle le résultat avec openclaw agents list --bindings. Elle envoie un ticket de test et vérifie qu’il arrive dans la session support, pas dans la session principale. Un second test demande une commande système : elle doit être refusée par la policy de tools, même si le texte du skill suggère une action. Enfin, l’équipe inspecte les logs et confirme que les deux historiques restent distincts. Cet exemple valide à la fois le routage nominal et la restriction négative ; il ne prétend pas isoler deux clients hostiles sur le même Gateway.

Bonnes pratiques

Donnez à chaque agent une mission durable et un propriétaire clair. Utilisez un workspace et un agentDir distincts, puis vérifiez les bindings après toute modification de canal. Gardez les instructions courtes, les skills ciblés et les credentials limités au service nécessaire. Si deux personas ont des niveaux de confiance différents, réduisez la visibilité des sessions et les échanges agent-à-agent.

En production, maintenez une checklist par agent : identité, modèle, workspace, skills éligibles, tools autorisés, sandbox, binding et test de refus. Exécutez openclaw security audit --deep avant d’ouvrir un canal. Pour une séparation forte entre organisations adverses, ne comptez ni sur le workspace ni sur le routage : déployez des Gateway et des comptes système distincts.

Questions fréquentes

Comment créer un agent OpenClaw ?

Utilisez openclaw agents add <nom> en mode interactif, ou fournissez --workspace avec --non-interactive. Vérifiez ensuite l’agent, son workspace et ses bindings avec openclaw agents list --bindings. Il n’y a pas de classe Python OpenClawAgent à instancier.

À quoi sert le workspace d’un agent OpenClaw ?

Le workspace contient les instructions, l’identité, les skills et les fichiers de mémoire de l’agent. C’est aussi son répertoire de travail par défaut. Il structure le contexte, mais n’empêche pas à lui seul un tool non sandboxé d’accéder à d’autres chemins de l’hôte.

Peut-on connecter plusieurs agents au même canal ?

Oui, grâce aux comptes et aux bindings. Vous pouvez router un compte complet ou une conversation précise vers un agent. Les règles les plus spécifiques prennent le dessus. Testez le routage avec de vrais messages et vérifiez les bindings après chaque changement.

Les agents OpenClaw sont-ils isolés entre eux ?

Leurs workspaces, états et sessions peuvent être séparés, mais un Gateway reste une frontière de confiance commune. Les outils de session et les échanges entre agents peuvent être larges selon la configuration. Pour des utilisateurs adverses, utilisez des Gateway, credentials et hôtes distincts.

Articles liés

Les agents OpenClaw servent à séparer des assistants durables et leurs surfaces, pas à reproduire un framework Python d’orchestration. Commencez avec un agent unique, puis ajoutez une identité seulement lorsqu’un vrai besoin de routage ou de politique le justifie.

• Créer un agent OpenClaw pas à pas
• Guide complet OpenClaw
• Configurer OpenClaw
• Comprendre les skills OpenClaw
• Architecture d’un agent IA