Configuring SSL Certificates and HTTPS for OpenClaw

Introduction

The OpenClaw Gateway runs on HTTP port 18789 by default. In production environments, especially when the Web Dashboard is publicly exposed or webhooks are used to receive messages, HTTPS encryption is a fundamental security requirement. This article introduces three approaches to configuring SSL for OpenClaw.

1. Choosing an Approach

Approach	Use Case	Complexity	Recommendation
Nginx Reverse Proxy + Let's Encrypt	Production, with a domain	Medium	Most recommended
OpenClaw Built-in SSL	Simple deployment, quick setup	Low	Suitable for testing
Self-Signed Certificate	Intranet, no domain	Low	Intranet only

2. Approach 1: Nginx Reverse Proxy (Recommended)

This is the recommended approach for production environments, where Nginx handles SSL termination while OpenClaw continues running over HTTP.

2.1 Install Nginx and Certbot

# Ubuntu/Debian
sudo apt update
sudo apt install nginx certbot python3-certbot-nginx

# CentOS/RHEL
sudo yum install nginx certbot python3-certbot-nginx

2.2 Configure Nginx Reverse Proxy

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

server {
    listen 80;
    server_name openclaw.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:18789;
        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;

        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Timeout settings (AI responses can be slow)
        proxy_read_timeout 120s;
        proxy_send_timeout 120s;
    }
}

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

2.3 Obtain a Let's Encrypt Certificate

# Automatically request and configure SSL
sudo certbot --nginx -d openclaw.yourdomain.com

# Follow the prompts:
# 1. Enter your email address (for certificate expiration reminders)
# 2. Agree to the terms of service
# 3. Choose whether to redirect HTTP to HTTPS (recommended: yes)

Certbot will automatically modify the Nginx configuration to add SSL-related settings. The resulting configuration will look similar to:

server {
    listen 443 ssl;
    server_name openclaw.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/openclaw.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/openclaw.yourdomain.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    location / {
        proxy_pass http://127.0.0.1:18789;
        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;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 120s;
        proxy_send_timeout 120s;
    }
}

server {
    listen 80;
    server_name openclaw.yourdomain.com;
    return 301 https://$host$request_uri;
}

2.4 Automatic Certificate Renewal

Let's Encrypt certificates are valid for 90 days. Certbot configures automatic renewal by default:

# Check renewal timer
sudo systemctl list-timers | grep certbot

# Test renewal manually
sudo certbot renew --dry-run

# If automatic renewal is not configured, add a crontab entry manually
# Attempt renewal every day at 3:00 AM
echo "0 3 * * * certbot renew --quiet --post-hook 'systemctl reload nginx'" | sudo tee -a /etc/crontab

2.5 SSL Security Hardening

Add security headers to the Nginx configuration:

# Add inside the server block
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-XSS-Protection "1; mode=block" always;

# Allow only strong cipher algorithms
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers on;

3. Approach 2: OpenClaw Built-in SSL

OpenClaw supports direct SSL certificate configuration without needing an Nginx intermediary.

3.1 Configure Built-in SSL

// ~/.config/openclaw/openclaw.json5
{
  "gateway": {
    "port": 18789,
    "ssl": {
      "enabled": true,
      "cert": "/path/to/fullchain.pem",
      "key": "/path/to/privkey.pem",
      "port": 18790   // HTTPS listening port
    }
  }
}

3.2 Using Let's Encrypt Certificates

# Request a certificate using standalone mode (requires temporarily stopping services on port 80)
sudo certbot certonly --standalone -d openclaw.yourdomain.com

# Certificate file locations
# /etc/letsencrypt/live/openclaw.yourdomain.com/fullchain.pem
# /etc/letsencrypt/live/openclaw.yourdomain.com/privkey.pem

Since Let's Encrypt certificate files are readable only by root by default, permissions need to be configured:

# Option 1: Add the openclaw user to the ssl-cert group
sudo usermod -aG ssl-cert openclaw
sudo chgrp -R ssl-cert /etc/letsencrypt/live/ /etc/letsencrypt/archive/
sudo chmod -R g+rx /etc/letsencrypt/live/ /etc/letsencrypt/archive/

# Option 2: Copy certificates to a location accessible by OpenClaw
sudo mkdir -p /home/openclaw/.openclaw/ssl
sudo cp /etc/letsencrypt/live/openclaw.yourdomain.com/fullchain.pem /home/openclaw/.openclaw/ssl/
sudo cp /etc/letsencrypt/live/openclaw.yourdomain.com/privkey.pem /home/openclaw/.openclaw/ssl/
sudo chown -R openclaw:openclaw /home/openclaw/.openclaw/ssl/
sudo chmod 600 /home/openclaw/.openclaw/ssl/privkey.pem

3.3 Auto-Reload After Certificate Renewal

# Create a renewal hook script
sudo nano /etc/letsencrypt/renewal-hooks/post/openclaw-reload.sh

#!/bin/bash
# Copy new certificates to OpenClaw directory
cp /etc/letsencrypt/live/openclaw.yourdomain.com/fullchain.pem /home/openclaw/.openclaw/ssl/
cp /etc/letsencrypt/live/openclaw.yourdomain.com/privkey.pem /home/openclaw/.openclaw/ssl/
chown openclaw:openclaw /home/openclaw/.openclaw/ssl/*.pem

# Reload OpenClaw to load new certificates
sudo -u openclaw openclaw restart

sudo chmod +x /etc/letsencrypt/renewal-hooks/post/openclaw-reload.sh

4. Approach 3: Self-Signed Certificate

Suitable for intranet deployments or testing environments.

4.1 Generate a Self-Signed Certificate

# Create certificate directory
mkdir -p ~/.openclaw/ssl && cd ~/.openclaw/ssl

# Generate private key and certificate (valid for 365 days)
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout privkey.pem \
  -out fullchain.pem \
  -subj "/CN=openclaw.local/O=OpenClaw/C=CN"

# Set permissions
chmod 600 privkey.pem
chmod 644 fullchain.pem

4.2 Configure OpenClaw to Use the Self-Signed Certificate

{
  "gateway": {
    "ssl": {
      "enabled": true,
      "cert": "~/.openclaw/ssl/fullchain.pem",
      "key": "~/.openclaw/ssl/privkey.pem",
      "port": 18790
    }
  }
}

4.3 Trust the Self-Signed Certificate on Clients

Browsers will show a security warning when accessing; you can manually add trust:

# Linux: Add to system trust store
sudo cp ~/.openclaw/ssl/fullchain.pem /usr/local/share/ca-certificates/openclaw.crt
sudo update-ca-certificates

# macOS: Add to Keychain
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/.openclaw/ssl/fullchain.pem

5. Verifying the HTTPS Configuration

After configuration is complete, verify that HTTPS is working properly:

# Test HTTPS connection
curl -v https://openclaw.yourdomain.com/health

# Check certificate information
openssl s_client -connect openclaw.yourdomain.com:443 -servername openclaw.yourdomain.com </dev/null 2>/dev/null | openssl x509 -noout -dates -subject

# Use SSL Labs online test (when publicly accessible)
# https://www.ssllabs.com/ssltest/analyze.html?d=openclaw.yourdomain.com

6. FAQ

Q: WebSocket connection fails after configuring HTTPS?

Ensure the Nginx configuration includes the Upgrade and Connection headers for WebSocket support.

Q: Service doesn't load the new certificate after renewal?

OpenClaw does not automatically detect certificate file changes. After renewal, you need to run openclaw restart or configure a renewal hook script.

Q: Can I use both HTTP and HTTPS simultaneously?

You can listen on both ports, but in production it's recommended to enforce HTTPS by using a 301 redirect to route HTTP requests to HTTPS.

With SSL certificates properly configured, your OpenClaw service gains transport-layer encryption protection, meets security compliance requirements, and satisfies the prerequisites for integrating with messaging platforms that require HTTPS webhooks.