# 腾讯云CVM部署OpenClaw全记录：从零到一的踩坑与解法

OpenClaw 是一个强大的AI网关，支持多平台接入与自动化工作流。本文详细记录了在腾讯云CVM（TencentOS）上部署OpenClaw的完整过程，包括环境配置、服务管理、Nginx反向代理、SSL证书申请等环节，以及遇到的各类典型问题与解决方案。

一、背景与目标

OpenClaw（原名Clawdbot）是一款开源的AI助手网关，可接入TG、WhatsApp、Discord等平台，并提供Web控制台用于模型配置、技能管理和会话监控。本文将分享如何在腾讯云CVM上从零开始部署OpenClaw，并最终通过子域名安全访问。

服务器环境：腾讯云CVM，系统TencentOS Server 3.1（基于CentOS 8），2核4GB。
目标：以非root用户运行OpenClaw，使用Nginx反向代理，支持HTTPS，并为后续添加其他子域名（如API服务）预留空间。

二、环境准备与基础安装

2.1 更新系统与安装必要工具

sudo yum update -y
sudo yum install curl git vim -y

2.2 安装Node.js（OpenClaw需要22+版本）

curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo yum install nodejs -y
node -v   # 应显示v22.x

2.3 配置npm国内镜像（可选，加速）

npm config set registry https://registry.npmmirror.com

2.4 安装OpenClaw

curl -fsSL https://openclaw.ai/install.sh | bash

安装后，openclaw命令应全局可用。若提示命令未找到，可手动添加环境变量或使用绝对路径。

三、安全运行：创建普通用户并配置服务

3.1 创建专用用户`claw`

sudo useradd claw
sudo passwd claw

将用户加入管理员组（TencentOS使用wheel组，而非sudo）：

sudo usermod -aG wheel claw

3.2 复制配置文件并授权

如果之前以root运行过openclaw onboard，配置保存在/root/.openclaw。将其迁移到claw用户：

sudo cp -r /root/.openclaw /home/claw/
sudo chown -R claw:claw /home/claw/.openclaw
sudo chmod -R 700 /home/claw/.openclaw

如果尚未配置，可先以claw用户运行openclaw onboard完成初始化。

3.3 创建系统级systemd服务（绕过用户服务限制）

TencentOS不支持systemctl --user，因此需要创建系统服务。

创建/etc/systemd/system/openclaw.service：

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
User=claw
WorkingDirectory=/home/claw
ExecStart=/home/claw/.nvm/versions/node/v22.22.1/bin/openclaw gateway start --foreground
Restart=on-failure
RestartSec=10
Environment="PATH=/home/claw/.nvm/versions/node/v22.22.1/bin:/usr/local/bin:/usr/bin:/bin"

[Install]
WantedBy=multi-user.target

注意：ExecStart中的路径需根据实际安装位置调整。若使用nvm安装，通常位于/home/claw/.nvm/versions/node/vXX/bin/openclaw。

启动并启用服务：

sudo systemctl daemon-reload
sudo systemctl enable openclaw.service
sudo systemctl start openclaw.service
sudo systemctl status openclaw.service

3.4 配置OpenClaw网关模式与绑定

OpenClaw新版本要求显式设置gateway.mode和bind模式。由于使用Nginx反向代理，推荐将bind设为loopback（仅监听127.0.0.1），避免直接暴露端口。

以claw用户执行：

openclaw config set gateway.mode local
openclaw config set gateway.bind loopback
openclaw doctor --fix

若需要允许特定域名访问Web UI，还需配置allowedOrigins（但对于loopback模式，此配置非必需，因为请求都来自Nginx）。

mode模式

模式	说明	适用场景
`local`	必须显式设置。网关在本机运行并负责所有 Agent 状态、渠道连接和会话管理。这是自部署场景的唯一选择。	腾讯云 CVM 上独立运行，管理所有对话和技能。
`remote`	网关运行在远程主机，当前设备仅作为 Node（执行端）连接到远程网关。	多设备分布式部署，例如 macOS 电脑连接到 VPS 上的网关。

Bind 模式（`gateway.bind`）

模式	行为	使用场景	安全等级
`loopback`	只监听 `127.0.0.1`	SSH 隧道访问、本机使用	🔒 最安全
`lan`	监听所有网络接口	直接公网/LAN 访问	⚠️ 需配合认证和白名单
`tailnet`	只监听 Tailscale 接口	通过 Tailscale VPN 访问	🔒 安全
`auto`	自动检测环境决定	通用场景，不推荐生产环境	取决于环境
`custom`	自定义绑定地址	高级场景（需额外配置）	取决于配置

四、Nginx反向代理与HTTPS配置

4.1 安装Nginx

sudo yum install nginx -y
sudo systemctl enable nginx
sudo systemctl start nginx

4.2 配置子域名`claw.你的域名.com`

创建/etc/nginx/conf.d/claw.conf：

server {
    listen 80;
    server_name claw.你的域名.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name claw.你的域名.com;

    ssl_certificate /etc/letsencrypt/live/claw.你的域名.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/claw.你的域名.com/privkey.pem;

    # 可选：HTTP基本认证
    # auth_basic "Private Access";
    # auth_basic_user_file /etc/nginx/.htpasswd;

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

4.3 申请SSL证书（Let's Encrypt）

使用Certbot自动获取证书。由于主域名你的域名.com已备案，且claw.你的域名.com作为子域名可以共用备案，但需要确保80端口可访问。若遇到验证失败，可改用DNS验证。

使用 Certbot 自动化申请 SSL 证书

这是目前最简单、最专业的方法。

安装 Certbot 和 Nginx 插件：

Bash

sudo apt install certbot python3-certbot-nginx -y

执行申请命令： 把下面的 example.com 换成你真实的域名。

Bash
```
sudo certbot --nginx -d example.com -d www.example.com
```

HTTP-01验证（需80端口）：

sudo certbot --nginx -d claw.你的域名.com

DNS-01验证（推荐，避免端口问题）：

sudo certbot certonly --manual --preferred-challenges dns -d claw.你的域名.com

按照提示添加TXT记录，验证成功后手动配置Nginx的SSL部分（Certbot会提示）。

五、踩坑记录与解决方案

5.1 systemd用户服务不可用

现象：运行openclaw onboard时提示Systemd user services are unavailable。

原因：TencentOS未启用systemd用户服务支持。

解决：创建系统级systemd服务（见3.3节），避免依赖--user。

5.2 端口只监听127.0.0.1，无法公网访问

现象：ss -tulnp | grep 18789显示127.0.0.1:18789。

原因：新版本OpenClaw使用bind模式，默认可能为loopback。

解决：若通过Nginx代理，这正是我们期望的（安全）。若需直接暴露，可设置为lan并配置allowedOrigins。

5.3 WebSocket连接断开（1006错误）

现象：登录Web控制台后提示disconnected (1006): no reason。

原因：Nginx未正确转发Upgrade和Connection头。

解决：确保Nginx配置中包含：

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

同时，若使用了$connection_upgrade变量，需在http块内定义map：

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

或者直接硬编码"upgrade"。

5.4 Certbot验证失败（404）

现象：为子域名申请证书时，Let's Encrypt返回404。

原因：Nginx未正确响应/.well-known/acme-challenge/路径。

解决：在Nginx配置中添加：

location ^~ /.well-known/acme-challenge/ {
    alias /var/www/html/.well-known/acme-challenge/;
}

并创建目录、赋予权限。若80端口被运营商屏蔽（例如未备案域名），改用DNS-01验证。

5.5 域名备案与Let's Encrypt的关系

主域名备案后，子域名无需再次备案。但如果80端口因未备案被屏蔽，仍会影响HTTP-01验证。此时DNS-01验证是更可靠的选择。

六、安全加固建议

使用非root用户运行服务：已实现。
网关绑定loopback：避免端口暴露，所有访问经Nginx。
Nginx增加基本认证：可添加auth_basic，额外保护一层。
防火墙限制：仅开放80、443端口（安全组配置）。
定期更新：使用openclaw update保持最新版本。

七、总结与展望

通过以上步骤，我们成功在腾讯云CVM上部署了OpenClaw，并实现了通过HTTPS安全访问。整个过程涵盖了环境配置、服务管理、反向代理、证书申请等多个环节，并解决了一系列典型问题。

后续可以在此基础上：

接入更多聊天平台（如TG、飞书）
开发自定义技能（Skills）
为其他子域名（如api.你的域名.com）配置独立服务

OpenClaw作为AI网关，其灵活性和可扩展性为我们提供了广阔的想象空间。希望本文能为你的部署之路提供参考。

附：常用命令速查

操作	命令
查看OpenClaw状态	`systemctl status openclaw.service`
重启服务	`systemctl restart openclaw.service`
查看日志	`journalctl -u openclaw.service -f`
修改配置	`openclaw config set <key> <value>`
获取Token	`openclaw config get gateway.auth.token`

本文基于OpenClaw 2026.3.13版本，系统环境TencentOS Server 3.1。部署时间：2026年3月。

posted @ 2026-03-22 21:08 转角90 阅读(854) 评论(0) 收藏举报

刷新页面返回顶部

转角90