Location command（nodes）

TL;DR

  • location.get 是一个 node command（通过 node.invoke 调用）
  • 默认关闭
  • Android app settings 使用选择器：Off / While Using
  • 另有单独开关：Precise Location

为什么是选择器，而不只是一个开关

操作系统的权限通常是分级的。我们可以在 app 内暴露一个选择器，但实际授予的权限级别仍由操作系统决定。

  • iOS/macOS 可能会在系统提示或 Settings 中提供 While Using 或 Always
  • Android app 当前只支持前台定位
  • Precise location 是单独的一项授权（iOS 14+ 的 “Precise”，Android 的 “fine” 与 “coarse”）

UI 中的选择器决定我们请求的模式；实际授予结果保存在系统设置中。

设置模型

按 node device 维度：

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

UI 行为：

  • 选择 whileUsing 时，会请求前台定位权限
  • 如果 OS 拒绝所请求的权限级别，则回退到当前已授予的最高级别，并显示相应状态

权限映射（node.permissions）

可选。macOS node 会通过 permissions map 上报 location；iOS/Android 可能不会包含它。

命令：location.get

通过 node.invoke 调用。

参数（建议）：

  1. {
  2.   "timeoutMs": 10000,
  3.   "maxAgeMs": 15000,
  4.   "desiredAccuracy": "coarse|balanced|precise"
  5. }

响应 payload：

  1. {
  2.   "lat": 48.20849,
  3.   "lon": 16.37208,
  4.   "accuracyMeters": 12.5,
  5.   "altitudeMeters": 182.0,
  6.   "speedMps": 0.0,
  7.   "headingDeg": 270.0,
  8.   "timestamp": "2026-01-03T12:34:56.000Z",
  9.   "isPrecise": true,
  10.   "source": "gps|wifi|cell|unknown"
  11. }

错误（稳定错误码）：

  • LOCATION_DISABLED：selector 处于关闭状态
  • LOCATION_PERMISSION_REQUIRED：缺少所请求模式所需的权限
  • LOCATION_BACKGROUND_UNAVAILABLE：app 在后台，但当前只允许 While Using
  • LOCATION_TIMEOUT：在规定时间内未获得定位结果
  • LOCATION_UNAVAILABLE：系统故障或没有可用 provider

后台行为

  • Android app 在后台时会拒绝 location.get
  • 在 Android 上请求定位时，请保持 OpenClaw 处于打开状态
  • 其他 node 平台的行为可能不同

Model / tooling 集成

  • Tool surface：nodes tool 增加 location_get action（必须提供 node）
  • CLI：openclaw nodes location get --node <id>
  • Agent guidelines：仅在用户已启用 location，且理解其作用范围时才调用

UX 文案（建议）

  • Off：“Location sharing is disabled.”
  • While Using：“Only when OpenClaw is open.”
  • Precise：“Use precise GPS location. Toggle off to share approximate location.”