Usage: search from OpenClaw, Telegram, or HTTP

01

Web UI

Open http://127.0.0.1:8080 on the host. Useful for checking engines and seeing the raw result page.

02

OpenClaw

Ask the agent to search. The plugin/provider decides when to call SearXNG and how many results to pass to the model.

03

HTTP JSON

Call /search?q=...&format=json from curl, a script, or another tool. No API key.

Through OpenClaw

Natural language, not a command grammar.

These are example requests, not a special syntax. OpenClaw decides whether to call the search tool and may rewrite the query. If the agent ignores the tool, check openclaw doctor and the tool policy for your setup.

Basic

Search for Rust async programming using SearXNG

Recency

Search for EU AI Act news with time_range: month

Reproduce exactly what the agent sees.

Parameter	Example	Notes
`q`	`rust async`	Required query string
`format`	`json`	Must be enabled in `search.formats`
`pageno`	`2`	Further result pages; engine support varies
`categories`	`it,science`	Comma-separated SearXNG categories
`language`	`en`	Result language where supported
`time_range`	`month`	Recency filter where the engine supports it
`engines`	`google`	Restrict to specific enabled engines
`safesearch`	`0`	0 off, 1 moderate, 2 strict (engine-dependent)

# Basic JSON search
curl -s "http://127.0.0.1:8080/search?q=python&format=json" | jq '.results[] | {title, url}'

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

# IT and science categories
curl -s "http://127.0.0.1:8080/search?q=rust&categories=it,science&format=json" | jq '.results | length'

# Recent results
curl -s "http://127.0.0.1:8080/search?q=climate&time_range=month&format=json" | jq '.results | length'

# One engine only
curl -s "http://127.0.0.1:8080/search?q=linux&engines=wikipedia&format=json" | jq '.results[] | .title'

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

Response shape

What comes back.

SearXNG returns a JSON object with metadata, a result array, and the list of engines that did not answer. This is a trimmed illustrative shape, not a captured response:

{
  "query": "rust async",
  "number_of_results": 0,
  "results": [
    {
      "url": "https://example.com/article",
      "title": "Result title",
      "content": "Snippet returned by the engine.",
      "engine": "google",
      "category": "general"
    }
  ],
  "answers": [],
  "unresponsive_engines": []
}

number_of_results is not a reliable total; some engines do not report one. Count the results array for what you actually received.

Field guide

Fields worth using

`results[].url`	Result target
`results[].title`	Display title
`results[].content`	Snippet text
`results[].engine`	Originating engine
`results[].category`	SearXNG category
`unresponsive_engines`	Engines that failed or timed out
`answers`	Instant answers, when available

Multi-page results

Pagination is real, but engine-dependent.

SearXNG accepts pageno=2, pageno=3, and so on. Not every upstream engine returns a full second page for every query, so expect the count to fall as page numbers rise.

for page in 1 2 3; do
  printf "page %s: " "$page"
  curl -s "http://127.0.0.1:8080/search?q=python&format=json&pageno=$page" \
    | jq '.results | length'
done

SearXNG pages are independent requests. Deduplicate results client-side if you combine pages.

Plugin limits

Know which layer caps you.

The searxng-search template requests defaultCount: 100 and sets enableMultiPage: true. Your installed plugin must support those keys.
OpenClaw's built-in provider caps a single call's count at 10 results and has no multi-page option.
SearXNG itself returns whatever each engine gives it for a page. There is no guarantee of 100 or 300 results.

Health checks

When a search looks wrong, isolate the layer.

# Is the service up?
sudo systemctl is-active searxng
redis-cli ping

# Does the API answer without the agent?
curl -s "http://127.0.0.1:8080/search?q=test&format=json" | jq '{results: (.results | length), unresponsive: .unresponsive_engines}'

# Does the agent see the plugin?
openclaw doctor 2>&1 | grep -i searxng

# Full suite
bash scripts/test-setup.sh

Failure Troubleshooting Zero results, HTML instead of JSON, Redis errors, plugin not loading. Trust boundary Untrusted results How OpenClaw wraps search content before the model sees it.

Ask the agent, or query the API directly.

Web UI

OpenClaw

HTTP JSON

Natural language, not a command grammar.

Reproduce exactly what the agent sees.

What comes back.

Fields worth using

Pagination is real, but engine-dependent.

Know which layer caps you.

When a search looks wrong, isolate the layer.