第2章环境准备与安装

一句话：装好 Node.js，跑一行命令，OpenClaw 就装好了——但国内用户有几个坑要提前避开。

2.1 系统要求

OpenClaw 是一个 Node.js 应用，对系统要求不高：

项目	要求
Node.js	v22.16+（推荐 v24，v22 LTS 也支持）
操作系统	macOS、Linux、Windows（需 WSL2）
内存	最低 512MB 可用（推荐 1GB+）
磁盘	约 200MB（安装本体 + 依赖）
网络	需能访问 LLM API 端点；若接 Telegram/Discord 等海外渠道，需代理

关于 Node.js 版本

OpenClaw 强制要求 Node.js v22.16 以上，推荐 Node 24（官方默认运行时），v22 LTS 也支持。如果你还没装 Node.js，推荐用 nvm（Node Version Manager）管理版本：

# 安装 nvm（macOS / Linux）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# 重新打开终端，然后安装 Node 24（推荐）
nvm install 24
nvm use 24

# 验证
node --version
# 应输出 v24.x.x

其他安装方式：

# macOS（Homebrew）
brew install node

# Linux (Ubuntu / Debian)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows（winget）
winget install OpenJS.NodeJS.LTS

其他版本管理器：fnm、mise、asdf 都可以。

注意：Windows 原生命令行对 OpenClaw 的支持有限。强烈建议 Windows 用户使用 WSL2（Windows Subsystem for Linux）。WSL2 中的体验和 Linux 完全一致，后续章节的所有命令都基于 macOS / Linux 环境。

WSL2 快速安装（Windows 用户）

# 在 PowerShell（管理员）中执行
wsl --install

# 安装完成后重启电脑，然后在 WSL 终端中照常安装 nvm + Node.js

2.2 安装方法一：一键脚本（推荐）

这是最简单的安装方式，脚本会自动检测系统环境、安装依赖、配置 PATH。

macOS / Linux / WSL2：

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

Windows PowerShell：

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

脚本做了什么：

检测是否已安装合适版本的 Node.js，若没有会提示你安装
通过 npm 全局安装 openclaw
将 openclaw 添加到 PATH
运行 openclaw doctor 做一次安装后自检

如果只想安装不想跑向导：

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

国内用户提示：如果 curl 下载脚本很慢或超时，可以先设置代理：
Terminal window
export https_proxy=http://127.0.0.1:7890
curl -fsSL https://openclaw.ai/install.sh | bash
或者跳过一键脚本，使用下面的 npm 手动安装方法。

2.3 安装方法二：npm 全局安装

如果你已经有 Node.js 环境，一行命令搞定：

npm install -g openclaw@latest

国内镜像加速

npm 默认从 registry.npmjs.org 下载包，国内速度感人。推荐使用 npmmirror 镜像：

# 方法一：只对这次安装使用镜像（推荐，不影响全局配置）
npm install -g openclaw --registry=https://registry.npmmirror.com

# 方法二：全局切换 npm 镜像源
npm config set registry https://registry.npmmirror.com
npm install -g openclaw

# 如果以后想换回官方源
npm config set registry https://registry.npmjs.org

小技巧：你也可以安装 nrm（npm registry manager）来快速切换镜像源：
Terminal window
npm install -g nrm
nrm ls          # 查看可用源
nrm use taobao  # 切换到淘宝镜像

pnpm 安装

pnpm add -g openclaw@latest
pnpm approve-builds -g        # 审批构建脚本（openclaw、node-llama-cpp、sharp 等）
openclaw onboard --install-daemon

注意：pnpm 需要显式批准带构建脚本的包。第一次安装看到 “Ignored build scripts” 警告后，运行 pnpm approve-builds -g 选择对应的包。

2.4 npm 全局路径踩坑（重要！）

这是国内用户反馈最多的安装问题：npm 全局安装成功了，但终端找不到 openclaw 命令。

典型表现：

$ npm install -g openclaw
# ...安装成功...

$ openclaw --version
zsh: command not found: openclaw
# 或
bash: openclaw: command not found

原因是 npm 的全局 bin 目录没有加入系统 PATH。三步排查法：

第一步：找到 npm 全局 bin 路径

npm config get prefix
# 常见输出：
# macOS:  /usr/local  或  /Users/你的用户名/.nvm/versions/node/v22.x.x
# Linux:  /usr/local  或  /home/你的用户名/.nvm/versions/node/v22.x.x

你要加入 PATH 的是上面输出 + /bin，比如 /usr/local/bin 或 /Users/你的用户名/.nvm/versions/node/v22.x.x/bin。

第二步：添加到 PATH

# 查看你用的是什么 shell
echo $SHELL

# 如果是 zsh（macOS 默认）
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 如果是 bash
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

第三步：验证

which openclaw
openclaw --version
# 应输出版本号

还是不行？ 试试以下排查：

# 查看 openclaw 到底装到了哪里
npm list -g --depth=0 | grep openclaw

# 查看 npm bin 目录下有没有 openclaw
ls "$(npm config get prefix)/bin/" | grep openclaw

# 如果用了 nvm，确保当前 shell 加载了 nvm
nvm current

2.5 安装方法三：Docker / Podman 部署

如果你不想在宿主机装 Node.js，可以用容器运行 OpenClaw。

Docker 快速开始

docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -p 18789:18789 \
  -v ~/.openclaw:/home/node/.openclaw \
  -e DEEPSEEK_API_KEY=sk-your-key-here \
  ghcr.io/openclaw/openclaw:latest

参数说明：

参数	说明
`-d`	后台运行
`--restart unless-stopped`	容器异常退出时自动重启
`-p 18789:18789`	映射 Dashboard 端口
`-v ~/.openclaw:/home/node/.openclaw`	持久化配置和数据目录（容器以 node 用户运行）
`-e DEEPSEEK_API_KEY=...`	通过环境变量注入 API Key

Docker Compose

创建 docker-compose.yml：

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ~/.openclaw:/home/node/.openclaw
    environment:
      - DEEPSEEK_API_KEY=sk-your-key-here

然后 docker compose up -d 启动。

Podman 部署（推荐，更安全）

Podman 是 Docker 的无守护进程替代品，支持 rootless 运行：

# 一键设置（创建用户、构建镜像、安装启动脚本）
./setup-podman.sh

# 生产部署（systemd Quadlet，开机自启 + 自动重启）
./setup-podman.sh --quadlet

特性	Docker	Podman
守护进程	需要 dockerd	无守护进程
Root 权限	默认需要	Rootless
systemd 集成	需额外配置	Quadlet 原生支持
安全性	普通	更好

容器部署注意事项：

配置文件通过 -v 挂载到宿主机 ~/.openclaw/
如果需要配置代理，在 docker run 时加上 -e https_proxy=...
升级时拉取新镜像：docker pull ghcr.io/openclaw/openclaw:latest && docker restart openclaw
镜像以 node 用户（uid 1000）运行，遇到权限错误执行 sudo chown -R 1000:1000 ~/.openclaw

2.6 常见安装问题排查

问题一：`EACCES` 权限错误

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/openclaw'

原因：npm 全局安装目录没有写权限。

解决（三选一）：

# 方法一：用 sudo（简单但不推荐长期使用）
sudo npm install -g openclaw

# 方法二：修改 npm 全局目录到用户目录（推荐）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
npm install -g openclaw

# 方法三：使用 nvm（最推荐，nvm 安装的 Node 天然没有权限问题）
nvm install 22
npm install -g openclaw

问题二：Node.js 版本过低

ERROR: OpenClaw requires Node.js >= 22.16.0, but you have 18.x.x

# 使用 nvm 升级
nvm install 22
nvm use 22
nvm alias default 22  # 设为默认版本

# 验证后重新安装
node --version  # 应输出 v22.x.x
npm install -g openclaw

问题三：网络超时

npm ERR! network timeout at: https://registry.npmjs.org/openclaw

# 使用国内镜像
npm install -g openclaw --registry=https://registry.npmmirror.com

# 或设置代理
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
npm install -g openclaw

# 安装完后记得删除代理配置（避免影响其他操作）
npm config delete proxy
npm config delete https-proxy

问题四：Windows 上直接安装失败

Windows 原生环境下可能遇到各种兼容性问题。最可靠的方案是使用 WSL2：

# 1. 安装 WSL2（PowerShell 管理员）
wsl --install

# 2. 重启后进入 WSL 终端

# 3. 在 WSL 中安装 Node.js + OpenClaw（和 Linux 一模一样）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 22
npm install -g openclaw

问题五：安装后 `openclaw doctor` 报端口被占用

[FAIL] Port 18789 is already in use

# 查看是谁占了 18789 端口
lsof -i :18789    # macOS / Linux
netstat -tlnp | grep 18789  # Linux

# 如果是上次异常退出的 OpenClaw 进程，直接杀掉
kill $(lsof -ti :18789)

# 或者在配置文件中改用其他端口

2.7 安装后的目录结构

安装完成后，~/.openclaw/ 目录结构如下：

~/.openclaw/
├── openclaw.json           # 主配置文件（JSON5 格式）
├── workspace/              # Agent 工作区（记忆、Bootstrap 文件）
├── credentials/            # 渠道凭证
├── agents/                 # Agent 运行时数据（Session 等）
├── state/                  # 运行时状态（lock 文件等）
├── skills/                 # 已安装的技能
├── logs/                   # 日志文件
└── data/                   # 持久化数据

备份提示：迁移 OpenClaw 到新机器，只需要把整个 ~/.openclaw/ 目录拷贝过去，然后在新机器上安装 openclaw 本体即可。配置、技能、聊天记录全部保留。

2.8 环境变量说明

环境变量	默认值	说明
`OPENCLAW_HOME`	`~/.openclaw`	主目录，存放配置、数据、日志
`OPENCLAW_STATE_DIR`	`$OPENCLAW_HOME/state`	运行时状态目录
`OPENCLAW_CONFIG_PATH`	`$OPENCLAW_HOME/openclaw.json`	配置文件路径

# 自定义主目录（比如放到外部磁盘）
export OPENCLAW_HOME=/data/openclaw
echo 'export OPENCLAW_HOME=/data/openclaw' >> ~/.zshrc

与 API Key 相关的环境变量在下一章详细介绍。

2.9 ARM64 服务器注意事项

Oracle Cloud 免费服务器用的是 ARM64 架构。安装时有个坑：

# ARM64 服务器安装要跳过 node-llama-cpp 编译
npm install -g openclaw@latest --ignore-scripts

不加 --ignore-scripts 的话，node-llama-cpp 编译会非常慢甚至失败。

小 VPS 性能调优（启用 Node 模块编译缓存）：

# 添加到 ~/.bashrc
export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
mkdir -p /var/tmp/openclaw-compile-cache
export OPENCLAW_NO_RESPAWN=1

2.10 验证安装

不管你用哪种方式安装，都用这两个命令验证：

# 查看版本
$ openclaw --version
openclaw/1.x.x darwin-arm64 node-v22.x.x

# 全面诊断
$ openclaw doctor

openclaw doctor 检查的内容包括：Node.js 版本、配置文件格式、API Key、渠道状态、端口可用性、网络连通性、守护进程状态。

加上 --fix 参数可以自动修复：创建缺失目录、修复格式错误、重启异常进程、清理残留 lock 文件。

openclaw doctor --fix

2.11 小结

步骤	命令
一键安装（macOS/Linux）	`curl -fsSL https://openclaw.ai/install.sh \| bash`
一键安装（Windows）	`iwr -useb https://openclaw.ai/install.ps1 \| iex`
npm 手动安装	`npm install -g openclaw`
npm 国内镜像安装	`npm install -g openclaw --registry=https://registry.npmmirror.com`
Docker 安装	`docker run -d ... ghcr.io/openclaw/openclaw:latest`
验证安装	`openclaw --version`
全面诊断	`openclaw doctor`
自动修复	`openclaw doctor --fix`
ARM64 安装	`npm install -g openclaw --ignore-scripts`

下一章我们正式开始——10 分钟跑通你的第一个 AI Agent。

第2章 环境准备与安装