本页内容

本页内容

工具

Tavily

Tavily 是专为 AI 应用而设计的搜索 API。 OpenClaw 通过两种方式公开它:

  • 作为通用搜索工具的 web_search 提供方
  • 作为显式插件工具:tavily_search 和 tavily_extract

Tavily 返回针对 LLM 使用而优化的结构化结果,具有可配置的搜索深度、主题过滤、域过滤器、AI- 生成的答案摘要以及从 URL(包括 JavaScript- 渲染的页面)中提取内容。

属性 值
插件 id tavily
包裹 @openclaw/tavily-plugin
认证 TAVILY_API_KEY 环境变量或配置 apiKey
基础 URL https://api.tavily.com(默认);可使用 TAVILY_BASE_URL 环境变量或配置 baseUrl 覆盖
超时 30 秒搜索,60 秒提取(默认)
工具 tavily_search, tavily_extract

入门

  • 安装插件

    bash
    openclaw plugins install @openclaw/tavily-plugin
  • 获取 API 密钥

    在 tavily.com 创建 Tavily 账户,然后在控制台中生成 API 密钥。

  • 配置插件和提供程序

    json5
    {  plugins: {    entries: {      tavily: {        enabled: true,        config: {          webSearch: {            apiKey: "tvly-...", // optional if TAVILY_API_KEY is set            baseUrl: "https://api.tavily.com",          },        },      },    },  },  tools: {    web: {      search: {        provider: "tavily",      },    },  },}
  • 验证搜索运行

    从任意 agent 触发一次 web_search,或直接调用 tavily_search。

  • 工具参考

    当您需要 Tavily- 特定搜索控件而不是通用 web_search 时,请使用此选项。

    参数 类型 约束 / 默认 描述
    query 字符串 必填 搜索查询字符串。
    search_depth 枚举 basic(默认)、advanced advanced 更慢,但相关性更高。
    topic 枚举 general(默认)、news、finance 按主题类别筛选。
    max_results 整数 1-20,默认 5 结果数量。
    include_answer 布尔值 默认false 包括 Tavily AI- 生成的答案摘要。
    time_range 枚举 day, week, month, year 按时间新旧筛选结果。
    include_domains 字符串数组 (无) 只包含这些域名中的结果。
    exclude_domains 字符串数组 (无) 排除这些域名中的结果。

    对于发布元数据,请使用 topic: "news"。当 Tavily 提供 published_date 时,OpenClaw 将其返回为 published; GMT 新闻时间戳转换为 ISO 8601。缺少日期、相对年龄和任意文本仍然不存在。 time_range 过滤器并不是发布日期的证据,返回的日期仍然需要对新鲜度敏感的工作流程进行源验证。

    搜索深度取舍:

    深度 速度 相关性 最适合
    basic 更快 高 通用查询(默认)。
    advanced 更慢 最高 精准研究和事实查证。

    tavily_extract

    使用它可以从一个或多个 URL 中提取干净的内容。处理 JavaScript- 渲染页面并支持以查询为中心的分块以进行有针对性的提取。

    参数 类型 约束 / 默认 描述
    urls 字符串数组 必填,1-20 从中提取内容的 URL。
    query 字符串 (可选) 按与此查询的相关性对提取出的片段重新排序。
    extract_depth 枚举 basic(默认)、advanced 将 advanced 用于 JS-heavy 页面、SPA 或动态表。
    chunks_per_source 整数 1-5;需要 query 每个 URL 返回的片段数。如果未设置 query,则报错。
    include_images 布尔值 默认false 在结果中包含图像 URL。

    提取深度取舍:

    深度 何时使用
    basic 简单页面。优先尝试这个。
    advanced JS-渲染的 SPA、动态内容、表格。

    选择合适的工具

    需求 工具
    快速网页搜索,无特殊选项 web_search
    带深度、主题、AI 回答的搜索 tavily_search
    从特定 URL 中提取内容 tavily_extract

    高级配置

    Tavily web_search 和 tavily_search 使用 tools.web.search.cacheTtlMinutes 作为 OpenClaw 的本地结果缓存(默认值:15 分钟)。将其设置为 0 以绕过缓存读写。较短的 TTL 限制了现有条目的重用;较长的 TTL 不会延长其原始有效期。此设置不控制单独的 tavily_extract 缓存。

    API 按键解析顺序

    Tavily 客户端按以下顺序查找 API 密钥:

    1. plugins.entries.tavily.config.webSearch.apiKey(通过 SecretRefs 解析)。
    2. 网关环境中的 TAVILY_API_KEY。

    tavily_search 和 tavily_extract 如果都不存在,则会抛出设置错误。

    定制底座 URL

    如果你通过代理转发 Tavily,可以覆盖 plugins.entries.tavily.config.webSearch.baseUrl,或设置 TAVILY_BASE_URL。配置优先于环境变量。默认值是 https://api.tavily.com。

    `chunks_per_source` 需要 `query`

    tavily_extract 拒绝在没有 query 的情况下通过 chunks_per_source 的呼叫。 Tavily 根据查询相关性对块进行排序,因此如果没有该参数,则该参数毫无意义。

    相关内容

    本页有帮助吗?