Node 위치 정보 가져오기: 설정부터 API 호출까지

사용자 기기의 위치 정보를 가져오는 작업은 생각보다 까다로워요. OS마다 권한 정책이 다르고, 포그라운드와 백그라운드 상태에 따라 결과가 달라지기도 하죠. “왜 내 기기에서는 안 되지?”라는 의문이 들 때가 많았을 거예요. OpenClaw는 이런 복잡한 과정을 단순한 설정과 API로 해결해 줍니다.

What You’ll Need

이 기능을 사용하려면 다음 항목이 필요해요.

• 위치 권한 설정이 가능한 Node 기기
• Gateway 연결 권한

Quick Start: 5분 안에 위치 정보 가져오기

Node의 위치 정보는 기본적으로 꺼져 있어요. 아래 단계에 따라 설정을 확인하고 데이터를 요청해 보세요.

1. 위치 모드 설정

Node 기기의 UI에서 location.enabledMode를 설정해야 해요. 단순한 스위치가 아니라 OS 권한과 연동되는 셀렉터 방식이에요.

• While Using: 앱을 사용 중일 때만 위치 정보를 가져와요.
• Always: 백그라운드에서도 위치 정보를 가져올 수 있어요. (시스템 설정 필요)
• Precise Location: 더 정확한 GPS 좌표가 필요할 때 켭니다.

2. location.get 호출하기

node.invoke를 통해 명령을 보낼 수 있어요. CLI를 사용한다면 아래 명령어를 입력하세요.

openclaw nodes location get --node <id>

API를 직접 호출할 때는 다음과 같은 JSON 페이로드를 사용해요.

Request:

{
  "timeoutMs": 10000,
  "maxAgeMs": 15000,
  "desiredAccuracy": "coarse|balanced|precise"
}

Response: 성공하면 기기에서 다음과 같은 데이터를 보내줍니다.

{
  "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"
}

Troubleshooting

문제가 발생하면 다음 에러 코드를 확인해 보세요.

• LOCATION_DISABLED: 설정에서 위치 공유 셀렉터가 ‘Off’ 상태예요.
• LOCATION_PERMISSION_REQUIRED: 요청한 모드에 필요한 OS 권한이 없어요.
• LOCATION_BACKGROUND_UNAVAILABLE: 앱이 백그라운드에 있지만 ‘While Using’ 권한만 허용된 상태예요.
• LOCATION_TIMEOUT: 정해진 시간 내에 위치 정보를 찾지 못했어요.
• LOCATION_UNAVAILABLE: 시스템 오류나 하드웨어 문제로 위치 정보를 가져올 수 없어요.

궁금한 점이 더 있다면 AI Setup Assistant에게 물어보세요.

What’s Next

• Permissions mapping: node.permissions를 통한 권한 상태 확인법
• Background behavior: 푸시 알림을 이용한 백그라운드 위치 업데이트 원리