Ricerca sul web

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.

Avvio rapido

openclaw configure --section web

await web_search({ query: "OpenClaw plugin SDK" });

await x_search({ query: "dinner recipes" });

Scelta di un provider

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:

1. Brave -- BRAVE_API_KEY o plugins.entries.brave.config.webSearch.apiKey (ordine 10)
2. MiniMax Search -- MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY / MINIMAX_OAUTH_TOKEN / MINIMAX_API_KEY o plugins.entries.minimax.config.webSearch.apiKey (ordine 15)
3. Gemini -- plugins.entries.google.config.webSearch.apiKey, GEMINI_API_KEY o models.providers.google.apiKey (ordine 20)
4. Grok -- OAuth xAI, XAI_API_KEY o plugins.entries.xai.config.webSearch.apiKey (ordine 30)
5. Kimi -- KIMI_API_KEY / MOONSHOT_API_KEY o plugins.entries.moonshot.config.webSearch.apiKey (ordine 40)
6. Perplexity -- PERPLEXITY_API_KEY / OPENROUTER_API_KEY o plugins.entries.perplexity.config.webSearch.apiKey (ordine 50)
7. Firecrawl -- FIRECRAWL_API_KEY o plugins.entries.firecrawl.config.webSearch.apiKey (ordine 60)
8. Exa -- EXA_API_KEY o plugins.entries.exa.config.webSearch.apiKey; il valore facoltativo plugins.entries.exa.config.webSearch.baseUrl sostituisce l'endpoint Exa (ordine 65)
9. Tavily -- TAVILY_API_KEY o plugins.entries.tavily.config.webSearch.apiKey (ordine 70)
10. Parallel -- API Parallel Search a pagamento tramite PARALLEL_API_KEY o plugins.entries.parallel.config.webSearch.apiKey; il valore facoltativo plugins.entries.parallel.config.webSearch.baseUrl sostituisce l'endpoint (ordine 75)

Successivamente, i provider con endpoint configurato:

11. SearXNG -- SEARXNG_BASE_URL o plugins.entries.searxng.config.webSearch.baseUrl (ordine 200)

I provider senza chiave, come Parallel Search (Free), DuckDuckGo, Ollama Web Search e Codex Hosted Search, non prevalgono mai nel rilevamento automatico, anche se dispongono di un valore di ordinamento interno. Vengono usati solo quando li selezioni esplicitamente con 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.

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 strumento web_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 provider web_search gestito 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 elemento webSearch ospitato.
• 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.provider su un provider gestito, come brave, per usare invece web_search gestito da OpenClaw
• Imposta tools.web.search.openaiCodex.enabled: false per rinunciare alla ricerca ospitata da Codex; gli altri provider gestiti rimangono disponibili
• Limitando la superficie degli strumenti nativi di Codex, anche web_search gestito 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: false disabilita sia la ricerca gestita sia quella nativa

Le modifiche persistenti ai criteri di ricerca effettivi di Codex avviano un nuovo thread associato, affinché un thread app-server già caricato non possa mantenere un accesso obsoleto alla ricerca ospitata. Le restrizioni transitorie per singolo turno usano un thread temporaneo con restrizioni e conservano l'associazione esistente per la successiva ripresa.

Anche il traffico OpenAI ChatGPT Responses diretto può usare lo strumento 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".

{  tools: {    web: {      search: {        enabled: true,        // Optional: use Codex Hosted Search from non-Codex parent models too.        provider: "codex",        openaiCodex: {          enabled: true,          mode: "cached",          allowedDomains: ["example.com"],          contextSize: "high",          userLocation: {            country: "US",            city: "New York",            timezone: "America/New_York",          },        },      },    },  },}

Per i runtime e i provider che non supportano la ricerca nativa di Codex, Codex può usare il fallback 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 provider web_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

{  tools: {    web: {      search: {        enabled: true, // default: true        provider: "brave", // or omit for auto-detection        maxResults: 5,        timeoutSeconds: 30,        cacheTtlMinutes: 15,      },    },  },}

La configurazione specifica del provider (chiavi API, URL di base, modalità) si trova in 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_fetch senza sandbox può usare i provider dei plugin installati che dichiarano contracts.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 webFetchProviders incluso ed è configurato in plugins.entries.firecrawl.config.webFetch.*

Quando scegli Kimi durante openclaw onboard o openclaw configure --section web, OpenClaw può anche richiedere:

• la regione dell'API Moonshot (https://api.moonshot.ai/v1 oppure https://api.moonshot.cn/v1)
• il modello predefinito di ricerca web di Kimi (il valore predefinito è kimi-k2.6)

Per 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

{  plugins: {    entries: {      brave: {        config: {          webSearch: {            apiKey: "YOUR_KEY", // pragma: allowlist secret          },        },      },    },  },}

export BRAVE_API_KEY="YOUR_KEY"

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.

Configurazione di x_search

Se enabled 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.

{  plugins: {    entries: {      xai: {        config: {          xSearch: {            enabled: true, // obbligatorio per un provider di modelli noto diverso da xAI            model: "grok-4.3",            baseUrl: "https://api.x.ai/v1", // facoltativo, sostituisce webSearch.baseUrl            inlineCitations: false,            maxTurns: 2,            timeoutSeconds: 30,            cacheTtlMinutes: 15,          },          webSearch: {            apiKey: "xai-...", // facoltativo se è configurato un profilo di autenticazione xAI o XAI_API_KEY            baseUrl: "https://api.x.ai/v1", // URL di base condiviso facoltativo per xAI Responses          },        },      },    },  },}

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

await x_search({  query: "dinner recipes",  allowed_x_handles: ["nytfood"],  from_date: "2026-03-01",});

// Statistiche per post: quando possibile, usa l'URL esatto dello stato o il relativo IDawait x_search({  query: "https://x.com/huntharo/status/1905678901234567890",});

Esempi

// Ricerca di baseawait web_search({ query: "OpenClaw plugin SDK" }); // Ricerca specifica per la Germaniaawait web_search({ query: "TV online schauen", country: "DE", language: "de" }); // Risultati recenti (ultima settimana)await web_search({ query: "AI developments", freshness: "week" }); // Intervallo di dateawait web_search({  query: "climate research",  date_after: "2024-01-01",  date_before: "2024-06-30",}); // Filtro per dominio (solo Perplexity)await web_search({  query: "product reviews",  domain_filter: ["-reddit.com", "-pinterest.com"],});

Profili degli strumenti

Se utilizzi profili degli strumenti o elenchi di elementi consentiti, aggiungi web_search, x_search o group:web:

{  tools: {    allow: ["web_search", "x_search"],    // oppure: allow: ["group:web"]  (include web_search, x_search e web_fetch)  },}

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