---
read_when:
    - می‌خواهید یک URL را دریافت و محتوای خوانا را استخراج کنید
    - باید web_fetch یا راهکار جایگزین آن، Firecrawl، را پیکربندی کنید
    - می‌خواهید محدودیت‌ها و ذخیره‌سازی موقت web_fetch را درک کنید
sidebarTitle: Web Fetch
summary: ابزار web_fetch — واکشی HTTP همراه با استخراج محتوای خوانا
title: واکشی وب
x-i18n:
    generated_at: "2026-07-12T11:05:23Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 8c956b01fce44dc4b8f3ac289b312691c3fe4293ed2e6777fb53f3345dd99e93
    source_path: tools/web-fetch.md
    workflow: 16
---

`web_fetch` یک درخواست سادهٔ HTTP GET انجام می‌دهد و محتوای خوانا را استخراج می‌کند (تبدیل HTML به
markdown یا متن). این ابزار JavaScript را اجرا **نمی‌کند**. برای وب‌سایت‌های متکی به JS یا
صفحه‌های محافظت‌شده با ورود، به‌جای آن از [مرورگر وب](/fa/tools/browser) استفاده کنید.

## شروع سریع

به‌طور پیش‌فرض فعال است و به پیکربندی نیاز ندارد:

```javascript
await web_fetch({ url: "https://example.com/article" });
```

## پارامترهای ابزار

<ParamField path="url" type="string" required>
URL موردنظر برای دریافت. فقط `http(s)`.
</ParamField>

<ParamField path="extractMode" type="'markdown' | 'text'" default="markdown">
قالب خروجی پس از استخراج محتوای اصلی.
</ParamField>

<ParamField path="maxChars" type="number">
خروجی را به این تعداد نویسه محدود می‌کند. مقدار آن به `tools.web.fetch.maxCharsCap` محدود می‌شود.
</ParamField>

## نحوهٔ کار

<Steps>
  <Step title="دریافت">
    یک درخواست HTTP GET با User-Agent مشابه Chrome و سرآیند `Accept-Language`
    ارسال می‌کند. نام‌های میزبان خصوصی/داخلی را مسدود می‌کند و تغییرمسیرها را دوباره بررسی می‌کند.
  </Step>
  <Step title="استخراج">
    Readability (استخراج محتوای اصلی) را روی پاسخ HTML اجرا می‌کند.
  </Step>
  <Step title="مسیر جایگزین (اختیاری)">
    اگر Readability ناموفق باشد و یک ارائه‌دهندهٔ دریافت در دسترس باشد، درخواست را از طریق
    آن ارائه‌دهنده دوباره امتحان می‌کند (برای مثال، حالت دور زدن ربات Firecrawl).
  </Step>
  <Step title="حافظهٔ نهان">
    نتایج برای ۱۵ دقیقه (قابل پیکربندی) در حافظهٔ نهان نگهداری می‌شوند تا
    دریافت‌های تکراری همان URL کاهش یابد.
  </Step>
</Steps>

## به‌روزرسانی‌های پیشرفت

`web_fetch` فقط زمانی یک خط عمومی پیشرفت نمایش می‌دهد که دریافت پس از پنج ثانیه
همچنان در انتظار باشد:

```text
در حال دریافت محتوای صفحه...
```

اصابت‌های سریع حافظهٔ نهان و پاسخ‌های سریع شبکه پیش از فعال شدن زمان‌سنج پایان می‌یابند؛ بنابراین
هرگز خط پیشرفت نمایش نمی‌دهند. لغو فراخوانی، زمان‌سنج را پاک می‌کند. خط
پیشرفت فقط وضعیت رابط کاربری کانال است و هرگز محتوای دریافت‌شدهٔ صفحه را در بر نمی‌گیرد.

## پیکربندی

```json5
{
  tools: {
    web: {
      fetch: {
        enabled: true, // پیش‌فرض: true
        provider: "firecrawl", // اختیاری؛ برای تشخیص خودکار حذف کنید
        maxChars: 20000, // نویسه‌های خروجی پیش‌فرض؛ محدودشده با maxCharsCap
        maxCharsCap: 20000, // سقف قطعی برای پارامتر maxChars
        maxResponseBytes: 750000, // حداکثر اندازهٔ دانلود پیش از کوتاه‌سازی (32000-10000000)
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        useTrustedEnvProxy: false, // اجازه به پراکسی محیطی مورداعتماد HTTP(S) برای تفکیک DNS
        readability: true, // استفاده از استخراج Readability
        userAgent: "Mozilla/5.0 ...", // جایگزینی User-Agent
        ssrfPolicy: {
          allowRfc2544BenchmarkRange: true, // فعال‌سازی اختیاری برای پراکسی‌های مورداعتماد IP جعلی با محدودهٔ 198.18.0.0/15
          allowIpv6UniqueLocalRange: true, // فعال‌سازی اختیاری برای پراکسی‌های مورداعتماد IP جعلی با محدودهٔ fc00::/7
        },
      },
    },
  },
}
```

## مسیر جایگزین Firecrawl

اگر استخراج Readability ناموفق باشد، `web_fetch` می‌تواند برای دور زدن ربات و استخراج بهتر به
[Firecrawl](/fa/tools/firecrawl) متوسل شود:

```json5
{
  tools: {
    web: {
      fetch: {
        provider: "firecrawl", // اختیاری؛ برای تشخیص خودکار از اعتبارنامه‌های موجود حذف کنید
      },
    },
  },
  plugins: {
    entries: {
      firecrawl: {
        enabled: true,
        config: {
          webFetch: {
            // apiKey: "fc-...", // اختیاری؛ برای دسترسی آغازین بدون کلید حذف کنید
            baseUrl: "https://api.firecrawl.dev",
            onlyMainContent: true,
            maxAgeMs: 172800000, // مدت حافظهٔ نهان (۲ روز)
            timeoutSeconds: 60,
          },
        },
      },
    },
  },
}
```

`plugins.entries.firecrawl.config.webFetch.apiKey` اختیاری است و از اشیای SecretRef پشتیبانی می‌کند.
پیکربندی قدیمی `tools.web.fetch.firecrawl.*` از طریق `openclaw doctor --fix` به‌طور خودکار به
`plugins.entries.firecrawl.config.webFetch` مهاجرت می‌کند.

<Note>
  اگر یک SecretRef کلید API مربوط به Firecrawl را پیکربندی کنید و بدون مسیر جایگزین متغیر محیطی
  `FIRECRAWL_API_KEY` قابل تفکیک نباشد، راه‌اندازی Gateway فوراً شکست می‌خورد.
</Note>

<Note>
  جایگزینی‌های `baseUrl` مربوط به Firecrawl محدود شده‌اند: ترافیک میزبانی‌شده از
  `https://api.firecrawl.dev` استفاده می‌کند؛ جایگزینی‌های خودمیزبان باید مقصدشان نقاط پایانی خصوصی یا
  داخلی باشد و `http://` فقط برای همین مقصدهای خصوصی پذیرفته می‌شود.
</Note>

رفتار فعلی زمان اجرا:

- `tools.web.fetch.provider` ارائه‌دهندهٔ مسیر جایگزین دریافت را به‌صراحت انتخاب می‌کند.
- اگر `provider` حذف شود، OpenClaw نخستین ارائه‌دهندهٔ آمادهٔ دریافت وب را
  از اعتبارنامه‌های پیکربندی‌شده به‌طور خودکار تشخیص می‌دهد. `web_fetch` خارج از محیط ایزوله می‌تواند از
  Pluginهای نصب‌شده‌ای استفاده کند که `contracts.webFetchProviders` را اعلام می‌کنند و
  هنگام اجرا یک ارائه‌دهندهٔ منطبق را ثبت می‌کنند. Plugin رسمی Firecrawl در حال حاضر این
  مسیر جایگزین را فراهم می‌کند.
- فراخوانی‌های `web_fetch` در محیط ایزوله، ارائه‌دهندگان همراه و نیز ارائه‌دهندگان نصب‌شده‌ای را مجاز می‌دانند
  که منشأ رسمی npm یا ClawHub آن‌ها تأیید شده باشد. در حال حاضر این مورد
  Plugin رسمی Firecrawl را مجاز می‌داند؛ Pluginهای خارجی دریافت متعلق به اشخاص ثالث همچنان مستثنا هستند.
- اگر Readability غیرفعال باشد، `web_fetch` مستقیماً به مسیر جایگزین ارائه‌دهندهٔ انتخاب‌شده
  می‌رود. اگر هیچ ارائه‌دهنده‌ای در دسترس نباشد، با حالت بسته شکست می‌خورد.

## پراکسی محیطی مورداعتماد

اگر استقرار شما مستلزم عبور `web_fetch` از یک پراکسی خروجی مورداعتماد
HTTP(S) است، `tools.web.fetch.useTrustedEnvProxy: true` را تنظیم کنید.

در این حالت، OpenClaw همچنان پیش از ارسال درخواست بررسی‌های SSRF مبتنی بر نام میزبان را اعمال
می‌کند، اما به‌جای سنجاق‌کردن محلی DNS، به پراکسی اجازه می‌دهد DNS را تفکیک کند.
این گزینه را فقط زمانی فعال کنید که پراکسی تحت کنترل اپراتور باشد و پس از تفکیک DNS،
سیاست خروجی را اعمال کند.

<Note>
  اگر هیچ متغیر محیطی پراکسی HTTP(S) پیکربندی نشده باشد یا میزبان مقصد با
  `NO_PROXY` مستثنا شده باشد، `web_fetch` به مسیر سخت‌گیرانهٔ عادی با سنجاق‌کردن محلی DNS
  بازمی‌گردد.
</Note>

## محدودیت‌ها و ایمنی

- `maxChars` به `tools.web.fetch.maxCharsCap` (پیش‌فرض `20000`) محدود می‌شود
- بدنهٔ پاسخ پیش از تجزیه به `maxResponseBytes` (پیش‌فرض `750000`، محدودشده به
  32000-10000000) محدود می‌شود؛ پاسخ‌های بیش‌ازحد بزرگ همراه با هشدار کوتاه می‌شوند
- نام‌های میزبان خصوصی/داخلی مسدود می‌شوند
- `tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange` و
  `tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange` گزینه‌های فعال‌سازی محدود
  برای پشته‌های پراکسی مورداعتماد با IP جعلی هستند؛ آن‌ها را تنظیم‌نشده رها کنید، مگر اینکه پراکسی شما مالک
  آن محدوده‌های مصنوعی باشد و سیاست مقصد خودش را اعمال کند
- تغییرمسیرها بررسی می‌شوند و با `maxRedirects` (پیش‌فرض `3`) محدود می‌شوند
- `useTrustedEnvProxy` یک گزینهٔ فعال‌سازی صریح است و فقط باید برای
  پراکسی‌های تحت کنترل اپراتور فعال شود که پس از تفکیک DNS همچنان سیاست خروجی را اعمال می‌کنند
- `web_fetch` بر پایهٔ بهترین تلاش کار می‌کند -- برخی وب‌سایت‌ها به [مرورگر وب](/fa/tools/browser) نیاز دارند

## نمایه‌های ابزار

اگر از نمایه‌های ابزار یا فهرست‌های مجاز استفاده می‌کنید، `web_fetch` یا `group:web` را اضافه کنید:

```json5
{
  tools: {
    allow: ["web_fetch"],
    // یا: allow: ["group:web"]  (شامل web_fetch، web_search و x_search)
  },
}
```

## مرتبط

- [جست‌وجوی وب](/fa/tools/web) -- جست‌وجوی وب با چندین ارائه‌دهنده
- [مرورگر وب](/fa/tools/browser) -- خودکارسازی کامل مرورگر برای وب‌سایت‌های متکی به JS
- [Firecrawl](/fa/tools/firecrawl) -- ابزارهای جست‌وجو و استخراج Firecrawl