Sous-agents

Les sous-agents sont des exécutions d’agent en arrière-plan lancées depuis une exécution d’agent existante. Ils s’exécutent dans leur propre session (agent:<agentId>:subagent:<uuid>) et, une fois terminés, annoncent leur résultat au canal de discussion demandeur. Chaque exécution de sous-agent est suivie comme une tâche en arrière-plan.

Pour le modèle de sécurité derrière la délégation, consultez Limites multi-agents et sous-agents. Les sous-agents sont des unités utiles d’isolation et de workflow, mais ils ne constituent pas une frontière d’autorisation multi-locataire hostile au sein d’un Gateway partagé.

Objectifs principaux :

• Paralléliser le travail de « recherche / tâche longue / outil lent » sans bloquer l’exécution principale.
• Garder les sous-agents isolés par défaut (séparation de session + sandboxing optionnel).
• Rendre la surface d’outils difficile à mal utiliser : les sous-agents n’obtiennent pas les outils de session par défaut.
• Prendre en charge une profondeur d’imbrication configurable pour les modèles d’orchestrateur.

# Commande slash

Utilisez /subagents pour inspecter ou contrôler les exécutions de sous-agent pour la session actuelle :

/subagents list
/subagents kill <id|#|all>
/subagents log <id|#> [limit] [tools]
/subagents info <id|#>
/subagents send <id|#> <message>
/subagents steer <id|#> <message>
/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]

Utilisez /steer <message> au niveau supérieur pour orienter l’exécution active de la session demandeuse actuelle. Utilisez /subagents steer <id|#> <message> lorsque la cible est une exécution enfant.

/subagents info affiche les métadonnées d’exécution (statut, horodatages, identifiant de session, chemin de transcription, nettoyage). Utilisez sessions_history pour une vue de rappel bornée et filtrée pour la sécurité ; inspectez le chemin de transcription sur disque lorsque vous avez besoin de la transcription brute complète.

# Contrôles de liaison au fil

Ces commandes fonctionnent sur les canaux qui prennent en charge les liaisons de fil 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 de lancement

/subagents spawn démarre un sous-agent en arrière-plan comme commande utilisateur (et non comme relais interne) et envoie une mise à jour finale d’achèvement au chat demandeur lorsque l’exécution se termine.

# Modes de contexte

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

Mode	Quand l’utiliser	Comportement
isolated	Recherche nouvelle, implémentation indépendante, travail d’outil lent ou toute tâche pouvant être expliquée dans le texte de tâche	Crée une transcription enfant propre. C’est la valeur par défaut et cela réduit l’utilisation des jetons.
fork	Travail qui dépend de la conversation actuelle, des résultats d’outils précédents ou d’instructions nuancées déjà présentes dans la transcription du demandeur	Branche la transcription du demandeur dans la session enfant avant le démarrage de l’enfant.

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

# Outil : sessions_spawn

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

La disponibilité dépend de la politique d’outils effective de l’appelant. Les profils coding et full exposent sessions_spawn par défaut. Le profil messaging ne le fait pas ; ajoutez tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"] ou utilisez tools.profile: "coding" pour les agents qui doivent déléguer du travail. Les politiques de canal/groupe, de fournisseur, de sandbox et d’autorisation/refus par agent peuvent toujours retirer l’outil après l’étape de profil. Utilisez /tools depuis la même session pour confirmer la liste d’outils effective.

Valeurs par défaut :

• Modèle : hérite de l’appelant sauf si vous définissez agents.defaults.subagents.model (ou agents.list[].subagents.model par agent) ; un sessions_spawn.model explicite prévaut toujours.
• Thinking : hérite de l’appelant sauf si vous définissez agents.defaults.subagents.thinking (ou agents.list[].subagents.thinking par agent) ; un sessions_spawn.thinking explicite prévaut toujours.
• Délai d’exécution : si sessions_spawn.runTimeoutSeconds est omis, OpenClaw utilise agents.defaults.subagents.runTimeoutSeconds lorsqu’il est défini ; sinon il revient à 0 (aucun délai).

# Paramètres de l’outil

taskstringrequired

La description de tâche pour le sous-agent.

labelstring

Libellé lisible par un humain, optionnel.

agentIdstring

Lancer sous un autre identifiant d’agent lorsque subagents.allowAgents l’autorise.

runtime"subagent" | "acp"

acp est réservé aux harnais ACP externes (claude, droid, gemini, opencode ou Codex ACP/acpx explicitement demandé) et aux entrées agents.list[] dont runtime.type est acp.

resumeSessionIdstring

ACP uniquement. Reprend une session de harnais ACP existante lorsque runtime: "acp" ; ignoré pour les lancements de sous-agent natifs.

streamTo"parent"

ACP uniquement. Diffuse la sortie d’exécution ACP vers la session parente lorsque runtime: "acp" ; omettez pour les lancements de sous-agent natifs.

modelstring

Remplace le modèle du sous-agent. Les valeurs invalides sont ignorées et le sous-agent s’exécute sur le modèle par défaut avec un avertissement dans le résultat de l’outil.

thinkingstring

Remplace le niveau de réflexion pour l’exécution du sous-agent.

runTimeoutSecondsnumber

Par défaut, vaut agents.defaults.subagents.runTimeoutSeconds lorsqu’il est défini, sinon 0. Lorsqu’il est défini, l’exécution du sous-agent est abandonnée après N secondes.

threadboolean

Lorsque true, demande une liaison de fil de canal pour cette session de sous-agent.

mode"run" | "session"

Si thread: true et que mode est omis, la valeur par défaut devient session. mode: "session" nécessite thread: true.

cleanup"delete" | "keep"

"delete" archive immédiatement après l’annonce (conserve tout de même la transcription via renommage).

sandbox"inherit" | "require"

require refuse le lancement sauf si le runtime enfant cible est sandboxé.

context"isolated" | "fork"

fork branche la transcription actuelle du demandeur dans la session enfant. Sous-agents natifs uniquement. Les lancements liés à un fil utilisent par défaut fork ; les lancements non liés à un fil utilisent par défaut isolated.

# Sessions liées à un fil

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

# Canaux prenant en charge les fils

Discord est actuellement le seul canal pris en charge. Il prend en charge les sessions de sous-agent persistantes liées à un fil (sessions_spawn avec thread: true), les contrôles manuels de fil (/focus, /unfocus, /agents, /session idle, /session max-age) et les clés d’adaptateur channels.discord.threadBindings.enabled, channels.discord.threadBindings.idleHours, channels.discord.threadBindings.maxAgeHours et channels.discord.threadBindings.spawnSessions.

# Flux rapide

# Contrôles manuels

Commande	Effet
/focus <target>	Lie le fil actuel (ou en crée un) à une cible de sous-agent/session
/unfocus	Supprime la liaison pour le fil actuellement lié
/agents	Liste les exécutions actives et l’état de liaison (thread:<id> ou unbound)
/session idle	Inspecte/met à jour le désenclenchement automatique en cas d’inactivité (fils liés ciblés uniquement)
/session max-age	Inspecte/met à jour la limite stricte (fils liés ciblés uniquement)

# Commutateurs de configuration

• Valeur par défaut globale : session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Les clés de remplacement par canal et de liaison automatique à la génération sont propres à l’adaptateur. Voir Canaux prenant en charge les fils ci-dessus.

Voir la référence de configuration et les commandes slash pour les détails actuels des adaptateurs.

# Liste d’autorisation

agents.list[].subagents.allowAgentsstring[]

Liste des ids d’agents pouvant être ciblés via agentId explicite (["*"] autorise n’importe lequel). Par défaut : uniquement l’agent demandeur. Si vous définissez une liste et souhaitez toujours que le demandeur se génère lui-même avec agentId, incluez l’id du demandeur dans la liste.

agents.defaults.subagents.allowAgentsstring[]

Liste d’autorisation des agents cibles par défaut utilisée lorsque l’agent demandeur ne définit pas son propre subagents.allowAgents.

agents.defaults.subagents.requireAgentIdboolean

Bloque les appels sessions_spawn qui omettent agentId (force la sélection explicite d’un profil). Remplacement par agent : agents.list[].subagents.requireAgentId.

Si la session du demandeur est en sandbox, sessions_spawn rejette les cibles qui s’exécuteraient sans sandbox.

# Découverte

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

# Archivage automatique

• Les sessions de sous-agent sont automatiquement archivées après agents.defaults.subagents.archiveAfterMinutes (par défaut 60).
• L’archivage utilise sessions.delete et renomme la transcription en *.deleted.<timestamp> (même dossier).
• cleanup: "delete" archive immédiatement après l’annonce (conserve tout de même la transcription via renommage).
• L’archivage automatique est effectué au mieux ; les minuteurs en attente sont perdus si le Gateway redémarre.
• runTimeoutSeconds n’archive pas automatiquement ; il arrête seulement l’exécution. La session reste jusqu’à l’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 séparé du nettoyage d’archive : les onglets/processus de navigateur suivis sont fermés au mieux lorsque l’exécution se termine, même si la transcription/l’enregistrement de session est conservé.

# Sous-agents imbriqués

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

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)
        maxChildrenPerAgent: 5, // max active children per agent session (default: 5)
        maxConcurrent: 8, // global concurrency lane cap (default: 8)
        runTimeoutSeconds: 900, // default timeout for sessions_spawn when omitted (0 = no timeout)
      },
    },
  },
}

# Niveaux de profondeur

Profondeur	Forme de la clé de session	Rôle	Peut générer ?
0	agent:<id>:main	Agent principal	Toujours
1	agent:<id>:subagent:<uuid>	Sous-agent (orchestrateur lorsque la profondeur 2 est autorisée)	Seulement si maxSpawnDepth >= 2
2	agent:<id>:subagent:<uuid>:subagent:<uuid>	Sous-sous-agent (worker feuille)	Jamais

# Chaîne d’annonce

Les résultats remontent la chaîne :

1. Le worker de profondeur 2 termine → annonce à son parent (orchestrateur de profondeur 1).
2. L’orchestrateur de profondeur 1 reçoit l’annonce, synthétise les résultats, termine → annonce au principal.
3. L’agent principal reçoit l’annonce et la transmet à l’utilisateur.

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

# Politique des outils par profondeur

• Le rôle et la portée de contrôle sont écrits dans les métadonnées de session au moment de la génération. Cela empêche les clés de session plates 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 gérer ses enfants. Les autres outils de session/système restent refusés.
• Profondeur 1 (feuille, lorsque maxSpawnDepth == 1) : aucun outil de session (comportement actuel par défaut).
• Profondeur 2 (worker feuille) : aucun outil de session — sessions_spawn est toujours refusé à la profondeur 2. Ne peut pas générer d’autres enfants.

# Limite de génération par agent

Chaque session d’agent (à n’importe quelle profondeur) peut avoir au plus maxChildrenPerAgent (par défaut 5) enfants actifs à la fois. Cela empêche un déploiement incontrôlé depuis un seul orchestrateur.

# Arrêt en cascade

Arrêter un orchestrateur de profondeur 1 arrête automatiquement tous ses enfants de profondeur 2 :

• /stop dans le chat principal arrête tous les agents de profondeur 1 et se propage à leurs enfants de profondeur 2.
• /subagents kill <id> arrête un sous-agent précis et se propage à ses enfants.
• /subagents kill all arrête tous les sous-agents du demandeur et se propage.

# Authentification

L’authentification du sous-agent est résolue par id d’agent, et non par type de session :

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

La fusion est additive, donc les profils principaux sont toujours disponibles comme solutions de repli. L’authentification entièrement isolée par agent n’est pas encore prise en charge.

# Annonce

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

• L’étape d’annonce s’exécute dans la session du sous-agent (pas dans la session du demandeur).
• Si le sous-agent répond exactement ANNOUNCE_SKIP, rien n’est publié.
• Si le dernier texte de l’assistant est le jeton silencieux exact NO_REPLY / no_reply, la sortie d’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 niveau supérieur utilisent un appel agent de suivi avec livraison externe (deliver=true).
• Les sessions de sous-agent demandeur imbriquées reçoivent une injection de suivi interne (deliver=false) afin que l’orchestrateur puisse synthétiser les résultats enfants en session.
• Si une session de sous-agent demandeur imbriquée a disparu, OpenClaw se rabat sur le demandeur de cette session lorsqu’il est disponible.

Pour les sessions de demandeur de niveau supérieur, la livraison directe en mode achèvement résout d’abord toute route de conversation/fil liée et tout remplacement de hook, puis remplit les champs de cible de canal manquants à partir de la route stockée de la session demandeuse. Cela garde les achèvements dans le bon chat/sujet même lorsque l’origine de l’achèvement identifie seulement le canal.

L’agrégation des fins d’enfants est limitée à l’exécution actuelle du demandeur lors de la création des conclusions d’achèvement imbriquées, empêchant les sorties d’enfants d’exécutions précédentes obsolètes de fuir dans l’annonce actuelle. Les réponses d’annonce préservent le routage de fil/sujet lorsqu’il est disponible sur les adaptateurs de canal.

# Contexte d’annonce

Le contexte d’annonce est normalisé en bloc d’événement interne stable :

Champ	Source
Source	subagent ou cron
Ids de session	Clé/id de session enfant
Type	Type d’annonce + libellé de tâche
Statut	Dérivé du résultat d’exécution (success, error, timeout ou unknown) — pas déduit du texte du modèle
Contenu du résultat	Dernier texte visible de l’assistant, sinon dernier texte d’outil/toolResult assaini
Suivi	Instruction décrivant quand répondre ou rester silencieux

Les exécutions terminales échouées signalent un statut d’échec sans rejouer le texte de réponse capturé. En cas de délai d’expiration, si l’enfant n’a effectué que des appels d’outils, l’annonce peut condenser cet historique en un court résumé de progression partielle au lieu de rejouer la sortie brute des outils.

# Ligne de statistiques

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

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

Les métadonnées internes sont destinées uniquement à l’orchestration ; les réponses destinées aux utilisateurs doivent être réécrites dans la voix normale de l’assistant.

# Pourquoi préférer sessions_history

sessions_history est le chemin d’orchestration le plus sûr :

• Le rappel de l’assistant est d’abord normalisé : balises de réflexion supprimées ; échafaudage <relevant-memories> / <relevant_memories> supprimé ; blocs de charges utiles XML d’appels d’outils en texte brut (<tool_call>, <function_call>, <tool_calls>, <function_calls>) supprimés, y compris les charges utiles tronquées qui ne se ferment jamais proprement ; échafaudage d’appels/résultats d’outils rétrogradé et marqueurs de contexte historique supprimés ; jetons de contrôle de modèle ayant fui (<|assistant|>, autres <|...|> ASCII, <｜...｜> pleine chasse) supprimés ; XML d’appels d’outils MiniMax malformé supprimé.
• Le texte ressemblant à des identifiants/jetons est expurgé.
• Les longs blocs peuvent être tronqués.
• Les très grands historiques peuvent supprimer les anciennes lignes ou remplacer une ligne surdimensionnée par [sessions_history omitted: message too large].
• L’inspection de la transcription brute sur 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 le même pipeline de politique des outils que l’agent parent ou cible. Ensuite, OpenClaw applique la couche de restriction des sous-agents.

Sans tools.profile restrictif, les sous-agents obtiennent tous les outils sauf les outils de session et les outils système :

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

sessions_history reste ici aussi une vue de rappel bornée et assainie — ce n’est pas un vidage brut de 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.

# Remplacement via 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 d’autorisation uniquement. Il peut restreindre l’ensemble d’outils déjà résolu, 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 avec le profil coding d’utiliser l’automatisation du navigateur, ajoutez browser à l’étape du profil :

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

Utilisez agents.list[].tools.alsoAllow: ["browser"] par agent lorsque seul un agent doit bénéficier de l’automatisation du navigateur.

# Concurrence

Les sous-agents utilisent une file dédiée dans le processus :

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

# Vivacité et récupération

OpenClaw ne considère pas l’absence de endedAt comme une preuve permanente qu’un sous-agent est encore vivant. Les exécutions non terminées plus anciennes que la fenêtre d’exécution obsolète cessent d’être comptées comme actives/en attente dans /subagents list, les résumés d’état, le verrouillage de fin des descendants et les contrôles 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 est marquée abortedLastRun: true. Ces sessions enfants interrompues par le redémarrage restent récupérables via le flux de récupération des sous-agents orphelins, qui envoie un message synthétique de reprise avant d’effacer le marqueur d’interruption.

La récupération automatique après redémarrage est bornée par session enfant. Si le même enfant de sous-agent est accepté à plusieurs reprises pour récupération d’orphelin dans la fenêtre de réenclenchement rapide, OpenClaw conserve une pierre tombale de récupération sur 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 de récupération interrompue obsolètes sur les sessions avec pierre tombale.

# 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 lancées depuis celle-ci, avec propagation aux enfants imbriqués.
• /subagents kill <id> arrête un sous-agent spécifique et se propage à ses enfants.

# Limitations

• L’annonce des sous-agents est effectuée au mieux. Si le gateway redémarre, le travail « announce back » en attente est perdu.
• Les sous-agents partagent toujours les mêmes ressources de 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 des sous-agents injecte uniquement AGENTS.md + TOOLS.md (pas de SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md ni BOOTSTRAP.md).
• La profondeur maximale d’imbrication est de 5 (plage de maxSpawnDepth : 1–5). La profondeur 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).

# Connexe

• Agents ACP
• Envoi à l’agent
• Tâches en arrière-plan
• Outils de bac à sable multi-agent