คำสั่งตำแหน่ง(โหนด)¶

TL;DR¶

• location.get เป็นคำสั่งโหนด(ผ่าน node.invoke).
• ปิดเป็นค่าเริ่มต้น.
• การตั้งค่าใช้ตัวเลือก: ปิด / ขณะใช้งาน / ตลอดเวลา.
• สวิตช์แยก: ตำแหน่งแบบแม่นยำ.

ทำไมต้องใช้ตัวเลือก(ไม่ใช่แค่สวิตช์)¶

28. สิทธิ์ของระบบปฏิบัติการเป็นแบบหลายระดับ สิทธิ์ของระบบปฏิบัติการมีหลายระดับ เราสามารถแสดงตัวเลือกในแอปได้ แต่ระบบปฏิบัติการยังคงเป็นผู้ตัดสินการอนุญาตจริง

• iOS/macOS: ผู้ใช้สามารถเลือก ขณะใช้งาน หรือ ตลอดเวลา ในพรอมต์/การตั้งค่าระบบ แอปสามารถขออัปเกรดได้ แต่ระบบปฏิบัติการอาจบังคับให้ไปที่การตั้งค่า 29. แอปสามารถขออัปเกรดได้ แต่ระบบปฏิบัติการอาจต้องการการตั้งค่า
• Android: ตำแหน่งเบื้องหลังเป็นสิทธิ์แยกต่างหาก บน Android 10+ มักต้องผ่านโฟลว์การตั้งค่า
• ตำแหน่งแบบแม่นยำเป็นการอนุญาตแยกต่างหาก(iOS 14+ “Precise”, Android “fine” เทียบกับ “coarse”)

ตัวเลือกในUIกำหนดโหมดที่เราขอ แต่การอนุญาตจริงอยู่ในการตั้งค่าของระบบปฏิบัติการ

โมเดลการตั้งค่า¶

ต่ออุปกรณ์โหนด:

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

พฤติกรรมของUI:

• การเลือก whileUsing จะขอสิทธิ์เบื้องหน้า
• การเลือก always จะตรวจสอบ whileUsing ก่อน จากนั้นจึงขอสิทธิ์เบื้องหลัง(หรือส่งผู้ใช้ไปที่การตั้งค่าหากจำเป็น)
• หากระบบปฏิบัติการปฏิเสธระดับที่ขอ ให้ย้อนกลับไปใช้ระดับสูงสุดที่ได้รับอนุญาตและแสดงสถานะ

การแมปสิทธิ์(node.permissions)¶

30. ไม่บังคับ ไม่บังคับ โหนด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บริการเบื้องหน้าหรือการอนุญาตพิเศษ)

โฟลว์ที่ทริกเกอร์ด้วยพุช(อนาคต):

1. Gateway ส่งพุชไปยังโหนด(พุชแบบเงียบหรือข้อมูลFCM)
2. โหนดตื่นชั่วครู่และขอตำแหน่งจากอุปกรณ์
3. โหนดส่งต่อเพย์โหลดไปยัง Gateway

หมายเหตุ:

• iOS: ต้องมีสิทธิ์ตลอดเวลา+โหมดตำแหน่งเบื้องหลัง พุชแบบเงียบอาจถูกจำกัด คาดว่าจะล้มเหลวเป็นครั้งคราว 31. Silent push อาจถูกจำกัดอัตรา คาดว่าจะเกิดความล้มเหลวเป็นครั้งคราว
• Android: ตำแหน่งเบื้องหลังอาจต้องใช้บริการเบื้องหน้า มิฉะนั้นคาดว่าจะถูกปฏิเสธ

การผสานรวมกับโมเดล/เครื่องมือ¶

• พื้นผิวเครื่องมือ: เครื่องมือ nodes เพิ่มแอ็กชัน location_get(ต้องมีโหนด)
• CLI: openclaw nodes location get --node <id>.
• แนวทางเอเจนต์: เรียกใช้เฉพาะเมื่อผู้ใช้เปิดใช้งานตำแหน่งและเข้าใจขอบเขต

ข้อความUX(แนะนำ)¶

• ปิด: “ปิดการแชร์ตำแหน่ง”
• ขณะใช้งาน: “เฉพาะเมื่อ OpenClaw เปิดอยู่”
• ตลอดเวลา: “อนุญาตตำแหน่งเบื้องหลัง ต้องได้รับสิทธิ์จากระบบ” 32. ต้องการสิทธิ์ของระบบ”
• แม่นยำ: “ใช้ตำแหน่งGPSแบบแม่นยำ ปิดเพื่อแชร์ตำแหน่งโดยประมาณ” 33. ปิดสวิตช์เพื่อแชร์ตำแหน่งโดยประมาณ”