OpenClaw SearXNG Setup

What Is SearXNG?

SearXNG is an open-source, privacy-respecting metasearch engine that aggregates results from 70+ search sources — including Google, Bing, DuckDuckGo, Wikipedia, and dozens more. Unlike traditional search APIs, SearXNG is completely free and can be self-hosted on your own server.

Because SearXNG runs on your infrastructure, there are no API keys to manage, no usage limits, and no third-party data sharing. Your search queries stay entirely private. It returns results in clean JSON format, making it ideal for AI agents like OpenClaw that need structured search data.

Why Use SearXNG with OpenClaw?

OpenClaw supports multiple search backends. Here's how SearXNG compares to other popular options:

SearXNG is the best choice if you want unlimited, free, private search for your OpenClaw agent. If you prefer simpler setup and don't mind API keys, Tavily or Brave Search are easier to get started with.

Option 1: Use a Public SearXNG Instance

The fastest way to try SearXNG with OpenClaw is to use an existing public instance. The SearXNG community maintains a directory of public instances at searx.space.

1. Visit searx.space and browse the list of public instances
2. Pick an instance that supports JSON output (most do)
3. Copy the instance URL (e.g., https://search.example.com)
4. Configure OpenClaw to use it (see “Connect SearXNG to OpenClaw” below)

Note: Public instances are free but may be slower, rate-limited, or occasionally unavailable. For reliable, production use, self-hosting is recommended.

Option 2: Self-Host SearXNG with Docker

For the best experience, run your own SearXNG instance. The simplest way is with Docker.

Quick Start with Docker Run

docker run -d \
  --name searxng \
  -p 8080:8080 \
  -v searxng-data:/etc/searxng \
  -e SEARXNG_BASE_URL=http://localhost:8080/ \
  searxng/searxng:latest

SearXNG will be available at http://localhost:8080. Verify it's running by visiting that URL in your browser.

Docker Compose (Recommended)

For a more robust setup, use Docker Compose:

# docker-compose.yml
version: "3.8"
services:
  searxng:
    image: searxng/searxng:latest
    container_name: searxng
    ports:
      - "8080:8080"
    volumes:
      - ./searxng:/etc/searxng:rw
    environment:
      - SEARXNG_BASE_URL=http://localhost:8080/
    restart: unless-stopped

Start it with docker compose up -d. The configuration files will be created automatically in the ./searxng directory.

Enable JSON API

By default, SearXNG's JSON API may be disabled. To enable it, edit your settings.yml (in the SearXNG config directory):

# settings.yml
search:
  formats:
    - html
    - json

Restart SearXNG after making this change. You can verify the JSON API works by visiting: http://localhost:8080/search?q=test&format=json

Connect SearXNG to OpenClaw

Once SearXNG is running, configure your OpenClaw agent to use it as a search backend. Add the following to your openclaw.json:

{
  "skills": {
    "web-search": {
      "provider": "searxng",
      "searxng": {
        "baseUrl": "http://localhost:8080",
        "format": "json"
      }
    }
  }
}

If SearXNG is running on a different machine, replace localhost:8080 with the actual hostname and port. For Docker-to-Docker setups on the same host, use the container name (e.g., http://searxng:8080) if both containers share a Docker network.

Advanced Configuration

Engine Selection

SearXNG lets you choose which search engines to query. Edit your settings.yml to enable or disable specific engines:

engines:
  - name: google
    disabled: false
  - name: bing
    disabled: false
  - name: duckduckgo
    disabled: false
  - name: wikipedia
    disabled: false
  - name: reddit
    disabled: true

Result Format and Limits

Control how many results SearXNG returns and how they're formatted in your OpenClaw config:

{
  "skills": {
    "web-search": {
      "provider": "searxng",
      "searxng": {
        "baseUrl": "http://localhost:8080",
        "format": "json",
        "maxResults": 10,
        "categories": ["general", "news", "science"]
      }
    }
  }
}

Timeout and Rate Limiting

If you're using a public instance or have a slow connection, increase the request timeout in SearXNG's settings.yml:

outgoing:
  request_timeout: 6.0   # seconds per engine
  max_request_timeout: 15.0

For self-hosted instances, you can also configure rate limiting to prevent upstream engines from blocking your IP:

server:
  limiter: true
  public_instance: false

Troubleshooting

Connection Refused

If OpenClaw can't reach your SearXNG instance:

• Verify SearXNG is running: docker ps | grep searxng
• Check the port is correct and not blocked by a firewall
• If using Docker, make sure both containers are on the same network or use the host's IP address instead of localhost
• Test the endpoint directly: curl "http://localhost:8080/search?q=test&format=json"

Slow Results

SearXNG queries multiple engines in parallel, so results depend on the slowest engine:

• Disable slow engines in settings.yml to speed things up
• Reduce the number of enabled engines — fewer engines means faster results
• Increase request_timeout if engines are timing out before responding
• Use categories to limit which engine categories are queried per search

Engine Errors

If specific engines return errors or no results:

• Check SearXNG's built-in stats page at /stats to see which engines are failing
• Some engines may block requests from certain IP ranges — try disabling those engines
• Update SearXNG to the latest version: docker pull searxng/searxng:latest and restart
• Verify the JSON format is enabled in your settings.yml

Use Search on OpenClaw Launch

Don't want to set up SearXNG yourself? OpenClaw Launch includes built-in web search out of the box — no SearXNG setup, no API keys, no Docker configuration. Your AI agent can search the web immediately after deployment.

The hosted platform handles all the search infrastructure for you, so you can focus on configuring your agent instead of managing search backends.

Frequently Asked Questions

Is SearXNG really free?

Yes. SearXNG is 100% free and open-source under the AGPL license. There are no API fees, no usage limits, and no hidden costs. The only expense is the server you run it on — which can be as cheap as $5/month for a small VPS, or free if you run it on hardware you already own.

Do I need a server to run SearXNG?

For self-hosting, yes — you need a machine that can run Docker. This can be a VPS, a home server, or even a Raspberry Pi. Alternatively, you can use a public SearXNG instance (available at searx.space) without running anything yourself, though public instances may be less reliable.

SearXNG vs Tavily — which should I use?

Use SearXNG if you want free, unlimited, private search and don't mind a bit more setup. Use Tavily if you want the highest-quality AI-optimized results with minimal configuration. Tavily is easier to set up (just an API key) but has usage limits on the free tier. SearXNG is completely free but requires Docker.

Can I use SearXNG with OpenClaw Launch?

OpenClaw Launch includes built-in web search, so you don't need SearXNG for the hosted platform. However, if you're running a self-hosted OpenClaw instance, SearXNG is an excellent free search backend to pair with it.

What's Next?

• Web search overview — Compare all search options available for OpenClaw
• Tavily search setup — AI-optimized search with minimal configuration
• Brave search setup — Privacy-focused search API alternative
• Explore all skills — Browse 3,200+ skills beyond search
• See pricing — Deploy with search pre-configured, starting at $3/month