About This Guide: The OpenClaw Gateway is the core control plane — it routes messages, manages channels, runs cron jobs, and serves the Web UI. Without a healthy gateway, nothing works. This Q&A covers every gateway command from initial startup to production operations: openclaw gateway, port config, hot-reload modes, daemon management, remote access, and multi-gateway deployments.
Gateway Architecture Overview
# Gateway: single multiplexed port for all clients
ws://127.0.0.1:18789 ← WebSocket control plane
http://127.0.0.1:18789 ← Control UI + REST APIs
# Clients connect via:
├─ Pi agent (RPC runtime)
├─ CLI (openclaw ...)
├─ WebChat UI
├─ macOS app
└─ iOS / Android nodes
Starting the Gateway
Q How do I start the OpenClaw gateway?
Use the basic openclaw gateway command. The gateway starts on port 18789 by default and binds to loopback only.
# Start on default port 18789
openclaw gateway
# Start on a custom port
openclaw gateway --port 18789
# Start with verbose debug output
openclaw gateway --port 18789 --verbose
# Force-kill any existing listener, then start
openclaw gateway --force
Tip: Running openclaw gateway in the foreground is great for troubleshooting. For always-on production use, install it as a daemon with openclaw gateway install.
Q
What does openclaw gateway --force do?
The --force flag force-kills any existing process listening on the selected port before starting a new gateway instance. This is useful when a previous gateway crashed and left a stale port binding.
# If you get EADDRINUSE, use --force
openclaw gateway --force
# Or combine with a custom port
openclaw gateway --port 19000 --force
Warning: --force will kill any process on that port, not just OpenClaw. Make sure no other critical service is running on port 18789.
Q How is the gateway port determined?
The port follows a strict resolution order. The first value found wins:
| Priority | Setting | Example |
|---|---|---|
| 1st | --port flag | openclaw gateway --port 19001 |
| 2nd | OPENCLAW_GATEWAY_PORT env | export OPENCLAW_GATEWAY_PORT=19001 |
| 3rd | gateway.port in config | { gateway: { port: 19001 } } |
| Default | Built-in default | 18789 |
Gateway Status & Health Commands
Q How do I check if the gateway is running?
There are three complementary status commands. A healthy gateway shows Runtime: running and RPC probe: ok.
# Quick status check
openclaw gateway status
# Deep diagnostic (more detail)
openclaw gateway status --deep
# Machine-readable JSON output
openclaw gateway status --json
# Short alias
openclaw status
Q How do I follow gateway logs in real time?
Use openclaw logs --follow to tail gateway logs live. This is the fastest way to diagnose connection issues and channel errors.
# Stream live logs
openclaw logs --follow
# Check overall health (readiness probe)
openclaw health
# Check channel status with probe
openclaw channels status --probe
Q
What does openclaw doctor check?
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.
# Full health audit
openclaw doctor
What doctor checks:
- ✓ Service config drift
- ✓ DM security policies
- ✓ Daemon health
- ✓ Config migrations
- ✓ Channel connectivity
Run doctor when:
- → After updating OpenClaw
- → Gateway won't start
- → Channels not connecting
- → After config changes
- → Security audit needed
Daemon Installation & Lifecycle Commands
Q How do I install the gateway as a background service?
Use openclaw gateway install. On macOS it creates a launchd LaunchAgent; on Linux it creates a systemd user service. The gateway then starts automatically on login.
# Install gateway as a system service (macOS + Linux)
openclaw gateway install
# Verify it's running after install
openclaw gateway status
macOS (launchd)
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
Label: ai.openclaw.gateway
Linux (systemd user)
openclaw gateway install
systemctl --user enable --now \
openclaw-gateway.service
openclaw gateway status
For persistence: loginctl enable-linger <user>
Q How do I restart or stop the gateway service?
The full lifecycle command set covers all operations. Note that openclaw gateway stop stops the service but does not uninstall it.
# Full operator command set
openclaw gateway status # check state
openclaw gateway status --deep # detailed diagnostics
openclaw gateway status --json # machine-readable
openclaw gateway install # install service
openclaw gateway restart # restart service
openclaw gateway stop # stop service
openclaw logs --follow # stream live logs
openclaw doctor # full health audit
Q How do I enable gateway persistence after logout on Linux?
By default, systemd user services stop when you log out. To keep the gateway running even when no one is logged in, enable lingering for your user account.
# Enable user lingering (run once, as root)
sudo loginctl enable-linger <your-username>
# Verify lingering is enabled
loginctl show-user <your-username> | grep Linger
# Expected output:
Linger=yes
Hot Reload Configuration
Q What are the gateway hot reload modes and how do I set them?
Hot reload allows the gateway to pick up config changes without a full restart. Set gateway.reload.mode in your config file.
| Mode | Behavior | Best For |
|---|---|---|
off |
No config reload at all | Static setups |
hot |
Apply only hot-safe changes | Minimal disruption |
restart |
Full restart on any change | Always-fresh config |
hybrid ⭐ |
Hot when safe, restart when required | Recommended (default) |
# Set reload mode in config (~/.openclaw/config.json5)
{"gateway": {"reload": {"mode": "hybrid"}}}
# Or disable reload entirely via env
OPENCLAW_SKIP_RELOAD=1 openclaw gateway
Remote Gateway Access
Q How do I access my gateway remotely?
OpenClaw recommends using Tailscale VPN or an SSH tunnel for remote access. The gateway binds to loopback by default and requires auth for non-loopback connections.
# Method 1: SSH tunnel (recommended for private access)
ssh -N -L 18789:127.0.0.1:18789 [email protected]
# Then connect locally to:
ws://127.0.0.1:18789
# Method 2: Tailscale (preferred for always-on)
# Install Tailscale, then access via:
ws://your-machine.tailnet.ts.net:18789
Security: Never expose the gateway port directly to the internet without authentication. Set gateway.auth.token and use gateway.bind: "all" only behind a firewall or VPN. This is exactly why a reliable VPN is critical for remote OpenClaw deployments.
Q How do I set a gateway authentication token?
Authentication is required for any non-loopback bind. Set the token in your config or environment variable:
# Via environment variable
export OPENCLAW_GATEWAY_TOKEN="your-secure-token-here"
# Via config (~/.openclaw/config.json5)
{"gateway": {"auth": {"token": "your-secure-token-here"}}}
# Or use a password instead of token
export OPENCLAW_GATEWAY_PASSWORD="your-password"
Without a token, the gateway will refuse to bind to non-loopback addresses, showing the error: refusing to bind gateway ... without auth
Multiple Gateways on One Host
Q Can I run multiple gateway instances on the same machine?
Yes, but each instance needs its own port, state directory, and config file. This is mainly useful for strict isolation or redundancy.
# Instance A — primary
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001
# Instance B — secondary/isolated
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json \
OPENCLAW_STATE_DIR=~/.openclaw-b \
openclaw gateway --port 19002
Checklist per instance: Unique agents.defaults.workspace · Unique OPENCLAW_STATE_DIR · Unique OPENCLAW_CONFIG_PATH · Unique gateway.port
Q What is the dev profile and how do I use it?
The dev profile provides an isolated development environment with its own state and config, defaulting to port 19001.
# Dev profile quick path
openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
# Dev profile defaults:
# port: 19001
# Isolated state + config from production
Common Gateway Error Messages
another gateway instance is already listening / EADDRINUSE
Port is occupied. Use openclaw gateway --force or change the port.
refusing to bind gateway ... without auth
Non-loopback bind requires a token. Set OPENCLAW_GATEWAY_TOKEN or gateway.auth.token.
Gateway start blocked: set gateway.mode=local
Config is set to remote mode. Change gateway.mode to "local" in your config file.
unauthorized during connect
Auth mismatch. The client token doesn't match the gateway token. Update the client config with the correct gateway.auth.token.
💡 Pro Tip: Gateway Diagnostics Sequence
# Run in order for fastest diagnosis
openclaw gateway status
openclaw doctor
openclaw logs --follow
openclaw channels status --probe
openclaw health
Key Environment Variables
| Variable | Purpose | Default |
|---|---|---|
| OPENCLAW_GATEWAY_PORT | Override gateway port | 18789 |
| OPENCLAW_GATEWAY_TOKEN | Gateway auth token | — |
| OPENCLAW_GATEWAY_PASSWORD | Gateway auth password | — |
| OPENCLAW_CONFIG_PATH | Override config file path | ~/.openclaw/config.json5 |
| OPENCLAW_STATE_DIR | Override state directory | ~/.openclaw/ |
| OPENCLAW_HOME | Set home dir for path resolution | System home dir |
| OPENCLAW_SKIP_CRON | Disable cron entirely (=1) | — |
Best VPN for OpenClaw Gateway Remote Access
VPN07 — #1 for OpenClaw Operators
Remote gateway access requires a VPN you can trust. VPN07 delivers 1000Mbps bandwidth with zero throttling — your gateway connections stay fast whether you're accessing via SSH tunnel or Tailscale. Available in 70+ countries with 10 years of proven reliability.
2. ExpressVPN
7.2/10Known brand but higher price point (~$8.32/mo). Speed is acceptable but throttles at peak hours. No special AI-agent optimization.
3. NordVPN
7.0/10Large server network but inconsistent speeds. Lacks the tunnel stability needed for persistent OpenClaw gateway connections.
Related Articles
OpenClaw Onboard & Dashboard 2026: Commands Q&A
Deep dive into onboard wizard, dashboard, status, logs, health, and message send commands.
Read More → Security GuideOpenClaw Pairing Commands 2026: DM Security Q&A
Complete Q&A for pairing approve, dmPolicy, allowFrom, and channel security commands.
Read More →Secure Your OpenClaw Gateway with VPN07
Remote gateway access, SSH tunnels, API authentication — all secured with VPN07's 1000Mbps network across 70+ countries. 10 years of uninterrupted service. Just $1.5/month with a 30-day money-back guarantee.