Comando de Ubicación

- location.get es un comando de nodo (vía node.invoke).

- Por defecto está desactivado.

- La configuración usa un selector: off / while using / always.

- Toggle independiente: ubicación precisa.

Los permisos del SO son multinivel. Podemos exponer un selector en la app, pero el SO decide las concesiones reales.

- iOS/macOS: El usuario puede elegir Mientras se Usa o Siempre en el prompt/ajustes del sistema. La app puede solicitar actualización, el SO podría requerir ajustes.

- Android: La ubicación en segundo plano es un permiso separado; Android 10+ frecuentemente requiere flujo de ajustes.

- La ubicación precisa es una concesión separada (iOS 14+ "precisa", Android "fina" vs "aproximada").

El selector en la UI controla el modo solicitado; la concesión real está en los ajustes del SO.

Por dispositivo nodo:

- location.enabledMode: off | whileUsing | always

- location.preciseEnabled: booleano

Comportamiento de UI:

- Seleccionar whileUsing solicita permiso de primer plano.

- Seleccionar always asegura whileUsing primero, luego solicita segundo plano (enviando al usuario a ajustes si es necesario).

- Si el SO niega el nivel solicitado, revierte al nivel más alto concedido y muestra el estado.

Opcional. Los nodos macOS reportan location vía mapa de permisos; iOS/Android podrían omitirlo.

Llamado vía node.invoke.

Parámetros (recomendados):

{
  "timeoutMs": 10000,
  "maxAgeMs": 15000,
  "desiredAccuracy": "coarse|balanced|precise"
}

Payload de Respuesta:

{
  "lat": 48.20849,
  "lon": 16.37208,
  "accuracyMeters": 12.5,
  "altitudeMeters": 182.0,
  "speedMps": 0.0,
  "headingDeg": 270.0,
  "timestamp": "2026-01-03T12:34:56.000Z",
  "isPrecise": true,
  "source": "gps|wifi|cell|unknown"
}

Errores (códigos estables):

- LOCATION_DISABLED: Selector apagado.

- LOCATION_PERMISSION_REQUIRED: Falta permiso para el modo solicitado.

- LOCATION_BACKGROUND_UNAVAILABLE: App en segundo plano pero solo permitido mientras se usa.

- LOCATION_TIMEOUT: Sin fijación a tiempo.

- LOCATION_UNAVAILABLE: Fallo del sistema / sin proveedor.

Objetivo: El modelo puede solicitar ubicación incluso si el nodo está en segundo plano, pero solo si:

- El usuario seleccionó Siempre.

- El SO concedió ubicación en segundo plano.

- La app tiene permitido ejecutarse en segundo plano (iOS Background Mode / Android Foreground Service o permiso especial).

Flujo de Disparo Push (Futuro):

1. El Gateway envía push al nodo (Silent Push o FCM Data).

2. El nodo despierta temporalmente y solicita ubicación del dispositivo.

3. El nodo reenvía el payload de vuelta al Gateway.

Nota:

- iOS: Requiere permiso Siempre + modo Background Location. Los silent pushes pueden ser limitados; espera fallos intermitentes.

- Android: La ubicación en segundo plano podría requerir Foreground Service; de lo contrario espera denegación.

- Superficie de Herramienta: la herramienta nodes añade acción location_get (requiere nodo).

- CLI: openclaw nodes location get --node <id>.

- Guías del Agente: Llamar solo si el usuario habilitó ubicación y entiende el alcance.

- Off: "El compartir ubicación está deshabilitado."

- While Using: "Solo cuando OpenClaw está abierto."

- Always: "Permitir ubicación en segundo plano. Requiere permiso del sistema."

- Precise: "Usar ubicación GPS precisa. Desactiva para compartir ubicación aproximada."