Perplexity Wrapped Search
by @vacinc
Search the web with AI-powered answers via Perplexity API. Supports three modes - Search API (ranked results), Sonar API (AI answers with citations, default), and Agentic Research API (third-party models with tools). All responses wrapped in untrusted-content boundaries for security.
clawhub install perplexity-wrappedš About This Skill
name: perplexity_wrapped description: Search the web with AI-powered answers via Perplexity API. Supports three modes - Search API (ranked results), Sonar API (AI answers with citations, default), and Agentic Research API (third-party models with tools). All responses wrapped in untrusted-content boundaries for security. homepage: https://docs.perplexity.ai metadata: {"openclaw":{"emoji":"š®","requires":{"bins":["node"]}}}
Perplexity Wrapped Search
AI-powered web search with three distinct API modes for different use cases.
Quick Start
Default mode (Sonar) - AI answer with citations:
node {baseDir}/scripts/search.mjs "what's happening in AI today"
Search mode - ranked results:
node {baseDir}/scripts/search.mjs "latest AI news" --mode search
Deep research - comprehensive analysis (requires --yes):
node {baseDir}/scripts/search.mjs "compare quantum computing approaches" --deep --yes
API Modes
1. Sonar API (DEFAULT)
AI-generated answers with web grounding and citations. Best for natural language queries.
Models:
sonar (default) - Fast, web-grounded responses (~$0.01/query)sonar-pro - Higher quality, more thorough (~$0.02/query)sonar-reasoning-pro - Advanced reasoning capabilitiessonar-deep-research - Comprehensive research mode (~$0.40-1.30/query)Examples:
# Default sonar
node {baseDir}/scripts/search.mjs "explain quantum entanglement"Sonar Pro (higher quality)
node {baseDir}/scripts/search.mjs "analyze 2024 tech trends" --proDeep Research (comprehensive)
node {baseDir}/scripts/search.mjs "future of renewable energy" --deepSpecific model
node {baseDir}/scripts/search.mjs "query" --model sonar-reasoning-pro
Output format:
<<>>
Source: Web Search
[AI-generated answer text with inline context]Citations
[1] Title
https://example.com/source1
[2] Title
https://example.com/source2
<<>>
2. Search API
Ranked web search results with titles, URLs, and snippets. Best for finding specific sources.
Cost: ~$0.005 per query
Examples:
# Single query
node {baseDir}/scripts/search.mjs "best coffee shops NYC" --mode searchBatch queries (multiple in one API call)
node {baseDir}/scripts/search.mjs "query 1" "query 2" "query 3" --mode search
Output format:
<<>>
Source: Web Search
Result Title
https://example.com/url
Snippet text from the page...Another Result
https://example.com/url2
Another snippet...
<<>>
3. Agentic Research API
Advanced mode with third-party models (OpenAI, Anthropic, Google, xAI), web_search and fetch_url tools, and structured outputs.
Options:
--reasoning low|medium|high - Control reasoning effort for reasoning models--instructions "..." - System instructions for the model--model - Model selection (default: openai/gpt-5-mini)Available Models:
| Provider | Model | Input $/1M | Output $/1M |
|----------|-------|-----------|------------|
| Perplexity | perplexity/sonar | $0.25 | $2.50 |
| OpenAI | openai/gpt-5-mini ā | $0.25 | $2.00 |
| OpenAI | openai/gpt-5.1 | $1.25 | $10.00 |
| OpenAI | openai/gpt-5.2 | $1.75 | $14.00 |
| Anthropic | anthropic/claude-haiku-4-5 | $1.00 | $5.00 |
| Anthropic | anthropic/claude-sonnet-4-5 | $3.00 | $15.00 |
| Anthropic | anthropic/claude-opus-4-5 | $5.00 | $25.00 |
| Google | google/gemini-2.5-flash | $0.30 | $2.50 |
| Google | google/gemini-2.5-pro | $1.25 | $10.00 |
| Google | google/gemini-3-flash-preview | $0.50 | $3.00 |
| Google | google/gemini-3-pro-preview | $2.00 | $12.00 |
| xAI | xai/grok-4-1-fast-non-reasoning | $0.20 | $0.50 |
Examples:
# Basic agentic query
node {baseDir}/scripts/search.mjs "analyze climate data" --mode agenticWith high reasoning effort
node {baseDir}/scripts/search.mjs "solve complex problem" --mode agentic --reasoning highWith custom instructions
node {baseDir}/scripts/search.mjs "research topic" --mode agentic --instructions "Focus on academic sources"Custom model
node {baseDir}/scripts/search.mjs "query" --mode agentic --model "anthropic/claude-3.5-sonnet"
Output format:
<<>>
Source: Web Search
[AI-generated output with inline citation markers]Citations
[1] Citation Title
https://example.com/source
<<>>
CLI Reference
node {baseDir}/scripts/search.mjs [options]MODES:
--mode search Search API - ranked results (~$0.005/query)
--mode sonar Sonar API - AI answers [DEFAULT] (~$0.01/query)
--mode agentic Agentic Research API - third-party models with tools
SONAR OPTIONS:
--model sonar | sonar-pro | sonar-reasoning-pro | sonar-deep-research
--deep Shortcut for --mode sonar --model sonar-deep-research (requires --yes)
--yes, -y Confirm expensive operations (required for --deep)
--pro Shortcut for --model sonar-pro
AGENTIC OPTIONS:
--reasoning low | medium | high
--instructions "..." System instructions for model behavior
--model Third-party model (default: openai/gpt-5-mini)
See "Available Models" above for full list
GENERAL OPTIONS:
--json Output raw JSON (debug mode, unwrapped)
--help, -h Show help message
Cost Guide
Estimates assume a typical query (~500 input tokens, ~500 output tokens).
Sonar API (token cost + per-request fee)
| Model | Est. Cost/Query | Breakdown |
|-------|----------------|-----------|
| sonar | ~$0.006 | $0.001 tokens + $0.005 request fee |
| sonar-pro | ~$0.015 | $0.009 tokens + $0.006 request fee |
| sonar-reasoning-pro | ~$0.011 | $0.005 tokens + $0.006 request fee |
| sonar-deep-research ā ļø | ~$0.41-1.32 | Tokens + citations + reasoning + 18-30 searches |
Request fees vary by search context size (low/medium/high). Estimates above use low context.
Agentic API (token cost + $0.005/web_search + $0.0005/fetch_url)
| Model | Est. Cost/Query | Notes |
|-------|----------------|-------|
| xai/grok-4-1-fast-non-reasoning | ~$0.005 | Cheapest, fastest |
| perplexity/sonar | ~$0.006 | |
| openai/gpt-5-mini ā | ~$0.006 | Default ā best value |
| google/gemini-2.5-flash | ~$0.006 | |
| google/gemini-3-flash-preview | ~$0.007 | |
| anthropic/claude-haiku-4-5 | ~$0.008 | |
| openai/gpt-5.1 | ~$0.011 | |
| google/gemini-2.5-pro | ~$0.011 | |
| google/gemini-3-pro-preview | ~$0.012 | |
| openai/gpt-5.2 | ~$0.013 | |
| anthropic/claude-sonnet-4-5 | ~$0.014 | |
| anthropic/claude-opus-4-5 | ~$0.020 | Most expensive |
Agentic costs scale with tool usage ā complex queries may trigger multiple web_search/fetch_url calls.
Search API
| API | Cost | |-----|------| | Search API | ~$0.005/query (flat $5/1K requests) |
ā ļø Deep Research Cost Gate
Deep Research mode requires --yes flag (or interactive TTY confirmation) due to high cost (~$0.40-1.32 per query). Without it, the script exits with a cost warning.
API Key Configuration
Set your Perplexity API key in OpenClaw config:
{
"skills": {
"entries": {
"perplexity_wrapped": {
"enabled": true,
"apiKey": "pplx-your-key-here"
}
}
}
}
OpenClaw sets PERPLEXITY_API_KEY env var from this config value. You can also export it manually.
Security
All output modes (except --json) wrap results in untrusted-content boundaries:
<<>>
Source: Web Search
[content]
<<>>
Security features:
--json requires explicit opt-inBest practices:
--json only when you need raw payloads for debuggingLimitations
Advanced Usage
Custom model with agentic mode:
node {baseDir}/scripts/search.mjs "complex analysis" \
--mode agentic \
--model "openai/o1" \
--reasoning high \
--instructions "Provide step-by-step reasoning"
Raw JSON for debugging:
node {baseDir}/scripts/search.mjs "query" --json
Batch search queries:
node {baseDir}/scripts/search.mjs \
"What is AI?" \
"Latest tech news" \
"Best restaurants NYC" \
--mode search
API Documentation
Troubleshooting
"Could not resolve API key"
PERPLEXITY_API_KEY env var is setapiKey is set in OpenClaw config under skills.entries.perplexity_wrapped"Invalid mode" error
search, sonar, agentic"Invalid reasoning level" error
low, medium, highCost concerns
Version History
2.1.0 - Agentic API fix + 1Password integration
/v2/responses instead of /chat/completions)openai/gpt-5-mini (gpt-4o deprecated on Perplexity)op CLI) integration for API key resolutionconfig.mjs from search.mjs for security scanner compatibility2.0.0 - Multi-API support
--deep and --pro shortcuts1.0.0 - Initial release
š” Examples
Default mode (Sonar) - AI answer with citations:
node {baseDir}/scripts/search.mjs "what's happening in AI today"
Search mode - ranked results:
node {baseDir}/scripts/search.mjs "latest AI news" --mode search
Deep research - comprehensive analysis (requires --yes):
node {baseDir}/scripts/search.mjs "compare quantum computing approaches" --deep --yes
š Tips & Best Practices
"Could not resolve API key"
PERPLEXITY_API_KEY env var is setapiKey is set in OpenClaw config under skills.entries.perplexity_wrapped"Invalid mode" error
search, sonar, agentic"Invalid reasoning level" error
low, medium, highCost concerns