Perfis de permissão do Codex: exemplos de config.toml para execuções seguras de agentes

Os perfis de permissão do Codex determinam o que os comandos do seu agente podem ler, escrever e acessar. Aqui estão exemplos testados de config.toml, incluindo um perfil para trabalho com APIs que executa o Apidog CLI sem acesso aberto à internet.

INEZA Felin-Michel

INEZA Felin-Michel

20 novembro 2026

Perfis de permissão do Codex: exemplos de config.toml para execuções seguras de agentes

Apidog para empresas

Implantação local

SSO & RBAC

Conforme SOC 2

Explorar Apidog Enterprise

Os perfis de permissão do Codex são políticas nomeadas no config.toml que definem o que os comandos executados pelo Codex na sua máquina podem ler, gravar e acessar na rede. Você escolhe um com default_permissions, parte de um perfil integrado (:read-only, :workspace ou :danger-full-access) e então adiciona caminhos read, write e deny, além de uma lista de domínios permitidos.

Este guia traz exemplos de config.toml prontos para copiar para as configurações mais comuns, incluindo um para trabalho com APIs que permite ao seu agente de programação executar testes do Apidog CLI nos hosts da sua própria API sem acesso aberto à internet.

O que são os perfis de permissão do Codex?

Um perfil de permissão é uma política de sandbox reutilizável para o Codex. Ele combina regras de sistema de arquivos (quais caminhos os comandos podem ler, gravar ou nunca acessar) com regras de rede (se os comandos podem acessar a rede e quais domínios). O Codex aplica o perfil com Seatbelt no macOS, bubblewrap mais seccomp no Linux e no WSL, e MXC no Windows.

A OpenAI explicou o design em Por dentro do sandbox do Codex, publicado em 18 de novembro de 2026. Em vez de mover seu trabalho para um contêiner, o Codex restringe os comandos no ambiente existente, para que as toolchains nativas continuem funcionando.

O Codex traz três perfis integrados:

Perfil Sistema de arquivos Rede
:read-only Os comandos podem ler, mas não gravar Desativada
:workspace Gravações dentro das raízes do workspace e diretórios temporários; .git, .agents, .codex, .aws permanecem somente leitura Desativada
:danger-full-access Sem restrições locais de sandbox Completa e direta

A documentação de permissões ainda classifica o recurso como Beta, então espere que as chaves mudem entre versões.

Onde a tabela de permissões fica no config.toml

Seus perfis ficam em ~/.codex/config.toml (ou em uma camada de projeto ou de sistema). Dois elementos de nível superior importam:

Uma regra costuma confundir as pessoas. Os perfis de permissão não se combinam com as configurações de sandbox mais antigas. Se sandbox_mode aparecer em qualquer arquivo de configuração carregado, ou se você passar --sandbox, o Codex usa as configurações antigas e ignora default_permissions. Remova sandbox_mode e [sandbox_workspace_write] antes de fazer a troca.

Os perfis seguem o modelo normal de precedência de configuração. As tabelas são mescladas recursivamente, então a configuração de uma equipe pode adicionar um domínio ou um caminho ao perfil de uma organização sem repetir tudo.

Regras de sistema de arquivos: read, write e deny

Cada entrada de sistema de arquivos mapeia um caminho para read, write ou deny. Caminhos mais específicos prevalecem sobre os mais amplos e, quando duas entradas apontam para o mesmo caminho, deny prevalece sobre write, que prevalece sobre read.

As formas de caminho que você mais vai usar:

Use extends para herdar as proteções integradas em vez de recriá-las. Aqui está um perfil que mantém os padrões de :workspace e bloqueia segredos:

default_permissions = "dev"

[permissions.dev]
description = "Workspace edits, secrets denied, no network."
extends = ":workspace"

[permissions.dev.filesystem]
"~/build-cache" = "write"

[permissions.dev.filesystem.":workspace_roots"]
".vscode" = "read"
"**/*.env" = "deny"
"secrets" = "deny"

As regras em :workspace_roots se aplicam a todas as raízes, então secrets significa a pasta secrets em cada raiz de projeto. Um perfil pode estender :read-only, :workspace ou outro perfil nomeado. Ele não pode estender :danger-full-access.

No Linux, no WSL e no Windows nativo, um glob de negação ** sem limite pode precisar de glob_scan_max_depth (pelo menos 1) em [permissions.<name>.filesystem] para que o Codex possa expandi-lo antes de o sandbox iniciar.

Diagram of how a Codex permission profile filters filesystem paths and network requests before a command runs

Regras de rede: desativada, aberta ou com lista de permissões

A rede tem três estados, e duas configurações os controlam:

  1. Rede desativada (enabled = false, o padrão de :workspace): os comandos não conseguem acessar a rede.
  2. Rede ativada, proxy desativado: os comandos recebem acesso direto e irrestrito. Suas regras de domínio são ignoradas.
  3. Rede ativada, proxy ativado: o tráfego passa pelo proxy de rede do Codex, que aplica as regras de domínio do perfil.

O segundo estado é a armadilha. Definir permissions.<name>.network.enabled = true não inicia o proxy. Você também precisa disto no nível superior:

[features]
network_proxy = true

Os padrões de domínio aceitam hosts exatos (api.example.com), *.example.com apenas para subdomínios, **.example.com para o domínio raiz e os subdomínios, e * como um curinga global válido apenas para permissões. Entradas deny substituem entradas allow, e um proxy ativo sem entradas allow bloqueia tudo que for externo.

Quando o proxy está ativo, ele também bloqueia destinos de rede locais e privados por padrão. Para acessar um serviço local, adicione o host literal à lista de permissões, como "localhost" = "allow" ou "127.0.0.1" = "allow".

Um perfil de permissão do Codex para trabalho com APIs

Este é o perfil que testamos para desenvolvimento de APIs. Ele edita código no workspace, nunca lê arquivos .env nem uma pasta secrets, e só consegue acessar o host da sua API e o Apidog:

default_permissions = "api-work"

[features]
network_proxy = true

[permissions.api-work]
description = "Workspace edits, no secrets, API hosts only."
extends = ":workspace"

[permissions.api-work.filesystem.":workspace_roots"]
"**/*.env" = "deny"
"secrets" = "deny"

[permissions.api-work.network]
enabled = true

[permissions.api-work.network.domains]
"api.your-company.com" = "allow"      # the API under test
"staging-api.your-company.com" = "allow"
"**.apidog.com" = "allow"             # Apidog CLI and its API

Substitua os dois hosts pelos que seus testes acessam. O Apidog CLI envia solicitações de teste da sua máquina para a API em teste, então esse host precisa estar na lista de permissões, não apenas o da Apidog. Se você testar um servidor local, adicione "localhost" = "allow".

Instale pacotes antes da sessão, não dentro dela. Executar npm install -g apidog-cli@latest exige registry.npmjs.org, que este perfil bloqueia de propósito.

Um detalhe inesperado do nosso teste: em um Mac executando um aplicativo de proxy ou VPN no modo de DNS fake-IP, todos os hosts permitidos eram resolvidos para um endereço 198.18.x.x. A proteção para redes locais/privadas tratava esses endereços como privados e os bloqueava, e o Codex informava “local/private network addresses are blocked by the sandbox policy”. Adicionar allow_local_binding = true em [permissions.api-work.network] resolveu o problema, mas também libera nomes de host na lista de permissões que resolvem para endereços privados, então defina isso apenas quando precisar.

Teste o perfil com codex sandbox

Não confie em um perfil antes de vê-lo bloquear alguma coisa. O comando codex sandbox executa qualquer comando sob um perfil nomeado e trata o diretório atual como uma raiz de workspace:

codex sandbox --permission-profile api-work -- cat README.md .env

Com o perfil acima, nossa execução imprimiu o README e depois:

cat: .env: Operation not permitted

Uma gravação fora do workspace falhou da mesma forma (Operation not permitted), enquanto um novo arquivo dentro do workspace foi criado. Para a rede, verifique se o proxy bloqueia um host que você não listou:

codex sandbox -P api-work -- curl -sI https://example.org

O proxy respondeu 403 Forbidden com x-proxy-error: blocked-by-allowlist, enquanto apidog.com retornou 200. No macOS, adicione --log-denials para imprimir as negações do Seatbelt depois que o comando terminar.

Você também pode usar codex sandbox para encapsular processos que o Codex não coloca em sandbox por conta própria. O post da OpenAI observa que servidores MCP via stdio no config.toml são executados sem sandbox e mostra um perfil memory-mcp com "~/mcp-data" = "write" e network.enabled = false encapsulando o comando npx do servidor.

Troque de perfil no meio da sessão com /permissions

No Codex CLI, digite /permissions para abrir o seletor. Quando existem perfis nomeados, ele os lista com suas descrições. Para selecionar um diretamente:

/permissions api-work --approval-policy=on-request --reviewer=user

Isso define o perfil para a sessão atual e envia solicitações de aprovação para você. Perfis e aprovações são controles separados: o perfil decide o que um comando em sandbox pode acessar, e a política de aprovação decide quando o Codex pede permissão antes de sair do sandbox. A referência de comandos da CLI lista os outros comandos de sessão.

Deixe o Codex testar sua API com o Apidog CLI

Com api-work ativo, o Codex pode executar testes reais de API sem acesso aberto à internet. O Apidog CLI oferece ao seu agente comandos para endpoints, casos de teste e execuções, com saída JSON que ele consegue ler. Você o configura uma vez fora do sandbox:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

Depois, envie um prompt ao Codex:

Using Apidog CLI, create a test case in project <projectId> for
GET /orders/{id} on endpoint <endpointId> that asserts a 200 status and
a non-empty "items" array. Run it against environment <envId> and
summarize any failures.

O Codex lê o schema do payload, valida o JSON e executa o caso:

apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog test-case run --project <projectId> --endpoint <endpointId> -e <envId> -r cli,json

No nosso teste, apidog auth status e apidog project list foram executados dentro do sandbox api-work com apenas **.apidog.com na lista de permissões. Seu token fica em ~/.apidog, que o perfil pode ler, mas não alterar. Para um passo a passo completo, veja como usar o Apidog CLI no Codex e troque -r cli,json por -r junit quando a mesma execução for para um pipeline de CI. O plano Free do Apidog cobre até 4 usuários.

Flow diagram of Codex running Apidog CLI inside the api-work profile, with the network proxy allowing the API host and Apidog and blocking other domains

Limites que você precisa conhecer antes de confiar em um perfil

Os perfis de permissão reduzem o raio de impacto. Eles não tornam um agente seguro por conta própria. A documentação e o post da OpenAI listam estes limites:

Se você já usou soluções alternativas para contornar o sandbox do Codex, um perfil personalizado e restrito costuma ser a solução mais limpa. Equipes que precisam de política em várias máquinas devem ler o guia de segurança do Codex e os allowed_permission_profiles gerenciados.

Perguntas frequentes

Qual é o perfil de permissão padrão do Codex?

Não há um perfil padrão em que você deva confiar. A documentação orienta definir default_permissions explicitamente para ter um comportamento previsível. Para a maioria dos trabalhos de programação, :workspace é a base sensata: gravações nas raízes do workspace e em diretórios temporários, rede desativada.

Por que minhas regras de domínio são ignoradas?

Normalmente, features.network_proxy está faltando. Com network.enabled = true e sem proxy, os comandos recebem acesso direto e irrestrito à rede. Verifique também se nenhuma configuração carregada define sandbox_mode, o que desativa os perfis por completo.

Como impedir que o Codex leia arquivos .env?

Adicione "**/*.env" = "deny" em [permissions.<name>.filesystem.":workspace_roots"]. No Linux, no WSL e no Windows, defina glob_scan_max_depth para padrões ** sem limite e lembre-se de que novas correspondências não são adicionadas a processos que já estão em execução.

Posso permitir localhost em um perfil de permissão do Codex?

Sim. Adicione o host literal à lista de permissões, como "localhost" = "allow" ou "127.0.0.1" = "allow". Defina allow_local_binding = true apenas quando um nome de host na lista de permissões resolver para um endereço local ou privado.

Os perfis de permissão colocam servidores MCP em sandbox?

Não. Servidores MCP via stdio no config.toml iniciam sem sandbox. Envolva o comando do servidor em codex sandbox --permission-profile <name> -- com um perfil próprio.

Posso usar perfis com a flag --sandbox?

Não. Passar --sandbox ou definir sandbox_mode faz o Codex usar as configurações de sandbox mais antigas em vez de default_permissions. Escolha um sistema por sessão.

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs