Complete HTTPS and Custom Domain Setup Guide for OpenClaw

Introduction

By default, the OpenClaw gateway runs over HTTP. If you need to access the Dashboard over the public internet, or if you are integrating with chat platforms that require HTTPS (such as Telegram Webhooks), you must configure HTTPS. This tutorial covers three mainstream approaches: Let's Encrypt free certificates, Cloudflare SSL, and Nginx reverse proxy.

Approach Comparison

Prerequisites

• A server with a public IP address
• A registered domain name (e.g., ai.example.com)
• DNS already pointing the domain to your server's IP
• OpenClaw installed and running on port 18789

Verify that OpenClaw is running:

openclaw doctor
curl http://localhost:18789/health

Approach 1: Let's Encrypt + Certbot

1.1 Install Certbot

# Ubuntu/Debian
sudo apt update
sudo apt install certbot

# CentOS/RHEL
sudo dnf install certbot

# macOS
brew install certbot

1.2 Obtain a Certificate

Make sure port 80 is not in use (Certbot needs it temporarily):

# Check port 80
sudo lsof -i :80

# If occupied, temporarily stop the service (e.g., nginx)
sudo systemctl stop nginx

Request the certificate:

sudo certbot certonly --standalone \
  -d ai.example.com \
  --email [email protected] \
  --agree-tos \
  --no-eff-email

On success, certificate files are located at:

/etc/letsencrypt/live/ai.example.com/fullchain.pem   # Certificate chain
/etc/letsencrypt/live/ai.example.com/privkey.pem      # Private key

1.3 Configure OpenClaw to Use the Certificate

Edit the OpenClaw configuration file:

{
  server: {
    port: 18789,
    host: "0.0.0.0",
    ssl: {
      enabled: true,
      cert: "/etc/letsencrypt/live/ai.example.com/fullchain.pem",
      key: "/etc/letsencrypt/live/ai.example.com/privkey.pem",
    }
  }
}

Restart OpenClaw:

openclaw restart

Verify that HTTPS is working:

curl https://ai.example.com:18789/health

1.4 Set Up Automatic Renewal

Let's Encrypt certificates are valid for 90 days and require automatic renewal:

# Test that renewal works
sudo certbot renew --dry-run

# Add a cron job for automatic renewal
sudo crontab -e

Add the following entry:

# Check and renew certificate daily at 3 AM
0 3 * * * certbot renew --quiet --post-hook "openclaw restart"

The --post-hook ensures OpenClaw restarts automatically after renewal to load the new certificate.

Approach 2: Cloudflare SSL

If your domain is managed on Cloudflare, this is the simplest approach.

2.1 Configure DNS

Add a DNS record in the Cloudflare Dashboard:

Type: A
Name: ai (for ai.example.com)
Content: Your server IP
Proxy status: Proxied (orange cloud)

2.2 Set the SSL Mode

In Cloudflare Dashboard → SSL/TLS:

SSL/TLS encryption mode: Full (Strict)

Mode descriptions:

2.3 Obtain a Cloudflare Origin Certificate

For Full (Strict) mode, you need to install an Origin certificate on your server:

1. Go to Cloudflare Dashboard → SSL/TLS → Origin Server
2. Click Create Certificate
3. Keep default settings and click Create
4. Copy the certificate and private key

Save them to your server:

# Save the certificate
sudo mkdir -p /etc/cloudflare
sudo nano /etc/cloudflare/origin-cert.pem
# Paste the certificate content

sudo nano /etc/cloudflare/origin-key.pem
# Paste the private key content

# Set permissions
sudo chmod 600 /etc/cloudflare/origin-key.pem

2.4 Configure OpenClaw

{
  server: {
    port: 18789,
    host: "0.0.0.0",
    ssl: {
      enabled: true,
      cert: "/etc/cloudflare/origin-cert.pem",
      key: "/etc/cloudflare/origin-key.pem",
    }
  }
}

openclaw restart

Cloudflare Origin certificates are valid for up to 15 years, so frequent renewal is not needed.

2.5 Configure Cloudflare Security Options

The following settings are recommended in the Cloudflare Dashboard:

• Always Use HTTPS: Automatically redirect HTTP to HTTPS
• HSTS: Enable HTTP Strict Transport Security
• Minimum TLS Version: Set to TLS 1.2
• Automatic HTTPS Rewrites: Automatically fix mixed content

Approach 3: Nginx Reverse Proxy

This is the most flexible approach, ideal for scenarios requiring load balancing, caching, or other advanced features.

3.1 Install Nginx

# Ubuntu/Debian
sudo apt update
sudo apt install nginx

# CentOS/RHEL
sudo dnf install nginx

3.2 Obtain an SSL Certificate

Use Certbot's Nginx plugin for one-click setup:

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

Or obtain the certificate manually (same as Approach 1, Step 1.2).

3.3 Configure Nginx

Create an Nginx configuration file:

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

Add the following content:

# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name ai.example.com;
    return 301 https://$server_name$request_uri;
}

# Main HTTPS configuration
server {
    listen 443 ssl http2;
    server_name ai.example.com;

    # SSL certificates
    ssl_certificate /etc/letsencrypt/live/ai.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ai.example.com/privkey.pem;

    # SSL security settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # HSTS
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # Additional security headers
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";

    # Reverse proxy to OpenClaw
    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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 responses may take longer)
        proxy_read_timeout 120s;
        proxy_send_timeout 120s;
    }

    # Cache Dashboard static assets
    location /dashboard/assets/ {
        proxy_pass http://127.0.0.1:18789;
        expires 7d;
        add_header Cache-Control "public, immutable";
    }
}

3.4 Enable the Configuration

# Create a symbolic link
sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/

# Test configuration syntax
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx

3.5 Configure OpenClaw to Trust the Proxy

When using an Nginx reverse proxy, OpenClaw does not need to handle SSL itself:

{
  server: {
    port: 18789,
    host: "127.0.0.1",           // Listen only on localhost, proxied by Nginx
    trustProxy: true,             // Trust X-Forwarded-For headers from the proxy
    ssl: {
      enabled: false,             // Nginx handles SSL, OpenClaw does not need to
    }
  }
}

3.6 Automatic Renewal (Nginx Approach)

sudo crontab -e

0 3 * * * certbot renew --quiet --post-hook "systemctl reload nginx"

Custom Domain Configuration

DNS Configuration Example

Multi-Domain Support

If you need multiple domains pointing to the same OpenClaw instance:

server {
    listen 443 ssl http2;
    server_name ai.example.com bot.example.com assistant.example.com;

    # Certificate must cover all domains
    ssl_certificate /etc/letsencrypt/live/ai.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ai.example.com/privkey.pem;

    # ... rest of the configuration same as above
}

Request a multi-domain certificate:

sudo certbot certonly --standalone \
  -d ai.example.com \
  -d bot.example.com \
  -d assistant.example.com

Verification and Testing

Test the HTTPS Connection

# Basic connection test
curl -I https://ai.example.com

# View certificate information
openssl s_client -connect ai.example.com:443 -servername ai.example.com </dev/null 2>/dev/null | openssl x509 -noout -dates

# Use SSL Labs for online testing (open in browser)
# https://www.ssllabs.com/ssltest/analyze.html?d=ai.example.com

Check HSTS

curl -I https://ai.example.com | grep -i strict
# Should show: Strict-Transport-Security: max-age=31536000; includeSubDomains

Troubleshooting

Certificate Renewal Failure

# View Certbot logs
sudo cat /var/log/letsencrypt/letsencrypt.log

# Manually renew with verbose output
sudo certbot renew --verbose

Common causes: port 80 is in use, DNS resolution issues, firewall blocking.

Mixed Content Warning

If the browser shows "some content is not secure," it usually means the page references HTTP resources. Enable Automatic HTTPS Rewrites in Cloudflare to fix this automatically.

WebSocket Connection Failure

Ensure the Nginx configuration includes WebSocket support:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Summary

Configuring HTTPS for OpenClaw is an essential step for production environments. For most users, we recommend Cloudflare SSL (simplest) or Nginx + Let's Encrypt (most flexible). Regardless of the approach you choose, make sure to enable HSTS, configure HTTP-to-HTTPS redirection, and set up automatic certificate renewal. Security is paramount -- HTTPS is the first line of defense for protecting your data and your users' data.