Como o Desktop usa o seu ambiente Node

O HagiCode Desktop usa o node e o npm externos instalados no seu sistema. Instale o Node.js antes de abrir o Desktop pela primeira vez e confirme que os dois comandos estão disponíveis no PATH do sistema.

Este FAQ explica como o Desktop encontra seu ambiente externo de Node, onde os Agent CLIs são instalados e como resolver problemas quando o Node ou o npm não é encontrado.

Requisitos de versão

É necessário o Node.js 24 ou superior (o requisito mínimo também é 24). O npm é instalado junto com o Node.js. Para instalar, veja Instalar o Node.js.

O Git também precisa ser instalado por você; veja o Guia de instalação.

Como o Desktop encontra o node e o npm

Ao iniciar, o Desktop lê o PATH do sistema e procura nele node, npm e git. Isso significa que:

• A versão que você vê ao executar node --version no terminal normalmente é a que o Desktop usa.
• O Desktop apenas usa o seu ambiente Node; ele não o substitui nem o modifica.
• Se você instalar ou atualizar o Node.js com o Desktop já aberto, feche-o por completo e abra-o novamente para que ele leia o novo PATH.

Gerenciadores de versões e PATH

No macOS e no Linux, gerenciadores de versões como nvm e fnm costumam definir o PATH apenas nos arquivos de configuração do shell. O Desktop aberto pelo Dock, pelo menu de aplicativos ou por um ícone da área de trabalho não lê essas configurações e pode não encontrar o node. Abra o Desktop a partir de um terminal em que o node já funcione ou use uma instalação em nível de sistema.

Onde os pacotes gerenciados, como os Agent CLIs, são instalados

A página de gerenciamento de dependências do Desktop descobre o node e o npm no PATH, exibe o prefixo global do npm resolvido e instala os pacotes de CLI listados no catálogo nesse diretório global externo.

Para cada CLI gerenciado, o Desktop procura o executável na seguinte ordem:

1. Um caminho gerenciado já existente
2. O diretório bin global do npm (no Windows, inclui os scripts de inicialização .cmd e .ps1)
3. O PATH

As configurações de espelho do npm se aplicam às operações de instalação e de sincronização. A desinstalação também atua no diretório global externo e exige confirmação na interface. Você pode usar o comando abaixo para ver o diretório global atual:

npm prefix -g

Se o diretório global estiver em um local que exige privilégios de administrador, podem ocorrer erros de permissão durante a instalação; consulte Configurar o diretório global do npm.

O que fazer se aparecer que o Node ou o npm não foi encontrado

1. Execute node --version no terminal e confirme que o Node.js está na versão 24 ou superior. Depois, execute npm --version para confirmar que o npm está disponível.
2. Se não estiverem instalados ou a versão for muito antiga, instale primeiro o Node.js fora do Desktop.
3. Feche o Desktop por completo e abra-o novamente; depois, volte à página de dependências e clique em atualizar.

Quando o Desktop avisar que um pacote de CLI precisa ser instalado manualmente, execute o comando indicado em um terminal fora do Desktop e, ao terminar, volte ao Desktop e atualize uma vez para que ele detecte novamente.