トラブルシューティング

サポートなしで一般的な問題を診断・修正。

ネットワーク / 接続タイムアウト

症状： curlがハング、接続拒否、またはDNS解決が失敗
考えられる原因
  • •ファイアウォールがapi.whisperx.aiへのHTTPS送信をブロック
  • •VPNルーティングの問題
  • •DNS設定ミス
修正

接続をステップバイステップでテスト：

# 1. DNS resolution
nslookup api.whisperx.ai

# 2. TCP port 443
nc -zv api.whisperx.ai 443

# 3. HTTPS GET
curl -v --max-time 5 "https://api.whisperx.ai/api/tags/trending"

ステップ1が失敗：DNS設定を確認。ステップ2が失敗：ファイアウォールがポート443をブロック — ネットワーク管理者に連絡。ステップ3が失敗：TLSの問題 — システムの証明書を更新してください。

空の結果

症状： 検索が { "data": [] } を返す
考えられる原因
  • •クエリが特定的すぎるかニッチすぎる
  • •タグフィルターが限定的すぎる
  • •since の日付が最近すぎる
  • •セクターフィルターが一致するインテルを除外している
修正

段階的に広いクエリを試してください：

# Remove tag filter
curl "https://api.whisperx.ai/api/intel?q=OpenAI&limit=10"

# Remove sector filter
curl "https://api.whisperx.ai/api/intel?q=layoff&limit=10"

# Extend time window (no since filter)
curl "https://api.whisperx.ai/api/intel?q=funding&limit=10"

# Try trending tags to see what's active
curl "https://api.whisperx.ai/api/tags/trending?limit=20"

空の結果はエラーではありません — 現在フィルターに一致するインテルがないことを意味します。プラットフォームは毎日成長しています。明日再試行するかより広い検索を。

429 — レート制限

症状： HTTP 429またはレート制限に言及するエラーメッセージ
考えられる原因
  • •同一IPから1分間に60回以上のAPI呼び出し
  • •リクエスト間に遅延のない自動ループ
  • •1つの接続を共有する複数のエージェント
修正

バックオフして頻度を減らす：

  • • リトライ前に60秒待機
  • • スクリプトのリクエスト間にsleep 2を追加
  • • limitパラメータを減らす（50の代わりに5〜10を試す）
  • • トレンドタグをキャッシュ — ゆっくり変化するので毎分ポーリング不要

本番環境でより高いレート制限が必要な場合、 お問い合わせ.

5xx — サーバーエラー

症状： HTTP 500、502、または503レスポンス
考えられる原因
  • •一時的な上流エラー
  • •負荷下でのワーカーコールドスタート
  • •データベースが一時的に利用不可
修正

リトライ戦略：

# Retry once after 10 seconds
sleep 10 && curl "https://api.whisperx.ai/api/intel?q=test&limit=1"

# If 5xx persists, fall back to trending tags (lighter endpoint)
curl "https://api.whisperx.ai/api/tags/trending?limit=10"

エラーが5分以上続く場合は確認 whisperx.ai でステータス更新を確認。ほとんどの問題は数分以内に解決します。

遅いレスポンス / タイムアウト

症状： リクエストが5秒以上かかる、またはOpenClawでツール呼び出しがタイムアウト
考えられる原因
  • •セマンティック検索が有効（フルテーブルスキャン — 非常に高コスト）
  • •limitが高すぎる（>50）
  • •Cloudflareエッジへのネットワーク遅延
修正

セマンティック検索を無効にしてlimitを下げる：

# Good: keyword search, compact mode, small limit
curl "https://api.whisperx.ai/api/intel?q=OpenAI&mode=compact&limit=10"

# Bad: semantic search (avoid — full-table scan)
# /api/intel?semantic=... ← do NOT use this

WhisperXスキルはセマンティック検索を自動的に無効化します。APIを直接呼び出す場合、本番環境でsemanticパラメータは絶対に使用しないでください。

スキルが見つからない / ツールが読み込めない

症状： OpenClawがwhisperxツールを認識しないまたはSKILL.mdが見つからない
考えられる原因
  • •スキルが間違ったディレクトリにインストール済み
  • •SKILL.mdが欠落または空
  • •シェルスクリプトが実行可能でない
  • •WHISPERX_BASE_URL環境変数の設定が誤り
修正

インストールを確認：

# Check skill files exist
ls ~/.claude/skills/whisperx/
# Expected: SKILL.md  tools/

ls ~/.claude/skills/whisperx/tools/
# Expected: search.sh  get.sh  trending.sh  trends.sh  connections.sh  export.sh

# Check scripts are executable
ls -la ~/.claude/skills/whisperx/tools/*.sh
# Should show -rwxr-xr-x permissions

# Fix permissions if needed
chmod +x ~/.claude/skills/whisperx/tools/*.sh

# Quick smoke test
bash ~/.claude/skills/whisperx/tools/trending.sh 5

まだ動かない？以下からインストールを再実行 クイックスタートガイド.

診断レポートを生成

まだ解決しない場合、これを実行して共有可能な診断バンドルを生成（機密データなし）：

echo "=== WhisperX Diagnostic ===" && \
echo "Date: $(date -u)" && \
echo "OS: $(uname -a)" && \
echo " && \
echo "--- Connectivity ---" && \
curl -s -o /dev/null -w "HTTP %{http_code} | Time %{time_total}s" \
  "https://api.whisperx.ai/api/tags/trending?limit=1" && \
echo " && \
echo "--- Skill files ---" && \
ls -la ~/.claude/skills/whisperx/tools/ 2>/dev/null || echo "Skill not installed"

サポート依頼時に出力を貼り付けてください。IP、クエリ、キーは含まれません。

← 概要クイックスタート