you.com Web Search
Free web search, deep research, and content extraction — no mandatory API key for basic search.
Tools
| Need | Tool | Cost | API Key |
|---|---|---|---|
| General web search | youcom_search | Free | ❌ |
| Deep research with citations | youcom_research | Paid | ✅ |
| Extract content from URLs | youcom_extract | Paid | ✅ |
Quick Start
Free Search (no setup)
python3 scripts/youcom_search.py "search query" --num 5
Research / Extract (requires API key)
export YOUCOM_API_KEY="your_key"
python3 scripts/youcom_research.py "topic" --depth deep
python3 scripts/youcom_extract.py https://example.com/article
Setup
Free Search
No setup required — youcom_search works immediately.
Research & Extract (Paid)
- Get an API key at you.com/platform/api-keys
- Add to
~/.openclaw/.env:YOUCOM_API_KEY=your_key_here - Restart the gateway:
systemctl --user restart openclaw-gateway
youcom_search — Free Web Search
Use for all general web searches. No API key needed.
python3 scripts/youcom_search.py "query" [--num N]
| Option | Description |
|---|---|
query | Search term (required) |
--num, -n | Results to return, 1–10 (default: 5) |
--out, -o | Write JSON to file instead of stdout |
Output: JSON with query, count, and results[] (title, url, description, snippets).
Tips:
- Supports search operators:
site:reddit.com,filetype:pdf,time:week - Results include social snippets when available
- Uses python3
urllib— no external dependencies
youcom_research — Deep Research (Paid)
Synthesized answer with citations. Requires YOUCOM_API_KEY.
python3 scripts/youcom_research.py "topic" [--depth lite|standard|deep|exhaustive]
| Option | Description |
|---|---|
query | Research topic (required) |
--depth, -d | lite, standard (default), deep, exhaustive |
⚠️ Always confirm cost with user before using paid endpoints.
youcom_extract — Content Extraction (Paid)
Extract clean text from specific URLs. Requires YOUCOM_API_KEY.
python3 scripts/youcom_extract.py <url> [<url>...] [--formats markdown html metadata] [--timeout 10]
| Option | Description |
|---|---|
urls | One or more URLs (space-separated) |
--formats, -f | Output formats: markdown, html, metadata (default: markdown metadata) |
--timeout, -t | Crawl timeout per URL in seconds 1–60 (default: 10) |
Max 20 URLs per call. Batch larger lists into multiple calls.
When to Use What
| Need | Tool |
|---|---|
| Quick lookup | youcom_search |
| Comprehensive analysis | youcom_research |
| Specific page content | youcom_extract |
| Cloudflare/GitHub blocks | youcom_search — bypasses them |
Escalation Order
youcom_search (free) → youcom_research (paid, confirm first) → youcom_extract (paid, confirm first)
When free search is insufficient, escalate to paid research.
Troubleshooting
"YOUCOM_API_KEY environment variable is not set"
The API key is not loaded. Source your .env or restart the gateway:
source ~/.openclaw/.env
systemctl --user restart openclaw-gateway
"HTTP Error 401 / 403"
Invalid or expired API key. Check or regenerate at you.com/platform/api-keys.
"HTTP Error 429"
Rate limit hit. Wait 30 seconds and retry.
"name or service not known"
DNS failure. Check internet connection.
Python Dependencies
No third-party dependencies. Uses Python standard library only:
urllib.request— HTTP GET/POSTurllib.parse— URL encodingjson— JSON parsingargparse— CLI argument parsing
API Endpoints Used
| Tool | Method | Endpoint |
|---|---|---|
youcom_search | GET | https://api.you.com/v1/agents/search |
youcom_research | POST | https://api.you.com/v1/research |
youcom_extract | POST | https://ydc-index.io/v1/contents |