---
read_when:
    - می‌خواهید جست‌وجوی وب با پشتیبانی Tavily داشته باشید
    - به یک کلید API برای Tavily نیاز دارید
    - می‌خواهید از Tavily به‌عنوان ارائه‌دهندهٔ web_search استفاده کنید
    - می‌خواهید محتوا را از نشانی‌های اینترنتی استخراج کنید
summary: ابزارهای جست‌وجو و استخراج Tavily
title: Tavily
x-i18n:
    generated_at: "2026-07-12T11:00:06Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 9a61351872eb8aecb0b3ada9b573ee8d3db1dcec3d7bd74074446fbe9dc1f274
    source_path: tools/tavily.md
    workflow: 16
---

[Tavily](https://tavily.com) یک API جست‌وجو است که برای برنامه‌های هوش مصنوعی طراحی شده است. OpenClaw آن را به دو روش ارائه می‌کند:

- به‌عنوان ارائه‌دهندهٔ `web_search` برای ابزار جست‌وجوی عمومی
- به‌عنوان ابزارهای صریح Plugin:‏ `tavily_search` و `tavily_extract`

Tavily نتایج ساختاریافته و بهینه‌شده برای استفادهٔ LLMها را بازمی‌گرداند و عمق جست‌وجوی قابل‌تنظیم، پالایش موضوعی، فیلترهای دامنه، خلاصهٔ پاسخ تولیدشده با هوش مصنوعی و استخراج محتوا از نشانی‌های URL (از جمله صفحه‌های رندرشده با JavaScript) را ارائه می‌دهد.

| ویژگی       | مقدار                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| شناسه Plugin | `tavily`                                                                                                |
| بسته        | `@openclaw/tavily-plugin`                                                                               |
| احراز هویت  | متغیر محیطی `TAVILY_API_KEY` یا پیکربندی `apiKey`                                                       |
| نشانی پایه  | `https://api.tavily.com` (پیش‌فرض)؛ متغیر محیطی `TAVILY_BASE_URL` یا پیکربندی `baseUrl` برای بازنویسی |
| مهلت‌ها     | ۳۰ ثانیه برای جست‌وجو، ۶۰ ثانیه برای استخراج (پیش‌فرض)                                                 |
| ابزارها     | `tavily_search`، `tavily_extract`                                                                       |

## شروع به کار

<Steps>
  <Step title="نصب Plugin">
    ```bash
    openclaw plugins install @openclaw/tavily-plugin
    ```
  </Step>
  <Step title="دریافت کلید API">
    در [tavily.com](https://tavily.com) یک حساب Tavily ایجاد کنید، سپس در داشبورد یک کلید API بسازید.
  </Step>
  <Step title="پیکربندی Plugin و ارائه‌دهنده">
    ```json5
    {
      plugins: {
        entries: {
          tavily: {
            enabled: true,
            config: {
              webSearch: {
                apiKey: "tvly-...", // اگر TAVILY_API_KEY تنظیم شده باشد، اختیاری است
                baseUrl: "https://api.tavily.com",
              },
            },
          },
        },
      },
      tools: {
        web: {
          search: {
            provider: "tavily",
          },
        },
      },
    }
    ```
  </Step>
  <Step title="اطمینان از اجرای جست‌وجو">
    از هر عامل یک `web_search` را اجرا کنید یا مستقیماً `tavily_search` را فراخوانی کنید.
  </Step>
</Steps>

<Tip>
انتخاب Tavily هنگام راه‌اندازی اولیه یا در `openclaw configure --section web`، در صورت نیاز Plugin رسمی Tavily را نصب و فعال می‌کند.
</Tip>

## مرجع ابزارها

### `tavily_search`

زمانی از این ابزار استفاده کنید که به‌جای `web_search` عمومی، کنترل‌های جست‌وجوی اختصاصی Tavily را می‌خواهید.

| پارامتر           | نوع              | محدودیت‌ها / پیش‌فرض                    | توضیحات                                                  |
| ----------------- | ---------------- | --------------------------------------- | -------------------------------------------------------- |
| `query`           | رشته             | الزامی                                  | رشتهٔ پرس‌وجوی جست‌وجو.                                  |
| `search_depth`    | شمارشی           | `basic` (پیش‌فرض)، `advanced`           | `advanced` کندتر است، اما ارتباط بیشتری با موضوع دارد.   |
| `topic`           | شمارشی           | `general` (پیش‌فرض)، `news`، `finance`  | پالایش بر اساس خانوادهٔ موضوعی.                          |
| `max_results`     | عدد صحیح         | ۱ تا ۲۰، پیش‌فرض `5`                    | تعداد نتایج.                                             |
| `include_answer`  | بولی             | پیش‌فرض `false`                         | افزودن خلاصهٔ پاسخ تولیدشده با هوش مصنوعی Tavily.        |
| `time_range`      | شمارشی           | `day`، `week`، `month`، `year`          | پالایش نتایج بر اساس تازگی.                              |
| `include_domains` | آرایه‌ای از رشته | (هیچ‌کدام)                              | فقط نتایج این دامنه‌ها را لحاظ می‌کند.                   |
| `exclude_domains` | آرایه‌ای از رشته | (هیچ‌کدام)                              | نتایج این دامنه‌ها را حذف می‌کند.                        |

موازنهٔ عمق جست‌وجو:

| عمق        | سرعت  | میزان ارتباط | مناسب برای                                    |
| ---------- | ----- | ------------ | --------------------------------------------- |
| `basic`    | سریع‌تر | زیاد         | پرس‌وجوهای عمومی (پیش‌فرض).                   |
| `advanced` | کندتر | بیشترین      | پژوهش دقیق و یافتن اطلاعات واقعی.             |

### `tavily_extract`

برای استخراج محتوای پاک‌سازی‌شده از یک یا چند نشانی URL از این ابزار استفاده کنید. این ابزار صفحه‌های رندرشده با JavaScript را پردازش می‌کند و برای استخراج هدفمند، قطعه‌بندی متمرکز بر پرس‌وجو را پشتیبانی می‌کند.

| پارامتر             | نوع              | محدودیت‌ها / پیش‌فرض            | توضیحات                                                               |
| ------------------- | ---------------- | -------------------------------- | --------------------------------------------------------------------- |
| `urls`              | آرایه‌ای از رشته | الزامی، ۱ تا ۲۰                  | نشانی‌های URL که محتوا باید از آن‌ها استخراج شود.                     |
| `query`             | رشته             | (اختیاری)                        | رتبه‌بندی دوبارهٔ قطعه‌های استخراج‌شده بر اساس ارتباط با این پرس‌وجو. |
| `extract_depth`     | شمارشی           | `basic` (پیش‌فرض)، `advanced`    | برای صفحه‌های سنگین از نظر JS، برنامه‌های تک‌صفحه‌ای یا جدول‌های پویا از `advanced` استفاده کنید. |
| `chunks_per_source` | عدد صحیح         | ۱ تا ۵؛ **نیازمند `query` است**  | تعداد قطعه‌های بازگردانده‌شده برای هر URL. اگر بدون `query` تنظیم شود، خطا می‌دهد. |
| `include_images`    | بولی             | پیش‌فرض `false`                  | افزودن نشانی‌های URL تصاویر به نتایج.                                |

موازنهٔ عمق استخراج:

| عمق        | زمان استفاده                                            |
| ---------- | ------------------------------------------------------- |
| `basic`    | صفحه‌های ساده. ابتدا این گزینه را امتحان کنید.          |
| `advanced` | برنامه‌های تک‌صفحه‌ای رندرشده با JS، محتوای پویا و جدول‌ها. |

<Tip>
فهرست‌های بزرگ‌تر URL را میان چند فراخوانی `tavily_extract` تقسیم کنید (حداکثر ۲۰ مورد در هر درخواست). برای دریافت فقط محتوای مرتبط به‌جای کل صفحه‌ها، از `query` همراه با `chunks_per_source` استفاده کنید.
</Tip>

## انتخاب ابزار مناسب

| نیاز                                          | ابزار              |
| --------------------------------------------- | ------------------ |
| جست‌وجوی سریع وب، بدون گزینه‌های ویژه         | `web_search`       |
| جست‌وجو با عمق، موضوع و پاسخ‌های هوش مصنوعی   | `tavily_search`    |
| استخراج محتوا از نشانی‌های URL مشخص           | `tavily_extract`   |

<Note>
ابزار عمومی `web_search` با Tavily به‌عنوان ارائه‌دهنده، از `query` و `count` (تا ۲۰ نتیجه) پشتیبانی می‌کند. برای کنترل‌های اختصاصی Tavily (`search_depth`، `topic`، `include_answer`، فیلترهای دامنه و بازهٔ زمانی)، به‌جای آن از `tavily_search` استفاده کنید.
</Note>

## پیکربندی پیشرفته

<AccordionGroup>
  <Accordion title="ترتیب تشخیص کلید API">
    کلاینت Tavily کلید API خود را به این ترتیب جست‌وجو می‌کند:

    1. `plugins.entries.tavily.config.webSearch.apiKey` (حل‌شده از طریق SecretRefs).
    2. `TAVILY_API_KEY` از محیط Gateway.

    اگر هیچ‌کدام موجود نباشد، هر دو ابزار `tavily_search` و `tavily_extract` خطای راه‌اندازی ایجاد می‌کنند.

  </Accordion>

  <Accordion title="نشانی پایهٔ سفارشی">
    اگر Tavily را از طریق یک پراکسی در دسترس قرار می‌دهید، `plugins.entries.tavily.config.webSearch.baseUrl` را بازنویسی کنید یا `TAVILY_BASE_URL` را تنظیم کنید. پیکربندی بر متغیر محیطی اولویت دارد. مقدار پیش‌فرض `https://api.tavily.com` است.
  </Accordion>

  <Accordion title="`chunks_per_source` به `query` نیاز دارد">
    `tavily_extract` فراخوانی‌هایی را که `chunks_per_source` را بدون `query` ارسال می‌کنند، رد می‌کند. Tavily قطعه‌ها را بر اساس ارتباط با پرس‌وجو رتبه‌بندی می‌کند؛ بنابراین این پارامتر بدون پرس‌وجو بی‌معنا است.
  </Accordion>
</AccordionGroup>

## مرتبط

<CardGroup cols={2}>
  <Card title="نمای کلی جست‌وجوی وب" href="/fa/tools/web" icon="magnifying-glass">
    همهٔ ارائه‌دهندگان و قواعد تشخیص خودکار.
  </Card>
  <Card title="Firecrawl" href="/fa/tools/firecrawl" icon="fire">
    جست‌وجو به‌همراه خزش و استخراج محتوا.
  </Card>
  <Card title="جست‌وجوی Exa" href="/fa/tools/exa-search" icon="binoculars">
    جست‌وجوی عصبی همراه با استخراج محتوا.
  </Card>
  <Card title="پیکربندی" href="/fa/gateway/configuration" icon="gear">
    طرح‌وارهٔ کامل پیکربندی برای ورودی‌های Plugin و مسیریابی ابزارها.
  </Card>
</CardGroup>