Evita conflictos en OpenClaw: Gestión de puertos y bloqueo

¿Alguna vez has tenido problemas porque dos instancias de un servicio intentan usar el mismo puerto al mismo tiempo? Es un dolor de cabeza común, especialmente cuando quedan archivos de bloqueo antiguos tras un cierre inesperado que te impiden reiniciar el sistema de forma limpia.

Bloqueo del Gateway

¿Por qué?

• Asegurar que solo corra una instancia del Gateway por puerto base en el mismo host; los Gateways adicionales deben usar perfiles aislados y puertos únicos. Además, esto permite fallar rápido con un error claro cuando el puerto de control ya está ocupado.
• Sobrevivir a cierres inesperados o SIGKILL sin dejar archivos de bloqueo obsoletos que requieran limpieza manual.

Mecanismo

• El Gateway vincula el listener de WebSocket (por defecto ws://127.0.0.1:18789) inmediatamente al iniciar usando un listener TCP exclusivo.
• Si la vinculación 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 cualquier proceso, incluyendo crashes y SIGKILL. No hace falta un archivo de bloqueo separado ni pasos de limpieza.
• Al apagarse, el Gateway cierra el servidor WebSocket y el servidor HTTP subyacente para liberar el puerto rápidamente.

Superficie de errores

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

Notas operativas

• 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 de macOS sigue manteniendo su propio guardián de PID ligero antes de lanzar el Gateway; el bloqueo en tiempo de ejecución lo aplica la vinculación del WebSocket.

Relacionado

• Multiple Gateways — ejecutar múltiples instancias con puertos únicos
• Troubleshooting — diagnosticar EADDRINUSE y conflictos de puertos

Pasos siguientes

• Revisa cómo configurar Multiple Gateways si necesitas más de una instancia.
• Si encuentras errores de puerto, consulta la guía de Troubleshooting.

AI Setup Assistant