Como configurar o Codex config.toml: API personalizada, proxy e erros comuns

O Codex mantém as configurações em um único arquivo, config.toml: qual modelo usar, qual API chamar e quanto o agente pode fazer sem perguntar. O formato mudou várias vezes em 2026, e muitos guias publicados no início do ano mostram configurações que agora impedem o Codex de iniciar.

Este guia começa com uma configuração funcional e, em seguida, aborda os elementos que a maioria das pessoas altera: perfis, configurações do projeto, o sandbox e um proxy. No final, há uma lista dos erros que você provavelmente verá e o significado de cada um. Verificado com base na documentação da OpenAI e testado no Codex CLI 0.162.1 em 19 de outubro de 2026. Os exemplos usam AIHubMix como provedor; qualquer gateway compatível com a Responses API da OpenAI funciona da mesma forma.

Em resumo

• O arquivo fica em ~/.codex/config.toml ou, no Windows, em C:\Users\<you>\.codex\config.toml.
• Um provedor personalizado precisa de base_url, wire_api = "responses" e env_key. A chave da API deve ficar em uma variável de ambiente.
• Os perfis agora são arquivos separados, ~/.codex/<name>.config.toml, selecionados com --profile <name>.
• O arquivo .codex/config.toml de um repositório só funciona em projetos confiáveis e não pode alterar o provedor.
• Reinicie o Codex após cada edição: ele só lê o arquivo ao iniciar.

Onde fica o config.toml

Suas configurações principais ficam em ~/.codex/config.toml. Tanto a CLI quanto a extensão para IDE leem esse arquivo. Se ele ainda não existir, crie-o.

Dois outros locais podem acrescentar configurações:

• Arquivos de perfil, ~/.codex/<name>.config.toml, usados somente ao iniciar o Codex com --profile <name>.
• Arquivos do projeto, .codex/config.toml dentro de um repositório, para compartilhar as configurações que a equipe quiser.

Se você executar o Codex no WSL2 no Windows, ele lerá o diretório pessoal do Linux (/home/<you>/.codex/config.toml), não o do Windows. Se CODEX_HOME estiver definido, o Codex usará essa pasta em vez de ~/.codex.

Uma configuração mínima funcional

Este arquivo completo ~/.codex/config.toml encaminha as solicitações do Codex para o AIHubMix:

model = "gpt-6-sol"
model_provider = "aihubmix"
model_reasoning_effort = "high"

[model_providers.aihubmix]
name = "AIHubMix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"

• model é o ID do modelo a ser chamado, e model_reasoning_effort define o nível de raciocínio padrão.
• model_provider deve corresponder ao nome em [model_providers.<name>]. Não use openai, ollama ou lmstudio; esses nomes são reservados para os provedores integrados do Codex.
• base_url é o endereço da API do provedor. wire_api = "responses" é o único valor aceito pelo Codex atualmente.
• env_key é o nome de uma variável de ambiente, não a própria chave.

Em seguida, defina essa variável usando uma chave do console do AIHubMix:

# macOS / Linux: add this line to ~/.zshrc or ~/.bashrc, then open a new terminal
export AIHUBMIX_API_KEY=sk-...

# Windows PowerShell: takes effect in new terminals
setx AIHUBMIX_API_KEY "sk-..."

Inicie codex em um novo terminal e faça qualquer pergunta. Se ele responder, o provedor está funcionando. Não importa se você está conectado ao Codex: a chave de codex login nunca é enviada a um provedor personalizado.

Perfis: um arquivo para cada configuração

Um perfil contém apenas as configurações diferentes das da configuração principal, como um raciocínio mais aprofundado e um sandbox somente leitura para revisar código. Cada perfil é um arquivo próprio, ao lado de config.toml, com as chaves no nível superior:

# ~/.codex/review.config.toml
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"

codex --profile review

Isso mudou no Codex 0.134.0. Guias antigos colocavam os perfis dentro de config.toml, em tabelas [profiles.review], e selecionavam um com profile = "review". Agora, o Codex se recusa a iniciar com esse seletor. Se uma tabela [profiles.review] antiga permanecer sozinha, ela será ignorada sem nenhuma mensagem, e as configurações deixarão silenciosamente de funcionar. Para migrar, mova as chaves de cada tabela para ~/.codex/<name>.config.toml e, em seguida, exclua a tabela e a linha profile = .... Veja mais detalhes no guia de configuração avançada da OpenAI.

Configuração do projeto: .codex/config.toml

Um arquivo .codex/config.toml em um repositório permite que a equipe compartilhe um modelo padrão, um nível de raciocínio ou um modo de sandbox. O Codex só o lê em projetos marcados como confiáveis no seu próprio ~/.codex/config.toml:

[projects."/Users/you/code/my-app"]
trust_level = "trusted"

Um arquivo de projeto não pode alterar o destino das solicitações. O Codex ignora model_provider, model_providers, openai_base_url, profile, notify e algumas outras chaves nesse arquivo, e exibe um aviso ao fazê-lo. Mantenha seu provedor em ~/.codex/config.toml. Um projeto ainda pode escolher o modelo; a solicitação será enviada ao seu próprio provedor.

Qual configuração prevalece

Quando a mesma chave está definida em mais de um lugar, a seção Noções básicas de configuração da OpenAI apresenta esta ordem, da maior para a menor prioridade:

1. Opções de linha de comando, incluindo substituições com -c
2. O .codex/config.toml do projeto
3. O perfil selecionado com --profile
4. Seu ~/.codex/config.toml
5. A configuração do sistema, /etc/codex/config.toml
6. Os padrões integrados do Codex

Observe que o arquivo do projeto tem prioridade sobre um perfil. Se uma configuração do perfil parecer não fazer efeito, verifique se o .codex/config.toml do repositório define a mesma chave.

Para alterar uma configuração apenas em uma execução, use -c:

codex -c model_reasoning_effort=high

Sandbox e aprovações

Duas chaves controlam o que o Codex faz por conta própria. sandbox_mode define o que os comandos podem acessar, e approval_policy define quando ele para para pedir sua aprovação.

sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true   # off by default

As duas configurações são independentes: never interrompe as perguntas, mas não flexibiliza o sandbox. Em workspace-write, os comandos não podem acessar a rede até que você defina network_access = true.

Por trás de um proxy

O Codex não tem uma configuração de proxy em config.toml. Ele usa as variáveis de ambiente padrão:

export HTTPS_PROXY=http://127.0.0.1:7890   # your proxy address
export NO_PROXY=localhost,127.0.0.1

A documentação da OpenAI não menciona essas variáveis, então elas foram testadas no Codex 0.162.1: as solicitações, inclusive as enviadas a um provedor personalizado, passaram por HTTPS_PROXY (ou ALL_PROXY), e os hosts em NO_PROXY foram acessados diretamente. Arquivos PAC não são compatíveis; informe o próprio endereço do proxy. Se o proxy da sua empresa usar seu próprio certificado raiz, defina CODEX_CA_CERTIFICATE para apontar para ele, conforme descrito na referência de variáveis de ambiente.

Mais modelos em /model

O seletor /model mostra apenas os modelos da OpenAI. Para escolher modelos GLM, Claude, Gemini ou DeepSeek por ele, adicione um catálogo de modelos: um arquivo JSON indicado pela chave de nível superior model_catalog_json. Coloque essa chave antes da primeira linha [table], ou o TOML a considerará parte dessa tabela e o Codex a ignorará.

O catálogo substitui a lista integrada, e cada entrada exige vários campos. Por isso, é melhor gerá-lo em vez de escrevê-lo manualmente. O guia do AIHubMix para o Codex CLI inclui um script que cria um catálogo com base nos 30 principais modelos do AIHubMix. O aplicativo para desktop ainda pode ocultar modelos personalizados no seletor (openai/codex#19694), então alterne entre os modelos no terminal.

Erros comuns e o que significam

Estas são as mensagens exibidas pelo Codex 0.162.1 para cada erro.

legacy profile = "..." config is no longer supported
Seu config.toml ainda contém a linha antiga profile = "...". Mova o perfil para um arquivo próprio, conforme descrito acima. Executar --profile x enquanto ainda existe uma tabela antiga [profiles.x] gera um erro semelhante: --profile x cannot be used while ... contains legacy ... config.

wire_api = "chat" is no longer supported
O Codex não é mais compatível com a Chat Completions API. Altere para wire_api = "responses". Um provedor que ofereça apenas Chat Completions não funcionará sem um proxy de conversão.

model_providers contains reserved built-in provider IDs
Você deu ao provedor o nome openai, ollama ou lmstudio. Renomeie a tabela e altere model_provider para outro nome.

approval_policy = "untrusted" is no longer supported
Remova a linha ou use on-request.

Missing environment variable: AIHUBMIX_API_KEY
A variável indicada em env_key não está definida no terminal que iniciou o Codex. Abra um novo terminal ou execute source ~/.zshrc e inicie o Codex novamente.

401 Unauthorized após algumas linhas de "Reconnecting..."
A solicitação foi enviada sem uma chave. Verifique se a tabela do provedor contém env_key. O login armazenado em auth.json não é válido para provedores personalizados.

Model metadata for ... not found. Defaulting to fallback metadata
O Codex não tem configurações integradas para esse modelo, o que é normal para modelos que não são da OpenAI. As solicitações ainda funcionam. Adicione um catálogo de modelos se quiser configurações adequadas e que o modelo apareça em /model.

Ignored unsupported project-local config keys
O arquivo .codex/config.toml de um repositório define uma chave que só funciona na sua própria configuração, geralmente model_provider. Mova-a para ~/.codex/config.toml.

missing field base_instructions
Está faltando um campo obrigatório em uma entrada do seu catálogo de modelos, então o Codex rejeita o arquivo inteiro. Gere o catálogo novamente com o script em vez de editá-lo manualmente.

Quando uma configuração não entra em vigor

• Reinicie o Codex após editar.
• Verifique se as chaves de nível superior vêm antes da primeira linha [table].
• Verifique o arquivo .codex/config.toml do repositório; ele tem prioridade sobre seu perfil.
• Procure por uma tabela [profiles.x] antiga que tenha sobrado.
• Execute codex doctor, que verifica a instalação, as configurações e o login.

Se quiser usar modelos da OpenAI, Anthropic, Google, Zhipu, DeepSeek e outros no Codex com uma única chave, o AIHubMix os disponibiliza pela Responses API em https://aihubmix.com/v1. Comece com a configuração mínima acima e adicione um catálogo de modelos quando quiser alternar entre modelos pelo /model.

Perguntas frequentes

Onde fica o arquivo config.toml do Codex?
Em ~/.codex/config.toml no macOS e no Linux, e em C:\Users<you>.codex\config.toml no Windows. Se CODEX_HOME estiver definido, o arquivo ficará nessa pasta.

Preciso reiniciar o Codex depois de alterar o config.toml?
Sim. O Codex lê o arquivo ao iniciar, então feche e reabra a sessão do terminal ou o aplicativo.

Por que o Codex diz “a configuração de perfil legada não é mais compatível”?
O Codex 0.134.0 deixou de aceitar perfis definidos dentro de config.toml. Mova cada perfil para ~/.codex/name.config.toml, exclua as linhas antigas e inicie o Codex com --profile name.

Ainda posso usar wire_api = "chat"?
Não. O Codex aceita apenas wire_api = "responses". Um provedor compatível apenas com Chat Completions precisa de um proxy que faça a conversão para a Responses API.

Por que meu provedor personalizado retorna 401 mesmo quando estou conectado ao Codex?
A chave de login em auth.json não é enviada aos provedores personalizados. Adicione env_key à tabela do provedor e defina essa variável no terminal.

O Codex usa HTTPS_PROXY?
Sim. Em um teste com o Codex 0.162.1, as solicitações passaram por HTTPS_PROXY e ignoraram os hosts listados em NO_PROXY. Arquivos PAC não são compatíveis.

Por que model_provider é ignorado no .codex/config.toml do meu projeto?
Os arquivos do projeto não podem alterar o destino das solicitações, então um repositório não pode redirecionar seu tráfego. Defina o provedor em ~/.codex/config.toml; o arquivo do projeto ainda pode definir o modelo.

Fontes

• Noções básicas de configuração, OpenAI
• Configuração avançada, OpenAI
• Referência de configuração, OpenAI
• Guia de integração do Codex CLI, AIHubMix
• Configuração de proxy do Codex CLI: SOCKS, HTTP e redes corporativas, Daniel Vaughan