A specialized tool for querying real-time China Railway 12306 schedules and ticket availability directly through a terminal or AI agent.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install 12306
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install 12306 using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is 12306 Train Query?
The 12306 skill provides a robust interface for accessing official China Railway data without the need for complex API keys or external authentication. It enables users to fetch high-fidelity information regarding train schedules, seat availability, and station details for the entire Chinese rail network, including high-speed G and D series trains as well as conventional Z, T, and K types. This utility is a core component for users leveraging Openclaw Skills to automate travel planning and logistics.
Built with Node.js, the skill handles the heavy lifting of station name resolution and data formatting. It supports various output modes, allowing for seamless integration into different workflows, whether you need a visual HTML report or a raw JSON stream. By utilizing this within the Openclaw Skills ecosystem, developers can build sophisticated travel assistants that provide accurate, real-time transit data for one of the world's most extensive rail networks.
12306 Train Query Use Cases
- Real-time checking of high-speed rail seat availability between any two Chinese cities.
- Filtering train options by specific departure or arrival time windows to fit tight schedules.
- Generating travel reports in Markdown format for quick review within AI chat interfaces.
- Automating the search for specific seat classes such as business class or soft sleepers during peak travel seasons.
- Using station lookup features to identify exact terminal names in large metropolitan areas through Openclaw Skills.
How 12306 Train Query Works
- The user provides the origin city, destination city, and optional parameters such as travel date or train type.
- The skill utilizes a built-in station lookup script to resolve city names to official 12306 station codes, using a local cache to improve performance.
- A direct request is made to the official 12306 API to retrieve current schedule and ticket inventory data.
- The retrieved data is processed through various filters, such as maximum duration or availability status, as defined by the user.
- The results are formatted into the requested output type (HTML, Markdown, or JSON) and presented to the user or saved to the local file system.
12306 Train Query Setup
To use this skill, ensure you have Node.js installed. Since it interfaces with official APIs, no additional API keys are required for basic functionality. Follow these steps to get started with this part of Openclaw Skills:
# Query tickets from Beijing to Shanghai for today
node scripts/query.mjs 北京 上海
# Query specific high-speed trains (G) with Markdown output
node scripts/query.mjs 北京 上海 -t G -f md
# Search for stations by name
node scripts/stations.mjs 杭州
Station data is automatically cached for 7 days in the data directory to ensure fast response times for subsequent queries.
12306 Train Query Data Schema & Taxonomy
The skill manages its data through a structured file system and specific metadata configurations within the Openclaw Skills framework.
| Component | Location | Description |
|---|---|---|
| Query Script | scripts/query.mjs |
The main logic for fetching and filtering ticket data. |
| Station Script | scripts/stations.mjs |
Utility for searching station codes. |
| Station Cache | data/stations.json |
Local storage for station names and codes (7-day TTL). |
| HTML Output | data/*.html |
Default location for generated visual reports. |
The data output includes detailed seat types such as swz (Business), zy (First Class), ze (Second Class), and various sleeper options, mapped directly from official railway classifications.
12306 Train Query Advanced Features
- Multi-format output support including HTML for humans, Markdown for agents, and JSON for programmatic use.
- Advanced time-window filtering for both departure and arrival times (e.g.,
-18:00for arrivals before 6 PM). - Granular seat type filtering allowing users to search only for trains with specific availability (e.g.,
ze,zy). - Intelligent duration filtering using human-readable strings like
2hor1h30m. - Integrated station caching mechanism that reduces network overhead and speeds up the Openclaw Skills execution flow.
SKILL.md
Loading
Related Openclaw Skills
Grokipedia
Search and fetch articles from xAI's AI-generated encyclopedia, Grokipedia.
Self - Organic Personality Development
A lightweight framework for AI agents to develop authentic personality traits and behavioral observations over time without forced journaling.
Clawpay
A payment delivery skill enabling AI agents and humans to exchange value via secure crypto payment requests and result delivery.
CloudMonkey
A comprehensive interface for managing Apache CloudStack infrastructure via the CloudMonkey (cmk) CLI tool.
Flight Query (Amadeus)
A high-performance travel retrieval skill that connects AI agents to real-time flight offers and airport data via the Amadeus API.
MD Table Image
A specialized utility that transforms markdown tables into clean, high-resolution PNG images for enhanced chat visibility.
METADATA
Featured*
