Configurar o seu ambiente e o ficheiro AGENTS.md
Nesta página
Atualizado a 3 de novembro de 2026 com base na documentação do Codex (Codex CLI, Autenticação, Extensão IDE do Codex, Instruções personalizadas com AGENTS.md): o pacote
@openai/codex-clie o comandocodex auth loginnão existem (utilizenpm install -g @openai/codexecodex login); o identificador da extensão éopenai.chatgpt; o endereço codex.openai.com e os planos “Team, Enterprise, or API” foram substituídos pelos métodos de acesso atuais; e a ordem de leitura do AGENTS.md foi clarificada (raiz do projeto → diretório atual). Fontes: Codex CLI · Authentication · AGENTS.md · Pricing.
Prepare o seu projeto para o Codex
Antes da sua primeira tarefa, duas coisas devem estar prontas: o seu acesso ao Codex — a sua conta e a ligação ao GitHub — e o próprio projeto, definido através do ficheiro AGENTS.md que irá guiar o agente. A primeira parte demora cerca de 15 minutos e é uma configuração única. A segunda determina a qualidade de tudo o que obtém do Codex, separando as equipas satisfeitas daquelas que ficam desapontadas.
Passo 1: O seu acesso ao Codex
Pode utilizar o Codex com uma conta ChatGPT ou uma chave de API. Os planos Free e Go fornecem acesso, dependendo da implementação atual, ao GPT-6 Luna na aplicação de desktop. A partir do plano Plus, o Codex está disponível na web, na CLI, na extensão do editor e no iOS, com integrações na nuvem como a revisão automática de código. Uma chave de API funciona para automação em ambientes partilhados como CI, utilizando a CLI, o SDK ou a extensão — embora algumas funcionalidades possam não estar disponíveis. Os detalhes e limites de uso encontram-se na página de preços do Codex.
Para trabalhar na nuvem nos seus repositórios, ligue o GitHub quando criar o seu primeiro ambiente Codex Cloud (Lição 2). Ao conceder permissões, mantenha-as mínimas: limite o acesso apenas aos repositórios de que realmente necessita.
Passo 2: Instalar a extensão do editor
No VS Code e nos seus derivados (Cursor, Windsurf), instale a extensão Codex a partir do marketplace — o seu identificador é openai.chatgpt:
code --install-extension openai.chatgpt
Em seguida, abra o Codex através do seu ícone ou através da paleta de comandos com Codex: Open Codex Sidebar, e inicie sessão. O Xcode e as IDEs JetBrains têm as suas próprias integrações: no JetBrains, abra AI Chat e selecione Codex.
Passo 3: Instalar a CLI
# Instalação (macOS e Linux), ou npm install -g @openai/codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# Verificar instalação
codex --version
# Iniciar sessão (navegador) ou verificar estado da ligação
codex login
codex login status
O comando codex login abre o fluxo de autenticação no seu navegador. Para uma chave de API, passe-a via entrada padrão (printenv OPENAI_API_KEY | codex login --with-api-key). O Codex guarda as credenciais em cache num ficheiro de texto simples, ~/.codex/auth.json, ou no chaveiro do sistema, dependendo da definição cli_auth_credentials_store (file, keyring, auto ou ephemeral). Se for utilizado o ficheiro, trate-o como uma palavra-passe: contém tokens de acesso, por isso nunca o coloque no repositório. A CLI e a extensão partilham este cache.
O ficheiro AGENTS.md — o guia do seu projeto
O AGENTS.md é central para utilizar o Codex de forma eficaz. É um simples ficheiro Markdown colocado na raiz do seu repositório que reúne instruções, convenções e comandos específicos do seu projeto. Quando o Codex clona o repositório, lê este ficheiro em primeiro lugar: pense nisso como uma integração automática para o agente, exatamente aquilo que explicaria oralmente a um novo membro da equipa.
O impacto é imediato. Sem o AGENTS.md, se pedir um teste unitário num projeto que utiliza Vitest, há uma grande probabilidade de o Codex lhe fornecer Jest, porque essa é a escolha mais comum no ecossistema. Uma única linha de convenção é suficiente para acertar no Vitest à primeira, poupando-lhe a correção repetida centenas de vezes. Eis a estrutura de um ficheiro básico para um projeto SaaS de gestão de faturas.
# AGENTS.md
## Project context
SaaS invoice management application.
Stack: Next.js 15, TypeScript, Prisma, PostgreSQL.
## Code conventions
- Use React functional components (no classes)
- Name files in kebab-case
- TypeScript types in separate .types.ts files
- Tests with Vitest, .test.ts files next to code
## Useful commands
- `npm run dev` — development server
- `npm run test` — run tests
- `npm run lint` — check linting
- `npm run build` — production build
## Project structure
src/
app/ → Next.js pages (App Router)
components/ → Reusable React components
lib/ → Business logic and utilities
prisma/ → DB schema and migrations
## Strict rules
- NEVER modify Prisma schema without a migration
- NEVER commit .env files
- Always use Server Actions for mutations
Como o Codex encontra os ficheiros AGENTS.md
Um único ficheiro na raiz torna-se rapidamente demasiado genérico. O Codex permite empilhar instruções numa ordem precisa que deve conhecer:
- Nível global: Na sua pasta Codex (
~/.codex, a menos queCODEX_HOMEsubstitua), o Codex lêAGENTS.override.mdse existir, caso contrário lêAGENTS.md. - Nível do projeto: A partir da raiz do projeto (geralmente a raiz Git), o Codex desce até ao diretório atual e lê, em cada pasta percorrida,
AGENTS.override.mdou, na falta deste,AGENTS.md. - Fusão: Os ficheiros são concatenados da raiz até ao diretório atual; os mais próximos do diretório atual vêm por último e, portanto, substituem instruções mais gerais.
my-project/
AGENTS.md → Project instructions
src/
api/
AGENTS.md → "API routes use Zod for validation"
Consequência prática: o src/api/AGENTS.md só é lido se o Codex estiver a trabalhar a partir de src/api ou de um dos seus subdiretórios, não quando lançado a partir da raiz. Ficheiros vazios são ignorados e a concatenação para nos 32 KiB por padrão (project_doc_max_bytes). Se o seu repositório já utilizar outro nome, como TEAM_GUIDE.md, adicione-o a project_doc_fallback_filenames em ~/.codex/config.toml.
Para verificar o que o Codex carregou efetivamente, basta perguntar: codex --ask-for-approval never "Summarize the current instructions.". O Codex reconstrói a cadeia de instruções em cada arranque: se tiver dúvidas, reinicie-o no diretório correto.
Melhores práticas para o AGENTS.md
O princípio orientador é a explicitação. “Utilize Vitest, não Jest” é melhor do que “Utilize o nosso framework de testes”, o que pressupõe um conhecimento que o agente não tem. Inclua sempre comandos: sem eles, o Codex não saberá como executar os seus testes, o linter ou a compilação, e entregará código que não pôde verificar. Documente a estrutura como uma árvore de diretórios, o que impede que explore às cegas e crie ficheiros no local errado.
Por fim, liste as proibições. As regras escritas como “NUNCA” são as mais rentáveis no ficheiro, porque bloqueiam erros dispendiosos e difíceis de corrigir: colocar um ficheiro .env no repositório, modificar um esquema sem uma migração. A disciplina mais difícil é manter o ficheiro atualizado. Um AGENTS.md que descreve o projeto do ano passado orienta ativamente o Codex para convenções abandonadas — muito pior do que não ter ficheiro nenhum, já que o erro se torna então sistemático.
Pontos-chave
- A configuração inicial requer uma conta OpenAI e uma ligação ao GitHub
- A extensão da IDE e a CLI instalam-se em minutos
- O AGENTS.md é o ficheiro mais importante para um uso eficaz do Codex
- Contém convenções, comandos e regras específicas do seu projeto
- Os ficheiros AGENTS.md em subdiretórios permitem instruções contextuais