جستجوی وب

ابزار web_search با استفاده از ارائه‌دهنده پیکربندی‌شده شما در وب جست‌وجو می‌کند و نتایج را برمی‌گرداند. نتایج بر اساس پرس‌وجو به مدت ۱۵ دقیقه (قابل پیکربندی) کش می‌شوند.

OpenClaw همچنین شامل x_search برای پست‌های X (که پیش‌تر Twitter نام داشت) و web_fetch برای واکشی سبک URL است. در این مرحله، web_fetch محلی می‌ماند در حالی که web_search و x_search می‌توانند در پشت صحنه از xAI Responses استفاده کنند.

# شروع سریع

openclaw configure --section web

await web_search({ query: "OpenClaw plugin SDK" });

await x_search({ query: "dinner recipes" });

# انتخاب یک ارائه‌دهنده

# مقایسه ارائه‌دهنده‌ها

# تشخیص خودکار

# جست‌وجوی وب بومی OpenAI

مدل‌های مستقیم OpenAI Responses وقتی جست‌وجوی وب OpenClaw فعال باشد و هیچ ارائه‌دهنده مدیریت‌شده‌ای سنجاق نشده باشد، به‌طور خودکار از ابزار میزبانی‌شده web_search متعلق به OpenAI استفاده می‌کنند. این رفتار متعلق به ارائه‌دهنده در Plugin بسته‌بندی‌شده OpenAI است و فقط برای ترافیک API بومی OpenAI اعمال می‌شود، نه URLهای پایه پروکسی سازگار با OpenAI یا مسیرهای Azure. برای حفظ ابزار مدیریت‌شده web_search برای مدل‌های OpenAI، tools.web.search.provider را روی ارائه‌دهنده دیگری مانند brave تنظیم کنید، یا برای غیرفعال کردن هم جست‌وجوی مدیریت‌شده و هم جست‌وجوی بومی OpenAI، tools.web.search.enabled: false را تنظیم کنید.

# جست‌وجوی وب بومی Codex

مدل‌های سازگار با Codex می‌توانند به‌صورت اختیاری به‌جای تابع مدیریت‌شده web_search متعلق به OpenClaw، از ابزار web_search بومی ارائه‌دهنده در Responses استفاده کنند.

• آن را زیر tools.web.search.openaiCodex پیکربندی کنید
• فقط برای مدل‌های سازگار با Codex فعال می‌شود (openai-codex/* یا ارائه‌دهندگانی که از api: "openai-codex-responses" استفاده می‌کنند)
• web_search مدیریت‌شده همچنان برای مدل‌های غیر Codex اعمال می‌شود
• mode: "cached" تنظیم پیش‌فرض و پیشنهادی است
• tools.web.search.enabled: false هم جست‌وجوی مدیریت‌شده و هم جست‌وجوی بومی را غیرفعال می‌کند

{
  tools: {
    web: {
      search: {
        enabled: true,
        openaiCodex: {
          enabled: true,
          mode: "cached",
          allowedDomains: ["example.com"],
          contextSize: "high",
          userLocation: {
            country: "US",
            city: "New York",
            timezone: "America/New_York",
          },
        },
      },
    },
  },
}

اگر جست‌وجوی بومی Codex فعال باشد اما مدل فعلی سازگار با Codex نباشد، OpenClaw رفتار عادی web_search مدیریت‌شده را حفظ می‌کند.

# ایمنی شبکه

فراخوانی‌های ارائه‌دهنده web_search مدیریت‌شده از مسیر واکشی محافظت‌شده OpenClaw استفاده می‌کنند. برای میزبان‌های API مورداعتماد ارائه‌دهنده، OpenClaw پاسخ‌های DNS جعلی-IP مربوط به Surge، Clash و sing-box را در 198.18.0.0/15 و fc00::/7 فقط برای نام میزبان همان ارائه‌دهنده مجاز می‌کند. مقصدهای خصوصی، loopback، link-local و metadata دیگر همچنان مسدود می‌مانند.

این مجوزدهی خودکار برای URLهای دلخواه web_fetch اعمال نمی‌شود. برای web_fetch، tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange و tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange را فقط زمانی صریحا فعال کنید که پروکسی مورداعتماد شما مالک آن بازه‌های مصنوعی باشد.

# راه‌اندازی جست‌وجوی وب

فهرست‌های ارائه‌دهندگان در مستندات و جریان‌های راه‌اندازی به‌ترتیب الفبایی هستند. تشخیص خودکار یک ترتیب اولویت جداگانه را حفظ می‌کند.

اگر هیچ provider تنظیم نشده باشد، OpenClaw ارائه‌دهندگان را به این ترتیب بررسی می‌کند و از اولین مورد آماده استفاده می‌کند:

ابتدا ارائه‌دهندگان مبتنی بر API:

1. Brave -- BRAVE_API_KEY یا plugins.entries.brave.config.webSearch.apiKey (ترتیب 10)
2. MiniMax Search -- MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY / MINIMAX_OAUTH_TOKEN / MINIMAX_API_KEY یا plugins.entries.minimax.config.webSearch.apiKey (ترتیب 15)
3. Gemini -- plugins.entries.google.config.webSearch.apiKey، GEMINI_API_KEY، یا models.providers.google.apiKey (ترتیب 20)
4. Grok -- XAI_API_KEY یا plugins.entries.xai.config.webSearch.apiKey (ترتیب 30)
5. Kimi -- KIMI_API_KEY / MOONSHOT_API_KEY یا plugins.entries.moonshot.config.webSearch.apiKey (ترتیب 40)
6. Perplexity -- PERPLEXITY_API_KEY / OPENROUTER_API_KEY یا plugins.entries.perplexity.config.webSearch.apiKey (ترتیب 50)
7. Firecrawl -- FIRECRAWL_API_KEY یا plugins.entries.firecrawl.config.webSearch.apiKey (ترتیب 60)
8. Exa -- EXA_API_KEY یا plugins.entries.exa.config.webSearch.apiKey؛ plugins.entries.exa.config.webSearch.baseUrl اختیاری نقطه پایانی Exa را بازنویسی می‌کند (ترتیب 65)
9. Tavily -- TAVILY_API_KEY یا plugins.entries.tavily.config.webSearch.apiKey (ترتیب 70)

پس از آن جایگزین‌های بدون کلید:

10. DuckDuckGo -- جایگزین HTML بدون کلید، بدون نیاز به حساب یا کلید API (ترتیب 100)
11. Ollama Web Search -- جایگزین بدون کلید از طریق میزبان محلی Ollama پیکربندی‌شده شما، زمانی که قابل دسترسی باشد و با ollama signin وارد آن شده باشید؛ وقتی میزبان به آن نیاز دارد می‌تواند از احراز هویت bearer ارائه‌دهنده Ollama دوباره استفاده کند، و وقتی با OLLAMA_API_KEY پیکربندی شده باشد می‌تواند جست‌وجوی مستقیم https://ollama.com را فراخوانی کند (ترتیب 110)
12. SearXNG -- SEARXNG_BASE_URL یا plugins.entries.searxng.config.webSearch.baseUrl (ترتیب 200)

اگر هیچ ارائه‌دهنده‌ای تشخیص داده نشود، به Brave برمی‌گردد (خطای نبود کلید دریافت می‌کنید که از شما می‌خواهد یکی را پیکربندی کنید).

# پیکربندی

{
  tools: {
    web: {
      search: {
        enabled: true, // default: true
        provider: "brave", // or omit for auto-detection
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
    },
  },
}

پیکربندی مختص هر ارائه‌دهنده (کلیدهای API، URLهای پایه، حالت‌ها) در plugins.entries.<plugin>.config.webSearch.* قرار می‌گیرد. Gemini همچنین می‌تواند از models.providers.google.apiKey و models.providers.google.baseUrl به‌عنوان گزینه‌های بازگشت با اولویت پایین‌تر، پس از پیکربندی اختصاصی جست‌وجوی وب خود و GEMINI_API_KEY، استفاده کند. برای نمونه‌ها، صفحه‌های ارائه‌دهنده را ببینید.

tools.web.search.provider با شناسه‌های ارائه‌دهنده جست‌وجوی وب که توسط مانیفست‌های Pluginهای همراه و نصب‌شده اعلام شده‌اند، به‌علاوه Pluginهای ارائه‌دهنده نصب‌پذیر شناخته‌شده، اعتبارسنجی می‌شود. یک غلط تایپی مانند "brvae" به‌جای بازگشت بی‌صدا به تشخیص خودکار، باعث شکست اعتبارسنجی پیکربندی می‌شود. اگر ارائه‌دهنده پیکربندی‌شده شناخته‌شده باشد اما Plugin مالک آن در دسترس نباشد، OpenClaw راه‌اندازی را تاب‌آور نگه می‌دارد و یک هشدار گزارش می‌کند تا بتوانید openclaw doctor --fix را برای نصب یا فعال‌سازی Plugin اجرا کنید. همین رفتار هشدار برای شواهد کهنه Plugin نیز اعمال می‌شود، مانند یک بلوک باقی‌مانده plugins.entries.<plugin> پس از حذف نصب یک Plugin شخص ثالث.

انتخاب ارائه‌دهنده بازگشتی web_fetch جداست:

• آن را با tools.web.fetch.provider انتخاب کنید
• یا آن فیلد را حذف کنید و اجازه دهید OpenClaw نخستین ارائه‌دهنده آماده web-fetch را از میان اعتبارنامه‌های موجود به‌صورت خودکار تشخیص دهد
• web_fetch بدون سندباکس می‌تواند از ارائه‌دهنده‌های Plugin نصب‌شده‌ای استفاده کند که contracts.webFetchProviders را اعلام می‌کنند؛ دریافت‌های سندباکس‌شده فقط همراه‌داخلی می‌مانند
• در حال حاضر ارائه‌دهنده همراه web-fetch، Firecrawl است که زیر plugins.entries.firecrawl.config.webFetch.* پیکربندی می‌شود

وقتی در طول openclaw onboard یا openclaw configure --section web Kimi را انتخاب می‌کنید، OpenClaw همچنین می‌تواند این موارد را بپرسد:

• منطقه API مربوط به Moonshot (https://api.moonshot.ai/v1 یا https://api.moonshot.cn/v1)
• مدل پیش‌فرض جست‌وجوی وب Kimi (پیش‌فرض kimi-k2.6)

برای x_search، plugins.entries.xai.config.xSearch.* را پیکربندی کنید. از همان بازگشت XAI_API_KEY مانند جست‌وجوی وب Grok استفاده می‌کند. پیکربندی قدیمی tools.web.x_search.* به‌صورت خودکار توسط openclaw doctor --fix مهاجرت داده می‌شود. وقتی در طول openclaw onboard یا openclaw configure --section web، Grok را انتخاب می‌کنید، OpenClaw همچنین می‌تواند راه‌اندازی اختیاری x_search را با همان کلید پیشنهاد کند. این یک مرحله پیگیری جداگانه داخل مسیر Grok است، نه یک انتخاب جداگانه در سطح بالای ارائه‌دهنده جست‌وجوی وب. اگر ارائه‌دهنده دیگری را انتخاب کنید، OpenClaw اعلان x_search را نشان نمی‌دهد.

# ذخیره‌سازی کلیدهای API

{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "YOUR_KEY", // pragma: allowlist secret
          },
        },
      },
    },
  },
}

export BRAVE_API_KEY="YOUR_KEY"

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

# x_search

x_search پست‌های X (قبلاً Twitter) را با استفاده از xAI پرس‌وجو می‌کند و پاسخ‌های ساخته‌شده توسط AI را همراه با ارجاع‌ها برمی‌گرداند. پرس‌وجوهای زبان طبیعی و فیلترهای ساختاریافته اختیاری را می‌پذیرد. OpenClaw ابزار داخلی x_search مربوط به xAI را فقط روی درخواستی فعال می‌کند که این فراخوانی ابزار را سرویس می‌دهد.

# پیکربندی x_search

{
  plugins: {
    entries: {
      xai: {
        config: {
          xSearch: {
            enabled: true,
            model: "grok-4-1-fast-non-reasoning",
            baseUrl: "https://api.x.ai/v1", // optional, overrides webSearch.baseUrl
            inlineCitations: false,
            maxTurns: 2,
            timeoutSeconds: 30,
            cacheTtlMinutes: 15,
          },
          webSearch: {
            apiKey: "xai-...", // optional if XAI_API_KEY is set
            baseUrl: "https://api.x.ai/v1", // optional shared xAI Responses base URL
          },
        },
      },
    },
  },
}

x_search وقتی plugins.entries.xai.config.xSearch.baseUrl تنظیم شده باشد، به <baseUrl>/responses پست می‌کند. اگر آن فیلد حذف شده باشد، به plugins.entries.xai.config.webSearch.baseUrl، سپس tools.web.search.grok.baseUrl قدیمی، و در نهایت endpoint عمومی xAI بازمی‌گردد.

# پارامترهای x_search

# نمونه x_search

await x_search({
  query: "dinner recipes",
  allowed_x_handles: ["nytfood"],
  from_date: "2026-03-01",
});

// Per-post stats: use the exact status URL or status ID when possible
await x_search({
  query: "https://x.com/huntharo/status/1905678901234567890",
});

# نمونه‌ها

// Basic search
await web_search({ query: "OpenClaw plugin SDK" });

// German-specific search
await web_search({ query: "TV online schauen", country: "DE", language: "de" });

// Recent results (past week)
await web_search({ query: "AI developments", freshness: "week" });

// Date range
await web_search({
  query: "climate research",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

// Domain filtering (Perplexity only)
await web_search({
  query: "product reviews",
  domain_filter: ["-reddit.com", "-pinterest.com"],
});

# پروفایل‌های ابزار

اگر از پروفایل‌های ابزار یا فهرست‌های مجاز استفاده می‌کنید، web_search، x_search یا group:web را اضافه کنید:

{
  tools: {
    allow: ["web_search", "x_search"],
    // or: allow: ["group:web"]  (includes web_search, x_search, and web_fetch)
  },
}

# مرتبط

• Web Fetch -- دریافت یک URL و استخراج محتوای خوانا
• Web Browser -- خودکارسازی کامل مرورگر برای سایت‌های سنگین از نظر JS
• Grok Search -- Grok به‌عنوان ارائه‌دهنده web_search
• Ollama Web Search -- جست‌وجوی وب بدون کلید از طریق میزبان Ollama شما