OpenClaw Gateway Explained:
What It Does & How to Keep It Running

If you've ever opened OpenClaw and gotten no response, seen a "gateway unreachable" error, or wondered why your Telegram bot stopped working after a reboot — the gateway is almost always involved.

But most documentation assumes you already know what the gateway is. This guide doesn't. Start here.

What Is the Gateway?

The OpenClaw gateway is a local background service — a small web server that runs on your machine and acts as the central hub for everything OpenClaw does.

Think of it this way:

Every message you send, every tool your agent runs, every channel it listens on — all of it flows through the gateway. When the gateway is down, nothing works. When it's misconfigured, things work inconsistently. When it's running clean, it's invisible.

What the Gateway Actually Does

• Routes inbound messages from Telegram, WhatsApp, Discord, iMessage, etc. to your agents
• Handles authentication — verifies who's allowed to talk to your agents and how
• Manages sessions — keeps track of which conversation is which
• Runs the web UI — the dashboard at http://127.0.0.1:18789 is served by the gateway
• Executes tool calls — when your agent needs to run a shell command, read a file, or call a web API, the gateway coordinates it
• Loads plugins and channels — channel integrations (Telegram bot, Discord, etc.) are gateway plugins

Checking Gateway Status

The fastest diagnostic is one command:

openclaw gateway status

This tells you:

• Whether the gateway is running (and its PID)
• Whether it's reachable at its configured address
• Which channels are connected and their state
• Any configuration warnings or security issues
• Session count and active agents

For a deeper diagnostic:

openclaw status --deep

This runs active connectivity tests against each channel, verifies tokens, and checks external reachability.

Starting, Stopping, and Restarting

# Check status
openclaw gateway status

# Start the gateway
openclaw gateway start

# Stop the gateway
openclaw gateway stop

# Restart (most common fix)
openclaw gateway restart

After any config change to openclaw.json — adding a channel, changing a token, updating a model — you need to restart the gateway for changes to take effect. This is the single most common "why isn't my change working?" answer.

Making the Gateway Start Automatically

By default, you have to manually start the gateway after a reboot. For a machine you want running 24/7, that's not acceptable. The fix is to install the gateway as a system service.

On Linux (systemd):

openclaw gateway install
# Then enable and start it:
systemctl --user enable openclaw-gateway
systemctl --user start openclaw-gateway

On macOS (launchd):

openclaw gateway install
# Starts automatically on login

Verify it survived a reboot: Restart your machine, then run openclaw gateway status. If it shows "running" without you doing anything — you're set.

Common Problems and Fixes

The Gateway Config (What You Actually Need to Know)

Gateway settings live in ~/.openclaw/openclaw.json under the gateway key. The ones that matter most:

{
  "gateway": {
    "bind": "127.0.0.1:18789",     // listen address — keep local unless you need remote
    "authToken": "your-token",      // required for remote access
    "trustedProxies": []            // set if behind a reverse proxy
  }
}

Keeping the Gateway Healthy Long-Term

• Monthly restarts — even a healthy gateway benefits from a monthly restart to clear accumulated session state and release memory
• Monitor with status — add openclaw gateway status to your mental checklist when something feels off
• Update carefully — always restart the gateway after OpenClaw updates; some updates change the gateway binary
• Log rotation — if you're running the gateway as a service, check that logs aren't filling your disk over time (journalctl --user -u openclaw-gateway --disk-usage on systemd)