第02篇-安装OpenClaw
【OpenClaw 从入门到精通】第 2 篇安装 OpenClaw — 全平台指南本系列定位零基础入门从安装配置到高级架构全覆盖。无论你是开发者、运维工程师、还是技术爱好者本系列带你彻底掌握 OpenClaw。本篇你将学到运行时要求Node.js 版本macOS / Linux 一键安装Windows 安装PowerShell Windows Hubnpm / pnpm / bun 包管理器安装Docker 安装方式安装验证与健康检查学完本篇你的机器上将拥有一个可运行的 OpenClaw 环境。下面是 OpenClaw 全平台安装的整体流程全部通过 ✅存在问题 ❌开始安装 OpenClaw选择安装方式macOS / Linux 一键安装Windows 安装包管理器安装Docker 安装curl -fsSL 脚本自动完成检查Node.js安装包、创建目录、配置PATHPowerShell 脚本Windows Hub 伴侣应用iwr -useb 在线安装npm / pnpm / bun全局安装 openclawlatestDocker Compose 部署配置 .env 环境变量docker compose up -d验证安装openclaw doctor 健康检查检查结果安装完成开始使用 OpenClaw参考常见问题修复一、运行时要求1.1 Node.js 版本OpenClaw 基于 TypeScript 构建需要 Node.js 运行时Node.js 版本支持状态说明Node 24.15✅ 推荐最新 LTS性能最佳Node 22.22.3✅ 支持上一代 LTSNode 25.9✅ 支持Current 版本 Node 22.22❌ 不支持版本太低1.2 检查 Node.jsnode--version# 输出 v24.15.0 或更高即可如果没有安装或版本太低# macOSHomebrewbrewinstallnode24# Linuxnvm 方式推荐curl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh|bashnvminstall24nvm use24# Windows从 nodejs.org 下载安装包1.3 系统要求要求最低推荐操作系统macOS 12 / Ubuntu 20.04 / Windows 10macOS 14 / Ubuntu 22.04 / Windows 11内存2GB4GB磁盘300MB500MB网络需要访问 AI 模型 API—二、macOS / Linux 安装2.1 一键安装脚本推荐# macOS / Linuxcurl-fsSLhttps://openclaw.ai/install.sh|bash脚本自动完成检查 Node.js 版本全局安装openclaw包创建配置目录~/.openclaw/创建 Workspace 目录~/.openclaw/workspace/添加openclaw到 PATH2.2 验证安装openclaw--versionOpenClaw v2026.7.x三、Windows 安装3.1 方式一PowerShell 一键安装iwr-useb https://openclaw.ai/install.ps1|iex3.2 方式二Windows Hub 伴侣应用Windows 用户可以使用原生的Windows Hub伴侣应用从 OpenClaw 官网下载 Windows Hub 安装包运行安装程序Windows Hub 提供图形化设置向导托盘状态图标内置聊天界面Node Mode节点模式Local MCP ModeWindows Hub 适合不想用命令行的用户。开发者建议用命令行方式安装。3.3 Windows 注意事项注意说明确保 Node.js 在 PATH 中安装后运行node --version验证PowerShell 执行策略如果脚本被阻止Set-ExecutionPolicy -Scope CurrentUser RemoteSigned防火墙Gateway 需要 18789 端口默认确保未被占用四、包管理器安装4.1 npmnpminstall-gopenclawlatest4.2 pnpmpnpmadd-gopenclawlatest4.3 bunbunadd-gopenclawlatest三种包管理器效果相同。如果你不确定选哪个用npm。五、Docker 安装Docker 部署架构如下持久化存储OpenClaw 容器宿主机环境注入对外暴露docker compose up -dVolume 挂载绑定挂载Docker Compose编排服务.env 环境变量ANTHROPIC_API_KEYOPENAI_API_KEYopenclaw-gateway端口 18789/root/.openclaw/配置文件目录openclaw_dataVolume 卷./workspace本地工作目录18789 端口5.1 Docker Composeversion:3.9services:openclaw:image:openclaw/openclaw:latestcontainer_name:openclaw-gatewayports:-18789:18789volumes:-openclaw_data:/root/.openclaw-./workspace:/workspaceenvironment:-ANTHROPIC_API_KEY${ANTHROPIC_API_KEY}-OPENAI_API_KEY${OPENAI_API_KEY}restart:unless-stoppedvolumes:openclaw_data:5.2 启动# 创建 .env 文件echoANTHROPIC_API_KEYyour_key.env# 启动dockercompose up-d# 验证dockerexecopenclaw-gateway openclaw doctor5.3 Docker 优势环境完全隔离配置通过 Volume 持久化方便服务器部署多实例运行简单六、安装后验证6.1 健康检查openclaw doctoropenclaw doctor检查检查项说明Node.js 版本是否满足要求依赖完整性核心包是否完整配置文件openclaw.json是否存在Workspace工作目录是否可写Gateway 端口18789 是否可用API Key是否配置了至少一个 ProviderDM 安全策略检查是否有风险配置如果有问题openclaw doctor会给出修复建议。6.2 目录结构安装完成后~/.openclaw/目录~/.openclaw/ ├── openclaw.json ← 主配置文件 ├── workspace/ ← 工作空间 │ ├── AGENTS.md ← 项目上下文 │ ├── SOUL.md ← Agent 人格 │ └── skills/ ← 技能目录 ├── gateway.db ← Gateway 数据库SQLite ├── logs/ ← 日志 └── state-snapshots/ ← 状态快照目录结构关系图~/.openclaw/OpenClaw 根目录openclaw.json主配置文件workspace/工作空间gateway.dbGateway 数据库SQLitelogs/日志目录state-snapshots/状态快照AGENTS.md项目上下文SOUL.mdAgent 人格skills/技能目录七、常见安装问题Q1openclaw: command not found# 检查 npm 全局目录是否在 PATH 中npmconfig get prefix# 添加到 PATH# macOS / Linuxechoexport PATH$(npm config get prefix)/bin:$PATH~/.bashrcsource~/.bashrc# Windows通常自动添加重启终端Q2Node.js 版本太低# 用 nvm 升级nvminstall24nvm use24nvmaliasdefault24Q3端口 18789 被占用# 查看占用进程lsof-i:18789# macOS / Linuxnetstat-ano|findstr :18789# Windows# 或者用其他端口启动openclaw gateway--port18790Q4权限不足# macOS / Linux修复 npm 全局目录权限sudochown-R$(whoami)$(npmconfig get prefix)/{lib/node_modules,bin,share}# 然后重新安装npminstall-gopenclawlatestQ5Docker 拉取镜像失败# 配置镜像加速器# 或使用代理exportHTTP_PROXYhttp://your-proxy:portexportHTTPS_PROXYhttp://your-proxy:portdockercompose pull本篇小结知识点核心内容Node.js需要 24.15 / 22.22.3 / 25.9macOS/Linuxcurl -fsSL https://openclaw.ai/install.sh | bashWindowsPowerShell 脚本 或 Windows Hub包管理器npm install -g openclawlatestDockerdocker-compose Volume 持久化验证openclaw doctor配置目录~/.openclaw/openclaw.json / workspace / logs默认端口18789下篇预告第 3 篇Onboarding 向导 — 五分钟完成初始配置安装完了用openclaw onboard五分钟完成 Gateway、Workspace、通道和技能的初始配置。如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。