Skip to main content

SSL Certificates

SSL certificates encrypt traffic between users and your ClawBook dashboard. This guide covers certificate options and management.

Certificate Options​

OptionCostEffortBest For
Let's EncryptFreeLowMost users
Self-SignedFreeLowTesting only
Commercial CA$10-100/yrMediumEnterprise
CloudflareFreeLowUsing Cloudflare

Free, automated SSL certificates that renew automatically.

Prerequisites​

  • Custom domain configured
  • Port 80 accessible (for verification)
  • DNS pointing to your VPS

Quick Setup​

clawbook-ssl setup yourdomain.com

This command:

  1. Verifies domain ownership via HTTP challenge
  2. Obtains certificate from Let's Encrypt
  3. Configures Caddy for HTTPS
  4. Sets up auto-renewal

Manual Setup​

If the quick command fails:

# Install certbot
apt install certbot -y

# Obtain certificate
certbot certonly --standalone -d yourdomain.com

# Configure Caddy
nano /etc/caddy/Caddyfile

Caddyfile configuration:

yourdomain.com {
    tls /etc/letsencrypt/live/yourdomain.com/fullchain.pem /etc/letsencrypt/live/yourdomain.com/privkey.pem
    reverse_proxy localhost:8443
}

Restart Caddy:

systemctl restart caddy

Auto-Renewal​

Let's Encrypt certificates expire after 90 days. Auto-renewal is configured:

# Check renewal timer
systemctl status certbot.timer

# Test renewal
certbot renew --dry-run

Wildcard Certificates​

For multiple subdomains (*.yourdomain.com):

certbot certonly --manual --preferred-challenges dns \
  -d "*.yourdomain.com" -d "yourdomain.com"

You'll need to add DNS TXT records for verification.

Self-Signed Certificates​

Only for testing or internal use. Browsers will show warnings.

Generate Self-Signed Certificate​

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/ssl/private/clawbook.key \
  -out /etc/ssl/certs/clawbook.crt \
  -subj "/CN=localhost"

Configure​

# /etc/openclaw/config.yaml
server:
  ssl:
    enabled: true
    certificate: /etc/ssl/certs/clawbook.crt
    key: /etc/ssl/private/clawbook.key

Commercial Certificates​

For enterprise requirements or extended validation.

Generating CSR​

openssl req -new -newkey rsa:2048 -nodes \
  -keyout domain.key \
  -out domain.csr

Fill in details when prompted:

  • Country Name (2 letter code): US
  • State: California
  • Locality: San Francisco
  • Organization: Your Company
  • Common Name: yourdomain.com

Installing Certificate​

After receiving certificate from CA:

# Combine certificate and chain
cat domain.crt intermediate.crt > fullchain.crt

# Install
clawbook-ssl import \
  --cert /path/to/fullchain.crt \
  --key /path/to/domain.key \
  --domain yourdomain.com

Certificate Management​

Viewing Certificate Info​

clawbook-ssl status

# Output:
# Domain: yourdomain.com
# Issuer: Let's Encrypt
# Valid From: 2026-01-30
# Valid Until: 2026-04-30
# Auto-Renew: Enabled
# Days Remaining: 90

Testing Certificate​

# Local test
clawbook-ssl test yourdomain.com

# Or use openssl
openssl s_client -connect yourdomain.com:443 -servername yourdomain.com

Online Testing​

TLS Configuration​

Security Settings​

# /etc/openclaw/config.yaml
server:
  ssl:
    min_version: TLS1.2
    ciphers:
      - TLS_AES_128_GCM_SHA256
      - TLS_AES_256_GCM_SHA384
      - TLS_CHACHA20_POLY1305_SHA256
    prefer_server_ciphers: true
    hsts: true
    hsts_max_age: 31536000

HSTS (HTTP Strict Transport Security)​

Force HTTPS for all connections:

Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

Enabled by default in ClawBook.

Troubleshooting​

Certificate Not Trusted​

Causes:

  • Self-signed certificate
  • Incomplete certificate chain
  • Expired certificate

Fix:

# Check certificate chain
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt fullchain.crt

# Rebuild chain
cat domain.crt intermediate.crt root.crt > fullchain.crt

Let's Encrypt Rate Limits​

Limits:

  • 50 certificates per domain per week
  • 5 duplicate certificates per week
  • 300 pending authorizations per account

If rate limited, wait or use staging:

certbot certonly --staging -d yourdomain.com

Port 80 Blocked​

Let's Encrypt HTTP verification requires port 80:

# Check if port 80 is open
ufw status
ufw allow 80/tcp

# Or use DNS verification instead
certbot certonly --manual --preferred-challenges dns -d yourdomain.com

Auto-Renewal Failed​

Check logs:

cat /var/log/letsencrypt/letsencrypt.log

Force renewal:

certbot renew --force-renewal
systemctl restart caddy

Certificate Chain Issues​

# Download intermediate certificates
wget https://letsencrypt.org/certs/lets-encrypt-r3.pem

# Test full chain
openssl s_client -connect yourdomain.com:443 -showcerts

Certificate Monitoring​

Expiration Alerts​

Set up alerts before expiration:

# /etc/openclaw/config.yaml
monitoring:
  ssl:
    check_interval: daily
    alert_days_before: [30, 14, 7, 1]
    alert_email: admin@yourdomain.com

External Monitoring​

Best Practices​

  1. Use Let's Encrypt - Free, automated, trusted
  2. Enable auto-renewal - Never expire unexpectedly
  3. Monitor expiration - Set up alerts
  4. Use strong TLS - TLS 1.2 minimum
  5. Enable HSTS - Force HTTPS always
  6. Test regularly - Use SSL Labs quarterly

Next Steps​