二、安装与快速开始
2.1 推荐安装方式（最快）
macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bashWindows (PowerShell)
iwr -useb https://openclaw.ai/install.ps1 | iex安装脚本会自动：
- 检测操作系统
- 在需要时安装 Node
- 安装 OpenClaw
- 启动新手引导（onboarding）
跳过新手引导
如果你只想安装，稍后再配置：
# macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
# Windows (PowerShell)
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard2.2 系统要求
| 要求 | 说明 |
|---|---|
| Node.js | 24（推荐）或 22.14+ |
| 操作系统 | macOS、Linux、Windows（原生或 WSL2） |
| WSL2 注意 | Windows 上 WSL2 更稳定 |
| pnpm | 仅从源码构建时需要 |
安装脚本会自动处理 Node 安装。
2.3 其他安装方式
npm / pnpm / bun
如果你已经自行管理 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
# bun
bun add -g openclaw@latest
openclaw onboard --install-daemon⚠️ pnpm 对带有构建脚本的软件包要求显式批准。首次安装后请运行
pnpm approve-builds -g。
sharp 构建错误修复
如果 sharp 因全局安装的 libvips 而失败：
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest本地前缀安装器
当你希望将 OpenClaw 和 Node 保持在本地前缀下（如 ~/.openclaw）：
curl -fsSL https://openclaw.ai/install-cli.sh | bash从源码安装
适用于贡献者：
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm ui:build && pnpm build
pnpm link --global
openclaw onboard --install-daemon从 GitHub main 安装
npm install -g github:openclaw/openclaw#main2.4 验证安装
# 确认 CLI 可用
openclaw --version
# 检查配置问题
openclaw doctor
# 验证 Gateway 正在运行
openclaw gateway status2.5 新手引导（Onboarding）
openclaw onboard --install-daemon这个命令会：
- 引导你完成初始配置
- 设置模型提供商 API Key
- 安装系统服务（LaunchAgent / systemd / Scheduled Task）
- 启动 Gateway 网关
托管服务安装
安装后，OpenClaw 会作为系统服务自动启动：
| 平台 | 服务类型 |
|---|---|
| macOS | LaunchAgent (ai.openclaw.gateway) |
| Linux/WSL2 | systemd 用户服务 |
| Windows（原生） | Scheduled Task 或 Startup 文件夹 |
2.6 5 分钟本地启动
# 1. 启动 Gateway
openclaw gateway --port 18789
# 调试模式（详细输出）
openclaw gateway --port 18789 --verbose
# 强制终止端口上的监听器后启动
openclaw gateway --force
# 2. 验证服务健康状态
openclaw gateway status
openclaw status
openclaw logs --follow
# 健康基线：Runtime: running 和 RPC probe: ok
# 3. 验证渠道就绪状态
openclaw channels status --probe2.7 打开控制面板
Gateway 启动后，在浏览器中打开 Control UI：
openclaw dashboard默认地址：http://127.0.0.1:18789/
2.8 容器和包管理器
Docker
# 容器化或无头部署
docker run -d openclaw/openclawNix
# 通过 Nix flake 进行声明式安装
nix run github:openclaw/openclawAnsible
# 自动化 fleet 配置
# 参见 Ansible 角色文档2.9 更新、迁移和卸载
更新
npm update -g openclaw@latest
openclaw gateway restart卸载
openclaw gateway stop
npm uninstall -g openclaw
# 清理配置（可选）
rm -rf ~/.openclaw2.10 故障排除：找不到 openclaw
如果安装成功，但终端中找不到 openclaw：
# 检查 Node 是否已安装
node -v
# 检查全局软件包安装位置
npm prefix -g
# 检查 PATH
echo "$PATH"如果 $(npm prefix -g)/bin 不在你的 $PATH 中，添加到 shell 启动文件：
# 添加到 ~/.zshrc 或 ~/.bashrc
export PATH="$(npm prefix -g)/bin:$PATH"然后打开一个新的终端。