Claude Code 完全トラブルシュート：アップデート／再インストール／認証エラーを“確実”解決

本記事は、Claude Code の アップデート失敗、認証エラー（401／OAuth期限切れ）、再インストールが必要な破損 を、最短・確実に復旧するための決定版ガイドです。Volta/n/NVM 等の Node 管理ツールの罠、PATH/権限問題、プロセス競合までを体系化し、安全側の順序で手順を提示します（macOSを主対象、WSL/Linux/CIの注意も補足）。

ゴール
まずは状況確認（診断のショートカット）
Step 1. 安全なアップデート手順
Step 2. 認証（401／期限切れ）を直す
Step 3. “更新中のまま”等のプロセス競合を解消
Step 4. 完全再インストール（壊れた時の最後の手段）
権限エラーを避けるコツ
環境別の落とし穴（macOS / WSL / CI）
端末の推奨設定（体験向上）
クイック診断フロー（最短ルート）
再発防止チェックリスト
参考

ゴール

現在の状態を正しく把握する（バージョン・PATH・プロセス）。
更新 → 認証 → プロセス整理 → 再インストールまでを段階的に解決。
次回以降の再発を防ぐ恒久対策（環境設計／権限／PATH）を適用。
想定所要：5〜20分（環境依存）。

まずは状況確認（診断のショートカット）

/status
claude --version
which claude
node -v
npm -v

症状／メッセージ	意味	対応先
A newer version (1.0.24 or higher) is required	バージョンが古い	アップデート
OAuth token has expired / API Error: 401	認証切れ／資格情報不正	認証リセット
Command not found: claude	未インストール／破損／PATH不整合	完全再インストール
Insufficient permissions to install update	権限不足	権限回避
Another instance is currently performing an update	プロセス競合／更新ロック	プロセス整理

Step 1. 安全なアップデート手順

標準アップデート

claude update
# 権限エラー時のみ
sudo claude update

失敗時は npm で上書き更新（推奨）

sudo npm install -g @anthropic-ai/claude-code@latest
# 可能なら権限なしで先に試す
npm update -g @anthropic-ai/claude-code

Volta / n / NVM 使用時の“反映されない”問題

which claude
# 例) /Users/<name>/.volta/bin/claude 等

# Claude Code 内でローカルインストーラへ移行
/migrate-installer

# zsh の PATH に追加
echo 'export PATH="$HOME/.claude/local:$PATH"' >> ~/.zshrc
source ~/.zshrc

Node 管理ツールの shims が先に解決されると、新版が拾われないことがあります。/migrate-installer と PATH 追加で解消します。

Step 2. 認証（401／期限切れ）を直す

状態確認
```
/status
```
再認証
```
/auth
# または
/login
```

完全ログアウト → 再起動 → 再認証

/logout
# Ctrl + C で終了 → 再度 `claude`

最終手段：設定リセット
```
/reset
```

Step 3. “更新中のまま”等のプロセス競合を解消

ps aux | grep claude
killall claude || pkill -f claude

残骸プロセスやロックが原因のケースを速やかに解消します。

Step 4. 完全再インストール（壊れた時の最後の手段）

npm uninstall -g @anthropic-ai/claude-code
npm cache clean --force
npm install -g @anthropic-ai/claude-code@latest

権限エラーを避けるコツ

グローバル npm 権限で詰まるなら、まずは /migrate-installer で ~/.claude/local 配下へ移行。
どうしても必要なときのみ sudo。頻発するなら Node/npm の権限設計を見直す（n/NVM/Volta の多層干渉回避）。
npm グローバルをユーザー領域へ：npm config set prefix "$HOME/.npm-global"（必要に応じて PATH 追加）。

環境別の落とし穴（macOS / WSL / CI）

macOS：sips や security コマンド絡みの権限で失敗することあり。再起動で直るケースあり。
WSL：ブラウザ認証がホスト（Windows）で開く場合あり。CLI の URL を Windows 側で開く。
CI：旧バージョンキャッシュが残りやすい。npm cache clean --force を明示、依存キャッシュキーをバージョンにバインド。

端末の推奨設定（体験向上）

/terminal-setup

Option+Enter の改行、Visual bell などが有効になります。

クイック診断フロー（最短ルート）

起動しない／古い：claude --version → 古いならアップデート
401／期限切れ：認証リセット
更新が終わらない：プロセス整理
直らない：完全再インストール

再発防止チェックリスト

Node 管理レイヤは 1つに統一（Volta / n / NVM を併用しない）。
PATH 解決順を固定（~/.claude/local が先頭に来るよう ~/.zshrc を調整）。
npm グローバル権限はユーザー領域へ（sudo 依存をやめる）。
CI はキャッシュキーにバージョンを含め、毎回の実体バージョンをログ出力。

参考

関連書籍：AmazonでClaude Code関連を探す