Перейти к основному содержанию

​
Команда 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. Параметры (рекомендуемые): 
{
  "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‑местоположение. Отключите, чтобы передавать приблизительное местоположение».