Claude Code リモート切断のトラブルシューティング：6種類の切断パターンの症状・判定基準・対処法

Claude Code をリモートで実行する際、最も辛いのは接続できないことではなく、接続できても切断されること、しかも毎回切断の原因が異なることです。

「切断」という言葉は実際には6種類のまったく異なる障害を一括りにしています。それぞれ現象に特徴があり、対処法も互いに関連しません——ネットワーク切り替えによる長期間接続の失効をマシンのスリープとして処理しても、スリープを無効にしても効果はありません。半死接続をネットワーク不良だと思って待っていても、夜が明けても自然に回復することはありません。

この記事では実際に目にする現象から原因を逆算します：各切断パターンについて症状、確認方法、対応する対処法を示します。すぐに行動したい方は、最後のセクションのトラブルシューティングチェックリストへ進んでください。

この記事では切断のトラブルシューティングのみを扱います。リモートアクセスの構築方法は『Claude Code リモートアクセス：ローカルマシンをオフにしてもどこでもセッションを操作』を、スマホでの利用方法は『スマホで Claude Code：iOSでいつでもセッションとツール承認を確認』を参照してください。

まず症状を照合：あなたが見ているのはどれか

リモート接続は2つの区間で構成されます：Claude Code を実行する開発マシン ←→ 手元の閲覧デバイス。どちらか一方に問題があれば「切断」として現れますが、現象には違いがあります：

あなたが見る現象	可能性が高い原因	移動先
セッションが突然動かなくなり、再接続しても進捗がその時点で止まっている	開発マシンのスリープ / 画面ロック	§1
エレベーターに入る、4Gに切り替える、WiFiを変更した瞬間に切断	長期間接続が切断される	§2
ローカル端末を閉じるか、ローカルマシンがスリープすると、リモートも即座に切断	ミラーリング方式の制約	§3
オンライン表示だが、メッセージが沈み、エラーも出ない	半死接続	§4
再接続できるが、空のセッションに戻る / 切断中のメッセージが消えている	再接続が元のセッションに戻れていない	§5
数時間後に再接続すると、セッションが消えている	プロセスが回収され、コールドリカバリもない	§6

最も誤診しやすいのは4番目です：エラーを出さないからです。接続状態は緑で、メッセージは送信できるが、永遠に応答がない——直接切断よりも調査が困難です。なぜなら、すべてのインジケーターが「すべて正常」と告げているからです。

1. 開発マシンのスリープ / 画面ロック / 蓋を閉じる

症状：セッションがある時点で完全に停止します。再接続しても、進捗は切断した時点で止まったままで、一歩も進んでいません。

原因：多くの人は「開発マシンは常に起動している」と思っていますが、システムのスリープ、蓋を閉じたスリープ、定時画面ロックはClaude Code プロセスを一時停止させるか、直接終了させます。閲覧側には「突然動かなくなった」と見えます。

確認方法：開発マシンに戻って、そのプロセスがまだ存在するか、システムログにスリープ記録があるかを確認します。プロセスは存在するがタイムスタンプが切断時刻で止まっている場合、ほぼこれが原因です。

対処法：開発マシンの電源プランを「スリープしない / 蓋を閉じてもスリープしない」に設定します。これが唯一の根本的な解決策です——いかなるリモートソリューションも、すでにスリープしたマシンを救うことはできません。

2. ネットワーク切り替えによる長期間接続の切断

症状：非常に明確な瞬間に切断されます——エレベーターに入る、WiFi から 4G への切り替え、自宅のブロードバンドが深夜に再接続される。

原因：リモートのリアルタイム同期は1つの長期間接続（WebSocket / SSH）に依存しています。IP が変わると、この接続は即座に無効になり、余地はありません。

確認方法：切断時刻とネットワーク切り替えの時刻が一致すれば、これが原因です。

対処法：このタイプは回避できません。自動再接続 + バックオフで支えるしかありません（1秒→2秒→5秒…、切断直後に一気に再試行しないように）。素の SSH にはこの機能がないため、切断されたら手動で再接続するしかありません。ソリューションを選ぶ際の必須条件です。

3. ミラーリング方式：ローカルマシンがフォアグラウンドで開いている必要がある

症状：ローカルの端末を閉じるか、ローカルマシンがスリープすると、スマホ側も即座に切断されます。ゆっくりタイムアウトするのではなく、同期が失効します。

原因：Anthropic 公式の Remote Control は、ローカルマシンで実行中のセッションを投影してスマホ/ブラウザに表示します。前提は、ローカルの Claude Code が常にフォアグラウンドで開いており、ローカルマシンが常にオンラインであることです。ローカルが落ちると、リモート側には依存できる独立したライフサイクルがありません。

確認方法：ローカルの端末ウィンドウを閉じて、リモートが同じ秒で切断されるかを確認します。そうであれば、ミラーリング方式を使用しています。

対処法：開発マシン側の常駐デーモンサービスのアーキテクチャに変更します——セッションを実行する側を起動時に自動開始するバックグラウンドサービスにし、閲覧デバイスから独立して動作させます。閲覧側が閉じられても、変更されても、切断されても、開発マシン上で通常通り実行され続けます。これが「ミラーリング」と「常駐サービス」の本質的な違いであり、パラメータで調整できるものではありません。

4. 半死接続（half-open）：最も発見が難しいタイプ

症状：オンライン表示だが、メッセージを送っても反応がない、エラーも出ません。数分間止まることもあ、手動で再接続するまで止まり続けることもあります。

原因：ネットワークが静かに中断した場合（NAT テーブルのエントリがタイムアウト、中間機器が状態を失う、信号が弱くパケットロスするだけでリンクは切断されない）、TCP の両端は互いに接続されていると思い込む可能性があり、実際にはデータが一切通過しなくなります。ハートビートがなければ、両者はこの幻想を維持し続けます。

確認方法：接続状態は正常と表示されるが、送信したメッセージに配信確認もエラーもない。手動で切断して再接続すると即座に回復する——それがこれです。

対処法：接続上で**ハートビート（keepalive ping）**を実行します：約定時間内に相手から一切の応答がなければ、それを半死接続と判定し、待つだけでなく積極的に切断して再接続します。判定基準は「応答が受信できないこと」でなければならず、「エラーがないこと」ではいけません——半死接続は決してエラーを出さないからです。

5. 再接続が元のセッションに戻れない / メッセージ消失

症状：切断しても再接続はできますが、戻ると空のセッションになっているか、切断中に相手が送ったメッセージがすべて消えています。

原因：再接続は単に新しい接続を確立しただけで、その接続を元のセッションに再サブスクライブしていません。切断中のメッセージもキャッシュされていません。

確認方法：再接続後にセッション ID が変わっているか、履歴が再接続時点からしか始まっていない。

対処法：再接続後に元のセッションへ自動再サブスクライブし、切断中の履歴をリプレイできるソリューションを選びます。再接続できるだけで元に戻れないのは、接続しないのと同じです。

6. セッションプロセスが回収され、コールドリカバリもない

症状：短時間の切断と再接続は正常ですが、数時間後に戻るとセッションが消えています。

原因：長時間アイドル状態のセッションプロセスは回収される可能性があり、デーモン自体も再起動されている可能性があります（アップグレード、クラッシュ後の再起動）。メモリ内のセッション状態もそれに伴って消えます。

確認方法：長時間の切断でのみ再現し、短時間の切断では再現しない。

対処法：コールドリカバリ機能が必要です——セッション状態をディスクに保存し、プロセスが消えてもディスクからコンテキストを復元できます。理想的には、メッセージを1件送信すると自動的に回復して継続し、ユーザーはそれを意識しません。

トラブルシューティングチェックリスト（どのソリューションでも実行可能）

順番に確認してください。各ステップは独立して検証できます：

1. セッションを実行しているマシンがスリープ / 画面ロックしていますか？ → 自動スリープを無効にし、蓋を閉じてもスリープしないように設定。（§1）
2. 切断時刻とネットワーク切り替えの時刻が一致しますか？ → 自動再接続 + バックオフ付きのソリューションが必要。素の SSH に頼らないでください。（§2）
3. ローカル端末を閉じると、リモートは即座に切断されますか？ → ミラーリング方式の制約です。常駐デーモンアーキテクチャに変更する必要があります。（§3）
4. 「オンライン表示だがメッセージに反応がない」状態で止まっていますか？ → 半死接続です。ハートビート検出だけが自動的に復旧できます。（§4）
5. 再接続後にセッションが空 / メッセージが減っていますか？ → 「元のセッションへの復帰 + 履歴リプレイ」が必要です。（§5）
6. 長時間の切断でのみセッションが失われますか？ → ディスク保存 + コールドリカバリが必要です。（§6）

具体的なソリューションについて

上記の6項目のうち、1番目だけが自分のマシンの設定問題であり、残りの5項目はすべてアーキテクチャによって決定されます——ソリューション選定時に確定しており、問題発生後にパラメータを調整しても救えません。

切断しないリモートソリューションには、以下が同時に必要です：開発マシン側の常駐デーモンプロセス（§1の残りのリスクと§3に対応）、自動再接続 + バックオフ（§2）、ハートビート検出（§4）、再接続時の元のセッションへの復帰 + 履歴リプレイ（§5）、ディスク保存によるコールドリカバリ（§6）。

PandaNpc + pandapaw はこの6項目に一つずつ対応しています：pandapaw は開発マシン上で起動時自動開始の常駐デーモンプロセスとして登録されます（手動で開いておく必要のある端末ウィンドウではなく、クラッシュすると自動的に再起動されます）。閲覧側は切断時に自動再接続され、バックオフも備えています。接続上でハートビートを実行し、応答が受信できない場合は半死と判定して積極的に再接続します。再接続後は自動的に元のセッションに再サブスクライブし、切断中の履歴をリプレイします。セッションプロセスが回収されても、メッセージを1件送信すればディスクからコールドリカバリして継続できます。

具体的なインストール方法と接続方法は『Claude Code リモートアクセス』を参照してください。スマホでのセッション閲覧とツール承認は『スマホで Claude Code』を参照してください。

ついでの落とし穴：リモート実行で課金に引っかからないために

切断のトラブルシューティングの際、つい claude -p（ヘッドレスモード）に切り替えて実行しがちですが、2026年6月15日から Anthropic は課金体系を変更しました——ヘッドレスはサブスクリプション枠ではなくなり、少額の月次 SDK クレジットを消費し、使い切ると API 課金になります。ヘビーに使うとすぐに超過しがちです。対話モード（claude REPL）は引き続きサブスクリプション枠が適用されます。ソリューションを変更して切断を調査する際は、うっかり課金モードも変更しないよう注意してください。