brave-headless
Headless web search and content extraction via the Brave Search API. Features exponential-backoff retry, circuit breaker fault isolation, bounded-concurrency parallel page fetching, structured leveled logging, and smart paragraph-boundary truncation. No browser required. Use for web research, documentation lookup, URL content extraction, and any workflow requiring scriptable, non-interactive web search.
Install via CLI (Recommended)
clawhub install openclaw/skills/skills/kelexine/brave-headlessbrave-search
Headless web search and content extraction via the Brave Search API.
Setup
Run once before first use:
cd <skill-root>
npm ci
Required environment variable:
export BRAVE_API_KEY="your-key-here"
Get a free API key at brave.com/search/api.
Usage
Search
node scripts/search.js "query" # Basic (5 results)
node scripts/search.js "query" -n 10 # Up to 20 results
node scripts/search.js "query" --content # Include page content
node scripts/search.js "query" -n 3 --content # Combined
node scripts/search.js "query" --json # Newline-delimited JSON
node scripts/search.js --help # Full options + env vars
Extract page content
node scripts/content.js https://example.com/article
node scripts/content.js https://example.com/article --json
node scripts/content.js https://example.com/article --max-length 8000
Output format (plain text)
--- Result 1 ---
Title: Page Title
URL: https://example.com/page
Snippet: Description from Brave Search
Content:
# Page Title
Extracted markdown content...
--- Result 2 ---
...
Pass --json to get one JSON object per line instead, suitable for piping.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Invalid input or configuration error |
2 | Page had no extractable content (content.js) |
130 | Interrupted (SIGINT) |
Configuration (environment variables)
All behaviour is configurable without touching code:
| Variable | Default | Description |
|---|---|---|
BRAVE_API_KEY | — | Required. Brave Search subscription token |
LOG_LEVEL | info | debug · info · warn · error · silent |
LOG_JSON | false | Emit logs as newline-delimited JSON to stderr |
FETCH_TIMEOUT_MS | 15000 | Per-page fetch timeout |
SEARCH_TIMEOUT_MS | 10000 | Brave API call timeout |
MAX_CONTENT_LENGTH | 5000 | Max chars of extracted content |
MAX_RETRY_ATTEMPTS | 3 | Retry attempts on transient errors |
RETRY_BASE_DELAY_MS | 500 | Base delay for exponential backoff |
RETRY_MAX_DELAY_MS | 30000 | Backoff delay cap |
CONCURRENCY_LIMIT | 3 | Parallel page fetches when --content is set |
CB_FAILURE_THRESHOLD | 5 | Consecutive failures before circuit opens |
CB_RESET_TIMEOUT_MS | 60000 | Circuit breaker reset window... |
Metadata
Not sure this is the right skill?
Describe what you want to build — we'll match you to the best skill from 16,000+ options.
Find the right skillPaste this into your clawhub.json to enable this plugin.
{
"plugins": {
"official-kelexine-brave-headless": {
"enabled": true,
"auto_update": true
}
}
}