web_search cerca sul web con il provider configurato e restituisce
risultati normalizzati, memorizzati nella cache per query per 15 minuti (configurabile). OpenClaw
include anche x_search per i post su X (precedentemente Twitter) e web_fetch per il
recupero leggero di URL. web_fetch viene sempre eseguito localmente; web_search viene instradato
tramite xAI Responses quando Grok è il provider, mentre x_search usa sempre
xAI Responses.
web_search è uno strumento HTTP leggero, non un sistema di automazione del browser. Per
siti che fanno ampio uso di JS o richiedono l’accesso, usa il browser web. Per
recuperare un URL specifico, usa Web Fetch.Avvio rapido
1
Scegli un provider
Scegli un provider e completa l’eventuale configurazione richiesta. Alcuni provider
non richiedono chiavi, mentre altri necessitano di una chiave API. Consulta le pagine dei provider riportate di seguito per
i dettagli.
2
Configura
BRAVE_API_KEY) e saltare questo passaggio.3
Usalo
Scelta di un provider
Brave Search
Risultati strutturati con estratti. Supporta la modalità
llm-context e i filtri per paese e lingua. È disponibile un piano gratuito.Codex Hosted Search
Risposte sintetizzate dall’IA e basate su fonti tramite il tuo account del server dell’app Codex.
DuckDuckGo
Provider senza chiave. Non è necessaria alcuna chiave API. Integrazione non ufficiale basata su HTML.
Exa
Ricerca neurale e per parole chiave con estrazione dei contenuti (parti evidenziate, testo e riepiloghi).
Firecrawl
Risultati strutturati. Offre i risultati migliori in abbinamento a
firecrawl_search e firecrawl_scrape per un’estrazione approfondita.Gemini
Risposte sintetizzate dall’IA con citazioni tramite l’ancoraggio a Google Search.
Grok
Risposte sintetizzate dall’IA con citazioni tramite l’ancoraggio web di xAI.
Kimi
Risposte sintetizzate dall’IA con citazioni tramite la ricerca web di Moonshot; i fallback alla chat non ancorata generano esplicitamente un errore.
MiniMax Search
Risultati strutturati tramite l’API di ricerca del piano MiniMax Token.
Ollama Web Search
Ricerca tramite un host Ollama locale con accesso effettuato oppure tramite l’API Ollama ospitata.
Parallel
API Parallel Search a pagamento (
PARALLEL_API_KEY); limiti di frequenza più elevati e ottimizzazione degli obiettivi.Parallel Search (Free)
Opzione senza chiave da attivare esplicitamente. Search MCP gratuito di Parallel, con estratti densi ottimizzati per gli LLM e senza chiave API.
Perplexity
Risultati strutturati con controlli per l’estrazione dei contenuti e filtri per dominio.
SearXNG
Metamotore di ricerca ospitato autonomamente. Non è necessaria alcuna chiave API. Aggrega Google, Bing, DuckDuckGo e altri servizi.
Tavily
Risultati strutturati con profondità di ricerca, filtri per argomento e
tavily_extract per l’estrazione dagli URL.Confronto tra provider
Rilevamento automatico
Gli elenchi dei provider nella documentazione e nei flussi di configurazione sono in ordine alfabetico. Il rilevamento automatico usa un ordine di precedenza separato e fisso e seleziona un provider che richiede una credenziale (requiresCredential !== false) solo quando ne trova uno configurato. Se
non è impostato alcun provider, OpenClaw controlla i provider nell’ordine seguente e usa il
primo pronto:
Prima i provider basati su API:
- Brave —
BRAVE_API_KEYoplugins.entries.brave.config.webSearch.apiKey(ordine 10) - MiniMax Search —
MINIMAX_CODE_PLAN_KEY/MINIMAX_CODING_API_KEY/MINIMAX_OAUTH_TOKEN/MINIMAX_API_KEYoplugins.entries.minimax.config.webSearch.apiKey(ordine 15) - Gemini —
plugins.entries.google.config.webSearch.apiKey,GEMINI_API_KEYomodels.providers.google.apiKey(ordine 20) - Grok — OAuth xAI,
XAI_API_KEYoplugins.entries.xai.config.webSearch.apiKey(ordine 30) - Kimi —
KIMI_API_KEY/MOONSHOT_API_KEYoplugins.entries.moonshot.config.webSearch.apiKey(ordine 40) - Perplexity —
PERPLEXITY_API_KEY/OPENROUTER_API_KEYoplugins.entries.perplexity.config.webSearch.apiKey(ordine 50) - Firecrawl —
FIRECRAWL_API_KEYoplugins.entries.firecrawl.config.webSearch.apiKey(ordine 60) - Exa —
EXA_API_KEYoplugins.entries.exa.config.webSearch.apiKey; il valore facoltativoplugins.entries.exa.config.webSearch.baseUrlsostituisce l’endpoint Exa (ordine 65) - Tavily —
TAVILY_API_KEYoplugins.entries.tavily.config.webSearch.apiKey(ordine 70) - Parallel — API Parallel Search a pagamento tramite
PARALLEL_API_KEYoplugins.entries.parallel.config.webSearch.apiKey; il valore facoltativoplugins.entries.parallel.config.webSearch.baseUrlsostituisce l’endpoint (ordine 75)
- SearXNG —
SEARXNG_BASE_URLoplugins.entries.searxng.config.webSearch.baseUrl(ordine 200)
tools.web.search.provider o tramite
openclaw configure --section web. OpenClaw non invia le query gestite di
web_search a un provider senza chiave solo perché non è configurato alcun provider
basato su API.
I modelli OpenAI Responses costituiscono un’eccezione: quando tools.web.search.provider
non è impostato, usano la ricerca web nativa di OpenAI anziché i provider gestiti
sopra elencati (vedi sotto). Imposta tools.web.search.provider su
parallel-free (o su un altro provider) per instradarli invece attraverso il percorso gestito.
Tutti i campi delle chiavi dei provider supportano oggetti SecretRef. I SecretRef con ambito Plugin
in
plugins.entries.<plugin>.config.webSearch.apiKey vengono risolti per i
provider di ricerca web basati su API installati, tra cui Brave, Exa, Firecrawl,
Gemini, Grok, Kimi, MiniMax, Parallel, Perplexity e Tavily,
sia quando il provider viene scelto esplicitamente tramite tools.web.search.provider, sia
quando viene selezionato mediante il rilevamento automatico. In modalità di rilevamento automatico, OpenClaw risolve solo la
chiave del provider selezionato: i SecretRef non selezionati rimangono inattivi, quindi puoi
mantenere configurati più provider senza sostenere il costo di risoluzione per quelli
che non utilizzi.Ricerca web nativa di OpenAI
I modelli OpenAI Responses diretti (api: "openai-responses", provider openai,
senza URL di base oppure con un URL di base ufficiale dell’API OpenAI) usano
automaticamente lo strumento web_search ospitato da OpenAI quando la ricerca
web di OpenClaw è abilitata e non è stato selezionato esplicitamente alcun
provider gestito. Questo comportamento appartiene al provider nel plugin
OpenAI incluso e non si applica agli URL di base di proxy compatibili con
OpenAI né alle route Azure. Imposta tools.web.search.provider su un altro
provider, come brave, per mantenere lo strumento web_search gestito per i
modelli OpenAI, oppure imposta tools.web.search.enabled: false per
disabilitare sia la ricerca gestita sia quella nativa di OpenAI.
Ricerca web nativa di Codex
Il runtime app-server di Codex usa automaticamente lo strumentoweb_search
ospitato da Codex quando la ricerca web è abilitata e non è selezionato alcun
provider gestito. La ricerca nativa ospitata e lo strumento dinamico
web_search gestito da OpenClaw si escludono a vicenda, quindi la ricerca
gestita non può aggirare le restrizioni sui domini della ricerca nativa.
OpenClaw usa lo strumento gestito quando la ricerca ospitata non è disponibile,
è disabilitata esplicitamente oppure viene sostituita da un provider gestito
selezionato. OpenClaw mantiene disabilitata l’estensione autonoma web.run di
Codex (features.standalone_web_search: false) perché il traffico app-server
di produzione rifiuta il namespace web definito dall’utente.
- Configura la ricerca nativa in
tools.web.search.openaiCodex - Imposta
tools.web.search.provider: "codex"per predisporre Codex Hosted Search come providerweb_searchgestito per qualsiasi modello padre. Ogni chiamata esegue un turno effimero e limitato dell’app-server di Codex e non riesce se Codex non emette un elementowebSearchospitato. mode: "cached"è la preferenza predefinita, ma Codex la risolve in accesso esterno in tempo reale per i turni app-server senza restrizioni; imposta"live"per richiedere esplicitamente l’accesso in tempo reale- Imposta
tools.web.search.providersu un provider gestito, comebrave, per usare inveceweb_searchgestito da OpenClaw - Imposta
tools.web.search.openaiCodex.enabled: falseper rinunciare alla ricerca ospitata da Codex; gli altri provider gestiti rimangono disponibili - Limitando la superficie degli strumenti nativi di Codex, anche
web_searchgestito rimane disponibile - Quando è impostato
allowedDomains, il fallback gestito automatico si interrompe in modo sicuro se la ricerca ospitata non è disponibile, in modo che l’elenco di domini consentiti nativo non possa essere aggirato - Le esecuzioni basate soltanto sull’LLM con gli strumenti disabilitati disabilitano sia la ricerca nativa sia quella gestita
tools.web.search.enabled: falsedisabilita sia la ricerca gestita sia quella nativa
web_search ospitato da OpenAI. Questo percorso separato rimane facoltativo
tramite tools.web.search.openaiCodex.enabled: true e si applica soltanto ai
modelli openai/* idonei che usano api: "openai-chatgpt-responses".
web_search gestito tramite il namespace dinamico
degli strumenti di OpenClaw. Usa un provider gestito esplicito quando ti
servono i controlli di rete specifici del provider di OpenClaw anziché la
ricerca ospitata da Codex.
La selezione di provider: "codex" abilita il plugin codex incluso e usa le
stesse restrizioni tools.web.search.openaiCodex mostrate sopra. Autentica
prima l’app-server di Codex con openclaw models auth login --provider openai.
L’agente padre può usare qualsiasi modello o runtime; soltanto il worker di
ricerca limitato viene eseguito tramite Codex.
Sicurezza della rete
Le chiamate HTTP dei providerweb_search gestiti usano il percorso di
recupero protetto di OpenClaw, limitato al nome host del provider corrente.
Soltanto per tale nome host, OpenClaw consente le risposte DNS fake-IP di
Surge, Clash e sing-box negli intervalli 198.18.0.0/15 e fc00::/7. Le altre
destinazioni private, local loopback, link-local e di metadati rimangono
bloccate. Codex Hosted Search costituisce l’eccezione: il suo worker limitato
delega l’accesso alla rete allo strumento web_search ospitato dall’app-server
di Codex.
Questa autorizzazione automatica non si applica agli URL web_fetch arbitrari.
Per web_fetch, abilita esplicitamente
tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange e
tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange soltanto quando il tuo
proxy attendibile gestisce tali intervalli sintetici.
Configurazione
plugins.entries.<plugin>.config.webSearch.*. Gemini può inoltre
riutilizzare models.providers.google.apiKey e
models.providers.google.baseUrl come fallback con priorità inferiore, dopo
la propria configurazione dedicata alla ricerca web e GEMINI_API_KEY. Per
alcuni esempi, consulta le pagine dei provider.
Grok può inoltre riutilizzare un profilo di autenticazione OAuth xAI ottenuto
con openclaw models auth login --provider xai --method oauth; la
configurazione tramite chiave API rimane il fallback.
tools.web.search.provider viene convalidato rispetto agli ID dei provider di
ricerca web dichiarati dai manifest dei plugin inclusi e installati. Un errore
di battitura come "brvae" causa il fallimento della convalida della
configurazione anziché ricorrere silenziosamente al rilevamento automatico. Se
per un provider configurato rimangono soltanto dati obsoleti del plugin, come
un blocco plugins.entries.<plugin> residuo dopo la disinstallazione di un
plugin di terze parti, OpenClaw mantiene resiliente l’avvio e segnala un
avviso, così puoi reinstallare il plugin oppure eseguire
openclaw doctor --fix per ripulire la configurazione obsoleta.
La selezione del provider di fallback per web_fetch è separata:
- sceglilo con
tools.web.fetch.provider - oppure ometti questo campo e lascia che OpenClaw rilevi automaticamente il primo provider di recupero web pronto in base alle credenziali configurate
web_fetchsenza sandbox può usare i provider dei plugin installati che dichiaranocontracts.webFetchProviders; i recuperi nella sandbox consentono i provider inclusi e le installazioni verificate dei plugin ufficiali, ma escludono i plugin esterni di terze parti- il plugin ufficiale Firecrawl è attualmente l’unico contributore
webFetchProvidersincluso ed è configurato inplugins.entries.firecrawl.config.webFetch.*
openclaw onboard o
openclaw configure --section web, OpenClaw può anche richiedere:
- la regione dell’API Moonshot (
https://api.moonshot.ai/v1oppurehttps://api.moonshot.cn/v1) - il modello predefinito di ricerca web di Kimi (il valore predefinito è
kimi-k2.6)
x_search, configura plugins.entries.xai.config.xSearch.*. Usa lo stesso
profilo di autenticazione xAI della chat oppure la credenziale
XAI_API_KEY/di ricerca web del plugin usata dalla ricerca web di Grok.
La configurazione precedente tools.web.x_search.* viene migrata
automaticamente da openclaw doctor --fix.
Quando scegli Grok durante openclaw onboard o
openclaw configure --section web, OpenClaw offre anche la configurazione
facoltativa di x_search con la stessa credenziale, subito dopo il
completamento della configurazione di Grok. Si tratta di un passaggio
successivo separato all’interno del percorso di Grok, non di una scelta
separata del provider di ricerca web di primo livello. Se scegli un altro
provider, OpenClaw non mostra la richiesta relativa a x_search.
Archiviazione delle chiavi API
- File di configurazione
- Variabile di ambiente
Esegui
openclaw configure --section web oppure imposta direttamente la chiave:Parametri dello strumento
x_search
x_search interroga i post su X (precedentemente Twitter) tramite xAI e
restituisce risposte sintetizzate dall’IA con citazioni. Accetta query in
linguaggio naturale e filtri strutturati facoltativi. OpenClaw costruisce lo
strumento x_search integrato di xAI per ogni richiesta, invece di mantenerlo
registrato in modo permanente, quindi è attivo soltanto durante il turno che
lo invoca effettivamente.
La documentazione di xAI indica che
x_search supporta la ricerca per parole
chiave, la ricerca semantica, la ricerca di utenti e il recupero dei thread.
Per le statistiche di interazione dei singoli post, come ripubblicazioni,
risposte, segnalibri o visualizzazioni, preferisci una ricerca mirata
dell’URL esatto del post o dell’ID di stato. Le ricerche generiche per parole
chiave possono individuare il post corretto, ma restituire metadati meno
completi per il singolo post. Un buon approccio consiste nell’individuare
prima il post e poi eseguire una seconda query x_search incentrata su quel
post specifico.Configurazione di x_search
Seenabled viene omesso, x_search viene esposto solo quando il provider del
modello attivo è xai e le credenziali xAI vengono risolte. Per un modello attivo
con un provider noto diverso da xAI, imposta plugins.entries.xai.config.xSearch.enabled
su true per abilitare esplicitamente l’uso tra provider diversi. Se il provider
del modello attivo è mancante o non risolto, lo strumento rimane nascosto. Imposta
enabled su false per disabilitarlo per tutti i provider. Le credenziali xAI
sono sempre obbligatorie.
x_search invia una richiesta POST a <baseUrl>/responses quando è impostato
plugins.entries.xai.config.xSearch.baseUrl. Se questo campo viene omesso,
utilizza come ripiego plugins.entries.xai.config.webSearch.baseUrl, quindi il
valore precedente tools.web.search.grok.baseUrl e infine l’endpoint pubblico
di xAI (https://api.x.ai/v1).
Parametri di x_search
allowed_x_handles ed excluded_x_handles si escludono a vicenda.
Esempio di x_search
Esempi
Profili degli strumenti
Se utilizzi profili degli strumenti o elenchi di elementi consentiti, aggiungiweb_search, x_search o group:web:
Contenuti correlati
- Recupero web — recupera un URL e ne estrae il contenuto leggibile
- Browser web — automazione completa del browser per siti che fanno ampio uso di JS
- Ricerca Grok — Grok come provider di
web_search - Ricerca web Ollama — ricerca web senza chiave tramite il tuo host Ollama