跳转到主要内容

​
安装

已经按照 入门指南 操作过了吗？那你已经准备好了 —— 本页适用于其他安装方法、特定平台说明以及维护操作。

​
系统要求

  • Node 24（推荐）（出于兼容性考虑，仍支持 Node 22 LTS，目前为 22.16+；如果缺失，安装脚本 会安装 Node 24）
  • macOS、Linux 或 Windows
  • 仅当你从源码构建时需要 pnpm
在 Windows 上，我们强烈建议你在 WSL2 下运行 OpenClaw。

​
安装方法

安装脚本 是安装 OpenClaw 的推荐方式。它会一步完成 Node 检测、安装和新手引导。
对于 VPS/云主机，尽量避免使用第三方“一键式”市场镜像。优先选择干净的基础 OS 镜像（例如 Ubuntu LTS），然后使用安装脚本自行安装 OpenClaw。

安装脚本

下载 CLI，通过 npm 全局安装，并启动设置向导。
curl -fsSL https://openclaw.ai/install.sh | bash
就这样 —— 脚本会处理 Node 检测、安装和新手引导。如果要跳过新手引导，只安装二进制文件：
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
所有标志、环境变量以及 CI/自动化选项，请参阅 Installer internals。
如果你已经自行管理 Node，我们推荐使用 Node 24。出于兼容性考虑，OpenClaw 仍支持 Node 22 LTS，目前为 22.16+：
npm install -g openclaw@latest
openclaw onboard --install-daemon
如果你全局安装了 libvips（在 macOS 上通过 Homebrew 很常见），并且 sharp 失败，请强制使用预构建二进制文件：
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
如果你看到 sharp: Please add node-gyp to your dependencies，请安装构建工具链（macOS：Xcode CLT + npm install -g node-gyp），或者使用上面的环境变量。
想通过包管理器安装当前 GitHub main 分支最新版本？
npm install -g github:openclaw/openclaw#main

pnpm add -g github:openclaw/openclaw#main
适用于贡献者或任何想从本地检出运行的人。
1

克隆并构建

克隆 OpenClaw 仓库 并构建：
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
2

链接 CLI

让 openclaw 命令在全局可用：
pnpm link --global
或者，你也可以跳过链接，直接在仓库内通过 pnpm openclaw ... 运行命令。
3

运行新手引导

openclaw onboard --install-daemon
更深入的开发工作流请参阅 Setup。

​
其他安装方法

Docker

容器化或无头部署。

Podman

无 root 容器：先运行一次 setup-podman.sh，然后运行启动脚本。

Nix

通过 Nix 进行声明式安装。

Ansible

自动化批量配置。

Bun

通过 Bun 运行时进行仅 CLI 使用。

​
安装后

验证一切是否正常工作： 
openclaw doctor         # 检查配置问题
openclaw status         # Gateway 网关状态
openclaw dashboard      # 打开浏览器 UI
如果你需要自定义运行时路径，请使用：
  • OPENCLAW_HOME 用于基于主目录的内部路径
  • OPENCLAW_STATE_DIR 用于可变状态位置
  • OPENCLAW_CONFIG_PATH 用于配置文件位置
有关优先级和完整细节，请参阅 Environment vars。

​
故障排除：找不到 openclaw

快速诊断：
node -v
npm -v
npm prefix -g
echo "$PATH"
如果 $(npm prefix -g)/bin（macOS/Linux）或 $(npm prefix -g)（Windows）不在你的 $PATH 中，那么你的 shell 就找不到全局 npm 二进制文件（包括 openclaw）。修复方法 —— 将其添加到你的 shell 启动文件（~/.zshrc 或 ~/.bashrc）中：
export PATH="$(npm prefix -g)/bin:$PATH"
在 Windows 上，将 npm prefix -g 的输出添加到你的 PATH 中。然后打开一个新的终端（或者在 zsh 中运行 rehash，在 bash 中运行 hash -r）。

​
更新 / 卸载

更新

让 OpenClaw 保持最新。

迁移

迁移到新机器。

卸载

完全移除 OpenClaw。