# OpenClaw 安装与部署指南：本地、WSL2、Docker 与 VPS 怎么选

> OpenClaw 安装的终点不是跑完脚本，而是 Gateway 正常、dashboard 可访问、选定 provider 能从同一运行环境返回结果。先本地验证 auth、gateway 和模型 route，再决定 Docker、VPS 或团队部署。

- URL: https://blog.laozhang.ai/zh/posts/openclaw-installation-deployment-guide
- Published: 2026-02-08
- Updated: 2026-05-08
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: 开发工具与智能体
- Tags: OpenClaw, 安装指南, Docker 部署, VPS 设置, WSL2, AI 助手

---
OpenClaw 安装的关键不是复制一条命令，而是让 Gateway、认证、模型 route 和启动方式在同一台实际运行的机器上闭环。更稳妥的顺序是：确认当前文档要求的 Node/runtime，运行对应平台的官方安装方式，完成 `openclaw onboard --install-daemon`，再用 `openclaw gateway status`、`openclaw doctor`、`openclaw dashboard` 和一次真实模型响应确认可用。没有验证这些信号前，不要把安装称为完成。

## 快速答案

- **第一次安装**：优先使用当前官方 installer 或 PowerShell installer，不要从旧文章复制版本号和服务脚本。
- **安装后必须 onboard**：`openclaw onboard --install-daemon` 用于写入 Gateway 需要的配置和受管启动方式。
- **验证顺序**：Gateway 运行、配置有效、dashboard 可打开、provider auth 正常、真实消息能返回。
- **部署选择**：本地适合个人测试；WSL2 适合 Windows 上的 Linux-like 工作流；Docker/VPS 适合隔离、常驻和团队运维。
- **安全边界**：不要直接暴露 Gateway 端口；不要把 `.env` 提交到 git；不要把旧硬件表、旧价格或旧 Docker image 当成当前事实。

核心命令形状如下，具体版本和平台细节以当前 OpenClaw 文档为准：

```bash
# macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows PowerShell, when supported by current docs
iwr -useb https://openclaw.ai/install.ps1 | iex

openclaw onboard --install-daemon
openclaw gateway status
openclaw doctor
openclaw dashboard
```

## 先选部署方式

| 方式 | 适合谁 | 上线前必须验证 |
|---|---|---|
| 官方安装脚本 | 个人本机、首次试用、日常开发 | Node/runtime、Gateway status、provider auth、登录启动行为 |
| Windows + WSL2 | 需要 Linux 工具链的 Windows 用户 | WSL2 网络转发、文件路径、Node、dashboard 端口 |
| npm/pnpm 全局安装 | 已经熟练管理 Node 工具链的开发者 | 全局包路径、升级方式、daemon 配置 |
| Docker Compose | VPS、团队、隔离部署 | 当前 image 名称、volume 路径、secret 来源、端口和反向代理 |
| VPS/托管服务器 | 需要常驻、远程访问或团队使用 | 防火墙、备份、账单 owner、重启策略、日志保留 |

实用建议是先在本地跑通 auth、Gateway 和 provider route。只有当你确认这个 assistant 真的符合工作流，再迁移到 Docker 或 VPS。这样能避免一边排查模型认证，一边排查容器网络、端口暴露和服务器防火墙。

## macOS 和 Linux 安装

先检查当前 Node/runtime 是否符合 OpenClaw 文档要求：

```bash
node --version
```

如果版本不符合要求，按当前 OpenClaw 或 Node 官方文档升级。不要把本文的旧截图或旧命令当成长期版本合同。

运行 installer 后，继续执行 onboarding：

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

onboarding 要完成三件事：选择模型/provider route，配置 auth，写入 Gateway mode 与受管启动方式。然后验证：

```bash
openclaw gateway status
openclaw doctor
openclaw dashboard
```

macOS 上如果系统或第三方防火墙弹出网络访问提示，只允许你实际使用的 provider、gateway 和 channel endpoint。若某个 provider 或 channel 只在 macOS 上失败，先查防火墙和网络代理，再换 API key。

Linux 上优先使用 onboarding 提供的 daemon 路径。只有当你明确要自己维护 systemd unit 时，才根据当前文档编写服务文件，并验证 `ExecStart`、用户、HOME、配置路径、日志和重启策略。不要把旧 systemd 模板直接复制到生产服务器。

## Windows、WSL2 和 Docker

Windows 有两条现实路线：当前文档支持的原生 PowerShell installer，以及 WSL2。需要 Unix-like 工具链、开发环境和 Linux 服务行为时，WSL2 更稳。安装 WSL2 后，在 Ubuntu 环境里按 Linux 流程安装并 onboard。

```powershell
wsl --install
```

WSL2 网络要单独验证。不要假设 dashboard 一定在某个旧端口。以 `openclaw dashboard` 输出为准；如果 Windows 浏览器打不开，检查 WSL2 localhost forwarding、防火墙和实际监听地址。

Docker Compose 适合已经接受容器运维成本的用户。写 compose 文件前，先查当前 OpenClaw Docker 文档，确认 image 名称、tag、volume、端口和 env/secret 形状。下面只是形状参考：

```yaml
services:
  openclaw:
    image: openclaw/openclaw:latest # verify current image/tag
    restart: unless-stopped
    ports:
      - "127.0.0.1:18789:18789"
    volumes:
      - ./data:/app/data # verify current data/config path
    environment:
      - NODE_ENV=production
```

`127.0.0.1` 绑定适合本机测试。生产或团队访问不要直接把 Gateway 暴露到公网；使用带认证的反向代理、VPN、tunnel 或防火墙规则。`.env` 只适合个人低风险部署；团队和服务器应优先考虑 Docker secrets、secret manager 或平台级密钥管理。

## 容量和性能怎么判断

OpenClaw 本身通常不是最重的部分。真正影响稳定性的常常是主机是否常在线、网络是否稳定、配置能否备份、日志是否增长、旁边是否运行其他服务，以及连接的模型 route 是否慢。

| 部署路线 | 上线前要验证 | 主要风险 |
|---|---|---|
| 现有笔记本/桌面机 | 睡眠、重启、网络变化、本地 secret | 合盖或换网络导致服务不可用 |
| 家庭服务器/单板机 | 供电、存储、备份、更新方式 | 家庭网络和存储可靠性 |
| VPS/托管服务器 | region、防火墙、重启策略、备份、账单 owner | 暴露端口、服务商维护、持续账单 |
| 团队部署 | secret rotation、日志、监控、rollback | 多人使用导致配置漂移和凭证归属混乱 |

性能排查时，把 Gateway 进程和模型 route 分开看。如果 CPU/RAM 很低但回复慢，瓶颈可能是 provider latency、quota、context size 或网络。如果主机已经 swap 或日志爆盘，先解决本机资源和日志轮转，再调模型。

## 配置、密钥和 provider

OpenClaw 行为可能来自 config file、auth profiles、environment variables、container secrets 和 channel settings。排查时要问一个问题：Gateway 进程实际读到了哪一份配置？

常见 provider env 形状如下，但实际 key 名称和配置方式以当前 provider/OpenClaw 文档为准：

```bash
ANTHROPIC_API_KEY=your-current-anthropic-key
OPENAI_API_KEY=your-current-openai-compatible-key
GOOGLE_AI_API_KEY=your-google-key-here
OLLAMA_BASE_URL=http://localhost:11434
```

如果你使用 [laozhang.ai](https://docs.laozhang.ai/) 或其他 OpenAI-compatible gateway，把它当作 provider-gateway route，而不是官方上游价格或官方上游可用性。当前 endpoint、model ID、pricing、quota、context window 和 tool support 都要在发布或生产使用前验证。

*说明：[laozhang.ai 是我们自己的服务](https://blog.laozhang.ai/zh/about#laozhang)，其价格是平台报价，不是独立比较的结论。*

消息平台 token 也要和模型 provider auth 分开排查。Telegram、Slack、Discord、WhatsApp 等 channel 各自有权限、scope、签名或 webhook 要求。Dashboard 正常但 channel 不正常时，不要换模型 key，先查 channel pairing 和平台权限。

## 首次运行验证

安装后按这个顺序检查：

```bash
openclaw gateway status
openclaw doctor
openclaw logs --follow
openclaw dashboard
```

健康信号包括：Gateway 正在运行；配置可验证；选定 provider 可达；dashboard 能连接；第一条真实消息能返回；如果启用了 channel，从该 channel 也能收到响应。

常见问题：

**Provider key invalid**：到 provider console 验证 key、billing、model access，并检查 shell/Docker/systemd 环境是否覆盖了你以为正在使用的值。

**Port already in use**：先确认占用端口的进程是谁。

```bash
lsof -i :18789
kill <PID>
```

只终止你确认是 stale OpenClaw gateway 的进程。若端口被其他合法服务使用，按当前 OpenClaw 文档配置替代端口。

**429 Too Many Requests**：看 provider dashboard、headers 和 `retry-after`。短时间反复重试通常只会浪费 quota。

**WebSocket/channel failed**：先查 channel token、scope、pairing、webhook、网络代理和防火墙。不要把 channel 失败直接当成模型认证失败。

## 升级、备份与回滚

升级前先备份配置、数据和 secret 来源：

```bash
cp -r ~/.openclaw ~/openclaw-backup-$(date +%Y%m%d)
cp -r ~/openclaw-docker/data ~/openclaw-data-backup-$(date +%Y%m%d)
```

更新命令取决于安装方式：

```bash
openclaw update
npm update -g openclaw
docker compose pull && docker compose up -d
```

如果你的版本没有 `openclaw update` 或 `update --check`，使用当前安装方式对应的 package manager、container registry 或 GitHub releases。Docker 减少 Node drift，但不会消除 image tag、volume path、migration 和 config 风险。

回滚不要直接删除原配置。先移动旧目录，再复制备份：

```bash
openclaw stop
mv ~/.openclaw ~/.openclaw-broken-$(date +%Y%m%d-%H%M%S)
cp -r ~/openclaw-backup-YYYYMMDD ~/.openclaw
openclaw start
```

Docker 环境应使用已测试的 release tag，而不是长期依赖 `latest`。回滚要同时验证 image、volume、env 和 provider route。

## 长期维护

1. 定期运行 `openclaw gateway status` 和 `openclaw doctor`。
2. 轮换 provider key 和 channel token，尤其是多人部署。
3. 对日志设置轮转，避免磁盘被日志填满。
4. 保留一份离机备份。
5. 更新前读 release notes，特别是 major version。
6. 每次改 provider、gateway、channel 或 Docker 配置后，从实际使用的 surface 重新发一条测试消息。

安装真正完成的标准很简单：Gateway 能稳定启动，dashboard 可访问，provider route 可用，secret 没泄露，备份可恢复，下一次重启后还能工作。