Pesquisa na web

A ferramenta web_search pesquisa na web usando o provedor configurado e retorna resultados. Os resultados são armazenados em cache por consulta por 15 minutos (configurável).

O OpenClaw também inclui x_search para publicações no X (antigo Twitter) e web_fetch para busca leve de URLs. Nesta fase, web_fetch permanece local, enquanto web_search e x_search podem usar xAI Responses nos bastidores.

Início rápido

openclaw configure --section web

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

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

Escolhendo um provedor

Comparação de provedores

Detecção automática

Busca web nativa da OpenAI

Modelos diretos do OpenAI Responses usam automaticamente a ferramenta hospedada web_search da OpenAI quando a busca web do OpenClaw está habilitada e nenhum provedor gerenciado está fixado. Esse é um comportamento de propriedade do provedor no Plugin OpenAI incluído e se aplica apenas ao tráfego nativo da API OpenAI, não a URLs base de proxy compatíveis com OpenAI nem a rotas do Azure. Defina tools.web.search.provider para outro provedor, como brave, para manter a ferramenta gerenciada web_search para modelos OpenAI, ou defina tools.web.search.enabled: false para desabilitar tanto a busca gerenciada quanto a busca nativa da OpenAI.

Busca web nativa do Codex

O runtime do app-server do Codex usa automaticamente a ferramenta hospedada web_search do Codex quando a busca web está habilitada e nenhum provedor gerenciado está selecionado. A busca hospedada nativa e a ferramenta dinâmica gerenciada web_search do OpenClaw são mutuamente exclusivas, portanto a busca gerenciada não pode contornar restrições nativas de domínio. O OpenClaw usa a ferramenta gerenciada quando a busca hospedada está indisponível, explicitamente desabilitada ou substituída por um provedor gerenciado selecionado. O OpenClaw mantém a extensão independente web.run do Codex desabilitada porque o tráfego de app-server de produção rejeita seu namespace web definido pelo usuário.

• Configure a busca nativa em tools.web.search.openaiCodex
• Defina tools.web.search.provider: "codex" para provisionar Codex Hosted Search como o provedor gerenciado de web_search para qualquer modelo pai. Cada chamada executa uma rodada efêmera limitada do app-server do Codex e falha se o Codex não emitir um item hospedado webSearch.
• mode: "cached" é a preferência padrão, mas o Codex a resolve para acesso externo em tempo real para rodadas irrestritas do app-server; defina "live" para solicitar acesso em tempo real explicitamente
• Defina tools.web.search.provider para um provedor gerenciado como brave para usar o web_search gerenciado do OpenClaw
• Defina tools.web.search.openaiCodex.enabled: false para recusar a busca hospedada pelo Codex; outros provedores gerenciados permanecem disponíveis
• Restringir a superfície da ferramenta nativa do Codex também mantém o web_search gerenciado disponível
• Quando allowedDomains está definido, o fallback gerenciado automático falha fechado se a busca hospedada estiver indisponível, para que a allowlist nativa não possa ser contornada
• Execuções apenas com LLM e ferramentas desabilitadas desabilitam tanto a busca nativa quanto a gerenciada
• tools.web.search.enabled: false desabilita tanto a busca gerenciada quanto a nativa

Alterações persistentes na política efetiva de busca do Codex iniciam uma nova thread vinculada para que uma thread de app-server já carregada não possa manter acesso obsoleto à busca hospedada. Restrições transitórias por rodada usam uma thread restrita temporária e preservam o vínculo existente para 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 opt-in por meio de tools.web.search.openaiCodex.enabled: true e se aplica apenas a modelos openai/* qualificados usando 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",          },        },      },    },  },}

Para runtimes e provedores que não são compatíveis com a busca nativa do Codex, o Codex pode usar o fallback gerenciado de web_search por meio do namespace de ferramenta dinâmica do OpenClaw. Use um provedor gerenciado explícito quando precisar dos controles de rede específicos do provedor do OpenClaw em vez da busca hospedada pelo Codex.

Selecionar provider: "codex" habilita o Plugin codex incluído e usa as mesmas restrições de tools.web.search.openaiCodex mostradas acima. Autentique primeiro o app-server Codex com openclaw models auth login --provider openai. O agente pai pode usar qualquer modelo ou runtime; apenas o worker de busca limitado é executado por meio do Codex.

Segurança de rede

Chamadas gerenciadas do provider HTTP web_search usam o caminho de fetch protegido do OpenClaw. Para hosts de API de provider confiáveis, o OpenClaw permite respostas DNS fake-IP do Surge, Clash e sing-box em 198.18.0.0/15 e fc00::/7 somente para esse hostname de provider. Outros destinos privados, loopback, link-local e de metadados continuam bloqueados. Codex Hosted Search é a exceção: seu worker limitado delega o acesso à rede à ferramenta web_search hospedada do app-server Codex.

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

Configurando a busca na Web

Listas de providers na documentação e nos fluxos de configuração ficam em ordem alfabética. A detecção automática mantém uma ordem de precedência separada.

Se nenhum provider estiver definido, o OpenClaw verifica os providers nesta ordem e usa o primeiro que estiver pronto:

Providers com API primeiro:

1. Brave -- BRAVE_API_KEY ou plugins.entries.brave.config.webSearch.apiKey (ordem 10)
2. MiniMax Search -- 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; plugins.entries.exa.config.webSearch.baseUrl opcional substitui o endpoint da Exa (ordem 65)
9. Tavily -- TAVILY_API_KEY ou plugins.entries.tavily.config.webSearch.apiKey (ordem 70)
10. Parallel -- API paga Parallel Search via PARALLEL_API_KEY ou plugins.entries.parallel.config.webSearch.apiKey; plugins.entries.parallel.config.webSearch.baseUrl opcional substitui o endpoint (ordem 75)

Depois disso, providers com endpoint configurado:

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

Providers sem chave, como Parallel Search (Free), DuckDuckGo, Ollama Web Search e Codex Hosted Search, ficam disponíveis 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 para um provider sem chave só porque nenhum provider com API está configurado.

Modelos OpenAI Responses são uma exceção: enquanto tools.web.search.provider estiver indefinido, eles usam a busca na Web nativa da OpenAI em vez dos providers gerenciados acima. Defina tools.web.search.provider como parallel-free (ou outro provider) para roteá-los pelo caminho gerenciado.

Configuração

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

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

tools.web.search.provider é validado contra os IDs de provider de busca na Web declarados por manifests de plugins incluídos e instalados. Um erro de digitação como "brvae" falha na validação da configuração em vez de voltar silenciosamente para a detecção automática. Se um provider configurado tiver apenas evidência obsoleta de Plugin, como um bloco plugins.entries.<plugin> restante após desinstalar um Plugin de terceiros, o OpenClaw mantém a inicialização resiliente e informa um aviso para que você possa reinstalar o Plugin ou executar openclaw doctor --fix para limpar a configuração obsoleta.

A seleção de provider 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 provider de web-fetch pronto a partir das credenciais configuradas
• web_fetch sem sandbox pode usar providers de Plugin instalados que declaram contracts.webFetchProviders; fetches com sandbox permitem providers incluídos e instalações verificadas de Plugins oficiais, mas excluem Plugins externos de terceiros
• o Plugin oficial Firecrawl fornece fallback de web-fetch, configurado em plugins.entries.firecrawl.config.webFetch.*

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

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

Para x_search, configure plugins.entries.xai.config.xSearch.*. Ele usa o mesmo perfil de autenticação da xAI que o chat, ou a credencial XAI_API_KEY / de busca na Web do Plugin usada pela busca 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 pode oferecer configuração opcional de x_search com a mesma credencial. Esta é uma etapa de acompanhamento separada dentro do caminho do Grok, não uma escolha separada de provider de busca na Web de nível superior. Se você escolher outro provider, o OpenClaw não mostra o prompt de x_search.

Armazenando 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 posts do X (antigo Twitter) usando xAI e retorna respostas sintetizadas por IA com citações. Ele aceita consultas em linguagem natural e filtros estruturados opcionais. O OpenClaw habilita a ferramenta x_search integrada da xAI somente na requisição que atende a esta chamada de ferramenta.

Configuração de 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          },        },      },    },  },}

x_search posta para <baseUrl>/responses quando plugins.entries.xai.config.xSearch.baseUrl está definido. Se esse campo for omitido, ele faz fallback para plugins.entries.xai.config.webSearch.baseUrl, depois para o legado tools.web.search.grok.baseUrl e, por fim, para o endpoint público da xAI.

Parâmetros de x_search

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

// Busca básicaawait web_search({ query: "OpenClaw plugin SDK" }); // Busca 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 de 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)  },}

Relacionado

• Web Fetch -- buscar uma URL e extrair conteúdo legível
• Web Browser -- automação completa de navegador para sites com muito JS
• Grok Search -- Grok como provedor de web_search
• Ollama Web Search -- busca na web sem chave por meio do seu host Ollama