Nginx Reverse Proxy and SSL Setup for OpenClaw

The OpenClaw Gateway service runs on port 18789 by default, and the official recommendation is clear: never expose this port directly to the public internet. The proper approach is to use Nginx as a reverse proxy that handles SSL encryption and access control on the frontend, then forwards requests to the OpenClaw Gateway. This tutorial walks through the entire setup.

Why You Need a Reverse Proxy

Exposing OpenClaw's port 18789 directly carries multiple risks:

No encryption: The Gateway defaults to HTTP, which means chat content and API keys could be intercepted by a man-in-the-middle attack
No access control: Anyone can attempt to access your Gateway endpoints
No domain name support: Many chat platforms require HTTPS URLs for webhooks

An Nginx reverse proxy gives you SSL encryption, request filtering, rate limiting, and much more. For detailed security recommendations, see the OpenClaw official documentation.

Prerequisites

A Linux server with OpenClaw already deployed (Ubuntu 22.04/24.04 recommended)
A domain name pointing to your server's IP address (e.g., ai.example.com)
The OpenClaw Gateway running locally

Step 1: Install Nginx

sudo apt update
sudo apt install -y nginx

Confirm that Nginx is running:

sudo systemctl status nginx
sudo systemctl enable nginx

Step 2: Create the Nginx Configuration

Create a dedicated Nginx site configuration for OpenClaw:

sudo nano /etc/nginx/sites-available/openclaw

Add the following configuration:

upstream openclaw_gateway {
    server 127.0.0.1:18789;
    keepalive 64;
}

server {
    listen 80;
    server_name ai.example.com;

    # Certbot will automatically add HTTPS redirect later
    location / {
        proxy_pass http://openclaw_gateway;
        proxy_http_version 1.1;

        # WebSocket support (required by some OpenClaw features)
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Pass real client information
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Timeout settings (AI generation can take a while)
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;

        # Buffer settings
        proxy_buffering off;
        proxy_cache off;
    }
}

Enable the site configuration:

sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo nginx -t  # Validate the configuration syntax
sudo systemctl reload nginx

The nginx -t command checks for syntax errors. If it reports syntax is ok and test is successful, the configuration is correct.

Step 3: Obtain an SSL Certificate

Use a free SSL certificate from Let's Encrypt, managed through the Certbot tool:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d ai.example.com

Certbot will automatically:

Verify domain ownership
Issue the SSL certificate
Update the Nginx configuration to add HTTPS and automatic HTTP-to-HTTPS redirection
Set up automatic certificate renewal

Certificates are valid for 90 days, and Certbot schedules a cron job to handle renewals. You can verify that renewal works correctly:

sudo certbot renew --dry-run

Step 4: Configure Trusted Proxies in OpenClaw

With a reverse proxy in front, OpenClaw needs to know which proxies are trusted so it can correctly determine the client's real IP address. Edit the OpenClaw configuration:

nano ~/.config/openclaw/openclaw.json5

Add the trusted proxy settings:

{
  gateway: {
    // Trust requests from the local Nginx instance
    trustedProxies: ["127.0.0.1", "::1"],
    // Bind to localhost only — stop listening for external requests
    host: "127.0.0.1",
    port: 18789,
  }
}

Setting host to 127.0.0.1 ensures the Gateway only accepts connections from the local machine. Even if the firewall is misconfigured, outsiders won't be able to reach port 18789 directly.

Restart the Gateway to apply the changes:

openclaw gateway restart

Step 5: Configure the Firewall

Use UFW to ensure only the necessary ports are open:

sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP (for certificate verification and redirects)
sudo ufw allow 443/tcp   # HTTPS
sudo ufw deny 18789/tcp  # Explicitly block direct Gateway access
sudo ufw enable
sudo ufw status

Step 6: Verify the Full Pipeline

With everything configured, run an end-to-end verification:

# Check that Nginx is proxying correctly
curl -I https://ai.example.com

# Check the OpenClaw Gateway status
openclaw doctor

# Confirm port 18789 is not publicly accessible
# From another machine, run:
curl http://your-server-ip:18789  # This should be refused

Advanced: Adding Rate Limiting

To prevent abuse, you can add rate limiting in Nginx. In the http block (typically in /etc/nginx/nginx.conf), add:

# Define a rate-limiting zone
limit_req_zone $binary_remote_addr zone=openclaw_limit:10m rate=10r/s;

Then reference it in the location block of your site configuration:

location / {
    limit_req zone=openclaw_limit burst=20 nodelay;
    proxy_pass http://openclaw_gateway;
    # ... keep the rest of the configuration unchanged
}

This limits each IP address to 10 requests per second, with a burst allowance of 20 requests.

Wrapping Up

With Nginx as a reverse proxy and SSL certificates in place, your OpenClaw Gateway now has solid security protection. All communications are encrypted, the Gateway port is no longer exposed, and you can add additional Nginx security features as needed. If you use Caddy or another web server, the general approach is similar — check the deployment guide in the OpenClaw official documentation for details. For configuration issues, head to the OpenClaw GitHub repository to get help from the community.