Claude Codeの応答が止まったときのタイムアウト調整方法

Claude Codeは、APIからのストリーミング応答の停止を、応答受信中の3層+応答開始前の1層、計4種類の独立したタイマーで検知します。既定のタイムアウトは接続経路によって180秒から300秒まで幅があり、CLAUDE_STREAM_IDLE_TIMEOUT_MSをはじめとする環境変数で個別に調整できます。プロキシ経由で頻繁に打ち切られる・Bedrockの拡張思考中に接続が切れるといった症状は、原因がどの層にあるかを見分ければ、当てるべき変数もほぼ一意に決まります。

ストリーミングアイドルウォッチドッグとは何を見張っているか

「ストリーミングアイドルウォッチドッグ」は、公式ドキュメントがこの検知の仕組みに付けた呼び名です。ストリーミング応答を受け取っている最中、接続は生きているのにデータだけが止まる状態を、Claude Codeは3種類のタイマーで別々に監視します。

• イベント単位のウォッチドッグ: パース済みのイベントが来ているかを見ます。全プロバイダーで動作し、既定は300秒です。SSEのkeep-aliveピングのような、意味のあるイベントにならない小さなバイトが届いてもこのタイマーはリセットされますが、それはパース済みイベントが来ないまま約5分までで、それを超えると打ち切られます
• バイト単位のウォッチドッグ: 配線上に1バイトでも届いているかを見ます。keep-aliveピングもバイトとして数えてリセットされてしまうため、keep-aliveだけが来て本体データが来ない接続を見分けることはできません。本当に1バイトも流れていない接続の検知に向いています。直接のAnthropic API・Claude Platform on AWS・ANTHROPIC_BASE_URLを含むゲートウェイ接続で動作します。Amazon Bedrockのvnd.amazon.eventstream応答では既定で無効で、Google CloudのAgent PlatformやMicrosoft Foundryでは動作しません。既定は直接APIで180秒、それ以外の経路で300秒です
• ボディアイドルタイムアウト: 5分間バイトが来なければ切る、もっと粗い監視です。直接のAnthropic APIとClaude Platform on AWS以外のプロバイダーで既定有効です

これらのタイマーとは別に、応答が始まる前――最初の1バイトが届くまでの待ち時間だけを見る「最初の1バイト猶予」という層もあります(後述)。複数層に分かれているのは、接続経路によって「何が正常なシグナルか」が違うためです。SSEのkeep-aliveだけを送ってくるプロキシもあれば、バイト単位でしか死活を判定できない経路もあります。1つのタイマーだけに頼ると、健全な接続を誤って切るか、本当に止まった接続を長時間放置するかのどちらかに寄ってしまいます。

監視対象ごとの既定タイムアウト早見表

同じ「応答が来ない」という体感でも、内部でどのレイヤーが反応したかによって、効く設定が変わります。

症状別に効く環境変数の早見表

環境変数の設定方法

環境変数はセッション開始前にエクスポートするか、settings.jsonに書きます。組織全体に配る場合はmanaged settings経由が確実です。

export CLAUDE_STREAM_IDLE_TIMEOUT_MS=600000
export CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1

主要な変数の役割は次の通りです。

CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MSを明示せずにAPI_TIMEOUT_MSだけを上げても、値がバイト単位ウォッチドッグの猶予を上回っていれば、最初の1バイト猶予はその値から1秒引いた値へ連動します。最初のバイトの猶予だけを個別に調整したいなら、CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MSを直接指定するほうが意図が明確です。

settings.jsonで書く場合

環境変数の代わりにsettings.jsonへ直接書くこともできます。CIジョブやコンテナイメージのように、シェルのexportを経由させたくない環境で使いやすい形です。

{
  "env": {
    "CLAUDE_STREAM_IDLE_TIMEOUT_MS": "600000",
    "CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK": "1"
  }
}

組織全体で同じ値を配りたい場合は、ユーザーごとの~/.claude/settings.jsonではなくmanaged settingsに書きます。管理者が配った値は、ユーザーがシェルで上書きしようとしても優先されます。

ウォッチドッグが作動するとClaude Codeはどう振る舞うか

タイマーが打ち切ったあとの挙動は、応答がどこまで進んでいたかで変わります。

• 応答ヘッダーが届く前(最初の1バイト猶予が切れた場合): 1回だけ自動で再送し、それでも応答がなければNo response from APIでターンを終了します。CLAUDE_CODE_RETRY_WATCHDOG=1を設定している場合は、この1回だけの上限が外れます
• テキストブロックやツール呼び出しを完了した後、応答全体が終わる前に切れた場合: 完了済みの出力は保持し、「応答が不完全な可能性があります」という通知を出します。同じツール呼び出しの二重実行を避けるため、リクエストをやり直すことはしません
• 応答がすでに完了した後に接続が切れた場合: 通知なしでそのままターンを正常終了します

非対話セッション(-p実行やAgent SDK経由)では、テキストだけで途切れツール呼び出しを含まない応答に限り、Claude Codeが自動で最大3回まで続きを促してから通知を出します。応答が不完全になったときの詳しい見え方は「Response incomplete」の通知にまとめています。

CLAUDE_CODE_RETRY_WATCHDOGとの関係

CLAUDE_CODE_RETRY_WATCHDOG=1を設定していると、ウォッチドッグが検知した失敗の扱いも変わります。応答ヘッダーが届く前の1回限りの再送上限が外れます。429・529のようなキャパシティ関連のエラーは無期限にリトライし続け、それ以外の一過性エラー(サーバーエラー・タイムアウト・接続断)のリトライ上限も既定の10回から300回まで引き上がります。CIジョブや常駐ワーカーのように、人が張り付いていない環境で長時間の障害を待ち切りたい場合に向いた設定です。ただし、支出上限や利用クレジット枯渇を理由にした429だけは例外で、リトライせずその場でエラーを返します。無制限リトライがコストの歯止めを失わないための線引きです。

ウォッチドッグはバージョンを重ねて拡張されてきた

3層のウォッチドッグと関連変数は、一度に導入されたものではなく、バージョンを重ねて拡張されてきました。

v2.1.229では、Vertex AIやBedrockを上流に持つゲートウェイ接続で、拡張思考中の無通信をSSE keepaliveピングが埋める改善も入りました。こちらはクライアント側のウォッチドッグ設定ではなくサーバー側の対策ですが、同じ「拡張思考中に接続が切れる」症状への対応として関連します。詳細はClaude Code v2.1.229のリリースノートにまとめています。

よくあるつまずき

• CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCKだけ設定してタイムアウト値を変えていない場合、既定のCLAUDE_STREAM_IDLE_TIMEOUT_MS(300秒)が適用されます。拡張思考が5分を超えるタスクでは、オプトインと同時に猶予も伸ばす必要があります
• CLAUDE_STREAM_IDLE_TIMEOUT_MSを5分未満に指定しても、明示指定時の下限として自動的に5分へ引き上げられます。短い値で早期検知させたい場合はCLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS側(下限10秒)を使います
• CLAUDE_ENABLE_BYTE_WATCHDOG=0はバイト単位ウォッチドッグだけでなく最初の1バイト猶予そのものも無効化します。イベント単位の監視だけを残したい場合の設定として意図せず両方を消してしまう組み合わせです
• API_FORCE_IDLE_TIMEOUT=0でボディアイドルタイムアウトを切っても、ウォッチドッグ2種は別枠で動き続けます。無通信を無期限に許容したい場合は、ウォッチドッグ側の値も一緒に見直す必要があります

よくある質問

CLAUDE_STREAM_IDLE_TIMEOUT_MSとAPI_TIMEOUT_MSはどう違いますか

API_TIMEOUT_MSはリクエスト1本全体のタイムアウト(既定10分)で、Request timed outエラーの原因になる値です。CLAUDE_STREAM_IDLE_TIMEOUT_MSは、応答が始まった後に「データが止まる」ことだけを監視するウォッチドッグの猶予です。応答開始前の遅さは前者、開始後の停止は後者が担当します。

プロキシ環境ではどちらを優先して調整すべきですか

社内プロキシ経由の接続は、プロキシ自体がバッファリングして届く間隔が空きやすいため、まずCLAUDE_STREAM_IDLE_TIMEOUT_MSを伸ばすのが最初の一手です。プロキシ設定全体の要点はClaude Codeプロキシ設定で扱っています。

VertexやFoundry経由でもバイト単位ウォッチドッグは動きますか

動きません。バイト単位ウォッチドッグの対象は、直接のAnthropic API・Claude Platform on AWS・ANTHROPIC_BASE_URL等のゲートウェイ接続だけです。Google CloudのAgent PlatformやMicrosoft Foundryでは動作しません。これらの経路ではイベント単位ウォッチドッグとボディアイドルタイムアウトの2層だけが監視を担います。

全部の変数を大きくしておけば安全ですか

猶予を伸ばすほど、本当に応答不能になった接続を検知するまでの時間も延びます。CI等で早期に失敗を検知したい用途では、逆に短めの値との組み合わせが向きます。用途に応じて上げ下げを使い分ける前提の設定です。

まとめ

ストリーミングアイドルウォッチドッグは、応答受信中をイベント単位・バイト単位・ボディアイドルの3層で検知する仕組みです。既定タイムアウトは接続経路によって180秒から300秒まで違います。症状が「最初の応答が来ない」のか「途中で止まる」のかを見分ければ、触るべき変数はほぼ一意に決まります。前者ならCLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS、後者ならCLAUDE_STREAM_IDLE_TIMEOUT_MSです。Bedrock経由だけは既定でバイト単位監視がオフなので、拡張思考の長いタスクを回すならオプトインを忘れずに設定してください。