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

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

Set di comandi 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 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 --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 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 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. 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.

Vedi: Gateway remoto, Autenticazione, Tailscale.

Supervisione e ciclo di vita del servizio

Usa esecuzioni supervisionate per 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 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

Percorso rapido per profilo dev

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --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 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 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:

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

Correlati

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