openclaw/docs/gateway/index.md

summary, read_when, title

summary	read_when	title
Runbook for the Gateway service, lifecycle, and operations	Running or debugging the gateway process	Gateway Runbook

Gateway runbook

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

Symptom-first diagnostics with exact command ladders and log signatures. Task-oriented setup guide + full configuration reference. SecretRef contract, runtime snapshot behavior, and migrate/reload operations. Exact `secrets apply` target/path rules and ref-only auth-profile behavior.

5-minute local startup

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

Healthy baseline: Runtime: running and RPC probe: ok.

openclaw channels status --probe

Gateway config reload watches the active config file path (resolved from profile/state defaults, or `OPENCLAW_CONFIG_PATH` when set). Default mode is `gateway.reload.mode="hybrid"`.

Runtime model

• One always-on process for routing, control plane, and channel connections.
• Single multiplexed port for:
  • WebSocket control/RPC
  • HTTP APIs, OpenAI compatible (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Control UI and hooks
• Default bind mode: loopback.
• Auth is required by default (gateway.auth.token / gateway.auth.password, or OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).

OpenAI-compatible endpoints

OpenClaw’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 openclaw, openclaw/default, and openclaw/<agentId>.
• openclaw/default is the stable alias that always maps to the configured default agent.
• Use x-openclaw-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.

Port and bind precedence

Setting	Resolution order
Gateway port	--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Bind mode	CLI/override → gateway.bind → loopback

Hot reload modes

gateway.reload.mode	Behavior
off	No config reload
hot	Apply only hot-safe changes
restart	Restart on reload-required changes
hybrid (default)	Hot-apply when safe, restart when required

Operator command set

openclaw gateway status
openclaw gateway status --deep
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

Remote access

Preferred: Tailscale/VPN. Fallback: SSH tunnel.

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

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

If gateway auth is configured, clients still must send auth (`token`/`password`) even over SSH tunnels.

See: Remote Gateway, Authentication, Tailscale.

Supervision and service lifecycle

Use supervised runs for production-like reliability.

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

LaunchAgent labels are ai.openclaw.gateway (default) or ai.openclaw.<profile> (named profile). openclaw doctor audits and repairs service config drift.

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

For persistence after logout, enable lingering:

sudo loginctl enable-linger <user>

Use a system unit for multi-user/always-on hosts.

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

Multiple gateways on one host

Most setups should run one Gateway. Use multiple only for strict isolation/redundancy (for example a rescue profile).

Checklist per instance:

• Unique gateway.port
• Unique OPENCLAW_CONFIG_PATH
• Unique OPENCLAW_STATE_DIR
• Unique agents.defaults.workspace

Example:

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

See: Multiple gateways.

Dev profile quick path

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --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).
• Requests: req(method, params) → res(ok/payload|error).
• Common events: connect.challenge, agent, chat, presence, tick, health, heartbeat, 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

openclaw gateway status
openclaw channels status --probe
openclaw health

Gap recovery

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

Common failure signatures

Signature	Likely issue
refusing to bind gateway ... without auth	Non-loopback bind without token/password
another gateway instance is already listening / EADDRINUSE	Port conflict
Gateway start blocked: set gateway.mode=local	Config set to remote mode
unauthorized during connect	Auth mismatch between client and gateway

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