Gemini CLI não funciona: corrija erros de instalação, autenticação e arranque
O Gemini CLI não arranca, recusa o seu login com a Google ou devolve "'gemini' is not recognized"? Aqui tem a reparação do PATH do Windows, as duas falhas reais de login com conta Google e a escolha entre OAuth e chave de API — pela ordem que resolve cada um.
Resumo
- "'gemini' is not recognized" depois de uma instalação npm limpa é um problema de PATH, não uma instalação partida. Execute npm config get prefix, adicione a pasta indicada (C:\Users\<você>\AppData\Roaming\npm) ao PATH do utilizador e reabra o terminal.
- O login falha com "This account requires setting the GOOGLE_CLOUD_PROJECT env var"? Contas individuais gratuitas, AI Pro ou AI Ultra NÃO precisam dela — só contas Workspace, licenças Code Assist, menores de 18 anos e regiões sem suporte no nível gratuito.
- "Not eligible for Gemini Code Assist for individuals … 18 years old or older" significa que a sua conta Google não tem idade confirmada. Verifique a idade na página de estado de idade da Google e volte a executar gemini para entrar.
- Ainda bloqueado depois de dois logins falhados? Abandone o OAuth: crie uma chave de API do Gemini no AI Studio e exporte-a como GEMINI_API_KEY — tem o seu próprio nível gratuito. Falhas de autenticação saem com o código 41.
How to Fix Gemini CLI is Not Recognized Error in Windows (Step by Step)
Canal: Web Tech Knowledge4:38
Several error issues encountered when logging into Gemini CLI with a Google account
Canal: AttackOnLife2:56
Troubleshooting — official documentation
Documentação oficial: google-gemini.github.io
Authentication setup — official documentation
Documentação oficial: google-gemini.github.io
Cada comando, mensagem de erro e diálogo desta página foi confrontado com a documentação oficial de autenticação e resolução de problemas do Gemini CLI. A gravação do Windows é a fonte visual da instalação e da reparação do PATH; a do macOS traz as duas falhas reais de login com conta Google e o fluxo de verificação de idade que as resolve.
As capturas pertencem aos seus criadores e ligam ao momento exato; não são usadas imagens com rostos.
Reparar o Gemini CLI, passo a passo
Parte 1 — "'gemini' is not recognized": reparar o PATH do Windows
- 1
Reproduza primeiro a falha exata
Na gravação, o npm install -g @google/gemini-cli termina limpo — "changed 577 packages in 4m" — e escrever gemini devolve mesmo assim "'gemini' is not recognized as an internal or external command, operable program or batch file.". O mesmo no terminal do VS Code. Esta formulação é a assinatura de um problema de PATH: o pacote está instalado, mas o Windows não faz ideia de onde o npm deixou o launcher.
577 pacotes instalados e, ainda assim, o gemini devolve "is not recognized" — sintoma de PATH, não instalação partida.Ver a partir de 0:08 - 2
Pergunte ao npm onde instala os launchers globais
Execute npm config get prefix. Ele imprime a pasta que o npm usa para pacotes globais — aqui C:\Users\User\AppData\Roaming\npm. É exatamente aí que vive o comando gemini, e é essa a pasta que falta no PATH. Anote-a ou mantenha-a na área de transferência.
npm config get prefix imprime C:\Users\User\AppData\Roaming\npm — a pasta que o PATH precisa.Ver a partir de 0:54 - 3
Mostrar o AppData no Explorador de Ficheiros
A pasta npm fica sob o diretório AppData do seu perfil de utilizador, que o Windows oculta por defeito. No Explorador, em C:\Users\User, abra Ver > Mostrar e marque Itens ocultos — a gravação faz exatamente isso e o AppData aparece logo na lista.
Ver > Mostrar > Itens ocultos torna o AppData visível sob C:\Users\User.Ver a partir de 1:30 - 4
Confirmar que o launcher existe na pasta npm
Navegue até AppData > Roaming > npm. Lá está o gemini.cmd — o script de comandos do Windows que o comando gemini executa — ao lado de gemini (o script de shell para Unix) e do node_modules. A existência dele prova que a instalação correu bem e só o PATH está partido.
gemini.cmd, um script de comandos Windows de 347 bytes, dentro de AppData\Roaming\npm.Ver a partir de 2:02 - 5
Abrir a caixa de diálogo Variáveis de Ambiente
Pesquise "variáveis de ambiente" no menu Iniciar, abra "Editar as variáveis de ambiente do sistema" e clique no botão Variáveis de Ambiente. A metade de baixo são variáveis do sistema; a de cima — onde o cursor da gravação aponta para PATH — são as variáveis de utilizador da sua conta. O PATH de utilizador é o lugar certo para uma pasta npm da sua conta.
Caixa Variáveis de Ambiente com o cursor sobre PATH nas variáveis de utilizador.Ver a partir de 2:38 - 6
Adicionar a pasta npm como nova entrada do PATH
Selecione PATH, clique em Editar e depois em Novo, e cole o prefixo npm do passo 2 — C:\Users\User\AppData\Roaming\npm. Confirme com OK em todas as caixas abertas. Na gravação, a lista já contém entradas de Python, Ollama e VS Code; a nova linha vazia fica por baixo. A ordem não influencia esta correção.
Caixa Editar variável de ambiente: a nova entrada PATH vazia selecionada, pronta a receber a pasta npm.Ver a partir de 3:01
Parte 2 — O login falha: resolver os dois erros de conta Google
- 7
Reconhecer os dois erros de login com conta Google
Com o PATH corrigido, o gemini arranca e pergunta como iniciar sessão — escolha "Login with Google". A segunda gravação mostra as duas falhas que bloqueiam logins reais. Erro um: "Failed to login. Message: This account requires setting the GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID env var." Erro dois: "Failed to login. Message: Your current account is not eligible for Gemini Code Assist for individuals. To use Gemini Code Assist for individuals you must be 18 years old or older."
As duas mensagens "Failed to login" tal e qual: a exigência do GOOGLE_CLOUD_PROJECT e a recusa por ser menor de 18.Ver a partir de 0:35 - 8
Não defina GOOGLE_CLOUD_PROJECT se não for preciso
A discussão dos mantenedores #13516, "Clarifying Authentication and Google Cloud Project Settings", mostrada na gravação, esclarece quando a variável é necessária: NÃO a deve definir se inicia sessão como indivíduo com conta gratuita, AI Pro ou AI Ultra. É obrigatória para contas Workspace, licenças Code Assist, menores de 18 anos e contas fora das regiões com nível gratuito. Se a definiu num plano pessoal, remova-a e volte a iniciar sessão.
Discussão gemini-cli #13516: quando NÃO definir o GOOGLE_CLOUD_PROJECT com contas gratuitas, AI Pro e AI Ultra.Ver a partir de 1:05 - 9
Verifique a idade se a Google recusou o login
A recusa "not eligible … 18 years old or older" não trata do seu aniversário real, mas do confirmado. A conta da gravação não tinha idade verificada, por isso a Google mostra a página de estado de idade com "Your age isn't confirmed" e um botão azul Verify your age. Complete esse fluxo (o criador usou o passaporte), volte a executar gemini e escolha Login with Google — o mesmo login agora passa.
"Your age isn't confirmed" com o botão Verify your age — resolvido uma vez, o login passa.Ver a partir de 1:35
Parte 3 — Provar a correção num terminal novo
- 10
Reinicie numa Linha de Comandos totalmente nova
Terminais abertos antes da alteração do PATH guardam o PATH antigo. Feche todas as janelas e abra uma Linha de Comandos nova. Escreva gemini: o banner ASCII GEMINI aparece com "Tips for getting started" e, como a sessão corre na pasta pessoal, a recomendação de usar um diretório de projeto — é um aviso, não um erro.
Primeiro arranque com sucesso: o banner GEMINI e as dicas de início na Linha de Comandos.Ver a partir de 4:08 - 11
Confirme que também funciona no VS Code
A gravação termina no VS Code: com o terminal já aberto numa pasta de projeto real (G:\TestProject), o gemini imprime o banner, mostra "no sandbox" no rodapé e deixa o cursor em "Type your message or @path/to/file". Se o VS Code estava aberto durante a alteração do PATH, feche-o e reabra-o — a mesma regra da Linha de Comandos.
Terminal do VS Code em G:\TestProject com o banner GEMINI e a caixa de entrada pronta.Ver a partir de 4:32
O Gemini CLI continua sem funcionar — as causas mais raras
O PATH e os dois erros de login cobrem a maioria dos casos. Se o Gemini CLI continua pendurado, lento ou com erros depois disso, percorra esta lista de cima para baixo:
- 1Reinstale em vez de adivinhar. A documentação oficial de resolução de problemas manda as falhas de PATH/npm direto para npm install -g @google/gemini-cli@latest; a gravação confirma ainda que o Node.js continua no PATH do sistema — um Node apagado ou um npm a meio de uma atualização deixa o gemini.cmd a apontar para o nada.
- 2Preso em "Initializing" ou à espera da autenticação? Esse ecrã espera que o fluxo OAuth no browser termine. Se nenhum separador abriu, execute o gemini de novo e conclua o Login with Google no separador descrito; um proxy ou uma rede offline penduram-no exatamente neste passo.
- 3A autenticação falha sempre? Um login falhado termina com o código 41, e as credenciais Google em cache vivem em ~/.gemini (oauth_creds.json ao lado de settings.json). Apague as credenciais em cache e execute o gemini de novo — entre limpo em vez de repetir uma sessão partida.
- 4O OAuth nunca termina? Mude de método. A terceira opção do diálogo de autenticação é uma chave de API do Gemini do Google AI Studio: exportada como GEMINI_API_KEY, a CLI salta completamente o fluxo do browser. A documentação recomenda primeiro o login Google, mas a chave de API tem o seu próprio nível gratuito e não exige projeto nem idade.
- 5Erros de acesso a modelos ou de quota? Contas Gmail ligadas ao Workspace podem não ativar o nível gratuito do Code Assist ("Request contains an invalid argument") — as saídas oficiais são definir o GOOGLE_CLOUD_PROJECT com um ID de projeto real ou mudar para a chave de API. Os limites gratuitos repõem-se; os planos pagos AI Pro/Ultra sobem-nos.
- 6Só falha no VS Code? É outra vez a regra do terminal velho: o VS Code herda o PATH no arranque, e uma janela aberta antes da alteração nunca vê a pasta npm. Feche e reabra o VS Code (no mínimo o terminal dele) e volte a tentar o gemini.
Nada disto se aplica? Leia o que a própria CLI registou: os registos e definições vivem em ~/.gemini, e relançar com --verbose imprime mais detalhe; a página oficial de resolução de problemas acaba como os mantenedores — pesquise no issue tracker do gemini-cli no GitHub e abra uma issue nova com a sua versão e o texto completo do erro.