---
read_when:
- Você quer buscar uma URL e extrair conteúdo legível
- Você precisa configurar o web_fetch ou seu fallback do Firecrawl
- Você quer entender os limites e o armazenamento em cache do web_fetch
sidebarTitle: Web Fetch
summary: ferramenta web_fetch -- busca HTTP com extração de conteúdo legível
title: Busca na Web
x-i18n:
generated_at: "2026-07-12T00:29:56Z"
model: gpt-5.6
postprocess_version: locale-links-v1
provider: openai
source_hash: 8c956b01fce44dc4b8f3ac289b312691c3fe4293ed2e6777fb53f3345dd99e93
source_path: tools/web-fetch.md
workflow: 16
---
`web_fetch` faz uma solicitação HTTP GET simples e extrai conteúdo legível (de HTML para
Markdown ou texto). Ele **não** executa JavaScript. Para sites que dependem muito de JS ou
páginas protegidas por login, use o [Navegador Web](/pt-BR/tools/browser).
## Início rápido
Ativado por padrão, sem necessidade de configuração:
```javascript
await web_fetch({ url: "https://example.com/article" });
```
## Parâmetros da ferramenta
URL a ser buscada. Somente `http(s)`.
Formato de saída após a extração do conteúdo principal.
Trunca a saída para esta quantidade de caracteres. Limitado por `tools.web.fetch.maxCharsCap`.
## Como funciona
Envia uma solicitação HTTP GET com um User-Agent semelhante ao Chrome e o cabeçalho
`Accept-Language`. Bloqueia nomes de host privados/internos e verifica novamente os redirecionamentos.
Executa o Readability (extração do conteúdo principal) na resposta HTML.
Se o Readability falhar e houver um provedor de busca disponível, tenta novamente por meio
desse provedor (por exemplo, o modo de contorno de bots do Firecrawl).
Os resultados são armazenados em cache por 15 minutos (configurável) para reduzir buscas
repetidas da mesma URL.
## Atualizações de progresso
`web_fetch` emite uma linha pública de progresso somente quando a busca ainda está pendente
após cinco segundos:
```text
Buscando conteúdo da página...
```
Acertos rápidos no cache e respostas rápidas da rede terminam antes que o temporizador seja acionado, portanto
nunca exibem uma linha de progresso. Cancelar a chamada limpa o temporizador. A
linha de progresso é apenas um estado da interface do canal e nunca contém o conteúdo buscado da página.
## Configuração
```json5
{
tools: {
web: {
fetch: {
enabled: true, // padrão: true
provider: "firecrawl", // opcional; omita para detecção automática
maxChars: 20000, // caracteres de saída padrão; limitado por maxCharsCap
maxCharsCap: 20000, // limite rígido para o parâmetro maxChars
maxResponseBytes: 750000, // tamanho máximo do download antes do truncamento (32000-10000000)
timeoutSeconds: 30,
cacheTtlMinutes: 15,
maxRedirects: 3,
useTrustedEnvProxy: false, // permite que um proxy HTTP(S) de ambiente confiável resolva o DNS
readability: true, // usa a extração do Readability
userAgent: "Mozilla/5.0 ...", // substitui o User-Agent
ssrfPolicy: {
allowRfc2544BenchmarkRange: true, // opção explícita para proxies de IP falso confiáveis que usam 198.18.0.0/15
allowIpv6UniqueLocalRange: true, // opção explícita para proxies de IP falso confiáveis que usam fc00::/7
},
},
},
},
}
```
## Alternativa com Firecrawl
Se a extração do Readability falhar, `web_fetch` pode recorrer ao
[Firecrawl](/pt-BR/tools/firecrawl) para contornar bots e melhorar a extração:
```json5
{
tools: {
web: {
fetch: {
provider: "firecrawl", // opcional; omita para detecção automática a partir das credenciais disponíveis
},
},
},
plugins: {
entries: {
firecrawl: {
enabled: true,
config: {
webFetch: {
// apiKey: "fc-...", // opcional; omita para acesso inicial sem chave
baseUrl: "https://api.firecrawl.dev",
onlyMainContent: true,
maxAgeMs: 172800000, // duração do cache (2 dias)
timeoutSeconds: 60,
},
},
},
},
},
}
```
`plugins.entries.firecrawl.config.webFetch.apiKey` é opcional e aceita objetos SecretRef.
A configuração legada `tools.web.fetch.firecrawl.*` é migrada automaticamente para
`plugins.entries.firecrawl.config.webFetch` por meio de `openclaw doctor --fix`.
Se você configurar uma SecretRef de chave de API do Firecrawl e ela não for resolvida, sem uma
alternativa na variável de ambiente `FIRECRAWL_API_KEY`, a inicialização do Gateway falhará imediatamente.
As substituições de `baseUrl` do Firecrawl são restritas: o tráfego hospedado usa
`https://api.firecrawl.dev`; substituições auto-hospedadas devem apontar para endpoints privados ou
internos, e `http://` é aceito somente para esses destinos privados.
Comportamento atual em tempo de execução:
- `tools.web.fetch.provider` seleciona explicitamente o provedor alternativo de busca.
- Se `provider` for omitido, o OpenClaw detectará automaticamente o primeiro provedor de busca
na web pronto a partir das credenciais configuradas. O `web_fetch` fora de sandbox pode usar
plugins instalados que declarem `contracts.webFetchProviders` e registrem um
provedor correspondente em tempo de execução. Atualmente, o Plugin oficial do Firecrawl fornece essa
alternativa.
- Chamadas de `web_fetch` em sandbox permitem provedores integrados e provedores instalados
cuja procedência oficial do npm ou ClawHub tenha sido verificada. Atualmente, isso permite o
Plugin oficial do Firecrawl; plugins externos de busca de terceiros permanecem excluídos.
- Se o Readability estiver desativado, `web_fetch` passa diretamente para o provedor alternativo
selecionado. Se nenhum provedor estiver disponível, ele falhará de forma segura.
## Proxy de ambiente 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 de SSRF baseadas no nome do host antes de enviar
a solicitação, mas permite que o proxy resolva o DNS em vez de realizar a fixação de DNS
localmente. Ative isso somente quando o proxy for controlado pelo operador e aplicar
a política de saída após a resolução de DNS.
Se nenhuma variável de ambiente de proxy HTTP(S) estiver configurada ou se o host de destino for excluído por
`NO_PROXY`, `web_fetch` voltará ao caminho estrito normal com fixação de DNS
local.
## Limites e segurança
- `maxChars` é limitado por `tools.web.fetch.maxCharsCap` (padrão: `20000`)
- O corpo da resposta é limitado a `maxResponseBytes` (padrão: `750000`, limitado ao intervalo
32000-10000000) 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 opções explícitas restritas
para pilhas confiáveis de proxy de IP falso; deixe-as sem definir, a menos que seu proxy controle
esses intervalos sintéticos e aplique sua própria política de destinos
- Os redirecionamentos são verificados e limitados por `maxRedirects` (padrão: `3`)
- `useTrustedEnvProxy` é uma opção explícita e deve ser ativada somente para
proxies controlados pelo operador que continuem aplicando a política de saída após a resolução de
DNS
- `web_fetch` funciona em regime de melhor esforço — alguns sites exigem o [Navegador Web](/pt-BR/tools/browser)
## Perfis de ferramentas
Se você usar perfis de ferramentas ou listas de permissões, adicione `web_fetch` ou `group:web`:
```json5
{
tools: {
allow: ["web_fetch"],
// ou: allow: ["group:web"] (inclui web_fetch, web_search e x_search)
},
}
```
## Relacionados
- [Pesquisa na Web](/pt-BR/tools/web) — pesquise na web com vários provedores
- [Navegador Web](/pt-BR/tools/browser) — automação completa do navegador para sites que dependem muito de JS
- [Firecrawl](/pt-BR/tools/firecrawl) — ferramentas de pesquisa e extração do Firecrawl