Come usare Brave Search in OpenClaw: la guida completa alla configurazione

Appena installato, OpenClaw sa pensare ma non sa cercare. Un’installazione fresca arriva senza provider di ricerca web, quindi la prima volta che chiedi al tuo agente qualcosa di più recente dei dati di addestramento del suo modello, o ammette la sconfitta o improvvisa in silenzio. Il rimedio richiede circa cinque minuti: collegare la Brave Search API. Noi ospitiamo istanze di OpenClaw di mestiere su PlusAgents, e Brave è il provider di ricerca che vediamo configurato più di ogni altro. Questa guida copre l’intero percorso: la chiave, la configurazione, i test, la messa a punto e la nuova skill Brave per gli utenti esperti.

Perché Brave è la risposta di default

OpenClaw supporta una piccola folla di provider di ricerca (Perplexity, Exa, Firecrawl, DuckDuckGo e compagnia), ma Brave è quello che il wizard di configurazione propone per primo, e quello che la community usa davvero. Tre ragioni. Primo: Brave gestisce un proprio indice indipendente del web invece di rivendere i risultati di Google o Bing, quindi è meno inquinato dalla SEO e rispetta davvero la privacy. Secondo: è nato come API per agenti AI, con una modalità di contesto pronta per gli LLM di cui parleremo più avanti. Terzo, un prezzo con cui è difficile discutere: ogni piano include 5 $ di credito gratuito che si rinnova ogni mese, e il piano Search costa 5 $ ogni 1.000 richieste. Sono circa 1.000 query gratuite al mese, che coprono comodamente le abitudini quotidiane di un assistente personale.

Una nota per chi c’era dall’inizio: se hai ancora il vecchio piano gratuito di Brave (2.000 query al mese), continua a funzionare, ma non include le funzioni più recenti come l’endpoint LLM Context. Le nuove configurazioni dovrebbero usare il piano Search.

Passo 1: ottieni una chiave API di Brave

1. Crea un account nella dashboard della Brave Search API. Email e password, senza drammi.
2. Nella sezione “My subscriptions” sottoscrivi il piano Search. I 5 $ di credito mensile si applicano da soli.
3. Imposta un limite di utilizzo nella dashboard. È facoltativo ma saggio: con un tetto a 5 $ l’uso resta gratuito per sempre, e nessun agente fuori controllo può fare brutte sorprese alla tua carta di credito.
4. Vai nella sezione “API Keys”, genera una chiave e copiala in un posto sicuro.

Passo 2: consegna la chiave a OpenClaw

Ci sono tre modi per passare la chiave a OpenClaw. Finiscono tutti nello stesso posto, quindi scegli quello più adatto al tuo temperamento.

Il wizard (consigliato)

openclaw configure --section web

Il wizard interattivo di OpenClaw ti chiede quale provider di ricerca web vuoi, richiede la chiave, la convalida e la scrive nel punto giusto della configurazione. Niente JSON, niente refusi, niente folklore da vecchi post di blog.

Il file di configurazione

Se preferisci modificare la configurazione a mano (o fai i deploy via script), apri ~/.openclaw/openclaw.json. La casa canonica della chiave è plugins.entries.brave.config.webSearch.apiKey, e l’interruttore del provider vive sotto tools.web.search:

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

In giro troverai guide più vecchie che mettono la chiave in tools.web.search.apiKey. Quel percorso viene ancora caricato tramite uno shim di compatibilità, ma è legacy: il plugin di Brave legge prima il percorso plugins, quindi le nuove configurazioni dovrebbero usare quello e risparmiarsi un pomeriggio di confusione più avanti.

La variabile d’ambiente

export BRAVE_API_KEY="your-key-here"

Come fallback, OpenClaw legge BRAVE_API_KEY dall’ambiente del Gateway. È la via naturale per Docker e per gli altri setup containerizzati, dove le variabili d’ambiente sono più comode dei file di configurazione.

Qualunque strada tu abbia scelto, riavvia il Gateway perché recepisca la modifica:

openclaw gateway restart

Passo 3: la prova del nove

Chiedi al tuo agente qualcosa che il suo modello non può assolutamente sapere: “Cosa è uscito nell’ultima release di OpenClaw questa settimana?” oppure “Che tempo fa in questo momento a Lisbona?”. Guardalo chiamare il tool web_search e tornare con una risposta, più fonti e URL che cinque secondi prima non aveva. Il test è tutto qui. Se l’agente risponde a memoria invece di cercare, digli esplicitamente di cercare sul web; se il tool dà errore, salta alla sezione di risoluzione dei problemi qui sotto (spoiler: quasi sempre è il riavvio).

Messa a punto: le impostazioni che contano davvero

• maxResults. Quanti risultati restituisce una ricerca, da 1 a 10 (5 di default). Più risultati significano più contesto e più token; 5 è un default sensato.
• Freschezza e filtri per data. L’agente può limitare i risultati all’ultimo giorno, settimana, mese o anno, oppure fissare un intervallo di date preciso. Utile per le domande tipo “cosa è cambiato da...”, dove un risultato vecchio è peggio di nessun risultato.
• Paese e lingua. Le ricerche si possono localizzare, per esempio paese DE con lingua de per risultati in tedesco. Se lavori in più di una lingua, il tuo agente ne beneficia in silenzio.
• La modalità llm-context. Impostando webSearch.mode su “llm-context” nella configurazione dei plugin si passa dai risultati classici (titolo, URL, snippet) alla LLM Context API di Brave, che restituisce blocchi di testo già estratti e pronti per il grounding. Meno pagine da aprire dopo, risposte migliori nei compiti di ricerca intensa.
• Cache. Le ricerche identiche restano in cache per 15 minuti di default (configurabile via cacheTtlMinutes), così un agente entusiasta non brucia la tua quota rifacendo sempre la stessa domanda.

La via per utenti esperti: la CLI bx di Brave come skill

Nel 2026 Brave ha rilasciato bx, un client a riga di comando senza dipendenze per la Search API pensato apposta per gli agenti AI, più una skill ufficiale di OpenClaw che insegna al tuo agente a usarlo. Rispetto al provider integrato guadagni gli endpoint più raffinati: bx context restituisce in una sola chiamata contenuti web già estratti e dentro un budget di token, e i Goggles ti lasciano riordinare i risultati con regole personalizzate (spingi in alto la documentazione, seppellisci lo spam SEO). Se il provider integrato è una casella di ricerca, bx è un assistente di ricerca.

Primo, installa la CLI con lo script ufficiale (ti dice dove è finito il binario, di solito ~/.local/bin):

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

Secondo, imposta la chiave lanciando bx config set-key senza argomenti: te la chiede in modo interattivo, così non finisce nella cronologia della shell. Terzo, fai in modo che OpenClaw trovi il binario, poi riavvia il Gateway:

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

Infine, installa la skill da ClawHub:

openclaw skills install bx-search

Da quel momento il tuo agente preferisce bx per le ricerche sul web. Puoi anche invocarla esplicitamente con /skill bx-search “la tua query”, utile quando l’agente si intestardisce a usare il suo tool integrato. Le due configurazioni convivono benissimo: il provider Brave integrato è la base affidabile, la skill è l’upgrade.

Su PlusAgents: incolla la chiave in chat

Se il tuo OpenClaw gira su PlusAgents, nel tuo futuro non ci sono né terminale né file da modificare. Il tuo agente ha pieno accesso alla propria configurazione, quindi l’intera procedura è un solo messaggio in chat: “Ecco la mia chiave della Brave Search API: BSA... Configurati per usare Brave per la ricerca web, poi riavvia il tuo gateway.” L’agente scrive la chiave nel percorso canonico della configurazione, si riavvia e conferma. Fa uno strano effetto la prima volta, chiedere a un software di riconfigurarsi da solo, ed è anche tutto il senso di avere un agente.

Se un agente ancora non ce l’hai, il piano gratuito ti dà una vera istanza OpenClaw in circa un minuto, crediti LLM inclusi, e la nostra guida al deploy confronta tutti gli altri modi di farlo girare.

Risoluzione dei problemi e sicurezza

• Hai cambiato la configurazione e non è successo niente? Riavvia il Gateway. È la segnalazione numero uno tra i “non funziona”, e openclaw gateway restart è la cura.
• Errori o risultati vuoti? Verifica nella dashboard di Brave che l’abbonamento sia attivo e che la chiave sia davvero quella che credi. Le chiavi di un abbonamento cancellato falliscono in silenzio.
• Stai toccando i limiti? Il credito gratuito copre circa 1.000 query al mese. Un agente che fa molta ricerca può bruciarle in fretta, quindi tieni d’occhio il grafico di utilizzo nella dashboard e alza il tetto in modo deliberato, non per sbaglio.
• Ti serve una diagnostica vera? Abilita il flag di diagnostica brave.http e OpenClaw registra nei log gli URL delle richieste, i tempi di risposta e gli hit o miss della cache. La tua chiave API non finisce mai nei log.
• Igiene della chiave. Imposta un tetto di utilizzo, evita di passare la chiave come flag da riga di comando (resta nella cronologia della shell) e revocala dalla dashboard al primo sospetto di fuga.

Tutto qui: adesso il tuo agente può fare ricerca sul serio invece di ricordare con troppa sicurezza. Se sei ancora all’inizio del tuo percorso con OpenClaw, la nostra guida su come usare OpenClaw trasforma un’installazione fresca in un assistente quotidiano in una settimana, e se non hai ancora chiaro cosa sia OpenClaw, parti da qui.