جست‌وجوی وب

web_search با ارائه‌دهنده پیکربندی‌شده شما وب را جست‌وجو می‌کند و نتایج عادی‌سازی‌شده را برمی‌گرداند که بر اساس پرس‌وجو به‌مدت ۱۵ دقیقه (قابل پیکربندی) در حافظه نهان نگه‌داری می‌شوند. OpenClaw همچنین x_search را برای پست‌های X (توییتر سابق) و web_fetch را برای واکشی سبک URL ارائه می‌کند. web_fetch همیشه به‌صورت محلی اجرا می‌شود؛ وقتی Grok ارائه‌دهنده باشد، web_search از طریق xAI Responses مسیریابی می‌شود و x_search همیشه از xAI Responses استفاده می‌کند.

شروع سریع

openclaw configure --section web

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

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

انتخاب ارائه‌دهنده

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

تشخیص خودکار

فهرست ارائه‌دهندگان در مستندات و جریان‌های راه‌اندازی به‌ترتیب الفبایی است. تشخیص خودکار از ترتیب تقدم ثابت و جداگانه‌ای استفاده می‌کند و فقط زمانی ارائه‌دهنده‌ای را که به اعتبارنامه نیاز دارد (requiresCredential !== false) انتخاب می‌کند که پیکربندی آن را بیابد. اگر provider تنظیم نشده باشد، OpenClaw ارائه‌دهندگان را به‌ترتیب زیر بررسی می‌کند و از نخستین مورد آماده استفاده می‌کند:

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

1. Brave -- BRAVE_API_KEY یا plugins.entries.brave.config.webSearch.apiKey (ترتیب ۱۰)
2. جست‌وجوی MiniMax -- 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 -- OAuth ‏xAI،‏ 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. Parallel -- API پولی Parallel Search از طریق PARALLEL_API_KEY یا plugins.entries.parallel.config.webSearch.apiKey؛ مقدار اختیاری plugins.entries.parallel.config.webSearch.baseUrl نقطه پایانی را بازنویسی می‌کند (ترتیب ۷۵)

پس از آن، ارائه‌دهندگان دارای نقطه پایانی پیکربندی‌شده:

11. SearXNG -- SEARXNG_BASE_URL یا plugins.entries.searxng.config.webSearch.baseUrl (ترتیب ۲۰۰)

ارائه‌دهندگان بدون کلید مانند جست‌وجوی Parallel (رایگان)، DuckDuckGo، جست‌وجوی وب Ollama و جست‌وجوی میزبانی‌شده Codex هرگز در تشخیص خودکار انتخاب نمی‌شوند، حتی اگر مقدار ترتیب داخلی داشته باشند. تنها زمانی از آن‌ها استفاده می‌شود که آن‌ها را صریحاً با tools.web.search.provider یا از طریق openclaw configure --section web انتخاب کنید. OpenClaw صرفاً به‌دلیل پیکربندی‌نشدن هیچ ارائه‌دهنده مبتنی بر API، پرس‌وجوهای مدیریت‌شده web_search را به یک ارائه‌دهنده بدون کلید ارسال نمی‌کند.

مدل‌های OpenAI Responses یک استثنا هستند: تا زمانی که tools.web.search.provider تنظیم نشده باشد، آن‌ها به‌جای ارائه‌دهندگان مدیریت‌شده بالا از جست‌وجوی وب بومی OpenAI استفاده می‌کنند (در ادامه ببینید). برای مسیریابی آن‌ها از طریق مسیر مدیریت‌شده، tools.web.search.provider را روی parallel-free (یا ارائه‌دهنده‌ای دیگر) تنظیم کنید.

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

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

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

زمان اجرای app-server در Codex، هنگامی که جست‌وجوی وب فعال باشد و هیچ ارائه‌دهندهٔ مدیریت‌شده‌ای انتخاب نشده باشد، به‌طور خودکار از ابزار میزبانی‌شدهٔ web_search متعلق به Codex استفاده می‌کند. جست‌وجوی میزبانی‌شدهٔ بومی و ابزار پویای مدیریت‌شدهٔ web_search در OpenClaw مانعةالجمع هستند؛ بنابراین جست‌وجوی مدیریت‌شده نمی‌تواند محدودیت‌های دامنهٔ بومی را دور بزند. هنگامی که جست‌وجوی میزبانی‌شده در دسترس نباشد، صراحتاً غیرفعال شده باشد، یا با یک ارائه‌دهندهٔ مدیریت‌شدهٔ انتخابی جایگزین شود، OpenClaw از ابزار مدیریت‌شده استفاده می‌کند. OpenClaw افزونهٔ مستقل web.run در Codex را غیرفعال نگه می‌دارد (features.standalone_web_search: false)، زیرا ترافیک app-server در محیط عملیاتی فضای نام web تعریف‌شده توسط کاربر را رد می‌کند.

• جست‌وجوی بومی را در tools.web.search.openaiCodex پیکربندی کنید
• برای فراهم‌کردن جست‌وجوی میزبانی‌شدهٔ Codex به‌عنوان ارائه‌دهندهٔ مدیریت‌شدهٔ web_search برای هر مدل والد، tools.web.search.provider: "codex" را تنظیم کنید. هر فراخوانی یک نوبت موقتی و محدودشدهٔ app-server در Codex را اجرا می‌کند و اگر Codex مورد میزبانی‌شدهٔ webSearch تولید نکند، با شکست مواجه می‌شود.
• mode: "cached" ترجیح پیش‌فرض است، اما Codex آن را برای نوبت‌های نامحدود app-server به دسترسی زندهٔ خارجی تبدیل می‌کند؛ برای درخواست صریح دسترسی زنده، "live" را تنظیم کنید
• برای استفاده از web_search مدیریت‌شدهٔ OpenClaw، tools.web.search.provider را روی یک ارائه‌دهندهٔ مدیریت‌شده مانند brave تنظیم کنید
• برای انصراف از جست‌وجوی میزبانی‌شده توسط Codex، tools.web.search.openaiCodex.enabled: false را تنظیم کنید؛ سایر ارائه‌دهندگان مدیریت‌شده همچنان در دسترس می‌مانند
• محدودکردن سطح ابزار بومی Codex نیز web_search مدیریت‌شده را در دسترس نگه می‌دارد
• هنگامی که allowedDomains تنظیم شده باشد، اگر جست‌وجوی میزبانی‌شده در دسترس نباشد، بازگشت خودکار به ابزار مدیریت‌شده به‌صورت بسته شکست می‌خورد تا فهرست مجاز بومی قابل دورزدن نباشد
• اجراهای صرفاً LLM که ابزارها در آن‌ها غیرفعال‌اند، جست‌وجوی بومی و مدیریت‌شده را هر دو غیرفعال می‌کنند
• tools.web.search.enabled: false جست‌وجوی مدیریت‌شده و بومی را هر دو غیرفعال می‌کند

تغییرات پایدار در سیاست مؤثر جست‌وجوی Codex یک رشتهٔ مقید تازه آغاز می‌کنند تا یک رشتهٔ app-server که از قبل بارگذاری شده است نتواند دسترسی قدیمی به جست‌وجوی میزبانی‌شده را حفظ کند. محدودیت‌های موقتی هر نوبت از یک رشتهٔ محدودشدهٔ موقت استفاده می‌کنند و قید موجود را برای ازسرگیری بعدی حفظ می‌کنند.

ترافیک مستقیم OpenAI ChatGPT Responses نیز می‌تواند از ابزار میزبانی‌شدهٔ web_search متعلق به OpenAI استفاده کند. آن مسیر جداگانه از طریق tools.web.search.openaiCodex.enabled: true اختیاری باقی می‌ماند و فقط برای مدل‌های واجد شرایط openai/* که از api: "openai-chatgpt-responses" استفاده می‌کنند اعمال می‌شود.

{  tools: {    web: {      search: {        enabled: true,        // اختیاری: استفاده از جست‌وجوی میزبانی‌شدهٔ Codex از مدل‌های والد غیر Codex نیز.        provider: "codex",        openaiCodex: {          enabled: true,          mode: "cached",          allowedDomains: ["example.com"],          contextSize: "high",          userLocation: {            country: "US",            city: "New York",            timezone: "America/New_York",          },        },      },    },  },}

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

انتخاب provider: "codex"، Plugin همراه codex را فعال می‌کند و از همان محدودیت‌های tools.web.search.openaiCodex که در بالا نشان داده شده‌اند استفاده می‌کند. ابتدا app-server در Codex را با openclaw models auth login --provider openai احراز هویت کنید. عامل والد می‌تواند از هر مدل یا زمان اجرایی استفاده کند؛ فقط کارگر محدودشدهٔ جست‌وجو از طریق Codex اجرا می‌شود.

ایمنی شبکه

فراخوانی‌های ارائه‌دهندهٔ مدیریت‌شدهٔ HTTP برای web_search از مسیر واکشی محافظت‌شدهٔ OpenClaw استفاده می‌کنند که دامنهٔ آن به نام میزبان خود ارائه‌دهندهٔ فعلی محدود است. OpenClaw فقط برای آن نام میزبان، پاسخ‌های DNS مبتنی بر IP مصنوعی متعلق به Surge، Clash و sing-box را در 198.18.0.0/15 و fc00::/7 مجاز می‌داند. سایر مقصدهای خصوصی، loopback، پیوند-محلی و فراداده همچنان مسدود می‌مانند. جست‌وجوی میزبانی‌شدهٔ Codex استثنا است: کارگر محدودشدهٔ آن دسترسی شبکه را به ابزار میزبانی‌شدهٔ web_search در app-server متعلق به Codex واگذار می‌کند.

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

پیکربندی

{  tools: {    web: {      search: {        enabled: true, // پیش‌فرض: true        provider: "brave", // یا برای تشخیص خودکار حذف شود        maxResults: 5,        timeoutSeconds: 30,        cacheTtlMinutes: 15,      },    },  },}

پیکربندی مختص ارائه‌دهنده (کلیدهای API، URLهای پایه، حالت‌ها) در plugins.entries.<plugin>.config.webSearch.* قرار می‌گیرد. Gemini همچنین می‌تواند پس از پیکربندی اختصاصی جست‌وجوی وب و GEMINI_API_KEY خود، از models.providers.google.apiKey و models.providers.google.baseUrl به‌عنوان گزینه‌های بازگشت با اولویت پایین‌تر استفاده کند. برای نمونه‌ها به صفحات ارائه‌دهندگان مراجعه کنید. Grok همچنین می‌تواند از نمایهٔ احراز هویت OAuth متعلق به xAI که با openclaw models auth login --provider xai --method oauth ایجاد شده است استفاده کند؛ پیکربندی کلید API همچنان گزینهٔ بازگشت است.

مقدار 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 خارج از سندباکس می‌تواند از ارائه‌دهندگان Pluginهای نصب‌شده که contracts.webFetchProviders را اعلام می‌کنند استفاده کند؛ واکشی‌های داخل سندباکس ارائه‌دهندگان همراه و نصب‌های تأییدشدهٔ Pluginهای رسمی را مجاز می‌دانند، اما Pluginهای خارجی شخص ثالث را مستثنا می‌کنند
• Plugin رسمی Firecrawl تنها مشارکت‌کنندهٔ همراه webFetchProviders در حال حاضر است و در plugins.entries.firecrawl.config.webFetch.* پیکربندی می‌شود

هنگامی که در جریان openclaw onboard یا openclaw configure --section web گزینهٔ Kimi را انتخاب می‌کنید، OpenClaw همچنین می‌تواند این موارد را درخواست کند:

• منطقهٔ Moonshot API (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 بلافاصله پس از تکمیل راه‌اندازی Grok، راه‌اندازی اختیاری 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 (توییتر سابق) را جست‌وجو می‌کند و پاسخ‌های ترکیب‌شده توسط هوش مصنوعی را همراه با ارجاع‌ها بازمی‌گرداند. این ابزار پرس‌وجوهای زبان طبیعی و فیلترهای ساخت‌یافتهٔ اختیاری را می‌پذیرد. OpenClaw ابزار داخلی x_search متعلق به xAI را به‌جای ثبت دائمی، برای هر درخواست ایجاد می‌کند؛ بنابراین فقط در نوبتی فعال است که واقعاً آن را فراخوانی می‌کند.

پیکربندی x_search

با حذف enabled، ابزار x_search فقط زمانی در دسترس قرار می‌گیرد که ارائه‌دهندهٔ مدل فعال xai باشد و اطلاعات احراز هویت xAI با موفقیت تعیین شوند. برای یک مدل فعال با ارائه‌دهندهٔ شناخته‌شدهٔ غیر xAI، مقدار plugins.entries.xai.config.xSearch.enabled را روی true تنظیم کنید تا استفادهٔ بین‌ارائه‌دهنده‌ای فعال شود. اگر ارائه‌دهندهٔ مدل فعال مشخص نباشد یا تعیین نشود، ابزار پنهان می‌ماند. برای غیرفعال‌کردن آن برای همهٔ ارائه‌دهندگان، enabled را روی false تنظیم کنید. اطلاعات احراز هویت xAI همیشه الزامی است.

{  plugins: {    entries: {      xai: {        config: {          xSearch: {            enabled: true, // برای ارائه‌دهندهٔ مدل شناخته‌شدهٔ غیر xAI الزامی است            model: "grok-4.3",            baseUrl: "https://api.x.ai/v1", // اختیاری؛ webSearch.baseUrl را بازنویسی می‌کند            inlineCitations: false,            maxTurns: 2,            timeoutSeconds: 30,            cacheTtlMinutes: 15,          },          webSearch: {            apiKey: "xai-...", // اگر نمایهٔ احراز هویت xAI یا XAI_API_KEY تنظیم شده باشد، اختیاری است            baseUrl: "https://api.x.ai/v1", // نشانی پایهٔ مشترک و اختیاری Responses در xAI          },        },      },    },  },}

وقتی plugins.entries.xai.config.xSearch.baseUrl تنظیم شده باشد، x_search درخواست را به <baseUrl>/responses ارسال می‌کند. اگر این فیلد حذف شده باشد، ابتدا از plugins.entries.xai.config.webSearch.baseUrl، سپس از مقدار قدیمی tools.web.search.grok.baseUrl و در نهایت از نقطهٔ پایانی عمومی xAI (https://api.x.ai/v1) استفاده می‌کند.

پارامترهای x_search

allowed_x_handles و excluded_x_handles را نمی‌توان هم‌زمان استفاده کرد.

نمونهٔ x_search

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

// آمار هر پست: در صورت امکان از نشانی دقیق وضعیت یا شناسهٔ وضعیت استفاده کنیدawait x_search({  query: "https://x.com/huntharo/status/1905678901234567890",});

نمونه‌ها

// جست‌وجوی پایهawait web_search({ query: "OpenClaw plugin SDK" }); // جست‌وجوی ویژهٔ زبان آلمانیawait web_search({ query: "TV online schauen", country: "DE", language: "de" }); // نتایج اخیر (هفتهٔ گذشته)await web_search({ query: "AI developments", freshness: "week" }); // بازهٔ زمانیawait web_search({  query: "climate research",  date_after: "2024-01-01",  date_before: "2024-06-30",}); // پالایش بر اساس دامنه (فقط Perplexity)await web_search({  query: "product reviews",  domain_filter: ["-reddit.com", "-pinterest.com"],});

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

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

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

مطالب مرتبط

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