Location Awareness

This skill provides commands to execute. When the user asks about location, RUN the appropriate command below.

⚠️ IMPORTANT: All commands use scripts/location.sh

Every command must be run via scripts/location.sh. Example:

User asks: "How long to walk home?"
You run:

scripts/location.sh eta home --mode walk

Output: 4.6 km, about 45 min walk
You reply with the output directly.

Do NOT run eta or other subcommands directly — they don't exist as standalone commands.

Quick Reference — What to Run

| User says | Run this (copy exactly) | Reply with | |-----------|----------|------------| | "Where am I?" | scripts/location.sh status | Zone name only | | "Map" / "map link" | scripts/location.sh herewego | Just the URL | | "What are my coordinates?" | scripts/location.sh status | Lat/lon from output | | "How long to walk home?" | scripts/location.sh eta home --mode walk | Distance + duration | | "How long to bike to X?" | scripts/location.sh eta X --mode bike | Distance + duration | | "How far is X by car?" | scripts/location.sh eta X --mode car | Distance + duration | | "Remind me to X when I get to Y" | scripts/location.sh remind "X" Y | Brief confirm | | "What reminders do I have?" | scripts/location.sh reminders | Bullet list or "None" | | "List my places" | scripts/location.sh places | Bullet list | | "List places nearby" | scripts/location.sh places --near | Sorted by distance | | "List my pubs downtown" | scripts/location.sh places --region downtown --category pub | Filtered list | | "Save this spot as X" | scripts/location.sh addplace "X" | Confirm | | "Delete place X" | scripts/location.sh delplace X | Confirm | | "Disable the grocery rule" | scripts/location.sh disable grocery | Confirm | | "List my geofence rules" | scripts/location.sh geofences | Bullet list | | "When was I last at X?" | scripts/location.sh history X | Date/time | | "Where have I been today?" | scripts/location.sh history --days 1 | List of places | | "Find me a cafe nearby" | scripts/location.sh nearby cafe | POI list with distances | | "Any pubs within 1km?" | scripts/location.sh nearby pub 1000 | Filtered POI list | | "How long was I at work this week?" | scripts/location.sh stats --days 7 | Hours per place |

Response style: Terse. No preamble. No "Here's your location:". Just the answer.

All Commands

All via scripts/location.sh <command>:

| Command | Description | |---------|-------------| | status | Current location, geofences inside, map link | | herewego | Just the HERE WeGo map link | | check | Check for triggered actions/reminders (used by cron) | | places [--near] [--region R] [--category C] | List saved places | | geofences | List all geofences with full details | | remind <text> <place_id> | Add one-shot location reminder | | reminders | List pending reminders | | addplace <name> [radius] [--region R] [--category C] | Save current location | | editplace <id> [--name] [--radius] [--region] [--category] [--action] [--cooldown] | Modify a place | | delplace <id> | Delete a place | | enable <id> / disable <id> | Toggle geofence on/off | | history [place] [--days N] | When was I last at a place? | | nearby <category> [radius] | Find nearby POIs (cafe, pub, restaurant, etc.) | | stats [--days N] | Time spent at each place, visit counts | | proximity <text> <place/lat> [lon] [radius] | Alert when approaching a location | | eta <place> [--mode walk\|bike\|car] | Travel time and distance to a place |

Note: eta accepts saved place names, coordinates (lat,lon), or any place name (geocoded via OpenStreetMap, biased to current location).

Note: status returns the zone name if in a known place, otherwise reverse geocodes to a street address (e.g., "123 Main Street, Downtown").

Concepts

Geofences — Saved places with lat/lon, radius, and optional action. Persistent.

Reminders — One-shot alerts tied to a place. Deleted after delivery.

Region/Category — Optional tags for filtering (e.g., "downtown", "pub").

---

Setup (for administrators)

Provider Configuration

Edit scripts/config.json:

Home Assistant (default):

{
  "provider": "homeassistant",
  "homeassistant": {
    "url": "https://your-ha.example.com",
    "token": "your-long-lived-token",
    "entity_id": "device_tracker.phone"
  }
}

OwnTracks:

{
  "provider": "owntracks",
  "owntracks": {
    "url": "https://owntracks.example.com",
    "user": "username",
    "device": "phone"
  }
}

Generic HTTP:

{
  "provider": "http",
  "http": {
    "url": "https://your-api.com/location",
    "headers": {"Authorization": "Bearer token"}
  }
}

GPSLogger (file-based):

{
  "provider": "gpslogger",
  "gpslogger": {
    "file": "/path/to/location.json"
  }
}

Secrets support: "env:VAR_NAME" (reads from environment variable) or plain string.

Alternative: Configure entirely via environment variables (no config.json needed):

| Provider | Env variables | |----------|--------------| | LOCATION_PROVIDER | homeassistant, owntracks, http, or gpslogger (default: homeassistant) | | Home Assistant | HA_URL, HA_TOKEN, HA_ENTITY_ID | | OwnTracks | OWNTRACKS_URL, OWNTRACKS_USER, OWNTRACKS_DEVICE, OWNTRACKS_TOKEN | | HTTP | LOCATION_HTTP_URL | | GPSLogger | GPSLOGGER_FILE |

Env vars take precedence over config.json values. Set them in ~/.openclaw/.env or your shell environment.

Output format: Most query commands output human-readable text by default. Add --json for JSON output (useful for scripting).

Travel Speeds

Customize walking/biking speeds for ETA calculations in scripts/config.json:

{
  "speeds_kmh": {
    "walk": 6,
    "bike": 15
  }
}

Geofence Config

Edit scripts/geofences.json:

{
  "geofences": [
    {
      "id": "grocery",
      "name": "Grocery Store",
      "lat": 40.7128,
      "lon": -74.0060,
      "radius_m": 30,
      "action": "shopping_tasks",
      "cooldown_hours": 4,
      "enabled": true,
      "region": "downtown",
      "category": "shop"
    }
  ],
  "location_reminders": [],
  "proximity_alerts": []
}

Automatic Notifications (OpenClaw Cron)

Use OpenClaw's built-in cron to run periodic location checks. Add a job to ~/.openclaw/cron/jobs.json:

{
  "name": "Location Check",
  "schedule": "*/5 * * * *",
  "prompt": "Run scripts/location.sh check --json and notify me of any triggered actions, reminders, or proximity alerts.",
  "channel": "signal",
  "to": "+1234567890",
  "wakeMode": "now"
}

This keeps scheduling within OpenClaw rather than requiring external systemd services.