Gateway

Blocco del Gateway

Perché

Un solo processo Gateway dovrebbe essere proprietario di una determinata configurazione e porta su un host; per eseguire Gateway aggiuntivi, usa profili isolati e porte univoche.
Sopravvivere ad arresti anomali/SIGKILL senza lasciare file di blocco obsoleti.
Interrompere immediatamente l'avvio con un errore chiaro quando un altro Gateway è già proprietario della porta.

L'avvio impone la proprietà a istanza singola in due passaggi indipendenti, nell'ordine seguente:

Il blocco del file acquisisce un file di blocco specifico per la configurazione nella directory dei blocchi dello stato. Durante l'acquisizione, l'avvio verifica se sulla porta configurata è presente un listener attivo, per rilevare un proprietario del blocco obsoleto (arrestato in modo anomalo).
Il binding del socket associa il listener HTTP/WebSocket (valore predefinito ws://127.0.0.1:18789) come listener TCP esclusivo.

Ogni livello può non riuscire indipendentemente e genera il proprio GatewayLockError.

Se il file di blocco non è presente, il processo proprietario registrato non è più in esecuzione oppure la verifica della porta del proprietario non rileva alcun listener attivo, l'avvio recupera il blocco e prosegue.
Se il blocco è attivamente detenuto e non si applica nessuna delle condizioni precedenti, l'avvio riprova per un massimo di 5 secondi (valore predefinito) prima di rinunciare:
text
```
GatewayLockError("gateway already running (pid <pid>); lock timeout after <ms>ms")
```

In caso di EADDRINUSE, l'avvio riprova il binding per un massimo di 20 tentativi a intervalli di 500 ms (circa 10 secondi in totale), per superare una finestra TIME_WAIT successiva alla recente terminazione di un processo.

Se la porta è ancora in uso dopo i tentativi:

text

GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")

Altri errori di binding:

text

GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: <cause>")

All'arresto, il Gateway chiude il server HTTP/WebSocket e rimuove il file di blocco.

Se la porta è occupata da un processo diverso, che non è un Gateway, l'errore è lo stesso; libera la porta oppure scegline un'altra con openclaw gateway --port <port>.
Con un supervisore di servizi, un nuovo processo Gateway che riscontra uno degli errori precedenti verifica prima /healthz sul processo esistente. Se tale processo è integro, il nuovo processo gli lascia il controllo anziché terminare con un errore. Su systemd, termina con il codice 78; l'impostazione RestartPreventExitStatus=78 dell'unità impedisce a Restart=always di entrare in un ciclo a causa di un conflitto di blocco o EADDRINUSE. Se il processo esistente non diventa mai integro, i nuovi tentativi di verifica dello stato sono limitati nel tempo e l'avvio termina quindi con l'errore di blocco riportato sopra, anziché continuare all'infinito.
L'app macOS mantiene una propria protezione PID leggera prima di avviare il Gateway; il blocco del file e il binding del socket descritti sopra costituiscono l'effettivo meccanismo di imposizione in fase di esecuzione.

Was this useful?