OpenAI Codex CLI: Comandos e configuração — Folha de dicas

OpenAI Codex CLI é o agente de programação nativo para terminal da OpenAI que inspeciona bases de código, edita arquivos, executa testes, integra-se com tarefas remotas do Codex Cloud e conecta-se a ferramentas externas via MCP diretamente pela linha de comando.

Esta folha de dicas cobre subcomandos e flags do Codex CLI, políticas de sandbox e aprovação, comandos slash interativos da TUI, atalhos de teclado e configuração de config.toml / AGENTS.md.

🔗 Folhas de dicas relacionadas: Comparativo de CLIs de agentes de IA no terminal · Folha de dicas do Claude Code CLI · Folha de dicas do Antigravity CLI (agy) · Arquitetura e runtime de AI Agent Harness

1. Instalação, autenticação e comandos CLI principais

1.1 Instalação e autenticação

Ação	Comando	Observações
Instalação global via npm	`npm install -g @openai/codex`	Instalação multiplataforma padrão
Script oficial de instalação	`curl -fsSL https://chatgpt.com/codex/install.sh \| sh`	Instalador em uma linha para macOS / Linux
Login pelo navegador	`codex login`	Autentica com conta ChatGPT Plus / Pro / Team
Autenticação por chave de API	`export OPENAI_API_KEY="sk-..."`	Ideal para ambientes CI headless ou contêineres

1.2 Subcomandos CLI e flags globais

Comando / Flag	Descrição	Exemplo de uso
`codex`	Inicia a TUI interativa no diretório atual	`codex`
`codex "prompt"`	Inicia uma sessão interativa com um prompt inicial	`codex "Debug 500 timeout errors on login"`
`codex exec` / `codex e`	Execução não interativa (headless) para scripts e CI	`codex exec "Run all unit tests and fix failures"`
`codex exec --json`	Transmite logs JSON estruturados de raciocínio e edições de arquivos	`codex exec --json "Refactor utils" > run.jsonl`
`codex review`	Revisão de código não interativa sobre o diff Git atual	`codex review`
`codex resume`	Abre seletor de sessões (armazenadas em `~/.codex/sessions/`)	`codex resume` / `codex resume --last` / `codex resume <id>`
`codex apply` / `codex a`	Aplica no workspace local diffs gerados por tarefas do Codex Cloud	`codex apply <task_id>`
`codex cloud`	Inspeciona ou gerencia tarefas remotas do Codex Cloud	`codex cloud`
`codex mcp`	Gerencia integrações com servidores Model Context Protocol (MCP)	`codex mcp list` / `codex mcp add <name> ...`
`-m, --model <name>`	Especifica o modelo subjacente para a sessão ou execução	`codex -m gpt-6.1-sol`
`--strict-config`	Valida rigorosamente a sintaxe e chaves do `config.toml`	`codex --strict-config`

2. Matriz de políticas de Sandbox e aprovação

O Codex CLI separa permissões em duas camadas ortogonais: o que o ambiente pode tocar (--sandbox) e quando perguntar ao usuário (--ask-for-approval).

Flag	Valores válidos	Comportamento e uso recomendado
`--sandbox <mode>` (atalho `-s`)	`read-only`	Somente leitura: inspeciona e pesquisa código sem modificar arquivos
	`workspace-write`	Escrita no workspace (padrão recomendado): permite edições apenas dentro da árvore de trabalho
	`danger-full-access`	Acesso irrestrito: acesso completo ao sistema de arquivos/sistema (apenas em contêineres isolados)
`--ask-for-approval <policy>`	`on-request`	Padrão recomendado: o modelo solicita confirmação quando ações arriscadas exigem
	`on-failure`	Escala apenas em caso de falha (use `on-request` se avisos de elevação de sandbox importarem)
	`never`	Totalmente silencioso: nunca solicita confirmação interativa (para CI / pipelines automatizados)

⚠️ Aviso sobre flags obsoletas e removidas:

--full-auto está obsoleta (deprecated) desde a v0.128.0. Especifique as políticas de sandbox e aprovação explicitamente: codex --sandbox workspace-write --ask-for-approval on-request "Fix failing tests"

A política de aprovação untrusted foi descontinuada na v0.149.0; migre as configurações para on-request.

3. Comandos slash interativos da TUI

Digite / no prompt interativo da TUI do codex para controlar contexto, permissões e fluxos de trabalho:

3.1 Contexto, modelos e permissões

Comando	Função	Observações e uso
`/init`	Gera um `AGENTS.md` inicial adaptado ao repositório	Primeiro passo recomendado em um novo projeto
`/status`	Inspeciona o modelo ativo, permissões e uso de tokens	Monitore a capacidade restante de contexto
`/model`	Alterna interativamente de modelo e nível de Reasoning Effort	Ajuste a profundidade de raciocínio sem reiniciar
`/permissions`	Ajusta o modo de sandbox e a política de aprovação durante a sessão	Restrinja ou flexibilize permissões sob demanda
`/mcp`	Inspeciona e gerencia servidores MCP conectados	Verifique conectividade com ferramentas externas e BDs

3.2 Fluxos de engenharia e controle de sessão

Comando	Função	Observações e uso
`/plan`	Elabora e revisa um plano de implementação antes de editar arquivos	Alinhe a arquitetura antes de grandes refatorações
`/review`	Executa revisão de código sob múltiplas perspectivas nas alterações não commitadas	Detecte bugs, casos de borda e riscos de segurança
`/diff`	Inspeciona modificações de arquivos ainda não commitadas	Revise diffs linha a linha antes de aceitar
`/fork`	Ramifica o histórico da conversa para um checkpoint separado	Explore uma abordagem alternativa sem poluir o contexto principal
`/compact`	Resume o histórico da conversa para recuperar espaço de contexto	Evite perda de coerência em sessões longas de múltiplos turnos
`/copy`	Copia a última resposta concluída para a área de transferência	Extraia patches ou resumos rapidamente
`/title`	Renomeia a thread da conversa atual	Facilita localizar sessões em `codex resume`
`/statusline` / `/theme`	Personaliza os itens da barra de status no rodapé ou o tema de cores da TUI	Adapte a apresentação visual do terminal
`/prompts:<name>`	Invoca um template personalizado de prompt em Markdown	Executa `~/.codex/prompts/<name>.md`

4. Atalhos de teclado no terminal e sintaxe de entrada

Atalho / Sintaxe	Ação	Efeito e cenário
`@<path>`	Referência difusa de arquivo	Injeta conteúdo de arquivos inline (ex.: `@src/auth.ts`)
`!<command>`	Comando shell local inline	Executa comandos shell dentro das regras ativas do sandbox (ex.: `!npm test`)
`Tab`	Enfileirar próximo prompt	Coloca na fila um próximo prompt, comando slash ou comando `!` enquanto o Codex trabalha
`Enter`	Interromper / direcionar em execução	Injeta orientações adicionais enquanto o agente está respondendo ativamente
`Ctrl + G`	Abrir editor externo	Redige prompts multilinha em `$VISUAL` / `$EDITOR` (Vim, VS Code, etc.)
`Ctrl + R`	Pesquisar histórico de prompts	Busca reversa em prompts enviados anteriormente
`Ctrl + L`	Limpar e redesenhar a tela	Limpa a poluição visual do terminal mantendo o estado da conversa
`Ctrl + O`	Copiar última saída	Equivalente ao comando `/copy`
`Ctrl + X`	Abrir menu de teclado	Acessa predefinições de atalhos e extensões
`Ctrl + C`	Cancelar / Sair	Aborta a tarefa ativa ou encerra a sessão do Codex

5. Arquivos de configuração e hierarquia de memória (`config.toml` e `AGENTS.md`)

As configurações no nível do projeto sobrescrevem os padrões globais do usuário:

Camada	Escopo global (todos os repos)	Escopo do projeto (repo atual)	Finalidade
Configuração principal	`~/.codex/config.toml`	`.codex/config.toml`	Modelo padrão, sandbox, política de aprovação, rede, MCP
Instruções do agente	`~/.codex/AGENTS.md`	`./AGENTS.md` (raiz do repo)	Comandos de build/teste, padrões de código, regras de arquitetura
Prompts personalizados	`~/.codex/prompts/*.md`	—	Templates reutilizáveis para comandos slash `/prompts:<name>`
Logs de sessão	`~/.codex/sessions/`	—	Registros persistentes restaurados pelo `codex resume`

`~/.codex/config.toml` mínimo recomendado

# Modelo padrão
model = "gpt-6.1-sol"

# Modo de sandbox e política de aprovação padrão
sandbox_mode = "workspace-write"
approval_policy = "on-request"

# Restringir acesso de rede de saída dentro do sandbox por padrão
network_access = false