Vai al contenuto principale
Usa questa pagina per l’avvio del giorno 1 e le operazioni del giorno 2 del servizio Gateway.

Risoluzione avanzata dei problemi

Diagnostica basata sui sintomi con sequenze esatte di comandi e firme dei log.

Configurazione

Guida alla configurazione orientata alle attività + riferimento completo alla configurazione.

Gestione dei segreti

Contratto SecretRef, comportamento degli snapshot di runtime e operazioni di migrazione/ricaricamento.

Contratto del piano dei segreti

Regole esatte di destinazione/percorso per secrets apply e comportamento dei profili di autenticazione solo ref.

​
Avvio locale in 5 minuti

1

Avvia il Gateway

openclaw gateway --port 18789
# debug/trace mirrored to stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force
2

Verifica l'integrità del servizio

openclaw gateway status
openclaw status
openclaw logs --follow
Baseline integra: Runtime: running, Connectivity probe: ok e Capability: ... che corrisponde a ciò che ti aspetti. Usa openclaw gateway status --require-rpc quando ti serve una prova RPC con ambito di lettura, non solo la raggiungibilità.
3

Convalida la disponibilità del canale

openclaw channels status --probe
Con un gateway raggiungibile, questo esegue probe dei canali live per account e audit facoltativi. Se il gateway non è raggiungibile, la CLI ripiega invece su riepiloghi dei canali basati solo sulla configurazione dell’output dei probe live.
Il ricaricamento della configurazione del Gateway osserva il percorso del file di configurazione attivo (risolto dai valori predefiniti di profilo/stato, oppure da OPENCLAW_CONFIG_PATH quando impostato). La modalità predefinita è gateway.reload.mode="hybrid". Dopo il primo caricamento riuscito, il processo in esecuzione serve lo snapshot della configurazione attiva in memoria; un ricaricamento riuscito sostituisce quello snapshot in modo atomico.

​
Modello di runtime

  • Un processo sempre attivo per routing, piano di controllo e connessioni dei canali.
  • Un’unica porta multiplexata per:
    • Controllo/RPC WebSocket
    • API HTTP (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
    • Route HTTP dei Plugin, come l’opzionale /api/v1/admin/rpc
    • Control UI e hook
  • Modalità di bind predefinita: loopback.
  • L’autenticazione è richiesta per impostazione predefinita. Le configurazioni con segreto condiviso usano gateway.auth.token / gateway.auth.password (oppure OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD) e le configurazioni con reverse proxy non loopback possono usare gateway.auth.mode: "trusted-proxy".

​
Endpoint compatibili con OpenAI

La superficie di compatibilità a maggiore leva di OpenClaw ora è:
  • GET /v1/models
  • GET /v1/models/{id}
  • POST /v1/embeddings
  • POST /v1/chat/completions
  • POST /v1/responses
Perché questo insieme è importante:
  • La maggior parte delle integrazioni Open WebUI, LobeChat e LibreChat controlla prima /v1/models.
  • Molte pipeline RAG e di memoria si aspettano /v1/embeddings.
  • I client agent-native preferiscono sempre più /v1/responses.
Nota di pianificazione:
  • /v1/models è agent-first: restituisce openclaw, openclaw/default e openclaw/<agentId>.
  • openclaw/default è l’alias stabile che mappa sempre all’agente predefinito configurato.
  • Usa x-openclaw-model quando vuoi un override del provider/modello backend; altrimenti restano in controllo il modello normale e la configurazione degli embedding dell’agente selezionato.
Tutti questi endpoint vengono eseguiti sulla porta principale del Gateway e usano lo stesso perimetro di autenticazione dell’operatore attendibile del resto dell’API HTTP del Gateway. RPC HTTP di amministrazione (POST /api/v1/admin/rpc) è una route di Plugin separata, disattivata per impostazione predefinita, per strumenti host che non possono usare RPC WebSocket. Vedi RPC HTTP di amministrazione.

​
Precedenza di porta e bind

ImpostazioneOrdine di risoluzione
Porta Gateway--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Modalità di bindCLI/override → gateway.bind → loopback
I servizi gateway installati registrano la --port risolta nei metadati del supervisore. Dopo aver modificato gateway.port, esegui openclaw doctor --fix oppure openclaw gateway install --force affinché launchd/systemd/schtasks avvii il processo sulla nuova porta. L’avvio del Gateway usa la stessa porta e lo stesso bind effettivi quando inizializza le origini locali della Control UI per bind non loopback. Per esempio, --bind lan --port 3000 inizializza http://localhost:3000 e http://127.0.0.1:3000 prima dell’esecuzione della convalida di runtime. Aggiungi esplicitamente eventuali origini di browser remoti, come URL di proxy HTTPS, a gateway.controlUi.allowedOrigins.

​
Modalità di hot reload

gateway.reload.modeComportamento
offNessun ricaricamento della configurazione
hotApplica solo modifiche sicure a caldo
restartRiavvia in caso di modifiche che richiedono ricaricamento
hybrid (predefinita)Applica a caldo quando sicuro, riavvia quando richiesto

​
Set di comandi operatore

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor
gateway status --deep serve per la scoperta aggiuntiva dei servizi (LaunchDaemons/unità systemd di sistema/schtasks), non per un probe RPC più approfondito dell’integrità.

​
Gateway multipli (stesso host)

La maggior parte delle installazioni dovrebbe eseguire un gateway per macchina. Un singolo gateway può ospitare più agenti e canali. Hai bisogno di più gateway solo quando vuoi intenzionalmente isolamento o un bot di soccorso. Controlli utili: 
openclaw gateway status --deep
openclaw gateway probe
Cosa aspettarsi:
  • gateway status --deep può segnalare Other gateway-like services detected (best effort) e stampare suggerimenti di pulizia quando sono ancora presenti installazioni launchd/systemd/schtasks obsolete.
  • gateway probe può avvisare di multiple reachable gateway identities quando rispondono gateway distinti, oppure quando OpenClaw non può provare che le destinazioni raggiungibili siano lo stesso gateway. Un tunnel SSH, un URL proxy o un URL remoto configurato verso lo stesso gateway è un solo gateway con più trasporti, anche quando le porte di trasporto sono diverse.
  • Se è intenzionale, isola porte, configurazione/stato e radici degli spazi di lavoro per gateway.
Checklist per istanza:
  • gateway.port univoco
  • OPENCLAW_CONFIG_PATH univoco
  • OPENCLAW_STATE_DIR univoco
  • agents.defaults.workspace univoco
Esempio: 
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
Configurazione dettagliata: /gateway/multiple-gateways.

​
Accesso remoto

Preferito: Tailscale/VPN. Ripiego: tunnel SSH. 
ssh -N -L 18789:127.0.0.1:18789 user@host
Poi connetti i client localmente a ws://127.0.0.1:18789.
I tunnel SSH non aggirano l’autenticazione del gateway. Per l’autenticazione con segreto condiviso, i client devono comunque inviare token/password anche attraverso il tunnel. Per le modalità che trasportano identità, la richiesta deve comunque soddisfare quel percorso di autenticazione.
Vedi: Gateway remoto, Autenticazione, Tailscale.

​
Supervisione e ciclo di vita del servizio

Usa esecuzioni supervisionate per affidabilità simile alla produzione. 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
Usa openclaw gateway restart per i riavvii. Non concatenare openclaw gateway stop e openclaw gateway start come sostituto del riavvio.Su macOS, gateway stop usa launchctl bootout per impostazione predefinita: questo rimuove il LaunchAgent dalla sessione di avvio corrente senza rendere persistente una disabilitazione, quindi il ripristino automatico KeepAlive continua a funzionare dopo crash imprevisti e gateway start riabilita in modo pulito. Per sopprimere in modo persistente il respawn automatico tra i riavvii, passa --disable: openclaw gateway stop --disable.Le etichette LaunchAgent sono ai.openclaw.gateway (predefinita) oppure ai.openclaw.<profile> (profilo con nome). openclaw doctor controlla e ripara la deriva della configurazione del servizio.

​
Percorso rapido per profilo dev

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
I valori predefiniti includono stato/configurazione isolati e porta gateway base 19001.

​
Riferimento rapido del protocollo (vista operatore)

  • Il primo frame del client deve essere connect.
  • Il Gateway restituisce lo snapshot hello-ok (presence, health, stateVersion, uptimeMs, limiti/policy).
  • hello-ok.features.methods / events sono un elenco di scoperta conservativo, non un dump generato di ogni route helper richiamabile.
  • Richieste: req(method, params) → res(ok/payload|error).
  • Gli eventi comuni includono connect.challenge, agent, chat, session.message, session.operation, session.tool, sessions.changed, presence, tick, health, heartbeat, eventi del ciclo di vita pairing/approval, e shutdown.
Le esecuzioni degli agenti hanno due fasi:
  1. Ack accettato immediato (status:"accepted")
  2. Risposta finale di completamento (status:"ok"|"error"), con eventi agent in streaming nel mezzo.
Vedi la documentazione completa del protocollo: Protocollo Gateway.

​
Controlli operativi

​
Vitalità

  • Apri WS e invia connect.
  • Aspettati una risposta hello-ok con snapshot.

​
Prontezza

openclaw gateway status
openclaw channels status --probe
openclaw health

​
Recupero dei gap

Gli eventi non vengono riprodotti. In caso di gap di sequenza, aggiorna lo stato (health, system-presence) prima di continuare.

​
Firme di errore comuni

FirmaProblema probabile
refusing to bind gateway ... without authBind non-loopback senza un percorso di autenticazione del gateway valido
another gateway instance is already listening / EADDRINUSEConflitto di porta
Gateway start blocked: set gateway.mode=localConfigurazione impostata in modalità remota, oppure marcatore della modalità locale mancante da una configurazione danneggiata
unauthorized durante la connessioneMancata corrispondenza di autenticazione tra client e gateway
Per procedure diagnostiche complete, usa Risoluzione dei problemi del Gateway.

​
Garanzie di sicurezza

  • I client del protocollo Gateway falliscono rapidamente quando il Gateway non è disponibile (nessun fallback implicito al canale diretto).
  • I primi frame non validi/non di connessione vengono rifiutati e chiusi.
  • L’arresto graceful emette l’evento shutdown prima della chiusura del socket.
Correlati:

​
Correlati