Gateway Runbook: Startup, Lifecycle, and Day-2 Operations

Use this page to handle both initial Gateway startup and ongoing day-2 operations.

• Deep troubleshooting, Diagnostics that start from symptoms, with exact command sequences and log fingerprints.

• Configuration, A task-driven setup guide plus the 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 aligns with your expectations. Use openclaw gateway status --require-rpc to verify read-scope RPC, not merely 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 cannot be reached, the CLI falls back to config-only channel summaries.

Note

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

Runtime model

• A single always-on process handles routing, control plane, and channel connections.
• One multiplexed port carries:
  • WebSocket control/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
• The default bind mode is loopback. In a detected container environment, the effective default becomes auto (resolving to 0.0.0.0 for port-forwarding), unless Tailscale serve/funnel is active, which always forces loopback.
• Authentication is on by default. Shared-secret setups rely on 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 most impactful 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 check /v1/models first.
• Many RAG and memory pipelines depend on /v1/embeddings.
• Agent-native clients increasingly favor /v1/responses.

/v1/models is agent-first: it provides openclaw, openclaw/default, and openclaw/<agentId> for every configured agent. openclaw/default is the stable alias that always points to the configured default agent. Send x-openclaw-model to request a backend provider or model override; otherwise the selected agent's standard model and embedding setup remains in charge.

These all run on the main Gateway port and share 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 plugin route, off by default, for host tooling that cannot use WebSocket RPC. See Admin HTTP RPC.

Port and bind precedence

Installed gateway services persist the resolved --port within supervisor metadata. Once you modify gateway.port, execute openclaw doctor --fix or openclaw gateway install --force so that launchd/systemd/schtasks launches the process on the updated port.

The effective port and bind used at gateway startup also apply when local Control UI origins are seeded for non-loopback binds. As an illustration, --bind lan --port 3000 seeds http://localhost:3000 and http://127.0.0.1:3000 ahead of runtime validation. Any remote browser origins, for instance HTTPS proxy URLs, need to be added to gateway.controlUi.allowedOrigins explicitly.

Hot reload modes

The older hot and restart modes are no longer supported; openclaw doctor --fix translates both into hybrid.

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 serves additional service discovery purposes (LaunchDaemons/systemd system units/schtasks), not as a more extensive RPC health check.

Multiple gateways (same host)

Typically, a single gateway per machine is sufficient. One gateway can accommodate multiple agents and channels. Additional gateways become necessary only when you deliberately seek isolation or a rescue bot.

Diagnostic steps:

openclaw gateway status --deep
openclaw gateway probe

Anticipated outcomes:

• gateway status --deep may return Other gateway-like services detected (best effort) and offer cleanup guidance when outdated launchd/systemd/schtasks installs persist.
• gateway probe can flag multiple reachable gateway identities when separate gateways respond, or when OpenClaw cannot confirm that reachable targets are identical. An SSH tunnel, proxy URL, or configured remote URL pointing to the same gateway counts as one gateway with multiple transports, even if transport ports differ.
• If this arrangement is deliberate, keep ports, config/state, and workspace roots separate per gateway.

Per-instance checklist:

• 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

Full instructions: /gateway/multiple-gateways.

Remote access

First choice: Tailscale/VPN. Alternative: SSH tunnel.

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

After that, 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

For production-like reliability, opt for supervised runs.

macOS (launchd)

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

Employ openclaw gateway restart for restarts. Avoid chaining openclaw gateway stop and openclaw gateway start as a substitute for restarting.

On macOS, gateway stop defaults to launchctl bootout. This unloads the LaunchAgent from the current boot session without persisting a disable, so KeepAlive auto-recovery remains functional after unexpected crashes, and gateway start re-enables it cleanly. To suppress auto-respawn persistently across reboots, supply --disable: openclaw gateway stop --disable.

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

Existing system LaunchDaemons

OpenClaw installs and manages a per-user LaunchAgent. It does not install or manage system LaunchDaemons. If a custom LaunchDaemon already occupies the same gateway label, OpenClaw refuses to write, start, restart, or repair a user LaunchAgent, because two KeepAlive managers can repeatedly restart the same gateway.

The ownership check reads launchctl print system/<label> and also inspects installed plists under /Library/LaunchDaemons. It fails closed when system ownership cannot be verified, and --force does not bypass it. openclaw gateway status reports a loaded same-label system job; add --deep to scan installed system service files.

Choose a single lifecycle owner before you retry:

• If you want to keep the custom system LaunchDaemon, delete any conflicting user LaunchAgent and pass OPENCLAW_SERVICE_REPAIR_POLICY=external to Doctor so it only performs diagnostics and never touches service lifecycle.
• To switch back to the supported user LaunchAgent, stop the system job using sudo launchctl bootout system/<label>, move or delete its actual plist, log into the macOS desktop as the intended user, and then execute openclaw gateway install.

For the default profile, <label> is set to ai.openclaw.gateway. Named profiles rely on ai.openclaw.<profile>.

Linux (systemd user)

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

To keep the service alive after logout, enable lingering:

sudo loginctl enable-linger $(whoami)

On a headless server with no desktop session, verify that XDG_RUNTIME_DIR is configured (export XDG_RUNTIME_DIR=/run/user/$(id -u)) before you retry any systemctl --user commands.

A manual user-unit example for 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 relies on a Scheduled Task named OpenClaw Gateway (or OpenClaw Gateway (<profile>) for named profiles). When Scheduled Task creation is blocked, OpenClaw falls back to a per-user Startup-folder launcher that targets gateway.cmd within the state directory.

Linux (system service)

For hosts that are multi-user or always on, use a system unit.

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

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

Do not allow openclaw doctor --fix to install a user-level gateway service for the same profile or port. When a system-level OpenClaw gateway service is detected, Doctor refuses that automatic install; use OPENCLAW_SERVICE_REPAIR_POLICY=external when the system unit manages the lifecycle.

Invalid configuration errors terminate with exit code 78. Linux systemd units rely on RestartPreventExitStatus=78 to avoid relaunching until the config is corrected. launchd and Windows Task Scheduler lack a per-exit-code stop rule, so the Gateway also tracks rapid unclean boot history and disables automatic channel/provider account startup after repeated boot failures. In that safe mode, the control plane still starts for inspection and repair, config hot reloads and secrets.reload block automatic channel restarts, and an explicit operator channels.start request can override the suppression. Step-by-step recovery is covered in Restart recovery.

Dev profile quick path

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

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

Protocol quick reference (operator view)

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

Agent runs proceed in two stages:

1. Quick acknowledgement (status:"accepted")
2. Final completion reply (status:"ok"|"error"), with agent events streamed in between.

Complete protocol details can be found here: Gateway Protocol.

Operational checks

Liveness

• Establish a WS connection and transmit connect.
• A snapshot should arrive in the hello-ok response.

Readiness

openclaw gateway status
openclaw channels status --probe
openclaw health

Gap recovery

Replays of events do not occur. If sequence numbers show gaps, call health and system-presence to refresh state prior to moving forward.

Common failure signatures

For step-by-step diagnosis, refer to Gateway Troubleshooting.

Safety guarantees

• Gateway protocol clients stop immediately when Gateway is down, with no silent fallback to a direct channel.
• Frames that are invalid or not connection-related get rejected and the connection closes.
• A clean shutdown triggers the shutdown event before the socket terminates.

Related

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