Búsqueda web

web_search busca en la web con el proveedor configurado y devuelve resultados normalizados, almacenados en caché por consulta durante 15 minutos (configurable). OpenClaw también incluye x_search para publicaciones de X (anteriormente Twitter) y web_fetch para obtener URL de forma ligera. web_fetch siempre se ejecuta localmente; web_search se enruta mediante xAI Responses cuando Grok es el proveedor, y x_search siempre utiliza xAI Responses.

Inicio rápido

openclaw configure --section web

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

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

Elegir un proveedor

Comparación de proveedores

Detección automática

Las listas de proveedores en la documentación y los flujos de configuración están ordenadas alfabéticamente. La detección automática utiliza un orden de precedencia fijo independiente y solo elige un proveedor que necesite una credencial (requiresCredential !== false) cuando encuentra una configurada. Si no se establece ningún provider, OpenClaw comprueba los proveedores en este orden y utiliza el primero que esté listo:

Primero, los proveedores respaldados por API:

1. Brave -- BRAVE_API_KEY o plugins.entries.brave.config.webSearch.apiKey (orden 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 (orden 15)
3. Gemini -- plugins.entries.google.config.webSearch.apiKey, GEMINI_API_KEY o models.providers.google.apiKey (orden 20)
4. Grok -- OAuth de xAI, XAI_API_KEY o plugins.entries.xai.config.webSearch.apiKey (orden 30)
5. Kimi -- KIMI_API_KEY / MOONSHOT_API_KEY o plugins.entries.moonshot.config.webSearch.apiKey (orden 40)
6. Perplexity -- PERPLEXITY_API_KEY / OPENROUTER_API_KEY o plugins.entries.perplexity.config.webSearch.apiKey (orden 50)
7. Firecrawl -- FIRECRAWL_API_KEY o plugins.entries.firecrawl.config.webSearch.apiKey (orden 60)
8. Exa -- EXA_API_KEY o plugins.entries.exa.config.webSearch.apiKey; el valor opcional plugins.entries.exa.config.webSearch.baseUrl sustituye el punto de conexión de Exa (orden 65)
9. Tavily -- TAVILY_API_KEY o plugins.entries.tavily.config.webSearch.apiKey (orden 70)
10. Parallel -- API de pago de Parallel Search mediante PARALLEL_API_KEY o plugins.entries.parallel.config.webSearch.apiKey; el valor opcional plugins.entries.parallel.config.webSearch.baseUrl sustituye el punto de conexión (orden 75)

Después, los proveedores con un punto de conexión configurado:

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

Los proveedores sin clave, como Parallel Search (gratuita), DuckDuckGo, Ollama Web Search y Búsqueda alojada de Codex, nunca tienen prioridad en la detección automática, aunque dispongan de un valor de orden interno. Solo se utilizan cuando los seleccionas explícitamente mediante tools.web.search.provider o openclaw configure --section web. OpenClaw no envía consultas administradas de web_search a un proveedor sin clave solo porque no haya configurado ningún proveedor respaldado por API.

Los modelos OpenAI Responses son una excepción: mientras tools.web.search.provider no esté establecido, utilizan la búsqueda web nativa de OpenAI en lugar de los proveedores administrados anteriores (consulta la sección siguiente). Establece tools.web.search.provider en parallel-free (u otro proveedor) para enrutarlos mediante la ruta administrada.

Búsqueda web nativa de OpenAI

Los modelos directos de OpenAI Responses (api: "openai-responses", proveedor openai, sin URL base o con una URL base oficial de la API de OpenAI) usan automáticamente la herramienta web_search alojada de OpenAI cuando la búsqueda web de OpenClaw está habilitada y no se ha fijado ningún proveedor gestionado. Este comportamiento pertenece al proveedor en el Plugin de OpenAI incluido y no se aplica a las URL base de proxies compatibles con OpenAI ni a las rutas de Azure. Establece tools.web.search.provider en otro proveedor, como brave, para conservar la herramienta web_search gestionada para los modelos de OpenAI, o establece tools.web.search.enabled: false para deshabilitar tanto la búsqueda gestionada como la búsqueda nativa de OpenAI.

Búsqueda web nativa de Codex

El entorno de ejecución del servidor de aplicaciones de Codex usa automáticamente la herramienta web_search alojada de Codex cuando la búsqueda web está habilitada y no se ha seleccionado ningún proveedor gestionado. La búsqueda nativa alojada y la herramienta dinámica web_search gestionada de OpenClaw son mutuamente excluyentes, por lo que la búsqueda gestionada no puede eludir las restricciones nativas de dominios. OpenClaw usa la herramienta gestionada cuando la búsqueda alojada no está disponible, se ha deshabilitado explícitamente o se ha reemplazado por un proveedor gestionado seleccionado. OpenClaw mantiene deshabilitada la extensión independiente web.run de Codex (features.standalone_web_search: false) porque el tráfico de producción del servidor de aplicaciones rechaza su espacio de nombres web definido por el usuario.

• Configura la búsqueda nativa en tools.web.search.openaiCodex
• Establece tools.web.search.provider: "codex" para proporcionar Codex Hosted Search como proveedor gestionado de web_search para cualquier modelo principal. Cada llamada ejecuta un turno efímero y acotado del servidor de aplicaciones de Codex y falla si Codex no emite un elemento webSearch alojado.
• mode: "cached" es la preferencia predeterminada, pero Codex la resuelve como acceso externo en vivo para los turnos sin restricciones del servidor de aplicaciones; establece "live" para solicitar explícitamente acceso en vivo
• Establece tools.web.search.provider en un proveedor gestionado, como brave, para usar en su lugar la herramienta web_search gestionada de OpenClaw
• Establece tools.web.search.openaiCodex.enabled: false para excluir la búsqueda alojada por Codex; los demás proveedores gestionados siguen disponibles
• Restringir la superficie de herramientas nativas de Codex también mantiene disponible la herramienta web_search gestionada
• Cuando se establece allowedDomains, el respaldo gestionado automático falla de forma segura si la búsqueda alojada no está disponible, de modo que no se pueda eludir la lista de permitidos nativa
• Las ejecuciones que solo usan el LLM y tienen las herramientas deshabilitadas deshabilitan tanto la búsqueda nativa como la gestionada
• tools.web.search.enabled: false deshabilita tanto la búsqueda gestionada como la nativa

Los cambios persistentes en la política efectiva de búsqueda de Codex inician un nuevo hilo vinculado para que un hilo ya cargado del servidor de aplicaciones no pueda conservar acceso obsoleto a la búsqueda alojada. Las restricciones transitorias por turno usan un hilo restringido temporal y conservan la vinculación existente para reanudarla más adelante.

El tráfico directo de OpenAI ChatGPT Responses también puede usar la herramienta web_search alojada de OpenAI. Esa ruta independiente sigue siendo opcional mediante tools.web.search.openaiCodex.enabled: true y solo se aplica a los modelos openai/* aptos que usan api: "openai-chatgpt-responses".

{  tools: {    web: {      search: {        enabled: true,        // Opcional: usar Codex Hosted Search también desde modelos principales que no sean de Codex.        provider: "codex",        openaiCodex: {          enabled: true,          mode: "cached",          allowedDomains: ["example.com"],          contextSize: "high",          userLocation: {            country: "US",            city: "New York",            timezone: "America/New_York",          },        },      },    },  },}

En los entornos de ejecución y proveedores que no admiten la búsqueda nativa de Codex, Codex puede usar el respaldo gestionado web_search mediante el espacio de nombres de herramientas dinámicas de OpenClaw. Usa un proveedor gestionado explícito cuando necesites los controles de red específicos del proveedor de OpenClaw en lugar de la búsqueda alojada por Codex.

Seleccionar provider: "codex" habilita el Plugin codex incluido y usa las mismas restricciones de tools.web.search.openaiCodex mostradas anteriormente. Primero autentica el servidor de aplicaciones de Codex con openclaw models auth login --provider openai. El agente principal puede usar cualquier modelo o entorno de ejecución; solo el trabajador de búsqueda acotado se ejecuta mediante Codex.

Seguridad de red

Las llamadas HTTP gestionadas a proveedores de web_search usan la ruta de obtención protegida de OpenClaw, limitada al nombre de host propio del proveedor actual. Solo para ese nombre de host, OpenClaw permite las respuestas DNS de IP falsa de Surge, Clash y sing-box en 198.18.0.0/15 y fc00::/7. Los demás destinos privados, de local loopback, de enlace local y de metadatos siguen bloqueados. Codex Hosted Search es la excepción: su trabajador acotado delega el acceso a la red en la herramienta web_search alojada del servidor de aplicaciones de Codex.

Esta autorización automática no se aplica a URL arbitrarias de web_fetch. Para web_fetch, habilita explícitamente tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange y tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange solo cuando tu proxy de confianza sea el propietario de esos intervalos sintéticos.

Configuración

{  tools: {    web: {      search: {        enabled: true, // valor predeterminado: true        provider: "brave", // o se omite para la detección automática        maxResults: 5,        timeoutSeconds: 30,        cacheTtlMinutes: 15,      },    },  },}

La configuración específica del proveedor (claves de API, URL base y modos) se encuentra en plugins.entries.<plugin>.config.webSearch.*. Gemini también puede reutilizar models.providers.google.apiKey y models.providers.google.baseUrl como respaldos de menor prioridad después de su configuración dedicada de búsqueda web y GEMINI_API_KEY. Consulta ejemplos en las páginas de los proveedores. Grok también puede reutilizar un perfil de autenticación OAuth de xAI procedente de openclaw models auth login --provider xai --method oauth; la configuración mediante clave de API sigue siendo el respaldo.

tools.web.search.provider se valida respecto a los identificadores de proveedores de búsqueda web declarados por los manifiestos de Plugins incluidos e instalados. Un error tipográfico como "brvae" provoca un error de validación de la configuración en lugar de recurrir silenciosamente a la detección automática. Si un proveedor configurado solo tiene indicios obsoletos del Plugin, como un bloque residual plugins.entries.<plugin> después de desinstalar un Plugin de terceros, OpenClaw mantiene un inicio resistente e informa de una advertencia para que puedas reinstalar el Plugin o ejecutar openclaw doctor --fix a fin de limpiar la configuración obsoleta.

La selección del proveedor de respaldo de web_fetch es independiente:

• selecciónalo con tools.web.fetch.provider
• u omite ese campo y deja que OpenClaw detecte automáticamente el primer proveedor de obtención web preparado a partir de las credenciales configuradas
• web_fetch sin aislamiento puede usar proveedores de Plugins instalados que declaren contracts.webFetchProviders; las obtenciones aisladas permiten proveedores incluidos e instalaciones verificadas de Plugins oficiales, pero excluyen los Plugins externos de terceros
• el Plugin oficial de Firecrawl es actualmente el único colaborador incluido de webFetchProviders, configurado en plugins.entries.firecrawl.config.webFetch.*

Cuando eliges Kimi durante openclaw onboard o openclaw configure --section web, OpenClaw también puede solicitar:

• la región de la API de Moonshot (https://api.moonshot.ai/v1 o https://api.moonshot.cn/v1)
• el modelo predeterminado de búsqueda web de Kimi (el valor predeterminado es kimi-k2.6)

Para x_search, configura plugins.entries.xai.config.xSearch.*. Usa el mismo perfil de autenticación de xAI que el chat, o la credencial XAI_API_KEY o de búsqueda web del Plugin que usa la búsqueda web de Grok. openclaw doctor --fix migra automáticamente la configuración heredada tools.web.x_search.*. Cuando eliges Grok durante openclaw onboard o openclaw configure --section web, OpenClaw también ofrece la configuración opcional de x_search con la misma credencial justo después de completar la configuración de Grok. Se trata de un paso de seguimiento independiente dentro de la ruta de Grok, no de una opción independiente de proveedor de búsqueda web de nivel superior. Si eliges otro proveedor, OpenClaw no muestra la solicitud de x_search.

Almacenamiento de claves de API

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

export BRAVE_API_KEY="YOUR_KEY"

Parámetros de la herramienta

x_search

x_search consulta publicaciones de X (antes Twitter) mediante xAI y devuelve respuestas sintetizadas por IA con citas. Acepta consultas en lenguaje natural y filtros estructurados opcionales. OpenClaw construye la herramienta integrada x_search de xAI para cada solicitud en lugar de mantenerla registrada permanentemente, por lo que solo está activa durante el turno que realmente la invoca.

Configuración de x_search

Con enabled omitido, x_search solo se expone cuando el proveedor del modelo activo es xai y se pueden resolver las credenciales de xAI. Para un modelo activo con un proveedor conocido distinto de xAI, establece plugins.entries.xai.config.xSearch.enabled en true para habilitar voluntariamente el uso entre proveedores. Si falta el proveedor del modelo activo o no se puede resolver, la herramienta permanece oculta. Establece enabled en false para deshabilitarla para todos los proveedores. Las credenciales de xAI son siempre obligatorias.

{  plugins: {    entries: {      xai: {        config: {          xSearch: {            enabled: true, // required for a known non-xAI model provider            model: "grok-4.3",            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 envía solicitudes a <baseUrl>/responses cuando plugins.entries.xai.config.xSearch.baseUrl está establecido. Si se omite ese campo, recurre a plugins.entries.xai.config.webSearch.baseUrl, después al tools.web.search.grok.baseUrl heredado y, por último, al endpoint público de xAI (https://api.x.ai/v1).

Parámetros de x_search

allowed_x_handles y excluded_x_handles son mutuamente excluyentes.

Ejemplo de 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",});

Ejemplos

// 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"],});

Perfiles de herramientas

Si utilizas perfiles de herramientas o listas de permitidos, añade web_search, x_search o group:web:

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

Contenido relacionado

• Obtención web -- obtiene una URL y extrae contenido legible
• Navegador web -- automatización completa del navegador para sitios con uso intensivo de JS
• Búsqueda con Grok -- Grok como proveedor de web_search
• Búsqueda web de Ollama -- búsqueda web sin clave mediante tu host de Ollama