186 lines
4.8 KiB
Markdown
186 lines
4.8 KiB
Markdown
# Tavily Web Search Skill for OpenClaw 🦀
|
|
|
|
A lightweight Tavily web search skill for OpenClaw that works without `pip` and without third-party Python packages.
|
|
|
|
This skill is designed for minimal Linux environments such as:
|
|
|
|
- Raspberry Pi
|
|
- Ubuntu Server
|
|
- small VPS setups
|
|
- systems where installing Python packages is unavailable, restricted, or intentionally avoided
|
|
|
|
Instead of using the `tavily-python` SDK, this skill calls the Tavily REST API directly using Python's standard library.
|
|
|
|
## Features
|
|
|
|
- Tavily web search through direct REST API calls
|
|
- No `pip install` required
|
|
- No external Python dependencies
|
|
- Works well on Raspberry Pi and Ubuntu Server
|
|
- Supports general search and news search
|
|
- Supports answer summaries, images, and domain filtering
|
|
- Easy to integrate into OpenClaw skills
|
|
- Simple secret-file based API key setup
|
|
|
|
## Why this version exists
|
|
|
|
The official Tavily Python SDK is convenient, but some environments do not have a practical or desirable `pip` workflow.
|
|
|
|
This skill exists for setups where you want:
|
|
|
|
- a small footprint
|
|
- no package installation step
|
|
- predictable deployment
|
|
- compatibility with minimal server environments
|
|
- a solution that keeps working even on systems where Python package installation is restricted
|
|
|
|
This is especially useful on Raspberry Pi, Ubuntu Server, and other minimal Linux systems where you may prefer to avoid virtual environments, extra package managers, or external Python dependencies for a simple search integration.
|
|
|
|
## Folder Structure
|
|
|
|
```text
|
|
skills/tavily/
|
|
├── SKILL.md
|
|
├── .secrets/
|
|
│ └── tavily.key
|
|
└── scripts/
|
|
└── tavily_search.py
|
|
```
|
|
|
|
## Secret Setup
|
|
|
|
Create the secret directory:
|
|
|
|
```bash
|
|
mkdir -p skills/tavily/.secrets
|
|
chmod 700 skills/tavily/.secrets
|
|
```
|
|
|
|
Create the key file:
|
|
|
|
```bash
|
|
nano skills/tavily/.secrets/tavily.key
|
|
```
|
|
|
|
The file must contain only your raw Tavily API key:
|
|
|
|
```
|
|
tvly-xxxxxxxxxxxxxxxx
|
|
```
|
|
|
|
Do **not** write:
|
|
|
|
```
|
|
TAVILY_API_KEY=tvly-xxxxxxxxxxxxxxxx
|
|
```
|
|
|
|
Set permissions:
|
|
|
|
```bash
|
|
chmod 600 skills/tavily/.secrets/tavily.key
|
|
```
|
|
|
|
## Usage
|
|
|
|
Basic search:
|
|
|
|
```bash
|
|
python3 skills/tavily/scripts/tavily_search.py --query "latest AI news"
|
|
```
|
|
|
|
News-focused search:
|
|
|
|
```bash
|
|
python3 skills/tavily/scripts/tavily_search.py --query "gold prices" --topic news
|
|
```
|
|
|
|
Advanced search:
|
|
|
|
```bash
|
|
python3 skills/tavily/scripts/tavily_search.py --query "raspberry pi ubuntu server optimization" --depth advanced
|
|
```
|
|
|
|
JSON output:
|
|
|
|
```bash
|
|
python3 skills/tavily/scripts/tavily_search.py --query "python asyncio" --json
|
|
```
|
|
|
|
## Supported Options
|
|
|
|
| Option | Description |
|
|
| ------------------- | ---------------------------- |
|
|
| `--query` | **required** search query |
|
|
| `--topic` | `general` or `news` |
|
|
| `--depth` | `basic` or `advanced` |
|
|
| `--max-results` | number of results |
|
|
| `--no-answer` | disable answer summary |
|
|
| `--raw-content` | include parsed raw content |
|
|
| `--images` | include image results |
|
|
| `--include-domains` | restrict to selected domains |
|
|
| `--exclude-domains` | filter out selected domains |
|
|
| `--json` | output raw JSON |
|
|
|
|
## OpenClaw Integration
|
|
|
|
This skill is meant to be used from OpenClaw through `SKILL.md`.
|
|
|
|
Typical usage flow:
|
|
|
|
1. The user asks for web search or recent information
|
|
2. OpenClaw invokes the Tavily skill
|
|
3. The skill runs `scripts/tavily_search.py`
|
|
4. The script reads the API key from `.secrets/tavily.key`
|
|
5. Results are returned in a format suitable for summarization
|
|
|
|
## Why no pip is required
|
|
|
|
This project intentionally avoids the Tavily Python SDK and other third-party dependencies.
|
|
|
|
That means:
|
|
|
|
- there is no `pip install` step
|
|
- there is no dependency on `tavily-python`
|
|
- there is no virtual environment requirement just to use the skill
|
|
- deployment stays simple on minimal systems
|
|
|
|
The script uses only Python's standard library to call the Tavily REST API directly.
|
|
|
|
## Security Notes
|
|
|
|
- The `.secrets` directory should never be committed
|
|
- Your API key should stay only on the target machine
|
|
- This repository should contain code and documentation only
|
|
- Add `.secrets/` to `.gitignore`
|
|
- Keep `tavily.key` readable only by the user or service that runs the skill
|
|
|
|
Example `.gitignore` entries:
|
|
|
|
```
|
|
.secrets/
|
|
__pycache__/
|
|
*.pyc
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- Python 3
|
|
- Network access to Tavily API
|
|
- A valid Tavily API key
|
|
- No additional Python packages are required
|
|
|
|
## Motivation
|
|
|
|
This project is especially useful for:
|
|
|
|
- Raspberry Pi home server setups
|
|
- Ubuntu Server deployments
|
|
- minimal VPS environments
|
|
- offline-managed or tightly controlled systems
|
|
- users who want Tavily search without SDK installation
|
|
- environments where `pip` is unavailable, restricted, or intentionally avoided
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
|