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 LTS（2024 年 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 openclaw@latest会卡在git+https://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 条目。这里埋着三个坑：

1. 重复条目：C:\Users\YourName\AppData\Roaming\npm出现两次，一次是完整路径，一次是C:\Users\YourName\AppData\Roaming\npm\（结尾多了一个反斜杠）。Windows 会把后者识别为无效路径，导致openclaw命令找不到。
2. 顺序错乱：C:\Program Files\nodejs\（Node 官方安装路径）排在C:\Users\YourName\AppData\Roaming\npm前面。这会导致系统优先找到C:\Program Files\nodejs\npm.cmd，但openclaw的可执行文件实际在Roaming\npm下，所以openclaw命令依然失败。
3. 空格与引号：如果用户名是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会装上openclaw@2.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-adapter@1.3.2 @shrimpcloud/doc-parser@0.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 openclaw@shrimpcloud。正确流程是：

1. 创建一个临时目录：mkdir C:\temp\oc && cd C:\temp\oc
2. 用 npm 初始化一个空项目：npm init -y
3. 安装虾壳云版核心包：npm install openclaw@2.6.4 @shrimpcloud/llm-adapter@1.3.2 @shrimpcloud/doc-parser@0.8.5
4. 进入node_modules\openclaw目录，执行npm link（这会把openclaw命令链接到全局 PATH）
5. 执行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 --global

pnpm build会编译 TypeScript 代码，生成dist目录；pnpm ui:build会打包前端资源到ui\dist；pnpm 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生成一个默认配置。但虾壳云版要求你手动修改至少五处：

1. gateway.host：默认是127.0.0.1，这意味只能本机访问。要让局域网内其他设备（比如你的 iPad 或另一台 PC）也能调用，必须改成0.0.0.0。
2. gateway.port：默认3000，但虾壳云版预设为8080，必须保持一致，否则openclaw gateway status会显示端口不匹配。
3. llm.provider：默认是openai，你要改成qwen（通义千问）、spark（讯飞星火）或glm（智谱 GLM）。虾壳云版内置了这三个 provider 的 adapter，无需额外安装。
4. llm.api_key：不是填你的 OpenAI Key，而是对应平台的 API Key。比如通义千问，要填你在dashscope.console.aliyun.com申请的 DashScope API Key。
5. 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不是一个简单的健康检查命令，它按顺序执行七个子检查，每个失败都会阻断后续：

1. Node.js 版本检查：确认node -v>= 22.16。
2. npm 权限检查：执行npm list -g openclaw，确认全局安装成功。
3. 配置文件存在性：检查C:\Users\YourName\.openclaw\config.yaml是否存在且可读。
4. 网关进程检查：用Get-Process -Name "node"查找命令行中包含gateway start的进程。
5. 端口监听检查：用netstat -ano | findstr :8080确认端口处于LISTENING状态。
6. API 连通性检查：向http://localhost:8080/health发 GET 请求，期望返回{"status":"ok"}。
7. 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 常见报错速查表：从现象到根因的精准定位

这个表格里的每一行，都是我在客户现场手把手解决过的真实问题。比如sharp模块报错，很多人会去网上搜 “rebuild sharp”，但给出的命令是针对 macOS 的，Windows 需要指定--msvs_version=2022，因为虾壳云版的构建脚本依赖 VS2022 的 C++ 工具链。

5.3 实操心得：三个你绝不会在官方文档里看到的技巧

技巧一：用openclaw log实时盯住网关日志，比看控制台输出更准

当你执行openclaw gateway start，PowerShell 窗口会刷屏式输出日志，但一旦你最小化窗口，日志就消失了。而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切换成spark，3 秒后新请求就走讯飞的 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，方法选POST，Body 填 JSON，Headers 加Content-Type: application/json。整个流程无需写一行代码，全是可视化拖拽。这证明 OpenClaw 不是一个孤立的玩具，而是能无缝嵌入你现有 Windows 生产环境的智能组件。

6.2 性能调优：在 8GB 内存的老旧笔记本上稳定运行

很多用户反馈，OpenClaw 在老机器上启动后内存飙升到 4GB，然后系统卡死。这不是 Bug，而是 Node.js V8 引擎的默认内存策略。虾壳云版的网关进程启动时，可以传入--max-old-space-size=2048参数，把最大堆内存限制在 2GB。修改计划任务的 Action，把原来的命令：

C:\Users\YourName\AppData\Roaming\npm\openclaw.ps1 gateway start --port 8080

改成：

C:\Program Files\nodejs\node.exe --max-old-space-size=2048 C:\Users\YourName\AppData\Roaming\npm\node_modules\openclaw\bin\openclaw.js gateway start --port 8080

注意，这里必须用node.exe的绝对路径，并指向openclaw.js（JS 入口文件），而不是openclaw.ps1（PowerShell 封装脚本），因为 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 邮件能自动生成回复草稿——那一刻，你就不再是工具的使用者，而是工作流的设计师。