Gateway

Bloqueo del Gateway

Por qué

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

El Gateway primero adquiere un archivo de bloqueo por configuración en el directorio de bloqueos de estado y sondea el puerto configurado para detectar un listener existente.
Si el propietario de bloqueo registrado ya no existe, el puerto está libre o el bloqueo está obsoleto, el inicio recupera el bloqueo y continúa.
Luego el Gateway enlaza el listener HTTP/WebSocket (predeterminado ws://127.0.0.1:18789) 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>").
Al apagarse, el Gateway cierra el servidor HTTP/WebSocket y elimina el archivo de bloqueo.

Si otro proceso ocupa el puerto, el inicio lanza GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>").
Otros fallos de enlace se muestran 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>.
Bajo un supervisor de servicios, un nuevo proceso de Gateway que ve un respondedor /healthz existente y en buen estado deja ese proceso en control. En systemd, el iniciador duplicado sale con el código 78, por lo que el RestartPreventExitStatus=78 predeterminado evita que Restart=always entre en bucle por un conflicto de bloqueo o EADDRINUSE. Si el proceso existente nunca llega a estar en buen estado, los reintentos quedan acotados y el inicio falla con un error de bloqueo claro en lugar de entrar en bucle indefinidamente.
La app de macOS todavía mantiene su propia protección ligera de PID antes de generar el Gateway; el bloqueo en tiempo de ejecución lo aplican el archivo de bloqueo más el enlace HTTP/WebSocket.