Sandbox

O sandbox é o limite que permite ao agente atuar de forma autónoma sem lhe dar acesso irrestrito à sua máquina. Quando um chat local executa comandos na aplicação ChatGPT para computador, na Codex CLI ou na extensão para IDE, esses comandos são executados num ambiente restrito, em vez de serem executados com acesso total por predefinição.

Esse ambiente define o que o agente pode fazer autonomamente, como os ficheiros que pode modificar e se os comandos podem utilizar a rede. Quando uma tarefa permanece dentro desses limites, o agente pode continuar sem parar para pedir confirmação. Quando precisa de os ultrapassar, o fluxo de aprovação assume o controlo.

O que faz o sandbox

O sandbox aplica-se aos comandos iniciados, e não apenas às operações de ficheiros incorporadas. Se o agente executar ferramentas como git, gestores de pacotes ou executores de testes, esses comandos herdam os mesmos limites do sandbox.

O Codex utiliza mecanismos de imposição nativos da plataforma em cada sistema operativo. A implementação difere entre macOS, Linux, WSL2 e Windows nativo, mas o princípio é o mesmo em todas as interfaces: proporcionar ao agente um espaço delimitado onde possa trabalhar, para que as tarefas de rotina sejam executadas autonomamente dentro de limites claros.

Por que é importante

O sandbox reduz o cansaço causado pelas aprovações. Em vez de lhe pedir que confirme todos os comandos de baixo risco, o agente pode ler ficheiros, fazer alterações e executar comandos de rotina do projeto dentro do limite que já aprovou.

Também lhe proporciona um modelo de confiança mais claro para o trabalho realizado por agentes. Não está apenas a confiar nas intenções do agente; está a confiar que o agente opera dentro de limites impostos. Isto facilita deixar o agente trabalhar de forma independente, sabendo ainda assim quando irá parar e pedir ajuda.

Introdução

O modo de permissões predefinido aplica o sandboxing automaticamente.

Pré-requisitos

No macOS, o sandboxing funciona sem configuração adicional através da framework Seatbelt incorporada.

No Windows, o Codex utiliza o sandbox do Windows nativo quando a execução ocorre no PowerShell e a implementação do sandbox do Linux quando a execução ocorre no WSL2.

No Linux e WSL2, instale primeiro bubblewrap com o seu gestor de pacotes:

Ubuntu/Debian

sudo apt install bubblewrap

Fedora

sudo dnf install bubblewrap

O Codex utiliza o primeiro executável bwrap que encontra em PATH. Se não estiver disponível nenhum executável bwrap, o Codex recorre a um utilitário incluído, mas esse utilitário requer suporte para a criação de espaços de nomes de utilizador sem privilégios. A instalação do pacote da distribuição que fornece bwrap mantém esta configuração fiável.

O Codex apresenta um aviso no arranque quando bwrap está em falta ou quando o utilitário não consegue criar o espaço de nomes de utilizador necessário. Nas distribuições que restringem esta definição do AppArmor, dê preferência ao carregamento do perfil AppArmor bwrap para que bwrap possa continuar a funcionar sem desativar globalmente a restrição.

Como funcionam as permissões

Utilize o controlo de permissões da sua interface para alterar a forma como o Codex trata as ações locais.

As aprovações determinam quando o Codex faz uma pausa antes de uma ação, enquanto o sandbox determina a que ficheiros e recursos de rede os comandos podem aceder. Quando uma aprovação oferece diferentes âmbitos, como aprovar uma vez ou durante a sessão, escolha o âmbito mais restrito que permita à tarefa continuar. Mantenha o limite do projeto como predefinição; utilize projetos ou árvores de trabalho separados em vez de alargar o acesso a repositórios não relacionados.

Na aplicação ChatGPT para computador, utilize o controlo de permissões por baixo da caixa de composição. Dependendo da sua configuração, o menu pode incluir Pedir aprovação, Aprovar por mim para pedidos de aprovação elegíveis, Acesso total e perfis de permissões personalizados ou com nome.

Configurar predefinições

Para começar sempre com o mesmo comportamento, defina as predefinições em config.toml. Noções básicas de configuração explica como funciona, e a Referência de configuração documenta as chaves exatas de sandbox_mode, approval_policy, approvals_reviewer e sandbox_workspace_write.writable_roots. Utilize essas definições para decidir quanta autonomia o agente recebe por predefinição, em que diretórios pode escrever, quando deve parar para pedir aprovação e quem analisa os pedidos de aprovação elegíveis.

Em termos gerais, os modos de sandbox comuns são:

• read-only: o agente pode inspecionar ficheiros, mas não pode editar ficheiros nem executar comandos sem aprovação.
• workspace-write: o agente pode ler ficheiros, editar dentro do espaço de trabalho e executar comandos locais de rotina dentro desse limite. Este é o modo predefinido de baixa fricção para trabalho local.
• danger-full-access: o agente é executado sem restrições de sandbox. Isto remove os limites do sistema de ficheiros e da rede e só deve ser utilizado quando pretender que o agente atue com acesso total.

As políticas de aprovação comuns são:

• untrusted: o agente pergunta antes de executar comandos que não fazem parte do seu conjunto de confiança.
• on-request: o agente trabalha dentro do sandbox por predefinição e pergunta quando precisa de ultrapassar esse limite.
• never: o agente não para para apresentar pedidos de aprovação.

Quando as aprovações são interativas, também pode escolher quem as analisa através de approvals_reviewer:

• user: os pedidos de aprovação são apresentados ao utilizador. Esta é a predefinição.
• auto_review: os pedidos de aprovação elegíveis são enviados para um agente revisor (consulte revisão automática).

Acesso total significa utilizar sandbox_mode = "danger-full-access" em conjunto com approval_policy = "never". Em contrapartida, a predefinição de automatização local de menor risco é sandbox_mode = "workspace-write" em conjunto com approval_policy = "on-request", ou os sinalizadores correspondentes da CLI --sandbox workspace-write --ask-for-approval on-request. Em seguida, pode manter approvals_reviewer = "user" para aprovações manuais ou definir approvals_reviewer = "auto_review" para revisão automática das aprovações.

Se precisar que o agente trabalhe em mais do que um diretório, as raízes com permissão de escrita permitem alargar os locais que pode modificar sem remover totalmente o sandbox. Se precisar de um limite de confiança mais amplo ou mais restrito, ajuste o modo de sandbox predefinido e a política de aprovação, em vez de depender de exceções pontuais.

Quando um fluxo de trabalho precisar de uma exceção específica, utilize regras. As regras permitem autorizar, solicitar aprovação ou proibir prefixos de comandos fora do sandbox, o que é frequentemente mais adequado do que alargar o acesso de forma abrangente. Para pontos de entrada de definições específicos do IDE, consulte Definições da extensão Codex para IDE.

A revisão automática, quando disponível, não altera o limite do sandbox. É uma opção possível de approvals_reviewer para pedidos de aprovação nesse limite, como escalamentos do sandbox, acesso à rede bloqueado ou chamadas de ferramentas com efeitos secundários que continuam a exigir aprovação. As ações já permitidas dentro do sandbox são executadas sem revisão adicional. Para obter informações sobre o ciclo de vida do revisor, os tipos de acionadores, a semântica de recusa e os detalhes de configuração, consulte revisão automática.

Os detalhes das plataformas encontram-se na documentação específica de cada plataforma. Para obter informações sobre a configuração, o comportamento e a resolução de problemas do Windows nativo, consulte Windows. Para conhecer os requisitos de administração e as restrições ao nível da organização relativas ao sandboxing e às aprovações, consulte Aprovações e segurança dos agentes.