Команда местоположения (узлы)

Кратко

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

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

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

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

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

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

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

  • location.enabledMode: off | whileUsing | always
  • location.preciseEnabled: логическое

Поведение 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 / служба переднего плана Android или специальное разрешение).

Поток, запускаемый push (будущее):

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

Примечания:

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

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

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

UX копия (рекомендуемая)

  • Выкл: "Совместное использование местоположения отключено."
  • Только при использовании: "Только когда OpenClaw открыт."
  • Всегда: "Разрешить фоновое местоположение. Требуется системное разрешение."
  • Точное: "Использовать точное GPS местоположение. Отключите, чтобы делиться приблизительным местоположением."
← Назад к документации