Aprovações e segurança do agente

O Codex ajuda a proteger seu código e seus dados e reduz o risco de uso indevido.

Por padrão, o agente é executado com o acesso à rede desativado. Na execução local, o sistema operacional aplica as restrições do sandbox do Codex. Em geral, o agente só pode acessar o espaço de trabalho atual. Uma política de aprovação define quando o agente deve parar e pedir sua aprovação antes de agir.

Para entender como funciona o isolamento no aplicativo ChatGPT para desktop, na CLI do Codex e na extensão para IDE, consulte Ambiente isolado. Para uma visão mais ampla da segurança empresarial, consulte o documento técnico sobre segurança do Codex.

Migração da política de aprovação descontinuada untrusted

O Codex e o ChatGPT Work deixaram de oferecer suporte a approval_policy = "untrusted". Essa configuração pode impedir a inicialização de qualquer um dos dois clientes. Remova-a das configurações de usuário ou de projeto, dos arquivos de perfil, dos scripts de inicialização e das configurações padrão gerenciadas. Para uso interativo em modo somente leitura, use a seguinte configuração:

sandbox_mode = "read-only"
approval_policy = "on-request"

Ou execute codex --sandbox read-only --ask-for-approval on-request.

Com on-request, os comandos permitidos pelo sandbox podem ser executados sem aprovação, ler os arquivos acessíveis e usar a rede se o acesso estiver ativado.

Para manter a regra mais rigorosa de aprovação de comandos, omita a configuração explícita de approval_policy e adicione uma entrada para o projeto ao arquivo ~/.codex/config.toml do usuário:

[projects."/path/to/project"]
trust_level = "untrusted"

Assim, os comandos exigem aprovação, a menos que uma regra da política de execução os permita. Isso também desativa a configuração local do projeto. Definir on-request explicitamente substitui a política derivada do projeto. Para permitir a política derivada, a configuração gerenciada allowed_approval_policies deve incluir untrusted.

Sandbox e aprovações

O acesso ao computador local com o Work Cloud tem políticas distintas para execução local e na nuvem:

• Execução na nuvem: os contêineres do Work na nuvem usam as políticas existentes do Work Cloud.
• Execução local: os requisitos de execução local se aplicam ao computador conectado. Os requisitos de MDM e os requisitos legados de dispositivos gerenciados têm precedência sobre as configurações de segurança do agente. Estas, por sua vez, têm precedência sobre o arquivo de requisitos do sistema no dispositivo.

No modo Work com acesso local e nos dots, quando a política gerenciada está ativada, as configurações compatíveis da política Global se aplicam ao orquestrador compartilhado na nuvem. Os contêineres do Work na nuvem e os computadores dos dots na nuvem usam configurações e requisitos de execução próprios. Teste os controles locais e os da nuvem separadamente. Mantenha os controles do orquestrador, incluindo aprovações e pesquisa na Web, em Global. Quando disponíveis, use os controles Políticas de aprovação permitidas e Modos de pesquisa na Web permitidos. Use TOML para os demais campos compatíveis. Antes de aplicar um exemplo do Codex ao acesso ao computador local com o Work Cloud, confira a lista de campos e o escopo de execução na referência de configuração.

Alternar entre desktop, Web e dispositivos móveis não concede acesso a outro computador. Antes de ativar a sincronização ou ampliar o acesso, revise a configuração básica de segurança do agente e teste uma ação permitida e uma bloqueada em cada ambiente de execução. Consulte Configuração gerenciada.

Os controles de segurança do Codex combinam duas camadas:

• Modo do sandbox: define o que o Codex pode fazer ao executar comandos gerados pelo modelo, por exemplo, onde pode gravar arquivos e se pode acessar a rede.
• Política de aprovação: define quando o Codex deve pedir sua aprovação antes de executar uma ação, como sair do sandbox, usar a rede ou executar comandos fora de um conjunto confiável.

O Codex usa modos de sandbox diferentes conforme o ambiente de execução:

• Codex Cloud (legado): é executado em contêineres isolados gerenciados pela OpenAI, o que impede o acesso ao sistema do host ou a dados não relacionados. A execução tem duas fases. A preparação ocorre antes da fase do agente e pode acessar a rede para instalar as dependências especificadas. Em seguida, a fase do agente é executada offline por padrão, a menos que você ative o acesso à internet nesse ambiente. Os segredos configurados para ambientes de nuvem ficam disponíveis apenas durante a preparação e são removidos antes do início da fase do agente.
• Codex Cloud atual: consulte Variáveis de ambiente e segredos de rede para entender como as credenciais são tratadas durante a preparação e as tarefas.
• CLI do Codex / extensão para IDE: mecanismos do sistema operacional aplicam as políticas do sandbox. Por padrão, o acesso à rede fica desativado e as permissões de gravação se limitam ao espaço de trabalho ativo. Você pode configurar o sandbox, a política de aprovação e a rede de acordo com sua tolerância a riscos.

Na predefinição Auto (por exemplo, --sandbox workspace-write --ask-for-approval on-request), o Codex pode ler e editar arquivos e executar comandos automaticamente no diretório de trabalho.

O Codex pede aprovação para editar arquivos fora do espaço de trabalho ou executar comandos que exigem acesso à rede. Se quiser conversar ou planejar sem fazer alterações, mude para o modo read-only com o comando /permissions.

O Codex também pode pedir aprovação para chamadas de ferramentas de aplicativos (conectores) que declaram efeitos colaterais, mesmo quando a ação não envolve um comando de shell nem uma alteração de arquivo. Chamadas destrutivas a ferramentas de aplicativos ou MCP sempre exigem aprovação quando a ferramenta declara uma anotação de ação destrutiva, a menos que também declare uma anotação de leitura, que tem prioridade.

Monitoramento de segurança e tarefas pausadas

O GPT-6 Astra inclui monitoramento de segurança no Codex e no ChatGPT Work. O monitoramento é assíncrono e pode pausar uma tarefa se detectar um comportamento potencialmente inseguro do modelo. A pausa pode ocorrer depois da atividade que a motivou. O monitoramento não substitui o ambiente isolado, as permissões nem a revisão do resultado.

Se uma tarefa for pausada, leia o aviso e examine os resultados da análise quando estiverem disponíveis. Só retome a tarefa depois de verificar que ela pode continuar com segurança. Se o aviso informar que a tarefa foi encerrada ou não oferecer a opção de retomá-la, você não poderá retomá-la nessa interface.

O monitoramento de segurança avalia o comportamento do modelo durante a tarefa. A revisão automática de aprovações avalia, antes da execução, cada ação que já exige aprovação. Mesmo que a revisão automática aprove uma ação, o monitoramento ainda pode pausar a tarefa posteriormente.

Acesso à rede Elevated Risk

Para consultar as configurações de rede do Codex Cloud atual, veja Conectar a serviços. No Codex Cloud (legado), consulte Acesso do agente à internet para permitir acesso completo à internet ou restringi-lo a uma lista de domínios permitidos.

No aplicativo ChatGPT para desktop, na CLI do Codex e na extensão para IDE, o modo de sandbox padrão workspace-write mantém o acesso à rede desativado, a menos que você o ative na configuração:

[sandbox_workspace_write]
network_access = true

Isolamento de rede

Nas modalidades de execução gerenciada do Codex Cloud que oferecem suporte a esse controle, os requisitos de segurança do agente restringem o acesso dos comandos à rede. As configurações de internet do ambiente do Codex Cloud se aplicam separadamente. Permitir um domínio nas configurações de segurança do agente não anula uma restrição nas configurações de internet do ambiente de nuvem. Por si só, esses controles de rede para comandos não desativam a pesquisa na Web hospedada, os aplicativos nem o MCP. O ChatGPT Work Cloud tem permissões próprias para seus recursos e não herda esses requisitos de segurança do agente.

A lista gerenciada de permissões para comandos se aplica aos comandos que usam o proxy gerenciado. Se a política permitir a elevação completa de privilégios do sandbox e essa elevação for aprovada, o comando poderá ser executado sem passar pelo proxy. Uma permissão restrita de rede é diferente da elevação completa de privilégios do sandbox. Configure os requisitos obrigatórios de aprovação e de sandbox de acordo com o limite de segurança desejado e teste comandos com e sem elevação de privilégios. Consulte Configuração gerenciada.

O acesso à rede é controlado por regras de destino que se aplicam a scripts, programas e subprocessos iniciados por comandos. Quando o acesso dos comandos à rede já estiver ativado, ative o recurso network_proxy para restringir esse tráfego de acordo com a política de rede configurada. Adicionar regras de domínio, por si só, não ativa o proxy.

[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow", "example.com" = "deny" }

Para uma sessão avulsa da CLI, use a forma booleana abreviada se só precisar ativar ou desativar o recurso. Use a forma de tabela se também precisar definir opções da política:

codex \
  -c 'features.network_proxy=true' \
  -c 'sandbox_workspace_write.network_access=true'

codex \
  -c 'features.network_proxy.enabled=true' \
  -c 'features.network_proxy.domains={ "api.openai.com" = "allow", "example.com" = "deny" }' \
  -c 'sandbox_workspace_write.network_access=true'

O recurso muda a forma como o acesso à rede é controlado quando está ativado. Ele não concede acesso por si só. Use sandbox_workspace_write.network_access na configuração de workspace-write para definir se os comandos terão acesso à rede:

• Rede desativada + network_proxy ativado: a rede continua desativada e o recurso não tem efeito.
• Rede ativada + network_proxy desativado: a rede continua ativada, com acesso direto de saída sem restrições.
• Rede ativada + network_proxy ativado: a rede continua ativada e a política de rede configurada restringe o tráfego de saída.

O recurso de proxy também se aplica aos perfis de permissões. Em um perfil, network.enabled = true concede aos comandos acesso à rede e features.network_proxy = true ativa a aplicação das regras de domínio desse perfil:

default_permissions = "project-edit"

[features]
network_proxy = true

[permissions.project-edit]
extends = ":workspace"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"

Se você omitir o recurso de proxy neste exemplo, os comandos terão acesso direto à rede e a regra que permite api.openai.com não restringirá seus destinos.

Os requisitos de experimental_network gerenciados pelo administrador são independentes da opção que o usuário usa para ativar o recurso. Esses requisitos podem configurar e iniciar a comunicação de rede no sandbox sem features.network_proxy, mas não ativam o acesso à rede quando o sandbox em uso o mantém desativado. Consulte Configuração gerenciada para ver o formato do arquivo requirements.toml usado pelo administrador.

Política de rede

As regras de domínio partem de uma lista de destinos permitidos:

• Uma regra com nome de host exato corresponde apenas a esse host.
• *.example.com corresponde a subdomínios como api.example.com, mas não a example.com.
• **.example.com corresponde tanto ao domínio raiz quanto aos subdomínios.
• Uma regra de permissão global * corresponde a qualquer host público que não esteja bloqueado. Considere * uma permissão ampla de acesso à rede e prefira regras de escopo delimitado sempre que possível.
• deny sempre tem precedência sobre allow, e o curinga global * só é válido em regras de permissão.

Destinos locais e privados

Por padrão, allow_local_binding = false bloqueia destinos de loopback, de link local e de redes privadas:

• Exceções específicas: quando um comando precisar de um único destino local, adicione uma regra que permita o endereço IP local exato, em forma literal, ou localhost.
• Acesso mais amplo: defina allow_local_binding = true somente se quiser ampliar deliberadamente o acesso a destinos locais ou privados.
• Curingas: regras com curingas não contam como exceções locais explícitas.
• Endereços resolvidos: nomes de host que resolvem para IPs locais ou privados continuam bloqueados, mesmo quando correspondem à lista de permissões.

Proteção contra DNS rebinding

Antes de permitir um nome de host, o Codex faz o possível para verificar a resolução DNS e a classificação do endereço IP:

• Se a consulta falhar ou exceder o tempo limite, o acesso será bloqueado.
• Nomes de host que resolvem para endereços não públicos são bloqueados.
• A verificação reduz o risco de DNS rebinding, mas não o elimina. Para impedir totalmente esse ataque, seria necessário fixar os IPs resolvidos até a camada de transporte.

Se o seu modelo de ameaças incluir DNS malicioso, aplique controles de tráfego de saída também em uma camada inferior.

Configurações perigosas

Duas configurações ampliam deliberadamente o limite de confiança:

• dangerously_allow_non_loopback_proxy = true pode expor os endpoints de escuta do proxy fora da interface de loopback.
• dangerously_allow_all_unix_sockets = true ignora a lista de sockets Unix permitidos.

Use essas configurações somente em ambientes com controles rigorosos. Quando o proxy para sockets Unix está ativado, os endpoints de escuta permanecem restritos ao loopback mesmo que tenha sido solicitada a vinculação a outra interface. Assim, a rede do sandbox não serve de ponte para acesso remoto aos daemons locais.

network_proxy vem desativado por padrão. Ao ativá-lo, aplicam-se as seguintes configurações:

Tráfego fora do proxy de rede dos comandos

O proxy de rede filtra o tráfego de scripts, programas e processos filhos executados dentro do sandbox local de comandos. Ele não filtra pesquisas na Web, chamadas de ferramentas de aplicativos ou conectores, conexões com servidores MCP, atividades do navegador ou do Uso do computador, tarefas do Codex na nuvem nem solicitações de modelo e autenticação do cliente. Esses recursos usam conexões de serviço, configurações de recursos, políticas do espaço de trabalho ou controles de ambiente próprios.

Antes de acessar uma origem, as ferramentas do navegador verificam separadamente as regras gerenciadas de bloqueio de rede e as listas exclusivas de destinos permitidos. As políticas de origem do navegador podem impor restrições adicionais ao acesso a sites, aos uploads, aos downloads e às ferramentas de desenvolvedor. Consulte os controles gerenciados do navegador.

Para usuários gerenciados, combine a política de rede dos comandos com controles como allowed_web_search_modes, servidores aprovados em mcp_servers e requisitos de recursos para aplicativos, plug-ins, navegadores ou Uso do computador. Consulte Configuração gerenciada.

Você também pode controlar a ferramenta de pesquisa na Web sem conceder acesso completo à rede aos comandos iniciados. Por padrão, o Codex usa um cache de pesquisa na Web para acessar os resultados. O cache é um índice de resultados da Web mantido pela OpenAI. Nesse modo, a pesquisa retorna resultados já indexados em vez de buscar páginas em tempo real. Isso reduz a exposição a injeções de prompt em conteúdo arbitrário obtido em tempo real. Trate os resultados da Web como não confiáveis. Se você usar --yolo ou outra configuração de sandbox com acesso completo, a pesquisa na Web retornará resultados em tempo real por padrão. Use --search ou defina web_search = "live" para permitir a navegação em tempo real, ou use o valor "disabled" para desativar a ferramenta:

web_search = "cached"  # default
# web_search = "disabled"
# web_search = "live"  # same as --search

Defina web_search = "indexed" quando o índice de pesquisa precisar controlar o acesso à Web externa. Tenha cuidado ao ativar o acesso à rede ou a pesquisa na Web no Codex. Uma injeção de prompt pode levar o agente a buscar e seguir instruções não confiáveis.

Configurações padrão e recomendações

• Ao iniciar, o Codex verifica se a pasta usa controle de versão e recomenda:
  • Pastas com controle de versão: Auto (gravação no espaço de trabalho e aprovações sob demanda)
  • Pastas sem controle de versão: read-only
• Dependendo da configuração, o Codex também pode iniciar em read-only até que você marque explicitamente o diretório de trabalho como confiável, por exemplo, na configuração inicial ou por meio de /permissions.
• O espaço de trabalho inclui o diretório atual e diretórios temporários como /tmp. Use o comando /status para ver quais diretórios fazem parte do espaço de trabalho.
• Para aceitar as configurações padrão, execute codex.
• Você pode definir as opções explicitamente:
  • codex --sandbox workspace-write --ask-for-approval on-request
  • codex --sandbox read-only --ask-for-approval on-request

Caminhos protegidos em diretórios raiz com permissão de gravação

Na política de sandbox padrão workspace-write, mesmo os diretórios raiz com permissão de gravação incluem caminhos protegidos:

• <writable_root>/.git é protegido como somente leitura, seja um diretório ou um arquivo.
• Se <writable_root>/.git for um arquivo que aponta para outro diretório (gitdir: ...), o caminho do diretório Git para o qual ele aponta também será protegido como somente leitura.
• <writable_root>/.agents é protegido como somente leitura quando existe como diretório.
• <writable_root>/.codex é protegido como somente leitura quando existe como diretório.
• <writable_root>/.aws é protegido como somente leitura quando existe como diretório.
• A proteção é recursiva. Todo o conteúdo desses caminhos é somente leitura.

Execução sem solicitações de aprovação

Você pode desativar as solicitações de aprovação com --ask-for-approval never ou com a forma abreviada -a never.

Essa opção funciona com todos os modos de --sandbox, de modo que você continua controlando o nível de autonomia do Codex. O Codex faz o que estiver ao seu alcance dentro das restrições definidas.

Se precisar que o Codex leia e edite arquivos e execute comandos com acesso à rede sem pedir aprovação, use --sandbox danger-full-access (ou a opção --dangerously-bypass-approvals-and-sandbox). Avalie os riscos antes de usar essa configuração.

Como opção intermediária, approval_policy = { granular = { ... } } permite manter interativas determinadas categorias de solicitações de aprovação e rejeitar outras automaticamente. A política granular abrange aprovações do sandbox, solicitações geradas por regras da política de execução, solicitações do MCP, solicitações de request_permissions e aprovações de scripts de habilidades.

Revisão automática de solicitações de aprovação

Por padrão, as solicitações de aprovação são encaminhadas a você:

approvals_reviewer = "user"

A Revisão automática se aplica quando as aprovações são interativas, por exemplo, com approval_policy = "on-request" ou com uma política de aprovação granular. Defina approvals_reviewer = "auto_review" para encaminhar as solicitações de aprovação elegíveis a um agente revisor antes que o Codex execute a ação.

approval_policy = "on-request"
approvals_reviewer = "auto_review"

Para conhecer o ciclo de atuação do revisor, as condições que acionam a revisão, a precedência das configurações e o comportamento em caso de falha, consulte Revisão automática.

O revisor avalia apenas ações que já exigem aprovação. Entre elas estão as elevações de privilégios do sandbox, as solicitações de rede que exigem aprovação, as solicitações de request_permissions e as chamadas de ferramentas de aplicativos ou do MCP que exigem aprovação. Uma regra de comando também pode exigir revisão dentro do sandbox.

A política do revisor verifica se há exfiltração de dados, tentativas de descobrir credenciais, redução persistente da segurança ou ações destrutivas. Ações de risco baixo ou médio podem prosseguir quando a política permite. A política bloqueia ações de risco crítico. Ações de alto risco exigem autorização suficiente do usuário e só podem prosseguir se nenhuma regra de bloqueio se aplicar. Se houver falha na montagem do prompt, na sessão de revisão ou na análise sintática, a ação é bloqueada. O sistema informa separadamente quando o tempo limite é excedido, mas também nesse caso a ação não é executada.

Para substituir a política localmente ou em toda a organização, consulte Configuração da revisão automática.

No aplicativo ChatGPT para desktop, essas revisões aparecem como itens de Revisão automática com um status que indica, por exemplo, se a solicitação está em análise, foi aprovada, negada ou cancelada, ou se o tempo limite foi excedido. Os itens também podem incluir o nível de risco e uma avaliação da autorização do usuário para a solicitação analisada.

A Revisão automática faz chamadas adicionais ao modelo, o que pode aumentar o consumo do Codex. Os administradores podem restringir seu uso com allowed_approvals_reviewers.

Combinações comuns de sandbox e aprovação

Para execuções não interativas, use codex exec --sandbox workspace-write.

Configuração em config.toml

Para conhecer o processo de configuração como um todo, consulte Configuração básica, Configuração avançada e a referência de configuração.

# Interactive approvals with a read-only sandbox
approval_policy = "on-request"
sandbox_mode    = "read-only"
allow_login_shell = false # optional hardening: disallow login shells for shell-based tools

# Optional: Allow network in workspace-write mode
[sandbox_workspace_write]
network_access = true

# Optional: granular approval policy
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

Você também pode salvar predefinições como arquivos de perfil e selecioná-las com codex --profile profile-name:

# ~/.codex/full_auto.config.toml
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

# ~/.codex/readonly_quiet.config.toml
approval_policy = "never"
sandbox_mode    = "read-only"

Teste o sandbox localmente

Para ver o que acontece quando um comando é executado no sandbox do Codex, use estes comandos da CLI do Codex:

# macOS
codex sandbox macos [--permissions-profile <name>] [--log-denials] [COMMAND]...
# Linux
codex sandbox linux [--permissions-profile <name>] [COMMAND]...
# Windows
codex sandbox windows [--permissions-profile <name>] [COMMAND]...

O comando sandbox também está disponível como codex debug, e os comandos auxiliares de cada plataforma têm aliases, como codex sandbox seatbelt e codex sandbox landlock.

Sandbox no sistema operacional

A forma como o Codex aplica as restrições do sandbox depende do sistema operacional:

• macOS usa políticas do Seatbelt e executa comandos por meio de sandbox-exec com um perfil (-p) correspondente ao modo --sandbox selecionado. Quando o acesso de leitura restrito ativa as configurações padrão da plataforma, o Codex acrescenta uma política com regras selecionadas para o macOS, em vez de permitir acesso amplo a /System. Isso preserva a compatibilidade com ferramentas comuns.
• Linux usa bwrap em conjunto com seccomp por padrão.
• Windows oferece suporte a MXC, com elevated e unelevated como alternativas legadas. No Subsistema do Windows para Linux 2 (WSL2), o Codex usa a implementação do sandbox do Linux. O Codex oferecia suporte ao WSL1 até a versão 0.114. A partir da versão 0.115, o sandbox do Linux passou a usar bwrap e o suporte ao WSL1 foi encerrado.

No Windows, a extensão do Codex para IDE oferece suporte direto ao WSL2. Adicione a opção abaixo às configurações do VS Code para manter o agente no WSL2 sempre que ele estiver disponível:

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

Assim, a extensão para IDE segue as regras do sandbox do Linux para comandos, aprovações e acesso ao sistema de arquivos mesmo quando o sistema operacional do host é Windows. Saiba mais no guia do WSL.

Ao executar o Codex no Windows, dê preferência ao MXC quando o dispositivo e a política oferecerem suporte a ele. Para isso, adicione o seguinte a config.toml:

[features]
prefer_mxc = true

Mantenha uma implementação legada permitida em windows.sandbox como alternativa. Consulte o guia de configuração do Windows para conhecer os limites de configuração e compatibilidade.

Se você executar o Linux em um ambiente de contêineres como o Docker, o sandbox poderá não funcionar se a configuração do host ou do contêiner bloquear operações com namespaces, bwrap com setuid ou seccomp necessárias ao Codex.

Nesse caso, configure o contêiner Docker para fornecer o isolamento necessário e execute codex com --sandbox danger-full-access (ou a opção --dangerously-bypass-approvals-and-sandbox) dentro do contêiner.

Execute o Codex em Dev Containers

Se o host não puder executar diretamente o sandbox do Linux ou se sua organização já adotar o desenvolvimento em contêineres como padrão, execute o Codex com Dev Containers e use o Docker para fornecer o isolamento externo. Essa abordagem funciona com o Visual Studio Code Dev Containers e ferramentas compatíveis.

Dentro do contêiner, escolha um dos seguintes modos:

• Mantenha o sandbox do Linux do Codex ativado se o perfil do Dev Container conceder os recursos necessários para que bwrap crie o sandbox interno.
• Se você pretende usar o contêiner como limite de segurança, execute o Codex com --sandbox danger-full-access dentro dele para que o Codex não tente criar uma segunda camada de sandbox.

Controle de versão

O Codex funciona melhor em um fluxo de trabalho com controle de versão:

• Trabalhe em uma branch dedicada à funcionalidade e verifique se git status indica que não há alterações pendentes antes de delegar a tarefa. Assim, fica mais fácil isolar e reverter os patches do Codex.
• Prefira aplicar alterações por meio de patches (por exemplo, com git diff/git apply) a editar diretamente os arquivos rastreados. Faça commits frequentes para poder reverter as alterações em pequenas etapas.
• Trate as sugestões do Codex como qualquer outro pull request. Faça verificações direcionadas, revise os diffs e documente as decisões nas mensagens de commit para fins de auditoria.

Monitoramento e telemetria

O Codex oferece monitoramento opcional por meio do OpenTelemetry (OTel). Com ele, as equipes podem auditar o uso, investigar problemas e atender a requisitos de conformidade sem enfraquecer as configurações padrão de segurança local. A telemetria vem desativada por padrão. Para usá-la, ative-a explicitamente na configuração.

Visão geral

• O Codex mantém a exportação de dados do OTel desativada por padrão para que os dados das execuções locais permaneçam no próprio ambiente.
• Com a telemetria ativada, o Codex emite eventos de log estruturados sobre chats, solicitações de API, atividade em fluxos SSE/WebSocket, prompts de usuários (com o conteúdo ocultado por padrão), decisões de aprovação de ferramentas e resultados das ferramentas.
• O Codex identifica os eventos exportados com service.name (serviço de origem), a versão da CLI e um rótulo de ambiente para distinguir o tráfego de desenvolvimento, homologação e produção.

Ative o OTel (opcional)

Adicione um bloco [otel] à configuração do Codex (geralmente em ~/.codex/config.toml). Escolha um exportador e defina se o texto dos prompts deve ser registrado.

[otel]
environment = "staging"   # dev | staging | prod
exporter = "none"          # none | otlp-http | otlp-grpc
log_user_prompt = false     # redact prompt text unless policy allows

• exporter = "none" mantém a instrumentação ativa sem enviar dados a nenhum destino.
• Para enviar eventos ao seu próprio coletor, escolha uma das opções:

[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}

[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

O Codex agrupa os eventos em lotes e envia os eventos pendentes ao encerrar. O Codex exporta apenas a telemetria produzida pelo seu módulo OTel.

Categorias de eventos

Alguns dos tipos de evento são:

• codex.conversation_starts (modelo, configurações de raciocínio, políticas de sandbox e aprovação)
• codex.api_request (tentativa, status ou indicação de sucesso, duração e detalhes do erro)
• codex.sse_event (tipo de evento do fluxo, sucesso ou falha, duração e contagens de tokens em response.completed)
• codex.websocket_request e codex.websocket_event (duração da solicitação e, para cada mensagem, tipo, indicação de sucesso ou erro)
• codex.user_prompt (comprimento do prompt, com o conteúdo ocultado a menos que seu registro seja ativado explicitamente)
• codex.tool_decision (aprovação ou recusa e origem da decisão, que pode vir da configuração ou do usuário)
• codex.tool_result (duração, indicação de sucesso e trecho da saída)

As métricas associadas do OTel combinam um contador com um histograma de duração. Elas incluem codex.api_request, codex.sse_event, codex.websocket.request, codex.websocket.event e codex.tool.call, com os respectivos instrumentos .duration_ms.

Para consultar o catálogo completo de eventos e a referência de configuração, veja a documentação de configuração do Codex no GitHub.

Orientações de segurança e privacidade

• Mantenha log_user_prompt = false a menos que a política permita explicitamente armazenar o conteúdo dos prompts. Eles podem conter código-fonte e dados confidenciais.
• Envie a telemetria apenas a coletores que você controla. Aplique limites de retenção e controles de acesso compatíveis com seus requisitos de conformidade.
• Trate os argumentos e as saídas das ferramentas como dados confidenciais. Sempre que possível, oculte os dados sensíveis no coletor ou no SIEM.
• Revise as configurações locais de retenção de dados (por exemplo, history.persistence / history.max_bytes) se não quiser que o Codex salve transcrições das sessões em CODEX_HOME. Consulte Configuração avançada e Referência de configuração.
• Se você executar a CLI com o acesso à rede desativado, o exportador do OTel não conseguirá alcançar o coletor. Para exportar os dados, permita acesso de rede ao endpoint do OTel no modo workspace-write ou exporte a partir do Codex na nuvem com o domínio do coletor na lista de permissões.
• Revise os eventos periodicamente para identificar alterações nas aprovações ou no sandbox e execuções inesperadas de ferramentas.

O OTel é opcional e complementa as proteções de sandbox e aprovação descritas acima, sem substituí-las.

Configuração gerenciada

Administradores empresariais podem definir as configurações de segurança do Codex para seu espaço de trabalho em Configuração gerenciada. Consulte essa página para obter detalhes sobre a configuração e as políticas.