戈玄白今天要做题很多人第一次接触 OpenClaw，是从一个很狼狈的场景开始的——在 PowerShell 里敲下 openclaw 命令，结果返回“无法将‘openclaw’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。我当时也是这样，第一反应是安装包坏了，后来才发现，真正的问题不在 OpenClaw 本身，而在 Node.js 环境没有就绪。这篇指南想把 OpenClaw 的全平台安装一次性讲透，覆盖 Windows、macOS、Linux、Docker 容器和云服务器五种环境，并顺带把安装之后必做的初始化配置、常见报错和升级维护一起交代清楚。OpenClaw 这类本地优先的 AI 代理工具，装起来本身不难，难的是环境差异带来的各种隐藏问题，所以我把重点放在“为什么这么做”和“出错了怎么查”上。
1. 装 OpenClaw 之前，先想清楚这三件事
1.1 它不是“又一个聊天客户端”，而是一个本地运行时
OpenClaw 本质上是一个本地优先的 AI 代理运行时，你可以把它想成一台装在你自己机器上的“AI 调度中枢”。它接收你的指令，根据任务调用不同的模型后端（云端的 Claude、OpenAI，或者本地的 Ollama、NVIDIA NIM），然后在你的终端里执行命令、读写文件、运行脚本，甚至通过插件去操作飞书、微信这类外部服务。这个定位决定了它的安装逻辑和普通应用软件完全不同：它不是一个双击安装的图形程序，而是一个依赖 Node.js 环境、以 CLI 为核心、以工作目录为“家”的命令行工具。搞明白这一点，你就知道为什么那么多人的安装问题都出在环境而非软件本身。
1.2 安装前先定三件事，能少走一半弯路
在我试过的各种安装组合里，最省事的做法是先不要急着敲命令，而是想清楚下面三件事：
- 运行环境：OpenClaw 基于 Node.js 生态，官方推荐使用 Node.js 的 LTS（长期支持）版本。版本太旧或太新都可能遇到模块兼容问题。
- 模型后端：你是准备走云端 API，还是本地模型？如果本地跑过 Ollama，可以走本地模型路线，不仅免费，私密性也好；如果要效果更强的模型，就准备云端 API 的 Key。
- 部署目标：是在自己的 Windows 笔记本上偶尔用，还是放到 Linux 云服务器上 7x24 小时挂着？这会直接决定你用 npm 全局安装、便携包还是 Docker 容器。
| 部署形态 | 适合场景 | 安装难度 | 维护成本 | 典型问题 |
|---|---|---|---|---|
| Windows 本机 | 日常使用、试玩 | 偏低 | 低 | PATH、执行策略 |
| Linux 服务器 | 长期运行、远程调用 | 中等 | 中 | 守护进程、全局权限 |
| macOS 开发机 | 开发调试 | 偏低 | 低 | Node 版本管理 |
| Docker | 环境隔离、快速迁移 | 中等 | 中 | 数据卷、端口映射 |
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Windows 安装实操：从 npm 到便携包
2.1 第一步不是装 OpenClaw，而是把 Node.js 备好
在 Windows 上，我见过太多人卡在第一步：直接去 npm 装 OpenClaw，结果各种报错。建议先去 nodejs.org 下载 LTS 版本的安装包，一路默认即可。装完以后，打开一个新的 PowerShell 窗口，输入 node -v 和 npm -v，能看到版本号，这一步才算过了。这里有个容易忽略的细节：务必新开一个终端窗口，因为旧窗口的环境变量不会自动刷新。如果你已经安装了 nvm-windows，也可以用 nvm install <版本号> 加 nvm use <版本号> 切到 LTS 版本，不同项目需要不同 Node 版本时会方便很多。
2.2 npm 全局安装，以及“cmdlet 识别不了”的根因
环境就绪后，在 PowerShell 里执行官方提供的 npm 全局安装命令。全局安装的意思是把 openc