Configuração gerenciada

A configuração gerenciada controla o comportamento do ambiente de execução local para as capacidades abrangidas no aplicativo do ChatGPT para desktop, na Codex CLI e na extensão para IDE, conforme o suporte de cada cliente. Os requisitos compatíveis podem variar conforme o cliente e a versão. A configuração gerenciada não concede acesso ao workspace do ChatGPT, não atribui licenças nem substitui o controle de acesso baseado em funções (RBAC) do workspace. Consulte Funções e permissões do workspace para saber sobre o acesso aos recursos do workspace e esta página para saber sobre a política do ambiente de execução local.

Os administradores empresariais podem controlar o comportamento dos clientes locais compatíveis de duas maneiras:

• Requisitos: restrições impostas pelos administradores que os usuários não podem substituir.
• Valores padrão gerenciados: valores iniciais aplicados quando um cliente compatível é iniciado. Os usuários ainda podem alterar as configurações durante uma execução; o cliente reaplica os valores padrão gerenciados na próxima inicialização.

Requisitos impostos pelos administradores (requirements.toml)

Os requisitos restringem configurações sensíveis à segurança (política de aprovação, revisor de aprovações, política de revisão automática, modo de sandbox, perfis de permissão, modo de pesquisa na Web, ganchos gerenciados, quais servidores MCP os usuários podem habilitar e quais fontes de marketplace de plug-ins configuradas pelos usuários eles podem adicionar, usar para instalar plug-ins ou atualizar). Ao resolver a configuração (por exemplo, com base em config.toml, arquivos de perfil ou substituições de configuração da CLI), se um valor entrar em conflito com uma regra imposta, o cliente local usará um valor compatível e notificará o usuário. Se você configurar uma lista de permissões em mcp_servers, o cliente só habilitará um servidor MCP quando seu nome e sua identidade corresponderem a uma entrada aprovada; caso contrário, o cliente o desabilitará.

Os requisitos também podem restringir sinalizadores de recursos por meio da tabela [features] em requirements.toml. Os recursos nem sempre são sensíveis à segurança, mas as empresas podem fixar valores, se desejarem. As chaves omitidas permanecem sem restrições.

No Codex 0.138.0 ou posterior, prefira perfis de permissão com allowed_permission_profiles e o valor gerenciado de default_permissions. Use allowed_sandbox_modes somente em implantações legadas que ainda configurem sandbox_mode.

Para conferir a lista exata de chaves, consulte a seção requirements.toml na Referência de configuração.

Locais e precedência

Cada cliente local compatível combina os requisitos da menor para a maior precedência:

1. O requirements.toml do sistema (/etc/codex/requirements.toml em sistemas Unix, incluindo Linux e macOS, ou %ProgramData%\OpenAI\Codex\requirements.toml no Windows).
2. Requisitos gerenciados pela empresa fornecidos no pacote de configuração da nuvem.
3. Campos legados de managed_config.toml que o cliente local reinterpreta como requisitos.
4. Preferências gerenciadas do macOS (MDM) fornecidas por meio de com.openai.codex:requirements_toml_base64.

As camadas de maior precedência substituem os valores escalares e de lista comuns das camadas de menor precedência. As tabelas são mescladas por chave, enquanto requisitos como regras, ganchos e restrições do sistema de arquivos têm um comportamento de composição específico de cada campo. Consulte a referência de requirements.toml para verificar o esquema atual, em vez de presumir que todos os campos sejam mesclados da mesma forma.

Para manter a compatibilidade retroativa, os clientes locais compatíveis reinterpretam os campos legados approval_policy, approvals_reviewer e sandbox_mode como requisitos. Essa conversão adiciona opções de compatibilidade quando necessário; use requirements.toml para listas de permissões explícitas.

Requisitos gerenciados na nuvem

Quando um usuário faz login com o ChatGPT em um plano compatível, os clientes locais compatíveis podem receber requisitos impostos pelos administradores associados ao workspace. Esse é um canal de distribuição de políticas compatíveis com requirements.toml. Ele não concede acesso ao workspace nem substitui o RBAC do workspace. Os requisitos de autenticação devem ser gerenciados localmente.

Abra Configuração gerenciada para criar e atribuir requisitos gerenciados na nuvem. Por exemplo, esta política limita as opções de aprovação e sandbox e solicita aprovação antes da execução de um ponto de entrada de shell compatível:

allowed_approval_policies = ["on-request"]
allowed_sandbox_modes = ["read-only", "workspace-write"]

[rules]
prefix_rules = [
  { pattern = [{ any_of = ["bash", "sh", "zsh"] }], decision = "prompt", justification = "Require explicit approval for shell entry points" },
]

Confirme se todas as versões dos clientes gerenciados oferecem suporte às chaves selecionadas e teste a política com um pequeno grupo antes de atribuí-la a toda a organização. Consulte a referência de configuração para verificar o esquema atual e a interface de administração para verificar o comportamento atual de atribuição.

O serviço seleciona as camadas de requisitos gerenciados pela empresa que se aplicam à identidade conectada. O cliente local avalia essas camadas junto com as outras fontes de requisitos descritas em Locais e precedência. Use a interface de administração atual para criar e atribuir requisitos no workspace. Não dependa de uma cópia do algoritmo de correspondência de grupos; o serviço de administração controla esse comportamento e pode alterá-lo independentemente do formato dos requisitos locais.

Para conferir as chaves compatíveis e exemplos, consulte Exemplo de requirements.toml e a referência de requirements.toml.

Como os clientes locais aplicam os requisitos gerenciados na nuvem

Quando um usuário inicia um cliente local compatível e faz login com o ChatGPT em um plano compatível, o cliente primeiro verifica se há uma entrada de cache válida que corresponda à identidade. Se não houver uma entrada válida disponível, o cliente busca o pacote aplicável, com novas tentativas, e grava uma entrada de cache assinada em caso de sucesso. Se a solicitação falhar ou exceder o tempo limite e não houver um cache válido disponível, o carregamento do pacote de configuração da nuvem retornará um erro, em vez de iniciar silenciosamente sem a camada de requisitos gerenciados na nuvem.

Após resolver o cache, o cliente combina os requisitos da nuvem com as outras camadas de requisitos descritas acima. Uma atualização em segundo plano pode atualizar o cache para uma inicialização posterior; ela não substitui os requisitos já carregados no processo atual.

Confirme a experiência dos administradores e funcionários

Designe uma pessoa responsável por cada política gerenciada, registre quais usuários ou grupos devem recebê-la e documente a justificativa de negócio para cada restrição de sistema de arquivos, rede, aprovação ou perfil de permissão.

Antes de ampliar a implantação, teste um fluxo de trabalho aprovado e outro intencionalmente proibido com um usuário representativo. Verifique as configurações efetivas no cliente compatível, em vez de presumir que uma função ou um grupo do workspace, por si só, impõe a restrição local.

Gerencie a autenticação localmente

Defina allowed_login_methods, allowed_chatgpt_workspaces, cli_auth_credentials_store e chatgpt_base_url no arquivo requirements.toml do sistema local ou nos requisitos de MDM do macOS. O Codex ignora esses quatro campos nos requisitos gerenciados na nuvem. Os requisitos locais de autenticação são aplicados antes do carregamento das credenciais e antes de o Codex obter a política da nuvem.

Para exigir o login com o ChatGPT em um workspace aprovado e armazenar as credenciais no repositório de credenciais do sistema operacional, use:

allowed_login_methods = ["chatgpt"]
allowed_chatgpt_workspaces = ["00000000-0000-0000-0000-000000000000"]
cli_auth_credentials_store = "keyring"

allowed_login_methods aceita chatgpt, api ou ambos. Se omitida, essa configuração não restringe os métodos de login. Se definida, a lista deve conter pelo menos um método. api permite a autenticação por API, incluindo Amazon Bedrock. A restrição de workspace também se aplica aos tokens de acesso do Codex.

Os valores de forced_login_method e forced_chatgpt_workspace_id configurados pelo usuário devem seguir os requisitos. Quando um usuário seleciona um workspace, ele também deve constar na lista gerenciada de workspaces permitidos. Se nenhum workspace corresponder à lista, o login com o ChatGPT ficará indisponível. A autenticação por API continuará disponível quando permitida. Se nenhum método de login estiver disponível, o Codex se recusará a iniciar.

Consulte a referência de requisitos para saber sobre os modos de armazenamento de credenciais e a configuração da URL do serviço.

Exemplo de requirements.toml

Este exemplo bloqueia --ask-for-approval never e --sandbox danger-full-access (incluindo --yolo):

allowed_approval_policies = ["untrusted", "on-request"]
allowed_sandbox_modes = ["read-only", "workspace-write"]

Desative as capturas do app

Para desativar as capturas do app para usuários gerenciados, defina o requisito allow_appshots no nível superior:

allow_appshots = false

Onde as capturas do app estão disponíveis, allow_appshots = false as desativa. Se você omitir a chave, os requisitos não restringirão as capturas do app, e as verificações normais de disponibilidade do produto serão aplicadas. Os clientes do App Server que leem os requisitos efetivos por meio de configRequirements/read recebem a mesma restrição no campo allowAppshots; omitir allowAppshots ou defini-lo como null não desativa as capturas do app.

Desative o controle remoto de dispositivos

Para desativar o controle remoto de dispositivos para usuários gerenciados, defina o requisito allow_remote_control no nível superior:

allow_remote_control = false

Onde há suporte ao controle remoto de dispositivos, allow_remote_control = false o desativa. Se você omitir a chave, os requisitos não restringirão o controle remoto de dispositivos, e as verificações normais de disponibilidade do produto serão aplicadas. Esse requisito não desativa as conexões remotas por SSH.

Controle os perfis de permissão disponíveis

Use allowed_permission_profiles para controlar quais perfis de permissão integrados e personalizados os usuários podem selecionar. Essa é a contraparte de allowed_sandbox_modes para perfis de permissão; use a lista de permissões que corresponde à forma como seus usuários selecionam as permissões.

As listas de perfis de permissão permitidos exigem Codex 0.138.0 ou posterior. O Codex 0.137.0 e versões anteriores ignoram allowed_permission_profiles e o valor gerenciado de default_permissions.

Use os exemplos de perfis de permissão abaixo somente depois que todos os clientes gerenciados estiverem executando uma versão compatível. Não implante perfis personalizados gerenciados até que a atualização de todos os clientes esteja concluída.

Quando presente, a tabela é a lista completa de perfis permitidos. Ela permite os perfis definidos como true e bloqueia os perfis omitidos ou definidos como false, incluindo perfis integrados adicionados em versões futuras do Codex.

Permita os perfis padrão

Esta política permite acesso somente leitura e acesso ao workspace, mas não acesso completo:

default_permissions = ":workspace"

[allowed_permission_profiles]
":read-only" = true
":workspace" = true
# ":danger-full-access" is omitted, so it is denied.

Adicione um padrão gerenciado de privilégio mínimo

Os administradores podem definir um perfil personalizado na mesma fonte de requisitos. Use nomes de perfil específicos da organização que não entrem em conflito com nomes na configuração carregada dos usuários. Os nomes personalizados não podem começar com : nem usar o nome reservado filesystem.

Não implante perfis personalizados gerenciados em clientes que executam Codex 0.137.0 ou anterior. Esses clientes reconhecem a tabela de perfis, mas não o valor padrão gerenciado que seleciona o perfil.

Por exemplo:

default_permissions = "acme_review_only"

[allowed_permission_profiles]
":read-only" = true
":workspace" = true
acme_review_only = true
# ":danger-full-access" is intentionally omitted, so it is denied.

[permissions.acme_review_only]
description = "Review code without modifying the workspace."
extends = ":read-only"

Permita apenas perfis definidos pela empresa

Omita todos os perfis integrados quando os usuários só puderem selecionar perfis definidos pelos administradores:

default_permissions = "acme_workspace"

[allowed_permission_profiles]
acme_workspace = true

[permissions.acme_workspace]
description = "Workspace access with sensitive files denied."
extends = ":workspace"

[permissions.acme_workspace.filesystem]
glob_scan_max_depth = 3

[permissions.acme_workspace.filesystem.":workspace_roots"]
"**/*.env" = "deny"

O perfil personalizado pode estender :workspace, mesmo que os usuários não possam selecionar o perfil integrado :workspace diretamente.

Desative um perfil permitido por outra fonte

As listas de permissões são combinadas pelo nome do perfil. Como os requisitos da nuvem têm precedência maior que os requisitos do sistema, os requisitos da nuvem podem usar false para desativar um perfil permitido pelo arquivo do sistema.

Requisitos da nuvem:

default_permissions = ":read-only"

[allowed_permission_profiles]
":read-only" = true
":workspace" = false

Requisitos do sistema:

[allowed_permission_profiles]
":read-only" = true
":workspace" = true  # Not honored because cloud requirements set this to false.

Defina default_permissions explicitamente como um perfil permitido. Se for omitido, o ambiente de execução local usará :workspace como padrão somente quando tanto :workspace quanto :read-only forem explicitamente permitidos. Quando allowed_permission_profiles estiver ausente, os requisitos gerenciados não restringirão quais nomes de perfil os usuários podem selecionar. Cada entrada deve nomear um perfil integrado ou um perfil personalizado definido em uma configuração ou fonte de requisitos carregada. Defina perfis personalizados nos requisitos gerenciados para controlar seu comportamento de forma centralizada.

Substituir requisitos de sandbox por host

Use [[remote_sandbox_config]] quando uma política gerenciada precisar aplicar requisitos de sandbox diferentes em hosts diferentes. Por exemplo, você pode manter um padrão mais restritivo para notebooks e permitir gravações no workspace em máquinas de desenvolvimento ou executores de CI que correspondam aos padrões. Atualmente, as entradas específicas por host substituem apenas allowed_sandbox_modes:

allowed_sandbox_modes = ["read-only"]

[[remote_sandbox_config]]
hostname_patterns = ["*.devbox.example.com", "runner-??.ci.example.com"]
allowed_sandbox_modes = ["read-only", "workspace-write"]

O ambiente de execução local compara cada entrada de hostname_patterns com o nome do host que consegue resolver. Ele dá preferência ao nome de domínio totalmente qualificado quando disponível e, caso contrário, usa o nome local do host. A correspondência não diferencia maiúsculas de minúsculas; * corresponde a qualquer sequência de caracteres, e ? corresponde a um caractere.

A primeira entrada de [[remote_sandbox_config]] correspondente prevalece dentro da mesma fonte de requisitos. Se nenhuma entrada corresponder, o ambiente de execução local mantém allowed_sandbox_modes do nível superior. A correspondência do nome do host serve apenas para selecionar a política; não a trate como prova autenticada da identidade do dispositivo.

Você também pode restringir o modo de pesquisa na Web:

allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed

allowed_web_search_modes = [] permite apenas "disabled". Por exemplo, allowed_web_search_modes = ["cached"] impede a pesquisa na Web em tempo real mesmo em sessões danger-full-access.

Configurar requisitos de acesso à rede

Use [experimental_network] em requirements.toml quando os administradores precisarem definir os requisitos de acesso à rede de forma centralizada. Esses requisitos são independentes da opção features.network_proxy do usuário: eles podem configurar a rede do sandbox sem essa flag de recurso, mas não concedem acesso à rede aos comandos quando o sandbox ativo mantém a rede desativada. Defina experimental_network.enabled = true para ativar o proxy gerenciado; as regras de domínio por si só não ativam o proxy.

[experimental_network]
enabled = true
managed_allowed_domains_only = true

[experimental_network.domains]
"api.openai.com" = "allow"
"**.example.com" = "allow"
"blocked.example.com" = "deny"
"**.exfil.example.com" = "deny"

Use experimental_network.managed_allowed_domains_only = true somente quando você também definir entradas "allow" controladas pelo administrador em [experimental_network.domains] e quiser que essas regras sejam exclusivas. Se o valor for true sem regras gerenciadas de permissão, as regras de permissão de domínio adicionadas pelo usuário deixam de ter efeito. Não combine o mapa canônico domains com as listas legadas allowed_domains ou denied_domains.

*.example.com corresponde apenas a subdomínios. **.example.com corresponde ao domínio raiz e aos seus subdomínios. Uma regra de negação correspondente prevalece sobre uma regra de permissão.

A sintaxe de domínio, as regras para destinos locais/privados, a precedência de negação sobre permissão e as limitações de DNS rebinding são as mesmas do comportamento de rede do sandbox descrito em Aprovações do agente e segurança.

O proxy roteia comandos locais executados dentro do sandbox. As ferramentas de navegador também verificam as negações de rede gerenciadas e as listas exclusivas de permissões antes de acessar uma origem; essa é uma verificação de política separada, que não roteia o tráfego do navegador pelo proxy de comandos. O proxy não filtra pesquisa na Web, aplicativos e conectores, servidores MCP, tráfego de aplicativos nativos, solicitações ao serviço Codex nem tráfego do Codex Cloud. Use os controles de cada interface:

• Use allowed_web_search_modes para restringir a pesquisa na Web.
• Use features.apps = false para desabilitar integrações de aplicativos e conectores, e features.plugins = false para desabilitar plug-ins onde houver suporte.
• Use a lista gerenciada de aprovados mcp_servers para restringir os servidores MCP.
• Use requisitos de recursos como browser_use, in_app_browser e computer_use para restringir as capacidades do navegador e de Uso do computador.
• Configure o acesso à rede do Codex Cloud nas configurações do ambiente de nuvem.

Uma lista de domínios permitidos para comandos não substitui esses controles específicos de cada capacidade.

Controlar o navegador e o Uso do computador

Use as tabelas [browser_use] e [computer_use] em requirements.toml para restringir os clientes para desktop compatíveis. Valide a política nas versões dos clientes e nos sistemas operacionais da sua implantação. Uma regra de permissão configurada não instala um plug-in, não concede uma permissão do sistema operacional nem aprova uma ação que ainda exige revisão.

Para o acesso pelo navegador, configure uma política de origem. Uma origem inclui o esquema, o host e, opcionalmente, a porta, como https://example.com ou https://*.example.com:8443. Não inclua caminho, consulta ou fragmento. Diferentemente das regras de domínio para a rede de comandos, as regras de origem do navegador distinguem HTTP de HTTPS e verificam a correspondência da porta.

Este exemplo restringe o acesso pelo navegador a um site aprovado e impede uploads e acesso completo ao Chrome DevTools Protocol (CDP) nesse site:

[browser_use]
allow_history_access = false
allow_global_persistent_approval = false

[browser_use.default_origin_policy]
access = "deny"

[browser_use.origins."https://example.com"]
access = "allow"
uploads = "deny"
downloads = "allow"
full_cdp_access = "deny"
persistent_approval = false
access_approval_lifetime = "turn"

As regras de origem correspondentes são resolvidas por campo. Uma negação correspondente prevalece; caso contrário, a política de origem padrão fornece os campos que as regras correspondentes não especificam. A configuração local pode adicionar restrições, mas não pode flexibilizar uma negação gerenciada. As negações de rede e as listas exclusivas de permissões de rede gerenciadas continuam se aplicando.

Defina browser_use.disable_auto_review = true para desabilitar a revisão automática de aprovações para ações do navegador, ou defina auto_review = "deny" em uma política de origem para restringi-la nessa origem. Isso controla o tratamento das aprovações; não desabilita o monitoramento de segurança do modelo.

Para aplicativos nativos, defina uma política de acesso padrão e identifique os aplicativos permitidos. Por exemplo, esta política do macOS permite a Calculadora e impede aprovações salvas:

[computer_use]
default_app_access = "deny"
allow_persistent_approval = false

[computer_use.macos.bundle_ids]
"com.apple.calculator" = "allow"

As políticas do Windows podem identificar aplicativos empacotados com computer_use.windows.aumids ou executáveis com computer_use.windows.exes. As regras de executáveis exigem publisher_name, product_name e access; binary_name é opcional. Use a identidade verificada do aplicativo, em vez de apenas seu nome de exibição.

Consulte a referência de configuração para ver todos os campos e as restrições de uso com o computador bloqueado para dispositivos macOS gerenciados.

Fixar flags de recursos

Você também pode fixar flags de recursos para usuários que recebem um requirements.toml gerenciado:

[features]
personality = true
unified_exec = false

# Disable surface-specific features when needed.
browser_use = false
browser_use_full_cdp_access = false
browser_use_external = false
in_app_browser = false
in_app_updates = false
computer_use = false

Use as chaves canônicas de recursos da tabela [features] de config.toml para recursos do ambiente de execução. O ambiente de execução local normaliza os recursos reconhecidos para respeitar esses valores fixados e rejeita gravações conflitantes em config.toml ou nas configurações de recursos do arquivo de perfil.

• in_app_browser = false desabilita o painel do navegador integrado.
• in_app_updates = false desabilita o atualizador próprio do aplicativo do ChatGPT para desktop ao reiniciar, onde houver suporte. Isso não afeta a implantação externa de pacotes nem estende o suporte a versões mais antigas do aplicativo. Para orientações de configuração e distribuição, consulte Gerenciar atualizações do aplicativo.
• browser_use = false desabilita o Uso do computador em navegadores e a disponibilidade do Agente de navegador.
• browser_use_full_cdp_access = false desabilita o acesso completo ao CDP no ambiente de execução local, incluindo o modo de desenvolvedor do navegador, e impede que o aplicativo do ChatGPT para desktop habilite a configuração correspondente.
• browser_use_external = false desabilita o Navegador externo.
• computer_use = false desabilita o Uso do computador, Gravar e reproduzir e os fluxos relacionados de instalação ou configuração.

Se você omitir essas chaves, a política permite os recursos, sujeitos à disponibilidade normal do cliente, da plataforma e da liberação.

Restringir o uso com o computador bloqueado

Para impedir que usuários habilitem o Uso com o computador bloqueado em um Mac gerenciado, adicione este requisito:

[computer_use]
allow_locked_computer_use = false

Esse requisito remove os controles que habilitam o Uso com o computador bloqueado. Ele não desativa o Uso com o computador bloqueado se já estiver habilitado. Se você omitir o requisito, a disponibilidade normal do produto e a configuração local do usuário continuam se aplicando.

Configurar a política de revisão automática

Use allowed_approvals_reviewers para exigir ou permitir a revisão automática. Defina o valor como ["auto_review"] para exigir a revisão automática, ou inclua "user" quando os usuários puderem escolher a aprovação manual.

Defina guardian_policy_config para substituir a seção específica do tenant na política de revisão automática. O ambiente de execução local continua usando o modelo integrado do revisor e o contrato de saída. A configuração gerenciada guardian_policy_config tem precedência sobre a configuração local [auto_review].policy.

allowed_approval_policies = ["on-request"]
allowed_approvals_reviewers = ["auto_review"]

guardian_policy_config = """
## Environment Profile
- Trusted internal destinations include github.com/my-org, artifacts.example.com,
  and internal CI systems.

## Tenant Risk Taxonomy and Allow/Deny Rules
- Treat uploads to unapproved third-party file-sharing services as high risk.
- Deny actions that expose credentials or private source code to untrusted
  destinations.
"""

Impor requisitos de negação de leitura

Os administradores podem negar leituras de caminhos exatos ou padrões glob com [permissions.filesystem]. Os usuários não podem enfraquecer esses requisitos por meio da configuração local.

[permissions.filesystem]
deny_read = [
  # values can be absolute paths...
  "/**/*.env",
  # ...or relative to $HOME/%USERPROFILE% using `~`.
  "~/.ssh",
  # But relative paths starting with `./` are not allowed.
]

Quando há requisitos de negação de leitura, o ambiente de execução local rejeita permissões de acesso completo e mantém a execução local em um sandbox somente leitura ou de workspace para poder impor esses requisitos. No Windows nativo, a configuração gerenciada deny_read se aplica a ferramentas de acesso direto a arquivos; as leituras de subprocessos do shell não usam essa regra de sandbox.

Impor ganchos gerenciados por meio de requisitos

Os administradores também podem definir ganchos gerenciados de ciclo de vida diretamente em requirements.toml. Use [hooks] para a configuração dos ganchos em si e aponte managed_dir para o diretório em que seu MDM ou suas ferramentas de gerenciamento de endpoints instalam os scripts referenciados.

Para impor ganchos gerenciados mesmo para usuários que desativaram os ganchos localmente, fixe [features].hooks = true junto com [hooks]. Para ignorar ganchos de usuário, projeto, sessão e plug-ins, mas continuar permitindo ganchos gerenciados, defina allow_managed_hooks_only = true.

allow_managed_hooks_only = true

[features]
hooks = true

[hooks]
managed_dir = "/enterprise/hooks"
windows_managed_dir = 'C:\enterprise\hooks'

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 /enterprise/hooks/pre_tool_use_policy.py"
command_windows = 'py -3 C:\enterprise\hooks\pre_tool_use_policy.py'
timeout = 30
statusMessage = "Checking managed Bash command"

Observações:

• O ambiente de execução local impõe a configuração de ganchos de requirements.toml, mas não distribui os scripts em managed_dir.
• Distribua esses scripts com seu MDM ou sua solução de gerenciamento de dispositivos.
• Os comandos dos ganchos gerenciados devem fazer referência a caminhos absolutos de scripts dentro do diretório gerenciado configurado.
• allow_managed_hooks_only = true ignora ganchos provenientes de usuário, projeto, sessão e plug-ins, mas continua carregando ganchos de requirements.toml e de outras camadas de configuração gerenciada.

Impor regras de comandos por meio de requisitos

Os administradores também podem impor regras restritivas de comandos em requirements.toml usando uma tabela [rules]. Essas regras são combinadas com os arquivos .rules comuns, e a decisão mais restritiva continua prevalecendo.

Diferentemente de .rules, as regras de requisitos devem especificar decision, e essa decisão deve ser "prompt" ou "forbidden" (não "allow").

[rules]
prefix_rules = [
  { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use git clean -fd instead." },
  { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require review before mutating history." },
]

Para restringir quais servidores MCP um cliente local pode habilitar, adicione uma lista de aprovados mcp_servers. Para servidores stdio, verifique a correspondência de command; para servidores HTTP com streaming, verifique a correspondência de url:

[mcp_servers.docs]
identity = { command = "codex-mcp" }

[mcp_servers.remote]
identity = { url = "https://example.com/mcp" }

A forma de string de identity.command verifica apenas a correspondência de command configurado. Ela não inspeciona args, cwd, env nem env_vars.

Para restringir uma invocação stdio completa, verifique a correspondência do executável e de cada argumento posicional:

[mcp_servers.internal.identity]
command = { executable = "/usr/local/bin/codex-mcp", args = [
  { match = "exact", value = "serve" },
  { match = "prefix", value = "--workspace=" },
] }

O executável, a quantidade de argumentos e a ordem dos argumentos devem corresponder. As regras de argumentos e URLs aceitam correspondência por exact, prefix e regex do valor completo. As regras estruturadas de comandos também não inspecionam cwd, env nem env_vars. Os servidores MCP incluídos em plug-ins usam as mesmas estruturas de identidade em plugins.<plugin>.mcp_servers.<server>.

Se mcp_servers estiver presente, mas vazio, o cliente local desabilita todos os servidores MCP.

Controlar a disponibilidade de plug-ins

Para desativar plug-ins nos clientes locais compatíveis, defina features.plugins como false em requirements.toml:

features.plugins = false

Essa configuração também se aplica quando os usuários entram no Codex com uma chave de API. Consulte a referência de features.plugins para ver a configuração compatível.

Restringir fontes de marketplaces de plug-ins

Para restringir operações em fontes de marketplaces configuradas pelo usuário, defina restrict_to_allowed_sources = true e estabeleça uma ou mais regras de origem:

[marketplaces]
restrict_to_allowed_sources = true

[marketplaces.allowed_sources.company_plugins]
source = "git"
url = "https://github.com/example/company-plugins.git"
ref = "main"

[marketplaces.allowed_sources.internal_git]
source = "host_pattern"
host_pattern = '^git\.example\.com$'

[marketplaces.allowed_sources.local_plugins]
source = "local"
path = "/opt/company/codex-plugins"

As regras de Git comparam a URL normalizada do repositório e, quando presente, o valor exato de ref. Os padrões de host são expressões regulares comparadas ao host Git em letras minúsculas; use ^ e $ para corresponder ao host inteiro. As regras locais exigem um caminho absoluto e normalizado. Consulte a referência de requirements.toml para ver o esquema completo e o comportamento de mesclagem.

Esses requisitos rejeitam operações de adição de marketplaces, instalação de plug-ins e atualização de marketplaces Git configurados quando as fontes configuradas pelo usuário não correspondem às regras. Os marketplaces da OpenAI gerenciados pelo Codex permanecem disponíveis quando sua fonte e seu nome reservado correspondem. Os requisitos não filtram os marketplaces já configurados pelo usuário nem seus plug-ins durante a execução.

Essas restrições de origem se aplicam apenas aos clientes locais que oferecem suporte a operações em marketplaces de plug-ins: ChatGPT e Codex no aplicativo para desktop e Codex CLI. Elas não controlam o uso de plug-ins no ChatGPT na Web ou em dispositivos móveis e não adicionam plug-ins à extensão para IDE.

Valores padrão gerenciados (managed_config.toml)

Os valores padrão gerenciados definem a configuração inicial de um cliente local compatível. Na inicialização, eles substituem as configurações do arquivo config.toml local do usuário e quaisquer valores definidos com --config na CLI. Os usuários ainda podem alterar essas configurações durante a execução atual, e os valores padrão voltam a ser aplicados na próxima inicialização do cliente.

Se um valor padrão gerenciado, um perfil MDM do macOS ou uma configuração salva fixar gpt-5.4 ou gpt-5.4-mini para usuários conectados com o ChatGPT, atualize-o antes de 31 de agosto de 2026. Substitua gpt-5.4 por gpt-5.6-terra e gpt-5.4-mini por gpt-5.6-luna. A API da OpenAI e o Codex autenticado com sua própria chave de API não são afetados. Consulte disponibilidade de modelos no workspace.

Verifique se os valores padrão gerenciados atendem aos seus requisitos; o ambiente de execução local rejeita valores não permitidos.

Precedência e camadas

O ambiente de execução local monta a configuração efetiva nesta ordem (os itens acima têm precedência sobre os itens abaixo):

• Preferências gerenciadas (MDM do macOS; maior precedência)
• managed_config.toml (arquivo do sistema/gerenciado)
• config.toml (configuração base do usuário)

Os valores definidos com --config key=value na CLI substituem os da configuração base, mas as camadas gerenciadas têm precedência sobre eles. Isso significa que cada execução começa com os valores padrão gerenciados, mesmo que você forneça flags locais.

Os requisitos gerenciados na nuvem afetam a camada de requisitos (não os valores padrão gerenciados). Consulte a seção Requisitos impostos pelo administrador acima para entender a precedência.

Locais

• Linux/macOS (Unix): /etc/codex/managed_config.toml
• Windows/sistemas não Unix: ~/.codex/managed_config.toml

Se o arquivo não existir, o ambiente de execução local ignora a camada gerenciada.

Preferências gerenciadas do macOS (MDM)

No macOS, os administradores podem distribuir um perfil de dispositivo que fornece payloads TOML codificados em base64 em:

• Domínio de preferências: com.openai.codex
• Chaves:
  • config_toml_base64 (valores padrão gerenciados)
  • requirements_toml_base64 (requisitos)

O ambiente de execução local interpreta esses payloads de "preferências gerenciadas" como TOML. Para valores padrão gerenciados (config_toml_base64), as preferências gerenciadas têm a maior precedência. Para requisitos (requirements_toml_base64), a precedência segue a ordem dos requisitos gerenciados na nuvem descrita acima. A mesma tabela [features] usada nos requisitos funciona em requirements_toml_base64; use as chaves canônicas dos recursos ali também.

Fluxo de trabalho de configuração do MDM

O ambiente de execução local respeita os payloads padrão de MDM do macOS, permitindo distribuir configurações com ferramentas como Jamf Pro, Fleet ou Kandji. Uma implantação simples segue estas etapas:

1. Crie o payload TOML gerenciado e codifique-o com base64 (sem quebras de linha).
2. Insira a string no seu perfil MDM, no domínio com.openai.codex, em config_toml_base64 (valores padrão gerenciados) ou requirements_toml_base64 (requisitos).
3. Distribua o perfil e peça aos usuários que reiniciem o cliente local compatível e confirmem que o resumo da configuração na inicialização reflete os valores gerenciados.
4. Ao revogar ou alterar a política, atualize o payload gerenciado; o cliente lê a preferência atualizada na próxima inicialização.

Evite incluir segredos ou valores dinâmicos que mudam com frequência no payload. Trate o TOML gerenciado como qualquer outra configuração de MDM sujeita a controle de alterações.

Exemplo de managed_config.toml

# Set conservative defaults
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

[sandbox_workspace_write]
network_access = false             # keep network disabled unless explicitly allowed

[otel]
environment = "prod"
exporter = "otlp-http"            # point at your collector
log_user_prompt = false            # keep prompts redacted
# exporter details live under exporter tables; see Monitoring and telemetry above

Medidas de proteção recomendadas

• Prefira workspace-write com aprovações para a maioria dos usuários; reserve o acesso completo para contêineres controlados.
• Mantenha network_access = false, a menos que sua revisão de segurança permita um coletor ou domínios necessários para seus fluxos de trabalho.
• Use a configuração gerenciada para fixar as configurações do OTel (exportador, ambiente), mas mantenha log_user_prompt = false, a menos que sua política permita explicitamente armazenar o conteúdo dos prompts.
• Audite periodicamente as diferenças entre o config.toml local e a política gerenciada para detectar desvios; as camadas gerenciadas devem ter precedência sobre flags e arquivos locais.