【ITニュース解説】9 Timeouts in Claude Code, Codex and Gemini CLI That Cut Long Test Runs Short

システム開発において、AIコーディングツールはプログラミング作業を効率化する強力な味方である。しかし、これらのツールを使用する際、予期せぬ挙動に遭遇することがある。特に、長時間の処理を実行しようとすると、途中でタスクが停止したり、期待する結果が得られなかったりすることがある。その原因の一つが「タイムアウト」である。タイムアウトとは、ある処理が指定された時間内に完了しない場合、強制的にその処理を打ち切る仕組みを指す。これは、システム全体が応答不能になることを防いだり、リソースを無駄に消費するのを防いだりするために非常に重要である。しかし、開発者にとっては、実行中のタスクが不完全に終わる原因となり得るため、その仕組みを理解し、適切に設定を管理することが求められる。この解説では、AIコーディングツールであるClaude Code、Codex、Gemini CLIにおいて、どのようなタイムアウトが存在し、どのように動作するのかを具体的に見ていく。

まず、Claude Codeにおける様々なタイムアウトについて説明する。Claude Codeは、特にシェルコマンドの実行に関して複数のタイムアウトを設けている。一つ目はBASH_DEFAULT_TIMEOUT_MSである。これは、BashやPowerShellなどのシェルコマンドをフォアグラウンドで実行する際のデフォルトのタイムアウトで、設定されていない場合は120,000ミリ秒、つまり2分が上限となる。もしコマンドがこの時間内に完了しない場合、Claude Codeはそのコマンドを強制終了するのではなく、バックグラウンドに移動させ、その旨を通知する。ただし、CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1という環境変数を設定している場合や、特定の「ベアモード」で実行している場合は、タイムアウトした時点でコマンドは停止する。これにより、テスト実行などの長時間タスクが2分で中断される可能性があるため注意が必要である。

二つ目はBASH_MAX_TIMEOUT_MSで、これはClaude Codeがシェルコマンドに対して要求できる最大のタイムアウト時間を設定する。デフォルトでは600,000ミリ秒、つまり10分が上限である。たとえ開発者が20分のタイムアウトを要求したとしても、この設定が10分であれば、コマンドは10分で打ち切られてしまう。この値は、BASH_DEFAULT_TIMEOUT_MSよりも大きい値に設定されている場合にのみ有効な上限となる。つまり、開発者が自身のテストスイートが遅いことを知っていても、この上限値を超えてタイムアウトを伸ばすことはできないのである。

三つ目は「バックグラウンド時間制限」である。これは、非対話型セッション、例えばCI/CD（継続的インテグレーション・継続的デリバリー）環境での実行やエージェントSDKアプリケーションでの実行に適用される。フォアグラウンドでタイムアウトしバックグラウンドに移動したコマンド、あるいはClaudeが最初からバックグラウンドで開始したコマンドは、デフォルトで30分の時間制限が設けられる。ただし、テキストプロンプトで実行する-pオプションの場合、このデフォルトは10分に短縮される。もしこの時間制限に達した場合、Claude Codeはバックグラウンドコマンドを停止し、開発者はより長いタイムアウトを設定して再度開始するよう促される。これらのBash関連のタイムアウトは、BASH_DEFAULT_TIMEOUT_MSとBASH_MAX_TIMEOUT_MSの環境変数を設定することで調整可能である。例えば、~/.claude/settings.jsonファイルにこれらを指定することで、デフォルトのタイムアウトを延長したり、Claudeが要求できる最大値を引き上げたりすることができる。これにより、14分かかるようなテストスイートも、フォアグラウンドで完了させることが可能となる。

次に、Claude Codeの他のタイムアウトについて説明する。MCPサーバーは、さまざまなツールとの連携を可能にする重要な要素である。そのMCPサーバーの起動にはMCP_TIMEOUTというタイムアウトが設定されており、デフォルトは30,000ミリ秒、つまり30秒である。もしサーバーがこの時間内に起動しない場合、そのサーバーはセッションで利用できなくなる。特に、初めて起動する際にパッケージのダウンロードが必要なNPM（Node Package Manager）のツールなどは、このタイムアウトに引っかかりやすい。このような場合は、環境変数としてMCP_TIMEOUTをより長い値、例えば60,000ミリ秒（1分）に設定することで対応できる。

MCPツール呼び出しにもタイムアウトが存在する。MCP_TOOL_TIMEOUTという全体的なタイムアウトは非常に長く設定されているが、より細かいレベルでの制限がある。HTTP、SSE、claude.aiコネクター経由のリモートサーバーに対する各リクエストは、デフォルトで60秒後にタイムアウトする。また、CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUTは、サーバーから何も出力がない状態が一定時間続くと、その呼び出しを中止するタイムアウトである。ネットワーク経由のサーバーでは5分、標準入出力（stdio）経由のサーバーでは30分がデフォルトとなる。これらのタイムアウトは、.mcp.jsonファイルにサーバーごとのtimeout設定を追加することで変更できる。このtimeoutは、サーバーの動作中に出力があっても延長されない厳格な時間制限であり、長い処理を実行する場合は、予想される最長時間よりも長く設定するか、設定を省略してアイドルタイムアウトに頼るかを選択することになる。

フック（Hook）とは、特定のイベント（例えば、コマンド実行前やプロンプト送信時など）が発生した際に実行されるカスタム処理のことである。Claude Codeのフックにはhook timeoutが設定されており、コマンド、HTTP、MCPツールフックのデフォルトは600秒（10分）である。プロンプトフックは30秒、エージェントフックは60秒と短く設定されている。フックがタイムアウトした場合、その処理はキャンセルされ、出力は破棄される。これにより、フックが期待する判断を下せない事態が発生する可能性がある。例えば、テストスイート全体をゲートとして実行するStopフックが12分かかる場合、デフォルトの10分ではタイムアウトし、何も通知しないことになる。この場合も、settings.jsonファイル内のフック設定でtimeout値を延長する必要がある。PreToolUseフックのように、タイムアウトしてもツール呼び出しが進行してしまうケースでは、onFailure: "block"を設定することで、タイムアウト時にツール呼び出しをブロックするように動作を変更できる場合もある。

最後に、Claude Codeにはモデル呼び出しに関するAPI_TIMEOUT_MSというタイムアウトがある。これは、各APIリクエストが応答ヘッダを受け取るまでの時間を制限するもので、デフォルトは600,000ミリ秒、つまり10分である。このタイムアウトは、ストリーミング応答が開始された後の継続時間には影響しないが、ネットワークが遅い環境やプロキシ環境下で応答ヘッダの受信に時間がかかる場合に問題となることがある。そのような場合は、この値を延長するか、特定のバージョンでは0に設定して制限を解除することも可能である。このように、Claude Codeでは、個々のリクエストに対する制限が、そのリクエストを含む処理に対する制限の中にさらに存在するというように、複数のタイムアウトが階層的に適用される設計になっている。

次に、Codexにおけるタイムアウトについて説明する。CodexもMCPサーバーを使用しており、サーバー起動とツール呼び出しに関するタイムアウトが存在する。startup_timeout_secはサーバー起動のタイムアウトで、デフォルトは10秒である。これはClaude Codeの30秒と比較して短いため、起動に時間のかかるサーバーでは注意が必要である。tool_timeout_secはツール呼び出しのタイムアウトで、デフォルトは60秒である。これらの設定は、~/.codex/config.tomlまたはプロジェクト内の.codex/config.tomlファイルで変更できる。例えば、startup_timeout_secを30秒に、tool_timeout_secを900秒（15分）に設定することで、より長い処理に対応できる。Codexの設定では、シェルコマンド自体のタイムアウトを直接設定する項目は見当たらない場合がある。

最後に、Gemini CLIのタイムアウトについて説明する。Gemini CLIにはtools.shell.inactivityTimeoutという特徴的なタイムアウトが存在する。これは、シェルコマンドからの出力が一定時間（デフォルトで300秒、つまり5分）なかった場合に、そのコマンドを停止させる設定である。このタイムアウトはコマンドの実行時間全体ではなく、「出力がない時間」を数えるため、テストランナーのように結果をまとめて出力したり、ビルドプロセスのように途中で沈黙する時間が長かったりする処理では、完了する前に停止してしまう可能性がある。この設定も、~/.gemini/settings.jsonまたはプロジェクト内の.gemini/settings.jsonファイルで変更できる。例えば、inactivityTimeoutを900秒（15分）に設定することで、より長い無出力期間を持つコマンドにも対応できる。Gemini CLIでは、シェルコマンドの設定が秒単位である一方で、MCPサーバーのタイムアウト設定はミリ秒単位であるなど、設定項目によって単位が異なる場合があるため、値を指定する際には注意が必要である。なお、2026年6月18日をもって、一部のユーザー向けにGemini CLIはAntigravity CLIに置き換えられる予定である点も補足しておく。

これらのAIコーディングツールにおけるタイムアウト設定を理解し、適切に管理することは、開発効率を向上させ、予期せぬ中断による時間のロスを防ぐ上で非常に重要である。特に、複数のタイムアウトが階層的に存在し、それぞれが異なるデフォルト値や単位を持っているため、自身の開発環境やタスクの特性に合わせて、これらの設定を慎重に調整する必要がある。タイムアウトはシステムの安定性を保つための安全装置であるが、開発者の意図しない形でタスクを妨げないよう、その挙動と設定方法を深く理解することが、システムエンジニアとしての成長に繋がるだろう。