Installation

From bare Ubuntu to a local JSON search endpoint.

The automated path installs SearXNG, Redis, and a systemd service. A separate script connects the endpoint to OpenClaw. The manual path exposes every command.

Time15–30 minutes
HostUbuntu 20.04+ / Debian 11+
Accesssudo
AgentOpenClaw optional

The installer does not configure OpenClaw.

It installs the service and prints the next command. Run bash scripts/configure-openclaw.sh as the user that owns ~/.openclaw, without sudo.

Automated path

Four commands, with a verification step that tells the truth.

Clone the repository

git clone https://github.com/FiredMosquito831/searxng-openclaw-complete-setup.git
cd searxng-openclaw-complete-setup

02
Install SearXNG and Redis
```
sudo bash scripts/install-all.sh
```
The script installs apt dependencies, creates the searxng user, clones SearXNG, builds a virtual environment, writes settings, starts Redis, installs the systemd unit, and checks the JSON API.

On a re-run it preserves an existing /etc/searxng/settings.yml and writes a timestamped backup next to it.
03
Configure OpenClaw
```
bash scripts/configure-openclaw.sh
```
Run this as your OpenClaw user, without sudo. It backs up ~/.openclaw/openclaw.json, adds the search plugin block, validates the config, restarts the user gateway, and verifies the plugin is visible.

Plugin compatibility.
The script writes a searxng-search block for the plugin this project was built around. Newer OpenClaw releases use a built-in searxng provider with different keys. See Configuration for both shapes.
04
Verify the installation
```
bash scripts/test-setup.sh
```
The suite checks the service, Redis, the HTML endpoint, the JSON API, page 2, OpenClaw installation, plugin visibility, and disk space. Missing OpenClaw or an undetected plugin is a warning, not a failure.

Standalone SearXNG is then reachable at http://127.0.0.1:8080.

Prerequisites

What the host needs.

Resource	Minimum	Recommended
OS	Ubuntu 20.04 / Debian 11	Ubuntu 22.04+
RAM	512 MB	2 GB
Disk	1 GB free	5 GB free
CPU	1 core	2+ cores
Network	Outbound HTTPS	Broadband
Access	`sudo`	—
Agent	OpenClaw optional	OpenClaw with a SearXNG plugin

The installer checks /etc/os-release and refuses distributions other than Ubuntu and Debian. Windows is supported through WSL2 with an Ubuntu distribution. macOS is not covered by these scripts.

Manual path

Install every component yourself.

Use this path when you want to inspect each step, change paths, or debug a failed automated install. These commands are the same work the installer performs.

0. Check the host

cat /etc/os-release
free -h
df -h /
sudo whoami

1. Install dependencies

sudo apt update

sudo apt install -y \
    python3 \
    python3-pip \
    python3-venv \
    redis-server \
    build-essential \
    libxslt1-dev \
    zlib1g-dev \
    libffi-dev \
    libssl-dev \
    git \
    curl \
    wget \
    jq

2. Create the user and directories

sudo useradd --shell /bin/bash --system \
    --home-dir "/usr/local/searxng" \
    --comment "SearXNG user" \
    searxng

sudo mkdir -p /usr/local/searxng /etc/searxng
sudo chown -R searxng:searxng /usr/local/searxng /etc/searxng

3. Clone SearXNG

sudo -u searxng -i << 'EOF'
cd /usr/local/searxng
git clone https://github.com/searxng/searxng.git searxng-src
EOF

4. Create the virtual environment

sudo -u searxng -i << 'EOF'
cd /usr/local/searxng
python3 -m venv searx-pyenv
source /usr/local/searxng/searx-pyenv/bin/activate
pip install --upgrade pip setuptools wheel pyyaml
EOF

5. Install SearXNG

sudo -u searxng -i << 'EOF'
cd /usr/local/searxng/searxng-src
source /usr/local/searxng/searx-pyenv/bin/activate
pip install --use-pep517 --no-build-isolation -e .
EOF

6. Write the configuration

The minimum needed for OpenClaw is JSON output, loopback binding, Redis, and a secret key.

SECRET_KEY=$(openssl rand -hex 32)
sudo bash -c "cat > /etc/searxng/settings.yml << SETTINGS
use_default_settings:
  engines:
    keep_only:
      - google
      - duckduckgo
      - brave
      - bing
      - wikipedia
      - github
      - youtube

general:
  debug: false
  instance_name: \"SearXNG\"
  enable_metrics: true

search:
  safe_search: 0
  autocomplete: \"google\"
  default_lang: \"en\"
  formats:
    - html
    - json

server:
  secret_key: \"$SECRET_KEY\"
  limiter: false
  image_proxy: true
  http_protocol_version: \"1.0\"
  bind_address: \"127.0.0.1\"
  port: 8080
  base_url: false

redis:
  url: \"redis://localhost:6379/0\"

ui:
  default_theme: simple
  default_locale: \"en\"
  query_in_title: true
  infinite_scroll: true
  center_alignment: true
  results_on_new_tab: true

outgoing:
  request_timeout: 10.0
  max_request_timeout: 30.0
  useragent_suffix: \"\"
  pool_connections: 100
  pool_maxsize: 50
  enable_http2: true

engines:
  - name: google
    engine: google
    shortcut: g
    disabled: false
  - name: duckduckgo
    engine: duckduckgo
    shortcut: d
    disabled: false
  - name: brave
    engine: brave
    shortcut: b
    disabled: false
  - name: bing
    engine: bing
    shortcut: i
    disabled: false
  - name: wikipedia
    engine: wikipedia
    shortcut: w
    disabled: false
  - name: github
    engine: github
    shortcut: gh
    disabled: false
  - name: youtube
    engine: youtube
    shortcut: yt
    disabled: false
SETTINGS
"

sudo chown searxng:searxng /etc/searxng/settings.yml

The repository also has an annotated settings.yml.template with two news engines added.

7. Start Redis

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

Expected: PONG.

8. Create the systemd unit

sudo bash -c "cat > /etc/systemd/system/searxng.service << 'SERVICE'
[Unit]
Description=SearXNG Privacy-Respecting Metasearch Engine
After=network.target redis-server.service
Wants=redis-server.service

[Service]
Type=simple
User=searxng
Group=searxng
WorkingDirectory=/usr/local/searxng/searxng-src

Environment=\"SEARXNG_SETTINGS_PATH=/etc/searxng/settings.yml\"
Environment=\"PYTHONPATH=/usr/local/searxng/searxng-src\"

ExecStart=/usr/local/searxng/searx-pyenv/bin/python -m searx.webapp --port 8080 --bind 127.0.0.1

Restart=always
RestartSec=10
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
SERVICE
"

sudo systemctl daemon-reload
sudo systemctl enable --now searxng.service

9. Configure OpenClaw

Install or select a SearXNG plugin/provider for your OpenClaw release. This repository supplies the configuration, not the plugin package.

mkdir -p ~/.openclaw
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup 2>/dev/null || true
nano ~/.openclaw/openclaw.json

Add the block for the searxng-search plugin:

{
  "plugins": {
    "entries": {
      "searxng-search": {
        "enabled": true,
        "config": {
          "baseUrl": "http://localhost:8080",
          "timeoutMs": 60000,
          "defaultCount": 100,
          "enableMultiPage": true
        }
      }
    }
  }
}

Then restart the gateway as your user:

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

Using the built-in provider instead? See the alternative configuration.

10. Verify

sudo systemctl status searxng --no-pager
redis-cli ping
curl -s "http://127.0.0.1:8080/search?q=test&format=json" | jq '.results | length'
curl -s "http://127.0.0.1:8080/search?q=test&format=json" | jq '.unresponsive_engines'

A positive result count means the JSON API is working. Exact counts vary by engine availability and upstream rate limits.

Post-install checks

Confirm the service, the API, and the agent.

# Services
sudo systemctl status searxng --no-pager
redis-cli ping

# JSON API and failed engines
curl -s "http://127.0.0.1:8080/search?q=test&format=json" | jq '{results: (.results | length), unresponsive: .unresponsive_engines}'

# OpenClaw integration
openclaw doctor 2>&1 | grep -i searxng

# Full suite
bash scripts/test-setup.sh

If something fails Troubleshooting guide Service failures, port conflicts, JSON errors, Redis, plugin visibility. Next Configuration reference Engines, Redis, timeouts, and both OpenClaw config shapes.