Gateway runbook

Use this page for day-1 startup and day-2 operations of the Gateway service.

5-minute local startup

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

Runtime model

• One always-on process for routing, control plane, and channel connections.
• Single multiplexed port for:
  • WebSocket control/RPC
  • HTTP APIs (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Plugin HTTP routes, such as optional /api/v1/admin/rpc
  • Control UI and hooks
• Default bind mode: loopback.
• Auth is required by default. Shared-secret setups use gateway.auth.token / gateway.auth.password (or OmeniaClaw_GATEWAY_TOKEN / OmeniaClaw_GATEWAY_PASSWORD), and non-loopback reverse-proxy setups can use gateway.auth.mode: "trusted-proxy".

OpenAI-compatible endpoints

OmeniaClaw's highest-leverage compatibility surface is now:

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

Why this set matters:

• Most Open WebUI, LobeChat, and LibreChat integrations probe /v1/models first.
• Many RAG and memory pipelines expect /v1/embeddings.
• Agent-native clients increasingly prefer /v1/responses.

Planning note:

• /v1/models is agent-first: it returns OmeniaClaw, OmeniaClaw/default, and OmeniaClaw/<agentId>.
• OmeniaClaw/default is the stable alias that always maps to the configured default agent.
• Use x-OmeniaClaw-model when you want a backend provider/model override; otherwise the selected agent's normal model and embedding setup stays in control.

All of these run on the main Gateway port and use the same trusted operator auth boundary as the rest of the Gateway HTTP API.

Admin HTTP RPC (POST /api/v1/admin/rpc) is a separate, default-off plugin route for host tooling that cannot use WebSocket RPC. See Admin HTTP RPC.

Port and bind precedence

Installed gateway services record the resolved --port in supervisor metadata. After changing gateway.port, run OmeniaClaw doctor --fix or OmeniaClaw gateway install --force so launchd/systemd/schtasks starts the process on the new port.

Gateway startup uses the same effective port and bind when it seeds local Control UI origins for non-loopback binds. For example, --bind lan --port 3000 seeds http://localhost:3000 and http://127.0.0.1:3000 before runtime validation runs. Add any remote browser origins, such as HTTPS proxy URLs, to gateway.controlUi.allowedOrigins explicitly.

Hot reload modes

Operator command set

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 is for extra service discovery (LaunchDaemons/systemd system units/schtasks), not a deeper RPC health probe.

Multiple gateways (same host)

Most installs should run one gateway per machine. A single gateway can host multiple agents and channels.

You only need multiple gateways when you intentionally want isolation or a rescue bot.

Useful checks:

OmeniaClaw gateway status --deepOmeniaClaw gateway probe

What to expect:

• gateway status --deep can report Other gateway-like services detected (best effort) and print cleanup hints when stale launchd/systemd/schtasks installs are still around.
• gateway probe can warn about multiple reachable gateway identities when distinct gateways answer, or when OmeniaClaw cannot prove reachable targets are the same gateway. An SSH tunnel, proxy URL, or configured remote URL to the same gateway is one gateway with multiple transports, even when transport ports differ.
• If that is intentional, isolate ports, config/state, and workspace roots per gateway.

Checklist per instance:

• Unique gateway.port
• Unique OmeniaClaw_CONFIG_PATH
• Unique OmeniaClaw_STATE_DIR
• Unique agents.defaults.workspace

Example:

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

Detailed setup: /gateway/multiple-gateways.

Remote access

Preferred: Tailscale/VPN. Fallback: SSH tunnel.

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

Then connect clients locally to ws://127.0.0.1:18789.

See: Remote Gateway, Authentication, Tailscale.

Supervision and service lifecycle

Use supervised runs for production-like reliability.

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

Dev profile quick path

OmeniaClaw --dev setupOmeniaClaw --dev gateway --allow-unconfiguredOmeniaClaw --dev status

Defaults include isolated state/config and base gateway port 19001.

Protocol quick reference (operator view)

• First client frame must be connect.
• Gateway returns hello-ok snapshot (presence, health, stateVersion, uptimeMs, limits/policy).
• hello-ok.features.methods / events are a conservative discovery list, not a generated dump of every callable helper route.
• Requests: req(method, params) → res(ok/payload|error).
• Common events include connect.challenge, agent, chat, session.message, session.operation, session.tool, sessions.changed, presence, tick, health, heartbeat, pairing/approval lifecycle events, and shutdown.

Agent runs are two-stage:

1. Immediate accepted ack (status:"accepted")
2. Final completion response (status:"ok"|"error"), with streamed agent events in between.

See full protocol docs: Gateway Protocol.

Operational checks

Liveness

• Open WS and send connect.
• Expect hello-ok response with snapshot.

Readiness

OmeniaClaw gateway statusOmeniaClaw channels status --probeOmeniaClaw health

Gap recovery

Events are not replayed. On sequence gaps, refresh state (health, system-presence) before continuing.

Common failure signatures

For full diagnosis ladders, use Gateway Troubleshooting.

Safety guarantees

• Gateway protocol clients fail fast when Gateway is unavailable (no implicit direct-channel fallback).
• Invalid/non-connect first frames are rejected and closed.
• Graceful shutdown emits shutdown event before socket close.

Related:

• Troubleshooting
• Background Process
• Configuration
• Health
• Doctor
• Authentication

Related

• Configuration
• Gateway troubleshooting
• Remote access
• Secrets management