O que é o OpenAI Codex?

O Codex é o agente de codificação da OpenAI. Ele lê um repositório, planeja uma alteração, edita arquivos, executa comandos em um ambiente isolado (sandbox) e fornece um diff para revisão — tudo isso a partir de quatro interfaces que compartilham a mesma configuração: o aplicativo Codex, uma extensão para IDE, uma CLI e um ambiente de nuvem/web para tarefas de longa duração ou em segundo plano. Isso porque todas as quatro leem o mesmo ~/.codex A configuração, um servidor MCP ou um plugin que você configura uma vez, acompanha você tanto no terminal quanto na IDE.

Resumidamente: O Codex é menos uma ferramenta isolada e mais um ambiente de execução — um local onde habilidades, conexões de aplicativos e servidores MCP se integram em torno de uma tarefa de programação, em vez de você ter que recriar a mesma configuração em cada projeto.

Por que os desenvolvedores estão adotando o Codex?

A maioria das comparações de "assistentes de codificação com IA" se concentra na qualidade do modelo, mas a mudança mais interessante é estrutural. O Codex separa três elementos que antes residiam em um único prompt gigante do sistema: instruções (AGENTES.md), procedimentos reutilizáveis (habilidades), e acesso à ferramenta (aplicativos e servidores MCP). Essa separação é o que torna os plugins possíveis — um plugin é apenas um pacote dessas três coisas que você pode instalar e desinstalar como uma unidade, em vez de colar código padrão em cada novo chat.

O resultado prático: uma equipe pode padronizar a forma como o Codex analisa solicitações de pull, lê problemas do Sentry ou elabora documentação, e disponibilizar esse padrão como um pacote instalável em vez de uma página wiki que ninguém lê.

Instalando e configurando o Codex

A interface de linha de comando (CLI) é o meio mais rápido para ver as configurações entrarem em vigor. O Codex armazena as configurações em ~/.codex/config.toml por padrão (substitua por CODEX_HOME (para um perfil específico do projeto).

# Abra o navegador de plugins dentro do CLI codex /plugins # Adicione um servidor MCP diretamente do CLI codex mcp add context7 -- npx -y @upstash/context7-mcp # Veja os servidores MCP ativos em uma sessão em execução /mcp

Para um controle preciso — tempos limite, listas de permissões de ferramentas, modos de aprovação por ferramenta — edite config.toml diretamente. Aqui está um bloco mínimo e realista para um servidor MCP com suporte a streaming HTTP:

[mcp_servers.figma] url = "https://mcp.figma.com/mcp" bearer_token_env_var = "FIGMA_OAUTH_TOKEN" [mcp_servers.figma] startup_timeout_sec = 20 tool_timeout_sec = 45

Plugins vs Skills vs Aplicativos vs MCP

Esses quatro termos são usados ​​indistintamente em textos de marketing, e é exatamente por isso que os iniciantes ficam confusos. Aqui está a distinção que realmente importa quando você está decidindo o que instalar.

Portanto, quando alguém diz "instale o plugin do GitHub", o que realmente é instalado em sua máquina pode ser uma skill, uma conexão de aplicativo, um servidor MCP ou os três — o plugin é apenas o invólucro que torna isso instalável e compartilhável.

O Diretório de Plugins

O Codex organiza os plugins em três grupos, independentemente de você estar navegando por eles no aplicativo ou na linha de comando:

• Com curadoria da OpenAI — Plugins revisados ​​disponíveis para todos os usuários do Codex.
• Compartilhado com vocês — plugins que outro membro do seu espaço de trabalho ChatGPT publicou internamente.
• Criado por você — plugins que você criou e adicionou ao seu próprio espaço de trabalho.

A instalação é a mesma em todos os lugares: abra a página de detalhes do plugin e selecione instalar (ou Instalar plugin Na linha de comando (CLI), conecte qualquer aplicativo externo necessário quando solicitado e, em seguida, inicie uma nova thread antes de usá-lo. Suas configurações de aprovação existentes ainda regem o que o plugin pode fazer depois de estar ativo — a instalação não concede permissões irrestritas.

Para desativar um plugin sem removê-lo, inverta a sua entrada em config.toml:

[plugins."gmail@openai-curated"] ativado = falso

O ecossistema de plugins do Codex

Até o momento da redação deste texto, o diretório selecionado da OpenAI concentra-se em um conjunto específico de ferramentas, em vez de um catálogo extenso de loja de aplicativos — uma escolha deliberada, visto que cada plugin selecionado passou por uma revisão. Plugins de terceiros e plugins criados pela própria OpenAI vão muito além desta lista, mas oferecem diferentes garantias de confiabilidade, portanto, é importante saber a diferença entre eles.

Como ler um cartão de plugin

Neste guia, cada plugin é identificado pelo tipo de limite de confiança que utiliza:

Desenvolvimento

Documentação e Design

Produtividade

Depuração

Implantação

Integração com o GitHub

O GitHub recebe tratamento especial porque o Codex oferece tanto um plugin selecionado quanto uma integração nativa mais profunda — além de uma Ação do GitHub dedicada para execuções acionadas por CI. Na prática, isso significa três pontos de entrada distintos: atribuir o Codex a uma issue pela interface do GitHub, invocá-lo pela linha de comando em um repositório clonado ou acioná-lo a partir de um arquivo de fluxo de trabalho em cada PR. Equipes que padronizam o uso do Codex para revisão de código geralmente começam com a Ação, já que ela não exige que todos os colaboradores tenham o Codex configurado localmente.

Integração do Figma

O Figma se conecta ao Codex por meio do próprio servidor MCP do Figma, em vez de uma integração do lado do Codex, tanto na versão local (aplicativo para desktop) quanto na remota (hospedada). Este é um bom exemplo do modelo de plugin em sua melhor forma: a OpenAI não precisou desenvolver ferramentas específicas para o Figma, apenas ofereceu um bom suporte ao MCP, e o próprio servidor do Figma cuida do resto. A desvantagem é que o comportamento do servidor, os limites de taxa e a confiabilidade ficam fora do controle da OpenAI.

Integração de conceitos

O plugin Notion, cuidadosamente selecionado, reúne funcionalidades de leitura e gravação de páginas e bancos de dados, otimizadas para transformar a saída de engenharia — logs de commits, resumos de pull requests, cronogramas de incidentes — em conteúdo estruturado no Notion. É uma das vantagens mais evidentes para equipes que já consideram o Notion a fonte principal de decisões, pois elimina a necessidade de alguém atualizar o documento manualmente.

Integração com o Slack

Assim como o GitHub, o Slack possui um plugin selecionado e uma integração nativa mais profunda. A diferença prática se manifesta em fluxos de trabalho sensíveis à latência: as integrações nativas tendem a suportar gatilhos mais complexos (uma execução do Codex iniciada a partir de uma mensagem do Slack, e não apenas o Codex publicando no Slack), enquanto um plugin sozinho geralmente é unidirecional, do Codex para o canal.

Integração Sentry

O Sentry é indiscutivelmente o plugin de maior impacto para uma equipe que já entrega resultados rapidamente, pois condensa o processo "perceber o erro → encontrar o rastreamento da pilha → encontrar o commit → propor a correção" em um único ciclo de conversa. A ressalva: o Codex sugerirá uma correção para um problema antigo ou duplicado se você não especificar o escopo da consulta (problemas em aberto, últimas 24 horas, projeto específico), portanto, a especificidade na solicitação é mais importante aqui do que em quase qualquer outro lugar neste guia.

Automação do navegador

Para qualquer operação que dependa de um navegador em vez de uma API — como verificar visualmente uma alteração na interface do usuário, extrair dados de uma página sem API pública ou realizar um fluxo de login — o Codex utiliza os servidores MCP do navegador em vez de um "plugin de navegador" dedicado. Os dois mais mencionados na documentação são o Playwright e o Chrome DevTools, ambos controláveis ​​por meio do MCP. O aplicativo Codex também inclui um navegador integrado e uma extensão para o Chrome, para uma integração mais eficiente entre "visualizar a página" e "editar o código".

Fluxo de trabalho do terminal

A interface de linha de comando (CLI) é onde a configuração de plugins e MCPs é realmente praticada no dia a dia. Alguns comandos que vale a pena memorizar:

/plugins # navegar, instalar e ativar/desativar plugins pelo marketplace /mcp # listar servidores MCP ativos nesta sessão codex mcp add # adicionar um novo servidor MCP a partir do shell codex mcp --help

Nas abas do marketplace do navegador de plugins, pressione Espaço Ao instalar um plugin, essa opção o ativa ou desativa para a sessão atual — útil quando você deseja descartar um plugin como a causa de uma chamada inesperada de ferramenta sem desinstalá-lo completamente.

AGENTES.md

O arquivo AGENTS.md é o recurso mais subutilizado na maioria das configurações do Codex. O Codex o lê antes de executar qualquer operação, construindo uma cadeia de instruções a partir de um arquivo global. ~/.codex/AGENTES.md percorrendo todos os diretórios entre a raiz do seu projeto e o seu diretório de trabalho atual — cada arquivo aninhado sobrepondo-se ou substituindo os arquivos acima dele.

# AGENTS.md ## Expectativas do repositório - Execute `npm run lint` antes de abrir uma solicitação de pull. - Documente as utilidades públicas em docs/ quando você alterar o comportamento.

Aninhado AGENTES.override.md Os arquivos permitem que um subdiretório específico (por exemplo, um serviço de pagamentos com regras mais rígidas) substitua completamente as diretrizes acima dele, em vez de apenas adicioná-las — útil em monorepos onde "executar os testes" significa algo diferente em cada pacote.

Memória

O sistema de memória local do Codex é separado da memória web do ChatGPT e está desativado por padrão. Uma vez ativado, o Codex pode converter o contexto de sessões anteriores elegíveis e ociosas em arquivos de memória local em ~/.codex/memórias/, ocultando segredos à medida que avança e ignorando conversas de curta duração para não resumir um trabalho que ainda está em andamento.

[características] memórias = verdadeiro

Duas configurações que vale a pena conhecer: memórias.usar_memórias controla se as memórias passadas são inseridas em novas sessões, e memories.disable_on_external_context Impede completamente que os chats que dependem de pesquisas na web ou chamadas de ferramentas MCP gerem memória — o que é útil se você não quiser que uma sessão de triagem do Sentry polua a memória com o rastreamento de pilha de outra pessoa.

Engenharia de prompts, contexto e loops

Três habilidades relacionadas, mas distintas, separam os desenvolvedores que lutam contra o Codex daqueles que o utilizam com facilidade para concluir tarefas pendentes.

Engenharia rápida

Especifique o que você deseja mudar e como isso se concretizará, não apenas o sintoma. "Corrigir o teste de finalização de compra instável" é menos eficaz do que "o teste de finalização de compra falha intermitentemente na verificação do código de desconto — reproduza o problema, encontre a condição de corrida e adicione um teste de regressão".

Engenharia de contexto

O problema está no acesso do Codex, não no que você digita: o escopo correto do arquivo AGENTS.md, os servidores MCP corretos habilitados e os arquivos corretos abertos. Mesmo uma solicitação perfeitamente formulada falhará se o Codex não conseguir acessar o arquivo de configuração que controla o comportamento que você está perguntando.

Engenharia de loop

A prática de projetar ciclos repetíveis de propor → executar → verificar → repetir, em vez de instruções únicas — por exemplo, programar o Codex para executar o conjunto de testes após cada alteração e continuar iterando até que esteja tudo certo, em vez de revisar cada tentativa manualmente. O guia do Codex documenta esse padrão diretamente para loops de reparo iterativos.

Fluxos de trabalho multiagentes e subagentes

O Codex suporta subagentes — instâncias de agentes com escopo definido às quais uma sessão principal do Codex pode delegar tarefas específicas. O caso de uso prático é a paralelização de trabalhos independentes: um subagente executa o conjunto de testes e gera relatórios enquanto a sessão principal continua editando, em vez de um único agente executar tudo sequencialmente. Essa é uma funcionalidade mais recente e avançada do que plugins ou MCP, e vale a pena considerá-la como uma otimização após o fluxo de trabalho com um único agente já estar funcionando corretamente, e não como um ponto de partida.

Fluxos de trabalho reais, passo a passo

1. Crie um aplicativo React com o Codex

Primeiro, crie um arquivo AGENTS.md claro (gerenciador de pacotes, comando de teste) e, em seguida, solicite a funcionalidade em termos de resultados. Peça testes junto com o componente, não como uma reflexão tardia.

2. Corrija erros de produção usando o plugin Sentry.

Defina o escopo da consulta, busque a causa raiz antes de corrigi-la e exija um teste de regressão na mesma diferença.

3. Gere a interface do usuário diretamente do Figma

Aponte o Codex para um quadro específico, não para um arquivo inteiro — arquivos grandes tornam a inspeção do MCP mais lenta e aumentam a probabilidade de incluir componentes não relacionados.

4. Escreva a documentação a partir dos commits do GitHub

5. Refatorar uma base de código legada

Peça um plano antes de começar a escrever o código. Refatorações de sistemas legados são onde a engenharia de loops mostra seu valor — peça ao Codex para refatorar um módulo, executar o conjunto de testes e só continuar quando estiver tudo certo.

6. Analise automaticamente as solicitações de pull request

A ação do GitHub é o ponto de partida ideal aqui — ela aciona a revisão do Codex em cada PR, em vez de depender de alguém se lembrar de solicitá-la manualmente.

7. Gerar migrações SQL

Sem um plugin de banco de dados específico, esse processo normalmente é executado por meio de um servidor MCP com escopo de projeto para o seu banco de dados, com a migração sempre revisada e aplicada manualmente, em vez de ser executada automaticamente.

8. Implantar no Vercel

Mantenha as implantações em produção sujeitas a uma etapa de aprovação manual, mesmo quando as implantações em versão prévia se tornarem rotineiras.

Melhores práticas

Dos

• Mantenha o arquivo AGENTS.md conciso e específico — uma regra clara é melhor do que cinco regras vagas.
• Inicie novos plugins em incitar modo de aprovação antes de mudar para auto.
• Desinstale os plugins que você não está usando ativamente — cada ferramenta instalada é uma superfície de ataque.
• Limite as credenciais do servidor MCP ao mínimo necessário para a tarefa.

Coisas que não se deve fazer

• Não confie na memória para regras que devem ser sempre aplicadas — use o arquivo AGENTS.md.
• Não conceda acesso de gravação de produção a um plugin "para economizar uma etapa" — a etapa que ele economiza é justamente aquela que detecta os erros.
• Não agrupe servidores MCP não relacionados em uma mesma sessão só porque estão instalados — cada um adiciona tokens ao contexto e aumenta a possibilidade de confusão entre as ferramentas.

Erros que os iniciantes cometem

• Tratar a instalação de um plugin como uma decisão única, em vez de rever suas permissões à medida que o projeto amadurece.
• Elaborar instruções que descrevam o sintoma em vez do estado final desejado.
• Ignorando completamente o arquivo AGENTS.md e explicando novamente as convenções do projeto em cada prompt.

Lista de verificação para organização de repositórios

• Um arquivo AGENTS.md de nível raiz contendo comando de teste, gerenciador de pacotes e ações proibidas.
• Arquivos AGENTS.override.md aninhados somente onde um subdiretório realmente difere.
• Com escopo definido para o projeto .codex/config.toml para servidores MCP específicos deste repositório
• Segue uma breve lista dos plugins aprovados para este repositório e os respectivos motivos.

Perguntas frequentes

Conclusão

O sistema de plugins é o que transforma o Codex de um excelente autocompletar em um agente que pode se integrar às ferramentas principais da sua equipe — GitHub, Figma, Sentry, Slack, Notion — sem que você precise desenvolver código adicional para elas. Nada disso substitui o bom senso: revise as diferenças, defina os modos de aprovação e mantenha o arquivo AGENTS.md atualizado. Comece com um plugin que resolva um problema real do dia a dia, familiarize-se com as configurações de aprovação e expanda a partir daí. O fluxo de trabalho que economiza mais tempo raramente é o mais complexo — é aquele que você realmente continua usando.