Bucle del agente (OpenClaw)¶

Un bucle agentic es la ejecución “real” completa de un agente: ingesta → ensamblaje de contexto → inferencia del modelo → ejecución de herramientas → streaming de respuestas → persistencia. Es la ruta autorizada que convierte un mensaje en acciones y una respuesta final, manteniendo consistente el estado de la sesión.

En OpenClaw, un bucle es una única ejecución serializada por sesión que emite eventos de ciclo de vida y de stream mientras el modelo razona, llama herramientas y transmite la salida. Este documento explica cómo ese bucle auténtico está conectado de extremo a extremo.

Puntos de entrada¶

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

Cómo funciona (alto nivel)¶

1. El RPC agent valida parámetros, resuelve la sesión (sessionKey/sessionId), persiste metadatos de la sesión y devuelve { runId, acceptedAt } de inmediato.
2. agentCommand ejecuta el agente: - resuelve el modelo y los valores predeterminados de thinking/verbose - carga el snapshot de Skills - llama a runEmbeddedPiAgent (runtime de pi-agent-core) - emite fin/error del ciclo de vida si el bucle embebido no emite uno
3. runEmbeddedPiAgent: - serializa ejecuciones mediante colas por sesión + globales - resuelve el modelo + perfil de autenticación y construye la sesión de pi - se suscribe a eventos de pi y transmite deltas del asistente/herramientas - aplica el timeout → aborta la ejecución si se excede - devuelve payloads + metadatos de uso
4. subscribeEmbeddedPiSession conecta eventos de pi-agent-core al stream agent de 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 usa waitForAgentJob: - espera fin/error del ciclo de vida para runId - devuelve { status: ok|error|timeout, startedAt, endedAt, error? }

Cola + concurrencia¶

• Las ejecuciones se serializan por clave de sesión (carril de sesión) y opcionalmente a través de un carril global.
• Esto evita condiciones de carrera de herramientas/sesión y mantiene consistente el historial de la sesión.
• Los canales de mensajería pueden elegir modos de cola (collect/steer/followup) que alimentan este sistema de carriles. Vea Command Queue.

Preparación de sesión + espacio de trabajo¶

• El espacio de trabajo se resuelve y crea; las ejecuciones en sandbox pueden redirigir a una raíz de espacio de trabajo de sandbox.
• Las Skills se cargan (o se reutilizan desde un snapshot) y se inyectan en el entorno y el prompt.
• Los archivos de arranque/contexto se resuelven y se inyectan en el informe del prompt del sistema.
• Se adquiere un bloqueo de escritura de la sesión; SessionManager se abre y prepara antes del streaming.

Ensamblaje del prompt + prompt del sistema¶

• El prompt del sistema se construye a partir del prompt base de OpenClaw, el prompt de Skills, el contexto de arranque y las anulaciones por ejecución.
• Se aplican los límites específicos del modelo y los tokens de reserva para compactación.
• Vea System prompt para lo que ve el modelo.

Puntos de enganche (donde puede interceptar)¶

OpenClaw tiene dos sistemas de hooks:

• Hooks internos (hooks del Gateway): scripts dirigidos por eventos para comandos y eventos del ciclo de vida.
• Hooks de plugins: puntos de extensión dentro del ciclo de vida del agente/herramientas y del pipeline del gateway.

Hooks internos (hooks del Gateway)¶

• agent:bootstrap: se ejecuta mientras se construyen los archivos de arranque antes de que se finalice el prompt del sistema. Úselo para agregar/eliminar archivos de contexto de arranque.
• Hooks de comandos: /new, /reset, /stop y otros eventos de comandos (ver documento de Hooks).

Vea Hooks para la configuración y ejemplos.

Hooks de plugins (ciclo de vida del agente + gateway)¶

Estos se ejecutan dentro del bucle del agente o del pipeline del gateway:

• before_agent_start: inyecta contexto o anula el prompt del sistema antes de que inicie la ejecución.
• agent_end: inspecciona la lista final de mensajes y los metadatos de la ejecución después de la finalización.
• before_compaction / after_compaction: observa o anota ciclos de compactación.
• before_tool_call / after_tool_call: intercepta parámetros/resultados de herramientas.
• tool_result_persist: transforma sincrónicamente los resultados de herramientas antes de que se escriban en la transcripción de la sesión.
• message_received / message_sending / message_sent: hooks de mensajes entrantes + salientes.
• session_start / session_end: límites del ciclo de vida de la sesión.
• gateway_start / gateway_stop: eventos del ciclo de vida del gateway.

Vea Plugins para la API de hooks y los detalles de registro.

Streaming + 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 ya sea en text_end o message_end.
• El streaming de razonamiento puede emitirse como un stream separado o como respuestas por bloques.
• Vea Streaming para el comportamiento de fragmentación y respuestas por bloques.

Ejecución de herramientas + herramientas de mensajería¶

• Los eventos de inicio/actualización/fin de herramientas se emiten en el stream tool.
• Los resultados de herramientas se sanitizan por tamaño y payloads de imagen antes de registrar/emitar.
• Los envíos de herramientas de mensajería se rastrean para suprimir confirmaciones duplicadas del asistente.

Modelado de respuestas + supresión¶

• Los payloads finales se ensamblan a partir de:
• texto del asistente (y razonamiento opcional)
• resúmenes de herramientas en línea (cuando verbose + permitido)
• texto de error del asistente cuando el modelo falla
• NO_REPLY se trata como un token silencioso y se filtra de los payloads salientes.
• 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 de respaldo (a menos que una herramienta de mensajería ya haya enviado una respuesta visible para el usuario).

Compactación + reintentos¶

• La compactación automática emite eventos de stream compaction y puede disparar un reintento.
• En el reintento, los buffers en memoria y los resúmenes de herramientas se restablecen para evitar salida duplicada.
• Vea Compaction para el pipeline de compactación.

Streams de eventos (hoy)¶

• 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 mensajes de chat delta.
• Se emite un chat final en fin/error del ciclo de vida.

Tiempos de espera¶

• Valor predeterminado de agent.wait: 30 s (solo la espera). El parámetro timeoutMs lo anula.
• Runtime del agente: valor predeterminado de agents.defaults.timeoutSeconds 600 s; aplicado en el temporizador de aborto runEmbeddedPiAgent.

Dónde las cosas pueden terminar antes¶

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