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 dovrebbero scrivere gateway.mode=local. Se il file esiste ma gateway.mode manca, considerala una configurazione danneggiata o sovrascritta e riparala invece di presupporre implicitamente la modalità locale.
• Se il file esiste e gateway.mode manca, il Gateway tratta la situazione come un danno sospetto alla configurazione e rifiuta di "indovinare local" per te.
• Il binding oltre il loopback senza autenticazione è bloccato (misura di sicurezza).
• SIGUSR1 attiva un riavvio nel processo quando autorizzato (commands.restart è abilitato per impostazione predefinita; imposta commands.restart: false per bloccare il riavvio manuale, mentre l'applicazione/aggiornamento tramite strumento/config del gateway rimane consentita).
• I gestori SIGINT/SIGTERM arrestano il processo gateway, ma non ripristinano alcuno stato personalizzato del terminale. Se incapsuli la CLI con una TUI o input in raw mode, ripristina il terminale prima dell'uscita.

• I record mantengono metadati operativi: nomi degli eventi, conteggi, dimensioni in byte, letture della memoria, stato di code/sessioni, nomi di canali/plugin e riepiloghi delle sessioni redatti. Non mantengono testo delle chat, corpi webhook, output degli strumenti, corpi raw di richiesta o risposta, token, cookie, valori segreti, nomi host o ID sessione raw. Imposta diagnostics.enabled: false per disabilitare completamente il recorder.
• In caso di uscite fatali del Gateway, timeout di spegnimento e fallimenti di avvio del riavvio, OpenClaw scrive lo stesso snapshot diagnostico in ~/.openclaw/logs/stability/openclaw-stability-*.json quando il recorder 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 è mancante o non valida.
• gateway status predefinito verifica lo stato del servizio, la connessione WebSocket e la capacità di autenticazione visibile al momento dell'handshake. Non verifica operazioni di lettura/scrittura/amministrazione.
• I probe diagnostici non apportano modifiche per l'autenticazione iniziale del dispositivo: riutilizzano un token dispositivo esistente nella cache quando presente, ma non creano una nuova identità dispositivo CLI o un record di abbinamento dispositivo in sola lettura solo per controllare lo stato.
• gateway status risolve i SecretRef di autenticazione configurati per l'autenticazione del probe quando possibile.
• Se un SecretRef di autenticazione richiesto non viene risolto in questo percorso di comando, gateway status --json segnala rpc.authWarning quando la connettività/autenticazione del probe fallisce; passa --token/--password esplicitamente o risolvi prima la sorgente del segreto.
• Se il probe riesce, gli avvisi sugli auth-ref non risolti vengono soppressi per evitare falsi positivi.
• Usa --require-rpc negli script e nell'automazione quando un servizio in ascolto non basta e hai bisogno che anche le chiamate RPC con ambito di lettura siano integre.
• --deep aggiunge un'analisi best-effort per installazioni aggiuntive launchd/systemd/schtasks. Quando vengono rilevati più servizi simili a 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 riavvio del supervisore Gateway quando il processo del servizio è uscito correttamente per un riavvio da parte di un supervisore esterno.
• --deep esegue la convalida della configurazione in modalità consapevole dei Plugin (pluginValidation: "full") ed espone gli avvisi dei manifest Plugin configurati (per esempio metadati di configurazione del canale mancanti), così i controlli smoke di installazione e aggiornamento li intercettano. gateway status predefinito mantiene il percorso rapido in sola lettura che salta la convalida dei Plugin.
• L'output umano include il percorso del log su file risolto più l'istantanea dei percorsi/validità della configurazione CLI-vs-servizio per aiutare a diagnosticare la deriva di profilo o state-dir.

• Nelle installazioni systemd Linux, i controlli di deriva dell'autenticazione del servizio leggono sia i valori Environment= sia EnvironmentFile= dall'unità (inclusi %h, percorsi quotati, più file e file opzionali -).
• I controlli di deriva risolvono i SecretRef gateway.auth.token usando l'env di runtime unito (prima l'env del comando del servizio, poi il fallback dell'env di processo).
• Se l'autenticazione tramite token non è effettivamente attiva (gateway.auth.mode esplicito pari a password/none/trusted-proxy, oppure modalità non impostata dove la password può prevalere e nessun candidato token può 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 segnala ciò che il probe ha potuto verificare sull'autenticazione. È separato dalla raggiungibilità.
• 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 è riuscita, ma l'RPC con ambito di lettura è limitato. Questo viene segnalato come raggiungibilità degradata, non come fallimento completo.
• Read probe: failed dopo Connect: ok significa che il Gateway ha accettato la connessione WebSocket, ma la diagnostica di lettura successiva è andata in timeout o è fallita. Anche questa è raggiungibilità degradata, non un Gateway non raggiungibile.
• Come gateway status, il probe riutilizza l'autenticazione dispositivo esistente nella cache ma non crea un'identità dispositivo iniziale o uno stato di abbinamento.
• Il codice di uscita è diverso da zero solo quando nessuna destinazione sottoposta a probe è raggiungibile.

Livello superiore:

• ok: almeno una destinazione è raggiungibile.
• degraded: almeno una destinazione ha accettato una connessione ma non ha completato la diagnostica RPC di dettaglio completa.
• capability: migliore capacità 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 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 di URL local loopback/tailnet derivati dalla configurazione corrente e dalla rete dell'host.
• discovery.timeoutMs e discovery.count: il budget/numero di risultati di discovery effettivamente usato per questo passaggio di probe.

Per destinazione (targets[].connect):

• ok: raggiungibilità dopo connessione + classificazione degradata.
• rpcOk: successo RPC di dettaglio completo.
• scopeLimited: RPC di dettaglio fallito a causa dell'ambito operatore mancante.

Per destinazione (targets[].auth):

• role: ruolo di autenticazione segnalato in hello-ok quando disponibile.
• scopes: ambiti concessi segnalati in hello-ok quando disponibili.
• capability: classificazione della capacità di autenticazione esposta per quella destinazione.

• ssh_tunnel_failed: configurazione del tunnel SSH fallita; il comando è tornato ai probe diretti.
• multiple_gateways: più di una destinazione era raggiungibile; è insolito a meno che tu non stia eseguendo intenzionalmente profili isolati, come un bot di soccorso.
• auth_secretref_unresolved: un SecretRef di autenticazione configurato non poteva essere risolto per una destinazione fallita.
• probe_scope_limited: connessione WebSocket riuscita, ma il probe di lettura era limitato dalla mancanza 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 rendere persistente una disabilitazione — il ripristino automatico KeepAlive rimane attivo per arresti anomali futuri e gateway start lo riabilita in modo pulito senza un launchctl enable manuale. Passa --disable per sopprimere in modo persistente KeepAlive e RunAtLoad affinché il Gateway non si riavvii fino al successivo gateway start esplicito; usalo quando un arresto manuale deve sopravvivere a riavvii o riavvii del sistema.
• gateway restart --safe chiede al Gateway in esecuzione di eseguire un controllo preliminare del lavoro OpenClaw attivo e di rinviare il riavvio finché la consegna delle risposte, le esecuzioni incorporate e le esecuzioni delle attività non si svuotano. --safe non può essere combinato con --force o --wait.
• gateway restart --wait 30s sovrascrive il budget di svuotamento del riavvio 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 rinvio, quindi il Gateway emette immediatamente il riavvio anche quando vengono segnalati blocchi. Via d'uscita per l'operatore per rinvii di esecuzioni di attività bloccate; richiede --safe.
• gateway restart --force salta lo svuotamento del lavoro attivo e riavvia immediatamente. Usalo quando un operatore ha già ispezionato i blocchi di attività 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 persiste 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 persistere testo normale di fallback.
• Per l'autenticazione tramite password su gateway run, preferisci OPENCLAW_GATEWAY_PASSWORD, --password-file o un gateway.auth.password supportato da SecretRef rispetto a --password inline.
• In modalità di autenticazione 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 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.