Domina el Agent Loop de OpenClaw: Guía de ejecución

Seguir el flujo de un agente de IA puede ser frustrante. A veces parece una caja negra donde envías un mensaje y esperas que ocurra un milagro técnico. Necesitas control real sobre el estado de la sesión, las herramientas y cómo se envían los datos al usuario sin que todo se rompa en el camino.

El Agent Loop es la ejecución “real” y completa de un agente: desde la entrada de datos y el ensamblado del contexto hasta la inferencia del modelo, la ejecución de herramientas, el streaming de respuestas y la persistencia. Es el camino de autoridad que convierte un mensaje en acciones y una respuesta final, manteniendo la consistencia del estado de la sesión.

En OpenClaw, un loop es una ejecución única y serializada por sesión que emite eventos de ciclo de vida y stream mientras el modelo piensa, llama a herramientas y genera salida. Aquí te explico cómo está conectado este loop de extremo a extremo.

Puntos de entrada

• Gateway RPC: agent y agent.wait.
• CLI: comando agent.

Cómo funciona (visión general)

1. El RPC agent valida los parámetros, resuelve la sesión (sessionKey/sessionId), guarda los metadatos de la sesión y devuelve { runId, acceptedAt } de inmediato.
2. agentCommand ejecuta el agente:
   • Resuelve el modelo y los valores por defecto de thinking/verbose.
   • Carga el snapshot de las skills.
   • Llama a runEmbeddedPiAgent (runtime de pi-agent-core).
   • Emite lifecycle end/error si el loop embebido no emite uno.
3. runEmbeddedPiAgent:
   • Serializa las ejecuciones mediante colas por sesión y colas globales.
   • Resuelve el modelo y el perfil de autenticación para construir la sesión de pi.
   • Se suscribe a los eventos de pi y hace streaming de los deltas del assistant/tool.
   • Aplica el timeout y aborta la ejecución si se excede el tiempo.
   • Devuelve los payloads y metadatos de uso.
4. subscribeEmbeddedPiSession conecta los eventos de pi-agent-core con el stream de agent en OpenClaw:
   • Eventos de herramientas => stream: "tool"
   • Deltas del asistente => stream: "assistant"
   • Eventos de ciclo de vida => stream: "lifecycle" (phase: "start" | "end" | "error")
5. agent.wait utiliza waitForAgentJob:
   • Espera al lifecycle end/error para el runId.
   • Devuelve { status: ok|error|timeout, startedAt, endedAt, error? }.

Colas y concurrencia

• Las ejecuciones se serializan por clave de sesión (session lane) y, opcionalmente, a través de un carril global.
• Esto evita conflictos entre herramientas o sesiones y mantiene la historia de la sesión consistente.
• Los canales de mensajería pueden elegir modos de cola (collect/steer/followup) que alimentan este sistema de carriles. Consulta Command Queue.

Preparación de sesión y workspace

• El workspace se resuelve y se crea; las ejecuciones en sandbox pueden redirigirse a una raíz de workspace específica para sandbox.
• Las skills se cargan (o se reutilizan desde un snapshot) y se inyectan en el entorno y el prompt.
• Los archivos de bootstrap/contexto se resuelven e inyectan en el reporte del system prompt.
• Se adquiere un bloqueo de escritura de sesión; el SessionManager se abre y se prepara antes del streaming.

Ensamblado del prompt y system prompt

• El system prompt se construye a partir del prompt base de OpenClaw, el prompt de skills, el contexto de bootstrap y los overrides por ejecución.
• Se aplican los límites específicos del modelo y la reserva de tokens para compactación.
• Revisa System prompt para ver qué es lo que el modelo recibe realmente.

Puntos de hook (donde puedes interceptar)

OpenClaw tiene dos sistemas de hooks:

• Hooks internos (Gateway hooks): scripts basados en eventos para comandos y eventos de ciclo de vida.
• Hooks de plugins: puntos de extensión dentro del ciclo de vida del agente/herramienta y el pipeline del Gateway.

Hooks internos (Gateway hooks)

• agent:bootstrap: se ejecuta mientras se construyen los archivos de bootstrap antes de finalizar el system prompt. Úsalo para añadir o eliminar archivos de contexto.
• Hooks de comandos: /new, /reset, /stop y otros eventos de comando (ver doc de Hooks).

Consulta Hooks para ver la configuración y ejemplos.

Hooks de plugins (ciclo de vida del agente y gateway)

Estos se ejecutan dentro del loop del agente o en el pipeline del Gateway:

• before_model_resolve: se ejecuta antes de la sesión (sin messages) para sobrescribir el proveedor o modelo de forma determinista.
• before_prompt_build: se ejecuta tras cargar la sesión (con messages) para inyectar prependContext, systemPrompt, prependSystemContext o appendSystemContext. Usa prependContext para texto dinámico por turno y los campos de system-context para guías estables en el espacio del system prompt.
• before_agent_start: hook de compatibilidad legado; es mejor usar los hooks explícitos mencionados arriba.
• before_agent_reply: se ejecuta tras las acciones inline y antes de la llamada al LLM, permitiendo que un plugin tome el turno y devuelva una respuesta sintética o silencie el turno.
• agent_end: permite inspeccionar la lista final de mensajes y los metadatos tras completar la ejecución.
• before_compaction / after_compaction: para observar o anotar los ciclos de compactación.
• before_tool_call / after_tool_call: intercepta parámetros o resultados de herramientas.
• before_install: inspecciona hallazgos de escaneo integrados y bloquea instalaciones de skills o plugins si es necesario.
• tool_result_persist: transforma sincrónicamente los resultados de las herramientas antes de escribirlos en el transcript de la sesión.
• message_received / message_sending / message_sent: hooks para mensajes entrantes y salientes.
• session_start / session_end: límites del ciclo de vida de la sesión.
• gateway_start / gateway_stop: eventos de ciclo de vida del Gateway.

Reglas de decisión de hooks para guardas de salida y herramientas:

• before_tool_call: { block: true } es terminal y detiene los manejadores de menor prioridad.
• before_tool_call: { block: false } no realiza ninguna acción y no elimina un bloqueo previo.
• before_install: { block: true } es terminal y detiene los manejadores de menor prioridad.
• before_install: { block: false } no realiza ninguna acción y no elimina un bloqueo previo.
• message_sending: { cancel: true } es terminal y detiene los manejadores de menor prioridad.
• message_sending: { cancel: false } no realiza ninguna acción y no elimina una cancelación previa.

Consulta Plugin hooks para detalles sobre la API y el registro.

Streaming y respuestas parciales

• Los deltas del asistente se transmiten desde pi-agent-core y se emiten como eventos assistant.
• El streaming por bloques puede emitir respuestas parciales en text_end o message_end.
• El streaming de razonamiento (reasoning) puede emitirse como un stream separado o como respuestas de bloque.
• Consulta Streaming para ver el comportamiento de fragmentación (chunking) y respuestas por bloque.

Ejecución de herramientas y messaging tools

• Los eventos de inicio, actualización y fin de herramientas se emiten en el stream tool.
• Los resultados de las herramientas se sanean (sanitization) en cuanto a tamaño y payloads de imagen antes de registrarse o emitirse.
• Se rastrean los envíos de herramientas de mensajería para evitar confirmaciones duplicadas del asistente.

Modelado y supresión de respuestas

• Los payloads finales se ensamblan a partir de:
  • Texto del asistente (y razonamiento opcional).
  • Resúmenes de herramientas inline (cuando el modo verbose está activo y permitido).
  • Texto de error del asistente si el modelo falla.
• NO_REPLY se trata como un token silencioso y se filtra de los payloads de salida.
• Los duplicados de herramientas de mensajería se eliminan de la lista final de payloads.
• Si no quedan payloads renderizables y una herramienta falló, se emite una respuesta de error de herramienta por defecto (a menos que una herramienta de mensajería ya haya enviado una respuesta visible para el usuario).

Compactación y reintentos

• La auto-compactación emite eventos de stream compaction y puede activar un reintento.
• En un reintento, los buffers en memoria y los resúmenes de herramientas se reinician para evitar salidas duplicadas.
• Consulta Compaction para entender el pipeline de compactación.

Streams de eventos (actualmente)

• lifecycle: emitido por subscribeEmbeddedPiSession (y como respaldo por agentCommand).
• assistant: deltas transmitidos desde pi-agent-core.
• tool: eventos de herramientas transmitidos desde pi-agent-core.

Manejo del canal de chat

• Los deltas del asistente se almacenan en buffers dentro de mensajes delta de chat.
• Se emite un mensaje final de chat al recibir el lifecycle end/error.

Timeouts

• Valor por defecto de agent.wait: 30s (solo la espera). El parámetro timeoutMs lo sobrescribe.
• Runtime del agente: agents.defaults.timeoutSeconds por defecto 172800s (48 horas); aplicado mediante un temporizador de aborto en runEmbeddedPiAgent.

Dónde pueden terminar las cosas antes de tiempo

• Timeout del agente (abort).
• AbortSignal (cancelación).
• Desconexión del Gateway o timeout de RPC.
• Timeout de agent.wait (solo afecta a la espera, no detiene al agente).

Relacionado

• Tools — herramientas disponibles para el agente.
• Hooks — scripts activados por eventos del ciclo de vida del agente.
• Compaction — cómo se resumen las conversaciones largas.
• Exec Approvals — puertas de aprobación para comandos de shell.
• Thinking — configuración del nivel de razonamiento y pensamiento.

Siguiente paso

Si necesitas ayuda para configurar tu primer loop o tienes dudas específicas sobre la integración de plugins, puedes consultar al AI Setup Assistant.