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:
default_permissionsnomeia o perfil que o Codex aplica por padrão. Ele precisa corresponder a um perfil integrado ou a um perfil em[permissions].[permissions.<name>]define um perfil. Dê a ele umadescription; ela aparece no seletor de/permissions.
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:
:minimal: os caminhos de plataforma e de runtime de que ferramentas comuns precisam:workspace_roots: as raízes do workspace da sessão mais quaisquer raízes adicionadas pelo perfil:root,:tmpdir,:slash_tmp, caminhos absolutos e caminhos~/
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.

Regras de rede: desativada, aberta ou com lista de permissões
A rede tem três estados, e duas configurações os controlam:
- Rede desativada (
enabled = false, o padrão de:workspace): os comandos não conseguem acessar a rede. - Rede ativada, proxy desativado: os comandos recebem acesso direto e irrestrito. Suas regras de domínio são ignoradas.
- 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.

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:
- Leituras amplas continuam ativas com
:workspace. Compiladores precisam de SDKs e configurações fora do repositório, então um arquivo de configuração em outro local que contenha chaves de API pode continuar legível. Negue~/.sshe caminhos semelhantes explicitamente, ou use":root" = "deny"mais":minimal" = "read". - Globs de negação são um retrato do momento. No Linux, no WSL e no Windows, as correspondências são expandidas quando cada processo em sandbox inicia. Um
.envcriado depois fica legível para um shell ou servidor de desenvolvimento em execução prolongada. - Curingas ainda podem vazar por DNS. O proxy resolve um nome de host somente depois que ele é permitido, mas regras de curinga amplas ou acesso a serviços de DNS ainda podem permitir exfiltração via DNS.
- O proxy cobre apenas comandos em sandbox. Pesquisa na web, conectores, servidores MCP, o navegador e o próprio tráfego do modelo do Codex usam controles separados.
- Gravações podem sobreviver à sessão. O exemplo da OpenAI é um
node_modules/prettieradulterado que seu editor executa depois ao salvar, fora do sandbox.
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.
