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 como criar Skills, não sabem como fazer deploy online e não sabem como deixar tarefas de automação rodando em segundo plano. Este artigo vai usar 14 passos para te levar 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 descontinuada 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, se desenvolveu em aplicativos para desktop, plugins de 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 é agora 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 passos. 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 "espaço de trabalho". Um projeto do Codex é apenas uma pasta normal no seu computador. Quando você inicia um novo projeto, o Codex vai pedir para você selecionar uma pasta.

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

Esse design simples traz uma enorme flexibilidade:

• Os projetos são completamente portáteis. A mesma pasta pode ser aberta no Codex CLI, Codex Desktop, plugins de IDE para 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—são todas 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 precisam da 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ê na inicialização

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 naquela pasta.

Ele diz ao agente de IA: quem você é, o que é 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 do projeto em palavras simples e deixe ele rascunhar um AGENTS.md para você. Você vai receber um arquivo bem estruturado que pode então modificar conforme necessário. Isso é mais rápido, mais completo e tem menos chance de perder 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 eles querem ver e quais ferramentas estão comparando—
6sem ter que ler manualmente cada comentário.
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 a YouTube Data API v3 e chave de API (sem OAuth).
14- Salvar credenciais em .env.local, nunca commitar para o repositório.
15- Formato de saída: 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 passos específicos. Passos pertencem ao Modo Plano (Passo 3).
• Restrições—formato de lista. Regras rígidas. Como escolhas de API, idiomas 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 constante melhoria, em vez de um assistente descartável. Comece com o contexto de tarefa certo, 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

Modo Plano significa que o Codex não vai executar imediatamente. Ele vai debater primeiro, fazer perguntas esclarecedoras, mostrar os prós e contras 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 passos. 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 em xlsx."
• Deixe-o fazer perguntas. O Codex no Modo Plano geralmente retorna de 3 a 5 perguntas esclarecedoras. Responda a elas com seriedade. Cada pergunta ajuda a evitar bugs futuros.
• Aprove o plano antes da execução. Leia os passos com atenção. 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 mudar 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 diz 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 mais cedo ou mais tarde. Assim que você enviar o código, as chaves se tornam 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. Pegue erros de autenticação antes que eles afetem toda a construção.

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

Parte II · Conectar e Construir

05. Conecte Servidores MCP e Plugins

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ê deixa ele ler seus dados diretamente. Em vez de descrever o que você quer fazer, você deixa ele executar 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, deixe o Codex te ajudar a configurar a 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.

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

Ele vai retornar diferentes opções (API Key vs. OAuth), recomendar uma e gerar um plano passo a passo para configurar credenciais, habilitar 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 prós e contras. Deixe-o tentar.
• Registre lições quando falharem. Por exemplo, "PowerShell encontrou um erro de TLS, Python funciona. Salve isso na memória do projeto para não tentarmos o caminho errado novamente." Conversas futuras herdarão esse conhecimento.
• Trave soluções funcionais. Uma vez que uma integração esteja estável, converta-a em uma Skill (Passo 9). Você não terá que 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 vai esquecer o que aprendeu hoje amanhã, a menos que você escreva.

Sempre que você encontrar uma lição que vale a pena registrar, peça 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 entregas reais com prompts específicos

O valor de qualquer ferramenta está em suas entregas. Para a maioria dos usuários, a primeira entrega é 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 fator chave que determina a qualidade da primeira construção: Especificidade do prompt. "Analisar meus comentários do YouTube" vai 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" vai 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 você se importa. Não deixe a classificação depender do julgamento padrão. Conte 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 imagem integrada usando gpt-image-2—o modelo de imagem da OpenAI. Chame-o explicitamente com $imagegen no seu prompt, ou apenas descreva o que você precisa, e o Codex vai reconhecer automaticamente.

Imagens geradas se tornam ativos do projeto que 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 para ele construir o dashboard e referenciar essas imagens conceituais. O resultado visual final será muito melhor do que deixar o modelo desenhar 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.

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. Você pode opcionalmente 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. Acionado sempre que eu peço
7  "insights de comentários" ou "relatório semanal do youtube".
8---
9
10# Insights de Comentários do YouTube
11
12## Configuração
13- Ler YOUTUBE_API_KEY do .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ível em todo projeto do Codex no seu computador.
• Skills de Nível de Projeto — Armazenadas dentro da pasta do projeto. Disponível 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:

• Descrição é tudo. O Codex corresponde sua tarefa baseado apenas no texto da descrição para chamadas implícitas. Coloque casos de uso e palavras-chave no início; descrições vagas nunca serão acionadas.
• Duas maneiras 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. Nada disso 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 envie o 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 o deploy.
10▲ Codex  Conectando Vercel…
11  - Projeto Vercel criado
12  - Build bem-sucedida em 38s
13✓ Live em: https://yt-comments-dashboard.vercel.app

Detalhe chave: GitHub e Vercel se comunicam continuamente após a conexão inicial. Cada 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. Combinado com Skills, é assim que você faz um dashboard "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, enviar novos dados e deixar o Vercel fazer deploy automaticamente. Atualização de ponta a ponta sem intervenção humana. Na segunda-feira de manhã, 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 em produção.

Defina explicitamente o modelo para cada tarefa de automação, caso contrário você vai 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 Cloud

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 cada alteração afeta seus arquivos de trabalho reais. Bom para pequenas edições controladas quando você confia no agente de IA.
• Worktree — Isola 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 excluir o worktree. Risco zero.
• Cloud — Roda remotamente em um ambiente de nuvem configurado. Seu laptop pode estar desligado. Combine isso com tarefas de automação (Passo 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, Cloud 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, navegar, tentar encontrar problemas e relatar de volta. Ele fará isso.

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 em sua memória de projeto ou Skills.

Toda vez que você lançar um novo recurso, o agente de IA executa testes no navegador antes de retornar para você. Você não é mais o testador de QA. O agente de IA faz o teste; 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 de administração 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: "Adicione 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 rapidamente. Combine a intensidade com a tarefa.
• $imagegen + Menções de Skill. Digite $ para mencionar skills inline. Mesma sintaxe de @ para arquivos. Permite combinar múltiplas skills em um único prompt.
• Sincronização Automática de Contexto com Extensões de IDE. Se a extensão de 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 prompts de aprovação. Mais rápido, mais perigoso. Comece com o padrão. Mude para Acesso Total apenas 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. Exposto publicamente assim que você fizer push.
• Nunca registrar lições. Cometer os mesmos erros repetidamente porque nada foi escrito.
• Prompts vagos. Receber entregas genéricas e depois se surpreender por que a saída é tão genérica.
• Construções únicas. Reconstruir 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 limpa 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çar dashboards com links quebrados e estados vazios simples.
• Tribalismo de ferramentas. Escolher Codex vs. Claude Code com base na 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—mais 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 fazendo a diferença com o Codex são aqueles que configuram suas pastas.

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

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

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