Comando de ubicación (nodos)

Resumen

location.get es un comando de nodo (vía node.invoke).
Desactivado por defecto.
Los ajustes de la app Android usan un selector: Desactivado / Mientras se usa.
Interruptor separado: Ubicación precisa.

Por qué un selector (y no solo un interruptor)

Los permisos del SO son multinivel. Podemos exponer un selector en la app, pero el SO decide la concesión real.

iOS/macOS puede exponer Mientras se usa o Siempre en los avisos del sistema/Ajustes.
La app Android actualmente solo soporta ubicación en primer plano.
La ubicación precisa es una concesión separada (“Precisa” en iOS 14+, “fine” vs “coarse” en Android).

El selector en la UI determina el modo solicitado; la concesión real reside en los ajustes del SO.

Modelo de ajustes

Por dispositivo nodo:

location.enabledMode: off | whileUsing
location.preciseEnabled: bool

Comportamiento de la UI:

Seleccionar whileUsing solicita permiso de primer plano.
Si el SO deniega el nivel solicitado, se revierte al nivel más alto concedido y se muestra el estado.

Mapeo de permisos (node.permissions)

Opcional. El nodo macOS reporta location a través del mapa de permisos; iOS/Android pueden omitirlo.

Comando: `location.get`

Se invoca mediante node.invoke.

Parámetros (sugeridos):

{
  "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: el selector está desactivado.
LOCATION_PERMISSION_REQUIRED: falta permiso para el modo solicitado.
LOCATION_BACKGROUND_UNAVAILABLE: la app está en segundo plano pero solo se permite “Mientras se usa”.
LOCATION_TIMEOUT: sin fix a tiempo.
LOCATION_UNAVAILABLE: fallo del sistema / sin proveedores.

Comportamiento en segundo plano

La app Android deniega location.get mientras está en segundo plano.
Mantén OpenClaw abierto al solicitar ubicación en Android.
Otras plataformas de nodos pueden comportarse diferente.

Integración con modelo/herramientas

Superficie de herramienta: la herramienta nodes agrega la acción location_get (requiere nodo).
CLI: openclaw nodes location get --node <id>.
Directrices para el agente: solo llamar cuando el usuario haya habilitado la ubicación y entienda el alcance.

Texto de UX (sugerido)

Desactivado: “La compartición de ubicación está desactivada.”
Mientras se usa: “Solo cuando OpenClaw está abierto.”
Precisa: “Usar ubicación GPS precisa. Desactiva para compartir ubicación aproximada.”