Claude Code / Codex の動作が重くなる場合の対処法は？AIプログラミングエージェントの接続失敗とネットワークトラブルシューティングの手順

1. なぜAIプログラミングエージェントは「動作が固まっているように見える」ことが多くなるのか

一般的なAI対話ツールの流れは通常、以下の通りです：

質問の入力 -> モデルによる回答の生成 -> テキストの返却

一方、AIプログラミングエージェントの処理フローはより長くなります。一見単純に見える「このバグを修正してください」というリクエストの背後には、次のようなプロセスが含まれている可能性があります：

プロジェクトファイルの読み込み
ディレクトリ構造の分析
関連コードの検索
エラーログの解析
モデルの呼び出し
修正案の生成
ファイルへの書き込み
テストコマンドの実行
テスト結果の読み取り
修正の継続
再検証
まとめの出力

したがって、ターミナルに長時間出力がない場合、必ずしもエージェントが停止しているわけではありません。エージェントは以下の処理を行っている可能性があります：

プロジェクトファイルのスキャン；
モデルの応答待ち；
ローカルコマンドの実行；
依存関係のダウンロード；
テストの実行；
大容量ファイルの読み込み；
特定のAPIからの応答待ち；
ツール呼び出し結果の処理；
ワークスペースに変更を反映している。

これこそが、Claude Code、Codex、Cursor Agent、GitHub Copilot Coding Agent などのツールと、一般的なチャットツールの最大の違いです。これらは単にテキストを返すQ&Aボットではなく、「実際に手を動かす」エージェントなのです。

2. まず、どの段階で停滞しているかを判断する

AIプログラミングエージェントのトラブルシューティングにおいて、最初のステップはツールの再インストールではなく、どの段階で処理が滞っているかを特定することです。

以下の表を使って素早く分類できます：

処理が滞る段階	一般的な症状	優先的に調査すべき方向
起動段階	CLIの起動が遅い、ログイン失敗、モデルリストの読み込み失敗	アカウント、バージョン、ターミナル環境、DNS/TLS
プロジェクト読み込み段階	プロジェクトに入っても長時間分析が続いており、タスクに移行しない	プロジェクトのサイズ、無視するディレクトリ、ファイル数
モデルの応答段階	タスクを送信してから、最初の文字が出力されるまで長時間かかる	モデルキュー、コンテキストの長さ、リクエストの遅延
ツール呼び出し段階	Agentがコマンドを実行した後、ずっと待機状態	ローカルコマンド、依存関係のダウンロード、権限、パス
ファイル変更段階	ソリューションは生成されたが、書き込みやパッチ適用が遅い	ファイルの競合、権限、ワークスペースの状態
テスト・検証段階	変更完了後、test、build、lintで停止している	テスト自体の所要時間、依存環境、外部インターフェース
結果の返送段階	実行は完了したが、まとめが表示されない、または途中で切断された	永続接続の安定性、ターミナル出力、リクエストタイムアウト

多くの人がすべての問題を「Claude Codeが固まった」や「Codexが固まった」とひとくくりにしがちですが、真に効果的なトラブルシューティング方法は、まず起動、読み込み、生成、実行、書き込み、検証のどの段階で停止しているかを特定することです。

3. まず空のディレクトリを使って最小限のテストを行う

最初から大規模なプロジェクトでトラブルシューティングを行わないでください。

まず、空のディレクトリを作成することをお勧めします：

mkdir agent-test
cd agent-test

簡単なファイルを作成します：

echo 「function add(a, b) { return a + b }」 > index.js

次に、Claude Code または Codex に非常に小さなタスクを実行させます：

index.js を読み込み、subtract 関数を追加してください。

タスクが完了するかどうかを確認します：

ファイルを読み込み；
タスクを理解する；
変更を生成する；
ファイルに書き込む；
説明を出力する。

空のディレクトリでは処理が速く、実際のプロジェクトでは遅い場合、ツール自体はほぼ確実に利用可能であり、問題はプロジェクトの規模、コンテキスト、依存関係、テストスクリプト、またはワークスペースの状態にある可能性が高いです。

空のディレクトリでも処理が遅い場合は、アカウント、CLI バージョン、ターミナル環境、ネットワーク接続についてさらに調査してください。

4. アカウント、モデルの権限、CLI バージョンの確認

Claude Code や Codex といったツールは、通常、アカウント、モデルの権限、クライアントのバージョン、ローカル設定に依存します。

基本的な確認項目は以下の通りです：

現在ログインしているアカウントが正しいか；
モデルの権限が有効か；
クォータや頻度制限がないか；
CLI またはクライアントのバージョンが古すぎないか；
現在のターミナルから設定ディレクトリに正常にアクセスできるか；
環境変数が誤って上書きされていないか；
ローカルシステムの時刻が正常か；
会社のデバイス、リモートサーバー、コンテナ、または CI 環境で実行されているか。

まずは次の 3 つのことを試してみてください：

1. アカウントからログアウトして再ログインする
2. 新しい CLI またはクライアントバージョンにアップグレードする
3. 空のディレクトリで最小限のタスクを実行する

最小タスクが正常に動作するようになった場合は、アカウントやツールのインストール環境レベルでの試行錯誤を繰り返さないでください。

それでも異常が続く場合は、次の段階の調査に進んでください。

5. 大規模なプロジェクトは、エージェントのコンテキスト処理を著しく遅くします

AIプログラミングエージェントの強みはコンテキストを理解することですが、コンテキストは多ければ多いほど良いというわけではありません。

典型的なプロジェクトには、以下のようなものが含まれる可能性があります：

ソースコード；
テストファイル；
ドキュメント；
ビルド成果物；
依存ディレクトリ；
ログ；
一時ファイル；
バイナリファイル；
画像、動画、圧縮ファイル；
データベースファイル；
生成されたレポート。

これらのファイルの多くは現在のタスクには役立ちませんが、検索、インデックス作成、およびコンテキストフィルタリングの負荷を増大させます。

以下のディレクトリやファイルタイプを優先的に除外することをお勧めします：

node_modules/
dist/
build/
coverage/
.next/
.turbo/
.gradle/
target/
logs/
tmp/
*.zip
*.mp4
*.apk
*.sqlite
*.log

さらに重要なのは、最初からエージェントに過大なタスクを課さないことです。

推奨されない例：

プロジェクト全体をリファクタリングし、潜在的な問題をすべて修正してください。

より推奨される例：

src/api/user.ts と src/services/auth.ts のみを読み込み、
ログインフローを解説し、トークンの無効化につながる可能性のあるコードパスを指摘する。

タスクの境界が明確であればあるほど、エージェントは安定して動作します。

6. ツールの呼び出しが停止しても、必ずしもモデルが停止しているとは限らない

AIプログラミングエージェントは、頻繁にローカルツールを呼び出します。

例えば：

rg コードを検索；
git status ワークスペースを確認；
npm test テストを実行；
pnpm install 依存関係をインストール；
docker build イメージをビルド；
python script.py スクリプトを実行；
curl APIにリクエスト；
設定ファイルを読み込む；
パッチを書き込む。

特定のコマンド自体が非常に遅い場合、Agent も応答しなくなっているように見えます。

例えば、Agent が以下で停止している場合：

npm install

あるいは：

docker build .

この場合、問題は Claude Code や Codex ではなく、依存関係のダウンロード、スクリプトのビルド、ローカル環境、テストコマンド、または外部 API の処理が遅いことが原因である可能性があります。

トラブルシューティング方法は簡単です。Agent が実行中のコマンドをコピーし、自分でターミナルで単独で実行してみてください。

単独で実行しても遅い場合は、ボトルネックはコマンド自体にあるということです。

単独で実行すると速いが、Agent内では遅い場合は、ツールの権限、作業ディレクトリ、環境変数、およびコンテキストとの相互作用を確認してください。

7. ターミナル環境もAI Agentに影響を与えます

Claude CodeやCodexは通常ターミナル内で実行されるため、ターミナル環境そのものが体験に影響を与えます。

注意すべき点：

PowerShell、bash、zsh、fish の初期化スクリプトの実行が遅すぎないか；
PATH が正しいか；
Node、Python、Git、Docker が正常に動作するか；
現在のディレクトリに適切な権限があるか；
セキュリティソフトがコマンドの実行をブロックしていないか；
がネットワークドライブ、同期ドライブ、またはアクセス権が制限されたディレクトリにあるかどうか；
に過大なターミナル出力がないかどうか；
ユーザーからの入力を待機しているコマンドがないかどうか。

よくある問題として、エージェントがコマンドを実行したものの、そのコマンドがユーザーの確認を待っている場合があります。

例えば：

続行しますか？ [Y/n]

Agentがこの対話処理を正しく行わない場合、「フリーズ」したように見えます。

したがって、対話が必要となる可能性のあるコマンドについては、可能な限り非対話モードに変更するか、事前にターミナルでコマンドの動作を確認してください。

8. ネットワーク層では、DNS、TLS、HTTPのタイムアウトおよびパーシステント接続に重点を置く

アカウント、プロジェクト、ローカルコマンドの原因をすべて排除したら、ネットワーク層を確認する必要があります。

AIプログラミングエージェントのネットワークリクエストは、おおむね以下の経路を通ります：

DNS 解決 -> TCP 接続 -> TLS ハンドシェイク -> API リクエスト -> モデル応答 -> ストリーミング返却 -> ツール結果の返送

ネットワーク層でよく見られる現象：

ネットワーク段階	異常な挙動	トラブルシューティングの重点
DNS解決が遅い	初回リクエストが遅い、モデルリストの読み込みが遅い	ドメイン名解決に時間がかかる、解決の安定性
TLS ハンドシェイク異常	接続段階でのタイムアウトまたは証明書エラー	システム時刻、証明書チェーン、セキュリティソフトウェア
API 遅延が大きい	タスク送信後、最初の文字が出力されるまで長時間かかる	リクエスト本文のサイズ、モデルの応答、リンク遅延
読み取りタイムアウト	接続は完了しているが、結果の待ち時間が長すぎる	コンテキストの長さ、タイムアウトパラメータ、タスクの複雑さ
ストリームの途切れ	出力が途中で停止	永続接続の安定性、パケットロス、ジッター
複数のツールで動作が遅い	GitHub、npm、Docker、AIツールすべてで動作が遅い	ローカルネットワーク、DNS、ゲートウェイの安定性

簡単なコマンドを使ってクロスチェックを行うことができます。

リポジトリへのアクセステスト：

git ls-remote <コードリポジトリのアドレス>

依存関係の照会テスト：

npm view react version

基本的なHTTPレスポンスのテスト：

curl -I <テスト対象のサイトアドレス>

コンテナの基本イメージのテスト：

docker pull hello-world

これらのコマンドの実行も明らかに遅い場合は、AIエージェントだけに注目しないでください。問題は、開発者のネットワーク回線、DNS、ゲートウェイの安定性、またはローカル環境の設定にある可能性があります。

DNS、IP、遅延、WebRTC、ポート、アクセス経路のトラブルシューティングが必要な場合は、「稳如狗ネットワークツールボックス」を使用し、まず基本的なネットワーク状態を明確に把握した上で、Claude Code、Codex、またはその他の開発ツールの問題の特定を進めてください。

9. AI Agentは、長時間の接続と安定した出力に対してより敏感です

一般的なコマンドラインツールは、APIへのリクエストを1回行うだけで済み、成功か失敗かが明確です。

AIプログラミングAgentは異なり、タスクの状態を長時間維持する必要がある場合があります：

プロジェクトを読み込む；
モデルと複数回のやり取りを行う；
ツールを呼び出す；
ツールの結果を待つ；
結果をモデルに再渡す；
コードの修正を続ける；
再度テストを実行する；
最後に要約を出力する。

このプロセスでは、長接続、ターミナル出力、およびリクエストの安定性に対する要求がより高くなります。

そのため、次のような状況に遭遇する可能性があります：

最初は出力されていたのに、途中で突然反応がなくなる
コマンドは実行されたが、結果がエージェントに返されていない
モデルの生成が途中で中断した
ツールの呼び出しは完了したが、エージェントが次のステップに進んでいない

このような問題は、2つの方向から調査できます：

ツールが実際に実行を完了したかどうか；
実行結果が安定してAgentに返されているかどうか。

「出力が存在するかどうか」だけでなく、コマンドがまだ実行中ではないか、対話入力で停止していないか、過大なログが書き込まれていないかを確認する必要があります。

10. 大規模なタスクを、Agentが安定して実行できる小さなタスクに分割する

多くのAIエージェントの動作が重くなるのは、ツール自体の問題ではなく、タスクの記述が広範囲すぎるためです。

例：

このプロジェクト全体を最適化してください。

このようなタスクは、エージェントにとって範囲が曖昧すぎます。

より適切な記述は次の通りです：

src/routes/user.ts と src/services/userService.ts のみを確認し、
ログインAPIが401を返す可能性のある原因を特定してください。
コードの修正は行わず、分析結果のみを出力してください。

次に、ステップ2として：

上記の分析に基づき、src/services/userService.tsのみを修正してください。
APIの構造を変更したり、関係のないファイルを修正したりしないでください。

3番目のステップについては、

関連するテストを実行してください。失敗した場合は、エラーメッセージに基づいて現在のファイルのみを修正してください。

この分割方法にはいくつかの利点があります：

Agentが関係のないファイルを読み込みすぎることを防げます；
ツールの呼び出し回数をより制御しやすくなります；
各ステップでの失敗原因を特定しやすくなります；
ファイルの変更範囲が明確になります；
コードレビューが容易になる；
タスクを中断して後で再開できる。

AIエージェントの性能が高ければ高いほど、エンジニアリング的なタスクの分割が必要となる。

11. 推奨トラブルシューティング手順

Claude Code / Codexの動作が重くなる問題を、以下の手順に整理できる：

ステップ1：空のディレクトリで最小限のタスクを実行する
ステップ2：アカウント、モデルの権限、利用枠、およびCLIのバージョンを確認する
ステップ3：起動、プロジェクトの読み込み、モデルの応答、ツールの呼び出し、あるいはテスト・検証のどの段階で停止しているかを判断する
ステップ4：大規模なプロジェクトのみが遅い場合は、依存ディレクトリ、ビルド成果物、ログ、および大容量ファイルを排除する
第5ステップ：大規模なタスクを「読み込み」「分析」「修正」「テスト」「まとめ」といった小さなステップに分割する
第6ステップ：Agentが実行するローカルコマンドを単独で一度実行してみる
第7ステップ：ターミナルの権限、PATH、環境変数、およびコマンドが対話待ちになっていないかを確認する
第8ステップ：GitHub、npm、Docker、OpenAI APIなどの開発リソースも遅延していないかテストする
第9ステップ：DNS、TLS、HTTPのタイムアウト、パーシステント接続、ネットワークのジッターを確認する
ステップ10：最後に、ツールの再インストールや設定のリセットを検討する

この順序の原則は、まず検証しやすい問題を排除し、その後、より複雑なネットワークや環境の問題に対処することです。

最初からツールの再インストール、設定の削除、PCの交換を行わないでください。

こうした操作はコストが高く、多くの場合、真の問題を解決できません。

12. よくある誤解

誤解その1：ターミナルに出力がないということは、Agentが停止しているということだ

必ずしもそうとは限りません。

ローカルコマンドを実行中、テストの終了を待機中、大容量ファイルを読み込んでいる、あるいはインタラクティブな入力が必要なコマンドで停止している可能性があります。

誤解その2：モデルの応答が遅いのは、必ずモデルサービスの問題だ

必ずしもそうとは限りません。

コンテキストが長すぎる、プロジェクトが大きすぎる、ネットワークの不安定さ、ローカルコマンドの処理が遅い、ツールの結果データが大きすぎるなど、さまざまな要因がモデルの処理を遅く見せている可能性があります。

誤解その3：AIエージェントはプロジェクト全体を一度に解決すべきだ

現実的ではありません。

一度に処理するタスクの範囲が広ければ広いほど、処理が遅くなったり、混乱したり、失敗しやすくなります。

より安定した方法は、まず分析してから修正すること、まず小範囲から始めて範囲を広げること、まず部分的なテストを実行してから全量テストを実行することです。

誤解その4：すべての問題はネットワークに起因する

ネットワーク回線のトラブルシューティングは、DNS、TLS、接続タイムアウト、持続接続の不安定さなどの問題を特定するのに適しています。

しかし、アカウントの権限、プロジェクト構造の混乱、テストスクリプト自体の処理速度の遅さ、依存関係の競合、プロンプトが不明確といった問題を解決することはできません。

13. まとめ

Claude Code / Codex の動作が重くなるのは、単一の原因による問題ではありません。

その原因は以下のいずれかである可能性があります：

アカウントおよびモデルの権限；
CLI またはクライアントのバージョン；
ターミナル環境；
PATH および環境変数；
プロジェクトファイルが多すぎる；
コンテキストが長すぎる；
ツールの呼び出し待ち；
ローカルコマンドの実行が遅い；
テストおよびビルドスクリプトに時間がかかる；
DNSおよびTLSの異常；
HTTPリクエストのタイムアウト；
パーシステント接続の不安定さ；
GitHub、npm、Docker、OpenAI API などの開発リソースへのアクセスが不安定。

比較的確実なトラブルシューティング方法は、まず空のディレクトリで基本機能を検証し、どの段階で詰まっているかを判断することです。プロジェクトに問題がある場合はコンテキストを縮小し、コマンドに問題がある場合はコマンドを単独で実行します。複数の開発ツールで動作が遅い場合は、DNS、TLS、接続の安定性、ネットワークの出口を調査します。

開発者にとって、AIプログラミングエージェントの効率は、モデルの能力だけでなく、プロジェクト構造、タスクの分割、ローカル環境、およびネットワーク回線の安定性にも左右されます。これらの基盤をしっかりと整えてこそ、Claude CodeやCodexといったツールは、真に信頼できる開発アシスタントとなるのです。

参考資料

「Wunuru」ヘルプセンターおよび技術ブログ：https://www.wenrugou.net/help.html