Codex CLI (Gerenciamento de Sessões e Execução)

Guia da Skill Codex

Executando uma Tarefa

1. Para uma nova sessão (retomadas herdam o modelo/esforço da sessão anterior — veja passo 5), pergunte ao usuário (via AskUserQuestion) qual modelo E qual esforço de raciocínio usar, em um único prompt com duas perguntas. Quando o usuário não expressar preferência, use como padrão gpt-6-astra com high.
   • Modelo — padrão gpt-6-astra:
     • GPT-6: gpt-6-astra (fronteira / mais capaz — padrão)
     • GPT-5.6: gpt-5.6-sol (cavalo de batalha confiável), gpt-5.6-terra (equilibrado, uso diário), gpt-5.6-luna (rápido e acessível)
     • Legado (mantido por compatibilidade): gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark, gpt-5.3-codex
   • Esforço de raciocínio — padrão high: low, medium, high, xhigh, max, ultra.
     • max/ultra exigem um modelo GPT-6 ou GPT-5.6; ultra está disponível apenas em astra/sol/terra (luna limita em max); modelos legados limitam em xhigh.
     • ultra = raciocínio máximo com delegação automática de tarefas (mais lento e caro — reserve para tarefas mais difíceis).
     • Se o esforço escolhido exceder o máximo do modelo escolhido, use o maior esforço suportado por aquele modelo e informe o usuário.
2. Selecione o modo sandbox necessário para a tarefa; use como padrão --sandbox read-only a menos que edições ou acesso à rede sejam necessários.
3. Monte o comando com as opções apropriadas:
   • -m, --model <MODELO>
   • --config model_reasoning_effort="<low|medium|high|xhigh|max|ultra>" (max/ultra apenas em modelos GPT-6 / GPT-5.6; ultra apenas em astra/sol/terra — veja passo 1)
   • --sandbox <read-only|workspace-write|danger-full-access>
   • --full-auto
   • -C, --cd <DIR>
   • --skip-git-repo-check
   • "seu prompt aqui" (como argumento posicional final)
4. Sempre use --skip-git-repo-check.
5. Ao continuar uma sessão anterior, use codex exec --skip-git-repo-check resume --last via stdin. Ao retomar, não use flags de configuração a menos que explicitamente solicitado pelo usuário (por exemplo, se ele especificar o modelo ou o esforço de raciocínio ao solicitar a retomada). Sintaxe de retomada: echo "seu prompt aqui" | codex exec --skip-git-repo-check resume --last 2>/dev/null. Todas as flags devem ser inseridas entre exec e resume.
6. IMPORTANTE: Por padrão, anexe 2>/dev/null a todos os comandos codex exec para suprimir tokens de pensamento (stderr). Mostre stderr apenas se o usuário solicitar explicitamente ver os tokens de pensamento ou se for necessário depuração.
7. IMPORTANTE (stdin): codex exec sempre lê stdin e o concatena com o prompt posicional — mesmo quando o prompt é totalmente fornecido como argumento posicional. Se o stdin não for fechado, o codex bloqueia para sempre. Ao invocar a partir de um harness (tarefas em segundo plano, hooks, scripts onde stdin não é um TTY mas também não está fechado), redirecione o stdin explicitamente: anexe </dev/null ao comando, por exemplo, codex exec ... "prompt" </dev/null 2>/dev/null. Sintoma de erro: zero bytes de stdout, zero CPU acumulado, processo parece travado indefinidamente.
8. Execute o comando, capture stdout/stderr (filtrados conforme apropriado) e resuma o resultado para o usuário.
9. Após o Codex concluir, informe ao usuário: "Você pode retomar esta sessão do Codex a qualquer momento dizendo 'codex resume' ou me pedindo para continuar com análises ou alterações adicionais."

Referência Rápida

Caso de uso	Modo sandbox	Flags principais
Revisão ou análise somente leitura	read-only	--sandbox read-only 2>/dev/null
Aplicar edições locais	workspace-write	--sandbox workspace-write --full-auto 2>/dev/null
Permitir rede ou acesso amplo	danger-full-access	--sandbox danger-full-access --full-auto 2>/dev/null
Retomar sessão recente	Herdado da original	echo "prompt" | codex exec --skip-git-repo-check resume --last 2>/dev/null (sem flags permitidas)
Executar de outro diretório	Corresponder às necessidades da tarefa	-C <DIR> mais outras flags 2>/dev/null

Timeouts de Execução

O Codex não produz saída intermediária — ele escreve o resultado apenas ao final. Se o processo for encerrado antes da conclusão, o arquivo de saída fica silenciosamente vazio (sem erro).

Abordagem preferida: executar de forma síncrona — elimina completamente o risco de timeout e a conversa espera pelo resultado de qualquer forma.

Se executar em segundo plano, defina o timeout de execução com base no esforço de raciocínio:

Esforço de raciocínio	Timeout
low	150s
medium	300s
high	600s
xhigh	1200s
max	1800s
ultra	1800s

Acompanhamento

• Após cada comando codex, use imediatamente AskUserQuestion para confirmar os próximos passos, coletar esclarecimentos ou decidir se deve retomar com codex exec resume --last.
• Ao retomar, envie o novo prompt via stdin: echo "novo prompt" | codex exec resume --last 2>/dev/null. A sessão retomada usa automaticamente o mesmo modelo, esforço de raciocínio e modo sandbox da sessão original.
• Reafirme o modelo escolhido, esforço de raciocínio e modo sandbox ao propor ações de acompanhamento.

Avaliação Crítica da Saída do Codex

O Codex é alimentado por modelos OpenAI com seus próprios cortes de conhecimento e limitações. Trate o Codex como um colega, não uma autoridade.

Diretrizes

• Confie no seu próprio conhecimento quando estiver confiante. Se o Codex afirmar algo que você sabe ser incorreto, conteste diretamente.
• Pesquise discordâncias usando WebSearch ou documentação antes de aceitar as afirmações do Codex. Compartilhe as descobertas com o Codex via retomada, se necessário.
• Lembre-se dos cortes de conhecimento - o Codex pode não saber sobre versões recentes, APIs ou mudanças que ocorreram após seus dados de treinamento.
• Não delegue cegamente - o Codex pode estar errado. Avalie suas sugestões criticamente, especialmente em relação a:
  • Nomes e capacidades de modelos
  • Versões recentes de bibliotecas ou mudanças de API
  • Melhores práticas que podem ter evoluído

Quando o Codex está Errado

1. Declare claramente sua discordância ao usuário
2. Forneça evidências (seu próprio conhecimento, pesquisa na web, documentação)
3. Opcionalmente, retome a sessão do Codex para discutir a discordância. Identifique-se como Claude para que o Codex saiba que é uma discussão entre IAs pares. Use seu nome de modelo real (por exemplo, o modelo que você está executando no momento) em vez de um nome fixo:

   echo "Este é o Claude (<seu nome de modelo atual>) acompanhando. Discordo de [X] porque [evidência]. Qual é a sua opinião sobre isso?" | codex exec --skip-git-repo-check resume --last 2>/dev/null
   

4. Enquadre discordâncias como discussões, não correções - qualquer IA pode estar errada
5. Deixe o usuário decidir como proceder se houver ambiguidade genuína

Tratamento de Erros

• Pare e reporte falhas sempre que codex --version ou um comando codex exec sair com código não zero; solicite orientação antes de tentar novamente.
• Antes de usar flags de alto impacto (--full-auto, --sandbox danger-full-access, --skip-git-repo-check), peça permissão ao usuário usando AskUserQuestion, a menos que já tenha sido concedida.
• Quando a saída incluir avisos ou resultados parciais, resuma-os e pergunte como ajustar usando AskUserQuestion.