Folha de Dicas de Comandos e Configurações
📚 Navegação da Série: A anterior 〔34 Projeto Prático Integrado〕 levou você a conectar todas as peças anteriores em um projeto completo para executar, isso foi a "união". Esta parte faz o inverso — extrai todos os comandos, flags e chaves de configuração espalhados por mais de trinta capítulos e os compacta em uma folha de dicas que você pode colar na lateral do seu monitor. O próximo capítulo 〔36 Melhores Práticas〕 concluirá toda a seção do Codex focando em "como usar corretamente".
Para ser sincero, isso é um pouco embaraçoso.
Nos primeiros meses usando o Codex, eu tinha um arquivo chamado codex-备忘.txt no meu computador, onde anotei de qualquer jeito coisas como "exportar JSON é --json" e "escrever a última mensagem em um arquivo é -o". O problema era a bagunça. Toda vez que eu precisava usar codex exec para gravar os resultados em um arquivo, eu tinha que vasculhar esse txt primeiro. Se não achava, buscava no histórico do shell com history | grep codex. Se ainda assim não encontrava, abria o navegador para pesquisar na documentação oficial — algo que deveria ser apenas um comando acabava me custando cinco minutos de frustração.
O mais estúpido eram as configurações. Uma vez eu quis desativar temporariamente a rede do sandbox para um determinado projeto. Lembrava que havia uma chave que começava com sandbox_workspace_write, mas esqueci completamente o que vinha a seguir: network? net_access? Fiquei tentando no config.toml às cegas até o Codex dar erro de inicialização. No final, tive que consultar a referência de configuração (config-reference) para descobrir que era sandbox_workspace_write.network_access. Naquele momento, decidi: Em vez de pesquisar toda vez, é melhor extrair de uma vez por todas os comandos e configurações de alta frequência e organizá-los em uma tabela, para poder apenas bater o olho e seguir em frente.
Este capítulo é o resultado dessa tabela. Ele não explica os conceitos (os princípios já foram explicados anteriormente), faz apenas uma coisa — permitir que você consulte rapidamente, copie com precisão e não precise abrir o navegador novamente.
Ao terminar de ler este capítulo, você obterá:
- Uma folha de dicas abrangendo instalação e login, comandos e flags da CLI, comandos com barra (slash commands) e itens de configuração frequentes do
config.toml - Uma tabela comparativa de níveis de permissão do sandbox, modelos e esforço de raciocínio, para preencher corretamente sem errar
- Uma lista de "pontos de entrada cruciais" para recursos avançados como MCP (Model Context Protocol, Protocolo de Contexto de Modelo) / subagentes / Skills, sabendo a partir de qual comando iniciar
- Um pequeno exemplo prático para verificar se os comandos consultados realmente funcionam no seu ambiente local
⚠️ Os comandos, flags e chaves de configuração baseiam-se na documentação oficial e podem mudar com as versões; os nomes dos modelos e os valores padrão mudam conforme a versão e a sua conta, estando sempre sujeitos ao comportamento real do seu
codex --helpeconfig.tomllocais; confirme a versão atual através decodex --version. Os itens marcados abaixo como "experimentais" serão indicados no início, portanto tenha atenção antes de usá-los.
01 Instalação e Login
Seja na primeira instalação, ao trocar de máquina ou ao reiniciar em um ambiente de CI, estes são os comandos mais comuns. Analogia: Este é o "kit de inicialização em três etapas" do Codex — instale, faça login e confirme que o login foi bem-sucedido; se faltar um passo, ele não funcionará.
Sob restrições de rede, o script de instalação e o login via OAuth podem exigir o uso de uma VPN/proxy, caso contrário, é fácil travar na etapa de download ou de callback.
| Objetivo | Comando | Plataforma / Observações |
|---|---|---|
| Instalação padrão (script) | curl -fsSL https://chatgpt.com/codex/install.sh | sh | macOS / Linux |
| Instalação padrão (script) | powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex" | Windows |
| Instalar via npm | npm install -g @openai/codex | Todas as plataformas, requer Node.js |
| Instalar via Homebrew | brew install --cask codex | macOS |
| Atualizar para a versão mais recente | codex update | Disponível quando a distribuição suporta auto-atualização |
| Login (OAuth via navegador) | codex login | Método padrão, abre o navegador para fazer login no ChatGPT |
| Login (código de dispositivo) | codex login --device-auth | Usado quando não é possível abrir o navegador (ex: servidor remoto) |
| Login com API Key | printenv OPENAI_API_KEY | codex login --with-api-key | Lê a chave a partir do stdin |
| Verificar status de login | codex login status | O código de saída quando logado é 0, adequado para verificação em scripts |
| Fazer logout | codex logout | Limpa as credenciais locais |
| Diagnóstico de integridade | codex doctor | Executar após instalar ou quando houver problemas; autoverifica instalação, configuração, autenticação, Git, etc. |
💡 Resumo em uma frase: após a instalação, execute primeiro o
codex doctorpara um diagnóstico e depois usecodex login statuspara confirmar o estado do login; isso evitará metade dos problemas no início.
02 Comandos e Flags Comuns da CLI do codex
Esta é a parte mais central de todo o capítulo. Analogia: codex é o programa principal, seguido pelo "subcomando" (para onde ir) e depois pelo --xxx que é a "flag" (como ir). Memorize primeiro os subcomandos, depois as flags, e combiná-los resultará em um comando completo.
Subcomandos Comuns
| Subcomando | O que faz | Maturidade |
|---|---|---|
codex | Inicia a interface de usuário baseada em terminal interativo (TUI, Terminal User Interface), sendo o padrão quando nenhum subcomando é fornecido | Estável |
codex exec | Executa uma vez de forma não interativa e sai imediatamente ao concluir; atalho codex e | Estável |
codex resume | Continua a conversa a partir da última sessão interativa | Estável |
codex fork | Cria um "fork" de uma sessão em uma nova thread, mantendo o histórico original intacto | Estável |
codex apply | Aplica localmente as alterações (diff) geradas por uma tarefa em nuvem; atalho codex a | Estável |
codex mcp | Gerencia servidores MCP (list / add / remove / login) | Experimental |
codex features | Lista as flags de recursos (features) e as ativa/desativa permanentemente | Estável |
codex completion | Gera scripts de autocompletar do shell | Estável |
Flags Globais Frequentes (seguem o codex ou a maioria dos subcomandos)
| Flag | Ação | Valores / Observações |
|---|---|---|
--model / -m | Muda temporariamente o modelo | Ex: -m gpt-5.5 |
--image / -i | Anexa imagens ao primeiro prompt | Separe múltiplos arquivos com vírgula ou repita -i |
--cd / -C | Especifica o diretório de trabalho antes de iniciar | Recebe um caminho |
--sandbox / -s | Seleciona o nível do sandbox | read-only / workspace-write / danger-full-access |
--ask-for-approval / -a | Seleciona o momento de aprovação | untrusted / on-request / never |
--search | Ativa a pesquisa web em tempo real | Altera web_search para live (o padrão é cached) |
--add-dir | Concede permissão de escrita adicional a um diretório específico | Pode ser repetido, sendo mais seguro do que liberar acesso total ao disco |
--profile / -p | Aplica um determinado perfil (profile) de configuração | Sobrepõe-se às configurações básicas |
--config / -c | Altera temporariamente as configurações via linha de comando | -c key=value, se puder ser analisado como TOML, será tratado como TOML |
--yolo | Ignora todas as aprovações e o sandbox | Perigoso, use apenas em ambientes isolados |
Flags Exclusivas de Alta Frequência do codex exec (Não Interativo)
Este é o conjunto mais comum para escrever scripts e executar em CI. Analogia: O modo interativo é como pedir comida no restaurante, enquanto o codex exec é como pedir um delivery — você faz o pedido e vai embora, e o resultado é entregue no local especificado.
| Flag | Ação |
|---|---|
PROMPT definido como - | Lê o prompt do stdin (ex: cat prompt.txt | codex exec -) |
--json | Gera uma saída em fluxo de eventos JSON em linhas (JSONL), facilitando a análise com jq |
--output-last-message / -o | Escreve a resposta final em um arquivo (enquanto ainda imprime no stdout) |
--output-schema | Fornece um JSON Schema para forçar a saída final a estar em conformidade com essa estrutura |
--skip-git-repo-check | Permite a execução em diretórios que não sejam Git |
--ephemeral | Não salva o histórico da sessão no disco |
--full-auto | Descontinuado, serve apenas para compatibilidade e exibirá um aviso; novos scripts devem usar --sandbox workspace-write |
codex exec resume --last | Continua a partir da sessão exec mais recente |
💡 Resumo em uma frase: trocar de modelo com
-m, ajustar o sandbox com-s, configurar a aprovação com-ae coletar os resultados com-o/--json— memorize essas quatro coisas e você cobrirá 80% dos cenários de linha de comando.
03 Comandos com Barra (Digitados na TUI)
Os comandos com barra são usados apenas na interface interativa — ao entrar na interface em tela cheia do codex, digite / para abrir o menu. Analogia: Eles são "botões de atalho" na sessão, eliminando a necessidade de sair para digitar comandos no shell; basta digitar uma barra e alternar ali mesmo.
Abaixo estão os que eu utilizo com mais frequência. A lista completa dependerá do menu suspenso que aparece ao digitar / localmente, variando conforme a versão.
| Comando com Barra | O que faz |
|---|---|
/model | Alterna o modelo atual (ajustando também o esforço de raciocínio, quando disponível) |
/status | Exibe o modelo atual, política de aprovação, diretórios graváveis e contexto restante |
/compact | Comprime conversas longas em resumos para liberar espaço no contexto |
/diff | Mostra o Git diff, incluindo até arquivos novos não rastreados |
/permissions | Ajusta no meio da sessão quais ações o Codex pode realizar sem perguntar |
/review | Solicita que o Codex faça uma revisão (review) das alterações no seu workspace atual |
/init | Gera o scaffold do AGENTS.md no diretório atual |
/skills | Navega e seleciona as skills locais |
/agent | Alterna entre threads de subagentes criadas |
/fast | Ativa/desativa a camada de serviço Fast para o modelo atual (/fast on/off/status) |
/new | Inicia uma nova conversa na mesma sessão de CLI |
/clear | Limpa a tela e inicia uma nova conversa |
/quit ou /exit | Sai da CLI |
Um lembrete: /fast é "orientado ao catálogo de modelos" — se o modelo atual não oferecer uma camada Fast, /fast nem sequer aparecerá no menu, portanto não pense que se trata de um bug.
💡 Resumo em uma frase: os quatro mais frequentes na sessão são —
/modelpara mudar o modelo,/statuspara ver a situação atual,/compactpara limpar o contexto e/diffpara verificar os resultados. Pratique esses quatro até virarem memória muscular.
04 Itens de Configuração Comuns no config.toml
O arquivo de configuração fica em ~/.codex/config.toml (formato TOML) e representa a "memória de longo prazo" do Codex. Analogia: As flags da linha de comando são "como fazer esta viagem específica", enquanto o config.toml define "como fazer todas as viagens por padrão no futuro". Você também pode colocar um .codex/config.toml no projeto para sobreposições no nível do projeto (requer confiar no projeto primeiro).
Abaixo estão listados apenas os itens de alta frequência; para ver a lista completa, consulte a referência de configuração (config-reference) oficial.
| Chave de Configuração | Ação | Exemplo de Valor |
|---|---|---|
model | Modelo padrão | "gpt-5.5" |
model_reasoning_effort | Esforço de raciocínio | minimal / low / medium / high / xhigh |
model_reasoning_summary | Detalhamento do resumo de raciocínio | auto / concise / detailed / none |
service_tier | Nível de serviço | flex / fast (relacionado à aceleração, emparelhado com /fast) |
sandbox_mode | Nível do sandbox | read-only / workspace-write / danger-full-access |
sandbox_workspace_write.network_access | Se permite acesso à rede sob o modo de escrita do workspace | true / false |
sandbox_workspace_write.writable_roots | Diretórios graváveis adicionais | ["/path/a", "/path/b"] |
approval_policy | Política de aprovação | untrusted / on-request / never |
web_search | Modo de pesquisa web | disabled / cached / live (padrão é cached) |
review_model | Modelo usado pelo /review | Se não preenchido, usa o modelo da sessão atual |
model_instructions_file | Usa um arquivo específico para substituir as instruções internas | Um caminho |
Um config.toml mínimo viável se parece com isto; você pode copiá-lo e modificá-lo para uso imediato:
model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
[sandbox_workspace_write]
network_access = false💡 Resumo em uma frase: definir as quatro chaves
model,model_reasoning_effort,sandbox_modeeapproval_policynoconfig.tomlé equivalente a dar ao Codex sua "personalidade padrão", com as demais flags da linha de comando prontas para sobreposição temporária.
05 Permissões / Níveis de Sandbox
O sandbox determina até que ponto o Codex pode interagir com sua máquina, e a aprovação decide se ele perguntará antes de agir. Os dois funcionam em conjunto. Analogia: O sandbox é "em quais salas o estagiário pode entrar", enquanto a aprovação é "se ele precisa chamar você antes de agir".
Nível de Sandbox (--sandbox / sandbox_mode) | O que faz | Cenários Recomendados |
|---|---|---|
read-only | Apenas leitura, não pode alterar arquivos | Para permitir apenas visualização e análise inicial, sem alterar o código |
workspace-write | Pode alterar arquivos dentro do workspace | A escolha ideal para desenvolvimento local diário |
danger-full-access | Leitura e escrita completas no disco, acesso à rede liberado | Use apenas em contêineres isolados ou runners de CI |
Momento de Aprovação (--ask-for-approval / approval_policy) | Significado |
|---|---|
untrusted | Permite apenas comandos que considera confiáveis; para os demais, pergunta |
on-request | Recomendado para execução interativa, pausando para perguntar apenas quando necessário |
never | Nunca pergunta; usado para execução não interativa/CI |
A recomendação oficial para trabalhar localmente com o mínimo de atrito é apenas uma linha:
codex --sandbox workspace-write --ask-for-approval on-requestAlguns pontos adicionais que aprendi na prática: se você quiser conceder permissão de escrita para outro diretório ao Codex, não use danger-full-access por pura conveniência; use --add-dir para liberar precisamente aquele diretório; --full-auto é uma sintaxe de compatibilidade antiga e obsoleta, devendo novos scripts ser alterados exclusivamente para --sandbox workspace-write.
💡 Resumo em uma frase: por padrão no ambiente local use "
workspace-write+on-request", em CI use " sandbox especificado +never"; se precisar liberar acesso, pense primeiro se pode usar--add-direm vez de liberar tudo.
06 Comparação de Modelos e Esforço de Raciocínio
Escolher um modelo define "quem enviar", enquanto ajustar o esforço de raciocínio define "quanto tempo deixá-lo pensar antes de agir" — esses dois botões são independentes. Analogia: O modelo é o profissional contratado, e o esforço de raciocínio é o tempo concedido para ele pensar — não faça um especialista gastar tempo com tarefas simples, nem deixe um iniciante entregar tarefas complexas às pressas.
| Modelo | Posicionamento | Quando usar |
|---|---|---|
gpt-5.5 | Flagship, o mais poderoso | Programação complexa, refatoração e tarefas difíceis de pesquisa |
gpt-5.4-mini | Leve, rápido e econômico | Tarefas cotidianas, tarefas em lote e subagentes |
gpt-5.3-codex-spark | Visualização rápida de pesquisa (apenas ChatGPT Pro) | Para iterações em tempo real com resposta quase instantânea |
gpt-5.2 e gpt-5.3-codex foram descontinuados; não os escreva mais na configuração ou no --model.
O esforço de raciocínio é controlado por model_reasoning_effort e possui os seguintes níveis:
| Valor | Intensidade do Pensamento | Cenário Típico |
|---|---|---|
minimal | Quase sem pensar, o mais rápido | Corrigir erros de digitação (typo), renomear, executar comandos |
low | Pensar brevemente | Pequenos ajustes e correções |
medium | A escolha ideal padrão (sweet spot) | Grande maioria da programação diária |
high | Reflexão profunda | Alterações em múltiplos arquivos, escolhas de design |
xhigh | Nível máximo (depende do modelo) | Problemas realmente difíceis, onde a espera vale a pena |
Meu padrão é utilizar " gpt-5.5 + medium " para quase tudo, subindo manualmente para high apenas quando tenho certeza de que vou enfrentar um problema complexo. Como mencionei no capítulo 30, cometi o erro estúpido de travar o modelo em xhigh por muito tempo, esperando um minuto inteiro apenas para corrigir um erro de digitação. A produtividade recuperada ao evitar essa "ansiedade pelo poder máximo" é muito maior do que você imagina.
💡 Resumo em uma frase: use "flagship +
medium" para o dia a dia, reduza paraminimal/lowpara tarefas mecânicas e suba parahigh/xhighapenas para problemas complexos; não use nenhum modelo descontinuado.
07 Pontos de Entrada Cruciais para MCP / Subagentes / Skills
Estes três recursos são capacidades avançadas, cujos conceitos foram explicados em seus respectivos capítulos (capítulos 20, 21 e 22). Aqui fornecemos apenas os pontos de entrada sobre "qual comando/configuração utilizar", poupando você de ter que voltar para consultar. Analogia: Estas são as "maçanetas" de três portas — lembre-se de onde estão as maçanetas, e consulte os detalhes de como entrar nos respectivos capítulos.
| Recurso | Ponto de Entrada | Descrição |
|---|---|---|
| MCP (ferramentas externas, como portas USB) | codex mcp list / codex mcp add <name> ... | Gerencia servidores via linha de comando; use /mcp na sessão para ver ferramentas disponíveis (experimental) |
| MCP (login em servidor HTTP) | codex mcp login <name> | Suporta apenas servidores HTTP streamable compatíveis com OAuth |
| Configurar servidor MCP | Chave [mcp_servers.<id>] no config.toml | Chaves como command/args/url definem um servidor |
| Subagentes (trabalho paralelo) | Chave [agents] / agents.<name>.* no config.toml | max_threads padrão é 6; use /agent na sessão para alternar threads |
| Skills (habilidades específicas de tarefas) | Use /skills na sessão | Navegue e selecione; use [[skills.config]] (com path/enabled) no config.toml para sobrepor a ativação |
Note que o conjunto de comandos do codex mcp está marcado atualmente como "experimental", e seus subcomandos e comportamentos podem mudar com a versão; consulte codex mcp --help antes de usar.
💡 Resumo em uma frase: gerencie MCP através do comando
codex mcp, controle subagentes com a configuração[agents]+ alternância via/agent, e use/skillspara selecionar Skills — lembre-se desses três pontos de entrada e você não ficará perdido ao começar a usar recursos avançados.
08 Prática: Verifique se os Comandos Consultados Funcionam na Prática
Não importa quão completa seja sua folha de dicas, nada supera executar um comando para garantir que ele realmente funciona em seu ambiente local. Abaixo está o menor exemplo viável, que não depende de nenhum projeto existente e requer apenas três passos.
Passo 1: Confirme o status do login (puramente para consulta, sem alterar nada):
codex login statusSaída esperada: Se estiver logado, imprimirá o método de autenticação atual, com código de saída 0; se não estiver logado, solicitará que você faça codex login.
Passo 2: Execute um comando não interativo que grave o resultado em um arquivo — validando simultaneamente codex exec, -o e o sandbox apenas de leitura (read-only):
codex exec --sandbox read-only -o /tmp/codex-check.txt "用一句话说明当前目录是不是一个 Git 仓库"Expectativa: O terminal imprimirá essa frase, enquanto a mesma frase será gravada em /tmp/codex-check.txt (no Windows, altere para o seu diretório temporário). Abrir o arquivo e conseguir ver o conteúdo prova que o -o funcionou.
Passo 3: Confirme que os nomes das flags consultadas estão corretos — perguntando diretamente à própria CLI:
codex exec --helpExpectativa: Lista todas as flags suportadas pelo codex exec. Sempre que você não tiver certeza sobre a existência de uma flag ou de como ela é chamada, o --help será a referência mais atualizada e precisa disponível.
💡 Resumo em uma frase:
login statusvalida o login,codex exec -ovalida que o comando realmente realiza o trabalho, e--helpvalida que os nomes das flags estão corretos — a execução bem-sucedida dessas três etapas garante que a folha de dicas está "ativa" para seu ambiente local.
Resumo
Este capítulo não introduziu novos conceitos, mas consolidou a "experiência prática" dos mais de trinta capítulos anteriores em sete tabelas:
- Kit de inicialização em três etapas: Instalação,
codex logine confirmação comcodex login status; executecodex doctorprimeiro se houver problemas. - Comandos e flags da CLI: Subcomandos definem "para onde ir", flags definem "como ir"; o quinteto de alta frequência é composto por
-m/-s/-a/-o/--json. - Comandos com barra: Pratique
/model,/status,/compacte/diffna sessão até virarem memória muscular. config.toml: Definamodel,model_reasoning_effort,sandbox_modeeapproval_policypara configurar a personalidade padrão.- Sandbox de permissões: "
workspace-write+on-request" para ambiente local, " sandbox especificado +never" para CI; conceda permissões adicionais preferindo--add-dir. - Modelos e esforço de raciocínio: Use a combinação flagship
gpt-5.5+mediumpara tudo; não use modelos descontinuados. - Pontos de entrada avançados: MCP via comandos
codex mcp, subagentes controlados por[agents]e Skills selecionadas via/skills.
Agora você deve conseguir: Descartar aquele arquivo txt de lembretes bagunçado; para qualquer comando, chave de configuração ou nível de sandbox, basta bater o olho nesta página e seguir em frente, usando o --help para tirar qualquer dúvida rápida sem precisar abrir o navegador para vasculhar a documentação.
O próximo capítulo 〔36 Melhores Práticas〕 concluirá toda a seção do Codex. A folha de dicas resolve o problema de "não lembrar", enquanto as melhores práticas abordam o "usar corretamente" — o mesmo comando codex exec pode ser usado por alguém para criar um pipeline automatizado fluido, ou por outro para bagunçar completamente o repositório de código. Fica a reflexão: Dos comandos que você tem em mãos, quais você usa diariamente sem nunca ter pensado se existe uma forma mais estável de utilizá-los? No próximo capítulo, dissecaremos cada um desses pontos comuns que usamos no dia a dia sem refletir a fundo.