跳转至

位置指令

太长不看

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

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

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

设置模型

按节点设备：

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

UI 行为：

  • 选择 whileUsing 会请求前台权限。
  • 在 Android 第三方构建中选择 always 时，先请求前台权限，说明后台访问，然后打开 Android 应用设置，以单独授予 Allow all the time。
  • 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：应用处于后台，但仅授予了“使用时”权限。
  • LOCATION_TIMEOUT：未能在限定时间内获取定位。
  • LOCATION_UNAVAILABLE：系统故障或没有可用提供者。

后台行为

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

Linux 节点主机

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

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

安装 GeoClue2 及其 where-am-i 演示（在 Debian 和 Ubuntu 上为 geoclue-2-demo）。节点服务用户必须被主机的 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。

模型/工具集成

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

UX 文案（建议）

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

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