Gateway Runbook: Lifecycle, Operations, and Troubleshooting

Refer to this page for both initial Gateway service startup and ongoing operational tasks.

• Deep troubleshooting, Diagnostics that start from the symptom, with exact command sequences and log identifiers.
• Configuration, A task-driven setup guide and a complete configuration reference.
• Secrets management, The SecretRef contract, how runtime snapshots behave, and migrate/reload procedures.
• Secrets plan contract, Precise secrets apply target and path rules, plus ref-only auth-profile behavior.

5-minute local startup

Start the Gateway

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

Verify service health

openclaw gateway status
openclaw status
openclaw logs --follow

A healthy baseline consists of Runtime: running, Connectivity probe: ok, and a Capability line that matches your expectations. Use openclaw gateway status --require-rpc for read-scope RPC verification, not just connectivity.

Validate channel readiness

openclaw channels status --probe

When the gateway is reachable, this runs live per-account channel probes and optional audits. If the gateway is unreachable, the CLI falls back to config-only channel summaries.

Note

The gateway config reload watches the path of the active config file, resolved from profile or state defaults, or from OPENCLAW_CONFIG_PATH if that is set. The default mode is gateway.reload.mode="hybrid". After the first successful load, the running process uses the active in-memory config snapshot; a successful reload replaces that snapshot atomically.

Runtime model

• A single always-on process for routing, control plane, and channel connections.
• One multiplexed port for:
  • WebSocket control and RPC
  • HTTP APIs (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Plugin HTTP routes, for example the optional /api/v1/admin/rpc
  • Control UI and hooks
• Default bind mode: loopback. Inside a detected container environment the effective default is auto (resolves to 0.0.0.0 for port forwarding), unless Tailscale serve or funnel is active, which always forces loopback.
• Authentication is required by default. Shared-secret setups use gateway.auth.token / gateway.auth.password (or OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), and non-loopback reverse-proxy setups can use gateway.auth.mode: "trusted-proxy".

OpenAI-compatible endpoints

OpenClaw's highest-leverage compatibility surface:

• 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.

/v1/models is agent-first: it returns openclaw, openclaw/default, and openclaw/<agentId> for every configured agent. openclaw/default is the stable alias that always maps to the configured default agent. Send x-openclaw-model when you want a backend provider or 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, execute openclaw doctor --fix or openclaw gateway install --force so that launchd/systemd/schtasks launches the process on the updated port.

When seeding local Control UI origins for non-loopback binds, gateway startup uses the same effective port and bind. For instance, --bind lan --port 3000 seeds http://localhost:3000 and http://127.0.0.1:3000 before runtime validation runs. Explicitly add any remote browser origins, like HTTPS proxy URLs, to gateway.controlUi.allowedOrigins.

Hot reload modes

Operator command set

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

Multiple gateways (same host)

Most setups should run one gateway per machine. A single gateway can host multiple agents and channels. Multiple gateways are only needed when you deliberately want isolation or a rescue bot.

Useful checks:

openclaw gateway status --deep
openclaw 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 present.
• gateway probe can warn about multiple reachable gateway identities when different gateways respond, or when OpenClaw cannot confirm that 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 if transport ports differ.
• If this is intentional, isolate ports, config/state, and workspace roots per gateway.

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

Detailed setup: /gateway/multiple-gateways.

Remote access

Preferred: Tailscale/VPN. Fallback: SSH tunnel.

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

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

Warning

SSH tunnels do not bypass gateway auth. For shared-secret auth, clients still must send token/password even over the tunnel. For identity-bearing modes, the request still has to satisfy that auth path.

See: Remote Gateway, Authentication, Tailscale.

Supervision and service lifecycle

Use supervised runs for production-like reliability.

macOS (launchd)

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

Use openclaw gateway restart for restarts. Do not chain openclaw gateway stop and openclaw gateway start as a restart substitute.

On macOS, gateway stop uses launchctl bootout by default. This removes the LaunchAgent from the current boot session without persisting a disable, so KeepAlive auto-recovery still works after unexpected crashes and gateway start re-enables cleanly. To persistently suppress auto-respawn across reboots, pass --disable: openclaw gateway stop --disable.

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

Linux (systemd user)

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

For persistence after logout, enable lingering:

sudo loginctl enable-linger $(whoami)

On a headless server without a desktop session, also make sure XDG_RUNTIME_DIR is set (export XDG_RUNTIME_DIR=/run/user/$(id -u)) before retrying systemctl --user commands.

Manual user-unit example when you need a custom install path:

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target
StartLimitBurst=5
StartLimitIntervalSec=60

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

[Install]
WantedBy=default.target

Windows (native)

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

Native Windows managed startup uses a Scheduled Task named OpenClaw Gateway (or OpenClaw Gateway (<profile>) for named profiles). If Scheduled Task creation is denied, OpenClaw falls back to a per-user Startup-folder launcher that points at gateway.cmd inside the state directory.

Linux (system service)

For hosts that run continuously or serve multiple users, employ a system unit.

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

Reuse the service body from the user unit, but place it under /etc/systemd/system/openclaw-gateway[-<profile>].service and modify ExecStart= if your openclaw executable is located elsewhere.

Prevent openclaw doctor --fix from also deploying a user-level gateway service for the same profile or port. Doctor declines that automatic installation when it detects a system-level OpenClaw gateway service; use OPENCLAW_SERVICE_REPAIR_POLICY=external when the system unit manages the lifecycle.

Configurations that are invalid produce exit code 78 on failure. Linux systemd units rely on RestartPreventExitStatus=78 to avoid restarting until the configuration is corrected. Neither launchd nor Windows Task Scheduler offers a per-exit-code stop rule, so the Gateway also logs rapid unclean boot history and blocks automatic channel/provider account startup after repeated boot failures. In that safe mode the control plane still starts for inspection and repair, configuration hot reloads and secrets.reload refuse automatic channel restarts, and an explicit operator channels.start request can override the block.

Dev profile quick path

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

Defaults include isolated state and configuration along with base gateway port 19001.

Protocol quick reference (operator view)

• The first client frame must be connect.
• The Gateway responds with a hello-ok frame containing a snapshot (presence, health, stateVersion, uptimeMs) plus policy limits (maxPayload, maxBufferedBytes, tickIntervalMs).
• hello-ok.features.methods / events form a conservative discovery list, not an auto-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, opt-in session.approval, sessions.changed, presence, tick, health, heartbeat, pairing/approval lifecycle events, and shutdown.

Agent runs proceed in two stages:

1. Immediate accepted acknowledgement (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 a WebSocket and send connect.
• Expect a hello-ok response with a snapshot.

Readiness

openclaw gateway status
openclaw channels status --probe
openclaw health

Gap recovery

Events are not replayed. When sequence gaps occur, refresh state (health, system-presence) before proceeding.

Common failure signatures

Complete diagnostic procedures are available in the Gateway Troubleshooting guide.

Safety guarantees

• Protocol clients for the Gateway will terminate immediately when the Gateway is unreachable (no automatic fallback to a direct channel exists).
• Any first frame that is invalid or not a connect frame is rejected and the connection is closed.
• A clean shutdown sends the shutdown event before the socket is closed.

Related

• Configuration
• Gateway troubleshooting
• Background process
• Health
• Doctor
• Authentication
• Remote access
• Secrets management