Pesquisa na web

The tool 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 do 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" });

# Como escolher um provedor

# Comparação de provedores

# Detecção automática

# Pesquisa web nativa da OpenAI

Modelos diretos de OpenAI Responses usam automaticamente a ferramenta web_search hospedada pela OpenAI quando a pesquisa 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 Azure. Defina tools.web.search.provider para outro provedor, como brave, para manter a ferramenta web_search gerenciada para modelos OpenAI, ou defina tools.web.search.enabled: false para desabilitar tanto a pesquisa gerenciada quanto a pesquisa nativa da OpenAI.

# Pesquisa web nativa do Codex

Modelos compatíveis com Codex podem opcionalmente usar a ferramenta web_search nativa do provedor em Responses em vez da função web_search gerenciada pelo OpenClaw.

• Configure-a em tools.web.search.openaiCodex
• Ela só é ativada para modelos compatíveis com Codex (openai-codex/* ou provedores usando api: "openai-codex-responses")
• web_search gerenciado ainda se aplica a modelos que não são Codex
• mode: "cached" é a configuração padrão e recomendada
• tools.web.search.enabled: false desabilita tanto a pesquisa gerenciada quanto a nativa

{
  tools: {
    web: {
      search: {
        enabled: true,
        openaiCodex: {
          enabled: true,
          mode: "cached",
          allowedDomains: ["example.com"],
          contextSize: "high",
          userLocation: {
            country: "US",
            city: "New York",
            timezone: "America/New_York",
          },
        },
      },
    },
  },
}

Se a pesquisa nativa do Codex estiver habilitada, mas o modelo atual não for compatível com Codex, o OpenClaw mantém o comportamento normal de web_search gerenciado.

# Segurança de rede

Chamadas de provedores web_search gerenciadas usam o caminho de fetch protegido do OpenClaw. Para hosts de API de provedores confiáveis, o OpenClaw permite respostas DNS de IP falso do Surge, Clash e sing-box em 198.18.0.0/15 e fc00::/7 somente para esse nome de host do provedor. Outros destinos privados, local loopback, link-local e de metadados permanecem bloqueados.

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 controlar esses intervalos sintéticos.

# Configuração da pesquisa web

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

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

Primeiro, provedores baseados em API:

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 -- 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)

Depois disso, alternativas sem chave:

10. DuckDuckGo -- alternativa HTML sem chave, sem conta ou chave de API (ordem 100)
11. Ollama Web Search -- alternativa sem chave via seu host local do Ollama configurado quando ele estiver acessível e autenticado com ollama signin; pode reutilizar a autenticação bearer do provedor Ollama quando o host precisar dela e pode chamar a pesquisa direta em https://ollama.com quando configurado com OLLAMA_API_KEY (ordem 110)
12. SearXNG -- SEARXNG_BASE_URL ou plugins.entries.searxng.config.webSearch.baseUrl (ordem 200)

Se nenhum provedor for detectado, ele volta para Brave (você receberá um erro de chave ausente solicitando que configure uma).

# 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 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 após sua configuração dedicada de busca na web e GEMINI_API_KEY. Consulte as páginas dos provedores para exemplos.

tools.web.search.provider é validado em relação aos IDs dos provedores de busca na web declarados pelos manifestos dos 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 provedor configurado tiver apenas evidência obsoleta de Plugin, como um bloco plugins.entries.<plugin> remanescente após desinstalar um Plugin de terceiros, o OpenClaw mantém a inicialização resiliente e relata 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 web-fetch pronto a partir das credenciais disponíveis
• web_fetch sem sandbox pode usar provedores de plugins instalados que declaram contracts.webFetchProviders; buscas com sandbox permanecem apenas incluídas
• hoje, o provedor de web-fetch incluído é Firecrawl, configurado em plugins.entries.firecrawl.config.webFetch.*

Ao escolher 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 (o padrão é kimi-k2.6)

Para x_search, configure plugins.entries.xai.config.xSearch.*. Ele usa o mesmo fallback XAI_API_KEY da busca na web do Grok. A configuração legada tools.web.x_search.* é migrada automaticamente por openclaw doctor --fix. Ao escolher Grok durante openclaw onboard ou openclaw configure --section web, o OpenClaw também pode oferecer a configuração opcional de x_search com a mesma chave. Esta é uma etapa complementar separada dentro do caminho do Grok, não uma escolha separada de provedor de busca na web de nível superior. Se você escolher outro provedor, o OpenClaw não mostrará o prompt 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 xAI e retorna respostas sintetizadas por IA com citações. Ele aceita consultas em linguagem natural e filtros estruturados opcionais. O OpenClaw só habilita a ferramenta x_search integrada da xAI 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 XAI_API_KEY is set
            baseUrl: "https://api.x.ai/v1", // optional shared xAI Responses base URL
          },
        },
      },
    },
  },
}

x_search envia 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",
});

// Per-post stats: use the exact status URL or status ID when possible
await x_search({
  query: "https://x.com/huntharo/status/1905678901234567890",
});

# Exemplos

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

// German-specific search
await web_search({ query: "TV online schauen", country: "DE", language: "de" });

// Recent results (past week)
await web_search({ query: "AI developments", freshness: "week" });

// Date range
await 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"],
});

# Perfis de ferramentas

Se você usar perfis de ferramentas ou allowlists, adicione web_search, x_search ou group:web:

{
  tools: {
    allow: ["web_search", "x_search"],
    // or: allow: ["group:web"]  (includes web_search, x_search, and web_fetch)
  },
}

# Relacionados

• Web Fetch -- busca uma URL e extrai 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