Gateway

• Per impostazione predefinita, il Gateway rifiuta di avviarsi a meno che gateway.mode=local non sia impostato in ~/.openclaw/openclaw.json. Usa --allow-unconfigured per esecuzioni ad hoc/dev.
• openclaw onboard --mode local e openclaw setup dovrebbero scrivere gateway.mode=local. Se il file esiste ma gateway.mode manca, consideralo una configurazione rotta o sovrascritta e riparalo invece di presumere implicitamente la modalità locale.
• Se il file esiste e gateway.mode manca, il Gateway lo considera un danno sospetto alla configurazione e rifiuta di "indovinare local" per te.
• Il binding oltre il loopback senza autenticazione è bloccato (misura di sicurezza).
• lan, tailnet e custom attualmente si risolvono tramite percorsi BYOH solo IPv4.
• BYOH solo IPv6 non è supportato nativamente su questo percorso oggi. Usa un sidecar IPv4 o un proxy se l'host stesso è solo IPv6.
• SIGUSR1 attiva un riavvio in-process quando autorizzato (commands.restart è abilitato per impostazione predefinita; imposta commands.restart: false per bloccare il riavvio manuale, mentre l'applicazione/aggiornamento di strumenti/configurazione del gateway rimane consentito).
• Gli handler SIGINT/SIGTERM arrestano il processo gateway, ma non ripristinano eventuali stati personalizzati del terminale. Se avvolgi la CLI con una TUI o input in modalità raw, ripristina il terminale prima di uscire.

• I record conservano metadati operativi: nomi degli eventi, conteggi, dimensioni in byte, letture di memoria, stato di code/sessioni, id di approvazione, nomi di canali/Plugin e riepiloghi di sessione redatti. Non conservano testo delle chat, body dei Webhook, output degli strumenti, body raw di richieste o risposte, token, cookie, valori segreti, hostname o id raw di sessione. Imposta diagnostics.enabled: false per disabilitare completamente il recorder.
• Su uscite fatali del Gateway, timeout di shutdown e fallimenti di avvio del riavvio, OpenClaw scrive lo stesso snapshot diagnostico in ~/.openclaw/logs/stability/openclaw-stability-*.json quando il recorder contiene eventi. Ispeziona il bundle più recente con openclaw gateway stability --bundle latest; --limit, --type e --since-seq si applicano anche all'output del bundle.

• gateway status resta disponibile per la diagnostica anche quando la configurazione CLI locale e' mancante o non valida.
• gateway status predefinito prova lo stato del servizio, la connessione WebSocket e la capacita' di autenticazione visibile al momento dell'handshake. Non prova operazioni di lettura/scrittura/amministrazione.
• Le verifiche diagnostiche non modificano nulla per l'autenticazione iniziale del dispositivo: riutilizzano un token dispositivo esistente nella cache quando esiste, ma non creano una nuova identita' dispositivo CLI o un record di associazione dispositivo in sola lettura solo per controllare lo stato.
• gateway status risolve i SecretRef di autenticazione configurati per l'autenticazione della verifica quando possibile.
• Se in questo percorso di comando un SecretRef di autenticazione richiesto non viene risolto, gateway status --json riporta rpc.authWarning quando la connettivita'/autenticazione della verifica non riesce; passa --token/--password esplicitamente o risolvi prima l'origine del segreto.
• Se la verifica riesce, gli avvisi auth-ref non risolti vengono soppressi per evitare falsi positivi.
• Quando la verifica e' abilitata, l'output JSON include gateway.version quando il Gateway in esecuzione lo riporta; --require-rpc puo' usare come fallback il payload RPC status.runtimeVersion se la verifica handshake successiva non puo' fornire metadati di versione.
• Usa --require-rpc negli script e nelle automazioni quando un servizio in ascolto non basta e ti serve che anche le chiamate RPC con ambito di lettura siano integre.
• --deep aggiunge una scansione best-effort per installazioni launchd/systemd/schtasks aggiuntive. Quando vengono rilevati piu' servizi simili a gateway, l'output per utenti stampa suggerimenti di pulizia e avvisa che la maggior parte delle configurazioni dovrebbe eseguire un gateway per macchina.
• --deep riporta anche un recente passaggio di riavvio del supervisore Gateway quando il processo del servizio e' uscito correttamente per un riavvio di supervisore esterno.
• --deep esegue la convalida della configurazione in modalita' consapevole dei plugin (pluginValidation: "full") e mostra avvisi del manifesto dei plugin configurati (per esempio metadati di configurazione canale mancanti) in modo che i controlli smoke di installazione e aggiornamento li intercettino. gateway status predefinito mantiene il percorso veloce in sola lettura che salta la convalida dei plugin.
• L'output per utenti include il percorso del file di log risolto piu' lo snapshot dei percorsi/validita' della configurazione CLI-vs-servizio per aiutare a diagnosticare derive di profilo o directory di stato.

• Nelle installazioni systemd su Linux, i controlli di deriva dell'autenticazione del servizio leggono sia i valori Environment= sia EnvironmentFile= dall'unita' (inclusi %h, percorsi tra virgolette, piu' file e file facoltativi con -).
• I controlli di deriva risolvono i SecretRef gateway.auth.token usando l'ambiente runtime unito (prima l'ambiente del comando del servizio, poi il fallback sull'ambiente del processo).
• Se l'autenticazione tramite token non e' effettivamente attiva (gateway.auth.mode esplicito di password/none/trusted-proxy, oppure modalita' non impostata dove la password puo' prevalere e nessun candidato token puo' prevalere), i controlli di deriva del token saltano la risoluzione del token di configurazione.

• Reachable: yes significa che almeno una destinazione ha accettato una connessione WebSocket.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only riporta cio' che la verifica ha potuto provare sull'autenticazione. E' separata dalla raggiungibilita'.
• Read probe: ok significa che sono riuscite anche le chiamate RPC di dettaglio con ambito di lettura (health/status/system-presence/config.get).
• Read probe: limited - missing scope: operator.read significa che la connessione e' riuscita ma l'RPC con ambito di lettura e' limitato. Questo viene riportato come raggiungibilita' degradata, non come errore completo.
• Read probe: failed dopo Connect: ok significa che il Gateway ha accettato la connessione WebSocket, ma la diagnostica di lettura successiva e' scaduta o non e' riuscita. Anche questa e' raggiungibilita' degradata, non un Gateway irraggiungibile.
• Come gateway status, probe riutilizza l'autenticazione dispositivo esistente nella cache ma non crea identita' dispositivo iniziale o stato di associazione.
• Il codice di uscita e' diverso da zero solo quando nessuna destinazione verificata e' raggiungibile.

Livello superiore:

• ok: almeno una destinazione e' raggiungibile.
• degraded: almeno una destinazione ha accettato una connessione ma non ha completato l'intera diagnostica RPC di dettaglio.
• capability: migliore capacita' vista tra le destinazioni raggiungibili (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope o unknown).
• primaryTargetId: migliore destinazione da trattare come vincitrice attiva in questo ordine: URL esplicito, tunnel SSH, remoto configurato, poi local loopback.
• warnings[]: record di avviso best-effort con code, message e targetIds facoltativi.
• network: suggerimenti URL local loopback/tailnet derivati dalla configurazione corrente e dalla rete host.
• discovery.timeoutMs e discovery.count: budget di discovery effettivo/conteggio risultati usato per questo passaggio di verifica.

Per destinazione (targets[].connect):

• ok: raggiungibilita' dopo connessione + classificazione degradata.
• rpcOk: successo completo dell'RPC di dettaglio.
• scopeLimited: RPC di dettaglio non riuscito a causa dell'ambito operatore mancante.

Per destinazione (targets[].auth):

• role: ruolo di autenticazione riportato in hello-ok quando disponibile.
• scopes: ambiti concessi riportati in hello-ok quando disponibili.
• capability: classificazione della capacita' di autenticazione esposta per quella destinazione.

• ssh_tunnel_failed: configurazione del tunnel SSH non riuscita; il comando e' tornato alle verifiche dirette.
• multiple_gateways: erano raggiungibili identita' gateway distinte, oppure OpenClaw non ha potuto provare che le destinazioni raggiungibili siano lo stesso gateway. Un tunnel SSH, URL proxy o URL remoto configurato verso lo stesso gateway non attiva questo avviso.
• auth_secretref_unresolved: un SecretRef di autenticazione configurato non ha potuto essere risolto per una destinazione non riuscita.
• probe_scope_limited: la connessione WebSocket e' riuscita, ma la verifica di lettura e' stata limitata dall'assenza di operator.read.

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node|bun>, --token, --wrapper <path>, --force, --json
• gateway restart: --safe, --skip-deferral, --force, --wait <duration>, --json
• gateway uninstall|start: --json
• gateway stop: --disable, --json

• Usa gateway restart per riavviare un servizio gestito. Non concatenare gateway stop e gateway start come sostituto del riavvio.
• Su macOS, gateway stop usa launchctl bootout per impostazione predefinita, che rimuove il LaunchAgent dalla sessione di avvio corrente senza mantenere una disabilitazione: il ripristino automatico KeepAlive resta attivo per crash futuri e gateway start riabilita tutto in modo pulito senza un launchctl enable manuale. Passa --disable per sopprimere in modo persistente KeepAlive e RunAtLoad, così il Gateway non si riavvia fino al successivo gateway start esplicito; usalo quando un arresto manuale deve sopravvivere a riavvii o riavvii di sistema.
• gateway restart --safe chiede al Gateway in esecuzione di verificare preventivamente il lavoro attivo e pianificare un unico riavvio coalescente dopo lo svuotamento del lavoro attivo. Il riavvio sicuro predefinito attende il lavoro attivo fino al valore configurato di gateway.reload.deferralTimeoutMs (predefinito 5 minuti); allo scadere di quel budget il riavvio viene forzato. Imposta gateway.reload.deferralTimeoutMs su 0 per un'attesa sicura indefinita che non forza mai. --safe non può essere combinato con --force o --wait.
• gateway restart --wait 30s sovrascrive il budget di svuotamento configurato per quel riavvio. I numeri senza unità sono millisecondi; sono accettate unità come s, m e h. --wait 0 attende indefinitamente.
• gateway restart --safe --skip-deferral esegue il riavvio sicuro consapevole di OpenClaw ma aggira il gate di differimento, così il Gateway emette immediatamente il riavvio anche quando vengono segnalati blocchi. È una via di fuga per l'operatore in caso di differimenti bloccati da task-run; richiede --safe.
• gateway restart --force salta lo svuotamento del lavoro attivo e riavvia immediatamente. Usalo quando un operatore ha già ispezionato i blocchi dei task elencati e vuole ripristinare subito il Gateway.
• I comandi del ciclo di vita accettano --json per lo scripting.

• Quando l'autenticazione tramite token richiede un token e gateway.auth.token è gestito da SecretRef, gateway install verifica che il SecretRef sia risolvibile ma non mantiene il token risolto nei metadati dell'ambiente del servizio.
• Se l'autenticazione tramite token richiede un token e il SecretRef del token configurato non è risolto, l'installazione fallisce in modo chiuso invece di mantenere testo normale di fallback.
• Per l'autenticazione tramite password su gateway run, preferisci OPENCLAW_GATEWAY_PASSWORD, --password-file o un gateway.auth.password basato su SecretRef rispetto a --password inline.
• In modalità auth inferita, OPENCLAW_GATEWAY_PASSWORD solo shell non allenta i requisiti del token di installazione; usa una configurazione durevole (gateway.auth.password o env di configurazione) quando installi un servizio gestito.
• Se sia gateway.auth.token sia gateway.auth.password sono configurati e gateway.auth.mode non è impostato, l'installazione viene bloccata finché la modalità non viene impostata esplicitamente.