Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

Risoluzione approfondita dei problemi

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

Configurazione

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

Gestione dei segreti

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

Contratto del piano dei segreti

Regole esatte di destinazione/percorso di secrets apply e comportamento dei profili di autenticazione solo tramite riferimento.

​
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 lo stato del servizio

openclaw gateway status
openclaw status
openclaw logs --follow
Baseline sana: 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 prontezza del canale

openclaw channels status --probe
Con un gateway raggiungibile, questo esegue probe live dei canali per account e audit opzionali. Se il gateway non è raggiungibile, la CLI ripiega invece su riepiloghi dei canali basati solo sulla configurazione anziché sull’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 attivo della configurazione in memoria; un ricaricamento riuscito sostituisce quello snapshot in modo atomico.

​
Modello a runtime

  • Un processo sempre attivo per routing, piano di controllo e connessioni dei canali.
  • Un’unica porta multiplexata per:
    • Controllo/RPC WebSocket
    • API HTTP compatibili con OpenAI (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
    • UI di controllo e hook
  • Modalità di binding 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 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 interroga prima /v1/models.
  • Molte pipeline RAG e di memoria si aspettano /v1/embeddings.
  • I client agent-native preferiscono sempre più spesso /v1/responses.
Nota di pianificazione:
  • /v1/models è agent-first: restituisce openclaw, openclaw/default e openclaw/<agentId>.
  • openclaw/default è l’alias stabile che punta sempre all’agente predefinito configurato.
  • Usa x-openclaw-model quando vuoi sovrascrivere provider/modello del backend; altrimenti la normale configurazione di modello ed embedding dell’agente selezionato resta in controllo.
Tutti questi endpoint vengono eseguiti sulla porta principale del Gateway e usano lo stesso confine di autenticazione dell’operatore fidato del resto dell’API HTTP del Gateway.

​
Precedenza di porta e binding

ImpostazioneOrdine di risoluzione
Porta Gateway--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Modalità di bindingCLI/override → gateway.bind → loopback
I servizi gateway installati registrano il --port risolto nei metadati del supervisore. Dopo aver modificato gateway.port, esegui openclaw doctor --fix oppure openclaw gateway install --force in modo che launchd/systemd/schtasks avvii il processo sulla nuova porta. L’avvio del Gateway usa la stessa porta e lo stesso binding effettivi quando inizializza le origini locali della UI di controllo per binding non loopback. Ad esempio, --bind lan --port 3000 inizializza http://localhost:3000 e http://127.0.0.1:3000 prima che venga eseguita la convalida a runtime. Aggiungi esplicitamente qualsiasi origine di browser remoto, come URL proxy HTTPS, a gateway.controlUi.allowedOrigins.

​
Modalità di hot reload

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

​
Set di comandi dell’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 ulteriore individuazione dei servizi (LaunchDaemons/unità systemd di sistema /schtasks), non per un probe di salute RPC più approfondito.

​
Gateway multipli (stesso host)

La maggior parte delle installazioni dovrebbe eseguire un gateway per macchina. Un singolo gateway può ospitare più agenti e canali. Servono più gateway solo quando vuoi intenzionalmente isolamento o un bot di ripristino. 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 gateways quando risponde più di un target.
  • Se è intenzionale, isola porte, configurazione/stato e radici workspace per ogni 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. Fallback: 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à con 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 un’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 recupero automatico KeepAlive continua a funzionare dopo arresti inattesi e gateway start riabilita in modo pulito. Per sopprimere in modo persistente il riavvio automatico tra i reboot, passa --disable: openclaw gateway stop --disable.Le etichette LaunchAgent sono ai.openclaw.gateway (predefinito) oppure ai.openclaw.<profile> (profilo con nome). openclaw doctor verifica e ripara la deriva della configurazione del servizio.

​
Percorso rapido del profilo di sviluppo

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
I valori predefiniti includono stato/configurazione isolati e porta gateway di 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 discovery conservativo, non un dump generato di ogni rotta helper chiamabile.
  • Richieste: req(method, params) → res(ok/payload|error).
  • Gli eventi comuni includono connect.challenge, agent, chat, session.message, session.tool, sessions.changed, presence, tick, health, heartbeat, eventi del ciclo di vita di pairing/approvazione e shutdown.
Le esecuzioni degli agenti sono in due fasi:
  1. Ack di accettazione 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

​
Liveness

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

​
Readiness

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 authAssociazione non-loopback senza un percorso di autenticazione Gateway valido
another gateway instance is already listening / EADDRINUSEConflitto di porta
Gateway start blocked: set gateway.mode=localConfigurazione impostata in modalità remota, oppure il contrassegno della modalità locale manca da una configurazione danneggiata
unauthorized durante la connessioneMancata corrispondenza di autenticazione tra client e Gateway
Per le scalette diagnostiche complete, usa Risoluzione dei problemi del Gateway.

​
Garanzie di sicurezza

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

​
Correlati