---
read_when:
    - افزودن پشتیبانی از گره مکان یا رابط کاربری مجوزها
    - طراحی مجوزهای مکان Android یا رفتار پیش‌زمینه
summary: فرمان مکان برای Nodeها (location.get)، حالت‌های مجوز، و رفتار پیش‌زمینه در Android
title: دستور موقعیت مکانی
x-i18n:
    generated_at: "2026-05-06T09:28:32Z"
    model: gpt-5.5
    provider: openai
    source_hash: 63ed754bfdda1cf379dcb7ac40817c0b93cc1efe4526512d70258072da4bc8a7
    source_path: nodes/location-command.md
    workflow: 16
---

## خلاصه

- `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` فراخوانی می‌شود.

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

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

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

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

## مرتبط

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