Diagnóstico de Conexão de Nós

Node Connect

Objetivo: corrigir um cliente exato contra um Gateway exato e, em seguida, provar a conexão nova desse cliente.

1. Bloquear o alvo

Registre o ambiente/perfil alvo, o binário OpenClaw, a raiz de configuração/estado, a URL/porta do Gateway e o serviço antes de alterar qualquer coisa.

• Use o wrapper/perfil de implantação nomeado para cada comando de configuração, log, serviço, dispositivo e nó.
• Nunca desvie para um openclaw simples, ambiente de prova ou implantação com nome semelhante.
• Se o executável global estiver desatualizado, invoque o alvo através de seu proprietário.
• Verifique se status, configuração, logs e identidade do processo descrevem o mesmo Gateway.

Identifique o Gateway alvo antes de alterar o pareamento ou a autenticação.

2. Classificar o cliente

Classifique a partir da solicitação e do log do Gateway antes de escolher comandos:

• Navegador Control UI: o usuário menciona navegador, dashboard, Control UI ou webchat; os logs mostram client=openclaw-control-ui ou mode=webchat.
• Mobile/nó nativo: o aplicativo oficial mostra Conectar, Escanear QR ou código de configuração; os logs/metadados da solicitação mostram um cliente nativo ou role=node.

Um telefone pode ser qualquer cliente. Não use openclaw qr ou openclaw nodes status para um navegador de telefone; esses comandos pertencem ao pareamento mobile/nó nativo.

3. Observar a tentativa de falha

Execute estes comandos através do alvo bloqueado:

openclaw gateway status --deep
openclaw logs --follow --json
openclaw devices list
openclaw config get gateway.mode
openclaw config get gateway.bind
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.allowTailscale
openclaw config get gateway.tailscale.mode

Peça ao cliente para tentar novamente uma vez enquanto os logs estão ativos. Correlacione seu ID de cliente, modo, plataforma, endereço, resultado de autenticação, ID de dispositivo, usuário e código de fechamento. Ignore outros dispositivos pareados.

Interprete a primeira transição com falha:

• Nenhuma tentativa de Gateway correspondente: problema de rota, DNS, TLS, origem ou proxy.
• token_missing, password_missing, incompatibilidade ou falha de identidade Tailscale: a autenticação falhou antes do pareamento, portanto, uma lista de pendências vazia é esperada.
• pairing required: rota e autenticação bem-sucedidas; aprove a solicitação pendente exata.
• client connected: corresponda conn, client, mode e role ao cliente exato. A admissão precede a resposta de hello; se for seguida por 1006, preserve autenticação/pareamento e inspecione a entrega do hello, ciclo de vida, transporte, proxy ou reconexão. Versões mais antigas usam registros sobrepostos de authenticated user connected / webchat connected que omitem clientes efêmeros.
• 1006 sem um registro de admissão em nível de aplicação correspondente não prova autenticação/pareamento; inspecione a transição de handshake anterior.

4. Provar a rota

Escolha uma topologia: mesma máquina, LAN, tailnet ou proxy reverso público. Não as misture.

• O navegador Control UI precisa de HTTPS ou localhost para a identidade do dispositivo do navegador. Uma URL HTTP simples remota via Tailnet/LAN não é um substituto válido.
• gateway.tailscale.mode=off significa que o OpenClaw não está gerenciando Serve/Funnel. Isso não prova que o Tailscale ou uma rota Serve gerenciada externamente está ausente.
• Quando o Tailscale estiver envolvido, inspecione o estado ativo em vez de inferi-lo da configuração do OpenClaw:

tailscale status --json
tailscale serve status --json

Corresponda a URL do cliente ao listener/rota de proxy que alcança o Gateway bloqueado.

5A. Rota do navegador Control UI

Restaure a autenticação do navegador antes de procurar uma solicitação de pareamento:

• Para autenticação por token/senha, insira a credencial nas configurações do Control UI. Nunca coloque segredos permanentes em chat, logs ou URLs.
• Prefira openclaw dashboard no host do Gateway para uma transferência assinada de uso único. Use --no-open apenas quando o operador puder recuperar a área de transferência desse host, e mantenha o navegador/área de transferência do host fora das ferramentas do agente. Nunca capture dashboard --json: isso pode expor a transferência e credenciais compartilhadas. Nunca retransmita, reescreva ou envie uma URL de transferência de loopback para um telefone remoto.
• Para Tailscale Serve, verifique a rota ativa e a identidade encaminhada. Habilite gateway.auth.allowTailscale apenas para esse limite de confiança pretendido. A autenticação Control UI verificada do Tailscale com identidade de dispositivo de navegador pode pular o pareamento.

Após a autenticação ser bem-sucedida:

• Tente novamente; nunca infira pareamento da tentativa pré-autenticação. A autenticação por token/senha pode revelar pairing required; a identidade Tailscale verificada pode pular.
• Se os logs disserem pairing required, reliste dispositivos e aprove o ID de solicitação exato.
• Uma conexão bem-sucedida com Tailscale verificado pode corretamente não criar nenhuma linha de dispositivo pendente ou pareado.
• Após um 1006 repetido, preserve autenticação/pareamento e inspecione evidências de reconexão.

5B. Rota mobile/nó nativo

Inspecione a rota nativa através do alvo bloqueado sem expor a credencial de configuração:

openclaw qr --json | jq '{gatewayUrl, gatewayUrls, auth, access, accessDowngraded, urlSource}'

Para uma CLI controlando um Gateway remoto, adicione --remote antes de --json; ele seleciona gateway.remote.url e credenciais remotas. Se o filtro de redação não estiver disponível, não execute JSON bruto de QR em saída visível pelo agente.

Verifique gatewayUrl e urlSource. O código de configuração é equivalente a senha: peça ao operador para copiá-lo de Control UI → Dispositivos → Parear dispositivo, ou execute openclaw qr --setup-code-only em um terminal fora das ferramentas do agente e cole diretamente no aplicativo oficial. Nunca o retransmita através da saída do agente/chat/ferramenta. Gere um código novo após uma correção de URL/autenticação ou expiração.

Se o aplicativo relatar pairing required:

openclaw devices list
openclaw devices approve --latest   # apenas pré-visualização; sai sem aprovação
openclaw devices approve <requestId>
openclaw nodes status

--latest apenas pré-visualiza a solicitação atual; nunca trate como aprovação. Reliste imediatamente antes do comando de ID exato porque novas tentativas podem substituir a solicitação. Nunca aprove por posição, idade ou semelhança.

6. Correlacionar e finalizar

Antes da aprovação, combine fatos disponíveis de solicitação, dispositivo/chave pública, cliente, modo/função, plataforma, endereço, usuário e tempo de nova tentativa.

Declare sucesso apenas após uma nova tentativa feita após a alteração final provar todas as verificações aplicáveis:

• o cliente exato alcança o Gateway bloqueado;
• a autenticação pretendida é bem-sucedida;
• o navegador completa solicitações iniciais, ou o nó nativo aparece em openclaw nodes status;
• a aprovação usou o ID de solicitação exato; e
• nenhuma falha imediata de autenticação, pareamento ou reconexão se segue.

Um QR/código de configuração, navegador iniciado, lista de pendências vazia, aprovação, contagem de dispositivos pareados ou ping do Tailscale prova apenas uma transição.

Relate o diagnóstico, a rota/faixa de autenticação escolhida, a evidência do cliente exato e qualquer transição com falha restante.