OpenClaw 在火山云部署与远程访问完整指南

作者：Administrator 发布时间： 2026-03-26 阅读量：3
#ai #openclaw #linux

本文档使用deepseek汇总了在火山云服务器上部署 OpenClaw 并配置远程访问的完整流程，包括常见问题排查、插件安全配置和命令参考。

1. 环境准备

1.1 系统要求

  • 操作系统：Ubuntu 20.04/22.04 或 CentOS 7/8（推荐 Ubuntu 22.04）
  • 网络：服务器需能访问外网（下载依赖、调用 API）

1.2 Node.js 环境

OpenClaw 必须运行在 Node.js v22 或更高版本。

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# CentOS/Rocky
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo yum install -y nodejs

# 验证版本
node -v   # 应输出 v22.x.x

2. 部署 OpenClaw

2.1 全局安装

npm install -g openclaw@latest
openclaw --version   # 验证安装

2.2 初始化配置

首次运行需配置模型提供商（如火山引擎）：

openclaw init

或手动编辑配置文件 ~/.openclaw/openclaw.json，示例：

{
  "models": {
    "providers": {
      "volcengine": {
        "baseUrl": "https://ark.cn-beijing.volces.com/api/v3",
        "apiKey": "你的方舟专属API Key",   // UUID 格式
        "api": "openai-completions",
        "models": [
          {
            "id": "ep-xxxxxxxx-xxxxx",      // ep- 开头的接入点 ID
            "name": "Doubao-Seed-2.0-pro"
          }
        ]
      }
    }
  }
}

2.3 启动 Gateway

openclaw gateway start
openclaw gateway status   # 查看状态

2.4 验证部署

使用 TUI 客户端测试：

openclaw tui

输入任意消息，若能收到回复则部署成功。

3. 配置远程访问

默认 Gateway 仅监听 127.0.0.1，无法从外部访问。根据网络环境选择以下方案之一。

3.1 SSH 端口转发（最简单，推荐）

# 在本地电脑执行
ssh -L 18789:127.0.0.1:18789 用户名@服务器公网IP

保持会话，然后本地浏览器访问 http://127.0.0.1:18789。
优点：无需开放防火墙，无需 CORS 配置，流量加密。

3.2 Tailscale（企业级安全隧道）

# 服务器安装 Tailscale
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

# 获取 Tailscale IP
tailscale ip -4

本地电脑安装 Tailscale 并登录同一账号，浏览器访问 http://<Tailscale-IP>:18789。
优点：自动 mTLS，无需开放端口，无 CORS 问题。

3.3 公网 IP 直连（需配置 CORS 与防火墙）

3.3.1 设置 Gateway 监听所有接口

openclaw config set gateway.bind lan

3.3.2 配置跨域来源

openclaw config set gateway.controlUi.allowedOrigins '["http://你的公网IP:18789"]'
# 或临时允许所有来源（测试用）：'["*"]'

3.3.3 开放防火墙和安全组

  • 系统防火墙： 
    # Ubuntu
ufw allow 18789/tcp
# CentOS
firewall-cmd --add-port=18789/tcp --permanent && firewall-cmd --reload
  • 火山云控制台：为服务器关联的安全组添加入方向规则，TCP 端口 18789，授权对象 0.0.0.0/0。

3.3.4 重启 Gateway

openclaw gateway restart

3.3.5 设备配对（首次访问必需）

# 服务器生成配对码
openclaw gateway pair   # 输出 6 位数字

浏览器访问 http://你的公网IP:18789，输入配对码完成验证。

3.4 反向代理 + HTTPS（生产环境推荐）

使用 Nginx 或 Caddy 为 Gateway 提供 HTTPS 支持。

Nginx 配置示例：

server {
    listen 443 ssl;
    server_name your-domain.com;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/privkey.pem;

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

证书可免费申请 Let's Encrypt（Certbot）。访问 https://your-domain.com 即可安全使用。

4. 插件安全配置

安装第三方插件（如微信插件）后需显式允许：

# 安装微信插件示例
npx -y @tencent-weixin/openclaw-weixin-cli@latest install

# 允许插件加载
openclaw config set plugins.allow '["openclaw-weixin"]'

# 启用插件管理命令
openclaw config set commands.plugins true

# 重启 Gateway
openclaw gateway restart

5. 常见问题排查

问题现象可能原因解决方法
Gateway start blocked: set gateway.mode=local缺少网关模式配置openclaw config set gateway.mode local
origin not allowedCORS 未配置设置 gateway.controlUi.allowedOrigins
control ui requires device identity远程访问需配对执行 openclaw gateway pair 完成配对
plugins.allow is empty 警告插件自动加载安全警告设置 plugins.allow 显式允许
/plugins is disabled插件命令未启用openclaw config set commands.plugins true
API 调用返回 401/404火山引擎 Key/模型 ID 错误使用方舟专属 Key 及 ep- 开头的接入点 ID
端口 18789 被占用其他进程占用lsof -i :18789 查看并 kill
Node.js 版本过低版本低于 v22按 1.2 升级

6. 常用命令参考

命令说明
openclaw gateway start/stop/restart控制网关服务
openclaw gateway status查看网关状态
openclaw config get <key>获取配置项
openclaw config set <key> <value>设置配置项
openclaw config edit编辑配置文件
openclaw doctor [--fix]诊断并尝试修复
openclaw logs [--follow]查看日志
openclaw tui启动文本界面
openclaw dashboard --no-open生成带 token 的 URL
openclaw gateway pair生成设备配对码

7. 部署验证清单

  • Node.js 版本 ≥ v22
  • openclaw --version 正常输出
  • openclaw gateway status 显示 running
  • curl http://127.0.0.1:18789 返回 HTML
  • 远程访问方式配置成功（SSH/Tailscale/公网/HTTPS）
  • 浏览器能打开控制界面（或配对成功）
  • TUI 能正常对话，模型调用成功
  • 插件（如有）已配置并允许加载

8. 总结

通过上述步骤，您可以在火山云服务器上完成 OpenClaw 的部署，并根据需要安全地实现远程访问。核心要点：

  • 务必使用 Node.js v22+
  • Gateway 绑定模式使用 lan 以监听所有接口
  • 远程访问优先考虑 SSH 隧道或 Tailscale，避免直接暴露公网端口
  • 若必须公网访问，配置 CORS、防火墙、设备配对
  • 插件需显式允许，确保安全

如遇其他问题，可通过 openclaw logs --follow 获取详细日志，或结合浏览器开发者工具排查。

上一篇：MySQL、PostgreSQL、...