openclaw - 💡(How to fix) Fix Bug: openclaw command not found after npm global install

Problem Description

After running npm install -g openclaw, the openclaw command is not found in the shell. Users get a "command not found" error and must manually configure their PATH.

Root Cause

When npm's global prefix is set to a user-level directory (e.g., ~/.npm-global), the global bin directory (~/.npm-global/bin) is not in the user's default PATH. This happens commonly when users follow npm's recommended setup to avoid sudo for global installs.

On a fresh macOS setup:

• npm config get prefix → /Users/<user>/.npm-global
• Binary installs to ~/.npm-global/bin/openclaw
• ~/.npm-global/bin is not in the default PATH

Environment

• OS: macOS (Darwin arm64)
• Shell: zsh
• npm global prefix: ~/.npm-global (user-level, no sudo)
• OpenClaw version: latest (npm)
• Node.js: v24.x

Steps to Reproduce

1. Configure npm to use a user-level global prefix (one-time setup):

   mkdir ~/.npm-global
   npm config set prefix '~/.npm-global'

2. Install OpenClaw globally:

   npm install -g openclaw

3. Run openclaw
4. Get zsh: command not found: openclaw

Current Workaround

Manually add the npm global bin directory to PATH in shell config:

# ~/.zshrc
export PATH="$HOME/.npm-global/bin:$PATH"

Then restart the shell or run source ~/.zshrc.

Expected Behavior

The install process should handle this gracefully. Ideally one of:

1. postinstall script that detects if the npm global bin directory is in PATH and prints clear instructions if not
2. Documentation with explicit post-install PATH setup steps for user-level npm prefixes
3. Alternative install method (e.g., curl | sh wrapper that handles PATH setup)

Proposed Solutions

1. Add a postinstall script in package.json that:

   • Detects the npm global bin path via process.env.npm_config_prefix
   • Checks if it's in the user's PATH
   • Prints a clear, actionable message with the exact export PATH=... command needed

2. Update the Getting Started docs to include a "Verify PATH" step after npm install, with instructions for common shells (bash, zsh, fish)

3. Enhance install.sh to detect and offer to configure PATH automatically (write to .zshrc/.bashrc with user confirmation)

Additional Context

This is a common pain point for npm global installs in general, but CLI tools with immediate user interaction (like OpenClaw) should handle it more gracefully than most. Users who are new to Node/npm will be especially confused by this.

Related issues:

• #73814 - Installer hangs with truncated warn_shell_path_missing_di function (install.sh PATH detection)
• #79048 - Impossible to install on mac (different root cause but similar user frustration)
• #80387 - Command disappears after brew upgrade (related PATH/node_modules resolution)