OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

Gateway

Il Gateway è il server WebSocket di OpenClaw (canali, nodi, sessioni, hook). Tutti i sottocomandi seguenti sono disponibili in openclaw gateway ....

Rilevamento Bonjour

Configurazione mDNS locale + DNS-SD su rete geografica.
Panoramica del rilevamento

Come OpenClaw pubblicizza e rileva i gateway.
Configurazione

Chiavi di configurazione di primo livello del gateway.

Eseguire il Gateway

bash
openclaw gatewayopenclaw gateway run   # forma equivalente ed esplicita
Comportamento all'avvio
  • Rifiuta di avviarsi a meno che gateway.mode=local non sia impostato in ~/.openclaw/openclaw.json. Usa --allow-unconfigured per esecuzioni ad hoc/di sviluppo; l'opzione ignora il controllo senza scrivere né riparare la configurazione.
  • openclaw onboard --mode local e openclaw setup scrivono gateway.mode=local. Se il file di configurazione esiste ma gateway.mode è assente, la configurazione viene considerata danneggiata o sovrascritta e il Gateway rifiuta di presumere local: esegui nuovamente l'onboarding, imposta manualmente la chiave oppure passa --allow-unconfigured.
  • L'associazione a interfacce diverse da local loopback senza autenticazione viene bloccata.
  • Attualmente i valori lan, tailnet e custom di --bind vengono risolti esclusivamente tramite percorsi IPv4; le configurazioni con host personalizzato esclusivamente IPv6 richiedono un sidecar IPv4 o un proxy davanti al Gateway.
  • SIGUSR1 attiva un riavvio interno al processo quando autorizzato. commands.restart (predefinito: abilitato) controlla i segnali SIGUSR1 inviati dall'esterno; impostalo su false per bloccare i riavvii manuali tramite segnale del sistema operativo, continuando a consentire il riavvio tramite il comando gateway restart, lo strumento gateway e l'applicazione o l'aggiornamento della configurazione.
  • SIGINT/SIGTERM arrestano il processo ma non ripristinano lo stato personalizzato del terminale: se incorpori la CLI in una TUI o usi un input in modalità raw, ripristina autonomamente il terminale prima dell'uscita.

Opzioni

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> Porta WebSocket (valore predefinito da configurazione/ambiente; solitamente 18789).

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tYmluZCA8bW9kZQ " type="string"> Modalità di associazione: loopback (predefinita), lan, tailnet, auto, custom.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdG9rZW4gPHRva2Vu " type="string"> Token condiviso per connect.params.auth.token. Il valore predefinito è OPENCLAW_GATEWAY_TOKEN, se impostato.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tYXV0aCA8bW9kZQ " type="string"> Modalità di autenticazione: none, token, password, trusted-proxy.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcGFzc3dvcmQgPHBhc3N3b3Jk " type="string"> Password per --auth password.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdGFpbHNjYWxlIDxtb2Rl " type="string"> Esposizione tramite Tailscale: off, serve, funnel.

--tailscale-reset-on-exitboolean

Reimposta la configurazione serve/funnel di Tailscale all'arresto.

--allow-unconfiguredboolean

Avvia senza imporre gateway.mode=local. Solo per bootstrap ad hoc/di sviluppo; non rende persistente né ripara la configurazione.

--devboolean

Crea una configurazione e un'area di lavoro di sviluppo, se assenti (ignora BOOTSTRAP.md).

--resetboolean

Reimposta configurazione di sviluppo, credenziali, sessioni e area di lavoro. Richiede --dev.

--forceboolean

Termina qualsiasi listener esistente sulla porta di destinazione prima dell'avvio.

--verboseboolean

Registrazione dettagliata su stdout/stderr.

--cli-backend-logsboolean

Mostra nella console solo i log del backend della CLI (abilita anche stdout/stderr).

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0td3MtbG9nIDxzdHlsZQ " type="string" default="auto"> Stile dei log WebSocket: auto, full, compact.

--compactboolean

Alias di --ws-log compact.

--raw-streamboolean

Registra in JSONL gli eventi raw del flusso del modello.

--claude-cli-logs è un alias deprecato di --cli-backend-logs.

Per --bind custom, imposta gateway.customBindHost su un indirizzo IPv4. Qualsiasi indirizzo diverso da 127.0.0.1 o 0.0.0.0 richiede anche 127.0.0.1 sulla stessa porta per i client sullo stesso host; l'avvio non riesce se uno dei due listener non può effettuare l'associazione. Il carattere jolly 0.0.0.0 non aggiunge un alias obbligatorio separato. Le configurazioni con host personalizzato esclusivamente IPv6 richiedono un sidecar IPv4 o un proxy davanti al Gateway.

Riavviare il Gateway

bash
openclaw gateway restartopenclaw gateway restart --safeopenclaw gateway restart --safe --skip-deferralopenclaw gateway restart --forceopenclaw gateway restart --wait 30s

--safe richiede al Gateway in esecuzione di verificare preliminarmente le attività attive e pianificare un unico riavvio accorpato dopo il loro completamento. L'attesa è limitata da gateway.reload.deferralTimeoutMs (valore predefinito: 5 minuti / 300000); allo scadere del limite, il riavvio viene forzato. Imposta deferralTimeoutMs: 0 per attendere indefinitamente, con avvisi periodici sulle attività ancora in sospeso, anziché forzare il riavvio. --safe non può essere combinato con --force o --wait.

--skip-deferral ignora il controllo di rinvio basato sulle attività attive durante un riavvio sicuro, pertanto il Gateway si riavvia immediatamente anche in presenza di impedimenti segnalati. Richiede --safe: usalo quando un rinvio è bloccato da un'attività fuori controllo.

--wait <duration> sostituisce il limite di attesa per il completamento delle attività durante un normale riavvio non sicuro. Accetta millisecondi senza suffisso oppure i suffissi di unità ms, s, m, h, d (ad esempio 30s, 5m, 1h30m); --wait 0 attende indefinitamente. Non è compatibile con --force o --safe.

--force ignora l'attesa per il completamento delle attività attive e riavvia immediatamente. Il semplice comando restart (senza opzioni) mantiene il comportamento di riavvio esistente del gestore dei servizi.

Profilazione del Gateway

  • OPENCLAW_GATEWAY_STARTUP_TRACE=1 registra le durate delle fasi durante l'avvio, inclusi il ritardo eventLoopMax per ciascuna fase e le durate delle tabelle di ricerca dei plugin (indice delle installazioni, registro dei manifest, pianificazione dell'avvio, elaborazione della mappa dei proprietari).
  • OPENCLAW_GATEWAY_RESTART_TRACE=1 registra righe restart trace: relative al riavvio: gestione dei segnali, attesa per il completamento delle attività attive, fasi di arresto, avvio successivo, tempo necessario per essere pronto e metriche della memoria.
  • OPENCLAW_DIAGNOSTICS=timeline con OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path> scrive, secondo il principio del massimo sforzo, una cronologia diagnostica JSONL dell'avvio destinata a sistemi QA esterni (equivalente alla configurazione diagnostics.flags: ["timeline"]; il percorso resta configurabile solo tramite ambiente). Aggiungi OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1 per includere campioni del ciclo degli eventi.
  • pnpm build seguito da pnpm test:startup:gateway -- --runs 5 --warmup 1 misura le prestazioni di avvio del Gateway rispetto al punto di ingresso della CLI compilata: primo output del processo, /healthz, /readyz, durate della traccia di avvio, ritardo del ciclo degli eventi e durata delle tabelle di ricerca dei plugin.
  • pnpm build seguito da pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5 misura le prestazioni del riavvio interno al processo su macOS o Linux (non supportato su Windows; il riavvio richiede SIGUSR1). Usa SIGUSR1, abilita entrambe le tracce nel processo figlio e registra le successive risposte di /healthz e /readyz, il periodo di indisponibilità, il tempo necessario per essere pronto, CPU, RSS e le metriche della traccia di riavvio.
  • /healthz indica che il servizio è attivo; /readyz indica che è pronto per l'uso. Considera le righe di traccia e l'output dei benchmark come segnali per attribuire la responsabilità ai componenti, non come una conclusione completa sulle prestazioni basata su un singolo intervallo o campione.

Interrogare un Gateway in esecuzione

Tutti i comandi di interrogazione usano RPC tramite WebSocket.

Modalità di output

  • Predefinita: leggibile dall'utente (a colori in una TTY).
  • --json: JSON leggibile dalla macchina (senza stile o indicatore di attività).
  • --no-color (oppure NO_COLOR=1): disabilita ANSI mantenendo il formato leggibile dall'utente.

Opzioni condivise

  • --url <url>: URL WebSocket del Gateway.
  • --token <token>: token del Gateway.
  • --password <password>: password del Gateway.
  • --timeout <ms>: timeout/limite temporale (il valore predefinito varia in base al comando; consulta ciascun comando di seguito).
  • --expect-final: attende una risposta "finale" (chiamate dell'agente).

gateway health

bash
openclaw gateway health --url ws://127.0.0.1:18789openclaw gateway health --port 18789

/healthz è una verifica dell'attività: restituisce una risposta non appena il server è in grado di rispondere tramite HTTP. /readyz è più rigoroso e resta in stato di errore mentre i sidecar dei plugin di avvio, i canali o gli hook configurati sono ancora in fase di inizializzazione. Le risposte dettagliate locali o autenticate di /readyz includono un blocco diagnostico eventLoop (ritardo, utilizzo, rapporto rispetto ai core della CPU, indicatore degraded).

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> Seleziona un Gateway local loopback su questa porta. Per questa chiamata, sostituisce OPENCLAW_GATEWAY_URL e OPENCLAW_GATEWAY_PORT.

gateway usage-cost

Recupera i riepiloghi dei costi di utilizzo dai log delle sessioni.

bash
openclaw gateway usage-costopenclaw gateway usage-cost --days 7openclaw gateway usage-cost --agent work --jsonopenclaw gateway usage-cost --all-agentsopenclaw gateway usage-cost --json
"--days
"--agent
--all-agentsboolean

Aggrega i dati di tutti gli agenti configurati. Non può essere combinato con --agent.

gateway stability

Recupera le registrazioni diagnostiche recenti sulla stabilità da un Gateway in esecuzione.

bash
openclaw gateway stabilityopenclaw gateway stability --type payload.largeopenclaw gateway stability --bundle latestopenclaw gateway stability --bundle latest --exportopenclaw gateway stability --json

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tbGltaXQgPGxpbWl0 " type="number" default="25"> Numero massimo di eventi recenti da includere (massimo 1000).

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdHlwZSA8dHlwZQ " type="string"> Filtra per tipo di evento diagnostico, ad esempio payload.large o diagnostic.memory.pressure.

"--since-seq
--bundle [path]string

Legge un pacchetto di stabilità persistente anziché chiamare il Gateway in esecuzione. --bundle latest (o il solo --bundle) seleziona il pacchetto più recente nella directory di stato; puoi anche passare direttamente il percorso di un pacchetto JSON.

--exportboolean

Scrive un archivio ZIP condivisibile con la diagnostica per l'assistenza anziché stampare i dettagli sulla stabilità.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tb3V0cHV0IDxwYXRo " type="string"> Percorso di output per --export.

Privacy e comportamento dei pacchetti
  • Le registrazioni conservano metadati operativi: nomi degli eventi, conteggi, dimensioni in byte, rilevazioni della memoria, stato delle code e delle sessioni, ID delle approvazioni, nomi di canali e plugin e riepiloghi anonimizzati delle sessioni. Escludono testo delle chat, corpi dei webhook, output degli strumenti, corpi raw delle richieste e delle risposte, token, cookie, valori segreti, nomi host e ID raw delle sessioni. Imposta diagnostics.enabled: false per disabilitare completamente il registratore.
  • Le uscite irreversibili del Gateway, i timeout di arresto e gli errori di avvio durante un riavvio scrivono la stessa istantanea diagnostica in ~/.openclaw/logs/stability/openclaw-stability-*.json quando il registratore contiene eventi. Esamina il pacchetto più recente con openclaw gateway stability --bundle latest; --limit, --type e --since-seq si applicano anche all'output dei pacchetti.

gateway diagnostics export

Scrive un archivio ZIP locale con la diagnostica, progettato per le segnalazioni di bug. Per il modello di privacy e il contenuto del pacchetto, consulta Esportazione della diagnostica.

bash
openclaw gateway diagnostics exportopenclaw gateway diagnostics export --output openclaw-diagnostics.zipopenclaw gateway diagnostics export --json
"--log-lines
"--log-bytes
"--url
"--token
"--password
"--timeout
--no-stability-bundleboolean

Ignora la ricerca del pacchetto di stabilità persistente.

--jsonboolean

Stampa in formato JSON il percorso scritto, le dimensioni e il manifesto.

L'esportazione raggruppa: manifest.json (inventario dei file), summary.md (riepilogo Markdown), diagnostics.json (riepilogo di primo livello di configurazione/log/rilevamento/stabilità/stato/integrità), config/sanitized.json, status/gateway-status.json, health/gateway-health.json, logs/openclaw-sanitized.jsonl e stability/latest.json quando esiste un pacchetto.

È progettata per essere condivisa. Mantiene i dettagli operativi utili per il debug — campi di log sicuri, nomi dei sottosistemi, codici di stato, durate, modalità configurate, porte, ID di plugin/provider, impostazioni non segrete delle funzionalità e messaggi operativi di log oscurati — e omette o oscura il testo delle chat, i corpi dei webhook, gli output degli strumenti, le credenziali, i cookie, gli identificatori di account/messaggi, il testo di prompt/istruzioni, i nomi host e i valori segreti. Quando un messaggio di log sembra contenere il testo di un payload utente/chat/strumento (ad es. "l'utente ha detto", "testo della chat", "output dello strumento", "corpo del webhook"), l'esportazione conserva solo l'indicazione che un messaggio è stato omesso e il relativo numero di byte.

gateway status

Mostra il servizio Gateway (launchd/systemd/schtasks) insieme a una verifica facoltativa di connettività/autenticazione.

bash
openclaw gateway statusopenclaw gateway status --jsonopenclaw gateway status --require-rpc
"--url
"--token
"--password
"--timeout
--no-probeboolean

Salta la verifica della connettività (visualizzazione del solo servizio).

--deepboolean

Analizza anche i servizi a livello di sistema.

--require-rpcboolean

Estende la verifica della connettività a una verifica di lettura e termina con un codice diverso da zero in caso di errore. Non può essere combinato con --no-probe.

Semantica dello stato
  • Rimane disponibile per la diagnostica anche quando la configurazione CLI locale è mancante o non valida.
  • L'output predefinito verifica lo stato del servizio, la connessione WebSocket e la capacità di autenticazione visibile durante l'handshake, non le operazioni di lettura/scrittura/amministrazione.
  • Le verifiche non apportano modifiche all'autenticazione iniziale del dispositivo: riutilizzano un token del dispositivo già memorizzato nella cache, se presente, ma non creano mai una nuova identità CLI del dispositivo o un record di associazione in sola lettura al solo scopo di controllare lo stato.
  • Quando possibile, risolve i SecretRef di autenticazione configurati per autenticare la verifica. Se un SecretRef obbligatorio non viene risolto, --json segnala rpc.authWarning quando la connettività/autenticazione della verifica non riesce; passa esplicitamente --token/--password oppure correggi l'origine del segreto. Gli avvisi relativi all'autenticazione non risolta vengono soppressi quando la verifica riesce.
  • L'output JSON include gateway.version quando il Gateway in esecuzione lo segnala; --require-rpc può ricorrere al payload RPC status.runtimeVersion se la verifica dell'handshake non riesce a fornire i metadati della versione.
  • Usa --require-rpc negli script e nelle automazioni quando un servizio in ascolto non è sufficiente ed è necessario che anche l'RPC con ambito di lettura sia operativo.
  • --deep cerca installazioni launchd/systemd/schtasks aggiuntive; quando vengono trovati più servizi simili a Gateway, l'output leggibile mostra suggerimenti per la pulizia (in genere, eseguire un solo Gateway per macchina) e segnala, quando pertinente, un recente passaggio di consegne dovuto al riavvio del supervisore.
  • --deep esegue inoltre la convalida della configurazione in modalità consapevole dei Plugin (pluginValidation: "full") e mostra gli avvisi del manifesto dei Plugin (ad es. metadati mancanti della configurazione del canale). Il comando predefinito gateway status mantiene il rapido percorso in sola lettura che salta la convalida dei Plugin.
  • L'output leggibile include il percorso risolto del file di log, oltre ai percorsi e alla validità delle configurazioni della CLI e del servizio, per facilitare la diagnosi delle divergenze del profilo o della directory di stato.
Controlli della divergenza dell'autenticazione di systemd su Linux
  • I controlli della divergenza dell'autenticazione del servizio leggono sia Environment= sia EnvironmentFile= dall'unità (inclusi %h, percorsi tra virgolette, più file e file facoltativi con -).
  • Risolve i SecretRef di gateway.auth.token usando l'ambiente di runtime unificato (prima l'ambiente del comando del servizio, quindi l'ambiente del processo come ripiego).
  • I controlli della divergenza del token saltano la risoluzione del token di configurazione quando l'autenticazione tramite token non è effettivamente attiva (gateway.auth.mode impostato esplicitamente su password/none/trusted-proxy, oppure modalità non impostata quando la password può avere la precedenza e nessun token candidato può prevalere).

gateway probe

Il comando per il "debug completo". Verifica sempre:

  • il Gateway remoto configurato (se impostato) e
  • localhost (local loopback), anche se è configurato un endpoint remoto.

Passare --url aggiunge tale destinazione esplicita prima di entrambe. L'output leggibile etichetta le destinazioni come URL (esplicito), Remoto (configurato) / Remoto (configurato, inattivo) e Local loopback.

bash
openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --port 18789

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> Usa questa porta per la destinazione di verifica local loopback e come porta remota del tunnel SSH. Senza --url, seleziona solo la destinazione local loopback invece dell'URL dell'ambiente Gateway configurato, della porta dell'ambiente o delle destinazioni remote.

Interpretazione
  • Raggiungibile: sì significa che almeno una destinazione ha accettato una connessione WebSocket.
  • Capacità: sola lettura|con possibilità di scrittura|con possibilità di amministrazione|associazione in sospeso|sola connessione indica ciò che la verifica ha potuto accertare sull'autenticazione, separatamente dalla raggiungibilità.
  • Verifica di lettura: riuscita significa che anche le chiamate RPC di dettaglio con ambito di lettura (health/status/system-presence/config.get) sono riuscite.
  • Verifica di lettura: limitata - ambito mancante: operator.read significa che la connessione è riuscita, ma l'RPC con ambito di lettura è limitato. Viene segnalata come raggiungibilità degradata, non come errore completo.
  • Verifica di lettura: non riuscita dopo Connessione: riuscita significa che la connessione WebSocket è stata stabilita, ma la diagnostica di lettura successiva è scaduta o non è riuscita; anche in questo caso lo stato è degradato, non irraggiungibile.
  • Come gateway status, la verifica riutilizza l'autenticazione del dispositivo già memorizzata nella cache, ma non crea l'identità iniziale del dispositivo o lo stato di associazione.
  • Il codice di uscita è diverso da zero solo quando nessuna destinazione verificata è raggiungibile.
Output JSON

Livello superiore:

  • ok: almeno una destinazione è raggiungibile.
  • degraded: almeno una destinazione ha accettato una connessione, ma non ha completato la diagnostica RPC dettagliata.
  • capability: migliore capacità rilevata tra le destinazioni raggiungibili (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope o unknown).
  • primaryTargetId: migliore destinazione da considerare come quella attiva, nell'ordine: URL esplicito, tunnel SSH, endpoint remoto configurato, local loopback.
  • warnings[]: record di avviso ottenuti al meglio delle possibilità, con code, message e targetIds facoltativi.
  • network: suggerimenti per gli URL local loopback/tailnet derivati dalla configurazione corrente e dalla rete dell'host.
  • discovery.timeoutMs / discovery.count: budget di rilevamento effettivo e numero di risultati usati per questa sessione di verifica.

Per destinazione (targets[].connect): ok (classificazione di raggiungibilità e degrado), rpcOk (successo completo dell'RPC dettagliato), scopeLimited (RPC dettagliato non riuscito a causa della mancanza dell'ambito operatore).

Per destinazione (targets[].auth): role e scopes segnalati in hello-ok quando disponibili, oltre alla classificazione capability mostrata.

Codici di avviso comuni
  • ssh_tunnel_failed: la configurazione del tunnel SSH non è riuscita; il comando ha ripiegato sulle verifiche dirette.
  • multiple_gateways: erano raggiungibili identità Gateway distinte oppure OpenClaw non ha potuto verificare che le destinazioni raggiungibili fossero lo stesso Gateway. Un tunnel SSH, un URL proxy o un URL remoto configurato verso lo stesso Gateway non attivano questo avviso.
  • auth_secretref_unresolved: non è stato possibile risolvere un SecretRef di autenticazione configurato per una destinazione non riuscita.
  • probe_scope_limited: la connessione WebSocket è riuscita, ma la verifica di lettura era limitata dalla mancanza di operator.read.
  • local_tls_runtime_unavailable: TLS del Gateway locale è abilitato, ma OpenClaw non ha potuto caricare l'impronta digitale del certificato locale.

Connessione remota tramite SSH (parità con l'app per Mac)

La modalità "Remote over SSH" dell'app macOS usa un inoltro di porta locale affinché un Gateway remoto accessibile solo tramite loopback diventi raggiungibile all'indirizzo ws://127.0.0.1:<port>.

Equivalente CLI:

bash
openclaw gateway probe --ssh user@gateway-host

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc3NoIDx0YXJnZXQ " type="string"> user@host o user@host:port (la porta predefinita è 22).

--ssh-autoboolean

Seleziona il primo host Gateway rilevato come destinazione SSH dall'endpoint di rilevamento risolto (local. più il dominio geografico configurato, se presente). I suggerimenti solo TXT vengono ignorati.

Valori predefiniti della configurazione (facoltativi): gateway.remote.sshTarget, gateway.remote.sshIdentity.

gateway call <method>

Strumento RPC di basso livello.

bash
openclaw gateway call statusopenclaw gateway call logs.tail --params '{"limit": 200}'
"--params
"--url
"--token
"--password
"--timeout
--expect-finalboolean

Principalmente per RPC in stile agente che trasmettono eventi intermedi prima di un payload finale.

--jsonboolean

Output JSON leggibile dalla macchina.

Gestire il servizio Gateway

bash
openclaw gateway installopenclaw gateway startopenclaw gateway stopopenclaw gateway restartopenclaw gateway uninstall

Installazione con un wrapper

Usa --wrapper quando il servizio gestito deve essere avviato tramite un altro eseguibile, ad esempio uno shim per la gestione dei segreti o uno strumento di esecuzione con un altro utente. Il wrapper riceve i normali argomenti del Gateway ed è responsabile dell'esecuzione finale di openclaw o Node con tali argomenti.

bash
cat > ~/.local/bin/openclaw-doppler <<'EOF'#!/usr/bin/env bashset -euo pipefailexec doppler run --project my-project --config production -- openclaw "$@"EOFchmod +x ~/.local/bin/openclaw-doppler openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --forceopenclaw gateway restart

Puoi anche impostare il wrapper tramite l'ambiente. gateway install verifica che il percorso sia un file eseguibile, inserisce il wrapper nei ProgramArguments del servizio e rende persistente OPENCLAW_WRAPPER nell'ambiente del servizio per successive reinstallazioni forzate, aggiornamenti e riparazioni eseguite da doctor.

bash
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --forceopenclaw doctor

Per rimuovere un wrapper persistente, azzera OPENCLAW_WRAPPER durante la reinstallazione:

bash
OPENCLAW_WRAPPER= openclaw gateway install --forceopenclaw gateway restart
Opzioni dei comandi
  • gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
  • gateway install: --port, --runtime <node|bun> (valore predefinito: node), --token, --wrapper <path>, --force, --json
  • gateway restart: --safe, --skip-deferral, --force, --wait <duration>, --json
  • gateway uninstall|start: --json
  • gateway stop: --disable, --json
Comportamento del ciclo di vita
  • Usa gateway restart per riavviare un servizio gestito. Non concatenare gateway stop e gateway start come alternativa al riavvio.
  • Su macOS, per impostazione predefinita gateway stop usa launchctl bootout, che rimuove il LaunchAgent dalla sessione di avvio corrente senza rendere persistente la disabilitazione: il ripristino automatico KeepAlive resta attivo per arresti anomali futuri e gateway start riabilita correttamente il servizio senza dover eseguire manualmente launchctl enable. Passa --disable per disattivare in modo persistente KeepAlive e RunAtLoad, impedendo al Gateway di riavviarsi fino alla successiva esecuzione esplicita di gateway start; usa questa opzione quando un arresto manuale deve persistere dopo il riavvio del sistema.
  • I comandi del ciclo di vita accettano --json per l'uso negli script.
Autenticazione e SecretRef al momento dell'installazione
  • Quando l'autenticazione tramite token richiede un token e gateway.auth.token è gestito tramite SecretRef, gateway install verifica 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 configurato per il token non è risolto, l'installazione si interrompe in modo sicuro anziché rendere persistente un valore di ripiego in testo normale.
  • Per l'autenticazione tramite password con gateway run, preferisci OPENCLAW_GATEWAY_PASSWORD, --password-file o un gateway.auth.password basato su SecretRef rispetto a --password specificato direttamente.
  • Nella modalità di autenticazione dedotta, OPENCLAW_GATEWAY_PASSWORD impostata solo nella shell non attenua i requisiti del token per l'installazione; quando installi un servizio gestito, usa una configurazione persistente (gateway.auth.password o env nella configurazione).
  • 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 specificata esplicitamente.

Individuare i Gateway (Bonjour)

gateway discover esegue la scansione dei beacon dei Gateway (_openclaw-gw._tcp).

  • DNS-SD multicast: local.
  • DNS-SD unicast (Bonjour su rete geografica): scegli un dominio (esempio: openclaw.internal.) e configura un DNS suddiviso e un server DNS; consulta Bonjour.

Solo i Gateway con l'individuazione Bonjour abilitata (impostazione predefinita) pubblicizzano il beacon.

Indicazioni TXT presenti in ogni beacon: role (indicazione sul ruolo del Gateway), transport (indicazione sul trasporto, ad esempio gateway), gatewayPort (porta WebSocket, solitamente 18789), tailnetDns (nome host MagicDNS, quando disponibile), gatewayTls / gatewayTlsSha256 (TLS abilitato e impronta digitale del certificato). sshPort e cliPath vengono pubblicati solo nella modalità di individuazione completa (discovery.mdns.mode: "full"; il valore predefinito è "minimal", che li omette; in tal caso, i client usano per impostazione predefinita la porta 22 per le destinazioni SSH).

gateway discover

bash
openclaw gateway discover
"--timeout
--jsonboolean

Output leggibile dalla macchina (disabilita anche lo stile e l'indicatore di attività).

Esempi:

bash
openclaw gateway discover --timeout 4000openclaw gateway discover --json | jq '.beacons[].wsUrl'

Contenuti correlati

Was this useful?
On this page

On this page