macOSでのOpenClawアップグレード時のnpmインストール失敗 - npm Install Failure During OpenClaw Upgrade on macOS

OpenClaw インストーラーは、npm グローバルインストールフェーズ中にサイレントエラーを報告します。インストールスクリプトは環境検出を正常に完了しますが、パッケージのインストールに失敗し、基礎となるエラーを表示しません。

確認された動作：

  🦞 OpenClaw Installer
  The only crab in your contacts you actually want to hear from. 🦞

✓ Detected: macos

Install plan
OS: macos
Install method: npm
Requested version: latest

[1/3] Preparing environment
✓ Homebrew already installed
✓ Node.js v22.22.0 found
· Active Node.js: v22.22.0 (/usr/local/bin/node)
· Active npm: 10.9.4 (/usr/local/bin/npm)

[2/3] Installing OpenClaw
✓ Git already installed
· Installing OpenClaw v2026.2.26
! npm install failed for openclaw@latest
  Command: env SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm --loglevel error --silent --no-fund --no-audit install -g openclaw@latest
  Installer log: /var/folders/mm/rhtrkglj0cn_h1xhmkp21w540000gn/T/tmp.kWd5ANRq99
! npm install failed; showing last log lines
! npm install failed; retrying

主な兆候：

• 環境検出は成功する（Node.js、npm、Git がすべて検出される）
• インストールコマンドは実行されるが、ゼロ以外の終了コードを返す
• ログファイルは存在するが、インストーラーが出力を切り詰める
• 後続の再試行も失敗する

インストール失敗後の二次的な症状：

# Verify installation state
$ openclaw --version
zsh: command not found: openclaw

# Check npm global packages
$ npm list -g --depth=0 | grep openclaw
# (empty output - package not installed)

インストールの失敗は、既存の clawbot インストールと新しい openclaw パッケージの間の衝突から発生しています。npm グローバルインストールは、以下の原因の1つ以上により失敗します：

1. 古いキャッシュと競合するメタデータ

clawbot から openclaw へのアップグレード時に、npm は以前のパッケージの破損または古いキャッシュエントリを保持したままにする可能性があります。clawbot の npm レジストリメタデータが新しいパッケージ解決と競合し、サイレントな解決失敗が発生します。

技術的なシーケンス：

# Internal npm behavior during upgrade
npm install -g openclaw@latest
  → Check registry for "openclaw"
  → npm cache contains stale "clawbot" metadata
  → Version resolution returns incorrect package or 404
  → Exit code: 1 (silently truncated by --silent flag)

2. macOS でのパーミッションと所有権の競合

npm グローバル接頭辞 /usr/local/lib/node_modules は、昇格された書き込みパーミッションが必要です。システム整合性保護（SIP）が有効な macOS で、Homebrew 管理的 Node インストールと組み合わせると、所有権の競合が頻繁に発生します。

問題のある設定：

# Typical macOS permission issue
$ ls -la /usr/local/lib/node_modules
drwxr-xr-x  root            admin  # Owned by root
drwxr-xr-x  user           staff  # Previous installation owned by user

# npm install cannot write to root-owned directories

3. Node.js バージョン管理ツールの競合

ユーザーには /usr/local/bin/node がアクティブになっていますが、これは典型的な Node バージョン管理ツールのパス外にあります。nvm、fnm、または volta がインストールされている場合、複数の Node.js バイナリが存在し、npm が不正確または古いインストールを参照する可能性があります。

4. ネイティブモジュールのコンパイル失敗（libvips/sharp）

インストーラーは SHARP_IGNORE_GLOBAL_LIBVIPS=1 を使用して libvips をスキップしますが、以前の clawbot インストールがコンパイルされた sharp モジュールアーティファクトを残している場合、npm のリビルドプロセスが互換性のないネイティブコードの再コンパイルを試みる可能性があります。

フェーズ 1: npm キャッシュのクリーンと以前のインストールの削除

# Step 1: Clear npm cache completely
npm cache clean --force

# Step 2: Remove previous clawbot installation
npm uninstall -g clawbot

# Step 3: Verify removal
npm list -g --depth=0 | grep -E "(clawbot|openclaw)" || echo "No previous installations found"

フェーズ 2: npm グローバル接頭辞のパーミッションを修正

# Step 4: Create npm global directory with correct permissions
mkdir -p ~/.npm-global

# Step 5: Configure npm to use local prefix
npm config set prefix '~/.npm-global'

# Step 6: Add to PATH (add to ~/.zshrc for persistent effect)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
export PATH=~/.npm-global/bin:$PATH

# Step 7: Verify npm prefix configuration
npm config get prefix
# Expected output: /Users/[username]/.npm-global

フェーズ 3: OpenClaw の再インストール

# Step 8: Install OpenClaw with verbose logging for debugging
npm install -g openclaw@latest --loglevel verbose

# Alternative: If specific version required
npm install -g [email protected] --loglevel verbose

フェーズ 4: 代替方法（Homebrew Node）

パーミッションの問題が解消されない場合は、パーミッションを自動的に処理する Homebrew の Node.js を使用してください：

# Step 9: Install Node.js via Homebrew (if not already)
brew install node

# Step 10: Reinstall OpenClaw with Homebrew-managed Node
npm install -g openclaw@latest

# Step 11: Verify installation path
which openclaw
# Expected: /opt/homebrew/bin/openclaw (M1/M2) or /usr/local/bin/openclaw (Intel)

設定のビフォー・アフター

ビフォー（問題あり）：

# ~/.npmrc or global npm config
prefix=/usr/local  # Root-owned, requires sudo
cache=/var/root/.npm  # Inaccessible

# Environment
NODE_PATH=/usr/local/lib/node_modules
PATH=/usr/local/bin:$PATH

アフォー（正しい）：

# ~/.npmrc or global npm config
prefix=/Users/[username]/.npm-global
cache=/Users/[username]/.npm
node_options=--max-old-space-size=4096

# Environment (in ~/.zshrc)
export PATH=~/.npm-global/bin:$PATH
export NPM_CONFIG_PREFIX=~/.npm-global

修正を適用した後、以下のコマンドを使用してインストールを確認します：

基本的な検証

# Test 1: Check OpenClaw binary is accessible
$ openclaw --version
v2026.2.26

# Test 2: Verify npm global package status
$ npm list -g --depth=0 | grep openclaw
├── [email protected]

# Test 3: Confirm installation location
$ npm list -g --depth=0 --parseable | grep openclaw
/Users/[username]/.npm-global/lib/node_modules/openclaw

# Test 4: Test OpenClaw initialization
$ openclaw init
# Should display setup wizard without errors

詳細な検証

# Test 5: Verify all dependencies are intact
$ openclaw doctor
✓ Node.js version: v22.22.0
✓ npm version: 10.9.4
✓ OpenClaw installation: valid
✓ Configuration directory: accessible
✓ Plugin directory: accessible

# Test 6: Check for conflicting installations
$ which -a openclaw
/Users/[username]/.npm-global/bin/openclaw
# Should show only one path

期待される正常な出力：

✓ OpenClaw v2026.2.26 installed successfully
✓ Binary location: /Users/[username]/.npm-global/bin/openclaw
✓ All dependencies resolved
✓ Installation complete

終了コードの検証：

# Verify clean exit code
$ echo $?
0

1. 複数の Node.js インストール（M シリーズ Mac）

問題： Apple Silicon Mac には、Homebrew (/opt/homebrew)、nvm (~/.nvm)、直接ダウンロード (/usr/local) 経由で Node.js がインストールされている場合があります。ユーザーが /usr/local/bin/node をアクティブにしていますが、これは典型的な Node バージョン管理ツールのパス外にあるため、複数の Node.js バイナリが存在し、npm が古かったり異なるインストールを参照する原因となる可能性があります。

検出方法：

# Check for multiple Node installations
$ which -a node
/opt/homebrew/bin/node
/usr/local/bin/node

# Check actual symlink targets
$ ls -la /usr/local/bin/node
/usr/local/bin/node -> ../Cellar/node/.../bin/node  # Homebrew Intel
$ ls -la /opt/homebrew/bin/node
/opt/homebrew/bin/node -> ../opt/node/bin/node  # Homebrew ARM

解決策： Node.js のインストールを1つに統合します。重複するパスを ~/.zshrc から削除します。

2. macOS での SIP 保護ディレクトリ

問題： /usr/local はシステム整合性保護の下で部分的に保護されている可能性があり、断続的なパーミッション失敗を引き起こします。

検出方法：

$ ls -la /usr/local/lib/node_modules
ls: cannot access '/usr/local/lib/node_modules': Operation not permitted

解決策： ~/.npm-global 接頭辞を排他的に使用します。sudo npm install -g は使用しないでください。所有権の競合が発生します。

3. 古い npm レジストリキャッシュ

問題： 以前clawbot インストールからの破損したキャッシュエントリが、キャッシュクリーンにもかかわらず残っています。

検出方法：

# Check cache integrity
$ npm cache verify
npm warn Failed to clean up old cache
npm error Unexpected end of JSON input while parsing near '...": "1.0.0", "dependencies": {'

解決策：

# Force complete cache deletion
rm -rf ~/.npm
npm cache clean --force --cache ~/.npm

4. Intel と ARM のアーキテクチャの不一致

問題： Intel アーキテクチャ用にコンパイルされたパッケージを Apple Silicon に（またはその逆で）インストールします。

検出方法：

$ file $(which openclaw)
# Intel: Mach-O 64-bit executable x86_64
# ARM:   Mach-O 64-bit executable arm64

解決策： npm が正しいアーキテクチャのネイティブバイナリをダウンロードしていることを確認します。必要に応じて npm rebuild を使用します。

5. .npmrc 設定の競合

問題： プロジェクトレベルまたはグローバルの .npmrc ファイルが予期される動作をオーバーライドします。

検出方法：

# Check all .npmrc files
$ cat ~/.npmrc
prefix=~/.npm-global
$ cat ./.npmrc  # in current directory
prefix=/usr/local  # Conflicts!

解決策： 競合する .npmrc エントリを削除または修正します。~/.npmrc をプロジェクトレベルの設定より優先します。