Claude Code「Connection timeout」エラーの原因と解決方法｜3つの対処法

エラーの種類を特定する

# 最初の診断コマンド
claude --version  # Claude Codeがインストール済みか確認

# Anthropic APIへの疎通確認
curl -s --max-time 10 https://api.anthropic.com \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "Content-Type: application/json" | head -c 200

# 正常なら {"error":{"type":"not_found_error"...}} が返ってくる
# タイムアウトするなら: curl: (28) Operation timed out after 10000 milliseconds

原因1：ネットワーク接続の問題

# Step 1: DNSとネットワーク疎通確認
ping -c 3 api.anthropic.com
nslookup api.anthropic.com  # 名前解決できるか

# Step 2: HTTPS接続の確認（ポート443）
curl -v --max-time 10 https://api.anthropic.com 2>&1 | grep -E "(Connected|SSL|timeout|error)"

# Step 3: プロキシ設定の確認
echo $HTTPS_PROXY
echo $HTTP_PROXY
echo $NO_PROXY

# VPN使用中の場合：api.anthropic.comをVPNバイパスに追加
# 例（macOS ProxyBypassDomains設定、環境によって異なる）:
# networksetup -setproxybypassdomains "Wi-Fi" "api.anthropic.com" "*.anthropic.com"

原因2：タイムアウト値が短い

# デフォルトのタイムアウトを伸ばす（秒）
export CLAUDE_API_TIMEOUT=300  # 5分

# 現在のセッションだけでなく、.zshrcや.bashrcに追加する場合
echo 'export CLAUDE_API_TIMEOUT=300' >> ~/.zshrc
source ~/.zshrc

# 確認
claude "簡単なテスト"

原因3：長時間かかるタスク

大きなコードベースを読み込む・大量のファイルを処理するタスクはタイムアウトしやすいです。

# ❌ タイムアウトしやすい例
claude "この10万行のコードベース全体を分析して問題を全て見つけて"

# ✅ 分割して処理する例
claude "src/api/ ディレクトリの認証関連コードだけを分析して問題点を挙げて"
claude "src/db/ ディレクトリのクエリ最適化について提案して"

# --print フラグで長い処理をパイプする場合のタイムアウト対策
timeout 120 claude --print "長い処理" || echo "タイムアウト - タスクを分割してください"

CI/CD環境でのリトライ実装

#!/bin/bash
# claude_with_retry.sh - タイムアウト時に自動リトライ

retry_claude() {
    local prompt="$1"
    local max_attempts=3
    local wait_seconds=10
    
    for ((i=1; i<=max_attempts; i++)); do
        echo "試行 $i/$max_attempts..."
        
        if timeout 120 claude --print "$prompt"; then
            echo "✅ 成功"
            return 0
        fi
        
        local exit_code=$?
        if [ $exit_code -eq 124 ]; then
            echo "❌ タイムアウト (試行 $i)"
        else
            echo "❌ エラー (exit code: $exit_code)"
        fi
        
        if [ $i -lt $max_attempts ]; then
            echo "${wait_seconds}秒後にリトライ..."
            sleep $wait_seconds
            wait_seconds=$((wait_seconds * 2))  # 指数バックオフ
        fi
    done
    
    echo "全試行が失敗しました"
    return 1
}

# 使用例
retry_claude "このPythonコードをレビューして: $(cat my_script.py)"

# GitHub Actions での設定例
name: AI Code Review

on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      
      - name: Run AI Review with retry
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          CLAUDE_API_TIMEOUT: "120"
        run: |
          for i in 1 2 3; do
            if timeout 120 claude --print "PRの変更点をレビューして: $(git diff HEAD~1)"; then
              break
            fi
            echo "Retry $i/3..."
            sleep $((i * 15))
          done

プロキシ経由の設定

# HTTP(S)プロキシ経由でClaude Codeを使う
export HTTPS_PROXY="http://proxy.company.internal:8080"
export HTTP_PROXY="http://proxy.company.internal:8080"
export NO_PROXY="localhost,127.0.0.1,.company.internal"

# プロキシ認証が必要な場合
export HTTPS_PROXY="http://user:password@proxy.company.internal:8080"

# 設定後に確認
curl -v --proxy $HTTPS_PROXY https://api.anthropic.com 2>&1 | grep -E "(Connected|proxy|error)"

まだ解決しない場合のチェックリスト

□ status.anthropic.com でサービス障害がないか確認
□ claude --version で最新バージョンかチェック（npm update -g @anthropic-ai/claude-code）
□ ANTHROPIC_API_KEY が正しく設定されているか（echo $ANTHROPIC_API_KEY）
□ APIキーがコンソールで有効状態か（console.anthropic.com）
□ 別のネットワーク（スマートフォンのテザリング等）では動くか
□ それでも解決しない場合: github.com/anthropics/claude-code/issues に報告

あわせて読みたい

• Anthropic APIアカウント停止時の対応｜影響確認コードと復旧手順
• Claude Code制御ルールが機能しない原因と5つの検証方法
• Claude Codeで午前中に機能完成する方法｜16のロール活用で爆速開発