Location Awareness

Location awareness via privacy-friendly GPS tracking (Home Assistant, OwnTracks, GPS Logger). Set location-based reminders and ask about movement history, travel time, and nearby POIs.

Security Scan

The skill's files, instructions, and required tools are consistent with a local location-tracking utility; it asks for location provider tokens/URLs which are expected but not declared in registry metadata, and it handles sensitive location data so review configuration before use.

Purpose & Capability

Name/description (privacy-friendly GPS tracking, Home Assistant/OwnTracks/GPSLogger support) match the included code: providers for Home Assistant, OwnTracks, generic HTTP and a file-based GPSLogger are implemented. The only required binary is python3 which is appropriate. Minor inconsistency: the registry metadata lists no required environment variables, yet the skill explicitly supports/reads many provider-related env vars (HA_TOKEN, HA_URL, OWNTRACKS_TOKEN, LOCATION_HTTP_URL, GPSLOGGER_FILE, LOCATION_PROVIDER), which are necessary for operation when used with remote services.

Instruction Scope

SKILL.md confines runtime actions to running scripts/location.sh which execs location.py and documents the exact commands the agent should run. The runtime instructions and code reference config.json, geofences.json and optionally env vars or ~/.openclaw/.env. The agent is instructed to run the local script and return its output; the instructions do not ask the agent to read arbitrary unrelated files or network endpoints beyond the configured providers. Important: the wrapper will source ~/.openclaw/.env if present, exposing any credentials stored there to the skill.

Install Mechanism

No install spec; the skill is delivered as files and requires an existing python3 on PATH. No downloads or archive extraction are performed by the skill itself, which is low-risk from an install perspective.

Credentials

The skill legitimately needs provider credentials/URLs to access Home Assistant, OwnTracks, or an HTTP endpoint. However, the registry metadata declares no required env vars or primary credential while SKILL.md and the code clearly support many sensitive env vars (HA_TOKEN, HA_URL, OWNTRACKS_TOKEN, LOCATION_HTTP_URL, GPSLOGGER_FILE, etc.). This mismatch is a transparency/metadata issue: users should expect to supply secrets if they want full functionality. The skill does not request unrelated credentials (e.g. AWS keys) and reads only provider-configured endpoints and files.

Persistence & Privilege

always:false (no forced inclusion) and the skill does not request elevated privileges. It stores its geofence/reminder/state files in its script directory (geofences.json, .location_state.json), which is normal for a local skill. It does source ~/.openclaw/.env (via the provided wrapper) which is documented — this gives the skill access to any credentials the user places there, so users should ensure that file only contains intended variables.

Assessment

This skill appears to be what it says: a local location-aware helper that talks to Home Assistant, OwnTracks, a generic HTTP endpoint, or a local GPSLogger file. Before installing or enabling it: - Review scripts/config.json and scripts/location.py to confirm provider URLs and tokens are correct and point to your own services. Don't use tokens from other services. - Understand it will handle highly sensitive location data and may send requests to whichever provider URL you configure (e.g., Home Assistant or an HTTP endpoint). If you configure a third-party HTTP URL, that service will receive your coordinates. - The wrapper automatically sources ~/.openclaw/.env; check that file for any secrets you don't want the skill to read. - The registry metadata omits declaring required env vars; expect to provide HA_TOKEN/HA_URL, OWNTRACKS_TOKEN/OWNTRACKS_URL, or LOCATION_HTTP_URL (depending on provider) for full functionality. - If you want additional assurance, inspect the remainder of scripts/location.py (the truncated portion) to confirm there are no unexpected network calls or remote endpoints beyond configured providers. If you do not trust the skill, run it in an isolated environment or omit provider credentials so it cannot contact external services.

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": "[phone]",
  "wakeMode": "now"
}

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