Tavily Quota Router
Use this skill for multi-key Tavily search routing. Do not confuse it with OpenClaw's built-in web_search provider.
What this skill does
- - Reads multiple Tavily API keys from INLINECODE1
- Syncs each key's real usage from Tavily's official
/usage endpoint - Chooses a healthy key automatically before each search
- Skips invalid, rate-limited, exhausted, or cooled-down keys
- Exposes status information for every configured key
Best use cases
Use this skill when the user wants any of the following:
- - Multiple Tavily API keys with automatic routing
- Quota-aware Tavily search instead of single-key search
- Better resilience when one key becomes invalid or temporarily unavailable
- Visibility into per-key usage and remaining plan quota
Files
- -
config/keys.json - active multi-key configuration - INLINECODE4 - configuration example
- INLINECODE5 - local runtime state and cooldown markers
- INLINECODE6 - core router script
If config/keys.json is still empty, copy the structure from config/keys.example.json and add real keys before searching.
Commands
Show status:
CODEBLOCK0
Test all keys:
CODEBLOCK1
Search:
CODEBLOCK2
Reset only local state:
CODEBLOCK3
Usage rules
- 1. Check
config/keys.json first. - If no keys are configured, stop and tell the user to add keys.
- Prefer the bundled script over ad-hoc Tavily requests.
- Be clear that this is a multi-key Tavily wrapper, not the built-in OpenClaw
web_search provider. - If the user later wants this behavior wired into their default search stack, handle that as a separate configuration task instead of silently mutating the built-in provider.
Routing policy
- - Sync usage via Tavily's official
/usage endpoint - Prefer keys with more remaining quota
- Prefer lower
search_usage when remaining quota is comparable - Disable keys on INLINECODE13
- Cool down keys temporarily on transient errors like
429, 5xx, or timeouts
Example config
CODEBLOCK4
Notes
- - This skill relies on Tavily's official API responses for usage and plan data.
- Local state is only used for cooldown/error handling and last synced snapshots.
- This skill is designed for controlled multi-key routing, not anonymous/public key distribution.
Tavily 配额路由器
使用此技能进行多密钥Tavily搜索路由。请勿将其与OpenClaw内置的web_search提供程序混淆。
此技能的功能
- - 从config/keys.json读取多个Tavily API密钥
- 通过Tavily官方/usage端点同步每个密钥的实际使用量
- 在每次搜索前自动选择健康密钥
- 跳过无效、速率受限、配额耗尽或冷却中的密钥
- 展示每个已配置密钥的状态信息
最佳使用场景
当用户需要以下任一功能时使用此技能：
- - 多个Tavily API密钥的自动路由
- 基于配额感知的Tavily搜索（替代单密钥搜索）
- 当某个密钥失效或暂时不可用时获得更好的容错性
- 查看每个密钥的使用情况和剩余计划配额
文件说明
- - config/keys.json - 活跃的多密钥配置
- config/keys.example.json - 配置示例
- state/quota.json - 本地运行时状态和冷却标记
- scripts/tavilymultikey.py - 核心路由脚本
如果config/keys.json仍为空，请从config/keys.example.json复制结构，并在搜索前添加真实密钥。
命令
显示状态：
bash
python3 scripts/tavilymultikey.py status
测试所有密钥：
bash
python3 scripts/tavilymultikey.py test-keys
搜索：
bash
python3 scripts/tavilymultikey.py search --query OpenClaw文档 --count 5
仅重置本地状态：
bash
python3 scripts/tavilymultikey.py reset-month
使用规则
- 1. 首先检查config/keys.json。
- 如果未配置任何密钥，停止并告知用户添加密钥。
- 优先使用捆绑脚本而非临时Tavily请求。
- 明确说明这是一个多密钥Tavily封装器，而非OpenClaw内置的web_search提供程序。
- 如果用户后续希望将此行为集成到默认搜索栈中，应作为单独的配置任务处理，而非静默修改内置提供程序。
路由策略
- - 通过Tavily官方/usage端点同步使用量
- 优先选择剩余配额更多的密钥
- 当剩余配额相当时，优先选择search_usage较低的密钥
- 遇到401/403时禁用密钥
- 遇到429、5xx或超时等临时错误时暂时冷却密钥
配置示例
json
{
cooldown_minutes: 10,
keys: [
tvly-xxx1,
tvly-xxx2
]
}
注意事项
- - 此技能依赖Tavily官方API响应获取使用量和计划数据。
- 本地状态仅用于冷却/错误处理及上次同步快照。
- 此技能专为受控的多密钥路由设计，不适用于匿名/公开密钥分发。
