Skip to content

2.2_installation.md

Latest commit

 

History

History
247 lines (167 loc) · 12.3 KB

2.2_installation.md

File metadata and controls

247 lines (167 loc) · 12.3 KB
Raw

2.2 安装 OpenClaw

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

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

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

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

前置检查

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

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

开始安装

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

macOS / Linux：

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

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

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

Windows (PowerShell)

在 PowerShell 中运行以下命令：

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

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

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

2.2.2 验证安装结果

安装后建议立即做一次最小验证（确保命令可用且 PATH 正确，更多 CLI 命令见附录 E 命令速查表）：

openclaw --version
openclaw --help

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

macOS / Linux / WSL（POSIX shell）诊断

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

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：

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

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

Windows PowerShell 诊断

原生 Windows 安装应在新的 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> 替换为真实名称：
wsl -d <DistroName> -- openclaw doctor
wsl -d <DistroName> -- openclaw gateway status

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

2.2.3 替代安装方式

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

Tip

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

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

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
Loading

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

1. 使用 npm 安装

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

# npm 全局安装（npm 12 默认拦截包的生命周期脚本，
# 会跳过 OpenClaw 的 preinstall/postinstall，需用 --allow-scripts= 显式放行；
# 注意是等号形式，写成空格会被当成第二个待装包名。
# npm 11.15 及更早没有这个选项，命令要去掉该参数）
npm install -g openclaw@latest --allow-scripts=openclaw

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

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

npm install -g openclaw@<version> --allow-scripts=openclaw

2. Docker 安装

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

前置要求：Docker Desktop 或 Docker Engine（含 Docker Compose v2），内存不低于 2.1 的最低要求（4 GB）。

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

./scripts/docker/setup.sh

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

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

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

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

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

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

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 的鉴权字段中粘贴。可通过健康检查端点确认网关状态：

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

本书仓库不包含上述 Docker 部署脚本与容器文件，更多配置选项详见 官方 Docker 安装指南。

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

适用于开发定制或特定运维场景，请参阅 官方安装文档 获取对应指引。

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 只认识这三个环境变量”。

详见 官方环境变量文档。

2.2.5 版本升级与治理

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

openclaw update

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

升级策略的目标不是单纯用上新版本，而是确保升级可验证、可回滚（版本号规则与配置迁移详见附录 版本映射与升级指南）：

  • 先回归再升级：每次升级后，至少覆盖 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 等版本管理器的环境。