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

OmeniaClaw gateway --port 18789# debug/trace mirrored to stdioOmeniaClaw gateway --port 18789 --verbose# force-kill listener on selected port, then startOmeniaClaw gateway --force

OmeniaClaw gateway statusOmeniaClaw statusOmeniaClaw logs --follow

OmeniaClaw 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 OmeniaClaw_GATEWAY_TOKEN / OmeniaClaw_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 OmeniaClaw 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 OmeniaClaw, OmeniaClaw/default e OmeniaClaw/<agentId>.
• OmeniaClaw/default è l'alias stabile che punta sempre all'agente predefinito configurato.
• Usa x-OmeniaClaw-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 OmeniaClaw doctor --fix oppure OmeniaClaw 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

OmeniaClaw gateway statusOmeniaClaw gateway status --deep   # adds a system-level service scanOmeniaClaw gateway status --jsonOmeniaClaw gateway installOmeniaClaw gateway restartOmeniaClaw gateway stopOmeniaClaw secrets reloadOmeniaClaw logs --followOmeniaClaw 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:

OmeniaClaw gateway status --deepOmeniaClaw 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
• OmeniaClaw_CONFIG_PATH univoco
• OmeniaClaw_STATE_DIR univoco
• agents.defaults.workspace univoco

Esempio:

OmeniaClaw_CONFIG_PATH=~/.OmeniaClaw/a.json OmeniaClaw_STATE_DIR=~/.OmeniaClaw-a OmeniaClaw gateway --port 19001OmeniaClaw_CONFIG_PATH=~/.OmeniaClaw/b.json OmeniaClaw_STATE_DIR=~/.OmeniaClaw-b OmeniaClaw 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.

OmeniaClaw gateway installOmeniaClaw gateway statusOmeniaClaw gateway restartOmeniaClaw gateway stop

OmeniaClaw gateway installsystemctl --user enable --now OmeniaClaw-gateway[-<profile>].serviceOmeniaClaw gateway status

sudo loginctl enable-linger <user>

[Unit]Description=OmeniaClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/OmeniaClaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143KillMode=control-group [Install]WantedBy=default.target

OmeniaClaw gateway installOmeniaClaw gateway status --jsonOmeniaClaw gateway restartOmeniaClaw gateway stop

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

Percorso rapido del profilo di sviluppo

OmeniaClaw --dev setupOmeniaClaw --dev gateway --allow-unconfiguredOmeniaClaw --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

OmeniaClaw gateway statusOmeniaClaw channels status --probeOmeniaClaw 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