Guia avançado do config.toml do Codex

Este guia explica as configurações do Codex CLI que afetam modelos, Provider, permissões, sessões salvas e uso de tokens em ~/.codex/config.toml.

O comportamento foi verificado no Codex CLI 0.146.0. Como o Codex evolui rapidamente, execute novamente a validação estrita após cada atualização. Para a primeira instalação, consulte Configuração do Codex.

Não grave API Keys ou Bearer Tokens diretamente no config.toml, no repositório, na documentação ou no histórico do shell.

Configuração com prioridade para qualidade

Esta base é adequada para uma máquina pessoal de desenvolvimento em que qualidade importa mais do que a menor latência possível.

model_provider = "icodeeasy"
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"
cli_auth_credentials_store = "file"

approval_policy = "on-request"
sandbox_mode = "danger-full-access"
personality = "pragmatic"
web_search = "live"

[model_providers.icodeeasy]
name = "I Code Easy"
base_url = "https://api.icodeeasy.cc"
wire_api = "responses"
requires_openai_auth = true

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

Deixe o Codex gerar e gerenciar ~/.codex/auth.json. Use a variável de ambiente somente para a importação única via entrada padrão:

read -s OPENAI_API_KEY
printf '\n'
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY
codex login status

Se o domínio principal estiver lento na sua rede, use https://jp.icodeeasy.cc ou https://sg.icodeeasy.cc em base_url. Não altere o ID do Provider.

Local e precedência da configuração

O arquivo do usuário fica normalmente em ~/.codex/config.toml. A precedência é:

1. opções da CLI e sobrescritas -c / --config;
2. .codex/config.toml de um projeto confiável;
3. Profile selecionado em ~/.codex/<name>.config.toml;
4. configuração do usuário;
5. configuração do sistema;
6. valores padrão do Codex.

Para uma alteração temporária:

codex -c 'model_reasoning_effort="xhigh"'

As chaves TOML de nível superior devem aparecer antes da primeira tabela:

model = "gpt-5.6-sol"
web_search = "live"

[model_providers.icodeeasy]
name = "I Code Easy"

Depois do cabeçalho de uma tabela, as chaves seguintes pertencem a ela até a próxima tabela.

Modelo e intensidade de raciocínio

model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"

model é o identificador enviado ao Provider ativo. Um nome disponível no seletor não garante que o Provider implemente todos os recursos. Valide geração de texto, chamadas de ferramentas, término do streaming e usage, não apenas o status HTTP 200.

Os níveis disponíveis dependem do modelo. Use max ou ultra somente quando o catálogo do modelo e o Provider confirmarem suporte. plan_mode_reasoning_effort afeta apenas o modo Plan. Evite definir model_context_window manualmente sem verificar o limite real no Provider ativo.

ID do Provider, nome exibido e Base URL

model_provider = "icodeeasy"

[model_providers.icodeeasy]
name = "I Code Easy"
base_url = "https://api.icodeeasy.cc"
wire_api = "responses"
requires_openai_auth = true

Alterar name = "OpenAI" para name = "I Code Easy" apenas melhora a clareza do status. Não muda qualidade, velocidade, autenticação, cache, cobrança ou sessões anteriores.

Já icodeeasy é um ID persistido nos metadados da sessão. Se ele for removido ou renomeado, uma sessão antiga pode continuar visível, mas falhar ao ser retomada:

failed to load configuration: Model provider `icodeeasy` not found

Ao criar um novo ID, mantenha a definição antiga como alias de compatibilidade. Não é necessário editar os arquivos JSONL ou o banco de estado do Codex.

Autenticação, permissões e aprovação

Com requires_openai_auth = true, o Codex usa seu armazenamento de autenticação OpenAI. No modo de API Key, este site recomenda credenciais em arquivo:

cli_auth_credentials_store = "file"

As credenciais ficam em ~/.codex/auth.json. Não crie ou edite o JSON manualmente, nem mantenha a API Key em .bashrc, .zshrc ou em uma variável de usuário do Windows. Use o mesmo fluxo para a primeira configuração e para trocar a chave:

read -s OPENAI_API_KEY
printf '\n'
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY
codex login status

config.toml controla modelo, Provider, Base URL, permissões e ferramentas; auth.json contém a API Key ou as credenciais do ChatGPT. Trate auth.json como uma senha. No Linux/macOS, execute chmod 600 ~/.codex/config.toml ~/.codex/auth.json e nunca envie o arquivo ao Git, compartilhe ou faça backup público. Entre novamente para trocar a chave ou use codex logout para removê-la.

O arquivo é mais consistente que uma variável permanente entre shells, tmux, IDEs e processos em segundo plano. Isso melhora a descoberta da credencial, não a rede do gateway, limites ou compatibilidade de modelos. Alterar o armazenamento não oculta sessões antigas; o Provider ID e o estado local da Session continuam determinando a retomada.

Account: API key configured (run codex login to use ChatGPT)

Essa mensagem não é um erro; ela informa que a sessão usa API Key em vez de login do ChatGPT.

approval_policy = "on-request"
sandbox_mode = "danger-full-access"

sandbox_mode controla o alcance técnico dos comandos. approval_policy controla quando o Codex pode pedir confirmação.

Uma máquina dedicada não torna automaticamente confiáveis repositórios novos, scripts de dependências, páginas web, hooks ou resultados de MCP. Use codex -s workspace-write para uma restrição temporária.

Confiança do projeto, Web Search e MCP

[projects."/absolute/path/to/repository"]
trust_level = "trusted"

Projetos confiáveis podem carregar .codex/config.toml, hooks e rules. Isso não muda o sandbox automaticamente para danger-full-access.

web_search = "live"

Os modos de Web Search são cached, indexed, live e disabled. live ajuda a consultar documentação atual, mas conteúdo web continua sendo uma entrada externa não confiável.

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"
enabled = true
required = false
startup_timeout_sec = 10
tool_timeout_sec = 60

Use required = true somente quando o trabalho não puder continuar sem esse MCP, pois uma falha de inicialização pode impedir a criação ou retomada de uma thread.

Profiles para velocidade e segurança

# ~/.codex/quick.config.toml
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"

codex --profile quick

# ~/.codex/readonly.config.toml
approval_policy = "never"
sandbox_mode = "read-only"
web_search = "cached"

codex --profile readonly

Mantenha no arquivo principal valores que afetam a compatibilidade de sessões, como o ID do Provider.

/status, tokens e Context Window

Model:              gpt-5.6-sol (reasoning xhigh, summaries auto)
Model provider:     I Code Easy - https://api.icodeeasy.cc
Permissions:        Custom (danger-full-access, Ask for approval)
Account:            API key configured
Token usage:        708K total (679K input + 28.9K output)
Context window:     51% left (132K used / 258K)
Limits:             not available for this account

Confira o destino real pela URL, não apenas pelo nome do Provider. Limits: not available significa que o Codex não consegue ler os limites do ChatGPT com a autenticação atual; não significa uso ilimitado.

Uma sessão longa envia novamente o contexto efetivo a cada turno, portanto a entrada acumulada pode ser maior que a Context Window. No Codex 0.146.0:

displayed input = input_tokens - cached_input_tokens
displayed total = displayed input + output_tokens

Tokens de reasoning já fazem parte de output e não devem ser somados novamente. Entrada em cache continua sendo entrada; a cobrança depende do serviço ativo.

132K used / 258K aparece como 51% left porque esta versão subtrai uma base fixa de cerca de 12K do uso e da capacidade antes de estimar a parte controlável pelo usuário.

Use /compact no fim de uma fase ou quando faltar contexto. Use /new para um trabalho sem relação com a sessão atual.

Retomar sessões

codex resume <session-id>
codex resume --last
codex resume --all

O seletor padrão e --last consideram o diretório atual; --all procura entre diretórios. Retomar restaura mensagens e metadados, não processos encerrados. Arquivos, Git e serviços externos mantêm seu estado real atual.

Campos inválidos e validação estrita

Não mantenha estes campos antigos em uma configuração do Codex 0.146.0:

disable_response_storage = true
preferred_auth_method = "apikey"

A inicialização normal pode ignorar campos desconhecidos. Nesta versão, requisições Responses que não usam Azure já enviam store = false; disable_response_storage não controla isso.

Linux / macOS:

codex --strict-config mcp-server </dev/null
codex doctor --summary --ascii

PowerShell:

"" | codex --strict-config mcp-server
codex doctor --summary --ascii

O primeiro comando rejeita chaves desconhecidas e termina após EOF. O segundo verifica instalação, autenticação, MCP, estado local e conexão com o Provider. No TUI, use /status e /debug-config para confirmar a configuração efetiva.

Referências

• Codex Authentication
• Codex Configuration Reference
• Codex Advanced Configuration
• Codex CLI command reference

Página verificada com o Codex CLI 0.146.0 e a documentação oficial da OpenAI em 2026-08-03.