OpenClaw 中文文档 — 安装方式全解

OpenClaw 提供多种安装方式，覆盖从个人开发到生产部署的不同场景。本文对各安装方式的流程、适用范围和技术取舍做一个系统性的对比。

系统要求

所有安装方式共享相同的基础要求：

项目	要求
Node.js	24（推荐）或 22 LTS（22.16+）
操作系统	macOS、Linux、Windows（推荐 WSL2）
源码编译	额外需要 pnpm

安装方式总览

方式	部署模型	维护模式	安全隔离	适用场景
安装脚本	主机直装	手动更新	无	个人开发、快速验证
npm/pnpm	主机直装	手动更新	无	有 Node 环境的开发者
源码编译	主机直装	git pull	无	贡献者、二次开发
Docker	容器化	重建镜像	进程隔离	服务器部署
Podman	无根容器	重建镜像	用户命名空间隔离	安全优先的服务器
Nix	声明式	switch/rollback	Nix store 隔离	NixOS/Nix 用户
Ansible	主机直装+Docker 沙箱	重跑 playbook	四层纵深防御	生产服务器

安装脚本

OpenClaw 提供三个安装脚本：

install.sh（推荐）

适用于 macOS/Linux/WSL 的交互式安装：

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

执行流程：检测 OS → 确保 Node 24 → 确保 Git → npm 全局安装 → 运行引导向导。

macOS 上会在缺失时安装 Homebrew，Linux 上通过 NodeSource 脚本安装 Node。脚本默认设置 SHARP_IGNORE_GLOBAL_LIBVIPS=1，避免 sharp 构建时链接系统 libvips。

常用参数：

参数	说明
--no-onboard	跳过引导流程
--dry-run	试运行
--install-method git	从源码安装
--beta	使用 beta 版本
--verbose	调试输出

install-cli.sh

将 Node 和 OpenClaw 安装到本地前缀（默认 ~/.openclaw），不依赖系统 Node：

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

值得注意的是，这个脚本下载固定版本的 Node 压缩包并验证 SHA-256，适合对系统环境有严格要求的场景。

install.ps1

Windows PowerShell 安装脚本：

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

按需通过 winget、Chocolatey 或 Scoop 安装 Node。

CI/自动化场景

# 非交互式 npm 安装
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard

# JSON 输出（适合解析）
curl -fsSL https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw

npm / pnpm

直接通过包管理器安装，适合自行管理 Node 环境的开发者：

# npm
npm install -g openclaw@latest
openclaw onboard --install-daemon

# pnpm
pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

pnpm 的 approve-builds 步骤是其安全机制的一部分——带构建脚本的包需要显式审批。从安全角度看，这比 npm 的默认行为（自动执行所有生命周期脚本）更谨慎。

常见问题：sharp/libvips 冲突。解决方案：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

源码编译

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
pnpm link --global
openclaw onboard --install-daemon

也可以不链接全局，在仓库目录内通过 pnpm openclaw ... 运行。

Docker

Docker 部署适合隔离环境和服务器场景。需要 Docker Desktop/Engine + Compose v2，至少 2 GB 内存。

快速开始

./docker-setup.sh

脚本完成：镜像构建 → 引导向导 → 网关启动 → Token 生成。

也可以使用远程镜像：

OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest ./docker-setup.sh

配置要点

• gateway.bind 使用绑定模式值（lan/loopback），不要用主机别名
• Token 写入 .env 文件
• 公网部署需配置 gateway.controlUi.allowedOrigins
• OPENCLAW_SANDBOX=1 启用 Agent 沙箱

值得注意的是，Agent 沙箱使用 Docker，但不要求网关本身运行在 Docker 中——这是两个独立的关注点。

Podman

在无根容器中运行网关，使用与 Docker 相同的镜像：

# 一次性配置（创建 openclaw 用户、构建镜像）
./setup-podman.sh

# 启动网关
./scripts/run-openclaw-podman.sh launch

# 运行引导向导
./scripts/run-openclaw-podman.sh launch setup

相比 Docker 部署，Podman 方案有几个设计决策值得关注：

1. 专用系统用户：创建 openclaw 用户（nologin shell），减小攻击面
2. 无根模式：通过 subuid/subgid 映射实现用户命名空间隔离
3. Quadlet 集成：--quadlet 参数注册 systemd 用户服务，比传统的 podman generate systemd 更规范

# 注册 systemd 服务（可选）
./setup-podman.sh --quadlet

# 服务管理
sudo systemctl --machine openclaw@ --user start openclaw.service
sudo systemctl --machine openclaw@ --user status openclaw.service
sudo journalctl --machine openclaw@ --user -u openclaw.service -f

Nix

通过 nix-openclaw Home Manager 模块安装：

• 锁定版本的 Gateway + macOS 应用 + 工具
• 开机自启的 Launchd 服务
• 声明式插件配置
• 即时回滚：home-manager switch --rollback

Nix 模式下（OPENCLAW_NIX_MODE=1），自动安装和自变更流程被禁用，确保配置确定性。

Ansible

生产部署推荐方案，安全优先的自动化安装：

curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash

从架构层面来看，Ansible 方案实现了四层纵深防御：

1. UFW 防火墙：仅开放 SSH(22) + Tailscale(41641/udp)
2. Tailscale VPN：网关仅通过 VPN 可达
3. Docker 隔离：DOCKER-USER iptables 链阻止外部端口暴露
4. Systemd 加固：NoNewPrivileges、PrivateTmp、非特权用户

系统要求：Debian 11+ 或 Ubuntu 20.04+，Ansible 2.14+。

注意：网关直接运行在主机上，Docker 仅用于 Agent 沙箱。

Bun（实验性）

不推荐用于 Gateway 运行时（WhatsApp/Telegram 存在兼容性问题）。仅适合本地开发和 TypeScript 运行。

安装后验证

openclaw doctor         # 检查配置问题
openclaw status         # 网关状态
openclaw dashboard      # 打开控制面板

小结

从安装方式的选择可以看出 OpenClaw 的目标用户群：安装脚本和 npm 覆盖开发者日常使用；Docker/Podman 覆盖服务器部署；Ansible 覆盖生产环境；Nix 覆盖声明式管理的需求。这种多层次的安装支持在开源项目中算是比较全面的。

本文是系列第三篇。下一篇覆盖升级、迁移与卸载流程。

---

完整中文文档：OpenClaw 中文文档

GitHub 仓库：openclaw/openclaw