Skip to main content

Custom Domain

Access your ClawBook dashboard via a custom domain like ai.yourdomain.com instead of an IP address.

Prerequisites​

  • Domain name you own
  • Access to DNS management
  • ClawBook VPS with public IP

Quick Setup​

Step 1: Create DNS Record​

In your domain registrar/DNS provider, create an A record:

TypeNameValueTTL
AaiYOUR_VPS_IP300

Example:

Type: A
Name: ai (for ai.yourdomain.com)
Value: 203.0.113.50
TTL: 300 (5 minutes)

Step 2: Wait for DNS Propagation​

DNS changes can take 5 minutes to 48 hours. Check propagation:

# Check from your computer
dig ai.yourdomain.com

# Or use online tool
# https://dnschecker.org

Step 3: Configure ClawBook​

  1. SSH into your VPS:

    ssh root@YOUR_VPS_IP

  2. Edit the configuration:

    nano /etc/openclaw/config.yaml

  3. Add your domain:

    server:
      domain: ai.yourdomain.com
      enable_ssl: true

  4. Run the domain setup:

    clawbook-setup domain ai.yourdomain.com

Step 4: Obtain SSL Certificate​

ClawBook uses Let's Encrypt for free SSL:

clawbook-ssl setup ai.yourdomain.com

This will:

  • Verify domain ownership
  • Obtain SSL certificate
  • Configure auto-renewal
  • Update Caddy configuration

Step 5: Verify​

Open https://ai.yourdomain.com - you should see the login page with a valid SSL certificate.

Multiple Domains​

Adding Additional Domains​

You can have multiple domains pointing to your dashboard:

clawbook-ssl setup dashboard.example.com
clawbook-ssl setup chat.example.org

Primary Domain​

Set your preferred primary domain:

# /etc/openclaw/config.yaml
server:
  domain: ai.yourdomain.com
  aliases:
    - dashboard.example.com
    - chat.example.org

Subdomain Examples​

SubdomainPurposeExample
ai.Generalai.company.com
assistant.Descriptiveassistant.company.com
claw.Brandclaw.company.com
chat.Functionchat.company.com

Cloudflare Configuration​

If using Cloudflare:

DNS Settings​

  1. Add A record for your subdomain
  2. Set proxy status to DNS only (gray cloud) initially
  3. After SSL is working, you can enable proxy (orange cloud)

SSL/TLS Settings​

If using Cloudflare proxy:

  1. Go to SSL/TLS → Overview
  2. Set mode to Full (strict)
  3. Ensure origin has valid certificate (Let's Encrypt)

Page Rules (Optional)​

Force HTTPS:

URL: http://ai.yourdomain.com/*
Setting: Always Use HTTPS

Reverse Proxy Setup​

Using Nginx (Advanced)​

If you have an existing Nginx server:

# /etc/nginx/sites-available/clawbook
server {
    listen 80;
    server_name ai.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name ai.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/ai.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ai.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8443;
        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;
    }
}

Using Traefik​

# docker-compose.yml or traefik config
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.clawbook.rule=Host(`ai.yourdomain.com`)"
  - "traefik.http.routers.clawbook.tls=true"
  - "traefik.http.routers.clawbook.tls.certresolver=letsencrypt"

SSL Certificate Management​

Checking Certificate Status​

clawbook-ssl status

# Output:
# Domain: ai.yourdomain.com
# Expires: 2026-04-30 (90 days)
# Auto-renew: Enabled
# Issuer: Let's Encrypt

Manual Renewal​

Certificates auto-renew, but you can force renewal:

clawbook-ssl renew ai.yourdomain.com

Using Your Own Certificate​

If you have a certificate from another provider:

clawbook-ssl import \
  --cert /path/to/cert.pem \
  --key /path/to/key.pem \
  --domain ai.yourdomain.com

Webhook URLs​

After setting up a custom domain, update webhook URLs:

WhatsApp Business API​

https://ai.yourdomain.com/webhook/whatsapp

Telegram​

https://ai.yourdomain.com/webhook/telegram

Troubleshooting​

DNS Not Resolving​

# Check DNS
dig ai.yourdomain.com

# Should show your IP
# ai.yourdomain.com.  300  IN  A  203.0.113.50

If not resolving:

  • Wait for DNS propagation (up to 48 hours)
  • Check DNS record is correct
  • Try different DNS server: dig @8.8.8.8 ai.yourdomain.com

SSL Certificate Error​

# Check certificate
clawbook-ssl test ai.yourdomain.com

# Common issues:
# - DNS not propagated yet
# - Port 80 blocked (needed for verification)
# - Rate limit exceeded

Connection Refused​

Ensure ports are open:

ufw allow 80/tcp
ufw allow 443/tcp
ufw status

Certificate Renewal Failed​

Check logs:

cat /var/log/openclaw/ssl.log

Manual fix:

certbot renew --force-renewal
systemctl restart caddy

Removing Custom Domain​

To go back to IP-only access:

clawbook-ssl remove ai.yourdomain.com

Edit config:

# /etc/openclaw/config.yaml
server:
  domain: null
  enable_ssl: false

Restart:

systemctl restart openclaw

Next Steps​