Quem atende mais de um cliente com Protheus conhece a cena. Você abre o WebApp do cliente A e tudo funciona. Uma hora depois abre o do cliente B e o sistema oferece a instalação do Web Agent. Você instala, trabalha, volta ao cliente A… e ele pede para instalar de novo.

Neste artigo explicamos por que isso acontece e mostramos o script BAT que usamos para resolver: um menu que troca o Web Agent da máquina para o do cliente escolhido, em segundos, sem reinstalar nada. O código completo está no final, para você copiar e adaptar.

Antes de tudo: o que é o Web Agent

O Web Agent é o agente local do SmartClient WebApp. Rotinas que precisam conversar com a máquina do usuário, como assinatura digital e anexos, passam por ele. No Windows ele fica, por padrão, na pasta C:\Users\<usuário>\AppData\Local\Programs\web-agent e roda na bandeja do sistema. Se você ainda não o instalou, veja o nosso passo a passo em Instalação do WebAgent Protheus.

Por que ele pede reinstalação a cada cliente

Cada ambiente Protheus informa ao WebApp qual agente deve oferecer, na seção [WEBAGENT] do AppServer.INI: a versão (VERSION), a porta e o caminho dos instaladores. Em clientes diferentes, essas informações costumam ser diferentes. Em módulos que usam equipamentos, como o Protheus Varejo, também é comum copiar DLLs para dentro da pasta do agente (veja Configuração do WebApp e WebAgent para uso de equipamentos).

Só que, em cada usuário do Windows, existe uma única pasta web-agent. Ao instalar o agente do cliente B, você sobrescreve a versão e os arquivos do cliente A. Quando volta ao A, o ambiente encontra um agente diferente do que espera e oferece a instalação outra vez. E assim por diante.

Observação: é o comportamento que observamos na prática. Os detalhes variam conforme a versão do Web Agent e do WebApp, e o procedimento oficial de instalação continua sendo o da TOTVS.

A ideia: uma pasta pronta por cliente

Em vez de reinstalar, guardamos uma cópia pronta do Web Agent de cada cliente e, quando precisamos, espelhamos essa cópia sobre a pasta ativa. Como a cópia já é a instalação correta daquele cliente, o ambiente encontra o agente que espera.

%LOCALAPPDATA%\Programs\
 ├─ web-agent               <- a pasta que o sistema realmente usa (a "ativa")
 ├─ web-agent-ClienteA      <- cópia pronta do cliente A
 ├─ web-agent-ClienteB      <- cópia pronta do cliente B
 ├─ WebAgent-Atual.txt      <- guarda qual ambiente está ativo
 └─ WebAgent-Historico.log  <- registro de cada troca

O nome do cliente é o que vem depois de web-agent-. Prefira nomes curtos e sem espaços.

Preparando a máquina (uma vez por cliente)

  1. Instale o Web Agent do cliente A normalmente, pelo WebApp dele.
  2. Feche o Web Agent (ícone na bandeja, opção sair). Copie a pasta web-agent inteira para uma nova pasta ao lado dela, chamada web-agent-ClienteA.
  3. Repita com o cliente B: instale o agente dele (isso sobrescreve a pasta web-agent), feche, e copie para web-agent-ClienteB. Se o cliente usa equipamentos, copie as DLLs dele para a pasta web-agent antes de fazer a cópia.
  4. Salve o script (abaixo) como WEBAGENT.BAT em uma pasta sua, por exemplo C:\ferramentas.

Usando o gerenciador

Dê dois cliques no WEBAGENT.BAT. Ele lista automaticamente todas as pastas web-agent-* que encontrar e mostra qual ambiente está ativo:

============================================================
                GERENCIADOR WEB AGENT
============================================================

Pasta utilizada pelo sistema:
  C:\Users\voce\AppData\Local\Programs\web-agent

Ambiente atualmente instalado:
  ClienteA

============================================================

AMBIENTES DISPONIVEIS:

  [1] ClienteA   <-- ativo
  [2] ClienteB

------------------------------------------------------------

  [H] Ver historico
  [R] Recarregar ambientes
  [0] Sair

============================================================

Escolha uma opcao: 2

Digite o número do ambiente e confirme com S. O script então:

  • confere se as pastas existem e se o ambiente escolhido já não é o ativo;
  • verifica se o web-agent.exe está em execução e, se estiver, pergunta se pode fechá-lo;
  • espelha a pasta do cliente sobre a pasta ativa, sem alterar a pasta de origem;
  • anota o ambiente ativo e registra a troca no histórico.

Pronto: abra o WebApp do cliente e o agente já é o certo. A opção H mostra o histórico:

[12/10/2026 08:41:12] DESCONHECIDO > ClienteB
[12/10/2026 14:05:33] ClienteB > ClienteA
[13/10/2026 09:12:07] ClienteA > ClienteB

Atalho por cliente (modo direto)

Você também pode informar o cliente na linha de comando e pular o menu:

WEBAGENT.BAT ClienteB          → troca e pede confirmação
WEBAGENT.BAT ClienteB /Y       → troca sem perguntas (fecha o Web Agent se estiver aberto)

Crie um atalho do Windows para cada cliente com esse comando e a troca vira um clique. Se a sua pasta de instalação não for a padrão, defina antes a variável de ambiente WEBAGENT_BASE com o caminho da pasta que contém web-agent e as cópias.

Como o script funciona por dentro

  • Descoberta dos ambientes. Um laço for /D %%D in ("%BASE%\web-agent-*") percorre as pastas e monta o menu. O nome exibido é tudo o que vem depois dos 10 primeiros caracteres (web-agent-), por isso o script usa !NOME_PASTA:~10!.
  • Expansão atrasada. As variáveis dentro do laço usam !variavel! (com EnableDelayedExpansion), senão o CMD as leria uma única vez, antes do laço rodar.
  • Fechar o agente. tasklist procura o web-agent.exe; taskkill /F o encerra, depois de você autorizar. Trocar arquivos com o agente aberto causaria erro ou deixaria o ambiente pela metade.
  • Espelhamento com Robocopy. O comando é robocopy "origem" "destino" /MIR /COPY:DAT /DCOPY:DAT /R:2 /W:2 /XJ. /MIR deixa o destino idêntico à origem; /COPY:DAT e /DCOPY:DAT preservam dados, atributos e datas; /R:2 /W:2 tentam duas vezes, esperando 2 segundos; /XJ ignora junctions.
  • Verificação do resultado. O Robocopy devolve códigos de 0 a 7 quando deu certo (por exemplo, 1 = arquivos copiados) e 8 ou mais quando houve falha. O script só confirma a troca se o código for menor que 8.
  • Memória e histórico. O ambiente ativo é gravado em WebAgent-Atual.txt e lido na próxima execução; cada troca é acrescentada ao WebAgent-Historico.log com data, hora e o "de > para".

Cuidados importantes

  • O /MIR apaga no destino o que não existe na origem. É exatamente o que queremos na pasta web-agent, mas por isso o destino deve ser somente a pasta ativa. Confira o caminho antes de usar em outro lugar.
  • Atualizou o Web Agent de um cliente? Refaça a cópia dele: instale, feche e copie a pasta web-agent por cima de web-agent-NomeDoCliente.
  • Feche o navegador do WebApp antes de trocar, para o agente não ser reaberto no meio da troca.
  • Leia antes de executar. Um .bat é texto simples, e o Windows ou o antivírus podem alertar ao rodar um arquivo baixado. Revise o código (ele está abaixo) e teste primeiro com uma cópia das suas pastas.
  • Vale por usuário do Windows. A pasta fica em %LOCALAPPDATA%, que é diferente para cada usuário da máquina.

Se o navegador pedir permissão

Esse é outro assunto, mas costuma ser confundido com o problema acima. Segundo a TOTVS, a partir do Chrome e do Edge 147 há uma camada extra de segurança chamada Local Network Access: na primeira vez que o WebApp é acessado com o Web Agent habilitado, o navegador pede permissão para acessar aplicativos e serviços locais, e sem ela o agente não funciona. Se você bloqueou por engano, libere nas configurações do site. Detalhes na documentação da TOTVS (TDN).

O script completo

Salve como WEBAGENT.BAT (texto simples, sem acentos, para não depender da codificação do Windows). Ele usa, por padrão, %LOCALAPPDATA%\Programs; para outra pasta, defina WEBAGENT_BASE.

@echo off
setlocal EnableExtensions EnableDelayedExpansion
title Gerenciador Web Agent

REM ============================================================
REM  GERENCIADOR WEB AGENT  |  FBS Consultoria
REM
REM  Mantem uma pasta do Web Agent para cada cliente
REM  (web-agent-NOMEDOCLIENTE) e espelha a escolhida na pasta
REM  que o sistema realmente usa (web-agent).
REM
REM  USO
REM    WEBAGENT.BAT                 menu interativo
REM    WEBAGENT.BAT CLIENTE         troca direto (pede confirmacao)
REM    WEBAGENT.BAT CLIENTE /Y      troca direto, sem perguntas
REM
REM  Por padrao usa %LOCALAPPDATA%\Programs. Para outra pasta,
REM  defina antes a variavel WEBAGENT_BASE.
REM ============================================================

if defined WEBAGENT_BASE (set "BASE=%WEBAGENT_BASE%") else (set "BASE=%LOCALAPPDATA%\Programs")
set "DESTINO=%BASE%\web-agent"
set "LOG=%BASE%\WebAgent-Historico.log"
set "CONTROLE=%BASE%\WebAgent-Atual.txt"
set "AUTO=0"

if not exist "%BASE%" (
    echo.
    echo ERRO: pasta base nao encontrada: %BASE%
    echo.
    if not "%~2"=="/Y" if not "%~2"=="/y" pause
    exit /b 1
)
if not exist "%DESTINO%" (
    echo.
    echo ERRO: a pasta web-agent nao foi encontrada: %DESTINO%
    echo Instale o Web Agent uma vez e renomeie/copie a pasta para web-agent-NOMEDOCLIENTE.
    echo.
    if not "%~2"=="/Y" if not "%~2"=="/y" pause
    exit /b 1
)

call :DetectarAmbiente

REM ------------------------------------------------------------
REM  MODO DIRETO: WEBAGENT.BAT CLIENTE [/Y]
REM ------------------------------------------------------------
if not "%~1"=="" (
    if /I "%~2"=="/Y" set "AUTO=1"
    if not exist "%BASE%\web-agent-%~1" (
        echo.
        echo ERRO: nao existe a pasta "%BASE%\web-agent-%~1"
        echo.
        if "!AUTO!"=="0" pause
        exit /b 2
    )
    call :TrocarAmbiente "%~1" "%BASE%\web-agent-%~1"
    exit /b !RESULTADO!
)

:MENU
cls
REM limpa a lista da rodada anterior
for /L %%i in (1,1,60) do (set "AMBIENTE_%%i=" & set "PASTA_%%i=")

echo.
echo ============================================================
echo                 GERENCIADOR WEB AGENT
echo ============================================================
echo.
echo Pasta utilizada pelo sistema:
echo   %DESTINO%
echo.
echo Ambiente atualmente instalado:
echo   !AMBIENTE_ATUAL!
echo.
echo ============================================================
echo.
echo AMBIENTES DISPONIVEIS:
echo.

set "CONTADOR=0"
for /D %%D in ("%BASE%\web-agent-*") do (
    set "NOME_PASTA=%%~nxD"
    set /a CONTADOR+=1
    set "AMBIENTE_!CONTADOR!=!NOME_PASTA:~10!"
    set "PASTA_!CONTADOR!=%%D"
    if /I "!NOME_PASTA:~10!"=="!AMBIENTE_ATUAL!" (
        echo   [!CONTADOR!] !NOME_PASTA:~10!   ^<-- ativo
    ) else (
        echo   [!CONTADOR!] !NOME_PASTA:~10!
    )
)
if !CONTADOR! EQU 0 (
    echo   Nenhum ambiente encontrado. Crie pastas web-agent-NOMEDOCLIENTE em:
    echo   %BASE%
)

echo.
echo ------------------------------------------------------------
echo.
echo   [H] Ver historico
echo   [R] Recarregar ambientes
echo   [0] Sair
echo.
echo ============================================================
echo.

set "OPCAO="
set /p "OPCAO=Escolha uma opcao: "

if not defined OPCAO goto MENU
if /I "!OPCAO!"=="H" goto HISTORICO
if /I "!OPCAO!"=="R" goto MENU
if "!OPCAO!"=="0" exit /b 0

REM aceita apenas numeros (qualquer outra coisa volta ao menu)
set "ESCOLHIDO="
set "NOVO_AMBIENTE="
echo(!OPCAO!| findstr /R "^[1-9][0-9]*$" >nul
if not errorlevel 1 (
    set "ESCOLHIDO=!PASTA_%OPCAO%!"
    set "NOVO_AMBIENTE=!AMBIENTE_%OPCAO%!"
)

if not defined ESCOLHIDO (
    echo.
    echo Opcao invalida.
    ping -n 3 127.0.0.1 >nul
    goto MENU
)

call :TrocarAmbiente "!NOVO_AMBIENTE!" "!ESCOLHIDO!"
goto MENU

REM ============================================================
REM  TROCAR AMBIENTE   (%1 = nome do ambiente, %2 = pasta de origem)
REM ============================================================
:TrocarAmbiente
set "RESULTADO=0"
set "NOVO_AMBIENTE=%~1"
set "ORIGEM=%~2"

if "!AUTO!"=="0" cls
echo.
echo ============================================================
echo                  TROCA DE AMBIENTE
echo ============================================================
echo.
echo   Ambiente atual : !AMBIENTE_ATUAL!
echo   Novo ambiente  : %NOVO_AMBIENTE%
echo   Origem         : %ORIGEM%
echo   Destino        : %DESTINO%
echo.
echo ============================================================
echo.

if not exist "%ORIGEM%" (
    echo ERRO: a pasta de origem nao existe: %ORIGEM%
    set "RESULTADO=2"
    if "!AUTO!"=="0" pause
    exit /b
)

if /I "!AMBIENTE_ATUAL!"=="%NOVO_AMBIENTE%" (
    echo O ambiente %NOVO_AMBIENTE% ja esta ativo.
    if "!AUTO!"=="0" pause
    exit /b
)

if "!AUTO!"=="0" (
    echo ATENCAO: o conteudo de "%DESTINO%"
    echo sera substituido pelo de "%ORIGEM%".
    echo A pasta de origem NAO sera alterada.
    echo.
    set "CONFIRMA="
    set /p "CONFIRMA=Deseja continuar? [S/N]: "
    if /I not "!CONFIRMA!"=="S" (
        echo.
        echo Operacao cancelada.
        ping -n 3 127.0.0.1 >nul
        exit /b
    )
)

REM --- o Web Agent nao pode estar em execucao durante a troca ---
tasklist /FI "IMAGENAME eq web-agent.exe" 2>NUL | find /I "web-agent.exe" >NUL
if not errorlevel 1 (
    echo.
    echo ATENCAO: o web-agent.exe esta em execucao.
    set "FECHAR=S"
    if "!AUTO!"=="0" set /p "FECHAR=Deseja fecha-lo automaticamente? [S/N]: "
    if /I not "!FECHAR!"=="S" (
        echo.
        echo Operacao cancelada. Feche o Web Agent e tente de novo.
        set "RESULTADO=3"
        if "!AUTO!"=="0" pause
        exit /b
    )
    taskkill /F /IM web-agent.exe >nul 2>&1
    ping -n 3 127.0.0.1 >nul
    tasklist /FI "IMAGENAME eq web-agent.exe" 2>NUL | find /I "web-agent.exe" >NUL
    if not errorlevel 1 (
        echo ERRO: nao foi possivel encerrar o Web Agent. A troca foi cancelada.
        set "RESULTADO=3"
        if "!AUTO!"=="0" pause
        exit /b
    )
    echo Web Agent encerrado.
)

echo.
echo Sincronizando... aguarde.
echo.

REM  /MIR  espelha a origem no destino (apaga no DESTINO o que nao existe na origem)
REM  /XJ   ignora junctions   /R:2 /W:2  duas tentativas, 2 s de espera
REM  Somente o destino e alterado: a origem nunca e modificada.
robocopy "%ORIGEM%" "%DESTINO%" /MIR /COPY:DAT /DCOPY:DAT /R:2 /W:2 /XJ /NFL /NDL /NJH /NP
set "ROBOCOPY_RESULT=!ERRORLEVEL!"

if !ROBOCOPY_RESULT! GEQ 8 (
    echo.
    echo ERRO DURANTE A SINCRONIZACAO - codigo ROBOCOPY: !ROBOCOPY_RESULT!
    echo O ambiente pode estar incompleto. A origem nao foi modificada.
    set "RESULTADO=4"
    if "!AUTO!"=="0" pause
    exit /b
)

> "%CONTROLE%" echo %NOVO_AMBIENTE%
>> "%LOG%" echo [%DATE% %TIME:~0,8%] !AMBIENTE_ATUAL! ^> %NOVO_AMBIENTE%
set "AMBIENTE_ATUAL=%NOVO_AMBIENTE%"

echo.
echo ============================================================
echo                 OPERACAO CONCLUIDA
echo ============================================================
echo   Web Agent configurado para: %NOVO_AMBIENTE%
echo   Origem preservada         : %ORIGEM%
echo   Destino atualizado        : %DESTINO%
echo ============================================================
echo.
if "!AUTO!"=="0" pause
exit /b

REM ============================================================
REM  LER O AMBIENTE ATUAL (gravado pela ultima troca)
REM ============================================================
:DetectarAmbiente
set "AMBIENTE_ATUAL=DESCONHECIDO"
if exist "%CONTROLE%" (
    set "AMBIENTE_LIDO="
    set /p "AMBIENTE_LIDO="<"%CONTROLE%"
    if defined AMBIENTE_LIDO set "AMBIENTE_ATUAL=!AMBIENTE_LIDO!"
)
exit /b

REM ============================================================
REM  HISTORICO
REM ============================================================
:HISTORICO
cls
echo.
echo ============================================================
echo                    HISTORICO DE TROCAS
echo ============================================================
echo.
if not exist "%LOG%" (
    echo Nenhuma troca de ambiente foi registrada ainda.
) else (
    type "%LOG%"
)
echo.
echo ============================================================
echo.
pause
goto MENU

Precisa de ajuda com Web Agent e WebApp?

Configurar o WebApp, o Web Agent, equipamentos e vários ambientes de clientes é parte da rotina de quem faz suporte a Protheus. Se você quer apoio nisso, conheça o Suporte Express Protheus ou fale com a nossa equipe.