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

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

All Commands

All via scripts/location.sh <command>:

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):

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.