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`

入门¶

1. 安装插件

openclaw plugins install @openclaw/tavily-plugin

2. 获取 API 密钥

在 tavily.com 创建 Tavily 账户，然后在仪表盘中生成 API 密钥。

3. 配置插件和提供程序

{
  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. 验证搜索运行

从任一智能体触发 web_search，或直接调用 tavily_search。

Tip

在引导流程中选择 Tavily，或运行 openclaw configure --section web，将按需安装并启用官方 Tavily 插件。

工具参考¶

`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`	对于 JS 密集型页面、SPA 或动态表格，请使用 `advanced`。
`chunks_per_source`	整数	1-5；需要 `query`	每个 URL 返回的分块数。如果未设置 `query` 则会报错。
`include_images`	布尔	默认 `false`	在结果中包含图片 URL。

提取深度权衡：

深度	使用时机
`basic`	简单页面。请先尝试此选项。
`advanced`	JS 渲染的 SPA、动态内容、表格。

Tip

将较大的 URL 列表分成多个 tavily_extract 调用（每次请求最多 20 个）。使用 query 和 chunks_per_source 只获取相关内容，而不是整个页面。

选择合适的工具¶

需求	工具

需求	工具
快速网络搜索，无特殊选项	`web_search`
支持深度、主题和 AI 答案的搜索	`tavily_search`
从特定 URL 提取内容	`tavily_extract`

Note

使用 Tavily 作为提供商的通用 web_search 工具支持 query 和 count（最多 20 条结果）。对于 Tavily 专属控制项（search_depth、topic、include_answer、域名过滤器、时间范围），请改用 tavily_search。

高级配置¶

Tavily 的 web_search 和 tavily_search 使用 tools.web.search.cacheTtlMinutes 作为 OpenClaw 的本地结果缓存（默认：15 分钟）。将其设置为 0 可绕过缓存读取和写入。较短的 TTL 会限制现有条目的复用；较长的 TTL 不会延长其原始过期时间。此设置不控制独立的 tavily_extract 缓存。

API 密钥解析顺序

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

plugins.entries.tavily.config.webSearch.apiKey（通过 SecretRefs 解析）。
来自网关环境的 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 根据查询相关性对块进行排序，因此没有查询时该参数没有意义。

网络搜索概览

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

Firecrawl

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

Exa Search

支持内容提取的神经搜索。

配置

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

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw