Governança do OpenAI Codex: Controles que um Desenvolvedor Não Pode Desativar

Por que agentes de codificação são um problema de governança à parte

Todas as outras cargas de trabalho de AI executam na infraestrutura que você possui — seu cluster, sua política de rede, uma credencial que você pode rotacionar. O Codex é um processo de CLI no laptop do desenvolvedor que lê um arquivo TOML em seu diretório home e se comunica diretamente com um provedor de modelo. Cinco propriedades o tornam uma classe diferente de problema:

A reação comum é criar um documento de política. Ele falha por uma razão: tudo o que ele exige reside em um arquivo que o desenvolvedor pode editar.

O que “governado” realmente precisa significar

Quatro propriedades precisam ser mantidas em cada requisição:

• Identidade. A requisição carrega o desenvolvedor individual, não uma chave de equipe. Uma chave compartilhada faz com que todos os controles a jusante — limites de taxa (rate limits), orçamentos, permissões, auditoria — se resolvam em um único principal sem significado.
• Controle de modelo. Quais modelos um desenvolvedor pode acessar é uma decisão de segurança e custo. Os preços diferem em ordens de grandeza entre os níveis (tiers); os termos de tratamento de dados diferem entre os provedores.
• Atribuição de custos. Por desenvolvedor, por equipe, por repositório — a linha de gastos surpresa usual assim que trinta engenheiros adotam um agente (preços de agentes de codificação de AI).
• Auditoria que o desenvolvedor não pode desativar. Logs atrás de uma flag local não são auditoria; são uma opção configurável.

Um gateway oferece as quatro propriedades — mas apenas se o cliente apontar para ele e continuar apontando para ele. Existem três posturas para isso, e apenas uma é a aplicação efetiva (enforcement):

Bloquear o arquivo sem rotacionar o token trata a adulteração, mas ignora o roubo de credenciais; rotacionar sem bloquear faz o oposto. Você precisa de ambos.

Onde as equipes erram

Tratar a conta do provedor do modelo como o ponto de controle. Identidade, SSO, associação ao workspace e políticas do console administrativo do Codex vivem no console da OpenAI, não no seu gateway — assim como a retenção de prompts e respostas, que “é governada pelo seu contrato com a OpenAI”. Um gateway controla roteamento, gastos, guardrails e seus próprios logs, não o seu contrato com o provedor.

Assumir que uma aplicação via MDM equivale a uma governança permanente. Clientes alteram a precedência de configuração entre versões. O Codex v0.149.0 deixou de suportar o managed_config.toml no Windows completamente — ele agora ignora o arquivo exibindo um aviso na inicialização (Ignoring deprecated managed config file), sem nenhum equivalente no registro do Windows. Uma frota configurada antes dessa versão fica desprotegida e não reporta erros.

Distribuir uma chave de API compartilhada. É a maneira mais rápida de colocar trinta desenvolvedores para trabalhar, mas destrói todos os controles a jusante de uma só vez. Você não consegue aplicar limites de taxa por pessoa nem responder “quem enviou aquele prompt” a partir de uma credencial corporativa única.

Quer ver como é o tráfego governado de um agente de codificação na prática?

Aponte uma instalação do Codex para o gateway e analise o rastreamento (trace).

Comece gratuitamente

Como isso funciona no TrueFoundry

O Codex trata o TrueFoundry AI Gateway como um provedor de modelos; todo o resto decorre do fato de o tráfego chegar a um local sob seu controle. Os detalhes do gateway vêm do trecho de código exibido na interface de usuário.

Modo de autenticação 1 — Chave de API

A forma para um único desenvolvedor: o token vai no cabeçalho Authorization e o gateway o resolve para uma pessoa.

model = "gpt-5.2-codex"
model_provider = "truefoundry"

[model_providers.truefoundry]
name = "TrueFoundry AI Gateway"
base_url = "{GATEWAY_BASE_URL}"
wire_api = "responses"

[model_providers.truefoundry.http_headers]
Authorization = "Bearer TFY_API_KEY"

Modo de autenticação 2 — ChatGPT Business/Enterprise

A assinatura do ChatGPT do próprio desenvolvedor paga pela inferência e o gateway continua governando o tráfego. Duas coisas mudam: exige requires_openai_auth = true e a credencial do TrueFoundry passa de Authorization para x-tfy-api-key, porque o Codex precisa do cabeçalho Authorization para seu próprio token OAuth do ChatGPT.

model = "gpt-5.2-codex"
model_provider = "truefoundry"

[model_providers.truefoundry]
name = "TrueFoundry AI Gateway"
base_url = "{GATEWAY_BASE_URL}"
wire_api = "responses"
requires_openai_auth = true

[model_providers.truefoundry.http_headers]
x-tfy-api-key = "TFY_API_KEY"

No lado do gateway, crie um provedor em Integrations → Providers do tipo OpenAI, URL base https://chatgpt.com/backend-api/codex, e deixe o campo da chave de API em branco.

O campo em branco é um sinal proposital, não um esquecimento. Se houver uma chave salva, o gateway a utilizará em vez das credenciais do ChatGPT do desenvolvedor — quebrando o fluxo da assinatura e possivelmente roteando o tráfego pela conta errada. Um administrador que "gentilmente" preencher esse campo converterá trinta desenvolvedores rastreáveis individualmente em uma única conta anônima via API key, sem gerar nenhum erro no sistema.

Deixando em branco, você obtém atribuição dupla: o TrueFoundry registra o desenvolvedor a partir da x-tfy-api-key, e a OpenAI atribui o uso à licença do ChatGPT dele. Os IDs dos modelos ficam no formato chatgpt-codex/gpt-5.2-codex.

Duas restrições decorrem do fato de a credencial estar vinculada a uma conta individual do ChatGPT. Apenas um dos destinos de um modelo virtual pode ser uma conta de modelo com assinatura do ChatGPT; destinos baseados em chaves de API podem coexistir ao lado dele. Além disso, erros 401, 403 ou 429 específicos de um desenvolvedor não colocam o destino compartilhado em período de espera (cooldown) no balanceador de carga, de modo que a cota esgotada de um usuário não afeta os demais.

(A documentação diverge sobre quais planos são elegíveis: a página de segurança empresarial menciona Business ou Enterprise, enquanto a página da CLI também lista Personal. [VERIFY] antes de prometer o suporte a determinado nível.)

Por que wire_api = "responses" é obrigatório

Esta é a linha que as equipes copiam errado e passam a tarde tentando depurar. O gateway adiciona o endpoint /responses apenas para o protocolo Responses. Se você definir wire_api = "chat", a requisição será enviada para /chat/completions na mesma URL base, que não é um endpoint válido para o tráfego do Codex. Isso também é o que faz os tokens de raciocínio (thinking tokens) do gpt-5.x-codex funcionarem corretamente.

A documentação da CLI do Codex apresenta isso de forma mais flexível — responses para gpt-5.x-codex, chat para outros modelos. No entanto, elas se alinham: para modelos da família Codex, a API Responses é obrigatória.

Slugs de Modelo Virtual devem corresponder ao ID real do modelo

O Codex envia tokens de raciocínio para certos modelos e os identifica combinando a string do modelo. Nomes totalmente qualificados — openai-main/gpt-5, azure-openai/gpt-5 — não correspondem, fazendo com que a detecção de recursos falhe.

A regra é: use um slug que corresponda exatamente ao ID do modelo real, ex: gpt-5.2-codex. O Codex reconhece esses IDs e ativa os recursos corretos. Não coloque o nome totalmente qualificado na configuração do Codex.

Os slugs são únicos em toda a organização (tenant) e definidos nas configurações do Grupo de Provedores do Modelo Virtual. Tanto o slug quanto o caminho completo do grupo/modelo funcionam no corpo da requisição; o Codex necessita do formato por slug.

Por trás de um único slug, você pode ponderar os destinos — openai-main/gpt-5 com peso 70, azure-openai/gpt-5 com peso 30 — e alterar a distribuição sem tocar em nenhum laptop, como em descontinuação de modelos e transições graduais.

A nomenclatura dos slugs é onde os clientes diferem drasticamente. O Cursor escolhe o formato da requisição a partir de palavras-chave no slug e altera o formato silenciosamente se o slug contiver anthropic, claude, openai, gpt, gemini ou vertex. O Codex exige o ID do modelo no slug; o Cursor quer essas palavras-chave fora do slug.

Aplicação na frota via MDM

Uma configuração individual por desenvolvedor é apenas uma configuração documentada, não um controle. A aplicação em frota usa o tfy-local-ai-setup, um binário distribuído pelo seu MDM e executado como root (Administrador no Windows) em uma frequência recomendada de uma hora, obtido em github.com/truefoundry/tfy-local-ai-setup/releases; os scripts do Codex fixam a versão RELEASE_TAG="v1.3.5". Cada execução realiza quatro etapas:

1. Salva ou carrega a configuração de um arquivo pertencente ao root — macOS /Library/Preferences/com.truefoundry.tfy-local-ai-setup.conf, Linux /etc/tfy/tfy-local-ai-setup.conf, Windows C:\ProgramData\TrueFoundry\tfy-local-ai-setup.conf (macOS: chown root:wheel, chmod 644).
2. Instala ou atualiza o binário, ignorando a etapa se a tag instalada for igual a RELEASE_TAG.
3. Detecta o usuário conectado e renova o token silenciosamente a partir de ~/.tf/refresh-token.
4. Escreve e bloqueia a configuração gerenciada — chflags schg no macOS, chattr +i no Linux, e uma ACL icacls no diretório do Windows.

A terceira etapa é a mais importante. O laptop nunca armazena um token de gateway de longa duração: o token de renovação (refresh token) é válido por 30 dias a partir da última emissão, cada execução bem-sucedida o rotaciona, e a credencial na configuração gerenciada é obtida recentemente e limitada à identidade daquele usuário.

Configurações obrigatórias: GATEWAY_URL, CONTROL_PLANE_URL, TENANT_NAME. Opcionais: CODEX_GATEWAY_URL, CODEX_AUTH_MODE, CODEX_DEFAULT_MODEL, CODEX_SETTINGS_FILE. CODEX_AUTH_MODE="api-key" é o padrão; "chatgpt-subscription" faz com que o binário escreva requires_openai_auth = true e mova o token para x-tfy-api-key. Máquinas sem o Codex instalado não sofrem alterações — o binário detecta a ausência, encerra a execução e não gera erros.

As cadeias de precedência, e por que o Windows é diferente

No macOS e Linux, o arquivo do administrador tem prioridade e é reaplicado a cada inicialização:

/etc/codex/managed_config.toml → ~/.codex/config.toml → Flags de CLI

model_provider = "truefoundry"
model = "gpt-5.2-codex"

[model_providers.truefoundry]
name     = "TrueFoundry Gateway"
base_url = "https://<your-truefoundry-gateway-url>"
wire_api = "responses"

[model_providers.truefoundry.http_headers]
Authorization = "Bearer <freshly-fetched-tfy-token>"

A chave de modelo de nível superior é gravada apenas quando CODEX_DEFAULT_MODEL está definido; se estiver desmarcada, a escolha do modelo permanece com o desenvolvedor enquanto o provedor continua sendo imposto.

No Windows, o arquivo, a ordem e o esquema mudam completamente.

C:\ProgramData\OpenAI\Codex\requirements.toml → ~/.codex/config.toml → Flags de CLI → C:\ProgramData\OpenAI\Codex\config.toml

Observe a última posição: o arquivo config.toml no Windows é a configuração padrão da máquina com a menor precedência entre as quatro, portanto, o arquivo do próprio desenvolvedor se sobrepõe a ele. O arquivo requirements.toml se sobrepõe a tudo. O bloco do provedor é idêntico ao do macOS, mas a fixação do modelo não é:

# C:\ProgramData\OpenAI\Codex\requirements.toml
model_provider = "truefoundry"
# ... mesmos blocos [model_providers.truefoundry] e http_headers ...

[models.new_thread]
model = "gpt-5.2-codex"

O esquema do requirements.toml não possui uma chave de modelo no nível superior. O CODEX_DEFAULT_MODEL deve ficar sob [models.new_thread]. Se você copiar o bloco do macOS para o Windows sem alterações, a fixação do modelo simplesmente não funcionará, sem emitir alertas.

Dois números de versão determinam se esse controle funciona no Windows. A versão v0.149.0 removeu o suporte ao managed_config.toml no sistema. A versão v0.156.0 é a mínima exigida para a aplicação das políticas — o Codex só respeita o model_provider no requirements.toml a partir dessa compilação; versões anteriores utilizam o config.toml de menor precedência, que pode ser sobrescrito pelo desenvolvedor a partir de seu diretório home. Verifique o resultado de codex --version antes de considerar a frota Windows protegida. O gerenciamento do Codex no Windows através do binário de instalação foi introduzido no tfy-local-ai-setup v1.3.5.

O bloqueio transforma o arquivo em um controle efetivo:

No macOS, /etc/codex/ tem permissão root:wheel 755 e o arquivo é root:wheel 644 com a flag schg — o próprio root precisa executar chflags noschg para editá-lo.

O aviso sobre as ACLs do Windows merece destaque. O diretório C:\ProgramData\OpenAI\Codex\ deve pertencer ao grupo Administrators, com a herança de permissões desativada: SYSTEM e Admins com controle total, Users apenas com permissão de leitura; ambos os arquivos TOML devem ter SYSTEM com controle total, Admins com leitura e Users com leitura. O motivo é claro — a pasta ProgramData permite que qualquer usuário autenticado crie diretórios, e o Codex carrega qualquer configuração encontrada ali em vez de rejeitar arquivos graváveis por usuários comuns. Não flexibilize essa ACL; um diretório com permissões abertas transforma uma configuração imposta em uma mera sugestão, de forma silenciosa.

Governança da busca na web

O Codex acessa a web pública de duas maneiras. A busca hospedada pelo provedor envia a ferramenta web_search da Responses API, inclusive em modelos suportados no AWS Bedrock Mantle — é rápida, mas o comportamento varia por provedor e não é uma chamada de ferramenta que você controla. A busca na web via MCP — Tavily ou Exa atrás do TrueFoundry MCP Gateway — é recomendada pela consistência, porque as ferramentas MCP executam no lado do cliente no processo do Codex, independentemente de qual modelo o gateway roteia.

[mcp_servers.web-search]
url = "https://<gateway>/<tenant>/mcp/<mcp-server-name>/server"
http_headers = { Authorization = "Bearer TFY_API_KEY" }

Use bearer_token_env_var = "TFY_API_KEY" em vez de incluir o token diretamente no texto. Para desativar a busca hospedada pelo provedor, defina web_search = "disabled" em ~/.codex/config.toml — isso desativa apenas o caminho do provedor; o servidor MCP continuará funcionando até que você remova o bloco [mcp_servers.<name>]. Registrar a busca como um servidor MCP é o que permite governar esse tráfego de ferramentas através do controle de acesso do MCP gateway.

Auditoria e custos

Como cada completamento passa pelo gateway, o registro é gerado independentemente da vontade do desenvolvedor — cada requisição é salva em Request Traces com o usuário identificado, o modelo servido, a quantidade de tokens e a latência.

Acima disso, o painel de métricas consolida os dados de toda a frota: custos e volume por usuário, equipe e modelo.

Todos os clientes de codificação conectados ao gateway aparecem na mesma visualização — fornecendo uma visão única de custos em vez de dados fragmentados, como abordado em centralização do controle de custos em IDEs de codificação com AI.

Exemplo prático de implementação

Cenário: duzentos engenheiros usando macOS e Windows com ChatGPT Enterprise já contratado. Os desenvolvedores mantêm o Codex; a equipe de segurança obtém rastreabilidade; o financeiro recebe os relatórios de custos por equipe.

1. Crie o provedor. Acesse Integrations → Providers → OpenAI, defina a URL base para https://chatgpt.com/backend-api/codex e mantenha o campo de chave de API vazio — documente essa instrução no seu guia operacional para evitar que outro administrador tente "corrigir" o campo.

2. Crie o Modelo Virtual. Defina o slug como gpt-5.2-codex — utilizando o ID real do modelo em vez do nome qualificado. Configure um destino principal associado à assinatura do ChatGPT e inclua destinos baseados em chave de API como reserva (failover).

3. Configure as variáveis do MDM. Defina GATEWAY_URL, CONTROL_PLANE_URL, TENANT_NAME, além de CODEX_AUTH_MODE="chatgpt-subscription" e CODEX_DEFAULT_MODEL="gpt-5.2-codex".

4. Execute o script de hora em hora como root. O script instalará o tfy-local-ai-setup v1.3.5, atualizará o token de cada usuário, criará o managed_config.toml no macOS ou o requirements.toml no Windows e aplicará o bloqueio em ambos.

5. Valide a versão do Windows antes de liberar. Qualquer versão abaixo da v0.156.0 não aplicará as regras; verifique a distribuição de versões na sua frota antes de confirmar a cobertura de segurança.

6. Valide a configuração. Execute ls -lO para verificar a flag schg no macOS, lsattr para verificar a flag i no Linux, ou icacls para confirmar que Administrators é o proprietário e Users tem apenas permissão Users:(RX) no Windows. Em seguida, acesse Request Traces e confirme que o nome do desenvolvedor aparece associado à requisição em vez de uma conta de serviço.

7. Restrinja a busca na web sem controle. Registre os serviços Tavily ou Exa atrás do MCP Gateway e defina web_search = "disabled".

Limitação importante: estas etapas garantem a governança sobre o provedor do modelo, a autenticação e os custos. Elas não restringem quais servidores MCP locais um desenvolvedor pode ativar por conta própria.

Pronto para colocar seus agentes de codificação sob um único ponto de controle?

Roteie uma instalação do Codex através do gateway e acompanhe a chegada do primeiro rastreamento.

Comece grátis

Detalhes técnicos importantes

O script de MDM não gerencia servidores MCP. Ele é responsável por gerenciar o arquivo managed_config.toml, cobrindo as configurações de autenticação e do provedor do modelo. As restrições do Codex sobre quais servidores MCP um desenvolvedor pode ativar são mantidas em um arquivo separado localizados em /etc/codex/requirements.toml no macOS e Linux, o qual não é editado pelo tfy-local-ai-setup. Implante esse arquivo em conjunto com o script — e não informe à auditoria que a automação de MDM cobre a lista de permissões (allowlist) do MCP.

Dois scripts de MDM, um arquivo de configuração, versões fixadas diferentes. Os scripts do Codex fixam o tfy-local-ai-setup na versão v1.3.5, enquanto os scripts do Claude Code utilizam a versão v1.3.4. Ambos os agentes compartilham o mesmo arquivo de configuração no sistema; caso uma máquina execute os dois scripts, ela reinstalará uma versão diferente a cada hora — lembrando que o suporte ao Codex no Windows só está presente a partir da v1.3.5. [VERIFY] a versão fixada antes de ativar ambos os scripts simultaneamente.

Divergência de versões de modelos na documentação. A página oficial do Codex menciona o GPT-5.3-Codex, enquanto os exemplos de configuração, as instruções de slug e os padrões do MDM continuam utilizando gpt-5.2-codex. Defina explicitamente a versão desejada na variável CODEX_DEFAULT_MODEL e [VERIFY] o ID do modelo atual antes de realizar a implantação.

O Cursor não pode ser governado da mesma maneira. As políticas de MDM do Cursor cobrem hooks, mas não os modelos: a URL base, a chave de API e a lista de modelos não são gerenciáveis via MDM, permitindo que o desenvolvedor altere essas opções a qualquer momento. A CLI do Copilot também não possui um caminho em settings.json para uso de chaves próprias (BYOK). O Codex e o Claude Code são as duas ferramentas que mantêm a aplicação efetiva das regras — o artigo sobre segurança no Cursor explica como cobrir essa lacuna.

Leituras relacionadas

• Governança do Claude Code com um AI Gateway — o mesmo desafio aplicado ao outro principal agente de codificação
• Centralização do Controle de Custos para IDEs de AI — uma visão unificada de custos para Codex, Cursor e Claude Code
• Preços de Agentes de Codificação de AI — os custos reais por desenvolvedor ao utilizar agentes de codificação
• Segurança no Cursor — onde terminam os limites da aplicação de regras no lado do cliente
• O que é um MCP Gateway — como governar chamadas de ferramentas e não apenas completamentos de texto

Conclusão

A maioria das orientações sobre a governança do OpenAI Codex limita-se a recomendar o roteamento por um proxy. Essa é a parte simples do processo. A parte complexa é garantir que o roteamento permaneça ativo em uma frota real: lidar com um campo de chave de API vazio que parece um erro mas é proposital, aplicar um protocolo de comunicação obrigatório, configurar slugs que devem corresponder exatamente ao ID do modelo, ajustar arquivos de configuração no Windows com esquemas próprios, respeitar a versão mínima abaixo da qual o controle falha silenciosamente e manter as permissões de acesso (ACL) configuradas corretamente.

Essas exigências não são meras recomendações de documentos de política. São parâmetros de configuração técnicos que podem ser verificados diretamente via linha de comando. Essa é a diferença entre um documento de governança e uma frota efetivamente governada: a capacidade de inspecionar qualquer máquina com comandos como ls -lO ou icacls e obter uma validação imediata do status de segurança.

Governe seus agentes de codificação no TrueFoundry

Gratuito para começar