Sous-agents

Les sous-agents sont des exécutions d’agent en arrière-plan lancées depuis une exécution d’agent existante. Chacun s’exécute dans sa propre session (agent:<agentId>:subagent:<uuid>) et, une fois terminé, annonce son résultat sur le canal de discussion du demandeur. Chaque exécution de sous-agent est suivie en tant que tâche en arrière-plan.

Objectifs :

• Paralléliser les recherches, les tâches longues et les opérations lentes des outils sans bloquer l’exécution principale.
• Maintenir les sous-agents isolés par défaut (séparation des sessions, mise en bac à sable facultative).
• Rendre la surface des outils difficile à utiliser de manière incorrecte : par défaut, les sous-agents n’ont pas accès aux outils de session ou de messagerie.
• Prendre en charge une profondeur d’imbrication configurable pour les modèles d’orchestration.

Commande oblique

/subagents examine les exécutions de sous-agents de la session actuelle :

/subagents list/subagents log <id|#> [limit] [tools]/subagents info <id|#>

/subagents info affiche les métadonnées de l’exécution (état, horodatages, identifiant de session, chemin de la transcription, nettoyage). /subagents log affiche les échanges récents d’une exécution ; ajoutez le jeton tools pour inclure les messages d’appel et de résultat des outils (omis par défaut). Utilisez sessions_history pour obtenir, depuis une exécution d’agent, une vue limitée et filtrée pour la sécurité, ou consultez le chemin de la transcription sur le disque pour accéder à la transcription brute complète.

Commandes de liaison aux fils

Ces commandes fonctionnent sur les canaux dotés de liaisons de fils persistantes. Consultez Canaux prenant en charge les fils ci-dessous.

/focus <subagent-label|session-key|session-id|session-label>/unfocus/agents/session idle <duration|off>/session max-age <duration|off>

Comportement du lancement

Les agents lancent des sous-agents en arrière-plan à l’aide de l’outil sessions_spawn. Les achèvements sont renvoyés sous forme d’événements internes de la session parente ; l’agent parent/demandeur décide si une mise à jour destinée à l’utilisateur est nécessaire.

Modes de contexte

Les sous-agents natifs démarrent isolés, sauf si l’appelant demande explicitement de dupliquer la transcription actuelle.

Utilisez fork avec parcimonie. Il est destiné à la délégation sensible au contexte, et non à remplacer la rédaction d’une consigne de tâche claire.

Outil : sessions_spawn

Démarre une exécution de sous-agent avec deliver: false sur la file globale subagent, puis exécute une étape d’annonce et publie la réponse de l’annonce sur le canal de discussion du demandeur.

La disponibilité dépend de la politique effective d’outils de l’appelant. Le profil intégré coding inclut sessions_spawn ; messaging et minimal ne l’incluent pas. full autorise tous les outils. Ajoutez tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"], ou utilisez tools.profile: "coding", pour les agents dont le profil plus restreint doit tout de même pouvoir déléguer du travail. Les politiques d’autorisation et d’interdiction propres au canal/groupe, au fournisseur, au bac à sable et à chaque agent peuvent encore retirer l’outil après l’étape du profil. Utilisez /tools depuis la même session pour confirmer la liste effective des outils.

Valeurs par défaut :

• Modèle : les sous-agents natifs héritent du modèle de l’appelant, sauf si vous définissez agents.defaults.subagents.model (ou agents.list[].subagents.model pour chaque agent). Les lancements dans l’environnement d’exécution ACP utilisent le même modèle de sous-agent configuré lorsqu’il est présent ; sinon, le banc d’essai ACP conserve sa propre valeur par défaut. Une valeur explicite de sessions_spawn.model reste prioritaire.
• Raisonnement : les sous-agents natifs héritent du réglage de l’appelant, sauf si vous définissez agents.defaults.subagents.thinking (ou agents.list[].subagents.thinking pour chaque agent). Les lancements dans l’environnement d’exécution ACP appliquent également agents.defaults.models["provider/model"].params.thinking pour le modèle sélectionné. Une valeur explicite de sessions_spawn.thinking reste prioritaire.
• Délai maximal d’exécution : OpenClaw utilise agents.defaults.subagents.runTimeoutSeconds lorsqu’il est défini ; sinon, il revient à 0 (aucun délai maximal). sessions_spawn n’accepte pas de remplacement du délai maximal pour chaque appel.
• Remise de la tâche : les sous-agents natifs reçoivent la tâche déléguée dans leur premier message visible [Subagent Task]. L’invite système du sous-agent contient les règles d’exécution et le contexte de routage, et non une copie cachée de la tâche.

Les lancements de sous-agents natifs acceptés incluent les métadonnées résolues du modèle enfant dans le résultat de l’outil : resolvedModel contient la référence du modèle appliqué et resolvedProvider contient le préfixe du fournisseur lorsque la référence en comporte un.

Mode d’invite de délégation

agents.defaults.subagents.delegationMode contrôle uniquement les consignes de l’invite ; il ne modifie pas la politique d’outils et n’impose pas la délégation.

• suggest (par défaut) : conserve l’incitation standard de l’invite à utiliser des sous-agents pour les travaux plus importants ou plus lents.
• prefer : demande à l’agent principal de rester réactif et de déléguer, via sessions_spawn, toute tâche plus complexe qu’une réponse directe.

Remplacement propre à chaque agent : agents.list[].subagents.delegationMode.

{  agents: {    defaults: {      subagents: {        delegationMode: "prefer",        maxConcurrent: 4,      },    },    list: [      {        id: "coordinator",        subagents: { delegationMode: "prefer" },      },    ],  },}

Paramètres de l’outil

Noms de tâches et ciblage

taskName est un identifiant destiné au modèle pour l’orchestration, et non une clé de session. Utilisez-le pour des noms d’enfants stables tels que review_subagents, linux_validation ou docs_update lorsqu’un coordinateur peut avoir besoin d’inspecter cet enfant ultérieurement.

La résolution de cible accepte les correspondances exactes de taskName et les préfixes non ambigus. La correspondance est limitée à la même fenêtre de cibles actives/récentes que celle utilisée par les cibles /subagents numérotées, de sorte qu’un ancien enfant terminé ne rende pas ambigu un identifiant réutilisé. Si deux enfants actifs ou récents partagent le même taskName, la cible est ambiguë ; utilisez plutôt l’index de la liste, la clé de session ou l’identifiant d’exécution.

Les cibles réservées last et all ne sont pas des valeurs taskName valides, car elles possèdent déjà une signification de contrôle.

Outil : sessions_yield

Met fin au tour actuel du modèle et attend que les événements d’exécution, principalement les événements de fin des sous-agents, arrivent dans le message suivant. Utilisez-le après avoir lancé le travail enfant requis lorsque le demandeur ne peut pas produire de réponse finale avant la réception de ces résultats.

sessions_yield est la primitive d’attente. Ne la remplacez pas par des boucles d’interrogation utilisant subagents, sessions_list, sessions_history, la commande shell sleep ou l’interrogation des processus uniquement pour détecter la fin d’un enfant.

Utilisez sessions_yield uniquement lorsque la liste effective des outils de la session l’inclut. Certains profils d’outils minimaux ou personnalisés peuvent exposer sessions_spawn et subagents sans exposer sessions_yield ; dans ce cas, n’inventez pas de boucle d’interrogation uniquement pour attendre la fin.

Lorsque des enfants actifs existent, OpenClaw injecte dans les tours normaux un bloc d’invite compact Active Subagents, généré à l’exécution, afin que le demandeur puisse voir les sessions enfants actuelles, les identifiants d’exécution, les états, les libellés, les tâches et les alias taskName sans interrogation. Les champs de tâche et de libellé de ce bloc sont cités en tant que données, et non en tant qu’instructions, car ils peuvent provenir d’arguments de lancement fournis par l’utilisateur ou le modèle.

Outil : subagents

Répertorie les exécutions de sous-agents lancées et détenues par la session du demandeur. Sa portée est limitée au demandeur actuel ; un enfant ne peut voir que les enfants qu’il contrôle lui-même.

Utilisez subagents pour consulter l’état à la demande et effectuer le débogage. Utilisez sessions_yield pour attendre les événements de fin.

Sessions associées à un fil

Lorsque les associations à des fils sont activées pour un canal, un sous-agent peut rester associé à un fil afin que les messages de suivi de l’utilisateur dans ce fil continuent d’être acheminés vers la même session de sous-agent.

Canaux prenant en charge les fils

Un canal prend en charge les sessions persistantes de sous-agents associées à un fil (sessions_spawn avec thread: true) lorsqu’il enregistre un adaptateur d’association de conversation. Canaux intégrés offrant cette prise en charge : Discord, iMessage, Matrix et Telegram. Discord et Matrix créent par défaut un fil enfant ; Telegram et iMessage associent par défaut la conversation actuelle. Utilisez les clés de configuration threadBindings propres à chaque canal pour l’activation, les délais d’expiration et spawnSessions.

Déroulement rapide

Commandes manuelles

Options de configuration

• Valeurs globales par défaut : session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Les clés de remplacement par canal et d’association automatique au lancement sont propres à l’adaptateur. Consultez Canaux prenant en charge les fils ci-dessus.

Consultez la Référence de configuration et les Commandes à barre oblique pour connaître les détails actuels des adaptateurs.

Liste d’autorisation

Si la session du demandeur est isolée, sessions_spawn refuse les cibles qui s’exécuteraient sans isolation.

Découverte

Utilisez agents_list pour voir quels identifiants d’agents sont actuellement autorisés pour sessions_spawn. La réponse inclut le modèle effectif de chaque agent répertorié ainsi que les métadonnées intégrées de son environnement d’exécution, afin que les appelants puissent distinguer OpenClaw, le serveur d’application Codex et les autres environnements natifs configurés.

Les entrées allowAgents doivent désigner des identifiants d’agents configurés dans agents.list[]. ["*"] désigne tout agent cible configuré ainsi que le demandeur. Si la configuration d’un agent est supprimée mais que son identifiant reste dans allowAgents, sessions_spawn refuse cet identifiant et agents_list l’omet. Exécutez openclaw doctor --fix pour nettoyer les entrées obsolètes de la liste d’autorisation, ou ajoutez une entrée agents.list[] minimale lorsque la cible doit rester disponible au lancement tout en héritant des valeurs par défaut.

Archivage automatique

• Les sessions de sous-agents sont automatiquement archivées après agents.defaults.subagents.archiveAfterMinutes (valeur par défaut : 60).
• L’archivage utilise sessions.delete et renomme la transcription en *.deleted.<timestamp> (dans le même dossier).
• cleanup: "delete" archive immédiatement après l’annonce (la transcription reste conservée par renommage).
• L’archivage automatique s’effectue au mieux ; les minuteries en attente sont perdues si le Gateway redémarre.
• Les délais d’expiration d’exécution configurés n’archivent pas automatiquement ; ils arrêtent uniquement l’exécution. La session reste présente jusqu’à son archivage automatique.
• L’archivage automatique s’applique de la même manière aux sessions de profondeur 1 et 2.
• Le nettoyage du navigateur est distinct du nettoyage d’archivage : la fermeture des onglets/processus de navigateur suivis est tentée au mieux à la fin de l’exécution, même si la transcription ou l’enregistrement de session est conservé.

Sous-agents imbriqués

Par défaut, les sous-agents ne peuvent pas lancer leurs propres sous-agents (maxSpawnDepth: 1). Définissez maxSpawnDepth: 2 pour activer un niveau d’imbrication — le modèle d’orchestrateur : principal → sous-agent orchestrateur → sous-sous-agents exécutants.

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2, // autorise les sous-agents à lancer des enfants (par défaut : 1, plage 1-5)        maxChildrenPerAgent: 5, // nombre maximal d’enfants actifs par session d’agent (par défaut : 5, plage 1-20)        maxConcurrent: 8, // limite globale de la file de concurrence (par défaut : 8)        runTimeoutSeconds: 900, // délai d’expiration par défaut de sessions_spawn (0 = aucun délai)        announceTimeoutMs: 120000, // délai d’expiration par appel pour l’annonce du Gateway      },    },  },}

Niveaux de profondeur

Chaîne d’annonce

Les résultats remontent la chaîne :

1. L’agent d’exécution de profondeur 2 termine → envoie une annonce à son parent (orchestrateur de profondeur 1).
2. L’orchestrateur de profondeur 1 reçoit l’annonce, synthétise les résultats, termine → envoie une annonce à l’agent principal.
3. L’agent principal reçoit l’annonce et transmet le résultat à l’utilisateur.

Chaque niveau ne voit que les annonces de ses enfants directs.

Politique des outils selon la profondeur

• Le rôle et la portée de contrôle sont inscrits dans les métadonnées de session lors de la création. Cela empêche des clés de session aplaties ou restaurées de récupérer accidentellement des privilèges d’orchestrateur.
• Profondeur 1 (orchestrateur, lorsque maxSpawnDepth >= 2) : reçoit sessions_spawn, subagents, sessions_list, sessions_history afin de pouvoir créer des enfants et examiner leur état. Les autres outils de session ou système restent refusés.
• Profondeur 1 (agent terminal, lorsque maxSpawnDepth == 1) : aucun outil de session (comportement actuel par défaut).
• Profondeur 2 (agent d’exécution terminal) : aucun outil de session — sessions_spawn est toujours refusé à la profondeur 2. Il ne peut pas créer d’autres enfants.

Limite de création par agent

Chaque session d’agent (quelle que soit sa profondeur) peut avoir au maximum maxChildrenPerAgent (par défaut 5) enfants actifs simultanément. Cela empêche une expansion incontrôlée depuis un même orchestrateur.

Arrêt en cascade

L’arrêt d’un orchestrateur de profondeur 1 arrête automatiquement tous ses enfants de profondeur 2 :

• /stop dans la discussion principale arrête tous les agents de profondeur 1 et se propage à leurs enfants de profondeur 2.

Authentification

L’authentification des sous-agents est déterminée par l’identifiant de l’agent, et non par le type de session :

• La clé de session du sous-agent est agent:<agentId>:subagent:<uuid>.
• Le magasin d’authentification est chargé depuis l’agentDir de cet agent.
• Les profils d’authentification de l’agent principal sont fusionnés en tant que solution de repli ; les profils de l’agent prévalent sur ceux de l’agent principal en cas de conflit.

La fusion est additive : les profils principaux restent donc toujours disponibles comme solutions de repli. L’isolation complète de l’authentification par agent n’est pas encore prise en charge.

Annonce

Les sous-agents rendent compte par une étape d’annonce :

• L’étape d’annonce s’exécute dans la session du sous-agent (et non dans celle du demandeur).
• Si le sous-agent répond exactement ANNOUNCE_SKIP, rien n’est publié.
• Si le texte le plus récent de l’assistant est le jeton silencieux exact NO_REPLY / no_reply, la sortie de l’annonce est supprimée, même si une progression visible existait auparavant.

La livraison dépend de la profondeur du demandeur :

• Les sessions de demandeur de premier niveau utilisent un appel agent de suivi avec livraison externe (deliver=true).
• Les sessions de sous-agent demandeur imbriquées reçoivent une injection interne de suivi (deliver=false) afin que l’orchestrateur puisse synthétiser les résultats des enfants au sein de la session.
• Si une session de sous-agent demandeur imbriquée n’existe plus, OpenClaw se replie sur le demandeur de cette session lorsqu’il est disponible.

Pour les sessions de demandeur de premier niveau, la livraison directe en mode achèvement commence par résoudre toute route de conversation ou de fil liée ainsi que toute substitution par un hook, puis complète les champs de canal et de cible manquants à partir de la route enregistrée dans la session du demandeur. Ainsi, les achèvements restent associés à la bonne discussion ou au bon sujet, même lorsque l’origine de l’achèvement n’identifie que le canal.

Lors de la construction des résultats d’achèvement imbriqués, l’agrégation des achèvements des enfants est limitée à l’exécution actuelle du demandeur, ce qui empêche les sorties d’enfants d’exécutions antérieures de se retrouver dans l’annonce actuelle. Les réponses d’annonce préservent le routage du fil ou du sujet lorsqu’il est disponible dans les adaptateurs de canal.

Contexte de l’annonce

Le contexte de l’annonce est normalisé sous la forme d’un bloc d’événement interne stable :

Les exécutions terminales ayant échoué signalent l’état d’échec sans reproduire le texte de réponse capturé. La sortie tool/toolResult n’est pas promue en texte de résultat de l’enfant.

Ligne de statistiques

Les charges utiles d’annonce comprennent une ligne de statistiques à la fin (même lorsqu’elles sont enveloppées) :

• Durée d’exécution (par exemple runtime 5m12s).
• Utilisation des jetons (entrée/sortie/total).
• Coût estimé lorsque la tarification des modèles est configurée (models.providers.*.models[].cost).
• sessionKey, sessionId et chemin de la transcription afin que l’agent principal puisse récupérer l’historique via sessions_history ou examiner le fichier sur le disque.

Les métadonnées internes sont réservées à l’orchestration ; les réponses destinées aux utilisateurs doivent être reformulées dans le ton habituel de l’assistant.

Pourquoi préférer sessions_history

sessions_history constitue la voie d’orchestration la plus sûre pour lire la transcription d’un enfant pendant un tour d’agent :

• Masque les textes ressemblant à des identifiants ou des jetons, même lorsque le masquage général des journaux est désactivé.
• Tronque les longs blocs de texte (4 000 caractères par bloc) et supprime les signatures de réflexion, les charges utiles de répétition du raisonnement et les données d’image intégrées.
• Impose une limite de réponse de 80 Ko ; les lignes trop volumineuses sont remplacées par [sessions_history omitted: message too large].
• Utilisez nextOffset lorsqu’il est présent pour parcourir à rebours les fenêtres plus anciennes de la transcription.
• sessions_history ne supprime pas les balises de raisonnement, la structure <relevant-memories> ni le XML des appels d’outils du texte des messages — il renvoie des blocs de contenu structurés proches de la forme brute de la transcription, mais masqués et limités en taille. /subagents log applique un assainissement textuel plus poussé (suppression des balises de raisonnement, de la structure de mémoire et du XML des appels d’outils), car il affiche des lignes de discussion en texte simple plutôt que des blocs structurés.
• L’examen de la transcription brute sur le disque est la solution de repli lorsque vous avez besoin de la transcription complète, octet pour octet.

Politique des outils

Les sous-agents utilisent d’abord le même profil et la même chaîne de politique des outils que l’agent parent ou cible. OpenClaw applique ensuite la couche de restrictions propre aux sous-agents.

Les sous-agents perdent toujours gateway, agents_list, session_status et cron, indépendamment de leur profondeur ou de leur rôle (outils système/interactifs, ou outils que l’agent principal doit coordonner). Les sous-agents terminaux (comportement par défaut à la profondeur 1, et toujours à la profondeur 2) perdent également subagents, sessions_list, sessions_history et sessions_spawn. Les sous-agents ne reçoivent jamais l’outil message — il est désactivé lors de la création, et non filtré par cette liste de refus — et sessions_send reste refusé afin que les sous-agents communiquent uniquement par la chaîne d’annonce.

sessions_history reste ici aussi une vue de rappel limitée et assainie — il ne s’agit pas d’un export brut de la transcription.

Lorsque maxSpawnDepth >= 2, les sous-agents orchestrateurs de profondeur 1 reçoivent en plus sessions_spawn, subagents, sessions_list et sessions_history afin de pouvoir gérer leurs enfants.

Substitution par la configuration

{  agents: {    defaults: {      subagents: {        maxConcurrent: 1,      },    },  },  tools: {    subagents: {      tools: {        // deny wins        deny: ["gateway", "cron"],        // if allow is set, it becomes allow-only (deny still wins)        // allow: ["read", "exec", "process"]      },    },  },}

tools.subagents.tools.allow est un filtre final limité aux éléments autorisés. Il peut restreindre l’ensemble d’outils déjà déterminé, mais il ne peut pas rajouter un outil supprimé par tools.profile. Par exemple, tools.profile: "coding" inclut web_search/web_fetch, mais pas l’outil browser. Pour permettre aux sous-agents du profil de codage d’utiliser l’automatisation du navigateur, ajoutez le navigateur à l’étape du profil :

{  tools: {    profile: "coding",    alsoAllow: ["browser"],  },}

Utilisez agents.list[].tools.alsoAllow: ["browser"] par agent lorsqu’un seul agent doit disposer de l’automatisation du navigateur.

Concurrence

Les sous-agents utilisent une file d’attente dédiée au sein du processus :

• Nom de la file : subagent
• Concurrence : agents.defaults.subagents.maxConcurrent (par défaut 8)

Activité et récupération

OpenClaw ne considère pas l’absence de endedAt comme une preuve permanente qu’un sous-agent est toujours actif. Les exécutions non terminées plus anciennes que la fenêtre d’obsolescence (2 heures, ou le délai d’expiration configuré de l’exécution augmenté d’une courte période de grâce, selon la durée la plus longue) cessent d’être comptabilisées comme actives ou en attente dans /subagents list, les résumés d’état, le blocage de l’achèvement des descendants et les vérifications de concurrence par session.

Après un redémarrage du Gateway, les exécutions restaurées obsolètes et non terminées sont élaguées, sauf si leur session enfant porte la marque abortedLastRun: true. Les exécutions interrompues par le redémarrage restent enregistrées pour le processus de récupération des sous-agents orphelins : les exécutions obsolètes sont finalisées sans reprise, tandis que les sessions enfants récentes reçoivent un message de reprise synthétique avant que le marqueur d’interruption soit effacé.

La récupération automatique après redémarrage est limitée par session enfant. Si le même enfant sous-agent est accepté à plusieurs reprises pour une récupération d’orphelin pendant la fenêtre de blocages répétés rapides, OpenClaw enregistre un marqueur définitif de récupération dans cette session et cesse de la reprendre automatiquement lors des redémarrages ultérieurs. Exécutez openclaw tasks maintenance --apply pour réconcilier l’enregistrement de tâche, ou openclaw doctor --fix pour effacer les indicateurs obsolètes de récupération interrompue dans les sessions ainsi marquées.

Arrêt

• L’envoi de /stop dans la discussion du demandeur interrompt la session du demandeur et arrête toutes les exécutions actives de sous-agents créées depuis celle-ci, avec propagation aux enfants imbriqués.

Limitations

• L’annonce du sous-agent s’effectue dans la mesure du possible. Si le Gateway redémarre, les tâches « announce back » en attente sont perdues.
• Les sous-agents partagent toujours les ressources du même processus Gateway ; considérez maxConcurrent comme une soupape de sécurité.
• sessions_spawn est toujours non bloquant : il renvoie immédiatement { status: "accepted", runId, childSessionKey }.
• Le contexte du sous-agent injecte uniquement AGENTS.md et TOOLS.md (sans SOUL.md, IDENTITY.md, USER.md, MEMORY.md, HEARTBEAT.md ni BOOTSTRAP.md). Les sous-agents natifs de Codex respectent la même limite : TOOLS.md reste dans les instructions héritées du fil Codex, tandis que les fichiers de personnalité, d’identité et d’utilisateur propres au parent sont injectés sous forme d’instructions de collaboration limitées au tour, afin que les enfants ne les clonent pas.
• La profondeur maximale d’imbrication est de 5 (plage de maxSpawnDepth : 1 à 5). Une profondeur de 2 est recommandée pour la plupart des cas d’utilisation.
• maxChildrenPerAgent limite le nombre d’enfants actifs par session (valeur par défaut : 5, plage : 1 à 20).

Voir aussi

• Outils de session et changements d’état
• Agents ACP
• Envoi d’agent
• Tâches en arrière-plan
• Outils de bac à sable multi-agents