Nodes and media
位置命令
重點摘要
location.get是節點命令，透過node.invoke或openclaw nodes location get呼叫。- 預設為關閉。
- Android 第三方建置版本使用選擇器：關閉／使用期間／永遠。Play 建置版本則維持關閉／使用期間。
- 精確位置是獨立的切換開關。
為什麼使用選擇器（而非只有開關）
作業系統的位置權限分為多個層級。精確位置也是作業系統另行授予的權限（iOS 14+ 的 “Precise”，以及 Android 的 “fine” 與 “coarse”）。應用程式內的選擇器會控制要求的模式，但實際授予的權限仍由作業系統決定。
設定模型
每個節點裝置：
location.enabledMode:off | whileUsing | alwayslocation.preciseEnabled: bool
使用者介面行為：
- 選取
whileUsing會要求前景位置權限。 - 在 Android 第三方建置版本中選取
always，會先要求前景位置權限、說明背景存取，接著開啟 Android 應用程式設定，以便另行授予 Allow all the time 權限。 - Android Play 建置版本不會宣告背景位置權限，也不會顯示
always。 - 如果作業系統拒絕要求的層級，應用程式會還原至已授予的最高層級並顯示狀態。
權限對應（node.permissions）
選用。macOS 節點透過 node.list/node.describe 上的 permissions 對應表回報 location；iOS/Android 可能省略此項。
命令：location.get
透過 node.invoke 或命令列介面輔助工具呼叫：
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"}命令列介面旗標會直接對應：--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：系統故障或沒有可用的提供者。
背景行為
- 只有在使用者選取
Always，且 Android 已授予背景位置權限時，Android 第三方建置版本才會接受背景location.get。現有的常駐節點服務會加入location服務類型，並在啟用期間揭露Location: Always。 - Android Play 建置版本和
While Using模式在背景執行時會拒絕location.get。 - 其他節點平台的行為可能不同。
Linux 節點主機
隨附的 Linux 節點外掛會將 location.get 加入命令列介面 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動作（必須指定節點）。 - 命令列介面：
openclaw nodes location get --node <id>。 - 代理程式準則：只有在使用者已啟用位置功能且了解其範圍時才能呼叫。
使用者體驗文案（建議）
- 關閉：“位置分享功能已停用。”
- 使用期間：“僅在 OpenClaw 開啟時。”
- 永遠：“允許在 OpenClaw 於背景執行時進行要求的位置檢查。”
- 精確：“使用精確的 GPS 位置。關閉此選項可分享大概位置。”
