Saltar para o conteúdo principal

​
Solução de problemas do Node

Use esta página quando um node estiver visível no status, mas as ferramentas do node falharem.

​
Escada de comandos

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
Em seguida, execute verificações específicas do node: 
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
Sinais saudáveis:
  • O Node está conectado e pareado para a função node.
  • nodes describe inclui a capacidade que você está chamando.
  • As aprovações de exec mostram o modo/lista de permissões esperados.

​
Requisitos de primeiro plano

canvas.*, camera.* e screen.* funcionam apenas em primeiro plano em nodes iOS/Android. Verificação e correção rápidas: 
openclaw nodes describe --node <idOrNameOrIp>
openclaw nodes canvas snapshot --node <idOrNameOrIp>
openclaw logs --follow
Se você vir NODE_BACKGROUND_UNAVAILABLE, traga o app do node para o primeiro plano e tente novamente.

​
Matriz de permissões

CapacidadeiOSAndroidApp de node no macOSCódigo de falha típico
camera.snap, camera.clipCâmera (+ microfone para áudio do clipe)Câmera (+ microfone para áudio do clipe)Câmera (+ microfone para áudio do clipe)*_PERMISSION_REQUIRED
screen.recordGravação de Tela (+ microfone opcional)Prompt de captura de tela (+ microfone opcional)Gravação de Tela*_PERMISSION_REQUIRED
location.getDurante o uso ou Sempre (depende do modo)Localização em primeiro plano/segundo plano com base no modoPermissão de localizaçãoLOCATION_PERMISSION_REQUIRED
system.runn/a (caminho do host do node)n/a (caminho do host do node)Aprovações de exec obrigatóriasSYSTEM_RUN_DENIED

​
Pareamento versus aprovações

Estes são bloqueios diferentes:
  1. Pareamento do dispositivo: este node pode se conectar ao gateway?
  2. Aprovações de exec: este node pode executar um comando de shell específico?
Verificações rápidas: 
openclaw devices list
openclaw nodes status
openclaw approvals get --node <idOrNameOrIp>
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"
Se o pareamento estiver ausente, aprove primeiro o dispositivo do node. Se o pareamento estiver ok, mas system.run falhar, corrija as aprovações de exec/lista de permissões.

​
Códigos comuns de erro do node

  • NODE_BACKGROUND_UNAVAILABLE → o app está em segundo plano; traga-o para o primeiro plano.
  • CAMERA_DISABLED → alternância da câmera desativada nas configurações do node.
  • *_PERMISSION_REQUIRED → permissão do SO ausente/negada.
  • LOCATION_DISABLED → o modo de localização está desativado.
  • LOCATION_PERMISSION_REQUIRED → o modo de localização solicitado não foi concedido.
  • LOCATION_BACKGROUND_UNAVAILABLE → o app está em segundo plano, mas existe apenas a permissão Durante o uso.
  • SYSTEM_RUN_DENIED: approval required → a solicitação de exec precisa de aprovação explícita.
  • SYSTEM_RUN_DENIED: allowlist miss → comando bloqueado pelo modo de lista de permissões.

​
Loop rápido de recuperação

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
Se ainda estiver com problemas:
  • Reaprovar o pareamento do dispositivo.
  • Reabrir o app do node (primeiro plano).
  • Conceder permissões de SO novamente.
  • Recriar/ajustar a política de aprovação de exec.
Relacionado: