Skip to content
OpenClaw Docs

SearXNG search

OpenClaw supports SearXNG as a self-hosted, key-free web_search provider. SearXNG is an open-source meta-search engine that aggregates results from Google, Bing, DuckDuckGo, and other sources.

Advantages:

  • Free and unlimited — no API key or commercial subscription required
  • Privacy / air-gap — queries never leave your network
  • Works anywhere — no region restrictions on commercial search APIs

Setup

Section titled “Setup”

  1. Run a SearXNG instance

    Terminal window
    docker run -d -p 8888:8080 searxng/searxng

    Or use any existing SearXNG deployment you have access to. See the SearXNG documentation for production setup.

  2. Configure

    Terminal window
    openclaw configure --section web
    # Select "searxng" as the provider

    Or set the env var and let auto-detection find it:

    Terminal window
    export SEARXNG_BASE_URL="http://localhost:8888"

Config

Section titled “Config”
{
  tools: {
    web: {
      search: {
        provider: "searxng",
      },
    },
  },
}

Plugin-level settings for the SearXNG instance:

{
  plugins: {
    entries: {
      searxng: {
        config: {
          webSearch: {
            baseUrl: "http://localhost:8888",
            categories: "general,news", // optional
            language: "en", // optional
          },
        },
      },
    },
  },
}

The baseUrl field also accepts SecretRef objects.

Transport rules:

  • https:// works for public or private SearXNG hosts
  • http:// is only accepted for trusted private-network or loopback hosts
  • public SearXNG hosts must use https://
  • private/internal hosts use the self-hosted network guard; public https:// hosts stay on the strict web-search guard and cannot redirect to private addresses

Environment variable

Section titled “Environment variable”

Set SEARXNG_BASE_URL as an alternative to config:

Terminal window
export SEARXNG_BASE_URL="http://localhost:8888"

When SEARXNG_BASE_URL is set and no explicit provider is configured, auto-detection picks SearXNG automatically (at the lowest priority — any API-backed provider with a key wins first).

Plugin config reference

Section titled “Plugin config reference”
FieldDescription
baseUrlBase URL of your SearXNG instance (required)
categoriesComma-separated categories such as general, news, or science
languageLanguage code for results such as en, de, or fr

Notes

Section titled “Notes”
  • JSON API — uses SearXNG’s native format=json endpoint, not HTML scraping
  • Image result URLs — image-category results include img_src when SearXNG returns a direct image URL
  • No API key — works with any SearXNG instance out of the box
  • Base URL validation — baseUrl must be a valid http:// or https:// URL; public hosts must use https://
  • Network guard — private/internal SearXNG endpoints opt in to private-network access; public https:// SearXNG endpoints keep strict SSRF protection
  • Auto-detection order — SearXNG is checked last (order 200) in auto-detection. API-backed providers with configured keys run first, then DuckDuckGo (order 100), then Ollama Web Search (order 110)
  • Self-hosted — you control the instance, queries, and upstream search engines
  • Categories default to general when not configured
  • Category fallback — if a non-general category request succeeds but returns zero results, OpenClaw retries the same query once with general before returning an empty result set
Section titled “Related”