Location-Befehl (Nodes)

TL;DR

  • location.get ist ein Node-Befehl (über node.invoke).
  • Standardmäßig deaktiviert.
  • Einstellungen nutzen einen Selector: Aus / Während Nutzung / Immer.
  • Separater Toggle: Präzise Ortung.

Warum ein Selector (nicht nur ein Schalter)

Betriebssystem-Berechtigungen sind mehrstufig. Wir können in der App einen Selector anbieten, aber das OS entscheidet letztendlich über die tatsächliche Berechtigung.

  • iOS/macOS: Der Nutzer kann in System-Prompts/Einstellungen zwischen Während Nutzung oder Immer wählen. Die App kann ein Upgrade anfragen, aber das OS verlangt möglicherweise den Gang in die Einstellungen.
  • Android: Hintergrund-Ortung ist eine separate Berechtigung; ab Android 10+ erfordert sie oft einen Einstellungs-Flow.
  • Präzise Ortung ist eine separate Berechtigung (iOS 14+ “Präzise”, Android “fine” vs “coarse”).

Der Selector in der UI steuert unseren angeforderten Modus; die tatsächliche Berechtigung liegt in den OS-Einstellungen.

Einstellungsmodell

Pro Node-Gerät:

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

UI-Verhalten:

  • Auswahl von whileUsing fordert Vordergrund-Berechtigung an.
  • Auswahl von always stellt zuerst whileUsing sicher, dann fordert sie Hintergrund-Berechtigung an (oder leitet den Nutzer zu den Einstellungen, falls erforderlich).
  • Wenn das OS die angeforderte Stufe ablehnt, wird auf die höchste gewährte Stufe zurückgesetzt und der Status angezeigt.

Permissions-Mapping (node.permissions)

Optional. macOS-Node meldet location über die Permissions-Map; iOS/Android können es weglassen.

Befehl: location.get

Wird über node.invoke aufgerufen.

Parameter (empfohlen):

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

Response-Payload:

{
  "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"
}

Fehler (stabile Codes):

  • LOCATION_DISABLED: Selector ist deaktiviert.
  • LOCATION_PERMISSION_REQUIRED: Berechtigung fehlt für den angeforderten Modus.
  • LOCATION_BACKGROUND_UNAVAILABLE: App läuft im Hintergrund, aber nur “Während Nutzung” ist erlaubt.
  • LOCATION_TIMEOUT: Keine Ortung innerhalb der Zeit.
  • LOCATION_UNAVAILABLE: Systemfehler / keine Provider verfügbar.

Hintergrundverhalten (zukünftig)

Ziel: Das Modell kann Ortung anfordern, auch wenn die Node im Hintergrund läuft, aber nur wenn:

  • Der Nutzer Immer ausgewählt hat.
  • Das OS Hintergrund-Ortung gewährt.
  • Die App im Hintergrund für Ortung laufen darf (iOS Background Mode / Android Foreground Service oder spezielle Erlaubnis).

Push-gesteuerter Flow (zukünftig):

  1. Gateway sendet einen Push an die Node (Silent Push oder FCM-Daten).
  2. Node wacht kurz auf und fordert Ortung vom Gerät an.
  3. Node leitet Payload an Gateway weiter.

Hinweise:

  • iOS: Always-Berechtigung + Background-Location-Modus erforderlich. Silent Push kann gedrosselt werden; rechne mit gelegentlichen Ausfällen.
  • Android: Hintergrund-Ortung erfordert möglicherweise einen Foreground Service; andernfalls ist mit Ablehnung zu rechnen.

Modell/Tooling-Integration

  • Tool-Oberfläche: nodes-Tool fügt location_get-Aktion hinzu (Node erforderlich).
  • CLI: openclaw nodes location get --node <id>.
  • Agent-Richtlinien: Nur aufrufen, wenn der Nutzer Ortung aktiviert hat und den Umfang versteht.

UX-Texte (Vorschlag)

  • Aus: “Standortfreigabe ist deaktiviert.”
  • Während Nutzung: “Nur wenn OpenClaw geöffnet ist.”
  • Immer: “Hintergrund-Ortung erlauben. Erfordert Systemberechtigung.”
  • Präzise: “Präzise GPS-Ortung verwenden. Deaktivieren, um ungefähren Standort zu teilen.”