claude code 動かない原因と対処法｜環境別トラブル完全解説

Claude Codeが「動かない」と感じたとき、原因カテゴリを素早く特定できるかどうかが解決速度を大きく左右する。本記事では、公式トラブルシューティングドキュメントおよび公式FAQページに基づき、環境別の具体的な対処手順を解説する。

claude code 動かないと感じたら最初に行う切り分け

Claude Codeが「動かない」と感じる状況は、性質の異なる二種類に大別できる。ひとつは起動・接続・認証の段階で完全に止まるケース、もうひとつは起動はするが応答品質が著しく低下するケースだ。後者は「最近 Claude Code が雑になった」「指示を無視するようになった」と表現されることが多く、エラーメッセージが出ないため原因特定が遅れやすい。

両者は原因の性質がまったく異なるため、最初に切り分けを行うことが解決への最短経路となる。以下のチェックリストを上から順に実行してほしい（公式：トラブルシューティング）。

1. バージョンを確認する：claude --version
2. 組み込み診断を実行する：claude doctor（CLIから実行）またはセッション内 /doctor
3. 認証状態を確認する：セッション内 /status
4. ネットワーク接続・プロキシ設定を確認する
5. npm 経由でインストールした場合は Node.js のバージョンが 18 以上であることを確認する：node -v

この5ステップだけで、「完全に動かない」問題の大半は原因カテゴリを特定できる。Claude Code の前提環境や導入手順については Claude Code インストール完全ガイド も参照されたい。

起動・認証エラー 証明書 / プロキシ / APIキー

応答品質の劣化 コンテキスト肥大化

バージョン不整合 Node.js / npm 依存関係

auth reset / NODE_EXTRA_CA_CERTS HTTPS_PROXY 設定 / /doctor

/compact でリセット / セッション分割 CLAUDE.md 活用

npm update -g @anthropic-ai/claude-code

まず claude –version と claude doctor で原因カテゴリを特定する

claude code 動かない原因1：インストール・認証・証明書エラーの具体的対処

Node.jsバージョンとPATHの確認

npm 経由で Claude Code をインストールする場合、Node.js 18 以上が必要だ（公式セットアップガイド）。なお、ネイティブインストーラを使用する場合は Node.js は不要となる。node -v で現在のバージョンを確認し、18 未満であれば LTS 系列へ更新すること。

インストール自体が通っていても、グローバルインストール先の PATH が通っていないケースが多い。公式ドキュメントによれば、mac/Linux/WSL 環境では ~/.local/bin をPATHに追加することで解消できる。

# PATHが通っているか確認
which claude

# 通っていない場合は以下をシェルプロファイル（~/.zshrc または ~/.bashrc）に追記
export PATH="$HOME/.local/bin:$PATH"
source ~/.zshrc

Windows 環境では、ユーザー環境変数 PATH に %USERPROFILE%\.local\bin を追加してから再起動することで解消する（公式：インストールトラブルシューティング）。

企業環境の証明書エラーへの対処

企業のゼロトラスト環境やプロキシ下では「証明書エラーが出て Claude Code が動かない」という問題が企業導入の障壁になりやすい。まず curl -I https://api.anthropic.com で疎通を確認し、接続できない場合は以下の環境変数を設定する（公式：ネットワーク設定）。

# 企業ルート証明書を指定（ファイルパスは環境に合わせて変更）
export NODE_EXTRA_CA_CERTS=/path/to/corporate-root-ca.pem

# プロキシ設定
export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080

設定後は新しいシェルセッションを開き直してから claude doctor コマンドで接続状態を確認する。

認証エラー（401 / 403）の対処手順

認証まわりのエラーについて、公式エラーリファレンスでは以下のケースが案内されている。

• 403 Forbidden：Pro/Max プランへの未加入、またはConsoleで “Claude Code” ロールが付与されていない場合に発生する。
• OAuth の “Invalid code” エラー：コードの期限切れまたはコピー欠けが原因。再度ログインフローをやり直す。
• “This organization has been disabled…” エラー：ANTHROPIC_API_KEY 環境変数が残存し、Pro/Max 認証より優先されている状態。unset ANTHROPIC_API_KEY してから再実行する。

# APIキー環境変数が残っている場合は解除して再実行
unset ANTHROPIC_API_KEY
claude auth logout
claude auth login
# セッション内で認証状態を確認
/status

Claude Code の料金体系や API キーの取得方法については Claude Code 料金・プラン解説 および Claude Code API料金の詳細 を参照してほしい。CI/CD パイプライン上での認証失敗は、シークレット管理の設定漏れが原因であるケースが大半だ。APIキーをリポジトリ内にハードコードするのは避け、環境変数またはシークレットマネージャー経由で注入する運用を徹底すること。

claude code 動かない原因2：コンテキスト肥大化による応答品質劣化の診断と回復

「雑になった」現象のメカニズム

Claude Code を大規模プロジェクトで使い続けると、「指示を無視する」「出力が雑になった」という品質劣化が起きることがある。セッションが長くなるにつれてコンテキストウィンドウに積み上がる情報量が増え、モデルが「何を優先すべきか」を判断しにくくなる。これが品質低下として表面化する。エラーログには何も残らないため、ハードウェアや接続の問題と誤診されやすい点に注意が必要だ。

コンテキスト管理の実践的手順

公式トラブルシューティングドキュメントでは、コンテキスト肥大化への対処として以下が案内されている。

• /compact コマンドの活用：セッションのコンテキストを定期的に圧縮する。長時間セッションでは定期的に実行する習慣をつけるとよい。
• 大きいディレクトリは .gitignore に追加：不要なファイルをコンテキストに取り込まないようにする。
• セッション再起動：「Autocompact is thrashing」状態になった場合は、大きいファイルを行範囲指定で読むか、サブエージェントに委譲する。
• タスクの細粒化：大きなタスクを小さなセッションに分割し、各セッションでは明確なスコープを持たせる。
• CLAUDE.md の設置：プロジェクトルートに CLAUDE.md を置き、コーディング規約・依存関係・禁止パターンを明示的に記述することで、セッションをまたいでも一定の文脈を引き継がせる。

スラッシュコマンドの詳細については Claude Code スラッシュコマンド解説 を参照されたい。

フィードバックループを構造的に設計する

単発プロンプトへの依存を脱し、テストスイートやリンタをエージェントループに組み込み、Claude Code 自身が出力品質を検証できる環境を整えることが、大規模プロジェクトでの品質劣化を防ぐ根本的な解決策となる。

IPA「SEC journal No.27」はソフトウェア品質確保においてフィードバックループの設計が不可欠であることを論じており（出典：IPA「SEC journal No.27」）、AI エージェントを活用したコーディング支援においても同じ原則が適用できる。テスト実行結果・静的解析結果を Claude Code に自動フィードバックする仕組みを構築することで、品質劣化の早期検知が現実的になる。

claude code 動かない原因3：バージョン不整合とアップデートの運用設計

アップデート速度がもたらすリスク

Claude Code は開発スピードが速く、継続的にアップデートが行われている。古いバージョンを使い続けることで、修正済みのバグを踏み続けるリスクが高まる。数週間放置するだけで現行バージョンとの乖離が大きくなる点に留意されたい。

アップデートの実行手順

# 現在のバージョンを確認
claude --version

# npm 経由でアップデート実行
npm update -g @anthropic-ai/claude-code

# またはバージョンを指定して再インストール
npm install -g @anthropic-ai/claude-code@latest

# アップデート後に詳細診断で状態確認
claude doctor

アップデート後は必ず claude doctor コマンドで接続・認証・依存関係の状態を確認すること。

再インストールが必要な場合の手順

アップデートでも解消しない場合は、公式ドキュメントが案内する完全再インストール手順を試す。まず ~/.local/bin/claude・~/.local/share/claude・~/.claude・~/.claude.json を削除し、以下いずれかの方法で再導入する。

# mac/Linux（公式インストールスクリプト）
curl -fsSL https://claude.ai/install.sh | bash

# Windows（PowerShell）
irm https://claude.ai/install.ps1 | iex

# Homebrew
brew install --cask claude-code

# WinGet
winget install Anthropic.ClaudeCode

# npm
npm install -g @anthropic-ai/claude-code

環境別トラブルシューティング比較表

環境別：claude code 動かない主な原因・症状・対処法

実行環境	典型的な症状	主な原因	対処法
macOS / Linux	command not found	~/.local/bin が PATH 未登録	~/.zshrc または ~/.bashrc に export PATH="$HOME/.local/bin:$PATH" を追記後 source（公式）
企業ネットワーク（プロキシ環境）	証明書エラー・接続タイムアウト（ETIMEDOUT）	SSL証明書・プロキシ未設定	NODE_EXTRA_CA_CERTS / HTTPS_PROXY 設定、curl -I https://api.anthropic.com で疎通確認（公式）
Windows（Git Bash）	nul ファイルが自動生成される	> nul 2>&1 がリテラル解釈される既知バグ（Issue #17886 / #25968）	PowerShell ネイティブで実行。削除は Remove-Item -Path "\\?\<full-path>"
Windows（WSL1）	exec format error	WSL1 非対応（Issue #26006）	wsl --set-version <Distro> 2 で WSL2 へ移行。/mnt/c は I/O が遅いため Linux FS にプロジェクトを配置
大規模プロジェクト（全環境共通）	応答が雑・指示を無視する	コンテキスト肥大化	/compact・セッション分割・CLAUDE.md 設置（公式）
CI/CDパイプライン	401 Unauthorized / 403 Forbidden	APIキー未設定・期限切れ、またはロール未付与	シークレット管理でキーを再設定・環境変数注入に切り替え。ANTHROPIC_API_KEY 残存時は unset（公式）
npm インストール環境	インストール失敗・起動しない	Node.js が 18 未満	Node.js 18 以上にアップグレード（公式）
旧バージョン（全環境共通）	既知バグが再現する・機能が存在しない	アップデート未実施	npm update -g @anthropic-ai/claude-code で最新化

claude code 動かない問題を予防する設計・運用プラクティス

チーム開発でのバージョン固定とCI連携

Claude Code をチーム開発に組み込む場合、使用バージョンを package.json や CI の設定ファイルに明記し、メンバー間の環境差異を排除することが重要だ。「ローカルでは動くのに CI では動かない」という問題の多くは、暗黙のバージョン差に起因する。

# package.jsonでバージョンを固定する例
{
  "devDependencies": {
    "@anthropic-ai/claude-code": "x.x.x"
  }
}

CLAUDE.md による文脈の明示管理

プロジェクトルートに CLAUDE.md を設置し、コーディング規約・依存ライブラリ・禁止パターン・テスト実行コマンドを明示することで、セッションをまたいでも一定の文脈をモデルに引き継がせることができる。これはコンテキスト肥大化問題への構造的な予防策だ。Claude Code の実践的な使い方 でも CLAUDE.md の設計指針を解説している。

自律エージェントへの権限設計

Claude Code がファイル操作やコマンド実行を行う際、権限が不足していると無言で失敗するケースがある。本番環境に近い CI/CD 上では、--allowedTools オプションで利用可能なツールを制限し、必要最小限の権限のみを付与する設計が求められる。

これはセキュリティ上の観点からも重要だ。自律エージェントとしての Claude Code に何をどこまで委譲するかは、エンジニアと組織が明示的に設計・合意すべき問題であり、技術的な設定だけでなくガバナンスの観点からも検討が必要となる。

他ツールとの選定時の確認事項

Claude Code と Cursor や Codex など他のコーディング AI ツールとのトレードオフについては、Claude Code vs Cursor 比較 および Claude Code vs Codex 比較 を参考にしてほしい。ツール選定の段階で各ツールの動作環境要件・認証方式・エージェント動作の仕様を確認しておくことが、後から「動かない」問題を引き起こすリスクを事前に低減する。Claude Code の全体像については Claude Code 総合ガイド も参照されたい。

限界・デメリットについて

本記事で紹介した対処法にも限界がある。CLAUDE.md は有効なコンテキスト管理手段だが、記述内容が古くなれば逆効果になる。定期的なメンテナンスが前提となる。

また、アップデート速度が速いということは、最新バージョン自体に新たなバグが混入しているリスクもある。大型リリースを本番環境にすぐ適用するのではなく、ステージング環境で動作確認を行ってから昇格させる運用が望ましい。

入門・基礎知識の確認には Claude Code スタートガイド も活用してほしい。

まとめ：claude code 動かないときの即時アクションチェックリスト

本記事で解説した内容を、実務で即座に参照できる形に集約する。

1. claude --version でバージョンを確認し、古ければ npm update -g @anthropic-ai/claude-code を実行する（公式）
2. claude doctor コマンドで詳細診断を行い、出力されたエラーメッセージを確認する
3. セッション内 /status で認証状態を確認し、問題があれば claude auth logout → claude auth login で再認証する
4. ANTHROPIC_API_KEY 環境変数が意図せず残存している場合は unset ANTHROPIC_API_KEY してから再実行する（公式エラーリファレンス）
5. 企業環境では NODE_EXTRA_CA_CERTS と HTTPS_PROXY を設定し、curl -I https://api.anthropic.com で疎通確認する
6. command not found の場合は ~/.local/bin（mac/Linux/WSL）または %USERPROFILE%\.local\bin（Windows）を PATH に追加する（公式）
7. 応答品質が低下している場合は /compact でコンテキストを圧縮し、セッションを再起動する（公式）
8. 大規模プロジェクトではセッションを細粒化し、CLAUDE.md でコンテキストを構造的に管理する
9. WSL 環境では WSL2 を使用し、プロジェクトを Linux FS 上に配置する（Issue #26006）
10. CI/CD 環境ではバージョンを package.json で固定し、APIキーをシークレット管理経由で注入する

「claude code 動かない」という状況は、原因カテゴリさえ正確に特定できれば、大半のケースは手順通りの操作で解消できる。「動かない」と感じた瞬間にエラーメッセージの有無を確認し、本記事の切り分けフローに沿って診断を進めてほしい。

---

弊社が開発する DeepAI について：弊社クリスタルメソッドでは、機械学習・深層学習（CNN）を用いた2D画像認識・異常検知ソリューション「DeepAI」を開発・提供している。ソファーのような不定形物の画像分類（正常・異常判定）など、形状が定まらない対象の異常検知を得意としており、弊社での取り組みの中で約99%の精度を実現している事例がある。AI活用を製造・品質管理領域に広げたい場合は、DeepAI もあわせて検討いただきたい。

---

参考文献

• Anthropic 公式「Claude Code セットアップガイド」
  https://code.claude.com/docs/en/setup
• Anthropic 公式「Claude Code インストールトラブルシューティング」
  https://code.claude.com/docs/en/troubleshoot-install
• Anthropic 公式「Claude Code トラブルシューティング（動作・パフォーマンス）」
  https://code.claude.com/docs/en/troubleshooting
• Anthropic 公式「Claude Code エラーリファレンス」
  https://code.claude.com/docs/en/errors
• GitHub anthropics/claude-code Issue #17886（Git Bash で nul ファイルが生成される問題）
  https://github.com/anthropics/claude-code/issues/17886
• GitHub anthropics/claude-code Issue #25968（Git Bash nul ファイル関連）
  https://github.com/anthropics/claude-code/issues/25968
• GitHub anthropics/claude-code Issue #26006（WSL1 exec format error）
  https://github.com/anthropics/claude-code/issues/26006
• IPA「SEC journal No.27」
  https://www.ipa.go.jp/archive/files/000024514.pdf

関連記事

• Claude Codeとは（基本ガイド）
• Claude Codeを日本語化する方法
• Claude Codeの使用量・制限を確認する方法
• Claude CodeをVSCodeで使う方法
• Claude Codeのセキュリティと安全な使い方