Loop del Agente

El loop del agente es la ejecución "verdadera" completa del agente: ingestión → ensamblaje de contexto → inferencia de modelo →

ejecución de herramientas → respuesta de streaming → persistencia. Este es el camino autorizado para entregar mensajes

convertidos en acciones y respuestas finales mientras mantiene consistencia del estado de sesión.

En OpenClaw, el loop es una única ejecución serializada por sesión que emite eventos de ciclo de vida y stream

mientras el modelo piensa, llama herramientas y transmite salida. Este documento explica cómo el loop real va

de extremo a extremo.

- Gateway RPC: ''agent'' y ''agent.wait''.

- CLI: comando ''agent''.

1. RPC ''agent'' valida argumentos, resuelve sesión (sessionKey/sessionId), guarda metadatos de sesión, retorna inmediatamente ''{ runId, acceptedAt }''.

2. ''agentCommand'' ejecuta el agente:

- Resuelve modelo+think/verbose predeterminados

- Carga snapshot de skills

- Llama ''runEmbeddedPiAgent'' (runtime pi-agent-core)

- Emite lifecycle end/error si el loop embebido no emitió uno

3.''runEmbeddedPiAgent'':

- Serializa ejecuciones por cola sesión+global

- Resuelve modelo+perfiles de auth y construye sesión pi

- Se suscribe a eventos pi y transmite deltas asistente/herramienta

- Aplica timeout → aborta ejecución si se excede

- Retorna payload+metadatos de uso

4. ''subscribeEmbeddedPiSession'' puentea eventos pi-agent-core al stream ''agent'' de OpenClaw:

ReferenceConceptsAgentLoopPage.step02.p14

ReferenceConceptsAgentLoopPage.step02.p15

ReferenceConceptsAgentLoopPage.step02.p16

ReferenceConceptsAgentLoopPage.step02.p17

ReferenceConceptsAgentLoopPage.step02.p18

ReferenceConceptsAgentLoopPage.step02.p19

- Las ejecuciones se serializan por clave de sesión (canal de sesión) y opcionalmente vía canal global.

- Esto previene carreras de herramientas/sesión y mantiene el historial de sesión consistente.

- Los canales de mensajería pueden opcionalmente usar modo cola para ese sistema de canal (collect/lead/follow).

Ver ''Cola de Comandos''.

- El workspace se resuelve y crea; las ejecuciones sandbox pueden redirigir a la raíz del workspace sandbox.

- Las skills se cargan (o reusan de snapshot) y se inyectan en el entorno y prompts.

- Los archivos bootstrap/contexto se resuelven e inyectan en el reporte de system prompt.

- El lock de escritura de sesión se adquiere; ''SessionManager'' se abre y está listo antes del streaming.

- El system prompt se construye desde el prompt base de OpenClaw, prompts de skills, contexto bootstrap y overrides por ejecución.

- Los límites específicos de modelo y tokens de reserva de compactación se aplican.

- Ver ''System Prompt'' para lo que el modelo ve.

OpenClaw tiene dos sistemas de hooks:

- Hooks Internos (gateway hooks): scripts basados en eventos para comandos y eventos de ciclo de vida.

- Hooks de Plugin: puntos de extensión dentro del ciclo de vida de agente/herramienta y pipeline del gateway.

#

- ''''agent:bootstrap'''': se ejecuta al construir archivos bootstrap antes de la finalización del system prompt.

Úsalo para agregar/remover archivos de contexto bootstrap.

- ''Hooks de Comando'': ''/new'', ''/reset'', ''/stop'' y otros eventos de comando (ver documentación de Hooks).

Ver ''Hooks'' para setup y ejemplos.

#

Se ejecutan dentro del loop del agente o pipeline del gateway:

- ''''before_agent_start'''': inyecta contexto o anula system prompt antes de que inicie la ejecución.

- ''''agent_end'''': inspecciona la lista final de mensajes y metadatos de ejecución después de completar.

ReferenceConceptsAgentLoopPage.step08.p4

ReferenceConceptsAgentLoopPage.step08.p5

ReferenceConceptsAgentLoopPage.step08.p6

ReferenceConceptsAgentLoopPage.step08.p7

ReferenceConceptsAgentLoopPage.step08.p8

ReferenceConceptsAgentLoopPage.step08.p9

ReferenceConceptsAgentLoopPage.step08.p10

- Assistant deltas are streamed from pi-agent-core and emitted as ''assistant'' events.

- Chunk streams can emit partial replies on ''text_end'' or ''message_end''.

- Reasoning streams can be emitted as separate stream or chunk reply.

- See ''Streaming'' for chunking and chunk reply behavior.

- Tool start/update/end events are emitted on ''tool'' stream.

- Tool results are sanitized based on size and image payloads before logging/sending.

- Messaging tool sends are tracked to suppress duplicate assistant acknowledgments.

- Final payload is assembled from:

- Assistant text (and optional reasoning)

- Inline tool summaries (when verbose+allowed)

- Assistant error text on model errors

- ''NO_REPLY'' is treated as silent token and filtered from outgoing payload.

- Messaging tool duplicates are removed from final payload list.

- If no renderable payload remains and tool errored, fallback tool error reply is emitted

(unless messaging tool already sent user-visible reply).

- Auto-compaction emits ''compaction'' stream event and can trigger retry.

- On retry, memory buffer and tool summaries are reset to avoid duplicate output.

- See ''Compaction'' for compaction pipeline.

- ''lifecycle'': emitted by ''subscribeEmbeddedPiSession'' (and as fallback for ''agentCommand'')

- ''assistant'': streaming deltas from pi-agent-core

- ''tool'': streaming tool events from pi-agent-core

- Assistant deltas are buffered into chat ''delta'' messages.

- Chat ''final'' is emitted on ''lifecycle end/error''.

- ''agent.wait'' default: 30 seconds (just wait). ''timeoutMs'' parameter overrides.

- Agent run time: ''agents.defaults.timeoutSeconds'' default 600 seconds; enforced in ''runEmbeddedPiAgent'' abort timer.

- Agent timeout (abort)

- AbortSignal (cancel)

- Gateway disconnect or RPC timeout

- ''agent.wait'' timeout (only waits, doesn't stop agent)