> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Команда Location

# Команда Location (узлы)

## TL;DR

* `location.get` — это команда узла (через `node.invoke`).
* По умолчанию выключено.
* Настройки используют селектор: Выкл. / При использовании / Всегда.
* Отдельный переключатель: Точное местоположение.

## Почему селектор (а не просто переключатель)

Разрешения ОС многоуровневые. Мы можем показать селектор в приложении, но фактическое разрешение всё равно определяет ОС.

* iOS/macOS: пользователь может выбрать **При использовании** или **Всегда** в системных запросах/Настройках. Приложение может запросить повышение уровня, но ОС может потребовать перехода в Настройки.
* Android: фоновое определение местоположения — отдельное разрешение; на Android 10+ часто требуется сценарий через Настройки.
* Точное местоположение — отдельное разрешение (iOS 14+ «Precise», Android «fine» vs «coarse»).

Селектор в UI определяет запрашиваемый нами режим; фактическое разрешение хранится в настройках ОС.

## Модель настроек

Для каждого устройства узла:

* `location.enabledMode`: `off | whileUsing | always`
* `location.preciseEnabled`: bool

Поведение UI:

* Выбор `whileUsing` запрашивает разрешение для работы на переднем плане.
* Выбор `always` сначала обеспечивает `whileUsing`, затем запрашивает фоновый доступ (или отправляет пользователя в Настройки, если требуется).
* Если ОС отклоняет запрошенный уровень, происходит откат к наивысшему выданному уровню с показом статуса.

## Соответствие разрешений (node.permissions)

Необязательно. Узел macOS сообщает `location` через карту разрешений; iOS/Android могут его не указывать.

## Команда: `location.get`

Вызывается через `node.invoke`.

Параметры (рекомендуемые):

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "timeoutMs": 10000,
  "maxAgeMs": 15000,
  "desiredAccuracy": "coarse|balanced|precise"
}
```

Полезная нагрузка ответа:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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`: системный сбой / нет провайдеров.

## Фоновое поведение (будущее)

Цель: модель может запрашивать местоположение, даже когда узел находится в фоне, но только если:

* Пользователь выбрал **Всегда**.
* ОС выдала разрешение на фоновое определение местоположения.
* Приложению разрешена работа в фоне для определения местоположения (фоновый режим iOS / foreground service Android или специальное разрешение).

Push‑триггерный сценарий (будущее):

1. Gateway (шлюз) отправляет push на узел (тихий push или данные FCM).
2. Узел кратковременно пробуждается и запрашивает местоположение у устройства.
3. Узел пересылает полезную нагрузку в Gateway (шлюз).

Примечания:

* iOS: требуется разрешение «Всегда» + фоновый режим для местоположения. Тихие push‑уведомления могут ограничиваться; ожидайте периодических сбоев.
* Android: фоновое определение местоположения может требовать foreground service; в противном случае ожидайте отказа.

## Интеграция модели/инструментов

* Поверхность инструментов: инструмент `nodes` добавляет действие `location_get` (требуется узел).
* CLI: `openclaw nodes location get --node <id>`.
* Рекомендации для агентов: вызывать только когда пользователь включил определение местоположения и понимает объём доступа.

## Тексты UX (рекомендуемые)

* Выкл.: «Передача местоположения отключена».
* При использовании: «Только когда OpenClaw открыт».
* Всегда: «Разрешить фоновое определение местоположения. Требуется системное разрешение».
* Точное: «Использовать точное GPS‑местоположение. Отключите, чтобы передавать приблизительное местоположение».