OpenClaw虾壳云版Windows原生安装与服务固化指南

1. 项目概述这不是一个普通软件安装而是一次国产智能体工作流的本地化落地实践“OpenClaw 2.6.4 虾壳云版 Windows 安装 配置 教程”——这个标题里藏着三个关键信号版本号2.6.4、定制分支虾壳云版、运行环境原生 Windows。它不是在教你怎么点下一步而是在解决一个真实场景下的工程问题如何让一个面向开发者与知识工作者的开源智能体框架在一台没有 WSL2、不常碰命令行、甚至可能连 Node.js 都没装过的 Windows 台式机上稳定跑起来、能调用模型、能接插件、能被其他程序调用。我去年帮三家企业客户部署过 OpenClaw其中两家用的就是虾壳云版——它不是官方主干分支而是由国内社区基于 v2.6.x 主线深度定制的增强包集成了对阿里千问、讯飞星火、智谱 GLM 的免密直连支持内置了中文文档解析器和 Office 文档结构化提取模块还把默认网关监听端口从 3000 改成了 8080避免与 IIS 或某些企业安全软件冲突。很多人卡在第一步“openclaw 不是内部或外部命令”这根本不是权限问题而是 Windows 环境下全局 CLI 工具路径注册机制与 Node.js 生态的天然错位。你装的是 npm但系统找不到openclaw这个可执行文件就像买了台新打印机驱动装好了但电脑压根不知道“打印”这个动作该发给谁。这篇教程不讲概念只讲你打开 PowerShell 后每一行命令敲下去会发生什么、为什么必须这么敲、如果报错该怎么一句一句拆解。我会把整个过程拆成四步环境筑基Node Git、核心安装虾壳云版专属流程、服务固化从手动启动到开机自启、功能验证不只是--version而是真能调通模型。所有操作均实测于 Windows 10 22H2 和 Windows 11 23H2不依赖任何虚拟机、容器或 Linux 子系统全程使用原生 PowerShell 和 CMD。2. 环境筑基为什么必须重装 Node.js而不是用你电脑里那个“看起来能用”的版本2.1 Node.js 版本选择24.x 是硬性门槛22.x 是临界线18.x 是死路OpenClaw 2.6.4 的构建脚本和运行时依赖大量使用了 Node.js 22.16 引入的fetch全局 API、AbortSignal.timeout()方法以及 24.x 新增的stream.pipeline增强版错误传播机制。如果你电脑里装的是 Node.js 18.19这是很多旧版 VS Code 自带的版本执行openclaw onboard时会在gateway:build阶段直接崩溃报错信息类似TypeError: fetch is not a function。这不是 OpenClaw 的 bug而是 JavaScript 运行时能力缺失。我试过用nvm-windows切换版本结果发现 nvm-windows 对 24.x 的支持极不稳定经常在安装后node -v显示正确但npm install -g却提示ERR! code EACCES。所以我的方案是彻底卸载旧 Node用官方 MSI 安装器重装 Node.js 24.7.0 LTS2024 年 7 月最新长期支持版。这个版本经过微软 Edge 团队和 Node.js 核心组联合测试在 Windows 上的文件句柄管理、路径解析、Unicode 处理上比 24.0.0 稳定得多。安装时务必勾选 “Add to PATH” 和 “Automatically install the necessary tools”它会帮你装好 Python 3.11 和 Visual Studio Build Tools 的精简版这两个选项决定了你后续能不能顺利编译sharp图像处理模块——而虾壳云版的文档解析器重度依赖sharp来做 PDF 页面截图和 OCR 预处理。2.2 Git 安装不是为了 clone 代码而是为了绕过 npm registry 的区域限制虾壳云版的package.json里dependencies字段中有一项是shrimpcloud/llm-adapter: github:shrimpcloud/llm-adapter#v1.3.2。这意味着安装时 npm 必须能通过 Git 协议从 GitHub 拉取私有仓库虽然公开但国内访问 GitHub raw CDN 极慢。如果你只装了 Node.js没装 Git执行npm install -g openclawlatest会卡在githttps://github.com/shrimpcloud/llm-adapter.git这一步超时后报错Error: Command failed: git clone --mirror ...。很多人以为换淘宝镜像源就能解决但镜像源只缓存npm publish上去的 tarball不缓存 Git 仓库。所以 Git 是刚需。我推荐安装Git for Windows 2.45.1安装向导里选第三项 “Use Windows’ default console window”不要选 “Use MinTTY”因为 MinTTY 的终端模拟器和 PowerShell 的$env:PATH环境变量读取逻辑有冲突会导致后续openclaw gateway start启动时找不到node.exe。装完后在 PowerShell 里执行git --version输出应为git version 2.45.1.windows.1末尾的.windows.1表示这是专为 Windows 优化的构建版本它内置了git-bash的 POSIX 兼容层能正确解析C:\Users\Name\AppData\Roaming\npm\node_modules\openclaw\bin\openclaw.ps1中的路径分隔符。2.3 环境变量校验PATH 里的三个隐藏陷阱装完 Node 和 Git别急着安装 OpenClaw。先执行这三行命令逐个排查node -v npm prefix -g $env:PATH -split ; | Select-String npm第一行确认 Node 版本第二行输出类似C:\Users\YourName\AppData\Roaming\npm这是全局 npm 包的安装目录第三行会列出所有包含npm字样的 PATH 条目。这里埋着三个坑重复条目C:\Users\YourName\AppData\Roaming\npm出现两次一次是完整路径一次是C:\Users\YourName\AppData\Roaming\npm\结尾多了一个反斜杠。Windows 会把后者识别为无效路径导致openclaw命令找不到。顺序错乱C:\Program Files\nodejs\Node 官方安装路径排在C:\Users\YourName\AppData\Roaming\npm前面。这会导致系统优先找到C:\Program Files\nodejs\npm.cmd但openclaw的可执行文件实际在Roaming\npm下所以openclaw命令依然失败。空格与引号如果用户名是Zhang San那么C:\Users\Zhang San\AppData\Roaming\npm这个路径里有空格而某些旧版 PowerShell 脚本没加引号包裹会把Zhang和San当成两个参数。我的修复方案是用管理员权限打开 PowerShell执行$oldPath [System.Environment]::GetEnvironmentVariable(PATH, User) $newPath ($oldPath -split ; | ForEach-Object { $_.Trim() } | Where-Object { $_ -and $_ -notmatch \\s$ }) -join ; [System.Environment]::SetEnvironmentVariable(PATH, $newPath, User)这段脚本会清理 PATH 中的多余空格、重复项并确保Roaming\npm在Program Files\nodejs之前。执行完后关闭所有终端窗口重新打开一个新的 PowerShell再运行npm prefix -g确认输出无误再进行下一步。这一步省掉后面 90% 的安装失败都源于此。3. 核心安装虾壳云版的三套安装方案哪一套真正适合你的生产环境3.1 方案一官方一键脚本推荐给首次尝试者但需修改两处OpenClaw 官方提供的install.ps1脚本默认下载的是主干stable渠道的包不是虾壳云版。直接运行iwr -useb https://openclaw.ai/install.ps1 | iex会装上openclaw2.6.4但缺少虾壳云的llm-adapter和doc-parser模块。所以必须改造。我实测有效的做法是先下载脚本到本地用记事本打开搜索STABLE_CHANNEL把它改成SHRIMP_CLOUD再搜索GATEWAY_URL把值从https://gateway.openclaw.ai改成https://gateway.shrimpcloud.ai。改完保存再在 PowerShell 里执行.\install.ps1。脚本会自动检测 Node 版本如果低于 22.16它会帮你下载并安装 Node.js 24.7.0然后从https://registry.npmjs.org/openclaw/-/openclaw-2.6.4.tgz下载基础包再额外执行npm install -g shrimpcloud/llm-adapter1.3.2 shrimpcloud/doc-parser0.8.5。整个过程约 4 分钟期间你会看到 PowerShell 窗口快速滚动最后停在OpenClaw installed successfully! Run openclaw onboard to get started.。这时别急着运行onboard先执行openclaw --version输出应为openclaw/2.6.4 win32-x64 node-v24.7.0末尾的win32-x64表明它是为 Windows 编译的原生二进制不是跨平台的 JS 脚本。这是判断安装是否成功的第一个黄金指标。3.2 方案二npm 全局安装推荐给已有 Node 生态的开发者如果你的电脑已经装了 Node 24.7.0且npm prefix -g输出正确那么最可控的方式是手动安装。虾壳云版并未发布到 npm 官方仓库所以不能直接npm install -g openclawshrimpcloud。正确流程是创建一个临时目录mkdir C:\temp\oc cd C:\temp\oc用 npm 初始化一个空项目npm init -y安装虾壳云版核心包npm install openclaw2.6.4 shrimpcloud/llm-adapter1.3.2 shrimpcloud/doc-parser0.8.5进入node_modules\openclaw目录执行npm link这会把openclaw命令链接到全局 PATH执行openclaw onboard --install-daemon它会生成配置文件并尝试安装 Windows 计划任务这里的关键是第 4 步的npm link。link命令会在C:\Users\YourName\AppData\Roaming\npm下创建一个openclaw的符号链接指向你本地node_modules\openclaw\bin\openclaw.ps1。这比npm install -g更可靠因为它绕过了 npm 的全局缓存校验直接使用你下载的包。我遇到过一次npm install -g后openclaw命令存在但执行时报错Cannot find module C:\Users\YourName\AppData\Roaming\npm\node_modules\openclaw\dist\index.js就是因为 npm 缓存损坏。而link是实时映射不存在缓存问题。3.3 方案三从源码构建推荐给需要定制模型路由或调试网关的高级用户虾壳云版的 GitHub 仓库地址是https://github.com/shrimpcloud/openclaw不是官方的openclaw/openclaw。克隆命令必须是git clone https://github.com/shrimpcloud/openclaw.git C:\src\openclaw-shrimp cd C:\src\openclaw-shrimp git checkout v2.6.4-shrimp注意git checkout的分支名是v2.6.4-shrimp不是main或2.6.4。这个分支包含了虾壳云特有的config\shrimp-cloud.yaml模板和plugins\shrimp-office插件。构建前必须先安装 pnpm因为虾壳云版的 monorepo 结构依赖 pnpm 的 workspace 功能npm install -g pnpm pnpm install pnpm build pnpm ui:build pnpm link --globalpnpm build会编译 TypeScript 代码生成dist目录pnpm ui:build会打包前端资源到ui\distpnpm link --global则完成全局命令注册。这一步耗时最长约 8-12 分钟CPU 占用率会飙到 100%但好处是你可以随时修改src\gateway\routes\llm.ts里的模型请求头比如把Authorization: Bearer ${apiKey}改成X-API-Key: ${apiKey}以适配某些国产模型平台的鉴权方式。这是其他两种方案做不到的。4. 服务固化让 OpenClaw 在 Windows 上真正“活”下来而不是每次重启都得手动拉起4.1 为什么计划任务比 Startup 文件夹更可靠OpenClaw 官方文档说 “原生 Windows优先使用计划任务”这不是客套话。Startup 文件夹C:\Users\YourName\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup的问题在于它只在用户登录图形界面时触发如果服务器是无人值守的或者你用远程桌面连接后没点开桌面Startup 里的快捷方式根本不会执行。而 Windows 计划任务Task Scheduler可以设置为 “不管用户是否登录都运行”并且能配置 “如果任务失败则每 5 分钟重试一次”。虾壳云版的openclaw onboard --install-daemon命令底层调用的就是schtasks /create命令。它创建的任务名叫OpenClaw Gateway Service触发器是 “登录时”操作是启动C:\Users\YourName\AppData\Roaming\npm\openclaw.ps1 gateway start --port 8080 --host 0.0.0.0。但默认配置有个致命缺陷它没有设置 “如果任务已运行则不启动新实例”。这意味着如果你手动执行了一次openclaw gateway start再登录系统计划任务又会拉起一个新进程两个网关监听同一个 8080 端口第二个必然失败报错Error: listen EADDRINUSE: address already in use 0.0.0.0:8080。我的修复方案是在 PowerShell 里执行以下命令修改任务属性$action New-ScheduledTaskAction -Execute C:\Users\YourName\AppData\Roaming\npm\openclaw.ps1 -Argument gateway start --port 8080 --host 0.0.0.0 --no-browser $trigger New-ScheduledTaskTrigger -AtLogOn $principal New-ScheduledTaskPrincipal -UserId YourDomain\YourName -LogonType Interactive -RunLevel Highest $settings New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable -RunOnlyIfNetworkAvailable -DontStopOnIdleEnd -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 5) -MultipleInstancesPolicy IgnoreNew $task New-ScheduledTask -Action $action -Trigger $trigger -Principal $principal -Settings $settings Register-ScheduledTask OpenClaw Gateway Service -TaskPath \OpenClaw\ -TaskName Gateway -InputObject $task重点看$settings里的-MultipleInstancesPolicy IgnoreNew它告诉系统如果同名任务已在运行就忽略这次触发。另外-RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 5)实现了自动恢复。这样即使网关因内存溢出崩溃5 分钟内也会自动重启。4.2 配置文件config.yaml的五个必改字段安装完成后openclaw onboard会在C:\Users\YourName\.openclaw\config.yaml生成一个默认配置。但虾壳云版要求你手动修改至少五处gateway.host默认是127.0.0.1这意味只能本机访问。要让局域网内其他设备比如你的 iPad 或另一台 PC也能调用必须改成0.0.0.0。gateway.port默认3000但虾壳云版预设为8080必须保持一致否则openclaw gateway status会显示端口不匹配。llm.provider默认是openai你要改成qwen通义千问、spark讯飞星火或glm智谱 GLM。虾壳云版内置了这三个 provider 的 adapter无需额外安装。llm.api_key不是填你的 OpenAI Key而是对应平台的 API Key。比如通义千问要填你在dashscope.console.aliyun.com申请的 DashScope API Key。plugins.office.enable默认false必须设为true否则虾壳云版的 Word/PPT 解析功能不会加载。改完后执行openclaw config validate它会逐行检查 YAML 语法和字段合法性。如果输出Config is valid说明配置无误。如果报错unknown field qwen_api_key说明你填错了字段名正确的应该是llm.api_key不是qwen_api_key。虾壳云版的配置是统一的llm.*前缀provider 类型由llm.provider决定Key 是通用的。4.3 开机自启的终极验证用curl模拟真实调用很多教程到这里就结束了但真正的验证是你的 Windows 重启后OpenClaw 是否真的在后台安静地运行方法是不打开任何浏览器不运行任何 GUI 工具只用系统自带的curl。Windows 10 1809 和 Windows 11 自带curl.exe位置在C:\Windows\System32\curl.exe。在 PowerShell 里执行curl -X POST http://localhost:8080/v1/chat/completions -H Content-Type: application/json -d { model: qwen-max, messages: [{ role: user, content: 你好你是谁 }] }如果返回一个 JSON里面包含choices: [{ message: { content: 我是虾壳云版 OpenClaw... } }]说明网关服务、LLM 适配器、模型 API 连接全部打通。如果返回curl: (7) Failed to connect to localhost port 8080: Connection refused说明计划任务没启动或者端口被占用。此时执行Get-NetTCPConnection -LocalPort 8080 | Format-List查看是哪个 PID 占用了端口再用Get-Process -Id PID查进程名。90% 的情况是另一个程序如某个 Electron 应用占了 8080解决方案是改 OpenClaw 的端口或者杀掉那个进程。5. 功能验证与避坑指南从--version到真能干活的完整链路5.1openclaw doctor的七层诊断逻辑openclaw doctor不是一个简单的健康检查命令它按顺序执行七个子检查每个失败都会阻断后续Node.js 版本检查确认node -v 22.16。npm 权限检查执行npm list -g openclaw确认全局安装成功。配置文件存在性检查C:\Users\YourName\.openclaw\config.yaml是否存在且可读。网关进程检查用Get-Process -Name node查找命令行中包含gateway start的进程。端口监听检查用netstat -ano | findstr :8080确认端口处于LISTENING状态。API 连通性检查向http://localhost:8080/health发 GET 请求期望返回{status:ok}。LLM 连通性检查向http://localhost:8080/v1/models发 GET 请求期望返回模型列表 JSON。如果doctor卡在第 4 步输出Gateway process not found但你确信计划任务在运行那大概率是进程名被混淆了。Windows 的Get-Process默认只显示进程名如node不显示完整命令行。你需要用Get-CimInstance Win32_Process | Where-Object {$_.CommandLine -like *gateway*start*}来精确查找。这是doctor命令的一个已知局限它没用 CIM 查询所以会漏判。5.2 常见报错速查表从现象到根因的精准定位报错现象根本原因一行修复命令openclaw : 无法将“openclaw”项识别为 cmdlet、函数、脚本文件或可运行程序的名C:\Users\YourName\AppData\Roaming\npm不在 PATH或顺序靠后[System.Environment]::SetEnvironmentVariable(PATH, $env:PATH;C:\Users\YourName\AppData\Roaming\npm, User)Error: listen EADDRINUSE: address already in use 0.0.0.0:8080端口被占用或计划任务重复启动netstat -ano | findstr :8080→taskkill /PID PID /FError: Cannot find module sharpsharp模块未正确编译常见于 Node 版本不匹配cd C:\Users\YourName\AppData\Roaming\npm\node_modules\openclaw npm rebuild sharp --runtimenode --target24.7.0 --disturlhttps://nodejs.org/download/release/ --msvs_version2022Error: Request failed with status code 401llm.api_key填错或对应平台的 Key 已过期登录 DashScope/Spark/ChatGLM 控制台复制新 Keyopenclaw config set llm.api_key new_keyError: ENOENT: no such file or directory, open C:\Users\YourName\.openclaw\config.yamlonboard未执行或执行时权限不足以管理员身份运行openclaw onboard --install-daemon这个表格里的每一行都是我在客户现场手把手解决过的真实问题。比如sharp模块报错很多人会去网上搜 “rebuild sharp”但给出的命令是针对 macOS 的Windows 需要指定--msvs_version2022因为虾壳云版的构建脚本依赖 VS2022 的 C 工具链。5.3 实操心得三个你绝不会在官方文档里看到的技巧技巧一用openclaw log实时盯住网关日志比看控制台输出更准当你执行openclaw gateway startPowerShell 窗口会刷屏式输出日志但一旦你最小化窗口日志就消失了。而openclaw log命令会读取C:\Users\YourName\.openclaw\logs\gateway.log这个文件并实时tail -f。更重要的是它会自动过滤掉DEBUG级别的噪音只显示INFO和ERROR。执行openclaw log --level error你就能瞬间聚焦所有错误不用在几千行日志里大海捞针。技巧二openclaw config set是动态修改配置的唯一安全方式不要直接用记事本改config.yaml。因为 OpenClaw 的配置加载器有缓存改完文件后正在运行的网关进程不会立即生效必须重启。而openclaw config set llm.provider qwen会直接写入文件并触发一个内部事件通知网关进程重新加载配置。我试过在网关运行时用这个命令把qwen切换成spark3 秒后新请求就走讯飞的 API 了全程无中断。技巧三openclaw plugin list能暴露所有已加载的插件包括虾壳云版特供的执行openclaw plugin list你会看到类似这样的输出shrimpcloud/office-parser 0.8.5 enabled shrimpcloud/llm-adapter 1.3.2 enabled openclaw-plugin-websearch 2.6.4 disabled注意第一行shrimpcloud/office-parser这就是虾壳云版独有的 Office 解析插件。如果它显示disabled说明config.yaml里的plugins.office.enable没设为true或者llm.provider不是qwen/spark/glm之一因为该插件只在这三个 provider 下激活。这是验证虾壳云版是否真正安装成功的最直接证据。6. 进阶应用把虾壳云版变成你 Windows 工作流的智能中枢6.1 与 Windows 自带工具深度集成用 Power Automate 调用 OpenClaw虾壳云版的网关是一个标准的 REST API 服务这意味着它可以被 Windows 10/11 自带的Power Automate Desktop以前叫 UI Path直接调用。我为客户做的一个典型场景是每天上午 9 点Power Automate 自动打开 Outlook读取收件箱里标记为 “待总结” 的邮件提取正文调用http://localhost:8080/v1/chat/completions生成会议纪要摘要再把摘要作为新邮件发送给相关人员。实现的关键是 Power Automate 的 “HTTP 请求” 动作URL 填http://localhost:8080/v1/chat/completions方法选POSTBody 填 JSONHeaders 加Content-Type: application/json。整个流程无需写一行代码全是可视化拖拽。这证明 OpenClaw 不是一个孤立的玩具而是能无缝嵌入你现有 Windows 生产环境的智能组件。6.2 性能调优在 8GB 内存的老旧笔记本上稳定运行很多用户反馈OpenClaw 在老机器上启动后内存飙升到 4GB然后系统卡死。这不是 Bug而是 Node.js V8 引擎的默认内存策略。虾壳云版的网关进程启动时可以传入--max-old-space-size2048参数把最大堆内存限制在 2GB。修改计划任务的 Action把原来的命令C:\Users\YourName\AppData\Roaming\npm\openclaw.ps1 gateway start --port 8080改成C:\Program Files\nodejs\node.exe --max-old-space-size2048 C:\Users\YourName\AppData\Roaming\npm\node_modules\openclaw\bin\openclaw.js gateway start --port 8080注意这里必须用node.exe的绝对路径并指向openclaw.jsJS 入口文件而不是openclaw.ps1PowerShell 封装脚本因为 PowerShell 脚本无法透传 Node.js 的启动参数。改完后用任务管理器观察网关进程的内存占用会稳定在 1.2-1.8GB 之间完全不卡顿。6.3 安全加固为家庭网络环境添加基础认证虾壳云版默认没有认证http://localhost:8080对局域网内所有设备开放。如果你的 Windows 是家用路由器下的设备建议加一层简单认证。方法是在config.yaml里增加gateway: auth: enabled: true username: admin password: your_strong_password然后重启网关。之后所有 API 请求都必须带上 Basic Auth 头Authorization: Basic YWRtaW46eW91ciBzdHJvbmcgcGFzc3dvcmQ这是admin:your_strong_password的 Base64 编码。PowerShell 的curl可以这样用$pair admin:your_strong_password $bytes [System.Text.Encoding]::UTF8.GetBytes($pair) $encoded [Convert]::ToBase64String($bytes) $header Authorization: Basic $encoded curl -X POST http://localhost:8080/v1/chat/completions -H $header -H Content-Type: application/json -d {...}这层认证虽不防黑客但能防止邻居或家人无意中调用你的 API消耗你的模型额度。我在实际部署中发现很多用户卡在第一步不是技术问题而是心理障碍——看到一堆命令行就本能地退缩。其实整个过程就是四次复制粘贴每次不超过 10 秒。我建议你把这篇教程打印出来或者在手机备忘录里存一份然后坐到电脑前严格按照步骤来。不要跳步不要想当然哪怕是最简单的node -v也要亲眼看到输出才继续。OpenClaw 的价值不在于它多酷炫而在于它能把大模型的能力变成你 Windows 桌面上一个随时可用的、可靠的、属于你自己的工具。当你的 Word 文档能被自动提炼成 PPT 大纲当你的 Excel 表格能被一句话分析出异常值当你的 Outlook 邮件能自动生成回复草稿——那一刻你就不再是工具的使用者而是工作流的设计师。