Isolate the layer, then fix it.

Active: failed (Result: exit-code)

sudo journalctl -u searxng -n 100 --no-pager

Common causes: port 8080 is in use, Redis is down, settings.yml is invalid, or file ownership is wrong.

Port conflict

sudo lsof -i :8080
# or
sudo ss -ltnp | grep :8080

Stop the conflicting service. To move SearXNG instead, change server.port and the --port value in the unit's ExecStart, then:

sudo systemctl daemon-reload
sudo systemctl restart searxng

Redis down

sudo systemctl start redis-server
sudo systemctl restart searxng

Invalid YAML

python3 -c "import yaml; yaml.safe_load(open('/etc/searxng/settings.yml'))"
sudo nano /etc/searxng/settings.yml
sudo systemctl restart searxng

Ownership

sudo chown -R searxng:searxng /usr/local/searxng /etc/searxng
sudo chmod 644 /etc/searxng/settings.yml
sudo systemctl restart searxng

curl "...format=json" returns <!doctype html>.

Enable JSON output in /etc/searxng/settings.yml:

search:
  formats:
    - html
    - json

sudo systemctl restart searxng
curl -s "http://127.0.0.1:8080/search?q=test&format=json" | jq '.results | length'

The same symptom appears when the plugin's baseUrl reaches an HTML page instead of SearXNG.

.results | length is 0.

Check which engines failed

curl -s "http://127.0.0.1:8080/search?q=test&format=json" | jq '.unresponsive_engines'

Confirm an engine is enabled

engines:
  - name: google
    engine: google
    disabled: false

Check outbound network and clock

curl -I https://www.google.com
ping -c 3 duckduckgo.com
timedatectl

Upstream engines may temporarily throttle your server. Wait and retry, or disable the failing engine. There is no fixed warmup period.

Error 111 connecting to localhost:6379. Connection refused.

sudo systemctl start redis-server
sudo systemctl enable redis-server
redis-cli ping

If it still fails, inspect the Redis unit and config:

sudo systemctl status redis-server --no-pager
sudo journalctl -u redis-server -n 50 --no-pager
sudo nano /etc/redis/redis.conf

Confirm bind 127.0.0.1 and port 6379, then restart both services.

OSError: [Errno 98] Address already in use

sudo lsof -i :8080
# or
sudo ss -ltnp | grep :8080

Stop the conflicting process, or move SearXNG to 8081 in both settings.yml and the unit's --port argument. If you move it, update the OpenClaw baseUrl too.

sudo systemctl daemon-reload
sudo systemctl restart searxng

openclaw doctor 2>&1 | grep -i searxng returns nothing.

Check the block for your release

For the plugin this repository targets:

{
  "plugins": {
    "entries": {
      "searxng-search": {
        "enabled": true,
        "config": {
          "baseUrl": "http://localhost:8080"
        }
      }
    }
  }
}

Newer OpenClaw releases use the built-in searxng provider and keys under plugins.entries.searxng.config.webSearch. See Configuration.

openclaw doctor
openclaw doctor --fix
systemctl --user restart openclaw-gateway.service
openclaw doctor 2>&1 | grep -i searxng

Confirm SearXNG answers on the configured URL:

curl -s "http://localhost:8080/search?q=test&format=json" | jq '.results | length'

Error: prompt too large for the model

Reduce result volume first. For the searxng-search plugin:

{
  "plugins": {
    "entries": {
      "searxng-search": {
        "config": {
          "defaultCount": 25
        }
      }
    }
  }
}

For the built-in provider, lower tools.web.search.maxResults and keep per-call count small. Then keep compaction enabled:

{
  "compaction": {
    "reserveTokensFloor": 80000,
    "softThresholdTokens": 15000
  }
}

Restart the gateway. Key names vary by release; check openclaw doctor.

pageno=2 returns an empty result array.

Not every engine supports pagination, and rate limiting can remove page 2. Try another query or a single engine:

curl -s "http://127.0.0.1:8080/search?q=python&format=json&pageno=2" | jq '.results | length'
curl -s "http://127.0.0.1:8080/search?q=python&format=json&pageno=2&engines=google" | jq '.results | length'

If your SearXNG version supports search.max_page, you can raise the page limit:

search:
  max_page: 10

If the key is rejected, remove it and use the default pagination behavior.

Search takes more than roughly ten seconds.

• Disable engines you do not need.
• Inspect unresponsive_engines; one blocked engine can hold the response.
• Lower outgoing.request_timeout and max_request_timeout.
• Reduce pool sizes on a small host.
• Check free -h, df -h /, and uptime.

outgoing:
  request_timeout: 5.0
  max_request_timeout: 15.0
  pool_connections: 50
  pool_maxsize: 25

No benchmark in this repository promises a specific latency. Measure your own engine set.

PermissionError: [Errno 13] Permission denied

sudo chown -R searxng:searxng /usr/local/searxng
sudo chown -R searxng:searxng /etc/searxng
sudo chmod 755 /usr/local/searxng
sudo chmod 644 /etc/searxng/settings.yml
sudo systemctl restart searxng

Do not run the SearXNG service as root. The supplied unit uses the searxng user.

This is intentional. On a re-run, install-all.sh does not overwrite /etc/searxng/settings.yml; it writes a timestamped backup and prints the path.

ls -l /etc/searxng/settings.yml*
sudo diff -u /etc/searxng/settings.yml.bak.YYYYMMDD-HHMMSS /etc/searxng/settings.yml
sudo nano /etc/searxng/settings.yml
sudo systemctl restart searxng

The update script fast-forwards the branch checked out in /usr/local/searxng/searxng-src. Failure usually means local modifications or a diverged checkout.

sudo -u searxng -i
cd /usr/local/searxng/searxng-src
git status
git branch --show-current
git log --oneline -5
exit

Back up local changes before resetting. SearXNG's upstream default branch is master.