Gateway

Bloqueo del Gateway

Por qué

Solo un proceso de Gateway debe ser propietario de un directorio de estado; ejecute Gateways adicionales con perfiles, directorios de estado, configuraciones y puertos aislados.
Permite sobrevivir a fallos o SIGKILL sin dejar archivos de bloqueo obsoletos.
Falla de inmediato con un error claro cuando otro Gateway ya es propietario del puerto.

El inicio aplica la propiedad en tres pasos, en este orden:

El bloqueo de propiedad del estado adquiere un bloqueo asociado al directorio de estado canónico. Todos los Gateway participan, incluidos los Gateway iniciados con OPENCLAW_ALLOW_MULTI_GATEWAY=1, para que el mantenimiento destructivo de SQLite no entre en conflicto con un propietario activo.
El bloqueo de configuración adquiere el bloqueo histórico por configuración y registra el puerto de ejecución. El modo multi-Gateway omite esta instancia única de configuración, pero conserva el bloqueo de propiedad del estado.
El enlace del socket enlaza el servidor HTTP/WebSocket (valor predeterminado: ws://127.0.0.1:18789) como servidor TCP exclusivo.

Cada capa puede fallar de forma independiente y genera su propio GatewayLockError.

La vigencia del bloqueo se determina mediante el PID registrado, la identidad de inicio del proceso de la plataforma cuando está disponible y la identidad del proceso de Gateway. Un propietario verificado conserva la autoridad durante el inicio antes de que su puerto comience a escuchar.
Un coordinador de SQLite dedicado serializa la inspección de metadatos, la recuperación de propietarios obsoletos y la sustitución de bloqueos. Su transacción exclusiva se libera automáticamente si el proceso propietario falla.
Si falta un archivo de bloqueo o el proceso propietario registrado ya no existe, el inicio recupera el bloqueo y continúa.
Si cualquiera de los bloqueos está activo, el inicio vuelve a intentarlo durante un máximo de 5 segundos (de forma predeterminada) antes de desistir:
text
```
GatewayLockError("el gateway ya se está ejecutando (pid <pid>); tiempo de espera del bloqueo agotado tras <ms>ms")
```

En EADDRINUSE, el inicio vuelve a intentar el enlace hasta 20 veces, en intervalos de 500ms (aproximadamente 10 segundos en total), para superar un intervalo de TIME_WAIT tras la finalización reciente de un proceso.

Si el puerto sigue en uso después de los reintentos:

text

GatewayLockError("otra instancia del gateway ya está escuchando en ws://127.0.0.1:<port>")

Otros fallos de enlace:

text

GatewayLockError("no se pudo enlazar el socket del gateway en ws://127.0.0.1:<port>: <cause>")

Al apagarse, el Gateway cierra el servidor HTTP/WebSocket y elimina sus archivos de bloqueo de estado y configuración.

Si el puerto está ocupado por otro proceso que no es un Gateway, el error es el mismo; libere el puerto o elija otro mediante openclaw gateway --port <port>.
OPENCLAW_ALLOW_MULTI_GATEWAY=1 permite varias instancias de configuración y ejecución, no un estado mutable compartido. Cada instancia sigue necesitando un OPENCLAW_STATE_DIR único.
Con un supervisor de servicios, un nuevo proceso de Gateway que detecta cualquiera de los errores anteriores primero comprueba /healthz en el proceso existente. Si ese proceso está en buen estado, el nuevo proceso permite que conserve el control en lugar de fallar. En systemd, termina con el código 78; el RestartPreventExitStatus=78 de la unidad evita que Restart=always se repita indefinidamente por un conflicto de bloqueo o de EADDRINUSE. Si el proceso existente nunca alcanza un estado correcto, los reintentos de comprobación de estado tienen un límite de tiempo y, a continuación, el inicio falla con el error de bloqueo anterior en lugar de repetirse indefinidamente.
La aplicación para macOS mantiene su propia protección ligera mediante PID antes de iniciar el Gateway; el archivo de bloqueo y el enlace del socket anteriores son los mecanismos reales de aplicación durante la ejecución.

Was this useful?