OpenClaw Gateway Explained: What It Does, How It Routes, and Restart Commands (2026)

What's up, AI infrastructure nerds — if you've ever sent a message to your OpenClaw bot and gotten silence back, stared at a frozen terminal wondering which part of this thing actually broke, you're in the right place.

I'm Hanks. Three-plus years of running automation systems on real hardware, and the number of times I've been stumped by "gateway or agent?" is honestly embarrassing. The OpenClaw docs are good, but they assume you already know the difference. This article is for the moment before you know that.

The core question worth answering: what is the Gateway actually doing, and what does it own versus what does the agent own? Once that clicks, restarting the right thing when something breaks becomes obvious.

What Is the OpenClaw Gateway?

The OpenClaw docs have a line buried in the architecture section that I keep coming back to: "The Gateway is the always-on control plane; the assistant is the product."

That's the whole thing right there. The Gateway isn't the AI. It's the infrastructure that makes the AI reachable — routing your messages, managing who's allowed to talk, handling sessions, and dispatching tool calls. The model is just a capability plugged into it.

Gateway vs. Agent — What Each Component Does

A lot of confusion starts here. These two components look coupled from the outside but have clean separation internally:

Pi Agent handles the core agentic loop. OpenClaw handles everything around it: channels, routing, sessions, memory injection, skill loading, and persistence. When your agent seems "stuck," you're almost always looking at a Gateway issue — not a model issue. The model doesn't even get called until the Gateway finishes routing.

Where the Gateway Sits in the Architecture

OpenClaw follows a hub-and-spoke architecture centered on a single Gateway that acts as the control plane between user inputs — WhatsApp, iMessage, Slack, the macOS app, web UI, CLI — and the AI agent.

Visually it looks like this:

WhatsApp / Telegram / Slack / iMessage
              ↓
         [GATEWAY]  ← WebSocket on port 18789
         /   |   \
    Routing  Auth  Sessions
              ↓
        [AGENT RUNTIME]
              ↓
       Model (Claude / GPT / DeepSeek / etc.)

The Gateway is a single WebSocket server process that serves as the central control plane for all OpenClaw operations. It coordinates between messaging channels, agent sessions, device nodes, and user interfaces. One process. One port. Everything flows through it.

How the Gateway Routes Messages

Inbound Channels (WhatsApp, Telegram, Slack, API)

A single long-lived Gateway owns all messaging surfaces — WhatsApp via Baileys, Telegram via grammY, Slack, Discord, Signal, iMessage, WebChat. Each platform is a separate channel adapter that normalizes the platform-specific message format into OpenClaw's internal structure before handing it to the Gateway.

Channels support multiple accounts — for example, multiple Telegram bots or multiple WhatsApp connections. Each account is independently monitored and routed. Account health monitoring tracks connection status and auto-restarts disconnected monitors.

Routing Logic: How the Agent Gets Selected

This is the step most people skip over. The execution sequence for every inbound message is:

1. Channel adapter receives message
2. Gateway routes to appropriate session
3. System prompt assembled from IDENTITY.md, SOUL.md, TOOLS.md, active skills, and memory files
4. Pi Agent called with context and tool registry
5. Model streams response
6. Tool calls executed with policy chain validation
7. Tool results fed back to model
8. Final response streamed to channel adapter
9. Transcript written to session JSONL

Group chat behavior is configurable. In group chats, the bot only responds when mentioned by default (activation: "mention"). You can set activation: "always" to have it respond to every message in a group — useful for dedicated bot channels.

Session Management and Persistence

OpenClaw maintains several state stores on disk, each with hot-reload or lazy-load semantics. Sessions are stored as JSONL files under ~/.openclaw/sessions/:

~/.openclaw/sessions/
├── main-default.jsonl          # Main DM session
├── group-telegram-123456789.jsonl  # Group session
├── cron-daily-summary.jsonl    # Cron job session
└── subagent-abc123.jsonl       # Spawned subagent

This matters for restarts. Because session state is written to disk, a Gateway restart doesn't wipe conversation history. The next message picks up where the session left off. That said — if the Gateway crashes mid-tool-call, the last incomplete turn won't be replayed. Check your session JSONL if you need to audit what got written.

Configuring the Gateway

Key Environment Variables

OpenClaw reads its config from ~/.openclaw/openclaw.json. The key Gateway settings you'll actually touch:

{
  "gateway": {
    "bind": "loopback",
    "port": 18789,
    "auth": {
      "token": "your-secure-token-here"
    },
    "reload": {
      "mode": "hot"
    },
    "channelHealthCheckMinutes": 5
  }
}

The gateway.auth section configures access control for the Gateway WebSocket endpoint. If OPENCLAW_GATEWAY_TOKEN is set, any connecting client must pass a matching token or the socket closes immediately.

Security note that comes up constantly: Bind Gateway to loopback only. Set gateway.bind: "loopback" in config. Access remotely via SSH tunnels or Tailscale Serve. Never expose port 18789 publicly. The CrowdStrike security overview of OpenClaw documents 30,000+ publicly exposed instances found by Censys — all because someone deployed to a VPS and skipped this setting.

The Gateway watches openclaw.json for changes and applies them automatically based on gateway.reload.mode. Changes to gateway.reload and gateway.remote are the exception — those require a full restart.

Port Settings and Reverse Proxy Considerations

The Gateway runs on port 18789 by default and multiplexes everything through that single port: WebSocket control plane, HTTP for the web UI, and the Canvas interface at /openclaw/canvas/.

The gateway.trustedProxies field configures proxy IP trust for header forwarding. When the Gateway sits behind a reverse proxy — nginx, Caddy, or Tailscale — this setting allows header forwarding (X-Forwarded-For, X-Real-IP).

For remote access, the recommended pattern per the official OpenClaw docs is Tailscale Serve, not opening port 18789 externally. When tailscale.mode is serve or funnel, the Gateway still binds to the configured gateway.bind address, and Tailscale forwards traffic to that bind address.

Restarting the Gateway

This is usually why someone lands on this article. The right command depends on how you installed.

Docker Restart Command

If you set up via Simon Willison's Docker walkthrough or the official Docker Compose setup, your container is named openclaw-openclaw-gateway-1. Restart from the directory containing your docker-compose.yml:

# Graceful restart
docker compose restart openclaw-gateway
# Full stop and start (when a restart isn't enough)
docker compose down && docker compose up -d
# Check logs immediately after
docker compose logs -f openclaw-gateway

For the openclaw-cli companion container used to run management commands:

docker compose run --rm openclaw-cli gateway restart

Native Process Restart (PM2 / systemd)

OpenClaw's built-in command (preferred when service is installed):

openclaw gateway restart

If your Gateway runs as a service, openclaw gateway restart is preferred over killing PIDs.

macOS (launchd):

launchctl kickstart -k gui/$UID/bot.molt.gateway

Linux (systemd user service):

systemctl --user restart openclaw-gateway.service

PM2 (common on VPS deployments where systemd isn't available):

pm2 restart openclaw-gateway
pm2 logs openclaw-gateway --lines 50

Headless server gotcha: If you're on EC2 or another headless Linux environment and openclaw gateway install fails with a D-Bus error, this is a known issue filed on GitHub. Fix it before installing the service:

sudo loginctl enable-linger $(whoami)
export XDG_RUNTIME_DIR=/run/user/$(id -u)
# Add the export to ~/.bashrc so it persists
echo 'export XDG_RUNTIME_DIR=/run/user/$(id -u)' >> ~/.bashrc
openclaw gateway install --force

Also note: if you're deployed on Zeabur or similar container platforms, openclaw gateway restart relies on systemctl --user which won't be available inside those containers. Use the platform's native restart mechanism instead.

When a Restart vs. Full Redeploy Is Needed

Monitoring Gateway Health

Log Locations and What to Look For

Follow logs live during a restart or channel issue:

# RPC-connected log stream (requires healthy gateway)
openclaw logs --follow
# Direct file tail (works even when RPC is down)
tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)"
# Last 100 lines
openclaw gateway logs --tail 100

A healthy gateway shows these in the health check:

Runtime: running
RPC probe: ok

Run the full audit at any time:

openclaw doctor

openclaw doctor runs a comprehensive health audit of your entire OpenClaw setup. It checks service config drift, risky DM policies, daemon status, and migrates outdated configurations automatically.

Common Gateway Errors and Quick Fixes

At Macaron, we built our agent layer so that the infrastructure side — routing, session continuity, keeping things running when you're not watching — is handled for you. If managing your own gateway is the part of OpenClaw that slows you down, you can try it free at macaron.im and test with a real task to see if the tradeoff makes sense for your workflow.

Frequently Asked Questions

Q: What's the difference between openclaw gateway restart and openclaw gateway --force?

restart gracefully stops and restarts the service. --force kills any process on port 18789 first — useful when a crash left a stale port binding. Warning: --force will kill any process on that port, not just OpenClaw. Make sure no other critical service is running on port 18789.

Q: Will restarting the Gateway lose my conversation history?

No. Session history is written to JSONL files on disk. A restart doesn't touch those files. Your next message picks up the same session context.

Q: How do I keep the Gateway running after I log out of my Linux server?

Enable systemd user lingering: sudo loginctl enable-linger $USER. Without this, the service won't come up after a reboot or logout. The OpenClaw setup docs cover the Linux systemd user service configuration in detail.

Q: The dashboard shows the Gateway as healthy but channels are offline — what's going on?

The Gateway process is running, but individual channel adapters disconnected. This is a channel-level issue, not a Gateway-level one. Check openclaw logs --follow for the specific channel error (usually an expired session token or API limit), then restart just that channel or run openclaw doctor --fix.

Q: Does changing openclaw.json require a restart?

Most sections hot-reload automatically when gateway.reload.mode: "hot" is set. The exceptions are gateway.reload and gateway.remote — those require a full openclaw gateway restart to apply.

Architecture details verified against docs.openclaw.ai/concepts/architecture and deepwiki.com/openclaw, February 2026. Restart commands cross-referenced against the official updating guide.