Como usar o Codex da OpenAI com LiteLLM na AWS: guia completo

Por que isso importa agora

Agentes de codificação como o Codex da OpenAI já ajudam times a entender repositórios, escrever código, rodar testes e concluir tarefas de engenharia com múltiplas etapas. O que mudou em 2026 é a passagem do experimento individual para a adoção gerenciada: empresas agora precisam de uma forma consistente de controlar o acesso ao modelo, atribuir o consumo por time e aplicar orçamentos e limites de taxa — sem abrir mão de observar todo o caminho da requisição.

Este guia mostra como implantar um gateway LiteLLM operado pelo próprio cliente na AWS, conectar o Codex a um modelo da OpenAI no Amazon Bedrock e validar o contrato completo da API Responses.

O que você ganha (e o que não ganha)

✅ Vantagens

• Um único ponto de controle para autenticação, roteamento, orçamentos e telemetria.
• Aliases de modelo estáveis: o desenvolvedor usa um nome fixo, e o time de infraestrutura troca o modelo no Bedrock por trás.
• Chaves por usuário, time ou workload, com limites rígidos de orçamento e de tokens/requisições por minuto.
• Roteamento centralizado com política de fallback e registro de identidade no gateway.
• Infraestrutura 100% dentro da sua conta AWS (VPC, RDS, KMS, Secrets Manager, CloudWatch).

⚠️ O que você NÃO ganha

• O gateway não substitui as aprovações locais do Codex nem vira um shell de uso geral na conta AWS.
• Você passa a operar disponibilidade, ciclo de vida do banco, upgrades e resposta a incidentes do gateway.
• Não substitui salvaguardas de IA responsável na camada do modelo (como o Amazon Bedrock Guardrails).

Requisitos

Passo a passo

1. Clone o repositório e prepare o ambiente

git clone https://github.com/openai-on-aws/guidance-codex.git
cd guidance-codex
git checkout feat/enterprise-gateway-readiness
cp deployment/litellm/.env.deploy.example deployment/litellm/.env.deploy

O arquivo .env.deploy real é ignorado pelo Git. Nele, defina perfil, regiões, CIDR de origem e DNS/certificado. Configurações de produção incluem ENABLE_TLS=true, ENABLE_WAF=true e contagens mínima/máxima de tarefas.

2. Checagem, build e planejamento

make litellm-check     # pré-voo read-only: CLI, identidade, CIDR, TLS
CONFIRM_AWS_WRITE=1 make litellm-build   # build da imagem e push ao ECR
make litellm-plan      # cria change set sem executar

O build usa uma imagem-base LiteLLM com digest fixo e grava o digest no ECR — o CloudFormation recebe o digest imutável, não uma tag mutável.

3. Deploy e verificação

CONFIRM_AWS_WRITE=1 make litellm-deploy
make litellm-status

O serviço ECS usa rollback por circuit-breaker e health checks do Application Load Balancer. Mantenha as tarefas ECS e o RDS em sub-redes privadas; não exponha as portas 4000 (tarefa) nem 5432 (PostgreSQL) publicamente.

4. Crie uma identidade de gateway com escopo

Não distribua a master key do LiteLLM. Provisione uma chave por desenvolvedor ou time, com orçamento e limites:

CODEX_API_SECRET_ID=codex-litellm-gateway/alice-key
[email protected]
CODEX_KEY_MAX_BUDGET=50
CODEX_KEY_BUDGET_DURATION=30d
CODEX_KEY_TPM_LIMIT=100000
CODEX_KEY_RPM_LIMIT=1000
CONFIRM_AWS_WRITE=1 make litellm-provision-key

O helper grava a chave gerada diretamente em um segredo criptografado com KMS no Secrets Manager — sem expor credenciais em argumentos de comando ou no terminal.

5. Configure o Codex

make litellm-codex-config

O comando imprime o bloco de provider. Adicione ao ~/.codex/config.toml (o Codex ignora essas configurações no .codex/ do projeto). O token é buscado em tempo de execução por um script auxiliar que lê o segredo via perfil AWS — nunca fica salvo em texto no config.toml.

6. Teste ponta a ponta

codex exec --sandbox read-only --ephemeral \
  "Reply with exactly LITELLM_GATEWAY_OK and no other text."

Depois, exercite o loop de agente com uma tarefa que exige inferência e ferramenta local, e confirme nos logs do LiteLLM que as requisições têm status de sucesso, o alias correto e custo/tokens preenchidos.

7. Valide o contrato da API Responses

make litellm-validate

Um texto de sucesso não prova compatibilidade de agente. O probe estrito verifica os campos obrigatórios do objeto Responses, a continuação semântica com previous_response_id, o streaming server-sent e a chamada forçada de função com ID.

Comparativo de caminhos de acesso

Casos de uso reais

• Onboarding por equipe: cada squad recebe uma chave com orçamento mensal e limite de tokens/minuto.
• Troca de modelo sem fricção: o alias gpt-5.5 permanece estável enquanto o Bedrock mapping muda por trás.
• Atribuição de custo: telemetria por chave permite cobrar o consumo interno por centro de custo.
• Conformidade: prompts e respostas tratados como dados sensíveis, com redação e retenção definidas.
• Fallback centralizado: política de roteamento com fallback entre provedores em caso de falha.

Troubleshooting

• ❌ 403 antes de qualquer linha no log: provável bloqueio de rede ou AWS WAF upstream. Revise CIDRs e regras do WAF.
• ❌ 401: autenticação do gateway ausente ou inválida. Confira o comando de auth e o secret-id.
• ❌ Continuação não preserva contexto: gateway aceita previous_response_id mas não guarda o estado. Rode make litellm-validate para detectar.
• ❌ Tarefa ECS instável no deploy: verifique health checks do ALB e o circuit-breaker de rollback.
• ❌ Chave excede orçamento e é rejeitada: comportamento esperado — use identidade descartável para validar a política, não apenas a aceitação dos parâmetros.

FAQ

• Preciso mesmo de um gateway? Não. Se IAM, CloudTrail e políticas nativas bastam, use o acesso direto ao Bedrock. O gateway só compensa quando há necessidade de política centralizada entre times ou provedores.
• O gateway substitui as aprovações do Codex? Não. O Codex continua executando ferramentas localmente sob seu sandbox e política de aprovação.
• Onde ficam as credenciais? A chave do gateway fica em um segredo KMS-encrypted no Secrets Manager; o Codex a busca em tempo de execução.
• Posso usar o modelo direto no Bedrock? Sim, via provider amazon-bedrock com aws sso login.
• Como limpar tudo? Use make litellm-cleanup-plan para revisar e make litellm-cleanup para excluir, confirmando o nome exato da stack.

O que vem por aí

À medida que os agentes de codificação saem do nicho de engenharia e alcançam outros fluxos profissionais, a capacidade de observar, atribuir e limitar o consumo se torna o pré-requisito real da adoção enterprise. Em 2027, a tendência é que o gateway deixe de ser uma peça opcional e vire o padrão em implantações corporativas de agentes — com controles de custo e governança tão importantes quanto o próprio desempenho do modelo.