Zenn
💡

2分の壁を突破する！Claude Codeで長時間実行コマンドのタイムアウト解決法

に公開
AI
Model Context Protocol
Claude Code
tech

英語で書いた記事をまだ日本語にし直していない K@zuki. です。

Claude Codeを使っていて、テストの実行やビルドが途中でタイムアウトで止まってしまった経験はありませんか？
Claude Codeにはデフォルトで2分のタイムアウトが設定されています。
今回は、この制限を回避する3つの方法を紹介します。

TL;DR

  • Claude Codeのデフォルトタイムアウトは2分（120秒）
  • 最大 10分（600秒） まで延長可能
  • 設定方法
    • 個別指定
    • 環境変数
    • settings.json

なぜタイムアウトが必要なのか

Claude Codeは対話型のAIツールですが、実行中のコマンドが無限ループに陥ったり、応答しなくなったりする可能性があります。
デフォルトの2分という制限は、多くのコマンドには十分に長いですが、以下のような場合では全然足りません。

  • 大規模なテストの実行
  • 時間のかかるビルド
  • 大規模なマイグレーション
  • 大量のデータでのバッチ処理

私は大規模なテストの実行でしばしば遭遇しています。

その1 個別のコマンドでタイムアウトを指定

最も簡単な方法は、長時間実行されるコマンドに対して個別にタイムアウトを指定することです。

docker compose run --rm -it app bin/rspec # timeout 600000ms

Bashツールで実行するコマンドの前か後ろにtimeoutをミリ秒単位で時間を指定します。
最大値は600000ms（10分）です。

ミリ秒でなくてもいいのですがコマンドで実行している場合は、 timeout xms の形式で書いてる方が安定してTimeoutを変更してくれています。

その2 環境変数で全体のデフォルトを変更

頻繁に長時間のコマンドを実行する場合は、環境変数でデフォルトタイムアウトを変更できます。

export BASH_DEFAULT_TIMEOUT_MS=300000

これにより、全てのBashコマンドのデフォルトタイムアウトが5分になります。

https://docs.anthropic.com/en/docs/claude-code/settings

その3 settings.jsonで環境変数を設定

Claude Codeの設定ファイルにその2で指定した環境変数を設定しておくことも可能なようです。
※ こちらは動作確認しておらず、公式ドキュメントによる記述のため注意してください。

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  }
}

この設定により、Claude Codeを起動するたびに自動的にタイムアウトが5分に設定されます。

https://docs.anthropic.com/en/docs/claude-code/settings

注意点

  • タイムアウトを長くしすぎると、問題のあるコマンドの検出が遅れる可能性があります。
  • 10分が最大値なので、それ以上の処理は分割を検討しましょう
  • CI/CDパイプラインでの実行とは異なり、対話的な使用を前提としています

短くする

逆に短くすることも可能です。

sleep 5 # timeout 1000ms

とやると書き、タイムアウトを短くすることも可能です。

まとめ

Claude Codeのタイムアウト設定は、開発効率を大きく左右する重要な要素です。
デフォルトの2分では不十分な場合は、今回紹介した方法で適切に調整しましょう。
特に環境変数やsettings.jsonでの設定は、一度設定すれば忘れることができるのでおすすめです。

皆さんもClaude Codeで快適な開発ライフを送ってください！

Discussion