故障排除

无需联系支持即可诊断和修复常见问题。

网络/连接超时

症状： 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、查询或密钥。

← 总览快速开始