Fix OpenClaw npm install failed on macOS

Diagnose before fixing

The npm error output contains the specific failure reason, but users often dismiss the terminal before reading it carefully. Open a new terminal and scroll up to find the error, or run the install command again with --loglevel verbose to capture detailed output. The first line of the error usually names the failing package, and the last line before the stack trace identifies the root cause category.

Common error patterns on macOS: EACCES errors mean npm tried to write to a directory it does not have permission for. EINTEGRITY errors indicate the downloaded package checksum did not match the registry record, suggesting a corrupted cache. ENOENT errors usually mean a transitive dependency was removed from the registry or is unreachable.

Save the full error output to a text file before attempting any fixes: npm install 2>&1 | tee npm-error.log. This preserves the full diagnostic information even if subsequent commands change the terminal state.

• Copy the full npm error output before closing the terminal
• Note the npm exit code (usually ENOENT, EACCES, or EINTEGRITY)
• Identify which package failed and the exact version npm tried to download

Fix Node.js version mismatches

OpenClaw pins its runtime to specific Node.js versions that have been tested for API compatibility and security patches. Using an older Node.js version such as 16 or 14 causes install failures because some packages in the dependency tree have dropped support for older runtimes. Using a newer unstable version such as 21 or 22 may cause behavioral differences in native module compilation.

If you use nvm, list all installed versions with nvm ls and switch to 18 or 20 with nvm use. If nvm is not installed, install it with curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash and then install the correct Node.js version.

After switching Node.js versions, clear the npm cache and retry installation. Run npm cache clean --force to remove all cached packages, then run npm install again. This ensures the new Node.js version downloads fresh packages rather than reusing any x64/arm64 binaries compiled for the previous version.

• Check the currently active Node.js version with node -v
• OpenClaw requires Node.js 18 LTS or Node.js 20 LTS
• Use nvm to switch to a compatible version: nvm use 18
• Verify the version is set for new shells: nvm alias default 18

Fix permission errors

EACCES errors on macOS occur because npm attempts to write global packages to /usr/local/lib, which is protected even for administrator accounts on recent macOS versions. The recommended fix is not to use sudo but to configure npm to use a user-owned directory for global packages.

Create a directory for global npm packages in your home folder: mkdir -p ~/npm-global. Then configure npm to use this directory: npm config set prefix ~/npm-global. Add ~/npm-global/bin to your PATH in ~/.zshrc or ~/.bash_profile: export PATH=~/npm-global/bin:$PATH. After sourcing your profile, npm install -g packages will work without sudo.

OpenClaw does not require global npm installations for its core runtime. The CLI tool can be installed globally via the official macOS installer or via Homebrew without needing npm install -g. Only use npm install for skill development, not for the main installation.

• Never run npm install with sudo unless you fully understand the implications
• Fix npm ownership: sudo chown -R $(whoami) ~/.npm
• Set npm prefix to a user-writable directory
• Use npm config set prefix ~/npm-global for local installs

Fix cache corruption (EINTEGRITY errors)

npm uses SHA512 checksums to verify package integrity. If the downloaded package bytes do not match the checksum recorded in the registry, npm rejects the package with an EINTEGRITY error. This usually happens because a cached package file on your machine was corrupted by a failed write or disk error, not because the registry is serving bad files.

Clear the cache completely: npm cache clean --force. Then delete both node_modules and package-lock.json from the project directory if they exist. Run npm install fresh to download all packages from the registry without any stale cache entries interfering.

If EINTEGRITY errors persist after clearing the cache, your machine may be behind a network proxy that compresses or modifies HTTP responses. npm logins and package downloads over HTTPS should not be affected by most transparent proxies, but corporate firewalls that perform TLS interception will cause checksum mismatches. In this case, configure npm to bypass the proxy or use the official installer.

• Run npm cache clean --force to purge the entire cache
• Delete node_modules and package-lock.json before retrying
• Check for network interception issues if errors persist after cache clean

Retry in a clean environment

After fixing the underlying issue, test in a clean directory to confirm the fix is complete. Create a temporary directory, copy only the package.json file, and run npm install there. If the install succeeds without errors, the original project directory may have leftover corrupted state that should be deleted and recreated.

Do not copy node_modules between machines or from backup. npm dependencies are platform-specific and may contain native binaries compiled for a different architecture or Node.js version. Always run npm install after copying package.json to ensure the dependencies are correct for the current environment.

• Create a new project directory and copy only package.json
• Run npm install without any additional flags first
• If it succeeds, compare the original node_modules with the clean one
• Use npx @clawmesh/skillsdoctor to validate the installation

When to switch to a different installation path

The npm install path is suited for skill development workflows where you need to modify or debug skill scripts directly. For production use cases where the goal is to run agents reliably without managing a Node.js environment, use the official macOS installer or the Docker Compose deployment. Both bypass npm entirely and deliver a tested, pre-built runtime.

• If npm install fails more than twice after following all steps
• If the failure involves native module compilation (node-gyp errors)
• If you need a faster path to running OpenClaw for production use