32blogby Studio Mitsu

Claude Codeが動かない時の完全トラブルシューティング

Claude Codeのエラーを即解決。401/403認証エラー、npmインストール失敗、WSL設定、PATH問題、パフォーマンス低下まで、OS別の対処法を全パターン網羅。

by omitsu20 min read
Claude CodetroubleshootingWSLinstallationerror-fix
目次

Claude Codeのトラブルは大きく3つに分類できる。インストール問題、認証エラー、環境固有の競合だ。まず claude doctor を実行すれば、大半の原因は数秒で特定できる。Claude Code自体が起動しない場合は、下のインストールセクションから読み進めてほしい。

Claude Codeをインストールしたのに claude コマンドが「command not found」——これはRedditでも定番のトラブルだ。認証エラー、WSLのパス競合、コンテキストウィンドウの問題まで、よくあるトラブルと解決策をまとめた。

Claude Codeが起動しない時、最初にやるべきことは？

個別の修正に入る前に、Claude Code自身に問題を診断させよう。

bash
claude doctor

このコマンドは以下を自動でチェックしてくれる。

  • Node.jsのバージョン互換性
  • 認証トークンの有効性
  • ネットワーク接続
  • 設定ファイルの整合性（JSONバリデーション）
  • MCPサーバーの設定エラー

出力に ✗ が含まれていたら、そこが根本原因だ。エラーメッセージをそのままコピーして検索すれば、大抵は先人が解決策を残している。

claude 自体が起動しない場合は doctor が使えないので、次のインストールセクションに進もう。

もうひとつ、早めに確認しておくべきなのが Anthropicのステータスページ。API側の障害なら、ローカルでいくらデバッグしても解決しない。

Claude Codeのインストールで詰まった時の対処法

ネイティブインストーラーを使う（推奨）

npmの問題と戦う前に、ネイティブインストーラーへの切り替えを検討しよう。2025年後半からAnthropicが推奨している方法で、依存関係ゼロ（Node.jsもnpmも不要）の単体実行ファイルとして動作し、バックグラウンドで自動更新される。

bash
# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash
powershell
# Windows（PowerShell）
irm https://claude.ai/install.ps1 | iex

インストール後は claude --version で確認。既存のnpmインストールから移行する場合は、先にnpm版をアンインストールして競合を防ぐ。

bash
npm uninstall -g @anthropic-ai/claude-code
curl -fsSL https://claude.ai/install.sh | bash

ネイティブインストーラーを使えば、以下で説明するnpm関連の問題はほぼ発生しない。CIパイプラインやcurlが制限された企業環境など、npm方式が必要な場合は読み進めてほしい。

パターン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をインストールまたは更新（2026年3月時点でv0.40.4）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
nvm alias default 22

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

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

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

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

bash
npm config set fetch-timeout 600000

パターン4: 企業プロキシ・ファイアウォールによるブロック

企業プロキシの裏側にいると、npmもClaude Codeも外部サーバーに到達できないことがある。npmのプロキシ設定と、カスタムCA証明書がある場合はNode.jsに認識させる必要がある。

bash
# npmのプロキシ設定
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# カスタムCA証明書がある場合
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.crt

NODE_EXTRA_CA_CERTS は .bashrc に追記して永続化しておこう。

パターン5: 複数インストールの競合

グローバル・ローカル・異なるNodeバージョンでClaude Codeを複数回インストールしていると、バージョン競合で不思議な挙動が起きることがある。

bash
# 複数インストールの確認
which -a claude
npm ls -g @anthropic-ai/claude-code

# クリーンインストール
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

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

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

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

403 Forbidden: プランにClaude Codeのアクセス権が含まれていないか、APIキーの権限が不足している。

Claude Codeが使えるプランは以下の通り。

  • Pro（$20/月）— Claude Code利用可
  • Max 5x（$100/月）— フルアクセス
  • Max 20x（$200/月）— フルアクセス
  • Team Premium（$150/人/月）— Claude Code利用可
  • APIキー — Anthropic Console から従量課金で利用

認証のリセット手順はこちら。

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

# 再認証
claude auth login

ブラウザが自動で開かない場合（リモートサーバーやヘッドレス環境）、c キーを押すとOAuth URLがクリップボードにコピーされる。ブラウザに貼り付けて認証を完了させよう。

環境変数で直接APIキーを設定する方法もある。

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

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

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

再認証後も403が続く場合は claude auth status で認証状態を確認しよう。自分側に問題がなければ Anthropicサポート に問い合わせる。

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

WSL（Windows Subsystem for Linux）には固有の問題がある。WSL2上でClaude Codeを使う場合、以下のトラブルはGitHub Issuesでも頻出している。

Windows側のnpmが混入する

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

bash
# WSL内でnvmをインストール（2026年3月時点でv0.40.4）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

ブラウザ認証が開かない

claude auth login はブラウザを開こうとするが、WSL環境ではデフォルトブラウザが起動しないことが多い。c キーを押してOAuth URLをクリップボードにコピーし、Windows側のブラウザに貼り付ければOKだ。

環境変数でAPIキーを直接設定する方法（上の認証セクション参照）も確実に動く。

ファイルパスとパフォーマンスの問題

WSLからWindows側のファイル（/mnt/c/...）を操作すると、パフォーマンスが大幅に低下する。Claude Codeのプロジェクトは必ずWSLファイルシステム内（~/）に置こう。

bash
# 良い: WSLネイティブファイルシステム
cd ~/projects/my-app

# 遅い: WSLにマウントされたWindowsファイルシステム
cd /mnt/c/Users/username/projects/my-app

WSL固有の接続問題については WSL2でClaude Codeが切断される問題の解決法 で詳しく解説している。

WSL2のサンドボックス設定

Claude Codeのサンドボックス機能はWSL2上で bubblewrap と socat を必要とする。サンドボックス関連のエラーが出たら以下を実行。

bash
sudo apt install bubblewrap socat

Windowsネイティブへの切り替え

WSLの問題がどうしても解決しない場合、Claude CodeはWindowsネイティブ（PowerShell）でも動作する。ただし、ほとんどの開発作業ではWSLの方が環境が整いやすい。WSL固有の問題を先に解決して、本当に行き詰まった時だけネイティブに切り替えよう。

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

macOS固有の問題と対処法

macOSはWSLほど問題が起きにくいが、いくつか注意点がある。

HomebrewとnvmのNode.js競合

HomebrewでNode.jsをインストールしつつnvmも使っていると、どちらの node が呼ばれるか分からなくなる。

bash
which node
# Homebrew: /opt/homebrew/bin/node
# nvm: /Users/username/.nvm/versions/node/v22.x.x/bin/node

どちらか一方に統一しよう。nvmを使うならHomebrewのNodeが邪魔にならないように外す。

bash
brew uninstall node

Keychainの認証情報トラブル

macOSではClaude Codeの認証情報がシステムKeychainに保存される場合がある。OSアップデートやパスワード変更後に認証が不安定になったら、まず認証をリセットする。

bash
claude auth logout
claude auth login

それでもダメなら、Keychainアクセス（アプリケーション > ユーティリティ）でClaude関連のエントリを手動で削除してから再ログインしよう。

Apple Silicon（M1/M2/M3/M4）互換性

Claude CodeはApple Siliconでネイティブ動作する——Rosettaは不要。ネイティブインストーラーならアーキテクチャを自動検出する。npm方式の場合は、ARM版のNode.jsを使っているか確認しよう（Rosetta経由のx86版だとパフォーマンスに影響する）。

bash
# ARM版Node.jsか確認
node -p "process.arch"
# arm64 と表示されればOK

「claude: command not found」の直し方

インストールは成功しているのに command not found になるのは、バイナリのディレクトリがPATHに含まれていないだけだ。

まずnpmがどこにインストールしたか確認する。

bash
npm root -g

claude バイナリはそのパスの1つ上の bin/ フォルダにある。

bash
# npm rootが /usr/local/lib/node_modules なら /usr/local/bin を確認
ls $(npm prefix -g)/bin/claude

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

bash
echo "export PATH=\"$(npm prefix -g)/bin:\$PATH\"" >> ~/.bashrc
source ~/.bashrc

npmのprefixをカスタマイズしている場合（上のインストール修正で推奨した方法）は、そのpathを使う。

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

設定後に新しいシェルセッションを開くか source ~/.bashrc を実行すること。これで大半は解決する。

パフォーマンスが遅い時の切り分け

Claude Codeの応答が異常に遅くなった場合、原因は大きく3つに分かれる。

1. コンテキストウィンドウの肥大化

セッションが長くなるとコンテキストウィンドウが埋まり、応答の質と速度が低下する。/cost でトークン使用量を確認しよう。

80%を超えていたら /compact で圧縮するか、/clear で新しいセッションを始める。コンテキストを計画的に管理する方法は トークン消費を50%削減した方法 と コンテキストウィンドウ超過の対処法 にまとめている。

2. MCPサーバーのオーバーヘッド

MCPサーバーが多すぎると、各ツール呼び出しのたびにレイテンシが加算される。Claude CodeのUI上で @ を押して接続中のサーバー一覧を確認し、使っていないものはオフにしよう。

claude doctor でもMCPサーバーの状態を確認できる。応答が遅い・失敗しているサーバーがあれば報告してくれる。

3. ネットワーク・API側の問題

Anthropic APIの応答速度はサーバー負荷で変動する。まず ステータスページ を確認。次に claude doctor でAPIへの接続状態を検証する。

bash
claude doctor

それでも解決しない場合の調査・報告方法

ここまでの手順で解決しないなら、ログを取得してエスカレーションする。

デバッグ情報の収集

bash
# 詳細ログを有効にして実行（ツール呼び出しやAPIインタラクションが見える）
claude --verbose 2>&1 | tee claude-verbose.log

# より深いプロトコルレベルのトレース（MCP関連のデバッグ）
claude --debug --mcp-debug 2>&1 | tee claude-debug.log

# 環境情報の収集
node --version
npm --version
claude --version
uname -a
echo $SHELL
echo $PATH
claude auth status

GitHub Issuesへの報告

Claude Codeのバグは 公式リポジトリ で管理されている。新規Issueを開く前に：

  1. 既存のIssueを検索——すでに解決策が見つかっているかもしれない
  2. OS・Node.jsバージョン・エラーメッセージ・デバッグログを含める
  3. 再現手順を明確に書く

コミュニティフォーラムよりGitHub Issuesの方が開発チームに届きやすい。公式のトラブルシューティングドキュメントも頻繁に更新されているのでチェックしておこう。

FAQ

無料プランでClaude Codeは使える？

使えない。Claude CodeにはPro（$20/月）、Max（$100〜200/月）、Team Premium（$150/人/月）のいずれかの有料プランが必要だ。Anthropic Console からAPIキーを取得して従量課金で使う方法もある。

Claude Codeに必要なNode.jsのバージョンは？

ネイティブインストーラーなら Node.jsは一切不要 だ。npm方式の場合はNode.js 18以上が必要で、互換性を考えるとNode.js 22 LTSがおすすめ。バージョン管理には nvm を使おう。

ネイティブインストーラーとnpm、どちらを使うべき？

特別な理由がなければネイティブインストーラー一択だ。2025年後半からAnthropicが推奨している方法で、依存関係ゼロ・自動更新・インストール問題の大半を回避できる。npm方式はNode.js 18+が必要で手動更新が必要になる。

AnthropicのAPIが落ちているか確認するには？

Anthropicのステータスページ にアクセスする。APIに障害が発生している場合、ローカルのトラブルシューティングは無意味なので復旧を待とう。

企業プロキシの裏側でClaude Codeは使える？

使える。インストール時は npm config set proxy と npm config set https-proxy を設定し、カスタムCA証明書がある場合は NODE_EXTRA_CA_CERTS を指定する。詳しくはインストールセクションを参照。

WSL2でClaude Codeが切断され続けるのはなぜ？

WSL2のネットワーキングレイヤー、スリープ/復帰サイクル、vmmem プロセスによるメモリ圧迫が主な原因だ。詳しくは専用ガイド WSL2でClaude Codeが切断される問題の解決法 を参照してほしい。

Claude Codeを完全にリセットするには？

認証情報の削除、キャッシュクリア、再インストールの手順。

bash
claude auth logout
npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude
npm install -g @anthropic-ai/claude-code
claude auth login

claude doctor、--verbose、--debug の違いは？

用途が異なる。claude doctor はNode.jsバージョン・認証・ネットワーク・MCP設定をサクッとチェックする健康診断。claude --verbose はツール呼び出しやAPIインタラクションを表示する詳細ログモード。claude --debug はより深いプロトコルレベルのトレースで、--mcp-debug と組み合わせるとMCP固有の問題も追跡できる。

ブラウザなしのリモートサーバーでClaude Codeを使うには？

ブラウザベースのログインの代わりに、環境変数でAPIキーを設定する。

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

または claude auth login を実行して c キーでOAuth URLをコピーし、ブラウザがある別のデバイスで開く方法もある。

まとめ

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

  1. インストール問題: Node.jsバージョン、npm権限、PATH設定、プロキシ設定
  2. 認証問題: APIキーの有効性、サブスクリプションプラン、環境変数
  3. 環境固有の問題: WSLとWindowsの競合、パス解決、サンドボックスの依存関係

claude doctor を最初に実行する習慣をつけるだけで、問題の切り分けが格段に速くなる。1時間デバッグに費やす前に Anthropicのステータスページ でサービス障害を除外することも忘れずに。

セットアップが完了したら、次は CLAUDE.mdファイル を整備してプロジェクト固有のコンテキストをClaude Codeに伝えよう。ここからが本当の生産性向上の始まりだ。複数プロジェクトを扱うなら、マルチインスタンスガイドも参考になるはずだ。他のAIコーディングツールと迷っているなら、Claude Code vs Cursor比較やClaude Code vs GitHub Copilot比較も読んでみてほしい。