openclaw-openclaw/docs/nodes/location-command.md at main

mirror of https://github.com/openclaw/openclaw.git synced 2026-07-06 17:24:42 +08:00

Files

Peter Steinberger f7d7148cf0 docs: rewrite published docs grounded in current source (#100142 )

Source-grounded rewrite of 529 published docs pages with per-unit information-loss verification: 1,713 factual corrections cited to src/**, generated surfaces regenerated, frontmatter titles preserved for i18n, release notes pages untouched. All docs gates green.

Closes #100141

2026-07-05 00:32:47 -04:00

3.1 KiB

Raw Permalink Blame History

summary, read_when, title

summary

read_when

title

Location command for nodes (location.get), permission modes, and Android foreground behavior

Adding location node support or permissions UI

Designing Android location permissions or foreground behavior

Location command

TL;DR

location.get is a node command, invoked via node.invoke or openclaw nodes location get.
Off by default.
Android app settings use a selector: Off / While Using.
Precise Location is a separate toggle.

Why a selector (not just a switch)

OS location permissions are multi-level (iOS/macOS expose While Using vs Always; Android currently supports foreground-only). Precise location is a separate OS grant too (iOS 14+ "Precise", Android "fine" vs "coarse"). The in-app selector drives the requested mode, but the OS still decides the actual grant.

Settings model

Per node device:

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

UI behavior:

Selecting whileUsing requests foreground permission.
If the OS denies the requested level, the app reverts to the highest granted level and shows status.

Permissions mapping (node.permissions)

Optional. The macOS node reports location via the permissions map on node.list/node.describe; iOS/Android may omit it.

Command: `location.get`

Called via 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

Params:

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

CLI flags map directly: --location-timeout -> timeoutMs, --max-age -> maxAgeMs, --accuracy -> desiredAccuracy.

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

Errors (stable codes):

LOCATION_DISABLED: selector is off.
LOCATION_PERMISSION_REQUIRED: permission missing for requested mode.
LOCATION_BACKGROUND_UNAVAILABLE: app is backgrounded but only While Using is granted.
LOCATION_TIMEOUT: no fix in time.
LOCATION_UNAVAILABLE: system failure or no providers.

Background behavior

The Android app denies location.get while backgrounded; keep OpenClaw open when requesting location on Android.
Other node platforms may differ.

Model/tooling integration

Agent tool: the nodes tool's location_get action (node required).
CLI: openclaw nodes location get --node <id>.
Agent guidelines: only call when the user enabled location and understands the scope.

UX copy (suggested)

Off: "Location sharing is disabled."
While Using: "Only when OpenClaw is open."
Precise: "Use precise GPS location. Toggle off to share approximate location."

3.1 KiB Raw Permalink Blame History