32blogby StudioMitsu
claude-code11 min read

Claude Codeが動かない時の完全対処法

Claude Codeが起動しない・認証エラー・コマンドが見つからない――よくある失敗パターンを網羅。インストールからWSL・Mac・Windows別の対処法まで全部解説。

claude-codetroubleshootingWSLインストールエラー解決
目次

npm install は成功したのに claude コマンドを打つと「command not found」。僕がClaude Code で新プロジェクトを始めようとした初日、1時間溶かした。

「インストール手順通りにやったのになぜ動かないのか」という状況は、環境依存の問題が積み重なって起きる。この記事では、よくある失敗パターンをすべて洗い出し、原因と解決策をOS別に整理した。セットアップで詰まったときの手順書として使ってほしい。

Claude Code が起動しない時、最初に何をすればいい？

Claude Code が起動できている状態なら、最初にやることは決まっている。

bash
claude doctor

このコマンドを実行すると、以下の項目を自動チェックしてくれる。

  • Node.js のバージョン互換性
  • 認証トークンの有効性
  • ネットワーク接続の状態
  • 設定ファイルの整合性

出力に ✗ が含まれていれば、そこが問題の根本だ。エラーメッセージをそのまま検索するか、後続のセクションで対処法を確認してほしい。

claude 自体が起動しない場合は doctor は使えないので、インストール段階の問題として次のセクションに進む。

Claude Code のインストールで詰まったらどう対処する？

パターン1: npm のグローバルインストール権限エラー

npm warn logfile Error: EACCES: permission denied

これは npm のグローバルディレクトリに書き込み権限がないときに起きる。sudo npm install -g で回避できるが、あとで別の権限問題を引き起こすことがある。正しい対処法は npm のグローバルディレクトリをホームディレクトリに変更することだ。

bash
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

パターン2: Node.js のバージョンが古い

Claude Code は Node.js 18 以上を要求する。バージョンを確認する。

bash
node --version

18 未満なら、nvm で切り替えるのが最も確実だ。

bash
nvm install 20
nvm use 20
nvm alias default 20

パターン3: npm install が途中で止まる

プロキシ環境下や企業ネットワークでよく起きる。--verbose フラグをつけてどこで詰まっているか確認する。

bash
npm install -g @anthropic-ai/claude-code --verbose

タイムアウトが原因なら npm のタイムアウト設定を延ばす。

bash
npm config set fetch-timeout 600000

Claude Code の認証エラー（401 / 403）はなぜ起きる？

インストール後にまず当たる壁が認証エラーだ。

401 Unauthorized: APIキーが無効か、期限切れ。Anthropic Console でキーを確認する。

403 Forbidden: プランの制限か、APIキーの権限不足。Claude Code は特定のプランでのみ使えるため、サブスクリプション状態を確認する必要がある。

認証を設定し直す手順は以下の通り。

bash
# 既存の認証情報を削除
claude logout

# 再認証
claude login

ブラウザが開かない環境（ヘッドレスサーバーなど）では API キーを直接環境変数に設定する。

bash
export ANTHROPIC_API_KEY="sk-ant-..."

.bashrc や .zshrc に追記して永続化する。

bash
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc

認証後も 403 が続く場合は、同じアカウントで別のデバイスから Claude Code が使えるか試す。アカウント側の問題なら Anthropic のサポートに問い合わせるしかない。

WSL で Claude Code が動かない原因は何？

Windows で WSL（Windows Subsystem for Linux）を使っている場合、独自の問題がある。

Windows 側の npm と混在する

WSL の中で which npm を実行したとき、/mnt/c/... のようなパスが返ってきたら Windows 側の npm が呼ばれている。WSL 内に Node.js をインストールし直す必要がある。

bash
# WSL 内で nvm をインストール
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20

ブラウザ認証が開かない

claude login を実行するとブラウザが開くが、WSL 環境ではデフォルトブラウザが起動しないことがある。この場合は API キーを直接環境変数に設定する方法（前のセクション参照）が確実だ。

ファイルパスの問題

WSL 内から Windows 側のファイルを操作するときは /mnt/c/... 形式のパスを使う。ただし、Claude Code の作業ディレクトリは WSL 内（~/ 以下）に置くことを推奨する。Windows 側のファイルシステムをマウントして使うとパフォーマンスと互換性の問題が起きやすい。

WSL から Windows ネイティブに切り替えると解決するケースは？

WSL でどうしても解決しない場合、Windows ネイティブ環境への移行を検討する。Claude Code は Windows ネイティブでも動作する。

powershell
# PowerShell で実行
npm install -g @anthropic-ai/claude-code

ただし、Windows ネイティブ版にも注意点がある。

  • パスの区切り文字が \ になるため、シェルスクリプトが動かない場合がある
  • Git for Windows が必要
  • 一部の Unix コマンドが使えない

実際の開発作業では WSL の方が環境が整いやすい。WSL 固有の問題は上のセクションで解決し、それでも詰まるなら Windows ネイティブを試すという順番がよい。

「claude: command not found」はどう直す？

インストール自体は成功しているのに command not found になるのは、インストール先のディレクトリが PATH に含まれていないことが原因だ。

まずインストール先を確認する。

bash
npm root -g

このパスの一つ上のディレクトリの bin/ フォルダに claude が存在するはずだ。

bash
# 例: /usr/local/lib/node_modules なら /usr/local/bin に claude がある
ls /usr/local/bin/claude

ファイルが存在するなら、そのディレクトリを PATH に追加する。

bash
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

npm の prefix 設定をカスタマイズしている場合は、その bin ディレクトリを追加する。

bash
npm config get prefix
# 例: /home/username/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

設定後に新しいシェルセッションを開くか source ~/.bashrc を実行する。これで解決するケースがほとんどだ。

それでも解決しない時はどう調査・報告すればいい？

ここまでの手順で解決しない場合は、ログを取得して状況を整理する。

デバッグログの取得

bash
# 詳細ログを有効にして実行
claude --debug 2>&1 | tee claude-debug.log

環境情報の取得

bash
node --version
npm --version
claude --version  # 起動できる場合
uname -a         # OS情報
echo $SHELL
echo $PATH

GitHub Issues への報告

Claude Code のバグは公式リポジトリで管理されている。

  1. github.com/anthropics/claude-code/issues で既存の Issue を検索
  2. 同じ問題がなければ新規 Issue を作成
  3. OS・Node.js バージョン・エラーメッセージ・デバッグログを含める

コミュニティフォーラムより GitHub Issues の方が開発チームの目に触れやすい。再現手順が明確であれば対応が早い。

まとめ

Claude Code のトラブルは、ほぼ以下の3カテゴリに収まる。

  1. インストール問題: Node.js バージョン・npm 権限・PATH 設定
  2. 認証問題: APIキーの有効性・プランの確認・環境変数の設定
  3. 環境固有の問題: WSL と Windows の混在・パスの解決

claude doctor を最初に実行する習慣をつけるだけで、問題の切り分けが格段に速くなる。それでも詰まったときは、エラーメッセージをそのまま GitHub Issues で検索すると先人の解決策が見つかることが多い。

セットアップが完了したら、次は CLAUDE.md を整備してプロジェクト固有の指示を Claude Code に伝える段階に進もう。