search

2.2 安装 OpenClaw

本节介绍如何在你选择的环境中安装 OpenClaw。官方推荐使用一键安装脚本以获得最佳体验，也可通过 npm 等包管理器进行安装。

hashtag
2.2.1 官方推荐：一键安装脚本

最简单快捷的安装方式是执行官方的一键安装脚本。该脚本会自动处理依赖并安装最新版 OpenClaw CLI。

macOS / Linux

在终端中运行以下命令：

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

Windows (PowerShell)

在 PowerShell 中运行以下命令：

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

hashtag
2.2.2 替代方案：使用 npm 安装

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


# npm 全局安装
npm install -g openclaw@latest

# pnpm 全局安装
pnpm add -g openclaw@latest

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

hashtag
2.2.3 Docker 安装

适合容器化或无头部署场景。

前置要求：Docker Desktop 或 Docker Engine（含 Docker Compose v2），至少 2 GB 内存。

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

可通过环境变量自定义行为，例如启用沙箱和预装扩展：

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

手动安装：如果不使用自动化脚本，可依次执行以下命令：

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

更多配置选项详见 官方 Docker 安装指南arrow-up-right。

hashtag
2.2.4 源码构建

适合开发者或需要定制修改的场景。需要 Node >= 22 和 pnpm。

启动网关：

开发模式（热重载）：

更新时执行 git pull，若 lockfile 变更则重新运行 pnpm install。更多详见 官方源码构建指南arrow-up-right。

hashtag
2.2.5 其他安装方式

官方还支持以下安装方式，适用于特定运维场景：

hashtag
2.2.6 环境变量与路径覆盖

OpenClaw 提供以下环境变量，用于覆盖默认路径（尤其在多实例或非标准部署时有用）：

  • OPENCLAW_HOME：设置内部路径解析的主目录。

  • OPENCLAW_STATE_DIR：覆盖可变状态存储目录。

  • OPENCLAW_CONFIG_PATH：覆盖配置文件路径。

详见 官方环境变量文档arrow-up-right。

hashtag
2.2.7 验证安装结果

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

hashtag
2.2.8 版本升级与治理

要升级到新版本，如果你使用的是一键脚本安装，可以重新运行脚本；如果使用的是包管理器，只需重新运行全局安装命令并指定 <version> 标签（或 @latest）即可。

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

  • 先回归再升级：每次升级后，至少覆盖 health、status、渠道探针与模型探针。

  • 出问题先回滚：如果新版本异常，直接全局安装上一稳定版本（例如 npm install -g openclaw@<旧版本号>），再做差异定位。

💡 踩坑实录：Node 版本引发的诡异症状

一位社区用户报告 openclaw 安装成功但启动时持续报 SyntaxError: Unexpected token。排查三小时后发现系统默认 Node 是 v16（通过 nvm 遗留），而 OpenClaw 要求 Node 22+。教训：安装前务必执行 node -v 确认版本，尤其是使用 nvm 或 volta 等版本管理器的环境。

上一页2.1 系统要求与运行前检查下一页2.3 初始化向导与首轮配置

最后更新于