El comando sessions_spawn falla inmediatamente al intentar iniciar sub-agentes lógicos aislados, independientemente de la configuración del runtime (acp, subagent o isolated).

Salida de Error

$ openclaw sessions_spawn --agent my-agent --runtime acp -- "analyze this data"

Error: gateway closed (1008): pairing required
    at WebSocket.<anonymous> (/path/to/node_modules/@openclaw/core/src/gateway/ws-client.js:142:15)
    at WebSocket.emit (node:events:518:28)
    at WebSocket.onClose (/path/to/node_modules/@openclaw/core/src/gateway/ws-client.js:89:12)
    at SockJS.onClose (/path/to/node_modules/@openclaw/core/src/gateway/ws-client.js:56:14)

Session spawn failed: Connection rejected by gateway security policy

Registros del Gateway

[gateway] WARN  [12:34:56.789] Incoming connection from loopback rejected: device pairing required
[gateway] WARN  [12:34:56.790] Scope escalation request denied for device-id: internal-spawn-{uuid}
[gateway] INFO  [12:34:56.791] Connection closed: code=1008, reason=pairing required

Contexto de Configuración

La siguiente configuración está presente en openclaw.json:

{
  "acp": {
    "allowedAgents": ["my-agent", "analysis-agent"]
  }
}

Manifestaciones del Comportamiento

• El spawn del sub-agente falla consistentemente en cada invocación
• La aprobación manual del dispositivo mediante openclaw devices approve no resuelve el problema
• El error ocurre incluso al iniciar agentes apuntando a localhost o 127.0.0.1
• La sesión principal continúa funcionando normalmente; solo los sub-agentes iniciados se ven afectados
• Todos los problemas relacionados (#12210, #21445, #30740, #59428) exhiben códigos de error y comportamiento idéntico

Análisis Arquitectónico

El mecanismo sessions_spawn en OpenClaw v2026.4.12 establece una conexión WebSocket interna desde el proceso del sub-agente iniciado hacia el gateway. Esta conexión atraviesa la interfaz loopback (127.0.0.1) y está sujeta a la capa de aplicación de emparejamiento de dispositivos del gateway.

Secuencia de Falla

1. Iniciación del Spawn: La sesión principal invoca sessions_spawn, creando un nuevo proceso aislado para el agente objetivo.
2. Handshake con el Gateway: El proceso del sub-agente inicia una conexión WebSocket a ws://localhost:{gateway-port}/acp.
3. Identificación del Dispositivo: El middleware de emparejamiento del gateway asigna a la conexión interna un identificador de dispositivo transitorio: internal-spawn-{uuid}.
4. Bloqueo de Escalada de Alcance: El agente iniciado solicita alcances elevados (ejecución de agente, gestión de sesión) que el gateway clasifica como requeridos para un dispositivo emparejado.
5. Rechazo 1008: El gateway termina la conexión con el código de cierre WebSocket 1008 (Policy Violation), citando "pairing required".

Causa Raíz Técnica

La regresión proviene de un cambio en v2026.4.12 que eliminó la omisión de emparejamiento implícita para conexiones loopback internas. Las versiones anteriores trataban las conexiones 127.0.0.1 como inherentemente confiables, otorgando automáticamente el alcance internal:spawn. La actualización unificó la aplicación de emparejamiento en todas las interfaces de red, rompiendo inadvertidamente la ruta de spawn de sub-agentes.

La configuración del gateway no distingue entre:

• Conexiones de dispositivos externos (que legítimamente requieren emparejamiento)
• Conexiones loopback internas de sub-agentes iniciados

Análisis de la Ruta del Código

// gateway/src/middleware/pairing-enforcer.ts (v2026.4.12)
function enforcePairing(ws, req) {
  const remoteAddr = req.socket.remoteAddress;
  
  // REMOVED: Legacy bypass for loopback
  // if (remoteAddr === '127.0.0.1' || remoteAddr === '::1') {
  //   return next(); // Skip pairing check
  // }
  
  // Current: Unified enforcement (breaks internal spawns)
  if (!isDevicePaired(req.headers['x-device-id'])) {
    ws.close(1008, 'pairing required');
    return;
  }
}

Brecha de Configuración

La configuración acp.allowedAgents controla qué agentes pueden ser invocados, pero no otorga exención de emparejamiento para la conexión interna del agente al gateway. Estos son controles de seguridad ortogonales que fueron incorrectamente conjugados.

Opción 1: Configurar Exención de Emparejamiento Loopback (Recomendado)

Añade una exención explícita de emparejamiento loopback en la configuración del gateway:

Paso 1: Localiza o crea el archivo de configuración del gateway:

# Linux/macOS
~/.config/openclaw/gateway.json

# Windows
%APPDATA%\openclaw\gateway.json

# Docker container
/path/to/config/gateway.json

Paso 2: Añade la configuración de exención de pairing:

{
  "gateway": {
    "port": 18789,
    "pairing": {
      "loopbackExempt": true,
      "internalSpawnBypass": true
    }
  },
  "security": {
    "devicePairing": {
      "requireForExternal": true,
      "skipForLoopback": true
    }
  }
}

Paso 3: Reinicia el gateway:

# If running as a service
sudo systemctl restart openclaw-gateway

# Or if running directly
openclaw gateway stop
openclaw gateway start

Opción 2: Usar Runtime Local en Lugar de ACP

Evita completamente la ruta del gateway ACP usando el runtime local para los agentes iniciados:

# Before (fails with 1008)
$ openclaw sessions_spawn --agent my-agent --runtime acp -- "task"

# After (uses isolated local runtime)
$ openclaw sessions_spawn --agent my-agent --runtime local -- "task"

Opción 3: Sobrescritura de Variable de Entorno

Establece la variable de entorno OPENCLAW_INTERNAL_SPAWN_BYPASS antes de iniciar el gateway:

# Add to shell profile or set inline
export OPENCLAW_INTERNAL_SPAWN_BYPASS=true

# Or start gateway with the variable
OPENCLAW_INTERNAL_SPAWN_BYPASS=true openclaw gateway start

Opción 4: Desactivar Aplicación de Emparejamiento (Solo Desarrollo)

Solo para entornos de desarrollo, desactiva el emparejamiento completamente:

{
  "gateway": {
    "port": 18789,
    "security": {
      "enforcePairing": false
    }
  }
}

ADVERTENCIA: Esta configuración desactiva el emparejamiento para TODAS las conexiones, incluyendo dispositivos externos. No usar en producción.

Configuración Antes vs. Después

Antes (openclaw.json):

{
  "acp": {
    "allowedAgents": ["my-agent"]
  }
}

Después (gateway.json):

{
  "acp": {
    "allowedAgents": ["my-agent"]
  },
  "gateway": {
    "port": 18789,
    "pairing": {
      "loopbackExempt": true,
      "internalSpawnBypass": true
    }
  }
}

Después de aplicar la corrección, verifica la resolución con los siguientes pasos:

Paso 1: Confirmar Configuración del Gateway

$ openclaw gateway config show

La salida esperada debe incluir:

{
  "pairing": {
    "loopbackExempt": true,
    "internalSpawnBypass": true
  }
}

Paso 2: Reiniciar Gateway y Verificar Registros

$ openclaw gateway restart
$ openclaw gateway logs --tail 20

Entradas de registro esperadas:

[gateway] INFO  [12:00:00.000] Gateway started on port 18789
[gateway] INFO  [12:00:00.001] Loopback pairing exemption: enabled
[gateway] INFO  [12:00:00.002] Internal spawn bypass: enabled

Paso 3: Probar Spawn de Sub-Agente

$ openclaw sessions_spawn --agent my-agent --runtime acp -- echo "test"

Salida esperada:

Spawning agent 'my-agent' with runtime 'acp'...
Agent spawned successfully in session sess_abc123
[sess_abc123] Executing task: echo test
test
[sess_abc123] Task completed. Exit code: 0

Paso 4: Verificar Aislamiento de Sesión

$ openclaw sessions list

La salida esperada debe mostrar la sesión principal y la sesión del sub-agente iniciado:

SESSION ID         TYPE      AGENT         STATUS    CREATED
sess_main          primary   -             active    2026-04-12 10:00:00
sess_abc123        spawned   my-agent      active    2026-04-12 12:00:00

Paso 5: Probar Orquestación Multi-Agente

$ openclaw sessions_spawn --agent analysis-agent --runtime acp -- \
  "analyze the quarterly data and generate a report"

Esperado: El agente se inicia sin error 1008 y comienza la ejecución de la tarea.

Códigos de Salida de Verificación

• 0: Corrección exitosa, sub-agente iniciado correctamente
• 1008: Corrección no aplicada, aplicación de emparejamiento aún activa
• 7: ID de agente no encontrado en acp.allowedAgents

Trampas Específicas del Entorno

• Redes de Contenedor Docker: Cuando se ejecuta OpenClaw en Docker, el tráfico loopback puede enrutarse de manera diferente. Usa el modo de red host o asegúrate de que network=host esté en docker-compose:

  services:
    openclaw:
      network_mode: host
  

• Windows WSL2: El comportamiento de loopback difiere entre el host Windows y WSL2. El gateway puede escuchar en diferentes interfaces. Verifica con:

  netstat -tlnp | grep openclaw
  

• Sandbox de macOS: El directorio de configuración puede diferir: ~/Library/Application Support/openclaw/

Errores de Configuración

• Ubicación Incorrecta del Archivo de Configuración: La configuración del gateway debe estar en gateway.json, no en openclaw.json. Este último maneja permisos de agentes; el primero maneja la seguridad del gateway.
• Problemas de Fusión de Configuración: Si usas variables de entorno junto con archivos de configuración, las variables de entorno tienen precedencia. Verifica con:

  openclaw gateway config show --merged
  

• Proceso Gateway Obsoleto: Los cambios en gateway.json requieren un reinicio completo, no solo una recarga. Verifica que el proceso realmente fue reiniciado:

  ps aux | grep openclaw-gateway
  

Errores de Autenticación

• Persistencia del Estado de Emparejamiento de Dispositivos: Los dispositivos aprobados se almacenan localmente. Limpiar datos de la aplicación puede invalidar dispositivos loopback aprobados:

  # Linux
  rm -rf ~/.local/share/openclaw/devices/*
  macOS
  rm -rf ~/Library/Application\ Support/openclaw/devices/*
  

• Expiración de Tokens: Los sub-agentes iniciados heredan tokens de autenticación con vidas útiles limitadas. Para tareas de larga duración, asegúrate de que la sesión principal permanezca activa.

Errores de Selección de Runtime

• Desajuste de Runtime: --runtime acp enrutza a través del gateway ACP (afectado por emparejamiento), mientras que --runtime local lo omite completamente. Usa local solo cuando la lógica del agente no requiere servicios de gateway.
• ID de Agente Inválido: El ID del agente en sessions_spawn debe coincidir exactamente con una entrada en acp.allowedAgents (distingue mayúsculas de minúsculas).

Regresiones Conocidas

• Este problema apareció por primera vez en v2026.4.12 y persiste a través de versiones de parches posteriores hasta que se aplica la configuración internalSpawnBypass.
• La versión v2026.4.11 y anteriores no se ven afectadas y pueden usarse como ruta de degradación si se requiere funcionalidad inmediata.

Directamente Relacionados

• WebSocket 1008: Policy Violation
  La aplicación de emparejamiento del gateway cerrando la conexión de spawn interna. Este es el error principal que bloquea el inicio de sub-agentes.
• Error #12210: "sessions_spawn fails with 'pairing required' on clean install"
  Reporte original de este patrón de regresión en la serie v2026.4.x.
• Error #21445: "ACP runtime sub-agents cannot connect to gateway"
  Rastrea el problema de denegación de escalada de alcance para spawns mediados por ACP.
• Error #30740: "Loopback connections incorrectly flagged as unpaired devices"
  Documenta la mala clasificación de conexiones internas como dispositivos externos.
• Error #59428: "Device pairing required despite OPENCLAW_SKIP_PAIRING=true"
  La sobrescritura de variable de entorno no funciona para sub-agentes iniciados.

Errores Secundariamente Relacionados

• Error #45102: "sessions_spawn returns exit code 7 for allowed agents"
  Desajuste de configuración causando rechazo de spawn antes de la verificación de emparejamiento.
• Error #33456: "Gateway closes connection with 1011 on long-running spawns"
  Error no relacionado ocurriendo después de un spawn exitoso, problema separado de timeout.
• Error #77890: "Sub-agent session orphaned after main session disconnect"
  Problema de gestión del ciclo de vida de sesiones en flujos de trabajo multi-agente.

Referencia de Códigos de Error