SearXNG Self-Host

Self-hosted web search aggregator for OpenClaw agents. Use this skill to (1) install SearXNG on a VPS/server so the agent can search the web without API keys...

SearXNG

SearXNG is a self-hosted search aggregator that queries Google, Bing, Brave, Startpage, DuckDuckGo, and Wikipedia simultaneously. No API keys required. Results returned as JSON.

Quick start (already installed)

python3 scripts/search.py "your query"             # human-readable
python3 scripts/search.py "your query" --json      # JSON (for parsing)
python3 scripts/search.py "query" --count 5 --json # limit + JSON

Place search.py anywhere convenient — typically tools/search.py in the workspace.

For detailed usage patterns and service management: see references/usage.md.

Installation (new instance)

Run as root on Ubuntu 22.04/24.04:

bash scripts/install_searxng.sh

This installs SearXNG, creates a searxng system user, writes /etc/searxng/settings.yml, and starts a systemd service on http://127.0.0.1:8888.

Verify:

curl 'http://127.0.0.1:8888/search?q=test&format=json' | python3 -m json.tool | head -20
systemctl status searxng

Connecting search.py to the instance

search.py targets http://127.0.0.1:8888 by default. If the port differs, update SEARXNG_URL at the top of the script.

Fallback

If SearXNG is down, search.py falls back to Wikipedia + GitHub APIs automatically. No action needed — results still return, just from narrower sources.

Troubleshooting

Symptom	Fix
[SearXNG unavailable] in stderr	systemctl restart searxng
Port conflict on 8888	Change port: in /etc/searxng/settings.yml + update SEARXNG_URL in script
Empty results from all engines	Check /etc/searxng/settings.yml engines block; restart service
Connection refused	Service not running — systemctl start searxng