جست‌وجوی وب

ابزار 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، از ابزار بومی ارائه‌دهندهٔ Responses به نام web_search استفاده کنند.

• آن را زیر 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 از مسیر fetch محافظت‌شدهٔ OpenClaw استفاده می‌کنند. برای میزبان‌های API ارائه‌دهندهٔ مورد اعتماد، OpenClaw پاسخ‌های DNS از نوع fake-IP مربوط به Surge، Clash و sing-box در 198.18.0.0/15 و fc00::/7 را فقط برای همان نام میزبان ارائه‌دهنده مجاز می‌کند. سایر مقصدهای خصوصی، loopback، link-local و فراداده همچنان مسدود می‌مانند.

این مجوز خودکار برای 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 (ترتیب ۱۰)
2. MiniMax Search -- MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY / MINIMAX_OAUTH_TOKEN / MINIMAX_API_KEY یا plugins.entries.minimax.config.webSearch.apiKey (ترتیب ۱۵)
3. Gemini -- plugins.entries.google.config.webSearch.apiKey، GEMINI_API_KEY، یا models.providers.google.apiKey (ترتیب ۲۰)
4. Grok -- XAI_API_KEY یا plugins.entries.xai.config.webSearch.apiKey (ترتیب ۳۰)
5. Kimi -- KIMI_API_KEY / MOONSHOT_API_KEY یا plugins.entries.moonshot.config.webSearch.apiKey (ترتیب ۴۰)
6. Perplexity -- PERPLEXITY_API_KEY / OPENROUTER_API_KEY یا plugins.entries.perplexity.config.webSearch.apiKey (ترتیب ۵۰)
7. Firecrawl -- FIRECRAWL_API_KEY یا plugins.entries.firecrawl.config.webSearch.apiKey (ترتیب ۶۰)
8. Exa -- EXA_API_KEY یا plugins.entries.exa.config.webSearch.apiKey؛ مقدار اختیاری plugins.entries.exa.config.webSearch.baseUrl نقطهٔ پایانی Exa را بازنویسی می‌کند (ترتیب ۶۵)
9. Tavily -- TAVILY_API_KEY یا plugins.entries.tavily.config.webSearch.apiKey (ترتیب ۷۰)

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

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

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

پیکربندی

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

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

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

انتخاب ارائه‌دهنده جایگزین 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 مانند چت، یا از اعتبارنامه XAI_API_KEY / جست‌وجوی وب Plugin که توسط جست‌وجوی وب 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 با استفاده از xAI پست‌های X (که قبلا Twitter بود) را پرس‌وجو می‌کند و پاسخ‌های ترکیب‌شده توسط 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 an xAI auth profile or XAI_API_KEY is set            baseUrl: "https://api.x.ai/v1", // optional shared xAI Responses base URL          },        },      },    },  },}

وقتی plugins.entries.xai.config.xSearch.baseUrl تنظیم شده باشد، x_search به <baseUrl>/responses پست می‌کند. اگر آن فیلد حذف شده باشد، به plugins.entries.xai.config.webSearch.baseUrl، سپس به tools.web.search.grok.baseUrl قدیمی، و در نهایت به نقطه پایانی عمومی 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 possibleawait x_search({  query: "https://x.com/huntharo/status/1905678901234567890",});

نمونه‌ها

// Basic searchawait web_search({ query: "OpenClaw plugin SDK" }); // German-specific searchawait web_search({ query: "TV online schauen", country: "DE", language: "de" }); // Recent results (past week)await web_search({ query: "AI developments", freshness: "week" }); // Date rangeawait 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)  },}

مرتبط

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