Busca na Web

A ferramenta web_fetch faz um HTTP GET simples e extrai conteúdo legível (HTML para markdown ou texto). Ela não executa JavaScript.

Para sites com uso intenso de JS ou páginas protegidas por login, use o Navegador Web.

Início rápido

web_fetch vem habilitada por padrão -- nenhuma configuração é necessária. O agente pode chamá-la imediatamente:

await web_fetch({ url: "https://example.com/article" });

Parâmetros da ferramenta

Como funciona

Atualizações de progresso

web_fetch emite uma linha pública de progresso somente quando a busca ainda está pendente após cinco segundos:

Fetching page content...

Acertos rápidos de cache e respostas rápidas de rede terminam antes do temporizador disparar, então não mostram uma linha de progresso. Se a chamada for cancelada, o temporizador é limpo. Quando a busca finalmente termina, o agente recebe o resultado normal da ferramenta; a linha de progresso é apenas estado da interface do canal e nunca contém conteúdo buscado da página.

Configuração

{  tools: {    web: {      fetch: {        enabled: true, // default: true        provider: "firecrawl", // optional; omit for auto-detect        maxChars: 50000, // max output chars        maxCharsCap: 50000, // hard cap for maxChars param        maxResponseBytes: 2000000, // max download size before truncation        timeoutSeconds: 30,        cacheTtlMinutes: 15,        maxRedirects: 3,        useTrustedEnvProxy: false, // let a trusted HTTP(S) env proxy resolve DNS        readability: true, // use Readability extraction        userAgent: "Mozilla/5.0 ...", // override User-Agent        ssrfPolicy: {          allowRfc2544BenchmarkRange: true, // opt-in for trusted fake-IP proxies using 198.18.0.0/15          allowIpv6UniqueLocalRange: true, // opt-in for trusted fake-IP proxies using fc00::/7        },      },    },  },}

Fallback do Firecrawl

Se a extração do Readability falhar, web_fetch pode recorrer ao Firecrawl para contorno de bots e melhor extração:

{  tools: {    web: {      fetch: {        provider: "firecrawl", // optional; omit for auto-detect from available credentials      },    },  },  plugins: {    entries: {      firecrawl: {        enabled: true,        config: {          webFetch: {            // apiKey: "fc-...", // optional; omit for keyless starter access            baseUrl: "https://api.firecrawl.dev",            onlyMainContent: true,            maxAgeMs: 86400000, // cache duration (1 day)            timeoutSeconds: 60,          },        },      },    },  },}

plugins.entries.firecrawl.config.webFetch.apiKey é opcional e oferece suporte a objetos SecretRef. A configuração legada tools.web.fetch.firecrawl.* é migrada automaticamente por openclaw doctor --fix.

Comportamento atual em runtime:

• tools.web.fetch.provider seleciona explicitamente o provedor de fallback de busca.
• Se provider for omitido, o OpenClaw detecta automaticamente o primeiro provedor de web-fetch pronto a partir das credenciais configuradas. web_fetch sem sandbox pode usar plugins instalados que declaram contracts.webFetchProviders e registram um provedor correspondente em runtime. O Plugin oficial do Firecrawl fornece esse fallback.
• Chamadas web_fetch em sandbox permitem provedores incluídos no pacote e provedores instalados cuja procedência oficial no npm ou ClawHub seja verificada. Hoje isso permite o Plugin oficial do Firecrawl; plugins externos de busca de terceiros permanecem excluídos.
• Se Readability estiver desabilitado, web_fetch pula direto para o fallback do provedor selecionado. Se nenhum provedor estiver disponível, falha em modo fechado.

Proxy de env confiável

Se sua implantação exigir que web_fetch passe por um proxy HTTP(S) de saída confiável, defina tools.web.fetch.useTrustedEnvProxy: true.

Nesse modo, o OpenClaw ainda aplica verificações SSRF baseadas em nome de host antes de enviar a solicitação, mas deixa o proxy resolver o DNS em vez de fazer fixação de DNS local. Habilite isso apenas quando o proxy for controlado pelo operador e aplicar política de saída após a resolução de DNS.

Limites e segurança

• maxChars é limitado a tools.web.fetch.maxCharsCap
• O corpo da resposta é limitado a maxResponseBytes antes da análise; respostas grandes demais são truncadas com um aviso
• Nomes de host privados/internos são bloqueados
• tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange e tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange são adesões restritas para pilhas de proxy de IP falso confiáveis; deixe-as indefinidas, a menos que seu proxy possua esses intervalos sintéticos e aplique sua própria política de destino
• Redirecionamentos são verificados e limitados por maxRedirects
• useTrustedEnvProxy é uma adesão explícita e deve ser habilitada apenas para proxies controlados pelo operador que ainda apliquem política de saída após a resolução de DNS
• web_fetch funciona em regime de melhor esforço -- alguns sites precisam do Navegador Web

Perfis de ferramenta

Se você usa perfis de ferramenta ou listas de permissão, adicione web_fetch ou group:web:

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

Relacionados

• Pesquisa Web -- pesquise na web com vários provedores
• Navegador Web -- automação completa de navegador para sites com uso intenso de JS
• Firecrawl -- ferramentas de pesquisa e scraping do Firecrawl