Runbook del Gateway

Usare questa pagina per l'avvio iniziale e le operazioni successive del servizio Gateway.

Avvio locale in 5 minuti

openclaw gateway --port 18789# debug/trace replicati su stdioopenclaw gateway --port 18789 --verbose# terminare forzatamente il listener sulla porta selezionata, quindi avviareopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

Modello di runtime

• Un unico processo sempre attivo per instradamento, piano di controllo e connessioni ai canali.
• Un'unica porta multiplex per:
  • Controllo/RPC WebSocket
  • API HTTP (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Route HTTP dei Plugin, come l'opzione /api/v1/admin/rpc
  • Control UI e hook
• Modalità di associazione predefinita: loopback. All'interno di un ambiente container rilevato, il valore predefinito effettivo è auto (risolto in 0.0.0.0 per l'inoltro delle porte), a meno che Tailscale serve/funnel non sia attivo, nel qual caso viene sempre imposto loopback.
• L'autenticazione è obbligatoria per impostazione predefinita. Le configurazioni con segreto condiviso usano gateway.auth.token / gateway.auth.password (oppure OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), mentre le configurazioni con proxy inverso non loopback possono usare gateway.auth.mode: "trusted-proxy".

Endpoint compatibili con OpenAI

La superficie di compatibilità a maggior impatto di OpenClaw:

• 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 verifica prima /v1/models.
• Molte pipeline RAG e di memoria richiedono /v1/embeddings.
• I client progettati nativamente per gli agenti preferiscono sempre più spesso /v1/responses.

/v1/models è progettato innanzitutto per gli agenti: restituisce openclaw, openclaw/default e openclaw/<agentId> per ogni agente configurato. openclaw/default è l'alias stabile associato sempre all'agente predefinito configurato. Inviare x-openclaw-model per sostituire provider/modello del backend; in caso contrario, restano attive le normali impostazioni del modello e degli embedding dell'agente selezionato.

Tutti questi endpoint vengono eseguiti sulla porta principale del Gateway e usano lo stesso confine di autenticazione attendibile dell'operatore del resto dell'API HTTP del Gateway.

L'RPC HTTP amministrativo (POST /api/v1/admin/rpc) è una route Plugin distinta, disattivata per impostazione predefinita, destinata agli strumenti host che non possono usare l'RPC WebSocket. Consultare RPC HTTP amministrativo.

Precedenza di porta e associazione

I servizi Gateway installati registrano il valore --port risolto nei metadati del supervisore. Dopo aver modificato gateway.port, eseguire openclaw doctor --fix o openclaw gateway install --force affinché launchd/systemd/schtasks avvii il processo sulla nuova porta.

All'avvio, il Gateway usa la stessa porta e associazione effettive quando inizializza le origini locali della Control UI per le associazioni non loopback. Ad esempio, --bind lan --port 3000 inizializza http://localhost:3000 e http://127.0.0.1:3000 prima dell'esecuzione della convalida di runtime. Aggiungere esplicitamente a gateway.controlUi.allowedOrigins tutte le origini dei browser remoti, ad esempio gli URL dei proxy HTTPS.

Modalità di ricaricamento a caldo

Insieme di comandi per l'operatore

openclaw gateway statusopenclaw gateway status --deep   # aggiunge una scansione dei servizi a livello di sistemaopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep serve per il rilevamento aggiuntivo dei servizi (LaunchDaemon/unità di sistema systemd/schtasks), non per una verifica più approfondita dello stato RPC.

Più Gateway sullo stesso host

Nella maggior parte delle installazioni è opportuno eseguire un solo Gateway per macchina. Un singolo Gateway può ospitare più agenti e canali. Sono necessari più Gateway solo quando si desidera intenzionalmente l'isolamento o un bot di emergenza.

Controlli utili:

openclaw gateway status --deepopenclaw gateway probe

Cosa aspettarsi:

• gateway status --deep può segnalare Other gateway-like services detected (best effort) e mostrare suggerimenti per la pulizia quando sono ancora presenti installazioni launchd/systemd/schtasks obsolete.
• gateway probe può avvisare della presenza di multiple reachable gateway identities quando rispondono Gateway distinti o quando OpenClaw non può dimostrare che le destinazioni raggiungibili corrispondano allo stesso Gateway. Un tunnel SSH, un URL proxy o un URL remoto configurato verso lo stesso Gateway rappresenta un unico Gateway con più trasporti, anche quando le porte di trasporto sono diverse.
• Se è intenzionale, isolare porte, configurazione/stato e directory radice degli spazi di lavoro per ciascun Gateway.

Lista di controllo per ogni 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 19001OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

Configurazione dettagliata: /gateway/multiple-gateways.

Accesso remoto

Opzione preferita: Tailscale/VPN. Alternativa: tunnel SSH.

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

Collegare quindi i client localmente a ws://127.0.0.1:18789.

Consultare: Gateway remoto, Autenticazione, Tailscale.

Supervisione e ciclo di vita del servizio

Per un'affidabilità adatta ad ambienti simili alla produzione, usare esecuzioni supervisionate.

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger $(whoami)

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

sudo systemctl daemon-reloadsudo systemctl enable --now openclaw-gateway[-<profile>].service

Gli errori di configurazione non valida terminano con il codice 78. Le unità systemd Linux usano RestartPreventExitStatus=78 per interrompere i riavvii finché la configurazione non viene corretta. launchd e l'Utilità di pianificazione di Windows non dispongono di una regola equivalente per interrompersi in base al codice di uscita; pertanto il Gateway conserva anche la cronologia degli avvii rapidi terminati in modo anomalo e impedisce l'avvio automatico degli account di canali/provider dopo ripetuti errori di avvio. In questa modalità sicura, il piano di controllo continua ad avviarsi per consentire ispezione e riparazione, i ricaricamenti a caldo della configurazione e secrets.reload rifiutano i riavvii automatici dei canali, mentre una richiesta esplicita dell'operatore channels.start può ignorare il blocco.

Percorso rapido per il profilo di sviluppo

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

I valori predefiniti includono stato/configurazione isolati e la porta Gateway di base 19001.

Riferimento rapido del protocollo (prospettiva dell'operatore)

• Il primo frame del client deve essere connect.
• Il Gateway restituisce un frame hello-ok con un snapshot (presence, health, stateVersion, uptimeMs) più i limiti policy (maxPayload, maxBufferedBytes, tickIntervalMs).
• hello-ok.features.methods / events sono un elenco di rilevamento prudenziale, 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, gli eventi facoltativi session.approval, sessions.changed, presence, tick, health, heartbeat, gli eventi del ciclo di vita di associazione/approvazione e shutdown.

Le esecuzioni dell'agente avvengono in due fasi:

1. Conferma immediata di accettazione (status:"accepted")
2. Risposta finale di completamento (status:"ok"|"error"), con eventi agent trasmessi in streaming nel frattempo.

Consultare la documentazione completa del protocollo: Protocollo del Gateway.

Controlli operativi

Operatività

• Aprire WS e inviare connect.
• Attendere una risposta hello-ok con snapshot.

Disponibilità

openclaw gateway statusopenclaw channels status --probeopenclaw health

Recupero delle lacune

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

Segnali di errore comuni

Per le procedure diagnostiche complete, consultare Risoluzione dei problemi del Gateway.

Garanzie di sicurezza

• I client del protocollo Gateway terminano immediatamente con errore quando il Gateway non è disponibile (nessun fallback implicito al canale diretto).
• I primi frame non validi o diversi da quelli di connessione vengono rifiutati e chiusi.
• L'arresto controllato emette l'evento shutdown prima della chiusura del socket.

Argomenti correlati

• Configurazione
• Risoluzione dei problemi del Gateway
• Processo in background
• Stato di integrità
• Doctor
• Autenticazione
• Accesso remoto
• Gestione dei segreti