Build This Now
Build This Now
クロード・コードとは何か？Claude Code のインストールClaude Code ネイティブインストーラーClaude Code で最初のプロジェクトを作る
コードを生み出すプロンプトテンプレートClaude Code トラブルシューティングClaude Code よくある質問Claude Code 変更履歴
speedy_devvkoen_salo
Blog/Handbook/Reference/Claude Code Troubleshooting

Claude Code トラブルシューティング

Claude Code の問題を解決する5つの手順: インストールエラー、無効なAPIキー、503タイムアウト、応答の遅延、権限の問題。各ケースへの具体的な対処法。

設定をやめて、構築を始めよう。

AIオーケストレーション付きSaaSビルダーテンプレート。

Published Mar 11, 2026Handbook hubReference index

問題. Claude Code が突然動かなくなり、原因がわからない。ほとんどの不具合は5つの原因から来ており、短いチェックリストで絞り込める。順番に確認していけば、数分以内にプロンプトを打てる状態に戻れるはずだ。

素早い診断チェックリスト:

# 1. Check your installation
claude --version
 
# 2. Test your internet connection
ping claude.ai
 
# 3. Verify your API key
echo $ANTHROPIC_API_KEY
 
# 4. Clear session state (inside Claude Code)
/clear
 
# 5. Restart with fresh config
claude config

いずれかのコマンドでエラーが出たら、該当セクションに飛んで具体的な対処法を確認しよう。

インストールの問題

エラー: command not found: claude

バイナリがPATHに追加されていないか、インストール自体が失敗している。ネイティブインストーラーを使えば自動的に解決する:

# Reinstall with native installer (recommended)
curl -fsSL https://claude.ai/install.sh | bash  # macOS/Linux
# Windows PowerShell: irm https://claude.ai/install.ps1 | iex
 
# Verify installation
which claude

エラー: Node.js version not supported

Node 18以上が必要だ。現在のバージョンを確認しよう:

# Check current version
node --version
 
# If below 18.0, install latest Node.js
# Visit nodejs.org and download the LTS version

エラー: EACCES permission denied

macOSとLinuxでは、npmの所有権が原因であることが多い:

# Fix npm ownership
sudo chown -R $(whoami) ~/.npm
 
# Alternative: use a version manager like nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Windowsの場合は、コマンドプロンプトを管理者として開き、インストーラーを再実行する。

認証の問題

エラー: Invalid API key

キーが設定されていないか、値が誤っている。正しく設定し直そう:

# Reconfigure Claude Code
claude config
 
# Or set environment variable
export ANTHROPIC_API_KEY="your-api-key-here"

新しいキーは console.anthropic.com で取得できる。貼り付け時に余分なスペースが入っていないか確認すること。

エラー: Subscription not recognized

MaxおよびProの認証エラーの場合:

  1. ブラウザでの Claude へのサインアウトを完全に行う
  2. Cookieとキャッシュデータをクリアする
  3. プライベートウィンドウを開いて再ログインする
  4. claude config を再実行して認証を完了させる

接続の問題

エラー: 503 Service Unavailable

これは Anthropic 側の問題であり、あなたの環境の問題ではない:

  • 2〜5分待てば通常サーバーは回復する
  • status.anthropic.com でサービス状況を確認できる
  • 再インストールはサーバーの問題を解決しない

Claude Code が起動したが無反応になる

セッション状態をリセットしよう:

# Clear conversation history (run inside Claude Code)
/clear
 
# Or restart with fresh session
exit
claude

それでも解決しない場合は、接続が生きているか確認してから再試行しよう。

パフォーマンスの問題

応答が遅い、またはフリーズする

より高速なモデルに切り替えてコンテキストを削減しよう:

# Use Claude Sonnet 4 for speed
claude --model claude-sonnet-4-20250514
 
# Compress conversation history (run inside Claude Code)
/compact keep only function names and current errors

エラー: Context window full

スレッドが大きくなりすぎている。リセットするか圧縮しよう:

# Quick fix: start fresh (run inside Claude Code)
/clear
 
# Better fix: compress intelligently
/compact preserve main components and recent changes only

ファイル権限のエラー

エラー: Permission denied on file operations

ディレクトリの所有権に問題がある。修正しよう:

# Check current permissions
ls -la
 
# Fix ownership of project directory
sudo chown -R $(whoami) .
 
# Verify Claude Code can access files
claude --add-dir $(pwd)

設定の問題

設定が意図通りに動かない

ほぼ確実にスコープの優先順位が原因だ。優先順位は Managed > コマンドライン > ローカル > プロジェクト > ユーザーの順になっている。つまり .claude/settings.local.json のキーは .claude/settings.json より優先され、.claude/settings.json は ~/.claude/settings.json より優先される。

# Check which settings files exist
ls ~/.claude/settings.json
ls .claude/settings.json
ls .claude/settings.local.json

マネージド設定が自分の設定を上書きしている

IT部門が managed-settings.json を配布している場合、それが最上位に位置するため上書きはできない。マネージドファイルは macOS では /Library/Application Support/ClaudeCode/、Linux/WSL では /etc/claude-code/、Windows では C:\Program Files\ClaudeCode\ に置かれている。ある設定が何度も元に戻る場合は、管理者にポリシーで固定されていないか確認しよう。

設定のオートコンプリートが動かない

settings.json の先頭に $schema 行を追加すると、エディタが検証・補完できるようになる:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

サンドボックスとセキュリティの問題

エラー: bubblewrap not installed (Linux/WSL2)

Linuxのサンドボックスには bubblewrap と socat パッケージが必要だ。両方インストールして再実行しよう:

# Debian/Ubuntu
sudo apt install bubblewrap socat
 
# Fedora
sudo dnf install bubblewrap socat

WatchmanがサンドボックスとコンフリクトするWatchman

MetaのWatchmanファイルウォッチャーは Claude Code のサンドボックスと競合する。Watchmanを無効にするか、サンドボックスの境界外に置くこと。

サンドボックス内でDockerコマンドが失敗する

Dockerはサンドボックス外で実行する必要がある。settings.json の excludedCommands に追加しよう:

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker", "docker-compose"]
  }
}

デバッグ用環境変数

頑固なバグに悩んでいるなら、これらの環境変数が問題の切り分けに役立つ:

変数内容
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC自動更新、テレメトリ、エラーレポート、バグレポートを一括無効化。ネットワーク問題の調査に便利。
DISABLE_AUTOUPDATER自動更新のみを無効化。更新処理が問題を起こしている場合は 1 にセット。
DISABLE_ERROR_REPORTINGSentryへのエラーレポートをオプトアウト（1 にセット）。
DISABLE_TELEMETRYStatsigのテレメトリをオプトアウト（1 にセット）。
CLAUDE_CODE_DISABLE_BACKGROUND_TASKSすべてのバックグラウンドタスクを停止（1 にセット）。
# Run Claude Code with all non-essential traffic disabled
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 claude
 
# Or set just the auto-updater off
DISABLE_AUTOUPDATER=1 claude

プロキシやネットワークの問題が疑われる場合は、HTTP_PROXY または HTTPS_PROXY でトラフィックをルーティングし、特定のホストをプロキシから除外するには NO_PROXY を使おう。

高度な対処法

それでも解決しない場合は完全にやり直す:

# 1. Uninstall any existing installation
npm uninstall -g @anthropic-ai/claude-code  # if installed via npm
 
# 2. Remove config files
rm ~/.claude.json
rm -rf ~/.claude/
 
# 3. Fresh install with native installer (recommended)
curl -fsSL https://claude.ai/install.sh | bash  # macOS/Linux
# Windows PowerShell: irm https://claude.ai/install.ps1 | iex
 
# 4. Reconfigure
claude config

ネイティブインストーラーはPATHの設定を自動で行い、最新状態を保つ。

動作確認

修正が完了したら、簡単な動作確認を行おう:

# Test basic functionality
claude "write hello world in Python"
 
# Test file operations
echo "# Test" > test.md
claude "read and improve test.md"
 
# Test help command (inside Claude Code)
/help

Claude Code が正常に応答するはずだ。まだ応答しない場合は、サービス側の問題の可能性が高い。数分待ってから再試行しよう。

Continue in Reference

  • Claude Code 変更履歴
    v0.2ベータから2026年3月までのClaude Codeのリリースノート。ベアモード、チャンネル権限リレー、OAuthの修正、すべての破壊的変更を網羅。
  • コードを生み出すプロンプトテンプレート
    コードを出荷する10のプロンプトレシピ: フルスタックスキャフォールディング、API、スキーマ、テスト、リファクタリング、デバッグ、レビュー、CI。それぞれの失敗パターンも紹介。
  • Claude Code よくある質問
    Claude Codeの料金、1日の支出、モデル選択、Cursorとの比較、スキル、CLAUDE.md、APIキー、ターミナルエージェントが実際にできることについての明確な回答。

More from Handbook

  • エージェントの基礎
    Claude Codeでスペシャリストエージェントを構築する5つの方法：タスクサブエージェント、.claude/agents YAML、カスタムスラッシュコマンド、CLAUDE.mdペルソナ、パースペクティブプロンプト。
  • エージェントパターン
    オーケストレーター、ファンアウト、バリデーションチェーン、スペシャリストルーティング、プログレッシブリファインメント、ウォッチドッグ。Claude Code のサブエージェントを組み合わせる6つのオーケストレーション形状。
  • エージェントチームのベストプラクティス
    Claude Code エージェントチームの実証済みパターン。コンテキストが豊富なスポーンプロンプト、適切なサイズのタスク、ファイルオーナーシップ、デリゲートモード、v2.1.33〜v2.1.45 の修正内容。
  • エージェントチームのコントロール
    デリゲートモード、表示モード、プラン承認、ファイル境界、CLAUDE.md ルールを設定して、Claude Code のチームリードがコーディングではなくコーディネートに専念できるようにします。

設定をやめて、構築を始めよう。

AIオーケストレーション付きSaaSビルダーテンプレート。

コードを生み出すプロンプトテンプレート

コードを出荷する10のプロンプトレシピ: フルスタックスキャフォールディング、API、スキーマ、テスト、リファクタリング、デバッグ、レビュー、CI。それぞれの失敗パターンも紹介。

Claude Code よくある質問

Claude Codeの料金、1日の支出、モデル選択、Cursorとの比較、スキル、CLAUDE.md、APIキー、ターミナルエージェントが実際にできることについての明確な回答。

On this page

インストールの問題
認証の問題
接続の問題
パフォーマンスの問題
ファイル権限のエラー
設定の問題
サンドボックスとセキュリティの問題
デバッグ用環境変数
高度な対処法
動作確認

設定をやめて、構築を始めよう。

AIオーケストレーション付きSaaSビルダーテンプレート。