位置命令（Nodes）

快速了解

  • location.get 是一个 Node 命令（通过 node.invoke 调用）。
  • 默认关闭。
  • 设置使用选择器：关闭 / 使用时 / 始终。
  • 独立开关：精确位置。

为什么用选择器（而不是简单开关）

操作系统的权限是多级的。我们可以在应用内提供选择器，但实际授权由操作系统决定。

  • iOS/macOS：用户可以在系统提示或设置中选择使用时或始终。应用可以请求升级，但操作系统可能要求用户去设置中操作。
  • Android：后台位置是独立权限；在 Android 10+ 上通常需要跳转到设置。
  • 精确位置是独立授权（iOS 14+ 的”精确”，Android 的”精确”与”粗略”）。

界面中的选择器驱动我们请求的模式；实际授权存储在操作系统设置中。

设置模型

每个 Node 设备：

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

界面行为：

  • 选择 whileUsing 会请求前台权限。
  • 选择 always 会先确保 whileUsing，然后请求后台权限（如果需要，会引导用户去设置）。
  • 如果操作系统拒绝请求的级别，会回退到已授予的最高级别并显示状态。

权限映射（node.permissions）

可选。macOS Node 通过权限映射报告 location；iOS/Android 可能省略。

命令：location.get

通过 node.invoke 调用。

参数（建议）：

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

响应数据：

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

错误码（稳定）：

  • LOCATION_DISABLED：选择器处于关闭状态。
  • LOCATION_PERMISSION_REQUIRED：请求的模式缺少权限。
  • LOCATION_BACKGROUND_UNAVAILABLE：应用在后台但只允许使用时权限。
  • LOCATION_TIMEOUT：超时未获取到位置。
  • LOCATION_UNAVAILABLE：系统故障或无可用提供商。

后台行为（未来）

目标：模型可以在 Node 处于后台时请求位置，但仅当：

  • 用户选择了始终。
  • 操作系统授予后台位置权限。
  • 应用被允许在后台运行位置服务（iOS 后台模式 / Android 前台服务或特殊许可）。

推送触发流程（未来）：

  1. Gateway 向 Node 发送推送（静默推送或 FCM 数据）。
  2. Node 短暂唤醒并从设备请求位置。
  3. Node 将数据转发给 Gateway。

注意事项：

  • iOS：需要始终权限 + 后台位置模式。静默推送可能被限流；预期会有间歇性失败。
  • Android：后台位置可能需要前台服务；否则预期会被拒绝。

模型/工具集成

  • 工具界面：nodes 工具添加 location_get 操作（需要 Node）。
  • CLI：openclaw nodes location get --node <id>。
  • Agent 指南：仅在用户启用位置并理解范围时调用。

界面文案（建议）

  • 关闭：“位置共享已禁用。”
  • 使用时：“仅在 OpenClaw 打开时。”
  • 始终：“允许后台位置。需要系统权限。”
  • 精确：“使用精确 GPS 位置。关闭以共享大致位置。”