Busca na Web

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.

Início rápido

Ativado por padrão, sem necessidade de configuração:

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

Parâmetros da ferramenta

string

obrigatório

URL a ser buscada. Somente http(s).

'markdown' | 'text'

padrão:"markdown"

Formato de saída após a extração do conteúdo principal.

number

Trunca a saída para esta quantidade de caracteres. Limitado por tools.web.fetch.maxCharsCap.

Como funciona

Busca

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.

Extração

Executa o Readability (extração do conteúdo principal) na resposta HTML.

Alternativa (opcional)

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

Cache

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:

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

{
  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 para contornar bots e melhorar a extração:

{
  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

Perfis de ferramentas

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

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

Relacionados

Pesquisa na Web — pesquise na web com vários provedores
Navegador Web — automação completa do navegador para sites que dependem muito de JS
Firecrawl — ferramentas de pesquisa e extração do Firecrawl

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Início rápido

Parâmetros da ferramenta

Como funciona

Atualizações de progresso

Configuração

Alternativa com Firecrawl

Proxy de ambiente confiável

Limites e segurança

Perfis de ferramentas

Relacionados

​Início rápido

​Parâmetros da ferramenta

​Como funciona

​Atualizações de progresso

​Configuração

​Alternativa com Firecrawl

​Proxy de ambiente confiável

​Limites e segurança

​Perfis de ferramentas

​Relacionados

Início rápido

Parâmetros da ferramenta

Como funciona

Atualizações de progresso

Configuração

Alternativa com Firecrawl

Proxy de ambiente confiável

Limites e segurança

Perfis de ferramentas

Relacionados