推荐语

OpenClaw部署全攻略：从本地到云端，解锁HTTPS安全访问的终极指南，助你轻松跨越生产部署的最后一道门槛。

核心内容：
1. OpenClaw的两种主要部署方式对比：官方安装器与源码部署
2. 不同部署方案的适用场景与核心优势解析
3. 实现HTTPS安全访问的完整技术路径详解

杨芳贤

53AI创始人/腾讯云(TVP)最具价值专家

在开源AI助手的生态中，OpenClaw凭借其强大的本地化能力和丰富的工具生态，已成为众多技术爱好者和开发者的首选平台。然而，从本地体验走向生产部署，配置HTTPS安全访问往往是许多用户面临的最后一道门槛。本文将系统梳理OpenClaw的各类部署方式，深入对比不同方案的适用场景，并详细解析实现HTTPS访问的完整技术路径。

一、部署方式全景对比

OpenClaw提供了多元化的部署选择，从快速上手到企业级生产环境，每种方案都有其独特的价值定位。基于官方文档和社区实践，我们首先建立整体认知框架。

1. 官方安装器部署（推荐入门）

适用场景：个人用户快速体验、本地开发环境、学习探索

核心优势：

• 一键安装，自动化处理环境依赖（Node.js 22+、Git等）
• 智能检测操作系统（macOS、Linux、WSL2）
• 支持npm和git两种安装模式灵活切换
• 自动处理Linux系统下的npm权限问题（自动切换到~/.npm-global）

安装命令：

# macOS/Linux/WSL2
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex

# 中国用户使用镜像加速
curl -fsSL https://open-claw.org.cn/install-cn.sh | bash

关键技术细节：

• 安装器会自动运行openclaw doctor --non-interactive进行健康检查
• 默认设置SHARP_IGNORE_GLOBAL_LIBVIPS=1避免原生模块编译问题
• 检测到已有源码仓库时会提示选择更新或迁移到全局npm安装

2. 源码部署（开发者首选）

适用场景：贡献者开发、定制化需求、深度集成项目

核心优势：

• 完全控制版本和功能
• 可进行源码级别的修改和调试
• 支持最新的前沿功能
• 便于理解系统架构和工作原理

部署步骤：

# 1. 克隆仓库（推荐Gitee镜像加速）
git clone https://gitee.com/OpenClaw-CN/openclaw-cn.git
cd openclaw-cn

# 2. 配置pnpm镜像源（关键！）
pnpm config set registry https://registry.npmmirror.com/

# 3. 安装依赖与构建
pnpm install
pnpm ui:build    # 构建前端界面
pnpm build       # 构建核心服务

# 4. 初始化配置
pnpm openclaw onboard --install-daemon

# 5. 启动服务
pnpm openclaw gateway      # 启动网关
pnpm openclaw dashboard    # 打开管理界面

注意事项：

• 必须使用Node.js >= 22.0.0
• 强制推荐使用pnpm而非npm（处理依赖树更稳定）
• 构建过程需要较长时间，首次运行请耐心等待

3. Docker容器化部署（运维友好）

适用场景：生产环境、多服务协同、快速扩展、云原生架构

核心优势：

• 环境隔离，避免依赖冲突
• 部署一致性，一次构建到处运行
• 易于备份和迁移
• 资源管控精确

快速启动：

# 使用官方镜像
docker run -d --name openclaw \
  -p 18789:18789 \
  -v openclaw-data:/root/.openclaw \
  -e OPENCLAW_GATEWAY_TOKEN=your-secure-token \
  --restart unless-stopped \
  ghcr.io/1186258278/openclaw-zh:latest

Docker Compose配置：

version: '3.8'
services:
openclaw:
    image: ghcr.io/1186258278/openclaw-zh:latest
    container_name: openclaw
    ports:
      - "18789:18789"
    volumes:
      - openclaw-data:/root/.openclaw
    environment:
      - OPENCLAW_GATEWAY_TOKEN=your-secure-token
      - TZ=Asia/Shanghai
    restart: unless-stopped
    
volumes:
openclaw-data:

4. 云服务器一键部署（最简单方案）

适用场景：快速上线、非技术用户、小团队使用、测试环境

主流云服务提供商：

• 阿里云轻量应用服务器：提供OpenClaw专属镜像，预置Node.js 22和所有依赖
• 腾讯云Lighthouse：一键部署方案，开箱即用
• Vultr：详细的Docker Compose部署文档

阿里云部署流程：

1. 选择"OpenClaw（原Moltbot/Clawdbot）"镜像
2. 配置服务器规格（推荐2vCPU+2GiB内存）
3. 一键放通18789端口
4. 绑定阿里云百炼API-Key
5. 通过http://服务器IP:18789访问

部署方式对比表

二、HTTPS访问：安全上下文配置详解

OpenClaw的Web控制界面基于Web Crypto API实现设备身份验证，这要求浏览器必须在**安全上下文（Secure Context）**中运行。具体而言，安全上下文仅存在于以下两种情况：

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

这也是为何直接通过http://公网IP:18789访问时会报错"disconnected (1008): control ui requires HTTPS or localhost (secure context)"的根本原因。

方案一：Nginx反向代理 + Let's Encrypt（生产环境推荐）

这是最成熟、最安全的生产级解决方案，适用于域名已解析到服务器的场景。

步骤1：安装Nginx和Certbot

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

# CentOS/RHEL
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反向代理创建配置文件/etc/nginx/sites-available/openclaw：

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;
    
    # SSL证书配置（由Certbot自动填充）
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    
    # SSL安全配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512;
    ssl_prefer_server_ciphers off;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    
    # 安全头
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    
    # WebSocket支持（关键配置）
    map $http_upgrade $connection_upgrade {
        default upgrade;
        '' close;
    }
    
    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        
        # WebSocket关键头
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $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_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
        
        # 超时配置（长时间连接）
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
        proxy_connect_timeout 75s;
        
        # 缓冲配置（实时交互）
        proxy_buffering off;
        proxy_buffer_size 4k;
        proxy_buffers 8 4k;
    }
}

步骤3：启用配置并申请证书

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

# 测试配置
sudo nginx -t

# 重载Nginx
sudo systemctl reload nginx

# 申请Let's Encrypt证书（自动配置HTTPS）
sudo certbot --nginx -d your-domain.com

Certbot会自动修改Nginx配置文件，添加SSL证书路径，并设置自动续期任务。

步骤4：配置OpenClaw信任代理

编辑~/.openclaw/openclaw.json，添加信任代理配置：

{
  gateway: {
    bind: "loopback",
    port: 18789,
    
    // 关键：配置信任的代理IP
    trustedProxies: ["127.0.0.1", "::1"],
    
    // 启用Token认证
    auth: {
      mode: "token",
      token: "your-secure-token-here"
    },
    
    // 允许跨域访问（可选）
    controlUi: {
      allowedOrigins: ["https://your-domain.com"]
    }
  }
}

步骤5：重启OpenClaw网关

# npm安装环境
openclaw gateway restart

# Docker环境
docker restart openclaw

验证访问： 打开浏览器访问https://your-domain.com，输入配置的token即可成功登录。

方案二：Caddy反向代理（最简单HTTPS方案）

Caddy是一款自动HTTPS的Web服务器，配置极其简单，推荐给追求效率的用户。

安装Caddy：

# Ubuntu/Debian
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

配置Caddyfile： 编辑/etc/caddy/Caddyfile：

your-domain.com {
    reverse_proxy localhost:18789
}

就这么简单！Caddy会自动：

1. 从Let's Encrypt申请SSL证书
2. 自动配置HTTPS
3. 处理HTTP到HTTPS的重定向
4. 正确配置WebSocket连接

重启Caddy：

sudo systemctl restart caddy

配置OpenClaw（同方案一的步骤4）。

方案三：OpenClaw内置TLS

OpenClaw自身支持直接配置TLS证书，无需额外的反向代理。

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

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

使用正式证书：

{
  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"
    }
  }
}

注意事项：

• 自签名证书会导致浏览器显示安全警告，需手动信任
• 生产环境强烈建议使用Let's Encrypt等正式CA签发的证书

方案四：Tailscale Serve（最安全远程访问）

如果你需要跨网络访问，Tailscale提供了最简洁的解决方案。

步骤1：安装并登录Tailscale

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

步骤2：配置OpenClaw

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

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

优势：

• 自动HTTPS（使用Tailscale证书）
• 内置身份认证（基于Tailscale账户）
• 无需暴露端口到公网
• 跨NAT穿透无需端口映射

方案五：内网访问的Token认证（最简单）

如果仅在局域网或内网环境使用，可以配置Token认证绕过HTTPS要求。

配置OpenClaw：

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

访问方式： 通过http://内网IP:18789访问，在登录界面输入token即可连接。

⚠️ 安全警告：

• 此方案仅适用于受信任的内网环境
• Token明文传输，存在中间人攻击风险
• 严禁在公网环境使用

三、高级安全配置

1. 可信代理认证（企业级单点登录）

对于企业环境，可以将认证完全委托给反向代理（如Pomerium、OAuth2-Proxy），实现SSO单点登录。

配置OpenClaw：

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1", "172.17.0.1"],
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        // 包含已认证用户身份的头
        userHeader: "x-forwarded-user",
        // 必须存在的头（代理验证）
        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],
        // 限制为特定用户（可选）
        allowUsers: ["nick@example.com", "admin@company.org"]
      }
    }
  }
}

Nginx + OAuth2-Proxy配置示例：

location / {
    auth_request /oauth2/auth;
    auth_request_set $user $upstream_http_x_auth_request_email;
    
    proxy_pass http://openclaw:18789;
    proxy_set_header X-Auth-Request-Email $user;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

2. 防火墙与安全组配置

系统防火墙（UFW）：

# 默认拒绝所有入站流量
sudo ufw default deny incoming

# 允许SSH（修改后的端口）
sudo ufw allow 20222/tcp

# 允许HTTP和HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# 启用防火墙
sudo ufw enable

云服务器安全组：

• 入站规则：仅放行80（HTTP）、443（HTTPS）、修改后的SSH端口
• 拒绝所有其他流量，包括OpenClaw的18789端口
• 出站规则：允许所有（或按需限制）

3. 主动防御：Fail2Ban配置

# 安装Fail2Ban
sudo apt install -y fail2ban

# 创建本地配置
sudo nano /etc/fail2ban/jail.local

添加以下内容：

[sshd]
enabled = true
port = 20222
maxretry = 3
bantime = 86400
findtime = 600

[nginx-http-auth]
enabled = true
maxretry = 3
bantime = 3600

启动Fail2Ban：

sudo systemctl enable fail2ban
sudo systemctl start fail2ban

四、常见问题排查

问题1：WebSocket连接失败

症状：连接频繁断开，无法实时交互原因：反向代理未正确配置WebSocket升级头解决方案：确保Nginx配置中包含以下关键头：

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

问题2：证书续期失败

症状：证书过期后无法访问原因：Certbot自动续期任务异常解决方案：

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

# 检查续期任务
sudo systemctl status certbot.timer

问题3：Proxy headers detected from untrusted address

症状：反向代理访问时报错原因：OpenClaw未配置信任代理IP解决方案：在openclaw.json中添加：

trustedProxies: ["127.0.0.1", "::1"]

问题4：跨域访问被拒绝

症状：通过域名访问时CORS错误原因：未配置允许的源解决方案：在openclaw.json中添加：

controlUi: {
  allowedOrigins: ["https://your-domain.com"]
}

五、总结与最佳实践

OpenClaw的部署方式选择应基于具体场景和需求：

• 快速体验：使用官方安装器，本地localhost访问
• 个人学习：源码部署，深度理解系统架构
• 生产环境：Docker + Nginx + HTTPS，企业级安全配置
• 团队协作：云服务器一键部署 + HTTPS配置
• 远程访问：Tailscale Serve，自动HTTPS + 身份认证
• 企业内网：可信代理认证，集成现有SSO系统

HTTPS配置的关键要点：

1. 必须使用HTTPS：公网部署的底线，保障数据传输安全
2. 正确配置WebSocket：确保Upgrade和Connection头的正确传递
3. 信任代理配置：配置trustedProxies避免代理头错误
4. 证书自动续期：Let's Encrypt证书90天有效期，务必配置自动续期
5. 安全第一：宁可配置过度，也不可疏忽安全细节

OpenClaw作为开源AI助手的杰出代表，其部署和HTTPS配置的复杂性恰恰体现了其在安全性和灵活性方面的深厚考量。掌握这些技术细节，不仅能让你充分发挥OpenClaw的强大能力，更能为你的AI应用构建坚实的安全基石。在这个数据安全日益重要的时代，正确的部署配置比功能本身更为重要。

关键词标签：#OpenClaw部署# #HTTPS配置# #反向代理# #Docker部署# #AI助手安全#

OpenClaw社区群：OpenClaw 铁粉群

友情提示：扫码入群！如有咨询，请加管理员微信号：winteroak，管理员单独邀请入群