tavily-search-pro-native-node

Tavily Search Pro (Native Node)

Version: 1.0.20 / public ClawHub utility candidate with external API, cache, and usage-log behavior.

Research-grade Tavily web search helper: one dependency-free Node script with search, extract, stats, and cache subcommands.

Risk / invocation class

Risk class: external research API / credit usage / plaintext query logging.

Use deliberately. This skill sends search queries or URLs to Tavily over HTTPS and may append plaintext queries/URLs to a local usage log unless --no-log is used.

Input packet

Required:

• task: search, extract, usage stats, or cache inspection.
• query_or_urls: search query or URL list when applicable.
• privacy_sensitivity: normal, sensitive, client/private, or unknown.
• freshness_need: normal cache ok, fresh/no-cache, or news/freshness-critical.
• depth: basic unless advanced is justified.

Optional:

• trusted_domains: include/exclude domains.
• max_results: default 5; avoid broad high-result searches unless needed.
• logging_preference: normal log, --no-log, or unknown.
• output_format: human summary or --json.

Stop or switch tools if the query is privacy-sensitive and sending it to Tavily is not appropriate. For one known URL, prefer web_fetch unless extraction quality matters.

Output packet

Return compactly:

• command used or planned, redacted as needed
• whether cache/logging was enabled
• freshness/depth choice
• sources/results with URLs
• estimated credits used or expected when known
• limitations/caveats
• next safe research step

Security behavior

• Reads TAVILY_API_KEY from the process environment only.
• Does not read credential files or ~/.openclaw/.env.
• Makes network calls only to Tavily's HTTPS endpoints:
  • https://api.tavily.com/search
  • https://api.tavily.com/extract
• Writes cache and usage logs only under ~/.openclaw/cache/tavily-search-pro-native-node/.
• Cache filenames are SHA-256-derived request hashes, not plaintext queries.
• Cache entries are not API-account-scoped; if multiple Tavily accounts share the same OS user/home directory, they may share cached results for identical requests. Use separate profiles or --no-cache when account isolation matters.
• Usage logs may contain plaintext search queries/URLs; use --no-log for sensitive calls.
• Local/private URL refusal is a guardrail for obvious mistaken extract targets, not a complete SSRF boundary; Tavily performs extraction from Tavily infrastructure, not this machine.
• Does not read or transmit local files or non-Tavily secrets; sends TAVILY_API_KEY only to Tavily for authentication.
• Does not modify system configuration or auto-update.
• Public-registry static-analysis potential_exfiltration warnings are expected because this tool combines env credentials, local cache/log file access, and Tavily network calls.

When to use

Use this Pro skill when:

• the user needs thorough web research, not just a quick lookup;
• multiple queries are likely and cache will save credits;
• full content extraction from specific URLs is needed;
• Tavily usage/stats matter;
• 429 retry/backoff is useful.

Prefer tavily-search-native-node when:

• a single simple search is enough;
• minimum audit surface matters;
• no disk writes/caching/logging are desired.

Prefer web_fetch for a one-off known URL read.

Do not use when:

• the query is privacy-sensitive and should not leave this machine;
• the user has not approved a sensitive/client/private query to an external research API;
• freshness requires live source browsing and cache state is uncertain, unless --no-cache is used.

Commands

Script: scripts/tavily-pro.mjs

node "\scripts\tavily-pro.mjs" search "OpenClaw skills ecosystem"
node "\scripts\tavily-pro.mjs" extract https://example.com/ https://www.iana.org/help/example-domains
node "\scripts\tavily-pro.mjs" stats
node "\scripts\tavily-pro.mjs" cache info
node "\scripts\tavily-pro.mjs" cache       # defaults to cache info
node "\scripts\tavily-pro.mjs" cache clear  # local deletion; use only after explicit approval
node "\scripts\tavily-pro.mjs" help

For full flags, cache/log behavior, troubleshooting, and publish/update checks, load references/tavily-pro-contract.md.

Operating guidance

• Prefer one well-crafted query over several narrow searches.
• Use basic depth unless advanced is justified; advanced costs more.
• Use --include/--exclude to scope sources when appropriate.
• Use cache by default; use --no-cache when freshness matters. --ttl 0 disables cache reads for that command but still writes the fresh response to cache unless --no-cache is also set.
• Use --no-log --no-cache for sensitive but approved external queries so plaintext query/URL logs are skipped and sensitive research context is not cached.
• For follow-up deep reads: search -> select URLs -> extract.
• Quote sources so the user/requester can verify.
• Track estimated credit usage with stats when research runs get large.
• Treat cache clear as local destructive cleanup; agents should ask before running it.

Required checks before publishing/updating

Minimum no-spend checks:

node --check skills\tavily-search-pro-native-node\scripts\tavily-pro.mjs
node skills\tavily-search-pro-native-node\scripts\tavily-pro.mjs help
node skills\tavily-search-pro-native-node\scripts\tavily-pro.mjs stats --json
node skills\tavily-search-pro-native-node\scripts\self-test.mjs

Also run a no-key smoke test in a temporary home/profile context when feasible to confirm credential errors without spending credits.

Public registry exposure

Classification: public ClawHub utility candidate with external API + local cache/log writes.

Before public update, run sanitizer/static checks and make sure docs clearly disclose:

• external calls to Tavily;
• cache/log file locations and the fact that help/cache output may print a local home-derived cache path; sanitize screenshots/logs before public sharing;
• plaintext query/URL logging;
• expected static-analysis warning;
• no local file/secret exfiltration.

Do not include private/internal/client strategy or operator-specific operational notes in a public release.

Changelog

• 1.0.20: Add ClawHub/OpenClaw runtime metadata for required TAVILY_API_KEY, including requires.env, primaryEnv, and envVars, so declared requirements match the script's env-key behavior. No runtime behavior change. No categories, topics, topic tags, tags, keywords, or ClawHub catalog metadata added to source.
• 1.0.19: Neutralize approval/process wording in header, classification, and changelog notes. No runtime behavior change. No categories, topics, topic tags, tags, keywords, or ClawHub catalog metadata added to source.
• 1.0.18: Normalize prior changelog wording. No runtime behavior change. No categories, topics, topic tags, tags, keywords, or ClawHub catalog metadata added to source.
• 1.0.17: Remove person-specific wording from prior changelog notes. No runtime behavior change. No categories, topics, topic tags, tags, keywords, or ClawHub catalog metadata added to source.
• 1.0.16: Clarify ClawHub candidate posture in the header and document that local/private URL refusal is a best-effort guardrail for obvious mistaken extract targets, not a complete SSRF boundary. No runtime behavior change. No categories, topics, topic tags, tags, keywords, or ClawHub catalog metadata added to source.
• 1.0.15: Input-validation polish: restrict IPv6 ULA fc00::/7 refusal to actual IPv6 literals so public DNS names beginning with fc/fd are not overblocked, while retaining ULA and link-local refusal before API key load/Tavily transmission. Adds self-test coverage for ULA and public fc*/fd* hostnames. No categories, topics, topic tags, tags, keywords, or ClawHub catalog metadata added to source.
• 1.0.14: Input-validation polish: correctly block the full IPv6 link-local fe80::/10 range (fe80 through febf) before API key load/Tavily transmission and add self-test coverage for boundary examples. No categories, topics, topic tags, tags, keywords, or ClawHub catalog metadata added to source.
• 1.0.13: Input-validation polish: block IPv6 link-local fe80::/10 extract URLs before API key load/Tavily transmission, add self-test coverage, and align frontmatter description with source wording. No categories, topics, topic tags, tags, keywords, or ClawHub catalog metadata added to source.
• 1.0.12: Polish source wording from “toolkit” to web search, clarify estimated credit labels/docs, document --ttl 0 cache-read semantics and default cache behavior, reject local/private extract URLs before Tavily transmission, and avoid standing publishability wording. No categories, topics, topic tags, tags, keywords, or ClawHub catalog metadata added to source.
• 1.0.11: Version refresh; no runtime behavior change.
• 1.0.10: Gate TAVILY_PRO_MOCK_JSON behind TAVILY_PRO_SELFTEST=1, add inert-hook regression, and reject unexpected cache clear arguments.
• 1.0.9: Add request timeout support, strict stats/cache info argument rejection, and no-spend self-tests.
• 1.0.8: Tighten public docs for cache-key precision and retry-attempt wording.
• 1.0.7: Document that cache entries are request-scoped, not API-account-scoped, so shared OS profiles may share cached results.
• 1.0.6: Add frontmatter version metadata and align reference docs so cache clear is consistently marked as local deletion requiring explicit approval.
• 1.0.5: Public package wording/metadata cleanup; cache/log/security behavior unchanged.