トラブルシューティング

Claude Code が起動したあとに起きる、性能・安定性・表示・検索の問題の対処をまとめたページです。ここに無い症状は、下の表で、該当するページへ進んでください。原因が分からないときは、Claude Code の中で /doctor を実行すると、インストール・設定・拡張・文脈の使用量を自動で点検し、直せるものは確認のうえで直す案を出します。

• claude が起動しないときは、シェルから claude doctor を実行します
• MCP サーバーの状態は /mcp で確認します
• 設定が効かない・フックが動かない場合は 設定のデバッグ を見ます

症状から探す#

性能と安定性#

CPU やメモリの使用量が高い#

大きなコードベースを処理すると、リソースを多く使うことがあります。

1. /compact をこまめに使って文脈を小さくします。Not enough messages to compact. と返るなら、要約するにはターン数が少なすぎます。1回の大きな貼り付けで文脈が埋まった場合は、文脈が満杯でも起こりえます
2. 大きな作業の合間に Claude Code を閉じて再起動します
3. 大きなビルドのディレクトリを .gitignore に足すことを検討します
4. claude --safe-mode で再起動して、プラグイン・MCP サーバー・フックが原因かを確かめます。そのセッションでカスタマイズをすべて無効にするので、使用量が下がるなら、設定のデバッグ の手順でどれが原因かを探します

session のヒープメモリが 2.5GB を超えると、メモリ使用量が危険な水準だという警告が出ます。メモリを解放するには、Claude Code を再起動し、claude --continue で新しいプロセスに会話を再開します。フルスクリーン表示（ターミナル・表示・音声入力）以外では、/compact を実行してもメモリが解放されます。使用量が 2.5GB を下回ると、警告は消えます。

これらの後もメモリが高いままなら、/heapdump を実行します。~/Desktop に2つのファイルを書き出します。

• このコマンドは、コマンドメニューには出ません。最後まで入力します
• Desktop のフォルダーが無い Linux では、ホームディレクトリに書き出されます
• 会話の中にも要約が出ます。プロセスの総メモリ・JS ヒープの量・ヒープの外の量・リークの兆候（メモリの増加率が高い、開いているハンドルが異常に多い、など）です。メモリの大半が、スナップショットが捉える JS ヒープなのか、捉えないネイティブメモリなのかも分かります

報告する場合は、GitHub の issue を開き、-diagnostics.json だけを添付します（印刷された要約の元の統計だけで、会話の内容や認証情報は含みません）。自分で調べるなら、要約が「メモリの大半は JS ヒープ」と言うとき、.heapsnapshot を Chrome DevTools の Memory で読み込み、retained size で並べて、何がメモリを保持しているか見ます。大半がネイティブなら、スナップショットでは見えないので、要約のリークの兆候を報告に含めます。

ターミナルで大きな表が切れる#

200 行を超える Markdown の表は、最初の 200 行と、… N more rows not shown の行が表示されます。制限されるのは表示だけで、表全体は会話に残り、/copy はすべての行をコピーします。ターミナルで読むには大きすぎる表は、Claude にファイルへ書かせます。v2.1.208 より前は、全行を描画していたので、非常に大きな表を含むセッションを再開すると、再描画で止まることがありました。

自動圧縮が thrashing のエラーで止まる#

Autocompact is thrashing: the context refilled to the limit... が出るときは、自動圧縮は成功したのに、ファイルやツールの出力が、続けて何度も文脈を埋め直した状態です。進展のないループで API 呼び出しを無駄にしないよう、Claude Code は再試行をやめます。

1. 大きなファイルを丸ごとでなく、特定の行の範囲や関数など、小さな塊で読むよう Claude に頼みます
2. 大きな出力を捨てる焦点を付けて /compact を実行します（例：/compact keep only the plan and the diff）
3. 大きなファイルの作業を サブエージェント に移し、別の文脈ウィンドウで動かします
4. これまでの会話が要らなければ /clear を実行します

/clear のあとにまた出るときは、/context を実行し、Messages の行をそれより上の行と比べます。

• Messages が最大の行：新しい会話の中のファイルやツールの出力が、ウィンドウをまた埋めています。上の手順 1〜3 をやり直します
• ほかの行の合計のほうが大きい：起動時に読み込むものが多く、作業に使える余地が足りません。起動時に読み込むものを減らします（エラー一覧）

仕組みは コンテキストとプロンプトキャッシュ を見てください。

コマンドが固まる・応答しない#

1. Ctrl+C で現在の操作の取り消しを試します
2. 応答しなければ、ターミナルを閉じて再起動します

再起動しても会話は失われません。同じディレクトリで claude --resume を実行すると、セッションに戻れます（セッションの再開と管理）。

表示と操作#

エディタの統合ターミナルで文字化けする#

VS Code・Cursor・Devin Desktop の統合ターミナルで Claude Code を動かして、文字が四角・にじみ・違う字形になるなら、ターミナルの GPU レンダラーが原因の可能性が高いです。Claude Code の中で /terminal-setup を実行すると、terminal.integrated.gpuAcceleration が "off" に設定されます。エディタの設定で手動で設定してウィンドウを再読み込みしてもかまいません。/terminal-setup が書くほかの設定は ターミナル・表示・音声入力 を見てください。

フルスクリーン表示でマウスホイールが1行ずつしか動かない#

フルスクリーン表示では、Claude Code が会話のスクロールを自分で行います。ホイールの1目盛りの行数が足りなければ、/scroll-speed で1目盛りの行数を上げて保存するか、環境変数 CLAUDE_CODE_SCROLL_SPEED を設定します。JetBrains の IDE のターミナルは、Claude Code が独自のスクロール処理を使うため、どちらも効きません。受け付ける値は ターミナル・表示・音声入力 を見てください。

• 速度を変えずに速く動くには、PgUp と PgDn で半画面ずつスクロールします
• ターミナル本来のスクロールバックを使うには、/tui default で従来のレンダラーに切り替えます

サンドボックスの中で pbcopy などのクリップボードのコマンドが失敗する#

サンドボックス が有効だと、pbcopy・xclip・wl-copy などのクリップボード用ツールが、サンドボックス内の Bash コマンドからシステムのクリップボードに届かないことがあり、Claude がテキストをパイプしても、クリップボードが変わりません。

Claude の出力をクリップボードに入れるには、内容を応答に出力させてから /copy を実行します。/copy は、サンドボックス内のコマンドでなく、Claude Code のプロセス自身からクリップボードに書くので、サンドボックスに止められません。応答全体でなく1つのコードブロックだけをコピーでき、コピーした内容をファイルにも書いてパスを出すので、SSH のようにクリップボードへの書き込みが端末に届かないときの代替になります。

SSH 越しにコピーしたテキストが手元のクリップボードに届かない#

リモートのマシンで Claude Code を SSH 越しに動かすと、手元のマシンのクリップボード用ツールを実行できません。tmux の外では、フルスクリーン表示でテキストを選択するか /copy を実行すると、Claude Code は代わりに OSC 52 のエスケープシーケンスをターミナルへ送ります。クリップボードに入れるかどうかは、ターミナルが決めます。/copy は、テキストが届いたかに関わらず Copied to clipboard と表示し、tmux の外では、選択の通知が sent N chars via OSC 52 と出ます。

OSC 52 に対応していないターミナルがあります。iTerm2 は、「Settings > General > Selection > Applications in terminal may access clipboard」を有効にするまで無視し、macOS の Terminal.app は対応していません。OSC 52 を使わずにテキストを得る方法です。

• ターミナルのネイティブ選択キーを押しながらドラッグし、ターミナルの通常のショートカット（Cmd+C など）でコピーする。キーは Terminal.app では Fn、iTerm2 では Option。ほかのターミナルは ターミナル・表示・音声入力 を見てください
• リモートのマシンで CLAUDE_CODE_DISABLE_MOUSE=1 を設定し、セッション全体で、選択をターミナルに処理させる

検索と検出#

Search ツール・@file の参照・カスタムエージェント・カスタムスキルがファイルを見つけないなら、組み込みの ripgrep のバイナリがそのシステムで動かない可能性があります。プラットフォームの ripgrep パッケージを入れて、Claude Code にそちらを使わせます。

そのうえで USE_BUILTIN_RIPGREP を 0 にします。シェルの環境変数でも、settings.json の env ブロックでもかまいません。

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

切り替わったかは、ターミナルで claude doctor を実行し、Search の行が OK (bundled) でなく、システムの ripgrep のパスを示すかで確かめます。

WSL で検索が遅い・結果が少ない#

WSL で、ファイルシステムをまたいで作業すると、ディスクの読み取り性能が落ち、期待より少ない一致しか返らないことがあります。検索は動きますが、ネイティブのファイルシステムより結果が少なくなります。

1. 検索を具体的にします。ディレクトリやファイルの種類を指定して、検索するファイル数を減らします（例：「Search for JWT validation logic in the auth-service package」「Find use of md5 hash in JS files」）
2. プロジェクトを Linux のファイルシステム（/home/）に置きます。Windows のファイルシステム（/mnt/c/）は避けます
3. ファイルシステムの性能のため、WSL でなくネイティブの Windows で Claude Code を動かすことを検討します

さらに助けを得る#

1. /doctor で環境の点検を、/mcp で MCP サーバーの状態を確認する
2. Claude Code の中の /feedback で、問題を Anthropic に直接報告する
3. GitHub のリポジトリで既知の問題を確認する
4. Claude 自身に、できることや機能を聞く。Claude は自分のドキュメントを組み込みで参照できる

アカウント・請求・サブスクリプションの問題は、Anthropic のサポートへ連絡します。claude.ai にサインインし（Console のユーザーは platform.claude.com）、左下のイニシャルから「Get help」を選びます。