Recherche web

L’outil web_search recherche sur le web avec le fournisseur que vous avez configuré et renvoie des résultats. Les résultats sont mis en cache par requête pendant 15 minutes (configurable).

OpenClaw inclut aussi x_search pour les publications X (anciennement Twitter) et web_fetch pour une récupération légère d’URL. Dans cette phase, 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 propre au fournisseur dans le Plugin OpenAI groupé, qui s’applique uniquement 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

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

• Configurez-la sous tools.web.search.openaiCodex
• Elle s’active uniquement pour les modèles compatibles Codex (openai-codex/* ou les fournisseurs utilisant api: "openai-codex-responses")
• 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 web_search géré normal.

# Sécurité réseau

Les appels aux fournisseurs web_search gérés utilisent le chemin de récupération protégé d’OpenClaw. Pour les hôtes d’API de fournisseurs fiables, 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 fournisseur. Les autres destinations privées, local loopback, link-local et de métadonnées restent bloquées.

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

# Configurer la recherche web

Les listes de fournisseurs dans la documentation et les flux de configuration sont alphabétiques. La détection automatique 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_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)

Solutions de repli sans clé ensuite :

10. DuckDuckGo -- solution de 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 joignable et connecté avec ollama signin ; peut réutiliser l’authentification bearer du fournisseur Ollama lorsque l’hôte l’exige, et peut appeler la recherche directe https://ollama.com lorsqu’elle est configurée 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é, OpenClaw se rabat sur Brave (vous recevrez une erreur de clé manquante vous invitant à en configurer une).

# Configuration

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

La configuration propre à chaque fournisseur (clés 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.

tools.web.search.provider est validé par rapport aux identifiants de fournisseurs de recherche web déclarés par les manifestes des plugins groupés et installés, ainsi qu’aux plugins fournisseurs installables connus. Une faute de frappe comme "brvae" fait échouer la validation de la configuration au lieu de revenir silencieusement à la détection automatique. Si le fournisseur configuré est connu mais que le plugin propriétaire est indisponible, OpenClaw conserve un démarrage robuste et signale un avertissement afin que vous puissiez exécuter openclaw doctor --fix pour installer ou activer le plugin. Le même comportement d’avertissement s’applique aux preuves de plugin obsolètes, par exemple un bloc plugins.entries.<plugin> restant après la désinstallation d’un plugin tiers.

La sélection du fournisseur 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 fournisseur web-fetch prêt à partir des identifiants disponibles
• web_fetch hors bac à sable peut utiliser des fournisseurs de plugins installés qui déclarent contracts.webFetchProviders; les récupérations en bac à sable restent limitées aux fournisseurs groupés
• aujourd’hui, le fournisseur web-fetch groupé est Firecrawl, configuré sous plugins.entries.firecrawl.config.webFetch.*

Quand 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 la même solution de repli XAI_API_KEY que la recherche web Grok. L’ancienne configuration tools.web.x_search.* est migrée automatiquement par openclaw doctor --fix. Quand vous choisissez Grok pendant openclaw onboard ou openclaw configure --section web, OpenClaw peut aussi proposer une configuration facultative de x_search avec la même clé. Il s’agit d’une étape de suivi distincte dans le parcours Grok, et non d’un choix distinct de fournisseur de recherche web de premier niveau. Si vous choisissez un autre fournisseur, OpenClaw n’affiche pas l’invite x_search.

# Stocker les clés 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

x_search interroge les publications X (anciennement Twitter) avec xAI et retourne des réponses synthétisées par IA avec citations. Il accepte les requêtes en langage naturel et des filtres structurés facultatifs. OpenClaw active l’outil intégré x_search de xAI uniquement 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 XAI_API_KEY is set
            baseUrl: "https://api.x.ai/v1", // optional shared xAI Responses base URL
          },
        },
      },
    },
  },
}

x_search envoie les publications à <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 public xAI.

# 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 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)
  },
}

# Connexe

• Web Fetch -- récupérer une URL et extraire le contenu lisible
• Navigateur web -- automatisation complète du navigateur pour les sites fortement basés sur JS
• Recherche Grok -- Grok comme fournisseur web_search
• Recherche web Ollama -- recherche web sans clé via votre hôte Ollama