OpenClaw Research Tool

Web search for OpenClaw agents, powered by OpenRouter. Ask questions in natural language, get accurate answers with cited sources. Defaults to GPT-5.2 which excels at documentation lookups and citation-heavy research.

Note: Even low-effort queries may take 1 minute or more to complete. High/xhigh reasoning can take 10+ minutes depending on complexity. This is normal — the model is searching the web, reading pages, and synthesizing an answer.

For OpenClaw agents: Run research-tool in a sub-agent so your main session stays responsive while the search runs:

sessions_spawn task:"research-tool 'your query here'"

⚠️ Never set a timeout on exec when running research-tool. Queries routinely take 1-10+ minutes. Use yieldMs to background it, then poll — but do NOT set timeout or the process will be killed mid-search.

research-tool "How do I set reasoning effort parameters on OpenRouter?"

Built on OpenRouter, which gives any model live web search via the :online suffix. The default model is openai/gpt-5.2:online, but you can use any model OpenRouter supports.

Install

cargo install --path .

Setup

Get an API key from OpenRouter and set it in your environment:

export OPENROUTER_API_KEY="sk-or-v1-..."

Or add it to a .env file in your working directory.

Usage

Search in natural language — write your query the way you'd ask a person:

# Simple question
research-tool "What are the x.com API rate limits?"

# Deep analysis
research-tool --effort xhigh "Compare tradeoffs between Opus 4.6 and gpt-5.3-codex for programming"

# Quick fact check
research-tool --effort low "What year was Rust 1.0 released?"

# Custom persona
research-tool -s "You are a senior infrastructure engineer" "Best practices for zero-downtime Kubernetes deployments"

# Use a different model
research-tool -m "anthropic/claude-sonnet-4-20250514:online" "Summarize recent changes to the OpenAI API"

# Pipe from stdin
cat question.txt | research-tool --stdin

# Save output (response goes to stdout, metadata to stderr)
research-tool "Explain the React Server Components architecture" > output.md

Options

How it works

1. Your query is sent to OpenRouter's chat completions API
2. The :online model variant enables live web search — the model browses the web, reads pages, and synthesizes an answer
3. Response text goes to stdout (pipe-friendly), reasoning traces and token stats go to stderr
4. Connection status is printed so you know if the search is still running or failed

Tips

• Write naturally. "What are the best practices for Rust error handling?" works better than keyword-style queries.
• Provide context. The model starts from zero — the more detail you give, the better the answer. A 200-word question with background context will outperform a 5-word question.
• Use effort levels. --effort low for quick lookups (~1-3 min), --effort xhigh for deep research (5-20+ min).
• Any model works with :online. Try anthropic/claude-opus-4-6:online or google/gemini-2.5-pro:online for different perspectives.

Output

🔍 Researching with openai/gpt-5.2:online (effort: high)...
✅ Connected — waiting for response...

[response text to stdout]

📊 Tokens: 4470 prompt + 184 completion = 4654 total | ⏱ 5s

Cost

Roughly $0.01–0.05 per query depending on response length and reasoning effort. Token usage is printed after each query.

License

MIT