はじめに

Claude Codeは強力なAIコーディングアシスタントですが、インストール時の環境差異、認証の問題、MCP接続エラーなど、使用中にさまざまなトラブルに遭遇することがあります。本記事では、Claude Codeで発生しやすい一般的な問題と、その解決策を体系的に解説します。

この記事を読むことで、以下のことができるようになります。

  • インストール時のエラーを自力で解決する
  • 認証関連の問題を診断・修正する
  • パフォーマンス問題の原因を特定し改善する
  • MCP接続エラーを解消する
  • claude doctorコマンドで環境を診断する

実行環境

  • オペレーティングシステム: macOS 10.15以上、Ubuntu 20.04以上/Debian 10以上、Windows 10以上（WSL 1/2またはGit for Windows）
  • ハードウェア: 4GB以上のRAM
  • Node.js 18以上（npmインストールの場合のみ必要）
  • インターネット接続（認証およびAI処理に必要）
  • シェル環境: Bash、Zsh、またはFish推奨

前提条件

  • コマンドライン操作の基礎知識
  • Gitの基本操作（clone、commit、push等）
  • プログラミングの基礎知識（言語は問わない）
  • Claude.aiまたはAnthropic Consoleアカウント

トラブルシューティングの基本アプローチ

問題が発生した際は、以下の手順で切り分けを行います。

flowchart TD
    A[問題発生] --> B{claude doctor<br>を実行}
    B --> C{診断結果を確認}
    C --> |インストール問題| D[インストール関連の<br>トラブルシューティング]
    C --> |認証問題| E[認証関連の<br>トラブルシューティング]
    C --> |パフォーマンス問題| F[パフォーマンス<br>最適化]
    C --> |MCP問題| G[MCP接続<br>トラブルシューティング]
    D --> H[問題解決]
    E --> H
    F --> H
    G --> H

まずはclaude doctorコマンドで環境の健全性をチェックし、問題の種類を特定することが効率的です。

claude doctorコマンドによる診断

claude doctorとは

claude doctorはClaude Codeのインストール状態と環境設定を診断するコマンドです。問題が発生した際の最初のステップとして実行することを推奨します。

1
2

# インストール状態の診断
claude doctor

このコマンドは以下の項目をチェックします。

チェック項目 説明
インストール方法 ネイティブ、Homebrew、npmのいずれか
実行ファイルパス claudeコマンドの配置場所
バージョン情報 現在インストールされているバージョン
PATH設定 実行ファイルがPATHに含まれているか
依存関係 必要なツール（Git等）の有無
検索機能 ripgrepの動作状況

診断結果の読み方

claude doctorの出力は色分けされており、緑色のチェックマークは正常、赤色のバツ印は問題ありを示します。問題が検出された場合は、対処方法のヒントも表示されます。

インストール関連のトラブルシューティング

Windowsでのインストールエラー

「Claude Code on Windows requires git-bash」エラー

Claude CodeをネイティブWindowsで使用するには、Git for Windowsのインストールが必要です。Gitがインストール済みでも検出されない場合は、以下の方法で明示的にパスを設定します。

PowerShellで一時的に設定する方法

1
2

$env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"
claude

システム環境変数に永続的に設定する方法

  1. Win + Rを押してsysdm.cplを実行
  2. 「詳細設定」タブの「環境変数」をクリック
  3. ユーザー環境変数にCLAUDE_CODE_GIT_BASH_PATHを追加
  4. 値にC:\Program Files\Git\bin\bash.exeを設定

Gitが標準以外の場所にインストールされている場合は、パスを適宜調整してください。

「installMethod is native, but claude command not found」エラー

インストール後にclaudeコマンドが見つからない場合は、PATHの設定が必要です。

  1. Win + Rを押してsysdm.cplを実行
  2. 「詳細設定」タブの「環境変数」をクリック
  3. ユーザー変数の「Path」を選択し「編集」をクリック
  4. 「新規」をクリックして以下を追加
1

%USERPROFILE%\.local\bin
  1. ターミナルを再起動して設定を反映

設定後、以下のコマンドでインストール状態を確認します。

1

claude doctor

WSLでのインストールエラー

OS/プラットフォーム検出の問題

WSL環境でインストール時にエラーが発生する場合、WSLがWindowsのnpmを参照している可能性があります。

1
2
3
4
5
6

# npmの設定を確認
which npm
which node

# Linuxパス（/usr/から始まる）を指していることを確認
# /mnt/c/から始まる場合はWindowsのnpmを使用している

解決策1: npmの設定を変更

1
2

npm config set os linux
npm install -g @anthropic-ai/claude-code --force --no-os-check

解決策2: ネイティブインストールを使用（推奨）

npmの問題を回避するため、ネイティブインストールを使用します。

1

curl -fsSL https://claude.ai/install.sh | bash

「exec: node: not found」エラー

WSL環境でnodeが見つからない場合は、WindowsのNode.jsを参照している可能性があります。

解決策: nvm経由でLinux版Node.jsをインストール

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# nvmのインストール（未インストールの場合）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# シェル設定ファイルにnvmの読み込みを追加
# ~/.bashrc または ~/.zshrc に以下を追加
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

# 設定を反映
source ~/.bashrc  # または source ~/.zshrc

# Node.jsをインストール
nvm install 20
nvm use 20

nvmバージョン競合

WSLとWindowsの両方にnvmがインストールされている場合、PATH設定によっては競合が発生します。

1
2
3

# PATHの優先順位を修正
# ~/.bashrc または ~/.zshrc に追加
export PATH="$HOME/.nvm/versions/node/$(nvm current)/bin:$PATH"

macOS/Linuxでのインストールエラー

パーミッションエラーまたは「command not found」

npmでのインストール時にパーミッションエラーが発生する場合は、ネイティブインストールを使用することを推奨します。

1
2

# ネイティブインストール（推奨）
curl -fsSL https://claude.ai/install.sh | bash

インストール後、以下のディレクトリがPATHに含まれていることを確認します。

1
2
3
4
5

# インストール先の確認
ls ~/.local/bin/claude

# PATHの確認
echo $PATH | grep -q ".local/bin" && echo "PATH OK" || echo "PATH要設定"

PATHに含まれていない場合は、シェル設定ファイルに追加します。

1
2
3
4
5

# ~/.bashrc または ~/.zshrc に追加
export PATH="$HOME/.local/bin:$PATH"

# 設定を反映
source ~/.bashrc

認証関連のトラブルシューティング

認証エラーの解決

認証に関する問題が発生した場合は、以下の手順で解決を試みます。

基本的な再認証手順

1
2
3
4
5
6
7
8

# 1. ログアウト
/logout  # Claude Code内で実行

# 2. Claude Codeを終了
exit

# 3. 再度起動して認証
claude

認証情報のリセット

上記で解決しない場合は、認証情報を完全に削除して再認証を行います。

1
2
3
4
5
6
7

# macOS/Linux/WSL
rm -rf ~/.config/claude-code/auth.json
claude

# Windows PowerShell
Remove-Item -Recurse -Force "$env:USERPROFILE\.config\claude-code\auth.json"
claude

繰り返しのパーミッション承認

同じコマンドに対して何度も承認を求められる場合は、/permissionsコマンドで許可設定を追加できます。

1
2

# Claude Code内で実行
/permissions

設定できる許可レベルは以下の通りです。

許可レベル 説明
Allow Always 常に許可（確認なし）
Allow for Session 現在のセッションのみ許可
Deny 拒否

許可設定は~/.claude/settings.jsonに保存されます。

パフォーマンス関連のトラブルシューティング

CPU・メモリ使用量が高い

Claude Codeは大規模なコードベースを処理する際に、多くのリソースを消費する場合があります。

コンテキストの圧縮

会話が長くなるとコンテキストが肥大化し、パフォーマンスに影響します。/compactコマンドでコンテキストを圧縮します。

1
2

# Claude Code内で実行
/compact

セッションのリスタート

大きなタスクが完了したら、セッションを終了して新しく開始することでメモリを解放できます。

1
2
3
4
5

# セッション終了
exit

# 新しいセッション開始
claude

.gitignoreの活用

ビルド出力やnode_modulesなどの大きなディレクトリは、Claude Codeの解析対象から除外されるよう.gitignoreに含まれていることを確認します。

コマンドのハング・フリーズ

Claude Codeが応答しなくなった場合の対処方法です。

1
2
3
4
5
6

# 1. 現在の操作をキャンセル
Ctrl+C

# 2. 反応がない場合はターミナルを閉じて再起動
# 新しいターミナルを開いて
claude

検索機能の問題

Search機能、@fileメンション、カスタムエージェント、カスタムスラッシュコマンドが動作しない場合は、システムのripgrepを使用するよう設定します。

ripgrepのインストール

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# macOS (Homebrew)
brew install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Arch Linux
pacman -S ripgrep

環境変数の設定

1
2

# システムのripgrepを使用するよう設定
export USE_BUILTIN_RIPGREP=0

この設定をシェル設定ファイル（~/.bashrc、~/.zshrc等）に追加すると永続化されます。

WSLでの検索パフォーマンス低下

WSLでWindowsファイルシステム（/mnt/c/配下）にあるプロジェクトを操作すると、ディスクI/Oのオーバーヘッドにより検索パフォーマンスが低下します。

解決策

1. より具体的な検索クエリを使用

1
2

悪い例: Search for validation logic
良い例: Search for JWT validation in the auth-service package

2. プロジェクトをLinuxファイルシステムに移動（推奨）

1
2
3
4
5

# Windowsパス（遅い）
/mnt/c/Users/username/projects/myapp

# Linuxパス（高速）
/home/username/projects/myapp

3. ネイティブWindowsでClaude Codeを使用

WSL特有の問題を回避するため、Git for Windows環境でClaude Codeを使用することも検討してください。

MCP接続のトラブルシューティング

MCP接続状態の確認

MCPサーバーの接続状態は/mcpコマンドで確認できます。

1
2

# Claude Code内で実行
/mcp

このコマンドで以下の情報を確認できます。

  • 設定済みのMCPサーバー一覧
  • 各サーバーの接続状態
  • 認証状態
  • 利用可能なツール

WindowsでのMCPサーバー起動エラー

ネイティブWindows（WSLではない）環境で、ローカルのstdio MCPサーバーが「Connection closed」エラーで起動しない場合があります。

原因

Windowsではnpxコマンドを直接実行できないため、cmd /cラッパーが必要です。

解決策

1
2
3
4
5

# 誤った設定
claude mcp add --transport stdio my-server -- npx -y @some/package

# 正しい設定
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

MCP認証エラー

OAuth認証が必要なリモートMCPサーバーへの接続で問題が発生した場合は、以下の手順で再認証を行います。

1
2
3
4
5
6

# 1. /mcpコマンドを実行
/mcp

# 2. 問題のあるサーバーを選択
# 3. 「Clear authentication」を選択して認証をクリア
# 4. 「Authenticate」を選択して再認証

ブラウザが自動的に開かない場合は、表示されるURLを手動でコピーしてブラウザに貼り付けてください。

MCPサーバーのタイムアウト

MCPサーバーの起動に時間がかかる場合、タイムアウトが発生することがあります。

1
2

# タイムアウト時間を10秒に設定してClaude Codeを起動
MCP_TIMEOUT=10000 claude

デフォルトのタイムアウト値で接続できない場合は、この値を増やしてみてください。

MCP出力が大きすぎる警告

MCPツールの出力が10,000トークンを超えると警告が表示されます。大量のデータを扱うMCPサーバーを使用する場合は、上限を引き上げます。

1
2
3

# 出力上限を50,000トークンに設定
export MAX_MCP_OUTPUT_TOKENS=50000
claude

MCPサーバーの設定リセット

MCP設定に問題がある場合は、設定ファイルを削除してリセットできます。

1
2
3
4
5
6
7
8

# プロジェクト固有のMCP設定を削除
rm .mcp.json

# ユーザー設定からMCPサーバーを削除
claude mcp remove <サーバー名>

# すべてのMCPサーバー設定を確認
claude mcp list

IDE連携のトラブルシューティング

WSL2でJetBrains IDEが検出されない

WSL2のNATネットワーキングにより、JetBrains IDEとの通信がブロックされる場合があります。

解決策1: Windowsファイアウォールの設定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 管理者権限のPowerShellで実行

# 1. WSL2のIPアドレスを確認
wsl hostname -I
# 出力例: 172.21.123.456

# 2. ファイアウォールルールを追加
New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16

# 3. IDEとClaude Codeを再起動

解決策2: ミラーネットワーキングモードに切り替え

Windowsユーザーディレクトリの.wslconfigに以下を追加します。

1
2

[wsl2]
networkingMode=mirrored

PowerShellでWSLを再起動します。

1

wsl --shutdown

JetBrainsターミナルでEscキーが効かない

JetBrains IDEのターミナルでClaude Codeを使用する際、Escキーがエージェントの中断に使えない場合があります。

解決策

  1. Settings → Tools → Terminalを開く
  2. 以下のいずれかを実行
    • 「Move focus to the editor with Escape」のチェックを外す
    • 「Configure terminal keybindings」をクリックし、「Switch focus to Editor」のショートカットを削除
  3. 設定を適用

設定ファイルのトラブルシューティング

設定ファイルの場所

Claude Codeの設定は複数の場所に保存されます。

ファイル 説明
~/.claude/settings.json ユーザー設定（パーミッション、フック、モデル設定）
.claude/settings.json プロジェクト設定（ソースコード管理対象）
.claude/settings.local.json ローカルプロジェクト設定（コミット対象外）
~/.claude.json グローバル状態（テーマ、OAuth、MCPサーバー、許可ツール）
.mcp.json プロジェクトMCPサーバー（ソースコード管理対象）

Windowsでは~はユーザーホームディレクトリ（例: C:\Users\YourName）を指します。

設定の完全リセット

設定を初期状態に戻すには、設定ファイルを削除します。

1
2
3
4
5
6
7

# すべてのユーザー設定と状態をリセット
rm ~/.claude.json
rm -rf ~/.claude/

# プロジェクト固有の設定をリセット
rm -rf .claude/
rm .mcp.json

この操作により、すべての設定、許可済みツール、MCPサーバー設定、セッション履歴が削除されます。

問題報告とサポート

/bugコマンドによる問題報告

解決できない問題が発生した場合は、/bugコマンドでAnthropicに直接報告できます。

1
2

# Claude Code内で実行
/bug

GitHubでの問題報告

Windows IDE連携の問題など、詳細な情報が必要な場合はGitHubリポジトリにIssueを作成してください。

報告時には以下の情報を含めてください。

  • 環境タイプ: ネイティブWindows（Git Bash）、WSL1、WSL2
  • WSLネットワーキングモード（該当する場合）: NATまたはmirrored
  • IDE名とバージョン
  • Claude Code拡張機能/プラグインのバージョン
  • シェルタイプ: Bash、Zsh、PowerShell等

Claude自体への質問

Claude Codeには公式ドキュメントへのアクセス機能が組み込まれています。Claude Code内で直接、機能や使い方について質問できます。

1
2

> Claude Codeでできることを教えてください
> /helpでどんなコマンドが使えますか

トラブルシューティングチェックリスト

問題発生時のクイックリファレンスとして、以下のチェックリストを活用してください。

インストール問題

  • claude doctorで診断を実行
  • PATHに~/.local/binが含まれているか確認
  • Windows: Git for Windowsがインストールされているか確認
  • WSL: which npmがLinuxパスを指しているか確認

認証問題

  • /logoutで完全にログアウト
  • ~/.config/claude-code/auth.jsonを削除して再認証
  • インターネット接続を確認

パフォーマンス問題

  • /compactでコンテキストを圧縮
  • セッションを再起動
  • ripgrepのインストール状況を確認
  • プロジェクトがLinuxファイルシステム上にあるか確認（WSL）

MCP問題

  • /mcpで接続状態を確認
  • Windows: cmd /cラッパーを使用しているか確認
  • タイムアウト設定を確認（MCP_TIMEOUT環境変数）
  • 認証をクリアして再認証

まとめ

本記事では、Claude Codeで発生しやすい問題とその解決策を解説しました。トラブルシューティングの基本は、まずclaude doctorコマンドで環境の健全性をチェックし、問題の種類を特定することです。

問題の種類ごとに適切な対処を行うことで、多くの問題は自力で解決できます。解決が難しい場合は、/bugコマンドやGitHub Issueを通じてAnthropicに報告することで、サポートを受けられます。

Claude Codeを安定して使用するために、本記事をブックマークして問題発生時のリファレンスとしてご活用ください。

参考リンク