Entenda a ponte codex-exec
O Codex tem um modo sem tela: codex exec. Você manda um pedido, ele trabalha e devolve a resposta final. Isso é uma CLI, o degrau 3 da escada de vias.
O kit embrulha esse comando num script curto: runtime/pontes/codex-exec.sh. É a ponte. Ela já escolhe o modelo, aplica a política e só devolve o texto que interessa.
Quem decide continua sendo o Claude. O Codex vira um colega que ele consulta, como você pediria a opinião de outra pessoa da equipe.
🆕 Novo aqui? Quatro palavras deste módulo
- Script — um arquivo de texto com comandos em sequência. Você roda o arquivo e ele executa tudo na ordem.
- stdin (entrada padrão) — o "cano" por onde um programa recebe texto. A ponte manda o seu pedido ao Codex por esse cano.
- Sandbox — uma caixa de areia: o espaço fechado onde o Codex trabalha. Ela define se ele só lê ou se também pode gravar arquivos.
- Saída — o que o programa imprime no terminal. Quando dá erro, ele também devolve um número (a "saída 2", por exemplo).
Como ler o desenho: a caixa azul do meio é a ponte. Tudo que é regra mora nela: qual sandbox vale, quanto tempo esperar e o que devolver. A seta tracejada de baixo é a resposta voltando para o Claude.
a via oficial (CLI)
codex-exec.sh
só lê, ou lê e grava
gasta cota, não API
Teste a ponte sozinha
Antes de pôr o Claude no meio, teste a ponte direto no terminal. Se ela falhar aqui, vai falhar dentro do agente também, e aí fica difícil saber de quem é a culpa.
O teste é o mais simples possível: pedir ao Codex que responda uma palavra só. Se a palavra volta, a ponte, o login e a cota estão funcionando.
Confira o login do Codex
O doctor do módulo 1.2 tem de mostrar codex ok e "Logged in using ChatGPT". Se não mostrar, rode codex login.
Dê permissão de execução ao script
O chmod +x marca o arquivo como "pode rodar". Só precisa uma vez.
Peça o PONG
Uma frase, uma palavra de volta. É a prova da receita R1.
No terminal, dentro da pasta do kit:
chmod +x runtime/pontes/codex-exec.sh runtime/pontes/codex-exec.sh "Responda apenas PONG"
Resultado provado no CHANGELOG 0.1.0:
PONG
PONG. Se aparecer codex falhou; log:, leia as linhas seguintes e vá ao tópico 6.💡 Por que um teste tão bobo
Um pedido de uma palavra gasta quase nada de cota e responde rápido. Ele separa problema de ponte (login, instalação) de problema de pedido. Só depois disso vale pedir algo sério.
pela assinatura
pode rodar
a prova da R1
antes do agente
Peça uma segunda opinião de dentro do Claude
Agora o uso de verdade. Você abre o Claude e pede que ele consulte o Codex. O Claude roda a ponte, lê a resposta e compara com a dele.
Por que isso vale a pena? A regra 3 do ROTEAMENTO.md responde: revisão por outro modelo pega erros que o mesmo modelo não vê. Dois olhares diferentes erram em lugares diferentes.
Abra claude na pasta do kit e cole:
Use runtime/pontes/codex-exec.sh para pedir ao Codex uma revisão do arquivo README.md: o que está confuso para um iniciante? Depois compare com a sua opinião.
runtime/pontes/codex-exec.sh e, na resposta, separa o que o Codex disse do que ele mesmo acha.Como ler o desenho: o mesmo arquivo segue por dois caminhos independentes. O valor está na caixa da direita: o que só um dos dois apontou é justamente o que você não teria visto pedindo a um modelo só.
A Clara pode usar a mesma ideia com os dados dela. Ela pede ao Claude: "Use runtime/pontes/codex-exec.sh para pedir ao Codex que confira se runtime/exemplos/agenda.csv tem dois atendimentos no mesmo horário com o mesmo profissional. Depois confira você também."
✓ Vale pedir segunda opinião
- ✓ Revisar texto que vai para cliente ou equipe
- ✓ Conferir uma conta ou uma planilha importante
- ✓ Antes de uma decisão difícil de desfazer
- ✓ Quando o Claude parece seguro demais
✗ Não compensa
- ✗ Tarefa trivial que um modelo resolve sozinho
- ✗ Toda pergunta, por hábito: gasta cota dos dois lados
- ✗ Quando você não vai ler a comparação
- ✗ Para "desempatar" sem olhar a evidência
regra 3 do roteamento
o Codex opina
padrão da ponte (N4)
o que só um viu
Deixe o Codex alterar arquivos
Por padrão a ponte usa o sandbox read-only: o Codex lê, mas não grava nada. É o teto "ler" da POLITICA.md, nível N4.
Quando você quer que ele crie ou altere arquivos, passa mais dois argumentos: a pasta e o sandbox workspace-write. Isso sobe a ação para "alterar", nível N3: ele faz e avisa.
| Sandbox | O Codex pode | Ação na POLITICA | Nível |
|---|---|---|---|
read-only (padrão) | ler arquivos da pasta | Ler arquivo, página, planilha | N4 |
workspace-write | ler e gravar dentro da pasta indicada | Criar/alterar arquivo do projeto | N3 |
O que olhar na tabela: são só duas linhas. Qualquer outro sandbox não passa pela ponte, como você vê no próximo tópico.
No terminal, dentro da pasta do kit:
runtime/pontes/codex-exec.sh "Crie notas.txt com a palavra OK" "$PWD" workspace-write cat notas.txt
Resultado provado no CHANGELOG 0.1.0 (o cat notas.txt):
OK
cat notas.txt mostra OK. O "$PWD" é a pasta onde você está: o Codex só grava ali dentro.⚠️ Gravar é decisão sua, não do agente
A receita é clara: alterar arquivos (N3) só se você pedir. Não deixe o Claude trocar sozinho o read-only por workspace-write "para agilizar". E aponte a pasta certa: o "$PWD" do projeto, nunca a sua pasta pessoal inteira.
padrão, N4
grava, N3
a pasta atual
a prova
Veja a política recusar o perigoso
O Codex tem um terceiro sandbox, danger-full-access: acesso total à máquina. A ponte não aceita. Antes de chamar o Codex, ela confere o sandbox e para na hora se não for um dos dois permitidos.
Isso é a política escrita em código, não num pedido educado ao agente. Mesmo que alguém peça, o comando não chega ao Codex.
Como ler o desenho: o porteiro fica antes do Codex. As setas azuis passam; a vermelha volta com a mensagem e a saída 2, sem que o Codex chegue a ser chamado.
No terminal, dentro da pasta do kit:
runtime/pontes/codex-exec.sh "x" . danger-full-access
Resultado provado no CHANGELOG 0.1.0 (a mensagem, com saída 2):
sandbox recusado pela POLITICA
✓ A ponte aceita
- ✓
read-only, quando você não diz nada - ✓
workspace-write, quando você pede - ✓ Qualquer pasta que você indicar no 2º argumento
✗ A ponte recusa
- ✗
danger-full-access - ✗ Qualquer nome de sandbox fora da lista
- ✗ Chamar sem pedido nenhum (ela mostra o "uso")
💡 Regra que vale para toda ponte
Coloque o limite dentro da ponte, não só no texto do pedido. O agente pode esquecer uma instrução; uma linha de código que recusa não esquece. O teste de "recusou?" vale tanto quanto o teste de "funcionou?".
Ajuste modelo, tempo e erros comuns
A ponte tem dois ajustes, feitos por variável de ambiente: um valor com nome que você define no terminal antes do comando, e que o script lê.
O padrão do modelo é gpt-6-luna, o nível "menor" do ROTEAMENTO.md. Começar pelo menor economiza cota. Só suba quando a resposta não servir.
| Variável | Padrão | Para quê |
|---|---|---|
CODEX_MODELO | gpt-6-luna | outro nível do ROTEAMENTO.md (no Codex: gpt-6-sol executor, gpt-6-astra topo e super) |
CODEX_TIMEOUT | 600 | segundos até desistir |
O que olhar na tabela: os nomes de modelo mudam com o tempo. O próprio ROTEAMENTO.md manda conferir com codex --help e atualizar a tabela.
Erros comuns (seção "Se der erro" da R1)
Fica parado sem responder
O pedido precisa ir pelo stdin com - no fim, senão o Codex fica esperando mais texto. A ponte já faz isso; o problema aparece quando alguém chama codex exec direto, sem a ponte.
sandbox recusado pela POLITICA
Só read-only e workspace-write são aceitos. Confira o 3º argumento.
O teste precisa de rede
O sandbox do Codex bloqueia rede, até a local. Se o teste precisar subir um servidor, acrescente -c sandbox_workspace_write.network_access=true na ponte e anote em LIMITES.md.
💡 Anote antes de seguir
A ponte já tem linha no CAPACIDADES.md: "Codex CLI · CLI · 3 · runtime/pontes/codex-exec.sh · ler (N4)". Se você mudou o sandbox de rede, o registro vai no LIMITES.md, com data. Assim ninguém descobre a mudança só quando algo quebra.
Teste rápido (opcional): a Clara quer que o Codex só leia a agenda e dê uma opinião. Qual chamada da ponte serve?
comece pelo menor
600 segundos
senão trava
ajuste anotado
🎓 Resumo do módulo
Próximo módulo:
2.2 — Sua primeira ponte MCP