Extensões para IDE (VS Code e similares)
📚 Navegação da Série: O artigo anterior 08 · Guia de Inicialização do Terminal CLI detalhou a linha de comando do assistente. Esta seção apresenta o acoplamento do Codex no VS Code e editores baseados em Chromium, cobrindo o painel de histórico lateral, mapeamento de caminhos de arquivos e auditorias de diffs integrados. No próximo artigo 10 · Codex em Nuvem (Cloud), explicaremos o processamento remoto de tarefas.
Cabe compartilhar um diálogo real com um colega sobre a instalação:
Colega: "Busquei por
Codexna loja do VS Code e não encontrei nenhuma extensão oficial. Apenas complementos secundários de terceiros." Resposta: "O identificador da extensão oficial do Codex difere do nome do binário. O ID correto na loja éopenai.chatgpt." Colega: "A OpenAI cadastrou a extensão como ChatGPT? Essa particularidade dificulta a busca." Resposta: "Essa nomenclatura também me causou dúvidas na primeira instalação. Basta localizar o desenvolvedor oficial (OpenAI) e prosseguir."
A maior dificuldade inicial da extensão do Codex para IDEs reside na identificação do pacote correto na loja, bem como na sua ativação em editores específicos como o Cursor. Mapearemos estas etapas e as vantagens gráficas de uso.
Ao terminar de ler este artigo, você terá:
- O passo a passo de instalação no VS Code, Cursor e Windsurf
- Como utilizar atalhos de contexto (referências
@filee trechos selecionados), níveis de sandbox e seleção de modelos - O comparativo entre CLI, Aplicativo Desktop e Extensão de IDE
01 Relação entre Interfaces da Central de Trabalho
A extensão para IDEs atua como um wrapper visual sobre o mesmo binário e configurações da CLI do Codex. O arquivo ~/.codex/config.toml (responsável por gerenciar chaves de API, modelos de linguagem e regras de sandbox) é compartilhado globalmente no sistema, mantendo os parâmetros e o histórico de credenciais de forma consistente entre as interfaces.
Analogia: a condução do mesmo veículo por controle remoto ou painel físico. A CLI do Codex assemelha-se ao painel principal: direto, completo e com todas as marchas acessíveis. A extensão do editor funciona como o controle remoto, simplificando ações rotineiras sem exigir a abertura da cabine do terminal, exibindo alterações estéticas e diffs no painel de código. A infraestrutura de hardware (sandbox e arquivos locais) é idêntica.
Comparativo técnico para seleção de interfaces:
| Cenário de desenvolvimento | Terminal CLI | Extensão de IDE | Aplicativo Desktop |
|---|---|---|---|
| Escrita de código ativa no VS Code / Cursor | Aceitável | ✅ Altamente recomendado (mapeamento nativo de arquivos) | Requer alternância de janelas |
| Automatização de scripts locais e deploy em servidores | ✅ Única rota viável | Indisponível | Indisponível |
| Tarefas paralelas em múltiplos projetos locais | Não recomendado | Aceitável | ✅ Altamente recomendado (review pane unificado) |
| Auditoria fina de diffs inline de arquivos | Exibição de logs em console | ✅ Recomendado (diffs gráficos paralelos) | ✅ Recomendado (visualização de branches) |
| Acesso total às flags de sandbox e MCP | ✅ Completo | Acesso parcial (requer chamar a CLI integrada) | Acesso parcial |
Para tarefas focadas na edição direta de código, a integração com a IDE oferece maior agilidade operacional. Para automações e logs de sistema, utilize a CLI integrada do editor.
💡 Resumo em uma frase: Extensões, CLI e o aplicativo desktop operam sob o mesmo motor do Codex, compartilhando credenciais e configurações do sistema.
02 Instalação e Configurações de Interfaces
Editores e Sistemas Operacionais homologados
A extensão do Codex está disponível para o VS Code, Cursor e Windsurf. Para IDEs JetBrains (como PyCharm, IntelliJ e Rider), existe um pacote de compatibilidade específico. macOS, Windows e Linux oferecem suporte total. Ambientes Windows podem rodar a sandbox local nativamente ou integrada ao WSL2.
Nota: O credenciamento técnico de login e conexões de rede exigem rotas livres com os servidores centrais da OpenAI.
Métodos de Instalação
Método 1: Busca na loja de extensões oficial
Abra a aba de extensões (Cmd+Shift+X no macOS). Ao pesquisar na loja, evite o termo Codex. Busque pelo ID openai.chatgpt ou pelo termo ChatGPT e valide se o desenvolvedor oficial cadastrado no campo publisher é a OpenAI. Não instale complementos alternativos de terceiros.
Exemplo de busca na loja do VS Code:
Método 2: Instalação por atalhos diretos
Se o editor de destino estiver aberto na máquina, os comandos abaixo chamam a instalação diretamente:
VS Code : vscode:extension/openai.chatgpt
Cursor : cursor:extension/openai.chatgpt
Windsurf : windsurf:extension/openai.chatgptMétodo 3: Instalação via CLI
Se o binário do editor estiver mapeado nas variáveis do shell, rode:
code --install-extension openai.chatgptNo Cursor, altere o prefixo para cursor --install-extension openai.chatgpt:
Installing extensions...
Extension 'openai.chatgpt' was successfully installed.⚠️ Nota: O ID
openai.chatgptrepresenta o identificador técnico homologado na documentação oficial de extensões da OpenAI.
Ajustes de Leiaute e Localização de Ícones
O painel do Codex é anexado à barra de ferramentas lateral por padrão. Siga o diagnóstico técnico caso o ícone não seja exibido:
| Retorno visual | Editor de destino | Ação corretiva |
|---|---|---|
| Ícone não exibido no menu | VS Code | Reinicie a instância ativa do editor para concluir o carregamento da extensão |
| Ícone oculto ou inexistente | Cursor | O painel do Cursor agrupa extensões adicionais no menu de três pontos da barra de status lateral. Mova o ícone do Codex para a barra principal |
| Mover painel para a esquerda | VS Code | Arraste o ícone da barra lateral direita para a barra lateral esquerda tradicional |
| Mover painel no Cursor | Cursor | Defina activity bar como vertical nas configurações gerais del editor, reposicione o painel do Codex e retorne ao leiaute original |
No Cursor, a disposição horizontal compacta a exibição de ícones de extensões instaladas depois da inicialização. Arraste e fixe o atalho visual do Codex na barra de controle principal.
Autenticação da Sessão
Utilize o credenciamento de login da sua conta do ChatGPT (Plus, Pro ou Enterprise) para carregar as cotas de processamento diretamente. Chaves de API podem ser utilizadas como credenciais secundárias (conforme descrito no Artigo 04).
A extensão do editor gerencia as atualizações de dependências e builds de forma automatizada.
💡 Resumo em uma frase: A extensão oficial possui o ID
openai.chatgptcadastrado pela OpenAI. Reabra o editor após o setup e fixe o ícone de atalho visual.
03 Mapeamento de Contextos de Arquivos
A vantagem da extensão consiste no compartilhamento dos arquivos e buffers ativos na IDE. A documentação técnica detalha: "Ao fornecer o contexto dos arquivos abertos e trechos de código selecionados na IDE, o desenvolvedor diminui a verbosidade dos prompts e otimiza a latência dos retornos" (traduzido).
Analogia: revisões presenciais de plantas de arquitetura. Tentar descrever uma parede por ligação de áudio costuma gerar desalinhamentos de interpretação. Apontar o dedo diretamente para a seção correspondente no papel elimina o ruído. A CLI opera como a ligação telefônica; a extensão atua como o apontamento visual na IDE por meio de caminhos de arquivos e blocos selecionados.
Métodos principais de declaração de contexto:
Método 1: Referência direta via @file
Digite o caractere @ na linha de prompt para listar e anexar caminhos de arquivos locais do repositório:
用 @example.tsx 当参考，给 app 加一个叫 "Resources" 的新页面，
内容是 @resources.ts 里定义的资源列表A instrução define de forma explícita o modelo a ser replicado e a fonte de dados que alimentará a lógica, otimizando o consumo de tokens.
Método 2: Código selecionado e Auto Context
Selecione o trecho de código a ser refatorado diretamente na janela do editor. O Codex adicionará esse escopo como contexto de chamada ativo. A funcionalidade Auto Context anexa de forma transparente os buffers e abas de arquivos abertos recentemente na IDE (pode ser desativada via comando de barra /auto-context).
Comandos globais para gerenciar o contexto na IDE:
| Comando no VS Code | Finalidade técnica |
|---|---|
chatgpt.addToThread | Copia o trecho de código selecionado na IDE para o contexto da conversa ativa |
chatgpt.addFileToThread | Copia o conteúdo completo do arquivo ativo para o contexto da conversa |
Selecionar estruturas de código e enviar prompts curtos como "corriga o alinhamento desse layout flex" agiliza a resolução de bugs de marcação na IDE.
⚠️ Nota: Para anexar capturas de tela e arquivos gráficos por arrasto direto na janela do Codex na IDE, segure a tecla
Shiftpara contornar bloqueios locais de I/O do VS Code.
💡 Resumo em uma frase: Declare escopos específicos de código na IDE com referências
@fileou por seleção direta de blocos para otimizar os retornos.
04 Níveis de Permissões de Sandbox
O aplicativo compacta as configurações de sandbox globais em um seletor visual de três posições abaixo da caixa de entrada do chat (Approval Mode):
Níveis operacionais de aprovação:
| Modo de aprovação | Escopo do Sandbox | Aplicação sugerida |
|---|---|---|
Agent (Padrão) | Leitura e gravação automáticas no diretório de trabalho. Comandos de rede e escritas no sistema requerem aprovação | Desenvolvimento cotidiano e refatorações comuns |
Chat | Apenas leitura (análise passiva). Bloqueia edições físicas em arquivos | Estudos conceituais, consultas de arquiteturas de pastas |
Agent (Full Access) | Acesso irrestrito livre. Desativa interrupções de confirmações locais | Automações em lote em ambientes controlados (recurso de risco) |
Analogia: concessão de credenciais a engenheiros juniores. O modo Chat autoriza o profissional a apenas desenhar planos na lousa, proibindo modificações de código. O modo Agent permite edições na mesa de trabalho, exigindo confirmações antes de acessar a rede local. O modo Agent (Full Access) remove todas as restrições e trancas operacionais do ambiente.
Cenários recomendados de uso:
- Estudo de projetos legados: use o modo Chat para analisar dependências sem riscos de gravações acidentais.
- Programação diária: use o modo Agent para edições pontuais no repositório com interrupções sob acessos externos.
- Automações locais confiáveis: use o modo Agent (Full Access) para agilizar processos repetitivos, retornando à política padrão após a conclusão.
Adote a prática de manter o Codex sob o modo Agent e evite liberar acesso total irrestrito (Full Access) em repositórios corporativos.
💡 Resumo em uma frase: Controle a escrita física na IDE alternando entre o modo Chat (leitura), Agent (sandbox padrão) e Full Access (acesso livre).
05 Seleção de Modelos e Profundidade de Raciocínio
O rodapé do chat reúne seletores rápidos para ajustar o processamento das chaves de API:
Modelos: O Codex consome as engines padrão da OpenAI. Troque o modelo ativo no seletor inferior para otimizar custos de tokens: use builds rápidas para revisões estéticas e reserve builds completas para lógicas de algoritmos.
Reasoning Effort (Esforço de Raciocínio): Controla a profundidade de processamento das engines. O seletor oferece três opções: low, medium e high (homologado na documentação oficial de Configuration Reference):
Analogia: distribuição de tempo em exames. Níveis baixos como low realizam avaliações superficiais de sintaxe. Níveis avançados como high criam rotas de auditoria lógica interna antes de responder. A documentação técnica oficial sugere manter o esforço em medium por padrão para equilibrar latência e consumo de tokens, acionando o nível high apenas sob algoritmos de alta complexidade.
| Modo de processamento | Escolha de Modelos | Nível de Esforço (Reasoning) |
|---|---|---|
| Localização | Seletor na barra inferior do chat | Integrado ao seletor de modelos por instância |
| Opções disponíveis | Mapeamento dinâmico (OpenAI/Locais) | low / medium / high |
| Critério técnico | Otimização de custos de chaves | Equilíbrio de latência e consumo de tokens |
| Ajuste sugerido | Builds oficiais recomendadas | Padrão em medium; high para algoritmos |
💡 Resumo em uma frase: Gerencie chaves de API mantendo o raciocínio em
mediumpara tarefas comuns e acionando o nívelhighem refatorações complexas.
06 Comandos de Barra e Processamento Remoto
Comandos de Barra da IDE
Os comandos de barra acionados na caixa de chat controlam o comportamento do agente local (homologados na documentação de referências oficiais de comandos):
| Comando de barra | Finalidade técnica |
|---|---|
/status | Exibe o ID da thread ativa, consumo de tokens e status de rede |
/auto-context | Ativa ou desativa a inclusão automática de buffers ativos na IDE |
/local | Configura o pipeline de escrita para o diretório local (pasta ativa) |
/cloud | Delega a escrita e a execução de sandbox para servidores remotos (Cloud) |
/cloud-environment | Permite selecionar e configurar sandboxes virtuais em nuvem |
/review | Executa rotina de auditoria de alterações locais comparando com a branch base |
/goal | Define uma meta lógica persistente na sessão |
/feedback | Abre formulário de feedback técnico e envia logs locais para análise |
⚠️ Nota: Prompts conceituais como
/explainnão constam na lista oficial da extensão. O console lerá estas diretrizes em formato texto limpo de chat. Comandos de barra destinam-se ao controle operacional do assistente.
Delegação de Tarefas em Nuvem
A extensão permite transferir o processamento de sandboxes pesadas para a infraestrutura em nuvem do Codex, monitorando o progresso diretamente no painel da IDE:
- Crie uma sandbox virtual (Cloud) no painel de configurações do Codex no ChatGPT.
- Aponte a extensão da IDE para o ambiente virtual criado e confirme a ação em nuvem.
O Codex permite disparar tarefas na nuvem a partir do estado atual da branch principal (main) ou importando modificações pendentes no seu diretório físico. A thread mantém o histórico de contexto carregado, permitindo que a IA continue o desenvolvimento de forma transparente e retorne os diffs de escrita para consolidação local.
Geralmente deixo correções rápidas rodando localmente no editor e delego suítes longas de compilação ou rotinas de refatoração para processamento remoto via comando /cloud, liberando os recursos locais da máquina.
💡 Resumo em uma frase: Os comandos oficiais da IDE gerenciam o sandbox local e conexões de rede. O comando
/cloudterceiriza tarefas complexas para sandboxes na nuvem.
07 Prática: Configurando o Codex no VS Code
Siga os passos a seguir para validar o mapeamento de arquivos e a exibição de diffs inline:
Passo 0: Crie o diretório de testes e abra na IDE
No macOS / Linux (no Windows PowerShell, use mkdir):
mkdir -p ~/codex-ide-demo && cd ~/codex-ide-demo
printf 'def greet(name):\n return "Hello " + name\n\nprint(greet("world"))\n' > demo.py
code .Saída esperada: Inicialização do VS Code focada na pasta. O arquivo demo.py estará visível na árvore de arquivos.
Passo 1: Autentique a extensão
Abra a janela do Codex anexada no menu lateral. Caso o ícone esteja oculto, verifique os menus de três pontos. Insira as credenciais da sua conta do ChatGPT na tela de autenticação.
Saída esperada: O painel exibirá a caixa de diálogos com seletores de modelos e sandbox ativos.
Passo 2: Selecione blocos de código para refatoração
Selecione o método greet no editor, confirme se o Approval Mode está configurado como Agent e envie o prompt:
帮我把它改成用 f-string，并加上类型注解Saída esperada: O Codex lerá o bloco selecionado na IDE e gerará o diff correspondente (f-strings e tipagem estática), exibindo as alterações de forma paralela no painel do editor.
Passo 3: Mude para análise estática (Chat)
Altere o seletor para o modo Chat e envie a diretriz de arquitetura:
给这个文件加上命令行参数支持，让用户能从终端传入名字，先说说你打算怎么改Saída esperada: O assistente proporá a inclusão do módulo argparse no formato descritivo, bloqueando alterações diretas nos arquivos físicos até que você mude para o modo Agent.
Passo 4: Verifique as estatísticas
Digite no prompt:
/statusSaída esperada: Exibição das métricas ativas da thread. O pipeline essencial da IDE está configurado e funcional.
08 Atalhos de Teclado Customizados
Mapeamento de Atalhos na IDE
As ações da extensão podem ser mapeadas para atalhos de teclado no VS Code através do painel de atalhos:
- Abra o painel de comandos do editor (
Cmd+Shift+Pno macOS). - Selecione a opção Preferences: Open Keyboard Shortcuts.
- Digite
Codexou IDs de comandos e configure a tecla de atalho desejada:
| Identificador do comando | Atalho padrão (macOS) | Finalidade técnica |
|---|---|---|
chatgpt.newChat | Cmd+N (Cursor/IDE) | Inicializa nova thread |
chatgpt.openSidebar | Não configurado | Exibe ou oculta a barra lateral do Codex |
chatgpt.newCodexPanel | Não configurado | Inicializa nova aba de chat no editor principal |
chatgpt.addToThread | Não configurado | Anexa o código selecionado à thread ativa |
chatgpt.addFileToThread | Não configurado | Anexa todo o arquivo aberto à thread |
chatgpt.implementTodo | Não configurado | Resolve comentários TODO marcados no código |
⚠️ Nota: Atalhos legados descritos em guias antigos não estão ativos nas builds atuais. Configure suas teclas de preferência no painel de atalhos do editor.
Parâmetros da extensão na IDE
As configurações estruturais do Codex residem no ~/.codex/config.toml. A IDE gerencia apenas parâmetros estéticos e comportamentais da janela gráfica:
| Chave de Configuração | Finalidade técnica |
|---|---|
chatgpt.openOnStartup | Exibe o painel do Codex automaticamente ao inicializar o editor |
chatgpt.commentCodeLensEnabled | Exibe botões do CodeLens acima de comentários TODO para resolução rápida |
chatgpt.localeOverride | Força um idioma específico para as respostas da extensão |
chatgpt.runCodexInWindowsSubsystemForLinux | Windows: Executa a sandbox física do Codex dentro do WSL2 (reinicia o editor) |
Windows usuário autodetect: Usuários do Windows devem ativar
runCodexInWindowsSubsystemForLinuxcaso o repositório físico e as dependências estejam localizados dentro do WSL2, reiniciando o VS Code para aplicar as alterações.
Terminal CLI integrado
A extensão compartilha as configurações do binário local. Execute o comando codex no console integrado do VS Code para dispor dos comandos da CLI no mesmo repositório.
💡 Resumo em uma frase: Customize atalhos na IDE no menu Keyboard Shortcuts. Use o console integrado do editor executando
codexpara tarefas avançadas.
09 Resumo
A extensão para IDEs reúne a facilidade dos painéis visuais com o mesmo motor e chaves da CLI do Codex.
Tópicos essenciais revisados:
| Tópico essencial | Diretriz e Ações |
|---|---|
| Arquitetura unificada | Compartilha configurações globais do config.toml, credenciais e sandbox com a CLI |
| Identificador correto | Pacote registrado na loja sob o ID openai.chatgpt da OpenAI |
| Mapeamento de arquivos | Vinculação estática do escopo de código por atalhos @file ou por seleção na tela |
| Modos de Sandbox | Seletor Approval Mode: Chat (leitura), Agent (padrão) e Full Access (acesso livre) |
| Ajustes operacionais | Alternância rápida de modelos de linguagem e esforço de raciocínio no rodapé do chat |
| Comandos de controle | Uso de comandos oficiais no prompt de chat (/status, /cloud, /review) |
Com essas etapas consolidadas, você está apto a gerenciar a extensão na IDE de desenvolvimento, importando escopos de código para prompts precisos e controlando sandboxes locais.
O próximo artigo 10 · Codex em Nuvem (Cloud) detalhará a execução de sandboxes em nuvem. Explicaremos o processamento remoto de tarefas, conexões de repositórios remotos no GitHub e automações integradas para entregas de Pull Requests.