Fundamentals

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 del contexto, inferencia del modelo, ejecución de herramientas, transmisión y persistencia.

Puntos de entrada

RPC del Gateway: agent y agent.wait.
CLI: openclaw agent.

Secuencia de ejecución

El RPC agent valida los parámetros, resuelve la sesión (sessionKey/sessionId), conserva los metadatos de la sesión y devuelve { runId, acceptedAt } inmediatamente.
agentCommand ejecuta el turno: resuelve el modelo y los valores predeterminados de razonamiento, detalle y seguimiento, carga la instantánea de Skills, llama a runEmbeddedAgent y emite un evento alternativo de fin/error del ciclo de vida si el bucle integrado aún no ha emitido uno.
runEmbeddedAgent: serializa las ejecuciones mediante colas por sesión y globales, resuelve el modelo y el perfil de autenticación, crea la sesión de OpenClaw, se suscribe a los eventos del entorno de ejecución, transmite los incrementos del asistente y de las herramientas, aplica el tiempo límite de ejecución (interrumpiéndola cuando vence) y devuelve las cargas útiles junto con los metadatos de uso. En los turnos del servidor de aplicaciones de Codex, también interrumpe un turno aceptado que deja de producir progreso del servidor de aplicaciones antes de un evento terminal.
subscribeEmbeddedAgentSession conecta los eventos del entorno de ejecución con el flujo de agent: los eventos de herramientas con stream: "tool", los incrementos del asistente con stream: "assistant" y los eventos del ciclo de vida con stream: "lifecycle" (phase: "start" | "end" | "error").
agent.wait (waitForAgentRun) espera un fin/error del ciclo de vida para un runId y devuelve { status: ok|error|timeout, startedAt, endedAt, error? }.

Colas y concurrencia

Las ejecuciones se serializan por clave de sesión (canal de sesión) y, opcionalmente, mediante un canal global, lo que evita condiciones de carrera entre herramientas y sesiones. Los canales de mensajería eligen un modo de cola (dirigir/continuar/recopilar/interrumpir) que alimenta este sistema de canales; consulte Cola de comandos.

Las escrituras de la transcripción también están protegidas mediante un bloqueo de escritura de sesión sobre el archivo de sesión. El bloqueo tiene en cuenta los procesos y está basado en archivos, por lo que detecta escritores que omiten la cola interna del proceso o proceden de otro proceso. Los escritores esperan hasta session.writeLock.acquireTimeoutMs (valor predeterminado: 60000 ms; se puede sustituir mediante la variable de entorno OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS) antes de informar de que la sesión está ocupada.

De forma predeterminada, los bloqueos de escritura de sesión no son reentrantes. Una función auxiliar que anide intencionadamente la adquisición del mismo bloqueo mientras conserva un único escritor lógico debe habilitarlo con allowReentrant: true.

Preparación de la sesión y del espacio de trabajo

El espacio de trabajo se resuelve y se crea; las ejecuciones aisladas pueden redirigirse a la raíz de un espacio de trabajo aislado.
Las Skills se cargan (o se reutilizan desde una instantánea) y se incorporan al entorno y al prompt.
Los archivos de arranque y contexto se resuelven y se incorporan al prompt del sistema.
Se adquiere un bloqueo de escritura de sesión y se prepara el destino de la transcripción de la sesión antes de iniciar la transmisión. Cualquier ruta posterior de reescritura, Compaction o truncamiento de la transcripción debe adquirir el mismo bloqueo antes de modificar las filas de la transcripción en SQLite.

Ensamblaje del prompt

El prompt del sistema se crea a partir del prompt base de OpenClaw, el prompt de Skills, el contexto de arranque y las sustituciones específicas de cada ejecución. Se aplican los límites específicos del modelo y los tokens de reserva para Compaction. Consulte Prompt del sistema para saber qué ve el modelo.

Hooks

OpenClaw tiene dos sistemas de hooks:

Hooks internos (hooks del Gateway): scripts controlados por eventos para comandos y eventos del ciclo de vida.
Hooks de Plugin: puntos de extensión dentro del ciclo de vida del agente y las herramientas, y de la canalización del Gateway.

Hooks internos (hooks del Gateway)

agent:bootstrap: se ejecuta mientras se crean los archivos de arranque, antes de finalizar el prompt del sistema. Se utiliza para añadir o eliminar archivos de contexto de arranque.
Hooks de comandos: /new, /reset, /stop y otros eventos de comandos (consulte la documentación de hooks).

Consulte Hooks para ver la configuración y ejemplos.

Hooks de Plugin

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

Hook	Cuándo se ejecuta
`before_model_resolve`	Antes de la sesión (sin `messages`), para sustituir de forma determinista el proveedor o modelo antes de la resolución.
`before_prompt_build`	Después de cargar la sesión (con `messages`), para incorporar `prependContext`, `systemPrompt`, `prependSystemContext` o `appendSystemContext` antes del envío. Utilice `prependContext` para texto dinámico por turno y los campos de contexto del sistema para instrucciones estables que correspondan al espacio del prompt del sistema.
`before_agent_start`	Hook de compatibilidad heredado que puede ejecutarse en cualquiera de las fases; se prefieren los hooks explícitos anteriores.
`before_agent_reply`	Después de las acciones en línea y antes de la llamada al LLM. Permite que un Plugin reclame el turno y devuelva una respuesta sintética o lo silencie por completo.
`agent_end`	Después de finalizar, con la lista final de mensajes y los metadatos de la ejecución.
`before_compaction` / `after_compaction`	Observan o anotan los ciclos de Compaction.
`before_tool_call` / `after_tool_call`	Interceptan los parámetros y resultados de las herramientas.
`before_install`	Después de aplicar la política de instalación del operador, sobre el material de instalación preparado de Skills o plugins, cuando los hooks de Plugin están cargados en el proceso actual.
`tool_result_persist`	Transforma sincrónicamente los resultados de las herramientas antes de escribirlos 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 la sesión.
`gateway_start` / `gateway_stop`	Eventos del ciclo de vida del Gateway.

Reglas de decisión de los hooks para las protecciones de salida y herramientas:

before_tool_call: { block: true } es terminal y detiene los controladores de menor prioridad. { block: false } no realiza ninguna acción ni elimina un bloqueo anterior.
before_install: tiene la misma semántica terminal/sin efecto descrita anteriormente. Utilice security.installPolicy, no before_install, para las decisiones de permitir o bloquear instalaciones que pertenezcan al operador y deban abarcar las rutas de instalación y actualización de la CLI.
message_sending: { cancel: true } es terminal y detiene los controladores de menor prioridad. { cancel: false } no realiza ninguna acción ni elimina una cancelación anterior.

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

Los arneses pueden adaptar estos hooks. El arnés del servidor de aplicaciones de Codex mantiene los hooks de Plugin de OpenClaw como contrato de compatibilidad para las superficies reflejadas documentadas; los hooks nativos de Codex son un mecanismo independiente de Codex y de nivel inferior.

Transmisión

Los incrementos del asistente se transmiten desde el entorno de ejecución del agente como eventos assistant.
La transmisión por bloques puede emitir respuestas parciales en text_end o message_end.
La transmisión del razonamiento puede ser un flujo independiente o bloquear las respuestas.
Consulte Transmisión para conocer el comportamiento de la fragmentación y las respuestas por bloques.

Ejecución de herramientas

Los eventos de inicio, actualización y finalización de herramientas se emiten en el flujo tool.
Los resultados de las herramientas se depuran según el tamaño y las cargas útiles de imágenes antes de registrarlos o emitirlos.
Los envíos de herramientas de mensajería se rastrean para suprimir confirmaciones duplicadas del asistente.

Conformación de respuestas

Las cargas útiles finales se ensamblan a partir del texto del asistente (más el razonamiento opcional), los resúmenes de herramientas en línea (cuando el modo detallado está activado y permitido) y el texto de error del asistente cuando el modelo produce un error.

El token silencioso exacto NO_REPLY se filtra de las cargas útiles salientes.
Los duplicados de las herramientas de mensajería se eliminan de la lista final de cargas útiles.
Si no quedan cargas útiles representables y una herramienta produjo un error, se emite una respuesta alternativa de error de herramienta, 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 compaction en el flujo y puede activar un reintento. Al reintentar, los búferes en memoria y los resúmenes de herramientas se restablecen para evitar resultados duplicados. Consulte Compaction.

Flujos de eventos

lifecycle: lo emite subscribeEmbeddedAgentSession (y, como alternativa, agentCommand).
assistant: incrementos transmitidos desde el entorno de ejecución del agente.
tool: eventos de herramientas transmitidos desde el entorno de ejecución del agente.

El Gateway proyecta los eventos de inicio y terminales del ciclo de vida y de las herramientas en el registro de auditoría acotado y compuesto únicamente por metadatos. Esta proyección registra la procedencia y los códigos de resultado sin copiar prompts, mensajes, argumentos de herramientas, resultados de herramientas ni errores sin procesar fuera de la ruta de la transcripción y del entorno de ejecución.

Gestión del canal de chat

Los incrementos del asistente se almacenan en búfer en mensajes delta del chat. Se emite un mensaje final del chat al producirse un fin/error del ciclo de vida.

Tiempos límite

Tiempo de espera	Valor predeterminado	Notas
`agent.wait`	30s	Solo espera; el parámetro `timeoutMs` lo sustituye. No detiene la ejecución subyacente.
Tiempo de ejecución del agente (`agents.defaults.timeoutSeconds`)	172800s (48h)	Se aplica mediante el temporizador de cancelación de `runEmbeddedAgent`. Establezca `0` para disponer de un presupuesto de ejecución ilimitado; los supervisores de actividad del flujo del modelo siguen aplicándose.
Turno aislado del agente de Cron	gestionado por Cron	El planificador inicia su propio temporizador cuando comienza la ejecución, cancela la ejecución en el plazo configurado y, a continuación, realiza una limpieza acotada antes de registrar el tiempo de espera agotado para que una sesión secundaria obsoleta no pueda mantener bloqueado el canal de ejecución.
Tiempo de espera por inactividad del modelo	Nube 120s; alojamiento propio 300s	OpenClaw cancela una solicitud al modelo cuando no llegan fragmentos de respuesta antes de que finalice el intervalo de inactividad. `models.providers.<id>.timeoutSeconds` amplía este supervisor de inactividad para proveedores locales o con alojamiento propio lentos, pero sigue limitado por cualquier valor finito inferior de `agents.defaults.timeoutSeconds` o por el tiempo de espera específico de la ejecución, ya que estos controlan toda la ejecución del agente. Los presupuestos de ejecución ilimitados siguen manteniendo el supervisor de inactividad de la clase de proveedor. Las ejecuciones de modelos en la nube activadas por Cron sin un tiempo de espera explícito del modelo o agente usan el mismo valor predeterminado; con un tiempo de espera explícito para la ejecución de Cron, los bloqueos del flujo de modelos en la nube se limitan a 60s para que las alternativas de modelo configuradas aún puedan ejecutarse antes del plazo externo de Cron. Las ejecuciones activadas por Cron en extremos realmente locales (baseUrl de bucle invertido/privada) mantienen la exclusión del tiempo de espera por inactividad local; los proveedores con alojamiento propio en baseUrls de red reciben el supervisor implícito de 300s. Con un tiempo de espera explícito para la ejecución de Cron, los bloqueos locales o con alojamiento propio se limitan a ese tiempo de espera. Establezca `models.providers.<id>.timeoutSeconds` para proveedores locales lentos.
Tiempo de espera de la solicitud HTTP del proveedor	`models.providers.<id>.timeoutSeconds`	Abarca la conexión, los encabezados, el cuerpo, el tiempo de espera de la solicitud del SDK, la gestión de cancelación de guarded-fetch y el supervisor de inactividad del flujo del modelo para ese proveedor. Úselo para proveedores locales o con alojamiento propio lentos (por ejemplo, Ollama) antes de aumentar el tiempo de espera de toda la ejecución del agente; mantenga el tiempo de espera del agente o de la ejecución como mínimo en el mismo valor cuando la solicitud al modelo necesite ejecutarse durante más tiempo.

Diagnóstico de sesiones bloqueadas

Con los diagnósticos habilitados, diagnostics.stuckSessionWarnMs (valor predeterminado: 120000 ms) clasifica las sesiones processing prolongadas en las que no se ha observado ningún progreso de respuesta, herramienta, estado, bloqueo ni ACP:

Las ejecuciones integradas, las llamadas al modelo y las llamadas a herramientas activas se notifican como session.long_running. Las llamadas silenciosas al modelo con propietario permanecen como session.long_running hasta diagnostics.stuckSessionAbortMs, para que los proveedores lentos o sin transmisión no se marquen como bloqueados demasiado pronto.
El trabajo activo sin progreso reciente se notifica como session.stalled. Las llamadas al modelo con propietario cambian a session.stalled al alcanzar o superar el umbral de cancelación; la actividad obsoleta del modelo o de herramientas sin propietario no se oculta como una ejecución prolongada.
session.stuck se reserva para el registro interno recuperable de sesiones obsoletas, incluidas las sesiones inactivas en cola con actividad obsoleta del modelo o de herramientas sin propietario.

El valor predeterminado de diagnostics.stuckSessionAbortMs es de al menos 5 minutos y 3 veces el umbral de advertencia. El registro interno de sesiones obsoletas libera el canal de ejecución de la sesión afectada inmediatamente después de que se superan las comprobaciones de recuperación; las ejecuciones integradas bloqueadas solo se cancelan y drenan después del umbral de cancelación, por lo que el trabajo en cola se reanuda sin interrumpir ejecuciones que simplemente son lentas. La recuperación emite resultados estructurados de solicitud y finalización; el estado de diagnóstico solo se marca como inactivo si la misma generación de procesamiento sigue siendo la actual, y los diagnósticos session.stuck repetidos aplican una espera incremental mientras la sesión permanezca sin cambios.

Situaciones en las que el proceso puede finalizar antes

Tiempo de espera del agente (cancelación)
AbortSignal (cancelación)
Desconexión del Gateway o tiempo de espera de RPC
Tiempo de espera de agent.wait (solo espera; no detiene el agente)

Contenido relacionado

Herramientas - herramientas disponibles para el agente
Hooks - scripts controlados por eventos que se activan mediante eventos del ciclo de vida del agente
Compaction - cómo se resumen las conversaciones largas
Aprobaciones de ejecución - controles de aprobación para comandos del shell
Pensamiento - configuración del nivel de pensamiento/razonamiento

Was this useful?