Boucle de l’agent

La boucle de l’agent est l’exécution sérialisée propre à chaque session qui transforme un message en actions et en réponse : réception, assemblage du contexte, inférence du modèle, exécution des outils, diffusion en continu, persistance.

​

Points d’entrée

• RPC du Gateway : agent et agent.wait.
• CLI : openclaw agent.

​

Séquence d’exécution

1. Le RPC agent valide les paramètres, résout la session (sessionKey/sessionId), conserve les métadonnées de session et renvoie immédiatement { runId, acceptedAt }.
2. agentCommand exécute le tour : résout le modèle et les valeurs par défaut de réflexion/détail/traçage, charge l’instantané des Skills, appelle runEmbeddedAgent et émet un événement de secours de fin/erreur de cycle de vie si la boucle intégrée n’en a pas déjà émis un.
3. runEmbeddedAgent : sérialise les exécutions au moyen de files d’attente propres à chaque session et globales, résout le modèle et le profil d’authentification, construit la session OpenClaw, s’abonne aux événements d’exécution, diffuse les deltas de l’assistant/des outils, impose le délai d’expiration de l’exécution (avec interruption à son expiration) et renvoie les charges utiles ainsi que les métadonnées d’utilisation. Pour les tours du serveur d’application Codex, il interrompt également un tour accepté qui cesse de produire une progression du serveur d’application avant un événement terminal.
4. subscribeEmbeddedAgentSession relie les événements d’exécution au flux agent : événements d’outils vers stream: "tool", deltas de l’assistant vers stream: "assistant", événements de cycle de vie vers stream: "lifecycle" (phase: "start" | "end" | "error").
5. agent.wait (waitForAgentRun) attend une fin/erreur de cycle de vie pour un runId et renvoie { status: ok|error|timeout, startedAt, endedAt, error? }.

​

Mise en file d’attente et concurrence

Les exécutions sont sérialisées par clé de session (voie de session) et, éventuellement, au moyen d’une voie globale, afin d’éviter les accès concurrents aux outils et aux sessions. Les canaux de messagerie choisissent un mode de file d’attente (steer/followup/collect/interrupt) qui alimente ce système de voies ; consultez File d’attente des commandes. Les écritures de transcription sont en outre protégées par un verrou d’écriture de session sur le fichier de session. Le verrou tient compte des processus et repose sur un fichier ; il détecte donc les processus d’écriture qui contournent la file d’attente interne au processus ou proviennent d’un autre processus. Les processus d’écriture attendent jusqu’à session.writeLock.acquireTimeoutMs (60000 ms par défaut ; remplacement par la variable d’environnement OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS) avant de signaler que la session est occupée. Par défaut, les verrous d’écriture de session ne sont pas réentrants. Un utilitaire qui imbrique intentionnellement l’acquisition du même verrou tout en conservant un seul processus d’écriture logique doit l’activer avec allowReentrant: true.

​

Préparation de la session et de l’espace de travail

• L’espace de travail est résolu et créé ; les exécutions dans un bac à sable peuvent être redirigées vers la racine d’un espace de travail de bac à sable.
• Les Skills sont chargées (ou réutilisées à partir d’un instantané) et injectées dans l’environnement et le prompt.
• Les fichiers d’amorçage et de contexte sont résolus et injectés dans le prompt système.
• Un verrou d’écriture de session est acquis et la cible de transcription de la session est préparée avant le début de la diffusion. Tout chemin ultérieur de réécriture, de compaction ou de troncature de la transcription doit acquérir le même verrou avant de modifier les lignes de transcription SQLite.

​

Assemblage du prompt

Le prompt système est construit à partir du prompt de base d’OpenClaw, du prompt des Skills, du contexte d’amorçage et des remplacements propres à l’exécution. Les limites propres au modèle et les jetons réservés à la compaction sont appliqués. Consultez Prompt système pour savoir ce que voit le modèle.

​

Hooks

OpenClaw comporte deux systèmes de hooks :

• Hooks internes (hooks du Gateway) : scripts pilotés par des événements pour les commandes et les événements de cycle de vie.
• Hooks de Plugin : points d’extension dans le cycle de vie de l’agent/des outils et le pipeline du Gateway.

​

Hooks internes (hooks du Gateway)

• agent:bootstrap : s’exécute pendant la construction des fichiers d’amorçage, avant la finalisation du prompt système. Utilisez-le pour ajouter ou supprimer des fichiers de contexte d’amorçage.
• Hooks de commande : /new, /reset, /stop et autres événements de commande (consultez la documentation sur les hooks).

Consultez Hooks pour la configuration et des exemples.

​

Hooks de Plugin

Ils s’exécutent dans la boucle de l’agent ou le pipeline du Gateway : Règles de décision des hooks pour les protections des sorties/outils :

• before_tool_call : { block: true } est terminal et arrête les gestionnaires de priorité inférieure. { block: false } est sans effet et n’annule pas un blocage antérieur.
• before_install : mêmes sémantiques terminales/sans effet que ci-dessus. Utilisez security.installPolicy, et non before_install, pour les décisions d’autorisation/de blocage d’installation appartenant à l’opérateur qui doivent couvrir les chemins d’installation et de mise à jour de la CLI.
• message_sending : { cancel: true } est terminal et arrête les gestionnaires de priorité inférieure. { cancel: false } est sans effet et n’annule pas une annulation antérieure.

Consultez Hooks de Plugin pour l’API des hooks et les détails d’enregistrement. Les harnais peuvent adapter ces hooks. Le harnais du serveur d’application Codex conserve les hooks de Plugin OpenClaw comme contrat de compatibilité pour les surfaces documentées reproduites ; les hooks natifs de Codex constituent un mécanisme Codex distinct et de plus bas niveau.

​

Diffusion en continu

• Les deltas de l’assistant sont diffusés depuis l’environnement d’exécution de l’agent sous forme d’événements assistant.
• La diffusion par blocs peut émettre des réponses partielles lors de text_end ou message_end.
• La diffusion du raisonnement peut être un flux distinct ou bloquer les réponses.
• Consultez Diffusion en continu pour le découpage et le comportement des réponses par blocs.

​

Exécution des outils

• Les événements de début/mise à jour/fin d’un outil sont émis sur le flux tool.
• La taille et les charges utiles d’images des résultats d’outils sont assainies avant leur journalisation/émission.
• Les envois par les outils de messagerie sont suivis afin d’éviter les confirmations en double de l’assistant.

​

Mise en forme des réponses

Les charges utiles finales sont assemblées à partir du texte de l’assistant (ainsi que du raisonnement facultatif), des résumés intégrés des outils (lorsque le mode détaillé est activé et autorisé) et du texte d’erreur de l’assistant lorsque le modèle rencontre une erreur.

• Le jeton silencieux exact NO_REPLY est supprimé des charges utiles sortantes.
• Les doublons des outils de messagerie sont supprimés de la liste finale des charges utiles.
• S’il ne reste aucune charge utile affichable et qu’un outil a rencontré une erreur, une réponse d’erreur d’outil de secours est émise, sauf si un outil de messagerie a déjà envoyé une réponse visible par l’utilisateur.

​

Compaction et nouvelles tentatives

La compaction automatique émet des événements de flux compaction et peut déclencher une nouvelle tentative. Lors d’une nouvelle tentative, les tampons en mémoire et les résumés des outils sont réinitialisés afin d’éviter les sorties en double. Consultez Compaction.

​

Flux d’événements

• lifecycle : émis par subscribeEmbeddedAgentSession (et comme mécanisme de secours par agentCommand).
• assistant : deltas diffusés depuis l’environnement d’exécution de l’agent.
• tool : événements d’outils diffusés depuis l’environnement d’exécution de l’agent.

Le Gateway projette les événements de cycle de vie ainsi que les événements de début/fin des outils dans le journal d’audit borné qui ne contient que des métadonnées. Cette projection enregistre la provenance et les codes de résultat sans copier les prompts, les messages, les arguments des outils, les résultats des outils ni les erreurs brutes en dehors du chemin de transcription/d’exécution.

​

Gestion des canaux de discussion

Les deltas de l’assistant sont mis en mémoire tampon dans des messages de discussion delta. Un message de discussion final est émis lors d’une fin/erreur de cycle de vie.

​

Délais d’expiration

​

Diagnostic des sessions bloquées

Lorsque les diagnostics sont activés, diagnostics.stuckSessionWarnMs (valeur par défaut : 120000 ms) classe les sessions processing de longue durée pour lesquelles aucune progression de réponse, d’outil, d’état, de bloc ou d’ACP n’a été observée :

• Les exécutions intégrées actives, les appels de modèle et les appels d’outil sont signalés comme session.long_running. Les appels de modèle silencieux avec propriétaire restent session.long_running jusqu’à diagnostics.stuckSessionAbortMs, afin que les fournisseurs lents ou sans diffusion en continu ne soient pas signalés trop tôt comme bloqués.
• Le travail actif sans progression récente est signalé comme session.stalled. Les appels de modèle avec propriétaire passent à session.stalled lorsque le seuil d’abandon est atteint ou dépassé ; les activités obsolètes de modèle ou d’outil sans propriétaire ne sont pas masquées comme étant de longue durée.
• session.stuck est réservé à la comptabilité récupérable des sessions obsolètes, notamment aux sessions inactives en file d’attente présentant une activité obsolète de modèle ou d’outil sans propriétaire.

La valeur par défaut de diagnostics.stuckSessionAbortMs est d’au moins 5 minutes et égale à 3x le seuil d’avertissement. La comptabilité des sessions obsolètes libère immédiatement le couloir de la session concernée une fois les contrôles de récupération réussis ; les exécutions intégrées bloquées ne sont abandonnées et purgées qu’après le seuil d’abandon, afin que le travail en file d’attente reprenne sans interrompre les exécutions simplement lentes. La récupération émet des résultats structurés de demande et d’achèvement ; l’état de diagnostic n’est marqué comme inactif que si la même génération de traitement est toujours actuelle, et les diagnostics session.stuck répétés appliquent un délai progressif tant que la session reste inchangée.

​

Situations pouvant entraîner un arrêt anticipé

• Délai d’expiration de l’agent (abandon)
• AbortSignal (annulation)
• Déconnexion du Gateway ou délai d’expiration RPC
• Délai d’expiration de agent.wait (attente uniquement, n’arrête pas l’agent)

​

Ressources associées

• Outils - outils disponibles pour l’agent
• Hooks - scripts pilotés par les événements et déclenchés par les événements du cycle de vie de l’agent
• Compaction - méthode de synthèse des longues conversations
• Approbations d’exécution - contrôles d’approbation pour les commandes shell
• Réflexion - configuration du niveau de réflexion/raisonnement