Otimização de modelos no Codex CLI

Instruções da skill

---
name: codex-otimizacao
description: Configura o roteamento de modelos de um projeto no OpenAI Codex CLI — descobre o catálogo de modelos vigente, define o modelo e o esforço de raciocínio da sessão principal, cria subagentes em modelos mais baratos para exploração e execução, e escreve a política de delegação no AGENTS.md, tudo adaptado ao stack do repositório. Use quando pedirem para otimizar custo do Codex num diretório, reduzir gasto de tokens, configurar subagentes ou reasoning effort, usar um modelo barato para tarefas pequenas, ou montar a configuração do Codex num repositório novo.
---

# Otimização de modelos no Codex CLI

Monta, num diretório de projeto, a configuração que faz a sessão principal do Codex rodar num modelo forte e delegar as tarefas menores a subagentes em modelos mais baratos.

O Codex tem duas alavancas de custo, não uma. Além de **qual modelo** roda cada coisa, existe **quanto esforço de raciocínio** ele gasta (`model_reasoning_effort`). Um `gpt-5.6-sol` em `xhigh` custa muito mais que o mesmo modelo em `low`. Configure as duas juntas, sempre.

Subagentes são nativos e ligados por padrão (`multi_agent`), então a delegação é de primeira classe — mas o modelo principal só delega quando o pedido ou o `AGENTS.md` mandam. Sem a política escrita, a configuração não economiza nada.

## Regra geral

Nunca sobrescreva `.codex/config.toml` ou `AGENTS.md` existentes. Leia, mescle, preserve.

## Passo 1 — Situar-se

```bash
pwd && ls -a
test -d .git && git rev-parse --show-toplevel
ls -a .codex/ 2>/dev/null
ls .codex/agents/ 2>/dev/null
cat .codex/config.toml 2>/dev/null
cat ~/.codex/config.toml 2>/dev/null
ls AGENTS.md AGENTS.override.md 2>/dev/null
codex --version 2>/dev/null
```

O Codex exige repositório Git para rodar sem `--skip-git-repo-check`. Se não houver `.git`, avise o usuário antes de escrever.

Se já existirem agentes em `.codex/agents/`, liste-os e pergunte se devem ser mantidos, substituídos ou complementados. Nunca apague um agente existente sem confirmação.

**Projeto confiável:** o Codex só lê `.codex/` de projetos marcados como confiáveis. Se o usuário marcou este projeto como untrusted, toda a configuração local é ignorada — verifique isso antes de concluir que algo não funcionou.

## Passo 2 — Descobrir o catálogo de modelos

Faça isto **toda vez**, antes de escolher o perfil. Os slugs do Codex mudam com frequência e modelos são retirados com data marcada — `gpt-5.4` saiu em 31/08/2026, `gpt-5.5` sai em 14/10/2026, e `gpt-5-codex`, `o3`, `o4-mini` e `codex-mini-latest` já não existem. Nunca escreva um slug de memória.

Pare no primeiro degrau que devolver uma lista utilizável.

**Degrau 1 — catálogo local declarado.** Se o usuário aponta um catálogo próprio, ele é a verdade para esta máquina:

```bash
grep -h 'model_catalog_json' ~/.codex/config.toml .codex/config.toml 2>/dev/null
```

Se houver, leia o JSON apontado.

**Degrau 2 — o próprio binário e a conta.**

```bash
codex --help 2>/dev/null | grep -i -A3 -- '--model'
```

Se a saída não listar modelos, peça ao usuário para rodar `/model` numa sessão do Codex e colar o que aparece. É o único degrau que reflete o plano da conta: modelos restritos a plano Pro só aparecem aqui.

**Degrau 3 — catálogo publicado.** A página de modelos aceita `.md` no fim da URL. O conteúdo vem com componentes JSX, e os slugs ficam em atributos `slug="..."`; as notas de retirada aparecem como texto:

```bash
curl -sS --max-time 20 https://learn.chatgpt.com/docs/models.md > /tmp/codex-models.md
grep -oE 'slug="[^"]+"' /tmp/codex-models.md | sort -u
grep -iE 'retir|replace .* with|deprecat' /tmp/codex-models.md
```

Se o `curl` falhar por rede ou proxy, busque a mesma URL com a ferramenta de fetch web disponível na sessão.

**Degrau 4 — fallback datado.** Só se os anteriores falharem: use a tabela de `references/modelos-e-perfis.md`, marcada com a data em que foi conferida, e **diga ao usuário** que o catálogo pode estar velho e que ele deve confirmar com `/model`.

Ao final você deve ter, explicitamente: quais slugs existem, qual é caro e qual é barato, e quais têm data de retirada. Se dois degraus discordarem, prevaleça o mais alto e mencione a divergência. Não configure um projeto com modelo perto da aposentadoria.

## Passo 3 — Escolher o perfil

Pergunte ao usuário qual perfil aplicar. Se ele já tiver dito na conversa, não pergunte de novo.

| Perfil | Sessão principal | Subagente `worker` | Subagente `explorer` | Quando |
| --- | --- | --- | --- | --- |
| `max` | modelo de topo, effort `high` | modelo forte, effort `high` | modelo barato, effort `medium` | Arquitetura difícil, refatoração ampla |
| `equilibrado` | modelo forte, effort `medium` | modelo intermediário, effort `medium` | modelo barato, effort `low` | Desenvolvimento do dia a dia |
| `economico` | modelo intermediário, effort `medium` | modelo barato, effort `medium` | modelo barato, effort `low` | Manutenção e correções pequenas |

Mapeamento para slugs concretos em `references/modelos-e-perfis.md`.

## Passo 4 — Ler o projeto

O valor da skill está aqui: os agentes precisam dos comandos reais do projeto.

```bash
ls package.json pyproject.toml requirements.txt go.mod Cargo.toml composer.json Gemfile pom.xml build.gradle 2>/dev/null
```

Extraia o comando de teste, o de lint e format, o gerenciador de pacotes, onde ficam código e testes, e leia o `AGENTS.md` e o `CONTRIBUTING.md` existentes. Confirme o comando de teste com o usuário se houver ambiguidade — um agente que roda o comando errado é pior que nenhum.

## Passo 5 — Escrever a configuração

### .codex/config.toml do projeto

Mescle preservando o que houver:

```bash
mkdir -p .codex/agents
python3 - <<'PY'
import pathlib, re
p = pathlib.Path(".codex/config.toml")
atual = p.read_text() if p.exists() else ""
bloco = '''
# --- otimização de modelos (codex-otimizacao) ---
model = "MODELO_PRINCIPAL"
model_reasoning_effort = "medium"

[agents]
default_subagent_model = "MODELO_BARATO"
default_subagent_reasoning_effort = "low"
max_concurrent_threads_per_session = 4
'''
if "codex-otimizacao" in atual:
    print("bloco já existe; edite manualmente em vez de duplicar")
else:
    p.write_text(atual.rstrip() + "\n" + bloco)
    print(p.read_text())
PY
```

`agents.default_subagent_model` é a rede de segurança: todo subagente que não declarar modelo próprio cai nele em vez de herdar o modelo caro da sessão.

Chaves opcionais que valem considerar, explicando ao usuário antes de gravar:

- `web_search = "cached"` — o padrão; `"live"` custa mais e abre rede
- `model_auto_compact_token_limit` — compacta o contexto antes de estourar
- `tool_output_token_limit` — corta saídas gigantes de comando
- `[sandbox_workspace_write] network_access = false` — mantém a rede fechada na escrita

### Subagentes

Um arquivo TOML por agente em `.codex/agents/`. Campos **obrigatórios**: `name`, `description`, `developer_instructions`. Opcionais mais úteis: `model`, `model_reasoning_effort`, `sandbox_mode`.

O `description` é o que faz a sessão principal escolher o agente certo — descreva **situações**, não capacidades.

Base mínima, com templates completos em `references/agentes.md`:

- **`explorer`** — leitura e investigação, modelo barato, `sandbox_mode = "read-only"`
- **`worker`** — implementação com arquitetura já definida, modelo intermediário

Acrescente conforme o repositório: `testes` (barato, read-only, com o comando real do projeto), `reviewer` (forte, read-only), `migracoes` (forte) quando houver migrações de banco.

Os nomes `default`, `worker` e `explorer` são agentes embutidos: criar um arquivo com esses nomes **sobrescreve** o embutido, o que é o comportamento desejado aqui.

### Política de delegação no AGENTS.md

Anexe uma seção ao `AGENTS.md` da raiz, criando o arquivo se não existir, sem tocar no resto:

```markdown
## Delegação

Antes de executar, classifique a tarefa:

- Investigar, mapear, localizar uso, ler muitos arquivos, rodar testes e
  reportar → delegue ao `explorer`.
- Implementar módulo, endpoint ou correção com arquitetura já definida →
  delegue ao `worker`.
- Decisão de arquitetura, modelagem de dados, revisão de segurança,
  refatoração que cruza módulos, bug sem causa conhecida → faça na sessão
  principal.

Prefira agentes paralelos em trabalho de leitura; seja conservador com
escrita em paralelo, que gera conflito de arquivo.
Não releia o que um agente já resumiu.
```

**Cuidado com o tamanho:** a cadeia de `AGENTS.md` tem limite de 32 KiB por padrão (`project_doc_max_bytes`) e é truncada em silêncio ao estourar. Se o arquivo do projeto já for grande, avise o usuário e mantenha a seção curta em vez de aumentar o limite.

### Perfil global, se o usuário quiser alternar

Perfis hoje são **arquivos separados**, um por perfil — a sintaxe antiga `[profiles.nome]` foi removida na versão 0.134.0 e não funciona mais.

```bash
cat > ~/.codex/revisao.config.toml <<'EOF'
model = "MODELO_DE_TOPO"
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"
EOF
```

Uso: `codex --profile revisao`.

## Passo 6 — Verificar e relatar

```bash
cat .codex/config.toml
ls -1 .codex/agents/
head -6 .codex/agents/*.toml
```

Confirme que cada agente tem `model` e `model_reasoning_effort` declarados, e que todo agente de leitura tem `sandbox_mode = "read-only"`.

**Teste de fumaça.** Se o usuário autorizar (custa uma chamada mínima), valide cada slug gravado antes de dar o trabalho por concluído:

```bash
codex exec -m SLUG_PRINCIPAL --skip-git-repo-check "responda apenas OK"
```

Erro de modelo desconhecido aqui é muito melhor que erro na primeira tarefa real do usuário.

Relate em poucas linhas: de qual degrau veio o catálogo, o perfil aplicado, os agentes criados com modelo e effort de cada um, o que foi preservado, e o tamanho atual da cadeia de `AGENTS.md` se estiver perto do limite. Lembre que `-c`/`--config` e `-m` na linha de comando vencem tudo o que foi escrito, então um alias de shell com `--model` fixo anula a configuração.

## Armadilhas

- Subagente sem `model` herda o modelo da sessão principal se `agents.default_subagent_model` não estiver definido. É o vazamento de custo mais comum.
- Esquecer o `model_reasoning_effort` deixa o agente barato gastando como caro.
- Projeto marcado como untrusted faz o Codex ignorar todo o `.codex/` local.
- `AGENTS.md` acima de 32 KiB é truncado sem aviso.
- Agente de leitura sem `sandbox_mode = "read-only"` pode escrever por engano.
- Subagentes consomem mais tokens no total que uma sessão única: a economia vem de eles rodarem em modelo barato e devolverem só o resumo. Se configurar todos no modelo caro, o custo sobe em vez de cair.
- Em execução não-interativa, ação que peça aprovação nova simplesmente falha; ajuste `approval_policy` e `sandbox_mode` antes de automatizar.
- Nomes de modelo são retirados com data marcada. A descoberta do passo 2 é obrigatória a cada execução, inclusive ao revisitar um projeto configurado meses atrás: compare o que está gravado com o catálogo atual.

Requisitos

• OpenAI Codex CLI 0.134.0 ou superior (perfis em arquivo separado e subagentes nativos)
• acesso a terminal no diretório do projeto
• repositório Git inicializado
• python3 disponível para mesclar TOML com segurança

Permissões declaradas

• leitura e escrita em .codex/config.toml, .codex/agents/ e AGENTS.md do projeto
• execução de comandos somente-leitura no repositório (ls, cat, git, grep, codex --version)
• escrita opcional de arquivo de perfil em ~/.codex/ mediante confirmação do usuário

Versões

• v1.0.0

  Primeira publicação. Descobre o catálogo de modelos vigente em tempo de execução (model_catalog_json, CLI e conta, catálogo publicado, fallback datado) e configura modelo e reasoning effort da sessão principal, subagentes TOML em .codex/agents/, defaults em [agents] e política de delegação no AGENTS.md, com três perfis (max, equilibrado, economico).