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

Deep troubleshooting

Symptom-first diagnostics with exact command ladders and log signatures.

Configuration

Task-oriented setup guide + full configuration reference.

Secrets management

SecretRef contract, runtime snapshot behavior, and migrate/reload operations.

Secrets plan contract

Exact secrets apply target/path rules and ref-only auth-profile behavior.

​
5-minute local startup

1

Start the Gateway

2

Verify service health

Healthy baseline: Runtime: running, Connectivity probe: ok, and a Capability line that matches what you expect. Use openclaw gateway status --require-rpc for read-scope RPC proof, not just reachability.
3

Validate channel readiness

With a reachable gateway this runs live per-account channel probes and optional audits. If the gateway is unreachable, the CLI falls back to config-only channel summaries.
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". After the first successful load, the running process serves the active in-memory config snapshot; a successful reload swaps that snapshot atomically.

​
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. Inside a detected container environment the effective default is auto (resolves to 0.0.0.0 for port-forwarding), unless Tailscale serve/funnel is active, which always forces loopback.
  • Auth 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/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

SettingResolution order
Gateway port--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Bind modeCLI/override → gateway.bind → loopback (or auto in containers)
Installed gateway services record the resolved --port in supervisor metadata. After changing gateway.port, run openclaw doctor --fix or openclaw 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

gateway.reload.modeBehavior
offNo config reload
hotApply only hot-safe changes
restartRestart on reload-required changes
hybrid (default)Hot-apply when safe, restart when required

​
Operator command set

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:
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 OpenClaw 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 OPENCLAW_CONFIG_PATH
  • Unique OPENCLAW_STATE_DIR
  • Unique agents.defaults.workspace
Example:
Detailed setup: /gateway/multiple-gateways.

​
Remote access

Preferred: Tailscale/VPN. Fallback: SSH tunnel.
Then connect clients locally to ws://127.0.0.1:18789.
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.
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.
Invalid configuration errors exit with code 78. Linux systemd units use RestartPreventExitStatus=78 to stop relaunching until the config is fixed. launchd and Windows Task Scheduler do not have an equivalent per-exit-code stop rule, so the Gateway also persists rapid unclean boot history and suppresses channel/provider account auto-start after repeated startup failures. In that safe mode the control plane still starts for inspection and repair, config hot reloads and secrets.reload refuse automatic channel restarts, and an explicit operator channels.start request can override the suppression.

​
Dev profile quick path

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

​
Protocol quick reference (operator view)

  • First client frame must be connect.
  • Gateway returns a hello-ok frame with a snapshot (presence, health, stateVersion, uptimeMs) plus policy limits (maxPayload, maxBufferedBytes, tickIntervalMs).
  • 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, opt-in session.approval, 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

​
Gap recovery

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

​
Common failure signatures

SignatureLikely issue
refusing to bind gateway ... without authNon-loopback bind without a valid gateway auth path
another gateway instance is already listening / EADDRINUSEPort conflict
Gateway start blocked: set gateway.mode=localConfig set to remote mode, or gateway.mode is missing from a damaged config
unauthorized during connectAuth 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.