Adoção de Codex em equipes: guia de decisão para permissões, convenções e a rota Bedrock

Quando uma equipe começa a usar Codex em conjunto, a primeira pergunta de segurança e operações quase nunca é “qual plano devemos comprar?”. Normalmente é “quem tem full access, o que .env pode ler e onde vemos uso e logs de auditoria?”. Essas perguntas decidem o primeiro passo da adoção. A resposta não é escolher a API key primeiro. A resposta é definir primeiro a fronteira de permissões. Este artigo traz um framework de decisão para adoção corporativa: configurar requirements.toml e permission profiles para limitar permissões por membro, padronizar as regras compartilhadas de AGENTS.md, escolher uma rota de deploy como ChatGPT workspace, API Key ou Amazon Bedrock e, por fim, conectar analytics e compliance. Também vale deixar claro um fato desde o início: a AWS anunciou a disponibilidade do GPT-5.4 em GovCloud em 2026-06-03, mas o provedor do Codex para Bedrock ainda não suporta endpoints de GovCloud. São dois fatos diferentes, não um só.

1. Estrutura empresarial de permissões: não deixe full access morar em toda máquina local

Quando uma empresa quer padronizar o Codex, pode usar cloud-managed requirements para restringir o comportamento local. requirements.toml é o arquivo de políticas do Codex. Administradores podem aplicar políticas diferentes por grupo de usuários, em vez de deixar cada membro configurar seu próprio ambiente.

1.1 Campos principais em requirements.toml

Estes são os campos mais usados quando esse rollout acontece:

Campo	Finalidade	Valor recomendado
approval_policy	Controla se é necessária aprovação humana	"suggest" ou "auto-edit"; não use "never" como padrão da equipe
approvals_reviewer	Define o aprovador	O owner da equipe ou o responsável por segurança
automatic_review_policy	Regras de revisão automática	Defina conforme o nível de risco do projeto
permission profiles	Modelo de permissões mais novo (0.138.0+)	Recomendado para novos deploys
sandbox_mode	Modelo de permissões anterior	Use só em migrações legadas
web_search_mode	Se a busca na web é permitida	Opcional, mas deve ser restrito em projetos sensíveis
managed_hooks	Configuração unificada de hooks	lint-check, test-runner e similares
MCP servers allowlist	Quais servidores MCP podem ser usados	Apenas filesystem, github e outros aprovados

O Codex 0.138.0 e posteriores recomendam permission profiles com allowed_permission_profiles e default_permissions. Deploys antigos ainda podem usar allowed_sandbox_modes.

1.2 Combinações proibidas

A combinação abaixo não deve ser usada como padrão da equipe:

danger-full-access + approval_policy = "never"

É a combinação de maior privilégio e sem aprovação. Ela deve ser bloqueada nos requisitos gerenciados na nuvem para não aparecer em configurações locais individuais.

1.3 Exemplo de configuração

# requirements.toml
[managed]
approval_policy = "suggest"
allowed_permission_profiles = ["suggest", "auto-edit"]
default_permissions = "suggest"

[mcp]
allowed_servers = ["filesystem", "github"]

[hooks]
managed_hooks = ["lint-check", "test-runner"]

Este exemplo limita os membros a "suggest" ou "auto-edit", deixa "suggest" como padrão, permite apenas filesystem e github para MCP e mantém o conjunto de hooks consistente. Se você quer dar "auto-edit" a um grupo central de desenvolvimento e deixar "suggest" para perfis mais restritos, este é o lugar certo.

2. Menor privilégio e desenho de sandbox: regras concretas, deny glob e proteção de arquivos sensíveis

Responsáveis por segurança não precisam de um slogan sobre “menor privilégio”. Eles precisam de regras concretas: quais arquivos podem ser lidos, quais podem ser escritos e quais estão totalmente proibidos.

2.1 Três valores de filesystem

As permissões de filesystem do Codex aceitam três valores:

• read: somente leitura, sem edição
• write: leitura e escrita, mudanças permitidas
• deny: acesso totalmente bloqueado

A regra de precedência é simples: a regra mais específica vence, e deny tem a prioridade mais alta. Por exemplo, se você configurar "**/*.env" = "deny" e ":workspace_roots" = "write" ao mesmo tempo, os arquivos .env continuam bloqueados mesmo com a raiz do workspace gravável.

2.2 Limites de escopo do workspace

Use :workspace_roots para limitar a área de trabalho. Exemplo:

[permissions.filesystem]
":workspace_roots" = "write"

Isso permite que o Codex opere apenas dentro da raiz atual do workspace e seus filhos. Ele não sai desse escopo.

2.3 Proteção de arquivos sensíveis

Você pode usar deny globs para manter arquivos de ambiente e diretórios secretos fora de alcance:

[permissions.filesystem]
":workspace_roots" = "write"
"**/*.env" = "deny"
"**/secrets/**" = "deny"
"**/*.log" = "read"

Isso significa:

• a raiz do workspace e seus filhos são graváveis
• todos os arquivos .env ficam bloqueados em qualquer lugar da árvore
• diretórios secrets/ e seus filhos ficam bloqueados
• arquivos .log ficam em somente leitura

2.4 Permissões de rede

As permissões de rede podem ser ativadas e controladas por listas allow/deny por domínio:

[permissions.network]
enabled = true
allow = ["github.com", "api.openai.com"]
deny = ["localhost", "127.0.0.1"]

Isso libera acesso a github.com e api.openai.com, e bloqueia localhost e loopback. Há proteção adicional para redes locais ou privadas, então equipes também podem definir políticas de domínio próprias.

2.5 permission profiles versus sandbox mode

Comparação	Permission profiles	Sandbox mode
Etapa de lançamento	Modelo mais novo	Modelo legado
Granularidade	Mais fina	Mais grossa
Campos de configuração	allowed_permission_profiles + default_permissions	allowed_sandbox_modes
Recomendação	Preferido para novos deploys	Principalmente para migração legada

Novos deploys devem preferir permission profiles. Sandbox mode pode ser removido gradualmente.

3. Convenções compartilhadas da equipe: um AGENTS.md só, não um arquivo para cada pessoa

Equipes precisam de um prompt compartilhado, regras de contexto compartilhadas e instruções de review compartilhadas. Não precisam de cada pessoa manter sua própria versão e transformar a manutenção em um quebra-cabeça. AGENTS.md é o arquivo de instruções do Codex e suporta regras em camadas com prioridade.

3.1 Ordem da cadeia de instruções

Quando o Codex inicia, ele monta esta cadeia de instruções:

global rules (~/.config/codex/AGENTS.md)
  -> project rules (project AGENTS.md)
  -> nearest-to-current-directory rules

O arquivo mais próximo vence quando houver sobreposição.

3.2 Arquitetura em camadas

Não coloque tudo em um arquivo gigante. Divida em camadas:

• ~/.config/codex/AGENTS.md: regras globais, estilo, expectativa de testes e proibições gerais
• AGENTS.md do projeto: arquitetura, dependências, estilo de deploy
• AGENTS.md do módulo: necessidades específicas do módulo

Cada camada deve ficar em torno de 10-15 KiB para continuar gerenciável e evitar truncamento.

3.3 Como lidar com o limite de 32 KiB

O Codex define project_doc_max_bytes em 32 KiB. Se AGENTS.md crescer demais, ele pode ser truncado.

Há duas formas de resolver:

1. aumentar project_doc_max_bytes
2. dividir o documento em diretórios aninhados

A segunda costuma ser melhor porque deixa claro quem mantém cada parte.

3.4 Para que serve AGENTS.override.md

AGENTS.override.md serve para sobrescrever o AGENTS.md acima e tem a maior prioridade. Use quando:

• um subdiretório específico precisa de regra temporária diferente
• um módulo experimental precisa de limites mais flexíveis
• um módulo diverge da política geral do projeto

Registre o motivo do override para não confundir a equipe.

3.5 Recomendação de manutenção

Ao manter AGENTS.md, deixe explícito:

• Ownership: quem mantém cada camada
• Maintenance budget: quanto tempo de revisão cada sprint recebe
• Review cycle: se as regras globais são revisadas trimestralmente e as do projeto mensalmente

Assim, AGENTS.md vira uma referência compartilhada viva, não um arquivo privado que cada um reescreve.

4. Escolha de deploy: como decidir entre ChatGPT workspace, API Key e Bedrock

Organizações precisam escolher qual rota de conta vão adotar. As três opções têm forças, limites e encaixes diferentes.

4.1 Tabela comparativa

Dimensão	ChatGPT Business/Enterprise	API Key	Amazon Bedrock
Autenticação	Login do ChatGPT	OPENAI_API_KEY	Bedrock API key ou AWS IAM
Titular da cobrança	Workspace da OpenAI	Conta de API da OpenAI	Conta da AWS
Governança de equipe	Analytics Dashboard, managed requirements	Sem governança nativa de equipe	AWS IAM e CloudTrail
Completude de recursos	A mais completa	A mais flexível	Conjunto parcial de recursos (ver 4.2)
Compliance / região	Regiões da OpenAI	Regiões da OpenAI	Regiões da AWS e residência de dados
Suporte a GovCloud	Não	Não	O modelo pode estar disponível, mas o suporte do provedor do Codex é separado (ver 4.3)
Melhor encaixe	Equipes pequenas ou médias que precisam de gestão de workspace	Desenvolvedores que querem integração flexível	Equipes centradas em AWS que precisam de cobrança, IAM e controles de compliance

4.2 Capacidades ausentes no Bedrock

Em 2026-06-08, as seguintes capacidades não estão disponíveis nessa rota:

• Fast Mode
• hosted web/file search
• computer use
• shell tool
• image generation tool
• remote MCP servers
• on-demand inference only não é suportado; use Provisioned Throughput

Essas capacidades dependem de serviços hospedados pela OpenAI, ferramentas hospedadas ou descoberta gerenciada na nuvem, então ficam fora dessa rota. Se sua equipe depende delas, use ChatGPT workspace ou API Key.

4.3 Esclarecimento sobre GovCloud

Há dois fatos distintos:

1. GPT-5.4 no AWS GovCloud (US-West) está disponível

   • o modelo está disponível em GovCloud
   • GPT-5.4 pode ser chamado via API do Bedrock

2. O provedor do Codex para Bedrock não suporta endpoints de GovCloud

   • o provedor amazon-bedrock do Codex não suporta hoje endpoints do Bedrock Mantle em regiões AWS GovCloud
   • você não pode configurar o Codex contra Bedrock no GovCloud hoje

Não escreva “Codex no Bedrock suporta GovCloud” como se fosse o mesmo fato.

4.4 Cenários de uso

Escolha a rota conforme a organização:

ChatGPT Business/Enterprise

• equipes pequenas e médias
• querem administração de workspace
• querem o conjunto mais completo de recursos
• não precisam de cobrança AWS nem IAM

API Key

• desenvolvedores que querem integração flexível
• sem necessidade de governança de equipe
• pagam diretamente em uma conta de API da OpenAI
• não precisam de administração de compliance

Amazon Bedrock

• equipes centradas em AWS com contas, IAM e cobrança já existentes
• querem agrupar custos sob compromissos AWS
• precisam de residência de dados ou regiões AWS específicas
• aceitam um conjunto parcial de recursos (ver 4.2)

5. Configuração e limites do Bedrock: autenticação nativa da AWS, recursos faltando e risco de GovCloud

As equipes que escolhem Bedrock precisam entender a configuração exata, o método de autenticação, as capacidades que faltam e o limite do GovCloud.

5.1 Configurando o provedor amazon-bedrock

Configure o provedor no arquivo do Codex:

{
  "provider": "amazon-bedrock",
  "aws_region": "us-east-1",
  "model_id": "openai.gpt-5.5"
}

O ID do modelo e a região devem seguir a documentação oficial.

5.2 Autenticação nativa da AWS

A rota Bedrock usa autenticação nativa da AWS, não OPENAI_API_KEY:

• Bedrock API key: chave temporária, no máximo 12 horas ou duração da sessão, herda permissões do principal IAM
• Credenciais AWS IAM: configuradas por role IAM ou usuário IAM

Para produção, são recomendadas chaves temporárias ou roles IAM. Chaves de longa duração servem só para exploração.

5.3 Regiões comerciais da AWS compatíveis

A documentação oficial atualmente suporta estas regiões comerciais da AWS:

• us-east-1
• us-west-2
• eu-west-1
• ap-northeast-1

Consulte a documentação de AWS Bedrock OpenAI models para a lista atual.

5.4 Governança de chaves Bedrock

Regras de governança para chaves Bedrock:

• Short-term key: até 12 horas ou a duração da sessão, herda permissões do principal IAM, recomendada para produção
• Long-term key: apenas para exploração, não recomendada para produção
• CloudTrail logging: chamadas de API são registradas no AWS CloudTrail; a chave não é armazenada em texto puro
• IAM actions control: ações IAM podem controlar quem cria e usa chaves de API

5.5 Lista repetida de capacidades ausentes

Em 2026-06-08, as seguintes não estão disponíveis no Bedrock:

• Fast Mode
• hosted web/file search
• computer use
• shell tool
• image generation tool
• remote MCP servers
• on-demand inference only não é suportado; use Provisioned Throughput

Se a equipe depende dessas funções, mude para ChatGPT workspace ou API Key.

5.6 Risco de GovCloud (repetição)

De novo, separe estes dois fatos:

• GPT-5.4 da AWS está disponível no GovCloud (US-West): o modelo está disponível em GovCloud
• O provedor do Codex para Bedrock não suporta endpoints de GovCloud: você não pode configurar o Codex contra Bedrock em regiões AWS GovCloud hoje

Se sua equipe precisa de GovCloud, não assuma que o Codex já pode apontar para lá.

6. Governança e auditoria: onde ver uso e logs de compliance

Gestores precisam acompanhar adoção, uso e impacto de code review, e para isso precisam de analytics e auditoria.

6.1 Comparação das três rotas de governança

Rota	Capacidade	Atraso	Melhor para
Analytics Dashboard	adoção, uso, feedback de code review	Os dados podem atrasar até 12 horas	Acompanhamento de rollout
Analytics API	buckets diários/semanais, uso por workspace/usuário, detalhamento por cliente, métricas de Code Review	De quase tempo real até algumas horas	Governança de custos e análise profunda
Compliance API	exporta atividade do Codex e metadados de auditoria	Depende da integração com SIEM/eDiscovery	Auditoria de compliance

6.2 Cenários de uso

6.2.1 Acompanhamento do rollout

Use o Analytics Dashboard para ver adoção e uso da equipe:

• taxa de ativação de membros
• qualidade do feedback de code review
• distribuição de uso por cliente

Os dados do dashboard podem atrasar até 12 horas, então servem melhor para relatórios semanais ou mensais do que para monitoramento em tempo real.

6.2.2 Governança de custos

Use a Analytics API para análise mais profunda:

• separe o uso por workspace/usuário/modelo
• compare buckets diários e semanais
• detalhe por cliente (Codex App/CLI/IDE/Cloud)
• resuma métricas de Code Review

Essa é a rota correta para governança interna de custos e otimização.

6.2.3 Auditoria de compliance

Use a Compliance API para exportar registros:

• atividade do Codex
• metadados de auditoria
• integração com SIEM/eDiscovery
• suporte a revisão de compliance

É a via certa para organizações reguladas como finanças, governo e saúde.

6.3 Recomendação de rota de governança

• Analytics Dashboard: melhor para responsáveis técnicos e project managers que acompanham rollout
• Analytics API: melhor para platform engineers que fazem governança de custos e análise profunda
• Compliance API: melhor para equipes de segurança e compliance que integram SIEM e eDiscovery

As três rotas podem ser combinadas conforme a necessidade da organização.

7. Rota de rollout da equipe: do piloto individual à governança organizacional

Muitas equipes não sabem por onde começar, como dividir a adoção ou como escolher a primeira leva de tarefas piloto.

7.1 Framework de rollout em três etapas

Etapa 1: controle individual (definir a fronteira de permissões)

Objetivo: garantir que a fronteira de permissões de cada membro seja controlável para que arquivos sensíveis não se espalhem por máquinas locais.

Ações principais:

• proibir danger-full-access + approval_policy = "never" como padrão da equipe
• proteger .env e secrets/ com deny globs
• usar :workspace_roots para limitar a área de trabalho

Critério de sucesso: nenhum membro acessa arquivos sensíveis sem aprovação.

Etapa 2: piloto de equipe pequena (convenções compartilhadas + tarefas de baixo risco)

Objetivo: unificar AGENTS.md e skills dentro da equipe pequena e então começar com tarefas de baixo risco para verificar se o fluxo funciona.

Ações principais:

• escrever um AGENTS.md global (estilo e expectativas de testes)
• escrever um AGENTS.md do projeto (arquitetura, dependências, deploy)
• escolher tarefas de baixo risco como geração de documentação, correções de lint e adições de testes
• evitar automatizar diretamente deploy de produção ou lógica de pagamento

Critério de sucesso: a maioria da equipe usa o AGENTS.md compartilhado e não há incidentes de segurança importantes.

Etapa 3: governança organizacional (managed requirements + Analytics/Compliance API)

Objetivo: elevar permissões e convenções para governança organizacional e conectar observabilidade e auditoria.

Ações principais:

• configurar requisitos gerenciados por grupo de usuários
• conectar Analytics Dashboard/API para acompanhar adoção e uso
• conectar Compliance API ao SIEM
• revisar periodicamente permission profiles e allowlists de MCP

Critério de sucesso: o painel de governança está online e os logs de auditoria são rastreáveis.

7.2 Tarefas piloto sugeridas

Priorize primeiro as tarefas de baixo risco

Boas tarefas para a primeira leva de pilotos:

• geração de documentação: README, docs de API, limpeza de notas
• correções de lint: eslint, prettier, automação de formatação
• adições de teste: testes unitários e esqueletos de integração
• sugestões de refatoração: melhorias de estrutura com revisão humana

Evite automação direta

Más tarefas para a primeira leva de pilotos:

• deploy de produção
• lógica de pagamento
• mudanças de permissões
• exclusão de dados

Essas tarefas são de alto risco e devem esperar a governança e a auditoria amadurecerem.

7.3 Relação com o restante da série

Este artigo é a página de decisão para adoção em equipe; os próximos podem aprofundar:

• estilo de escrita de AGENTS.md: como escrever regras em camadas, evitar truncamento e manter tudo
• bloqueios pessoais e sandboxes: problemas de permissão, configuração de sandbox e erros comuns
• integração Cloud/GitHub: desenvolvimento remoto, GitHub review, cloud tasks
• otimização de custos e quota: habilidades para reduzir tokens e controlar orçamento
• automação e tarefas longas: gatilhos agendados, heartbeats e jobs de vários dias

Resumo e próximos passos

Se você é responsável técnico e está fazendo o rollout do Codex em uma equipe, a ordem deveria ser:

1. Leia primeiro a configuração de permissões (seções 1 e 2) para bloquear combinações perigosas
2. Padronize as convenções depois (seção 3) para que o AGENTS.md tenha uma forma compartilhada
3. Escolha a rota de deploy depois (seções 4 e 5) para decidir entre workspace, API Key e Bedrock
4. Conecte a governança por último (seção 6) por meio de Analytics e Compliance APIs

Depois você pode seguir para módulos mais específicos:

• estilo de escrita de AGENTS.md: como escrever regras em camadas, evitar truncamento e manter tudo
• bloqueios pessoais e sandboxes: problemas de permissão, configuração de sandbox e erros comuns
• integração Cloud/GitHub: desenvolvimento remoto, GitHub review, cloud tasks
• otimização de custos e quota: habilidades para reduzir tokens e controlar orçamento
• automação e tarefas longas: gatilhos agendados, heartbeats e jobs de vários dias

Conceitos básicos relacionados:

• fundamentos de colaboração Git em equipe: Git flow, estratégia de branches e fluxo de code review
• segredos de CI e segurança de permissões: segredos do GitHub Actions, limites de permissão e práticas de segurança