Codex CLI

O que Codex CLI faz?

Delegue tarefas de codificação para o Codex por meio do terminal Hermes. Codex é o CLI de agente autônomo de codificação da OpenAI.

Quando usar

• Construção de funcionalidades
• Refatoração
• Revisões de PR
• Correção de problemas em lote

Requer o CLI Codex e um repositório git.

Pré-requisitos

• Codex instalado: npm install -g @openai/codex
• Autenticação OpenAI configurada: OPENAI_API_KEY ou credenciais OAuth do Codex a partir do fluxo de login do Codex CLI
• Deve ser executado dentro de um repositório git — Codex se recusa a executar fora de um
• Use pty=true nas chamadas de terminal — Codex é um aplicativo de terminal interativo

Para o próprio Hermes, model.provider: openai-codex usa o Codex OAuth gerenciado pelo Hermes em ~/.hermes/auth.json após hermes auth add openai-codex. Para o Codex CLI independente, uma sessão OAuth válida do CLI pode estar em ~/.codex/auth.json; não trate a ausência de OPENAI_API_KEY como prova de que a autenticação do Codex está faltando.

Tarefas Únicas

terminal(command="codex exec 'Adicionar alternância de modo escuro às configurações'", workdir="~/projeto", pty=true)

Para trabalho temporário (Codex precisa de um repositório git):

terminal(command="cd $(mktemp -d) && git init && codex exec 'Criar um jogo da cobra em Python'", pty=true)

Modo Plano de Fundo (Tarefas Longas)

# Iniciar em segundo plano com PTY
terminal(command="codex exec --full-auto 'Refatorar o módulo de autenticação'", workdir="~/projeto", background=true, pty=true)
# Retorna session_id

# Monitorar progresso
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")

# Enviar entrada se o Codex fizer uma pergunta
process(action="submit", session_id="<id>", data="sim")

# Finalizar se necessário
process(action="kill", session_id="<id>")

Principais Flags

Flag	Efeito
exec "prompt"	Execução única, encerra quando termina
--full-auto	Em sandbox, mas aprova automaticamente alterações de arquivos no workspace
--yolo	Sem sandbox, sem aprovações (mais rápido, mais perigoso)
--sandbox danger-full-access	Sem sandbox do Codex; útil quando o contexto do serviço host quebra o bubblewrap

Atenção sobre o Gateway Hermes

Ao invocar o Codex CLI a partir de um contexto de gateway/serviço do Hermes (por exemplo, sessões de agente dirigidas pelo Telegram), a proteção de sandbox do Codex workspace-write pode falhar mesmo que o mesmo comando funcione no shell interativo do usuário. Um sintoma típico são erros de bubblewrap/namespace de usuário como setting up uid map: Permission denied ou loopback: Failed RTM_NEWADDR: Operation not permitted.

Nesse contexto, prefira:

codex exec --sandbox danger-full-access "<tarefa>"

Use os limites do processo como camada de segurança: workdir explícito, status git limpo antes da inicialização, prompts de tarefa específicos, revisão git diff, testes direcionados e confirmação humana/de agente antes de confirmar alterações amplas.

Revisões de PR

Clone para um diretório temporário para revisão segura:

terminal(command="REVISÃO=$(mktemp -d) && git clone https://github.com/usuario/repo.git $REVISÃO && cd $REVISÃO && gh pr checkout 42 && codex review --base origin/main", pty=true)

Correção Paralela de Problemas com Worktrees

# Criar worktrees
terminal(command="git worktree add -b correcao/issue-78 /tmp/issue-78 main", workdir="~/projeto")
terminal(command="git worktree add -b correcao/issue-99 /tmp/issue-99 main", workdir="~/projeto")

# Iniciar Codex em cada um
terminal(command="codex --yolo exec 'Corrigir issue #78: <descrição>. Confirmar quando terminar.'", workdir="/tmp/issue-78", background=true, pty=true)
terminal(command="codex --yolo exec 'Corrigir issue #99: <descrição>. Confirmar quando terminar.'", workdir="/tmp/issue-99", background=true, pty=true)

# Monitorar
process(action="list")

# Após conclusão, enviar e criar PRs
terminal(command="cd /tmp/issue-78 && git push -u origin correcao/issue-78")
terminal(command="gh pr create --repo usuario/repo --head correcao/issue-78 --title 'correção: ...' --body '...'")

# Limpeza
terminal(command="git worktree remove /tmp/issue-78", workdir="~/projeto")

Revisões de PR em Lote

# Buscar todas as referências de PR
terminal(command="git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'", workdir="~/projeto")

# Revisar vários PRs em paralelo
terminal(command="codex exec 'Revisar PR #86. git diff origin/main...origin/pr/86'", workdir="~/projeto", background=true, pty=true)
terminal(command="codex exec 'Revisar PR #87. git diff origin/main...origin/pr/87'", workdir="~/projeto", background=true, pty=true)

# Publicar resultados
terminal(command="gh pr comment 86 --body '<revisão>'", workdir="~/projeto")

Regras

1. Sempre use pty=true — Codex é um aplicativo de terminal interativo e trava sem um PTY
2. Repositório Git obrigatório — Codex não executa fora de um diretório git. Use mktemp -d && git init para temporário
3. Use exec para tarefas únicas — codex exec "prompt" executa e termina corretamente
4. --full-auto para construção — aprova automaticamente alterações dentro do sandbox
5. Plano de fundo para tarefas longas — use background=true e monitore com a ferramenta process
6. Não interfira — monitore com poll/log, seja paciente com tarefas demoradas
7. Paralelo é aceitável — execute vários processos Codex ao mesmo tempo para trabalho em lote