Como usar o Brave Search no OpenClaw: o guia completo de configuração

Recém-instalado, o OpenClaw sabe pensar, mas não sabe pesquisar. Uma instalação nova vem sem provedor de busca na web, então na primeira vez que você perguntar ao seu agente algo mais recente que os dados de treinamento do modelo dele, ele ou admite a derrota ou improvisa quietinho. A solução leva uns cinco minutos: plugar a API do Brave Search. Hospedar instâncias do OpenClaw é o nosso ganha-pão na PlusAgents, e o Brave é o provedor de busca que a gente mais vê configurado por aí. Este guia cobre o processo inteiro: a chave, a configuração, os testes, os ajustes e a nova habilidade do Brave para usuários avançados.

Por que o Brave é a resposta padrão

O OpenClaw suporta um punhado de provedores de busca (Perplexity, Exa, Firecrawl, DuckDuckGo e companhia), mas o Brave é o primeiro que o assistente de configuração sugere e o que a comunidade de fato usa. Três motivos. Primeiro, o Brave mantém um índice próprio e independente da web em vez de revender resultados do Google ou do Bing, o que o deixa menos manipulado por SEO e genuinamente respeitoso com a privacidade. Segundo, ele foi construído como uma API para agentes de IA, com um modo de contexto pronto para LLMs que a gente vê mais adiante. Terceiro, o preço é difícil de contestar: todo plano inclui $5 de crédito grátis que renovam todo mês, e o plano Search custa $5 por 1.000 requisições. Isso dá mais ou menos 1.000 consultas grátis por mês, o que cobre com folga os hábitos diários de um assistente pessoal.

Uma nota de rodapé para os pioneiros: se você ainda tem o plano gratuito original do Brave (2.000 consultas por mês), ele continua funcionando, mas não inclui recursos mais novos como o endpoint de LLM Context. Configurações novas devem usar o plano Search.

Passo 1: pegue uma chave de API do Brave

1. Crie uma conta no painel da API do Brave Search. E-mail e senha, sem drama.
2. Em "My subscriptions", assine o plano Search. O crédito mensal de $5 entra automaticamente.
3. Defina um limite de uso no painel. É opcional, mas sábio: com o teto em $5, seu uso continua grátis para sempre e nenhum agente descontrolado surpreende o seu cartão de crédito.
4. Vá à seção "API Keys", gere uma chave e copie para um lugar seguro.

Passo 2: entregue a chave ao OpenClaw

Existem três jeitos de entregar a chave ao OpenClaw. Todos terminam no mesmo lugar, então escolha o que combina com o seu temperamento.

O assistente de configuração (recomendado)

openclaw configure --section web

O assistente interativo do OpenClaw pergunta qual provedor de busca na web você quer, pede a chave, valida e escreve no lugar certo da configuração. Sem JSON, sem erro de digitação, sem folclore de post antigo de blog.

O arquivo de configuração

Se você prefere editar a configuração direto (ou automatiza suas implantações com scripts), abra ~/.openclaw/openclaw.json. O endereço canônico da chave é plugins.entries.brave.config.webSearch.apiKey, e a seleção do provedor mora em tools.web.search:

{
  "plugins": {
    "entries": {
      "brave": {
        "config": {
          "webSearch": {
            "apiKey": "YOUR_BRAVE_API_KEY"
          }
        }
      }
    }
  },
  "tools": {
    "web": {
      "search": {
        "provider": "brave",
        "maxResults": 5,
        "timeoutSeconds": 30
      }
    }
  }
}

Você vai encontrar guias antigos que colocam a chave em tools.web.search.apiKey. Esse caminho ainda carrega por uma camada de compatibilidade, mas é legado: o plugin do Brave lê primeiro o caminho de plugins, então configurações novas devem usar ele e se poupar de uma tarde confusa no futuro.

A variável de ambiente

export BRAVE_API_KEY="your-key-here"

O OpenClaw pega BRAVE_API_KEY do ambiente do Gateway como alternativa. É o caminho natural para Docker e outras configurações em contêiner, onde variáveis de ambiente são mais convenientes que arquivos de configuração.

Seja qual for o caminho escolhido, reinicie o Gateway para ele aplicar a mudança:

openclaw gateway restart

Passo 3: prove que funciona

Pergunte ao seu agente algo que o modelo dele não tem como saber: "O que saiu na última versão do OpenClaw esta semana?" ou "Como está o tempo em Lisboa agora?". Veja ele chamar a ferramenta web_search e voltar com uma resposta acompanhada de fontes e URLs que ele não tinha cinco segundos atrás. O teste é esse. Se o agente responder de memória em vez de buscar, mande explicitamente ele pesquisar na web; se a ferramenta der erro, pule para a seção de solução de problemas logo abaixo (spoiler: quase sempre é o reinício que faltou).

Ajustes: as configurações que importam de verdade

• maxResults. Quantos resultados uma busca retorna, de 1 a 10 (padrão 5). Mais resultados significam mais contexto e mais tokens; 5 é um padrão sensato.
• Filtros de atualidade e de data. O agente pode restringir os resultados ao último dia, semana, mês ou ano, ou fixar um intervalo exato de datas. Útil para perguntas do tipo "o que mudou desde...", em que resultado velho é pior que nenhum.
• País e idioma. As buscas podem ser localizadas, por exemplo país DE com idioma de para resultados em alemão. Se você trabalha em mais de um idioma, seu agente se beneficia disso sem alarde.
• Modo llm-context. Definir webSearch.mode como "llm-context" na configuração de plugins troca os resultados clássicos (título, URL, trecho) pela LLM Context API do Brave, que retorna blocos de texto pré-extraídos e prontos para embasar respostas. Menos páginas para buscar na sequência, respostas melhores em tarefas pesadas de pesquisa.
• Cache. Buscas idênticas ficam em cache por 15 minutos por padrão (configurável via cacheTtlMinutes), então um agente empolgado não queima sua cota repetindo a mesma pergunta.

O caminho dos usuários avançados: a CLI bx do Brave como habilidade

Em 2026 o Brave lançou o bx, um cliente de linha de comando sem dependências para a API de busca, feito especificamente para agentes de IA, além de uma habilidade oficial do OpenClaw que ensina o seu agente a usar. Comparado ao provedor embutido, você ganha os endpoints sofisticados: bx context retorna conteúdo da web pré-extraído e dentro de um orçamento de tokens em uma chamada só, e os Goggles deixam você reordenar os resultados com regras próprias (dar impulso à documentação, enterrar spam de SEO). Se o provedor embutido é uma caixa de busca, o bx é um assistente de pesquisa.

Primeiro, instale a CLI com o script oficial (ele imprime onde o binário foi parar, normalmente ~/.local/bin):

curl -fsSL https://raw.githubusercontent.com/brave/brave-search-cli/main/scripts/install.sh | sh

Segundo, defina a sua chave rodando bx config set-key sem argumento: ele pergunta interativamente, o que mantém a chave fora do histórico do seu shell. Terceiro, deixe o OpenClaw encontrar o binário e reinicie o Gateway:

openclaw config set tools.exec.pathPrepend '["/home/you/.local/bin"]'
openclaw gateway restart

Por fim, instale a habilidade a partir do ClawHub:

openclaw skills install bx-search

Daí em diante, seu agente passa a preferir o bx para pesquisas na web. Você também pode invocar explicitamente com /skill bx-search "sua consulta", útil quando o agente teima em usar a ferramenta embutida. As duas configurações convivem numa boa: o provedor Brave embutido é a base confiável, a habilidade é o upgrade.

Na PlusAgents: cole a chave no chat

Se o seu OpenClaw roda na PlusAgents, não tem terminal nem edição de arquivo no seu futuro. Seu agente tem acesso total à própria configuração, então a instalação inteira é uma mensagem de chat: "Aqui está a minha chave da API do Brave Search: BSA... Configure-se para usar o Brave nas buscas na web e depois reinicie o seu gateway." O agente escreve a chave no caminho canônico da configuração, reinicia e confirma. É uma sensação estranha na primeira vez, pedir para o software se reconfigurar sozinho, e é também exatamente a graça de rodar um agente.

Se você ainda não tem um agente, o plano gratuito te dá uma instância de verdade do OpenClaw em cerca de um minuto, com créditos LLM inclusos, e o nosso guia de implantação compara todos os outros jeitos de rodar.

Solução de problemas e segurança

• Mudou a configuração e nada aconteceu? Reinicie o Gateway. Esse é o relato número um de "não funciona", e openclaw gateway restart é a solução.
• Erros ou resultados vazios? Confira no painel do Brave se a sua assinatura está ativa e se a chave é mesmo a que você pensa que é. Chaves de uma assinatura excluída falham em silêncio.
• Batendo nos limites? O crédito grátis cobre cerca de 1.000 consultas por mês. Um agente pesado em pesquisa consegue torrar isso, então acompanhe o gráfico de uso no painel e aumente o seu teto de propósito, não por acidente.
• Precisa de diagnóstico de verdade? Ative a flag de diagnóstico brave.http e o OpenClaw registra as URLs das requisições, o tempo de resposta e os acertos ou erros de cache. Ele nunca registra a sua chave de API.
• Higiene da chave. Defina um teto de uso, evite passar a chave como flag de linha de comando (ela fica no histórico do shell) e revogue no painel no instante em que suspeitar de vazamento.

É isso: seu agente agora consegue pesquisar de verdade em vez de lembrar com confiança. Se você ainda está no começo da jornada com o OpenClaw, nosso guia de como usar o OpenClaw transforma uma instalação nova em um assistente diário em uma semana, e, se você ainda não sabe direito o que é o OpenClaw, comece por aqui.