Summary

The iOS app exposes a Location setting with Off, While Using, and Always, and the runtime already has code paths that depend on Always for background location. But the product/use-case contract is still under-specified: users need a clear, intentional permission flow that explains when Always is useful, why the app is asking, and what behavior changes when they choose it.

This is related to #86217, which tracks the lower-level UIBackgroundModes=location / bundle configuration decision. This issue is about the user-facing feature shape and acceptance criteria around Always location.

Current source state

From current iOS source inspection:

• Settings -> Location offers Off, While Using, and Always.
• LocationService.ensureAuthorization(mode:) can call requestAlwaysAuthorization() after authorizedWhenInUse.
• NodeAppModel.handleLocationInvoke rejects background location.get unless the app mode is .always and iOS authorization is authorizedAlways.
• SignificantLocationMonitor only starts for .always plus authorizedAlways, then sends location.update events to the gateway.
• Info.plist copy says OpenClaw can share location in the background when Always is enabled.
• Question: should iOS background location claims include UIBackgroundModes=location? #86217 currently tracks whether the shipped app bundle should include the location background mode or remove/soften the background-location claim.

Use cases that justify an explicit Always flow

These are the use cases worth designing for if maintainers keep background location as an intended iOS capability:

1. Presence-aware automations

   • Home/away/work detection for private automations.
   • Example: "When I arrive at work, adjust notification/assistant behavior" or "when I leave home, trigger a private home-state update."

2. Gateway-initiated location query while the app is not foregrounded

   • A paired gateway/agent may need location.get when the phone app is in the background.
   • This should work only when the user explicitly selected Always, granted iOS Always, and the command policy allows location access.

3. Significant-location wake events

   • iOS can wake the app on significant location changes so OpenClaw can send a low-frequency location.update event.
   • This is different from continuous tracking and should be described that way if that is the intended implementation.

4. Context for mobile assistant workflows

   • Location can help answer context-dependent requests like "am I near home/work?" or "where did this mobile event happen?"
   • This needs clear user consent because location is sensitive even when no exact automation is configured.

5. Reliability across foreground/background transitions

   • While Using is enough for an active foreground request.
   • Always is required for background requests and location-change wakes.
   • The UI should make this distinction obvious instead of letting users select Always but end up with only When In Use at the OS level.

Product / privacy requirements

If this feature remains intended:

• Default stays Off.
• Always must be an explicit user action, not implied by enabling general device capabilities.
• The app should explain the actual behavior before or during the permission request:
  • foreground sharing vs background sharing;
  • significant-change wake vs continuous tracking, if applicable;
  • that iOS Settings may still need the user to upgrade permission to Always;
  • how to turn it off again.
• The Settings card should show the effective state, not only the desired app preference:
  • app setting: Always;
  • iOS authorization: While Using, Always, denied, restricted, or not determined;
  • Precise Location state where relevant.
• Background location should remain blocked unless both app preference and iOS authorization are actually Always.
• Any background event should be sparse and explainable in logs/proof, not continuous high-rate tracking.

Acceptance criteria

• Selecting Location -> Always follows a deliberate flow:
  • requests When In Use first when needed;
  • then requests or guides the user to Always;
  • does not silently pretend Always is active if iOS only granted When In Use.
• Settings displays a clear effective status when iOS authorization and the app preference disagree.
• Background location.get and significant-location updates work only with app mode .always and iOS authorizedAlways.
• If background location is intended, Question: should iOS background location claims include UIBackgroundModes=location? #86217 is resolved consistently by adding UIBackgroundModes=location to the processed app bundle and keeping docs/copy/runtime aligned.
• If background location is not intended, the Always option, background runtime paths, and background-location copy are removed or softened together.
• Add focused tests for:
  • Always request flow state transitions;
  • mismatch between desired mode and actual iOS authorization;
  • background location.get allowed/blocked behavior;
  • significant-location monitor start conditions.

Suggested implementation shape

• Keep the existing OpenClawLocationMode model, but distinguish desired app mode from effective OS authorization in the UI.
• Add a small location-permission status model used by Settings and tests.
• Keep LocationService.ensureAuthorization(mode:) as the platform boundary, but avoid relying on a single picker change to communicate the privacy meaning of Always.
• Add a processed bundle plist guard if the product decision is to support background location.

Open questions

• Is OpenClaw intended to support iOS background location in App Store/TestFlight builds, or should the feature stay foreground-only?
• Should the implementation use only significant-location changes for wake/event behavior, or should any form of continuous background updates be supported?
• What wording should be used in the permission explanation so users understand that this is private gateway/device automation rather than generic tracking?