OpenClaw Windows 启动指南

OpenClaw Windows 启动指南

在Windows系统上运行这个项目，你可能会直接遇到几个典型的、让新手头疼的问题。别担心，我们把它理清楚，并提供可靠的解决方案。

问题

核心挑战有两个：一是项目构建脚本依赖Bash环境，而Windows自带的PowerShell或CMD并不兼容；二是用pnpm进行包管理时，模块解析有时会出岔子。说白了，想在Windows上顺利跑起来，你得换个“壳”。

解决方案

下面是三个备选方案，你可以根据自身技术偏好和系统环境来选择。

方案一：安装 Git Bash（推荐）

这是最直接、对新手也最友好的方法。说白了，就是给Windows装上一个好用的Bash终端。

1. 安装Git for Windows：去官网（https://git-scm.com/download/win）下载并安装。这个过程会附带安装Git Bash。
2. 打开Git Bash：安装完成后，在开始菜单找到并打开它，一个熟悉的命令行界面就出现了。
3. 进入项目目录：在Git Bash中导航到你的项目位置。注意路径写法是Unix风格的：cd /d/BaiduNetdiskDownload/openclaw/openclaw
4. 安装依赖：如果还没做，运行 pnpm install 来安装所有必需的包。
5. 启动项目：一切就绪后，用 pnpm start 启动生产环境，或者用 pnpm dev 进入带热重载的开发模式。

这样一来，项目脚本就完全在它熟悉的环境中运行了，问题迎刃而解。

方案二：使用 WSL2

如果你更偏爱原生Linux环境，或者经常进行跨平台开发，Windows Subsystem for Linux 2（WSL2）是个更彻底的方案。

1. 在Windows功能中启用“适用于Linux的Windows子系统”和“虚拟机平台”，然后从Microsoft Store安装一个发行版（比如Ubuntu）。
2. 在WSL2的Linux环境中，访问或克隆你的项目代码。
3. 确保安装了Node.js和pnpm。
4. 运行命令。注意，访问Windows盘符下的文件，路径通常在/mnt/下，例如：cd /mnt/d/BaiduNetdiskDownload/openclaw/openclaw，之后同样执行pnpm install和pnpm start。

这个方案让你获得近乎原生的Linux开发体验，一劳永逸。

方案三：手动构建（临时方案）

如果项目已经构建好了dist文件，只是无法通过脚本启动，可以试试这个权宜之计。直接在Windows PowerShell中执行：

cd d:\BaiduNetdiskDownload\openclaw\openclaw
$env:OPENCLAW_RUNNER_LOG="0"
node scripts/run-node.mjs

这相当于绕过了部分构建流程，直接调用Node运行核心代码。但注意，这不能解决首次安装或代码变更后的构建需求。

常用命令

熟悉这几个命令，能让你在项目中更加游刃有余：

• pnpm start - 启动生产环境服务器。
• pnpm dev - 启动开发环境，代码变动会自动重载，效率必备。
• pnpm openclaw --help - 查看OpenClaw命令行工具的所有可用指令和帮助。
• pnpm tui - 启动文本用户界面（TUI），如果你更喜欢图形化的操作方式。

注意事项

在开始之前，请务必确认以下环境条件，这能避免大量不必要的麻烦：

1. Node.js版本：确保是22.12.0或更高版本。版本不符是许多奇怪错误的源头。
2. pnpm版本：使用10.23.0或更高版本。不同版本间的包管理策略可能有差异。
3. 耐心等待首次构建：第一次运行pnpm install或pnpm build时，可能会花费较长时间，这是正常现象。

故障排除

即便按照指南操作，也可能遇到一些具体错误。这里有几个常见问题的应对策略。

如果看到 “missing dist/entry.(m)js” 错误

这个错误信息很明确：项目还没有被构建，运行时代码找不到入口文件。解决起来很简单，在Git Bash中执行一次构建命令即可：

pnpm build

构建完成后，再尝试启动。

如果看到 “Cannot find package ‘chalk’” 错误

这是典型的pnpm模块解析问题。模块安装好了，但Node运行时找不到它们。请按以下步骤检查：

1. 确认你在项目根目录下执行了pnpm install，并且没有报错。
2. 务必使用pnpm exec或pnpm run来运行项目命令（如pnpm start），这能确保使用正确的模块路径。
3. 避免直接使用node命令去运行编译后的.js文件，这很容易错过pnpm设置的包解析环境。

如果构建脚本报错 “bash not found”

这又回到了我们最初的问题：Windows原生环境没有Bash。解决方法就是回到上方“方案一”，安装Git Bash，为你的Windows补上这个关键组件。