定位指令（節點）

重點摘要

• location.get 是節點指令（透過 node.invoke）。
• 預設關閉。
• Android 應用程式設定使用選擇器：關閉 / 使用中。
• 另有獨立開關：精確定位。

為何使用選擇器（而非單純開關）

作業系統的權限是多層級的。我們可以在應用程式內提供選擇器，但實際授權仍由作業系統決定。

• iOS/macOS 可能在系統提示/設定中提供使用中或始終選項。
• Android 應用程式目前僅支援前景定位。
• 精確定位是獨立的授權（iOS 14+ 的「精確」、Android 的「fine」vs「coarse」）。

UI 中的選擇器控制我們請求的模式；實際授權存在於作業系統設定中。

設定模型

按節點裝置：

• location.enabledMode：off | whileUsing
• location.preciseEnabled：布林值

UI 行為：

• 選擇 whileUsing 會請求前景權限。
• 如果作業系統拒絕請求的層級，回退到已授權的最高層級並顯示狀態。

權限對應（node.permissions）

可選。macOS 節點透過 permissions 對應表回報 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：系統故障 / 無可用提供者。

背景行為

• Android 應用程式在背景時拒絕 location.get。
• 在 Android 上請求定位時，請保持 OpenClaw 開啟。
• 其他節點平台行為可能不同。

模型/工具整合

• 工具介面：nodes 工具新增 location_get 動作（需要節點）。
• CLI：openclaw nodes location get --node <id>。
• Agent 指引：僅在使用者已啟用定位且了解範圍時才呼叫。

UX 文案（建議）

• 關閉：「定位分享已停用。」
• 使用中：「僅在 OpenClaw 開啟時。」
• 精確：「使用精確 GPS 定位。關閉後改為分享大約位置。」