Flightmapify

Find cheapest flights and create interactive flight route maps with real-time flight search.

Security Scan

The skill mostly does what it says (local flight search + map), but its code accesses undeclared local config (~/ .flyai/config.json), assumes/uses an external 'flyai' CLI, can kill processes to free ports, and will serve your OpenClaw workspace over HTTP — these behaviors are not fully disclosed and are disproportionate to the declared requirements.

Purpose & Capability

The skill's stated purpose (flight search + interactive maps) is consistent with the code, but the code expects and calls an external 'flyai' CLI via subprocess (flyai search-flight) even though the skill metadata listed no required binaries. It also reads user config (~/.flyai/config.json) to obtain API keys if environment variables are not set — access to user home config is not declared in the registry metadata or SKILL.md as a required config path.

Instruction Scope

SKILL.md describes using optional environment variables and local servers, but the runtime instructions/code go further: they read ~/.flyai/config.json, load a .env file from the skill directory, dynamically detect the OpenClaw workspace (and write output into it), enable CORS on the Flask API, and attempt to kill processes occupying HTTP ports. The skill therefore reads local config and may modify system processes and expose arbitrary workspace files via an HTTP server — actions beyond a simple flight-map generator.

Install Mechanism

There is no install specification (instruction-only), which reduces supply-chain risk, but the bundle includes multiple executable Python scripts that spawn subprocesses (flyai CLI, lsof, kill, python -m http.server). Because the skill will invoke external binaries, the absence of a declared dependency on 'flyai' and tools like lsof is a notable omission.

Credentials

SKILL.md lists optional environment variables (FLYAI_API_KEY, AMAP_API_KEY) but the code will also silently read the user's ~/.flyai/config.json for API keys and will load a .env file from the skill directory. The skill requests no credentials in registry metadata, yet it actively seeks and uses potentially sensitive keys from the user's home — this is not proportional to the declared environment requirements.

Persistence & Privilege

The skill runs background servers (Flask flight-search server and a local HTTP server) and includes logic to kill processes on occupied ports (using lsof + kill -9). While it does not request 'always: true', these runtime actions give it ability to affect other local processes and to expose the workspace directory over HTTP, which increases blast radius if misused.

What to consider before installing

Before installing or running this skill: - Expect it to require the external 'flyai' CLI even though it's not listed — install and verify that tool if you want full functionality. - The skill will try to read ~/ .flyai/config.json (your FlyAI API key) if you don't set FLYAI_API_KEY; if you don't want it to access that file, explicitly set FLYAI_API_KEY or run the skill in a sandbox. - The skill starts local servers and will serve your detected OpenClaw workspace directory via a Python HTTP server — this can expose files in that workspace to anyone who can reach your machine. Run it only on trusted/local networks or change the output directory to a dedicated folder. - The startup logic can kill processes to free ports (uses lsof + kill -9). This can terminate unrelated programs; avoid running as root and consider running in an isolated environment (container or VM). - If you need to proceed: inspect the included scripts (flight-search-server.py, main_flightmapify.py, server_manager.py) line-by-line, set explicit environment variables (FLYAI_API_KEY, AMAP_API_KEY), and run the skill in a disposable/sandboxed workspace where exposing files and killing processes is safe. - If you want higher assurance, ask the author to declare required binaries (flyai, lsof) and explicitly document that the skill reads ~/.flyai/config.json and serves the workspace directory.

FlightMapify Skill

Overview

FlightMapify creates interactive flight route maps that allow users to search for flights between cities and visualize flight paths on an interactive map. Unlike TravelMapify which focuses on ground travel routes, FlightMapify is specifically designed for air travel planning.

Features

• Optimized server management with automatic port conflict resolution
• Flask-based flight search server for robust API handling
• Interactive flight search between origin and destination cities
• Real-time flight data from FlyAI (Fliggy MCP)
• Support for both direct and connecting flights with complete route information
• Visual flight path display on Amap maps with animated markers
• Direct booking links to Fliggy
• Support for both domestic and international flights
• Single-date input for simple flight queries
• Enhanced UX with loading states, notifications, and auto-hiding messages
• Professional error handling with user-friendly feedback
• Environment variable configuration for API Key management
• Complete connecting flight details including transfer cities, prices, and durations

Usage

Environment Setup

FlightMapify is an OpenClaw skill that supports optional user-configurable FlyAI API Key.

Configuration Options:

1. User-provided API Key (Recommended - avoids rate limiting)

   Get your API key from: https://flyai.open.fliggy.com/console

   export FLYAI_API_KEY=your_api_key_here
   

2. FlyAI Built-in API Key (Default)

   • If FLYAI_API_KEY is not configured, FlyAI will use its built-in default API key
   • Built-in key may have rate limits for frequent requests
   • No configuration required for basic usage

Environment Variables:

• FLYAI_API_KEY: Your FlyAI API key for flight search (optional, recommended to avoid rate limits)
• FLYAI_API_TOKEN: Alternative API token variable (optional)
• FLYAI_TOKEN: Another API token variable for compatibility (optional)

Note: FLYAI_API_KEY is optional. If not set, FlyAI will use its built-in default API key, but this may be subject to rate limiting for frequent requests.

Generate Flight Map

# Generate a flight map between two cities
flightmapify --origin "北京" --destination "上海" --date "2026-04-22" --output flight-beijing-shanghai.html

Parameters

• --origin: Departure city (required)
• --destination: Arrival city (required)
• --date: Travel date in YYYY-MM-DD format (required)
• --output: Output HTML file name (required)
• --port: HTTP server port (default: 9000)

Integration

FlightMapify integrates with the existing FlyAI skill for real-time flight search and booking capabilities. It uses Amap for map visualization and provides a clean, focused interface for flight planning.

API Keys

• Amap API Key: Uses built-in default API key (no user key required)
• Custom Amap Key: Set AMAP_API_KEY environment variable to use your own key

Local Server Architecture

• Flight search server runs locally on dynamic ports
• HTTP server serves from OpenClaw workspace directory
• All URLs use localhost for security and simplicity

Technical Details

Server Architecture

• Flight Search Server: Flask-based server on configurable port (default: 8790)
• HTTP Server: Lightweight server for map display (default: 9000)
• Port Management: Automatic port conflict resolution and server health checks

Flight Data

• Direct Flights: Non-stop flights with price, duration, and booking links
• Connecting Flights: Multi-segment flights with transfer cities, complete pricing, and duration
• Route Visualization: Interactive map showing flight paths with animated markers
• Real-time Data: Live search results from FlyAI API

Environment Variables

• FLYAI_API_KEY: Your FlyAI API key for flight search (optional, recommended to avoid rate limits)
• FLYAI_API_TOKEN: Alternative API token variable (optional)
• FLYAI_TOKEN: Another API token variable for compatibility (optional)

Note: FLYAI_API_KEY is optional. If not set, FlyAI will use its built-in default API key, but this may be subject to rate limiting for frequent requests. Setting your own API key is recommended for production use or high-volume requests.

Changelog

Version 1.4.0 (2026-04-16)

• ✅ Reverted to optional API Key configuration
• ✅ Support for FlyAI built-in default API key (may have rate limits)
• ✅ User-provided API Key recommended to avoid rate limiting
• ✅ Updated documentation with clear configuration options
• ✅ Enhanced input box width optimization for better UI
• ✅ Fixed city suggestion box width for better UX

Version 1.3.0 (2026-04-16)

• ✅ Removed default API Key - now requires explicit user configuration
• ✅ Added clear error message when FLYAI_API_KEY is not set
• ✅ Updated documentation to reflect required API Key configuration
• ✅ Improved security by removing hardcoded API keys

Version 1.2.0 (2026-04-16)

• ✅ Fixed connecting flight search functionality
• ✅ Added complete connecting flight details (route cities, prices, durations)
• ✅ Implemented OpenClaw skill configuration with user-configurable API Key
• ✅ Added automatic fallback to default FlyAI API Key when not configured
• ✅ Updated server manager to use Flask-based server
• ✅ Enhanced server management with .env file support
• ✅ Fixed API Key configuration issues (trial limit errors)
• ✅ Improved error handling and user feedback
• ✅ Removed flight-search-server-simple.py (now using Flask-based server exclusively)

Version 1.1.0

• Initial release with basic flight search and map visualization

Examples

# Basic flight map
flightmapify --origin "北京" --destination "阿克苏" --date "2026-04-22" --output beijing-aksu-flight.html

# With custom port
flightmapify --origin "上海" --destination "乌鲁木齐" --date "2026-05-01" --output shanghai-urumqi-flight.html --port 8080

Troubleshooting Common Problems

🔴 "No flights found" or Empty Results

Possible Causes:

• API Rate Limits: Built-in FlyAI API key has trial limits
• Route Availability: Remote destinations may have limited flight options
• Date Too Far: Airlines may not have published schedules for distant dates

Solutions:

1. Get your own FlyAI API key from https://flyai.open.fliggy.com/console

   export FLYAI_API_KEY=your_api_key_here
   

2. Try closer dates (within 3-6 months)
3. Test with major city pairs first (Beijing-Shanghai, Guangzhou-Shenzhen)

🔴 404 File Not Found Error

Cause: HTML file generated in wrong directory

Solution:

• The skill now uses dynamic workspace detection
• Files are always generated in your OpenClaw workspace directory
• Check that your workspace contains AGENTS.md or SOUL.md

🔴 Character Encoding Issues (乱码)

Symptoms: Chinese cities show as garbled text like "阿克苯"

Cause: URL parameter double-decoding

Solution:

• This is fixed in version 1.4.0
• Ensure you're using the latest version from ClawHub
• If issues persist, restart your terminal session

🔴 Flight Search Server Won't Start

Symptoms: "Failed to start flight search server on port XXXX"

Causes & Solutions:

1. Port already in use: Server automatically finds next available port
2. Missing dependencies: Ensure flyai CLI is installed

   npm install -g @openclaw/flyai
   

3. Permission issues: Run with appropriate permissions

🔴 API Key Configuration Issues

Problem: Still getting rate limits after setting API key

Solutions:

1. Verify key is set correctly:

   echo $FLYAI_API_KEY
   

2. Check FlyAI config file:

   cat ~/.flyai/config.json
   

3. Use environment variable method (more reliable):

   export FLYAI_API_KEY=sk_your_actual_key
   flightmapify --origin "北京" --destination "上海" --date "2026-04-25" --output test.html
   

🔴 Map Not Loading or JavaScript Errors

Causes:

• Amap API key issues
• Network connectivity problems
• Browser security restrictions

Solutions:

1. Amap key is built-in - no user configuration needed
2. Open HTML file via HTTP server (not file:// protocol)
3. Check browser console for specific error messages

🟡 Performance Issues with Many Flights

Symptoms: Slow loading with routes having many connecting options

Solutions:

• The system shows top 20 flights by default
• Use direct flights only for faster results if needed
• Close other browser tabs to free memory

🔧 Debugging Tips

1. Check server logs:

   # Look for Python server output in your terminal
   

2. Test FlyAI CLI directly:

   flyai search-flight --origin "北京" --destination "上海" --dep-date "2026-04-25"
   

3. Verify file locations:

   ls -la ~/.openclaw/workspace/*.html
   

4. Check port availability:

   lsof -i :9000  # Replace with your port
   

📞 When to Contact Support

Contact the skill maintainer if:

• You've tried all troubleshooting steps above
• The issue persists with major city pairs (Beijing-Shanghai)
• You see consistent errors across different dates/routes
• The HTML file generates but shows completely blank map

Include in your report:

• OpenClaw version (openclaw --version)
• Skill version (check SKILL.md)
• Exact command used
• Error messages from terminal
• Screenshot of the HTML page (if applicable)