夜雨聆风
检查项 | 最低要求 | 推荐配置 |
Node.js 版本 | >= v22.16 | Node 24 LTS 最新版 |
内存 (RAM) | 4 GB | 8 GB 及以上 |
磁盘空间 | 2 GB 可用 | 5 GB 及以上 |
网络环境 | 能访问 npm 仓库 | 稳定的国际网络或配置镜像源 |
操作系统 | macOS 12+ / Windows 10+ / Ubuntu 20.04+ | macOS 最新版 |
node -vv24.x.xmacOS：打开 Node.js 官网下载页，选择 Node 24 LTS 下载 .pkg 安装包，双击后按向导一路安装即可。
Windows：下载 Node 24 LTS 的 .msi 安装包，保留默认配置完成安装。安装后务必关闭并重新打开 PowerShell 以加载环境变量。
Linux：下载官网对应架构的二进制包（.tar.xz），解压至
/usr/local/lib/nodejs/npm install -g openclaw@latestopenclaw onboard --install-daemon部署方式 | 适用场景 | 难度 | 推荐指数 |
macOS 本地一键安装 | Mac 日常使用、桌面控制 | 简单 | ★★★★★ |
Windows 安装 (原生 / WSL2) | Windows 用户 | 中等 | ★★★★☆ |
Linux 一键安装 | Linux 桌面、VPS、云主机 | 简单 | ★★★★★ |
Docker 部署 | 7x24 小时无头运行 | 中等 | ★★★★★ |
curl -fsSL https://openclaw.ai/install.sh | bashiwr-useb https://openclaw.ai/install.ps1 | iex
wsl --installcurl -fsSL https://openclaw.ai/install.sh | bash腾讯云轻量应用服务器 | 阿里云 ECS | AWS EC2 | |
推荐配置 | 2 核 4G | 2 核 4G | t3.medium |
月费参考 | 约 50-80 元 | 约 60-100 元 | 约 $30-40 |
国内访问速度 | 快 | 需要中转 | |
适合人群 | 国内个人用户首选 | 企业用户 / 有阿里云生态 | 海外用户 / 需要海外 API 直连 |
操作系统推荐 | Ubuntu 22.04 | Ubuntu 22.04 | Ubuntu 22.04 |
备案要求 | 需要（绑定域名时） | 需要（绑定域名时） | 不需要 |
curl -fsSL https://get.docker.com | bashsudo usermod -aG docker $USERexitdocker-compose.ymlservices:openclaw:image:ghcr.io/openclaw/openclaw:latestcontainer_name:openclawrestart:unless-stoppedports:-"18789:18789"volumes:-./workspace:/app/workspace-./openclaw.json:/app/openclaw.jsonenvironment:-TZ=Asia/Shanghailogging:driver:"json-file"options:max-size:"10m"max-file:"3"openclaw.json{"models":{"providers":{"openai":{"apiKey":"sk-your-api-key-here"}}},"agents":{"defaults":{"model":{"primary":"openai/gpt-5"}}},"gateway":{"port":18789,"bind":"lan","auth":{"mode":"token","token":"replace-with-a-long-random-token"}}}
chmod 600 ~/openclaw/openclaw.jsoncd ~/openclawdocker compose up -ddocker compose logs -f openclawopenclaw onboard --install-daemonopenclaw dashboarddocker exec -it openclaw openclaw onboardStep 1：配置 LLM 提供商。选择你的大模型提供商并填入 API Key。如果你使用国产大模型，请选择 Custom Provider。 Step 2：配置通讯渠道。OpenClaw 支持 Telegram、Discord 等渠道。新手建议先选择 skip，直接使用内置面板即可。 Step 3：安装技能（Skills）。新手建议优先按空格键选中 web-search、file-manager 和 code-runner 这三个基础技能，后续可随时追加。
问题 1：openclaw: command not found
原因：npm 全局安装目录没有被添加到系统的 PATH 环境变量中。
解决方案：执行 `npm config get prefix` 找到路径，然后将其下的 bin 子目录添加到 `~/.zshrc` 或 `~/.bashrc` 中。
npm config get prefix~/.zshrc~/.bashrc
问题 2：图像库 sharp 安装报错
原因：sharp 是一个依赖本地 C++ 编译的图像处理库，预编译包下载失败时会导致此报错。
解决方案：macOS 执行 `brew install vips`；Ubuntu 执行 `sudo apt-get install -y libvips-dev` 安装系统依赖后重新安装。
brew install vipssudo apt-get install -y libvips-dev
问题 3：EACCES: permission denied
原因：npm 全局安装时权限不足。
解决方案：不要使用 sudo npm install -g。可以先执行 `sudo chown -R $(whoami) $(npm config get prefix)` 修复当前 npm 全局目录权限。
sudo chown -R $(whoami) $(npm config get prefix)问题 4：ETIMEOUT 或 ECONNREFUSED（网络超时）
原因：国内网络访问 npm 官方仓库速度慢或被阻断。
解决方案：执行如下命令切换到国内镜像源，然后重新安装。
npm config set registry https://registry.npmmirror.com问题 5：Docker 容器启动后立即退出
原因：通常是环境变量配置错误或端口冲突。
解决方案：执行 `docker compose logs openclaw` 查看日志，检查 18789 端口是否被其他程序占用，或配置文件格式是否正确。
docker compose logs openclaw问题 6：Onboarding 向导中 LLM 连接验证失败
原因：API Key 错误、网络不通或 Base URL 配置有误。
解决方案：检查 API Key 是否有多余空格。如果是国产大模型，请确保 Base URL 配置正确（如携带 /v1 后缀）。
问题 7：Windows 上 node-gyp 编译报错
原因：缺少 C++ 编译工具链。
解决方案：推荐切换到 WSL2 环境；如果必须在原生环境解决，请手动前往微软官网安装 Visual Studio Build Tools。
问题 8：Node.js 安装完成后 node -v 仍然报错
原因：新安装的路径还没被当前终端会话加载，或者 Linux 手动安装时没有把解压目录的 bin 加入 PATH。
解决方案：完全关闭当前终端再重新打开重试。Linux 用户需确认 `~/.bashrc` 中的 PATH 已包含 Node 的 bin 目录。
~/.bashrc
