Pesquisa na web

web_search pesquisa na web com o provedor configurado e retorna resultados normalizados, armazenados em cache por consulta durante 15 minutos (configurável). O OpenClaw também inclui x_search para publicações no X (antigo Twitter) e web_fetch para buscas leves de URLs. web_fetch sempre é executado localmente; web_search é encaminhado por meio do xAI Responses quando o Grok é o provedor, e x_search sempre usa o xAI Responses.

Início rápido

openclaw configure --section web

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

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

Como escolher um provedor

Comparação de provedores

Detecção automática

As listas de provedores na documentação e nos fluxos de configuração estão em ordem alfabética. A detecção automática usa uma ordem de precedência separada e fixa e só escolhe um provedor que exige uma credencial (requiresCredential !== false) quando encontra um configurado. Se nenhum provider estiver definido, o OpenClaw verifica os provedores nesta ordem e usa o primeiro que estiver pronto:

Primeiro, os provedores baseados em API:

1. Brave -- BRAVE_API_KEY ou plugins.entries.brave.config.webSearch.apiKey (ordem 10)
2. Pesquisa MiniMax -- MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY / MINIMAX_OAUTH_TOKEN / MINIMAX_API_KEY ou plugins.entries.minimax.config.webSearch.apiKey (ordem 15)
3. Gemini -- plugins.entries.google.config.webSearch.apiKey, GEMINI_API_KEY ou models.providers.google.apiKey (ordem 20)
4. Grok -- OAuth da xAI, XAI_API_KEY ou plugins.entries.xai.config.webSearch.apiKey (ordem 30)
5. Kimi -- KIMI_API_KEY / MOONSHOT_API_KEY ou plugins.entries.moonshot.config.webSearch.apiKey (ordem 40)
6. Perplexity -- PERPLEXITY_API_KEY / OPENROUTER_API_KEY ou plugins.entries.perplexity.config.webSearch.apiKey (ordem 50)
7. Firecrawl -- FIRECRAWL_API_KEY ou plugins.entries.firecrawl.config.webSearch.apiKey (ordem 60)
8. Exa -- EXA_API_KEY ou plugins.entries.exa.config.webSearch.apiKey; o plugins.entries.exa.config.webSearch.baseUrl opcional substitui o endpoint do Exa (ordem 65)
9. Tavily -- TAVILY_API_KEY ou plugins.entries.tavily.config.webSearch.apiKey (ordem 70)
10. Parallel -- API Parallel Search paga por meio de PARALLEL_API_KEY ou plugins.entries.parallel.config.webSearch.apiKey; o plugins.entries.parallel.config.webSearch.baseUrl opcional substitui o endpoint (ordem 75)

Depois, provedores com endpoint configurado:

11. SearXNG -- SEARXNG_BASE_URL ou plugins.entries.searxng.config.webSearch.baseUrl (ordem 200)

Provedores sem chave, como Pesquisa Parallel (Gratuita), DuckDuckGo, Pesquisa Web do Ollama e Pesquisa Hospedada do Codex, nunca vencem a detecção automática, embora tenham um valor de ordem interno. Eles são usados somente quando você os seleciona explicitamente com tools.web.search.provider ou por meio de openclaw configure --section web. O OpenClaw não envia consultas gerenciadas de web_search a um provedor sem chave apenas porque nenhum provedor baseado em API está configurado.

Os modelos OpenAI Responses são uma exceção: enquanto tools.web.search.provider não estiver definido, eles usam a pesquisa web nativa da OpenAI em vez dos provedores gerenciados acima (veja abaixo). Defina tools.web.search.provider como parallel-free (ou outro provedor) para encaminhá-los pelo caminho gerenciado.

Pesquisa web nativa da OpenAI

Os modelos diretos do OpenAI Responses (api: "openai-responses", provedor openai, sem URL base ou com uma URL base oficial da API da OpenAI) usam automaticamente a ferramenta hospedada web_search da OpenAI quando a pesquisa na web do OpenClaw está habilitada e nenhum provedor gerenciado está fixado. Esse comportamento pertence ao provedor no plugin integrado da OpenAI e não se aplica a URLs base de proxies compatíveis com a OpenAI nem a rotas do Azure. Defina tools.web.search.provider como outro provedor, como brave, para manter a ferramenta gerenciada web_search para modelos da OpenAI, ou defina tools.web.search.enabled: false para desabilitar tanto a pesquisa gerenciada quanto a pesquisa nativa da OpenAI.

Pesquisa nativa na web do Codex

O ambiente de execução do app-server do Codex usa automaticamente a ferramenta hospedada web_search do Codex quando a pesquisa na web está habilitada e nenhum provedor gerenciado está selecionado. A pesquisa hospedada nativa e a ferramenta dinâmica gerenciada web_search do OpenClaw são mutuamente exclusivas, portanto a pesquisa gerenciada não pode contornar as restrições nativas de domínio. O OpenClaw usa a ferramenta gerenciada quando a pesquisa hospedada está indisponível, explicitamente desabilitada ou substituída por um provedor gerenciado selecionado. O OpenClaw mantém desabilitada a extensão autônoma web.run do Codex (features.standalone_web_search: false), pois o tráfego de produção do app-server rejeita o namespace web definido pelo usuário.

• Configure a pesquisa nativa em tools.web.search.openaiCodex
• Defina tools.web.search.provider: "codex" para disponibilizar a Pesquisa Hospedada do Codex como o provedor gerenciado de web_search para qualquer modelo principal. Cada chamada executa um turno efêmero e limitado do app-server do Codex e falha se o Codex não emitir um item webSearch hospedado.
• mode: "cached" é a preferência padrão, mas o Codex a resolve como acesso externo em tempo real para turnos irrestritos do app-server; defina "live" para solicitar explicitamente o acesso em tempo real
• Defina tools.web.search.provider como um provedor gerenciado, como brave, para usar a web_search gerenciada do OpenClaw
• Defina tools.web.search.openaiCodex.enabled: false para desativar a pesquisa hospedada pelo Codex; outros provedores gerenciados permanecem disponíveis
• Restringir a superfície de ferramentas nativas do Codex também mantém a web_search gerenciada disponível
• Quando allowedDomains está definido, o fallback gerenciado automático falha de forma fechada se a pesquisa hospedada estiver indisponível, para que a lista nativa de permissões não possa ser contornada
• Execuções somente com LLM e ferramentas desabilitadas desabilitam tanto a pesquisa nativa quanto a gerenciada
• tools.web.search.enabled: false desabilita tanto a pesquisa gerenciada quanto a nativa

Alterações persistentes na política efetiva de pesquisa do Codex iniciam uma nova thread vinculada, para que uma thread do app-server já carregada não mantenha acesso obsoleto à pesquisa hospedada. Restrições transitórias por turno usam uma thread temporária restrita e preservam o vínculo existente para uma retomada posterior.

O tráfego direto do OpenAI ChatGPT Responses também pode usar a ferramenta hospedada web_search da OpenAI. Esse caminho separado continua sendo opcional por meio de tools.web.search.openaiCodex.enabled: true e se aplica apenas a modelos openai/* qualificados que usam api: "openai-chatgpt-responses".

{  tools: {    web: {      search: {        enabled: true,        // Opcional: use a Pesquisa Hospedada do Codex também com modelos principais que não sejam do Codex.        provider: "codex",        openaiCodex: {          enabled: true,          mode: "cached",          allowedDomains: ["example.com"],          contextSize: "high",          userLocation: {            country: "US",            city: "New York",            timezone: "America/New_York",          },        },      },    },  },}

Para ambientes de execução e provedores que não oferecem suporte à pesquisa nativa do Codex, o Codex pode usar o fallback gerenciado web_search por meio do namespace dinâmico de ferramentas do OpenClaw. Use um provedor gerenciado explícito quando precisar dos controles de rede específicos do provedor do OpenClaw em vez da pesquisa hospedada pelo Codex.

Selecionar provider: "codex" habilita o plugin integrado codex e usa as mesmas restrições de tools.web.search.openaiCodex mostradas acima. Primeiro, autentique o app-server do Codex com openclaw models auth login --provider openai. O agente principal pode usar qualquer modelo ou ambiente de execução; somente o executor de pesquisa limitado é executado pelo Codex.

Segurança de rede

As chamadas HTTP dos provedores gerenciados de web_search usam o caminho de busca protegido do OpenClaw, limitado ao hostname próprio do provedor atual. Somente para esse hostname, o OpenClaw permite respostas DNS de IP falso do Surge, Clash e sing-box nos intervalos 198.18.0.0/15 e fc00::/7. Outros destinos privados, de local loopback, link-local e de metadados permanecem bloqueados. A Pesquisa Hospedada do Codex é a exceção: seu executor limitado delega o acesso à rede à ferramenta hospedada web_search do app-server do Codex.

Essa permissão automática não se aplica a URLs arbitrárias de web_fetch. Para web_fetch, habilite explicitamente tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange e tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange somente quando seu proxy confiável for proprietário desses intervalos sintéticos.

Configuração

{  tools: {    web: {      search: {        enabled: true, // padrão: true        provider: "brave", // ou omita para detecção automática        maxResults: 5,        timeoutSeconds: 30,        cacheTtlMinutes: 15,      },    },  },}

A configuração específica do provedor (chaves de API, URLs base, modos) fica em plugins.entries.<plugin>.config.webSearch.*. O Gemini também pode reutilizar models.providers.google.apiKey e models.providers.google.baseUrl como fallbacks de prioridade mais baixa depois de sua configuração dedicada de pesquisa na web e de GEMINI_API_KEY. Consulte as páginas dos provedores para ver exemplos. O Grok também pode reutilizar um perfil de autenticação OAuth da xAI criado com openclaw models auth login --provider xai --method oauth; a configuração por chave de API continua sendo o fallback.

tools.web.search.provider é validado em relação aos IDs de provedores de pesquisa na web declarados pelos manifestos dos plugins integrados e instalados. Um erro de digitação como "brvae" faz a validação da configuração falhar, em vez de recorrer silenciosamente à detecção automática. Se um provedor configurado tiver apenas evidências obsoletas de plugin, como um bloco plugins.entries.<plugin> remanescente após a desinstalação de um plugin de terceiros, o OpenClaw mantém a inicialização resiliente e emite um aviso para que você possa reinstalar o plugin ou executar openclaw doctor --fix para limpar a configuração obsoleta.

A seleção do provedor de fallback de web_fetch é separada:

• escolha-o com tools.web.fetch.provider
• ou omita esse campo e deixe o OpenClaw detectar automaticamente o primeiro provedor de busca na web pronto com base nas credenciais configuradas
• web_fetch sem sandbox pode usar provedores de plugins instalados que declarem contracts.webFetchProviders; buscas com sandbox permitem provedores integrados e instalações verificadas de plugins oficiais, mas excluem plugins externos de terceiros
• o plugin oficial Firecrawl é atualmente o único colaborador integrado de webFetchProviders, configurado em plugins.entries.firecrawl.config.webFetch.*

Quando você escolhe Kimi durante openclaw onboard ou openclaw configure --section web, o OpenClaw também pode solicitar:

• a região da API Moonshot (https://api.moonshot.ai/v1 ou https://api.moonshot.cn/v1)
• o modelo padrão de pesquisa na web do Kimi (o padrão é kimi-k2.6)

Para x_search, configure plugins.entries.xai.config.xSearch.*. Ele usa o mesmo perfil de autenticação da xAI usado pelo chat, ou a credencial XAI_API_KEY / de pesquisa na web do plugin usada pela pesquisa na web do Grok. A configuração legada tools.web.x_search.* é migrada automaticamente por openclaw doctor --fix. Quando você escolhe Grok durante openclaw onboard ou openclaw configure --section web, o OpenClaw também oferece a configuração opcional de x_search com a mesma credencial logo após a conclusão da configuração do Grok. Essa é uma etapa posterior separada dentro do caminho do Grok, não uma escolha separada de provedor de pesquisa na web no nível superior. Se você escolher outro provedor, o OpenClaw não exibirá a solicitação de x_search.

Armazenamento de chaves de API

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

export BRAVE_API_KEY="YOUR_KEY"

Parâmetros da ferramenta

x_search

x_search consulta publicações do X (antigo Twitter) usando a xAI e retorna respostas sintetizadas por IA com citações. Ele aceita consultas em linguagem natural e filtros estruturados opcionais. O OpenClaw constrói a ferramenta integrada x_search da xAI a cada solicitação, em vez de mantê-la registrada permanentemente, portanto ela fica ativa apenas no turno que efetivamente a chama.

Configuração de x_search

Com enabled omitido, x_search é exposto somente quando o provedor do modelo ativo é xai e as credenciais da xAI são resolvidas. Para um modelo ativo com um provedor conhecido que não seja xAI, defina plugins.entries.xai.config.xSearch.enabled como true para habilitar o uso entre provedores. Se o provedor do modelo ativo estiver ausente ou não puder ser resolvido, a ferramenta permanecerá oculta. Defina enabled como false para desativá-la para todos os provedores. As credenciais da xAI são sempre obrigatórias.

{  plugins: {    entries: {      xai: {        config: {          xSearch: {            enabled: true, // obrigatório para um provedor conhecido de modelo que não seja xAI            model: "grok-4.3",            baseUrl: "https://api.x.ai/v1", // opcional, substitui webSearch.baseUrl            inlineCitations: false,            maxTurns: 2,            timeoutSeconds: 30,            cacheTtlMinutes: 15,          },          webSearch: {            apiKey: "xai-...", // opcional se um perfil de autenticação da xAI ou XAI_API_KEY estiver definido            baseUrl: "https://api.x.ai/v1", // URL base compartilhada opcional da API Responses da xAI          },        },      },    },  },}

x_search envia uma solicitação POST para <baseUrl>/responses quando plugins.entries.xai.config.xSearch.baseUrl está definido. Se esse campo for omitido, usa como alternativas, na ordem, plugins.entries.xai.config.webSearch.baseUrl, o campo legado tools.web.search.grok.baseUrl e, por fim, o endpoint público da xAI (https://api.x.ai/v1).

Parâmetros de x_search

allowed_x_handles e excluded_x_handles são mutuamente exclusivos.

Exemplo de x_search

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

// Estatísticas por publicação: use a URL exata do status ou o ID do status quando possívelawait x_search({  query: "https://x.com/huntharo/status/1905678901234567890",});

Exemplos

// Pesquisa básicaawait web_search({ query: "OpenClaw plugin SDK" }); // Pesquisa específica para a Alemanhaawait web_search({ query: "TV online schauen", country: "DE", language: "de" }); // Resultados recentes (última semana)await web_search({ query: "AI developments", freshness: "week" }); // Intervalo de datasawait web_search({  query: "climate research",  date_after: "2024-01-01",  date_before: "2024-06-30",}); // Filtragem por domínio (somente Perplexity)await web_search({  query: "product reviews",  domain_filter: ["-reddit.com", "-pinterest.com"],});

Perfis de ferramentas

Se você usar perfis de ferramentas ou listas de permissões, adicione web_search, x_search ou group:web:

{  tools: {    allow: ["web_search", "x_search"],    // ou: allow: ["group:web"]  (inclui web_search, x_search e web_fetch)  },}

Conteúdo relacionado

• Busca de conteúdo da Web -- busca uma URL e extrai conteúdo legível
• Navegador da Web -- automação completa do navegador para sites que dependem intensamente de JS
• Pesquisa do Grok -- Grok como provedor de web_search
• Pesquisa na Web do Ollama -- pesquisa na Web sem chave por meio do seu host Ollama