---
read_when:
    - Adição de suporte a nós de localização ou interface de permissões
    - Projetando permissões de localização ou comportamento em primeiro plano no Android
summary: Comando de localização para Nodes, modos de permissão da plataforma e configuração do GeoClue no Linux
title: Comando de localização
x-i18n:
    generated_at: "2026-07-16T12:36:03Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 644229c1eafc8fc7b59bc23ba01d4ba95687ea66c4f9bd4a4cda98a87f2b6085
    source_path: nodes/location-command.md
    workflow: 16
---

## TL;DR

- `location.get` é um comando de Node, invocado por meio de `node.invoke` ou `openclaw nodes location get`.
- Desativado por padrão.
- Compilações Android de terceiros usam um seletor: Desativado / Durante o Uso / Sempre. As compilações da Play permanecem com Desativado / Durante o Uso.
- Localização Precisa é uma opção separada.

## Por que um seletor (e não apenas uma opção)

As permissões de localização do SO têm vários níveis. A localização precisa também é uma concessão separada do SO ("Precise" no iOS 14+, "fine" versus "coarse" no Android). O seletor no aplicativo determina o modo solicitado, mas o SO ainda decide a concessão efetiva.

## Modelo de configurações

Por dispositivo Node:

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

Comportamento da interface:

- Selecionar `whileUsing` solicita permissão de primeiro plano.
- Selecionar `always` na compilação Android de terceiros primeiro solicita permissão de primeiro plano, explica o acesso em segundo plano e, em seguida, abre as configurações do aplicativo no Android para a concessão separada **Allow all the time**.
- As compilações Android da Play não declaram permissão de localização em segundo plano nem exibem `always`.
- Se o SO negar o nível solicitado, o aplicativo reverte para o nível mais alto concedido e exibe o status.

## Mapeamento de permissões (node.permissions)

Opcional. O Node do macOS informa `location` por meio do mapa `permissions` em `node.list`/`node.describe`; iOS/Android podem omiti-lo.

## Comando: `location.get`

Chamado por meio de `node.invoke` ou do auxiliar da CLI:

```bash
openclaw nodes location get --node <idOrNameOrIp>
openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000
```

Parâmetros:

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

As opções da CLI são mapeadas diretamente: `--location-timeout` -> `timeoutMs`, `--max-age` -> `maxAgeMs`, `--accuracy` -> `desiredAccuracy`.

Payload da resposta:

```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"
}
```

Erros (códigos estáveis):

- `LOCATION_DISABLED`: o seletor está desativado.
- `LOCATION_PERMISSION_REQUIRED`: falta a permissão para o modo solicitado.
- `LOCATION_BACKGROUND_UNAVAILABLE`: o aplicativo está em segundo plano, mas apenas Durante o Uso foi concedido.
- `LOCATION_TIMEOUT`: nenhuma localização foi obtida a tempo.
- `LOCATION_UNAVAILABLE`: falha do sistema ou nenhum provedor.

## Comportamento em segundo plano

- As compilações Android de terceiros aceitam `location.get` em segundo plano somente quando o usuário selecionou `Always` e o Android concedeu acesso à localização em segundo plano. O serviço persistente existente do Node adiciona o tipo de serviço `location` e informa `Location: Always` enquanto está ativo.
- As compilações Android da Play e o modo `While Using` negam `location.get` enquanto estão em segundo plano.
- Outras plataformas de Node podem apresentar diferenças.

## Host de Node no Linux

O Plugin Linux Node incluído adiciona `location.get` ao serviço `openclaw node` da CLI, incluindo hosts sem interface gráfica que não tenham o aplicativo Linux para desktop. A localização é desativada por padrão. Ative-a na entrada do Plugin e reinicie o serviço do Node:

```json5
{
  plugins: {
    entries: {
      "linux-node": {
        config: {
          location: { enabled: true },
        },
      },
    },
  },
}
```

Instale o GeoClue2 e sua demonstração `where-am-i` (`geoclue-2-demo` no Debian e Ubuntu). O usuário do serviço do Node deve ter permissão concedida pela política do GeoClue e pelo agente de autorização do host.

O Plugin usa `where-am-i` em vez de uma sequência de chamadas `busctl`. O GeoClue vincula a criação do cliente, as propriedades, a inicialização, as atualizações e a interrupção a uma única conexão de cliente D-Bus; a demonstração mantém esse ciclo de vida unificado, enquanto subprocessos `busctl` separados não o fazem. Nenhuma dependência npm é adicionada.

O Linux mapeia `coarse`, `balanced` e `precise` para os níveis de precisão do GeoClue `4`, `6` e `8`. Ele valida `maxAgeMs` em relação ao carimbo de data e hora retornado. A demonstração do GeoClue não expõe o provedor selecionado, portanto `source` é `unknown`; `isPrecise` é verdadeiro somente quando a precisão informada é de 100 metros ou melhor.

O Linux usa os mesmos erros estáveis: `LOCATION_DISABLED`, `LOCATION_TIMEOUT` e `LOCATION_UNAVAILABLE`.

## Integração com modelo e ferramentas

- Ferramenta do agente: a ação `location_get` da ferramenta `nodes` (Node obrigatório).
- CLI: `openclaw nodes location get --node <id>`.
- Diretrizes do agente: chamar somente quando o usuário tiver ativado a localização e compreender o escopo.

## Texto da experiência do usuário (sugerido)

- Desativado: "O compartilhamento de localização está desativado."
- Durante o Uso: "Somente quando o OpenClaw estiver aberto."
- Sempre: "Permita as verificações de localização solicitadas enquanto o OpenClaw estiver em segundo plano."
- Precisa: "Use a localização precisa por GPS. Desative esta opção para compartilhar a localização aproximada."

## Relacionados

- [Visão geral dos Nodes](/pt-BR/nodes)
- [Análise de localização do canal](/pt-BR/channels/location)
- [Captura da câmera](/pt-BR/nodes/camera)
- [Modo de conversa](/pt-BR/nodes/talk)
