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

# أمر الموقع

# أمر الموقع (العُقد)

## TL;DR

* `location.get` هو أمر عُقدة (عبر `node.invoke`).
* مُعطَّل افتراضيًا.
* تستخدم الإعدادات مُحدِّدًا: إيقاف / أثناء الاستخدام / دائمًا.
* مفتاح تبديل منفصل: الموقع الدقيق.

## لماذا مُحدِّد (وليس مجرد مفتاح)

أذونات أنظمة التشغيل متعددة المستويات. يمكننا عرض مُحدِّد داخل التطبيق، لكن نظام التشغيل هو من يقرر المنح الفعلي.

* iOS/macOS: يمكن للمستخدم اختيار **أثناء الاستخدام** أو **دائمًا** في مطالبات النظام/الإعدادات. يمكن للتطبيق طلب ترقية، لكن النظام قد يتطلب الذهاب إلى الإعدادات.
* Android: الموقع في الخلفية إذن منفصل؛ وعلى Android 10+ غالبًا ما يتطلب مسار إعدادات.
* الموقع الدقيق إذن منفصل (iOS 14+ «Precise»، وAndroid «fine» مقابل «coarse»).

المُحدِّد في واجهة المستخدم يوجّه وضع الطلب لدينا؛ أما المنح الفعلي فيوجد في إعدادات نظام التشغيل.

## نموذج الإعدادات

لكل جهاز عُقدة:

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

سلوك واجهة المستخدم:

* اختيار `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 / خدمة أمامية في Android أو سماح خاص).

تدفّق مُحفَّز بالإشعارات (مستقبلي):

1. يرسل Gateway إشعارًا إلى العُقدة (إشعار صامت أو بيانات FCM).
2. تستيقظ العُقدة لفترة وجيزة وتطلب الموقع من الجهاز.
3. تُمرِّر العُقدة الحمولة إلى Gateway.

ملاحظات:

* iOS: يتطلب إذن «دائمًا» + وضع الموقع في الخلفية. قد يتم تقييد الإشعار الصامت؛ توقّع إخفاقات متقطعة.
* Android: قد يتطلب الموقع في الخلفية خدمة أمامية؛ وإلا فتوقّع الرفض.

## تكامل النموذج/الأدوات

* سطح الأدوات: أداة `nodes` تضيف إجراء `location_get` (العُقدة مطلوبة).
* CLI: `openclaw nodes location get --node <id>`.
* إرشادات الوكيل: لا تُستدعِ إلا عندما يكون المستخدم قد فعّل الموقع ويفهم النطاق.

## نسخة UX (مقترح)

* إيقاف: «مشاركة الموقع مُعطَّلة.»
* أثناء الاستخدام: «فقط عندما يكون OpenClaw مفتوحًا.»
* دائمًا: «السماح بالموقع في الخلفية. يتطلب إذن النظام.»
* دقيق: «استخدام موقع GPS الدقيق. أوقفه لمشاركة موقع تقريبي.»