Domine 97% dos recursos do Codex em 30 minutos: um tutorial completo

A maioria das pessoas abre o Codex, vê a janela de chat e o trata como um ChatGPT mais sofisticado. Como resultado, 90% dos usuários perdem seus recursos verdadeiramente poderosos.

Eles não sabem criar Skills, não sabem fazer deploy online e não sabem deixar tarefas de automação rodando em segundo plano. Este artigo usará 14 etapas para levar você de uma _pasta vazia_ a um _fluxo de trabalho de IA totalmente funcional_ em 30 minutos.

O Codex é o assistente de programação de IA lançado pela OpenAI — não a API de conclusão de código obsoleta de 2021, mas uma versão totalmente nova. Foi lançado pela primeira vez em abril de 2025 como uma ferramenta de linha de comando (CLI) e, subsequentemente, desenvolvido em aplicativos para desktop, plugins IDE para VS Code/Cursor/Windsurf e uma versão em nuvem.

Sam Altman revelou em abril de 2026 que o Codex já tem cerca de 4 milhões de usuários ativos semanais. Ele é hoje o concorrente mais direto do Claude Code.

Se você já usou o Claude Code, pode entender o Codex em uma frase: Uma pasta local + um arquivo de configuração markdown + um agente de IA que pode ler todos os arquivos + Skills, servidores MCP, tarefas de automação e um navegador integrado.

Diferentes shells de ferramentas, diferentes modelos, mas a mesma filosofia central.

14 etapas. 3 níveis. Uma pasta lida com todos os fluxos de trabalho.

Parte I · Configuração Básica

01. Crie uma pasta de projeto no seu computador

O Codex não tem seu próprio banco de dados, sistema de arquivos ou "workspace". Um projeto do Codex é apenas uma pasta comum no seu computador. Ao iniciar um novo projeto, o Codex pedirá que você selecione uma pasta.

Uma vez selecionada, todos os arquivos dentro dela podem ser livremente operados pelo Codex: lidos, escritos, editados, organizados e movidos.

Este design simples traz uma enorme flexibilidade:

• Projetos são completamente portáteis. A mesma pasta pode ser aberta no Codex CLI, Codex Desktop, plugins IDE do VS Code/Cursor/Windsurf — ou até mesmo com o Claude Code ou Cursor. A ferramenta muda, mas o conteúdo do projeto permanece.
• Controle de versão como código. Git, GitHub, Vercel — essas são ferramentas padrão, sem necessidade de integração especial.
• Backup, compartilhamento e migração são simples, como lidar com uma pasta normal.

O Codex roda em modo agente por padrão — ele pode automaticamente ler, editar e executar comandos dentro do diretório de trabalho. Conteúdo fora da pasta e acesso à rede ainda exigem sua aprovação. A pasta é o limite de confiança.

02. Escreva o arquivo de configuração AGENTS.md: O primeiro documento que o Codex lê ao iniciar

Este é o arquivo mais subestimado no Codex. O AGENTS.md é colocado na raiz do projeto, e o Codex o lê toda vez que você abre uma nova conversa nessa pasta.

Ele informa ao agente de IA: quem você é, qual é o projeto, quais são os objetivos e quais são as restrições.

Dica: Não escreva do zero. Conte ao Codex seus objetivos de projeto em palavras simples e peça para ele rascunhar um AGENTS.md para você. Você receberá um arquivo bem estruturado que poderá modificar conforme necessário. Isso é mais rápido, mais completo e com menos chance de esquecer algo.

1# Projeto: Análise Inteligente de Comentários do YouTube
2
3## Contexto
4Eu administro um canal no YouTube sobre ferramentas de IA. Quero entender
5o que os espectadores estão perguntando, o que querem ver e quais ferramentas estão comparando —
6sem ter que ler cada comentário manualmente.
7
8## Objetivos
9Construir um fluxo de trabalho para extrair comentários recentes, classificá-los,
10descobrir padrões e visualizar os resultados em um dashboard em tempo real.
11
12## Restrições
13- Usar YouTube Data API v3 e chave de API (sem OAuth).
14- Salvar credenciais em .env.local, nunca commitar no repositório.
15- Saída alvo: pasta de trabalho do Excel para análise + Dashboard web.
16- Fazer deploy do dashboard no Vercel.
17- Atualizar dados semanalmente via automação.
18
19## Hábitos de Trabalho
20- Salvar métodos que falharam na memória do projeto para evitar repetir erros.
21- Sempre confirmar o plano antes de escrever código.

Um bom AGENTS.md deve incluir:

• Contexto — um parágrafo. Quem você é e por que está fazendo este projeto. Isso evita ter que reexplicar toda vez.
• Objetivos — um parágrafo. Descreva o estado final, não etapas específicas. Etapas pertencem ao Modo Plano (Etapa 3).
• Restrições — formato de lista. Regras rígidas. Como escolhas de API, linguagens a evitar, limites de segurança, formatos de saída. Quanto mais conciso e específico, melhor.
• Hábitos de Trabalho — formato de lista. Por exemplo, "Salvar lições aprendidas na memória", "Sempre confirmar o plano primeiro", "Nunca executar X". Eles se acumulam em padrões de trabalho confiáveis.

O guia de melhores práticas oficial da OpenAI afirma: "O Codex funciona melhor quando você o trata como um colega de equipe configurável e em melhoria contínua, em vez de um assistente de uso único. Comece com o contexto de tarefa correto, use o AGENTS.md para orientação persistente e configure o Codex para corresponder ao seu fluxo de trabalho."

03. Use o Modo Plano para cada construção

O Modo Plano significa que o Codex não executará imediatamente. Ele fará um brainstorming primeiro, fará perguntas esclarecedoras, mostrará os trade-offs entre diferentes soluções e, em seguida, gerará um plano numerado para sua aprovação antes de escrever código. Pular o Modo Plano é a maior razão pela qual os projetos dão errado.

Uso eficaz:

• Descreva objetivos, não etapas. Por exemplo, "Extrair comentários recentes do meu canal do YouTube e gerar um relatório em Excel" — em vez de "Usar Python para chamar a API do YouTube e depois escrever para xlsx."
• Deixe-o fazer perguntas. O Codex no Modo Plano geralmente retorna de 3 a 5 perguntas esclarecedoras. Responda-as com seriedade. Cada pergunta ajuda você a evitar bugs futuros.
• Aprove o plano antes da execução. Leia as etapas com cuidado. Se encontrar problemas — como falta de tratamento de casos extremos, má escolha de ferramenta ou complexidade desnecessária — levante-os. Modificar na fase de planejamento é muito mais fácil do que alterar o código depois de escrito.

O Modo Plano funciona especialmente bem com o AGENTS.md: as restrições no arquivo de configuração influenciarão as soluções que o Codex propõe. Combinar os dois reduz significativamente a tentativa e erro.

04. Gerencie chaves de API com .env.local

Todas as chaves de API, segredos e credenciais devem ser colocados em um arquivo .env.local na raiz do projeto. O ponto antes do nome do arquivo não é decoração — ele informa ao Codex (e ao git) para excluir este arquivo de commits públicos.

Duas regras de ferro para evitar vazamentos:

• Nunca cole chaves em um secrets.txt com nome aleatório e definitivamente não as cole diretamente em mensagens de chat. Ambas as práticas acabarão no controle de versão. Assim que você enviar o código, as chaves estarão públicas.
• Teste imediatamente após adicionar uma chave. Peça ao Codex para fazer uma chamada de API mínima para confirmar que a chave funciona. Capture erros de autenticação antes que eles afetem toda a construção.

Se uma chave for commitada acidentalmente, gire-a imediatamente no provedor de serviços (Google Cloud, OpenAI, etc.). Não basta deletá-la do arquivo e fazer push da exclusão — a chave ainda está no histórico antigo do commit, e bots escaneiam commits do GitHub em minutos para encontrar segredos vazados. A única maneira segura é girar as credenciais.

Parte II · Conectar e Construir

05. Conecte Servidores e Plugins MCP

O Codex usa o Model Context Protocol (MCP) — um padrão aberto também usado pelo Claude Code. Isso significa que a maioria dos servidores MCP existentes pode ser usada no Codex: GitHub, Slack, Notion, Linear, Drive, Figma e dezenas de servidores desenvolvidos pela comunidade.

O que muda: Em vez de descrever seus dados para o Codex, você permite que ele leia seus dados diretamente. Em vez de descrever o que você quer fazer, você permite que ele execute diretamente. As conversas mudam de _"Aqui está o que está no meu repositório"_ para _"Crie um PR com esta correção e notifique o proprietário."_

Três casos de uso de alto ROI:

• GitHub MCP — Ler repositórios, criar branches, iniciar PRs, comentar em issues. Benefício imediato para qualquer desenvolvedor.
• Vercel MCP — Fazer deploy, verificar status, reverter. Funciona com o GitHub para alcançar um loop completo de "Build → Commit → Deploy".
• Notion ou Drive MCP — Extrair documentos internos como contexto, escrever registros de decisão de volta para uma base de conhecimento central. O Codex deixa de ser uma caixa preta e se torna parte da memória da equipe.

06. Quando não houver plugin, peça ao Codex para ajudar na configuração da API

Nem todo serviço tem um servidor MCP. A YouTube Data API não tem. APIs internas de empresas não têm. Ferramentas SaaS de nicho geralmente não têm.

Nesses casos, você não precisa encontrar uma biblioteca wrapper de terceiros. Pergunte diretamente ao Codex. No Modo Plano, diga a ele seu objetivo de integração — como "Extrair comentários recentes do meu canal do YouTube."

Ele retornará diferentes opções (API Key vs. OAuth), recomendará uma e gerará um plano passo a passo para configurar credenciais, ativar APIs relevantes e testar a conexão.

Práticas eficazes de longo prazo:

• Tente o primeiro método primeiro. O Codex escolherá um plano com base nos trade-offs. Deixe-o tentar.
• Registre lições quando falharem. Por exemplo, "O PowerShell encontrou um erro TLS, o Python funciona. Salve isso na memória do projeto para não tentarmos o caminho errado novamente." Conversas futuras herdarão esse conhecimento.
• Consolide soluções funcionais. Quando uma integração estiver estável, converta-a em uma Skill (Etapa 9). Você não precisará configurá-la novamente.

Este é o hábito mais importante no trabalho assistido por IA. Tente, falhe, registre a falha e não repita o mesmo erro. O agente de IA do Codex tem apenas memória de curto prazo por padrão — ele esquecerá o que aprendeu hoje amanhã, a menos que você escreva.

Sempre que encontrar uma lição que vale a pena registrar, diga ao Codex para atualizar o AGENTS.md ou a memória do projeto. O sistema fica mais inteligente quanto mais você o usa.

07. Construa entregáveis reais com prompts específicos

O valor de qualquer ferramenta está em seus entregáveis. Para a maioria dos usuários, o primeiro entregável é algo concreto — um relatório em Excel, um script de automação, um dashboard ou documentação gerada. Algo que prove o valor da ferramenta.

O principal fator que determina a qualidade da primeira construção: Especificidade do prompt. "Analisar meus comentários do YouTube" gerará uma planilha do Excel com apenas as categorias "Positivo", "Negativo" e "Neutro", o que não é muito útil. "Analisar meus comentários do YouTube e classificá-los por: Comparações de Ferramentas, Sugestões de Conteúdo, Problemas Técnicos, Feedback Geral — depois ordená-los por prioridade de resposta para mim como criador" gerará uma pasta de trabalho que você realmente usará.

Duas dicas para melhorar rapidamente a qualidade da saída:

• Declare o propósito da saída — "Para mim como criador", "Para um relatório do conselho", "Para minha equipe de engenharia." O público determina a estrutura.
• Liste as categorias ou dimensões que lhe interessam. Não deixe a classificação depender do julgamento padrão. Diga ao Codex sua taxonomia.

Se a primeira versão estiver ok, mas não ótima, não comece do zero. <u>Adicione mais detalhes e execute novamente.</u> Iterar três vezes com prompts mais claros é melhor do que começar do zero cinco vezes.

08. Use gpt-image-2 para gerar conceitos antes de construir a UI

O Codex tem geração de imagens integrada usando gpt-image-2 — o modelo de imagem da OpenAI. Chame-o explicitamente com $imagegen no seu prompt, ou apenas descreva o que precisa, e o Codex o reconhecerá automaticamente.

As imagens geradas se tornam ativos do projeto que as construções subsequentes podem referenciar.

Como desbloquear isso: Gere arte conceitual antes de escrever código de UI. Peça ao Codex para simular a aparência do dashboard com uma ou duas imagens primeiro. Salve-as no projeto.

Depois, peça a ele para construir o dashboard e referenciar essas imagens conceituais. O resultado visual final será muito melhor do que deixar o modelo projetar apenas a partir de descrições de texto.

09. Converta fluxos de trabalho em Skills

Uma Skill é uma receita reutilizável que o Codex carrega sob demanda. Depois de construir um fluxo de trabalho funcional — como extrair comentários, gerar relatórios e fazer deploy de um dashboard — você pode convertê-lo em uma Skill e executá-lo com um único comando na próxima vez.

As Skills no Codex são arquivos markdown em uma pasta. Há um arquivo SKILL.md no diretório contendo metadados (nome + descrição) e o corpo da instrução. Opcionalmente, você pode colocar scripts e arquivos de referência junto com ele.

1---
2name: youtube-comment-insights
3description: Extrai comentários recentes do YouTube via Data API,
4  classifica-os por categoria de conteúdo e menções a ferramentas,
5  ordena por prioridade de resposta e gera uma pasta de trabalho do Excel com
6  abas de resumo e gráficos. Acionada sempre que eu peço
7  "insights de comentários" ou "relatório semanal do youtube".
8---
9
10# YouTube Comment Insights
11
12## Configuração
13- Ler YOUTUBE_API_KEY de .env.local.
14- Buscar ~200 comentários mais recentes dos 10 vídeos mais recentes.
15
16## Classificação
17- Categorias: Comparações de Ferramentas, Sugestões de Conteúdo, Problemas Técnicos,
18  Feedback Geral, Irrelevante.
19- Rastreamento de Menções a Ferramentas: Codex, Claude Code, Cursor, API, GPT, etc.
20- Sinais de Prioridade: Perguntas > Comentários de alto engajamento > Outros.
21
22## Saída
23- Abas da pasta de trabalho: Resumo, Classificação, Menções a Ferramentas,
24  Respostas Prioritárias, Ideias de Conteúdo, Dados Brutos.
25- Gráficos na aba Resumo: Distribuição de categorias, Rankings de ferramentas.

Dois níveis de armazenamento que vale a pena conhecer:

• Skills Globais — Armazenadas em ~/.agents/skills/. Disponíveis em todo projeto do Codex no seu computador.
• Skills de Nível de Projeto — Armazenadas dentro da pasta do projeto. Disponíveis apenas naquele projeto. Bom para receitas específicas de cliente ou projeto.

Três fatores que determinam se uma Skill é acionada automaticamente quando necessário:

• A descrição é tudo. O Codex corresponde sua tarefa com base apenas no texto da descrição para chamadas implícitas. Coloque os principais casos de uso e palavras-gatilho no início; descrições vagas nunca serão acionadas.
• Duas formas de chamar. Explicitamente (via /skills no CLI/IDE, ou mencionando $skillname), ou implicitamente (quando seu prompt corresponde à descrição e o Codex seleciona automaticamente a skill).
• Padrão Aberto. As Skills foram lançadas para o Codex em dezembro de 2025 e agora fazem parte do padrão Agent Skills multiplataforma — o mesmo formato funciona no Codex, Claude Code, Gemini CLI e Cursor. Escreva uma vez, execute em qualquer lugar.

10. Faça deploy de serviços locais online <u>GitHub → Vercel → Produção</u>

Planilhas do Excel são backends. Dashboards são frontends. Localhost é um endereço de desenvolvimento. Nenhum deles pode ser entregue diretamente.

Para ir do local ao online, você precisa conectar dois serviços: GitHub para o repositório e Vercel para hospedagem. O Codex coordena todo o processo.

1> Conecte este projeto ao GitHub. Crie um repositório privado chamado
2  "yt-comments-dashboard" e faça push do código.
3▲ Codex  Autenticando com gh CLI…
4  - Criado github.com/voce/yt-comments-dashboard (privado)
5  - Commit inicial enviado
6✓ Repositório pronto
7
8> Conecte o Vercel à mesma conta do GitHub.
9  Importe este repositório. Faça deploy.
10▲ Codex  Conectando Vercel…
11  - Projeto Vercel criado
12  - Build bem-sucedido em 38s
13✓ Live em: https://yt-comments-dashboard.vercel.app

Detalhe importante: GitHub e Vercel se comunicam continuamente após a conexão inicial. Todo push para o branch principal aciona um deploy automático do Vercel. Você não precisa fazer login no Vercel novamente. Você trabalha no Codex, o Codex faz push para o GitHub, e o Vercel faz deploy automaticamente. Três ferramentas, um fluxo de trabalho.

11. Configure tarefas de automação — e especifique o modelo claramente

O aplicativo Codex tem uma aba de automação. Você pode executar tarefas agendadas via expressões cron. Combinadas com Skills, é assim que você faz um dashboard "se atualizar automaticamente enquanto você dorme."

Uma automação real de domingo à noite: Extrair novos comentários, executar a Skill de Insights, atualizar o arquivo Excel, fazer push de novos dados e deixar o Vercel fazer auto-deploy. Atualização de ponta a ponta sem intervenção humana. Na manhã de segunda-feira, o dashboard está atualizado.

O seletor de modelo no painel de automação não herda as configurações da sua conversa ativa. Novas tarefas de automação usam os valores padrão do painel, que podem ser mais lentos ou mais baratos do que o modelo que você realmente deseja para execuções de produção.

Defina explicitamente o modelo para cada tarefa de automação, caso contrário, você se perguntará por que uma tarefa que normalmente leva 7 minutos de repente leva 40. O mesmo problema ocorre se você tiver um arquivo aberto localmente que o Codex precisa sobrescrever — feche-o primeiro.

12. Escolha o modo de thread correto — Local, Worktree ou Nuvem

Cada thread de conversa no aplicativo Codex roda em um de três modos:

• Local — Funciona diretamente no diretório do seu projeto atual. Mais rápido e simples, mas toda alteração afeta seus arquivos de trabalho reais. Bom para edições pequenas e controladas quando você confia no agente de IA.
• Worktree — Isola as alterações em um worktree do Git (um diretório de trabalho separado vinculado ao mesmo repositório). O agente de IA trabalha em um branch separado sem afetar seu branch principal. Esta é a escolha padrão para qualquer construção significativa. Se algo der errado, basta deletar o worktree. Risco zero.
• Nuvem — Executa remotamente em um ambiente de nuvem configurado. Seu laptop pode ser desligado. Combine isso com tarefas de automação (Etapa 11) para fluxos de trabalho verdadeiramente assíncronos que não dependem da sua máquina estar online.

Regra prática: Worktree para trabalho importante, Local para pequenos ajustes, Nuvem para automações de longa duração. Três níveis de confiança, escolhidos por tarefa.

13. Use o navegador integrado para testes de QA

Depois de construir um dashboard, peça ao Codex para abri-lo no navegador integrado, clicar, tentar encontrar problemas e relatar. Ele o fará.

Ele encontrará problemas que você não consegue ver olhando para o código — links externos quebrados, estados vazios que parecem muito simples, comportamento de pesquisa rígido, falhas de acessibilidade e pequenas inconsistências de UI.

Como transformar isso de algo pontual em um hábito: Escreva testes de QA na memória do seu projeto ou nas Skills.

Toda vez que você lançar um novo recurso, o agente de IA executará testes no navegador antes de retornar para você. Você não é mais o testador de QA. O agente de IA faz os testes; você revisa o relatório.

No entanto, o navegador não é apenas para QA. É uma ferramenta universal quando APIs não existem:

• Faça login em ferramentas sem APIs — Painéis administrativos tradicionais, portais de fornecedores, dashboards internos.
• Extraia relatórios de dashboards que não fornecem interfaces programáticas — Visualizações de análise, ferramentas de faturamento, páginas de status.
• Automatize fluxos de UI de várias etapas que você normalmente teria que clicar manualmente. Descreva as etapas em linguagem natural; o Codex as executa.

14. Use os recursos de UX que a maioria das pessoas ignora

O aplicativo Codex tem recursos de UI que o transformam de uma "ferramenta que eu uso" em um "ambiente onde eu trabalho." Eles parecem pequenos individualmente, mas são poderosos juntos.

• Conversas Laterais. Abra um thread lateral a partir da conversa principal. Mesmo contexto de projeto, diálogo diferente. Faça perguntas rápidas sem poluir o thread principal. Feche quando terminar.
• Comandos de Barra. Digite / para navegar: /skills para chamar uma Skill explicitamente, /clear, /help, etc. O menu de barra mostra todos os recursos do Codex.
• Menções @. Marque arquivos específicos nos prompts: "Adicionar uma nova página referenciando @exemplo.tsx, listando itens de @recursos.ts." Muito mais limpo do que colar caminhos.
• Alternador de Modelo + Intensidade de Raciocínio. O alternador abaixo do campo de chat permite trocar de modelo por conversa. A intensidade de raciocínio controla quanto tempo o Codex pensa antes de responder. Intensidade mais alta = melhor desempenho em tarefas complexas, mais tokens consumidos, limites de taxa atingidos mais rápido. Combine a intensidade com a tarefa.
• $imagegen + Menções de Skill. Digite $ para mencionar skills inline. Mesma sintaxe de @ para arquivos. Permite combinar várias skills em um prompt.
• Sincronização Automática de Contexto com Extensões IDE. Se a extensão IDE do Codex estiver instalada, o aplicativo e o editor sincronizam automaticamente quando ambos estão no mesmo projeto. Você pode ver threads rodando no aplicativo dentro do editor e vice-versa. Alterne "Auto-context" para deixar o Codex rastrear o arquivo que você está visualizando no momento.
• Modo de Acesso Total. Configurações → Alterne para pular os prompts de aprovação. Mais rápido, mais perigoso. Comece com o padrão. Só mude para Acesso Total quando confiar nos limites do projeto.

Hábitos que mantêm o Codex em apenas 3% do potencial

• Sem AGENTS.md. Reexplicando o projeto a cada conversa, obtendo respostas diferentes toda vez.
• Pular o Modo Plano. Alterar quarenta arquivos para corrigir um mal-entendido de uma frase.
• Colocar chaves no chat ou em secrets.txt. Expostas publicamente assim que você faz push.
• Nunca registrar lições. Cometer os mesmos erros repetidamente porque nada foi escrito.
• Prompts vagos. Obtendo entregáveis genéricos e depois se surpreendendo com o quão genérica é a saída.
• Construções únicas. Reconstruindo o mesmo fluxo de trabalho do zero toda semana em vez de convertê-lo em uma Skill.
• Usar o modo Local para tudo. Uma execução ruim de IA destrói seus arquivos de trabalho porque você não usou um worktree.
• Deixar automações usarem modelos padrão. Uma tarefa de 7 minutos leva 40 minutos.
• Sem testes de QA. Lançando dashboards com links quebrados e estados vazios simples demais.
• Tribalismo de ferramentas. Escolher Codex vs. Claude Code com base em identidade em vez da tarefa em mãos. Ambos têm pontos fortes dependendo da situação.

Resumo

O Codex parece uma janela de chat. Mas não é uma janela de chat. É uma pasta com um agente de IA que conhece o conteúdo — além de Skills, MCP, tarefas de automação e uma camada de navegador, tudo configurado via arquivos markdown dentro da pasta.

Esta pasta é portátil. Abra-a no Codex, Claude Code, Cursor ou qualquer ferramenta que suporte o padrão Agent Skills. O shell da ferramenta muda, mas o trabalho permanece.

A maioria dos usuários continuará digitando perguntas na caixa de chat e parando por aí. Eles obterão respostas, copiarão código e seguirão em frente. Os 4 milhões de usuários ativos semanais que realmente estão causando impacto com o Codex são aqueles que configuram suas pastas.

Escolha uma etapa que você ainda não fez — talvez o AGENTS.md ou sua primeira Skill real — e adicione-a amanhã.

A saída do Codex depende da configuração do Codex.

Artigo de referência de: https://substack.com/@0xmovez