​
一般的なインストールの問題

​
Windowsインストールの問題：WSLでのエラー

WSLで以下の問題が発生する可能性があります：

OS/プラットフォーム検出の問題：インストール中にエラーが発生した場合、WSLがWindows npmを使用している可能性があります。以下を試してください：

  • インストール前にnpm config set os linuxを実行
  • npm install -g @anthropic-ai/claude-code --force --no-os-checkでインストール（sudoは使用しないでください）

Nodeが見つからないエラー：claudeを実行時にexec: node: not foundが表示される場合、WSL環境がWindows版のNode.jsを使用している可能性があります。which npmとwhich nodeで確認でき、これらは/mnt/c/ではなく/usr/で始まるLinuxパスを指している必要があります。これを修正するには、Linuxディストリビューションのパッケージマネージャーまたはnvmを使用してNodeをインストールしてみてください。

nvmバージョンの競合：WSLとWindowsの両方にnvmがインストールされている場合、WSLでNodeバージョンを切り替える際にバージョンの競合が発生する可能性があります。これは、WSLがデフォルトでWindows PATHをインポートするため、Windows nvm/npmがWSLインストールより優先されることが原因です。

この問題は以下で識別できます：

  • which npmとwhich nodeを実行 - これらがWindowsパス（/mnt/c/で始まる）を指している場合、Windowsバージョンが使用されています
  • WSLでnvmを使用してNodeバージョンを切り替えた後に機能が破損する

この問題を解決するには、Linux node/npmバージョンが優先されるようにLinux PATHを修正してください：

主要な解決策：nvmがシェルで適切に読み込まれていることを確認

最も一般的な原因は、nvmが非対話型シェルで読み込まれていないことです。シェル設定ファイル（~/.bashrc、~/.zshrcなど）に以下を追加してください：

# nvmが存在する場合は読み込む
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

または現在のセッションで直接実行：

source ~/.nvm/nvm.sh

代替案：PATH順序の調整

nvmが適切に読み込まれているがWindowsパスが依然として優先される場合、シェル設定でLinuxパスを明示的にPATHの前に追加できます：

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

Windows PATHインポートの無効化（appendWindowsPath = false）は、WSLからWindows実行ファイルを簡単に呼び出す機能を破損するため避けてください。同様に、Windows開発に使用している場合は、WindowsからNode.jsをアンインストールすることも避けてください。

​
LinuxとMacのインストール問題：権限またはコマンドが見つからないエラー

npmでClaude Codeをインストールする際、PATHの問題によりclaudeにアクセスできない場合があります。 npmグローバルプレフィックスがユーザー書き込み可能でない場合（例：/usr、または/usr/local）、権限エラーが発生する可能性もあります。

​
推奨解決策：ネイティブClaude Codeインストール

Claude Codeには、npmやNode.jsに依存しないネイティブインストールがあります。

ネイティブClaude Codeインストーラーは現在ベータ版です。

以下のコマンドを使用してネイティブインストーラーを実行してください。

macOS、Linux、WSL：

# 安定版をインストール（デフォルト）
curl -fsSL https://claude.ai/install.sh | bash

# 最新版をインストール
curl -fsSL https://claude.ai/install.sh | bash -s latest

# 特定のバージョン番号をインストール
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Windows PowerShell：

# 安定版をインストール（デフォルト）
irm https://claude.ai/install.ps1 | iex

# 最新版をインストール
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# 特定のバージョン番号をインストール
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

このコマンドは、お使いのオペレーティングシステムとアーキテクチャに適したClaude Codeのビルドをインストールし、~/.local/bin/claudeのインストールにシンボリックリンクを追加します。

システムPATHにインストールディレクトリがあることを確認してください。

​
代替解決策：ローカルインストールへの移行

または、Claude Codeが実行される場合は、ローカルインストールに移行できます：

claude migrate-installer

これによりClaude Codeが~/.claude/local/に移動し、シェル設定にエイリアスが設定されます。今後のアップデートにsudoは必要ありません。

移行後、シェルを再起動し、インストールを確認してください：

macOS/Linux/WSLの場合：

which claude  # ~/.claude/local/claudeへのエイリアスを表示する必要があります

Windowsの場合：

where claude  # claude実行ファイルへのパスを表示する必要があります

インストールの確認：

claude doctor # インストールの健全性をチェック

​
権限と認証

​
繰り返される権限プロンプト

同じコマンドを繰り返し承認している場合は、/permissionsコマンドを使用して特定のツールを承認なしで実行できるようにすることができます。権限ドキュメントを参照してください。

​
認証の問題

認証の問題が発生している場合：

  1. /logoutを実行して完全にサインアウト
  2. Claude Codeを閉じる
  3. claudeで再起動し、認証プロセスを再度完了

問題が続く場合は、以下を試してください：

rm -rf ~/.config/claude-code/auth.json
claude

これにより保存された認証情報が削除され、クリーンなログインが強制されます。

​
パフォーマンスと安定性

​
高いCPUまたはメモリ使用量

Claude Codeはほとんどの開発環境で動作するように設計されていますが、大規模なコードベースを処理する際に大量のリソースを消費する可能性があります。パフォーマンスの問題が発生している場合：

  1. /compactを定期的に使用してコンテキストサイズを削減
  2. 主要なタスクの間でClaude Codeを閉じて再起動
  3. 大きなビルドディレクトリを.gitignoreファイルに追加することを検討

​
コマンドのハングまたはフリーズ

Claude Codeが応答しない場合：

  1. Ctrl+Cを押して現在の操作をキャンセルしようとする
  2. 応答しない場合は、ターミナルを閉じて再起動する必要がある場合があります

​
検索と発見の問題

検索ツール、@fileメンション、カスタムエージェント、カスタムスラッシュコマンドが機能しない場合は、システムripgrepをインストールしてください：

# macOS（Homebrew）  
brew install ripgrep

# Windows（winget）
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

# Arch Linux
pacman -S ripgrep

次に、環境でUSE_BUILTIN_RIPGREP=0を設定してください。

​
WSLでの遅いまたは不完全な検索結果

WSLでファイルシステム間での作業時のディスク読み取りパフォーマンスのペナルティにより、WSLでClaude Codeを使用する際に期待より少ないマッチ（ただし検索機能の完全な欠如ではない）が生じる可能性があります。

この場合、/doctorは検索をOKとして表示します。

解決策：

  1. より具体的な検索を送信：ディレクトリやファイルタイプを指定して検索するファイル数を減らす：「auth-serviceパッケージでJWT検証ロジックを検索」または「JSファイルでmd5ハッシュの使用を見つける」。

  2. プロジェクトをLinuxファイルシステムに移動：可能であれば、プロジェクトがWindowsファイルシステム（/mnt/c/）ではなくLinuxファイルシステム（/home/）に配置されていることを確認してください。

  3. 代わりにネイティブWindowsを使用：より良いファイルシステムパフォーマンスのために、WSLを通してではなくWindows上でClaude Codeをネイティブに実行することを検討してください。

​
IDE統合の問題

​
WSL2でJetBrains IDEが検出されない

WSL2でJetBrains IDEと共にClaude Codeを使用していて「利用可能なIDEが検出されません」エラーが発生する場合、これはWSL2のネットワーク設定またはWindows Firewallが接続をブロックしていることが原因の可能性があります。

​
WSL2ネットワークモード

WSL2はデフォルトでNATネットワークを使用し、これがIDE検出を妨げる可能性があります。2つのオプションがあります：

オプション1：Windows Firewallを設定（推奨）

  1. WSL2 IPアドレスを見つける：

    wsl hostname -I
# 出力例：172.21.123.456

  2. 管理者としてPowerShellを開き、ファイアウォールルールを作成：

    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

    （ステップ1のWSL2サブネットに基づいてIP範囲を調整）

  3. IDEとClaude Codeの両方を再起動

オプション2：ミラードネットワークに切り替え

Windowsユーザーディレクトリの.wslconfigに追加：

[wsl2]
networkingMode=mirrored

次に、PowerShellからwsl --shutdownでWSLを再起動。

これらのネットワーク問題はWSL2のみに影響します。WSL1はホストのネットワークを直接使用し、これらの設定は必要ありません。

追加のJetBrains設定のヒントについては、IDE統合ガイドを参照してください。

​
Windows IDE統合問題の報告（ネイティブとWSLの両方）

WindowsでIDE統合の問題が発生している場合は、以下の情報と共に問題を作成してください：ネイティブ（git bash）かWSL1/WSL2か、WSLネットワークモード（NATまたはミラード）、IDE名/バージョン、Claude Code拡張/プラグインバージョン、シェルタイプ（bash/zsh/など）

​
JetBrains（IntelliJ、PyCharmなど）ターミナルでESCキーが機能しない

JetBrainsターミナルでClaude Codeを使用していて、ESCキーが期待通りにエージェントを中断しない場合、これはJetBrainsのデフォルトショートカットとのキーバインドの競合が原因の可能性があります。

この問題を修正するには：

  1. 設定 → ツール → ターミナルに移動
  2. 以下のいずれかを実行：
    • 「Escapeでエディターにフォーカスを移動」のチェックを外す、または
    • 「ターミナルキーバインドを設定」をクリックし、「エディターにフォーカスを切り替え」ショートカットを削除
  3. 変更を適用

これによりESCキーがClaude Code操作を適切に中断できるようになります。

​
Markdownフォーマットの問題

Claude Codeは時々、コードフェンスに言語タグが欠けているMarkdownファイルを生成し、GitHub、エディター、ドキュメントツールでの構文ハイライトと可読性に影響を与える可能性があります。

​
コードブロックの言語タグの欠如

生成されたMarkdownで以下のようなコードブロックに気づいた場合：

```
function example() {
  return "hello";
}
```

適切にタグ付けされたブロックの代わりに：

```javascript
function example() {
  return "hello";
}
```

解決策：

  1. Claudeに言語タグの追加を依頼：単純に「このMarkdownファイルのすべてのコードブロックに適切な言語タグを追加してください」と要求。

  2. 後処理フックを使用：欠けている言語タグを検出して追加する自動フォーマットフックを設定。実装の詳細についてはMarkdownフォーマットフックの例を参照。

  3. 手動検証：Markdownファイルを生成した後、適切なコードブロックフォーマットを確認し、必要に応じて修正を要求。

​
一貫性のない間隔とフォーマット

生成されたMarkdownに過度の空行や一貫性のない間隔がある場合：

解決策：

  1. フォーマット修正を要求：Claudeに「このMarkdownファイルの間隔とフォーマットの問題を修正してください」と依頼。

  2. フォーマットツールを使用：生成されたMarkdownファイルでprettierやカスタムフォーマットスクリプトなどのMarkdownフォーマッターを実行するフックを設定。

  3. フォーマット設定を指定：プロンプトやプロジェクトメモリファイルにフォーマット要件を含める。

​
Markdown生成のベストプラクティス

フォーマットの問題を最小限に抑えるために：

  • 要求で明示的に：「言語タグ付きコードブロックを含む適切にフォーマットされたMarkdown」を要求
  • プロジェクト規約を使用：CLAUDE.mdで好みのMarkdownスタイルを文書化
  • 検証フックを設定：一般的なフォーマット問題を自動的に検証・修正する後処理フックを使用

​
さらなるヘルプの取得

ここでカバーされていない問題が発生している場合：

  1. Claude Code内で/bugコマンドを使用してAnthropicに直接問題を報告
  2. 既知の問題についてGitHubリポジトリを確認
  3. /doctorを実行してClaude Codeインストールの健全性をチェック
  4. Claudeの機能と特徴について直接Claudeに質問 - Claudeはそのドキュメントへの組み込みアクセスを持っています