دستور موقعیت مکانی

# خلاصه

• location.get یک فرمان Node است (از طریق node.invoke).
• به‌صورت پیش‌فرض خاموش است.
• تنظیمات برنامه Android از یک انتخاب‌گر استفاده می‌کند: خاموش / هنگام استفاده.
• کلید جداگانه: موقعیت دقیق.

# چرا انتخاب‌گر (نه فقط یک کلید)

مجوزهای سیستم‌عامل چندسطحی هستند. ما می‌توانیم داخل برنامه یک انتخاب‌گر ارائه کنیم، اما همچنان سیستم‌عامل سطح دسترسی واقعی را تعیین می‌کند.

• iOS/macOS ممکن است هنگام استفاده یا همیشه را در اعلان‌های سیستم/تنظیمات نشان دهد.
• برنامه Android در حال حاضر فقط از موقعیت مکانی پیش‌زمینه پشتیبانی می‌کند.
• موقعیت دقیق یک مجوز جداگانه است (iOS 14+ «دقیق»، Android «fine» در برابر «coarse»).

انتخاب‌گر در UI حالت درخواستی ما را تعیین می‌کند؛ سطح دسترسی واقعی در تنظیمات سیستم‌عامل قرار دارد.

# مدل تنظیمات

برای هر دستگاه Node:

• location.enabledMode: off | whileUsing
• location.preciseEnabled: bool

رفتار UI:

• انتخاب whileUsing مجوز پیش‌زمینه را درخواست می‌کند.
• اگر سیستم‌عامل سطح درخواستی را رد کند، به بالاترین سطح اعطاشده برگرد و وضعیت را نشان بده.

# نگاشت مجوزها (node.permissions)

اختیاری. Node در 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: خرابی سیستم / ارائه‌دهنده‌ای وجود ندارد.

# رفتار پس‌زمینه

• برنامه Android هنگام قرار داشتن در پس‌زمینه location.get را رد می‌کند.
• هنگام درخواست موقعیت در Android، OpenClaw را باز نگه دارید.
• دیگر پلتفرم‌های Node ممکن است متفاوت باشند.

# ادغام مدل/ابزارها

• سطح ابزار: ابزار nodes اقدام location_get را اضافه می‌کند (Node لازم است).
• CLI: openclaw nodes location get --node <id>.
• دستورالعمل‌های عامل: فقط وقتی فراخوانی شود که کاربر موقعیت مکانی را فعال کرده و دامنه آن را می‌فهمد.

# متن UX (پیشنهادی)

• خاموش: «اشتراک‌گذاری موقعیت مکانی غیرفعال است.»
• هنگام استفاده: «فقط وقتی OpenClaw باز است.»
• دقیق: «از موقعیت دقیق GPS استفاده کن. برای اشتراک‌گذاری موقعیت تقریبی، این گزینه را خاموش کن.»

# مرتبط

• تجزیه موقعیت کانال
• ثبت تصویر دوربین
• حالت گفت‌وگو