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

Claude Codeは、APIからのストリーミング応答の停止を、応答受信中の3層+応答開始前の1層、計4種類の独立したタイマーで検知します。既定のタイムアウトは接続経路によって180秒から300秒まで幅があり、CLAUDE_STREAM_IDLE_TIMEOUT_MSをはじめとする環境変数で個別に調整できます。まず画面に出たメッセージから層を当て、その層に効く変数だけを触るのが最短です。

画面のメッセージから、どのタイマーが働いたかを逆引きする

打ち切りの原因は、ターン終了時に出るメッセージの文言でおおよそ絞れます。

v2.1.227より前の文言は次のとおりです。The response stopped arrivingはResponse stalled mid-stream、Connection lost mid-responseはConnection closed mid-responseでした。古いバージョンの報告を検索するときは旧文言でも当たります。

応答待ちが20秒続くと、スピナーにWaiting for API response · will retry in …と出ます。打ち切りの前段の表示で、見え方は応答待ちの表示の記事で扱っています。応答が不完全になったときの見え方は「Response incomplete」の通知にまとめています。

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

「ストリーミングアイドルウォッチドッグ」は、公式ドキュメントがこの検知の仕組みに付けた呼び名です。応答を受け取っている最中の3種類に、応答開始前の1種類を足した4つが、それぞれ別の信号を見ています。Claude Code全体の設定の位置づけは、完全ガイドで確認できます。

どの経路でどのタイマーが動くか、既定は何秒かは、次の表のとおりです。

ANTHROPIC_BEDROCK_BASE_URLのようにプロバイダー専用のベースURLで向けたゲートウェイは、バイト単位ウォッチドッグの対象になりません。

応答が止まったときに効く環境変数の早見表

No response from APIの待ち時間は1回目と再送で別々に決まる

最初の1バイトが来ないとき、Claude Codeは1回目と再送で待ち時間を別に決めます。メッセージのwaited 3m, then 10m on the retryは、この2つの実測値です。

どちらの待ち時間も、正の値のAPI_TIMEOUT_MSから1秒引いた時間を超えません。API_TIMEOUT_MSが11秒未満だと、この猶予自体が無効になります。ここから、切り分けが2通りに分かれます。

• 1回目が毎回切れて再送で通る場合は、CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MSを上げて1回目の待ちを延ばします
• 再送も無応答なら、プロキシが応答を溜め込んでいる可能性があります。API_TIMEOUT_MSを上げて再送の待ちを延ばします。Bedrockでは両方を上げます

API_TIMEOUT_MSは、リクエスト1本全体のタイムアウトとしてはRequest timed outエラーの原因にもなる値です。プロキシまわりの設定全体はClaude Codeプロキシ設定で扱っています。API_TIMEOUT_MSだけを上げても、CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MSを指定していなければ1回目の待ちは変わりません。値は上限として働くだけで、バイト単位ウォッチドッグの猶予より長くなる方向には連動しないためです。

環境変数の設定方法

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

export CLAUDE_STREAM_IDLE_TIMEOUT_MS=600000
export CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1

settings.jsonに書くなら、値は文字列で指定します。

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

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

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

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

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

非対話セッション(-p実行やAgent SDK経由)では、テキストだけで途切れツール呼び出しを含まない応答に限り、Claude Codeが自動で最大3回まで続きを促してから通知を出します。サブエージェントは、対話セッションでも同様に続きを促します。

CLAUDE_STREAM_IDLE_TIMEOUT_MSを上げると、ストリームウォッチドッグが有効な間はCLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MSの既定値も一緒に上がります。詳しくは非同期エージェントの停止タイムアウトにあります。

CLAUDE_CODE_RETRY_WATCHDOGとの関係

CLAUDE_CODE_RETRY_WATCHDOG=1を設定していると、リトライの扱いが無人運用向けに変わります。429・529のようなキャパシティ関連のエラーは無期限にリトライし続けます。それ以外の一過性エラー(サーバーエラー・タイムアウト・接続断)は、リトライ上限がv2.1.199以降では既定の10回から300回に上がります。300回はおよそ3時間分のバックオフに当たります。CIジョブや常駐ワーカーのように、人が張り付いていない環境で長時間の障害を待ち切りたい場合に向いた設定です。429・529の待機に上限を付ける方法はMAX_WAIT_MSの解説にあります。

ただし、標準速度のリクエストが支出上限や利用クレジット枯渇を理由にした429を受けた場合は例外で、リトライせずその場でエラーを返します。fast modeのリクエストは扱いが別です。v2.1.239より前は、この種の429も無期限にリトライしていました。

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

4つのタイマーと関連変数は、一度に導入されたものではありません。

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分を超えるタスクでは、オプトインと同時に猶予も伸ばす必要があります
• 思考完了後の2つの文言も、v2.1.227より前は別でした。Connection closed while thinking, before producing a responseとResponse stalled while thinking, before producing a responseです。古い報告と突き合わせるときは、この旧文言で読み替えます
• Server error mid-responseは、ストリームの途中で過負荷や5xxのサーバーエラーが返ったときの文言です。v2.1.199以降に出る表示で、ウォッチドッグとは別の原因なので、タイムアウトの変数を触っても変わりません
• 20秒待ちのスピナー表示は、advisorに相談している間だけ90秒に延びます。相談中は長い間データが来ないことがあるためで、v2.1.214より前は相談中も20秒で出ていました

まとめ

応答が始まる前に止まるのか、始まってから止まるのかで、触る変数が分かれます。前者はCLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MSとAPI_TIMEOUT_MS、後者はCLAUDE_STREAM_IDLE_TIMEOUT_MSです。Bedrockは、バイト単位監視のオプトインが済んでいるかも確認します。