Pular para conteúdo
Intermediário Cap. 5 de 10 14 min de leitura

Web e APIs com OpenClaw: Automação de Dados Externos

Use OpenClaw para consumir APIs REST, fazer web scraping e integrar dados externos. Exemplos com ViaCEP, Receita Federal e WhatsApp Business API.

Um agente que só responde com o que está no system prompt tem valor limitado. O salto de qualidade acontece quando o agente consegue buscar dados externos em tempo real: consultar um CEP, verificar um CNPJ, checar disponibilidade de estoque, buscar cotações. Este capítulo cobre como usar a ferramenta web_request do OpenClaw para conectar seu agente ao mundo.

A Ferramenta web_request

O OpenClaw tem uma ferramenta nativa chamada web_request que permite ao agente fazer chamadas HTTP para qualquer URL. O agente decide quando e como usar essa ferramenta com base no contexto — você não precisa escrever código, só configurar quais ferramentas estão disponíveis e o agente aprende a usá-las automaticamente.

Para habilitar a ferramenta, adicione ao seu agente:

agents:
  - name: meu-agente
    model: haiku
    channel: whatsapp-principal
    tools:
      - name: web_request
        description: "Faz requisições HTTP para APIs e URLs externas"
        allowed_domains:
          - "viacep.com.br"
          - "brasilapi.com.br"
          - "api.example.com"

O campo allowed_domains é uma lista de domínios que o agente tem permissão para acessar. Isso é um controle de segurança — o agente não pode fazer requisições para domínios não listados, o que evita que o agente seja usado para acessar serviços não autorizados.

O backend de execução das ferramentas HTTP é configurável desde a v2026.3.22: por padrão usa o processo local, mas pode ser trocado para Docker (isolamento total — sandbox: docker) ou SSH (execução em servidor remoto). Para agentes em produção que acessam APIs com dados sensíveis, sandbox Docker isola cada chamada web_request em container efêmero.

Requisições GET: Consultando Dados

A maioria das APIs públicas funciona com GET — você monta a URL com os parâmetros e recebe os dados de volta.

Exemplo: ViaCEP

O ViaCEP é uma API pública brasileira gratuita que retorna endereço completo a partir de um CEP. Perfeita para confirmar endereços de entrega, pre-preencher formulários ou verificar cobertura de atendimento.

Formato da requisição:

GET https://viacep.com.br/ws/01001000/json/

Resposta:

{
  "cep": "01001-000",
  "logradouro": "Praça da Sé",
  "complemento": "lado ímpar",
  "bairro": "Sé",
  "localidade": "São Paulo",
  "uf": "SP",
  "ibge": "3550308",
  "ddd": "11"
}

Quando um cliente manda o CEP para o agente, ele chama a ferramenta web_request com essa URL, recebe os dados em JSON e os incorpora na resposta.

Exemplo: BrasilAPI CNPJ

A BrasilAPI agrega diversas APIs públicas brasileiras em uma interface padronizada. O endpoint de CNPJ retorna dados da Receita Federal:

GET https://brasilapi.com.br/api/cnpj/v1/11222333000181

Resposta inclui: razão social, nome fantasia, situação cadastral, endereço, atividade principal (CNAE), capital social e data de abertura.

Casos de uso práticos:

  • Agente de crédito que verifica situação do CNPJ antes de aprovar parceria
  • Onboarding de PJ que preenche automaticamente os dados da empresa pelo CNPJ
  • Validação de fornecedores antes de emitir NF

Outros endpoints úteis da BrasilAPI:

  • /api/cep/v2/{cep} — endereço por CEP (alternativa ao ViaCEP)
  • /api/banks/v1 — lista de bancos para validação de dados PIX
  • /api/feriados/v1/{ano} — feriados nacionais para cálculo de prazo útil
  • /api/ddd/v1/{ddd} — estado/cidade de um DDD
  • /api/taxas/v1 — taxas Selic, CDI e outras para cálculos financeiros

Requisições POST: Enviando Dados

Quando você precisa enviar dados para um sistema externo, usa POST. O agente monta o payload, adiciona os headers necessários e faz a requisição.

Exemplo de configuração para uma integração com webhook:

tools:
  - name: web_request
    allowed_domains:
      - "hooks.zapier.com"
      - "api.meusistema.com.br"
    default_headers:
      Content-Type: "application/json"

O agente vai construir o payload com base no contexto da conversa e enviar automaticamente. Você não precisa mapear cada campo manualmente — o agente entende o que é relevante com base na documentação que você coloca no system prompt.

Autenticação: Bearer Tokens e API Keys

A maioria das APIs que você vai usar em produção requer autenticação. O OpenClaw suporta os padrões mais comuns:

Bearer Token (OAuth 2.0)

tools:
  - name: web_request
    allowed_domains:
      - "api.minhaplataforma.com"
    auth:
      type: bearer
      token: "${MINHA_API_KEY}"

API Key em Header

tools:
  - name: web_request
    allowed_domains:
      - "api.externa.com"
    auth:
      type: header
      header_name: "X-API-Key"
      header_value: "${EXTERNA_API_KEY}"

API Key em Query String

tools:
  - name: web_request
    allowed_domains:
      - "api.legado.com.br"
    auth:
      type: query_param
      param_name: "api_key"
      param_value: "${LEGADO_API_KEY}"

Sempre coloque tokens em variáveis de ambiente, nunca no config.yaml diretamente.

Web Scraping: Quando Usar e Quando Não Usar

O OpenClaw também suporta extração de conteúdo de páginas HTML — web scraping. Use com critério:

Quando faz sentido usar:

  • O site não tem API pública
  • Você está acessando dados do próprio site da sua empresa
  • Os dados são públicos e o site não proíbe scraping no robots.txt
  • Volume baixo (não vai sobrecarregar o servidor)

Quando evitar:

  • Sites que têm API disponível (sempre prefira a API)
  • Dados com login necessário (questões legais e de ToS)
  • Volume alto sem permissão do dono do site
  • Sites com proteção Cloudflare ou similares

Para scraping, use a ferramenta web_fetch em vez de web_request — ela lida com renderização de HTML e extração de texto:

tools:
  - name: web_fetch
    allowed_domains:
      - "meusite.com.br"
    extract_text: true    # remove tags HTML, retorna só texto

Plugins de busca nativos: Exa, Tavily e Firecrawl

A v2026.3.22 inclui três plugins de busca prontos para uso:

  • Exa — busca semântica (encontra conteúdo por significado, não só palavras-chave)
  • Tavily — resultados otimizados para agentes (resumidos, com fonte)
  • Firecrawl — extração estruturada de páginas inteiras (HTML → markdown limpo)

Instale com openclaw skills install exa (ou tavily, firecrawl).

Para agentes que precisam de dados da web além de APIs REST documentadas — notícias, preços, conteúdo de sites sem API — esses plugins substituem a web_fetch genérica com resultados mais limpos e contextualizados.

Tratamento de Erros

APIs falham. Redes ficam lentas. Servidores retornam erros 500. Seu agente precisa lidar com isso graciosamente.

Configure timeouts e comportamento de fallback:

tools:
  - name: web_request
    timeout_seconds: 10     # desiste após 10 segundos
    max_retries: 2          # tenta mais 2 vezes em caso de falha de rede
    retry_delay_seconds: 1
    on_error: "Não consegui acessar essa informação agora. Tente novamente em alguns instantes."

Quando a ferramenta falha e não há fallback disponível, o agente deve comunicar isso ao usuário de forma clara — não ficar em loop tentando ou retornar um erro técnico incompreensível.

Também instrua o agente no system prompt sobre como se comportar quando dados externos não estão disponíveis:

Se não conseguir consultar o CEP, peça para o cliente confirmar o endereço manualmente ou tente novamente.
Se a API de CNPJ retornar erro, continue o atendimento sem os dados automáticos e peça que o cliente informe os dados da empresa.

Rate Limits: Não Abuse das APIs

APIs públicas têm limites de requisições. O ViaCEP, por exemplo, suporta uso normal sem autenticação, mas bloqueará se você fizer centenas de consultas por minuto. A BrasilAPI tem limites mais explícitos.

Boas práticas:

  • Cache: se o mesmo CEP for consultado várias vezes, guarde o resultado em memória por alguns minutos
  • Debounce: não faça a consulta até o usuário confirmar o CEP
  • Rate limiting interno: configure o OpenClaw para não fazer mais de N requisições por minuto para um mesmo domínio
tools:
  - name: web_request
    rate_limit:
      requests_per_minute: 30
      per_domain: true

Na Prática: Agente que Consulta CEP via WhatsApp

Este é o exemplo completo: um agente que recebe um CEP no WhatsApp, consulta o ViaCEP e responde com o endereço completo. Caso de uso real: serviço de entregas que verifica cobertura antes de confirmar o pedido.

Config do agente:

agents:
  - name: "EntregaBot"
    model: haiku
    channel: whatsapp-entregas
    system_prompt: |
      Você é o assistente de atendimento da Entregas Veloz.

      Quando um cliente informar um CEP, use a ferramenta web_request para consultar
      o endereço em https://viacep.com.br/ws/{CEP}/json/ (substitua {CEP} pelo CEP informado,
      sem hífen).

      Com o endereço retornado:
      1. Confirme o endereço para o cliente
      2. Verifique se o bairro está na lista de cobertura abaixo
      3. Informe se faz entrega naquela região e qual o prazo

      Regiões com cobertura (prazo 2h):
      - Vila Mariana, Moema, Ibirapuera, Brooklin, Santo André, São Bernardo do Campo

      Regiões sem cobertura:
      - Guarulhos, Osasco, Cotia, Carapicuíba (sugira o aplicativo parceiro X)

      Se o CEP não existir ou a API retornar erro, peça para o cliente verificar o CEP e tentar novamente.

    tools:
      - name: web_request
        allowed_domains:
          - "viacep.com.br"
        timeout_seconds: 8
        max_retries: 1

    memory:
      enabled: true
      max_turns: 10

    limits:
      max_tokens_per_session: 1500

Fluxo de conversa esperado:

Cliente: "Olá, vocês entregam no CEP 04116-020?"

AgentBot: [chama web_request para viacep.com.br/ws/04116020/json/]
         [recebe: bairro "Vila Mariana", cidade "São Paulo"]

AgentBot: "Olá! O CEP 04116-020 corresponde à Vila Mariana, em São Paulo.
          Sim, entregamos nessa região! Prazo estimado: 2 horas após confirmação do pedido.
          Quer fazer um pedido?"

Como testar:

openclaw agent test --agent EntregaBot --message "Entregam no CEP 01310-200?"

Verifique no output se a ferramenta foi chamada (deve aparecer nos logs de debug) e se a resposta incorporou os dados reais do endereço.

Para ir além desse padrão e automatizar o envio de mensagens proativas (lembretes, confirmações, notificações), o próximo capítulo cobre comunicação e mensagens — onde o agente não só responde, mas também inicia conversas.

Você também pode explorar os templates de mensagens para ver exemplos prontos de mensagens que funcionam bem no contexto de automação com agentes.

Baseado no “Automate Everything: The OpenClaw Handbook” por Kelly Claude (CC BY 4.0). Adaptado e expandido para o mercado brasileiro.

Ainda não instalou o OpenClaw?

Um comando instala tudo. Funciona em Linux, macOS e VPS (Hostinger, DigitalOcean).

curl -fsSL https://openclaw.ai/install.sh | bash
Ver guia de instalação completo
Esc