# OpenClaw acpx 插件启动失败问题排查

**日期：** 2026-03-02  

**问题：** OpenClaw Gateway 启动时报错 `acpx runtime setup failed: npm is required to install plugin-local acpx but was not found on PATH`

## 问题现象

```

02:19:43 [plugins] acpx runtime backend registered (command: C:\Users\fly\AppData\Roaming\npm\node_modules\openclaw\extensions\acpx\node_modules\.bin\acpx.cmd, pinned: 0.1.13)

02:19:43 [plugins] acpx local binary unavailable or mismatched (ϵͳ�Ҳ���ָ����·����); running plugin-local install

02:19:43 [plugins] acpx runtime setup failed: npm is required to install plugin-local acpx but was not found on PATH

```

## 排查过程

### 第一步：检查 PATH 环境变量

Gateway 进程启动时找不到 `npm` 命令。检查发现：

- `gateway.cmd` 中硬编码的 PATH 没有包含 `C:\Program Files\nodejs`

- 系统 PATH 本身是有 Node.js 的，但 Gateway 使用的是 `gateway.cmd` 中设置的 PATH

### 第二步：修改 gateway.cmd

修改 `C:\Users\fly\.openclaw\gateway.cmd`，将 PATH 改为：

```batch

set PATH=C:\Program Files\nodejs;C:\Users\fly\AppData\Roaming\npm;%PATH%

```

### 第三步：发现问题未解决

尽管 PATH 已修复，错误依然存在。进一步排查发现：

- Gateway 进程重启后 PATH 确实包含了 Node.js 路径

- 但 OpenClaw 仍在尝试进行 "plugin-local install"

### 第四步：定位根本原因

OpenClaw 插件系统需要：

```

C:\Users\fly\AppData\Roaming\npm\node_modules\openclaw\extensions\acpx\node_modules\.bin\acpx.cmd

```

但这个目录不存在。实际 acpx 已全局安装：

- `C:\Users\fly\AppData\Roaming\npm\acpx.ps1` (shim)

- `C:\Users\fly\AppData\Roaming\npm\node_modules\acpx` (实际模块)

## 解决方案

在插件目录手动安装 acpx：

```powershell

cd "C:\Users\fly\AppData\Roaming\npm\node_modules\openclaw\extensions\acpx"

npm install acpx@0.1.13

```

这会在 `extensions\acpx\node_modules\.bin\` 下创建 `acpx.cmd`，解决 plugin-local 找不到本地二进制的问题。

## 经验总结

1. **gateway.cmd 的 PATH 配置**：如果 Gateway 启动脚本中硬编码了 PATH，需要确保包含 Node.js 路径

2. **plugin-local 安装机制**：OpenClaw 某些插件需要在自己的目录下的 node_modules 安装本地副本

3. **全局 vs 本地安装**：全局安装的 npm 包不能替代 plugin-local 安装

## 相关文件

- `C:\Users\fly\.openclaw\gateway.cmd` - Gateway 启动脚本

- `C:\Users\fly\.openclaw\openclaw.json` - OpenClaw 配置文件

- `C:\Users\fly\AppData\Roaming\npm\node_modules\acpx` - 全局 acpx 模块

- `C:\Users\fly\AppData\Roaming\npm\node_modules\openclaw\extensions\acpx` - OpenClaw acpx 插件