OpenClaw 通过 Tavily 提供网页搜索和 URL 内容提取，可配置为 web_search 的 provider，或直接调用 tavily_search 和 tavily_extract 插件工具。需要先在 tavily.com 获取 API key，然后在插件配置中填写 TAVILY_API_KEY 环境变量或 plugins.entries.tavily.config.webSearch.apiKey。通过 openclaw configure --section web 可自动启用捆绑插件。搜索支持 basic 和 advanced 深度，内容提取支持 JS 渲染页面，每次最多 20 个 URL。

OpenClaw Tavily 搜索与内容提取配置指南

Tavily 是一个为 AI 应用设计的搜索 API。OpenClaw 以两种方式使用它：

作为通用搜索工具 web_search 的 provider；
作为显式的插件工具：tavily_search 和 tavily_extract。

Tavily 返回针对 LLM 消费优化的结构化结果，支持可配置的搜索深度、主题过滤、域名过滤、AI 生成的答案摘要，以及从 URL（包括 JavaScript 渲染页面）提取内容。

属性	值
插件 ID	`tavily`
认证方式	`TAVILY_API_KEY` 或配置 `apiKey`
基础 URL	`https://api.tavily.com`（默认）
内置工具	`tavily_search`、`tavily_extract`

Getting started

获取 API key

在 [tavily.com](https://tavily.com) 创建账户，然后在控制台生成 API key。

配置插件和 provider

```json5
{
  plugins: {
    entries: {
      tavily: {
        enabled: true,
        config: {
          webSearch: {
            apiKey: "tvly-...", // 如果已设置 TAVILY_API_KEY 可省略
            baseUrl: "https://api.tavily.com",
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        provider: "tavily",
      },
    },
  },
}
```

验证搜索是否生效

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

在引导程序或 openclaw configure --section web 中选择 Tavily 会自动启用捆绑的 Tavily 插件。

工具参考

`tavily_search`

当你需要 Tavily 特有的搜索控制（而非通用 web_search）时使用此工具。

参数	类型	约束/默认值	描述
`query`	string	必填	搜索查询字符串，不超过 400 字符。
`search_depth`	enum	`basic`（默认），`advanced`	`advanced` 更慢但相关性更高。
`topic`	enum	`general`（默认），`news`，`finance`	按主题分类过滤。
`max_results`	integer	1-20（默认 5）	返回结果数量。
`include_answer`	boolean	默认 `false`	包含 Tavily AI 生成的答案摘要。
`time_range`	enum	`day`，`week`，`month`，`year`	按时效过滤结果。
`include_domains`	字符串数组	无	只包含这些域名的结果。
`exclude_domains`	字符串数组	无	排除这些域名的结果。

搜索深度选择：

深度	速度	相关性	最适合
`basic`	较快	高	通用查询（默认）
`advanced`	较慢	最高	精确研究、事实查证

`tavily_extract`

用于从一个或多个 URL 提取干净内容。支持 JavaScript 渲染页面，并可根据查询进行分块以实现精准提取。

参数	类型	约束/默认值	描述
`urls`	字符串数组	必填，1-20 个	要提取内容的 URL。
`query`	string	可选	根据与此查询的相关性重排提取的分块。
`extract_depth`	enum	`basic`（默认），`advanced`	对 JS 密集页面、SPA 或动态表格使用 `advanced`。
`chunks_per_source`	integer	1-5；需要 `query`	每个 URL 返回的分块数。如果未设置 `query` 会报错。
`include_images`	boolean	默认 `false`	在结果中包含图片 URL。

提取深度选择：

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

批量较大的 URL 列表时可以分多次调用 tavily_extract（每次最多 20 个 URL）。使用 query 加 chunks_per_source 只获取相关内容，而非完整页面。

选择合适的工具

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

使用 Tavily 作为 provider 的通用 web_search 工具只支持 query 和 count（最多 20 个结果）。如果需要 Tavily 特有的控制（search_depth、topic、include_answer、域名过滤、时间范围），请直接使用 tavily_search。

高级配置

API key 解析顺序

Tavily 客户端按以下顺序查找 API key：

1. `plugins.entries.tavily.config.webSearch.apiKey`（通过 SecretRefs 解析）。
2. 网关环境变量 `TAVILY_API_KEY`。

如果两者都不存在，`tavily_extract` 会抛出设置错误。

自定义 base URL

如果你想通过代理访问 Tavily，可以覆盖 `plugins.entries.tavily.config.webSearch.baseUrl`。默认为 `https://api.tavily.com`。

chunks_per_source 需要 query

调用 `tavily_extract` 时，如果传了 `chunks_per_source` 但没有 `query`，会报错。因为 Tavily 是按查询相关性对分块排序的，没有查询时该参数无意义。

常见问题

为什么 `tavily_search` 返回的结果比 `web_search` 少？

web_search 作为通用工具只支持 query 和 count，而 tavily_search 支持更多过滤参数（如 search_depth、topic、include_answer、域名过滤等）。结果数量由 max_results 控制，默认 5 条。如果希望获得更多结果，显式设置 max_results: 20。

`tavily_extract` 对 JavaScript 渲染页面不生效怎么办？

尝试将 extract_depth 设为 advanced。basic 适用于简单静态页面；advanced 会渲染 JS 并处理 SPA 或动态表格。如果仍不生效，检查 URL 是否可公开访问，以及 Tavily 服务是否正常。

配置 Tavily 时，API key 如何设置最安全？

推荐通过网关环境变量 TAVILY_API_KEY 设置，避免明文写在配置文件中。也可以在 plugins.entries.tavily.config.webSearch.apiKey 中通过 SecretRefs 引用密钥。如果两者都未设置，tavily_extract 会报错。

OpenClaw Tavily 搜索与内容提取配置指南 ​

Getting started ​

工具参考 ​

tavily_search ​

tavily_extract ​

选择合适的工具 ​

高级配置 ​

常见问题 ​

为什么 tavily_search 返回的结果比 web_search 少？ ​

tavily_extract 对 JavaScript 渲染页面不生效怎么办？ ​

配置 Tavily 时，API key 如何设置最安全？ ​

相关链接 ​