# Location Command Documentation

## Core Functionality

The `location.get` node command retrieves device location data. It operates through a three-tier permission model rather than a simple on/off switch, reflecting how modern operating systems handle location access.

## Permission Levels

The system uses three modes: disabled, foreground-only ("While Using"), and background-enabled ("Always"). OS permissions are multi-level. We can expose a selector in-app, but the OS still decides the actual grant.

## Command Parameters & Response

When invoked, the command accepts timeout, cache age, and accuracy preferences. The response includes latitude, longitude, accuracy in meters, altitude, speed, heading, timestamp, precision status, and location source (GPS, WiFi, cellular, or unknown).

## Error Handling

The implementation provides five stable error codes: `LOCATION_DISABLED`, `LOCATION_PERMISSION_REQUIRED`, `LOCATION_BACKGROUND_UNAVAILABLE`, `LOCATION_TIMEOUT`, and `LOCATION_UNAVAILABLE`.

## Implementation Details

- Precise location is a separate toggle from the enablement mode
- iOS/macOS users configure through system settings
- Android distinguishes between standard and background location permissions
- Future background support requires push-triggered workflows

## Integration

The feature integrates via the `nodes` tool (`location_get` action) and CLI command (`openclaw nodes location get`), with recommended UX copy provided for each permission level.
