OpenClaw��Win中部署

OpenClaw🦞windows部署

在Windows-WSL-Debian13

基于 npm 安装

0. Windows下启动wsl

以下都可以交给codex完成

• • 默认已经有wsl2
• • wsl.exe --list --online
• • 显示可安装的linux子系统
• • wsl.exe --install Debian
• • 安装Debian子系统（可选择其他系统）
• • wsl -d Debian进入子系统
• • 安装一些常用工具
• • 比如git curl nodejs npm等
• • 安装官方的OpenClaw🦞
• • npm isntall -g @openclaw/latest
• 能启动的话这就可以开始使用了
• 想要助力真实工作还是需要研究一下的**如果失败那么就选择仓库源码构建**
• 
  

1. 记录元数据

• • 记录时间: 2026-03-15
• • 目标环境: Windows 下 WSL 内 Debian 13
• • 项目仓库: openclaw
• • 用户约束: 仅允许使用既有 npm install 路径排查与修复，不改用其他安装方式
• • 本次操作边界:
• • 未改用 pnpm/bun/源码构建安装作为替代安装方式
• • 未重新从网络安装其他发行渠道的 OpenClaw
• • 所有修复均围绕既有 npm 全局安装结果与本机本地文件展开

2. 执行目标

目标是对“已经通过 npm install 安装，但启动失败”的 OpenClaw CLI 做一次完整排查，并完成长期修复，要求结果满足以下条件:

• • 可复现: 后续在同类 WSL 环境中可按步骤复做
• • 可回溯: 能看清每个阶段发现了什么、为什么这么做
• • 可审计: 有明确命令、明确观察结果、明确最终状态
• • 重点避坑: 明确记录 npm 全局前缀、PATH、符号链接、离线包、运行时依赖等关键坑点

3. 初始环境与基线确认

3.1 基线命令

1
2
3
4
5

pwd
node -v
npm -v
git status --short
ls -la

3.2 基线事实

• • 当前仓库目录为 /home/你的路径/work_openclaw/openclaw
• • Node 版本为 v24.14.0
• • npm 版本为 11.9.0
• • 仓库工作区无额外未提交改动

3.3 关键判断

进一步检查发现，当前仓库目录本身并不是“本地已构建可直接运行”的状态:

1
2

test -d node_modules && echo yes || echo no
ls -la dist

结果:

• • 仓库下不存在本地 node_modules
• • 仓库下不存在本地 dist

结论:

• • 当前问题不是“仓库源码已经装好但构建失败”
• • 更符合“OpenClaw 是通过 npm 全局安装的 CLI，但命令启动失败”的路径

4. 阶段一: 复现真实失败现象

4.1 复现命令

1
2
3
4

which openclaw
npm list -g openclaw --depth=0
openclaw --version
openclaw --help

4.2 观察结果

• • npm list -g openclaw --depth=0 显示已安装 openclaw@2026.3.13
• • 但 which openclaw 无结果
• • openclaw --version 报错: command not found
• • openclaw --help 报错: command not found

4.3 第一结论

这一步确认了最重要的事实:

• • OpenClaw 并不是“没装上”
• • 而是“已经装上，但 shell 找不到命令入口”

这属于典型的 npm 全局安装目录与 PATH 不一致 问题。

5. 阶段二: 定位 npm 全局前缀与 PATH 错位

5.1 定位命令

1
2
3
4
5

npm prefix -g
npm root -g
ls -la $(npm prefix -g)/bin
npm config get prefix
echo "$PATH"

5.2 关键观察

• • npm 全局前缀为:

1

/home/你的路径/.local/opt/node-v24.14.0-linux-x64

• • 该目录下存在真实的 openclaw 可执行入口:

1

/home/你的路径/.local/opt/node-v24.14.0-linux-x64/bin/openclaw

• • 但当前 shell 的 PATH 中并不包含:

1

/home/你的路径/.local/opt/node-v24.14.0-linux-x64/bin

• • 当前 PATH 包含的是:

1

/home/你的路径/.local/bin

5.3 进一步确认

为了排除“命令文件损坏”的可能，又直接用绝对路径启动:

1
2

$(npm prefix -g)/bin/openclaw --version
$(npm prefix -g)/bin/openclaw --help

观察结果:

• • 绝对路径下 CLI 正常运行
• • openclaw --version 返回 OpenClaw 2026.3.13 (61d171a)
• • openclaw --help 正常输出完整帮助信息

5.4 阶段结论

根因明确为:

1. 1. npm 的全局安装前缀被配置到了版本化 Node 目录下
2. 2. shell 只把 ~/.local/bin 放进了 PATH
3. 3. 因此 npm install -g openclaw 成功，但 openclaw 命令没有暴露到 shell 中

6. 阶段三: 先做短期修复，恢复命令可用

6.1 修复动作

为保持与当前 node / npm 的暴露方式一致，先补一个符号链接:

1

ln -s /home/你的路径/.local/opt/node-v24.14.0-linux-x64/bin/openclaw /home/你的路径/.local/bin/openclaw

6.2 验证命令

1
2
3
4

ls -la /home/你的路径/.local/bin/openclaw
readlink -f /home/你的路径/.local/bin/openclaw
openclaw --version
bash -lic 'which openclaw && openclaw --version'

6.3 短期修复结果

• • openclaw 命令恢复可用
• • 登录 shell 下 which openclaw 能正确找到命令
• • openclaw --version 正常输出版本号
• • openclaw --help、openclaw doctor --help 可运行

6.4 审计结论

短期修复只解决了“命令暴露”问题，没有解决“未来安装仍可能再次错位”的长期问题。

7. 阶段四: 长期修复设计

7.1 长期修复目标

为了避免未来再次出现“npm 已安装但命令不在 PATH”问题，需要让 npm 的全局前缀稳定落在 shell 已经包含的目录体系中。

当前 shell 已包含:

1

/home/你的路径/.local/bin

因此长期修复策略定为:

• • 将 npm 用户级全局前缀固定为 ~/.local
• • 使未来的全局安装命令入口稳定落在 ~/.local/bin
• • 使全局包稳定落在 ~/.local/lib/node_modules

7.2 配置动作

执行:

1

npm config set prefix /home/你的路径/.local --location=user

验证:

1
2
3

cat ~/.npmrc
npm config get prefix
npm config get prefix --location=user

结果:

• • ~/.npmrc 中写入了:

1

prefix=/home/你的路径/.local

• • npm 当前用户级前缀稳定为 /home/你的路径/.local

8. 阶段五: 基于既有 npm 安装做本地迁移时踩到的坑

这一阶段是本次排查最需要重点审计和复盘的部分。

8.1 坑一: 直接从“已安装目录”再次 npm install -g，不一定得到独立安装

尝试过如下操作:

1

npm install -g --prefix /home/你的路径/.local --ignore-scripts --force /home/你的路径/.local/opt/node-v24.14.0-linux-x64/lib/node_modules/openclaw

表面上安装成功，但检查后发现:

1

ls -la /home/你的路径/.local/lib/node_modules/openclaw

结果显示:

• • ~/.local/lib/node_modules/openclaw 只是一个软链接
• • 它仍然指回旧的版本化 Node 安装目录

这意味着:

• • 该方法并未真正摆脱旧路径依赖
• • 只是把引用关系从命令层转移到了包目录层

避坑结论

不要把下面这条命令误认为“会生成一个自包含的新全局安装”:

1

npm install -g --prefix ~/.local <一个本地已安装包目录>

对于本地目录源，npm 很可能创建的是 符号链接式安装，不是完整复制。

8.2 坑二: npm install -g 覆盖已有 bin 链接时可能报 EEXIST

测试过程中发现，如果目标前缀下已经存在同名二进制入口，例如:

1

/tmp/openclaw-overwrite/bin/openclaw

则再次安装时会报:

1

npm ERR! EEXIST: file already exists

后续验证表明:

• • 使用 --force 可以覆盖这类已存在入口
• • 但 --force 只能解决入口冲突，不能解决“目录安装被处理成软链接” 这个更深层问题

避坑结论

• • --force 只能解决覆盖问题，不能解决安装形态问题
• • 覆盖成功不等于安装结果是独立、完整、自包含的

8.3 坑三: 离线打包/安装验证时，npm cache 可能出现 EACCES

在尝试离线验证过程中，遇到过类似错误:

1
2

npm error code EACCES
npm error Your cache folder contains root-owned files

虽然随后检查用户级 ~/.npm 顶层目录时显示为 你的路径:你的路径，但为避免缓存污染继续影响验证，后续 pack/install 测试全部切换为临时 cache:

1
2

npm --cache /tmp/openclaw-npm-cache pack ...
npm --cache /tmp/openclaw-npm-cache install ...

避坑结论

• • WSL/提权混用 npm 时，cache 权限容易变脏
• • 排查阶段如果出现 cache 权限异常，优先切到临时 cache，避免把“缓存问题”误判成“包本身问题”

8.4 坑四: 从离线 tarball 解包得到的目录不等于“可直接运行的完整安装”

为避免“目录安装被转成软链接”，曾尝试本地离线打包:

1

npm --cache /tmp/openclaw-npm-cache pack --ignore-scripts --pack-destination /tmp/openclaw-pack-out /home/你的路径/.local/opt/node-v24.14.0-linux-x64/lib/node_modules/openclaw

然后把 tarball 解包到稳定目录，试图形成真正实体目录安装。

解包后检查发现:

• • dist/entry.js 文件是存在的
• • 但运行 openclaw --version 时却报:

1

Error: openclaw: missing dist/entry.(m)js (build output).

这条错误信息容易误导。进一步核对发现真正的问题不是 dist/entry.js 不存在，而是:

• • openclaw.mjs 的 tryImport('./dist/entry.js') 会在导入失败时统一转成“missing dist/entry”
• • 实际失败原因是解包后的稳定目录缺少运行时 node_modules
• • 也就是说，entry.js 存在，但它的依赖无法被解析

避坑结论

遇到以下报错时:

1

openclaw: missing dist/entry.(m)js

不要第一时间只看 dist/entry.js 文件是否存在。还要检查:

1

test -d <安装目录>/node_modules

因为这类报错也可能是 入口文件存在，但其运行时依赖缺失 导致的包装性误报。

9. 阶段六: 最终长期修复实施

9.1 最终实施思路

经过前述验证，最终采用如下长期修复方案:

1. 1. 保留 npm 用户级前缀为 ~/.local
2. 2. 保留命令入口为 ~/.local/bin/openclaw
3. 3. 将 ~/.local/lib/node_modules/openclaw 替换为真实实体目录，而非指向旧 Node 目录的软链接
4. 4. 将原始已安装 OpenClaw 的运行时 node_modules 一并复制到稳定目录中

9.2 关键实施动作

第一步: 将稳定目录替换为实体目录

先把从本地 tarball 解出的 package 目录放到稳定位置:

1

mv -T /tmp/openclaw-extract/package /home/你的路径/.local/lib/node_modules/openclaw

第二步: 补齐运行时依赖

1

cp -a /home/你的路径/.local/opt/node-v24.14.0-linux-x64/lib/node_modules/openclaw/node_modules /home/你的路径/.local/lib/node_modules/openclaw/

9.3 最终目录形态

最终形成如下结构:

• • ~/.local/bin/openclaw 为符号链接
• • 该链接指向 ~/.local/lib/node_modules/openclaw/openclaw.mjs
• • ~/.local/lib/node_modules/openclaw 为真实目录
• • ~/.local/lib/node_modules/openclaw/node_modules 为真实运行时依赖目录

这意味着:

• • 命令入口已经稳定
• • 包目录已经稳定
• • 运行时依赖已经齐全
• • 不再依赖旧的版本化 Node 安装路径中的 openclaw 包目录

10. 最终验证结果

10.1 验证命令

1
2
3
4
5
6

npm config get prefix
openclaw --version
bash -lic 'which openclaw && openclaw --version && npm config get prefix'
node -e "import('/home/你的路径/.local/lib/node_modules/openclaw/dist/entry.js').then(()=>console.log('entry-ok')).catch(err=>{console.error(err);process.exit(1)})"
ls -ld /home/你的路径/.local/lib/node_modules/openclaw /home/你的路径/.local/bin/openclaw
readlink -f /home/你的路径/.local/bin/openclaw

10.2 验证结果

• • npm config get prefix 输出:

1

/home/你的路径/.local

• • openclaw --version 输出:

1

OpenClaw 2026.3.13 (61d171a)

• • 登录 shell 下:

1
2
3

/home/你的路径/.local/bin/openclaw
OpenClaw 2026.3.13 (61d171a)
/home/你的路径/.local

• • 直接导入入口模块结果:

1

entry-ok

• • 当前 ~/.local/lib/node_modules/openclaw 已确认为真实目录而非软链接

11. 审计结论

本次问题的最终根因链如下:

1. 1. OpenClaw 通过 npm 全局安装成功
2. 2. npm 的全局前缀落在版本化 Node 安装目录下
3. 3. shell PATH 只包含 ~/.local/bin，不包含该版本化前缀的 bin
4. 4. 因此 openclaw 命令无法被 shell 发现
5. 5. 进一步长期修复时，如果直接拿“已安装目录”做 npm install -g，npm 会把它当成本地目录源并创建软链接式安装
6. 6. 如果只是把 tarball 解包成目录，又会缺少运行时 node_modules
7. 7. 因此最终必须同时解决:
• • npm 用户级前缀稳定化
• • 命令入口稳定化
• • 包目录实体化
• • 运行时依赖完整化

12. 可复现操作清单

如果未来在同类 WSL 环境里复现同类问题，可以按以下顺序执行。

12.1 诊断步骤

1
2
3
4
5
6
7
8

node -v
npm -v
npm list -g openclaw --depth=0
which openclaw || true
npm config get prefix
npm prefix -g
npm root -g
echo "$PATH"

12.2 如果已安装但命令找不到，先做短期恢复

1
2

ln -s ~/.local/opt/node-v*/bin/openclaw ~/.local/bin/openclaw
openclaw --version

注意:

• • 这里只是临时恢复
• • 不代表长期路径已经稳定

12.3 做长期修复

1

npm config set prefix ~/.local --location=user

然后确认:

1
2

npm config get prefix
cat ~/.npmrc

12.4 避免错误迁移方式

不要默认使用下面这种方式作为“独立迁移”:

1

npm install -g --prefix ~/.local /path/to/already-installed/openclaw

因为它很可能创建软链接，而不是实体安装。

12.5 若必须离线迁移，检查两件事

• • 安装目录是否为真实目录而非软链接
• • 安装目录下是否存在完整 node_modules

对应检查命令:

1
2

test -L ~/.local/lib/node_modules/openclaw && echo symlink || echo realdir
test -d ~/.local/lib/node_modules/openclaw/node_modules && echo has_node_modules || echo missing_node_modules

13. 重点避坑清单

13.1 PATH 与 npm prefix 必须成对审计

只看“npm list -g 已安装”是不够的，必须同时看:

• • npm config get prefix
• • npm prefix -g
• • echo $PATH
• • which openclaw

13.2 本地目录源安装不等于实体安装

使用本地已安装目录做 npm install -g 时，npm 可能创建软链接式安装。

13.3 missing dist/entry 不一定真的是缺文件

它也可能是:

• • 入口文件存在
• • 但入口的依赖找不到
• • 被上层包装成了统一报错

13.4 WSL 下的 npm cache 权限容易误导排查

如出现 EACCES，优先切临时 cache 再排查，不要立即判断为包损坏。

13.5 长期方案要优先选“稳定用户前缀”

对这类 WSL 用户环境，~/.local 作为 npm 用户级前缀比“绑定到某个 Node 版本目录”更稳。

14. 当前最终状态

截至本记录生成时，当前状态为:

• • npm 用户级前缀: /home/你的路径/.local
• • OpenClaw 命令入口: /home/你的路径/.local/bin/openclaw
• • OpenClaw 包目录: /home/你的路径/.local/lib/node_modules/openclaw
• • CLI 版本: OpenClaw 2026.3.13 (61d171a)
• • 运行状态: openclaw --version 与 openclaw --help 正常

15. 清理说明

排查过程中产生的临时目录均已清理，包括但不限于:

• • /tmp/openclaw-pack-out
• • /tmp/openclaw-extract
• • /tmp/openclaw-pack-test
• • /tmp/openclaw-overwrite
• • /tmp/openclaw-testprefix
• • /tmp/openclaw-npm-cache

因此当前机器上保留的是最终稳定状态，不依赖临时验证目录。

16. 一句话结论

本次故障不是 OpenClaw 本体损坏，而是 npm 全局安装前缀与 WSL shell PATH 错位 引发的命令不可见问题；长期修复通过 将 npm 用户级前缀固定到 ~/.local，并把 OpenClaw 整理为完整、自包含的用户级全局安装 完成。