OpenClaw 中文版

主题

云服务器 SSL 证书部署 ​

当您在云服务器上部署 Openclaw 并尝试从浏览器访问控制界面时，可能会遇到以下错误：

disconnected (1008): control ui requires HTTPS or localhost (secure context)

这是因为 Openclaw 的 Web 控制界面需要 安全上下文（Secure Context） 才能正常工作。浏览器只在以下情况下提供安全上下文：

  1. 通过 localhost 或 127.0.0.1 访问
  2. 通过 HTTPS 访问

本文档将介绍几种解决方案。

方案一：使用反向代理 + Let's Encrypt（推荐） ​

这是最推荐的生产环境方案，使用 Nginx 作为反向代理，配合 Let's Encrypt 免费证书。

前提条件 ​

  • 一个指向您服务器 IP 的域名
  • 服务器开放 80 和 443 端口

步骤 1：安装 Nginx 和 Certbot ​

Ubuntu/Debian：

bash
sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx

CentOS/RHEL：

bash
sudo yum install -y epel-release
sudo yum install -y nginx certbot python3-certbot-nginx
sudo systemctl enable nginx
sudo systemctl start nginx

步骤 2：配置 Nginx 反向代理 ​

创建 Nginx 配置文件：

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

添加以下内容（将 your-domain.com 替换为您的域名）：

nginx
server {
    listen 80;
    server_name your-domain.com;

    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;
        proxy_read_timeout 86400;
    }
}

启用配置：

bash
sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

步骤 3：申请 Let's Encrypt 证书 ​

bash
sudo certbot --nginx -d your-domain.com

按提示操作，Certbot 会自动配置 HTTPS 并设置自动续期。

步骤 4：配置 Openclaw ​

编辑 ~/.openclaw/openclaw.json：

json5
{
  gateway: {
    // 绑定到本地，由 Nginx 代理
    bind: "loopback",
    port: 18789,
    // 配置信任的代理地址
    trustedProxies: ["127.0.0.1"],
    // 启用认证（推荐）
    auth: {
      mode: "token",
      token: "your-secure-token-here"
    }
  }
}

重启 Openclaw：

bash
openclaw gateway

步骤 5：访问控制界面 ​

打开浏览器访问 https://your-domain.com，输入配置的 token 即可。

方案二：使用 Openclaw 内置 TLS ​

Openclaw 支持内置 TLS，可以直接配置证书。

使用自签名证书（开发/测试） ​

json5
{
  gateway: {
    bind: "lan",  // 或 "0.0.0.0"
    port: 18789,
    tls: {
      enabled: true,
      autoGenerate: true  // 自动生成自签名证书
    },
    auth: {
      mode: "token",
      token: "your-secure-token-here"
    }
  }
}

注意： 自签名证书会导致浏览器显示安全警告，需要手动信任。

使用正式证书 ​

json5
{
  gateway: {
    bind: "lan",
    port: 18789,
    tls: {
      enabled: true,
      certPath: "/path/to/fullchain.pem",
      keyPath: "/path/to/privkey.pem"
    },
    auth: {
      mode: "token",
      token: "your-secure-token-here"
    }
  }
}

方案三：使用 Tailscale（简单易用） ​

如果您使用 Tailscale 组网，这是最简单的方案。

步骤 1：安装并登录 Tailscale ​

bash
# Ubuntu/Debian
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

步骤 2：配置 Openclaw ​

json5
{
  gateway: {
    bind: "loopback",
    tailscale: {
      mode: "serve"  // 或 "funnel" 用于公网访问
    },
    auth: {
      allowTailscale: true  // 允许 Tailscale 身份认证
    }
  }
}

步骤 3：访问 ​

通过 Tailscale MagicDNS 地址访问：https://<your-machine>.<tailnet>.ts.net/

方案四：仅开发/测试用 - 禁用安全检查 ​

⚠️ 警告：此方案仅用于开发测试，切勿在生产环境使用！

如果您只是临时测试，可以禁用控制界面的安全检查：

json5
{
  gateway: {
    bind: "lan",
    port: 18789,
    controlUi: {
      // 允许 HTTP 下使用 token 认证
      allowInsecureAuth: true
    },
    auth: {
      mode: "token",
      token: "your-token-here"
    }
  }
}

然后通过 http://your-server-ip:18789 访问。

常见问题 ​

Q: 为什么必须使用 HTTPS？ ​

Openclaw 控制界面使用 Web Crypto API 进行设备身份验证，这些 API 只在安全上下文（Secure Context）下可用。浏览器将 localhost 和 HTTPS 页面视为安全上下文。

Q: 可以使用 IP 地址而不是域名吗？ ​

可以，但需要：

  1. 使用自签名证书（会有浏览器警告）
  2. 或使用方案四的不安全模式

Q: Let's Encrypt 证书如何自动续期？ ​

Certbot 会自动设置定时任务，您可以通过以下命令测试续期：

bash
sudo certbot renew --dry-run

Q: 反向代理后 WebSocket 连接失败？ ​

确保 Nginx 配置中包含 WebSocket 相关的头部设置：

nginx
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Q: 如何配置多个域名？ ​

在 Nginx 配置中添加多个 server_name，然后为每个域名申请证书：

bash
sudo certbot --nginx -d domain1.com -d domain2.com

安全建议 ​

  1. 始终启用认证 - 设置 gateway.auth.mode 为 token 或 password
  2. 使用强密码/Token - 避免使用简单的密码
  3. 限制访问来源 - 如果可能，使用防火墙限制访问 IP
  4. 定期更新证书 - Let's Encrypt 证书有效期 90 天，确保自动续期正常
  5. 保护私钥 - 证书私钥权限应为 600，仅 root 可读

相关文档 ​

基于 MIT 许可发布

Copyright © 2026-present OpenClaw-CN

💬加入微信