Permissões

Com os perfis de permissões, você pode aplicar o princípio do menor privilégio aos comandos locais que o Codex executa em seu nome. Um perfil é uma política identificada por nome 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 conceder ao Codex o acesso necessário para o chat atual sem dar acesso amplo ao computador ou à rede. Por exemplo, com um perfil somente leitura, o Codex pode inspecionar um projeto sem editá-lo. Já um perfil com permissão de gravação pode limitar as edições a determinadas raízes do espaço de trabalho.

O macOS, o Linux, o WSL e o Windows nativo oferecem suporte a perfis de permissões locais. Consulte Escopo e aplicação das regras para ver detalhes e ressalvas de cada plataforma.

Para consultar as configurações de rede atuais do Codex Cloud, veja Conectar-se a serviços. Para o Codex Cloud (legado), veja Acesso à internet.

Definir e selecionar um perfil

O Codex inclui três perfis de permissões predefinidos:

• :read-only limita os comandos locais a operações de leitura.
• :workspace permite gravações nas raízes ativas do espaço de trabalho e nos diretórios temporários do sistema.
• :danger-full-access remove as restrições do sandbox local. Use esse perfil somente quando quiser conceder esse nível de acesso.

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

Administradores de ambientes corporativos podem definir perfis e restringir quais deles os usuários podem selecionar por meio do arquivo gerenciado requirements.toml. Quando allowed_permission_profiles está presente, todos os perfis omitidos são bloqueados, inclusive os predefinidos que não constam na lista e os que forem adicionados em versões futuras do Codex. Consulte Controlar os perfis de permissões 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 o perfil deve considerar raízes do espaço de trabalho.
• [permissions.<name>.filesystem.":workspace_roots"] define as regras do sistema de arquivos que o Codex aplica em cada raiz efetiva do espaço de trabalho. Isso inclui tanto as raízes que o ambiente de execução fornece à sessão atual quanto as definidas pelo perfil acima.

Os perfis também seguem o modelo usual de configuração em camadas. Camadas de maior precedência podem adicionar ou substituir entradas de um perfil com o mesmo nome sem precisar repetir toda a definição.

Por exemplo, as configurações da organização e 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, as duas raízes do espaço de trabalho 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"

Esse perfil:

• Permite ler o conjunto mínimo de caminhos de execução necessários para ferramentas comuns de desenvolvimento.
• Aplica as mesmas regras às raízes do espaço de trabalho da sessão atual e às definidas pelo perfil.
• Mantém configurações relacionadas ao IDE, como .devcontainer/, em modo somente leitura em cada raiz.
• Bloqueia o acesso aos arquivos de ambiente que correspondem a um padrão glob.
• Permite acesso à rede somente conforme a política de domínios configurada.

Em um perfil ativo, as regras de bloqueio mais específicas continuam valendo mesmo quando um caminho mais abrangente permite leitura ou gravação. Por exemplo, um perfil pode permitir gravações nas raízes do espaço de trabalho e ainda bloquear um caminho .env correspondente com a regra deny.

Estender um perfil

Use extends quando um perfil tiver quase as mesmas regras que um perfil predefinido ou outro perfil com nome. Prefira estender um perfil predefinido a começar do zero para manter as proteções básicas. Ao estender :workspace, por exemplo, os caminhos .git, .agents, .codex e .aws na raiz do espaço de trabalho permanecem em modo somente leitura, a menos que você substitua essas regras explicitamente. Defina o perfil pai uma 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"

Esse perfil parte de :workspace, mantém o bloqueio dos arquivos .env que correspondem ao padrão e permite solicitações a api.openai.com. Um perfil pode estender :read-only, :workspace ou outro perfil com nome. Ele não pode estender :danger-full-access. O Codex também rejeita perfis pais 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 prevalecem sobre as mais abrangentes. Quando duas entradas se aplicam ao mesmo caminho, deny tem precedência sobre write, e write tem precedência sobre read.

Com essa ordem de precedência, o perfil pode definir primeiro uma área de trabalho ampla e depois excluir 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 espaço de trabalho continua permitindo gravação, .devcontainer/ permanece em modo somente leitura e os arquivos de ambiente que correspondem ao padrão continuam inacessíveis aos comandos executados no sandbox.

Um caminho mais específico também pode restabelecer o acesso a uma subárvore dentro de uma área bloqueada por uma regra mais abrangente:

[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 quiser conceder ao perfil acesso amplo de leitura:

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

Use entradas aninhadas em :workspace_roots para delimitar o acesso a subcaminhos relativos a cada raiz do espaço de trabalho:

[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 respectiva raiz do espaço de trabalho. O Codex rejeita caminhos que sobem para o diretório pai, como ../other-repo.

Bloquear 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 abrangente do perfil conceda acesso à área em que se encontram. Caminhos exatos funcionam bem para locais fixos, como ~/.ssh. Padrões glob são mais adequados quando o perfil precisa abranger um conjunto de arquivos confidenciais cuja localização varia de um repositório para outro.

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

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

Essa regra bloqueia a leitura dos arquivos .env que correspondem ao padrão em cada raiz do espaço de trabalho fornecida pelo ambiente de execução ou definida pelo perfil. Use-a quando quiser manter as permissões normais de gravação no espaço de trabalho e impedir a leitura de arquivos de ambiente, segredos gerados ou outros arquivos semelhantes que contenham credenciais.

No Linux, no WSL e no Windows nativo com MXC ou elevated, o Codex lista os arquivos que correspondem aos padrões glob de bloqueio de leitura no início de cada processo executado no sandbox. Se um arquivo que corresponde ao padrão for criado depois, ele não entrará na lista de bloqueio desse processo. O processo poderá lê-lo se as demais permissões permitirem o acesso. Por exemplo, um shell, script, monitor de arquivos ou servidor de desenvolvimento de longa duração pode ler um arquivo .env correspondente criado após o início do processo.

Essa lista vale durante a execução do processo no sandbox. Seu alcance não se estende a toda a sessão do Codex. Ao iniciar um novo processo no sandbox, o Codex lista novamente as correspondências. Continuar usando um processo em execução não atualiza a lista de bloqueio dele. Não conte com um padrão glob para bloquear arquivos recém-criados nesse processo. Consulte Compatibilidade do MXC no Windows para conhecer as limitações específicas do Windows.

Os padrões glob com deny são aceitos como regras de bloqueio de leitura. Padrões glob com read ou write têm menor portabilidade entre os ambientes isolados do Linux, do WSL e do Windows nativo. Sempre que possível, prefira caminhos exatos ou regras de subárvore, como "docs/**" = "read".

No Linux, no WSL e no Windows nativo, um padrão ** de bloqueio de leitura sem limite de profundidade pode exigir uma expansão prévia limitada antes de iniciar o sandbox. Defina glob_scan_max_depth ao 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"

O valor de glob_scan_max_depth deve ser de pelo menos 1. Valores maiores fazem a varredura percorrer mais níveis antes de iniciar o sandbox, o que pode aumentar o trabalho de inicialização no Linux, no WSL e no Windows nativo. Se preferir não usar a expansão limitada, especifique as profundidades explicitamente com padrões como *.env, */*.env e */*/*.env.

Adicione raízes reutilizáveis do espaço de trabalho ao perfil quando as mesmas regras precisarem ser aplicadas além da raiz da sessão atual:

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

Quando esse perfil está ativo, o Codex aplica as regras de :workspace_roots às raízes do espaço de trabalho fornecidas pelo ambiente de execução da sessão atual e a cada raiz 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 independentes. 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 depende das duas configurações:

• Rede desativada: os comandos não podem acessar a rede, independentemente da configuração do proxy.
• Rede ativada, proxy desativado: os comandos têm acesso direto e irrestrito à rede. As regras de domínio do perfil de permissões não são aplicadas.
• Rede e proxy ativados: os comandos usam o proxy, que aplica as regras de domínio do perfil. Se não houver domínios permitidos, o proxy ativo bloqueará 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 ativo, o proxy de rede do sandbox escuta em endereços 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 as configurações de escuta nos valores padrão, a menos que esteja fazendo uma integração com um ambiente de execução específico. As chaves de rede dangerously_* permitem contornar restrições em 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 protege as redes locais e privadas por padrão contra ataques de DNS rebinding e acesso acidental a serviços locais. Para permitir intencionalmente um destino local especificado de forma literal, inclua o nome exato do host ou o endereço IP literal na lista de permissões:

[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 que estejam na lista de permissões e que resolvam 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 encaminhamento de sockets Unix pelo proxy permite abrir uma exceção local para ferramentas como o Docker. Use esse recurso com moderação:

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

Use deny para bloquear um caminho de socket, mesmo que uma entrada herdada permita o acesso. Os caminhos de socket bloqueados ficam fora da lista efetiva de permissões.

Quando os sockets Unix estiverem habilitados, mantenha o proxy escutando apenas em endereços de loopback.

Migrar das configurações antigas do sandbox

Os perfis de permissões substituem a combinação antiga de sandbox_mode e sandbox_workspace_write quando você quer definir o comportamento do sistema de arquivos e da rede em um único perfil reutilizável. Use apenas um dos dois sistemas por sessão.

Sugestões para começar:

• Para um fluxo de trabalho somente leitura, use o perfil predefinido :read-only ou defina um perfil personalizado que permita leitura somente onde for necessário.
• Para editar arquivos no espaço de trabalho, use o perfil predefinido :workspace ou defina um perfil personalizado que permita gravação por meio de :workspace_roots. Adicione apenas os caminhos temporários ou de cache adicionais que o fluxo de trabalho exigir.
• Para executar comandos locais sem restrições, use :danger-full-access somente quando quiser conceder o nível mais amplo de acesso local.

Os perfis definem as permissões locais padrão de uma sessão. Os requisitos gerenciados pela organização ainda podem impor restrições, e a configuração do usuário não deve ampliar o acesso além desses limites. Consulte Configuração gerenciada para conhecer as restrições de sistema de arquivos e de rede impostas pelo administrador.

Escopo e aplicação das regras

Acesso ao computador local com o Work na nuvem e política de ambiente

Verifique a política de cada ambiente em que o Work na nuvem usa o acesso ao computador local:

• Requisitos corporativos: Para o modo Work com acesso local e para os dots, as regras compatíveis da política Global regem o orquestrador compartilhado na nuvem quando a política gerenciada está habilitada. Os requisitos de execução local aplicáveis regem o computador conectado.
• Execução na nuvem: Os contêineres do Work na nuvem usam as políticas existentes do Work na nuvem.
• Ordem das políticas locais: Os requisitos de MDM e os requisitos legados de dispositivos gerenciados têm prioridade sobre a segurança de agentes. O arquivo de requisitos do sistema do dispositivo tem prioridade inferior à da segurança de agentes.
• Prioridade das políticas: A política de maior prioridade prevalece mesmo quando uma de menor prioridade é mais específica. Dentro de uma mesma política, as substituições de ambiente específicas de um sistema operacional têm prioridade sobre as que se aplicam a todos os sistemas operacionais. A política Global vem em seguida.

Alguns requisitos têm regras de mesclagem específicas por campo. Consulte Configuração gerenciada e a Referência de configuração para conhecer os campos compatíveis e os limites do ambiente de execução. Não presuma que o Work na nuvem oferece suporte aos perfis de permissões do Codex apresentados aqui.

Os perfis de permissões definem os limites da execução de comandos locais no sandbox. Use-os em conjunto com as políticas de aprovação e os controles separados da pesquisa na Web, dos conectores, dos servidores MCP, do navegador integrado, do Uso do computador e do Codex Cloud.

O que os perfis controlam

• Execução de comandos locais: Os perfis de permissões regem os comandos executados no sandbox do seu computador. Conectores, servidores MCP, recursos de navegador ou de uso do computador, configurações de ambiente do Codex Cloud e elevações de privilégios aprovadas têm controles próprios.
• Gravações no sistema de arquivos: Um perfil com permissão de gravação pode fazer 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. Outras ferramentas ou usuários poderão executar esses arquivos fora do contexto original do sandbox.
• Destinos do tráfego de saída: As regras de domínio de rede restringem os destinos do tráfego gerado pelos comandos no sandbox somente enquanto o proxy de rede está ativo. Elas não determinam se um destino permitido é confiável. Regras de permissão com curingas continuam tendo alcance amplo.
• Serviços locais: Um proxy de rede ativo bloqueia por padrão os destinos em redes locais e privadas. Incluir localhost, IPs privados ou sockets Unix na lista de permissões, ou definir allow_local_binding = true, abre 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 dentro do sandbox. Ele não aplica a lista de domínios permitidos do perfil aos seguintes recursos:

• Pesquisa na Web: A ferramenta de pesquisa hospedada usa configurações de acesso próprias. Para controlá-la, use web_search e, em clientes gerenciados, allowed_web_search_modes. A configuração tools.web_search.allowed_domains filtra os resultados da pesquisa e não interfere no acesso dos comandos à rede.
• Apps e conectores: As ferramentas que usam conectores têm conexões próprias no lado do serviço, permissões do espaço de trabalho e configurações do aplicativo ou da ferramenta.
• Servidores MCP: Os servidores MCP locais e remotos usam seus próprios processos ou meios de transporte. Controle-os com a configuração mcp_servers e as listas gerenciadas de servidores permitidos.
• Navegador e Uso do computador: A navegação e as ações de uso do computador têm controles próprios de recursos e aprovação.
• Tráfego de serviço do Codex: Solicitações a modelos, solicitações de autenticação e outras solicitações de serviço do cliente usam configurações separadas do cliente para HTTP e para o proxy do sistema.
• Codex Cloud: Essas tarefas usam as configurações de rede do próprio ambiente. O Codex Cloud (legado) tem configurações de acesso à internet separadas.

Para limitar esses recursos, configure cada um diretamente. A lista de destinos de rede permitidos para comandos não funciona como política de rede global para todas as ações que o Codex pode executar.

Como as restrições são aplicadas

• No macOS, o Codex usa perfis de sandbox do Seatbelt. Se o sandbox da plataforma não conseguir aplicar a política selecionada, o Codex se recusará a executar o comando, em vez de executá-lo silenciosamente fora do sandbox.
• No Linux e no WSL, o Codex usa bubblewrap e seccomp para aplicar as restrições do sistema de arquivos. A opção legada Landlock não consegue isolar os sockets Unix do App Server. Por isso, o Codex rejeita essa opção em políticas que restringem o sistema de arquivos. Desative features.use_legacy_landlock ao atualizar. Hosts que bloqueiam as operações necessárias do bubblewrap não conseguem executar comandos sob essas políticas.
• No Windows, o MXC usa isolamento de processos para aplicar as permissões do sistema de arquivos e da rede. Consulte Compatibilidade do MXC antes de habilitá-lo. A alternativa legada elevated usa contas de usuário dedicadas ao sandbox com privilégios reduzidos, limites de permissão no sistema de arquivos e regras de firewall. A alternativa legada unelevated oferece isolamento de rede mais fraco e não consegue aplicar todas as exceções que distinguem leitura de gravação. Por isso, o Codex rejeita as políticas incompatíveis. Use o WSL quando precisar do modelo de sandbox do Linux.

Orientações de uso

Escolha o perfil mais restritivo que ainda permita concluir a tarefa, especialmente ao conceder acesso 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 domínios permitidos

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 espaço de trabalho

O perfil de permissões a seguir permite que o Codex grave nas pastas do espaço de trabalho e bloqueia a leitura no restante do sistema de arquivos, com as poucas exceções determinadas por :minimal.

default_permissions = "workspace-only"

[permissions.workspace-only]
# By extending the :workspace profile, you get Codex's safeguards to ensure
# paths such as .git/, .agents/, .codex/, and .aws/ 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 espaço de trabalho sem acesso à 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 espaço de trabalho 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 quiser permitir o acesso à rede pública. Regras de bloqueio podem restringir o alcance de uma lista de permissões ampla.