OpenClaw Gateway: The One Config Change That Changes Everything

Change the gateway token from the default and you immediately prevent the most common OpenClaw deployment vulnerability. That one change alone stops unauthorized agent connections. But the gateway does far more than authentication — it's the entire routing, queuing, and delivery infrastructure for your AI system. Here's every setting that matters and exactly how to configure it.

What the Gateway Actually Does

The OpenClaw gateway is the central hub of your deployment. Every message — from a Telegram user, a WhatsApp webhook, a direct API call, or one agent talking to another — enters and exits through the gateway.

On the inbound side, the gateway receives webhooks from messaging platforms, validates the request signature, extracts the message content, and routes it to the correct agent channel. On the outbound side, it receives the agent's response, formats it for the target platform, and delivers it back to the user.

In a multi-agent setup, the gateway also handles inter-agent messages. When Agent A sends a task to Agent B, that message goes through the gateway's internal bus. The gateway queues it, routes it to Agent B's registered channel, and delivers Agent B's response back to Agent A. None of this requires any code — it's all configuration.

Core Config Settings You Must Set

The gateway config lives in gateway.yaml (or the path you specify with the --config flag). Here are the settings that matter most for every deployment.

gateway:
  host: "0.0.0.0"
  port: 8080
  token: "your-strong-random-token-here"   # CHANGE THIS
  trusted_proxies: ["127.0.0.1"]            # Your reverse proxy IP
  allow_insecure_auth: false                # Keep false in production

  heartbeat:
    enabled: true
    interval_seconds: 30
    timeout_seconds: 10

  queue:
    max_size: 10000
    message_ttl_seconds: 3600              # Messages expire after 1 hour

  logging:
    level: "info"                          # "debug" for troubleshooting
    log_messages: true                     # Log all inter-agent messages

Three settings are non-negotiable. Token: set a random 32+ character string. TrustedProxies: set this to your reverse proxy IP or you'll see IP spoofing issues in logs. AllowInsecureAuth: keep it false — this flag exists for local development only.

Exposing the Gateway to the Internet

The gateway listens on plain HTTP by default. This is fine for local development and internal network deployments. For anything internet-facing, you must add HTTPS termination through a reverse proxy.

The simplest production setup uses Caddy. It handles certificate provisioning automatically and requires two lines of configuration.

# Caddyfile
yourdomain.com {
  reverse_proxy localhost:8080
}

Start Caddy and it fetches a Let's Encrypt certificate automatically, terminates HTTPS, and forwards requests to your gateway. For nginx, the setup is similar but requires manual certificate management with Certbot.

After setting up HTTPS, update your gateway.yaml to set trusted_proxies to 127.0.0.1 (for local reverse proxy) or your proxy server's IP. This tells the gateway which upstream IP to trust for headers like X-Forwarded-For. Without this, the gateway sees your proxy as the client for all requests.

Security Settings That Matter

Beyond the basic token, the gateway has three security settings worth understanding.

AllowInsecureAuth

This setting allows agents to connect without a valid gateway token. It exists for local development when you want to prototype quickly without setting up authentication. Never enable this in production. As of early 2025, this is the most commonly misconfigured gateway setting in public OpenClaw deployments found during security reviews.

TrustedProxies

When the gateway receives a request through a reverse proxy, the real client IP is in the X-Forwarded-For header. If you don't set TrustedProxies, the gateway ignores this header and sees all requests as coming from the proxy itself. This breaks IP-based rate limiting and makes logs useless for security analysis. Set this to your proxy's IP.

Rate Limiting

The gateway supports per-channel rate limiting to prevent abuse. Configure limits in gateway.yaml under the rate_limit block. Start with 10 messages per minute per channel for user-facing deployments and adjust based on your usage patterns.

Monitoring the Gateway

The gateway exposes a health endpoint at /health and metrics at /metrics (Prometheus format). Set up a simple uptime monitor against the health endpoint. If the gateway goes down, your entire agent system stops responding — you want to know immediately.

Enable message logging in development (log_messages: true). This records every inter-agent message to your log output, which is invaluable for debugging multi-agent coordination. In production, consider disabling message logging for sensitive deployments or setting up log redaction for PII.

Heartbeat monitoring automatically detects agent connections that have gone silent. Set heartbeat.enabled: true with a 30-second interval. If an agent doesn't respond to a heartbeat within the timeout window, the gateway marks the channel as unavailable and queues incoming messages rather than dropping them.

Common Gateway Configuration Mistakes

• Default token in production — the most critical mistake. Generate a new token before any deployment that connects to external services.
• Missing TrustedProxies — causes all requests to appear as coming from the proxy IP. Breaks rate limiting, breaks IP-based logging, and can cause auth failures with strict IP validation.
• No heartbeat enabled — without heartbeats, a crashed agent looks like a slow agent. Messages queue up silently instead of failing fast and alerting you.
• Running HTTP in production — webhook providers like Telegram require HTTPS endpoints. HTTP webhooks will fail silently or be rejected.
• message_ttl too short — if an agent goes offline and the message TTL expires before it reconnects, messages are lost permanently. Set TTL to at least 1 hour for worker agents and longer for critical pipelines.

Frequently Asked Questions

What is the OpenClaw gateway?

The OpenClaw gateway is the central routing layer that connects your AI agents to communication channels (Telegram, WhatsApp, Discord, REST API) and to each other. Every inbound message from users and every inter-agent message passes through the gateway, which normalizes formats, handles authentication, and routes to the correct agent.

Does every OpenClaw installation need a gateway?

Yes. The gateway is required for any deployment involving channel integrations or multi-agent communication. For local development with a single agent and no external channels, you can interact via CLI. But any production deployment with user-facing channels needs the gateway running.

How do I expose the gateway to the internet?

Run the gateway behind a reverse proxy (nginx or Caddy) with HTTPS termination. The gateway listens on HTTP by default. Configure the reverse proxy to forward to the gateway port (default 8080). Set TrustedProxies in gateway config to your proxy's IP. Never expose the raw HTTP gateway directly to the internet.

What is the gateway token used for?

The gateway token is a shared secret that authenticates agent connections. Every agent process must present this token when registering its channel. Without a valid token, the gateway rejects the connection. Set a strong random token in production — never use the default placeholder.

Can I run multiple gateways?

Yes. Multiple gateway instances can share the same database backend and coordinate agent routing for high-availability setups. Each instance runs independently and agents register with the gateway nearest to them.

What happens to messages when the gateway restarts?

The gateway persists the message queue to its database backend between restarts. Queued messages are preserved and re-queued when the gateway comes back online. Configure retry logic in your agent error handling to cover in-flight messages that may need resending after a restart.