Recherche web

L’outil web_search recherche sur le web en utilisant votre provider configuré et renvoie les résultats. Les résultats sont mis en cache par requête pendant 15 minutes (configurable).

OpenClaw inclut également x_search pour les posts X (anciennement Twitter) et web_fetch pour la récupération d’URL légère. À ce stade, web_fetch reste local tandis que web_search et x_search peuvent utiliser xAI Responses en arrière-plan.

Info

web_search

est un outil HTTP léger, et non une automatisation de navigateur. Pour les sites utilisant beaucoup de JS ou les connexions, utilisez le

Navigateur Web

. Pour récupérer une URL spécifique, utilisez

Récupération Web

.

Quick start

1. Choisir un provider

   Choisissez un provider et complétez la configuration requise. Certains providers sont sans clé, tandis que d’autres utilisent des clés API. Consultez les pages de providers ci-dessous pour plus de détails.

2. Configurer

   openclaw configure --section web

   Cela stocke le provider et les informations d’identification nécessaires. Vous pouvez également définir une var d’env (par exemple BRAVE_API_KEY) et ignorer cette étape pour les providers basés sur API.

3. Utiliser

   L’agent peut maintenant appeler web_search :

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

   Pour les posts X, utilisez :

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

Choosing a provider

Recherche Brave

Résultats structurés avec extraits. Prend en charge le mode llm-context, les filtres de pays/langue. Offre gratuite disponible.

DuckDuckGo

Solution de repli sans clé. Aucune clé API nécessaire. Intégration HTML non officielle.

Exa

Recherche neuronale + par mots-clés avec extraction de contenu (surlignages, texte, résumés).

Firecrawl

Résultats structurés. Fonctionne mieux avec firecrawl_search et firecrawl_scrape pour une extraction approfondie.

Gemini

Réponses synthétisées par l’IA avec citations via le grounding Google Search.

Grok

Réponses synthétisées par l’IA avec citations via le grounding web xAI.

Kimi

Réponses synthétisées par l’IA avec citations via la recherche web Moonshot ; les replis de chat non fondés échouent explicitement.

MiniMax Search

Résultats structurés via l’API de recherche Token Plan MiniMaxAPI.

Ollama Web Search

Recherche via un hôte local Ollama connecté ou l’API Ollama hébergée.

Perplexity

Résultats structurés avec des contrôles d’extraction de contenu et un filtrage de domaine.

SearXNG

Métamoteur auto-hébergé. Aucune clé API nécessaire. Agrège Google, Bing, DuckDuckGo, et plus encore.

Tavily

Résultats structurés avec profondeur de recherche, filtrage par sujet et tavily_extract pour l’extraction d’URL.

Comparaison des fournisseurs

Fournisseur	Style de résultat	Filtres	Clé API
Brave	Extraits structurés	Pays, langue, heure, mode llm-context	BRAVE_API_KEY
DuckDuckGo	Extraits structurés	—	Aucune (sans clé)
Exa	Structuré + extrait	Mode neuronal/par mots-clés, date, extraction de contenu	EXA_API_KEY
Firecrawl	Extraits structurés	Via l’outil firecrawl_search	FIRECRAWL_API_KEY
Gemini	Synthétisé par IA + citations	—	GEMINI_API_KEY
Grok	Synthétisé par IA + citations	—	XAI_API_KEY
Kimi	Synthétisé par l’IA + citations ; échoue sur les replis de chat non fondés	—	KIMI_API_KEY / MOONSHOT_API_KEY
MiniMax Search	Extraits structurés	Région (global / cn)	MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY / MINIMAX_OAUTH_TOKEN
Ollama Web Search	Extraits structurés	—	Aucun pour les hôtes locaux connectés ; OLLAMA_API_KEY pour la recherche https://ollama.com directe
Perplexity	Extraits structurés	Pays, langue, heure, domaines, limites de contenu	PERPLEXITY_API_KEY / OPENROUTER_API_KEY
SearXNG	Extraits structurés	Catégories, langue	Aucun (auto-hébergé)
Tavily	Extraits structurés	Via l’outil tavily_search	TAVILY_API_KEY

Détection automatique

Recherche web native OpenAI

Les modèles de réponses Direct OpenAI utilisent automatiquement l’outil OpenAIOpenAIweb_searchOpenClawOpenAIOpenAIAPIOpenAI hébergé par OpenAI lorsque la recherche web OpenClaw est activée et qu’aucun provider géré n’est épinglé. Il s’agit d’un comportement propre au provider dans le plugin OpenAI inclus et cela s’applique uniquement au trafic de l’API OpenAI native, et non aux URL de base de proxy compatibles OpenAI ou aux routes Azure. Définissez tools.web.search.provider sur un autre provider tel que brave pour conserver l’outil web_searchOpenAI géré pour les modèles OpenAI, ou définissez tools.web.search.enabled: falseOpenAI pour désactiver à la fois la recherche gérée et la recherche native OpenAI.

Recherche web native Codex

Les modèles compatibles Codex peuvent facultativement utiliser l’outil web_searchOpenClaw Responses natif du provider au lieu de la fonction web_search gérée par OpenClaw.

• Configurez-le sous tools.web.search.openaiCodex
• Il ne s’active que pour les modèles compatibles Codex (openai-codex/* ou providers utilisant api: "openai-codex-responses")
• Le web_search géré s’applique toujours aux modèles non-Codex
• mode: "cached" est le paramètre par défaut et recommandé
• tools.web.search.enabled: false désactive à la fois la recherche gérée et la recherche native

{
  tools: {
    web: {
      search: {
        enabled: true,
        openaiCodex: {
          enabled: true,
          mode: "cached",
          allowedDomains: ["example.com"],
          contextSize: "high",
          userLocation: {
            country: "US",
            city: "New York",
            timezone: "America/New_York",
          },
        },
      },
    },
  },
}

Si la recherche Codex native est activée mais que le modèle actuel n’est pas compatible Codex, OpenClaw conserve le comportement normal de l’outil OpenClawweb_search géré.

Sécurité réseau

Les appels au provider web_searchOpenClawAPIOpenClaw géré utilisent le chemin d’extraction protégé d’OpenClaw. Pour les hôtes d’API de provider de confiance, OpenClaw autorise les réponses DNS fake-IP de Surge, Clash et sing-box dans 198.18.0.0/15 et fc00::/7 uniquement pour ce nom d’hôte de provider. Les autres destinations privées, de bouclage (loopback), de lien local et de métadonnées restent bloquées.

Cet autorisation automatique ne s’applique pas aux URL web_fetch arbitraires. Pour web_fetch, activez tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange et tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange explicitement uniquement lorsque votre proxy de confiance possède ces plages synthétiques.

Configuration de la recherche web

Les listes de fournisseurs dans la documentation et les flux de configuration sont par ordre alphabétique. La détection automatique conserve un ordre de priorité distinct.

Si aucun provider n’est défini, OpenClaw vérifie les fournisseurs dans cet ordre et utilise le premier qui est prêt :

Fournisseurs pris en charge par une API d’abord :

1. Brave — BRAVE_API_KEY ou plugins.entries.brave.config.webSearch.apiKey (ordre 10)
2. Recherche MiniMax — MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY / MINIMAX_OAUTH_TOKEN / MINIMAX_API_KEY ou plugins.entries.minimax.config.webSearch.apiKey (ordre 15)
3. Gemini — plugins.entries.google.config.webSearch.apiKey, GEMINI_API_KEY ou models.providers.google.apiKey (ordre 20)
4. Grok — XAI_API_KEY ou plugins.entries.xai.config.webSearch.apiKey (ordre 30)
5. Kimi — KIMI_API_KEY / MOONSHOT_API_KEY ou plugins.entries.moonshot.config.webSearch.apiKey (ordre 40)
6. Perplexity — PERPLEXITY_API_KEY / OPENROUTER_API_KEY ou plugins.entries.perplexity.config.webSearch.apiKey (ordre 50)
7. Firecrawl — FIRECRAWL_API_KEY ou plugins.entries.firecrawl.config.webSearch.apiKey (ordre 60)
8. Exa — EXA_API_KEY ou plugins.entries.exa.config.webSearch.apiKey ; plugins.entries.exa.config.webSearch.baseUrl facultatif remplace le point de terminaison Exa (ordre 65)
9. Tavily — TAVILY_API_KEY ou plugins.entries.tavily.config.webSearch.apiKey (ordre 70)

Replis sans clé ensuite :

10. DuckDuckGo — repli HTML sans clé sans compte ni clé API (ordre 100)
11. Ollama Web Search — solution de repli sans clé via votre hôte Ollama local configuré lorsqu’il est accessible et connecté avec ollama signin ; peut réutiliser l’authentification bearer du fournisseur Ollama lorsque l’hôte en a besoin, et peut appeler directement la recherche https://ollama.com lorsqu’il est configuré avec OLLAMA_API_KEY (ordre 110)
12. SearXNG — SEARXNG_BASE_URL ou plugins.entries.searxng.config.webSearch.baseUrl (ordre 200)

Si aucun fournisseur n’est détecté, il revient à Brave (vous obtiendrez une erreur de clé manquante vous invitant à en configurer un).

Note

Tous les champs de clé de fournisseur prennent en charge les objets SecretRef. Les SecretRefs limités au plugin sous `plugins.entries.

.config.webSearch.apiKeysont résolus pour les fournisseurs de recherche web intégrés prenant en charge l'API, notamment Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax, Perplexity et Tavily, que le fournisseur soit choisi explicitement viatools.web.search.provider` ou sélectionné par détection automatique. En mode de détection automatique, OpenClaw résout uniquement la clé du fournisseur sélectionné — les SecretRefs non sélectionnés restent inactifs, vous pouvez donc conserver plusieurs fournisseurs configurés sans payer de coût de résolution pour ceux que vous n’utilisez pas.

Config

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

La configuration spécifique au fournisseur (clés d’API, URL de base, modes) se trouve sous plugins.entries.<plugin>.config.webSearch.*. Gemini peut également réutiliser models.providers.google.apiKey et models.providers.google.baseUrl comme solutions de repli moins prioritaires après sa configuration de recherche web dédiée et GEMINI_API_KEY. Consultez les pages des fournisseurs pour des exemples.

tools.web.search.provider est validé par rapport aux identifiants de provider de recherche web déclarés par les manifests des plugins groupés et installés. Une faute de frappe telle que "brvae" échoue à la validation de la configuration au lieu de revenir silencieusement à la détection automatique. Si un provider configuré ne possède que des preuves de plugin obsolètes, comme un bloc plugins.entries.<plugin> restant après la désinstallation d’un plugin tiers, OpenClaw maintient le démarrage résilient et signale un avertissement afin que vous puissiez réinstaller le plugin ou exécuter openclaw doctor --fix pour nettoyer la configuration obsolète.

La sélection du provider de repli web_fetch est distincte :

• choisissez-le avec tools.web.fetch.provider
• ou omettez ce champ et laissez OpenClaw détecter automatiquement le premier provider de récupération web prêt parmi les identifiants disponibles
• web_fetch non sandboxé peut utiliser les providers de plugins installés qui déclarent contracts.webFetchProviders ; les récupérations sandboxées restent limitées aux plugins groupés
• le provider de récupération web groupé est aujourd’hui Firecrawl, configuré sous plugins.entries.firecrawl.config.webFetch.*

Lorsque vous choisissez Kimi pendant openclaw onboard ou openclaw configure --section web, OpenClaw peut également demander :

• la région de l’Moonshot API (https://api.moonshot.ai/v1 ou https://api.moonshot.cn/v1)
• le model de recherche web Kimi par défaut (par défaut kimi-k2.6)

Pour x_search, configurez plugins.entries.xai.config.xSearch.*. Il utilise le même profil d’authentification xAI que le chat, ou les informations d’identification XAI_API_KEY / plugin web-search utilisées par la recherche web Grok. La configuration tools.web.x_search.* existante est automatiquement migrée par openclaw doctor --fix. Lorsque vous choisissez Grok pendant openclaw onboard ou openclaw configure --section webOpenClaw, OpenClaw peut également proposer une configuration x_searchOpenClaw optionnelle avec la même clé. Il s’agit d’une étape de suivi distincte dans le chemin Grok, et non d’un choix distinct de provider de recherche web de premier niveau. Si vous choisissez un autre provider, OpenClaw n’affiche pas l’invite x_search.

Stockage des clés API

Config fileEnvironment variable

Exécutez openclaw configure --section web ou définissez la clé directement :

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

Définissez la variable d’environnement du provider dans l’environnement de processus du Gateway :

export BRAVE_API_KEY="YOUR_KEY"

Pour une installation de gateway, placez-la dans ~/.openclaw/.env. Voir Env vars.

Paramètres de l’outil

Paramètre	Description
query	Requête de recherche (requis)
count	Résultats à renvoyer (1-10, par défaut : 5)
country	Code de pays ISO à 2 lettres (ex. « US », « DE »)
language	Code de langue ISO 639-1 (ex. « en », « de »)
search_lang	Code de langue de recherche (Brave uniquement)
freshness	Filtre temporel : day, week, month ou year
date_after	Résultats après cette date (AAAA-MM-JJ)
date_before	Résultats avant cette date (AAAA-MM-JJ)
ui_lang	Code de langue de l’interface utilisateur (Brave uniquement)
domain_filter	Tableau de liste d’autorisation/liste de refus de domaine (Perplexity uniquement)
max_tokens	Budget total du contenu, 25000 par défaut (Perplexity uniquement)
max_tokens_per_page	Limite de jetons par page, 2048 par défaut (Perplexity uniquement)

Warning

Tous les paramètres ne fonctionnent pas avec tous les fournisseurs. Le mode Bravellm-context de Brave rejette ui_lang ; date_before nécessite également date_afterBrave car les plages de fraîcheur personnalisées de Brave nécessitent les dates de début et de fin. Gemini, Grok et Kimi renvoient une réponse synthétisée avec des citations. Ils acceptent count pour la compatibilité des outils partagés, mais cela ne modifie pas la forme de la réponse ancrée. Gemini prend en charge freshness, date_after et date_beforePerplexity en les convertissant en plages de temps d’ancrage Google Search. Perplexity se comporte de la même manière lorsque vous utilisez le chemin de compatibilité Sonar/OpenRouter (plugins.entries.perplexity.config.webSearch.baseUrl / model ou OPENROUTER_API_KEY). SearXNG accepte http:// uniquement pour les hôtes de réseau privé de confiance ou de bouclage ; les points de terminaison publics SearXNG doivent utiliser https://Firecrawl. Firecrawl et Tavily prennent uniquement en charge query et count via web_search — utilisez leurs outils dédiés pour les options avancées.

x_search

x_search interroge les publications X (anciennement Twitter) à l’aide de xAI et renvoie des réponses synthétisées par l’IA avec des citations. Il accepte les requêtes en langage naturel et des filtres structurés facultatifs. OpenClaw n’active l’outil intégré xAI x_search que sur la requête qui sert cet appel d’outil.

Note

xAI documente x_search comme prenant en charge la recherche par mots-clés, la recherche sémantique, la recherche d’utilisateur et la récupération de fils. Pour les statistiques d’engagement par publication telles que les repartages, les réponses, les signets ou les vues, préférez une recherche ciblée pour l’URL exacte de la publication ou l’ID de statut. Les recherches larges par mots-clés peuvent trouver la bonne publication mais renvoient moins de métadonnées complètes par publication. Un bon modèle est : localiser d’abord la publication, puis exécuter une deuxième requête x_search axée sur cette publication exacte.

configuration x_search

{
  plugins: {
    entries: {
      xai: {
        config: {
          xSearch: {
            enabled: true,
            model: "grok-4-1-fast-non-reasoning",
            baseUrl: "https://api.x.ai/v1", // optional, overrides webSearch.baseUrl
            inlineCitations: false,
            maxTurns: 2,
            timeoutSeconds: 30,
            cacheTtlMinutes: 15,
          },
          webSearch: {
            apiKey: "xai-...", // optional if an xAI auth profile or XAI_API_KEY is set
            baseUrl: "https://api.x.ai/v1", // optional shared xAI Responses base URL
          },
        },
      },
    },
  },
}

x_search publie sur <baseUrl>/responses lorsque plugins.entries.xai.config.xSearch.baseUrl est défini. Si ce champ est omis, il revient à plugins.entries.xai.config.webSearch.baseUrl, puis à l’ancien tools.web.search.grok.baseUrl, et enfin au point de terminaison public xAI.

paramètres x_search

Paramètre	Description
query	Requête de recherche (requis)
allowed_x_handles	Limiter les résultats à des comptes X spécifiques
excluded_x_handles	Exclure des comptes X spécifiques
from_date	Inclure uniquement les publications à partir de cette date (YYYY-MM-DD)
to_date	Inclure uniquement les publications jusqu’à cette date (YYYY-MM-DD)
enable_image_understanding	Permettre à xAI d’inspecter les images jointes aux publications correspondantes
enable_video_understanding	Permettre à xAI d’inspecter les vidéos jointes aux publications correspondantes

exemple x_search

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

// Per-post stats: use the exact status URL or status ID when possible
await x_search({
  query: "https://x.com/huntharo/status/1905678901234567890",
});

Exemples

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

// German-specific search
await web_search({ query: "TV online schauen", country: "DE", language: "de" });

// Recent results (past week)
await web_search({ query: "AI developments", freshness: "week" });

// Date range
await web_search({
  query: "climate research",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

// Domain filtering (Perplexity only)
await web_search({
  query: "product reviews",
  domain_filter: ["-reddit.com", "-pinterest.com"],
});

Profils d’outils

Si vous utilisez des profils d’outils ou des listes d’autorisation, ajoutez web_search, x_search ou group:web :

{
  tools: {
    allow: ["web_search", "x_search"],
    // or: allow: ["group:web"]  (includes web_search, x_search, and web_fetch)
  },
}

Connexes

• Web Fetch — récupérer une URL et extraire le contenu lisible
• Web Browser — automatisation complète du navigateur pour les sites lourds en JS
• Grok Search — Grok en tant que provider web_search
• Ollama Web Search — recherche Web sans clé via votre hôte Ollama