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

奔跑吧邓邓子2026-06-29 9:33

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

目录

  • [一、必备依赖：Node.js 22 + 与 pnpm](#一、必备依赖：Node.js 22 + 与 pnpm)
    • [1.1 各平台 Node.js 安装与版本校验](#1.1 各平台 Node.js 安装与版本校验)
    • [1.2 pnpm 安装与国内镜像配置](#1.2 pnpm 安装与国内镜像配置)
    • [1.3 环境变量与权限检查](#1.3 环境变量与权限检查)
  • 二、系统要求与硬件建议
    • [2.1 Windows/macOS/Linux/Raspberry Pi 兼容清单](#2.1 Windows/macOS/Linux/Raspberry Pi 兼容清单)
    • [2.2 最低配置与推荐配置](#2.2 最低配置与推荐配置)
    • [2.3 网络与端口要求（18789 默认端口）](#2.3 网络与端口要求（18789 默认端口）)
  • 三、安装前自检清单
    • [3.1 权限检查：管理员 /root 与读写权限](#3.1 权限检查：管理员 /root 与读写权限)
    • [3.2 端口占用排查](#3.2 端口占用排查)
    • [3.3 防火墙与安全软件白名单](#3.3 防火墙与安全软件白名单)
  • 四、本篇总结与下节预告
  • 专栏系列文章链接
    • [1. OpenClaw 实战开篇 ------ 本地 AI 助手，从龙虾精神开始](#1. OpenClaw 实战开篇 —— 本地 AI 助手，从龙虾精神开始)
    • [2. OpenClaw实战02：OpenClaw核心架构与龙虾设计理念](#2. OpenClaw实战02：OpenClaw核心架构与龙虾设计理念)
    • [3. OpenClaw实战03：前置依赖与环境准备（Node.js 22+）](#3. OpenClaw实战03：前置依赖与环境准备（Node.js 22+）)

大家好，欢迎继续阅读 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 安装可彻底解决权限全局污染、版本锁定失败等问题，是服务端部署最优方案。

通用版本校验命令（全平台通用）

bash 复制代码 
node -v

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

1.2 pnpm 安装与国内镜像配置

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

全局安装 pnpm 命令

bash 复制代码 
npm install -g pnpm

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

bash 复制代码 
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 端口排查

bash 复制代码 
netstat -ano | findstr 18789

macOS/Linux 端口排查

bash 复制代码 
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 落地与二次开发教程！

专栏系列文章链接

1. OpenClaw 实战开篇 ------ 本地 AI 助手，从龙虾精神开始

OpenClaw 实战开篇 ------ 本地 AI 助手，从龙虾精神开始

2. OpenClaw实战02：OpenClaw核心架构与龙虾设计理念

OpenClaw实战02：OpenClaw核心架构与龙虾设计理念

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

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

热门推荐
01如何新建文件夹？ 电脑新建文件夹的4种方法022026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片03GitHub 镜像站点04AI科技热点日报 | 2026年07月01日05国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）06AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路072026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？082026 年 AI 大模型 & AI 编程工具实战全总结09幻兽帕鲁 - 服务器管理员权限与 GM 命令完全指南10微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新