Fundamentals

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

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 }.
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.
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.
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").
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 :

Hook	Exécution
`before_model_resolve`	Avant la session (sans `messages`), pour remplacer de manière déterministe le fournisseur/modèle avant la résolution.
`before_prompt_build`	Après le chargement de la session (avec `messages`), pour injecter `prependContext`, `systemPrompt`, `prependSystemContext` ou `appendSystemContext` avant l’envoi. Utilisez `prependContext` pour le texte dynamique propre à chaque tour et les champs de contexte système pour les directives stables qui appartiennent à l’espace du prompt système.
`before_agent_start`	Hook de compatibilité hérité pouvant s’exécuter dans l’une ou l’autre phase ; préférez les hooks explicites ci-dessus.
`before_agent_reply`	Après les actions intégrées, avant l’appel au LLM. Permet à un Plugin de prendre en charge le tour et de renvoyer une réponse synthétique ou de le rendre entièrement silencieux.
`agent_end`	Après la fin, avec la liste finale des messages et les métadonnées d’exécution.
`before_compaction` / `after_compaction`	Observe ou annote les cycles de compaction.
`before_tool_call` / `after_tool_call`	Intercepte les paramètres/résultats des outils.
`before_install`	Après l’application de la politique d’installation de l’opérateur, sur les éléments d’installation de Skill/Plugin préparés, lorsque les hooks de Plugin sont chargés dans le processus actuel.
`tool_result_persist`	Transforme de manière synchrone les résultats des outils avant leur écriture dans une transcription de session appartenant à OpenClaw.
`message_received` / `message_sending` / `message_sent`	Hooks des messages entrants et sortants.
`session_start` / `session_end`	Limites du cycle de vie de la session.
`gateway_start` / `gateway_stop`	Événements du cycle de vie 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

Délai d’expiration	Valeur par défaut	Remarques
`agent.wait`	30s	Attente uniquement ; le paramètre `timeoutMs` remplace cette valeur. N’arrête pas l’exécution sous-jacente.
Durée d’exécution de l’agent (`agents.defaults.timeoutSeconds`)	172800s (48h)	Appliquée par le minuteur d’abandon de `runEmbeddedAgent`. Définissez `0` pour un budget d’exécution illimité ; les mécanismes de surveillance de l’activité du flux du modèle restent applicables.
Tour d’agent isolé Cron	géré par Cron	Le planificateur démarre son propre minuteur au début de l’exécution, abandonne l’exécution à l’échéance configurée, puis effectue un nettoyage limité avant d’enregistrer l’expiration du délai, afin qu’une session enfant obsolète ne puisse pas maintenir le couloir bloqué.
Délai d’inactivité du modèle	Cloud 120s ; auto-hébergé 300s	OpenClaw abandonne une requête au modèle lorsqu’aucun fragment de réponse n’arrive avant l’expiration de la fenêtre d’inactivité. `models.providers.<id>.timeoutSeconds` prolonge ce mécanisme de surveillance de l’inactivité pour les fournisseurs locaux/auto-hébergés lents, mais reste limité par toute valeur finie inférieure de `agents.defaults.timeoutSeconds` ou par tout délai propre à l’exécution, car ceux-ci régissent l’intégralité de l’exécution de l’agent. Les budgets d’exécution illimités conservent le mécanisme de surveillance de l’inactivité propre à la classe du fournisseur. Les exécutions de modèles Cloud déclenchées par Cron sans délai explicite pour le modèle ou l’agent utilisent la même valeur par défaut ; avec un délai explicite d’exécution Cron, les blocages du flux d’un modèle Cloud sont limités à 60s afin que les modèles de secours configurés puissent encore s’exécuter avant l’échéance Cron externe. Les exécutions déclenchées par Cron sur des points de terminaison réellement locaux (baseUrl en boucle locale/privée) conservent la désactivation locale du délai d’inactivité ; les fournisseurs auto-hébergés utilisant des baseUrls réseau reçoivent le mécanisme de surveillance implicite de 300s. Avec un délai explicite d’exécution Cron, les blocages locaux/auto-hébergés sont limités à ce délai. Définissez `models.providers.<id>.timeoutSeconds` pour les fournisseurs locaux lents.
Délai d’expiration des requêtes HTTP du fournisseur	`models.providers.<id>.timeoutSeconds`	Couvre la connexion, les en-têtes, le corps, le délai d’expiration des requêtes du SDK, la gestion de l’abandon de guarded-fetch et le mécanisme de surveillance de l’inactivité du flux du modèle pour ce fournisseur. Utilisez-le pour les fournisseurs locaux/auto-hébergés lents (par exemple Ollama) avant d’augmenter le délai d’exécution global de l’agent ; maintenez le délai de l’agent/de l’environnement d’exécution au moins aussi élevé lorsque la requête au modèle doit s’exécuter plus longtemps.

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

Was this useful?