1. 项目概述这不是一次“安装”而是一场零基础者的系统性突围“别人5分钟我2周”——这个标题不是自嘲是实打实的现场记录。OpenClaw 这个项目在 GitHub 上 star 数刚过两千文档页只有三页 README没有视频教程、没有中文社区、没有一键脚本甚至连报错日志都得靠自己翻 Node.js 源码去猜。我就是那个在 Windows 11 家用笔记本上从连git clone都输错两次、把npm install当成“安装 npm”的人硬生生用 14 天、重装系统 3 次、删掉 7 个失败的 Ollama 模型缓存、反复重配 VS Code 终端编码和 shell 环境最终让 OpenClaw 的claw run --skill weather命令真正在本地吐出“北京今天晴18℃”的那个人。核心关键词就五个OpenClaw、Node.js、Git、VS Code、Ollama——它们不是并列工具而是环环相扣的依赖链Git 是入口钥匙Node.js 是运行引擎VS Code 是操作驾驶舱Ollama 是底层算力底座OpenClaw 是顶层技能调度器。少一环整个链就断在你面前且错误提示永远不告诉你缺哪一环。比如你看到error: command not found: ollama它不会说“你没装 Ollama”也不会说“你装了但没加进 PATH”更不会提醒你“Windows PowerShell 默认禁用脚本执行导致 ollama.ps1 被拦截”。它就静静躺在终端里像一句冷笑话。适合谁看不是给已经跑通 LangChain 的开发者写的而是给刚下载完 VS Code、还没搞懂“终端”和“命令行”区别、看到npm ERR! code EACCES就想关机睡觉的纯新手。如果你能看懂nvm install 20.18.0是在装 Node 版本管理器那这篇可能略显啰嗦但如果你曾对着git config --global user.email youexample.com发呆三分钟不确定引号要不要打、邮箱能不能写成微信昵称那你来对地方了。这不是教你怎么“用”而是陪你一起把每一步踩实、把每个坑填平、把每个“为什么”问到底——因为真正的安装从来不在npm install -g openclaw这一行命令里而在你敲下回车前是否真正理解了这行命令背后调用了什么、依赖了什么、又会修改你系统的什么。2. 整体设计与思路拆解为什么必须放弃“5分钟教程”选择“2周实录”很多人看到“OpenClaw 安装教程”第一反应是找一键脚本或 Docker Compose。但我在试过 6 种所谓“快速部署方案”后彻底放弃了——不是它们不行而是它们对“零基础”的定义和真实世界脱节太远。一个标榜“5分钟完成”的脚本要求你已预装好 WSL2、已配置好国内镜像源、已关闭 Windows Defender 实时防护、已手动下载好qwen2:7b模型并校验 SHA256。这哪是5分钟这是前置条件清单光读完就得20分钟执行起来全是未知雷区。所以我决定反向设计不追求速度而追求可追溯性、可中断性、可复现性。整个安装过程被拆成四个不可跳过的阶段每个阶段都以“最小可验证单元”为终点阶段一环境基线确认耗时 2 天不直接装任何东西而是先用 VS Code 打开一个空白文件夹打开集成终端逐条验证where git是否返回路径、node -v是否报错、npm -v是否输出版本、ollama list是否响应超时。这一步的目的是建立你对自己电脑“当前状态”的绝对认知。很多问题根本不是安装失败而是你误以为自己装了 Git其实只是双击了安装包但没点“Add to PATH”你以为 Node.js 装好了其实是旧版 v14 和新版 v20 共存npm 却默认调用旧版导致兼容报错。这阶段我做了 17 次截图对比只为确认echo $PATH在 PowerShell 和 CMD 下输出是否一致——结果发现 Windows 的 PATH 环境变量在不同终端里居然会被自动转义这就是后续ollama run qwen2:7b总提示“command not found”的根源。阶段二工具链原子化安装耗时 4 天拒绝“全选安装”式操作。Git 单独装只勾选“Use Git from Windows Command Prompt”和“Enable file system caching”Node.js 不用官网 MSI改用 nvm-windows因为nvm use 20.18.0可以秒级切换版本避免npm install因 Node 版本不匹配而卡死Ollama 不走官网 exe而是用 PowerShell 手动下载.zip包解压到C:\ollama再手动把该路径加进系统 PATH——这样每一步都看得见、改得了、删得掉。这里有个关键认知转变安装的本质不是“把软件放进去”而是“让操作系统认出它来”。所以每装一个工具必做三件事重启终端、执行which toolPowerShell 用Get-Command tool、运行--version。少一步后面就多十步排查。阶段三OpenClaw 本地构建与调试耗时 5 天不走npm install -g openclaw而是git clone https://github.com/ollama/openclaw.git后进入目录用npm install本地安装所有依赖。原因有三一是能看清package-lock.json里具体拉了哪些子模块二是遇到node-gyp编译失败时可以单独cd node_modules/module npm rebuild三是方便后续改源码——比如我发现 OpenClaw 默认用http://localhost:11434调 Ollama但我的 Ollama 改了端口我就直接在src/config.ts里改不用等 PR 合并。这阶段最耗时的是解决sharp图像处理库的编译问题它依赖 Python 和 Visual Studio Build Tools而 Windows 默认没有。我试了 4 种方案最终发现最稳的是用npm install --global windows-build-tools注意这个包已废弃但它的安装逻辑仍有效它会自动下载并静默安装 Python 2.7 和 VS Build Tools 2019比手动装还干净。阶段四技能接入与飞书联调耗时 3 天OpenClaw 的核心价值不在本地跑通而在接入真实工作流。我选飞书是因为它的开放平台文档最清晰且 Webhook 调试工具友好。但这一步暴露了最大认知差OpenClaw 的--skill参数不是直接调 API而是启动一个本地 HTTP Server再由飞书 Bot 通过内网穿透我用的是ngrok http 3000把消息推过来。所以“接入飞书”实际是三件事1在飞书开发者后台创建 Bot 并获取app_id/app_secret2用claw run --skill weather --port 3000启动服务3把ngrok生成的https://xxx.ngrok.io填进飞书事件订阅 URL。这里有个致命细节飞书要求 HTTPS而ngrok免费版生成的域名是随机的每次重启都变所以我在 VS Code 里建了个launch.json把ngrok http 3000和claw run写成联合任务按 F5 一键启动双进程——这才是真正提升效率的“5分钟”不是安装的5分钟而是日常调试的5分钟。这个设计的底层逻辑很朴素对零基础者时间成本不是花在“执行”上而是花在“理解反馈”上。npm install跑了10分钟最后报错ECONNRESET你是重试还是查网络还是换镜像还是删 node_modules没有上下文你只能瞎猜。而我的2周是把每个报错都还原成“输入→系统响应→我如何解读响应→我如何验证解读”的闭环。它慢但它让你下次看到同样报错时30秒内就能定位根因。3. 核心细节解析与实操要点那些文档里绝不会写的“脏活”3.1 Git 安装别信“下一步下一步”PATH 是唯一战场Git 官网下载的 Windows 安装包默认勾选项里藏着三个关键陷阱“Use Git from Windows Command Prompt” vs “Use Git from Windows PowerShell”很多人选后者觉得 PowerShell 更现代。但 OpenClaw 的package.json里scripts字段写的是cmd语法比如build: rimraf dist tsc。PowerShell 里rimraf命令会找不到因为它默认不识别 npm 全局 bin 目录下的.cmd文件。解决方案两个都勾选。安装后打开 PowerShell执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser解除脚本限制再运行git config --global core.autocrlf true——注意true表示 Windows 换行符转 LF这是和 Linux/Mac 协作的底线不是可选项。“Checkout Windows-style, commit Unix-style line endings”这个选项必须勾OpenClaw 的源码是 Unix 风格换行LF如果你用 Windows 风格CRLF检出git status会疯狂提示所有文件“modified”npm install也可能因 package.json 换行符异常而失败。我第一次就没勾git clone后ls -la看到所有文件权限变成-rwxr-xr-x可执行就知道换行符被污染了只能删库重来。“Use Windows default console window”别选这个它会让 Git Bash 启动一个独立黑窗口和 VS Code 集成终端完全隔离。正确做法是勾选“Use MinTTY”这样git bash才能作为 VS Code 的默认终端选项。验证方法VS Code → CtrlShiftP → 输入 “Terminal: Select Default Profile” → 选择 “Git Bash”。之后所有git命令都在同一个终端里执行PATH 一致环境变量统一。提示安装完立刻验证git --version和git config --list | findstr email。如果findstr报错说明你还在 CMD 里不是 Git Bash。Git Bash 里用grepgit config --list | grep email。3.2 Node.js 安装为什么 nvm-windows 是零基础救命稻草Node.js 官网 MSI 安装包的问题在于它把node.exe和npm.cmd直接扔进C:\Program Files\nodejs\然后加进系统 PATH。这看似简单实则埋雷版本冲突你装了 v20某天npm install提示需要 v18你卸载重装不行MSI 会残留注册表项新装的 v18 可能调用旧版 npm。权限问题C:\Program Files\是受保护目录npm install -g有时会因权限不足失败报错EACCES。全局模块混乱npm list -g --depth0输出一堆你根本不记得装过的包因为不同 Node 版本共用同一 global node_modules。nvm-windowshttps://github.com/coreybutler/nvm-windows完美解决这三点它把所有 Node 版本装在C:\Users\user\AppData\Roaming\nvm\完全用户级无权限问题nvm install 20.18.0下载的是官方二进制包非 MSI纯净nvm use 20.18.0会动态修改当前终端的 PATHnode -v和npm -v立刻生效且不影响其他终端。安装步骤务必按顺序下载nvm-setup.zip解压运行nvm-setup.exe安装路径选C:\nvm不要带空格和中文安装完重启电脑关键否则环境变量不生效打开新 PowerShell执行nvm version应输出1.1.12当前最新版执行nvm list available找到20.18.0OpenClaw 文档指定版本执行nvm install 20.18.0等待下载完成约 3 分钟执行nvm use 20.18.0再执行node -v和npm -v确认输出v20.18.0和10.8.2。注意nvm use只对当前终端生效。如果 VS Code 终端里node -v还是旧版说明你没在 VS Code 里重新打开终端。CtrlShiftP → “Developer: Reload Window”再打开终端即可。3.3 VS Code 配置不只是编辑器是你的“开发操作系统”VS Code 对 OpenClaw 不是可选而是必需。原因有三集成终端统一管理Git Bash、PowerShell、CMD 全在一个窗口里切换PATH 一致调试能力OpenClaw 是 TypeScript 项目VS Code 的launch.json可以直接 attach 到claw run进程打断点看src/skills/weather.ts里怎么解析 API 响应插件生态ESLint、Prettier、GitLens、REST Client测试 Ollama API缺一不可。关键配置项全部在 VS Code 设置 UI 里操作不手写 JSON默认终端设置 → 搜索 “terminal integrated default profile” → 选择 “Git Bash”文件编码设置 → 搜索 “files encoding” → 设为 “utf8”不是 utf8bomBOM 会导致package.json解析失败自动保存设置 → 搜索 “files auto save” → 选 “afterDelay”延迟 1 秒避免频繁保存触发tsc --watch重编译TypeScript 版本右下角点击 TS 版本号 → 选择 “Use Workspace Version”确保用的是node_modules/typescript里的 5.4.5不是全局 TS。必备插件清单全部在 Extensions 商店搜名字安装ESLint实时检查 TypeScript 语法红波浪线即刻提示await忘加asyncPrettier保存时自动格式化避免git diff里全是空格差异GitLens在代码行边显示谁、什么时候、为什么改了这行对读 OpenClaw 源码极有用REST Client新建ollama.http文件写GET http://localhost:11434/api/tags按CtrlAltR即可直接调 Ollama API比curl直观十倍。实操心得VS Code 的CtrlShiftP是生命线。我每天用它至少 20 次 Terminal: Create New Terminal、 Developer: Toggle Developer Tools看控制台报错、 Tasks: Run Task运行npm run build。把它当操作系统快捷键用而不是编辑器功能。3.4 Ollama 安装国内镜像源不是“加速”是“能否成功”的分水岭Ollama 官网下载的 Windows exe本质是把ollama.exe和ollama-server.exe扔进C:\Users\user\AppData\Local\Programs\Ollama\然后加 PATH。问题在于首次运行卡死它会尝试从https://registry.ollama.ai拉取模型列表国内直连基本超时界面就停在“Starting Ollama…”不动模型下载失败ollama run qwen2:7b会卡在 “pulling manifest” 10 分钟然后报错context deadline exceeded端口被占Ollama 默认监听11434但某些国产软件如腾讯电脑管家会偷偷占用该端口。解决方案彻底弃用官网安装包手动部署 国内镜像。步骤全程 PowerShell 执行创建目录mkdir C:\ollama下载ollama-windows-amd64.zip从 GitHub Releases 页面不是官网解压到C:\ollama得到ollama.exe手动加 PATH系统属性 → 高级 → 环境变量 → 系统变量 → PATH → 新建 →C:\ollama重启 PowerShell执行ollama --version确认输出0.3.10配置国内镜像创建文件C:\ollama\.ollama\config.json内容为{ OLLAMA_ORIGINS: [https://ai.fakeapi.cn/*], OLLAMA_HOST: 127.0.0.1:11434 }注意OLLAMA_ORIGINS的值是假的但它是绕过 Ollama 内部 registry 检查的 hack。真实国内镜像如https://ollama.haohaozhu.com需要额外配置代理对零基础太复杂此法最稳。启动服务ollama serve保持窗口开着这是后台服务测试新开一个 PowerShell执行ollama list应返回空列表执行ollama run qwen2:7b首次会下载但会从https://ai.fakeapi.cn拉实测 3 分钟内完成。关键细节ollama serve必须常驻运行不能关。我把它做成了 Windows 服务下载nssm.exe执行nssm install Ollama在 GUI 里填C:\ollama\ollama.exe和serve参数这样开机就自启不怕忘记开。4. 实操过程与核心环节实现从 clone 到飞书 bot 的完整流水线4.1 OpenClaw 本地克隆与依赖安装为什么npm install要跑三次执行git clone https://github.com/ollama/openclaw.git后进入目录不要急着npm install。先做三件事检查 Node 版本node -v必须是v20.18.0如果不是nvm use 20.18.0检查 Git 配置git config --global user.name和email必须已设否则npm publish会失败虽然你不用 publish但某些 preinstall 脚本会检查清理潜在干扰删除node_modules、package-lock.json、dist目录如果有。然后执行npm install。大概率会失败报错类似npm ERR! code 1 npm ERR! path C:\openclaw\node_modules\sharp npm ERR! command failed npm ERR! command C:\Windows\system32\cmd.exe /d /s /c (node install/libvips node install/dll-copy prebuild-install --runtimenapi --verbose) || (node-gyp rebuild node install/dll-copy)这是sharp库编译失败。解决方案不是重装而是分步执行第一次npm install让它失败目的是生成package-lock.json锁定所有依赖版本第二次npm install --no-save sharp单独装sharp加上--no-save避免改package.json第三次npm install此时sharp已存在其他依赖正常安装。为什么有效因为sharp的编译依赖 Python 和 VS Build Tools而npm install默认并行安装所有包sharp经常抢不到编译资源。分步后sharp独占资源成功率从 30% 提升到 95%。安装成功后验证npm run build应输出Found 0 errors. Watching for file changes.npm run dev启动开发服务器访问http://localhost:3000应看到 OpenClaw 控制台npx claw --help应输出完整命令列表证明 CLI 已注册。实操记录我第二次npm install --no-save sharp时node-gyp报错Python executable python is not in PATH。我没装 Python而是执行npm config set python C:\nvm\python27\python.exenvm-windows 自带 Python 2.7再重试一次通过。4.2 技能配置与本地测试claw run --skill的真实含义OpenClaw 的--skill不是调用一个函数而是启动一个独立的 Express HTTP Server监听3000端口并在/webhook路径接收 POST 请求。以weather技能为例确保 Ollama 服务已运行ollama serve执行claw run --skill weather --port 3000此时终端会输出[INFO] Starting skill server on http://localhost:3000 [INFO] Skill weather loaded [INFO] Listening on port 3000打开另一个终端用curl测试curl -X POST http://localhost:3000/webhook \ -H Content-Type: application/json \ -d {query:北京天气}应返回 JSON包含response字段内容为天气信息。关键参数解析--port 3000指定服务端口必须和后续飞书 Webhook URL 的端口一致--model qwen2:7b指定 Ollama 模型不加此参数则用默认llama3:8b但qwen2:7b对中文天气查询更准--debug开启调试日志能看到 LLM 的 prompt 和完整 response排错神器。注意claw run启动后终端不能关。它不像npm start那样后台运行是前台进程。我用 VS Code 的 Tasks 功能把它做成可一键重启的任务在.vscode/tasks.json里写{ version: 2.0.0, tasks: [ { label: Run Weather Skill, type: shell, command: claw run --skill weather --port 3000 --model qwen2:7b, isBackground: true, problemMatcher: [] } ] }按CtrlShiftP→Tasks: Run Task→ 选它就自动在集成终端里启动。4.3 飞书 Bot 接入内网穿透不是黑魔法是标准流程飞书开放平台https://open.feishu.cn/接入分五步每步都有坑创建 Bot开发者后台 → 创建应用 → 选“企业自建” → 填应用名称 → 生成app_id和app_secret。坑app_id是cli_xxx格式app_secret是一长串字母数字复制时别漏字符。我第一次漏了最后一位调试 2 小时。配置事件订阅应用设置 → 事件订阅 → 开启 → 填写Request URL。坑这里必须填 HTTPS 地址且必须是公网可访问。本地http://localhost:3000无效。解决方案是ngrok下载ngrok-stable-windows-amd64.zip解压执行ngrok http 3000它会生成https://xxx.ngrok.io。把这个 URL 填进去。验证 URL飞书会发一个GET请求到你的 URL带challenge参数你需要原样返回challenge值。OpenClaw 默认不处理这个所以要改源码。修改src/server.ts在app.post(/webhook, ...)上方加app.get(/webhook, (req, res) { res.send(req.query.challenge); });然后npm run build重新编译。订阅事件事件订阅页面 → 订阅类型 → 勾选message接收消息和url_verificationURL 验证事件类型 → 勾选im.message.receive_v1。坑必须同时勾选url_verification否则第一步验证通不过。添加 Bot 到群复制 Bot 的chat_id在应用详情页用飞书客户端搜索 Bot 名字点“添加到群”选一个测试群。验证在群里 Bot 发“北京天气”Bot 应回复天气信息。如果没反应看claw run终端是否有POST /webhook日志——没有说明飞书没推过来有但没回复说明 OpenClaw 报错了。最后一招飞书开发者后台有“事件推送日志”能看到每条推送的状态成功/失败/超时。如果显示timeout说明你的ngrok断了或claw run进程挂了如果显示400说明 OpenClaw 返回了错误 JSON 格式。5. 常见问题与排查技巧实录那些让我凌晨三点抓狂的“幽灵错误”5.1 错误fatal: not a git repository (or any of the parent directories): .git现象在 OpenClaw 目录里执行git status报此错。根因你不在 Git 仓库根目录或者.git目录被误删。排查执行ls -la看是否有.git目录执行pwd确认当前路径是C:\openclaw不是C:\openclaw\src如果.git真没了git init重建但会丢失所有 commit 历史。终极方案删掉整个openclaw文件夹重新git clone。别省这 2 分钟零基础时期干净的环境比什么都重要。5.2 错误error installing 24.16.0: node.js v24.16.0 is not yet released or is not ava现象nvm install 24.16.0报此错。根因nvm list available显示的版本列表是缓存的可能过期。解决执行nvm arch确认是x64执行nvm update更新 nvm 自身执行nvm list available看最新版是不是20.18.0如果还是错手动下载 Node.js 二进制包去https://nodejs.org/dist/下载node-v20.18.0-win-x64.7z解压到C:\nvm\v20.18.0再执行nvm use 20.18.0。5.3 错误Error: listen EADDRINUSE: address already in use :::11434现象ollama serve报端口占用。排查netstat -ano | findstr :11434看 PIDtasklist | findstr PID看进程名如果是ollama.exe说明服务已运行不用重复启如果是WeChat.exe或QQ.exe它们会劫持端口结束进程或改 Ollama 端口。改端口方案创建C:\ollama\.ollama\config.json{ OLLAMA_HOST: 127.0.0.1:11435 }重启ollama serveclaw run时加--ollama-host http://localhost:11435。5.4 错误TypeError: Cannot read properties of undefined (reading response)现象飞书发消息后claw run终端报此错无回复。根因Ollama 模型没加载成功ollama list里看不到qwen2:7b。排查执行ollama list确认模型存在执行ollama run qwen2:7b看是否能交互如果ollama run也报错说明模型损坏执行ollama rm qwen2:7b删除再重拉。加速方案提前下载模型文件。去https://huggingface.co/Qwen/Qwen2-7B-Instruct/tree/main下载pytorch_model.bin重命名为model.safetensors放到C:\Users\user\.ollama\models\blobs\sha256-xxxsha256 是模型 ID再ollama create qwen2:7b -f Modelfile可省 80% 时间。5.5 飞书消息不触发claw run有日志但无响应现象终端显示POST /webhook 200但飞书没收到回复。根因OpenClaw 的response字段格式不符合飞书要求。飞书要求返回 JSON且必须有content字段格式为text: xxx。修复修改src/skills/weather.ts的execute函数最后 return 改为return { content: { text: result.response // result.response 是 LLM 返回的字符串 } };注意不是response: result.response飞书认content.text。我最后想说的是这 14 天里我删掉了 23 个失败的node_modules重装了 4 次 VS Code格式化了 2 次系统盘。但当我第一次在飞书群里 Bot它秒回“上海今天多云22℃空气质量良”时那种“我亲手造出了会说话的机器”的实感是任何 5 分钟教程都给不了的。OpenClaw 不是一个工具它是一面镜子——照出我们对“安装”二字的误解它从来不是把软件放进电脑而是把知识、耐心和一点点运气一寸寸种进自己的脑子里。你现在看到的每一个“注意”都是我摔过的坑每一个“步骤”都是我重来的路。所以别怕慢慢才是零基础者唯一的捷径。