---
name: searxng-local-search
description: Search the web via the local self-hosted SearXNG instance and use Brave only as fallback. Use when gathering current information, docs, links, or fact checks, and when privacy/local-first search is preferred.
metadata:
  openclaw:
    requires:
      bins: ["bb"]
      env: ["SEARXNG_URL"]
    emoji: "🔍"
    nix:
      plugin: "babashka"
---

# SearXNG Local Search

## Policy (default behavior)

1. Use **SearXNG first** for normal web lookups.
2. Fall back to **Brave** only when:
   - SearXNG is unavailable,
   - SearXNG returns very weak/empty results,
   - or user explicitly asks for Brave/second opinion.
3. In research answers, label which source was used.

## Preconditions

- `SEARXNG_URL` points to the local instance.
- SearXNG JSON API is enabled.
- Script entrypoint is available: `scripts/search.sh`.

Preferred local value in this workspace is the LAN endpoint already documented in `TOOLS.md`.

## Quick usage

```bash
scripts/search.sh "your search query"
```

With options:

```bash
scripts/search.sh "your query" '{"category":"news","time_range":"week","num_results":8}'
```

Options:
- `category`: `general|news|images|videos|it|science`
- `time_range`: `day|week|month|year`
- `language`: ISO language code (default `en`)
- `num_results`: integer (default `5`)

## Smoke test routine

Run before first use in a fresh environment or after changes:

```bash
scripts/smoke.sh openclaw
```

Pass criteria:
- command exits successfully,
- returns at least one result,
- includes title + URL fields.

If smoke test fails:
1. Confirm `SEARXNG_URL` is reachable.
2. Confirm SearXNG container/service is healthy.
3. Retry with a broad query and no filters.
4. If still failing, switch to Brave fallback and report SearXNG incident.

## Troubleshooting

- **Connection/timeout**: verify endpoint + container health.
- **Empty results**: broaden query, remove filters, retry.
- **Bad JSON/format**: verify SearXNG JSON format support.
- **Rate concerns**: keep queries paced; avoid burst loops.

## Notes

- This skill defines behavior and checks; it does not replace the underlying SearXNG service deployment.
- For API details and response structure, see `references/api-guide.md`.