位置情報コマンド（ノード）

TL;DR

  • location.get はノードコマンドです（node.invoke 経由）。
  • デフォルトでオフ。
  • 設定はセレクターを使用: オフ / 使用中 / 常に。
  • 別個のトグル: 正確な位置情報。

セレクターを使用する理由（単なるスイッチではない）

OS 権限はマルチレベルです。アプリ内でセレクターを公開できますが、実際の許可を決定するのは OS です。

  • iOS/macOS: ユーザーはシステムプロンプト/設定で使用中または常にを選択できます。アプリはアップグレードをリクエストできますが、OS は設定を要求する場合があります。
  • Android: バックグラウンド位置情報は別個の権限です。Android 10+ では、設定フローが必要になることがよくあります。
  • 正確な位置情報は別個の許可です（iOS 14+ 「正確」、Android「fine」vs「coarse」）。

UI のセレクターはリクエストされたモードを駆動します。実際の許可は OS 設定に存在します。

設定モデル

ノードデバイスごと:

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

UI の動作:

  • whileUsing を選択すると、フォアグラウンド権限をリクエストします。
  • always を選択すると、最初に whileUsing を確保し、次にバックグラウンドをリクエストします（または必要に応じてユーザーを設定に送信）。
  • OS がリクエストされたレベルを拒否した場合、最高の許可レベルに戻り、ステータスを表示します。

権限マッピング（node.permissions）

オプション。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: システム障害/プロバイダーなし。

バックグラウンド動作（将来）

目標: ノードがバックグラウンドにある場合でも、モデルは位置情報をリクエストできますが、次の場合のみ:

  • ユーザーが常にを選択しました。
  • OS がバックグラウンド位置情報を許可します。
  • アプリが位置情報のためにバックグラウンドで実行することが許可されています（iOS バックグラウンドモード / Android フォアグラウンドサービスまたは特別な許可）。

プッシュトリガーフロー（将来）:

  1. Gateway がノードにプッシュを送信します（サイレントプッシュまたは FCM データ）。
  2. ノードが短時間起動し、デバイスから位置情報をリクエストします。
  3. ノードがペイロードを Gateway に転送します。

注意:

  • iOS: 常に権限 + バックグラウンド位置情報モードが必要です。サイレントプッシュはスロットルされる場合があります。断続的な障害が予想されます。
  • Android: バックグラウンド位置情報はフォアグラウンドサービスが必要な場合があります。そうでない場合、拒否が予想されます。

モデル/ツール統合

  • ツールサーフェス: nodes ツールは location_get アクションを追加します（ノードが必要）。
  • CLI: openclaw nodes location get --node <id>。
  • エージェントガイドライン: ユーザーが位置情報を有効にし、スコープを理解している場合のみ呼び出します。

UX コピー（推奨）

  • オフ: 「位置情報共有は無効です。」
  • 使用中: 「OpenClaw が開いている場合のみ。」
  • 常に: 「バックグラウンド位置情報を許可します。システム権限が必要です。」
  • 正確: 「正確な GPS 位置情報を使用します。オフにするとおおよその位置情報を共有します。」
← ドキュメントに戻る