Bucle del agente

El bucle del agente es la ejecución serializada, por sesión, que convierte un mensaje en acciones y una respuesta: recepción, ensamblaje de contexto, inferencia del modelo, ejecución de herramientas, streaming y persistencia.

​

Puntos de entrada

• RPC de Gateway: agent y agent.wait.
• CLI: openclaw agent.

​

Secuencia de ejecución

1. La RPC agent valida los parámetros, resuelve la sesión (sessionKey/sessionId), persiste los metadatos de la sesión y devuelve { runId, acceptedAt } de inmediato.
2. agentCommand ejecuta el turno: resuelve los valores predeterminados de modelo + razonamiento/verbosidad/traza, carga la instantánea de Skills, llama a runEmbeddedAgent y emite un fin/error de ciclo de vida de reserva si el bucle embebido aún no emitió uno.
3. runEmbeddedAgent: serializa las ejecuciones mediante colas por sesión y globales, resuelve el modelo + perfil de autenticación, crea la sesión de OpenClaw, se suscribe a eventos de runtime, transmite deltas del asistente/herramienta, aplica el tiempo límite de ejecución (abortando al vencer) y devuelve payloads junto con metadatos de uso. Para turnos de app-server de Codex también aborta un turno aceptado que deja de producir progreso de app-server antes de un evento terminal.
4. subscribeEmbeddedAgentSession conecta los eventos de runtime con el stream agent: eventos de herramienta a stream: "tool", deltas del asistente a stream: "assistant", eventos de ciclo de vida a stream: "lifecycle" (phase: "start" | "end" | "error").
5. agent.wait (waitForAgentRun) espera el fin/error de ciclo de vida en un runId y devuelve { status: ok|error|timeout, startedAt, endedAt, error? }.

​

Colas y concurrencia

Las ejecuciones se serializan por clave de sesión (carril de sesión) y opcionalmente mediante un carril global, lo que evita carreras de herramientas/sesión. Los canales de mensajería eligen un modo de cola (steer/followup/collect/interrupt) que alimenta este sistema de carriles; consulta Cola de comandos. Las escrituras de transcripción también se protegen con un bloqueo de escritura de sesión en el archivo de sesión. El bloqueo es consciente del proceso y está basado en archivos, por lo que detecta escritores que omiten la cola en proceso o provienen de otro proceso. Los escritores esperan hasta session.writeLock.acquireTimeoutMs (predeterminado 60000 ms; override de entorno OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS) antes de informar que la sesión está ocupada. Los bloqueos de escritura de sesión no son reentrantes de forma predeterminada. Un helper que anida intencionalmente la adquisición del mismo bloqueo mientras conserva un único escritor lógico debe habilitarlo con allowReentrant: true.

​

Preparación de sesión y espacio de trabajo

• El espacio de trabajo se resuelve y se crea; las ejecuciones en sandbox pueden redirigirse a una raíz de espacio de trabajo de sandbox.
• 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 prompt del sistema.
• Se adquiere un bloqueo de escritura de sesión y SessionManager se abre y prepara antes de que empiece el streaming. Cualquier ruta posterior de reescritura, Compaction o truncamiento de transcripción debe tomar el mismo bloqueo antes de abrir o mutar el archivo de transcripción.

​

Ensamblaje del prompt

El prompt del sistema 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 límites específicos del modelo y tokens de reserva para Compaction. Consulta Prompt del sistema para ver qué recibe el modelo.

​

Enlaces

OpenClaw tiene dos sistemas de enlaces:

• Enlaces internos (enlaces de Gateway): scripts orientados a eventos para comandos y eventos de ciclo de vida.
• Enlaces de Plugin: puntos de extensión dentro del ciclo de vida del agente/herramienta y la canalización de Gateway.

​

Enlaces internos (enlaces de Gateway)

• agent:bootstrap: se ejecuta al crear archivos de bootstrap antes de que se finalice el prompt del sistema. Úsalo para añadir o eliminar archivos de contexto de bootstrap.
• Enlaces de comandos: /new, /reset, /stop y otros eventos de comando (consulta la documentación de Enlaces).

Consulta Enlaces para configuración y ejemplos.

​

Enlaces de Plugin

Se ejecutan dentro del bucle del agente o la canalización de Gateway: Reglas de decisión de enlaces para guardas de salida/herramienta:

• before_tool_call: { block: true } es terminal y detiene los manejadores de menor prioridad. { block: false } es un no-op y no elimina un bloqueo previo.
• before_install: mismas semánticas terminal/no-op que arriba. 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 los manejadores de menor prioridad. { cancel: false } es un no-op y no elimina una cancelación previa.

Consulta Enlaces de Plugin para la API de enlaces y los detalles de registro. Los arneses pueden adaptar estos enlaces. El arnés de app-server de Codex mantiene los enlaces de Plugin de OpenClaw como contrato de compatibilidad para superficies espejadas documentadas; los enlaces nativos de Codex son un mecanismo separado de Codex, de nivel más bajo.

​

Streaming

• Los deltas del asistente se transmiten desde el runtime del agente como eventos assistant.
• El streaming por bloques puede emitir respuestas parciales en text_end o message_end.
• El streaming de razonamiento puede ser un stream separado o respuestas por bloques.
• Consulta Streaming para el comportamiento de fragmentación y respuesta por bloques.

​

Ejecución de herramientas

• Los eventos de inicio/actualización/fin de herramienta se emiten en el stream tool.
• Los resultados de herramientas se limpian 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.

​

Moldeado de respuestas

Los payloads finales se ensamblan a partir del texto del asistente (más razonamiento opcional), resúmenes de herramientas inline (cuando la verbosidad está habilitada y permitida) y texto de error del asistente cuando el modelo falla.

• El token silencioso exacto 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 produjo un error, se emite una respuesta de error de herramienta de reserva salvo que una herramienta de mensajería ya haya enviado una respuesta visible para el usuario.

​

Compaction y reintentos

La Compaction automática emite eventos de stream compaction y puede activar un reintento. En el reintento, los búferes en memoria y los resúmenes de herramientas se reinician para evitar salida duplicada. Consulta Compaction.

​

Streams de eventos

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

Gateway proyecta eventos de ciclo de vida y eventos de inicio/terminales de herramientas en el libro de auditoría acotado y solo de metadatos. Esta proyección registra procedencia y códigos de resultado sin copiar prompts, mensajes, argumentos de herramientas, resultados de herramientas ni errores sin procesar fuera de la ruta de transcripción/runtime.

​

Manejo de canales de chat

Los deltas del asistente se almacenan en búfer como mensajes delta de chat. Se emite un final de chat en fin/error de ciclo de vida.

​

Tiempos límite

​

Diagnóstico de sesiones atascadas

Con el diagnóstico activado, diagnostics.stuckSessionWarnMs (valor predeterminado 120000 ms) clasifica las sesiones processing largas sin respuesta, herramienta, estado, bloqueo ni progreso de ACP observados:

• Las ejecuciones incrustadas activas, las llamadas de modelo y las llamadas de herramienta se notifican como session.long_running. Las llamadas de modelo silenciosas con propietario permanecen como session.long_running hasta diagnostics.stuckSessionAbortMs para que los proveedores lentos o sin stream no se marquen como bloqueados demasiado pronto.
• El trabajo activo sin progreso reciente se notifica como session.stalled. Las llamadas de modelo con propietario cambian a session.stalled en el umbral de cancelación o después; la actividad obsoleta de modelo/herramienta sin propietario no se oculta como de larga duración.
• session.stuck se reserva para la contabilidad recuperable de sesiones obsoletas, incluidas las sesiones en cola inactivas con actividad obsoleta de modelo/herramienta sin propietario.

diagnostics.stuckSessionAbortMs tiene un valor predeterminado de al menos 5 minutos y 3 veces el umbral de advertencia. La contabilidad de sesiones obsoletas libera el carril de la sesión afectada inmediatamente después de que pasen las puertas de recuperación; las ejecuciones incrustadas bloqueadas solo se drenan mediante cancelación después del umbral de cancelación, por lo que el trabajo en cola se reanuda sin cortar ejecuciones meramente lentas. La recuperación emite resultados estructurados solicitados/completados; el estado de diagnóstico se marca como inactivo solo si la misma generación de procesamiento sigue siendo la actual, y los diagnósticos session.stuck repetidos aplican backoff mientras la sesión permanece sin cambios.

​

Dónde las cosas pueden terminar antes

• Tiempo de espera del agente (cancelación)
• AbortSignal (cancelar)
• Desconexión de Gateway o tiempo de espera de RPC
• Tiempo de espera de agent.wait (solo espera, no detiene el 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 - puertas de aprobación para comandos de shell
• Thinking - configuración del nivel de pensamiento/razonamiento