Permissões

Os perfis de permissão permitem aplicar limites de privilégio mínimo aos comandos locais que o Codex executa em seu nome. Um perfil é uma política nomeada que combina regras do sistema de arquivos, que definem o que os comandos podem ler ou gravar, com regras de rede, que definem quais destinos os comandos podem acessar.

Use perfis para dar ao Codex acesso suficiente para o chat atual sem conceder acesso amplo à sua máquina ou rede. Por exemplo, um perfil somente leitura pode permitir que o Codex inspecione um projeto sem editá-lo, enquanto um perfil com permissão de gravação pode limitar as edições às raízes selecionadas do workspace.

Há suporte a perfis de permissão locais no macOS, no Linux, no WSL e no Windows nativo. Consulte Escopo e aplicação para ver detalhes e ressalvas específicos de cada plataforma.

Para ver as configurações de rede do Codex Cloud, consulte Acesso à internet.

Definir e selecionar um perfil

O Codex inclui três perfis de permissão integrados:

• :read-only mantém a execução de comandos locais no modo somente leitura.
• :workspace permite gravar nas raízes ativas do workspace e nos diretórios temporários do sistema.
• :danger-full-access remove as restrições do sandbox local e deve ser usado somente quando esse acesso amplo for intencional.

Crie um perfil nomeado em [permissions.<name>] e defina a chave de nível superior default_permissions como o nome desse perfil ou como um dos perfis integrados acima. Neste exemplo, project-edit é um nome de perfil definido pelo usuário, não um valor integrado.

Os administradores de empresas podem definir perfis e restringir quais deles os usuários podem selecionar por meio do requirements.toml gerenciado. Quando allowed_permission_profiles estiver presente, os perfis omitidos não serão permitidos, inclusive perfis integrados omitidos e perfis adicionados em versões futuras do Codex. Consulte Controlar os perfis de permissão disponíveis para ver a configuração gerenciada recomendada.

Os perfis personalizados usam dois conceitos relacionados:

• [permissions.<name>.workspace_roots] adiciona diretórios específicos que devem ser considerados raízes do workspace desse perfil.
• [permissions.<name>.filesystem.":workspace_roots"] define as regras do sistema de arquivos que o Codex aplica dentro de cada raiz efetiva do workspace: as raízes do workspace do ambiente de execução da sessão atual, além das raízes definidas pelo perfil acima.

Os perfis também usam o modelo normal de camadas de configuração. As camadas de maior precedência podem adicionar ou substituir entradas com o mesmo nome de perfil sem redefinir todo o perfil.

Por exemplo, uma configuração no nível da organização e outra no nível do usuário podem estender o mesmo perfil de forma independente:

# /etc/codex/config.toml
[permissions.server.workspace_roots]
"~/code/server" = true

# ~/.codex/config.toml
[permissions.server.workspace_roots]
"~/code/mobile-app" = true

Quando server está ativo, ambas as raízes do workspace fazem parte do perfil efetivo.

default_permissions = "project-edit"

[features]
network_proxy = true

[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"

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

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"
"objects.githubusercontent.com" = "allow"
"*.github.com" = "allow"
"tracking.example.com" = "deny"

Este perfil:

• Lê o conjunto mínimo de caminhos do ambiente de execução de que as ferramentas comuns de desenvolvimento precisam.
• Aplica as mesmas regras às raízes do workspace da sessão atual e às raízes definidas pelo perfil.
• Mantém as configurações associadas à IDE, como .devcontainer/, no modo somente leitura em cada raiz.
• Nega o acesso aos arquivos de ambiente correspondentes por meio de uma regra glob.
• Permite acesso à rede somente por meio da política de domínios configurada.

Em um perfil ativo, as regras de negação mais específicas continuam em vigor mesmo quando um caminho mais abrangente tem permissão de leitura ou gravação. Por exemplo, um perfil pode permitir gravação nas raízes do workspace e ainda definir um caminho correspondente a .env como deny.

Estender um perfil

Use extends quando um perfil for quase igual a um perfil integrado ou a outro perfil nomeado. Prefira estender um perfil integrado em vez de começar do zero para manter as proteções básicas. Por exemplo, estender :workspace mantém o diretório .codex da raiz do workspace no modo somente leitura, a menos que você substitua essa regra explicitamente. Defina o perfil pai uma única vez e adicione ou substitua apenas as regras que forem diferentes.

default_permissions = "project-edit"

[features]
network_proxy = true

[permissions.project-edit]
description = "Project editing with OpenAI API access."
extends = ":workspace"

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

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

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

Este perfil começa com :workspace, mantém negado o acesso aos arquivos que correspondem a .env e permite solicitações para api.openai.com. Um perfil pode estender :read-only, :workspace ou outro perfil nomeado. Ele não pode estender :danger-full-access; o Codex também rejeita perfis pai desconhecidos e ciclos de herança.

Especificação da configuração

Permissões do sistema de arquivos

As entradas do sistema de arquivos usam read, write ou deny:

Entradas mais específicas têm precedência sobre entradas mais amplas. Quando duas entradas se aplicam ao mesmo caminho, deny tem precedência sobre write, e write tem precedência sobre read.

Essa precedência permite que um perfil defina primeiro uma área ampla de trabalho e depois delimite os arquivos ou diretórios que devem permanecer inacessíveis para leitura:

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"

Neste exemplo, a raiz do workspace continua gravável, .devcontainer/ permanece acessível apenas para leitura, e os arquivos de ambiente correspondentes ficam indisponíveis para comandos executados em ambiente isolado.

Um caminho mais específico também pode reabrir o acesso a uma subárvore mais restrita dentro de uma regra de negação mais ampla:

[permissions.project-edit.filesystem]
"~/Documents" = "deny"
"~/Documents/codex" = "write"

Formatos de caminho aceitos:

No Windows nativo, caminhos relativos ao diretório pessoal também podem usar barras invertidas, como ~\work.

Use :root somente quando houver a intenção de conceder amplo acesso de leitura ao perfil:

[permissions.audit.filesystem]
":root" = "read"

Use entradas aninhadas em :workspace_roots para delimitar o acesso a subcaminhos relativos à raiz do workspace:

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"          # each workspace root
"docs" = "read"        # each workspace-root docs directory
"generated" = "deny"   # each workspace-root generated directory

Os subcaminhos aninhados devem permanecer dentro da raiz do workspace. A navegação para o diretório pai, como ../other-repo, é rejeitada.

Negar leituras com caminhos exatos ou padrões glob

Use deny para arquivos ou subárvores que o Codex não deve ler, mesmo que uma regra mais ampla do perfil conceda acesso a caminhos próximos. Caminhos exatos funcionam bem para locais estáveis, como ~/.ssh. Padrões glob são mais adequados quando o perfil precisa abranger uma família de arquivos confidenciais cujos locais exatos variam entre repositórios.

Quando um padrão glob está em :workspace_roots, o Codex o interpreta em relação a cada raiz efetiva do workspace. Por exemplo:

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

Essa regra nega a leitura dos arquivos .env correspondentes encontrados sob cada raiz do workspace do ambiente de execução ou definida pelo perfil. Use-a quando quiser manter as operações normais de gravação no workspace e impedir a leitura de arquivos de ambiente, segredos gerados ou arquivos semelhantes que contenham credenciais.

Padrões glob com deny são compatíveis com regras de negação de leitura. Padrões glob com read ou write são menos portáveis nos ambientes isolados do Linux, do WSL e do Windows nativo; por isso, prefira caminhos exatos ou regras para subárvores, como "docs/**" = "read", sempre que possível.

No Linux, no WSL e no Windows nativo, um padrão ** sem limite para negação de leitura pode exigir uma pré-expansão limitada antes da inicialização do Sandbox. Defina glob_scan_max_depth quando usar um padrão sem limite, como "**/*.env" = "deny":

[permissions.project-edit.filesystem]
glob_scan_max_depth = 3

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

glob_scan_max_depth deve ser, no mínimo, 1. Valores mais altos fazem uma verificação mais profunda antes da inicialização do Sandbox, o que pode aumentar o processamento durante a inicialização no Linux, no WSL e no Windows nativo. Se preferir não usar a expansão limitada, enumere profundidades explícitas, como *.env, */*.env e */*/*.env.

Adicione raízes de workspace reutilizáveis ao perfil quando as mesmas regras precisarem se aplicar a outras raízes além da raiz da sessão atual:

[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true

Quando este perfil está ativo, o Codex aplica as regras de :workspace_roots às raízes de workspace em tempo de execução da sessão atual e a cada raiz de workspace habilitada definida pelo perfil.

No Windows nativo, caminhos com letra de unidade, como D:\work, e caminhos UNC, como \\server\share, são aceitos como caminhos absolutos.

Permissões de rede

O acesso à rede e a filtragem de rede são configurações separadas. Defina permissions.<name>.network.enabled = true para permitir que os comandos acessem a rede e habilite features.network_proxy para aplicar as regras de domínio do perfil:

[features]
network_proxy = true

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

[permissions.project-edit.network.domains]
"example.com" = "allow"      # exact host
"*.example.com" = "allow"    # subdomains only
"**.example.com" = "allow"   # apex and subdomains
"ads.example.com" = "deny"   # deny wins over allow

O comportamento resultante depende das duas configurações:

• Rede desativada: os comandos não podem acessar a rede, independentemente do recurso de proxy.
• Rede ativada, proxy desativado: os comandos têm acesso direto e irrestrito à rede. As regras de domínio do perfil de permissão não são aplicadas.
• Rede ativada, proxy ativado: os comandos usam o proxy, que aplica as regras de domínio do perfil. Se o proxy ativo não tiver domínios permitidos, ele bloqueia os destinos externos.

Adicionar [permissions.<name>.network.domains] ou definir permissions.<name>.network.enabled = true não habilita features.network_proxy. Como alternativa, os administradores podem habilitar o proxy com [experimental_network] em requirements.toml. Consulte Configuração gerenciada.

Quando está ativo, o proxy de rede do Sandbox vincula-se a listeners locais por padrão:

[permissions.project-edit.network]
enabled = true
proxy_url = "http://127.0.0.1:3128"
enable_socks5 = true
socks_url = "http://127.0.0.1:8081"
enable_socks5_udp = true

Mantenha essas configurações de listener nos valores padrão, a menos que esteja fazendo uma integração com um runtime específico. As chaves de rede dangerously_* são mecanismos de escape para ambientes especializados e não devem ser usadas no desenvolvimento local comum.

Redes locais e privadas

Quando o proxy de rede está ativo, o Codex aplica, por padrão, uma proteção para redes locais e privadas contra DNS rebinding e o acesso acidental a serviços locais. Para permitir intencionalmente um destino local literal, adicione à lista de permissões o host exato ou o endereço IP literal:

[permissions.project-edit.network.domains]
"localhost" = "allow"
"127.0.0.1" = "allow"

Defina allow_local_binding = true somente quando o perfil precisar acessar nomes de host permitidos que sejam resolvidos para endereços locais ou privados:

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

[permissions.project-edit.network.domains]
"localhost" = "allow"

Sockets Unix

O uso de proxy para sockets Unix é um mecanismo de escape local para ferramentas como o Docker. Use-o com moderação:

[permissions.project-edit.network.unix_sockets]
"/var/run/docker.sock" = "allow"
"/tmp/old.sock" = "deny"

Use deny para rejeitar um caminho de socket, inclusive uma entrada de permissão herdada. Os caminhos de socket negados são omitidos da lista de permissões efetiva.

Quando os sockets Unix estiverem habilitados, mantenha os listeners do proxy vinculados a endereços de loopback.

Migrar das configurações antigas do Sandbox

Os perfis de permissão substituem a antiga combinação de sandbox_mode e sandbox_workspace_write quando você precisa de um único perfil reutilizável para definir o comportamento do sistema de arquivos e da rede. Em uma sessão, use um sistema ou outro, nunca os dois.

Pontos de partida sugeridos:

• Para um fluxo de trabalho somente leitura, use o perfil integrado :read-only ou defina um perfil personalizado com acesso de leitura apenas onde necessário.
• Para editar o workspace, use o perfil integrado :workspace ou defina um perfil personalizado que grave por meio de :workspace_roots e adicione apenas os caminhos temporários ou de cache adicionais necessários ao fluxo de trabalho.
• Para execução local irrestrita, use :danger-full-access somente se você pretender usar o modelo de acesso local mais amplo.

Os perfis definem a política local padrão de uma sessão. Requisitos gerenciados pela organização ainda podem impor restrições que a configuração do usuário não deve flexibilizar. Consulte Configuração gerenciada para conhecer as restrições de sistema de arquivos e rede impostas pelos administradores.

Escopo e aplicação

Os perfis de permissão definem os limites para a execução local de comandos em ambiente isolado. Use-os em conjunto com políticas de aprovação e com os controles separados para pesquisa na Web, conectores, servidores MCP, o navegador integrado, o Uso do computador e o Codex Cloud.

O que os perfis controlam

• Execução local de comandos: os perfis de permissão controlam os comandos em ambiente isolado executados na sua máquina. Conectores, servidores MCP, interfaces de navegador ou de Uso do computador, configurações dos ambientes do Codex Cloud e elevações aprovadas usam seus próprios controles.
• Gravações no sistema de arquivos: um perfil com permissão de gravação pode criar alterações persistentes. Trate como sensíveis as gravações em scripts, etapas de build, hooks de gerenciadores de pacotes, arquivos de inicialização do shell e diretórios compartilhados, porque outras ferramentas ou usuários podem executar esses arquivos posteriormente, fora do contexto original do Sandbox.
• Destinos de saída: as regras de domínio de rede restringem o destino do tráfego de comandos em ambiente isolado somente enquanto o proxy de rede está ativo. Elas não determinam se um destino permitido é confiável, e as regras de permissão com caracteres curinga continuam amplas.
• Serviços locais: um proxy de rede ativo bloqueia, por padrão, destinos em redes locais e privadas. Adicionar localhost, endereços IP privados ou sockets Unix à lista de permissões, ou definir allow_local_binding = true, libera explicitamente o acesso a serviços locais.

O que o proxy de rede não controla

O proxy de rede filtra apenas o tráfego de comandos locais executados no Sandbox. Ele não aplica a lista de domínios permitidos do perfil a:

• Pesquisa na Web: a ferramenta de pesquisa hospedada usa suas próprias configurações de acesso. Use web_search e, em clientes gerenciados, allowed_web_search_modes para controlá-la. tools.web_search.allowed_domains filtra os resultados da pesquisa, não o acesso dos comandos à rede.
• Apps e conectores: as ferramentas baseadas em conectores usam suas próprias conexões do lado do serviço, permissões do workspace e configurações de aplicativos ou ferramentas.
• Servidores MCP: servidores MCP locais e remotos usam seu próprio processo ou transporte. Controle-os com a configuração mcp_servers e com listas gerenciadas de servidores permitidos.
• Navegador e Uso do computador: a navegação no navegador e as ações de uso do computador usam seus próprios controles de recursos e aprovação.
• Tráfego do serviço Codex: as solicitações de modelo, autenticação e outros serviços do cliente usam as configurações separadas de HTTP e de proxy do sistema do cliente.
• Codex Cloud: essas tarefas usam as próprias configurações de acesso à internet de seus ambientes.

Para limitar essas superfícies, configure cada recurso diretamente. Uma lista de permissões de rede para comandos não é uma política global de rede aplicável a todas as ações que o Codex pode executar.

Como funciona a aplicação das regras

• No macOS, o Codex usa perfis de Sandbox do Seatbelt. Se o Sandbox da plataforma não puder aplicar a política selecionada, o Codex se recusa a executar o comando, em vez de executá-lo silenciosamente sem isolamento.
• No Linux e no WSL, o Codex usa bubblewrap e seccomp, com o Landlock disponível para alternativas de compatibilidade. O mecanismo de aplicação mais rigoroso depende dos namespaces de usuário e do suporte do kernel; hosts de contêiner com restrições podem exigir alternativas de compatibilidade, e políticas de acesso segmentado sem suporte são recusadas.
• No Windows nativo, o ambiente isolado elevated é o que oferece mais proteção, pois pode usar usuários dedicados do Sandbox com privilégios reduzidos, limites de permissão do sistema de arquivos e regras de firewall. O ambiente isolado unelevated é uma alternativa com isolamento de rede mais fraco e não consegue aplicar todas as exceções segmentadas de leitura e gravação; por isso, políticas sem suporte são recusadas. Use o WSL quando precisar do modelo de Sandbox do Linux.

Orientações operacionais

Escolha o perfil mais restrito que ainda permita concluir a tarefa, especialmente quando conceder permissões de gravação ou acesso de saída à rede. Mantenha a política de aprovação, o tratamento de segredos e as regras de permissão alinhados a esse nível de acesso.

Perfis comuns

Somente leitura com lista de permissões de rede

default_permissions = "readonly-net"

[features]
network_proxy = true

[permissions.readonly-net.filesystem]
":minimal" = "read"

[permissions.readonly-net.filesystem.":workspace_roots"]
"." = "read"

[permissions.readonly-net.network]
enabled = true

[permissions.readonly-net.network.domains]
"api.openai.com" = "allow"

Acesso a arquivos limitado ao workspace

Este é um exemplo de perfil de permissão que permite ao Codex gravar nas pastas do seu workspace, mas nega a leitura do restante do sistema de arquivos (com exceções limitadas, conforme determinado por :minimal).

default_permissions = "workspace-only"

[permissions.workspace-only]
# By extending the :workspace profile, you get Codex's safeguards to ensure
# subfolders such as .codex/ and .git/ within a workspace root are read-only
# while the rest of the folder is writable.
extends = ":workspace"

[permissions.workspace-only.filesystem]
# By default, deny read access to all files on disk.
":root" = "deny"

# Though in practice, a software agent needs to be able to read folders that
# contain common tools, such as `/usr/bin`, to get work done, so grant access
# to a "minimal" set of files and folders, as determined by Codex.
":minimal" = "read"

# By extending the :workspace profile, :tmpdir and :slash_tmp are "write" by
# default, though you can deny access to them altogether, if desired.
":tmpdir" = "deny"
":slash_tmp" = "deny"

Gravação no workspace sem rede

default_permissions = "project-edit"

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"

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

Gravação no workspace com acesso à Web pública

default_permissions = "workspace-net"

[features]
network_proxy = true

[permissions.workspace-net.filesystem]
":minimal" = "read"

[permissions.workspace-net.filesystem.":workspace_roots"]
"." = "write"

[permissions.workspace-net.network]
enabled = true

[permissions.workspace-net.network.domains]
"*" = "allow"

Use a regra global de permissão "*" somente quando pretender permitir o acesso à rede pública. Regras de negação podem restringir uma lista de permissões ampla.