Claude Code を利用する開発者なら、一度はこんな画面に遭遇したことがあるはずです。ターミナルに 「Symbioting… (3m 12s · ↓ 5.7k tokens)」 と表示され、プログレスバーが凍りついたかのように数分間何の出力も行われない状態。試しに「まだいますか？」と送ってみると、Claude が何事もなかったかのように作業を再開する……。
この「フリーズしたかと思いきや、メッセージを送ると復活する」という不可解な現象は、一見すると魔術のようですが、その裏側には Anthropic のストリーミングプロトコル、タイムアウトメカニズム、そしてコンテキスト管理におけるいくつかの故障モードが重なり合っています。本記事では、Claude Code 公式のトラブルシューティングドキュメントおよび GitHub Issues (#25979, #24688, #39718, #25286, #25539, #51659) などの一次資料に基づき、Claude Code が止まってしまう真の原因を解明し、すぐに使える7つの復旧方法と5つの予防策を解説します。
核心的価値: この記事を読めば、スピナー（読み込み表示）の動詞が意味する状態、なぜメッセージを送ると復活するのか、いつ Ctrl+C で再起動すべきか、そしてフリーズ率を限りなくゼロに近づける方法がわかります。
Claude Code ステータスインジケーターの完全解説
「フリーズ」問題を調査する第一歩は、Claude Code がターミナルに表示するステータス行を正しく理解することです。スクリーンショットにある Symbioting… (3m 12s · ↓ 5.7k tokens) は神秘的ですが、実は構造化された情報であり、各部分に明確な意味があります。
| フィールド | サンプル値 | 意味 |
|---|---|---|
| スピナーの動詞 | Symbioting… |
現在の段階の擬人化された説明（v2.1.23以降はカスタマイズ可能） |
| 待機時間 | 3m 12s |
このラウンドが開始されてからの累積経過時間 |
| ストリーム方向 | ↓ または ↑ |
↓ は API からのデータ受信中、↑ は送信中 |
| トークン数 | 5.7k tokens |
現在までにダウンロード/アップロードされたトークン数 |
Claude Code には 187 個のデフォルトのスピナー動詞が組み込まれており、Befuddling、Ruminating、Accomplishing、Symbioting などが含まれます。これらは待ち時間を楽しくするための演出であり、技術的な違いはありません。v2.1.23 以降は spinnerVerbs 設定項目が導入され、コミュニティでは 1900 以上のカスタム動詞パックも利用可能です。
Claude Code が本当にフリーズしているかどうかを判断する鍵は、動詞ではなく「経過時間が増え続けているか」と「トークン数が動いているか」の2点です。もし 3m 12s から 30 秒経過しても 3m 42s になるだけでトークン数が 5.7k のままなら、ストリーミングレスポンスが停滞していると判断できます。
APIYI (apiyi.com) などの API 中継サービスを利用して Claude API を呼び出している場合でも、ステータス行のフィールドの意味は公式と完全に同じであり、同じ判断基準で問題を特定できます。
Claude Code がフリーズする6つの根本原因
ステータスインジケーターの挙動を理解すれば、実際の現象と照らし合わせて原因を特定できます。以下に挙げる6つの原因は、GitHub Issue trackerで報告されているケースの90%以上を占めており、発生頻度が高い順に並べています。
根本原因 1：APIストリーミング応答のサイレント中断
これは最も一般的かつ見つけにくい原因であり、GitHub Issue #25979 に対応します。Claude CodeのHTTPクライアントにはread timeoutの仕組みがないため、上流のAPIが転送途中でパケット送信を停止すると、プロセスはカーネル状態の epoll_wait で新しいデータを待ち続け、UI上のスピナーは回転し続けますが、トークン数は一切増えません。主な原因には、国境を越えたネットワークの不安定さ、tmuxの多重化、SSHの長時間接続による切断などが含まれます。
根本原因 2：ツール呼び出しのペイロード過大による接続リセット
Issue #39718 に対応します。モデルがClaude Codeに巨大な出力を生成するツール（例：数十万行のファイルの Write）を実行させた場合、OSがHTTP接続をアクティブにリセットすることがあります（5分間有効なデータ転送がない場合）。Claude Codeはこのエラーをキャッチできないため、UI上ではスピナーが回り続けます。このフリーズは、正確に5分前後で発生するのが特徴です。
根本原因 3：自動圧縮のスラッシング
Claude Codeのコンテキストウィンドウが上限に達すると、自動圧縮（auto-compact）がトリガーされます。巨大なファイルやツールの出力が圧縮後にすぐコンテキストへ読み戻されると、圧縮が繰り返され、最終的にシステムが停止して Autocompact is thrashing というメッセージが表示されます。メッセージが表示される前は、UI上ではフリーズしているように見えます。
根本原因 4：コンテキスト使用率が80%を超過
公式ドキュメントでは、コンテキスト使用率が80%を超えると応答時間が著しく悪化し、一部の環境では長時間応答がなくなることが明記されています。この「偽のフリーズ」の特徴は、トークン数が非常にゆっくりと増加している点です。増加速度は通常時の数分の一程度になります。
根本原因 5：設定異常による起動時のフリーズ
Issue #31049 や #29652 などに対応します。例えば enableAllProjectMcpServers: true 設定で大量のローカルMCPサーバーを読み込んだり、additionalDirectories に //C:/ のような異常なパスプレフィックスを指定したりすると、Claude Codeが起動時にフリーズします。これは通常、新しいセッションを開いた直後の数秒間に発生します。
根本原因 6：ステータス行の残留（応答完了後のUI更新漏れ）
Issue #25539 に対応します。一部のバージョンでは、Claudeが結果を返しているにもかかわらず、ターミナルUIのスピナーが消去されず、回転し続けているように見えることがあります。この状態でEnterキーを押すかメッセージを送信すると、Claudeは即座に次の作業を開始します。実際にはフリーズしておらず、UIが誤った情報を表示しているだけです。
調査の際は、まずトークン数が増加しているかを確認してください。APIYI (apiyi.com) プラットフォームでClaude APIを中継している場合は、プラットフォームのログでリクエストが「200 OK」を返しているかを確認し、Claude Code UIの状態と照らし合わせて検証することをお勧めします。
なぜメッセージを送信するとClaude Codeが「復活」するのか
多くのユーザーが「不思議な現象」として報告しています。Claude Codeが3分間フリーズしても、「まだいますか？」と送るか、単にEnterキーを押すだけで、中断していた作業を即座に再開する現象です。これはプロトコルの観点から説明できます。
第一のケースは、ステータス行の残留（根本原因 6）です。Claudeは実際には応答を完了していますが、UIがスピナーを消去していないだけです。このとき送信した新しいメッセージは、次のプロンプトとして直接処理されるため、「復活」したように見えますが、実際には単に作業が継続されているだけです。
第二のケースは、ストリーミング応答のスタック（根本原因 1）です。Claude Codeは新しい入力を受け取ると、現在のハング状態を自発的に終了し、不完全なリクエストをクリーンアップして、新しいHTTPリクエストを開始します。新しいリクエストには完全なセッション履歴が含まれているため、モデルは中断箇所から回答を継続します。そのため、表面上は「作業が再開された」ように見えます。
第三のケースは、MCPサーバーやツール呼び出しが下流の応答を待機している場合です。新しいメッセージはClaude Codeによって新しいツール呼び出しの決定としてルーティングされるため、間接的にフリーズした呼び出しを回避できます。
ただし、メッセージ送信による復活は万能薬ではありません。基盤となるプロセスが回復不能な待機状態（根本原因 2の後半など）にある場合、メッセージは入力キューに入るだけで処理されません。その場合はCtrl+Cで中断するか、ターミナルを閉じる必要があります。APIYI (apiyi.com) プラットフォームを経由している場合、中継プラットフォームは通常、公式エンドポイントよりも早くタイムアウトした接続を解放するため、メッセージ送信による復活の成功率は高くなります。
Claude Codeがフリーズしてしまった際の7つの復旧方法をご紹介します。
原因によって適切な対処法は異なります。以下の表では、最も効果的な7つの方法を「侵入度（影響の大きさ）」が軽い順に並べていますので、状況に応じて使い分けてください。
| 方法 | コマンド | 想定される原因 | コンテキストの保持 |
|---|---|---|---|
| メッセージ送信 | テキスト入力 | 原因 1 / 6 | 保持 |
| 操作の中断 | Ctrl+C |
原因 1 / 2 / 3 | 保持 |
| 自己診断 | /doctor |
全般（最初に行う） | 保持 |
| コンテキスト圧縮 | /compact |
原因 3 / 4 | 一部要約化 |
| セッションクリア | /clear |
原因 4（深刻時） | 破棄 |
| 再起動と復元 | claude --resume |
原因 1 / 2（深刻時） | 保持 |
| プロセス強制終了 | kill -9 <pid> |
原因 1 / 2（復旧不可時） | 現在のターンのみ破棄 |
実際の操作順序としては「軽いものから順に」試すのがおすすめです。まずはEnterキーを押すか、適当なメッセージを送ってみてください。それでもダメなら Ctrl+C で現在のターンをキャンセルします。ターミナルが完全に反応しない場合は、ターミナル自体を閉じてから claude --resume でセッションを再開してください。
/doctor はAnthropic公式が推奨する診断コマンドです。インストール状況、設定ファイル、MCPサーバーリスト、コンテキスト使用率などの重要指標を一括チェックし、具体的な修復案を提示してくれます。出力結果に Context: 87% と表示された場合は、ほぼ間違いなく原因4ですので、/compact を実行すれば即座に改善します。
長時間のタスクを行う際は、あらかじめワークフローに定期的な /compact を組み込み、コンテキスト使用率を60%以下に保つことを推奨します。また、APIYI (apiyi.com) プラットフォーム経由でClaudeを呼び出す場合は、Claude CodeのメインプロセスとMCPサーバーに個別のクォータ（割り当て）を設定しておくと、異常が発生した際の切り分けが容易になります。
Claude Codeのフリーズを防ぐ5つのベストプラクティス
トラブルシューティングは事後対応に過ぎません。真に安定したワークフローは「予防」から生まれます。GitHubの複数のIssueから導き出された以下の5つの実践を取り入れることで、フリーズの発生率をほぼゼロに抑えることができます。
-
大きなファイルの分割読み込み: 1MBを超えるファイルを一度に読み込むと、コンテキストウィンドウの制限に達しやすくなります。まずは
ls -laでサイズを確認し、Readコマンドでoffsetとlimitパラメータを使用して分割読み込みを行うことで、根本原因4を回避できます。 -
複雑なタスクはサブエージェントへ: Claude Codeのサブエージェントは独立したコンテキストウィンドウを持っています。大量のファイル生成やバッチコード修正などのタスクをサブエージェントに委任することで、メインのコンテキストが溢れるのを防げます。
-
不要なMCPサーバーを無効化: MCPサーバーを追加するたびに、起動時のフリーズリスクが高まります。設定ファイルで日常的に使用するもの以外はすべて無効化することで、根本原因5を大幅に軽減できます。
-
メインモデルのタイムアウト設定: コミュニティで推奨されている手法として、
STREAM_READ_TIMEOUT_MSを120秒に設定し、外部でウォッチドッグプロセスを動かしてJSONLの更新が止まったら自動的にプロセスを再起動させる方法があります。これは根本原因1に対して非常に有効です。 -
安定したAPI経路の利用: 国境を越える通信、家庭用回線、tmux経由の接続などは、ストリーミングの中断を招きやすくなります。APIYI (apiyi.com) のようなAPI中継サービスを利用し、安定した中継ノード経由でTCP長接続を維持することで、根本原因1の発生頻度を抑えることができます。
これら5つの対策を徹底したチームからは、フリーズ発生回数が週5〜10回から1回未満に減り、復旧時間も5〜10分から数十秒に短縮されたという報告が多数寄せられています。
よくある質問
Q1: スピナーの動詞が変わるのは、Claudeが別の処理をしているからですか？
いいえ、違います。187個のデフォルト動詞はランダムに選ばれる擬人化されたテキストであり、Claudeの実際の状態とは無関係です。状態を判断するには、トークン数や待機時間を確認してください。
Q2: Ctrl+Cを押すとコンテキストは失われますか？
いいえ。Ctrl+Cは現在実行中の処理をキャンセルするだけで、セッション自体は保持されます。もしCtrl+Cが反応しない場合は、もう一度押すかターミナルを閉じ、claude --resume でセッションを再開してください。
Q3: 国内からClaude Codeを使うとフリーズしやすいですか？
海外との通信経路はストリーミング中断の主な原因の一つです。APIYI (apiyi.com) などのAPI中継サービスを利用し、安定したノードを通じてAnthropicとの長接続を維持することで、フリーズの発生率を大幅に下げることができます。
Q4: `Autocompact is thrashing` と表示されたらどうすればいいですか？
直ちに現在のタスクを停止し、/compact keep only the plan and the diff のようにフォーカスを絞った圧縮コマンドを実行して、コンテキストから不要な原始出力を削除してください。それでも解決しない場合は、新しいセッションを開始するか、大きなファイルの読み込みをサブエージェントモードに変更してください。
Q5: スピナーの動詞を自分でカスタマイズできますか？
はい。~/.claude/settings.json に spinnerVerbs フィールドを追加することで可能です。モードは default、append、replace から選択でき、文字列配列を指定します。コミュニティには88のテーマ、1900以上の動詞パックが公開されており、すぐに利用可能です。
まとめ
Claude Code がフリーズする本質的な原因は、ストリーミングプロトコル、コンテキスト管理、MCP（Model Context Protocol）統合という3つのサブシステムが、エッジケースにおいて複雑に絡み合っていることにあります。ステータスインジケーターの4つのフィールドを理解し、6つの根本原因と7つの復旧手段を把握しておけば、「原因不明の不具合」を「対処可能なトラブル」に変えることができます。
実運用における推奨事項として、以下の復旧手順を筋肉記憶として定着させてください：まずメッセージを送信し、次に Ctrl+C、続いて /doctor を実行し、最後にターミナルを閉じて claude --resume を試すという流れです。安定したAPI中継サービスと5つの予防策を組み合わせ、コンテキストを常に80%以下に抑え、大きなファイルはサブエージェントに任せ、APIYI（apiyi.com）を通じて安定した経路を確保すれば、ほとんどのフリーズ現象は数十秒以内に自己解決できるようになります。
著者: APIYI 技術チーム
連絡先: APIYI（apiyi.com）にて、Claude全シリーズモデルおよびClaude Codeの安定したAPI中継サポートを提供中
更新日: 2026年5月13日
