Búsqueda web

La herramienta web_search busca en la web utilizando 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 la obtención ligera de URL. En esta fase, web_fetch se mantiene local mientras que web_search y x_search pueden utilizar xAI Responses en segundo plano.

Info

web_search

es una herramienta HTTP ligera, no automatización del navegador. Para sitios con mucho JS o inicios de sesión, use

Web Browser

. Para obtener una URL específica, use

Web Fetch

.

Inicio rápido

1. Elegir un proveedor

   Elige un proveedor y completa la configuración necesaria. Algunos proveedores son sin clave, mientras que otros usan claves de API. Consulta las páginas de proveedores a continuación para obtener más detalles.

2. Configurar

   openclaw configure --section web

   Esto almacena el proveedor y cualquier credencial necesaria. También puedes establecer una var de entorno (por ejemplo BRAVE_API_KEY) y omitir este paso para proveedores con API.

3. Usarlo

   El agente ahora puede llamar a web_search:

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

   Para publicaciones de X, usa:

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

Elegir un proveedor

Brave Search

Resultados estructurados con fragmentos. Soporta el modo llm-context, filtros de país/idioma. Plan gratuito disponible.

DuckDuckGo

Alternativa sin clave. No se necesita clave de API. Integración no oficial basada en HTML.

Exa

Búsqueda neuronal + por palabras clave con extracción de contenido (destacados, texto, resúmenes).

Firecrawl

Resultados estructurados. Se combina mejor con firecrawl_search y firecrawl_scrape para una extracción profunda.

Gemini

Respuestas sintetizadas por IA con citas a través de la vinculación con Google Search.

Grok

Respuestas sintetizadas por IA con citas a través de la vinculación web de xAI.

Kimi

Respuestas sintetizadas por IA con citas a través de la búsqueda web Moonshot; los respaldos de chat sin base fallan explícitamente.

MiniMax Search

Resultados estructurados a través de la API de búsqueda del plan de tokens MiniMax.

Ollama Web Search

Búsqueda a través de un host local de Ollama con sesión iniciada o la API alojada de Ollama.

Perplexity

Resultados estructurados con controles de extracción de contenido y filtrado de dominios.

SearXNG

Metabuscador autoalojado. No se necesita clave de API. Agrega Google, Bing, DuckDuckGo y más.

Tavily

Resultados estructurados con profundidad de búsqueda, filtrado de temas y tavily_extract para la extracción de URL.

Comparación de proveedores

Proveedor	Estilo de resultado	Filtros	Clave de API
Brave	Fragmentos estructurados	País, idioma, hora, modo llm-context	BRAVE_API_KEY
DuckDuckGo	Fragmentos estructurados	—	Ninguna (sin clave)
Exa	Estructurado + extraído	Modo neuronal/palabras clave, fecha, extracción de contenido	EXA_API_KEY
Firecrawl	Fragmentos estructurados	Vía herramienta firecrawl_search	FIRECRAWL_API_KEY
Gemini	Sintetizado por IA + citas	—	GEMINI_API_KEY
Grok	Sintetizado por IA + citas	—	xAI OAuth, XAI_API_KEY, o plugins.entries.xai.config.webSearch.apiKey
Kimi	Sintetizado por IA + citas; falla en respaldos de chat sin base	—	KIMI_API_KEY / MOONSHOT_API_KEY
MiniMax Search	Fragmentos estructurados	Región (global / cn)	MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY / MINIMAX_OAUTH_TOKEN
Ollama Web Search	Fragmentos estructurados	—	Ninguno para hosts locales con sesión iniciada; OLLAMA_API_KEY para búsqueda https://ollama.com directa
Perplexity	Fragmentos estructurados	País, idioma, hora, dominios, límites de contenido	PERPLEXITY_API_KEY / OPENROUTER_API_KEY
SearXNG	Fragmentos estructurados	Categorías, idioma	Ninguno (autohospedado)
Tavily	Fragmentos estructurados	Vía la herramienta tavily_search	TAVILY_API_KEY

Detección automática

Búsqueda web nativa de OpenAI

Los modelos directos de OpenAI Responses usan automáticamente la herramienta alojada web_search de OpenAI cuando la búsqueda web de OpenClaw está habilitada y no hay ningún proveedor administrado fijado. Este es un comportamiento del proveedor en el complemento OpenAI incluido y solo se aplica al tráfico de la API nativa de OpenAI, no a las URL base de proxy compatibles con OpenAI ni a rutas de Azure. Establezca tools.web.search.provider en otro proveedor como brave para mantener la herramienta administrada web_search para los modelos de OpenAI, o establezca 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

Los modelos con capacidad para Codex pueden usar opcionalmente la herramienta Responses web_search nativa del proveedor en lugar de la función gestionada web_search de OpenClaw.

• Configúrelo bajo tools.web.search.openaiCodex
• Solo se activa para modelos de OpenAI compatibles con Codex (modelos openai/* que usan api: "openai-chatgpt-responses")
• El web_search gestionado todavía se aplica a modelos que no son Codex
• mode: "cached" es la configuración predeterminada y recomendada
• tools.web.search.enabled: false deshabilita tanto la búsqueda gestionada como la nativa

{
  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 búsqueda nativa de Codex está habilitada pero el modelo actual no tiene capacidad para Codex, OpenClaw mantiene el comportamiento normal gestionado de web_search.

Seguridad de red

Las llamadas al proveedor gestionadas de web_search usan la ruta de recuperación protegida de OpenClaw. Para hosts de API de proveedores confiables, 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 nombre de host del proveedor. Otros destinos privados, de loopback, de enlace local y de metadatos permanecen bloqueados.

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

Configurar la búsqueda web

Las listas de proveedores en los documentos y 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 ningún provider, OpenClaw verifica los proveedores en este orden y usa el primero que esté listo:

Primero los proveedores con 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 — xAI OAuth, 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; plugins.entries.exa.config.webSearch.baseUrl opcional anula el endpoint de Exa (orden 65)
9. Tavily — TAVILY_API_KEY o plugins.entries.tavily.config.webSearch.apiKey (orden 70)

Alternativas sin clave después:

10. DuckDuckGo — alternativa HTML sin clave y sin cuenta ni clave de API (orden 100)
11. Ollama Web Search — respaldo sin clave a través de su host local de Ollama configurado cuando es accesible y ha iniciado sesión con ollama signin; puede reutilizar la autenticación de portador del proveedor Ollama cuando el host la necesita, y puede llamar a la búsqueda directa https://ollama.com cuando está configurado con OLLAMA_API_KEY (orden 110)
12. SearXNG — SEARXNG_BASE_URL o plugins.entries.searxng.config.webSearch.baseUrl (orden 200)

Si no se detecta ningún proveedor, se recurre a Brave (obtendrá un error de clave faltante que le pedirá que configure uno).

Note

Todos los campos de clave de proveedor admiten objetos SecretRef. Los SecretRefs con alcance de complemento bajo `plugins.entries.

.config.webSearch.apiKeyse resuelven para los proveedores de búsqueda web respaldados por API incluidos, como Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax, Perplexity y Tavily, ya sea que el proveedor se seleccione explícitamente a través detools.web.search.provider` o se seleccione mediante detección automática. En modo de detección automática, OpenClaw resuelve solo la clave del proveedor seleccionado; los SecretRefs no seleccionados permanecen inactivos, por lo que puede mantener varios proveedores configurados sin incurrir en costos de resolución para aquellos que no está utilizando.

Config

{
  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) 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 de búsqueda web dedicada y GEMINI_API_KEY. Consulte las páginas del proveedor 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 de clave de API sigue siendo el respaldo.

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

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

• elíjalo con tools.web.fetch.provider
• u omita ese campo y deje que OpenClaw detecte automáticamente el primer proveedor de obtención web listo a partir de las credenciales disponibles
• web_fetch sin espacio aislado puede usar proveedores de complementos instalados que declaren contracts.webFetchProviders; las recuperaciones en espacio aislado se limitan a las incluidas
• hoy el proveedor de recuperación web incluido es Firecrawl, configurado en plugins.entries.firecrawl.config.webFetch.*

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

• 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 Kimi predeterminado (predeterminado a kimi-k2.6)

Para x_search, configure plugins.entries.xai.config.xSearch.*. Utiliza el mismo perfil de autenticación xAI que el chat, o la credencial de búsqueda web XAI_API_KEY / complemento 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 elige Grok durante openclaw onboard o openclaw configure --section web, OpenClaw también puede ofrecer una 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 separada de proveedor de búsqueda web de nivel superior. Si elige otro proveedor, OpenClaw no muestra el mensaje x_search.

Almacenamiento de claves API

Archivo de configuraciónVariable de entorno

Ejecute openclaw configure --section web o establezca la clave directamente:

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

Establezca la variable de entorno del proveedor en el entorno del proceso de Gateway:

export BRAVE_API_KEY="YOUR_KEY"

Para una instalación de puerta de enlace, colóquela en ~/.openclaw/.env. Vea Variables de entorno.

Parámetros de la herramienta

Parámetro	Descripción
query	Consulta de búsqueda (obligatorio)
count	Resultados a devolver (1-10, predeterminado: 5)
country	Código de país ISO de 2 letras (ej. “US”, “DE”)
language	Código de idioma ISO 639-1 (ej. “en”, “de”)
search_lang	Código de idioma de búsqueda (solo Brave)
freshness	Filtro de tiempo: day, week, month o year
date_after	Resultados después de esta fecha (AAAA-MM-DD)
date_before	Resultados antes de esta fecha (AAAA-MM-DD)
ui_lang	Código de idioma de la interfaz (solo Brave)
domain_filter	Matriz de lista de permitidos/denegados de dominio (solo Perplexity)
max_tokens	Presupuesto total de contenido, por defecto 25000 (solo Perplexity)
max_tokens_per_page	Límite de tokens por página, por defecto 2048 (solo Perplexity)

Warning

No todos los parámetros funcionan con todos los proveedores. El modo llm-context de Brave rechaza ui_lang; date_before también necesita date_after porque los rangos de frescura personalizados de Brave requieren fechas de inicio y finalización. Gemini, Grok y Kimi devuelven una respuesta sintetizada con citas. Ellos aceptan count para compatibilidad con herramientas compartidas, pero no cambia la forma de la respuesta fundamentada. Gemini admite freshness, date_after y date_before convirtiéndolos en rangos de tiempo de fundamentación de Google Search. Perplexity se comporta de la misma manera cuando usa la ruta de compatibilidad Sonar/OpenRouter (plugins.entries.perplexity.config.webSearch.baseUrl / model o OPENROUTER_API_KEY). SearXNG acepta http:// solo para hosts de red privada o loopback confiables; los puntos finales públicos de SearXNG deben usar https://. Firecrawl y Tavily solo admiten query y count a través de web_search — use sus herramientas dedicadas para opciones avanzadas.

x_search

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

Note

La documentación de xAI indica que x_search admite búsqueda por palabras clave, búsqueda semántica, búsqueda de usuario y recuperación de hilos. Para estadísticas de interacción por publicación, como republicaciones, respuestas, marcadores o vistas, se recomienda una búsqueda específica de la URL exacta de la publicación o del ID de estado. Las búsquedas amplias por palabras clave pueden encontrar la publicación correcta, pero devuelven metadatos por publicación menos completos. Un buen patrón es: localizar primero la publicación y luego ejecutar una segunda consulta de x_search enfocada en esa publicación exacta.

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 envía publicaciones a <baseUrl>/responses cuando plugins.entries.xai.config.xSearch.baseUrl está configurado. Si se omite ese campo, se remite a plugins.entries.xai.config.webSearch.baseUrl, luego al tools.web.search.grok.baseUrl heredado y finalmente al punto final público de xAI.

Parámetros de x_search

Parámetro	Descripción
query	Consulta de búsqueda (requerida)
allowed_x_handles	Restringir los resultados a identificadores de X específicos
excluded_x_handles	Excluir identificadores de X específicos
from_date	Incluir solo publicaciones en o después de esta fecha (AAAA-MM-DD)
to_date	Incluir solo publicaciones en o antes de esta fecha (AAAA-MM-DD)
enable_image_understanding	Permitir que xAI inspeccione las imágenes adjuntas a las publicaciones coincidentes
enable_video_understanding	Permitir que xAI inspeccione los videos adjuntos a las publicaciones coincidentes

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

Ejemplos

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

Perfiles de herramientas

Si utiliza perfiles de herramientas o listas de permitidos, añada 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

• Web Fetch — obtiene una URL y extrae el contenido legible
• Web Browser — automatización completa del navegador para sitios con mucho JS
• Grok Search — Grok como proveedor de web_search
• Ollama Web Search — búsqueda web sin clave a través de su host Ollama