QWE AI Academy Here’s something most OpenClaw tutorials skip: the Gateway will refuse to start the first time you run it. Not because of a bug – by design. Per the official CLI docs, the Gateway refuses to start unless gateway.mode=local is set in ~/.openclaw/openclaw.json. New users see an error, assume installation failed, and bounce. It didn’t fail. You just haven’t told it what kind of life it should live.
This guide treats the OpenClaw Gateway as what it actually is: a small, opinionated control plane with strong defaults. We’ll cover the architecture in one section, then move straight to the failure modes a beginner hits in the first hour, the OpenAI-compatible API surface (the part most guides gloss over), and an honest comparison with a few alternatives.
What the OpenClaw Gateway actually is
Strip away the marketing and the Gateway is a single long-lived process. One always-on process for routing, control plane, and channel connections – that’s the whole job description (per the runbook). It speaks WebSocket on port 18789 by default and also exposes an HTTP surface that mimics the OpenAI API.
The key mental model: the Gateway is not the assistant. Channels – Telegram, Slack, iMessage, WebChat, and others – connect into it. Nodes (your laptop, phone, a Raspberry Pi) pair into it. Agents run on top. The Gateway is the switchboard, not the intelligence.
Here’s something worth sitting with: most installs should run one gateway per machine, and a single gateway can host multiple agents and channels. That raises a real question – if one gateway handles everything, what does it mean for your setup when it goes down? There’s no implicit direct-channel fallback. Your agents go quiet. That design choice makes the Gateway’s reliability load-bearing in a way that a stateless proxy isn’t. Worth thinking through before you build anything on top of it.
The first-hour failure modes
Forget the happy path for a second. Here’s what actually trips up beginners.
1. The “refuses to start” wall. Already mentioned above. Fix: open ~/.openclaw/openclaw.json, set gateway.mode to "local", save, retry. For one-off experiments, the docs offer --allow-unconfigured for ad-hoc/dev runs – it bypasses the guardrail without touching config.
2. The silent bind block. You change bind from loopback to lan hoping to reach the Gateway from your phone. Nothing happens – no error, just silence. That’s the safety net: binding beyond loopback without auth is blocked as a guardrail. Either keep loopback and use an SSH tunnel, or set gateway.auth.token before changing the bind. The order matters.
3. The –url credential trap. This one is mean. You set a token in your config, then run openclaw gateway status --url ws://remote-host:18789. It fails with an auth error. Why? When you pass --url, the CLI does not fall back to config or environment credentials – according to the remote-access docs, missing explicit --token or --password is treated as an error, not a fallback. The fix is one flag. The error message doesn’t always say that clearly.
4. The phantom gateway. If you upgraded from an older version or experimented with manual installs, gateway status --deep can report “Other gateway-like services detected” and print cleanup hints when stale launchd/systemd/schtasks installs are still around. Two processes fighting for port 18789 produces fantastically confusing logs.
The OpenAI-compatible surface (and why this matters)
Most articles describe the Gateway only through its WebSocket protocol. They miss the bigger story. The Gateway also serves HTTP APIs compatible with the OpenAI format – specifically /v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, and /tools/invoke. That’s the compatibility surface that lets third-party frontends talk to your local agents without custom integration code.
The gotcha nobody writes about: most Open WebUI, LobeChat, and LibreChat integrations probe /v1/models first. If that single endpoint isn’t reachable or returns an unexpected shape, the client decides your Gateway is dead – before any chat request is even attempted. So when LibreChat shows “no models found,” curl the endpoint yourself:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN"
http://127.0.0.1:18789/v1/modelsIf that returns a model list, your problem is in the client config. If it doesn’t respond or returns an error, your problem is auth, port, or bind mode – in that order of likelihood.
Minimal setup walkthrough
Shortest path from zero to a working Gateway, assuming you already have the CLI installed.
- Check your Node version. As of early 2026, the runtime requirement is Node 24 (recommended) or Node 22.16+ per the GitHub README. Older versions will install but break in subtle ways.
- Run
openclaw onboard. This installs the Gateway daemon as a launchd/systemd user service so it stays running – and it writes the config file that resolves the “refuses to start” issue from step zero. - Verify with
openclaw gateway status. You want to see a running status and a clean connectivity probe. If the probe fails, check bind mode and auth before anything else. - If you plan to expose it beyond your laptop, set a token:
export OPENCLAW_GATEWAY_TOKEN="$(openssl rand -hex 32)". Shared-secret setups usegateway.auth.token/gateway.auth.passwordin config, or the env varsOPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORD. - For remote access, keep loopback and tunnel:
ssh -N -L 18789:127.0.0.1:18789 user@host. This is the recommended pattern instead of opening the port directly – it avoids the bind-without-auth guardrail entirely.
Five steps. The temptation to over-configure on day one is strong – resist it.
How it compares to the alternatives
The honest pitch for the Gateway is local-first agents with channel breadth. Here’s a rough comparison with tools people actually consider (note: competitor defaults may change – verify against their current docs).
| Property | OpenClaw Gateway | LiteLLM Proxy | Cloud agent platforms |
|---|---|---|---|
| Default network exposure | Loopback only | All interfaces by default (verify) | Public SaaS |
| OpenAI-compat HTTP | Yes (multi-endpoint) | Yes (primary feature) | Usually proprietary |
| Channel integrations | Built-in (Telegram, Slack, iMessage, etc.) | None – LLM routing only | Varies |
| Runs on your machine | Yes, always | Yes | No |
| Setup friction (first run) | Medium (mode guardrail) | Low | Low |
Pure LLM routing? LiteLLM is simpler and purpose-built for that. OpenClaw’s Gateway is doing something different: it wants to be the single point where your personal assistant listens across every app you already use, on hardware you own. They share an OpenAI-compat surface, but the goals don’t really overlap.
One thing the docs don’t fully spell out
Events are not durable. Per the runbook, events are not replayed – on sequence gaps, you should refresh state (health, system-presence) before continuing. Combined with the fact that Gateway protocol clients fail fast when the Gateway is unavailable (no implicit direct-channel fallback), this means a flaky network between client and Gateway can leave your agent’s view of the world quietly stale. Your CLI thinks it’s connected, the WebSocket survived, but you missed three events in between. Always refresh state after any reconnect – the docs say it once and move on, but it’s the kind of thing that costs you an afternoon when you skip it.
FAQ
Can I run multiple Gateways on the same machine?
Yes, but you’ll need separate ports, config paths, and state directories for each instance. Most setups shouldn’t bother.
Does the Gateway store my chat history in the cloud?
A common assumption – and it’s wrong. The Gateway is a local process; sessions, channels, and routing live entirely on your machine. The nuance: if you’ve configured an external model provider like OpenAI or Anthropic, the prompts you send to that provider still leave your network to reach their servers. That’s unavoidable for any non-local LLM, and it has nothing to do with the Gateway itself. The Gateway doesn’t ship anything to a third-party backend on its own initiative.
What’s the actual difference between a Channel and a Node?
Channel = inbox. Telegram, Slack, WebChat – where messages arrive from users. Node = a device or process paired into the Gateway (your phone, a second laptop) that can run tools or surface UI. Same underlying WebSocket connection, completely different role. The Gateway routes between them.
Next step: Run openclaw gateway status --deep right now. If you’ve never installed OpenClaw, it’ll tell you. If you have, it’ll surface any phantom processes from previous attempts – and that’s the single most useful command to know before you build anything on top of the Gateway.