OpenClaw Gateway Commands: Port 18789 Setup, Start/Stop & Token Auth

1. What Is the Gateway? A One-Minute Primer

If you're searching for "openclaw gateway" or "openclaw gateway start," you've likely installed OpenClaw but are still unsure about the Gateway's role. In short: the Gateway is OpenClaw's control center — it receives messages from communication platforms (Telegram, LINE, Discord, etc.), dispatches them to AI agents for processing, and manages all connections and authentication.^[1]

MIT Technology Review defined AI agents in early 2025 as "AI systems capable of autonomously executing multi-step tasks."^[9] OpenClaw's Gateway is the infrastructure that makes this autonomy operational: without it, agents cannot receive instructions, connect to external services, or run persistently. As MIT Technology Review further explored in their analysis of agentic workflows, the orchestration layer — the Gateway, in OpenClaw's case — is what transforms a standalone model into a genuinely autonomous agent.^[11]

Think of the Gateway as a "switchboard for AI agents" — all incoming messages pass through it first, and it decides which agent handles the request, which AI model to use, and which security rules to apply.

2. Gateway Command Cheatsheet

Below are the most commonly used Gateway CLI commands. Bookmark this page — according to the OpenClaw official docs^[2], these commands cover over 95% of Gateway management scenarios.

2.1 Status Queries

2.2 Start and Stop

Note: OpenClaw Gateway does not have separate gateway start or gateway stop subcommands. To start, run openclaw gateway (foreground) or install as a system service via openclaw gateway install --force.^[1] To stop the service, use systemctl stop openclaw-gateway on Linux or launchctl unload on macOS.

2.3 Diagnostics and Debugging

2.4 Config Management

3. Port Configuration: Solving 90% of Startup Issues

"openclaw gateway default port" and "openclaw gateway port" are among the most searched queries — this is one of the most common questions users have.

3.1 Default Port: 18789

OpenClaw Gateway's default WebSocket port is 18789.^[1] After installation, the Control UI (Dashboard) is accessible at http://127.0.0.1:18789.

3.2 How to Change the Port

Method 1: CLI (Recommended)

# Permanently change Gateway port
openclaw config set gateway.port 28789

# Verify the change
openclaw config get gateway.port

# Restart service to apply changes
openclaw gateway restart

Method 2: Edit openclaw.json directly

Config file is at ~/.openclaw/openclaw.json (JSON5 format):^[1]

{
  gateway: {
    port: 28789,
    bind: "loopback"
  }
}

Method 3: Temporary port override (without modifying config)

# Start in foreground with custom port
openclaw gateway --port 28789

3.3 Port Conflict (EADDRINUSE) Troubleshooting

If you see EADDRINUSE or another gateway instance is already listening^[2], the port is occupied:

# Find the process using port 18789
# macOS / Linux
sudo lsof -i :18789

# Kill the occupying process (replace PID)
kill -9 <PID>

# Or switch to a different port
openclaw config set gateway.port 28789
openclaw gateway restart

4. Token Authentication Management

Token security is the Gateway's most critical concern. CrowdStrike's research found over 42,000 publicly exposed OpenClaw instances^[6], with 93.4% having authentication bypass vulnerabilities. The Hacker News also reported CVE-2026-25253^[8] — a cross-site WebSocket hijacking vulnerability that gives attackers full control. This makes token management a matter of critical importance.

Harvard Business Review's analysis of AI deployment barriers confirms that security remains the top concern for enterprise AI adoption: organizations that fail to implement proper authentication and access controls expose themselves to catastrophic risk.^[12] OpenClaw's token management is the first line of defense.

4.1 Generating a Token

# Auto-generate and write a secure random token
openclaw doctor --generate-gateway-token

# Manually set a token
openclaw config set gateway.auth.token "your-long-random-token-here"

# Verify the token is set
openclaw config get gateway.auth.token

4.2 Gateway Authentication Modes

OpenClaw supports three authentication modes:^[3]

Complete token auth config example:

{
  gateway: {
    auth: {
      mode: "token",
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    }
  }
}

The official docs explicitly warn: "Gateway HTTP bearer auth is effectively full-privilege operator access. Protect credentials as full-access keys."^[3]

4.3 Environment Variable Management

Rather than storing tokens in plaintext within openclaw.json, the official recommendation is to use environment variables:^[1]

# Set in ~/.openclaw/.env
OPENCLAW_GATEWAY_TOKEN=your-secure-random-token
OPENCLAW_GATEWAY_PASSWORD=your-backup-password

OpenClaw's environment variable priority order:

1. Parent process environment variables
2. Current directory .env file
3. ~/.openclaw/.env (global fallback)

5. Local vs Remote Mode

This is the most confusing part of Gateway configuration — and the #1 cause of gateway start blocked errors.^[2]

5.1 Local Mode (Default)

Gateway only accepts local connections (127.0.0.1), no authentication required:

# Enable Local mode
openclaw config set gateway.mode local
openclaw config set gateway.bind loopback

Best for: personal development, single-machine use, getting started.

5.2 Remote Mode

Allows external devices (phones, other computers) to connect to the Gateway. Token must be configured first — otherwise the Gateway refuses to start:^[3]

# Switch to Remote mode
openclaw config set gateway.mode remote

# Set token (required!)
openclaw doctor --generate-gateway-token

# Bind to all network interfaces (not just loopback)
openclaw config set gateway.bind 0.0.0.0

# Restart to apply
openclaw gateway restart

Security warning: Binding to 0.0.0.0 means any device that can reach your machine can attempt to connect. The official docs strongly recommend pairing this with firewall rules or using Tailscale for VPN tunneling.^[4] Harvard Business Review noted in late 2024 that secure deployment of AI agents is the single biggest barrier to enterprise adoption^[10] — OpenClaw's Remote mode configuration is a microcosm of this challenge.

5.3 SSH Tunnel (Secure Remote Access)

Don't want to expose the Gateway to the public internet? An SSH tunnel is the most secure approach:^[4]

# Create SSH tunnel
ssh -N -L 18789:127.0.0.1:18789 user@your-server

# Gateway stays on loopback binding, accessed securely via SSH forwarding
# Access locally at http://127.0.0.1:18789

6. Common Error Reference

Compiled from the OpenClaw official troubleshooting docs^[2], covering the most common Gateway error messages and fixes:

6.1 Standard Debugging Flow

For any Gateway issue, run these three commands in order:^[2]

# Standard 3-step debug flow

# 1. Check current status
openclaw gateway status

# 2. Check logs for clues
openclaw logs --follow

# 3. Auto-diagnose
openclaw doctor

7. Complete openclaw.json Config Example

Here's a complete openclaw.json example covering all Gateway-related settings:^[1]

{
  // Gateway core settings
  gateway: {
    mode: "local",           // "local" or "remote"
    port: 18789,             // WebSocket listening port
    bind: "loopback",        // "loopback" or "0.0.0.0"

    // Authentication (required for Remote mode)
    auth: {
      mode: "token",         // "token", "password", "trusted-proxy"
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    },

    // Config hot-reload
    reload: {
      mode: "hybrid"         // "hybrid", "hot", "restart", "off"
    },

    // Remote connection (when this machine connects to a remote Gateway)
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "remote-token"
    }
  }
}

8. Advanced: systemd Service Management (Linux)

On Linux servers, OpenClaw Gateway typically runs as a systemd background service:^[4]

# systemd service management

# Install as system service
openclaw gateway install --force

# Check service status
systemctl status openclaw-gateway

# Manual start / stop / restart
systemctl start openclaw-gateway
systemctl stop openclaw-gateway
systemctl restart openclaw-gateway

# View service logs
journalctl -u openclaw-gateway -f

9. Security Checklist

CNBC reported that OpenClaw's explosive growth has been accompanied by serious security concerns.^[7] Below is a pre-deployment security checklist based on the official security documentation:^[3]

FAQ

Q: What is the default port for OpenClaw Gateway?

A: 18789. The Control UI is accessible at http://127.0.0.1:18789. To change it, use openclaw config set gateway.port <new-port>.^[1]

Q: How do I fix "gateway start blocked"?

A: Run openclaw config set gateway.mode local to enable local mode. For Remote mode, you must first configure gateway.auth.token.^[2]

Q: How can I securely control OpenClaw from my phone?

A: Use an SSH tunnel (ssh -N -L 18789:127.0.0.1:18789 user@host) or Tailscale VPN.^[4] Avoid exposing the Gateway directly to the public internet.

Q: What if I forget my Gateway token?

A: Use openclaw config get gateway.auth.token to view the current token, or run openclaw doctor --generate-gateway-token to regenerate one.^[3]

Q: Can I run Gateway on multiple machines simultaneously?

A: The official recommendation is one Gateway instance per host. For multi-machine setups, use Remote mode with one machine as the primary controller and others connecting as clients.^[4]