Tavily Search Pro（原生 Node 版）

版本：1.0.20 / 公共 ClawHub 工具候选者，集成外部 API、缓存及使用日志功能。

面向研究级任务的 Tavily 网络搜索辅助工具：单个无依赖的 Node 脚本，支持 search、extract、stats 和 cache 子命令。

风险等级 / 调用类别

风险等级：外部研究 API / 信用额度消耗 / 明文查询日志记录。

请谨慎使用。该技能通过 HTTPS 将搜索查询或 URL 发送至 Tavily，并可能将明文查询/URL 追加写入本地使用日志，除非显式指定 --no-log 参数。

输入数据包

必需字段：

• task：执行搜索、内容提取、用量统计或缓存检查。
• query_or_urls：适用时提供搜索查询字符串或 URL 列表。
• privacy_sensitivity：取值为 normal、sensitive、client/private 或 unknown。
• freshness_need：取值为 normal cache ok（允许使用缓存）、fresh/no-cache（强制不使用缓存）或 news/freshness-critical（对时效性要求极高）。
• depth：默认为 basic；仅当有充分理由时才启用 advanced 模式。

可选字段：

• trusted_domains：指定需包含或排除的域名列表。
• max_results：默认值为 5；除非确有需要，否则应避免宽泛且高结果数的搜索请求。
• logging_preference：取值为 normal log（默认日志）、--no-log（禁用日志）或 unknown。
• output_format：返回人类可读摘要，或使用 --json 输出结构化 JSON。

若查询涉及隐私敏感信息，且将其发送至 Tavily 不合适，请立即中止或切换至其他工具。对于已知的单一 URL，如无需高质量内容提取，优先使用 web_fetch。

输出数据包

以紧凑格式返回以下内容：

• 实际执行或计划执行的命令（必要时进行脱敏处理）
• 缓存与日志功能是否启用
• 所选的时效性策略与深度模式
• 来源与结果（含对应 URL）
• 已知情况下预估或实际消耗的信用额度
• 限制条件与注意事项
• 下一步安全可行的研究操作

安全行为

• 仅从进程环境变量中读取 TAVILY_API_KEY。
• 不读取任何凭证文件，也不读取 ~/.openclaw/.env。
• 网络调用仅限于 Tavily 的 HTTPS 接口：
  • https://api.tavily.com/search
  • https://api.tavily.com/extract
• 缓存与使用日志仅写入 ~/.openclaw/cache/tavily-search-pro-native-node/ 目录下。
• 缓存文件名基于请求内容生成 SHA-256 哈希值，不含明文查询。
• 缓存条目未按 API 账户隔离；若多个 Tavily 账户共享同一操作系统用户及主目录，则相同请求可能命中彼此缓存结果。在需账户隔离场景下，请使用独立 profile 或显式指定 --no-cache。
• 使用日志中可能包含明文搜索查询/URL；对敏感调用请务必使用 --no-log。
• 拒绝本地/私有 URL 是一项针对明显误用提取目标的防护机制，而非完整的 SSRF 边界；Tavily 的内容提取由其自身基础设施执行，而非本机。
• 不读取或传输任何本地文件或非 Tavily 类型的密钥；仅向 Tavily 发送 TAVILY_API_KEY 用于身份验证。
• 不修改系统配置，也不自动更新。
• 公共注册中心静态分析报告中的 potential_exfiltration 警告属于预期行为，因本工具同时涉及环境变量凭据读取、本地缓存/日志文件访问以及对 Tavily 的网络调用。

适用场景

在以下情形中使用本 Pro 技能：

• 用户需要深度网络调研，而不仅是一次快速查证；
• 预计会发起多次查询，缓存机制可节省信用额度；
• 需对特定 URL 执行完整内容提取；
• 需关注 Tavily 的用量统计或配额状态；
• 需利用 429 状态码触发的重试与退避机制。

在以下情形中优先选用 tavily-search-native-node：

• 一次简单搜索即可满足需求；
• 最小化审计面（audit surface）是关键考量；
• 不希望产生任何磁盘写入、缓存或日志记录。

对单次已知 URL 的读取操作，请优先使用 web_fetch。

禁止使用的情形：

• 查询涉及隐私敏感信息，不应离开本机；
• 用户尚未明确授权将敏感/客户/私有类查询提交至外部研究 API；
• 时效性要求极高，必须实时浏览原始网页，且当前缓存状态不确定——除非已显式启用 --no-cache。

命令

脚本路径：scripts/tavily-pro.mjs

node "scriptstavily-pro.mjs" search "OpenClaw skills ecosystem"
node "scriptstavily-pro.mjs" extract https://example.com/ https://www.iana.org/help/example-domains
node "scriptstavily-pro.mjs" stats
node "scriptstavily-pro.mjs" cache info
node "scriptstavily-pro.mjs" cache       # 默认执行 cache info
node "scriptstavily-pro.mjs" cache clear  # 本地删除操作；仅在获得明确批准后执行
node "scriptstavily-pro.mjs" help

如需查阅完整参数说明、缓存/日志行为细节、故障排查指南及发布/更新校验流程，请加载 references/tavily-pro-contract.md。

运行指导

• 优先构造一个高质量的查询，而非发起多个狭窄范围的搜索。
• 除非确有理由，否则始终使用 basic 深度；advanced 模式成本更高。
• 在适当时使用 --include/--exclude 限定信息来源范围。
• 默认启用缓存；当时效性至关重要时，请使用 --no-cache。参数 --ttl 0 将禁用本次命令的缓存读取，但仍会将新响应写入缓存——除非同时指定 --no-cache。
• 对已获批准但属敏感的外部查询，请使用 --no-log --no-cache，以跳过明文查询/URL 日志记录，并避免将敏感研究上下文缓存至本地。
• 针对后续深度阅读：先执行搜索 → 筛选目标 URL → 再执行提取。
• 引用所有信息源，便于用户/请求方验证。
• 当研究任务规模扩大时，使用 stats 命令跟踪预估信用额度消耗。
• 将 cache clear 视为本地破坏性清理操作；智能体在执行前应主动确认。

发布/更新前必需检查项

最低限度的零消耗检查：

node --check skillstavily-search-pro-native-nodescriptstavily-pro.mjs
node skillstavily-search-pro-native-nodescriptstavily-pro.mjs help
node skillstavily-search-pro-native-nodescriptstavily-pro.mjs stats --json
node skillstavily-search-pro-native-nodescriptsself-test.mjs

如条件允许，还应在临时 home/profile 环境中运行一次无密钥冒烟测试（no-key smoke test），以确认凭证错误提示是否正常，且不产生信用额度消耗。

公共注册中心暴露情况

分类：公共 ClawHub 工具候选者，集成外部 API + 本地缓存/日志写入。

在公开更新前，须运行净化/静态分析检查，并确保文档清晰披露以下内容：

• 对外部 Tavily 服务的调用；
• 缓存/日志文件的具体路径，以及帮助信息或缓存输出中可能打印出基于本地 home 目录推导出的缓存路径；对外分享截图或日志前须完成脱敏处理；
• 明文查询/URL 的日志记录行为；
• 静态分析工具预期发出的警告；
• 不存在本地文件或密钥外泄行为。

切勿在公开发布版本中包含私有/内部/客户专属策略，或运维人员专用的操作备注。

更新日志

• 1.0.20：为 ClawHub/OpenClaw 运行时元数据补充关于必需环境变量 TAVILY_API_KEY 的声明，包括 requires.env、primaryEnv 和 envVars 字段，使声明的依赖项与脚本实际的环境变量行为保持一致。无运行时行为变更。源码中未添加任何分类、主题、主题标签、标签、关键词或 ClawHub 目录元数据。
• 1.0.19：中立化标题、分类及更新日志中有关审批/流程的措辞。无运行时行为变更。源码中未添加任何分类、主题、主题标签、标签、关键词或 ClawHub 目录元数据。
• 1.0.18：规范化前期更新日志表述。无运行时行为变更。源码中未添加任何分类、主题、主题标签、标签、关键词或 ClawHub 目录元数据。
• 1.0.17：移除前期更新日志中涉及具体人员的表述。无运行时行为变更。源码中未添加任何分类、主题、主题标签、标签、关键词或 ClawHub 目录元数据。
• 1.0.16：在标题中进一步明确 ClawHub 候选者定位，并在文档中说明“拒绝本地/私有 URL”仅为一种尽最大努力（best-effort）的防护机制，用于拦截明显误用的提取目标，而非完整的 SSRF 边界。无运行时行为变更。源码中未添加任何分类、主题、主题标签、标签、关键词或 ClawHub 目录元数据。
• 1.0.15：优化输入校验逻辑：将 IPv6 ULA 地址段 fc00::/7 的拒绝规则限制为真正的 IPv6 字面量，避免误阻断以 fc/fd 开头的公网 DNS 域名，同时在加载 API 密钥及向 Tavily 发送请求前，仍保留对 ULA 及链路本地地址的拒绝策略。新增针对 ULA 地址及公网 fc*/fd* 主机名的自测覆盖。源码中未添加任何分类、主题、主题标签、标签、关键词或 ClawHub 目录元数据。
• 1.0.14：优化输入校验逻辑：在加载 API 密钥及向 Tavily 发送请求前，完整屏蔽 IPv6 链路本地地址段 fe80::/10（即 fe80 至 febf），并补充边界案例的自测覆盖。源码中未添加任何分类、主题、主题标签、标签、关键词或 ClawHub 目录元数据。
• 1.0.13：优化输入校验逻辑：在加载 API 密钥及向 Tavily 发送请求前，屏蔽 IPv6 链路本地地址 fe80::/10 的提取 URL，并补充相应自测覆盖；同时统一前置元数据（frontmatter）描述与源码表述。源码中未添加任何分类、主题、主题标签、标签、关键词或 ClawHub 目录元数据。
• 1.0.12：将源码中 “toolkit” 表述统一调整为 “web search”，明确信用额度估算的标注与文档说明，完善 --ttl 0 缓存读取语义及默认 cache 行为的文档，拒绝本地/私有提取 URL 并阻止其抵达 Tavily，同时避免使用暗示“随时可发布”的措辞。源码中未添加任何分类、主题、主题标签、标签、关键词或 ClawHub 目录元数据。
• 1.0.11：版本号刷新；无运行时行为变更。
• 1.0.10：将 TAVILY_PRO_MOCK_JSON 的启用条件限定为 TAVILY_PRO_SELFTEST=1，新增惰性钩子（inert-hook）回归测试，并拒绝意外传入的 cache clear 参数。
• 1.0.9：新增请求超时支持，严格校验 stats/cache info 的参数合法性，并加入零消耗自测用例。
• 1.0.8：收紧公开文档中关于缓存键精度及重试尝试次数的表述。
• 1.0.7：明确说明缓存条目按请求作用域划分，而非按 API 账户隔离，因此共享同一操作系统 profile 的用户可能共享相同请求的缓存结果。
• 1.0.6：在前置元数据中增加版本字段，并同步参考文档，确保 cache clear 始终被明确标记为需显式批准的本地删除操作。
• 1.0.5：公共包相关措辞与元数据清理；缓存/日志/安全行为均无变更。