TAF: TOTVS Web Agent não conecta — quando o problema não é o agente, é o navegador

Um cliente teve o ambiente TAF atualizado. Da noite para o dia o sistema, que antes abria num cliente instalado, passou a rodar no navegador — o SmartClient HTML. Tudo funcionava, com uma exceção que parava o mês inteiro: em Configurações → Configurações TSS, a opção de escolher um arquivo do computador simplesmente não existia mais. Sem ela, não dá para apontar o certificado digital. Sem certificado, não sai eSocial.

Quando um sistema web precisa alcançar um arquivo do seu disco, ele não faz isso sozinho — o navegador não deixa. É para isso que existe o TOTVS Web Agent: um programa pequeno que roda na bandeja do Windows, abre uma porta local e serve de ponte entre a página e o computador.

O agente estava instalado. A tela dizia que não.

Duas causas reais, e ainda assim insuficientes

Reproduzimos o caso do zero numa estação limpa — Windows 11, Chrome 151, Web Agent 1.1.1 x64 — porque diagnosticar na máquina de quem está com o trabalho parado é o caminho mais lento que existe. Na bancada apareceram duas causas verdadeiras.

A primeira: cópias empilhadas. Se uma segunda instância do agente tenta subir na porta que a primeira já ocupa, ela morre imprimindo apenas Could not initialize! — sem dizer o motivo. A mesma falha, executada com --console, é explícita:

Could not initialize WebAgent because port 21021 is already in use

Vale registrar: o modo bandeja esconde a causa. Quem só vê a janela preta piscando não tem como saber o que aconteceu.

A segunda: o parâmetro --browser no atalho. Circula uma orientação de que o atalho deve conter o caminho do executável do navegador em --browser= e uma porta fixa em --port. Medimos: na versão 1.1.1, nenhuma forma do parâmetro funciona — nem o caminho completo do .exe, nem --browser=chrome, nem --browser chrome, nem --browser=msedge. Em todos os casos o agente aborta com

No valid browser to launch

e não chega a abrir socket nenhum. Ou seja: o atalho montado conforme essa orientação garante que nada funcione.

Há um detalhe pior na mesma orientação. Ela manda descobrir a porta clicando no ícone da bandeja — que é a porta do agente que já está rodando — e usar esse número no --port de um novo atalho. Isso sobe uma segunda instância na porta ocupada, que morre na hora. A receita produz exatamente a primeira causa.

Corrigimos as duas. Escrevemos um procedimento. E não funcionou.

O erro que nos custou um dia

Nosso teste de validação era honesto na aparência: subir o agente, servir uma página, e verificar se a página conseguia abrir uma conexão WebSocket com ele. Conexão aberta, teste verde, procedimento aprovado.

A página do teste era servida da rede local. A página real do cliente vem da internet.

Essa diferença — que parecia detalhe de bancada — era a causa inteira.

Fica a lição, que vale para qualquer diagnóstico: o que você substituiu por um dublê conveniente é o suspeito número um. Se no teste você trocou a URL, a origem, a conta ou o ambiente por algo parecido, é exatamente ali que o defeito pode estar escondido. E, se você anotou “não testei tal elo”, essa ressalva precisa aparecer na conclusão — não adianta registrar a dúvida e publicar a certeza.

A causa verdadeira

Navegadores modernos aplicam uma proteção chamada Local Network Access: uma página não pode simplesmente alcançar serviços que rodam dentro da sua máquina ou da sua rede. É uma defesa contra um site qualquer varrer o que existe no seu computador.

Essa proteção tem um degrau importante: para uma página sequer poder pedir essa permissão, ela precisa estar num contexto seguro — na prática, HTTPS. O ambiente que atendíamos era publicado em HTTP simples, num endereço público.

O resultado é que a permissão é negada automaticamente, sem nenhuma pergunta ao usuário. Não aparece aviso, não aparece cadeado para clicar, não há nada na tela que o usuário possa autorizar. Do ponto de vista de quem trabalha, o sistema apenas “não enxerga” o agente.

Medimos os três cenários na mesma máquina, com o mesmo agente rodando na mesma porta, mudando só a origem da página:

O agente estava perfeito o tempo todo. Quem recusava era o navegador.

A correção de verdade não é do cliente

Vale dizer isso com todas as letras: a solução definitiva é o ambiente ser publicado em HTTPS. Enquanto o endereço for http://, cada versão nova de navegador tende a apertar mais esse cerco, e o problema volta.

Há um segundo motivo, que não é de conveniência: estamos falando de um sistema fiscal, no qual se instala o certificado digital da empresa, trafegando sem criptografia pela internet. Isso merece um chamado com o fabricante — nós abrimos o nosso.

Enquanto isso não acontece, existe um contorno legítimo.

O contorno: duas políticas do Chrome

O Chrome permite, por política administrativa e por endereço específico, tratar uma origem HTTP como se fosse segura e conceder o acesso à rede local:

• OverrideSecurityRestrictionsOnInsecureOrigin — é a obrigatória. Sem ela o Chrome nem chega a perguntar.
• LocalNetworkAccessAllowedForUrls — dispensa a pergunta. Só com a primeira, o navegador exibe uma caixa "…quer acessar outros apps e serviços neste dispositivo" e o usuário precisa clicar em Permitir toda vez que a permissão for solicitada.

Ambas valem apenas para o endereço informado. Nenhum outro site é afetado. Ainda assim, são uma redução de proteção do navegador, e existem só porque o ambiente é HTTP — devem ser removidas quando ele passar a HTTPS.

Como aplicar, passo a passo

O procedimento abaixo foi executado do zero numa estação limpa, e as telas são as que você vai ver. Os arquivos citados acompanham este artigo — cada um pergunta o endereço do seu ambiente, então nada precisa ser digitado à mão. São arquivos de texto: abra e leia antes de executar, é o que você deveria fazer com qualquer script baixado da internet, inclusive os nossos.

• 📄 criar-atalho-webagent.cmd — cria o atalho na Área de Trabalho. Não pede administrador.
• 🔐 liberar-webagent-chrome.cmd — aplica as duas políticas. Precisa ser executado como administrador.
• 🧩 webagent-chrome-EXEMPLO.reg — opcional, e só para quem administra o domínio. É o mesmo conteúdo do arquivo acima, em formato .reg, para quem vai aplicar em várias máquinas de uma vez por Política de Grupo (GPO) do Active Directory. Nele o endereço não é perguntado: é preciso editar o arquivo e trocar o endereço de exemplo pelo do seu ambiente, nas duas linhas.

Se você vai arrumar uma estação só, use os dois primeiros e ignore o terceiro.

Os três baixam direto. Para ler antes de executar — que é o que recomendamos —, clique com o botão direito no arquivo baixado e abra com o Bloco de Notas: são arquivos de texto comum.

1 · Feche as cópias do agente que já estejam abertas

Na barra de tarefas, clique na seta Mostrar ícones ocultos. Para cada ícone de globo do Web Agent: botão direito → Sair. Precisam sumir todos. Confirme em Ctrl+Shift+Esc → aba Detalhes que não restou nenhum web-agent.exe. Se esta é uma máquina nova, pule para o passo 2.

2 · Instale o Web Agent

Baixe o pacote SMARTCLIENT WEB-AGENT 1.1.1 WINDOWS - X64 na central de downloads do fabricante, extraia o ZIP e execute o instalador. Leva poucos segundos e não pede senha de administrador — ele instala na pasta do seu usuário.

A instalação é rápida e não pede administrador. Ela grava em %LOCALAPPDATA%\Programs\web-agent.

Assim que termina, o instalador já deixa o agente rodando — e é por isso que o Firewall do Windows pergunta na sequência, ainda antes de você usar o sistema. Clique em Permitir.

O aviso do Firewall aparece logo após a instalação, porque o instalador já sobe o agente.

3 · Crie o atalho

Execute o criar-atalho-webagent.cmd. Ele confere se o agente está instalado e pergunta o endereço do seu ambiente — o mesmo que você usa hoje no navegador.

O script encontra o agente sozinho e pede o endereço, com um exemplo do formato esperado.

Cole o endereço e tecle Enter.

O endereço precisa começar com http:// ou https:// — o script recusa qualquer outra coisa.

Pronto: o atalho Sistema TOTVS aparece na Área de Trabalho. Repare no destino e no parâmetro que ele mostra — é o executável do agente, o verbo launch e a URL entre aspas. Sem --browser e sem --port.

O atalho criado, com destino e parâmetro à vista. O ícone Sistema TOTVS aparece na Área de Trabalho, à esquerda.

4 · Libere o navegador — este é o passo obrigatório

Este é o passo que resolve a causa raiz. Execute o liberar-webagent-chrome.cmd — mas ele precisa de administrador. Se você der um duplo clique comum, ele recusa e explica:

Sem administrador o script para antes de gravar qualquer coisa, e diz o que fazer.

Feche, clique com o botão direito no arquivo e escolha Executar como administrador. Agora ele explica o que vai fazer e pede a origem — só protocolo, host e porta, sem caminho no final.

Com administrador, a barra de título mostra “Administrador:”. Note que aqui não vai o /webapp/ do fim.

Informe a origem e tecle Enter. Ele grava as duas políticas e avisa do passo que falta.

As duas políticas gravadas — e o aviso do passo obrigatório que quase todo mundo pula.

5 · Feche o Chrome por completo e confira

Não basta fechar a janela: confirme no Gerenciador de Tarefas que não sobrou nenhum chrome.exe. Depois abra o Chrome e acesse chrome://policy. As duas políticas devem aparecer com Origem Plataforma, Nível Obrigatória e Status OK.

É assim que fica quando deu certo: as duas políticas com Status OK.

A pegadinha: se você aplicou as políticas com o Chrome aberto, elas aparecem aqui com o status “É necessário reiniciar o navegador” — e o botão Atualizar políticas não resolve. Enquanto estiver assim, o sistema continua falhando e parece que o procedimento não funcionou. Feche o Chrome por completo e confira de novo.

6 · Abra o sistema sempre pelo atalho

Por favorito ou digitando o endereço não funciona: é o atalho que informa à página em que porta o agente está escutando.

O que NÃO é sintoma

Três coisas que parecem defeito e não são — e que fazem perder tempo:

• https://localhost:21021 dá erro de certificado. Dá em qualquer máquina, sempre: essa porta é HTTP e WebSocket, não TLS. Não indica problema de certificado, e a versão 1.1.1 não traz arquivo de certificado nenhum. Perseguimos essa pista antes de descartá-la.
• O quadro “TOTVS WebAgent — INSTALAR PARA WINDOWS”, no canto da tela de parâmetros iniciais, é informativo. Ele aparece mesmo com o agente instalado e funcionando.
• Vários ícones de globo quando se usa mais de um ambiente é normal — cada ambiente sobe o seu. O problema é ter várias cópias do mesmo.

E um alerta de robustez que encontramos de brinde: abrir http://localhost:21021 no navegador encerra o agente. Uma requisição HTTP comum na porta derruba o processo com violação de acesso 0xC0000005, registrada no Visualizador de Eventos. Reproduzimos três vezes na 1.1.1. Se você foi testar “se a porta responde” abrindo no navegador, foi você quem matou o agente.

Como conferir que ficou bom

Dois testes, e o segundo é o que realmente importa.

O agente está saudável? No PowerShell:

curl.exe -i --http1.1 -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" http://127.0.0.1:21021/

A resposta precisa conter HTTP/1.1 101 Switching Protocols.

O navegador chega no agente? Com o sistema aberto pelo atalho, tecle F12, vá na aba Console e cole:

new WebSocket('ws://127.0.0.1:21021/').onopen = () => console.log('WEBAGENT OK')

Precisa aparecer WEBAGENT OK.

Repare que o primeiro teste passa mesmo com o sistema quebrado — foi exatamente ele que nos enganou. É o segundo que prova o elo que faltava.

Uma observação de porta: aberto pelo atalho, o agente usa uma porta sorteada, não a 21021. Ela aparece no fim do endereço da página, em agent-port:

.../webapp/?agent-started=launch&agent-port=55550

Nesse caso, troque 21021 pelo número que estiver ali, nos dois testes.

Se mesmo assim não voltar

Se, com os dois testes passando, a opção de arquivos locais continuar sem aparecer, o problema deixou de ser o agente e o navegador — é do próprio sistema. A diferença é que agora você tem evidência para abrir o chamado: consegue demonstrar que o agente responde e que a página o alcança.

Que é, no fim, a única coisa que faz um chamado andar.

Caso real, anonimizado. Se a sua empresa passou por isso — ou por qualquer sistema web que precisa alcançar um programa na estação — fale com a Ellos.