Bucle del agente

Un bucle agéntico es la ejecución "real" completa de un agente: recepción → ensamblaje de contexto → inferencia del modelo → ejecución de herramientas → respuestas en streaming → persistencia. Es la ruta autoritativa que convierte un mensaje en acciones y una respuesta final, manteniendo coherente 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 flujo mientras el modelo razona, llama herramientas y transmite salida. Este documento explica cómo se conecta ese bucle auténtico de extremo a extremo.

Puntos de entrada

• RPC de 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 sesión y devuelve { runId, acceptedAt } inmediatamente.
2. agentCommand ejecuta el agente:
   • resuelve el modelo y los valores predeterminados de thinking/verbose/trace
   • carga la instantánea de Skills
   • llama a runEmbeddedAgent (runtime de agente de OpenClaw)
   • emite fin/error de ciclo de vida si el bucle embebido no emite uno
3. runEmbeddedAgent:
   • serializa ejecuciones mediante colas por sesión y globales
   • resuelve el modelo y el perfil de autenticación y construye la sesión de OpenClaw
   • se suscribe a eventos del runtime y transmite deltas de asistente/herramienta
   • aplica timeout -> aborta la ejecución si se supera
   • para turnos del servidor de aplicaciones de Codex, aborta un turno aceptado que deja de producir progreso del servidor de aplicaciones antes de un evento terminal
   • devuelve payloads y metadatos de uso
4. subscribeEmbeddedAgentSession conecta eventos del runtime de agente al flujo agent de OpenClaw:
   • eventos de herramienta => stream: "tool"
   • deltas de asistente => stream: "assistant"
   • eventos de ciclo de vida => stream: "lifecycle" (phase: "start" | "end" | "error")
5. agent.wait usa waitForAgentRun:
   • espera fin/error de ciclo de vida para runId
   • devuelve { status: ok|error|timeout, startedAt, endedAt, error? }

Encolado + concurrencia

• Las ejecuciones se serializan por clave de sesión (carril de sesión) y opcionalmente mediante un carril global.
• Esto evita carreras de herramientas/sesión y mantiene coherente el historial de sesión.
• Los canales de mensajería pueden elegir modos de cola (steer/followup/collect/interrupt) que alimentan este sistema de carriles. Consulta Cola de comandos.
• Las escrituras de transcripción también están protegidas por un bloqueo de escritura de sesión sobre el archivo de sesión. El bloqueo es consciente del proceso y basado en archivo, por lo que captura escritores que omiten la cola en proceso o vienen de otro proceso. Los escritores de transcripción de sesión esperan hasta session.writeLock.acquireTimeoutMs antes de informar que la sesión está ocupada; el valor predeterminado es 60000 ms.
• Los bloqueos de escritura de sesión no son reentrantes de forma predeterminada. Si un helper anida intencionalmente la adquisición del mismo bloqueo mientras preserva un único escritor lógico, debe habilitarlo explícitamente con allowReentrant: true.

Preparación de sesión + espacio de trabajo

• El espacio de trabajo se resuelve y se crea; las ejecuciones con sandbox pueden redirigirse a una raíz de espacio de trabajo sandbox.
• Las Skills se cargan (o se reutilizan desde una instantánea) y se inyectan en el entorno y el prompt.
• Los archivos de bootstrap/contexto se resuelven y se inyectan en el informe del prompt del sistema.
• Se adquiere un bloqueo de escritura de sesión; SessionManager se abre y se prepara antes del streaming. Cualquier ruta posterior de reescritura de transcripción, Compaction o truncamiento debe tomar el mismo bloqueo antes de abrir o mutar el archivo de transcripción.

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 bootstrap y las anulaciones por ejecución.
• Se aplican los límites específicos del modelo y los tokens de reserva de Compaction.
• Consulta Prompt del sistema para ver lo que recibe el modelo.

Puntos de hook (dónde puedes interceptar)

OpenClaw tiene dos sistemas de hooks:

• Hooks internos (hooks de Gateway): scripts dirigidos por eventos para comandos y eventos de ciclo de vida.
• Hooks de Plugin: puntos de extensión dentro del ciclo de vida del agente/herramienta y la canalización de Gateway.

Hooks internos (hooks de Gateway)

• agent:bootstrap: se ejecuta mientras se construyen archivos de bootstrap antes de finalizar el prompt del sistema. Úsalo para agregar/quitar archivos de contexto de bootstrap.
• Hooks de comando: /new, /reset, /stop y otros eventos de comando (consulta la documentación de Hooks).

Consulta Hooks para configuración y ejemplos.

Hooks de Plugin (ciclo de vida de agente + Gateway)

Estos se ejecutan dentro del bucle del agente o la canalización de Gateway:

• before_model_resolve: se ejecuta antes de la sesión (sin messages) para anular de forma determinista el proveedor/modelo antes de la resolución del modelo.
• before_prompt_build: se ejecuta después de cargar la sesión (con messages) para inyectar prependContext, systemPrompt, prependSystemContext o appendSystemContext antes del envío del prompt. Usa prependContext para texto dinámico por turno y campos de contexto del sistema para orientación estable que debe residir en el espacio del prompt del sistema.
• before_agent_start: hook de compatibilidad heredado que puede ejecutarse en cualquiera de las fases; prefiere los hooks explícitos anteriores.
• before_agent_reply: se ejecuta después de las acciones inline y antes de la llamada al LLM, lo que permite que un Plugin reclame el turno y devuelva una respuesta sintética o silencie el turno por completo.
• agent_end: inspecciona la lista final de mensajes y los metadatos de ejecución después de completarse.
• before_compaction / after_compaction: observa o anota ciclos de Compaction.
• before_tool_call / after_tool_call: intercepta parámetros/resultados de herramientas.
• before_install: inspecciona material preparado de instalación de skill o Plugin después de que se ejecuta la política de instalación del operador, cuando los hooks de Plugin están cargados en el proceso actual de OpenClaw.
• tool_result_persist: transforma sincrónicamente resultados de herramientas antes de que se escriban en una transcripción de sesión propiedad de OpenClaw.
• message_received / message_sending / message_sent: hooks de mensajes entrantes y salientes.
• session_start / session_end: límites del ciclo de vida de sesión.
• gateway_start / gateway_stop: eventos del ciclo de vida de Gateway.

Reglas de decisión de hooks para protecciones de salida/herramientas:

• before_tool_call: { block: true } es terminal y detiene handlers de menor prioridad.
• before_tool_call: { block: false } es una no-op y no borra un bloqueo previo.
• before_install: { block: true } es terminal y detiene handlers de menor prioridad.
• before_install: { block: false } es una no-op y no borra un bloqueo previo.
• Usa security.installPolicy, no before_install, para decisiones de permitir/bloquear instalaciones propiedad del operador que deben cubrir rutas de instalación y actualización de CLI.
• message_sending: { cancel: true } es terminal y detiene handlers de menor prioridad.
• message_sending: { cancel: false } es una no-op y no borra una cancelación previa.

Consulta Hooks de Plugin para la API de hooks y los detalles de registro.

Los arneses pueden adaptar estos hooks de forma diferente. El arnés de servidor de aplicaciones de Codex mantiene los hooks de Plugin de OpenClaw como el contrato de compatibilidad para superficies reflejadas documentadas, mientras que los hooks nativos de Codex siguen siendo un mecanismo separado de Codex de nivel inferior.

Streaming + respuestas parciales

• Los deltas de asistente se transmiten desde el runtime del agente 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 flujo separado o como respuestas de bloque.
• Consulta Streaming para el comportamiento de fragmentación y respuestas de bloque.

Ejecución de herramientas + herramientas de mensajería

• Los eventos de inicio/actualización/fin de herramienta se emiten en el flujo tool.
• Los resultados de herramientas se saneán por tamaño y payloads de imagen antes de registrarse/emitirse.
• Los envíos de herramientas de mensajería se rastrean para suprimir confirmaciones duplicadas del asistente.

Modelado de respuesta + supresión

• Los payloads finales se ensamblan a partir de:
  • texto del asistente (y razonamiento opcional)
  • resúmenes de herramientas inline (cuando verbose + permitido)
  • texto de error del asistente cuando el modelo falla
• El token silencioso exacto NO_REPLY / no_reply 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).

Compaction + reintentos

• La Compaction automática emite eventos de flujo compaction y puede activar un reintento.
• En el reintento, los buffers en memoria y los resúmenes de herramientas se reinician para evitar salida duplicada.
• Consulta Compaction para la canalización de Compaction.

Flujos de eventos (hoy)

• lifecycle: emitido por subscribeEmbeddedAgentSession (y como respaldo por agentCommand)
• assistant: deltas transmitidos desde el runtime del agente
• tool: eventos de herramientas transmitidos desde el runtime del agente

Manejo de canal de chat

• Los deltas de asistente se almacenan en buffer como mensajes delta de chat.
• Se emite un final de chat en fin/error de ciclo de vida.

Timeouts

• Valor predeterminado de agent.wait: 30 s (solo la espera). El parámetro timeoutMs lo anula.
• Runtime del agente: agents.defaults.timeoutSeconds predeterminado 172800 s (48 horas); aplicado en el temporizador de aborto de runEmbeddedAgent.
• Runtime de Cron: el timeoutSeconds de turno de agente aislado pertenece a cron. El planificador inicia ese temporizador cuando comienza la ejecución, aborta la ejecución subyacente en el plazo configurado y luego ejecuta limpieza acotada antes de registrar el timeout para que una sesión hija obsoleta no pueda dejar el carril atascado.
• Diagnósticos de actividad de sesión: con diagnósticos habilitados, diagnostics.stuckSessionWarnMs clasifica sesiones processing largas que no tienen respuesta, herramienta, estado, bloque ni progreso de ACP observado. Las ejecuciones embebidas activas, las llamadas al modelo y las llamadas de herramientas se informan como session.long_running; las llamadas silenciosas al modelo con propietario también permanecen como session.long_running hasta diagnostics.stuckSessionAbortMs para que los proveedores lentos o sin streaming no se informen como detenidos demasiado pronto. El trabajo activo sin progreso reciente se informa como session.stalled; las llamadas al modelo con propietario cambian a session.stalled en o después del umbral de aborto, y la actividad obsoleta de modelo/herramienta sin propietario no se oculta como de larga duración. session.stuck se reserva para contabilidad de sesiones obsoletas recuperables, incluidas sesiones en cola inactivas con actividad obsoleta de modelo/herramienta sin propietario. La contabilidad de sesiones obsoletas libera el carril de sesión afectado inmediatamente después de que pasan las compuertas de recuperación; las ejecuciones embebidas detenidas solo se abortan y drenan después de diagnostics.stuckSessionAbortMs (valor predeterminado: al menos 5 minutos y 3x el umbral de advertencia) para que el trabajo en cola pueda reanudarse sin cortar ejecuciones simplemente lentas. La recuperación emite resultados estructurados solicitados/completados, y el estado de diagnóstico se marca como inactivo solo si la misma generación de procesamiento sigue siendo la actual. Los diagnósticos session.stuck repetidos aplican backoff mientras la sesión permanece sin cambios.
• Timeout de inactividad del modelo: OpenClaw aborta una solicitud de modelo cuando no llegan fragmentos de respuesta antes de la ventana de inactividad. models.providers.<id>.timeoutSeconds extiende este watchdog de inactividad para proveedores locales/autohospedados lentos, pero sigue estando acotado por cualquier agents.defaults.timeoutSeconds menor o timeout específico de ejecución porque esos controlan toda la ejecución del agente. De lo contrario, OpenClaw usa agents.defaults.timeoutSeconds cuando está configurado, limitado a 120 s de forma predeterminada. Las ejecuciones de modelos en la nube activadas por Cron sin timeout explícito de modelo o agente usan el mismo watchdog de inactividad predeterminado; con un timeout explícito de ejecución de Cron, las detenciones de flujo de modelos en la nube se limitan a 60 s para que los fallbacks de modelo configurados puedan ejecutarse antes del plazo externo de Cron. Las ejecuciones de modelos locales o autohospedados activadas por Cron deshabilitan el watchdog implícito a menos que se configure un timeout explícito, y los timeouts explícitos de ejecución de Cron siguen siendo la ventana de inactividad para proveedores locales/autohospedados, por lo que los proveedores locales lentos deben establecer models.providers.<id>.timeoutSeconds.
• Timeout de solicitud HTTP del proveedor: models.providers.<id>.timeoutSeconds se aplica a las fetches HTTP de modelo de ese proveedor, incluidos conexión, headers, body, timeout de solicitud del SDK, manejo de aborto total de guarded-fetch y watchdog de inactividad de flujo del modelo. Usa esto para proveedores locales/autohospedados lentos como Ollama antes de aumentar el timeout de todo el runtime del agente, y mantén el timeout del agente/runtime al menos igual de alto cuando la solicitud de modelo necesite ejecutarse durante más tiempo.

Dónde las cosas pueden terminar antes

• Tiempo de espera del agente (anulación)
• AbortSignal (cancelación)
• Desconexión del Gateway o tiempo de espera de RPC
• Tiempo de espera de agent.wait (solo espera, no detiene al agente)

Relacionado

• Herramientas — herramientas de agente disponibles
• Hooks — scripts basados en eventos activados por eventos del ciclo de vida del agente
• Compaction — cómo se resumen las conversaciones largas
• Aprobaciones de exec — controles de aprobación para comandos de shell
• Thinking — configuración del nivel de pensamiento/razonamiento