Vai al contenuto principale
Il Gateway è il server WebSocket di OpenClaw (canali, nodi, sessioni, hook). I sottocomandi in questa pagina si trovano sotto openclaw gateway ….

Rilevamento Bonjour

Configurazione mDNS locale + DNS-SD wide-area.

Panoramica del rilevamento

Come OpenClaw pubblicizza e trova i gateway.

Configurazione

Chiavi di configurazione del gateway di primo livello.

​
Eseguire il Gateway

Esegui un processo Gateway locale: 
openclaw gateway
Alias in primo piano: 
openclaw gateway run
  • 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.

​
Opzioni

​
--port <port>
number
Porta WebSocket (il valore predefinito proviene da config/env; di solito 18789).
​
--bind <loopback|lan|tailnet|auto|custom>
string
Modalità di bind del listener. lan, tailnet e custom attualmente si risolvono tramite percorsi solo IPv4.
​
--auth <token|password>
string
Override della modalità di autenticazione.
​
--token <token>
string
Override del token (imposta anche OPENCLAW_GATEWAY_TOKEN per il processo).
​
--password <password>
string
Override della password.
​
--password-file <path>
string
Leggi la password del gateway da un file.
​
--tailscale <off|serve|funnel>
string
Espone il Gateway tramite Tailscale.
​
--tailscale-reset-on-exit
boolean
Reimposta la configurazione serve/funnel di Tailscale allo spegnimento.
​
--bind custom + gateway.customBindHost
string
Oggi si aspetta un indirizzo IPv4. Per BYOH solo IPv6, metti un sidecar IPv4 o un proxy davanti al Gateway e punta OpenClaw a quell’endpoint IPv4.
​
--allow-unconfigured
boolean
Consenti l’avvio del gateway senza gateway.mode=local nella configurazione. Bypassa la protezione di avvio solo per bootstrap ad hoc/dev; non scrive né ripara il file di configurazione.
​
--dev
boolean
Crea una configurazione dev + workspace se mancano (salta BOOTSTRAP.md).
​
--reset
boolean
Reimposta configurazione dev + credenziali + sessioni + workspace (richiede --dev).
​
--force
boolean
Termina qualsiasi listener esistente sulla porta selezionata prima dell’avvio.
​
--verbose
boolean
Log dettagliati.
​
--cli-backend-logs
boolean
Mostra solo i log del backend CLI nella console (e abilita stdout/stderr).
​
--ws-log <auto|full|compact>
string
predefinito:"auto"
Stile dei log WebSocket.
​
--compact
boolean
Alias per --ws-log compact.
​
--raw-stream
boolean
Registra gli eventi raw dello stream del modello in jsonl.
​
--raw-stream-path <path>
string
Percorso jsonl dello stream raw.

​
Riavviare il Gateway

openclaw gateway restart
openclaw gateway restart --safe
openclaw gateway restart --safe --skip-deferral
openclaw gateway restart --force
openclaw gateway restart --safe chiede al Gateway in esecuzione di fare un preflight del lavoro attivo e pianificare un singolo riavvio coalescente dopo lo svuotamento del lavoro attivo. Il riavvio sicuro predefinito attende il lavoro attivo fino al gateway.reload.deferralTimeoutMs configurato (predefinito 5 minuti); quando quel budget scade, il riavvio viene forzato. Imposta gateway.reload.deferralTimeoutMs a 0 per un’attesa sicura indefinita che non forza mai. Il semplice restart mantiene il comportamento esistente del service manager; --force rimane il percorso di override immediato. openclaw gateway restart --safe --skip-deferral esegue lo stesso riavvio coordinato consapevole di OpenClaw di --safe, ma bypassa il gate di rinvio del lavoro attivo, quindi il Gateway emette il riavvio immediatamente anche quando vengono segnalati blocchi. Usalo come via di uscita per l’operatore quando un rinvio è stato bloccato da un’esecuzione di task incagliata e --safe da solo può essere limitato da gateway.reload.deferralTimeoutMs. --skip-deferral richiede --safe.
--password inline può essere esposta negli elenchi dei processi locali. Preferisci --password-file, env o una gateway.auth.password basata su SecretRef.

​
Profilazione del Gateway

  • Imposta OPENCLAW_GATEWAY_STARTUP_TRACE=1 per registrare i tempi delle fasi durante l’avvio del Gateway, incluso il ritardo eventLoopMax per fase e i tempi delle tabelle di lookup dei Plugin per indice installato, registro manifest, pianificazione di avvio e lavoro owner-map.
  • Imposta OPENCLAW_GATEWAY_RESTART_TRACE=1 per registrare righe restart trace: con ambito di riavvio per gestione del segnale di riavvio, svuotamento del lavoro attivo, fasi di shutdown, avvio successivo, tempi di ready e metriche di memoria.
  • Imposta OPENCLAW_DIAGNOSTICS=timeline con OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path> per scrivere una timeline diagnostica di avvio JSONL best-effort per harness QA esterni. Puoi anche abilitare il flag con diagnostics.flags: ["timeline"] nella configurazione; il percorso è comunque fornito tramite env. Aggiungi OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1 per includere campioni dell’event loop.
  • Esegui prima pnpm build, poi pnpm test:startup:gateway -- --runs 5 --warmup 1 per fare benchmark dell’avvio del Gateway rispetto all’entry CLI compilata. Il benchmark registra il primo output del processo, /healthz, /readyz, tempi della traccia di avvio, ritardo dell’event loop e dettagli sui tempi delle tabelle di lookup dei Plugin.
  • Esegui prima pnpm build, poi pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5 per fare benchmark del riavvio in-process del Gateway rispetto all’entry CLI compilata su macOS o Linux. Il benchmark di riavvio usa SIGUSR1, abilita sia le tracce di avvio sia quelle di riavvio nel processo figlio e registra il successivo /healthz, il successivo /readyz, downtime, tempi di ready, CPU, RSS e metriche della traccia di riavvio.
  • Considera /healthz come liveness e /readyz come readiness utilizzabile. Le righe di traccia e l’output del benchmark servono per l’attribuzione al proprietario; non considerare un singolo span di traccia o un singolo campione come una conclusione completa sulle prestazioni.

​
Interrogare un Gateway in esecuzione

Tutti i comandi di query usano WebSocket RPC.
  • Predefinita: leggibile da persone (colorata in TTY).
  • --json: JSON leggibile da macchine (senza stile/spinner).
  • --no-color (o NO_COLOR=1): disabilita ANSI mantenendo il layout umano.
Quando imposti --url, la CLI non fa fallback alle credenziali di configurazione o ambiente. Passa esplicitamente --token o --password. La mancanza di credenziali esplicite è un errore.

​
gateway health

openclaw gateway health --url ws://127.0.0.1:18789
openclaw gateway health --port 18789
L’endpoint HTTP /healthz è una sonda di liveness: restituisce quando il server può rispondere via HTTP. L’endpoint HTTP /readyz è più rigoroso e rimane rosso mentre sidecar dei Plugin di avvio, canali o hook configurati si stanno ancora assestando. Le risposte dettagliate di readiness locali o autenticate includono un blocco diagnostico eventLoop con ritardo dell’event loop, utilizzo dell’event loop, rapporto dei core CPU e un flag degraded.
​
--port <port>
number
Indirizza un Gateway local loopback su questa porta. Questo sovrascrive OPENCLAW_GATEWAY_URL e OPENCLAW_GATEWAY_PORT per la chiamata di health.

​
gateway usage-cost

Recupera riepiloghi usage-cost dai log di sessione. 
openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --agent work --json
openclaw gateway usage-cost --all-agents
openclaw gateway usage-cost --json
​
--days <days>
number
predefinito:"30"
Numero di giorni da includere.
​
--agent <id>
string
Limita il riepilogo dei costi a un singolo id agent configurato.
​
--all-agents
boolean
Aggrega il riepilogo dei costi su tutti gli agent configurati. Non può essere combinato con --agent.

​
gateway stability

Recupera il recorder diagnostico recente della stabilità da un Gateway in esecuzione. 
openclaw gateway stability
openclaw gateway stability --type payload.large
openclaw gateway stability --bundle latest
openclaw gateway stability --bundle latest --export
openclaw gateway stability --json
​
--limit <limit>
number
predefinito:"25"
Numero massimo di eventi recenti da includere (max 1000).
​
--type <type>
string
Filtra per tipo di evento diagnostico, come payload.large o diagnostic.memory.pressure.
​
--since-seq <seq>
number
Includi solo eventi dopo un numero di sequenza diagnostico.
​
--bundle [path]
string
Leggi un bundle di stabilità persistito invece di chiamare il Gateway in esecuzione. Usa --bundle latest (o solo --bundle) per il bundle più recente nella directory di stato, oppure passa direttamente un percorso JSON del bundle.
​
--export
boolean
Scrivi uno zip di diagnostica di supporto condivisibile invece di stampare i dettagli di stabilità.
​
--output <path>
string
Percorso di output per --export.
  • 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 diagnostics export

Scrive uno zip diagnostico locale progettato per essere allegato a segnalazioni di bug. Per il modello di privacy e i contenuti del bundle, vedi Esportazione diagnostica. 
openclaw gateway diagnostics export
openclaw gateway diagnostics export --output openclaw-diagnostics.zip
openclaw gateway diagnostics export --json
​
--output <path>
string
Percorso dello zip di output. Il valore predefinito e’ un’esportazione per il supporto nella directory di stato.
​
--log-lines <count>
number
predefinito:"5000"
Numero massimo di righe di log sanificate da includere.
​
--log-bytes <bytes>
number
predefinito:"1000000"
Numero massimo di byte di log da ispezionare.
​
--url <url>
string
URL WebSocket del Gateway per lo snapshot di integrita’.
​
--token <token>
string
Token del Gateway per lo snapshot di integrita’.
​
--password <password>
string
Password del Gateway per lo snapshot di integrita’.
​
--timeout <ms>
number
predefinito:"3000"
Timeout dello snapshot di stato/integrita’.
​
--no-stability-bundle
boolean
Salta la ricerca del bundle di stabilita’ persistito.
​
--json
boolean
Stampa il percorso scritto, la dimensione e il manifesto come JSON.
L’esportazione contiene un manifesto, un riepilogo Markdown, la forma della configurazione, dettagli di configurazione sanificati, riepiloghi di log sanificati, snapshot sanificati di stato/integrita’ del Gateway e il bundle di stabilita’ piu’ recente, quando esiste. E’ pensata per essere condivisa. Mantiene dettagli operativi utili al debug, come campi di log OpenClaw sicuri, nomi dei sottosistemi, codici di stato, durate, modalita’ configurate, porte, ID dei plugin, ID dei provider, impostazioni di funzionalita’ non segrete e messaggi di log operativi redatti. Omette o redige testo delle chat, corpi dei webhook, output degli strumenti, credenziali, cookie, identificatori di account/messaggio, testo di prompt/istruzioni, nomi host e valori segreti. Quando un messaggio in stile LogTape sembra testo di payload utente/chat/strumento, l’esportazione conserva solo l’indicazione che un messaggio e’ stato omesso piu’ il relativo conteggio di byte.

​
gateway status

gateway status mostra il servizio Gateway (launchd/systemd/schtasks) piu’ una verifica facoltativa della capacita’ di connettivita’/autenticazione. 
openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc
​
--url <url>
string
Aggiunge una destinazione di verifica esplicita. La remota configurata + localhost vengono comunque verificate.
​
--token <token>
string
Autenticazione tramite token per la verifica.
​
--password <password>
string
Autenticazione tramite password per la verifica.
​
--timeout <ms>
number
predefinito:"10000"
Timeout della verifica.
​
--no-probe
boolean
Salta la verifica della connettivita’ (vista solo del servizio).
​
--deep
boolean
Scansiona anche i servizi a livello di sistema.
​
--require-rpc
boolean
Aggiorna la verifica di connettivita’ predefinita a una verifica di lettura ed esce con codice diverso da zero quando tale verifica di lettura non riesce. Non puo’ essere combinato con --no-probe.
  • 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.

​
gateway probe

gateway probe e’ il comando “esegui il debug di tutto”. Verifica sempre:
  • il gateway remoto configurato (se impostato), e
  • localhost (local loopback) anche se il remoto e’ configurato.
Se passi --url, quella destinazione esplicita viene aggiunta prima di entrambe. L’output per utenti etichetta le destinazioni come:
  • URL (explicit)
  • Remote (configured) oppure Remote (configured, inactive)
  • Local loopback
Se piu’ destinazioni di verifica sono raggiungibili, le stampa tutte. Un tunnel SSH, un URL TLS/proxy e un URL remoto configurato possono puntare tutti allo stesso gateway anche quando le loro porte di trasporto differiscono; multiple_gateways e’ riservato a gateway raggiungibili distinti o con identita’ ambigua. Piu’ gateway sono supportati quando usi profili isolati (per esempio, un bot di soccorso), ma la maggior parte delle installazioni esegue comunque un solo gateway.
openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --port 18789
​
--port <port>
number
Usa questa porta per la destinazione di verifica local loopback e la porta remota del tunnel SSH. Senza --url, seleziona la destinazione local loopback invece dell’URL dell’ambiente gateway configurato, della porta dell’ambiente o delle destinazioni remote.
  • 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.

​
Remoto tramite SSH (parita’ con app Mac)

La modalita’ “Remote over SSH” dell’app macOS usa un port-forward locale in modo che il gateway remoto (che puo’ essere associato solo a loopback) diventi raggiungibile a ws://127.0.0.1:<port>. Equivalente CLI: 
openclaw gateway probe --ssh user@gateway-host
​
--ssh <target>
string
user@host o user@host:port (la porta predefinita e’ 22).
​
--ssh-identity <path>
string
File di identita’.
​
--ssh-auto
boolean
Sceglie il primo host gateway individuato come destinazione SSH dall’endpoint di discovery risolto (local. piu’ il dominio wide-area configurato, se presente). I suggerimenti solo TXT vengono ignorati.
Configurazione (facoltativa, usata come valori predefiniti):
  • gateway.remote.sshTarget
  • gateway.remote.sshIdentity

​
gateway call <method>

Helper RPC di basso livello. 
openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
​
--params <json>
string
predefinito:"{}"
Stringa oggetto JSON per i parametri.
​
--url <url>
string
URL WebSocket del Gateway.
​
--token <token>
string
Token del Gateway.
​
--password <password>
string
Password del Gateway.
​
--timeout <ms>
number
Budget di timeout.
​
--expect-final
boolean
Principalmente per RPC in stile agente che trasmettono eventi intermedi prima di un payload finale.
​
--json
boolean
Output JSON leggibile da macchina.
--params deve essere JSON valido.

​
Gestire il servizio Gateway

openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

​
Installare con un wrapper

Usa --wrapper quando il servizio gestito deve avviarsi tramite un altro eseguibile, ad esempio uno shim per il gestore dei segreti o un helper run-as. Il wrapper riceve i normali argomenti del Gateway ed è responsabile di eseguire infine openclaw o Node con quegli argomenti. 
cat > ~/.local/bin/openclaw-doppler <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
exec doppler run --project my-project --config production -- openclaw "$@"
EOF
chmod +x ~/.local/bin/openclaw-doppler

openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart
Puoi anche impostare il wrapper tramite l’ambiente. gateway install verifica che il percorso sia un file eseguibile, scrive il wrapper in ProgramArguments del servizio e mantiene OPENCLAW_WRAPPER nell’ambiente del servizio per reinstallazioni forzate, aggiornamenti e riparazioni con doctor successive. 
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
openclaw doctor
Per rimuovere un wrapper mantenuto, svuota OPENCLAW_WRAPPER durante la reinstallazione: 
OPENCLAW_WRAPPER= openclaw gateway install --force
openclaw gateway restart
  • 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.

​
Scoprire i Gateway (Bonjour)

gateway discover esegue la scansione dei beacon del Gateway (_openclaw-gw._tcp).
  • Multicast DNS-SD: local.
  • Unicast DNS-SD (Wide-Area Bonjour): scegli un dominio (esempio: openclaw.internal.) e configura split DNS + un server DNS; consulta Bonjour.
Solo i Gateway con discovery Bonjour abilitata (predefinita) pubblicizzano il beacon. I record di discovery wide-area possono includere questi suggerimenti TXT:
  • role (suggerimento sul ruolo del Gateway)
  • transport (suggerimento sul trasporto, ad es. gateway)
  • gatewayPort (porta WebSocket, di solito 18789)
  • sshPort (solo modalità discovery completa; i client usano come destinazioni SSH predefinite 22 quando è assente)
  • tailnetDns (nome host MagicDNS, quando disponibile)
  • gatewayTls / gatewayTlsSha256 (TLS abilitato + fingerprint del certificato)
  • cliPath (solo modalità discovery completa)

​
gateway discover

openclaw gateway discover
​
--timeout <ms>
number
predefinito:"2000"
Timeout per comando (browse/resolve).
​
--json
boolean
Output leggibile dalla macchina (disabilita anche stile/spinner).
Esempi: 
openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'
  • La CLI esegue la scansione di local. più il dominio wide-area configurato quando ne è abilitato uno.
  • wsUrl nell’output JSON deriva dall’endpoint del servizio risolto, non da suggerimenti solo TXT come lanHost o tailnetDns.
  • Su mDNS local. e DNS-SD wide-area, sshPort e cliPath vengono pubblicati solo quando discovery.mdns.mode è full.

​
Correlati