OpenClaw装到一半十个人里有八个是卡在pnpm install和pnpm build这两步。上一篇把环境准备讲完了这一篇继续“之二”的实操路线目标很单纯让你跑完依赖安装越过构建报错最终顺利进入OpenClaw界面。适合正在为“pnpm不是内部或外部命令”“pnpm下载失败”头疼的人看也适合那种build到一半被一堆系统级错误砸懵的玩家。我会把每个环节的根因和绕坑方法都讲清楚按顺序走一遍基本可以少走一晚上的弯路。1. 动手前的环境盘点比install更该先做好的三件小事1.1 Node.js版本决定后面一半的命运OpenClaw这类现代AI代理项目构建链路几乎全部建立在Node生态上。pnpm本身是Node写的项目源码里的依赖、脚本、打包工具也都是围绕Node转的。我实测下来比较省心的版本区间是18.17以上或20.x的LTS一个简单标准node -v能跑出v18.17.0之后的版本npm -v是9或10基本就够用。太老的Node版本在编译原生模块时经常报一些莫名其妙的语法错误而且corepack的使用也不完整。怎么处理版本问题最直接的是用nvmWindows用nvm-windows切版本。不要图省事直接去官网装个最新版然后硬着头皮搞等遇到node-gyp编译失败再回来换版本那才是真正的浪费时间。装完nvm之后三行命令nvm install 20、nvm use 20、node -v确认版本号干净利落。1.2 系统编译依赖Windows和Linux差得不是一个量级OpenClaw的依赖里有不少原生模块编译时需要系统级的工具链。很多人的“pnpm install失败”其实不是pnpm的问题是系统里缺了编译器。Windows用户需要的核心是“Build Tools for Visual Studio 2022”也就是C生成工具。安装时勾选“使用C的桌面开发”别只装那个最小的包后面编译原生模块会缺一堆头文件。如果你已经装了却仍然报错Windows设置里搜“program install and uninstall troubleshooter”这是微软官方疑难解答器能自动修复很多注册表级别的安装残留问题这招我确实用过有奇效。Linux用户Debian/Ubuntu系跑apt install build-essential python3 gitCentOS/RHEL系跑yum install xdotool之类。这里特别提醒xdotool不是可有可无的装饰品OpenClaw做自动化操作时要模拟键鼠事件xdotool是底层支撑没有它界面能起来但很多自动化能力会在运行时罢工而且报错信息往往藏在日志深处很难第一时间联想到是缺了它。macOS用户装上Xcode Command Line Toolsxcode-select --install一行搞定然后大概率还要装python3因为部分原生模块编译时要用到Python。1.3 镜像源与网络提前省掉一半报错pnpm install要从npm仓库拉上百个包网络状况不佳就会出现各种“下载失败”“ETIMEDOUT”。这不是你操作错了是网络链路原因。国内网络环境下直接在项目根目录加一个.npmrc文件内容就两行registryhttps://registry.npmmirror.com然后用pnpm config set registry https://registry.npmmirror.com全局设置也行。注意的是改完镜像源之后最好把pnpm的缓存清一遍再重新install否则可能出现源都换了还在用旧缓存里不完整文件的怪问题。清缓存命令是pnpm store prune。这一步看着不起眼但能帮你少看无数次红色的ERR字样。2. pnpm安装的三种路径与“不是内部或外部命令”的根因修复2.1 三种安装方式哪条最顺pnpm的安装方式网上说法很多我按可靠性排个序。第一种官方推荐的corepack方式命令是corepack enable然后直接pnpm -v验证。Node 18.17以上自带corepack这是我最推荐的路子。如果corepack在拉取pnpm时超时可以执行COREPACK_NPM_REGISTRYhttps://registry.npmmirror.com corepack enableWindows PowerShell里要先写$env:COREPACK_NPM_REGISTRYhttps://registry.npmmirror.com再执行。第二种npm全局安装npm install -g pnpm。这种方式最简单但有几个隐患一是全局目录权限问题Linux/macOS上经常报EACCES二是如果npm源状态不好装出来的pnpm版本可能滞后。第三种独立安装脚本。Windows用户用PowerShell执行官方安装脚本Linux/macOS用户用curl。这种方式的优势是绕开npm生态的版本滞后劣势是卸载的时候要手动清理。如果之前装过旧版pnpm装新版之前先彻底删干净Windows下执行npm uninstall -g pnpm然后删掉npm全局目录里的pnpm相关文件Linux下还要检查~/.local/share/pnpm这个目录。旧缓存留着不删版本混乱就会成为你后续排查中最难查的暗坑。2.2 “pnpm 不是内部或外部命令也不是可运行的程序或批处理文件”的真相这是Windows用户最常见的拦路虎。这句报错的本质pnpm已经装上了但可执行文件的目录不在系统PATH里CMD找不到它。注意npm能跑而pnpm不能跑这并不奇怪——npm是随Node自动进PATH的pnpm的全局bin目录不一定是。排查步骤其实很机械执行npm root -g找到全局node_modules路径比如C:\Users\你的用户名\AppData\Roaming\npm。看看这个目录下有没有pnpm.cmd。如果没有说明安装过程有问题重装如果有就把这个目录加进系统环境变量PATH。加完之后开一个新的CMD窗口验证不要用老窗口。Linux/macOS用户遇到“command not found”也是同一个思路把npm全局bin目录常见是~/.npm-global/bin或/usr/local/bin加进.bashrc或.zshrc的PATH。很多人只加了bashrc换了个shell就找不到命令这种低级问题也很常见。2.3 pnpm下载失败的镜像源与缓存方案“pnpm下载失败”不一定发生在install阶段有时候在你第一次执行pnpm -v时就失败了。corepack下载pnpm本体时从npm官方源拉网络不好就卡住。解决办法就是上面提到的COREPACK_NPM_REGISTRY环境变量把它指向镜像源。如果是已经装好pnpminstall项目依赖时反复下载失败先把pnpm的仓库地址切到镜像再执行pnpm store prune清理不完整缓存把node_modules整个删掉重来。有时候还要删掉项目里的pnpm-lock.yaml重新生成但注意lockfile是用来锁版本的能不动尽量不动真的反复失败再考虑删。3. pnpm install阶段依赖解析、原生编译与清理重试3.1 clone之后别急着install先看这两样代码拉下来之后进入项目目录先看两样东西有没有pnpm-lock.yaml有没有.npmrc。有lockfile说明项目锁定了依赖版本直接用pnpm安装是最优解没有的时候pnpm会现场解析版本所见即所得但结果可能跟官方不一致。.npmrc则可能已经写好了需要的registry和特殊配置不要随便覆盖它。然后执行pnpm install。首次安装的时间会比较长因为要下载的包很多期间你会看到很多“Progress”滚动别慌只要没有出现红色ERR字样的记录就让它跑完。装到一半断了怎么办冷静这不是世界末日重试前先做一次pnpm store prune加删除node_modules把不完整的残留清干净再重新执行。这个道理跟Maven里先mvn clean再install一样clean的环节省不得。3.2 原生模块编译报错的几种经典姿势OpenClaw的依赖中有一些需要现场编译的原生模块比如某些数据库驱动、系统调用库。这类报错的典型特征错误信息里能看到“node-gyp”“python”“MSBuild”等字样。Windows上最常见的是缺VS Build Tools或Python。缺Build Tools的报错通常提示找不到MSBuild装好“Build Tools for Visual Studio 2022”的C桌面开发组件即可。缺Python的提示则多半指向找不到Python解释器装一个Python 3.10安装时记得勾选“Add Python to PATH”这个细节能省很多事。装好之后重启终端让环境变量生效。Linux上编译报错多数是缺python3或make/g。Debian系一句apt install build-essential python3搞定。如果报错指向xdotool缺失就用apt install xdotool或yum install xdotool装好。还有一个细节编译时如果日志里滚动出一堆warning大部分可以忽略真正的error通常集中在最后几十行。你只要盯住“ERR!”、“Error:”、“failed”这几个关键词就行别被前面的warning吓到。3.3 权限问题与Python环境管理器Linux/macOS用户经常会碰到“EACCES: permission denied”这类权限错误。原因往往是npm全局目录归root所有而你用普通用户执行。解决思路不是加sudo硬闯而是把npm全局目录改到用户目录下。用npm config set prefix ~/.npm-global然后把对应目录加进PATH。我之前用sudo装过结果后面一堆文件权限混乱重启终端各种找不到命令最后彻底清理重装才正常。如果你本机装了好几个Python版本编译原生模块时可能发生版本错乱。建议用python install manager这类工具固定一个干净版本并把python --version确认好之后再重试install。Python版本不是越新越好很多原生模块在3.12/3.13上编译链还没跟上3.10或3.11反而是最顺的。4. pnpm build阶段从源码到可运行产物的关键一环4.1 build到底在干什么pnpm install把依赖装齐不等于OpenClaw就能直接跑。项目源码是TypeScript加一堆前端资源运行前需要先编译打包这一步就是pnpm build。build脚本一般定义在package.json里执行pnpm build或者说pnpm run build编译器会依次处理类型检查、代码转译、资源拷贝和打包最后在dist或out目录里生成可运行产物。不少人build时看到类似“build version: 10.5.99 build date: 2024-08-06”的日志以为出问题了其实这是某个核心依赖的版本信息在正常输出恰恰说明编译已经走到打包阶段。真正要担心的是“error during build: rollup error”这种字样比如“could not resolve entry module index.html”这类错误一般是前端资源没被正确处理根子往往不在build本身而在install阶段没装全或者版本被lockfile卡在不兼容的组合上。处理方式按第3.3节的思路彻底清理重装一次很多“build怪病”重新install之后自动就消失了。4.2 构建失败的常见血泪点构建失败里我见过最多的是两类资源路径问题和内存问题。资源路径问题通常出现在Windows上项目路径里如果带了空格、中文或者奇奇怪怪的字符打包工具在处理文件路径时会直接罢工。解决方案很粗暴把项目放到一个纯英文、无空格的路径下比如直接放D:\dev\openclaw。这个建议我在第一篇里就强调过但几乎每次都有人栽在这上面。内存问题则更多体现在老机器上构建过程需要占用的内存不小执行到一半进程被系统杀掉日志尾部会出现“JavaScript heap out of memory”或直接“Killed”。解决思路给Node进程加内存上限在package.json的build脚本前加NODE_OPTIONS--max-old-space-size4096Windows用cross-env兼容写法。如果还不行检查是不是同时跑着太多应用或虚拟机给构建过程腾出资源。4.3 构建完别急着启动先做这三项检查build成功刷绿只是一半启动前花两分钟做三件事看产物目录。不同版本的OpenClaw产物位置可能不同常见是dist/或out/确认可执行文件或入口文件确实存在。查看package.json里的启动脚本比如pnpm start或pnpm dev先搞清楚自己该跑哪个命令。检查.env或config文件模板是否已经生成。很多项目会提供.env.example你要copy成.env并填好配置否则启动到一半会因为缺密钥直接退出。这三项检查大约一分钟但能帮你把“构建成功了却启动失败”这一类问题在源头上灭掉。5. 运行OpenClaw环境变量、本地模型与进入界面的标志5.1 密钥与环境变量少一个都进不去OpenClaw运行时需要一个模型后端。它支持接入各种大模型API比如Anthropic或OpenAI系。最简单的配置方式是把API密钥写进环境变量在Windows PowerShell里用setx命令在Linux/macOS里用export写入.bashrc。注意setx设置成功后当前窗口不会立即生效新开一个终端才会读到。第一次配置完关掉终端重开这个细节能避免你白折腾十分钟。另外OpenClaw还提供了Windows Companion这类辅助工具。它的作用是在Windows桌面环境里管理系统级的自动化操作权限跟主程序之间的配对关系类似蓝牙耳机——一个主端一个伴生端。配置方式一般是先在Windows Companion里登录并生成配对码再在主程序里输入配对码完成连接。如果连接不上先检查系统防火墙有没有拦截本地端口通信。这个问题我在Windows上遇到过两次第一次还怀疑是代码bug后来发现纯粹是防火墙规则没放行。5.2 OpenClaw只能用API方式接入算力吗这个问题几乎每个第一次接触OpenClaw的人都会问。答案是不是。OpenClaw不是“只能”走云API它同样支持接入本地模型。最常见的组合是Ollama加OpenClaw先在本地跑起Ollama并拉取一个模型比如ollama pull qwen2.5这类然后在OpenClaw的配置里把模型后端指向本地Ollama服务地址。这样不仅能省API费用数据也都留在本机对隐私敏感的玩法来说尤其有吸引力。但本地模型和云API各有取舍。本地模型对显卡要求高推理速度和大模型的智能水平受模型尺寸限制云API则开箱即用效果通常更好代价是按token计费。我的建议日常折腾、调试用Ollama跑正经任务或电商自动化这类需要高准确率的场景用云API更靠谱。注意不管哪种方式都要在config里把模型名称和服务地址填对否则界面上会一直显示连接失败。5.3 界面出现的标志与第一眼该看什么如果你是带界面启动的运行启动命令后会看到日志刷出监听地址然后在浏览器里打开对应地址比如http://localhost:3000登陆后就算正式进入OpenClaw界面了。CLI模式则会在终端里出现交互提示符可以直接输入指令。注意启动日志里出现“listening”或“running at”这类字样才是真正的进入标志别看到一堆初始化日志就以为卡住了。进了界面之后第一件事去设置里确认模型连接状态是不是正常。如果模型没连上界面能打开但发指令就会报错。这个检查顺手做掉比之后在任务执行到一半时忽然报错要舒服得多。6. 多平台部署避坑Ubuntu、Windows与安卓Termux6.1 Ubuntu服务器部署实录Ubuntu上部署OpenClaw麻烦点集中在系统依赖和后台运行。依赖顺序一般是先装Node环境再装编译链然后apt install xdotool补齐自动化组件。pnpm的安装我推荐corepack方式需要留意的是在服务器上执行corepack enable后最好再手动跑一次pnpm -v确认二进制确实下下来了。如果服务器访问外网受限在install和build时同样用镜像源和前面讲的路径一致。服务器上还有一个常见坑直接在前台跑OpenClawSSH一断开服务就没了。正确做法是用systemd或screen/tmux把服务托到后台写一个简单的service文件把执行用户和工作目录写清楚再用systemctl enable设为开机自启。不要把服务挂在root账号下跑权限风险太大而且以后想改低权限迁移会非常痛苦。6.2 Windows桌面与Companion的配对问题Windows上的坑除了PATH和Build Tools最典型的是路径空格问题。项目目录一旦放在“C:\Program Files\OpenClaw”这种带空格的路径下build或启动时都有可能出怪问题路径解析会抓狂。直接放在“D:\openclaw”这类干净路径下是成本最低的解决方法。Companion的配置还有一个容易忽略的点主程序和Companion必须是同一版本或兼容版本版本差太多时配对码会因为密钥协商失败而一直连不上。升级主程序时记得同步升级Companion这个规则我吃了一次亏才总结出来的。6.3 安卓Termux部署的极限挑战在安卓上用Termux装OpenClaw属于进阶玩法但确实能跑。前提是手机要留足存储空间安装Node、pnpm加依赖至少预留3GB以上。Termux里装Node后有两点要注意一是某些系统依赖在Termux里不可用xdotool这类窗口工具基本放弃界面模式也不用指望只能跑CLI二是Termux的后台进程容易被系统杀掉只能在前台保持运行充电时用屏幕常亮选项是最基本的操作。性能上手机跑模型不现实Termux上运行OpenClaw更适合控制远程API或操作局域网内的其他设备。另外Termux的包源和官方源不同装某些依赖时会让你装Termux专用变体别强行用Linux通用包版本对不上编译能卡到你怀疑人生。7. 常见问题速查与避坑清单7.1 报错速查表现象根因解法pnpm 不是内部或外部命令npm全局bin目录不在PATH找全局路径加入PATH重开终端pnpm下载失败corepack拉取二进制网络失败设置COREPACK_NPM_REGISTRY为镜像源node-gyp编译报错缺编译工具链Windows装Build ToolsLinux装build-essential找不到xdotoolLinux缺自动化组件apt/yum安装xdotoolEACCES permission deniednpm全局目录权限问题改用户级全局目录不要盲目sudocould not resolve entry module index.htmlinstall阶段资源不完整清store删node_modules重装JavaScript heap out of memoryNode内存上限不足NODE_OPTIONS加大内存启动后界面连不上模型模型后端配置不对或Ollama没启动核对config和服务地址7.2 那些不值得掉的坑给新人的几条硬经验先说删除pnpm这件事。网上很多人建议“删除pnpm重装”但你没搞清楚就删反而会把npm全局目录搞得更乱。卸载之前先npm list -g --depth0看看到底装了什么删除后用pnpm -v确认已经失效再装新版本这样每一步都有明确的状态可查。再提一句“openclaw只能用接入api的方式使用算力吗”的后续如果你选择Ollama本地路线一定先把Ollama服务起起来再启动OpenClaw顺序反了的话OpenClaw会拿不到模型列表。Ollama起了之后用ollama list验证模型存在再继续后续操作。最后是我个人强烈建议每次install或build都保留一份完整日志。执行命令时把输出重定向到文件比如pnpm install install.log 21。报错没头绪的时候在日志里搜“Error”“ERR”等关键词比在终端里翻屏找半天靠谱得多。我排过很多次的坑大半都能靠日志精准定位。我在实际装OpenClaw的过程里最深刻的体会是这类项目的安装难点几乎不在某一条命令本身而在于你对它的依赖体系没有全局概念。pnpm install解决的是“依赖齐不齐”pnpm build解决的是“代码能不能变成可运行产物”每个环节出错都对应一类系统级原因。只要你把Node版本、编译工具链、镜像源、项目路径这四件事一次性做对后面几乎就是一路绿灯。最后再分享一个小技巧装好之后别急着配置一堆东西先跑一个最简单的指令试通链路再逐步叠加模型、技能和自动化场景比如OpenClaw的skill生态和电商运营类的自动化工作流等基础链路通畅了扩展起来会省心很多。折腾的过程本身就是理解这个项目的最佳方式祝你一次跑通。