Веб-поиск

web_search выполняет поиск в интернете с помощью настроенного провайдера и возвращает нормализованные результаты, кэшируемые по запросу на 15 минут (период можно настроить). OpenClaw также включает x_search для публикаций в X (ранее Twitter) и web_fetch для упрощённого получения данных по URL. web_fetch всегда выполняется локально; web_search направляет запросы через xAI Responses, когда провайдером является Grok, а 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 (порядок 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 переопределяет конечную точку 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 переопределяет конечную точку (порядок 75)

Затем провайдеры с настроенной конечной точкой:

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 не направляет управляемые запросы web_search провайдеру без ключа только потому, что не настроен ни один провайдер с API.

Модели OpenAI Responses являются исключением: пока tools.web.search.provider не задан, они используют встроенный веб-поиск OpenAI вместо перечисленных выше управляемых провайдеров (см. ниже). Задайте для tools.web.search.provider значение parallel-free (или другого провайдера), чтобы вместо этого направлять их через управляемый путь.

Встроенный веб-поиск OpenAI

Прямые модели OpenAI Responses (api: "openai-responses", провайдер openai, без базового URL или с официальным базовым URL API OpenAI) автоматически используют размещённый OpenAI инструмент web_search, когда веб-поиск OpenClaw включён и не закреплён управляемый провайдер. Это поведение принадлежит провайдеру во встроенном плагине OpenAI и не применяется к базовым URL прокси-серверов, совместимых с OpenAI, или маршрутам Azure. Задайте для tools.web.search.provider другого провайдера, например brave, чтобы сохранить управляемый инструмент web_search для моделей OpenAI, либо задайте tools.web.search.enabled: false, чтобы отключить как управляемый поиск, так и встроенный поиск OpenAI.

Нативный веб-поиск Codex

Среда выполнения app-server Codex автоматически использует размещённый инструмент Codex web_search, когда веб-поиск включён и управляемый провайдер не выбран. Нативный размещённый поиск и динамический управляемый инструмент OpenClaw web_search являются взаимоисключающими, поэтому управляемый поиск не может обойти нативные ограничения доменов. OpenClaw использует управляемый инструмент, когда размещённый поиск недоступен, явно отключён или заменён выбранным управляемым провайдером. OpenClaw оставляет отдельное расширение Codex web.run отключённым (features.standalone_web_search: false), поскольку рабочий трафик 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", чтобы явно запросить активный доступ
• Укажите в tools.web.search.provider управляемого провайдера, например brave, чтобы вместо этого использовать управляемый инструмент OpenClaw web_search
• Укажите tools.web.search.openaiCodex.enabled: false, чтобы отказаться от размещённого Codex поиска; другие управляемые провайдеры останутся доступны
• Ограничение нативной поверхности инструментов Codex также сохраняет доступность управляемого web_search
• Когда задано allowedDomains, автоматический управляемый резервный механизм закрывается при отказе, если размещённый поиск недоступен, поэтому нативный список разрешённых ресурсов нельзя обойти
• Запуски только с LLM и отключёнными инструментами отключают как нативный, так и управляемый поиск
• tools.web.search.enabled: false отключает как управляемый, так и нативный поиск

Постоянные изменения фактической политики поиска Codex запускают новый связанный поток, чтобы уже загруженный поток app-server не мог сохранить устаревший доступ к размещённому поиску. Временные ограничения для отдельного цикла используют временный ограниченный поток и сохраняют существующую привязку для последующего возобновления.

Прямой трафик OpenAI ChatGPT Responses также может использовать размещённый инструмент OpenAI web_search. Этот отдельный путь остаётся доступным только при явном включении через tools.web.search.openaiCodex.enabled: true и применяется только к подходящим моделям openai/*, использующим api: "openai-chatgpt-responses".

{  tools: {    web: {      search: {        enabled: true,        // Необязательно: также использовать Codex Hosted Search из родительских моделей, отличных от 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. Выберите явного управляемого провайдера, если вам нужны специфичные для провайдера сетевые ограничения OpenClaw вместо размещённого поиска Codex.

Выбор provider: "codex" включает встроенный плагин 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. Другие частные адреса, адреса обратной связи, локальные адреса канала и адреса служб метаданных остаются заблокированными. Codex Hosted Search является исключением: его ограниченный исполнитель делегирует сетевой доступ размещённому инструменту app-server Codex web_search.

Это автоматическое разрешение не применяется к произвольным 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 также может повторно использовать models.providers.google.apiKey и models.providers.google.baseUrl как резервные варианты с более низким приоритетом после своей специальной конфигурации веб-поиска и GEMINI_API_KEY. Примеры приведены на страницах провайдеров. Grok также может повторно использовать профиль аутентификации xAI OAuth из openclaw models auth login --provider xai --method oauth; конфигурация ключа API остаётся резервным вариантом.

Значение tools.web.search.provider проверяется по идентификаторам провайдеров веб-поиска, объявленным в манифестах встроенных и установленных плагинов. Опечатка вроде "brvae" приводит к ошибке проверки конфигурации вместо незаметного перехода к автоматическому определению. Если для настроенного провайдера остались только устаревшие данные плагина, например оставшийся блок plugins.entries.<plugin> после удаления стороннего плагина, OpenClaw сохраняет устойчивость запуска и выводит предупреждение, чтобы вы могли переустановить плагин или запустить openclaw doctor --fix для очистки устаревшей конфигурации.

Выбор резервного провайдера web_fetch выполняется отдельно:

• выберите его с помощью tools.web.fetch.provider
• либо не указывайте это поле, и OpenClaw автоматически определит первого готового провайдера веб-загрузки по настроенным учётным данным
• запрос web_fetch вне песочницы может использовать провайдеры установленных плагинов, которые объявляют contracts.webFetchProviders; запросы из песочницы разрешают встроенных провайдеров и проверенные установки официальных плагинов, но исключают сторонние внешние плагины
• официальный плагин Firecrawl на сегодня является единственным встроенным участником webFetchProviders, который настраивается в разделе plugins.entries.firecrawl.config.webFetch.*

Когда вы выбираете Kimi в процессе openclaw onboard или openclaw configure --section web, 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 / веб-поиска плагина, используемые веб-поиском Grok. Устаревшая конфигурация tools.web.x_search.* автоматически переносится командой openclaw doctor --fix. Когда вы выбираете Grok в процессе openclaw onboard или openclaw configure --section web, OpenClaw также предлагает необязательную настройку x_search с теми же учётными данными сразу после завершения настройки Grok. Это отдельный последующий шаг в рамках пути 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 и возвращает ответы, синтезированные ИИ, с цитатами. Он принимает запросы на естественном языке и необязательные структурированные фильтры. OpenClaw создаёт встроенный инструмент xAI x_search для каждого запроса, а не сохраняет его постоянно зарегистрированным, поэтому он активен только в том цикле, который действительно его вызывает.

Конфигурация 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", // необязательный общий базовый URL xAI Responses          },        },      },    },  },}

x_search отправляет запросы в <baseUrl>/responses, когда задано plugins.entries.xai.config.xSearch.baseUrl. Если это поле не указано, используется 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: "рецепты ужина",  allowed_x_handles: ["nytfood"],  from_date: "2026-03-01",});

// Статистика отдельной публикации: по возможности используйте точный URL статуса или идентификатор статусаawait x_search({  query: "https://x.com/huntharo/status/1905678901234567890",});

Примеры

// Базовый поискawait web_search({ query: "SDK плагинов OpenClaw" }); // Поиск для Германииawait web_search({ query: "смотреть телевидение онлайн", country: "DE", language: "de" }); // Недавние результаты (за последнюю неделю)await web_search({ query: "разработки в области ИИ", freshness: "week" }); // Диапазон датawait web_search({  query: "исследования климата",  date_after: "2024-01-01",  date_before: "2024-06-30",}); // Фильтрация по доменам (только Perplexity)await web_search({  query: "обзоры продуктов",  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)  },}

Связанные материалы

• Получение веб-страниц -- получение URL и извлечение удобного для чтения содержимого
• Веб-браузер -- полная автоматизация браузера для сайтов, активно использующих JS
• Поиск Grok -- Grok в качестве провайдера web_search
• Веб-поиск Ollama -- веб-поиск без ключа через ваш хост Ollama