Recherche Web

L’outil web_search recherche sur le Web à l’aide de votre fournisseur configuré et renvoie des résultats. Les résultats sont mis en cache par requête pendant 15 minutes (configurable).

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

Démarrage rapide

openclaw configure --section web

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

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

Choisir un fournisseur

Comparaison des fournisseurs

Détection automatique

Recherche Web OpenAI native

Les modèles OpenAI Responses directs utilisent automatiquement l’outil web_search hébergé par OpenAI lorsque la recherche Web OpenClaw est activée et qu’aucun fournisseur géré n’est épinglé. Il s’agit d’un comportement détenu par le fournisseur dans le Plugin OpenAI groupé, qui ne s’applique qu’au trafic API OpenAI natif, pas aux URL de base de proxy compatibles OpenAI ni aux routes Azure. Définissez tools.web.search.provider sur un autre fournisseur, tel que brave, pour conserver l’outil web_search géré pour les modèles OpenAI, ou définissez tools.web.search.enabled: false pour désactiver à la fois la recherche gérée et la recherche OpenAI native.

Recherche Web Codex native

Le runtime de serveur d’application Codex utilise automatiquement l’outil web_search hébergé par Codex lorsque la recherche Web est activée et qu’aucun fournisseur géré n’est sélectionné. La recherche hébergée native et l’outil dynamique web_search géré par OpenClaw s’excluent mutuellement, de sorte que la recherche gérée ne peut pas contourner les restrictions de domaine natives. OpenClaw utilise l’outil géré lorsque la recherche hébergée est indisponible, explicitement désactivée ou remplacée par un fournisseur géré sélectionné. OpenClaw garde l’extension autonome web.run de Codex désactivée, car le trafic de serveur d’application en production rejette son espace de noms web défini par l’utilisateur.

• Configurez la recherche native sous tools.web.search.openaiCodex
• Définissez tools.web.search.provider: "codex" pour provisionner Codex Hosted Search comme fournisseur web_search géré pour n’importe quel modèle parent. Chaque appel exécute un tour éphémère borné du serveur d’application Codex et échoue si Codex n’émet pas un élément webSearch hébergé.
• mode: "cached" est la préférence par défaut, mais Codex la résout en accès externe en direct pour les tours de serveur d’application sans restriction ; définissez "live" pour demander explicitement un accès en direct
• Définissez tools.web.search.provider sur un fournisseur géré tel que brave pour utiliser le web_search géré par OpenClaw à la place
• Définissez tools.web.search.openaiCodex.enabled: false pour désactiver la recherche hébergée par Codex ; les autres fournisseurs gérés restent disponibles
• Restreindre la surface d’outil native de Codex maintient également web_search géré disponible
• Lorsque allowedDomains est défini, la solution de repli gérée automatique échoue de façon fermée si la recherche hébergée est indisponible, afin que la liste d’autorisation native ne puisse pas être contournée
• Les exécutions LLM uniquement avec outils désactivés désactivent à la fois la recherche native et gérée
• tools.web.search.enabled: false désactive à la fois la recherche gérée et native

Les changements persistants de politique de recherche Codex effective démarrent un nouveau fil lié afin qu’un fil de serveur d’application déjà chargé ne puisse pas conserver un accès de recherche hébergée obsolète. Les restrictions transitoires par tour utilisent un fil restreint temporaire et préservent la liaison existante pour une reprise ultérieure.

Le trafic OpenAI ChatGPT Responses direct peut également utiliser l’outil web_search hébergé par OpenAI. Ce chemin distinct reste optionnel via tools.web.search.openaiCodex.enabled: true et ne s’applique qu’aux modèles openai/* éligibles utilisant 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",          },        },      },    },  },}

Pour les runtimes et fournisseurs qui ne prennent pas en charge la recherche Codex native, Codex peut utiliser la solution de repli web_search gérée via l’espace de noms d’outils dynamiques d’OpenClaw. Utilisez un fournisseur géré explicite lorsque vous avez besoin des contrôles réseau propres au fournisseur d’OpenClaw au lieu de la recherche hébergée par Codex.

La sélection de provider: "codex" active le plugin codex groupé et utilise les mêmes restrictions tools.web.search.openaiCodex indiquées ci-dessus. Authentifiez d'abord le serveur d'application Codex avec openclaw models auth login --provider openai. L'agent parent peut utiliser n'importe quel modèle ou runtime ; seul le worker de recherche bornée passe par Codex.

Sécurité réseau

Les appels au fournisseur HTTP géré web_search utilisent le chemin fetch protégé d'OpenClaw. Pour les hôtes d'API de fournisseurs 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 fournisseur. Les autres destinations privées, loopback, link-local et de métadonnées restent bloquées. Codex Hosted Search est l'exception : son worker borné délègue l'accès réseau à l'outil web_search hébergé du serveur d'application Codex.

Cette 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 alphabétiques. L'auto-détection conserve un ordre de priorité séparé.

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

Fournisseurs adossés à une API d'abord :

1. Brave -- BRAVE_API_KEY ou plugins.entries.brave.config.webSearch.apiKey (ordre 10)
2. MiniMax Search -- 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 OAuth, 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)
10. Parallel -- API Parallel Search payante via PARALLEL_API_KEY ou plugins.entries.parallel.config.webSearch.apiKey ; plugins.entries.parallel.config.webSearch.baseUrl facultatif remplace le point de terminaison (ordre 75)

Fournisseurs de points de terminaison configurés ensuite :

11. SearXNG -- SEARXNG_BASE_URL ou plugins.entries.searxng.config.webSearch.baseUrl (ordre 200)

Les fournisseurs sans clé tels que Parallel Search (Free), DuckDuckGo, Ollama Web Search et Codex Hosted Search ne sont disponibles que lorsque vous les sélectionnez explicitement avec tools.web.search.provider ou via openclaw configure --section web. OpenClaw n'envoie pas les requêtes web_search gérées à un fournisseur sans clé simplement parce qu'aucun fournisseur adossé à une API n'est configuré.

Les modèles OpenAI Responses font exception : tant que tools.web.search.provider n'est pas défini, ils utilisent la recherche web native d'OpenAI au lieu des fournisseurs gérés ci-dessus. Définissez tools.web.search.provider sur parallel-free (ou un autre fournisseur) pour les router via le chemin géré.

Configuration

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

La configuration propre au fournisseur (clés d'API, URL de base, modes) se trouve sous plugins.entries.<plugin>.config.webSearch.*. Gemini peut aussi réutiliser models.providers.google.apiKey et models.providers.google.baseUrl comme solutions de repli de priorité inférieure après sa configuration dédiée de recherche web et GEMINI_API_KEY. Consultez les pages des fournisseurs pour des exemples. Grok peut aussi réutiliser un profil d'authentification xAI OAuth provenant de openclaw models auth login --provider xai --method oauth ; la configuration par clé d'API reste la solution de repli.

tools.web.search.provider est validé par rapport aux identifiants de fournisseurs de recherche web déclarés par les manifestes de plugins groupés et installés. Une faute de frappe telle que "brvae" échoue à la validation de configuration au lieu de revenir silencieusement à l'auto-détection. Si un fournisseur configuré ne dispose que de preuves de plugin obsolètes, comme un bloc plugins.entries.<plugin> résiduel après la désinstallation d'un plugin tiers, OpenClaw garde 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 fournisseur de repli web_fetch est séparée :

• choisissez-le avec tools.web.fetch.provider
• ou omettez ce champ et laissez OpenClaw auto-détecter le premier fournisseur web-fetch prêt à partir des identifiants configurés
• web_fetch non sandboxé peut utiliser les fournisseurs de plugins installés qui déclarent contracts.webFetchProviders ; les fetches sandboxés autorisent les fournisseurs groupés et les installations vérifiées de plugins officiels, mais excluent les plugins externes tiers
• le plugin officiel Firecrawl fournit le repli web-fetch, configuré sous plugins.entries.firecrawl.config.webFetch.*

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

• la région de l'API Moonshot (https://api.moonshot.ai/v1 ou https://api.moonshot.cn/v1)
• le modèle 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 l'identifiant XAI_API_KEY / de recherche web de plugin utilisé par la recherche web Grok. La configuration héritée tools.web.x_search.* est migrée automatiquement par openclaw doctor --fix. Lorsque vous choisissez Grok pendant openclaw onboard ou openclaw configure --section web, OpenClaw peut aussi proposer la configuration facultative de x_search avec le même identifiant. Il s'agit d'une étape de suivi séparée dans le chemin Grok, et non d'un choix séparé de fournisseur de recherche web de premier niveau. Si vous choisissez un autre fournisseur, OpenClaw n'affiche pas l'invite x_search.

Stockage des clés d'API

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

export BRAVE_API_KEY="YOUR_KEY"

Paramètres de l'outil

x_search

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

Configuration de 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 vers <baseUrl>/responses lorsque plugins.entries.xai.config.xSearch.baseUrl est défini. Si ce champ est omis, il se replie sur plugins.entries.xai.config.webSearch.baseUrl, puis sur l'ancien tools.web.search.grok.baseUrl, et enfin sur le point de terminaison xAI public.

Paramètres de x_search

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 possibleawait x_search({  query: "https://x.com/huntharo/status/1905678901234567890",});

Exemples

// Basic searchawait web_search({ query: "OpenClaw plugin SDK" }); // German-specific searchawait web_search({ query: "TV online schauen", country: "DE", language: "de" }); // Recent results (past week)await web_search({ query: "AI developments", freshness: "week" }); // Date rangeawait 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)  },}

Associés

• Récupération Web -- récupérer une URL et extraire le contenu lisible
• Navigateur Web -- automatisation complète du navigateur pour les sites fortement dépendants de JS
• Recherche Grok -- Grok comme fournisseur de web_search
• Recherche Web Ollama -- recherche Web sans clé via votre hôte Ollama