位置命令
摘要¶
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 | alwayslocation.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
参数:
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 桌面应用的无头主机。位置默认关闭。在插件条目下启用它,然后重启节点服务:
安装 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