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, or (2) run web searches using an existing local SearXNG instance. Covers installation, configuration, the search.py CLI tool, and fallback behaviour. Use when the agent needs web search capability, when setting up a new OpenClaw instance, or when diagnosing search failures.

Audits

Pass

ClawScanPass

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install searxng-selfhost

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`