奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

OpenClaw 该用哪种方式装：脚本、npm、Bun、Docker 的前置条件与升级路径对照

2026-08-17

第一次部署 OpenClaw 的人，通常卡在文档的第一页：安装页上并排摆着安装脚本、本地前缀脚本、npm / pnpm / bun、源码 checkout、Docker，还有 Ansible、Nix、Podman、Kubernetes 一排卡片。每一条看上去都能跑通，问题是没人告诉你选错的代价是什么。

代价其实是有的，而且不在安装当天。安装方式决定了三件事：OpenClaw 的代码装在哪个前缀下、Gateway 服务由谁托管、以及半年后你敲 openclaw update 时更新器会去动哪个目录。官方文档里关于升级、回滚、通道切换的绝大部分内容，前提都是”你的安装类型是 X”。所以这篇不按”怎么装”排，按”装完之后你会遇到什么”排。

先说结论式的判断依据：如果你只是想在自己机器上先跑起来，用官方安装脚本；如果这台机器上的 Node 你不想被动，用本地前缀脚本；如果你已经有成熟的 Node 环境和自己的运维习惯，用 npm 手装；如果你要的是一个可丢弃的隔离环境或者一台没装 Node 的宿主机，用 Docker。 下面把每条路的依据摊开。

三件不管走哪条路都绕不开的事

第一是 Node 版本门槛。 官方文档写明支持 Node 22.22.3+、24.15+ 或 25.9+，Node 26 是默认和推荐的运行时，Node 23 明确不支持。文档还提到 CI 和发布流程目前仍固定在 Node 24，Node 22 通过其 LTS 线继续受支持。关于 Node 26 的好处，文档的说法是它”启动 Gateway 明显更快、比 Node 24 占用更少内存”——这是官方文档的表述，没有给出具体数字。

第二是 node:sqlite。 OpenClaw 的状态存储依赖 Node 的 node:sqlite API，这一条直接决定了 Bun 的处境，后面单独讲。它也解释了为什么 Alpine/musl 环境会被文档反复点名：安装脚本在 Alpine 上会改用 apk 包，并且会校验实际链接的 SQLite 版本。文档明说当前稳定版 Alpine 包流可能提供了足够新的 Node，却仍链着有漏洞的系统 SQLite；碰到这种情况，建议改用官方的 node:26-alpine 容器或者一台基于 glibc 的主机。

第三是 Git。 即使你走 npm 方式，安装脚本也会检查并安装 Git——文档给的理由是避免依赖里出现 git URL 时报 spawn git ENOENT。走 git 安装方式的话 Git 就是硬依赖。

顺带一提，pnpm 只有在你从源码构建时才需要。

五条路的对照

安装方式装到哪里前置条件适合谁
install.sh / install.ps1全局 npm 前缀（默认）或 ~/openclaw checkout无（缺 Node 会自动装）绝大多数第一次部署的人
install-cli.sh本地前缀，默认 ~/.openclaw无，Node 也装在前缀里不想依赖系统级 Node、不想要 root 的环境
npm / pnpm / bun 手装你自己的全局前缀自备符合版本要求的 Node已有 Node 管理习惯的人
源码 checkout你 clone 的目录Node + pnpm + Git贡献者、要改代码的人
Docker容器 + 挂载卷Docker Desktop 或 Engine + Compose v2，构建至少 2 GB 内存要隔离环境或宿主机不装 Node

安装脚本：install.sh 和 install-cli.sh 不是同一件事

官方一共提供三个脚本，都从 openclaw.ai 分发：install.sh（macOS / Linux / WSL）、install-cli.sh（同平台，本地前缀）、install.ps1（Windows PowerShell）。

install.sh 是推荐路径：

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

它的流程是检测系统、按需装 Node（macOS 用 Homebrew，Linux apt/dnf/yum 用 NodeSource 脚本）、确保 Git 存在、用 npm 全局装 OpenClaw，然后进入 onboarding。macOS 上 Homebrew 只在脚本确实需要它装 Node 或 Git 时才会被安装。不想跑 onboarding 就加 --no-onboard。

有一个细节值得留意：如果你恰好在一个 OpenClaw 源码 checkout 里（脚本靠 package.json + pnpm-workspace.yaml 判断）运行它，脚本会问你用 checkout 还是全局安装；没有 TTY 又没指定安装方式时，它默认走 npm 并给出警告。安装方式选择非法或 --install-method 取值非法时，脚本以退出码 2 结束——这一条对写 CI 的人有用。

install-cli.sh 解决的是另一个问题：把 OpenClaw 和 Node 都放进一个本地前缀（默认 ~/.openclaw），不依赖系统级 Node，也不需要 root。

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

它会下载一个固定版本的 Node LTS 压缩包到 <prefix>/tools/node-v<version> 并校验 SHA-256，版本号内嵌在脚本里独立更新，默认 24.15.0；Linux ARMv7 上用 22.22.3，因为官方没有 Node 24+ 的 ARMv7 二进制。装完它会跑一次 <prefix>/bin/openclaw --version，拿不到非空版本号就直接报错停下——这个自校验比很多安装脚本讲究。它还支持 --json 输出 NDJSON 事件，适合接自动化。

两个脚本共有的自动化开关值得记一下：--dry-run 只打印不改动，--no-prompt 关掉交互，--verify 跑一次装后冒烟检查。环境变量形式也齐全（OPENCLAW_INSTALL_METHOD、OPENCLAW_VERSION、OPENCLAW_NO_ONBOARD、OPENCLAW_DRY_RUN 等）。CI 里典型写法是：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard

想装 GitHub main 分支的代码，注意不能用 npm 的版本号写法。文档明说 openclaw@main 这类 GitHub 源规格不是合法的 --version 目标，要写成：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git --version main

用包管理器手装：三个不同的拦路虎

如果你自己管理 Node，三条命令看起来长得差不多，坑却各不相同。

npm 的坑是生命周期脚本被拦。 文档写得很具体：npm 12 默认阻止包的生命周期脚本，所以普通的全局安装会跳过 OpenClaw 的 preinstall 和 postinstall，npm 会报它们 blocked because they are not covered by allowScripts。正确写法是显式放行：

npm install -g openclaw@latest --allow-scripts openclaw
openclaw onboard --install-daemon

npm 11.16.x 只是警告脚本 not yet covered by allowScripts，仍然会执行。想消掉这个警告的话，别照 npm 建议的 npm approve-scripts openclaw 去做——文档说这条命令对全局安装无效，会以 ENOMATCH No installed packages match: openclaw 失败。npm 11.12 及更早没有这套策略。

还有一条容易被忽略：官方托管的安装脚本会为 OpenClaw 包的安装清掉 npm 的 min-release-age 之类新鲜度过滤；你手动用 npm 装，你自己的 npm 策略照旧生效。

pnpm 的坑是构建审批。 pnpm 要求对带构建脚本的包显式批准，而 approve-builds -g 不支持全局安装，所以只能在 pnpm add -g 这条命令上传参：

pnpm add -g --allow-build=openclaw openclaw@latest
openclaw onboard --install-daemon

Bun 的坑最根本：它能装，但不一定能跑。 文档的警告写得很直白——Bun 到 1.3.x 为止无法运行 OpenClaw 的 CLI 和 Gateway，因为它们不提供必需的 node:sqlite API。OpenClaw 会对运行时做特性探测：带 node:sqlite 的 Bun 构建（1.4.0 canary 及之后）可以实验性地跑 CLI 和 Gateway，更旧的 Bun 版本在启动时就会被拒绝。Node 仍然是所有 OpenClaw 运行时命令受支持且被推荐的运行时。

换句话说，bun add -g openclaw@latest 装出来的 openclaw 可执行文件，仍然需要一个受支持的 Node 运行时。Bun 在这个项目里更现实的定位是可选的包脚本运行器：默认包管理器仍是 pnpm，而且 Bun 用不了 pnpm-lock.yaml 也会忽略它，当前 Bun 版本（包括 1.4 canary）解析不了这个仓库的 pnpm-workspace.yaml 布局，bun install 会在工作区解析阶段失败，所以依赖安装还是得用 pnpm install。构建和测试倒是可以走 Bun：

bun run build
bun run vitest run

另外 Bun 默认拦依赖的生命周期脚本，对这个仓库来说常被拦的两个（baileys 的 preinstall、protobufjs 的 postinstall）都不是必需的；真需要时用 bun pm trust baileys protobufjs 显式信任。还有一批包脚本（check:docs、ui:*、protocol:check）内部硬编码了 pnpm，用 bun run 跑它们等于绕一圈再 shell 出去调 pnpm，不如直接用 pnpm。

Docker：隔离换来的是另一套运维

文档把 Docker 定位成可选：适合做隔离的、用完即弃的 Gateway 环境，或者一台不想装本地依赖的宿主机；如果你本来就在自己机器上开发，用常规安装流程就行。这里要分清两件事——Gateway 跑在容器里，和 Agent 的沙箱用 Docker，是两个独立的开关，沙箱默认关闭，而且沙箱不要求 Gateway 本身跑在容器里。

前置条件是 Docker Desktop 或 Engine 加 Docker Compose v2，镜像构建至少 2 GB 内存（文档提到 1 GB 主机上 pnpm install 可能被 OOM 杀掉，表现为退出码 137）。镜像可以本地构建成 openclaw:local，也可以用预构建镜像；官方说 GHCR 是发布自动化、固定部署和溯源检查的主注册表，同一次发布会在 Docker Hub 发一份镜像。变体包括 slim、main-slim、extended-stable-slim、latest-browser 等，-browser 变体预装了 Chromium。

几个新手常撞的点：绑定模式要写 gateway.bind 支持的取值（lan / loopback / custom / tailnet / auto），不要写 0.0.0.0 或 127.0.0.1 这种主机别名；容器里的 127.0.0.1 是容器自己，连宿主机上的 LM Studio 或 Ollama 要用 host.docker.internal；镜像以 node（uid 1000）身份运行，宿主机 bind mount 的属主对不上就会在 /home/node/.openclaw 上报权限错误。持久化方面，Compose 会把配置目录挂到 /home/node/.openclaw、工作区挂到 /home/node/.openclaw/workspace、auth-profile 密钥目录挂到 /home/node/.config/openclaw。容器化部署的完整步骤和排错，另见 OpenClaw Docker 部署。

Windows 单独说

Windows 用户有三条起点：原生的 Windows Hub 应用、PowerShell CLI 安装器、或者 WSL2 上的 Gateway。

install.ps1 需要 PowerShell 5+。缺 Node 时它依次尝试 winget、Chocolatey、Scoop；都没有的话，下载官方 Node.js 26 的 Windows zip 到 %LOCALAPPDATA%\OpenClaw\deps\portable-node 并加进当前进程和用户 PATH。走 git 方式而系统没有 Git 时，脚本会先引导一份用户级 MinGit 到 %LOCALAPPDATA%\OpenClaw\deps\portable-git，再考虑提示你去装 Git for Windows。

Windows 上最高频的问题是装完提示 openclaw is not recognized。官方给的处理是跑 npm config get prefix，把那个目录加进用户 PATH（Windows 上不需要 \bin 后缀），然后重开 PowerShell。macOS / Linux 上同类问题的排查顺序是 node -v、npm prefix -g、echo "$PATH" 三连，缺的话在 ~/.zshrc 或 ~/.bashrc 里加 export PATH="$(npm prefix -g)/bin:$PATH"。用 nvm / fnm / mise 这类版本管理器的话，务必在 shell 启动文件里初始化它，否则新开的终端里 PATH 不含 Node 的 bin 目录，openclaw 照样找不到。

升级路径才是真正的分水岭

选安装方式的时候盯着安装命令看，是次要的；真正该看的是升级那一步。

官方推荐的升级入口是一条命令，它会检测你的安装类型（npm、pnpm、Bun 或 git），拉取最新版本，跑 openclaw doctor，然后重启 Gateway：

openclaw update

通道是这里的核心概念：stable、beta、extended-stable、dev。其中 dev 给的是一个持续跟随 GitHub main 的 checkout，stable / extended-stable / beta 走包安装。有意思的是，通道也是切换安装类型的手段：

# npm 包安装 -> 可编辑的 git checkout
openclaw update --channel dev

# git checkout -> npm 包安装
openclaw update --channel stable

文档明说更新器只改”CLI 和 Gateway 用哪份 OpenClaw 代码”，你的状态、配置、凭据和工作区都留在 ~/.openclaw 里。这大幅降低了第一次选错的代价——但也只覆盖 npm ↔ git 这条线。Docker 部署不在这条线上：容器镜像替换有单独的一套流程，你换掉镜像但保留挂载的状态/配置时，新 Gateway 会在就绪前跑启动期安全的升级迁移和插件收敛；如果这些修复没法安全完成，Gateway 会直接退出而不是报告健康。

从 git checkout 直接跑 Gateway 的服务器还有第三条路：checkout 内的 scripts/update-gateway.sh，它会恢复被 pnpm build 重写的受跟踪构建产物、遇到任何其它本地改动就 fail closed、快进 main、装依赖、干净构建、重启 Gateway。不过文档也说了，单人的源码安装更推荐直接用 openclaw update --channel dev。

自动更新默认关闭，要开得改 ~/.openclaw/openclaw.json：

{
  update: {
    channel: "stable",
    auto: {
      enabled: true,
    },
  },
}

回滚同样分层：先做只换代码的回滚（openclaw update --tag <known-good-version>，文档强调它优于直接用包管理器装，因为它会识别降级、要求确认、跑插件收敛和兼容性检查、刷新服务元数据并验证运行版本），实在不行才恢复状态。升级前建议显式做一次可验证备份，因为 openclaw update 只保留一份自动的更新前配置副本，不是完整的状态恢复点。这块的完整取舍见 OpenClaw 更新与回滚。

装完先跑这三条

不管哪条路，验证动作是一样的：

openclaw --version      # CLI 是否可用
openclaw doctor         # 检查配置问题
openclaw gateway status # 确认 Gateway 在跑

openclaw doctor 在升级之后同样要跑一遍——它会迁移配置、审计 DM 策略、检查 Gateway 健康。它的输出信息量不小，怎么读见 OpenClaw doctor 输出怎么读。

托管启动的方式按平台不同：macOS 是通过 openclaw onboard --install-daemon 或 openclaw gateway install 装 LaunchAgent；Linux / WSL2 是同样命令装 systemd 用户服务；原生 Windows 优先用计划任务，任务创建被拒时回落到每用户的启动文件夹登录项。这三种托管形式的差异，会在后续所有”重启 Gateway”的操作里反复出现，值得在选安装方式时一并想清楚。想先搞明白 Gateway、CLI、插件这几层是什么关系，可以先看 OpenClaw 架构总览。

什么时候这篇不适用，以及还有哪些没解决

这篇只覆盖了官方安装文档里的五条主路。文档同页还列了 Ansible、ClawDock、Nix、Podman 这些容器与包管理器入口，以及 Cloudflare Containers（文档标为实验性）、Kubernetes、macOS VM、Upstash Box、Render 等托管部署方案——这些页面本文没有读，所以不下任何判断。同理，Windows Hub 原生应用除了”包含设置、托盘状态、聊天、节点模式和本地 MCP 模式”这句官方描述之外，本文没有更多信息。

几个明确的空白也说在前面：官方安装文档没有给出除”构建镜像至少 2 GB 内存”之外的硬件要求，没有磁盘容量下限，也没有各安装方式的耗时对比——想要这些数字的话，文档里没有，别信任何替你编出来的版本。多用户托管场景（一租户一 cell 的模型）在另一篇文档里，本文没覆盖。

最后一个提醒：如果你现在还没想好，选官方 install.sh 的机会成本是最低的——npm 和 git 两种安装类型之间可以靠通道来回切，状态不动。真正难回头的是 Docker 与非 Docker 之间的选择，因为那涉及状态目录的挂载形态和整套升级流程的替换。这个决定值得在动手之前多花十分钟。

延伸阅读

本文依据 OpenClaw 官方仓库（github.com/openclaw/openclaw）docs/ 下的官方文档整理，核对日 2026-08-17。 我们没有安装或运行过 OpenClaw，因此不涉及界面外观、操作手感与实测耗时的任何描述； 文中的默认值、命令与配置项均为文档口径，不构成对实际运行结果的保证。 该项目迭代很快，请以仓库最新内容为准。接入即时通讯平台前，请自行确认所在平台的规则与合规要求。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员