使用 location.get 獲取 Node 設備位置

開發過定位功能的人都知道，最煩人的通常不是獲取經緯度，而是處理不同操作系統的權限邏輯。有時候你以為權限已經拿到了，但換到背景模式就失效，或者因為用戶沒開啟「精確位置」導致數據偏差極大。

這份指南會幫你理清 Node 設備上的位置獲取邏輯，讓你直接透過 API 拿到需要的數據。

需要準備的東西

• Node 設備（iOS, Android 或 macOS）
• OpenClaw 環境
• 具備調用 node.invoke 的權限

快速開始

要在 5 分鐘內獲取位置，你需要先確保權限設定正確，然後發送指令。

1. 配置權限模式

每個 Node 設備都有兩個核心設定：

• location.enabledMode: 可選值為 off / whileUsing / always。
• location.preciseEnabled: 布林值，決定是否使用精確 GPS。

當你在 UI 選擇 always 時，系統會先確保 whileUsing 已授權，接著請求背景權限。如果 OS 拒絕了請求，設定會自動退回到目前允許的最高等級。

2. 調用 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"
}

3. 使用 CLI 測試

如果你偏好命令行，可以直接運行：

openclaw nodes location get --node <id>

背景執行邏輯

如果你需要在 Node 處於背景時獲取位置，必須滿足以下條件：

• 用戶在設定中選擇了 Always。
• OS 已授予背景位置權限。
• iOS 需要開啟 background location mode；Android 可能需要 foreground service。

在未來，Gateway 可以透過靜默推送（Silent Push）喚醒 Node 並回傳位置數據，但這取決於 OS 是否限制了背景活動。

疑難排解

當獲取失敗時，請檢查以下錯誤代碼：

• LOCATION_DISABLED: 你在設定中把選擇器關掉了。
• LOCATION_PERMISSION_REQUIRED: 系統層級缺少權限。
• LOCATION_BACKGROUND_UNAVAILABLE: App 在背景運行，但權限僅限「使用中」。
• LOCATION_TIMEOUT: 在指定時間內拿不到定位。
• LOCATION_UNAVAILABLE: 系統故障或沒有定位服務提供商。

有任何設定上的疑問？可以詢問 AI Setup Assistant。

下一步

• Node Permissions 概覽
• 使用 Gateway 發送指令