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

Um agente que só responde com o que está nas instruções tem valor limitado. O salto acontece quando o agente busca dados externos em tempo real: consulta um CEP, verifica um CNPJ, checa uma cotação. Este capítulo mostra como habilitar as ferramentas web do OpenClaw e fazer o agente usá-las.

As Ferramentas Web do OpenClaw

O acesso à web não é configurado por agente — é controlado globalmente pelo grupo de ferramentas group:web, que reúne web_fetch (buscar o conteúdo de uma URL) e web_search (pesquisar na web). O agente decide quando usar cada uma com base no contexto.

A forma de habilitar é pelo perfil de ferramentas ou por um allowlist explícito, no ~/.openclaw/openclaw.json (JSON5):

// ~/.openclaw/openclaw.json
{
  tools: {
    // O perfil "coding" já inclui o group:web (web_fetch, web_search)
    profile: "coding",
    // Alternativa explícita: allow: ["group:web"],
    web: {
      fetch: {
        enabled: true,
        provider: "firecrawl", // extrai HTML como texto/markdown limpo
        maxChars: 50000,
        timeoutSeconds: 30,
      },
      search: {
        enabled: true,
        apiKey: "${BRAVE_API_KEY}",
        maxResults: 5,
      },
    },
  },
}

Os perfis de permissão vão de minimal (só leitura) a full (acesso completo, com aprovação humana para ações destrutivas) — messaging, coding e full liberam a web em escala crescente. O esquema exato e sempre atualizado fica na referência de ferramentas oficial.

Consultando APIs Públicas

Com web_fetch habilitado, o agente busca uma URL e usa a resposta. Você não escreve código de requisição — descreve no AGENTS.md qual API usar e quando, e o agente monta a chamada.

Exemplo: ViaCEP

O ViaCEP é uma API pública brasileira gratuita que retorna endereço a partir de um CEP. Perfeita para confirmar endereços de entrega ou verificar cobertura.

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

Resposta:

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

Quando um cliente manda o CEP, o agente chama web_fetch nessa URL, recebe o JSON e incorpora os dados na resposta.

Exemplo: BrasilAPI CNPJ

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

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

A resposta inclui razão social, nome fantasia, situação cadastral, endereço, CNAE e data de abertura. Outros endpoints úteis:

/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 — Selic, CDI e outras taxas para cálculos financeiros

Como o Agente Sabe Qual API Usar

A instrução vai no AGENTS.md do workspace, não numa config de ferramenta. Você diz ao agente a URL e o passo a passo:

# AGENTS.md — trecho sobre CEP

Quando o cliente informar um CEP, use a ferramenta web_fetch em
https://viacep.com.br/ws/{CEP}/json/ (troque {CEP} pelo número, 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
3. Informe prazo e disponibilidade
Se a API falhar, peça para o cliente confirmar o endereço manualmente.

Esse é o padrão: as ferramentas são habilitadas no openclaw.json, e o “como usar” mora nas instruções do agente.

APIs com Autenticação

Para APIs públicas (ViaCEP, BrasilAPI), web_fetch resolve direto. Para APIs que exigem chave, há dois caminhos confiáveis:

Skill dedicada: escreva uma skill no workspace (~/.openclaw/workspace/skills/) que encapsula a chamada autenticada. A chave fica em variável de ambiente, referenciada pela skill. Veja anatomia do workspace para a estrutura de skills.
Plugin: instale um plugin do ClawHub que já integra o serviço (openclaw skills install nome).

A regra de ouro de segurança continua: a chave vai em variável de ambiente (${MINHA_API_KEY}), nunca colada no arquivo de configuração — releia as 5 regras de segurança.

Web Scraping: Quando Usar

O web_fetch também extrai conteúdo de páginas HTML. Use com critério:

Faz sentido quando: o site não tem API, os dados são do seu próprio site, são públicos e o robots.txt não proíbe, e o volume é baixo.

Evite quando: existe API disponível (sempre prefira a API), os dados exigem login, o volume é alto sem permissão, ou o site tem proteção anti-bot.

Plugins de Busca: Exa, Tavily e Firecrawl

Para conteúdo da web além de APIs REST — notícias, preços, páginas sem API — os plugins dedicados entregam resultados mais limpos que a busca genérica:

Exa — busca semântica (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).

Tratamento de Erros e Rate Limits

APIs falham e têm limites. Esse comportamento não se configura com chaves mágicas — você instrui o agente no AGENTS.md e escolhe boas práticas:

Fallback claro: diga ao agente o que fazer quando a consulta falhar (“peça para o cliente confirmar o endereço manualmente”).
Não martelar a API: instrua a não repetir a consulta em loop; uma tentativa e, se falhar, segue sem o dado automático.
Respeite os limites públicos: o ViaCEP bloqueia uso abusivo; a BrasilAPI tem limites explícitos. Para consultas repetidas do mesmo dado, peça ao agente para reaproveitar o que já buscou na sessão em vez de consultar de novo.

Exemplo de instrução no AGENTS.md:

Se não conseguir consultar o CEP, peça para o cliente confirmar o endereço.
Não tente a mesma consulta mais de uma vez na mesma conversa.
Se a API de CNPJ falhar, siga o atendimento e peça os dados da empresa ao cliente.

Na Prática: Agente que Consulta CEP via WhatsApp

Um agente que recebe um CEP no WhatsApp, consulta o ViaCEP e responde com o endereço e a cobertura. Caso real: serviço de entregas que verifica a região antes de confirmar o pedido.

1. Habilite a web no openclaw.json (tools.profile: "coding", como acima) e mantenha o canal WhatsApp ativo.

2. Instrua o agente no AGENTS.md:

# AGENTS.md — Entregas Veloz

Quando o cliente informar um CEP, use web_fetch em
https://viacep.com.br/ws/{CEP}/json/ (sem hífen) e:
1. Confirme o endereço
2. Verifique a cobertura (prazo 2h): Vila Mariana, Moema, Ibirapuera, Brooklin, Santo André, São Bernardo
3. Sem cobertura: Guarulhos, Osasco, Cotia, Carapicuíba — sugira o app parceiro
Se o CEP não existir ou a API falhar, peça para o cliente verificar e tentar de novo.

3. Teste pela linha de comando:

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

No output, verifique se a ferramenta foi chamada (aparece nos logs com openclaw logs --follow) e se a resposta incorporou o endereço real.

Para automatizar mensagens proativas (lembretes, confirmações), o próximo capítulo cobre comunicação e mensagens. E os templates de mensagens trazem exemplos prontos que funcionam bem com agentes.

Conteúdo original do OpenClaw Club Brasil, escrito para o mercado brasileiro. Referência oficial: documentação do OpenClaw.