Permissões

A definição gerida allowed_permission_profiles é a exceção: faz com que o Codex utilize perfis de permissões. Remova definições mais antigas, como sandbox_mode e [sandbox_workspace_write], antes de implementar uma lista de permissões de perfis gerida. Para uma implementação empresarial com versões mistas, pode manter o requisito gerido allowed_sandbox_modes como restrição temporária de compatibilidade até todos os clientes executarem o Codex 0.138.0 ou posterior.

Os perfis de permissões permitem aplicar limites de menor privilégio aos comandos locais que o Codex executa em seu nome. Um perfil é uma política com nome que combina regras do sistema de ficheiros, que definem o que os comandos podem ler ou escrever, com regras de rede, que definem os destinos aos quais os comandos podem aceder.

Utilize perfis para conceder ao Codex acesso suficiente para a conversa atual sem conceder acesso abrangente ao seu computador ou à rede. Por exemplo, um perfil só de leitura pode permitir que o Codex inspecione um projeto sem o editar, enquanto um perfil com capacidade de escrita pode limitar as edições às raízes selecionadas da área de trabalho.

Os perfis de permissões locais são suportados no macOS, Linux, WSL e Windows nativo. Consulte Âmbito e imposição para obter detalhes e ressalvas específicos de cada plataforma.

Para conhecer as definições de rede do Codex cloud, consulte Acesso à Internet.

Definir e selecionar um perfil

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

• :read-only mantém a execução de comandos locais só de leitura.
• :workspace permite escritas nas raízes ativas da área de trabalho e nos diretórios temporários do sistema.
• :danger-full-access remove as restrições da sandbox local e só deve ser utilizado quando esse acesso abrangente for intencional.

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

Os administradores empresariais podem definir perfis e restringir os perfis que os utilizadores podem selecionar através de requirements.toml gerido. Assim que allowed_permission_profiles estiver presente, os perfis omitidos são recusados, incluindo perfis incorporados omitidos e perfis adicionados em versões futuras do Codex. Consulte Controlar os perfis de permissões disponíveis para obter a configuração gerida recomendada.

Os perfis personalizados utilizam dois conceitos relacionados:

• [permissions.<name>.workspace_roots] adiciona diretórios concretos que devem contar como raízes da área de trabalho desse perfil.
• [permissions.<name>.filesystem.":workspace_roots"] define as regras do sistema de ficheiros que o Codex aplica em cada raiz efetiva da área de trabalho: as raízes da área de trabalho em tempo de execução da sessão atual e as raízes definidas pelo perfil acima.

Os perfis também utilizam 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 voltar a declarar todo o perfil.

Por exemplo, uma configuração ao nível da organização e uma configuração ao nível do utilizador podem ampliar 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 da área de trabalho participam no 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ê os caminhos mínimos de tempo de execução necessários às ferramentas comuns de desenvolvimento.
• Aplica as mesmas regras de raiz da área de trabalho à sessão atual e às raízes definidas pelo perfil.
• Mantém as definições adjacentes ao IDE, como .devcontainer/, só de leitura em cada raiz.
• Recusa ficheiros de ambiente correspondentes através de uma regra glob.
• Permite acesso à rede apenas através da política de domínios configurada.

Num perfil ativo, as regras de recusa mais restritas continuam em vigor mesmo quando um caminho mais abrangente pode ser lido ou escrito. Por exemplo, um perfil pode tornar as raízes da área de trabalho graváveis e, ainda assim, definir um caminho .env correspondente como deny.

Ampliar um perfil

Utilize extends quando um perfil for quase igual a um perfil incorporado ou a outro perfil com nome. Prefira ampliar um perfil incorporado em vez de começar do zero, para que as proteções de base sejam mantidas. Por exemplo, ampliar :workspace mantém o diretório .codex da raiz da área de trabalho só de leitura, a menos que o substitua explicitamente. Defina o perfil ascendente 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"

Este perfil começa com :workspace, mantém recusados os ficheiros .env correspondentes e permite pedidos a api.openai.com. Um perfil pode ampliar :read-only, :workspace ou outro perfil com nome. Não pode ampliar :danger-full-access; o Codex também rejeita perfis ascendentes desconhecidos e ciclos de herança.

Especificação da configuração

Permissões do sistema de ficheiros

As entradas do sistema de ficheiros utilizam read, write ou deny:

As entradas mais específicas substituem as entradas mais abrangentes. Quando duas entradas visam o mesmo caminho, deny tem precedência sobre write e write tem precedência sobre read.

Esta precedência permite que um perfil descreva primeiro uma área de trabalho abrangente e, em seguida, exclua ficheiros ou diretórios que devem permanecer ilegíveis:

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

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

Neste exemplo, a raiz da área de trabalho permanece gravável, .devcontainer/ permanece legível sem se tornar gravável e os ficheiros de ambiente correspondentes permanecem indisponíveis para comandos na sandbox.

Um caminho mais específico também pode reabrir uma subárvore mais restrita dentro de uma recusa mais abrangente:

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

Formas de caminho suportadas:

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

Utilize :root apenas quando um perfil precisar intencionalmente de uma cobertura de leitura abrangente:

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

Utilize entradas aninhadas em :workspace_roots para limitar o acesso a subcaminhos relativos à raiz da área 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 têm de permanecer dentro da respetiva raiz da área de trabalho. A travessia ascendente, como ../other-repo, é rejeitada.

Recusar leituras com caminhos exatos ou globs

Utilize deny para ficheiros ou subárvores que o Codex não deve ler, mesmo quando uma regra de perfil mais abrangente concede acesso nas proximidades. Os caminhos exatos são adequados para localizações estáveis, como ~/.ssh. Os padrões glob são mais adequados quando um perfil precisa de abranger uma família de ficheiros confidenciais cujas localizações exatas variam entre repositórios.

Quando um glob se encontra em :workspace_roots, o Codex interpreta-o relativamente a cada raiz efetiva da área de trabalho. Por exemplo:

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

Esta regra recusa leituras de ficheiros .env correspondentes encontrados sob cada raiz da área de trabalho em tempo de execução ou definida pelo perfil. Utilize-a quando pretender preservar as escritas normais na área de trabalho e, simultaneamente, manter ilegíveis ficheiros de ambiente, segredos gerados ou ficheiros semelhantes que contenham credenciais.

Os padrões glob deny são suportados como regras de recusa de leitura. Os globs read ou write são menos portáveis na sandbox do Linux, WSL e Windows nativo, pelo que deve preferir caminhos exatos ou regras de subárvore, como "docs/**" = "read", quando possível.

No Linux, WSL e Windows nativo, um padrão de recusa de leitura ** sem limites pode precisar de pré-expansão limitada antes de a sandbox arrancar. Defina glob_scan_max_depth quando utilizar um padrão sem limites, como "**/*.env" = "deny":

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

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

glob_scan_max_depth tem de ser, pelo menos, 1. Valores mais elevados analisam a maior profundidade antes do arranque da sandbox, o que pode adicionar trabalho ao arranque no Linux, WSL e Windows nativo. Se preferir não utilizar a expansão limitada, enumere profundidades explícitas, como *.env, */*.env e */*/*.env.

Adicione raízes da área de trabalho reutilizáveis ao perfil quando as mesmas regras se devam aplicar a mais do que a 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 :workspace_roots às raízes da área de trabalho em tempo de execução da sessão atual e a cada raiz da área de trabalho ativada definida pelo perfil.

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

Permissões de rede

O acesso à rede e a filtragem da rede são definições distintas. Defina permissions.<name>.network.enabled = true para permitir que os comandos acedam à rede e ative features.network_proxy para impor 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 de ambas as definições:

• Rede desativada: os comandos não podem aceder à rede, independentemente da funcionalidade de 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 impostas.
• Rede ativada, proxy ativado: os comandos utilizam o proxy, que impõe as regras de domínio do perfil. Se o proxy ativo não tiver domínios permitidos, bloqueia os destinos externos.

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

Quando está ativo, o proxy de sandbox de rede vincula-se, por predefinição, a serviços de escuta locais:

[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 estas definições de serviço de escuta nos valores predefinidos, a menos que esteja a integrar com um ambiente de execução específico. As chaves de rede dangerously_* são vias de escape para ambientes especializados e não devem ser utilizadas no desenvolvimento local normal.

Redes locais e privadas

Quando o proxy de rede está ativo, o Codex aplica, por predefinição, uma proteção da rede local/privada como defesa contra a revinculação de DNS e o acesso acidental a serviços locais. Para permitir intencionalmente um destino local literal, inclua na lista de permissões o anfitrião ou literal de IP exato:

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

Defina allow_local_binding = true apenas quando o perfil tiver de aceder a nomes de anfitrião incluídos na lista de permissões 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 proxy de sockets Unix é uma via de escape local para ferramentas como o Docker. Utilize-o com moderação:

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

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

Quando os sockets Unix estiverem ativados, mantenha os serviços de escuta do proxy vinculados a endereços de loopback.

Migrar das definições de sandbox mais antigas

Os perfis de permissões substituem a combinação mais antiga de sandbox_mode e sandbox_workspace_write quando pretender que um único perfil reutilizável descreva o comportamento do sistema de ficheiros e da rede. Utilize um sistema ou o outro numa sessão, mas não ambos.

Pontos de partida sugeridos:

• Para um fluxo de trabalho só de leitura, utilize o perfil incorporado :read-only ou defina um perfil personalizado com acesso de leitura apenas onde for necessário.
• Para editar a área de trabalho, utilize o perfil incorporado :workspace ou defina um perfil personalizado que escreva através de :workspace_roots e adicione apenas os caminhos adicionais de ficheiros temporários ou de cache necessários ao fluxo de trabalho.
• Para execução local irrestrita, utilize :danger-full-access apenas quando pretender intencionalmente o modelo de acesso local mais abrangente.

Os perfis descrevem a postura local predefinida de uma sessão. Os requisitos geridos pela organização ainda podem adicionar restrições que a configuração do utilizador não deve ampliar. Consulte Configuração gerida para conhecer as restrições do sistema de ficheiros e da rede impostas pelo administrador.

Âmbito e imposição

Os perfis de permissões definem os limites da execução local de comandos na sandbox. Utilize-os em conjunto com políticas de aprovação e os controlos distintos para pesquisa na Web, conectores, servidores MCP, o navegador incorporado, Computer Use e Codex cloud.

O que os perfis controlam

• Execução local de comandos: os perfis de permissões regem os comandos na sandbox executados no seu computador. Os conectores, servidores MCP, superfícies de navegador ou de utilização do computador, definições do ambiente Codex cloud e escalamentos aprovados utilizam os respetivos controlos.
• Escritas no sistema de ficheiros: um perfil com capacidade de escrita pode criar alterações persistentes. Trate como confidenciais as escritas em scripts, etapas de compilação, hooks do gestor de pacotes, ficheiros de arranque da shell e diretórios partilhados, pois outras ferramentas ou outros utilizadores podem executar esses ficheiros posteriormente fora do contexto original da sandbox.
• Destinos de saída: as regras de domínio de rede restringem os destinos do tráfego dos comandos na sandbox apenas enquanto o proxy de rede está ativo. Não determinam se um destino permitido é fidedigno, e as regras de permissão com caracteres universais continuam a ser abrangentes.
• Serviços locais: um proxy de rede ativo bloqueia, por predefinição, destinos de 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 da sandbox. Não aplica a lista de permissões de domínios do perfil a:

• Pesquisa na Web: a ferramenta de pesquisa alojada utiliza as suas próprias definições de acesso. Utilize web_search e, para clientes geridos, allowed_web_search_modes para a controlar. tools.web_search.allowed_domains filtra resultados de pesquisa, não o acesso dos comandos à rede.
• Aplicações e conectores: as ferramentas suportadas por conectores utilizam as suas próprias ligações do lado do serviço, permissões da área de trabalho e definições da aplicação ou da ferramenta.
• Servidores MCP: os servidores MCP locais e remotos utilizam o seu próprio processo ou transporte. Controle-os com a configuração mcp_servers e listas de permissões de servidores geridas.
• Navegador e Computer Use: a navegação no navegador e as ações de utilização do computador utilizam os respetivos controlos de funcionalidades e de aprovação.
• Tráfego do serviço Codex: os pedidos de modelo, autenticação e outros serviços do cliente utilizam as definições HTTP e de proxy do sistema distintas do cliente.
• Codex cloud: estas tarefas utilizam as próprias definições de acesso à Internet do respetivo ambiente.

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

Como funciona a imposição

• No macOS, o Codex utiliza perfis de sandbox Seatbelt. Se a política selecionada não puder ser imposta pela sandbox da plataforma, o Codex recusa-se a executar o comando, em vez de o executar silenciosamente sem sandbox.
• No Linux e WSL, o Codex utiliza bubblewrap e seccomp, com Landlock disponível para caminhos de contingência de compatibilidade. O caminho de imposição mais robusto depende dos espaços de nomes do utilizador e do suporte do kernel; anfitriões de contentores restritos podem forçar caminhos de compatibilidade, e as políticas divididas não suportadas são recusadas.
• No Windows nativo, a sandbox elevated é a mais robusta, pois pode utilizar utilizadores de sandbox dedicados e com privilégios inferiores, limites de permissões do sistema de ficheiros e regras de firewall. A sandbox unelevated é uma contingência com isolamento de rede mais fraco e não consegue impor todas as exclusões com divisão entre leitura e escrita, pelo que as políticas não suportadas são recusadas. Utilize 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 escritas ou acesso de saída à rede. Mantenha a política de aprovação, o tratamento de segredos e as regras de permissão alinhados com esse nível de acesso.

Perfis comuns

Só de 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 ficheiros limitado à área de trabalho

Segue-se um exemplo de um perfil de permissões que torna as pastas da sua área de trabalho graváveis pelo Codex, recusando simultaneamente leituras no resto do sistema de ficheiros (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"

Escrita na área de trabalho 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

Escrita na área 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"

Utilize a regra de permissão global "*" apenas quando pretender permitir acesso à rede pública. As regras de recusa podem restringir uma lista de permissões abrangente.