OpenClaw(小龙虾)详细的部署教程

最推荐的路径是： Windows 用户：用 WSL2 + Ubuntu 部署 Linux 用户：直接用官方安装脚本 想跑在云服务器/VPS：优先 Docker 方案 想改源码/二次开发：走 from source 官方当前推荐使用安装脚本与 onboarding wizard；运行时推荐 Node 24，Node 2…

作者：lh

最推荐的路径是：

  • Windows 用户：用 WSL2 + Ubuntu 部署

  • Linux 用户：直接用官方安装脚本

  • 想跑在云服务器/VPS：优先 Docker 方案

  • 想改源码/二次开发：走 from source

官方当前推荐使用安装脚本与 onboarding wizard；运行时推荐 Node 24，Node 22 LTS（22.16+） 也仍兼容。官方还明确说 Windows 推荐走 WSL2，Linux 上推荐 Node，不推荐 Bun 作为 Gateway 运行时。

另外有一个很重要的坑：
GitHub 上有人报告，某些手动 npm 安装说明曾误导用户装到一个第三方占坑包；官方安装脚本是相对更安全的路径。所以这份教程里我优先用 官方 install.sh / install.ps1，不建议你自己凭感觉 npm install -g。

一、OpenClaw 部署前你要先知道什么

OpenClaw 当前的核心运行方式是：

  1. 安装 CLI

  2. 跑 onboard 向导

  3. 启动 Gateway

  4. 用浏览器打开本地控制台，或者再接 WhatsApp / Telegram 等渠道

官方默认把 Gateway 跑在 18789 端口，最快的首个可用聊天方式其实是先直接打开本地 Control UI，不一定非要先接聊天软件。

常用路径和文件：

  • 配置文件：~/.openclaw/openclaw.json

  • 凭据目录：~/.openclaw/credentials/

  • 工作区目录：~/.openclaw/workspace

升级前官方也建议你先备份这三处。

二、最推荐：Linux/macOS 直接安装

1）系统要求

官方要求/建议：

  • Node 24 推荐

  • Node 22 LTS（22.16+）兼容

  • macOS / Linux / Windows

  • 只有在 源码构建 时才需要 pnpm

2）官方一键安装

在终端运行：

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

官方说明这个脚本会：

  • 检测 Node

  • 必要时安装 Node

  • 安装 OpenClaw CLI

  • 启动 onboarding 流程

如果你只想安装，不想立刻进入向导：

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

官方也提供了一个 无需 root、本地前缀安装 的脚本，会装到 ~/.openclaw：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

3）运行 onboarding

安装后执行：

openclaw onboard --install-daemon

这一步是官方推荐流程。它会配置：

  • 本地或远程 Gateway

  • 认证

  • 可选 channels

  • skills/workspace 默认项
    并且如果你带上 --install-daemon，通常会把 Gateway 作为受管服务装起来。

4）检查 Gateway 是否起来了

openclaw gateway status

5）打开控制台

openclaw dashboard

或者直接在部署机上打开：

http://127.0.0.1:18789/

这是官方文档给出的最快首聊方式。

6）前台运行模式

你调试时也可以不装 daemon，直接前台跑：

openclaw gateway --port 18789

或者：

openclaw gateway run

官方说明 openclaw gateway run 是前台别名；而且默认要求配置里 gateway.mode=local，否则需要 --allow-unconfigured 做临时开发运行。

三、Windows 最推荐方案：WSL2 + Ubuntu

官方明确写了：OpenClaw 在 Windows 上推荐通过 WSL2 运行，这样兼容性最好，尤其是 Node/pnpm/Linux binaries/skills 这套环境会更稳。

1）安装 WSL2

管理员 PowerShell：

wsl --install

如果想指定发行版：

wsl --list --online
wsl --install -d Ubuntu-24.04

如果系统要求重启，就重启。

2）在 WSL 中启用 systemd

这是官方特别强调的，因为 gateway install 需要它。
在 Ubuntu 终端里执行：

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

然后回到 PowerShell：

wsl --shutdown

重新打开 Ubuntu，验证：

systemctl --user status

这些步骤都是官方 Windows(WSL2) 页面给出的。

3）在 WSL 中安装 OpenClaw

最稳妥写法：

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

这是我建议你优先用的流程。

4）WSL2 自动开机启动

如果你希望 Windows 开机后 OpenClaw 在 WSL 里自动活着，官方文档给了三步。

第一步：允许用户服务在未登录时继续运行

在 WSL 里：

sudo loginctl enable-linger "$(whoami)"

第二步：安装 Gateway 用户服务

在 WSL 里：

openclaw gateway install

第三步：让 WSL 随 Windows 启动

管理员 PowerShell：

schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM

如果你的发行版不叫 Ubuntu，先看名字：

wsl --list --verbose

这整套是官方给出的 WSL 自启动链路。

5）Windows 原生安装能不能用

能，但官方态度是：可以尝试，仍不如 WSL2 稳。
官方说原生 Windows 当前这些场景比较可行：

  • install.ps1

  • 本地 CLI 基础命令

  • 某些本地 agent/provider smoke test

安装命令：

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

如果你只想在原生 Windows 上先试 CLI，不想碰服务安装：

openclaw onboard --non-interactive --skip-health
openclaw gateway run

如果你想装托管启动：

openclaw gateway install
openclaw gateway status --json

官方还说明：如果 Windows Scheduled Task 创建失败，会回退到 Startup-folder 的登录启动项。

四、最省心的“先跑起来”方案

如果你只想验证 OpenClaw 能跑，不想先折腾 WhatsApp/Telegram，直接这样：

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

然后浏览器访问本地 UI。
官方明确说 “Fastest chat” 就是直接用 Control UI。

五、接入 WhatsApp / 聊天渠道

官方的 Personal Assistant Setup 页面给了一个最小 WhatsApp quick start：

openclaw channels login
openclaw gateway --port 18789

然后在 ~/.openclaw/openclaw.json 里写最小配置：

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123"]
    }
  }
}

官方说明 openclaw channels login 会弹出 WhatsApp Web 的二维码配对。

DM 安全策略

官方配置里，DM 控制支持这几种模式：

  • pairing：默认，陌生人先拿一次性配对码

  • allowlist：只允许白名单

  • open：允许全部私聊，但要求 allowFrom: ["*"]

  • disabled：禁用私聊

也就是你刚部署时，推荐别直接开全网，先用 pairing 或 allowlist。

一个更稳妥的例子：

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+491234567890"]
    }
  }
}

六、Docker / VPS / 云服务器部署

如果你希望：

  • 24 小时在线

  • 跑在云主机

  • 宿主机保持干净

  • 以后迁移方便

那 Docker 是比较合适的。

官方 VPS 文档说，VSP/cloud 场景是支持的；官方的 GCP/Hetzner 指南本质上也都是围绕 Docker 和持久化目录。

1）Docker 路线的核心原则

官方特别强调：

  • 容器是易失的

  • ~/.openclaw 和 ~/.openclaw/workspace 必须持久化到宿主机

  • 容器里运行时临时装的二进制，重启会丢失

  • 如果技能依赖额外二进制，应该在镜像构建阶段 bake 进去，而不是容器启动后再装

2）官方 Docker 预构建镜像

官方 Docker 文档给出了使用 GHCR 预构建镜像的方法：

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

它说明：

  • 默认 docker-setup.sh 会从源码构建镜像

  • 设了 OPENCLAW_IMAGE 后就改成 docker pull

  • 但依然要从仓库根目录执行，因为它还会用本地 docker-compose.yml 和 helper files

3）Docker/VPS 标准流程

以 Ubuntu VPS 为例：

安装 Docker 与 Git

sudo apt update
sudo apt install -y docker.io docker-compose-plugin git curl
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
newgrp docker

克隆仓库

git clone https://github.com/openclaw/openclaw.git
cd openclaw

创建持久化目录

mkdir -p ~/.openclaw
mkdir -p ~/.openclaw/workspace

这两步和官方 GCP 指南一致：容器状态必须放宿主机持久化目录。

用预构建镜像启动

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

访问方式

对于云服务器，官方建议两种：

  • SSH 隧道访问

  • 直接暴露端口，但你要自己做好防火墙和 token 管理

官方 GCP 页面更偏向 SSH port forwarding。

例如本机到服务器做端口转发：

ssh -L 18789:127.0.0.1:18789 youruser@your-vps-ip

然后本机浏览器打开：

http://127.0.0.1:18789/

这比直接公网暴露更稳。

七、源码部署（适合你要改代码/做二开）

如果你想：

  • 看源码

  • 改插件/工具/前端

  • 跟主仓库一起更新

  • 在开发机上自己 build

那就走源码部署。

官方 install 页面给了 from source 的命令：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
pnpm link --global
openclaw onboard --install-daemon

官方也说，如果你不想 pnpm link --global，可以在仓库内直接用：

pnpm openclaw ...

这些都是当前官方文档给出的源码构建步骤。

源码部署详细版

1）准备 Node 与 pnpm

先确认 Node：

node --version

推荐 Node 24。
然后装 pnpm：

npm install -g pnpm

2）克隆仓库

git clone https://github.com/openclaw/openclaw.git
cd openclaw

3）安装依赖

pnpm install

4）构建 UI

pnpm ui:build

5）构建项目

pnpm build

6）全局链接 CLI

pnpm link --global

7）执行向导

openclaw onboard --install-daemon

8）检查服务

openclaw gateway status
openclaw dashboard

八、推荐的最小配置模板

如果你装完想手动改配置，配置文件通常是：

~/.openclaw/openclaw.json

一个最小本地 Gateway + WhatsApp allowlist 风格可以写成：

{
  "gateway": {
    "mode": "local"
  },
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+491234567890"]
    }
  }
}

如果只是本地 dashboard 测试，很多项可以先通过 openclaw onboard 让向导生成，再按需改。官方也建议 新手优先走 onboard，而不是手搓全配置。

九、部署后常用命令

基础检查

openclaw --version
openclaw gateway status
openclaw dashboard

前台调试

openclaw gateway run

指定端口前台运行

openclaw gateway --port 18789

重新配置

openclaw configure

添加 agent

openclaw agents add main

这些命令都来自官方 getting started / wizard / gateway 文档。

十、最常见的坑与解决办法

1）装到了错误 npm 包

这是当前最需要防的坑之一。
GitHub issue 指出，有手动安装说明曾把用户引向第三方占坑包；优先用官方 install.sh / install.ps1。

建议：

  • 不要自己凭印象 npm i -g 某个名字

  • 优先用：

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

    • iwr -useb https://openclaw.ai/install.ps1 | iex

2）Windows 原生各种奇怪兼容性

官方已经写得很明确：WSL2 是推荐路径。
如果你在 Windows 原生环境下遇到：

  • 计划任务创建失败

  • gateway 状态异常

  • 端口冲突

  • 某些 skills 不工作

那就别硬拗，直接切换 WSL2。

3）18789 端口被占用

如果你已经用 daemon 方式启动过，再跑前台命令，很容易撞端口。
先看状态：

openclaw gateway status

再决定是停掉后台，还是别再开一个前台实例。
Windows 的官方 PR 里也专门提到过 daemon 占着 18789 导致开发 watch 流程失败的问题。

4）Linux 上浏览器工具异常

官方单独写了 Linux browser troubleshooting：
Ubuntu 上默认 apt install chromium 往往拿到的是 snap wrapper，而 Snap 的 AppArmor 会干扰 OpenClaw 管理浏览器进程。官方明确说那不是一个真正适合这里的浏览器安装方式。

也就是说，如果后面你要用 browser tools，遇到浏览器相关报错，不要先怀疑 OpenClaw 配置，先检查你是不是装成了 snap 版 Chromium。

5）Docker 容器里临时装依赖，重启全没了

官方明说这是陷阱。
需要的二进制应当在 镜像构建阶段 bake 进去，而不是 container runtime 里临时安装。

6）更新后配置丢失

更新前先备份：

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
cp -r ~/.openclaw/credentials ~/.openclaw/credentials.bak
cp -r ~/.openclaw/workspace ~/.openclaw/workspace.bak

因为官方明确说升级前最重要的就是保住：

  • config

  • credentials

  • workspace

十一、我建议你的实际部署路线

方案 A：你是 Windows 用户

最推荐：

wsl --install -d Ubuntu-24.04

然后在 Ubuntu 里：

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

这是成功率最高的。

方案 B：你是 Ubuntu / Debian 用户

直接：

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

方案 C：你想云端 24 小时在线

git clone https://github.com/openclaw/openclaw.git
cd openclaw
mkdir -p ~/.openclaw ~/.openclaw/workspace
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

再用 SSH 隧道访问控制台。

方案 D：你要二开

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
pnpm link --global
openclaw onboard --install-daemon

十二、给你一份可直接照抄的 Ubuntu 完整部署清单

# 1. 安装
curl -fsSL https://openclaw.ai/install.sh | bash

# 2. 运行向导并安装后台服务
openclaw onboard --install-daemon

# 3. 检查服务
openclaw gateway status

# 4. 打开控制台
openclaw dashboard

# 5. 如果要前台调试
openclaw gateway run

# 6. 如果要接 WhatsApp
openclaw channels login

# 7. 编辑配置
mkdir -p ~/.openclaw
nano ~/.openclaw/openclaw.json

一个最小配置示例：

{
  "gateway": {
    "mode": "local"
  },
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+491234567890"]
    }
  }
}

十三、给你一份 Windows + WSL2 完整部署清单

管理员 PowerShell：

wsl --install -d Ubuntu-24.04

进入 Ubuntu 后：

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

回到 PowerShell：

wsl --shutdown

重新打开 Ubuntu：

systemctl --user status
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

要开机自动运行：

sudo loginctl enable-linger "$(whoami)"
openclaw gateway install

管理员 PowerShell：

schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM