Búsqueda web

La herramienta web_search busca en la web usando tu proveedor configurado y devuelve resultados. Los resultados se almacenan en caché por consulta durante 15 minutos (configurable).

OpenClaw también incluye x_search para publicaciones de X (antes Twitter) y web_fetch para obtención ligera de URL. En esta fase, web_fetch permanece local mientras web_search y x_search pueden usar xAI Responses internamente.

Inicio rápido

openclaw configure --section web

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

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

Elección de un proveedor

Comparación de proveedores

Detección automática

Búsqueda web nativa de OpenAI

Los modelos directos de OpenAI Responses usan automáticamente la herramienta hospedada web_search de OpenAI cuando la búsqueda web de OpenClaw está habilitada y no hay ningún proveedor gestionado fijado. Este es un comportamiento propiedad del proveedor en el plugin de OpenAI incluido y solo se aplica al tráfico nativo de la API de OpenAI, no a URL base de proxy compatibles con OpenAI ni a rutas de Azure. Define tools.web.search.provider en otro proveedor, como brave, para conservar la herramienta gestionada web_search para los modelos de OpenAI, o define 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 runtime del servidor de aplicaciones de Codex usa automáticamente la herramienta hospedada web_search de Codex cuando la búsqueda web está habilitada y no se ha seleccionado ningún proveedor gestionado. La búsqueda hospedada nativa y la herramienta dinámica gestionada web_search de OpenClaw son mutuamente excluyentes, por lo que la búsqueda gestionada no puede omitir las restricciones de dominio nativas. OpenClaw usa la herramienta gestionada cuando la búsqueda hospedada no está disponible, está deshabilitada explícitamente o se reemplaza por un proveedor gestionado seleccionado. OpenClaw mantiene deshabilitada la extensión independiente web.run de Codex 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
• Define tools.web.search.provider: "codex" para aprovisionar Codex Hosted Search como proveedor gestionado de web_search para cualquier modelo padre. Cada llamada ejecuta un turno efímero acotado del servidor de aplicaciones de Codex y falla si Codex no emite un elemento hospedado webSearch.
• mode: "cached" es la preferencia predeterminada, pero Codex la resuelve como acceso externo en vivo para turnos sin restricciones del servidor de aplicaciones; define "live" para solicitar acceso en vivo explícitamente
• Define tools.web.search.provider en un proveedor gestionado como brave para usar la web_search gestionada de OpenClaw en su lugar
• Define tools.web.search.openaiCodex.enabled: false para excluirte de la búsqueda hospedada por Codex; otros proveedores gestionados siguen disponibles
• Restringir la superficie de herramientas nativa de Codex también mantiene disponible la web_search gestionada
• Cuando allowedDomains está definido, la alternativa gestionada automática falla de forma cerrada si la búsqueda hospedada no está disponible, para que la lista de permitidos nativa no pueda omitirse
• Las ejecuciones solo LLM con 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 de política de búsqueda efectiva de Codex inician un nuevo hilo vinculado para que un hilo del servidor de aplicaciones ya cargado no pueda conservar acceso obsoleto a la búsqueda hospedada. Las restricciones transitorias por turno usan un hilo restringido temporal y conservan la vinculación existente para reanudarla más tarde.

El tráfico directo de OpenAI ChatGPT Responses también puede usar la herramienta hospedada web_search de OpenAI. Esa ruta separada sigue siendo opcional mediante tools.web.search.openaiCodex.enabled: true y solo se aplica a modelos openai/* aptos que usan 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",          },        },      },    },  },}

Para runtimes y proveedores que no admiten la búsqueda nativa de Codex, Codex puede usar la alternativa gestionada 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 hospedada por Codex.

Seleccionar provider: "codex" habilita el plugin codex incluido y usa las mismas restricciones de tools.web.search.openaiCodex que se muestran arriba. Autentica primero el servidor de aplicaciones Codex con openclaw models auth login --provider openai. El agente padre puede usar cualquier modelo o runtime; solo el worker de búsqueda acotada se ejecuta a través de Codex.

Seguridad de red

Las llamadas del proveedor HTTP administrado web_search usan la ruta de fetch protegida de OpenClaw. Para hosts de API de proveedor de confianza, OpenClaw permite respuestas DNS de IP falsa de Surge, Clash y sing-box en 198.18.0.0/15 y fc00::/7 solo para ese hostname de proveedor. Otros destinos privados, loopback, link-local y de metadatos permanecen bloqueados. Codex Hosted Search es la excepción: su worker acotado delega el acceso de red a la herramienta web_search alojada del servidor de aplicaciones Codex.

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

Configurar la búsqueda web

Las listas de proveedores en la documentación y los flujos de configuración están en orden alfabético. La detección automática mantiene un orden de precedencia separado.

Si no se establece provider, OpenClaw revisa los proveedores en este orden y usa el primero que esté listo:

Primero, 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 plugins.entries.exa.config.webSearch.baseUrl opcional reemplaza el endpoint de Exa (orden 65)
9. Tavily -- TAVILY_API_KEY o plugins.entries.tavily.config.webSearch.apiKey (orden 70)
10. Parallel -- API de Parallel Search de pago mediante PARALLEL_API_KEY o plugins.entries.parallel.config.webSearch.apiKey; el plugins.entries.parallel.config.webSearch.baseUrl opcional reemplaza el endpoint (orden 75)

Después, proveedores con endpoint configurado:

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

Los proveedores sin clave, como Parallel Search (Free), DuckDuckGo, Ollama Web Search y Codex Hosted Search, solo están disponibles cuando los seleccionas explícitamente con tools.web.search.provider o mediante openclaw configure --section web. OpenClaw no envía consultas administradas de web_search a un proveedor sin clave solo porque no haya ningún proveedor respaldado por API configurado.

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

Configuración

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

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

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

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

• elígelo con tools.web.fetch.provider
• o omite ese campo y deja que OpenClaw detecte automáticamente el primer proveedor de web-fetch listo a partir de las credenciales configuradas
• web_fetch sin sandbox puede usar proveedores de plugins instalados que declaren contracts.webFetchProviders; los fetches con sandbox permiten proveedores incluidos e instalaciones verificadas de plugins oficiales, pero excluyen plugins externos de terceros
• el plugin oficial Firecrawl proporciona fallback de web-fetch, configurado bajo plugins.entries.firecrawl.config.webFetch.*

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

• la región de 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 / de búsqueda web del plugin que usa la búsqueda web de Grok. La configuración heredada tools.web.x_search.* se migra automáticamente mediante openclaw doctor --fix. Cuando eliges Grok durante openclaw onboard o openclaw configure --section web, OpenClaw también puede ofrecer la configuración opcional de x_search con la misma credencial. Este es un paso de seguimiento separado dentro de la ruta de Grok, no una opción independiente de proveedor de búsqueda web de nivel superior. Si eliges otro proveedor, OpenClaw no muestra el prompt de x_search.

Almacenar claves de API

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

export BRAVE_API_KEY="YOUR_KEY"

Parámetros de herramienta

x_search

x_search consulta publicaciones de X (antes Twitter) usando xAI y devuelve respuestas sintetizadas por IA con citas. Acepta consultas en lenguaje natural y filtros estructurados opcionales. OpenClaw solo habilita la herramienta x_search integrada de xAI en la solicitud que atiende esta llamada de herramienta.

Configuración 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 publica en <baseUrl>/responses cuando plugins.entries.xai.config.xSearch.baseUrl está establecido. Si se omite ese campo, recurre a plugins.entries.xai.config.webSearch.baseUrl, luego al tools.web.search.grok.baseUrl heredado y finalmente al endpoint público de xAI.

Parámetros de x_search

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 usas perfiles de herramientas o listas de permitidos, agrega 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)  },}

Relacionado

• Extracción web -- obtiene una URL y extrae contenido legible
• Navegador web -- automatización completa del navegador para sitios con mucho JS
• Búsqueda de Grok -- Grok como proveedor de web_search
• Búsqueda web de Ollama -- búsqueda web sin clave a través de tu host de Ollama