Problem Description
When globally installing OpenClaw with pnpm, warnings or errors appear during installation indicating that postinstall scripts were not executed:
$ pnpm add -g openclaw
WARN Lifecycle script `postinstall` of package `[email protected]` was blocked by pnpm.
WARN Lifecycle script `postinstall` of package `[email protected]` was blocked by pnpm.
WARN To allow scripts from packages, run:
WARN pnpm approve-builds -g
The installation appears to complete, but running openclaw start produces errors:
Error: Cannot find module '../build/Release/sharp-linux-x64.node'
Or:
Error: Could not locate the bindings file. Tried:
→ /path/to/better-sqlite3/build/better_sqlite3.node
This is because starting from v9, pnpm blocks lifecycle scripts (such as postinstall) by default to improve security. Some packages (like sharp and better-sqlite3) need to download precompiled native binaries or perform local compilation during the postinstall phase. When scripts are blocked, these packages can't function properly.
Root Cause
pnpm's security policy is designed to prevent malicious packages from executing dangerous scripts during installation. However, some legitimate packages that OpenClaw depends on genuinely need to run postinstall scripts:
- sharp: Downloads platform-specific precompiled libvips binaries during postinstall
- better-sqlite3: Compiles or downloads native SQLite bindings during postinstall
- @napi-rs packages: Download Rust-compiled native modules during postinstall
If these scripts don't execute, the corresponding native modules won't be installed correctly, resulting in "binary not found" errors at runtime.
Solutions
Option 1: Use pnpm approve-builds (Recommended)
pnpm provides the approve-builds command to explicitly approve build scripts for specific packages. For global installations:
pnpm approve-builds -g
After running this, pnpm will list all blocked packages and their script contents, letting you confirm each one:
? Allow build scripts for the following packages?
[email protected] (postinstall: node install/sharp)
[email protected] (postinstall: prebuild-install -r napi || node-gyp rebuild)
✔ [email protected]
✔ [email protected]
After selecting the packages to approve, pnpm will re-execute their postinstall scripts.
Reinstall OpenClaw after approving to ensure all native modules are built correctly:
pnpm add -g openclaw
Option 2: Allow Script Execution During Installation
If you trust OpenClaw and its dependencies, you can use the --unsafe-perm flag to allow script execution during installation:
pnpm add -g openclaw --unsafe-perm
Or configure pnpm to globally allow build scripts from specific packages:
pnpm config set approve-builds-automatically true -g
Note: approve-builds-automatically will automatically approve all packages' build scripts, which reduces security. Only use this if you trust all installed packages.
Option 3: Use .pnpmfile.cjs Configuration
Create a global pnpm configuration to pre-approve build scripts for OpenClaw-related packages.
First, find pnpm's global config directory:
pnpm config get global-dir
Create or edit .pnpmfile.cjs in that directory:
module.exports = {
hooks: {
readPackage(pkg) {
// Allow these packages to run build scripts
const allowedPackages = ['sharp', 'better-sqlite3', '@napi-rs'];
if (allowedPackages.some(name => pkg.name.includes(name))) {
pkg.allowBuild = true;
}
return pkg;
}
}
};
Option 4: Switch to npm for Installation
If pnpm's build script management is causing ongoing trouble, consider using npm for global installation. npm allows postinstall scripts to execute by default:
npm install -g openclaw
You can still use pnpm for your projects — only the OpenClaw global tool is installed via npm. The two don't conflict.
Option 5: Manually Trigger the Build
If OpenClaw is already installed but native modules weren't built, you can manually trigger a rebuild:
pnpm rebuild -g
This re-executes all build scripts for global packages. If some packages are still blocked, run pnpm approve-builds -g before rebuilding.
You can also rebuild specific packages:
pnpm rebuild -g sharp
pnpm rebuild -g better-sqlite3
Verifying the Fix
Confirm that native modules are correctly built:
# Verify sharp
node -e "require('sharp')" && echo "sharp OK" || echo "sharp FAILED"
# Verify better-sqlite3
node -e "require('better-sqlite3')" && echo "sqlite OK" || echo "sqlite FAILED"
Run OpenClaw's environment check:
openclaw doctor
If all checks pass, start the service:
openclaw start
Prevention Tips
To avoid the same issue when updating OpenClaw in the future, it's recommended to persist the approval records after the first resolution. pnpm stores the list of approved packages in its global configuration, and subsequent installs or updates will automatically allow approved packages to run their build scripts.
View the current approved builds list:
pnpm audit --fix -g
pnpm approve-builds -g --list
Regularly update pnpm to the latest version, as newer versions may improve build script management:
pnpm self-update