No Comments

OpenClaw 混合部署终极详细教程（QQ Channel + 云端 Gateway + 本地多 Node）

OpenClaw 混合部署终极详细教程（云端 Gateway + 本地 Node）

核心架构：云端服务器仅部署 Gateway（控制中枢，24 小时在线），本地电脑仅部署 Node（执行端，负责实际操作本地设备），两者通过加密连接通信，本地无需暴露任何公网端口，安全且稳定。
适用场景：远程控制个人电脑、自动化本地操作（文件管理/浏览器控制/应用操作）、跨设备任务调度。

一、部署前核心认知

  1. 分工明确：
    • Gateway（云端）：只做「指令接收、任务调度、节点管理」，不碰本地设备；
    • Node（本地）：只做「接收 Gateway 指令、执行本地操作」，主动连接云端，无入站端口暴露。
  2. 关键前提：
    • 云端 Gateway 和本地 Node 的 GATEWAY_TOKEN 必须完全一致（身份认证）；
    • 本地 Node 能访问到云端 Gateway 的地址（需确保云端网络放行 18789 端口，或用隧道代理）。

二、前置准备

1. 云端服务器要求

  • 系统：Ubuntu 20.04+/CentOS 7+/Debian 10+（推荐 Ubuntu 22.04）；
  • 配置：2 核 2G 及以上（最低 1 核 1G 也能运行）；
  • 网络：公网 IP，能访问外网，放行 18789 端口（或后续用隧道跳过端口放行）；
  • 预装工具：Docker + Docker Compose（下文会教安装）。

2. 本地电脑要求

  • 系统：Windows 10+/macOS 10.15+/Linux（任意桌面系统）；
  • 网络：能正常上网（无需公网 IP、无需端口映射）；
  • 预装工具：Node.js ≥ 22.x（下文会教安装）。

3. 工具清单（提前准备）

  • 云端：SSH 工具（Xshell/Finalshell/Mac 终端），用于连接云服务器；
  • 本地：文本编辑器（Notepad++/VS Code），用于编写配置文件。

三、云端 Gateway 部署（超详细步骤）

步骤 1：连接云服务器

打开 SSH 工具，输入服务器 IP、用户名（默认 root）、密码，登录云服务器。

步骤 2：安装 Docker + Docker Compose（必装）

Docker 是运行 Gateway 容器的基础，一键执行以下命令（区分系统）：

👉 Ubuntu/Debian 系统

# 更新系统源
apt update -y && apt upgrade -y

# 安装依赖
apt install -y apt-transport-https ca-certificates curl software-properties-common

# 添加 Docker 官方 GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | apt-key add -

# 添加 Docker 源
add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

# 安装 Docker
apt update -y && apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 启动 Docker 并设置开机自启
systemctl start docker && systemctl enable docker

# 验证安装（出现版本号即成功）
docker --version && docker compose version

👉 CentOS 系统

# 更新系统源
yum update -y

# 安装依赖
yum install -y yum-utils device-mapper-persistent-data lvm2

# 添加 Docker 源
yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 安装 Docker
yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 启动 Docker 并设置开机自启
systemctl start docker && systemctl enable docker

# 验证安装
docker --version && docker compose version

步骤 3：创建 Gateway 部署目录

# 创建专属目录（方便管理）
mkdir -p /opt/openclaw/gateway
cd /opt/openclaw/gateway

# 赋予目录权限
chmod -R 755 /opt/openclaw/gateway

步骤 4：编写 Docker Compose 配置文件

创建并编辑 docker-compose.yml 文件（Gateway 的核心配置）：

# 用 vim 编辑文件（新手也可先用 nano，命令：nano docker-compose.yml）
vim docker-compose.yml

按下 i 进入编辑模式，粘贴以下内容（每一行都有注释解释，新手可直接复制）：

version: '3.8'  # Docker Compose 版本，兼容主流 Docker
services:
  openclaw-gateway:
    image: openclaw/gateway:latest  # 拉取最新版 Gateway 镜像
    container_name: openclaw-gateway  # 容器名称，方便管理
    restart: always  # 服务器重启后自动启动 Gateway
    ports:
      - "18789:18789"  # 映射端口：主机端口18789 → 容器端口18789（WebSocket 服务）
    environment:
      # 运行环境：生产模式
      - NODE_ENV=production
      # 核心认证令牌（★★★ 必须修改！自定义强密码，本地 Node 要和这个一致 ★★★）
      - GATEWAY_TOKEN=MySuperStrongToken123!@#
      # WebSocket 服务端口（和上面 ports 映射的一致）
      - WS_PORT=18789
      # 允许跨域（确保 Node 能连接）
      - CORS_ALLOW_ORIGIN=*
      # 日志级别：info（调试时可改 debug）
      - LOG_LEVEL=info
    volumes:
      # 数据持久化：网关的任务记录、节点信息等存储到本地目录
      - ./gateway-data:/app/data

粘贴完成后，按下 Esc → 输入 :wq → 回车，保存并退出 vim。

步骤 5：启动 Gateway 容器

# 启动 Gateway（后台运行）
docker compose up -d

# 查看容器状态（出现 Up 即成功）
docker compose ps

# 查看 Gateway 日志（验证启动是否正常）
docker compose logs -f openclaw-gateway

✅ 日志中出现 Gateway started successfully on port 18789 表示 Gateway 启动成功。

步骤 6：验证云端 Gateway 可访问

在本地电脑浏览器访问：http://你的云服务器IP:18789/health
如果返回 {"status":"ok"}，说明 Gateway 服务正常（若访问失败，检查云服务器安全组是否放行 18789 端口）。

四、云端 Gateway 安全加固（必做！避免端口暴露）

禁止直接将 18789 端口暴露到公网，推荐用 Cloudflare Tunnel 做加密代理（免费、无需端口放行）：

步骤 1：云服务器安装 Cloudflare Tunnel

# 下载并安装 cloudflared
curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
dpkg -i cloudflared.deb

# 验证安装
cloudflared --version

步骤 2：启动 Cloudflare Tunnel 代理

# 启动隧道，映射 127.0.0.1:18789 到 Cloudflare 临时域名
cloudflared tunnel --url http://127.0.0.1:18789

✅ 执行后会输出类似 https://xxxx-xxxx-xxxx.trycloudflare.com 的临时域名，这就是你的「Gateway 安全访问地址」（永久使用可绑定自己的域名，新手先用临时域名）。

五、本地 Node 部署（分系统超详细）

步骤 1：安装 Node.js ≥ 22.x（必装）

Node.js 是运行 OpenClaw Node 的基础，以下是各系统安装方法：

👉 Windows 系统

  1. 打开官网：https://nodejs.org/，下载「LTS 版 ≥22.x」安装包；
  2. 双击安装，勾选「Add to PATH」（自动添加环境变量）；
  3. 验证：打开 cmd 命令提示符，输入 node -v，出现版本号即成功。

👉 macOS 系统

# 安装 Homebrew（未安装的话）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js
brew install node@22

# 验证
node -v

👉 Linux 系统（Ubuntu/Debian/CentOS）

# 安装 nvm（Node 版本管理器）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 刷新环境变量
source ~/.bashrc

# 安装 Node.js 22
nvm install 22
nvm use 22

# 验证
node -v

步骤 2：安装 OpenClaw Node

打开本地电脑的终端（Windows：cmd/PowerShell；Mac/Linux：终端），执行：

# 全局安装 OpenClaw（推荐用 pnpm，无则用 npm）
npm install -g openclaw

# 验证安装（出现版本号即成功）
openclaw --version

步骤 3：创建 Node 配置文件

  1. 在本地电脑任意位置新建文件夹（如 OpenClaw-Node）；
  2. 用文本编辑器（VS Code/Notepad++）在该文件夹内创建 .env 文件（注意文件名以 . 开头）；
  3. 粘贴以下配置（关键参数必须和云端 Gateway 一致）：
    
# Node 运行模式：仅作为执行节点
NODE_MODE=node

★★★ 云端 Gateway 地址（二选一）★★★

方式 1：直接用云服务器 IP（需放行 18789 端口）

GATEWAY_URL=http://你的云服务器IP:18789

方式 2：用 Cloudflare Tunnel 安全域名（推荐）

GATEWAY_URL=https://xxxx-xxxx-xxxx.trycloudflare.com

★★★ 云端 Gateway 的认证令牌（必须和云端的 GATEWAY_TOKEN 完全一致）★★★

GATEWAY_TOKEN=MySuperStrongToken123!@#

本地节点名称（自定义，方便云端识别）

NODE_NAME=My-Laptop

日志级别（调试用 debug，正常用 info）

LOG_LEVEL=info

自动重连（断网后自动重新连接 Gateway）

AUTO_RECONNECT=true


### 步骤 4：启动本地 Node
1. 打开终端，进入 `OpenClaw-Node` 文件夹（例：`cd D:\OpenClaw-Node`）；
2. 执行启动命令：
```bash
# 启动 Node 节点
openclaw node start

✅ 终端输出 Connected to gateway successfully 表示 Node 已成功连接云端 Gateway。

六、验证 Gateway 与 Node 的连接

回到云端服务器的 SSH 终端，执行：

# 查看 Gateway 日志，确认 Node 连接
docker compose logs -f openclaw-gateway

✅ 日志中出现 Node "My-Laptop" connected 表示连接成功。

七、测试实际操作（验证本地执行）

步骤 1：云端发送测试指令

在云服务器执行以下命令，触发本地 Node 执行操作：

# 进入 Gateway 容器
docker exec -it openclaw-gateway /bin/sh

# 发送「列出本地桌面文件」指令（替换为你的 Node 名称）
openclaw task create --node "My-Laptop" --command "fs.listdir" --params '{"path":"~/Desktop"}'

步骤 2：查看执行结果

  • 本地 Node 终端会输出桌面文件列表；
  • 云端 Gateway 日志会返回执行结果；
    ✅ 能看到本地桌面文件，说明部署成功！

八、本地 Node 开机自启（确保常驻运行）

👉 Windows 系统（创建批处理脚本 + 任务计划程序）

  1. 在 OpenClaw-Node 文件夹创建 start-node.bat：
    @echo off
cd /d "D:\OpenClaw-Node"  # 替换为你的 Node 文件夹路径
openclaw node start
pause
  2. 打开「任务计划程序」→ 创建任务 → 触发器选「开机时」→ 操作选「启动程序」→ 选择该批处理脚本。

👉 macOS/Linux 系统（systemd 服务）

# 创建 systemd 服务文件
sudo vim /etc/systemd/system/openclaw-node.service

粘贴以下内容（替换路径）：

[Unit]
Description=OpenClaw Node Service
After=network.target

[Service]
Type=simple
User=你的用户名
WorkingDirectory=/home/你的用户名/OpenClaw-Node  # 替换为你的 Node 文件夹
ExecStart=/usr/bin/openclaw node start
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

启动并设置开机自启：

sudo systemctl daemon-reload
sudo systemctl start openclaw-node
sudo systemctl enable openclaw-node

# 验证状态
sudo systemctl status openclaw-node

九、常见问题排查（新手易踩坑）

  1. Node 连接 Gateway 失败：
    • 检查 GATEWAY_TOKEN 是否和云端完全一致；
    • 检查 GATEWAY_URL 是否正确（Cloudflare 域名需确保隧道在运行）；
    • 本地网络是否能访问云端（ping 云服务器 IP 测试）。
  2. 指令执行无响应：
    • 检查 Node 是否启动（终端是否有 Connected 提示）；
    • 检查 Gateway 日志是否有指令转发记录；
    • 本地 Node 权限是否足够（避免用管理员/root 权限，也不要权限过低）。
  3. Cloudflare Tunnel 断开：
    • 用 nohup cloudflared tunnel --url http://127.0.0.1:18789 & 后台运行隧道；
    • 查看隧道日志：tail -f nohup.out。

总结

  1. 核心配置：云端 Gateway 和本地 Node 的 GATEWAY_TOKEN 必须一致，Gateway 地址需正确；
  2. 安全原则：永远用 Cloudflare Tunnel/VPN 代理 Gateway，不直接暴露 18789 端口；
  3. 关键验证：Node 启动后显示「Connected」、能执行「列出桌面文件」指令，即为部署成功。

至此，你已完成「云端 Gateway + 本地 Node」的完整混合部署，可通过云端指令远程操作本地电脑，且全程安全可控。

中文版OpenClaw，非阉割版，同原版保持自动更新
OpenClaw 安装与运行教程

最后更新于  2026-03-10 09:48:21  并被添加「」标签，已有 38 位童鞋阅读过。

本站使用「署名 4.0 国际」创作共享协议，可自由转载、引用，但需署名作者且注明文章出处

此处评论已关闭