dvcrn Package Tracker
Track packages via the 17track universal API. Supports FedEx, UPS, DHL, CTT, China Post, Royal Mail, USPS, and 2000+ other carriers with automatic carrier detection.
Setup
Run once from the skill directory:
cd /root/.openclaw/workspace/skills/package-tracker
bash scripts/setup.sh
Then edit scripts/.env to add your API key:
SEVENTEEN_TRACK_API_KEY=your_key_here
Get a free key at https://admin.17track.net (100 registrations/month, unlimited status checks).
Usage
All commands run from the skill directory. Activate the venv first:
cd /root/.openclaw/workspace/skills/package-tracker
source scripts/venv/bin/activate
Add a Package
python scripts/cli.py add "TRACKING_NUMBER" -d "Description of contents"
- Carrier is auto-detected from the tracking number format
- Override with
-c "FedEx"if needed - Uses 1 registration from monthly quota (100/month free)
- Returns a tracking URL for the detected carrier
Check for Updates
python scripts/cli.py check
- Queries 17track for all active packages
- Prints status changes and new tracking events
- Outputs notifications to stdout for OpenClaw to relay via native messaging
- gettrackinfo calls are free and unlimited
List Packages
python scripts/cli.py list # Active only
python scripts/cli.py list --all # Include delivered/inactive
Package Details
python scripts/cli.py details "TRACKING_NUMBER"
Shows full tracking history with all events, locations, and timestamps.
Remove a Package
python scripts/cli.py remove "TRACKING_NUMBER"
Deactivates tracking (does not delete history).
Check API Quota
python scripts/cli.py quota
Shows registrations used this month vs. the 100/month free limit.
Cron Integration
Set up periodic checks with cron or OpenClaw heartbeats.
Using cron (every 3 hours)
# Add to crontab:
0 */3 * * * cd /root/.openclaw/workspace/skills/package-tracker && scripts/venv/bin/python scripts/check_updates.py --quiet
Using OpenClaw heartbeat
In your heartbeat logic, include:
cd /root/.openclaw/workspace/skills/package-tracker
source scripts/venv/bin/activate
python scripts/check_updates.py
The check_updates.py script:
- Checks all active packages for updates
- Prints notifications to stdout for OpenClaw to relay
- Exits 0 on success, 1 on error
- Use
--quietto suppress output when there are no updates
Notifications
When updates are detected, the tracker outputs formatted notifications to stdout. OpenClaw reads this output and relays it via its native message tool — which works on Telegram, Signal, Discord, WhatsApp, or whatever channel the user has configured.
Tracking URLs
Every package gets a carrier-specific tracking URL:
| Carrier | URL Pattern |
|---|---|
| FedEx | fedex.com/fedextrack/?trknbr={tn} |
| UPS | ups.com/track?tracknum={tn} |
| DHL | dhl.com/en/express/tracking.html?AWB={tn} |
| CTT | ctt.pt/.../objectSearch.jspx?objects={tn} |
| USPS | tools.usps.com/go/TrackConfirmAction?tLabels={tn} |
| Fallback | t.17track.net/en#nums={tn} |
The get_tracking_url(tracking_number, carrier) function in tracker.py generates these.
Status Codes
| Status | Emoji | Meaning |
|---|---|---|
| pending | ⏳ | Just added, not yet checked |
| Not Found | ❓ | 17track has no data yet |
| In Transit | 🚚 | Package is moving |
| Pick Up | 📬 | Ready for pickup |
| Delivered | ✅ | Delivered (auto-deactivated) |
| Undelivered | ⚠️ | Delivery attempt failed |
| Expired | ⌛ | Tracking data expired |
| Alert | 🚨 | Exception or issue |
Delivered packages are automatically deactivated.
Data Storage
- Database:
scripts/data/tracker.db(SQLite) - Tables:
packages,tracking_events,api_usage - All data is local. Nothing is sent externally except 17track API calls.
Environment Variables
| Variable | Required | Description |
|---|---|---|
SEVENTEEN_TRACK_API_KEY |
Yes | 17track API key from admin.17track.net |
Troubleshooting
- "API key not set" — Edit
scripts/.envand add your 17track key - "Monthly limit reached" — Free tier is 100 registrations/month. Wait or upgrade.
- No carrier detected — Pass
-c "CarrierName"when adding, or let 17track auto-detect (carrier code 0)
References
references/carriers.md— Full list of supported carriers with patterns and URLsreferences/17track-api.md— API endpoint reference, status codes, rate limits