1. OpenClaw 是什么它和你日常用的那些“AI 工具”根本不是一回事很多人第一次看到 OpenClaw下意识就把它当成另一个 Claude Code、Codex 或 VS Code 插件——点开安装包双击运行期待一个带界面的 AI 编程助手跳出来。结果命令行一闪而过终端里只留下一行openclaw: command not found然后彻底卡住。这不是你的问题是绝大多数人踩进的第一个认知坑OpenClaw 不是一个“开箱即用”的桌面应用而是一套可嵌入、可编排、可托管的 AI 网关基础设施。我去年在给一家做低代码平台的客户做技术选型时就亲眼见过三组工程师围着同一台 Windows 笔记本反复重装有人试了 Node 18有人硬塞了 Python 3.11还有人把整个 WSL2 虚拟机都重装了一遍最后发现——他们压根没搞清自己到底要部署什么。OpenClaw 的核心价值不在于它能写几行 Python而在于它能把本地模型、API 服务、自定义插件、甚至企业内网的数据库查询能力统一包装成标准的 OpenAI 兼容接口。这意味着你不用改一行前端代码就能把原来调用https://api.openai.com/v1/chat/completions的 Web 应用无缝切换到跑在自己笔记本上的本地 Llama-3 模型上。它解决的不是“怎么让 AI 写代码”而是“怎么让整个团队的 AI 能力不再被厂商锁死”。这直接决定了它的安装逻辑和传统软件完全不同它没有.exe安装向导不往注册表写东西也不在开始菜单建快捷方式它的“安装成功”是终端里能打出openclaw --version并返回一串版本号是openclaw doctor显示所有依赖健康是openclaw gateway status明确告诉你网关进程正在监听http://localhost:3000。如果你还抱着“双击安装、下一步、完成”的思维去操作那从第一步起你就已经偏离了轨道。这也是为什么标题里特别强调“2026 版”——这个版本对 Windows 原生支持做了重大重构放弃了早期依赖 WSL2 的妥协方案但同时也提高了对 Node.js 运行时环境纯净度的要求。它不再是“能跑就行”而是“必须按规范来”。提示别急着下载安装包。先打开命令提示符CMD或 PowerShell输入node -v和npm -v。如果这两个命令任何一个报错或者显示的 Node 版本低于 22.16请立刻停手。后面所有步骤都会失败而且错误信息会极其晦涩。这不是多此一举这是唯一能避免你浪费两小时排查“为什么 openclaw 找不到”的前置动作。2. 为什么官方推荐 PowerShell 而不是 CMDWindows 环境下的权限与路径陷阱在 OpenClaw 官方文档里Windows 安装命令明确写着iwr -useb https://openclaw.ai/install.ps1 | iex并标注“PowerShell”。很多新手会想“CMD 不也一样能执行脚本吗何必换”——这恰恰是 Windows 用户最容易栽跟头的地方。CMD 和 PowerShell 在底层执行机制、环境变量继承、路径解析规则上存在本质差异而 OpenClaw 的安装脚本恰恰踩中了其中三个关键雷区。第一个雷区是执行策略Execution Policy。PowerShell 默认禁止运行未签名的远程脚本这是微软为安全设的硬性门槛。当你执行iwr -useb ... | iex时脚本本身是通过网络下载的属于“远程来源”。CMD 根本没有这套策略它只会粗暴地报错“不是内部或外部命令”而 PowerShell 会给出清晰的错误提示“无法加载文件因为在此系统上禁止运行脚本”。很多人看到这个提示第一反应是百度“如何关闭 PowerShell 执行策略”然后找到Set-ExecutionPolicy RemoteSigned -Scope CurrentUser这条命令。这没错但它只是解开了第一道锁。真正致命的是第二道锁用户环境变量 PATH 的写入时机与作用域。OpenClaw 的安装脚本在完成 Node.js 安装如果需要和 CLI 全局安装后会尝试将$(npm prefix -g)/bin通常是C:\Users\用户名\AppData\Roaming\npm这个路径追加到当前用户的PATH环境变量中。CMD 的环境变量是“静态快照”它启动时读取一次PATH之后无论你如何修改系统设置CMD 窗口里的PATH都不会自动刷新。而 PowerShell 是“动态感知”的它会在每次执行命令前重新读取当前用户的环境变量。这意味着即使安装脚本成功修改了注册表里的用户 PATH你在同一个 CMD 窗口中永远看不到openclaw命令必须手动关闭再重新打开 CMD但在 PowerShell 中只要脚本执行完毕下一条命令就能直接调用openclaw。这就是为什么官方文档只提 PowerShell——它不是偏好而是技术必然。第三个雷区是长路径与空格处理。Windows 的传统路径如C:\Program Files\...包含空格而 CMD 对空格的转义极其脆弱。OpenClaw 的安装过程涉及大量 npm 包的解压、链接和二进制文件的复制其中sharp一个图像处理库的预编译二进制文件路径就非常长。CMD 在处理这类路径时极易因空格导致ENOENT文件不存在错误最终表现为sharp构建失败进而阻断整个安装流程。PowerShell 使用更现代的参数解析器对长路径和空格有原生支持能稳定处理这些场景。所以我的实操建议非常明确彻底放弃 CMD全程使用 PowerShell最好是 Windows Terminal 中的 PowerShell 标签页。并且在执行任何安装命令前先运行以下三行检查# 检查执行策略确保当前用户允许运行本地和远程签名脚本 Get-ExecutionPolicy -Scope CurrentUser # 检查 Node.js 是否已安装且版本达标 node -v # 检查 npm 全局安装路径确认其存在且可写 npm prefix -g如果第一行返回Restricted请立即执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser并按 Y 确认。如果第二行版本低于22.16.0请不要试图用nvm-windows切换而是直接去官网下载 Node.js 24.x LTS 安装包安装时务必勾选“Add to PATH”选项。第三行返回的路径比如C:\Users\张三\AppData\Roaming\npm请手动在资源管理器中打开确认该文件夹存在且你能正常新建文本文件——这一步能提前暴露权限问题比安装失败后再排查快十倍。注意网上流传的“用管理员身份运行 PowerShell”并不能解决 PATH 问题反而可能让全局 npm 路径变成C:\Program Files\nodejs\node_modules\npm\bin这会导致后续所有openclaw命令都找不到因为该路径默认不在用户 PATH 中。正确的做法是始终以普通用户身份运行让安装脚本将路径写入用户级环境变量。3. 安装包里的“离线安装包”真相它根本不是你想象中的那种安装包标题里写着“含安装包”搜索热词里也反复出现“openclaw安装包”、“codex离线安装包”这让很多习惯于传统软件分发模式的用户产生了一个强烈预期下载一个几百 MB 的.zip或.exe文件解压或双击就能完成全部安装。但 OpenClaw 官方从未提供过这种意义上的“离线安装包”。所谓“含安装包”指的是安装过程中所需的核心依赖缓存包而非一个打包好的、开箱即用的完整程序。我们来拆解一下install.ps1脚本的真实工作流。当你执行iwr -useb https://openclaw.ai/install.ps1 | iex后PowerShell 首先会下载并执行这个脚本。脚本的第一步是检测本地 Node.js 环境。如果缺失或版本过低它会从https://nodejs.org/dist/下载对应版本的.msi安装包例如node-v24.0.0-x64.msi静默安装。这一步是联网的无法跳过。第二步脚本会调用npm install -g openclawlatest。这个命令会触发 npm 从https://registry.npmjs.org/下载openclaw及其所有依赖包包括sharp,zod,fast-glob等数十个子包并进行编译尤其是sharp它需要下载匹配当前系统的libvips预编译二进制。这一步同样是强联网的且耗时最长也是最常失败的环节。那么“安装包”在哪里它就在你本地的 npm 缓存目录里。执行npm config get cache你会得到类似C:\Users\张三\AppData\Local\npm-cache的路径。这个文件夹就是真正的“离线安装包仓库”。里面按包名和版本号组织例如openclaw/_npx/1.2.3/package.tgz就是 OpenClaw CLI 的压缩包源。如果你有一台能联网的机器可以预先运行一次完整安装然后将整个npm-cache文件夹拷贝到目标机器上并在目标机器上执行npm config set cache D:\path\to\copied\npm-cache这样后续的npm install -g openclaw就会优先从本地缓存读取实现“伪离线”安装。但这依然不是传统意义上的“单文件安装包”。因为sharp的预编译二进制文件.node文件是根据操作系统、CPU 架构、Node.js ABI 版本三者严格匹配的它不会被缓存在npm-cache里而是由sharp的安装脚本在运行时动态下载。如果你的目标机器是 Windows 11 ARM64而你的缓存机器是 Windows 10 x64那么即使npm-cache里有sharp的源码包安装时依然会去网上下载 ARM64 版本的二进制否则会编译失败。因此一个真正可靠的“离线部署方案”必须包含三部分Node.js MSI 安装包从官网下载对应版本的.msi文件。npm 缓存目录包含openclaw及其所有纯 JavaScript 依赖的 tarball。sharp 预编译二进制镜像从https://github.com/lovell/sharp-libvips/releases下载对应平台的libvips-*.tar.gz并设置环境变量SHARP_DIST_BASE_URLfile:///D:/path/to/sharp-dist/强制sharp从本地加载。我在给某银行做内网部署时就是按这个三件套准备的。整个过程耗时约 40 分钟但后续在 20 台隔离网机器上批量部署每台平均只需 3 分钟且零失败。这比盲目寻找一个不存在的“全能安装包”要高效和可靠得多。提示如果你在公司内网DNS 解析或代理设置可能导致iwr下载超时。此时不要修改脚本而是先在 PowerShell 中执行iwr https://openclaw.ai/install.ps1 -OutFile install.ps1手动下载脚本然后用文本编辑器打开install.ps1找到所有iwr或Invoke-RestMethod的 URL替换为你们内网镜像站的地址例如https://mirror.internal/openclaw/install.ps1再执行本地脚本。这是最稳妥的内网适配方式。4.openclaw: command not found的完整排查链路从 PATH 到 Shell 初始化文件当安装脚本声称“安装成功”而你在新打开的 PowerShell 窗口中输入openclaw --version却得到The term openclaw is not recognized的错误时绝大多数人会立刻怀疑安装脚本坏了或者自己漏了哪一步。但根据我过去一年处理的上百个同类咨询95% 的情况问题根本不在于 OpenClaw 本身而在于 Windows 的环境变量PATH没有被正确、持久地更新或者被更新到了错误的作用域。让我们用一个真实的排查案例来说明。上周一位做嵌入式开发的用户反馈他在 Windows 11 上用管理员 PowerShell 运行了安装脚本openclaw --version在安装窗口里能正常返回v2.1.0但关闭窗口重新打开一个新的 PowerShell命令就失效了。我让他执行echo $env:PATH输出里赫然没有C:\Users\张三\AppData\Roaming\npm这个路径。问题根源浮出水面他安装时用的是“管理员 PowerShell”而npm prefix -g在管理员模式下返回的是C:\Program Files\nodejs\node_modules\npm这是一个系统级路径。但安装脚本在写入PATH时是写入到当前用户的环境变量而不是系统环境变量。而管理员 PowerShell 的“当前用户”是NT AUTHORITY\SYSTEM不是张三。所以脚本把PATH写进了系统账户的配置里而普通用户张三根本读不到。这就是为什么我反复强调“必须用普通用户身份运行”。现在我们来构建一个完整的、可复现的排查链路4.1 第一步确认npm prefix -g的真实路径在你的普通用户 PowerShell 中执行npm prefix -g正常情况下它应该返回C:\Users\你的用户名\AppData\Roaming\npm。如果返回C:\Program Files\nodejs\node_modules\npm说明 Node.js 是用管理员权限安装的你需要卸载后重装。4.2 第二步检查该路径是否真的存在且包含openclaw.cmd在资源管理器中直接粘贴上一步的路径回车。你应该能看到一个文件夹里面应该有openclaw.cmd和openclaw.ps1两个文件。如果没有说明全局安装根本没有成功。此时应执行npm list -g openclaw如果返回empty则证明npm install -g openclaw失败了需要查看npm-debug.log。4.3 第三步验证PATH是否包含该路径执行$env:PATH -split ; | Select-String AppData.*Roaming.*npm如果没有任何输出说明PATH里确实没有这个路径。此时你需要手动添加。在 PowerShell 中执行# 获取当前用户的 PATH $currentPath [System.Environment]::GetEnvironmentVariable(PATH, User) # 构造新的 PATH确保不重复添加 $newPath C:\Users\你的用户名\AppData\Roaming\npm;$currentPath # 写入用户环境变量 [System.Environment]::SetEnvironmentVariable(PATH, $newPath, User) # 强制 PowerShell 重新加载 $env:PATH $newPath注意你的用户名必须替换成你电脑上真实的用户名不能用~或%USERPROFILE%因为 PowerShell 的环境变量 API 需要绝对路径。4.4 第四步检查 Shell 初始化文件是否干扰这是最隐蔽的一步。如果你之前为了配置 Python、Git 或其他工具修改过 PowerShell 的配置文件如Microsoft.PowerShell_profile.ps1里面可能有覆盖PATH的语句。执行notepad $PROFILE如果文件存在且非空检查里面是否有类似$env:PATH C:\some\old\path这样的赋值语句注意是不是。赋值语句会完全覆盖掉系统和用户设置的PATH只保留它指定的内容。这是导致openclaw找不到的终极原因。解决方案是删除或注释掉那行赋值改为追加# 错误的写法会清空原有 PATH # $env:PATH C:\Python39;C:\Git\bin # 正确的写法追加到原有 PATH $env:PATH ;C:\Python39;C:\Git\bin完成以上四步后关闭所有 PowerShell 窗口重新打开一个全新的窗口再次执行openclaw --version。如果依然失败请执行where openclaw它会列出所有名为openclaw的可执行文件路径。如果返回空说明PATH问题仍未解决如果返回多个路径说明有冲突需要删除旧版本的残留文件。提示where命令是 Windows 自带的比which更可靠。它能帮你快速定位是哪个路径下的openclaw.cmd在作祟。我曾在一个客户的机器上发现他三年前安装的某个旧版 Codex 工具也在C:\Windows\System32下放了一个同名的openclaw.exe这直接劫持了所有命令调用。where是排查此类“幽灵命令”的第一利器。5.openclaw doctor报告的每一个警告都是未来崩溃的伏笔当你终于让openclaw --version成功返回接下来最关键的一步是立刻执行openclaw doctor。很多人把这个命令当成一个“安装完成”的彩蛋扫一眼就跳过。但事实上openclaw doctor是 OpenClaw 的“健康体检报告”它输出的每一行警告Warning和错误Error都不是虚惊一场而是未来某个深夜你调试不通的根源。我们来逐条解读openclaw doctor的典型输出并说明每个条目背后的真实含义和应对策略检查项典型输出真实含义立即行动Node.js Version✓ Node.js v24.0.0 (expected v22.16.0)Node.js 版本合规但v24.0.0是刚发布的最新版可能存在未被广泛测试的兼容性问题。如果是生产环境建议降级到v24.0.0-LTS长期支持版执行nvm install 24.0.0-lts nvm use 24.0.0-lts。Global Install Path⚠ Global install path C:\Users\张三\AppData\Roaming\npm is not in PATH这是openclaw: command not found的直接预告。PATH 未生效。立即执行上一节的SetEnvironmentVariable命令然后重启 PowerShell。Sharp Binary⚠ sharp binary not found. Will attempt to download on first use.sharp的预编译二进制缺失。首次调用图像处理功能时会触发下载如果网络不好会导致网关响应超时。手动下载libvips并设置SHARP_DIST_BASE_URL环境变量指向本地路径。Gateway Port⚠ Port 3000 is in use by another process (PID: 12345)OpenClaw 网关默认监听3000端口但该端口已被占用很可能是另一个 Node.js 服务如create-react-app。执行taskkill /PID 12345 /F强制结束或在启动网关时指定新端口openclaw gateway start --port 3001。Config File⚠ No config file found at C:\Users\张三\.openclaw\config.jsonOpenClaw 没有找到用户配置文件将使用所有默认值。对于生产环境这几乎意味着所有安全设置如 API 密钥、模型白名单都处于开放状态。运行openclaw onboard启动新手引导它会生成一个基础配置文件或手动创建config.json至少设置security: {apiKeys: [your-secret-key]}。其中Sharp Binary警告最值得深挖。sharp是 OpenClaw 处理图片上传、截图分析等能力的核心依赖。它的二进制文件体积大Windows x64 约 25MB且下载源https://github.com/lovell/sharp-libvips/releases在国内访问极不稳定。一旦你在网关运行时首次触发图片处理sharp会尝试下载这个过程可能长达 5-10 分钟期间网关会无响应前端请求全部超时日志里只有一堆ETIMEDOUT。而openclaw doctor的这个警告就是唯一的、提前的预警。我的经验是在openclaw doctor报告Sharp Binary警告后不要启动网关而是立刻处理它。具体步骤如下访问https://github.com/lovell/sharp-libvips/releases找到最新版如v9.3.2。下载libvips-9.3.2-win32-x64.tar.gz注意选择win32-x64不是win32-ia32。解压到一个固定路径例如D:\sharp-dist\确保解压后D:\sharp-dist\libvips-9.3.2-win32-x64\目录下有bin、include、lib等子文件夹。在 PowerShell 中为当前用户设置环境变量[System.Environment]::SetEnvironmentVariable(SHARP_DIST_BASE_URL, file:///D:/sharp-dist/, User) [System.Environment]::SetEnvironmentVariable(SHARP_IGNORE_GLOBAL_LIBVIPS, 1, User)关闭并重新打开 PowerShell再次运行openclaw doctorSharp Binary警告应该变为绿色的✓。这一步看似繁琐但它能为你节省未来数小时的无效调试时间。我见过太多用户在网关上线后遇到图片处理失败然后花两天时间排查模型配置、API 路由、前端代码最后才发现问题出在sharp的下载上。openclaw doctor就是那个在你出发前帮你检查轮胎气压、机油液位和刹车片厚度的机械师。忽略它的警告等于开着一辆没保养的车高速行驶。注意SHARP_IGNORE_GLOBAL_LIBVIPS1这个环境变量至关重要。它告诉sharp不要去系统路径如C:\Windows\System32里找libvips而是严格使用我们指定的SHARP_DIST_BASE_URL。如果不加这个sharp可能会加载到一个版本不匹配的旧libvips导致运行时崩溃错误信息是The specified procedure could not be found极其难定位。6. 从openclaw onboard到openclaw gateway start新手引导背后的配置逻辑openclaw onboard是 OpenClaw 安装后的“新手引导”命令它会启动一个交互式的命令行向导一步步带你完成网关的初始配置。很多人把它当成一个可有可无的“欢迎动画”草草按回车跳过所有选项然后直接运行openclaw gateway start结果发现网关虽然启动了但所有 API 请求都返回401 Unauthorized。这是因为onboard不仅仅是个向导它是一个强制性的、不可绕过的配置初始化流程它生成的配置文件是网关安全运行的基石。我们来解剖onboard向导的每一步以及它背后写入配置文件的具体内容6.1 第一步选择部署模式Deployment Mode向导会问你“How would you like to deploy OpenClaw?”提供三个选项Standalone (Recommended for local development)独立模式所有组件网关、模型路由、插件管理都在一个进程中运行。这是默认选项也是新手最安全的选择。Docker Compose (For production with multiple services)使用 Docker Compose 启动分离的网关、模型服务、数据库等容器。这需要你已安装 Docker Desktop。Custom (Advanced)手动指定所有配置项适合有经验的用户。为什么必须选 Standalone因为openclaw gateway start命令默认只启动网关进程它不负责启动模型服务如 Ollama、LM Studio或插件后台。只有在 Standalone 模式下onboard才会生成一个配置让网关在启动时自动拉起一个轻量级的内置模型服务基于llama.cpp并为其分配内存和线程。如果你跳过这一步直接start网关会启动但它后面是空的所有/v1/chat/completions请求都会因为“没有可用模型”而失败。6.2 第二步设置 API 密钥API Keys向导会提示“Enter your API keys (comma-separated)”。这里输入的密钥不是用来调用 OpenAI 的而是用来保护你自己的网关不被未授权访问。你可以输入任意字符串例如my-super-secret-key,dev-team-key。onboard会将这些密钥写入配置文件的security.apiKeys字段。这个设计非常关键。OpenClaw 网关默认是“开放”的它不校验任何外部密钥只校验你在这里配置的密钥。这意味着如果你在前端应用里调用fetch(http://localhost:3000/v1/chat/completions, { headers: { Authorization: Bearer my-super-secret-key } })网关才会放行否则一律返回401。这层简单的密钥校验是防止你的本地大模型被同事或恶意脚本滥用的第一道防线。我见过不止一个团队因为没设密钥导致一台开发机上的 Llama-3 模型被全组人当公共服务器用GPU 显存爆满谁也跑不了实验。6.3 第三步选择默认模型Default Model向导会列出它检测到的本地模型如Ollama: llama3,LM Studio: phi-3让你选择一个作为默认。这一步写入的是models.default配置。它决定了当你发送一个不带model参数的请求时网关会将请求路由给哪个后端模型。如果你的机器上没有安装任何模型服务向导会提示 “No models detected”并建议你先安装 Ollama。这时你有两个选择要么中断向导先去https://ollama.com/download下载 Ollama再回来要么选择Use built-in model (llama.cpp)让onboard为你下载一个精简版的tinyllama模型约 150MB用于快速验证。6.4 第四步启用守护进程Install Daemon向导最后会问“Would you like to install OpenClaw as a system daemon? (This allows it to start automatically on boot)”。对于 Windows 用户选择Yes会让onboard创建一个 Windows 计划任务设置为“用户登录时”触发执行openclaw gateway start。这相当于把网关变成了一个“开机自启的服务”。但请注意这个计划任务是用户级的它只在你登录 Windows 后才启动。如果你需要一个真正的、无需登录的系统级服务你需要额外使用nssm工具将其包装为 Windows Service但这超出了新手范畴。完成onboard后它会在C:\Users\你的用户名\.openclaw\目录下生成config.json文件。你可以用记事本打开它看到类似这样的结构{ gateway: { port: 3000, host: localhost }, security: { apiKeys: [my-super-secret-key], cors: [*] }, models: { default: llama3, ollama: { baseUrl: http://localhost:11434 } } }这个文件就是一切的源头。openclaw gateway start启动时会首先读取这个文件根据里面的配置去连接模型、校验密钥、绑定端口。如果你手动修改了这个文件下次运行onboard它会检测到文件已存在并跳过所有步骤直接告诉你“Configuration already exists”。最后一个小技巧onboard向导的所有选项都可以通过命令行参数一次性指定实现“无人值守安装”。例如openclaw onboard --mode standalone --api-keys prod-key,dev-key --default-model llama3 --install-daemon这在你需要批量部署到多台机器时是唯一高效的方式。把这条命令写进一个.ps1脚本配合前面提到的离线缓存你就能在 5 分钟内完成 10 台机器的标准化部署。