Gateway

• Per impostazione predefinita, il Gateway rifiuta di avviarsi a meno che gateway.mode=local sia impostato in ~/.openclaw/openclaw.json. Usa --allow-unconfigured per esecuzioni ad hoc/di sviluppo.
• openclaw onboard --mode local e openclaw setup devono scrivere gateway.mode=local. Se il file esiste ma gateway.mode manca, trattalo come una configurazione rotta o sovrascritta e riparala 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 (protezione di sicurezza).
• SIGUSR1 attiva un riavvio in-process quando autorizzato (commands.restart è abilitato per impostazione predefinita; imposta commands.restart: false per bloccare il riavvio manuale, mentre applicazione/aggiornamento di strumenti/configurazione del gateway restano consentiti).
• I gestori SIGINT/SIGTERM arrestano il processo gateway, ma non ripristinano alcuno stato personalizzato del terminale. Se avvolgi la CLI con una TUI o input in raw mode, ripristina il terminale prima dell'uscita.

• I record conservano metadati operativi: nomi evento, conteggi, dimensioni in byte, letture di memoria, stato di coda/sessione, nomi di canali/plugin e riepiloghi di sessione redatti. Non conservano testo di chat, corpi webhook, output di strumenti, corpi raw di richieste o risposte, token, cookie, valori segreti, nomi host o id raw di sessione. Imposta diagnostics.enabled: false per disabilitare completamente il registratore.
• In caso di uscite fatali del Gateway, timeout di spegnimento e fallimenti di avvio dopo riavvio, OpenClaw scrive lo stesso snapshot diagnostico in ~/.openclaw/logs/stability/openclaw-stability-*.json quando il registratore ha 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 della CLI locale manca o non e valida.
• gateway status predefinito verifica lo stato del servizio, la connessione WebSocket e la capacita di autenticazione visibile al momento dell'handshake. Non verifica le operazioni di lettura/scrittura/amministrazione.
• Le sonde diagnostiche non modificano l'autenticazione del dispositivo al primo utilizzo: riutilizzano un token dispositivo memorizzato nella cache quando esiste, ma non creano una nuova identita dispositivo della CLI ne 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 sonda quando possibile.
• Se un SecretRef di autenticazione richiesto non viene risolto in questo percorso di comando, gateway status --json riporta rpc.authWarning quando connettivita/autenticazione della sonda fallisce; passa esplicitamente --token/--password oppure risolvi prima l'origine del segreto.
• Se la sonda riesce, gli avvisi di riferimento di autenticazione non risolto vengono soppressi per evitare falsi positivi.
• Usa --require-rpc in script e automazione 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 aggiuntive launchd/systemd/schtasks. Quando vengono rilevati piu servizi simili al Gateway, l'output umano stampa suggerimenti di pulizia e avvisa che la maggior parte delle configurazioni dovrebbe eseguire un solo Gateway per macchina.
• --deep segnala anche un recente passaggio di consegne del riavvio del supervisore Gateway quando il processo del servizio e terminato correttamente per un riavvio del supervisore esterno.
• L'output umano include il percorso risolto del file di log piu l'istantanea dei percorsi/validita della configurazione CLI rispetto al servizio per aiutare a diagnosticare divergenze di profilo o directory di stato.

• Nelle installazioni Linux systemd, i controlli di deriva dell'autenticazione del servizio leggono sia i valori Environment= sia EnvironmentFile= dall'unita (inclusi %h, percorsi tra virgolette, file multipli e file opzionali -).
• I controlli di deriva risolvono i SecretRef gateway.auth.token usando l'ambiente di runtime unito (prima l'ambiente del comando del servizio, poi il fallback all'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 in cui 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 un target ha accettato una connessione WebSocket.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only riporta cio che la sonda ha potuto verificare sull'autenticazione. E separato dalla raggiungibilita.
• Read probe: ok significa che anche le chiamate RPC di dettaglio con ambito di lettura (health/status/system-presence/config.get) sono riuscite.
• 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, la sonda riutilizza l'autenticazione dispositivo memorizzata nella cache esistente ma non crea identita dispositivo o stato di associazione al primo utilizzo.
• Il codice di uscita e diverso da zero solo quando nessun target sondato e raggiungibile.

Livello superiore:

• ok: almeno un target e raggiungibile.
• degraded: almeno un target ha accettato una connessione ma non ha completato la diagnostica RPC dettagliata completa.
• capability: migliore capacita vista tra i target raggiungibili (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope o unknown).
• primaryTargetId: miglior target da trattare come vincitore attivo in questo ordine: URL esplicito, tunnel SSH, remoto configurato, quindi local loopback.
• warnings[]: record di avviso best-effort con code, message e targetIds opzionali.
• network: suggerimenti URL local loopback/tailnet derivati dalla configurazione corrente e dalla rete dell'host.
• discovery.timeoutMs e discovery.count: budget di scoperta effettivo/conteggio dei risultati usato per questo passaggio della sonda.

Per target (targets[].connect):

• ok: raggiungibilita dopo connessione + classificazione degradata.
• rpcOk: successo RPC dettagliato completo.
• scopeLimited: RPC dettagliato fallito a causa dell'assenza dell'ambito operatore.

Per target (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 quel target.

• ssh_tunnel_failed: configurazione del tunnel SSH fallita; il comando e tornato alle sonde dirette.
• multiple_gateways: piu di un target era raggiungibile; e insolito a meno che tu non esegua intenzionalmente profili isolati, come un bot di soccorso.
• auth_secretref_unresolved: un SecretRef di autenticazione configurato non ha potuto essere risolto per un target fallito.
• probe_scope_limited: connessione WebSocket riuscita, ma la sonda 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, --force, --wait <duration>, --json
• gateway uninstall|start|stop: --json

• Usa gateway restart per riavviare un servizio gestito. Non concatenare gateway stop e gateway start come sostituto del riavvio; su macOS, gateway stop disabilita intenzionalmente il LaunchAgent prima di arrestarlo.
• gateway restart --safe chiede al Gateway in esecuzione di eseguire il preflight del lavoro OpenClaw attivo e rimandare il riavvio fino allo svuotamento della consegna delle risposte, delle esecuzioni incorporate e delle esecuzioni dei task. --safe non puo essere combinato con --force o --wait.
• gateway restart --wait 30s sostituisce il budget configurato di svuotamento del riavvio per quel riavvio. I numeri senza unita sono millisecondi; sono accettate unita come s, m e h. --wait 0 attende indefinitamente.
• gateway restart --force salta lo svuotamento del lavoro attivo e riavvia immediatamente. Usalo quando un operatore ha gia ispezionato i blocchi di task elencati e vuole ripristinare subito il gateway.
• I comandi di ciclo di vita accettano --json per gli script.

• Quando l'autenticazione tramite token richiede un token e gateway.auth.token è gestito da SecretRef, gateway install convalida che il SecretRef sia risolvibile, ma non rende persistente 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 si blocca in modo sicuro invece di rendere persistente testo semplice di fallback.
• Per l'autenticazione tramite password su gateway run, preferisci OPENCLAW_GATEWAY_PASSWORD, --password-file o gateway.auth.password supportato da SecretRef rispetto a --password inline.
• Nella modalità di autenticazione dedotta, OPENCLAW_GATEWAY_PASSWORD solo shell non allenta i requisiti del token di installazione; usa una configurazione durevole (gateway.auth.password o env della configurazione) quando installi un servizio gestito.
• Se sono configurati sia gateway.auth.token sia gateway.auth.password e gateway.auth.mode non è impostato, l'installazione viene bloccata finché la modalità non viene impostata esplicitamente.