故障排除

無需聯絡支援即可診斷和修復常見問題。

網路／連線逾時

症狀： 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 每分鐘超過 60 次 API 呼叫
  • •自動循環請求間無延遲
  • •多個智慧體共用一個連線
修復

退避並降低頻率：

  • • 重試前等待 60 秒
  • • 在腳本中的請求之間加入 sleep 2
  • • 減小 limit 參數（嘗試 5–10 而非 50）
  • • 快取熱門標籤 —— 變化緩慢，無需每分鐘輪詢

若需要更高頻率限制用於生產環境， 聯絡我們.

5xx —— 伺服器錯誤

症狀： HTTP 500、502 或 503 回應
可能的原因
  • •上游暫時性錯誤
  • •高負載時 Worker 冷啟動
  • •資料庫暫時不可用
修復

重試策略：

# 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 Skill 自動停用語意搜尋。若你直接呼叫 API，生產環境中不要使用 semantic 參數。

找不到 Skill / 工具未載入

症狀： OpenClaw 無法識別 whisperx 工具或找不到 SKILL.md
可能的原因
  • •Skill 安裝到了錯誤的目錄
  • •SKILL.md 缺失或為空
  • •Shell 腳本沒有執行權限
  • •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、查詢或金鑰。

← 總覽快速開始