Guía de solución de problemas: Sesiones de agentes anidados bloqueándose entre sí

Síntomas

Si está ejecutando múltiples sesiones de agente simultáneamente, puede encontrar los siguientes síntomas:

• Respuestas retrasadas o faltantes: Una o más sesiones de agente parecen “congelarse” o tomar significativamente más tiempo del esperado para responder, incluso cuando la tarea solicitada es simple.
• Bloqueo entre sesiones: Una tarea de larga duración en una sesión (como una ejecución de ACP Claude Code) causa retrasos en sesiones completamente no relacionadas.
• Tiempo de espera del gateway agotado: Mensajes de error en los registros que indican lane wait exceeded: lane=nested waitedMs=XXXXX queueAhead=1.
• Fallos de entrega en Discord: Las respuestas del asistente generadas durante el backlog nunca se entregan a los canales de Discord.
• Comportamiento inconsistente: Algunas sesiones responden instantáneamente mientras otras permanecen inactivas durante minutos, incluso cuando las tareas subyacentes no están relacionadas.

Causa raíz

La causa raíz fue un cuello de botella de cola global única en el sistema de ejecución de agentes anidados.

Anteriormente, todas las operaciones de agentes anidados en todas las sesiones compartían un carril llamado "nested" con maxConcurrent=1. Esto significaba:

1. Cada sessions_send, runAgentStep y envío de ACP competía por la misma entrada en la cola.
2. Cuando la sesión A ejecutaba una tarea de 10 minutos, las sesiones B, C y D tenían que esperar en línea detrás de ella.
3. La cola de comandos trataba cada operación anidada de manera idéntica, independientemente de a qué sesión estaba dirigida.

Esta limitación arquitectónica causaba un bloqueo de cabeza de línea donde una única operación anidada de larga duración podía paralizar todas las demás sesiones de agente en el gateway.

Solución paso a paso

Opción 1: Actualizar a la versión corregida (Recomendado)

Actualice su instalación de OpenClaw a la versión v2026.4.19-beta.2 o posterior.

Esta versión introduce carriles anidados por sesión que limitan el trabajo anidado a nested:<sessionKey>, permitiendo la ejecución paralela en diferentes sesiones mientras mantiene los invariantes de concurrencia dentro de cada sesión.

Opción 2: Verificar la configuración del carril (Para verificación manual)

Si necesita verificar que la corrección se aplicó correctamente, revise los registros del gateway para ver los nombres de los carriles que se están usando:

Antes de la corrección, vería registros como:

[agent:nested] Processing session A
[agent:nested] Processing session B

Después de la corrección, debería ver nombres de carriles con ámbito:

[agent:nested:session-A] Processing session A
[agent:nested:session-B] Processing session B

Opción 3: Verificar el mapa de estado del carril

En su configuración de gateway, el estado del carril ahora debe estar indexado por el identificador completo con ámbito de sesión en lugar de la cadena desnuda "nested". Cada entrada debe mostrar:

• nested:<sessionKey> para sesiones estándar
• "nested" como alternativa para rutas cron heredadas únicamente

Verificación

Para confirmar que la corrección funciona correctamente:

1. Ejecute múltiples sesiones concurrentes: Configure dos o más sesiones de agente que puedan recibir operaciones anidadas.
2. Inicie una tarea de larga duración en una sesión: Por ejemplo, invoque una tarea que tome varios minutos en completarse.
3. Envíe una tarea rápida a otra sesión: Mientras la tarea larga se está ejecutando, envíe una solicitud simple a una sesión diferente.
4. Verifique la ejecución en paralelo: La segunda sesión debe responder inmediatamente sin esperar a que la tarea de la primera sesión se complete.
5. Revise los registros para carriles con ámbito: Busque prefijos [agent:nested:<sessionKey>] en los registros de su gateway confirmando el aislamiento de carriles por sesión.

Resultados de pruebas esperados después de la corrección:

pnpm test src/agents/lanes.test.ts         # 13 tests green
pnpm test src/gateway/server.sessions-send.test.ts  # 14 tests green
pnpm test 'src/agents/**/*.test.ts'        # 3841 tests green

Errores comunes

Manejo de claves de sesión

• Claves de sesión vacías o solo espacios en blanco: Estas regresan al carril sin ámbito "nested". Asegúrese de que sus claves de sesión estén correctamente pobladas antes de enrutar operaciones anidadas.
• Rutas cron heredadas: Las integraciones cron que usan resolveNestedAgentLane(lane) todavía usan la alternativa sin ámbito. Esto es intencional para compatibilidad hacia atrás.

Colisiones de nombres de carriles

• Nombres de carriles proporcionados por el usuario: Si tiene carriles personalizados con nombres como "nested:something", tenga en cuenta que estos son distintos de los carriles nested:<sessionKey> generados por el sistema. El carril del sistema usa una convención de prefijo específica que coincide con el patrón existente session:<key>.

Consideraciones de memoria

El Map de estado del carril ahora crece a medida que aparecen nuevas claves de sesión. Cada entrada de estado del carril es aproximadamente 200 bytes. El límite superior realista es el número de sesiones activas, que ya está limitado por la gestión de sesiones de su gateway. Una mejora futura para eliminar carriles anidados inactivos puede agregarse si esto se convierte en una preocupación.

Problemas no relacionados

Dos problemas relacionados mencionados en el informe original permanecen fuera del alcance de esta corrección:

• Corrupción del contexto de entrega de sesiones
• Ausencia de mecanismos de reintento de entrega/DLQ

Estos son seguimientos arquitectónicos rastrados por separado.

Errores relacionados

Versiones afectadas

• Corregido en: v2026.4.19-beta.2
• Versiones afectadas: v2026.4.14 y anteriores

Compatibilidad

Esta corrección es completamente compatible hacia atrás:

• La constante AGENT_LANE_NESTED todavía se exporta
• Los llamadores que continúan pasando la constante directamente mantienen su comportamiento existente (sin ámbito)
• No se requieren cambios de configuración
• No se necesitan pasos de migración

La corrección fortalece el aislamiento de sesiones sin romper las integraciones existentes.