Manuale operativo del Gateway

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

Avvio locale in 5 minuti

openclaw gateway --port 18789# debug/trace mirrored to stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

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

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

Set di comandi dell'operatore

openclaw gateway statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw 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 --deepopenclaw 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 19001OPENCLAW_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.

Vedi: Gateway remoto, Autenticazione, Tailscale.

Supervisione e ciclo di vita del servizio

Usa esecuzioni supervisionate per un'affidabilità simile alla produzione.

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 <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143KillMode=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

Percorso rapido del profilo di sviluppo

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --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 statusopenclaw channels status --probeopenclaw 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

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:

• Risoluzione dei problemi
• Processo in background
• Configurazione
• Stato
• Doctor
• Autenticazione

Correlati

• Configurazione
• Risoluzione dei problemi del Gateway
• Accesso remoto
• Gestione dei segreti