> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/openclaw_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/02_setup/2.2_installation.md).

# 2.2 安装 OpenClaw

> **预计耗时**：10–20 分钟（取决于安装方式和网速）

本节介绍如何在你选择的环境中安装 OpenClaw。我们为首次用户推荐**一键安装脚本**，原因有三：首先它自动处理依赖与版本选择，避免你被 npm 版本冲突困扰；其次它最快获得可工作的系统；第三，如果后来你发现需要容器化或源码定制，可以先跑通这条路，再迁移到其他方式。这样的顺序避免了初装就掉进“工具选择困境”。

## 2.2.1 推荐安装方式：一键安装脚本

最简单快捷的安装方式是执行官方的一键安装脚本。

**前置检查**

执行脚本前，请先快速确认：

* 你已经读过[第2.1节系统要求](/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/02_setup/2.1_requirements.md)，并通过了**必须项**的检查（Node.js 版本、网络连通性）
* 网络访问 `openclaw.ai` 无阻碍（某些内网或企业 WiFi 需配置 HTTP 代理；如不确定，运行 `curl -v https://openclaw.ai/install.sh` 测试）
* 如在 WSL 环境，确认已启用 WSL2（而非 WSL1），可用 `wsl --list --verbose` 查看

**开始安装**

> 安全提示：以下是官方快速安装路径。受管控环境建议先下载脚本并审阅内容，或采用官方手动/npm 安装路径，避免直接执行未审阅的远程脚本。

macOS / Linux：

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

如果只想安装 CLI、暂时跳过 onboarding，可使用：

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

**Windows (PowerShell)**

在 PowerShell 中运行以下命令：

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

如需跳过 onboarding，可用官方脚本参数：

```powershell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
```

## 2.2.2 验证安装结果

安装后建议立即做一次最小验证（确保命令可用且 PATH 正确，更多 CLI 命令见[附录 E 命令速查表](/openclaw_guide/fu-lu/appendix/command_cheatsheet.md)）：

```bash
openclaw --version
openclaw --help
```

如果验证失败，不要立即重复安装。先确认命令究竟安装到了哪个运行环境，以及该环境的全局 npm 目录是否在 PATH 中。OpenClaw 支持 Node 22.22.3+、24.15+ 或 25.9+（含 Node 26），新安装推荐 Node 26，Node 23 不受支持；版本和 PATH 规则以[官方 Node.js 安装说明](https://docs.openclaw.ai/install/node)为准。

### macOS / Linux / WSL（POSIX shell）诊断

在**执行安装的同一个 shell 环境**中依次运行：

```bash
node --version
npm prefix -g
command -v openclaw
printf '%s\n' "$PATH"
openclaw doctor
openclaw gateway status
```

`npm prefix -g` 返回 `<npm-prefix>`；在 macOS、Linux 和 WSL 中，可执行文件通常位于 `<npm-prefix>/bin`。如果 `command -v openclaw` 没有结果，且 PATH 中没有这个目录，把下面一行加入当前 shell 的 `~/.zshrc` 或 `~/.bashrc`：

```bash
export PATH="$(npm prefix -g)/bin:$PATH"
```

保存后关闭并重新打开终端，再运行上述诊断。也可以在当前会话执行 `rehash`（zsh）或 `hash -r`（bash）刷新命令缓存。不要一边在 macOS/Linux 主机安装、一边在 WSL 中寻找命令；它们拥有不同的 Node、npm prefix 和 PATH。

### Windows PowerShell 诊断

原生 Windows 安装应在新的 PowerShell 窗口中运行：

```powershell
node --version
$npmPrefix = npm prefix -g
$npmPrefix
Get-Command openclaw -ErrorAction SilentlyContinue
$env:Path -split ';'
$env:Path -split ';' -contains $npmPrefix
openclaw doctor
openclaw gateway status --json
```

Windows 直接把 `<npm-prefix>` 加入 PATH，不追加 `/bin`。如果上面的 `-contains` 返回 `False`，在“设置 → 系统 → 环境变量”中把 `$npmPrefix` 的实际值加入用户 PATH，然后重新打开 Windows Terminal 或 PowerShell；已经打开的终端不会自动读取新 PATH。

### Windows Hub 与 WSL2 的路由边界

Windows 上有三条独立路径：Windows Hub、本机 PowerShell CLI/Gateway、手动安装在某个 WSL2 发行版中的 Gateway。先选定一条，再在对应环境诊断：

* Windows Hub 的“本地设置”会创建应用自有的 `OpenClawGateway` WSL 发行版并自动配对，不会修改你已有的 Ubuntu 发行版。此路径优先在 Hub 的 Command Center 和 Connections 中检查连接、配对和 Gateway 状态。
* PowerShell 原生安装使用 Windows 的 Node、npm prefix 和 PATH；不要用 WSL 的 `command -v` 判断它是否成功。
* 手动 WSL2 安装必须在安装所在的同一发行版运行诊断。从 PowerShell 先用 `wsl --list --verbose` 确认名称，再把 `<DistroName>` 替换为真实名称：

```powershell
wsl -d <DistroName> -- openclaw doctor
wsl -d <DistroName> -- openclaw gateway status
```

Windows 主机通常可通过 `localhost` 访问 WSL2 内监听的服务；跨机器连接不能把 `127.0.0.1` 当作远端 Gateway 地址，必须使用客户端可达的 URL，并同时检查绑定地址和防火墙。具体选择与故障入口见 [OpenClaw Windows 官方指南](https://docs.openclaw.ai/platforms/windows)；WSL NAT、mirrored networking 和端口转发规则见 [Microsoft WSL 网络文档](https://learn.microsoft.com/windows/wsl/networking)。

## 2.2.3 替代安装方式

如果一键脚本不适用于你的环境，以下是其他安装方式。

> \[!TIP] **首次部署只选一条路径跑通。** 如果你的目标只是先成功进入 Dashboard 并完成首轮对话，不要同时比较 npm、Docker、源码和运维化方案。最短成功路径永远优先，其余路径留到你确认需要容器化、自托管或定制化时再看。

如果你不确定该选哪一种，可以先按下面的决策树判断：

```mermaid
flowchart TD
  S["开始安装"] --> Q1{"想最快用起来？"}
  Q1 -->|"是"| A["一键脚本安装"]
  Q1 -->|"否"| Q2{"是否需要容器化/无头部署？"}
  Q2 -->|"是"| B["Docker 安装"]
  Q2 -->|"否"| Q3{"是否已深度使用 Node 生态？"}
  Q3 -->|"是"| C["npm / pnpm 全局安装"]
  Q3 -->|"否"| D["源码构建 / Podman / Nix / Ansible"]

  A --> V["验证：openclaw --version"]
  B --> V
  C --> V
  D --> V
```

图 2-1：OpenClaw 安装方式选择决策树

### 1. 使用 npm 安装

如果你熟悉 Node 生态，或者需要在特定流程中进行精确版本控制，也可以直接使用 `npm`、`pnpm` 或 `bun` 进行全局安装。

```bash
# npm 全局安装（npm 12 默认拦截包的生命周期脚本，
# 会跳过 OpenClaw 的 preinstall/postinstall，需显式放行：
# npm install -g openclaw@latest --allow-scripts openclaw）
npm install -g openclaw@latest

# pnpm 全局安装（全局安装不支持 approve-builds -g，
# 需在 pnpm add -g 上直接传 --allow-build=openclaw 放行构建脚本）
pnpm add -g --allow-build=openclaw openclaw@latest
```

建议：测试与生产环境不要长期依赖 `latest`。更稳妥的做法是固定到明确版本，并把版本号写进交付文档与回归清单。

```bash
npm install -g openclaw@<version>
```

### 2. Docker 安装

适合容器化、无头部署或需要隔离网关环境的场景。官方文档把 Docker 作为**可选安装路径**；如果你只是在本机快速跑通，普通安装流程通常更直接。

**前置要求**：Docker Desktop 或 Docker Engine（含 Docker Compose v2），内存不低于 [2.1](/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/02_setup/2.1_requirements.md) 的最低要求（4 GB）。

**快速安装（推荐）**：在 **OpenClaw 源码仓库根目录** 执行自动化脚本（不是本书仓库根目录），会自动完成镜像构建、引导向导、启动网关并生成 Token：

```bash
./scripts/docker/setup.sh
```

可通过环境变量自定义行为，例如启用沙箱，并在构建时包含指定的 bundled plugin helpers：

```bash
export OPENCLAW_SANDBOX=1
export OPENCLAW_EXTENSIONS="diagnostics-otel matrix"
./scripts/docker/setup.sh
```

也可使用官方预构建镜像跳过本地编译：

```bash
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh
```

官方 Docker 文档强调：上面的 setup 脚本会先做 onboarding，把 gateway token 写入 `.env`，再启动 `openclaw-gateway`。如果你只想跳过本地编译，可以保留 `OPENCLAW_IMAGE`，继续走同一脚本。

**手动安装**：如果不使用自动化脚本，可在 OpenClaw 源码仓库根目录依次执行以下命令。它更适合已经明确需要自定义镜像或拆开各步骤调试的读者，不是首次安装的推荐起点：

```bash
docker build -t openclaw:local -f Dockerfile .
docker compose run --rm --no-deps --entrypoint node openclaw-gateway dist/index.js onboard --mode local --no-install-daemon
docker compose run --rm --no-deps --entrypoint node openclaw-gateway dist/index.js config set gateway.mode local
docker compose run --rm --no-deps --entrypoint node openclaw-gateway dist/index.js config set gateway.bind lan
docker compose run --rm --no-deps --entrypoint node openclaw-gateway dist/index.js config set gateway.controlUi.allowedOrigins '["http://localhost:18789","http://127.0.0.1:18789"]' --strict-json
docker compose up -d openclaw-gateway
```

> \[!NOTE] 官方文档里，`openclaw-cli` 是网关启动后的后置工具容器。对首次 Docker setup 来说，应先用 `openclaw-gateway` 容器完成 onboarding 和配置写入，再启动 gateway。

**安装后验证**：浏览器访问 `http://127.0.0.1:18789/`，从 `.env` 文件获取 Token 并在控制台 Settings 的鉴权字段中粘贴。可通过健康检查端点确认网关状态：

```bash
curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz
```

本书仓库不包含上述 Docker 部署脚本与容器文件，更多配置选项详见 [官方 Docker 安装指南](https://docs.openclaw.ai/install/docker)。

### 3. 其他方式（源码构建、Podman、Nix、Ansible）

适用于开发定制或特定运维场景，请参阅 [官方安装文档](https://docs.openclaw.ai/install) 获取对应指引。

## 2.2.4 环境变量与路径覆盖

与路径覆盖直接相关的核心环境变量如下（尤其适用于多实例或非标准部署）：

* `OPENCLAW_HOME`：设置内部路径解析的主目录。
* `OPENCLAW_STATE_DIR`：覆盖可变状态存储目录。
* `OPENCLAW_CONFIG_PATH`：覆盖配置文件路径。

除此之外，当前官方文档还明确了环境变量加载顺序：进程环境 > 当前工作目录 `.env` > `~/.openclaw/.env` > Ubuntu 默认状态目录兼容回退 `~/.config/openclaw/gateway.env` > `openclaw.json` 的 `env` 块 > 可选 shell 导入（`OPENCLAW_LOAD_SHELL_ENV=1`）。因此，不要把这里误解成“OpenClaw 只认识这三个环境变量”。

详见 [官方环境变量文档](https://docs.openclaw.ai/help/environment)。

## 2.2.5 版本升级与治理

要升级到新版本，当前推荐先使用官方更新入口，它会识别安装方式、拉取目标版本、运行 `doctor` 并重启 Gateway：

```bash
openclaw update
```

重新运行安装脚本，或通过 npm、pnpm、bun 重新安装 `openclaw@<version>` / `@latest`，仍可作为恢复或手动升级路径。手动替换包之后，应立即重启 Gateway，并执行 `openclaw doctor`、`openclaw health` 等验收命令，避免旧进程继续使用已替换的包文件。

升级策略的目标不是单纯用上新版本，而是确保升级可验证、可回滚（版本号规则与配置迁移详见[附录 版本映射与升级指南](/openclaw_guide/fu-lu/appendix/version_mapping.md)）：

* 先回归再升级：每次升级后，至少覆盖 `health`、`status`、渠道探针与模型探针。
* 出问题先回滚：如果新版本异常，直接全局安装上一稳定版本（例如 `npm install -g openclaw@<旧版本号>`），再做差异定位。

> **踩坑实录：Node 版本引发的诡异症状**
>
> 一位社区用户报告 `openclaw` 安装成功但启动时持续报 `SyntaxError: Unexpected token`。排查三小时后发现系统默认 Node 是 v16（通过 `nvm` 遗留），低于 OpenClaw 当前官方兼容的 Node.js 22 LTS 支持线（当前 22.22.3+）；新安装推荐 Node.js 26，官方 CI 与发布流程则固定在 Node 24。教训：安装前务必执行 `node -v` 确认版本，尤其是使用 nvm 或 volta 等版本管理器的环境。