OpenClaw 怎么安装？官方脚本一键装好与报错速查

OpenClaw 的安装本身只要一条命令：macOS、Linux 和 WSL2 上用官方 curl 脚本，Windows 用 PowerShell 脚本，脚本会自动装好 Node 并启动新手引导，官方的说法是大约 5 分钟内就能和自己的 AI 助手聊上天。真正容易卡住的是 Node 版本、pnpm 构建批准和 PATH 这类环境细节，本文按 官方安装文档 把三条路线、验证方法、守护进程配置和报错一次讲清。

装之前：系统和 Node 版本要求

官方对 Node 的要求写得很死，这是第一个容易踩的坑：

1. 支持 Node 22.22.3+、24.15+ 或 25.9+，其中 Node 24 是安装、CI 和发布工作流的默认与推荐运行时。
2. Node 24 官方推荐 v24.15.0 或更新的 24.x；Node 22 走活跃 LTS 线；Node 25 需 25.9.0 及以上。
3. Node 23 明确不支持，装 23 会出问题，别用奇数版本凑数。

系统方面支持 macOS、Linux 和 Windows，Windows 用户有三个起点可选：原生 Windows Hub 应用、PowerShell CLI 安装程序或 WSL2 网关。只有从源码构建时才需要 pnpm，一键脚本会自动检测并安装 Node，不用手动装。硬件方面官方没有给硬性门槛，它本质是跑在你自己机器上的常驻 Agent，内存和磁盘按日常开发机标准即可。

路线一：官方一键脚本（推荐）

macOS、Linux 和 WSL2 用户执行：

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

Windows 用户在 PowerShell 里执行：

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

脚本会检测你的操作系统、在需要时安装 Node、安装 OpenClaw 并启动新手引导。只想先装好、暂不进引导流程的话，两个平台各有对应写法：macOS、Linux、WSL2 用 curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard，Windows 用 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard。

Windows 桌面用户还可以额外安装原生 Windows Hub 配套应用，里面带设置、托盘状态、聊天、节点模式和本地 MCP 模式，体验比纯命令行友好。

路线二：npm、pnpm、bun 手动装

已经自己管理 Node 的用户可以直接用包管理器，三条命令里最后一条都是装守护进程：

1. npm：执行 npm install -g openclaw@latest，再跑 openclaw onboard --install-daemon。
2. pnpm：执行 pnpm add -g openclaw@latest，注意首次安装后必须执行 pnpm approve-builds -g 批准带构建脚本的包，否则可能装完不可用，这是官方文档明确标注的坑。
3. bun：执行 bun add -g openclaw@latest，但要留意生成的可执行文件需要受支持的 Node 运行时，因为 OpenClaw 的状态存储依赖 node:sqlite。

还有一个官方提示容易被忽略：托管安装程序会为 OpenClaw 清除 npm 的「新鲜度」过滤条件（例如 min-release-age），但如果你走手动 npm 安装，你自己的 npm 策略依然生效，可能导致装到的版本比官方脚本旧。

路线三：本地前缀、源码和容器

1. 本地前缀安装，不想污染系统 Node 环境的首选：curl -fsSL https://openclaw.ai/install-cli.sh | bash，会把 OpenClaw 和 Node 装在 ~/.openclaw 这类本地前缀下。
2. 源码安装，面向贡献者：克隆 GitHub 仓库 后执行 pnpm install && pnpm build && pnpm ui:build，再 pnpm link --global。
3. 指定 main 分支安装：curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git --version main。
4. 容器部署：Docker 或 Podman，适合服务器和无头环境；另有 Nix、Ansible、Kubernetes 等进阶方式，文档均有独立章节。

不确定选哪条？个人电脑选路线一，服务器选 Docker，爱折腾环境隔离选本地前缀。

验证安装成功的 3 条命令

openclaw --version
openclaw doctor
openclaw gateway status

第一条确认 CLI 可用，第二条让官方诊断工具检查配置问题，第三条确认 Gateway 网关正在运行。三条都正常，安装就算完成了。希望开机常驻的话，用 openclaw onboard --install-daemon 装成守护进程：macOS 走 LaunchAgent，Linux 和 WSL2 走 systemd 用户服务，原生 Windows 优先用计划任务、任务创建被拒时回退到每用户「启动」文件夹的登录项。

常见报错速查表

下面这份表把官方安装文档和网关排障文档里明确写到的错误现象整理到一起：

更新或启动异常时的官方诊断顺序

如果装完能用、但更新后突然不工作，官方建议按固定顺序排查，而不是乱试：

1. openclaw status，看整体与更新交接状态。
2. openclaw gateway status，确认显示 Runtime: running 与 Connectivity probe: ok。
3. openclaw logs --follow，实时看日志里的第一处报错。
4. openclaw doctor（必要时 --fix），让它自动修复阻塞性配置问题。
5. openclaw channels status --probe，确认各渠道账户的实时传输状态正常。

另外两类报错官方也列得很清楚：一是某个 openclaw 二进制比最后写入配置的版本更旧时，OpenClaw 会用 meta.lastTouchedVersion 拒绝执行启动、重启、卸载等操作，需要用 openclaw config get meta.lastTouchedVersion 确认并修正 PATH；二是接本地 OpenAI 兼容后端时，直连 curl 能通过但 Agent 轮次失败，通常要给模型加 compat.requiresStringContent: true 或 compat.strictMessageKeys: true。这两类问题都不是重装能解决的，别急着重来一遍。

一个重要提醒：认准官方域名

官方文档站是 docs.openclaw.ai，项目主域是 openclaw.ai，代码在 GitHub 的 openclaw/openclaw 仓库。搜索结果里还有 openclaws.io、open-claw.org.cn 等相似域名，多为第三方社区站或教程站，命令可能过时甚至有误导，动手前先和官方文档核对一遍再执行。

装完之后：绑定渠道和模型

新手引导会带你配置网关和第一个 Agent。OpenClaw 的核心玩法是让 AI 在你自己的电脑上干活：绑定 Telegram 等消息渠道后，你在聊天窗口发一句话，它就替你读写文件、跑命令、做监控。渠道配置和模型接入的逐项说明，看官方文档的消息渠道和模型两章即可，站内的 OpenClaw 2.0 更新解读 和 OpenClaw 能做什么 可以帮你明确任务边界。