Solução de problemas do gac

May 18, 2026 · View on GitHub

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | हिन्दी | Tiếng Việt | Français | Русский | Español | Português | Norsk | Svenska | Deutsch | Nederlands | Italiano

Este guia cobre problemas comuns e soluções para instalar, configurar e executar o gac.

Índice

1. Problemas de Configuração

Problema: Comando uvx não encontrado

  • Instale uv seguindo as instruções em astral.sh/uv
  • Garanta que uv está instalado e no seu $PATH
  • Reinicie seu terminal após a instalação

2. Problemas de Configuração

Problema: gac não consegue encontrar sua chave de API ou modelo

  • Se você é novo, execute uvx gac init para configurar interativamente seu provedor, modelo e chaves de API
  • Certifique-se de que seu .gac.env ou variáveis de ambiente estão configurados corretamente
  • Execute uvx gac --log-level=debug para ver quais arquivos de configuração são carregados e depurar problemas de configuração
  • Verifique erros de digitação nos nomes das variáveis (ex: GAC_GROQ_API_KEY)

Problema: Alterações no nível de usuário $HOME/.gac.env não são detectadas

  • Certifique-se de que você está editando o arquivo correto para o seu SO:
    • No macOS/Linux: $HOME/.gac.env (geralmente /Users/<seu-usuario>/.gac.env ou /home/<seu-usuario>/.gac.env)
    • No Windows: $HOME/.gac.env (tipicamente C:\Users\<seu-usuario>\.gac.env ou use %USERPROFILE%)
  • Execute uvx gac --log-level=debug para confirmar que a configuração no nível de usuário está carregada
  • Reinicie seu terminal ou execute seu shell novamente para recarregar as variáveis de ambiente
  • Se ainda não funcionar, verifique erros de digitação e permissões de arquivo

Problema: Alterações no nível de projeto .gac.env não são detectadas

  • Certifique-se de que seu projeto contém um arquivo .gac.env no diretório raiz (ao lado da sua pasta .git)
  • Execute uvx gac --log-level=debug para confirmar que a configuração no nível de projeto está carregada
  • Se você editar .gac.env, reinicie seu terminal ou execute seu shell novamente para recarregar as variáveis de ambiente
  • Se ainda não funcionar, verifique erros de digitação e permissões de arquivo

Problema: Não consegue definir ou alterar idioma para mensagens de commit

  • Execute uvx gac language (ou uvx gac lang) para selecionar interativamente entre 25+ idiomas suportados
  • Use o flag -l <idioma> para substituir o idioma para um único commit (ex: uvx gac -l zh-CN, uvx gac -l Spanish)
  • Verifique sua configuração com uvx gac config show para ver a configuração atual de idioma
  • A configuração de idioma é armazenada em GAC_LANGUAGE no seu arquivo .gac.env

3. Erros de Provedor/API

Problema: Erros de autenticação ou API

  • Garanta que você definiu as chaves de API corretas para seu modelo escolhido (ex: ANTHROPIC_API_KEY, GROQ_API_KEY)
  • Verifique novamente sua chave de API e status da conta do provedor
  • Para Ollama e LM Studio, confirme que a URL da API corresponde à sua instância local. Chaves de API são necessárias apenas se você ativou a autenticação.
  • Para expiração de token do Claude Code: Execute uvx gac auth para se autenticar novamente rapidamente e atualizar seu token. Seu navegador será aberto automaticamente para OAuth.
  • Para expiração de token do ChatGPT OAuth: Execute uvx gac auth chatgpt login para se autenticar novamente. Seu navegador será aberto automaticamente para OAuth.
  • Para outros problemas de OAuth do Claude Code, consulte o guia de configuração do Claude Code para solução de problemas abrangente.
  • Para outros problemas de OAuth do ChatGPT, consulte o guia de configuração do ChatGPT OAuth para solução de problemas abrangente.
  • Para tokens de sessão do GitHub Copilot expirados: Execute uvx gac auth copilot login para reautenticar via Device Flow. Os tokens de sessão são renovados automaticamente a partir do token OAuth em cache.
  • Para outros problemas do GitHub Copilot, consulte o guia de configuração do GitHub Copilot para solução de problemas completa.

Problema: Modelo não disponível ou não suportado

  • Streamlake usa IDs de endpoint de inferência em vez de nomes de modelo. Garanta que você forneceu o ID do endpoint do console deles.
  • Verifique se o nome do modelo está correto e suportado pelo seu provedor
  • Verifique a documentação do provedor para modelos disponíveis

4. Problemas de Agrupamento de Commits

Problema: Flag --group não funcionando como esperado

  • A flag --group analisa automaticamente as alterações em staging e pode criar múltiplos commits lógicos
  • O LLM pode decidir que um único commit faz sentido para seu conjunto de alterações em staging, mesmo com --group
  • Este é comportamento intencional - o LLM agrupa alterações com base em relacionamentos lógicos, não apenas quantidade
  • Garanta que você tenha múltiplas alterações não relacionadas em staging (ex: correção de bug + adição de funcionalidade) para melhores resultados
  • Use uvx gac --show-prompt para depurar o que o LLM está vendo

Problema: Commits agrupados incorretamente ou não agrupados quando esperado

  • O agrupamento é determinado pela análise do LLM de suas alterações
  • O LLM pode criar um único commit se determinar que as alterações estão logicamente relacionadas
  • Tente adicionar dicas com -h "dica" para guiar a lógica de agrupamento (ex: -h "separar correção de bug de refatoração")
  • Revise os grupos gerados antes de confirmar
  • Se o agrupamento não funcionar bem para seu caso de uso, faça commits das alterações separadamente

5. Segurança e Detecção de Segredos

Importante: A verificação de segredos é executada antes de qualquer chamada à API de IA. Se um segredo for detectado, o fluxo de trabalho é interrompido imediatamente e nenhuma chamada à API é feita. O varredor usa correspondência de padrões baseada em regex (não LLMs), portanto a varredura é rápida e executada inteiramente localmente — seu código nunca é enviado a um modelo de IA para detecção de segredos.

Problema: Falso positivo: verificação de segredos detecta não-segredos

  • O verificador de segurança procura padrões regex que se assemelham a chaves de API, tokens e senhas
  • Se você está fazendo commit de código de exemplo, fixtures de teste ou documentação com chaves de placeholder, você pode ver falsos positivos
  • Use --skip-secret-scan para ignorar a verificação se tiver certeza de que as alterações são seguras
  • Considere excluir arquivos de teste/exemplo dos commits, ou use placeholders claramente marcados

Problema: Verificação de segredos não detectando segredos reais

  • O verificador usa correspondência de padrões baseada em regex (não LLMs) e pode não pegar todos os tipos de segredos
  • Sempre revise suas alterações em staging com git diff --staged antes de fazer commit
  • Considere usar ferramentas de segurança adicionais como git-secrets ou gitleaks para proteção abrangente
  • Relate quaisquer padrões perdidos como issues para ajudar a melhorar a detecção

Problema: Precisa desativar verificação de segredos permanentemente

  • Defina GAC_SKIP_SECRET_SCAN=true no seu arquivo .gac.env
  • Use uvx gac config set GAC_SKIP_SECRET_SCAN true
  • Nota: Desative apenas se você tiver outras medidas de segurança em vigor

6. Problemas com Hooks do Pre-commit e Lefthook

Problema: Hooks do pre-commit ou lefthook estão falhando e bloqueando commits

  • Use uvx gac --no-verify para ignorar temporariamente todos os hooks do pre-commit e lefthook
  • Corrija os problemas subjacentes que estão fazendo os hooks falharem
  • Considere ajustar sua configuração do pre-commit ou lefthook se os hooks forem muito restritivos

Problema: Hooks do pre-commit ou lefthook estão demorando muito ou interferindo no fluxo de trabalho

  • Use uvx gac --no-verify para ignorar temporariamente todos os hooks do pre-commit e lefthook
  • Considere configurar hooks do pre-commit em .pre-commit-config.yaml ou hooks do lefthook em .lefthook.yml para serem menos agressivos para seu fluxo de trabalho
  • Revise sua configuração de hooks para otimizar o desempenho

7. Problemas Comuns de Fluxo de Trabalho

Problema: Nenhuma alteração para fazer commit / nada em staging

  • gac requer alterações em staging para gerar uma mensagem de commit
  • Use git add <arquivos> para colocar alterações em staging, ou use uvx gac -a para colocar todas as alterações em staging automaticamente
  • Verifique git status para ver quais arquivos foram modificados
  • Use uvx gac diff para ver uma view filtrada de suas alterações

Problema: Mensagem de commit não é o que eu esperava

  • Use o sistema de feedback interativo: digite r para reroll, e para editar (TUI in-place, ou editor externo via GAC_EDITOR), ou forneça feedback em linguagem natural
  • Adicione contexto com -h "sua dica" para guiar o LLM
  • Use -o para mensagens mais simples de uma linha ou -v para mensagens mais detalhadas
  • Use --show-prompt para ver quais informações o LLM está recebendo

Problema: gac está muito lento

  • Use uvx gac -y para ignorar o prompt de confirmação
  • Use uvx gac -q para modo silencioso com menos saída
  • Considere usar modelos mais rápidos/baratos para commits de rotina
  • Use uvx gac --no-verify para ignorar hooks se estiverem atrasando você

Problema: Não consigo editar ou fornecer feedback após a geração da mensagem

  • No prompt, digite e para entrar no modo de edição (TUI in-place com keybindings vi/emacs; defina GAC_EDITOR para usar o seu editor preferido)
  • Digite r para regenerar sem feedback
  • Ou simplesmente digite seu feedback diretamente (ex: "torne mais curto", "foco na correção do bug")
  • Pressione Enter na entrada vazia para ver o prompt novamente

8. Depuração Geral

  • Use uvx gac init para redefinir ou atualizar sua configuração interativamente
  • Use uvx gac --log-level=debug para saída de depuração detalhada e logging
  • Use uvx gac --show-prompt para ver qual prompt está sendo enviado para o LLM
  • Use uvx gac --help para ver todos os flags de linha de comando disponíveis
  • Use uvx gac config show para ver todos os valores de configuração atuais
  • Verifique logs para mensagens de erro e stack traces
  • Verifique o README.md principal para recursos, exemplos e instruções de início rápido

Ainda em Dúvidas?

  • Pesquise issues existentes ou abra uma nova no repositório GitHub
  • Inclua detalhes sobre seu SO, versão do Python, versão do gac, provedor e saída de erro
  • Quanto mais detalhes você fornecer, mais rápido sua issue poderá ser resolvida

Onde Obter Ajuda Adicional