OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Nodes and media

Comando de localização

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

Was this useful?
On this page

On this page