OpenClaw实战03：前置依赖与环境准备（Node.js 22+）

原创已于 2026-06-28 11:27:43 修改 · 340 阅读

6 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

OpenClaw实战

于 2026-06-28 10:58:53 首次发布

AI 时代程序员必备技能

Codex、Claude Code、Cursor、Hermes Agent、OpenClaw等工程化实战专栏，讲透 AI 如何接管脏活累活

一键订阅

提示：“奔跑吧邓邓子” 的 OpenClaw 实战专栏聚焦开源本地 AI 助手 OpenClaw，以 “龙虾精神” 为主线，用 80 篇系统化内容，带你从入门到实战。涵盖部署、架构、技能开发、多渠道接入、记忆安全、自动化运维等核心模块。全程实操、可直接复用，帮助开发者快速搭建私有、安全、可扩展的本地 AI 智能体，掌握下一代 AI 自动化技术。

大家好，欢迎继续阅读 OpenClaw 从入门到实战专栏。
在前两篇内容中，我们完成了项目认知与龙虾设计理念学习、核心架构拆解，彻底搞懂了 OpenClaw Gateway+Agent+Skills+Channels 的底层运行逻辑。从本篇开始，我们正式进入落地部署实战阶段。
很多新手部署 OpenClaw 报错、启动失败、服务异常，90% 的问题都源于环境依赖不达标、版本不匹配、权限不足、端口被占用。OpenClaw 对运行环境有严格的版本硬性要求，其中 Node.js 22+ 是核心强制依赖，不满足版本将直接无法启动网关服务。
本篇作为部署前置核心教程，将手把手完成全平台环境搭建、硬件适配、网络端口配置与安装自检，一次性解决所有前置问题，保证下一篇一键脚本部署流程丝滑无报错。
本文适配 Windows、macOS、Linux、树莓派全平台，所有操作均可直接复制实操，零基础可上手。

一、必备依赖：Node.js 22 + 与 pnpm

OpenClaw 官方明确规定：项目运行必须使用 Node.js 22 及以上 LTS 版本，不兼容 Node.js 20 及以下旧版本，同时默认采用 pnpm 作为包管理工具，禁止使用 npm、yarn 安装依赖。
核心原因：OpenClaw 底层使用了 Node.js 22 全新的稳定 API、异步任务调度机制与权限处理能力，旧版本会出现语法报错、进程常驻失败、热更新失效等一系列问题，pnpm 则可以保证依赖安装轻量化、版本锁定统一、磁盘占用更低，适配项目极简的龙虾设计理念。

1.1 各平台 Node.js 安装与版本校验

为保证全平台版本统一，推荐全部用户安装 Node.js 22.x LTS 长期支持版，不建议安装最新非稳定版，避免兼容问题。
Windows/macOS 图形化安装
直接前往 Node.js 官方官网，选择 22.x LTS 安装包，全程默认下一步安装即可，安装程序会自动配置系统环境变量。安装完成后重启终端，执行校验命令。
Linux / Raspberry Pi 命令行安装
推荐使用 nvm 多版本管理器安装，方便后续版本切换与升级，避免系统自带 Node 版本过低问题。通过 nvm 安装可彻底解决权限全局污染、版本锁定失败等问题，是服务端部署最优方案。
通用版本校验命令（全平台通用）

node -v

执行后输出 v22.x.x 即为安装成功，若显示其他版本或命令不存在，说明安装失败或环境变量未生效，需重新安装或重启终端。

1.2 pnpm 安装与国内镜像配置

pnpm 是 OpenClaw 指定唯一依赖管理工具，相比 npm、yarn，具备安装速度快、依赖极简复用、安全性高、磁盘占用低的优势，完美契合项目极简、可靠的设计理念。
全局安装 pnpm 命令

npm install -g pnpm

安装完成后执行版本校验：

pnpm -v

为解决国内网络拉取依赖慢、超时、失败问题，必须配置国内淘宝镜像源，配置命令如下：
pnpm config set registry https://registry.npmmirror.com
配置完成后，可通过 pnpm config get registry 校验镜像是否生效，确保后续一键安装、依赖更新全程高速无报错。

1.3 环境变量与权限检查

安装完成后，需要确保 Node.js、pnpm 已写入系统全局环境变量，终端可任意目录调用全局命令，同时规避全局权限报错。
环境变量校验：在任意终端执行 node、pnpm 命令，若不提示“不是内部或外部命令”，即代表环境变量配置成功。Windows 若失效，可手动将 Node 安装目录添加至系统 Path；macOS/Linux 可写入 ~/.bashrc 或 ~/.zshrc 永久生效。
权限预处理：macOS/Linux 禁止使用 sudo 强制全局安装依赖，避免权限过高导致后续项目读写权限混乱、配置文件生成失败；Windows 避免普通用户权限安装，防止目录写入失败。

二、系统要求与硬件建议

OpenClaw 主打轻量化、低资源占用，适配桌面端、服务端、嵌入式设备多场景，对硬件要求极低，低配设备也可稳定7×24小时常驻运行，完美契合龙虾极简、可靠的核心理念。

2.1 Windows/macOS/Linux/Raspberry Pi 兼容清单

OpenClaw 支持全主流平台全覆盖，无平台壁垒，适配个人本地部署、服务器部署、嵌入式设备离线部署场景：
Windows：Win10 2020年后版本、Win11，支持原生部署 + WSL2 子系统部署
macOS：Intel / Apple Silicon 全适配，macOS 12 及以上版本
Linux：Ubuntu、Debian、CentOS、Fedora 等主流发行版全适配
Raspberry Pi：树莓派 3/4/5 全系列，支持 ARM 架构离线本地部署，适配边缘AI场景

2.2 最低配置与推荐配置

得益于极简架构设计，OpenClaw 常驻进程资源消耗极低，闲置状态几乎不占用系统资源：
最低运行配置（可跑通基础对话、简单插件）
内存：2GB 及以上；硬盘：10GB 空闲空间；CPU：双核基础处理器，满足基础常驻运行、单任务调度。
推荐配置（稳定长期运行、多插件、多渠道并发）
内存：4GB 及以上；硬盘：20GB 以上固态硬盘；CPU：四核及以上处理器，可稳定支撑多Agent并发、多渠道同时在线、插件持续调用、日志长期存储。
特别说明：本地模型推理资源消耗独立，不占用 OpenClaw 网关进程资源，网关本身轻量化无压力。

2.3 网络与端口要求（18789 默认端口）

OpenClaw 网关默认独占 18789 端口，同时承载 HTTP 控制台访问与 WebSocket 长连接通信，是服务启动、渠道连接、插件通信、控制台访问的核心端口。
端口核心规则
1、默认固定端口：18789，不建议新手手动修改端口配置，避免多组件通信异常；
2、本地闭环运行：仅监听 127.0.0.1，默认仅本机访问，外网无法直接穿透，保障本地安全；
3、端口必须独占：该端口不能被其他程序、代理工具、服务占用，否则网关启动直接报错。
网络要求
基础安装、插件拉取、模型密钥校验需要外网网络；部署完成后，核心对话、本地任务、记忆读写可完全离线闭环运行，契合本地优先设计理念。

三、安装前自检清单

正式部署前，必须完成全套自检，这是规避部署失败的关键步骤。新手绝大多数安装报错、启动失败、服务闪退，均可通过以下三步自检提前解决。

3.1 权限检查：管理员 /root 与读写权限

OpenClaw 所有配置、数据、日志均存储在用户目录 ~/.openclaw，无需系统最高权限，但必须保证当前用户拥有完整读写权限。
Windows：建议以普通用户运行终端，如需写入系统目录可临时开启管理员权限，禁止全程管理员运行，避免权限绑定异常；
macOS/Linux/树莓派：使用普通用户部署，禁止直接使用 root 部署，防止生成的配置文件权限过高，后续普通用户无法读写、服务启动失败。
自检标准：当前用户可自由读写用户根目录，无权限拒绝、权限不足报错。

3.2 端口占用排查

提前排查 18789 端口占用，是网关成功启动的核心前提，不同平台排查命令如下：
Windows 端口排查

netstat -ano | findstr 18789

macOS/Linux 端口排查

lsof -i :18789

若无任何输出，代表端口空闲可正常使用；若有进程输出，需手动结束占用进程或修改对应程序端口，保证 18789 端口独占空闲。

3.3 防火墙与安全软件白名单

本地防火墙、杀毒软件、安全拦截工具，可能会拦截 18789 端口本地通信、Node.js 网络请求，导致服务启动成功但控制台无法访问、渠道连接失败、插件拉取失败。
自检配置规则
1、关闭系统严格防火墙拦截策略，放行本地 127.0.0.1 内网通信；
2、将 Node.js、终端工具、开发工具加入杀毒软件白名单；
3、本地部署无需开放外网端口，仅放行本地访问权限即可，兼顾安全与可用性。

四、本篇总结与下节预告

本篇我们完成了 OpenClaw 部署前全套环境前置准备，彻底解决版本依赖、系统兼容、硬件适配、端口权限、安全拦截等核心前置问题，核心要点总结：
1、强制依赖 Node.js 22+、pnpm 工具，需严格匹配版本并配置国内镜像；
2、全平台兼容 Windows/macOS/Linux/树莓派，轻量化硬件门槛极低；
3、18789 为核心独占端口，需提前排查占用、放行本地通信；
4、权限、端口、防火墙三大自检步骤，是部署成功的关键前提。

下一篇预告：专栏第4篇将正式开启一键安装脚本快速部署（官方推荐），手把手讲解全平台一键部署命令、初始化流程、令牌配置、模型密钥绑定与服务健康校验，带你从零完成完整部署落地。

专栏持续更新纯干货实战教程，欢迎点赞、收藏、关注，跟进全套 OpenClaw 落地与二次开发教程！