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 stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force

openclaw gateway status
openclaw status
openclaw logs --follow

openclaw channels status --probe

# Modello runtime

• Un processo sempre attivo per routing, piano di controllo e connessioni ai canali.
• Porta singola multiplexed per:
  • Controllo/RPC WebSocket
  • API HTTP, compatibili con OpenAI (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • 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 reverse proxy non-loopback possono usare gateway.auth.mode: "trusted-proxy".

# Endpoint compatibili con OpenAI

La superficie di compatibilità a maggior valore di OpenClaw ora è:

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/chat/completions
• POST /v1/responses

Perché questo set è importante:

• La maggior parte delle integrazioni Open WebUI, LobeChat e LibreChat verifica 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 è progettato prima di tutto per gli agenti: 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 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 confine di autenticazione dell'operatore fidato del resto dell'API HTTP del Gateway.

# Precedenza di porta e bind

I servizi gateway installati registrano il valore risolto di --port nei metadati del supervisor. 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 effettiva e lo stesso bind quando inizializza le origini locali della Control UI per i 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 runtime. Aggiungi esplicitamente eventuali origini di browser remoti, come URL di proxy HTTPS, a gateway.controlUi.allowedOrigins.

# Modalità di hot reload

# Set di comandi per operatori

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 il rilevamento aggiuntivo dei servizi (LaunchDaemons/unità di sistema systemd/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.

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ò riportare 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 una destinazione.
• Se è intenzionale, isola porte, configurazione/stato e radici del workspace per ciascun 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

Quindi 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 install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

sudo loginctl enable-linger <user>

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop

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

# Percorso rapido del 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 discovery conservativo, non un dump generato di ogni route 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 dell'agente sono in 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

# Liveness

• Apri WS e invia connect.
• Aspettati 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

Per le sequenze 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
• Integrità
• Diagnostica
• Autenticazione

# Correlati

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