# Tavily

> Tavily 搜索和提取工具

- 网址：https://funcoding.ai/agents/openclaw/tools/tavily/
- 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/tools/tavily

---
[Tavily](https://tavily.com) 是一款专为 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` 覆盖    |
| 超时时间  | 搜索 30s，提取 60s（默认）                                                                    |
| 工具      | `tavily_search`、`tavily_extract`                                                        |

## 入门指南

**安装插件**

```bash
openclaw plugins install @openclaw/tavily-plugin
```

**获取 API 密钥**

在 [tavily.com](https://tavily.com) 创建 Tavily 账户，然后在仪表板中生成 API 密钥。

**配置插件和提供商**

```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`。

<div class="callout callout-tip">

在新手引导或 `openclaw configure --section web` 中选择 Tavily，会在需要时安装并启用官方 Tavily 插件。

</div>

## 工具参考

### `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` | 字符串数组   | （无）                                   | 排除来自这些域名的结果。                      |

搜索深度权衡：

| 深度              | 速度   | 相关性 | 最适合                               |
| ----------------- | ------ | ------ | ------------------------------------ |
| `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、动态内容和表格。       |

<div class="callout callout-tip">

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

</div>

## 选择合适的工具

| 需求                                 | 工具                   |
| ------------------------------------ | ---------------------- |
| 快速 Web 搜索，无特殊选项            | `web_search`      |
| 使用深度、主题和 AI 回答进行搜索     | `tavily_search`      |
| 从指定 URL 提取内容                  | `tavily_extract`      |

<div class="callout callout-note">

将 Tavily 用作提供商的通用 `web_search` 工具支持 `query` 和 `count`（最多 20 条结果）。如需 Tavily 特有的控制项（`search_depth`、`topic`、`include_answer`、域名筛选、时间范围），请改用 `tavily_search`。

</div>

## 高级配置

<details>
<summary>API 密钥解析顺序</summary>

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

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

如果两者都不存在，`tavily_search` 和 `tavily_extract` 都会引发设置错误。

</details>

<details>
<summary>自定义基础 URL</summary>

如果通过代理转发 Tavily，请覆盖 `plugins.entries.tavily.config.webSearch.baseUrl`，或设置 `TAVILY_BASE_URL`。配置的优先级高于环境变量。默认值为 `https://api.tavily.com`。

</details>

<details>
<summary>`chunks_per_source` 需要 `query`</summary>

如果调用传入 `chunks_per_source` 但未传入 `query`，`tavily_extract` 会拒绝该调用。Tavily 会按内容块与查询的相关性进行排序，因此没有查询时该参数毫无意义。

</details>

## 相关内容

- [Web 搜索概览](https://funcoding.ai/agents/openclaw/tools/web/)：所有提供商和自动检测规则。
- [Firecrawl](https://funcoding.ai/agents/openclaw/tools/firecrawl/)：搜索和抓取，并支持内容提取。
- [Exa Search](https://funcoding.ai/agents/openclaw/tools/exa-search/)：支持内容提取的神经搜索。
- [配置](https://funcoding.ai/agents/openclaw/gateway/configuration/)：插件条目和工具路由的完整配置架构。