Skip to main content
Tavily 是一个专为 AI 应用设计的搜索 API。OpenClaw 通过两种方式公开它：
  • 作为通用搜索工具的 web_search 提供商
  • 作为显式插件工具：tavily_search 和 tavily_extract
Tavily 返回针对 LLM 消费优化的结构化结果，支持可配置的搜索深度、主题过滤、域名过滤、AI 生成的答案摘要，以及从 URL 提取内容（包括 JavaScript 渲染的页面）。
属性值
插件 IDtavily
包@openclaw/tavily-plugin
认证TAVILY_API_KEY 环境变量或配置 apiKey
基础 URLhttps://api.tavily.com（默认）；TAVILY_BASE_URL 环境变量或配置 baseUrl 可用于覆盖
超时搜索 30 秒，提取 60 秒（默认）
工具tavily_search, tavily_extract

​
入门指南

1

Install the plugin

openclaw plugins install @openclaw/tavily-plugin
2

Get an API key

在 tavily.com 创建 Tavily 账户，然后在仪表板中生成 API key。
3

Configure the plugin and provider

{
  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",
      },
    },
  },
}
4

Verify search runs

从任意智能体触发 web_search，或直接调用 tavily_search。
在新手引导或 openclaw configure --section web 中选择 Tavily，会在需要时安装并启用官方 Tavily 插件。

​
工具参考

当你想使用 Tavily 专属搜索控制，而不是通用 web_search 时，请使用此工具。
参数类型约束 / 默认值描述
query字符串必需搜索查询字符串。
search_depth枚举basic（默认），advancedadvanced 较慢，但相关性更高。
topic枚举general（默认），news，finance按主题类别过滤。
max_results整数1-20，默认 5结果数量。
include_answer布尔值默认 false包含 Tavily AI 生成的答案摘要。
time_range枚举day，week，month，year按新近程度过滤结果。
include_domains字符串数组（无）仅包含来自这些域名的结果。
exclude_domains字符串数组（无）排除来自这些域名的结果。
搜索深度权衡：
深度速度相关性最适合
basic更快高通用查询（默认）。
advanced更慢最高精准研究和事实查找。

​
tavily_extract

使用此工具从一个或多个 URL 提取干净内容。它可以处理 JavaScript 渲染的页面，并支持面向查询的分块，用于目标化提取。
参数类型约束 / 默认值描述
urls字符串数组必需，1-20要从中提取内容的 URL。
query字符串（可选）按与此查询的相关性对提取的分块重新排序。
extract_depth枚举basic（默认），advanced对 JS 密集页面、SPA 或动态表格使用 advanced。
chunks_per_source整数1-5；需要 query每个 URL 返回的分块数。未设置 query 时会报错。
include_images布尔值默认 false在结果中包含图片 URL。
提取深度权衡：
深度使用时机
basic简单页面。先尝试此选项。
advancedJS 渲染的 SPA、动态内容、表格。
将较大的 URL 列表拆分为多次 tavily_extract 调用（每个请求最多 20 个）。使用 query 加 chunks_per_source，只获取相关内容，而不是完整页面。

​
选择合适的工具

需求工具
快速 Web 搜索，无特殊选项web_search
使用深度、主题、AI 答案进行搜索tavily_search
从特定 URL 提取内容tavily_extract
以 Tavily 作为提供商的通用 web_search 工具支持 query 和 count（最多 20 条结果）。如需 Tavily 专属控制（search_depth、topic、include_answer、域名过滤、时间范围），请改用 tavily_search。

​
高级配置

Tavily 客户端按以下顺序查找其 API key：
  1. plugins.entries.tavily.config.webSearch.apiKey（通过 SecretRefs 解析）。
  2. 来自 Gateway 网关环境的 TAVILY_API_KEY。
如果两者都不存在，tavily_search 和 tavily_extract 都会抛出设置错误。
如果你通过代理访问 Tavily，可以覆盖 plugins.entries.tavily.config.webSearch.baseUrl，或设置 TAVILY_BASE_URL。配置优先于环境变量。默认值为 https://api.tavily.com。
tavily_extract 会拒绝传入 chunks_per_source 但未传入 query 的调用。Tavily 会按查询相关性对分块排序，因此没有查询时该参数没有意义。

​
相关内容

Web Search overview

所有提供商和自动检测规则。

Firecrawl

搜索加抓取，并支持内容提取。

Exa Search

带内容提取的神经搜索。

Configuration

插件条目和工具路由的完整配置 schema。