Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

ストリーミングのアイドルウォッチドッグが、すべてのプロバイダーでデフォルトで有効になりました。レスポンスストリームが5分間イベントを生成しない場合、ストリームを中断（abort）してリトライします。無効化するには CLAUDE_ENABLE_STREAM_WATCHDOG=0 を設定してください。

原文（英語） ​

The streaming idle watchdog is now on by default for all providers — it aborts and retries when a response stream produces no events for 5 minutes. Set CLAUDE_ENABLE_STREAM_WATCHDOG=0 to disable.

概要 ​

Claude Codeのストリーミング応答（AIの回答を逐次受信する仕組み）には、ストリームが完全にハングしてしまうケースに備えた「アイドルウォッチドッグ」が存在します。HTTPヘッダーは届いたものの、その後レスポンスボディのイベントがまったく流れてこない状態が5分間続くと、ウォッチドッグがリクエストを自動的に中断し、通常のリトライ経路で再試行します。これまでは一部の接続経路でのみ有効でしたが、今回のアップデートでAnthropic API・Bedrock・Vertex AI・Foundryなど、すべてのプロバイダーでデフォルト有効になりました。動作が不要な場合は環境変数 CLAUDE_ENABLE_STREAM_WATCHDOG=0 で無効化できます。

基本的な使い方 ​

デフォルトで有効なため、通常は何も設定する必要はありません。ストリームがハングした場合、Claude Codeが自動的に検知して中断・リトライします。

bash
# 何も設定しなくても、デフォルトでウォッチドッグが有効
claude

# 5分間ストリームが無応答の場合 → 自動的にabortしてリトライ

無効化したい場合は環境変数を設定します。

bash
# ウォッチドッグを無効化（非推奨だが、特殊な環境では有用）
export CLAUDE_ENABLE_STREAM_WATCHDOG=0
claude

実践例 ​

不安定なネットワーク環境での利用 ​

Wi-Fiの瞬断やVPN経由の接続など、ネットワークが不安定な環境では、ストリームがハングしたまま応答が返ってこなくなることがあります。デフォルト有効化により、こうした状況でも自動的に回復します。

bash
# 不安定な回線でもデフォルトのまま利用するだけでOK
claude "長いリファクタリングを実行してください"

# ストリームが5分間止まった場合:
# → Claude Codeがリクエストをabortし、自動的にリトライ
# → ユーザーが手動でCtrl+Cして再実行する必要がない

CI環境でのハング防止 ​

CI/CDパイプラインでClaude Codeを使う場合、ストリームがハングしたままジョブがタイムアウトしてしまうと無駄な待機時間が発生します。ウォッチドッグが有効であれば、最大5分でリクエストが中断・再試行されるため、ジョブ全体が長時間ハングするリスクを抑えられます。

yaml
# GitHub Actions の例
- name: Run Claude Code
  env:
    # デフォルトのままウォッチドッグを有効にしておく
    CLAUDE_ENABLE_STREAM_WATCHDOG: "1"
  run: claude -p "テストを実行して結果を要約してください"

サードパーティ経由のゲートウェイ・プロキシ環境 ​

社内プロキシやAPIゲートウェイを経由している場合、ストリームのアイドル検知タイムアウトを調整したいことがあります。関連する環境変数 CLAUDE_STREAM_IDLE_TIMEOUT_MS（デフォルトはミリ秒単位の閾値）と組み合わせて利用できます。

bash
# ウォッチドッグは有効のまま、アイドルタイムアウトの閾値を調整したい場合
export CLAUDE_ENABLE_STREAM_WATCHDOG=1
export CLAUDE_STREAM_IDLE_TIMEOUT_MS=300000  # 5分（デフォルト相当）
claude

動作比較（有効 / 無効） ​

[CLAUDE_ENABLE_STREAM_WATCHDOG が有効（デフォルト）]
1. ストリーミング応答を受信開始
2. 何らかの理由でストリームが完全に停止（イベントが流れてこない）
3. 5分間イベントなしが続く
4. ✅ ウォッチドッグがリクエストをabort
5. ✅ 通常のリトライ経路で自動的に再試行

[CLAUDE_ENABLE_STREAM_WATCHDOG=0（無効化した場合）]
1. ストリーミング応答を受信開始
2. 何らかの理由でストリームが完全に停止
3. ❌ 自動的なabort・リトライが行われない
4. ❌ ユーザーが手動でCtrl+Cするまで応答待ち状態が継続する可能性

注意点 ​

  • 無効化（CLAUDE_ENABLE_STREAM_WATCHDOG=0）は基本的に推奨されません。ハングしたストリームに対する自動回復が失われ、応答が返ってこないまま待ち続けるリスクがあります。
  • ウォッチドッグが反応するのは「ヘッダー受信後、ボディのイベントが5分間まったく流れない」場合です。応答生成自体に時間がかかっている（トークン生成が継続している）通常の長時間応答では発火しません。
  • 関連する環境変数として CLAUDE_STREAM_IDLE_TIMEOUT_MS があり、アイドル判定までの閾値（ミリ秒）を調整できます。
  • 同バージョンでは、ストリームキャンセル時にウォッチドッグのタイマーが正しくクリアされず、応答完了から5分後に誤って「stream idle timeout」が発生する不具合も修正されています。
  • Anthropic API・Bedrock・Vertex AI・Foundryなど、利用しているプロバイダーによらず共通の挙動になりました。これまでは接続経路によって有効/無効の挙動が異なっていました。

関連情報 ​