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 la obtención ligera de URL. En esta fase, web_fetch permanece local mientras que 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" });

# Elegir 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 web_search alojada de OpenAI cuando la búsqueda web de OpenClaw está habilitada y no hay ningún proveedor administrado 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. Establece tools.web.search.provider en otro proveedor como brave para mantener la herramienta web_search administrada para los modelos de OpenAI, o establece 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 compatibles con Codex pueden usar opcionalmente la herramienta web_search nativa del proveedor de Responses en lugar de la función web_search administrada de OpenClaw.

• Configúrala en tools.web.search.openaiCodex
• Solo se activa para modelos compatibles con Codex (openai-codex/* o proveedores que usan api: "openai-codex-responses")
• La web_search administrada sigue aplicándose a modelos que no son Codex
• mode: "cached" es la opción predeterminada y recomendada
• tools.web.search.enabled: false deshabilita tanto la búsqueda administrada 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 es compatible con Codex, OpenClaw mantiene el comportamiento normal de web_search administrada.

# Seguridad de red

Las llamadas de proveedor de web_search administrada usan la ruta de obtención 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 nombre de host del proveedor. Otros destinos privados, local loopback, link-local y de metadatos permanecen bloqueados.

Esta concesión automática no se aplica a URL 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 independiente.

Si no se establece ningún 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 -- 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 sobrescribe 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 de eso:

10. DuckDuckGo -- alternativa HTML sin clave, sin cuenta ni clave API (orden 100)
11. Ollama Web Search -- alternativa sin clave mediante tu host local de Ollama configurado cuando sea accesible y tenga sesión iniciada con ollama signin; puede reutilizar la autenticación bearer del proveedor Ollama cuando el host la necesite, y puede llamar a la búsqueda directa de https://ollama.com cuando esté configurada 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 (recibirás un error de clave faltante que te pedirá configurar una).

# 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, URL base, modos) reside en 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. Consulta las páginas de proveedores para ver ejemplos.

tools.web.search.provider se valida contra los ids de proveedor de búsqueda web declarados por los manifiestos de plugins incluidos e instalados, además de plugins de proveedor instalables conocidos. Un error tipográfico como "brvae" hace fallar la validación de configuración en lugar de recurrir silenciosamente a la detección automática. Si el proveedor configurado es conocido pero el plugin propietario no está disponible, OpenClaw mantiene el arranque resiliente e informa una advertencia para que puedas ejecutar openclaw doctor --fix para instalar o habilitar el plugin. El mismo comportamiento de advertencia se aplica a evidencias de plugin obsoletas, como un bloque plugins.entries.<plugin> restante después de desinstalar un plugin de terceros.

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

• elígelo con tools.web.fetch.provider
• u omite ese campo y deja que OpenClaw detecte automáticamente el primer proveedor de captura web listo a partir de las credenciales disponibles
• web_fetch sin sandbox puede usar proveedores de plugins instalados que declaren contracts.webFetchProviders; las capturas en sandbox siguen limitadas a los incluidos
• hoy el proveedor de captura web incluido es Firecrawl, configurado en plugins.entries.firecrawl.config.webFetch.*

Cuando eliges Kimi durante openclaw onboard u 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 predeterminado de búsqueda web de Kimi (predeterminado: kimi-k2.6)

Para x_search, configura plugins.entries.xai.config.xSearch.*. Usa la misma alternativa XAI_API_KEY que la búsqueda web de Grok. La configuración heredada tools.web.x_search.* se migra automáticamente con openclaw doctor --fix. Cuando eliges Grok durante openclaw onboard u openclaw configure --section web, OpenClaw también puede ofrecer una configuración opcional de x_search con la misma clave. Este es un paso posterior separado dentro de la ruta de Grok, no una opción separada de proveedor de búsqueda web de nivel superior. Si eliges otro proveedor, OpenClaw no muestra el prompt 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) usando xAI y devuelve respuestas sintetizadas por IA con citas. Acepta consultas en lenguaje natural y filtros estructurados opcionales. OpenClaw solo habilita la herramienta integrada x_search 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 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 a 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 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 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

• Web Fetch -- capturar una URL y extraer 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 mediante tu host de Ollama