Location command (nodes)

요약

  • location.get은 node 명령입니다(node.invoke를 통해).
  • 기본적으로 비활성화되어 있습니다.
  • 설정은 선택기를 사용합니다: Off / While Using / Always.
  • 별도 토글: Precise Location.

선택기를 사용하는 이유 (단순 스위치가 아닌)

OS 권한은 다단계입니다. 앱 내에서 선택기를 노출할 수 있지만 실제 부여는 OS가 결정합니다.

  • iOS/macOS: 사용자는 시스템 프롬프트/설정에서 While Using 또는 Always를 선택할 수 있습니다. 앱이 업그레이드를 요청할 수 있지만 OS가 설정을 요구할 수 있습니다.
  • Android: 백그라운드 위치는 별도 권한입니다; Android 10+ 이상에서는 종종 설정 흐름이 필요합니다.
  • 정확한 위치는 별도 부여입니다(iOS 14+ "Precise", Android "fine" vs "coarse").

UI의 선택기는 요청된 모드를 구동합니다; 실제 부여는 OS 설정에 있습니다.

설정 모델

Node 장치당:

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

UI 동작:

  • whileUsing 선택 시 포그라운드 권한을 요청합니다.
  • always 선택 시 먼저 whileUsing을 확보한 다음 백그라운드를 요청합니다(필요한 경우 사용자를 설정으로 보냅니다).
  • OS가 요청된 수준을 거부하면 가장 높은 부여 수준으로 되돌리고 상태를 표시합니다.

권한 매핑 (node.permissions)

선택 사항입니다. macOS node는 권한 맵을 통해 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: 앱이 백그라운드 상태이지만 While Using만 허용됩니다.
  • LOCATION_TIMEOUT: 시간 내에 위치를 찾지 못했습니다.
  • LOCATION_UNAVAILABLE: 시스템 실패 / 제공자 없음.

백그라운드 동작 (향후)

목표: node가 백그라운드 상태일 때도 모델이 위치를 요청할 수 있지만 다음 조건에서만:

  • 사용자가 Always를 선택했습니다.
  • OS가 백그라운드 위치를 부여합니다.
  • 앱이 위치를 위해 백그라운드에서 실행할 수 있습니다(iOS 백그라운드 모드 / Android 포그라운드 서비스 또는 특별 허용).

푸시 트리거 흐름(향후):

  1. Gateway가 node에 푸시를 보냅니다(사일런트 푸시 또는 FCM 데이터).
  2. Node가 잠시 깨어나고 장치에서 위치를 요청합니다.
  3. Node가 페이로드를 Gateway로 전달합니다.

참고:

  • iOS: Always 권한 + 백그라운드 위치 모드 필요. 사일런트 푸시가 제한될 수 있습니다; 간헐적 실패 예상.
  • Android: 백그라운드 위치는 포그라운드 서비스가 필요할 수 있습니다; 그렇지 않으면 거부 예상.

모델/도구 통합

  • 도구 인터페이스: nodes 도구가 location_get 액션을 추가합니다(node 필요).
  • CLI: openclaw nodes location get --node <id>.
  • Agent 가이드라인: 사용자가 위치를 활성화하고 범위를 이해할 때만 호출합니다.

UX 카피 (권장)

  • Off: "위치 공유가 비활성화되어 있습니다."
  • While Using: "OpenClaw가 열려 있을 때만."
  • Always: "백그라운드 위치를 허용합니다. 시스템 권한이 필요합니다."
  • Precise: "정확한 GPS 위치를 사용합니다. 끄면 대략적인 위치를 공유합니다."
← 문서로 돌아가기