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 (antes Twitter) y web_fetch para la obtención ligera de URL. web_fetch siempre se ejecuta localmente; web_search se enruta mediante xAI Responses cuando Grok es el proveedor, y x_search siempre usa 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

Estructura de los resultados

web_search normaliza todos los proveedores de plugins incluidos y externos en el límite de la herramienta principal. Los invocadores reciben exactamente una de estas estructuras cerradas:

type WebSearchOutput =  | {      kind: "error";      provider: string;      error: "provider_error";      message: string;      docs?: string;    }  | {      kind: "results";      provider: string;      query: string;      count: number;      tookMs?: number;      results: Array<{        title: string;        url: string;        snippet?: string;        published?: string;        siteName?: string;      }>;      externalContent: {        untrusted: true;        source: "web_search";        wrapped: true;        provider: string;      };      cached?: true;    }  | {      kind: "answer";      provider: string;      query: string;      tookMs?: number;      content: string;      citations?: Array<{ url: string; title?: string }>;      externalContent: {        untrusted: true;        source: "web_search";        wrapped: true;        provider: string;      };      cached?: true;    }  | {      kind: "raw";      provider: string;      data: unknown;    };

Los proveedores estructurados usan kind: "results"; los proveedores sintetizados usan kind: "answer". Los proveedores de plugins externos cuyas cargas no coinciden con ninguna estructura se transmiten literalmente como kind: "raw" por compatibilidad. Los campos específicos del proveedor, como puntuaciones sin procesar, fragmentos, búsquedas relacionadas, desplazamientos de citas insertadas, identificadores de modelos o metadatos de sesión, no se transmiten en las ramas normalizadas. Use la herramienta específica de un proveedor cuando su respuesta más detallada forme parte del flujo de trabajo.

externalContent.wrapped: true es un marcador de confianza cuya veracidad garantiza el propio límite: el texto del proveedor (title, snippet, siteName, content, títulos de citas y message de errores) se limpia de cualquier línea de envoltura preexistente y se vuelve a envolver exactamente una vez en el límite principal, por lo que ningún metadato del proveedor puede suplantar el marcador. query siempre es la consulta solicitada, las URL de citas y resultados deben poder analizarse como http(s), published debe tener formato de fecha ISO, las URL se emiten canonizadas y una carga que contiene una clave error siempre se notifica como kind: "error", conservando el código original del proveedor dentro del mensaje envuelto. Las cargas transmitidas sin procesar conservan los marcadores establecidos por el proveedor.

Detección automática

Las listas de proveedores de la documentación y los flujos de configuración siguen un orden alfabético. La detección automática usa un orden de precedencia fijo e independiente, y solo selecciona un proveedor que necesita una credencial (requiresCredential !== false) cuando encuentra una configurada. Si no se establece provider, OpenClaw comprueba los proveedores en este orden y usa 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 endpoint de Exa (orden 65)
9. Tavily -- TAVILY_API_KEY o plugins.entries.tavily.config.webSearch.apiKey (orden 70)
10. Parallel -- API de pago Parallel Search mediante PARALLEL_API_KEY o plugins.entries.parallel.config.webSearch.apiKey; el valor opcional plugins.entries.parallel.config.webSearch.baseUrl sustituye el endpoint (orden 75)

A continuación, los proveedores de endpoints configurados:

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, nunca prevalecen en la detección automática, aunque tengan un valor de orden interno. Solo se utilizan cuando se seleccionan 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 únicamente 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é definido, utilizan la búsqueda web nativa de OpenAI en lugar de los proveedores administrados anteriores (véase más adelante). Defina tools.web.search.provider como parallel-free (u otro proveedor) para dirigirlos, en cambio, por la ruta administrada.

Búsqueda web nativa de OpenAI

Los modelos OpenAI Responses directos (api: "openai-responses", proveedor openai, sin URL base o con una URL base oficial de la API de OpenAI) utilizan automáticamente la herramienta web_search alojada por OpenAI cuando la búsqueda web de OpenClaw está habilitada y no hay ningún proveedor administrado fijado. 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. Defina tools.web.search.provider como otro proveedor, por ejemplo brave, para mantener la herramienta web_search administrada para los modelos de OpenAI, o defina tools.web.search.enabled: false para deshabilitar tanto la búsqueda administrada como la búsqueda nativa de OpenAI.

Búsqueda web nativa de Codex

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

• Configure la búsqueda nativa bajo tools.web.search.openaiCodex
• Defina tools.web.search.provider: "codex" para proporcionar Codex Hosted Search como el proveedor web_search administrado para cualquier modelo principal. Cada llamada ejecuta un turno efímero y acotado del app-server 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 de app-server sin restricciones; defina "live" para solicitar explícitamente acceso en vivo.
• Defina tools.web.search.provider como un proveedor administrado, por ejemplo brave, para utilizar en su lugar el web_search administrado de OpenClaw.
• Defina tools.web.search.openaiCodex.enabled: false para excluirse de la búsqueda alojada por Codex; los demás proveedores administrados seguirán disponibles.
• Restringir la superficie de herramientas nativas de Codex también mantiene disponible el web_search administrado.
• Cuando se define allowedDomains, la alternativa administrada automática falla de forma cerrada si la búsqueda alojada no está disponible, de modo que no se pueda eludir la lista de permitidos nativa.
• Las ejecuciones solo con LLM y herramientas deshabilitadas deshabilitan tanto la búsqueda nativa como la administrada.
• tools.web.search.enabled: false deshabilita tanto la búsqueda administrada 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 de app-server ya cargado no pueda conservar un acceso obsoleto a la búsqueda alojada. Las restricciones transitorias por turno utilizan un hilo restringido temporal y conservan la vinculación existente para reanudarla posteriormente.

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

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

Para los entornos de ejecución y proveedores que no admiten la búsqueda nativa de Codex, Codex puede utilizar la alternativa web_search administrada mediante el espacio de nombres de herramientas dinámicas de OpenClaw. Utilice un proveedor administrado explícito cuando necesite 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 utiliza las mismas restricciones tools.web.search.openaiCodex mostradas anteriormente. Primero autentique el app-server de Codex con openclaw models auth login --provider openai. El agente principal puede utilizar cualquier modelo o entorno de ejecución; solo el trabajador de búsqueda acotado se ejecuta mediante Codex.

Seguridad de la red

Las llamadas administradas de proveedores HTTP web_search utilizan 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 respuestas DNS de IP falsas de Surge, Clash y sing-box en 198.18.0.0/15 y fc00::/7. Los demás destinos privados, de bucle invertido, locales de enlace y de metadatos permanecen bloqueados. Codex Hosted Search es la excepción: su trabajador acotado delega el acceso a la red en la herramienta web_search alojada del app-server de Codex.

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

Configuración

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

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

tools.web.search.provider se valida con 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 plugins.entries.<plugin> sobrante después de desinstalar un Plugin de terceros, OpenClaw mantiene un inicio resiliente e informa de una advertencia para que se pueda reinstalar el Plugin o ejecutar openclaw doctor --fix a fin de limpiar la configuración obsoleta.

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

• elíjalo con tools.web.fetch.provider
• o bien omita ese campo y permita que OpenClaw detecte automáticamente el primer proveedor de obtención web disponible entre las credenciales configuradas.
• El web_fetch sin entorno aislado puede utilizar proveedores de Plugins instalados que declaren contracts.webFetchProviders; las obtenciones en entornos aislados permiten proveedores incluidos e instalaciones verificadas de Plugins oficiales, pero excluyen los Plugins externos de terceros.
• El Plugin oficial Firecrawl es actualmente el único colaborador incluido de webFetchProviders, configurado bajo plugins.entries.firecrawl.config.webFetch.*.

Cuando se elige 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 de búsqueda web predeterminado de Kimi (el valor predeterminado es kimi-k2.6)

Para x_search, configure plugins.entries.xai.config.xSearch.*. Utiliza el mismo perfil de autenticación de xAI que el chat, o la credencial XAI_API_KEY / de búsqueda web del Plugin utilizada por la búsqueda web de Grok. La configuración heredada tools.web.x_search.* se migra automáticamente mediante openclaw doctor --fix. Cuando se elige 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. Este es un paso posterior independiente dentro de la ruta de Grok, no una opción independiente de proveedor de búsqueda web de nivel superior. Si se elige otro proveedor, OpenClaw no muestra la solicitud 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 (anteriormente Twitter) mediante xAI y devuelve respuestas sintetizadas por IA con citas. Acepta consultas en lenguaje natural y filtros estructurados opcionales. OpenClaw crea la herramienta x_search integrada 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

Si se omite enabled, 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 que no sea xAI, establezca plugins.entries.xai.config.xSearch.enabled en true para habilitar su uso entre proveedores. Si falta el proveedor del modelo activo o no puede resolverse, la herramienta permanece oculta. Establezca enabled en false para deshabilitarla para todos los proveedores. Las credenciales de xAI son siempre obligatorias.

{  plugins: {    entries: {      xai: {        config: {          xSearch: {            enabled: true, // obligatorio para un proveedor conocido de modelos que no sea xAI            model: "grok-4.3",            baseUrl: "https://api.x.ai/v1", // opcional, reemplaza webSearch.baseUrl            inlineCitations: false,            maxTurns: 2,            timeoutSeconds: 30,            cacheTtlMinutes: 15,          },          webSearch: {            apiKey: "xai-...", // opcional si se ha configurado un perfil de autenticación de xAI o XAI_API_KEY            baseUrl: "https://api.x.ai/v1", // URL base opcional compartida de Responses de xAI          },        },      },    },  },}

x_search envía solicitudes POST a <baseUrl>/responses cuando se establece plugins.entries.xai.config.xSearch.baseUrl. Si se omite ese campo, se recurre a plugins.entries.xai.config.webSearch.baseUrl y, después, 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: "recetas para la cena",  allowed_x_handles: ["nytfood"],  from_date: "2026-03-01",});

// Estadísticas por publicación: utilice la URL exacta del estado o el ID de estado cuando sea posibleawait x_search({  query: "https://x.com/huntharo/status/1905678901234567890",});

Ejemplos

// Búsqueda básicaawait web_search({ query: "SDK de plugins de OpenClaw" }); // Búsqueda específica para alemánawait web_search({ query: "ver televisión en línea", country: "DE", language: "de" }); // Resultados recientes (última semana)await web_search({ query: "avances en IA", freshness: "week" }); // Intervalo de fechasawait web_search({  query: "investigación climática",  date_after: "2024-01-01",  date_before: "2024-06-30",}); // Filtrado de dominios (solo Perplexity)await web_search({  query: "reseñas de productos",  domain_filter: ["-reddit.com", "-pinterest.com"],});

Perfiles de herramientas

Si se utilizan perfiles de herramientas o listas de permitidos, añada web_search, x_search o group:web:

{  tools: {    allow: ["web_search", "x_search"],    // o bien: allow: ["group:web"]  (incluye web_search, x_search y web_fetch)  },}

Temas relacionados

• 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 web_search
• Búsqueda web de Ollama -- búsqueda web sin clave mediante el host de Ollama