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

Кратко¶

• 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.

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

{
  "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: приложение в фоне, но разрешён только режим «При использовании».
• 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‑местоположение. Отключите, чтобы передавать приблизительное местоположение».