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

​
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. 応答しない場合は、ターミナルを閉じて再起動する必要がある場合があります

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

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

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

  1. 設定 → ツール → ターミナルに移動
  2. 「IDEショートカットを上書き」の横にある「ターミナルキーバインドを設定」ハイパーリンクをクリック
  3. ターミナルキーバインド内で、「エディターにフォーカスを切り替え」までスクロールダウンし、そのショートカットを削除

これにより、ESCキーがPyCharmの「エディターにフォーカスを切り替え」アクションによってキャプチャされる代わりに、Claude Code操作のキャンセルに適切に機能するようになります。

​
検索と発見の問題

検索ツール、@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をネイティブに実行することを検討してください。

​
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はそのドキュメントへの組み込みアクセスを持っています