Location command（位置命令）（节点）

TL;DR

  • location.get 是一个节点命令（通过 node.invoke）。
  • 默认关闭。
  • 设置使用选择器：Off / While Using / Always。
  • 单独的切换：Precise Location（精确位置）。

为什么使用选择器（而不仅仅是开关）

OS 权限是多级别的。我们可以在应用内公开选择器，但 OS 仍然决定实际授予。

  • iOS/macOS：用户可以在系统提示/设置中选择 While Using（使用时） 或 Always（始终）。应用可以请求升级，但 OS 可能需要设置。
  • Android：后台位置是单独的权限；在 Android 10+ 上，它通常需要设置流程。
  • 精确位置是单独的授予（iOS 14+ "Precise（精确）"，Android "fine（精细）" vs "coarse（粗略）"）。

UI 中的选择器驱动我们请求的模式；实际授予位于 OS 设置中。

设置模型

每个节点设备：

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

UI 行为：

  • 选择 whileUsing 请求前台权限。
  • 选择 always 首先确保 whileUsing，然后请求后台（如果需要，则将用户发送到设置）。
  • 如果 OS 拒绝请求的级别，则恢复到最高授予级别并显示状态。

权限映射（node.permissions）

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

命令：location.get

通过 node.invoke 调用。

参数（建议）：

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

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

错误（稳定代码）：

  • LOCATION_DISABLED：选择器关闭。
  • LOCATION_PERMISSION_REQUIRED：请求模式缺少权限。
  • LOCATION_BACKGROUND_UNAVAILABLE：应用在后台，但仅允许 While Using。
  • LOCATION_TIMEOUT：及时没有定位。
  • LOCATION_UNAVAILABLE：系统故障/无提供者。

后台行为（未来）

目标：模型可以请求位置，即使节点在后台，但仅在以下情况下：

  • 用户选择了 Always（始终）。
  • OS 授予后台位置。
  • 应用被允许在后台运行以获取位置（iOS 后台模式 / Android 前台服务或特殊许可）。

推送触发流程（未来）：

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

注意事项：

  • iOS：需要 Always 权限 + 后台位置模式。静默推送可能受到限制；预期间歇性故障。
  • Android：后台位置可能需要前台服务；否则，预期拒绝。

模型/工具集成

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

UX 文案（建议）

  • Off："位置共享已禁用。"
  • While Using："仅当 OpenClaw 打开时。"
  • Always："允许后台位置。需要系统权限。"
  • Precise："使用精确的 GPS 位置。关闭以共享大致位置。"
← 返回文档首页