托管配置

身份非官方简体中文镜像

翻译状态 AI 翻译

来源版本官方未提供

同步日期 2026-07-31

如需完整文档索引，请参阅 llms.txt。文档页面的 Markdown 版本可通过在页面后追加 .md 来获取 URL。

托管配置控制 ChatGPT 桌面应用、 Codex CLI和 IDE 扩展中受支持功能的本地运行时行为。支持的要求可能因客户端和版本而异。托管配置不会授予 ChatGPT 工作区访问权限、分配席位，也不会取代工作区基于角色的访问控制（RBAC）。使用角色和工作区权限来管理工作区功能访问，使用本页面管理本地运行时策略。

企业管理员可以通过两种方式控制受支持的本地客户端行为：

要求：管理员强制执行、用户无法覆盖的约束。
托管默认值：受支持客户端启动时应用的初始值。用户仍可在运行期间更改设置；客户端会在下次启动时重新应用托管默认值。

管理员强制执行的要求（requirements.toml）

要求会约束安全敏感设置（审批策略、审批审阅者、自动审阅策略、沙箱模式、权限配置文件、网页搜索模式、托管钩子、用户可启用哪些 MCP 服务器，以及他们可以添加、安装来源或刷新的用户配置插件市场来源）。解析配置时（例如来自 config.toml、配置文件或 CLI 配置覆盖），如果某个值与强制规则冲突，本地客户端会回退到兼容值并通知用户。如果你配置了 mcp_servers 允许列表，客户端仅在 MCP 服务器的名称和身份都匹配已批准条目时才会启用该服务器；否则，客户端会将其禁用。

要求还可以通过功能标志在 [features] 中的表来约束 requirements.toml。请注意，功能并不总是安全敏感的，但企业可以按需固定取值。省略的键不受约束。

对于 Codex 0.138.0 或更高版本，优先使用带有权限配置文件的 allowed_permission_profiles 以及托管 default_permissions。仅对仍配置 allowed_sandbox_modes 的旧版部署使用 sandbox_mode。

有关准确的键列表，请参阅《配置参考》中的 requirements.toml 章节。

位置和优先级

每个受支持的本地客户端都会按从低到高的优先级组合要求：

系统 requirements.toml （/etc/codex/requirements.toml 在 Unix 系统上，包括 Linux 和 macOS，或 %ProgramData%\OpenAI\Codex\requirements.toml 在 Windows 上）。
通过云配置包交付的企业托管要求。
旧版 managed_config.toml 字段，本地客户端会将其重新解释为要求。
macOS 通过MDM交付的托管偏好设置（ com.openai.codex:requirements_toml_base64）。

较高优先级的层会覆盖较低层中的普通标量和列表值。表按键合并，而规则、钩子和文件系统限制等要求具有字段特定的组合行为。请使用 requirements.toml 参考了解当前架构，而不要假设每个字段都以相同方式合并。

为保持向后兼容，受支持的本地客户端会将旧版 approval_policy、 approvals_reviewer和 sandbox_mode 字段重新解释为要求。此转换会在必要时添加兼容选项；如需显式允许列表，请使用 requirements.toml 。

云托管要求

当用户使用 ChatGPT 在受支持的套餐上登录时，受支持的本地客户端可以接收与该工作区关联的管理员强制要求。这是用于 requirements.toml-compatible 策略的传递渠道。它不会授予工作区访问权限，也不会取代工作区 RBAC。

打开托管配置以创建和分配云托管要求。例如，此策略要求受支持的客户端使用美国数据驻留，限制审批和沙箱选项，并在受支持的 shell 入口点运行前提示：

enforce_residency = "us"
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" },
]

确认每个托管客户端版本都支持你选择的键，并先用小范围群组测试该策略，再分配给整个组织。使用配置参考了解当前架构，并使用管理界面了解当前分配行为。

服务会选择适用于已登录身份的企业托管要求层。本地客户端会将这些层与在位置和优先级中描述的其他要求来源一起评估。使用当前管理界面在工作区侧创建和分配。不要依赖复制的群组匹配算法；管理服务拥有该行为，并且可以独立于本地要求格式进行更改。

有关受支持的键和示例，请参阅示例 requirements.toml 和 requirements.toml 参考。

本地客户端如何应用云托管要求

当用户启动受支持的本地客户端，并在 ChatGPT 上使用在受支持的计划中登录时，客户端首先检查是否存在有效且身份匹配的缓存条目。如果没有可用的有效条目，客户端会通过重试获取适用的包，并在成功后写入签名缓存条目。如果请求失败或超时且没有可用的有效缓存，云配置包加载会返回错误，而不是在没有云托管要求层的情况下静默启动。

缓存解析后，客户端会将云要求与上述其他要求层组合。后台刷新可以更新缓存供后续启动使用；它不会替换已经加载到当前进程中的要求。

示例 requirements.toml

此示例会阻止 --ask-for-approval never 和 --sandbox danger-full-access （包括 --yolo）：

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

禁用 Appshots

要为托管用户禁用 Appshots，请设置顶层 allow_appshots 要求：

allow_appshots = false

在 Appshots 可用的地方， allow_appshots = false 会将其禁用。如果你省略该键，要求不会约束 Appshots，并会应用正常的产品可用性检查。通过读取有效要求的应用服务器客户端 configRequirements/read 会收到与 allowAppshots相同的限制；省略或 null allowAppshots 值不会禁用 Appshots。

禁用设备远程控制

要为托管用户禁用设备远程控制，请设置顶层 allow_remote_control 要求：

allow_remote_control = false

在支持设备远程控制的地方， allow_remote_control = false 会将其禁用。如果省略该键，要求不会约束设备远程控制，并会应用正常的产品可用性检查。此要求不会禁用 SSH 远程连接。

控制可用的权限配置文件

使用 allowed_permission_profiles 来控制用户可以选择哪些内置和自定义权限配置文件。这是的权限配置文件对应项 allowed_sandbox_modes；请使用与用户选择权限方式相匹配的允许列表。

权限配置文件允许列表要求 Codex 0.138.0 或更高版本。 Codex 0.137.0 和更早版本会忽略 allowed_permission_profiles 和托管 default_permissions。

仅在每个托管客户端都运行支持版本后，才使用下面的权限配置文件示例。在整个设备群升级完成之前，不要部署托管自定义配置文件。

存在该表时，它就是允许配置文件的完整列表。它允许设置为 true 的配置文件，并拒绝省略或设置为 false的配置文件，包括未来版本中新增的内置 Codex 配置文件。

允许标准配置文件

此策略允许只读访问和工作区访问，但不允许完全访问：

default_permissions = ":workspace"

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

添加托管的最小权限默认值

管理员可以在同一要求来源中定义自定义配置文件。使用组织特定的配置文件名称，避免与用户已加载配置中的名称冲突。自定义名称不能以 : 开头，也不能使用保留 filesystem 名称。

不要向运行 Codex 0.137.0 或更早版本的客户端部署托管自定义配置文件。这些客户端能识别配置文件表，但不能识别用于选择它的托管默认值。

例如：

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"

仅允许企业定义的配置文件

当用户只能选择管理员定义的配置文件时，请省略所有内置配置文件：

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"

自定义配置文件可以扩展 :workspace ，即使用户不能直接选择内置 :workspace 配置文件。

关闭另一个来源允许的配置文件

权限允许列表按配置文件名称组合。由于云要求的优先级高于系统要求，云要求可以使用 false 来关闭系统文件允许的配置文件。

云要求：

default_permissions = ":read-only"

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

系统要求：

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

将 default_permissions 显式设置为允许的配置文件。如果省略它，本地运行时仅在 :workspace 和 :workspace 都被显式允许时才默认使用 :read-only 。当 allowed_permission_profiles 不存在时，托管要求不会限制用户可以选择哪些配置文件名称。每个条目都必须命名一个内置配置文件，或在已加载配置或要求来源中定义的自定义配置文件。在托管要求中定义自定义配置文件，以集中控制其行为。

按主机覆盖沙箱要求

当一个托管策略需要在不同主机上应用不同的 [[remote_sandbox_config]] 沙箱要求时，请使用。例如，你可以为笔记本电脑保留更严格的默认值，同时允许匹配的开发机器或 CI 运行器进行工作区写入。主机特定条目目前只覆盖 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"]

本地运行时会将每个 hostname_patterns 条目与尽力解析出的主机名进行比较。可用时，它优先使用完全限定域名，否则回退到本地主机名。匹配不区分大小写； * 匹配任意字符序列， ? 匹配一个字符。

在同一 [[remote_sandbox_config]] 要求来源中，第一个匹配的条目生效。如果没有条目匹配，本地运行时会保留顶层 allowed_sandbox_modes。主机名匹配仅用于策略选择；不要将其视为经过身份验证的设备证明。

你还可以约束网页搜索模式：

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

allowed_web_search_modes = [] 仅允许 "disabled"。例如， allowed_web_search_modes = ["cached"] 会阻止实时网页搜索，即使在 danger-full-access 会话中也是如此。

配置网络访问要求

[experimental_network] 是实验性的，可能会发生变化。不要在整个企业部署中广泛启用这些要求，除非已在用户运行的本地客户端版本和操作系统上验证它们。Windows 支持仍然有限；除非你已经在自己的环境中测试过，否则请避免将此策略应用于 Windows 用户。

使用 [experimental_network] 在 requirements.toml 当管理员应集中定义网络访问要求时。这些要求独立于用户 features.network_proxy 开关：它们可以配置沙箱网络，而不需要该功能标志，但当活动沙箱保持网络关闭时，它们不会授予命令网络访问权限。

experimental_network.enabled = true
experimental_network.allowed_domains = [
  "api.openai.com",
  "*.example.com",
]
experimental_network.denied_domains = [
  "blocked.example.com",
  "*.exfil.example.com",
]

仅使用 experimental_network.managed_allowed_domains_only = true 当你也定义由管理员拥有的 allowed_domains 并希望该允许列表具有排他性时。如果它是 true 且没有托管允许规则，则用户添加的域允许规则不会继续生效。

域语法、 local/private 目标规则、拒绝优先于允许的行为、以及 DNS 重绑定限制与中描述的沙箱联网行为相同见 Agent approvals & security。

固定功能标志

你还可以固定功能标志供用户接收托管的 requirements.toml：

[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
computer_use = false

使用来自 config.toml的 [features] 表中的规范功能键用于运行时功能。本地运行时会将已识别的功能规范化以满足这些固定项，并拒绝对 config.toml 或配置文件中的功能设置进行冲突写入。

in_app_browser = false 禁用内置浏览器窗格。
browser_use = false 禁用浏览器中的 Computer Use 和 Browser Agent 可用性。
browser_use_full_cdp_access = false 禁用本地 CDP 运行时中的完整访问权限，包括 Browser Developer 模式，并阻止 ChatGPT 桌面应用启用相应设置。
browser_use_external = false 禁用外部 Browser Use。
computer_use = false 禁用 Computer Use、Record & Replay 以及相关的安装或设置流程。

如果省略这些键，策略会允许这些功能，但仍受正常客户端、平台和发布可用性限制。

限制锁定状态下的计算机使用

要防止 Computer Use 在托管 Mac 锁定后继续运行，请添加此要求：

[computer_use]
allow_locked_computer_use = false

此要求不会启用 Computer Use。它只会阻止在 macOS上的锁定状态使用。如果省略它，要求不会约束锁定状态使用；正常产品可用性和用户的本地设置仍然适用。

配置自动审查策略

使用 allowed_approvals_reviewers 来要求或允许自动审查。将其设置为 ["auto_review"] 以要求自动审查，或包含 "user" 当用户可以选择手动批准时。

设置 guardian_policy_config 以替换自动审查策略中租户特定的部分。本地运行时仍使用内置审查器模板和输出契约。托管 guardian_policy_config 优先于本地 [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.
"""

强制执行拒绝读取要求

管理员可以使用 [permissions.filesystem]拒绝对精确路径或 glob 模式的读取。用户无法通过本地配置削弱这些要求。

[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.
]

当存在拒绝读取要求时，本地运行时会拒绝完整访问权限，并将本地执行保持在只读或工作区沙箱中，以便能够强制执行它们。在原生 Windows 上，托管 deny_read 适用于直接文件工具；shell 子进程读取不使用此沙箱规则。

从要求强制执行托管钩子

管理员还可以直接在 requirements.toml中定义托管生命周期钩子。使用 [hooks] 用于钩子配置本身，并将 managed_dir 指向你的 MDM 或端点管理工具安装所引用脚本的目录。

要即使用户在本地关闭钩子也强制执行托管钩子，请将 [features].hooks = true 与 [hooks]一起固定。要跳过用户、项目、会话和插件钩子，同时仍允许托管钩子，请设置 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"

注意：

本地运行时会强制执行来自 requirements.toml的钩子配置，但不会分发 managed_dir中的脚本。
请使用你的 MDM 或设备管理解决方案交付这些脚本。
托管钩子命令应引用配置的托管目录下的绝对脚本路径。配置的托管目录。
allow_managed_hooks_only = true 会跳过来自用户、项目、会话和插件来源的钩子，但仍会加载来自 requirements.toml 以及其他托管配置层的钩子。

从要求强制执行命令规则

管理员还可以使用 requirements.toml 中的 [rules] 表强制执行限制性命令规则。这些规则会与常规 .rules 文件合并，并且最严格的决策仍然胜出。

不同于 .rules，要求规则必须指定 decision，并且该决策必须是 "prompt" 或 "forbidden" （不能是 "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." },
]

要限制本地客户端可以启用哪些 MCP 服务器，请添加 mcp_servers 批准列表。对于 stdio 服务器，按 command匹配；对于可流式传输的 HTTP 服务器，按 url匹配：

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

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

的字符串形式 identity.command 仅匹配配置的 command。它不会检查 args、 cwd、 env或 env_vars。

要约束完整的 stdio 调用，请匹配可执行文件和每个位置参数：

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

可执行文件、参数数量和参数顺序必须匹配。参数和 URL 规则支持 exact、 prefix以及完整值 regex 匹配。结构化命令规则仍不会检查 cwd、 env或 env_vars。插件捆绑的 MCP 服务器在 plugins.<plugin>.mcp_servers.<server>下使用相同的身份形态。

如果 mcp_servers 存在但为空，本地客户端会禁用所有 MCP 服务器。

控制插件可用性

要在受支持的本地客户端中关闭插件，请将 features.plugins 设置为 false 在 requirements.toml中：

features.plugins = false

当用户使用 Codex 密钥登录 API 时，此设置也适用。请参阅 features.plugins 参考了解支持的配置。

限制插件市场来源

要限制对用户配置的市场来源执行操作，请设置 restrict_to_allowed_sources = true 并定义一个或多个来源规则：

[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"

Git 规则匹配规范化的仓库 URL 以及在存在时的精确 ref。主机模式是与小写 Git 主机匹配的正则表达式；使用 ^ 和 Git 规则匹配规范化的仓库 URL 以及在存在时的精确 ref。主机模式是与小写 Git 主机匹配的正则表达式；使用 ^ 和进行整主机匹配。本地规则要求绝对、规范化路径。请参阅 [requirements.toml` 参考](/docs/config-file/config-reference#requirementstoml) 了解完整架构和合并行为。

这些要求会拒绝不匹配的市场添加、插件安装和针对用户配置来源的已配置 Git 市场刷新操作。 Codex-managed OpenAI 当来源和保留名称匹配时，市场仍然可用。这些要求不会在运行时过滤已配置的用户市场或其插件。

这些来源限制仅适用于本地客户端支持插件市场操作的地方： ChatGPT Work 和 Codex 在桌面应用中，以及 Codex CLI。它们不会向 Chat、 IDE 扩展或移动端添加插件。

托管默认值（`managed_config.toml`）

托管默认值会合并到用户的本地 config.toml 之上，并优先于任何 CLI --config 覆盖，在受支持的本地客户端启动时设置起始值。用户仍可在运行期间更改这些设置；客户端会在下次启动时重新应用托管默认值。

请确保你的托管默认值满足你的要求；本地运行时会拒绝不允许的值。

优先级和分层

本地运行时按以下顺序组装有效配置（上层覆盖下层）：

托管偏好设置（macOS MDM；最高优先级）
managed_config.toml （system/managed 文件）
config.toml （用户的基础配置）

CLI --config key=value 覆盖会应用于基础配置，但托管层会覆盖它们。这意味着即使你提供本地标志，每次运行也会从托管默认值开始。

云托管要求会影响要求层（而非托管默认值）。请参阅上方“管理员强制执行的要求”部分了解优先级。

位置

Linux/macOS （Unix）： /etc/codex/managed_config.toml
Windows/non-Unix： ~/.codex/managed_config.toml

如果文件缺失，本地运行时会跳过托管层。

macOS 托管偏好设置（MDM）

在 macOS上，管理员可以推送一个设备配置文件，提供 base64 编码的 TOML 载荷，位置为：

偏好设置域： com.openai.codex
键：
- config_toml_base64 （托管默认值）
- requirements_toml_base64 （要求）

本地运行时会将这些“托管偏好设置”载荷解析为 TOML。对于托管默认值（config_toml_base64），托管偏好设置具有最高优先级。对于要求（requirements_toml_base64），优先级遵循上文所述的云托管要求顺序。同一个要求侧 [features] 表也可在 requirements_toml_base64中使用；在那里也请使用规范功能键。

MDM 设置工作流

本地运行时支持标准 macOS MDM 载荷，因此你可以使用之类的工具分发 Jamf Pro、 Fleet或 Kandji设置。一个轻量级的部署如下：

构建托管载荷 TOML 并使用 base64 进行编码（不换行）。
将该字符串放入你的 MDM 配置文件中的 com.openai.codex 域下，位置为 config_toml_base64 （托管默认值）或 requirements_toml_base64 （要求）。
推送配置文件，然后让用户重启受支持的本地客户端，并确认启动配置摘要反映了托管值。
撤销或更改策略时，更新托管载荷；客户端会在下次启动时读取刷新的偏好设置。

避免在载荷中嵌入密钥或频繁变化的动态值。像对待任何其他 TOML 设置一样，在变更控制下处理托管的 MDM 设置。

示例 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

建议的防护措施

优先为大多数用户使用 workspace-write 并配合批准；将完整访问权限保留给受控容器。
保持 network_access = false 除非你的安全审查允许采集器或工作流所需的域。
使用托管配置固定 OTel 设置（导出器、环境），但保持 log_user_prompt = false 除非你的策略明确允许存储提示内容。
定期审计本地 config.toml 与托管策略之间的差异以发现漂移；托管层应优先于本地标志和文件。