【教程】Linux 上从 0 部署 OpenClaw（能跑、能用、能反代）

作者

一句话：这篇就是把 OpenClaw 在 Linux 上从 0 搭起来，按“宝宝都能学会”的思路写清楚：安装 → 配置 → 跑起来 →（可选）域名反代进 Control UI。

我自己踩过的坑也会写出来（比如反代 WebSocket 授权、systemd 重复实例、端口冲突、htpasswd 权限 500 等）。

🧾 你需要什么

  • ✅ 一台 Linux 服务器（Ubuntu/Debian 都行）
  • ✅ CPU/内存别太抠：建议 2H4G 起步（低配也能跑，但更容易各种“卡/超时/不回”）
  • ✅ 一个域名（可选：想在浏览器远程打开 Control UI 才需要）
  • ✅（可选）Telegram Bot（如果你想用 Telegram 当入口）

⚠️ 注意注意注意（安全 + 稳定性）

  • 不要把 OpenClaw 的管理端口直接裸奔公网；要么只监听 127.0.0.1，要么反代加认证。
  • 反代推荐走 trusted-proxy + BasicAuth，不然 WebSocket 授权经常翻车。
  • 同一台机器上别让 OpenClaw 启两个实例（user service + system service 混着来），很容易端口冲突/token mismatch。

🚀 第一部分：系统准备（10 分钟）

1）更新系统 + 安装常用工具

# Ubuntu/Debian 都通用
sudo apt update -y
sudo apt upgrade -y
sudo apt install -y curl git ca-certificates jq

2）安装 Node.js 22+（OpenClaw 必需）

OpenClaw 需要 Node 22 或更新版本。我更推荐用 nvm（省心，不污染系统包）：

curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc

nvm install 22
nvm use 22
node -v
npm -v

如果你用 root 跑服务，确认一下 HOME（真遇到过 HOME 为空导致异常的环境）：

echo $HOME
# 期望输出：/root

🦞 第二部分：安装 OpenClaw（最快路线）

1）安装 OpenClaw

npm install -g openclaw@latest
openclaw --version

2）跑引导 + 安装后台服务

openclaw onboard --install-daemon

3）验证配置没写坏

openclaw config validate

✅ 第三部分：跑起来（确认它真的在跑）

1）看服务状态

systemctl status openclaw-gateway --no-pager

2）确认端口在监听（默认 18789）

ss -ltnp | grep 18789

3）本机打开控制台

  • http://127.0.0.1:18789/

🌐 第四部分：域名反代 Control UI（可选，但我强烈推荐这么做）

如果你想在手机/外网浏览器直接打开控制台，一般会做 Nginx 反代。这里我给一套最稳的配置：BasicAuth + trusted-proxy。

为什么不推荐直接用 token？

因为浏览器的 WebSocket 场景下，很多时候你没法“优雅地”在请求里带 Authorization（或者某些路径能带，WS 又断）。所以我最终稳定下来的方式是：反代负责认证，OpenClaw 只相信反代转发的用户身份。

1）OpenClaw 配置：trusted-proxy（核心思路）

（示意）你需要在 ~/.openclaw/openclaw.json 里启用 trusted-proxy，并指定需要的头：

{
  "gateway": {
    "auth": {
      "mode": "trusted-proxy",
      "trustedProxy": {
        "userHeader": "x-forwarded-user",
        "requiredHeaders": ["x-forwarded-proto", "x-forwarded-host"],
        "allowUsers": ["admin"]
      }
    },
    "trustedProxies": ["127.0.0.1", "::1"]
  }
}

2）Nginx 反代配置（可以直接抄）

下面是最关键的几行：一定要把 X-Forwarded-Host、X-Forwarded-Proto 这些头带上，不然 OpenClaw 会直接拒绝（你会看到类似 trusted_proxy_missing_header_x-forwarded-host 的日志）。

location / {
  auth_basic "OpenClaw";
  auth_basic_user_file /path/to/htpasswd;

  proxy_pass http://127.0.0.1:18789;

  proxy_http_version 1.1;
  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-user $remote_user;

  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";

  proxy_read_timeout 3600s;
  proxy_send_timeout 3600s;
}

3）一个很坑但很常见的错误：htpasswd 权限导致 500

现象：输入账号密码后直接 500，Nginx error.log 里是：

open() "/path/to/htpasswd" failed (13: Permission denied)

处理：确保 htpasswd 文件可读 + 目录可遍历（不要把文件放在 nginx 进程读不到的目录权限里）。

宝塔用户小提示

宝塔站点配置容易被覆盖，建议把反代片段放到 extension include 里（不同站点目录不一样）：

/www/server/panel/vhost/nginx/extension/你的域名/*.conf

🧯 第五部分：常见问题（我自己最常遇到的）

1）端口冲突 / token mismatch / 一会儿能用一会儿不能用

九成是你启动了不止一个 OpenClaw（比如 user service + system service 同时存在）。先看端口到底谁占了：

ss -ltnp | grep 18789
systemctl status openclaw-gateway --no-pager

2）页面能打开但功能不工作（WS 1008 unauthorized）

优先检查：

  • Nginx 有没有转发 X-Forwarded-Host / X-Forwarded-Proto
  • OpenClaw trusted-proxy 的 requiredHeaders 有没有写了但没转发

3）“不回复/超时”

多数不是 OpenClaw 自己挂了，而是上游模型超时/网络抖动。我的顺序是：

  1. 把 OpenClaw 的全局 timeout 调大一点（比如 1800 秒）
  2. 看 provider 是否频繁 timeout
  3. 看系统是否异常（比如僵尸进程暴涨、某容器疯狂 fork）

🎉 结尾

到这里，你至少已经做到：OpenClaw 能在 Linux 上稳定常驻，控制台能打开，远程访问也不会裸奔。

后面如果你要接 Telegram/WhatsApp，再加 allowlist（避免群消息乱入），再单独写一篇会更清楚。