Aprovações e segurança do agente
Como utilizar o Codex de forma segura com isolamento, aprovações e controlos de rede
O Codex ajuda a proteger o seu código e os seus dados e reduz o risco de utilização indevida.
Por predefinição, o agente é executado com o acesso à rede desativado. Localmente, o Codex utiliza um ambiente isolado imposto pelo sistema operativo que limita aquilo a que pode aceder (normalmente, ao espaço de trabalho atual), juntamente com uma política de aprovação que controla quando tem de parar e pedir a sua autorização antes de atuar.
Para obter uma explicação geral sobre como o isolamento funciona na aplicação ChatGPT para computador, no Codex CLI e na extensão para IDE, consulte isolamento. Para obter uma visão geral mais abrangente da segurança empresarial, consulte o documento técnico de segurança do Codex.
Ambiente isolado e aprovações
Os controlos de segurança do Codex resultam de duas camadas que funcionam em conjunto:
- Modo de isolamento: aquilo que o Codex pode fazer tecnicamente (por exemplo, onde pode escrever e se pode aceder à rede) ao executar comandos gerados pelo modelo.
- Política de aprovação: quando o Codex tem de pedir a sua autorização antes de executar uma ação (por exemplo, sair do ambiente isolado, utilizar a rede ou executar comandos fora de um conjunto fidedigno).
O Codex utiliza modos de isolamento diferentes consoante o local onde é executado:
- Codex cloud: é executado em contentores isolados geridos pela OpenAI, impedindo o acesso ao seu sistema anfitrião ou a dados não relacionados. Utiliza um modelo de execução em duas fases: a configuração é executada antes da fase do agente e pode aceder à rede para instalar as dependências especificadas; em seguida, a fase do agente é executada offline por predefinição, a menos que ative o acesso à Internet para esse ambiente. Os segredos configurados para ambientes na nuvem só estão disponíveis durante a configuração e são removidos antes do início da fase do agente.
- Codex CLI / extensão para IDE: mecanismos ao nível do sistema operativo impõem as políticas de isolamento. As predefinições incluem a ausência de acesso à rede e permissões de escrita limitadas ao espaço de trabalho ativo. Pode configurar o ambiente isolado, a política de aprovação e as definições de rede com base na sua tolerância ao risco.
Na predefinição Auto (por exemplo, --sandbox workspace-write --ask-for-approval on-request), o Codex pode ler ficheiros, efetuar alterações e executar automaticamente comandos no diretório de trabalho.
O Codex pede aprovação para editar ficheiros fora do espaço de trabalho ou executar comandos que exijam acesso à rede. Se pretender conversar ou planear sem efetuar alterações, mude para o modo read-only com o comando /permissions.
O Codex também pode solicitar aprovação para chamadas de ferramentas de aplicações (conectores) que indiquem efeitos secundários, mesmo quando a ação não é um comando da shell nem uma alteração de ficheiros. As chamadas destrutivas de ferramentas de aplicações/MCP exigem sempre aprovação quando a ferramenta indica uma anotação destrutiva, mesmo que também indique outras informações (por exemplo, informações de apenas leitura).
Acesso à rede
Para o Codex cloud, consulte acesso do agente à Internet para ativar o acesso total à Internet ou uma lista de domínios permitidos.
Na aplicação ChatGPT para computador, no Codex CLI ou na extensão para IDE, o modo de isolamento workspace-write predefinido mantém o acesso à rede desativado, a menos que o ative na sua configuração:
[sandbox_workspace_write]
network_access = trueIsolamento de rede
O acesso à rede é controlado através de regras de destino que se aplicam a scripts,
programas e subprocessos iniciados por comandos. Quando o acesso à rede por comandos já está
ativado, ative a funcionalidade network_proxy para restringir esse tráfego
à política de rede que configurar.
[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow", "example.com" = "deny" }Para uma sessão pontual do CLI, utilize a forma abreviada booleana quando apenas precisar de ativar ou desativar a opção, e a forma de tabela quando também 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'A funcionalidade altera a forma como o acesso à rede ativado é imposto; não concede
acesso à rede por si só. Utilize sandbox_workspace_write.network_access com a configuração
workspace-write para decidir se os comandos têm acesso à rede:
- Rede desativada +
network_proxyativado: a rede permanece desativada e a funcionalidade não produz qualquer efeito. - Rede ativada +
network_proxydesativado: a rede permanece ativada com acesso direto de saída sem restrições. - Rede ativada +
network_proxyativado: a rede permanece ativada e o tráfego de saída fica restringido pela política de rede configurada.
Os requisitos de experimental_network geridos pelo administrador são independentes da opção da
funcionalidade do utilizador. Podem configurar e iniciar a rede isolada sem
features.network_proxy, mas não ativam o acesso à rede quando o ambiente isolado ativo
o mantém desativado. Consulte Configuração gerida
para conhecer a estrutura de requirements.toml do lado do administrador.
Política de rede
As regras de domínio dão prioridade à lista de permissões:
- Os anfitriões exatos correspondem apenas a si próprios.
*.example.comcorresponde a subdomínios comoapi.example.com, mas não aexample.com.**.example.comcorresponde tanto ao domínio raiz como aos subdomínios.- Uma regra de permissão global
*corresponde a qualquer anfitrião público que não esteja bloqueado. Trate*como acesso abrangente à rede e prefira regras específicas sempre que possível. denyprevalece sempre sobreallow, e o*global só é válido para regras de permissão.
Destinos locais e privados
Por predefinição, allow_local_binding = false bloqueia destinos de loopback, link-local e
privados:
- Exceções específicas: adicione uma regra de permissão com um literal de IP local exato ou
localhostquando um comando precisar de um destino local específico. - Acesso mais abrangente: defina
allow_local_binding = trueapenas quando pretender intencionalmente um acesso local/privado mais amplo. - Carateres universais: as regras com carateres universais não contam como exceções locais explícitas.
- Endereços resolvidos: os nomes de anfitrião que sejam resolvidos para IP locais/privados permanecem bloqueados, mesmo que correspondam à lista de permissões.
Proteções contra reenlace de DNS
Antes de permitir um nome de anfitrião, o Codex efetua uma verificação de DNS e de classificação de IP com base no melhor esforço:
- As consultas que falhem ou excedam o tempo limite são bloqueadas.
- Os nomes de anfitrião que sejam resolvidos para endereços não públicos são bloqueados.
- A verificação reduz o risco de reenlace de DNS, mas não o elimina. Impedir totalmente o reenlace exigiria fixar os IP resolvidos através da camada de transporte.
Se um DNS hostil fizer parte do âmbito, imponha também controlos de saída numa camada inferior.
Definições perigosas
Duas definições alargam deliberadamente o limite de confiança:
dangerously_allow_non_loopback_proxy = truepode expor os listeners do proxy para além do loopback.dangerously_allow_all_unix_sockets = trueignora a lista de permissões de sockets Unix.
Utilize-as apenas em ambientes rigorosamente controlados. Quando o encaminhamento por proxy de sockets Unix está ativado, os listeners permanecem limitados ao loopback mesmo que tenha sido solicitada a associação fora do loopback, pelo que a rede isolada não se transforma numa ponte remota para daemons locais.
network_proxy está desativado por predefinição. Quando o ativa:
| Definição | Predefinição | Comportamento |
|---|---|---|
enabled |
false |
Inicia a rede isolada apenas quando o acesso à rede por comandos já está ativado. |
domains |
não definido | Utiliza o comportamento de lista de permissões, pelo que nenhum destino externo é permitido até adicionar regras allow. Suporta anfitriões exatos, carateres universais específicos e regras de permissão * globais; deny prevalece sempre. |
unix_sockets |
não definido | Não são permitidos destinos de sockets Unix até adicionar regras allow explícitas. |
allow_local_binding |
false |
Bloqueia destinos locais e de redes privadas, a menos que adicione um literal de IP local exato ou uma regra de permissão localhost, ou aceite explicitamente um acesso local/privado mais abrangente. |
enable_socks5 |
true |
Disponibiliza suporte para SOCKS5 quando a política o permite. |
enable_socks5_udp |
true |
Permite UDP através de SOCKS5 quando SOCKS5 está disponível. |
allow_upstream_proxy |
true |
Permite que a rede isolada respeite um proxy a montante proveniente do ambiente. |
dangerously_allow_non_loopback_proxy |
false |
Mantém os pontos finais dos listeners no loopback, a menos que os exponha deliberadamente para além de localhost. |
dangerously_allow_all_unix_sockets |
false |
Mantém o acesso a sockets Unix baseado numa lista de permissões, a menos que ignore deliberadamente essa proteção. |
Também pode controlar a ferramenta de pesquisa na Web sem conceder acesso total à rede aos comandos iniciados. Por predefinição, o Codex utiliza uma cache de pesquisa na Web para aceder aos resultados. A cache é um índice de resultados da Web mantido pela OpenAI, pelo que o modo em cache devolve resultados pré-indexados em vez de obter páginas em tempo real. Isto reduz a exposição à injeção de instruções provenientes de conteúdos arbitrários em tempo real, mas deve continuar a tratar os resultados da Web como não fidedignos. Se estiver a utilizar --yolo ou outra definição de acesso total do ambiente isolado, a pesquisa na Web utiliza resultados em tempo real por predefinição. Utilize --search ou defina web_search = "live" para permitir a navegação em tempo real, ou defina-a como "disabled" para desativar a ferramenta:
web_search = "cached" # default
# web_search = "disabled"
# web_search = "live" # same as --searchDefina web_search = "indexed" quando o acesso externo à Web deva ser controlado pelo
índice de pesquisa. Tenha cuidado ao ativar o acesso à rede ou a pesquisa na Web no Codex.
A injeção de instruções pode levar o agente a obter e seguir instruções não fidedignas.
Predefinições e recomendações
- Ao iniciar, o Codex deteta se a pasta está sob controlo de versões e recomenda:
- Pastas sob controlo de versões:
Auto(escrita no espaço de trabalho + aprovações mediante pedido) - Pastas não sujeitas a controlo de versões:
read-only
- Pastas sob controlo de versões:
- Consoante a sua configuração, o Codex também pode iniciar em
read-onlyaté que considere explicitamente o diretório de trabalho fidedigno (por exemplo, através de um pedido de integração inicial ou de/permissions). - O espaço de trabalho inclui o diretório atual e diretórios temporários como
/tmp. Utilize o comando/statuspara ver quais os diretórios que fazem parte do espaço de trabalho. - Para aceitar as predefinições, execute
codex. - Pode defini-las explicitamente:
codex --sandbox workspace-write --ask-for-approval on-requestcodex --sandbox read-only --ask-for-approval on-request
Caminhos protegidos em raízes com permissão de escrita
Na política de isolamento workspace-write predefinida, as raízes com permissão de escrita continuam a incluir caminhos protegidos:
<writable_root>/.gitestá protegido como só de leitura, quer apareça como diretório ou como ficheiro.- Se
<writable_root>/.gitfor um ficheiro apontador (gitdir: ...), o caminho resolvido do diretório Git também estará protegido como só de leitura. <writable_root>/.agentsestá protegido como só de leitura quando existe como diretório.<writable_root>/.codexestá protegido como só de leitura quando existe como diretório.- A proteção é recursiva, pelo que tudo o que estiver nesses caminhos é só de leitura.
Executar sem pedidos de aprovação
Pode desativar os pedidos de aprovação com --ask-for-approval never ou -a never (forma abreviada).
Esta opção funciona com todos os modos --sandbox, pelo que continua a controlar o nível de autonomia do Codex. O Codex envida os melhores esforços dentro das restrições definidas.
Se precisar que o Codex leia ficheiros, faça alterações e execute comandos com acesso à rede sem pedidos de aprovação, utilize --sandbox danger-full-access (ou o sinalizador --dangerously-bypass-approvals-and-sandbox). Proceda com cuidado antes de o fazer.
Como solução intermédia, approval_policy = { granular = { ... } } permite manter interativas determinadas categorias de pedidos de aprovação, rejeitando automaticamente as restantes. A política granular abrange aprovações da sandbox, pedidos de regras de execpolicy, pedidos de MCP, pedidos de request_permissions e aprovações de scripts de competências.
Revisões automáticas de aprovações
Por predefinição, os pedidos de aprovação são encaminhados para si:
approvals_reviewer = "user"As revisões automáticas de aprovações aplicam-se quando as aprovações são interativas, como
approval_policy = "on-request" ou uma política de aprovação granular. Defina
approvals_reviewer = "auto_review" para encaminhar os pedidos de aprovação elegíveis
através de um agente revisor antes de o Codex executar o pedido:
approval_policy = "on-request"
approvals_reviewer = "auto_review"Para conhecer o ciclo de vida completo do revisor, as condições de ativação, a precedência da configuração e o comportamento em caso de falha, consulte Revisão automática.
O revisor avalia apenas ações que já necessitam de aprovação, como escalamentos
da sandbox, pedidos de rede bloqueados, pedidos de request_permissions ou
chamadas de ferramentas de aplicações e MCP com efeitos secundários. As ações que permanecem dentro da sandbox
continuam sem uma etapa de revisão adicional.
A política do revisor verifica a exfiltração de dados, a pesquisa de credenciais, o enfraquecimento persistente da segurança e as ações destrutivas. As ações de risco baixo e médio podem prosseguir quando a política o permite. A política recusa ações de risco crítico. As ações de risco elevado requerem autorização suficiente do utilizador e a ausência de uma regra de recusa correspondente. As falhas na criação do pedido, na sessão de revisão e na análise resultam numa recusa por segurança. Os tempos limite são apresentados separadamente, mas a ação continua sem ser executada.
A política predefinida do revisor
encontra-se no repositório de código aberto do Codex. As empresas podem substituir a respetiva
secção específica do inquilino por guardian_policy_config nos requisitos geridos.
Também é suportado texto local de [auto_review].policy, mas os requisitos geridos
têm precedência. Para obter detalhes de configuração, consulte
Configuração gerida.
Na aplicação ChatGPT para computador, estas revisões aparecem como itens de revisão automática com um estado como Em revisão, Aprovado, Recusado, Abortado ou Tempo limite excedido. Também podem incluir um nível de risco e uma avaliação da autorização do utilizador para o pedido revisto.
A revisão automática utiliza chamadas adicionais ao modelo, pelo que pode aumentar a utilização do Codex. Os administradores
podem limitá-la com allowed_approvals_reviewers.
Combinações comuns de sandbox e aprovação
| Objetivo | Sinalizadores/configuração | Efeito |
|---|---|---|
| Automático (predefinição) | não são necessários sinalizadores ou --sandbox workspace-write --ask-for-approval on-request |
O Codex pode ler ficheiros, fazer alterações e executar comandos no espaço de trabalho. O Codex requer aprovação para editar fora do espaço de trabalho ou aceder à rede. |
| Navegação segura só de leitura | --sandbox read-only --ask-for-approval on-request |
O Codex pode ler ficheiros e responder a perguntas. O Codex requer aprovação para fazer alterações, executar comandos ou aceder à rede. |
| Só de leitura não interativo (CI) | --sandbox read-only --ask-for-approval never |
O Codex só pode ler ficheiros; nunca pede aprovação. |
| Editar automaticamente, mas pedir aprovação para executar comandos não fidedignos | --sandbox workspace-write --ask-for-approval untrusted |
O Codex pode ler e editar ficheiros, mas pede aprovação antes de executar comandos não fidedignos. |
| Modo de revisão automática | --sandbox workspace-write --ask-for-approval on-request -c approvals_reviewer=auto_review ou approvals_reviewer = "auto_review" |
O mesmo limite da sandbox que no modo padrão mediante pedido, mas os pedidos de aprovação elegíveis são analisados pela Revisão automática em vez de serem apresentados ao utilizador. |
| Acesso total perigoso | --dangerously-bypass-approvals-and-sandbox (alias: --yolo) |
Sem sandbox; sem aprovações (não recomendado) |
Para execuções não interativas, utilize codex exec --sandbox workspace-write; o Codex mantém as invocações antigas de codex exec --full-auto como um mecanismo de compatibilidade obsoleto e apresenta um aviso.
Com --ask-for-approval untrusted, o Codex só executa automaticamente operações de leitura reconhecidamente seguras. Os comandos que podem alterar o estado ou acionar caminhos de execução externos (por exemplo, operações Git destrutivas ou sinalizadores de saída/substituição de configuração do Git) requerem aprovação.
Configuração em config.toml
Para conhecer o fluxo de trabalho de configuração mais abrangente, consulte Noções básicas de configuração, Configuração avançada e a Referência de configuração.
# Always ask for approval mode
approval_policy = "untrusted"
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
# } }Também pode guardar predefinições como ficheiros de perfil e, em seguida, 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"Testar a sandbox localmente
Para ver o que acontece quando um comando é executado na sandbox do Codex, utilize estes comandos da Codex CLI:
# 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 auxiliares de plataforma têm aliases (por exemplo, codex sandbox seatbelt e codex sandbox landlock).
Sandbox ao nível do sistema operativo
O Codex aplica a sandbox de forma diferente consoante o sistema operativo:
- O macOS utiliza políticas Seatbelt e executa comandos através de
sandbox-execcom um perfil (-p) que corresponde ao modo--sandboxselecionado. Quando o acesso de leitura restrito ativa as predefinições da plataforma, o Codex acrescenta uma política de plataforma macOS selecionada (em vez de permitir amplamente/System) para preservar a compatibilidade com ferramentas comuns. - O Linux utiliza
bwrapeseccomppor predefinição. - O Windows utiliza a implementação da sandbox do Linux quando é executado no Windows Subsystem for Linux 2 (WSL2). O WSL1 foi suportado até ao Codex
0.114; a partir de0.115, a sandbox do Linux passou a utilizarbwrap, pelo que o WSL1 deixou de ser suportado. Quando é executado nativamente no Windows, o Codex utiliza uma implementação de sandbox do Windows.
Se utilizar a extensão Codex IDE no Windows, esta suporta diretamente o WSL2. Defina o seguinte nas definições do VS Code para manter o agente dentro do WSL2 sempre que este estiver disponível:
{
"chatgpt.runCodexInWindowsSubsystemForLinux": true
}Isto garante que a extensão IDE herda a semântica da sandbox do Linux para comandos, aprovações e acesso ao sistema de ficheiros, mesmo quando o sistema operativo anfitrião é o Windows. Saiba mais no guia do WSL.
Quando executar nativamente no Windows, configure o modo de sandbox nativo em config.toml:
[windows]
sandbox = "unelevated" # or "elevated"
# sandbox_private_desktop = true # default; set false only for compatibilityConsulte o guia de configuração do Windows para obter detalhes.
Quando executa o Linux num ambiente em contentor, como o Docker, a sandbox poderá não funcionar se a configuração do anfitrião ou do contentor bloquear o espaço de nomes, as operações de setuid bwrap ou as operações de seccomp de que o Codex necessita.
Nesse caso, configure o contentor Docker para fornecer o isolamento necessário e, em seguida, execute codex com --sandbox danger-full-access (ou o sinalizador --dangerously-bypass-approvals-and-sandbox) dentro do contentor.
Executar o Codex em Dev Containers
Se o anfitrião não conseguir executar diretamente a sandbox do Linux, ou se a sua organização já tiver normalizado o desenvolvimento em contentores, execute o Codex com Dev Containers e permita que o Docker forneça o limite de isolamento externo. Isto funciona com Visual Studio Code Dev Containers e ferramentas compatíveis.
Utilize o exemplo de devcontainer seguro do Codex como implementação de referência. O exemplo instala o Codex, ferramentas de desenvolvimento comuns, bubblewrap e controlos de saída baseados em firewall.
A implementação de referência inclui:
- uma imagem base do Ubuntu 24.04 com o Codex e ferramentas de desenvolvimento comuns instalados;
- um perfil de firewall baseado numa lista de permissões para acesso de saída;
- definições do VS Code e recomendações de extensões para reabrir o espaço de trabalho num contentor;
- montagens persistentes para o histórico de comandos e a configuração do Codex;
bubblewrap, para que o Codex possa continuar a utilizar o respetivo sandbox do Linux quando o contentor concede as capacidades necessárias.
Para experimentar:
- Instale o Visual Studio Code e a extensão Dev Containers.
- Copie a configuração
.devcontainerdo exemplo do Codex para o seu repositório ou comece diretamente a partir do repositório do Codex. - No VS Code, execute Dev Containers: Open Folder in Container... e selecione
.devcontainer/devcontainer.secure.json. - Depois de o contentor iniciar, abra um terminal e execute
codex.
Também pode iniciar o contentor a partir da CLI:
devcontainer up --workspace-folder . --config .devcontainer/devcontainer.secure.jsonO exemplo tem três componentes principais:
.devcontainer/devcontainer.secure.jsoncontrola as definições, capacidades, montagens, variáveis de ambiente e extensões do VS Code do contentor..devcontainer/Dockerfile.securedefine a imagem baseada no Ubuntu e as ferramentas instaladas..devcontainer/init-firewall.shaplica a política de rede de saída.
O firewall de referência destina-se intencionalmente a servir como ponto de partida. Se depender da inclusão de domínios numa lista de permissões para fins de isolamento, implemente proteções contra revinculação de DNS e atualização de DNS adequadas ao seu ambiente, como atualizações sensíveis ao TTL ou um firewall com reconhecimento de DNS.
Dentro do contentor, escolha um destes modos:
- Mantenha o sandbox do Linux do Codex ativado se o perfil do Dev Container conceder as capacidades necessárias para
bwrapcriar o sandbox interno. - Se o contentor for o limite de segurança pretendido, execute o Codex com
--sandbox danger-full-accessdentro do contentor, para que o Codex não tente criar uma segunda camada de sandbox.
Controlo de versões
O Codex funciona melhor com um fluxo de trabalho de controlo de versões:
- Trabalhe num ramo de funcionalidade e mantenha
git statuslimpo antes de delegar. Isto facilita o isolamento e a reversão dos patches do Codex. - Dê preferência a fluxos de trabalho baseados em patches (por exemplo,
git diff/git apply) em vez de editar diretamente ficheiros controlados. Faça commits com frequência para poder reverter em pequenos incrementos. - Trate as sugestões do Codex como qualquer outro PR: execute verificações específicas, reveja as diferenças e documente as decisões nas mensagens de commit para fins de auditoria.
Monitorização e telemetria
O Codex permite a monitorização opcional através do OpenTelemetry (OTel), para ajudar as equipas a auditar a utilização, investigar problemas e cumprir requisitos de conformidade sem enfraquecer as predefinições de segurança local. A telemetria está desativada por predefinição; ative-a explicitamente na sua configuração.
Descrição geral
- O Codex desativa por predefinição a exportação de OTel para manter as execuções locais autocontidas.
- Quando ativado, o Codex emite eventos de registo estruturados que abrangem conversas, pedidos à API, atividade de transmissão SSE/WebSocket, pedidos do utilizador (ocultados por predefinição), decisões de aprovação de ferramentas e resultados das ferramentas.
- O Codex identifica os eventos exportados com
service.name(originador), a versão da CLI e uma etiqueta de ambiente para separar o tráfego de desenvolvimento, staging e produção.
Ativar o OTel (opcional)
Adicione um bloco [otel] à configuração do Codex (normalmente ~/.codex/config.toml), escolhendo um exportador e indicando se pretende registar o texto dos pedidos.
[otel]
environment = "staging" # dev | staging | prod
exporter = "none" # none | otlp-http | otlp-grpc
log_user_prompt = false # redact prompt text unless policy allowsexporter = "none"mantém a instrumentação ativa, mas não envia dados para nenhum destino.- Para enviar eventos para o seu próprio coletor, escolha uma das seguintes 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 ao encerrar. O Codex exporta apenas a telemetria produzida pelo respetivo módulo OTel.
Categorias de eventos
Os tipos de eventos representativos incluem:
codex.conversation_starts(modelo, definições de raciocínio, política de sandbox/aprovação)codex.api_request(tentativa, estado/sucesso, duração e detalhes do erro)codex.sse_event(tipo de evento de transmissão, sucesso/falha, duração e contagens de tokens emresponse.completed)codex.websocket_requestecodex.websocket_event(duração do pedido e tipo/sucesso/erro por mensagem)codex.user_prompt(comprimento; conteúdo ocultado, salvo se explicitamente ativado)codex.tool_decision(aprovado/recusado, origem: configuração ou utilizador)codex.tool_result(duração, sucesso, excerto da saída)
As métricas OTel associadas (pares de contador e histograma de duração) incluem codex.api_request, codex.sse_event, codex.websocket.request, codex.websocket.event e codex.tool.call (com os instrumentos .duration_ms correspondentes).
Para consultar o catálogo completo de eventos e a referência de configuração, consulte a documentação de configuração do Codex no GitHub.
Orientações de segurança e privacidade
- Mantenha
log_user_prompt = false, salvo se a política permitir explicitamente o armazenamento do conteúdo dos pedidos. Os pedidos podem incluir código-fonte e dados confidenciais. - Encaminhe a telemetria apenas para coletores sob o seu controlo; aplique limites de retenção e controlos de acesso alinhados com os seus requisitos de conformidade.
- Trate os argumentos e as saídas das ferramentas como dados confidenciais. Sempre que possível, dê preferência à ocultação no coletor ou SIEM.
- Reveja as definições de retenção de dados locais (por exemplo,
history.persistence/history.max_bytes) se não pretender que o Codex guarde transcrições das sessões emCODEX_HOME. Consulte Configuração avançada e Referência de configuração. - Se executar a CLI com o acesso à rede desativado, a exportação de OTel não conseguirá chegar ao seu coletor. Para exportar, permita o acesso à rede no modo
workspace-writepara o ponto final OTel ou exporte a partir do Codex cloud com o domínio do coletor na sua lista de permissões. - Reveja periodicamente os eventos para detetar alterações de aprovação/sandbox e execuções inesperadas de ferramentas.
O OTel é opcional e foi concebido para complementar, e não substituir, as proteções de sandbox e aprovação descritas acima.
Configuração gerida
Os administradores empresariais podem configurar as definições de segurança do Codex para o respetivo espaço de trabalho em Configuração gerida. Consulte essa página para obter detalhes sobre a configuração e as políticas.