Universal travel planning skill for OpenClaw agents
Plan itineraries, check weather, discover attractions, and estimate budgets — all through natural conversation.
Quick Start
Installation
# Install via ClawHub
clawhub install Asif2BD/openclaw-tour-planner
# Or via OpenClaw CLI
openclaw skills install openclaw-tour-planner
Or clone manually
git clone https://github.com/Asif2BD/openclaw.tours.git cd openclaw.tours npm install
### Usage
User: Plan a 5-day trip to Tokyo in April Agent: I'll create a personalized itinerary for Tokyo. Let me gather the latest information...
[Agent generates day-by-day plan with weather, attractions, and budget estimates]
---
## Capabilities
### Core Features
| Feature | Description | Data Source |
|---------|-------------|-------------|
| **Itinerary Planning** | Day-by-day trip plans | Wikivoyage + OSM |
| **Weather Forecasts** | 15-day weather outlook | Visual Crossing |
| **Geocoding** | Location lookup | Nominatim |
| **Budget Estimation** | Cost breakdown by category | Local data + APIs |
| **Attraction Discovery** | Top sights and hidden gems | Wikivoyage |
| **Cultural Tips** | Local customs and etiquette | Wikivoyage |
### Commands
| Command | Description | Example |
|---------|-------------|---------|
| `plan` | Generate full itinerary | `/tour plan Tokyo 5 days in April` |
| `weather` | Get destination weather | `/tour weather Tokyo next week` |
| `budget` | Estimate trip costs | `/tour budget Tokyo 5 days mid-range` |
| `attractions` | Find things to do | `/tour attractions Tokyo family-friendly` |
| `guide` | Get destination guide | `/tour guide Tokyo` |
---
## Architecture
### Data Flow
User Request │ ▼ ┌─────────────────┐ │ Input Parser │ ──→ Extract: destination, dates, budget, interests └────────┬────────┘ │ ┌────┴────┐ ▼ ▼ ┌────────┐ ┌────────┐ │Geocode │ │Weather │ │Nominatim│ │Visual │ └───┬────┘ │Crossing│ │ └───┬────┘ │ │ └────┬─────┘ ▼ ┌─────────────────┐ │ Wikivoyage API │ ──→ Travel guide, attractions, tips └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Itinerary Engine│ ──→ Build day-by-day plan └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Output Formatter│ ──→ Markdown / JSON / Text └─────────────────┘
### API Integrations
#### Free Tier APIs (No Cost)
| Service | Purpose | Limits |
|---------|---------|--------|
| **Nominatim** | Geocoding | 1 req/sec |
| **Visual Crossing** | Weather | 1000 records/day |
| **Wikivoyage** | Travel guides | Unlimited |
| **RestCountries** | Country info | Unlimited |
| **ExchangeRate-API** | Currency | 1500 req/month |
---
## Configuration
### Environment Variables
```bash
# Optional — improves weather accuracy (free tier available at visualcrossing.com)
# Core features work without any keys using Open-Meteo (free, keyless)
VISUAL_CROSSING_API_KEY=your_key_here
# Optional — alternative weather source
OPENWEATHER_API_KEY=backup_weather_key
# Optional — flight search (Phase 2, not yet implemented in current release)
AMADEUS_API_KEY=flight_search_key
AMADEUS_API_SECRET=flight_search_secret
# Optional — redirect the local SQLite response cache (default: ~/.openclaw/cache/tour-planner.db)
TOUR_PLANNER_CACHE_PATH=/custom/path/tour-planner.db
Skill Config (openclaw.json)
{
"skills": {
"tour-planner": {
"enabled": true,
"config": {
"defaultBudget": "mid-range",
"cacheEnabled": true,
"cachePath": "./cache/tour-planner.db"
}
}
}
}
Output Formats
Markdown Itinerary (Default)
# 5-Day Tokyo Adventure
## Overview
- **Dates:** April 15-19, 2025
- **Weather:** 18-22°C, partly cloudy
- **Budget:** $1,200-1,800 (excl. flights)
## Day 1: Arrival & Shibuya
### Morning
- **10:00** Arrive at Narita/Haneda
- **12:00** Airport Express to Shibuya
- **Activity:** Shibuya Crossing + Hachiko
### Afternoon
- **14:00** Lunch at Genki Sushi
- **16:00** Meiji Shrine walk
### Evening
- **19:00** Dinner in Nonbei Yokocho
JSON (For Agent Processing)
{
"destination": "Tokyo",
"duration_days": 5,
"weather_summary": {...},
"days": [...],
"budget_breakdown": {...},
"packing_list": [...]
}
Development
Setup
# Clone repository
git clone https://github.com/Asif2BD/openclaw.tours.git
cd tour-planner
# Install dependencies
npm install
# Run tests
npm test
# Build
npm run build
Project Structure
tour-planner/
├── src/
│ ├── apis/ # API clients
│ │ ├── nominatim.ts
│ │ ├── weather.ts
│ │ └── wikivoyage.ts
│ ├── planners/ # Planning engines
│ │ ├── itinerary.ts
│ │ └── budget.ts
│ ├── utils/ # Utilities
│ │ ├── cache.ts
│ │ └── formatter.ts
│ └── data/ # Static data
│ └── countries.json
├── tests/
├── docs/
└── package.json
Roadmap
Phase 1: MVP (Complete)
- Basic itinerary generation
- Weather integration
- Wikivoyage guides
- Markdown output
Phase 2: Enhanced (In Progress)
- Flight search (Amadeus API)
- Hotel price estimates
- Multi-city optimization
- PDF export
Phase 3: Advanced (Planned)
- Real-time events
- Restaurant reservations
- Collaborative planning
- Mobile app wrapper
Contributing
We welcome contributions! See CONTRIBUTING.md for guidelines.
Adding a New Destination
- Check Wikivoyage coverage
- Add to
data/destinations.json - Test itinerary generation
- Submit PR
License
MIT License — see LICENSE for details.
Links
- Website: https://openclaw.tours
- GitHub: https://github.com/Asif2BD/openclaw.tours
- Docs: https://openclaw.tours/docs
- Issues: https://github.com/Asif2BD/openclaw.tours/issues
Built with ❤️ for the OpenClaw community.