جستجوی وب

ابزار 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

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

• جست‌وجوی بومی را زیر tools.web.search.openaiCodex پیکربندی کنید
• tools.web.search.provider: "codex" را تنظیم کنید تا Codex Hosted Search به‌عنوان ارائه‌دهنده مدیریت‌شده web_search برای هر مدل والد فراهم‌سازی شود. هر فراخوانی یک نوبت 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,        // Optional: use Codex Hosted Search from non-Codex parent models too.        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 استفاده کند. وقتی به کنترل‌های شبکه خاص ارائه‌دهنده در OpenClaw به‌جای جست‌وجوی میزبانی‌شده Codex نیاز دارید، از یک ارائه‌دهنده مدیریت‌شده صریح استفاده کنید.

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

ایمنی شبکه

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

این مجوز خودکار برای 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 -- OAuth متعلق به xAI، 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، endpoint مربوط به Exa را بازنویسی می‌کند (ترتیب 65)
9. Tavily -- TAVILY_API_KEY یا plugins.entries.tavily.config.webSearch.apiKey (ترتیب 70)
10. Parallel -- API پولی Parallel Search از طریق PARALLEL_API_KEY یا plugins.entries.parallel.config.webSearch.apiKey؛ مقدار اختیاری plugins.entries.parallel.config.webSearch.baseUrl، endpoint را بازنویسی می‌کند (ترتیب 75)

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

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

ارائه‌دهنده‌های بدون کلید مانند Parallel Search (Free)، DuckDuckGo، Ollama Web Search و Codex Hosted Search فقط زمانی در دسترس هستند که آن‌ها را صراحتا با 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 (یا ارائه‌دهنده‌ای دیگر) تنظیم کنید.

پیکربندی

{  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 خود، به‌عنوان fallback با اولویت پایین‌تر دوباره استفاده کند. برای نمونه‌ها، صفحه‌های ارائه‌دهنده‌ها را ببینید. Grok همچنین می‌تواند از پروفایل احراز هویت OAuth مربوط به xAI از openclaw models auth login --provider xai --method oauth دوباره استفاده کند؛ پیکربندی کلید API همچنان fallback باقی می‌ماند.

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

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

• آن را با tools.web.fetch.provider انتخاب کنید
• یا آن فیلد را حذف کنید و بگذارید OpenClaw اولین ارائه‌دهنده web-fetch آماده را از credentialهای پیکربندی‌شده به‌صورت خودکار تشخیص دهد
• web_fetch غیر sandboxشده می‌تواند از ارائه‌دهنده‌های Plugin نصب‌شده‌ای استفاده کند که contracts.webFetchProviders را اعلام می‌کنند؛ fetchهای sandboxشده ارائه‌دهنده‌های همراه و نصب‌های تاییدشده Plugin رسمی را مجاز می‌کنند، اما Pluginهای خارجی شخص ثالث را کنار می‌گذارند
• Plugin رسمی Firecrawl، fallback مربوط به web-fetch را ارائه می‌کند که زیر 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 مانند chat، یا credential مربوط به XAI_API_KEY / جست‌وجوی وب Plugin که توسط جست‌وجوی وب Grok استفاده می‌شود، بهره می‌برد. پیکربندی قدیمی tools.web.x_search.* توسط openclaw doctor --fix به‌صورت خودکار migrate می‌شود. وقتی در طول openclaw onboard یا openclaw configure --section web، Grok را انتخاب می‌کنید، OpenClaw همچنین می‌تواند راه‌اندازی اختیاری x_search را با همان credential پیشنهاد کند. این یک مرحله پیگیری جداگانه داخل مسیر Grok است، نه یک انتخاب جداگانه در سطح بالای ارائه‌دهنده جست‌وجوی وب. اگر ارائه‌دهنده دیگری را انتخاب کنید، OpenClaw prompt مربوط به 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 همراه با citation بازمی‌گرداند. این ابزار پرس‌وجوهای زبان طبیعی و فیلترهای ساختاریافته اختیاری را می‌پذیرد. 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 قدیمی و در نهایت endpoint عمومی xAI fallback می‌کند.

پارامترهای 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)  },}

مرتبط

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