Bloqueo del Gateway

Última actualización: 2025-12-11

Por qué

Asegurar que solo una instancia del gateway se ejecute por puerto base en el mismo host; los gateways adicionales deben usar perfiles aislados y puertos únicos.
Sobrevivir a crashes/SIGKILL sin dejar archivos de bloqueo obsoletos.
Fallar rápidamente con un error claro cuando el puerto de control ya está ocupado.

El gateway enlaza el listener WebSocket (por defecto ws://127.0.0.1:18789) inmediatamente al inicio usando un listener TCP exclusivo.
Si el enlace falla con EADDRINUSE, el inicio lanza GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>").
El sistema operativo libera el listener automáticamente al salir del proceso, incluyendo crashes y SIGKILL — no se necesita archivo de bloqueo separado ni paso de limpieza.
Al apagarse, el gateway cierra el servidor WebSocket y el servidor HTTP subyacente para liberar el puerto con prontitud.

Si otro proceso retiene el puerto, el inicio lanza GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>").
Otros fallos de enlace aparecen como GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …").

Si el puerto está ocupado por otro proceso, el error es el mismo; libera el puerto o elige otro con openclaw gateway --port <port>.
La app macOS aún mantiene su propia protección ligera de PID antes de generar el gateway; el bloqueo en runtime es aplicado por el enlace WebSocket.