문제 해결

지원 없이 일반적인 문제를 진단하고 해결하세요.

네트워크 / 연결 타임아웃

증상: 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 파라미터 줄이기 (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, 쿼리, 키는 포함되지 않습니다.

← 개요빠른 시작