Location command for nodes

TL;DR

Node command location.get runs through node.invoke or openclaw nodes location get.
Disabled initially.
Android third-party distributions offer three choices: Off, While Using, Always. Play Store builds only show Off and While Using.
Precise Location operates as an independent toggle.

Why a selector (not just a switch)

Location permissions in the operating system have multiple tiers. Precise location is also a separate OS permission (iOS 14+ uses "Precise", Android distinguishes "fine" from "coarse"). The in-app selector controls which mode gets requested, but the OS ultimately determines what is granted.

Settings model

For each node device:

location.enabledMode: off | whileUsing | always
location.preciseEnabled: boolean

Interface behavior:

Picking whileUsing requests foreground permission.
On Android third-party builds, choosing always first requests foreground permission, explains why background access is needed, then opens the Android app settings so the user can grant the separate Allow all the time permission.
Android Play Store builds do not declare background location permission and do not show always.
When the OS denies the requested permission level, the app falls back to the highest level that was granted and displays the status.

Permissions mapping (node.permissions)

Not required. On macOS, the node provides location inside the permissions map on node.list/node.describe; iOS and Android may leave it out.

Command: `location.get`

Invoked through node.invoke or the CLI helper:

openclaw nodes location get --node <idOrNameOrIp>
openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000

Parameters:

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

CLI flags correspond directly: --location-timeout maps to timeoutMs, --max-age to maxAgeMs, --accuracy to desiredAccuracy.

Response body:

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

Errors (stable codes):

LOCATION_DISABLED: the selector is turned off.
LOCATION_PERMISSION_REQUIRED: the required permission for the chosen mode is missing.
LOCATION_BACKGROUND_UNAVAILABLE: the app is in the background but only While Using permission was granted.
LOCATION_TIMEOUT: no location fix was obtained in time.
LOCATION_UNAVAILABLE: system error or no location providers available.

Background behavior

Android third-party builds allow background location.get only when the user selected Always and Android has granted background location. The persistent node service already running adds the location service type and shows Location: Always while active.
Android Play Store builds and While Using mode reject location.get when the app is backgrounded.
Other node platforms may behave differently.

Linux node host

The bundled Linux Node plugin adds location.get to the CLI openclaw node service, even on headless hosts without the Linux desktop application. Location starts disabled. Activate it under the plugin entry, then restart the node service:

{
  plugins: {
    entries: {
      "linux-node": {
        config: {
          location: { enabled: true },
        },
      },
    },
  },
}

Install GeoClue2 together with its where-am-i demo (geoclue-2-demo on Debian and Ubuntu). The user running the node service must be permitted by the host's GeoClue policy and authorization agent.

The plugin uses where-am-i rather than a series of busctl calls. GeoClue ties client creation, property setting, starting, updates, and stopping to a single D-Bus client connection; the demo keeps that lifecycle intact, whereas separate busctl subprocesses do not. No npm dependency is introduced.

On Linux, coarse, balanced, and precise correspond to GeoClue accuracy levels 4, 6, and 8. It validates maxAgeMs against the returned timestamp. Because GeoClue's demo does not expose which provider was selected, source is unknown; isPrecise is true only when the reported accuracy is 100 meters or better.

On Linux, the same consistent error codes apply: LOCATION_DISABLED, LOCATION_TIMEOUT, and LOCATION_UNAVAILABLE.

Model/tooling integration

Agent tool: the nodes utility's location_get action (a node is mandatory).
CLI: openclaw nodes location get --node <id>.
Agent guidelines: invoke this only after the user has turned on location and understands what it covers.

UX copy (suggested)

Off: "Location sharing is disabled."
While Using: "Only when OpenClaw is running."
Always: "Allow location checks when OpenClaw is in the background."
Precise: "Use exact GPS coordinates. Disable this to share an approximate location."