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 atuais do Codex Cloud, consulte Ligar a serviços. Para o Codex Cloud (Legacy), 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 os caminhos .git, .agents, .codex e .aws da raiz da área de trabalho só de leitura, a menos que substitua explicitamente essas regras. 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.

Em Linux, WSL e Windows nativo com MXC ou elevated, as correspondências de padrões glob de negação de leitura são enumeradas quando cada processo em sandbox é iniciado. Os ficheiros correspondentes criados posteriormente não são adicionados à lista de negação desse processo e continuam legíveis se as restantes permissões permitirem o acesso. Por exemplo, uma shell, um script, um monitor de alterações ou um servidor de desenvolvimento em execução prolongada pode ler um ficheiro .env correspondente criado após o seu início.

Este retrato mantém-se durante a vida útil do processo em sandbox, e não durante toda a sessão do Codex. Iniciar um novo processo em sandbox através do Codex enumera as correspondências novamente; continuar a utilizar um processo já em execução não atualiza a sua lista de negação. Não confie num padrão glob para bloquear ficheiros recém-criados nesse processo em execução. Consulte Compatibilidade com MXC no Windows para conhecer as limitações específicas do Windows.

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 aumentar o trabalho de arranque no Linux, WSL e Windows nativo. Se preferir não utilizar a expansão limitada, indique 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 reassociaçã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

Acesso ao computador local com Work Cloud e política de ambiente

Reveja a política de cada ambiente em que é executado o acesso ao computador local com Work Cloud:

• Requisitos empresariais: Para Work com acesso local e dots, a política Global suportada rege o orquestrador partilhado na nuvem quando a política gerida está ativada; os requisitos de execução local aplicáveis regem o computador ligado.
• Execução na nuvem: Os contentores na nuvem do Work utilizam as políticas existentes do Work Cloud.
• Ordem das políticas locais: Os requisitos de MDM e os requisitos legados de dispositivos geridos têm prioridade sobre o Agent Security. O ficheiro de requisitos de sistema do dispositivo tem prioridade inferior à do Agent Security.
• Prioridade das políticas: Uma política de prioridade superior prevalece mesmo que uma política de prioridade inferior seja mais específica. Numa mesma política, as substituições de ambiente específicas do sistema operativo têm prioridade sobre as substituições de ambiente para todos os sistemas operativos, seguidas de Global.

Alguns requisitos têm regras de combinação específicas de cada campo. Consulte Configuração gerida e a Referência de configuração para conhecer os campos suportados e os limites de execução. Não pressuponha que o Work Cloud suporta os perfis de permissões do Codex apresentados aqui.

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, MCP servers, 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, MCP servers, 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 os resultados da pesquisa, não o acesso à rede dos comandos.
• Aplicações e conectores: As ferramentas baseadas em conectores utilizam as suas próprias ligações do lado do serviço, permissões do espaço de trabalho e definições de aplicação ou ferramenta.
• MCP servers: Os MCP servers 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 seus próprios controlos de funcionalidades e aprovação.
• Tráfego dos serviços do Codex: Os pedidos de modelos, autenticação e outros serviços do cliente utilizam as definições separadas de HTTP e de proxy do sistema do cliente.
• Codex Cloud: Estas tarefas utilizam as próprias definições de rede do respetivo ambiente. O Codex Cloud (Legacy) tem definições de acesso à Internet separadas.

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 fora da sandbox.
• No Linux e no WSL, o Codex utiliza bubblewrap e seccomp para aplicar restrições ao sistema de ficheiros. A opção legada Landlock não consegue isolar sockets Unix do app-server e é rejeitada em políticas com restrições ao sistema de ficheiros. Desative features.use_legacy_landlock ao atualizar. Os anfitriões que bloqueiam as operações necessárias do bubblewrap não conseguem executar estas políticas.
• No Windows, o MXC utiliza isolamento de processos para as permissões do sistema de ficheiros e de rede. Reveja a compatibilidade do MXC antes de o ativar. A alternativa legada elevated utiliza utilizadores de sandbox dedicados com menos privilégios, limites de permissões do sistema de ficheiros e regras de firewall. unelevated é uma alternativa legada com isolamento de rede mais fraco e não consegue impor todas as exceções com permissões de leitura/escrita separadas, pelo que as políticas não suportadas são recusadas. Utilize 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 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
# 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"

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.