メインコンテンツまでスキップ

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

中級
What you'll learn
  • 症状の表を使って、Claude Codeのあらゆる問題をワンステップで対処法にたどり着かせる
  • 手作業でデバッグを始める前に、たいていのセットアップ問題を解決する2つの診断コマンドを実行する
  • プラグイン、MCPサーバー、フックのどれが真の原因かを切り分ける
  • 典型的な4つのランタイム障害を直す: メモリ肥大、ハング、コンパクションのスラッシング、検索が何も見つけない
  • バグ報告を出す前に、適切な証拠を集める

大きな考え方​

Claude Codeの問題はほぼすべて2種類のどちらかであり、その対処法はまったく異なります:

  • セットアップが間違っている — プラグイン、MCPサーバー、フック、設定ファイル、足りないバイナリ。対処法は設定です。
  • セッションに負荷がかかっている — コンテキストウィンドウが一杯、巨大なファイルがメモリを膨れ上がらせた、ターミナルが描画できない。対処法は衛生管理です。

どちらなのかを当てずっぽうで探るのが、人が午後をまるごと失うポイントです。下の表は、その当てずっぽうを省きます。

:::tip 別の種類の「おかしさ」ですか？ このページはツールの不具合についてです — 起動しない、ハングする、検索が何も見つけない。モデルの挙動がおかしい場合 — 事実をでっち上げた、指示を忘れた、まっとうな依頼を拒否した — それは別のページです: Claudeはなぜそうしたのか？ :::

ここから始める: 症状 → 行き先​

自分の症状を見つけてください。このページの残りは読まなくて構いません。

症状行き先
command not found、インストール失敗、EACCES、PATH や TLS のエラー公式: インストールとログイン
ログインのループ、OAuthエラー、403 Forbidden、「organization disabled」公式: ログインと認証
設定が反映されない、フックが発火しない、MCPサーバーが読み込まれない下の設定を切り分ける
API Error: 5xx、529 Overloaded、429、バリデーションエラーエラーとレート制限
model not found / 「アクセス権がない可能性があります」最新のモデルと料金
VS Code や JetBrains が Claude を検出しないIDE統合
CPU やメモリの使用率が高い下のメモリとCPU
ハング、フリーズ、無反応下のハングとフリーズ
Autocompact is thrashing下のコンパクションのスラッシング
検索、@file、エージェント、Skillがファイルを見つけられない下の検索が何も見つけない
IDEのターミナルで四角、にじみ、誤ったグリフが出る下のターミナルの文字化け

まず実行すべき2つのコマンド​

手作業でデバッグを始める前に、組み込みの健康診断を実行しましょう。インストール、設定、拡張機能、コンテキスト使用量を診断し、確認のうえ適用できる修正を提案してくれます。

Guided walkthrough1 of 3
  1. /doctor（エイリアスは /checkup）は、インストール、設定、拡張機能、コンテキスト使用量を検査し、適用できる修正を提案します。これだけで、セットアップに関する不満のほとんどは解決します。

壊れたセットアップを診断する

# inside a session
/doctor

# if the session won't start at all
claude doctor

# check MCP server status
/mcp

設定を切り分ける​

設定が反映されない、フックが発火しない、あるいは単に何かがおかしいとき、問うべきは「何が壊れているか」ではありません — 自分のカスタマイズのどれが壊れているかです。それは、すべてを一度に取り除くことで答えられます。

--safe-mode は、あらゆるカスタマイズを無効にしてClaude Codeを起動します: プラグインなし、MCPサーバーなし、フックなし。

クリーンな設定で試す

claude --safe-mode

これにより、きれいな二択の結果が得られます:

カスタマイズが原因だと分かったら、二分探索しましょう: 問題が再発するまで、グループ単位で再有効化していきます。犯人になりやすい順に並べると、MCPサーバー、フック、プラグイン、設定です。

Pro tip
  • --safe-mode は、あからさまな故障だけでなく、原因不明の遅さに対しても正しい第一手です。おしゃべりなMCPサーバーは、その両方の非常によくある原因です。

メモリとCPU​

Claude Codeはたいていの環境で動作しますが、大規模なコードベースでは相応のリソースを消費することがあります。安いものから順に並べてあるので、上から順に試してください。

Guided walkthrough1 of 5
  1. /compact を実行してコンテキストを縮小します。コンテキストウィンドウの肥大は、セッションが重くなる最大の原因です。/docs/claude-code/context-management を参照してください。

/heapdump の内訳は、レジデントセットサイズ、JSヒープ、array buffer、および計上されていないネイティブメモリを報告します。この内訳こそが有用な部分です: メモリの増加がJavaScriptオブジェクトにあるのか、それともネイティブコード側にあるのかが分かります。何がメモリを保持し続けているかを調べるには、.heapsnapshot ファイルを Chrome DevTools の Memory → Load で開いてください。

ハングとフリーズ​

Claude Codeが応答しなくなったら:

Guided walkthrough1 of 3
  1. Ctrl+C を押します。セッションを終了させずに、実行中の処理を中断します。
Pro tip
  • 長い会話を失うのが怖いからこそ、人はハングを終了させずに耐えてしまいます。その必要はありません — 同じディレクトリで claude --resume を実行すればセッションは戻ってきます。

コンパクションのスラッシング​

このエラーは不穏に見えますが、実際には保護です:

Autocompact is thrashing: the context refilled to the limit...

これは、自動コンパクションが成功したことを意味します — そのうえで、ファイルやツールの出力が即座にコンテキストウィンドウ全体を埋め直す、という事態が数回続いたのです。Claude Codeは、前進していないループでAPI呼び出しを浪費するより、リトライをやめます。

原因はほぼ常に、大きすぎる何かを丸ごと読み込んでいることです。自分の状況に合う対処法を選んでください:

状況対処法
巨大なファイル1つが問題ファイル全体ではなく、行範囲や単一の関数を読むようClaudeに頼む
もう不要な大きな出力がコンテキストにあるそれを捨てるフォーカスを付けて /compact
その大きな読み込みが本当に必要サブエージェントに移し、別のコンテキストウィンドウを消費させる
それまでの会話がもう重要でない/clear

肥大を捨てるフォーカス付きでコンパクトする

/compact keep only the plan and the diff

サブエージェントという選択肢は忘れられがちですが、多くの場合これが最善です: サブエージェントは自分のコンテキストで巨大なファイルを読み、結論だけをあなたのコンテキストに返します。コンテキスト管理とサブエージェントを参照してください。

検索が何も見つけない​

Searchツール、@file メンション、カスタムエージェント、カスタムSkillが、存在すると分かっているファイルを見つけられない場合、同梱の ripgrep バイナリがあなたのシステムで実行できていない可能性が高いです。対処法は、プラットフォーム純正の ripgrep をインストールし、それを使うようClaude Codeに伝えることです。

Guided walkthrough1 of 3
  1. macOS: brew install ripgrep — Ubuntu/Debian: sudo apt install ripgrep — Alpine: apk add ripgrep — Arch: pacman -S ripgrep — Windows: winget install BurntSushi.ripgrep.MSVC

macOSで検索を直す

brew install ripgrep
export USE_BUILTIN_RIPGREP=0

WSLという例外​

WSLでは、検索結果が不完全なのはたいてい壊れたバイナリのせいではありません。Windows/Linux間のファイルシステム境界をまたぐ読み込みにはディスク性能上のペナルティがあるため、検索は期待より少ない件数を返します。検索は動いてはいます — ただ、取りこぼすのです。

Watch out
  • WSLでは、結果が不完全であっても claude doctor は Search を OK と報告します。診断が緑でも、この可能性は排除できません — まさにそれが、この問題の診断を難しくしています。

抜け出す方法は3つ、良い順に: プロジェクトを /mnt/c/ ではなく Linux のファイルシステム（/home/）へ移す。WSL経由ではなく Windows でネイティブに Claude Code を動かす。あるいは検索対象のファイルが減るよう検索を絞り込む — 「auth のコードを探して」より「auth-service パッケージ内の JWT 検証ロジックを検索して」の方が優れています。

ターミナルの文字化け​

VS Code、Cursor、Devin Desktop の統合ターミナル内で、文字が四角、にじみ、誤ったグリフとして描画されるのは、GPUレンダラーの問題であり、フォントやエンコーディングの問題ではありません。

IDEターミナルのグリフ化けを直す

/terminal-setup

これは terminal.integrated.gpuAcceleration を "off" に設定します。エディタの設定で手動で設定し、ウィンドウを再読み込みしても構いません — 結果は同じです。

大きな表が途中で切れる​

200行を超えるMarkdownの表は、最初の200行を描画し、続けて … N more rows not shown という行を表示します。これは表示上の上限のみです — 表の全体は会話の中に残っており、/copy はすべての行をコピーします。ターミナルで読むには大きすぎる表なら、ファイルに書き出すようClaudeに頼みましょう。

良いバグ報告を出す​

ここに当てはまるものが何もなければ報告してください — ただし証拠を携えて。「遅いです」という報告はどこにも行き着きませんが、ヒープスナップショットと --safe-mode の結果が付いた報告は修正されます。

Guided walkthrough1 of 4
  1. 健康診断の内容と、実際に読み込まれているMCPサーバーを記録します。報告されるバグの半分はここで答えが出ます。
Key takeaways
  • まず /doctor（エイリアス /checkup）を実行する — セッションが起動しないなら、シェルから claude doctor として実行します。インストール、設定、拡張機能、コンテキスト使用量を診断し、修正を適用できます。
  • claude --safe-mode はすべてのカスタマイズを一度に無効化します。問題がそれを生き延びるかどうかは、集められる中で最も情報量の多い事実です。
  • メモリ肥大: /compact、タスク間の再起動、ビルドディレクトリの .gitignore、次に --safe-mode、そして証拠として /heapdump。
  • ハングは会話の喪失ではありません — Ctrl+C、次にターミナルを再起動、そして同じディレクトリで claude --resume。
  • Autocompactのスラッシングは、大きすぎる読み込み1つがウィンドウを埋め直していることを意味します。分割して読む、フォーカス付きで /compact、あるいは読み込みをサブエージェントに委ねましょう。
  • 検索が何も見つけないのは、たいてい同梱の ripgrep が実行できないためです: プラットフォームの ripgrep をインストールし、かつ USE_BUILTIN_RIPGREP=0 を設定しましょう。WSLではファイルシステム境界のペナルティが原因で、しかも claude doctor は Search を OK と報告し続けます。

理解度チェック

0/5
  1. フックが発火せず、設定も無視されているようです。試すべき最も情報量の多いことは何ですか？
  2. Claude Codeがタスクの途中でハングし、Ctrl+C も効きません。ターミナルを閉じます。会話はどうなりますか？
  3. 「Autocompact is thrashing: the context refilled to the limit...」と表示されました。実際には何が起きたのですか？
  4. @file メンションが何も見つけないので brew で ripgrep をインストールしましたが、検索はまだ壊れています。何を見落としましたか？
  5. WSLで、検索が期待より少ない件数しか返さないのに claude doctor は Search を OK と報告します。何が起きていますか？

次へ​