Como conectar chaves de API personalizadas e indexar o espaço de trabalho no CodeGPT para VS Code

No Visual Studio Code, usar o CodeGPT apenas colando trechos isolados no chat impede que a inteligência artificial compreenda a arquitetura global do projeto. Para transformar a extensão em um assistente ciente de todo o repositório, capaz de explicar lógicas complexas e executar refatorações seguras entre múltiplos arquivos, os desenvolvedores precisam dominar duas etapas fundamentais: conectar chaves de API personalizadas (modalidade BYOK e endpoints customizados) e indexar o contexto do workspace local (Codebase Indexing). Com essa base configurada, a ferramenta de busca semântica integrada e os modos de perfil permitem auditar e refatorar código diretamente no editor.

1. Conectando chaves de API personalizadas (BYOK e endpoints customizados)

O CodeGPT funciona com um sistema híbrido: novos usuários recebem um limite inicial gratuito (30 interações mensais), mas fluxos de desenvolvimento profissional geralmente exigem o modelo BYOK (Bring Your Own Key) ou planos de equipe. Ao utilizar suas próprias chaves de API, você elimina restrições de mensagens impostas pela plataforma e paga o custo de tokens diretamente ao provedor do modelo escolhido.

Passo a passo para configurar provedores e chaves

1. Instalação e sincronização: Na aba de extensões do VS Code, instale a extensão CodeGPT: AI Coding Agents & Chat (publicada por DanielSanMedium). Abra a barra lateral do CodeGPT e faça login com Google, GitHub ou e-mail para sincronizar seu perfil.
2. Acessar o painel de provedores:
   • Na parte inferior do painel de chat do CodeGPT, clique no botão Manage Models e acesse a aba Providers.
   • Ou abra a paleta de comandos do VS Code (Ctrl+Shift+P no Windows/Linux ou Cmd+Shift+P no macOS) e execute o comando CodeGPT: Set API KEY.
3. Selecionar o provedor de IA:
   • O CodeGPT oferece suporte nativo para OpenAI, Anthropic, Google AI Studio, DeepSeek, Mistral, Cohere, Groq, Cerebras, Perplexity, além de servidores locais como Ollama e LM Studio.
   • Cole a chave de API gerada no console oficial do serviço (por exemplo, no painel da OpenAI ou Anthropic). Se a conta possuir identificador de organização, informe o Organization ID.
4. Configurar endpoints compatíveis com OpenAI (Custom Provider):
   • Para modelos hospedados em infraestrutura própria (como vLLM ou instâncias remotas do Ollama) ou proxies empresariais, selecione Custom na lista de provedores.
   • Digite o nome do modelo de destino (exemplo: cognitivecomputations/dolphin3.0-mistral-24b:free ou o identificador do seu modelo interno).
   • Insira a respectiva chave de API.
   • Informe a URL completa do endpoint de conclusão (Custom Link, apontando para o endpoint HTTP /chat/completions).
   • Clique em Connect para salvar.
5. Ação obrigatória no modelo BYOK: Após registrar a chave, é indispensável selecionar explicitamente um modelo ativo no menu suspenso do chat. Tentar enviar prompts sem um modelo selecionado resultará no erro: "You must select a model first".

2. Indexando o contexto do espaço de trabalho local (Augmented Context)

Por padrão, modelos de linguagem não enxergam os arquivos que estão fechados no editor nem a estrutura das pastas vizinhas. O recurso de Codebase Indexing do CodeGPT constrói um índice vetorial local para conceder ao assistente visibilidade de todo o repositório.

Destaque manual vs. indexação do repositório

• Seleção manual de código (Highlighting): Ideal para analisar funções isoladas, resolver erros pontuais ou tirar dúvidas conceituais sem envolver outros módulos.
• Indexação do Codebase: Essencial quando as alterações afetam vários arquivos, definições de interfaces residem em diretórios separados ou quando o modelo precisa seguir os padrões de design do projeto.

Como gerar o índice do workspace

1. No menu principal da barra lateral do CodeGPT, localize a seção Augmented Context e clique no botão Codebase.
2. Clique em Create Codebase Index.
3. Na janela de seleção de pastas, escolha a pasta raiz do seu projeto no workspace.
4. O CodeGPT processará os arquivos de código e gerará o banco de dados vetorial localmente.
5. Ao concluir, a ferramenta Semantic Search Tool (Busca Semântica) será habilitada automaticamente para o assistente.

Formas de injetar contexto nas conversas

• Busca semântica autônoma: Ao fazer perguntas sobre módulos interligados, o CodeGPT aciona a Semantic Search Tool para recuperar os blocos de código mais relevantes e adicioná-los ao contexto do prompt.
• Adição manual de arquivos: Clique no botão +Add Context e escolha #Files para fixar arquivos cruciais na conversa, ou digite @ na caixa de texto para referenciar rapidamente arquivos abertos e símbolos.
• Arquivo ativo automático: Nas configurações do CodeGPT (ícone de engrenagem ⚙️), ative a opção que inclui automaticamente o arquivo atualmente aberto no editor em todas as mensagens.

3. Explicando código com contexto abrangente do projeto

Entender sistemas legados ou bibliotecas internas exige analisar tanto a sintaxe imediata quanto as dependências distribuídas pelo repositório.

Modo de perfil recomendado: Search Mode

O CodeGPT conta com três perfis pré-configurados no seletor do chat:

• Chat Mode: Modo de conversação puro, sem acesso a ferramentas do sistema de arquivos.
• Search Mode (Recomendado para explicações): Modo de leitura estruturada. Permite que a IA explore a hierarquia de diretórios, execute buscas semânticas e leia arquivos relacionados sem realizar nenhuma alteração no disco.
• Agent Mode: Modo com controle total para criar, editar, excluir arquivos e executar comandos no terminal integrado.

Roteiro para explicar código

1. Selecionar o trecho de código: No editor do VS Code, selecione a função, classe ou bloco de lógica que deseja investigar.
2. Executar /Explain:
   • No campo de entrada do chat do CodeGPT, digite /Explain e pressione Enter.
   • Ou clique com o botão direito sobre o código selecionado e escolha Explain CodeGPT.
3. Interpretação ciente do projeto: Graças ao índice do workspace, a explicação detalhará de onde vêm os dados passados como argumento, onde estão implementadas as funções auxiliares chamadas e qual papel o trecho cumpre na arquitetura geral.
4. Perguntas complementares: No Search Mode, você pode aprofundar a investigação com comandos como:
   • "Onde este método é chamado ao longo do repositório?"
   • "Como este middleware afeta o fluxo de autenticação das rotas?"

4. Refatorando código com segurança e consistência

Refatorações sem visão global costumam quebrar assinaturas de funções ou introduzir padrões conflitantes. O CodeGPT combina comandos dedicados e ferramentas com permissões controladas para garantir intervenções seguras.

Processo de refatoração

1. Definir o bloco-alvo: Destaque o trecho de código que precisa de modernização, simplificação ou correção estrutural.
2. Disparar o comando /Refactor:
   • No chat, digite /Refactor com as orientações desejadas (exemplo: /Refactor converta o encadeamento de promises em async/await e extraia a validação de dados em uma função separada), pressionando Enter.
   • Ou clique com o botão direito e selecione Refactor CodeGPT.
3. Revisão e aplicação:
   • No Search Mode ou Chat Mode: O CodeGPT exibe no painel de conversa o código refatorado com justificativas técnicas. Clique no botão Insert code (ícone de seta no canto superior direito do bloco de código) para aplicar o código diretamente no arquivo ativo.
   • No Agent Mode: O CodeGPT executa a ferramenta interna Edit File para aplicar a alteração diretamente no disco. Se a aprovação automática não estiver habilitada, você poderá inspecionar e aprovar a modificação antes que ela seja gravada.

Práticas recomendadas para refatorações confiáveis

• Fluxo progressivo (Search → Agent): Comece no Search Mode para mapear o impacto da refatoração nas outras partes do projeto. Validado o planejamento, mude para o Agent Mode para efetuar as edições nos arquivos.
• Validação com testes no terminal: No Agent Mode, peça ao assistente para executar os testes automatizados da aplicação (npm test, pytest, etc.) por meio da ferramenta Run Terminal Command, confirmando que não houve quebra de comportamento.
• Manutenção do índice: Sempre que concluir uma grande rodada de refatorações ou atualizar branches importantes no Git, clique novamente no botão Codebase para reindexar o projeto e manter o banco vetorial alinhado ao código atual.

Referências

• Configuration | CodeGPT
• CodeGPT Chat | CodeGPT
• Profile Modes | CodeGPT
• Internal Tools | CodeGPT
• Explain CodeGPT | CodeGPT
• Refactor CodeGPT | CodeGPT
• 🤖 AI Providers | CodeGPT
• Custom | CodeGPT
• CodeGPT: AI Coding Agents & Chat - Visual Studio Marketplace