跳转至

位置命令

摘要

  • location.get 是一个节点命令,通过 node.invoke 或 openclaw nodes location get 调用。
  • 默认关闭。
  • Android 第三方构建使用选择器:Off / While Using / Always。Play 构建保持 Off / While Using。
  • 精确定位是单独的开关。

为什么使用选择器(而不是开关)

操作系统的位置权限是多级的。精确定位也是操作系统单独授予的权限(iOS 14+ 的 "Precise",Android 的 "fine" 与 "coarse")。应用内选择器决定请求的模式,但实际授予仍由操作系统决定。

设置模型

每个节点设备:

  • location.enabledMode:off | whileUsing | always
  • location.preciseEnabled:布尔值

UI 行为:

  • 选择 whileUsing 会请求前台权限。
  • 在 Android 第三方构建中选择 always 时,会先请求前台权限,解释后台访问,然后打开 Android 应用设置以单独授予 始终允许。
  • Android Play 构建不会声明后台位置权限,也不显示 always。
  • 如果操作系统拒绝了请求的级别,应用会回退到已授予的最高级别并显示状态。
  • 在 Android 上,关闭精确定位会限制共享的坐标,即使操作系统仍授予精确定位权限。缓存和新的定位结果使用 2 公里网格并带有缓慢变化的随机偏移;近似响应会省略海拔、速度和航向,并报告至少 2,000 米的不确定性。已经较低精度的定位结果会保留其更大的不确定性。
  • Android 在构造响应前会重新检查精度,因此在请求等待期间关闭该开关也会限制该响应。这不会撤销操作系统权限,也不会撤回已经共享的位置。

权限映射(node.permissions)

可选。macOS 节点通过 node.list/node.describe 上的 permissions 映射报告 location;iOS/Android 可能省略它。

命令:location.get

通过 node.invoke 调用,或使用 CLI 辅助命令:

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

参数:

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

CLI 标志直接映射:--location-timeout -> timeoutMs、--max-age -> maxAgeMs、--accuracy -> desiredAccuracy。

响应载荷:

{
  "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:系统故障或没有可用提供者。

后台行为

  • Android 第三方构建仅在用户选择 Always 且 Android 授予后台位置权限时,才接受后台 location.get。现有的持久节点服务会添加 location 服务类型,并在激活期间披露 Location: Always。
  • Android Play 构建和 While Using 模式会在后台拒绝 location.get。
  • 其他节点平台可能不同。

Linux 节点主机

内置的 Linux Node 插件会为 CLI openclaw node 服务添加 location.get,包括没有 Linux 桌面应用的无头主机。位置默认关闭。在插件条目下启用它,然后重启节点服务:

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

安装 GeoClue2 及其 where-am-i 演示(在 Debian 和 Ubuntu 上为 geoclue-2-demo)。node-service 用户必须被主机的 GeoClue 策略和授权代理允许。

该插件使用 where-am-i,而不是一系列 busctl 调用。GeoClue 将客户端创建、属性、启动、更新和停止绑定到一个 D-Bus 客户端连接;该演示会将这些生命周期保持在一起,而单独的 busctl 子进程不会。不会添加 npm 依赖。

Linux 将 coarse、balanced 和 precise 映射到 GeoClue 精度级别 4、6 和 8。它会针对返回的时间戳验证 maxAgeMs。GeoClue 的演示不会公开所选提供者,因此 source 为 unknown;仅当报告的精度为 100 米或更好时,isPrecise 才为 true。

Linux 使用相同的稳定错误:LOCATION_DISABLED、LOCATION_TIMEOUT 和 LOCATION_UNAVAILABLE。

模型/工具集成

  • Agent 工具:nodes 工具的 location_get 操作(需要 node)。
  • locationTimeoutMs 控制定位预算。设置后,Agent 工具会为节点调用增加 30 秒,并为 Gateway 传输再增加 30 秒。显式的 invokeTimeoutMs 和 timeoutMs 覆盖仍然独立,包括更短的限制。
  • CLI:openclaw nodes location get --node <id>。
  • Agent 指南:仅在用户启用了位置并理解其范围时调用。

UX 文案(建议)

  • Off:“已禁用位置共享。”
  • While Using:“仅在 OpenClaw 打开时。”
  • Always:“允许在 OpenClaw 处于后台时进行请求的位置检查。”
  • Precise:“使用精确 GPS 位置。关闭以共享近似位置。”

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw