---
read_when:
    - افزودن پشتیبانی از Node مکان یا رابط کاربری مجوزها
    - طراحی مجوزهای مکان Android یا رفتار پیش‌زمینه
summary: فرمان موقعیت مکانی برای Nodeها (`location.get`)، حالت‌های مجوز، و رفتار پیش‌زمینه در Android
title: دستور موقعیت مکانی
x-i18n:
    generated_at: "2026-04-29T23:08:23Z"
    model: gpt-5.5
    provider: openai
    source_hash: fcd7ae3bf411be4331d62494a5d5263e8cda345475c5f849913122c029377f06
    source_path: nodes/location-command.md
    workflow: 16
---

## خلاصه

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

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

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

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

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

## مدل تنظیمات

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

- `location.enabledMode`: `off | whileUsing`
- `location.preciseEnabled`: bool

رفتار رابط کاربری:

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

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

اختیاری. Node در macOS مقدار `location` را از طریق نگاشت مجوزها گزارش می‌کند؛ iOS/Android ممکن است آن را حذف کنند.

## دستور: `location.get`

از طریق `node.invoke` فراخوانی می‌شود.

پارامترها (پیشنهادی):

```json
{
  "timeoutMs": 10000,
  "maxAgeMs": 15000,
  "desiredAccuracy": "coarse|balanced|precise"
}
```

محموله پاسخ:

```json
{
  "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>`.
- دستورالعمل‌های عامل: فقط زمانی فراخوانی شود که کاربر مکان را فعال کرده و محدوده را درک می‌کند.

## متن رابط کاربری (پیشنهادی)

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

## مرتبط

- [تجزیه مکان کانال](/fa/channels/location)
- [گرفتن عکس با دوربین](/fa/nodes/camera)
- [حالت گفت‌وگو](/fa/nodes/talk)
