Solução de problemas

Cada seção abaixo começa pelo que você vê na tela. Se o seu caso não estiver aqui, colete um diagnóstico com o passo a passo em Coletar um diagnóstico.

“dsh web authentication required” no navegador

Causa: você abriu http://127.0.0.1:3082/ sem o token, num navegador que ainda não entrou no painel.

Solução: abra uma vez o endereço completo, com ?token=.

neuro-harness open

Ou copie o endereço que neuro-harness url mostra. Depois disso, o navegador guarda o acesso por 30 dias, mesmo depois de reiniciar o Harness. No app desktop isso não acontece. Veja Painel e acesso pelo navegador.

“Sua conta do GitHub não tem acesso” na instalação

O instalador para com a mensagem Sua conta do GitHub não tem acesso a monrars1995/neuro-harness. Peça acesso ao dono do repositório.

Causa: os repositórios do Neuro Harness são privados, e a conta com que você entrou no GitHub não tem acesso a eles. O acesso é antecipado.

Solução:

Confira qual conta está conectada:
Terminal
```
gh auth status
```

Se for a conta errada, saia e entre com a conta que tem acesso:

gh auth logout
gh auth login --web --git-protocol https --hostname github.com

Se a conta certa ainda não tem acesso, peça ao dono do repositório e rode o instalador de novo.

“não consegui baixar o neuro-mv-edit” no setup

O setup falha com não consegui baixar o neuro-mv-edit v1.8.0 (repositório privado: gh auth login ou chave SSH), ou mostra ✗ neuro-ads-manager: não consegui baixar v0.1.0.

Causa: o git da máquina não consegue clonar os repositórios privados do motor ou do plugin.

Solução: dê acesso ao git e rode o setup de novo.

gh auth login --web
gh auth setup-git
git ls-remote https://github.com/monrars1995/neuro-mv-edit
neuro-harness setup

O git ls-remote deve listar as referências do repositório. Se ele pedir senha ou devolver 404, a conta não tem acesso.

O macOS não abre o app (Gatekeeper)

Causa: o app ainda não tem assinatura de código nem notarização da Apple.

Solução: clique com o botão direito no app, escolha Abrir e depois Abrir de novo. Ou tire a quarentena pelo Terminal:

xattr -dr com.apple.quarantine "/Applications/Neuro Harness.app"

Se o app está em ~/Applications, troque o caminho. O instalador de uma linha já tira a quarentena.

“O Windows protegeu o computador” (SmartScreen)

Causa: o instalador do app ainda não tem assinatura de código.

Solução: clique em Mais informações e depois em Executar assim mesmo.

Erro de permissão no cache do npm

O setup falha ao instalar o DeepSeek Harness com um erro de permissão do npm, ou o doctor mostra ~/.npm tem arquivos do root.

Causa: a pasta ~/.npm tem arquivos que pertencem ao root, um problema antigo do npm que aparece depois de um sudo npm. Nas sessões, outra causa possível é a sandbox: ela só deixa gravar na pasta de trabalho, em /tmp e no TMPDIR.

Solução:

Devolva a pasta ao seu usuário (macOS e Linux):
Terminal
```
sudo chown -R "$(id -u):$(id -g)" ~/.npm
```
Rode neuro-harness setup de novo.
Nas sessões, suba o Harness sempre pelo neuro-harness start ou pelo app. Eles apontam o cache npm das sessões para uma pasta temporária, gravável na sandbox. O doctor mostra qual é.

A porta 3082 está ocupada

Causa: outro programa usa a porta 3082. Nesse caso, o Harness sobe numa porta livre, e o endereço http://127.0.0.1:3082/ não abre o painel.

Solução: use o endereço que o Harness mostra, com a porta certa:

neuro-harness url

Para fixar outra porta, defina NEURO_HARNESS_PORT e reinicie. Veja Variáveis de ambiente. Para descobrir quem está na porta:

lsof -i :3082

Get-NetTCPConnection -LocalPort 3082

lsof -i :3082

“o Harness não subiu”

O start falha com o Harness não subiu; veja ~/.neuro-harness/harness.log e mostra o fim do log.

Causa: o processo do Harness saiu ou não mostrou o endereço em 90 segundos. Se a mensagem for Harness não instalado: rode neuro-harness setup, o Harness ainda não foi instalado.

Solução:

Leia o fim do ~/.neuro-harness/harness.log.
Rode neuro-harness doctor e resolva os itens reprovados.
Rode neuro-harness setup e depois neuro-harness start.

O comando neuro-harness não é encontrado

Causa: o terminal foi aberto antes da instalação, e o PATH dele não tem ~/.neuro-harness/bin.

Solução: abra um terminal novo. Se ainda não funcionar:

macOS e Linux: confira se o ~/.zshrc, o ~/.bashrc ou o ~/.profile tem a linha que termina em # neuro-harness. Ela não é escrita se NEURO_HARNESS_NO_RC=1 estava definida.
Windows: confira se %USERPROFILE%\.neuro-harness\bin está no PATH do usuário.

“winget não encontrado” no Windows

Causa: o Windows não tem o winget, que o instalador usa para instalar as dependências.

Solução: instale o Instalador de Aplicativo pela Microsoft Store e rode o instalador de novo.

“Feche e abra o PowerShell e rode de novo”

O instalador para com essa mensagem depois de instalar o Node.js, o git, o Python, o FFmpeg ou o GitHub CLI.

Causa: o PowerShell aberto ainda não enxerga as ferramentas que acabaram de ser instaladas.

Solução: feche o PowerShell, abra outro e rode o mesmo comando de instalação. O instalador pula o que já está instalado.

“Gerenciador de pacotes não suportado” no Linux

Causa: o instalador só conhece apt, dnf e pacman.

Solução: instale à mão o Node.js 22+, o git, o Python 3.10+, o FFmpeg e o GitHub CLI e rode o instalador de novo.

O app pede “Instalar o que falta”

Causa: falta alguma dependência do sistema, como o Node.js 22+ ou o login no GitHub.

Solução: clique em Instalar o que falta. O app abre o Terminal (ou o PowerShell) com o instalador. Siga a janela, que pode pedir a senha do computador e o login no GitHub. O app continua sozinho quando o instalador termina. Para ver o que falta, rode neuro-harness deps.

A sessão pede aprovação para gravar um arquivo

Causa: as sessões rodam no modo workspace-write. Gravar fora da pasta de trabalho (~/Neuro) e das pastas temporárias pede aprovação. Isso acontece, por exemplo, ao salvar um perfil em ~/.neuro-mv-edit.

Solução: aprove o pedido no painel. Para não precisar de aprovação, trabalhe com arquivos dentro de ~/Neuro.

O agente não acha o comando neuro-mv-edit

Causa: o Harness subiu antes de o plugin ser instalado, a sessão é antiga ou o motor não está instalado.

Solução: rode neuro-harness doctor. Se o motor ou o plugin estiver ausente, rode neuro-harness setup. Depois, rode neuro-harness restart e abra uma sessão nova.

MISSING_CREDENTIAL ou saldo insuficiente numa sessão

Causa: não há chave para o provedor do modelo escolhido, ou a conta do provedor está sem saldo.

Solução: veja a tabela em Provedores e chaves.

Coletar um diagnóstico

Antes de pedir ajuda, junte estas informações:

A versão da distribuição:
Terminal
```
neuro-harness version
```
A conferência completa:
Terminal
```
neuro-harness doctor
neuro-harness deps
```
O log do Harness, em ~/.neuro-harness/harness.log (%USERPROFILE%\.neuro-harness\harness.log no Windows). O log é zerado a cada start: copie-o antes de reiniciar.