Flujo de Ejecución del Agente OpenClaw

Analicemos el pipeline de ejecución de agentes de OpenClaw, cubriendo todo desde la deduplicación de mensajes de canal hasta las estrategias automáticas de failover. Perfecto para desarrolladores que construyen sistemas de agentes de IA o contribuyen a OpenClaw.

OpenClaw parece engañosamente simple desde fuera: un agente conectado a un canal de comunicación que simplemente ejecuta código. Pero bajo el capó, está impulsado por Pi Monorepo, un agente de programación deliberadamente minimalista construido en torno a una única idea, casi herética: que los LLM ya son buenos escribiendo y ejecutando software, por lo que el sistema debería apartarse de su camino y permitirles hacer exactamente eso.

Con un núcleo diminuto, un puñado de herramientas y una potente arquitectura autoextensible, Pi trata el software como algo maleable, inspeccionable y desechable, lo que permite agentes que no solo usan herramientas, sino que se reescriben y evolucionan activamente a sí mismos. OpenClaw es lo que sucede cuando esa filosofía se toma en serio y se conecta directamente con interfaces del mundo real.

Tabla de Contenidos

Introducción
Visión General de la Arquitectura
Fase 1: Recepción de Mensajes y Enrutamiento de Canal
Fase 2: Enrutamiento y Control de Acceso
Fase 3: Resolución de Sesión y Bloqueo
Fase 4: Ensamblaje de Contexto
Fase 5: Inicialización del Runtime del Agente
Fase 6: Ejecución del Modelo y Streaming
Fase 7: Enrutamiento y Ejecución de Llamadas a Herramientas
Fase 8: Entrega de Respuesta
Fase 9: Persistencia de Estado
Manejo de Errores y Estrategias de Failover
Ejemplo de Traza de Extremo a Extremo
Conclusiones Clave

Introducción

OpenClaw es una plataforma de asistente de IA personal autoalojada que conecta modelos de IA (Claude, GPT, Gemini, modelos locales) con canales de mensajería que ya usas: WhatsApp, Telegram, Discord, Slack, Signal, iMessage y más de 15 adicionales.

Lo que distingue a OpenClaw es su sofisticado pipeline de ejecución de agentes, un sistema de orquestación de nueve fases que maneja todo desde la deduplicación de mensajes hasta el failover automático de modelos. Entender este flujo es crucial para:

Contribuidores que quieren extender las capacidades de OpenClaw
Ingenieros de IA diseñando arquitecturas de agentes similares
Equipos de DevOps solucionando problemas en despliegues de producción

Profundicemos en cada fase con referencias de código e insights arquitectónicos.

Visión General de la Arquitectura

La ejecución del agente de OpenClaw envuelve la biblioteca Pi Agent Core y añade integraciones específicas de plataforma para canales, herramientas, sandboxing y configuración.

Punto de Entrada Principal:

runEmbeddedPiAgent en src/agents/pi-embedded-runner/run.ts

Abstracciones Clave:

Abstracción	Propósito
`EmbeddedPiAgentMeta`	Configuración para una instancia de agente (workspace, modelo, herramientas, sandbox)
`EmbeddedPiRunMeta`	Metadatos por turno (clave de sesión, mensaje, contexto de canal)
`EmbeddedPiRunResult`	Resultado de ejecución (éxito, error, uso, tiempo)
`SubscribeEmbeddedPiSessionParams`	Callbacks de streaming para salida en tiempo real

Fase 1: Recepción de Mensajes y Enrutamiento de Canal

Cómo Funciona

Cada adaptador de canal (Telegram, Discord, Slack, WhatsApp, etc.) implementa un pipeline estandarizado de manejo de mensajes:

Estrategia de Deduplicación

Cada canal usa IDs de actualización únicos para prevenir el reprocesamiento. Para Telegram:

// src/telegram/bot.ts (líneas 157-178)
function buildTelegramUpdateKey(update: Update): string {
  return `telegram:${update.update_id}`;
}

// La verificación de duplicados previene que el mismo mensaje active múltiples turnos del agente
if (await isDuplicateUpdate(updateKey)) {
  return; // Descarte silencioso
}

Adaptadores Específicos por Canal

Canal	Biblioteca	Archivo Clave
Telegram	grammY	`src/telegram/bot.ts`
Discord	discord.js	`src/discord/monitor.ts`
Slack	Bolt	`src/slack/monitor.ts`
WhatsApp	Baileys	`src/provider-web.ts`
Signal	signal-cli	`src/signal/`
iMessage	imsg	`src/imessage/`

Fase 2: Enrutamiento y Control de Acceso

Aplicación de Políticas

Antes de que cualquier mensaje llegue al agente, pasa por puertas de control de acceso:


// Las políticas de acceso determinan quién puede interactuar
interface AccessPolicy {
  dmPolicy: 'open' | 'allowlist' | 'pairing' | 'deny';
  groupPolicy: 'open' | 'allowlist' | 'mention' | 'deny';
}

Tipos de Políticas:

Política	Comportamiento en DM	Comportamiento en Grupo
`open`	Acepta todos	Acepta todos
`allowlist`	Verifica lista `allowFrom`	Verifica lista `allowFrom`
`pairing`	Envía código de emparejamiento	N/A
`mention`	N/A	Solo responde cuando es @mencionado
`deny`	Descarte silencioso	Descarte silencioso

Enrutamiento de Agentes

La función resolveAgentRoute determina qué agente maneja un mensaje basándose en los bindings de canal:


// Ejemplo de configuración de binding
{
  bindings: {
    agents: {
      "whatsapp:default": "main",
      "telegram:work_bot": "work",
      "slack:support_bot": "support"
    }
  }
}

Fase 3: Resolución de Sesión y Bloqueo

Patrones de Clave de Sesión

Las claves de sesión aíslan el contexto de conversación. El patrón sigue:

agent:{agentId}:{channel}:{scope}:{identifier}

Ejemplos:

Clave de Sesión	Tipo	Descripción
`agent:main:telegram:dm:123456789`	Telegram DM	Mensaje directo
`agent:main:discord:group:987654321`	Canal de Discord	Canal del servidor
`agent:work:whatsapp:group:120363...@g.us`	Grupo de WhatsApp	Chat grupal
`agent:main:main`	CLI/TUI	Interacción directa por CLI

Flujo de Resolución de Sesión

Modos de Cola

OpenClaw soporta dos modos de ejecución:

Modo	Comportamiento	Caso de Uso
`sequential` (por defecto)	Adquiere bloqueo, procesa uno a la vez por sesión	Flujos de trabajo críticos en consistencia
`concurrent`	Sin bloqueo, procesamiento paralelo	Escenarios de alto rendimiento


// src/agents/pi-embedded-runner/lanes.ts
const lane = await resolveSessionLane(sessionKey, config);
if (lane.mode === 'sequential') {
  await acquireSessionWriteLock(sessionKey);
}

Fase 4: Ensamblaje de Contexto

Construcción del System Prompt

El system prompt se construye desde múltiples fuentes—aquí es donde el poder de OpenClaw se hace evidente:

Secciones del Prompt (Modo Completo)

El system prompt completo incluye estas secciones:

Sección	Condición	Propósito
Identidad de Usuario	`ownerNumbers` configurado	Identificar usuarios autorizados
Fecha y Hora Actual	`userTimezone` configurado	Zona horaria para programación
Skills	`skillsPrompt` presente	Descubrimiento y carga de habilidades
Recuperación de Memoria	herramienta `memory_search` disponible	Guía de integración de memoria
Mensajería	No en modo minimal	Reglas de mensajería cross-channel
Voz (TTS)	`ttsHint` configurado	Uso de etiquetas TTS
Etiquetas de Respuesta	No en modo minimal	Sintaxis nativa de respuesta/cita
Documentación	`docsPath` configurado	Referencia de docs de OpenClaw
Formato de Razonamiento	`reasoningTagHint` true	Uso de etiquetas `<think>`/`<final>`
Referencia Rápida CLI	Siempre (modo completo)	Comandos del gateway
Entorno de Ejecución	`runtimeInfo` presente	Contexto de host/OS/modelo
Herramientas	`toolNames` presente	Lista de herramientas disponibles
Workspace	Siempre	Directorio del workspace
Sandbox	Sandbox habilitado	Puente del navegador, modo elevado

Modos de Prompt


type PromptMode = 'full' | 'minimal' | 'none';

// Full: Todas las secciones (por defecto para agente principal)
// Minimal: Secciones reducidas - usado para subagentes
// None: Solo línea básica de identidad

Fase 5: Inicialización del Runtime del Agente

Configuración del Runtime

Antes de la ejecución del modelo, el runtime ensambla el contexto de ejecución completo:


// src/agents/pi-embedded-runner/run.ts
interface RuntimeContext {
  sessionKey: string;              // ej., "agent:main:telegram:dm:123"
  agentConfig: AgentConfig;        // De agents.list[agentId]
  workspace: string;               // Directorio raíz para archivos del agente
  agentDir: string;                // ~/.openclaw/agents/main/agent
  toolRegistry: Tool[];            // De createOpenClawCodingTools
  sandboxContext: SandboxContext;  // Configuración de contenedor Docker
  bootstrapFiles: string[];        // AGENTS.md, SOUL.md, TOOLS.md
  memoryResults: MemoryResult[];   // De búsqueda de memoria
}

Componentes Clave del Runtime

Componente	Fuente	Descripción
Workspace	`agents.list[].workspace`	Directorio raíz para archivos del agente
Directorio del Agente	Derivado del ID del agente	Perfiles de auth, caché, estado
Archivos Bootstrap	Auto-descubiertos	AGENTS.md, SOUL.md, TOOLS.md
Registro de Herramientas	`tools.allow`, `tools.deny`	Herramientas disponibles (exec, read, browser)
Contexto de Sandbox	`agents.list[].sandbox`	Contenedor Docker para aislamiento
Búsqueda de Memoria	`memorySearch.*`	Recuperación híbrida BM25 + vector

Fase 6: Ejecución del Modelo y Streaming

Flujo de Solicitud al Modelo

Esta fase maneja la interacción real con el modelo de IA con failover sofisticado:

Tipos de Eventos


// Eventos de streaming del proveedor de modelo
type StreamEvent = 
  | { type: 'text_delta'; content: string }
  | { type: 'tool_call'; name: string; arguments: object }
  | { type: 'thinking_delta'; content: string }
  | { type: 'message_end'; reason: StopReason }
  | { type: 'error'; error: Error };

Manejo de Eventos en `subscribeEmbeddedPiSession`

Evento	Comportamiento del Handler
`text_delta`	Acumula en `deltaBuffer`, fragmenta para streaming
`tool_call`	Enruta al ejecutor de herramientas, espera resultado
`thinking_delta`	Opcionalmente transmite razonamiento (si `reasoningMode=stream`)
`message_end`	Finaliza texto del asistente, guarda en sesión

Fase 7: Enrutamiento y Ejecución de Llamadas a Herramientas

Árbol de Decisión de Ejecución de Herramientas

OpenClaw implementa un sofisticado sistema de políticas multicapa para la ejecución de herramientas:

Precedencia de Políticas de Herramientas

Las políticas se evalúan en orden de más a menos restrictiva:

Perfil de Herramientas: Lista permitida base (tools.profile)
Perfil de Proveedor: Restricciones específicas por proveedor (tools.byProvider)
Política Global: tools.allow / tools.deny
Política de Agente: agents.list[].tools.allow / agents.list[].tools.deny
Política de Grupo: Restricciones por grupo/canal
Política de Sandbox: Lista permitida de herramientas del sandbox (agents.list[].sandbox.tools)
Política de Subagente: Heredada del padre

Flujo de Aprobación de Herramienta Exec

Para la ejecución de comandos shell, se aplican puertas de seguridad adicionales:


// Configuración de tools.exec
interface ExecToolConfig {
  ask: 'off' | 'elevated' | 'always';
  security: 'full' | 'sandbox';
  safeBins: string[];  // Comandos auto-aprobados (ls, cat, etc.)
}

// ¿Se necesita aprobación? Verificar en este orden:
// 1. ¿Está el comando en safeBins? → Auto-aprobar
// 2. ¿Es security=sandbox y ejecutando en sandbox? → Auto-aprobar
// 3. ¿Es ask=off? → Auto-aprobar
// 4. De lo contrario → Enviar prompt de aprobación, esperar /approve <id>

Grupos de Herramientas

Grupo	Herramientas Incluidas
`group:fs`	read, write, edit, apply_patch, grep, find, ls
`group:runtime`	exec, process
`group:sessions`	sessions_list, sessions_history, sessions_send, sessions_spawn
`group:memory`	memory_search, memory_get
`group:messaging`	message (todas las acciones)

Fase 8: Entrega de Respuesta

Streaming y Fragmentación

La entrega de respuestas se adapta a las capacidades del canal:

Modos de Streaming por Bloques

Modo	Comportamiento
`text_end`	Transmitir mensaje completo después de `message_end`
`tool_call`	Transmitir después de que cada llamada a herramienta complete
`text_delta`	Transmitir en cada text delta (tiempo real)

Configuración de Fragmentación


// Configuración de fragmentación por canal
interface ChunkConfig {
  textChunkLimit: number;  // Máx caracteres por fragmento (varía por canal)
  chunkMode: 'length' | 'newline';  // Estrategia de división
}

// Valores por defecto por canal:
// Telegram: 4096 caracteres
// Discord: 2000 caracteres
// WhatsApp: 65536 caracteres

Fase 9: Persistencia de Estado

Esquema del Almacén de Sesión

Después de cada turno del agente, el estado de la sesión se persiste:


interface SessionStore {
  history: Array<{
    role: 'user' | 'assistant' | 'system';
    content: string;
    timestamp: string;
  }>;
  thinkingLevel: 'off' | 'low' | 'medium' | 'high';
  verboseLevel: 0 | 1 | 2 | 3;
  model?: string;
  sendPolicy?: 'announce' | 'quiet';
  groupActivation?: 'mention' | 'always';
  lastActiveAt?: string;
  messageCount?: number;
  totalTokens?: number;
  totalCost?: number;
}

Ubicación de Almacenamiento

Las sesiones se almacenan como archivos JSONL:

Ubicación: ~/.openclaw/sessions/{sessionKey}.jsonl
Formato: Un objeto JSON por línea (mensajes, metadatos, eventos)

Auto-Compactación

Cuando el contexto se desborda, OpenClaw compacta automáticamente el historial:



Estrategia de Compactación:

Divide el historial en segmentos semánticos (chunking adaptativo)
Resume cada segmento vía modelo
Fusiona resúmenes en contexto compacto
Retiene los últimos N turnos literalmente (configurable)

Políticas de Reinicio

Política	Comportamiento
`daily`	Reiniciar a las 4am hora local
`idle`	Reiniciar después de N horas de inactividad
`none`	Solo `/reset` manual

Manejo de Errores y Estrategias de Failover

Clasificación de Errores

OpenClaw clasifica los errores para determinar la estrategia de failover apropiada:

Tipo de Error	Detección	Acción de Recuperación
Errores de Auth	`isAuthAssistantError` (401, invalid_api_key)	Rotar perfil de auth
Errores de Facturación	`isBillingAssistantError` (402, insufficient_quota)	Cooldown + modelo de respaldo
Límites de Tasa	`isRateLimitAssistantError` (429)	Failover inmediato
Desbordamiento de Contexto	`isContextOverflowError`	Auto-compactar + reintentar
Timeouts	`isTimeoutErrorMessage`	Reintentar mismo modelo
Errores de Tamaño de Imagen	`isImageSizeError`	Mostrar al usuario

Comportamiento de Cooldown


// Configuración de cooldown por defecto
interface CooldownConfig {
  billingBackoffHours: 24;      // Cooldown por defecto para error de facturación
  failureWindowHours: 1;        // Rastrear errores durante esta ventana
  billingMaxHours: 168;         // Cooldown máximo (7 días)
}

Algoritmo de Rotación de Perfil de Auth


1. Verificar auth.order[provider] para lista de perfiles
2. Omitir perfiles en cooldown
3. Intentar siguiente perfil con credenciales válidas
4. Si todos los perfiles agotados → recurrir al siguiente modelo en la cadena de fallback

Ejemplo de Traza de Extremo a Extremo

Tracemos una ejecución completa para: «Escribe un script de hola mundo» enviado vía Telegram.

RECEPCIÓN — Bot de Telegram recibe update y valida que no es duplicado.
POLÍTICA — Verifica channels.telegram.allowFrom y pasa.
ENRUTAMIENTO — Resuelve a agent:main:telegram:dm:123456789.
COLA — Llama queueEmbeddedPiMessage con clave de sesión.
BLOQUEO — Adquiere bloqueo de sesión (si queueMode=sequential).
CARGAR — Lee almacén de sesión desde ~/.openclaw/sessions/agent:main/sessions.json.
BOOTSTRAP — Lee AGENTS.md, SOUL.md y TOOLS.md del workspace.
MEMORIA — Consulta búsqueda de memoria con «Escribe un script…».
HERRAMIENTAS — Construye registro de herramientas (exec, read, write).
PROMPT — Combina bootstrap + memoria + herramientas en el system prompt.
MODELO — Transmite a anthropic/claude-sonnet-4-5 con failover.
DELTA — Recibe eventos text_delta y los acumula en buffer.

TOOL CALL — El modelo llama:

write(
  path="hello.sh",
  content="#!/bin/bash
echo 'Hola, Mundo!'
")

VERIFICACIÓN DE POLÍTICA — Valida que write esté permitido.
EJECUTAR — Escribe el archivo en el workspace.
RESULTADO — Retorna éxito al modelo.
FINAL — El modelo envía: «He creado un script de hola mundo».
STREAM — Fragmenta respuesta para Telegram (límite 4096).
GUARDAR — Escribe el almacén de sesión actualizado con el nuevo turno.
DESBLOQUEAR — Libera el bloqueo de sesión.

Conclusiones Clave

1. La Arquitectura Multi-Fase Proporciona Flexibilidad

El pipeline de nueve fases permite una separación limpia de responsabilidades. Cada fase puede ser extendida o modificada independientemente.

2. La Seguridad es Multi-Capa

La ejecución de herramientas pasa por 7 capas de políticas. El aislamiento de sandbox proporciona protección adicional para ejecución de código no confiable.

3. El Failover es Automático e Inteligente

La clasificación de errores impulsa la estrategia de recuperación—desde reintentos simples hasta rotación de auth y cadenas de failover de modelos.

4. La Gestión de Contexto es Sofisticada

La búsqueda híbrida de memoria (BM25 + vector) combinada con compactación automática asegura que los agentes mantengan contexto relevante sin alcanzar límites de tokens.

5. La Abstracción de Canal Habilita Portabilidad

La misma lógica de agente funciona a través de más de 15 plataformas de mensajería a través de adaptadores de canal que manejan formateo y capacidades específicas de cada plataforma.

Contribuir a OpenClaw

¿Quieres profundizar más? Aquí están los archivos fuente clave:

Componente	Ruta del Archivo
Punto de Entrada del Agente	`src/agents/pi-embedded-runner/run.ts`
Gestión de Sesiones	`src/config/sessions.ts`
Registro de Herramientas	`src/agents/pi-tools.ts`
Constructor de System Prompt	`src/agents/pi-embedded-runner/system-prompt.ts`
Clasificación de Errores	`src/agents/pi-embedded-helpers/errors.ts`
Enrutamiento de Canal	`src/routing/session-key.ts`
Streaming	`src/agents/pi-embedded-subscribe.ts`

Repositorio de GitHub: github.com/openclaw/openclaw

¿Te resultó útil esta inmersión profunda? ¡Sígueme para más análisis técnicos de proyectos de infraestructura de IA de código abierto!