OpenClaw配置SSL证书与HTTPS加密

前言

OpenClaw Gateway 默认使用 HTTP 协议运行在 18789 端口。在生产环境中，特别是 Web Dashboard 对外暴露或使用 Webhook 接收消息时，HTTPS 加密是安全运营的基本要求。本文将介绍三种为 OpenClaw 配置 SSL 的方案。

一、方案选择

方案	适用场景	复杂度	推荐度
Nginx 反向代理 + Let's Encrypt	生产环境，有域名	中	最推荐
OpenClaw 内置 SSL	简单部署，快速启用	低	适合测试
自签名证书	内网环境，无域名	低	仅限内网

二、方案一：Nginx 反向代理（推荐）

这是生产环境的推荐方案，由 Nginx 处理 SSL 终结，OpenClaw 保持 HTTP 运行。

2.1 安装 Nginx 和 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 配置 Nginx 反向代理

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 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 超时设置（AI 回复可能较慢）
        proxy_read_timeout 120s;
        proxy_send_timeout 120s;
    }
}

# 启用站点配置
sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

2.3 申请 Let's Encrypt 证书

# 自动申请并配置 SSL
sudo certbot --nginx -d openclaw.yourdomain.com

# 按提示操作：
# 1. 输入邮箱地址（用于证书过期提醒）
# 2. 同意服务条款
# 3. 选择是否将 HTTP 重定向到 HTTPS（建议选是）

Certbot 会自动修改 Nginx 配置，添加 SSL 相关设置。完成后的配置类似：

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 证书自动续期

Let's Encrypt 证书有效期为 90 天，Certbot 默认配置了自动续期定时任务：

# 检查续期定时任务
sudo systemctl list-timers | grep certbot

# 手动测试续期
sudo certbot renew --dry-run

# 如果自动续期未配置，手动添加 crontab
# 每天凌晨 3 点尝试续期
echo "0 3 * * * certbot renew --quiet --post-hook 'systemctl reload nginx'" | sudo tee -a /etc/crontab

2.5 SSL 安全加固

在 Nginx 配置中添加安全头：

# 在 server 块中添加
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;

# 仅允许强加密算法
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;

三、方案二：OpenClaw 内置 SSL

OpenClaw 支持直接配置 SSL 证书，无需 Nginx 中间层。

3.1 配置内置 SSL

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

3.2 使用 Let's Encrypt 证书

# 使用 standalone 模式申请证书（需要临时关闭占用 80 端口的服务）
sudo certbot certonly --standalone -d openclaw.yourdomain.com

# 证书文件位置
# /etc/letsencrypt/live/openclaw.yourdomain.com/fullchain.pem
# /etc/letsencrypt/live/openclaw.yourdomain.com/privkey.pem

由于 Let's Encrypt 证书文件默认只有 root 可读，需要设置权限：

# 方案一：将 openclaw 用户加入 ssl-cert 组
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/

# 方案二：复制证书到 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 证书续期后自动重载

# 创建续期钩子脚本
sudo nano /etc/letsencrypt/renewal-hooks/post/openclaw-reload.sh

#!/bin/bash
# 复制新证书到 OpenClaw 目录
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

# 重载 OpenClaw 以加载新证书
sudo -u openclaw openclaw restart

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

四、方案三：自签名证书

适用于内网部署或测试环境。

4.1 生成自签名证书

# 创建证书目录
mkdir -p ~/.openclaw/ssl && cd ~/.openclaw/ssl

# 生成私钥和证书（有效期365天）
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout privkey.pem \
  -out fullchain.pem \
  -subj "/CN=openclaw.local/O=OpenClaw/C=CN"

# 设置权限
chmod 600 privkey.pem
chmod 644 fullchain.pem

4.2 配置 OpenClaw 使用自签名证书

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

4.3 客户端信任自签名证书

浏览器访问时会提示不安全，可以手动添加信任：

# Linux：添加到系统信任列表
sudo cp ~/.openclaw/ssl/fullchain.pem /usr/local/share/ca-certificates/openclaw.crt
sudo update-ca-certificates

# macOS：添加到钥匙串
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/.openclaw/ssl/fullchain.pem

五、验证 HTTPS 配置

配置完成后，验证 HTTPS 是否正常工作：

# 测试 HTTPS 连接
curl -v https://openclaw.yourdomain.com/health

# 检查证书信息
openssl s_client -connect openclaw.yourdomain.com:443 -servername openclaw.yourdomain.com </dev/null 2>/dev/null | openssl x509 -noout -dates -subject

# 使用 SSL Labs 在线检测（公网可访问时）
# https://www.ssllabs.com/ssltest/analyze.html?d=openclaw.yourdomain.com

六、常见问题

Q: 配置 HTTPS 后 WebSocket 连接失败？

确保 Nginx 配置中包含 WebSocket 支持的 Upgrade 和 Connection 头。

Q: 证书续期后服务没有加载新证书？

OpenClaw 不会自动监测证书文件变化，续期后需要执行 openclaw restart 或配置续期钩子脚本。

Q: 混合使用 HTTP 和 HTTPS？

可以同时监听两个端口，但建议在生产环境强制 HTTPS，通过 301 重定向将 HTTP 请求引导到 HTTPS。

正确配置 SSL 证书后，你的 OpenClaw 服务将获得传输层加密保护，满足安全合规要求，同时也是接入某些需要 HTTPS Webhook 的消息平台的前提条件。