托管配置

托管配置用于控制 ChatGPT 桌面应用、Codex CLI 和 IDE 扩展中所涵盖功能的受支持本地运行时行为。支持的要求可能因客户端和版本而异。托管配置不会授予 ChatGPT 工作空间访问权限、分配席位，也不会取代工作空间基于角色的访问控制 (RBAC)。有关工作空间功能访问权限，请参阅角色与工作空间权限；有关本地运行时策略，请参阅本页。

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

• 要求：由管理员强制执行、用户无法覆盖的约束。
• 配置默认值：由系统或云端管理、用户可以覆盖的 config.toml 设置。
• 旧版托管默认值：受支持的客户端启动时应用的 managed_config.toml 初始值。用户仍可在运行期间更改设置；客户端会在下次启动时重新应用这些默认值。

配置插件市场和默认值

在系统 config.toml 或托管配置的 config.toml 部分中定义本地或 Git 市场及插件默认值。 这些设置是默认值，并非强制执行的策略。

有关配置键，请参阅配置参考资料； 有关覆盖规则，请参阅配置优先级； 有关项目级配置，请参阅代码仓库插件设置。 工作空间 GitHub 导入和 同步是独立功能。

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

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

要求还可以通过 requirements.toml 中的 [features] 表约束功能标志。功能并非总是涉及安全，但企业仍可根据需要固定其值。省略的键不受约束。

对于 Codex 0.138.0 或更高版本，建议使用权限配置方案， 并配合 allowed_permission_profiles 和托管的 default_permissions。 仅对仍配置 sandbox_mode 的旧版部署使用 allowed_sandbox_modes。

有关确切的键列表，请参阅配置参考资料中的 requirements.toml 部分。

从已停用的 untrusted 审批策略迁移

Codex 和 ChatGPT Work 不再支持 approval_policy = "untrusted"。 请将其从托管默认值、旧版 managed_config.toml 以及所有设置了该值的用户、 项目、配置方案或启动配置中移除。

对于交互式只读使用场景，请选择 approval_policy = "on-request"，并搭配 托管要求允许的只读沙盒或权限配置方案。 该沙盒允许的命令无需审批即可运行。

要保留更严格的命令审批，请勿显式设置 approval_policy， 并在用户级 ~/.codex/config.toml 的项目条目中设置 trust_level = "untrusted"，同时在 allowed_approval_policies 中保留 untrusted。 这也会禁用项目本地配置。显式设置 on-request 会覆盖该策略。有关示例和安全方面的权衡，请参阅 从已停用的 untrusted 审批策略迁移 。

位置与优先级

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

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

优先级较高的层会覆盖较低层的普通标量值和列表值。 表按键合并，而规则、钩子和 文件系统限制等要求则采用各字段特定的组合方式。 请参阅requirements.toml 参考资料 了解当前模式，不要假定所有字段都以相同 方式合并。

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

云端托管要求

当用户使用受支持套餐的 ChatGPT 账户登录时，受支持的本地客户端 可以接收与工作空间关联、由管理员强制执行的要求。 这是与 requirements.toml 兼容的策略的分发渠道。它不会授予 工作空间访问权限，也不会取代工作空间 RBAC。身份验证要求必须 在本地管理。

打开托管配置 以创建和分配云端托管要求。例如，以下策略会限制 审批和沙盒选项，并在受支持的 Shell 入口点 运行前请求确认：

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 或 macOS MDM 要求中设置 allowed_login_methods、allowed_chatgpt_workspaces、 cli_auth_credentials_store 和 chatgpt_base_url。 Codex 会忽略云端托管要求中的这四个字段。 本地身份验证要求会在凭据加载前 以及 Codex 获取云端策略前应用。

要强制用户通过 ChatGPT 登录到获准的工作空间，并将凭据保存在操作系统凭据存储中，请使用以下设置：

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

allowed_login_methods 接受 chatgpt、api 或两者。如果省略此设置， 则不限制登录方式。如果设置了此项，列表必须至少包含一种方式。 api 允许 API 身份验证，包括 Amazon Bedrock。 工作空间限制也适用于 Codex 访问令牌。

用户配置的 forced_login_method 和 forced_chatgpt_workspace_id 必须 符合要求。用户选择的工作空间也必须列在 托管的工作空间允许列表中。如果没有匹配的工作空间， 则无法通过 ChatGPT 登录。API 身份验证在获准时仍然可用。如果没有可用的登录方式， Codex 会拒绝启动。

有关凭据存储模式和服务 URL 配置，请参阅要求参考资料 。

requirements.toml 示例

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

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

这里，untrusted 保留了由 trust_level = "untrusted" 衍生的更严格的审批行为；这并不意味着可以将 approval_policy = "untrusted" 用作受支持的显式设置。

禁用应用快照

要为受管理用户禁用应用快照，请设置顶层 allow_appshots 要求：

allow_appshots = false

在应用快照可用的情况下，allow_appshots = false 会禁用该功能。 如果您省略此键，要求不会约束应用快照，仍会执行正常的产品 可用性检查。通过 configRequirements/read 读取生效要求的 App Server 客户端 会收到相同的限制， 其字段为 allowAppshots；如果省略 allowAppshots 或将其值设为 null，则不会禁用 应用快照。

禁用设备远程控制

要为受管理用户禁用设备远程控制， 请设置顶层 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 和 :read-only 均被明确允许时，才会默认使用 :workspace。如果未设置 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 用户。

如果管理员需要集中定义网络访问要求， 请使用 requirements.toml 中的 [experimental_network]。这些要求 独立于用户的 features.network_proxy 开关：无需启用该功能标志， 它们也能配置沙盒网络，但如果当前沙盒关闭了网络， 它们不会授予命令网络访问权限。请设置 experimental_network.enabled = true 以启用受管代理； 仅配置域名规则并不会启用代理。

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

只有在您还于 [experimental_network.domains] 中 定义了由管理员管理的 "allow" 条目， 并希望仅允许这些规则时，才应使用 experimental_network.managed_allowed_domains_only = true。如果将其设为 true，却没有受管允许规则，用户添加的域名允许规则将不再 生效。请勿将规范的 domains 映射与旧版 allowed_domains 或 denied_domains 列表混用。

*.example.com 仅匹配子域名。**.example.com 匹配根域名 及其子域名。匹配的拒绝规则优先于允许规则。

域名语法、本地和私有目标地址规则、拒绝优先于允许的行为 以及 DNS 重绑定限制，均与 智能体审批与安全中描述的沙盒网络行为相同。

代理负责转发沙盒内运行的本地命令的网络流量。浏览器工具在访问源之前，也会检查受管网络拒绝规则和排他性允许列表；这是单独的策略检查，并非通过命令代理转发浏览器流量。该代理不会过滤网页搜索、应用和连接器、MCP 服务器、原生应用流量、Codex 服务请求或 Codex 云端流量。请使用各功能对应的控制项：

• 使用 allowed_web_search_modes 限制网页搜索。
• 使用 features.apps = false 禁用应用和连接器集成，并 在支持的客户端中使用 features.plugins = false 禁用插件。
• 使用受管的 mcp_servers 批准列表限制 MCP 服务器。
• 使用 browser_use、in_app_browser 和 computer_use 等功能要求，限制浏览器和计算机使用能力。
• 在 Codex 云端的云端环境设置中配置其网络访问。

命令的域名允许列表不能替代这些针对特定能力的控制项。

控制浏览器和计算机使用

使用 requirements.toml 中的 [browser_use] 和 [computer_use] 表 对支持这些设置的桌面客户端施加限制。请在部署所用的客户端版本 和操作系统上验证策略。配置允许规则并不会 安装插件、授予操作系统权限，也不会批准 仍需审查的操作。

对于浏览器访问，请配置源策略。源包含协议、 主机和可选的端口，例如 https://example.com 或 https://*.example.com:8443。请勿包含路径、查询参数或片段标识符。 与命令网络的域名规则不同，浏览器源规则会区分 HTTP 和 HTTPS， 并匹配端口。

此示例将浏览器访问限制在一个已批准的网站，并禁止在该网站上传文件和进行完整的 Chrome DevTools Protocol（CDP）访问：

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

匹配的源规则按字段分别确定结果。匹配的拒绝规则优先；否则，匹配规则中未指定的字段由默认源策略提供。本地配置可以添加限制，但不能放宽受管拒绝规则。网络拒绝规则和排他性受管网络允许列表仍然适用。

设置 browser_use.disable_auto_review = true 可禁用针对浏览器操作的 自动审批审查，也可以在源策略中设置 auto_review = "deny"， 仅对该源施加限制。这控制的是审批处理方式；它不会 禁用模型安全监控。

对于原生应用，请设置默认访问策略，并标识允许的应用。例如，以下 macOS 策略允许使用“计算器”，并禁止保存审批结果：

[computer_use]
default_app_access = "deny"
allow_persistent_approval = false

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

Windows 策略可以使用 computer_use.windows.aumids 标识打包应用，或使用 computer_use.windows.exes 标识可执行文件。可执行文件规则必须包含 publisher_name、 product_name 和 access；binary_name 为可选项。请使用应用经过验证的 身份信息，而不要仅依赖其显示名称。

请参阅配置参考 以了解完整字段，并参阅锁定时使用的限制 以了解受管 macOS 设备的相关限制。

固定功能标志

对于接收受管 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
in_app_updates = false
computer_use = false

对于运行时功能，请使用 config.toml 的 [features] 表中的规范功能键。 本地运行时会调整其识别的功能，使其符合这些固定值， 并拒绝向 config.toml 或配置方案文件的功能设置 写入与之冲突的值。

• in_app_browser = false 会禁用内置浏览器窗格。
• 在支持此设置的客户端中，in_app_updates = false 会在重启后 禁用 ChatGPT 桌面应用自身的更新程序。它不会影响外部软件包部署， 也不会延长对旧版应用的支持。如需设置和推出方面的指导，请参阅 管理应用更新。
• browser_use = false 会禁用浏览器中的计算机使用功能，并使浏览器 Agent 不可用。
• browser_use_full_cdp_access = false 会禁用本地运行时中的完整 CDP 访问， 包括浏览器开发者模式，并阻止 ChatGPT 桌面应用 启用相应设置。
• browser_use_external = false 会禁用外部浏览器功能。
• computer_use = false 会禁用计算机使用、录制与重放，以及相关的 安装或设置流程。

如果省略这些键，策略将允许这些功能，但仍受常规客户端、平台支持情况及推出范围的限制。

限制锁定时使用计算机

要阻止用户在受管 Mac 上启用锁定时使用， 请添加以下要求：

[computer_use]
allow_locked_computer_use = false

此要求会移除用于启用“锁定时使用”的控制项。如果“锁定时使用”已启用，它不会将其关闭。如果省略此要求，仍按常规产品可用性和用户的本地设置执行。

配置自动审查策略

使用 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 或终端管理工具安装所引用 脚本的目录。

要对已在本地关闭钩子的用户也强制执行受管钩子，请在配置 [hooks] 的同时， 固定 [features].hooks = true。要跳过用户、项目、会话 和插件钩子，同时仍允许受管钩子，请设置 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 服务器。

控制插件可用性

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

features.plugins = false

当用户使用 API 密钥登录 Codex 时，此设置同样适用。请参阅 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 主机名； 使用 ^ 和 $ 可匹配整个主机名。本地规则要求使用 规范化的绝对路径。请参阅 requirements.toml 参考资料， 了解完整的模式和合并行为。

这些要求会拒绝不匹配的市场添加、插件安装以及已配置的 Git 市场刷新操作。它们还会在运行时筛选已配置的市场及其插件。

OpenAI 精选的 Git 市场（包括面向 API 密钥用户的目录）也必须 匹配来源允许列表。要允许使用这些市场，请添加以下 Git 来源， 且不要设置 ref 约束：

[marketplaces.allowed_sources.openai_curated]
source = "git"
url = "https://github.com/openai/plugins.git"

要排除精选目录，请勿添加该来源，并确保没有范围更广的主机规则允许它。捆绑插件和远程安装的工作空间插件不受此精选 Git 来源策略控制。

这些来源限制仅适用于支持插件市场操作的本地客户端：桌面应用中的 ChatGPT 和 Codex，以及 Codex CLI。它们不控制网页版或移动版 ChatGPT 中的插件使用，也不会为 IDE 扩展添加插件。

托管默认值（managed_config.toml）

托管默认值决定受支持的本地客户端启动时使用的配置。 启动时，它们会覆盖用户本地的 config.toml 以及通过 CLI --config 指定的任何覆盖值。 用户仍可在当前运行期间更改这些设置， 而默认值会在客户端下次启动时重新应用。

如果托管默认值、macOS MDM 描述文件或已保存的配置为使用 ChatGPT 登录的用户固定了 gpt-5.4 或 gpt-5.4-mini，请在 2026 年 8 月 31 日之前更新。将 gpt-5.4 替换为 gpt-5.6-terra，将 gpt-5.4-mini 替换为 gpt-5.6-luna。OpenAI API 和使用您自己的 API 密钥进行身份验证的 Codex 不受影响。请参阅工作空间模型 可用性。

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

优先级与分层

本地运行时按以下顺序组合出最终生效的配置（上方覆盖下方）：

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

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

云端 config.toml 使用常规配置优先级， 而非上述旧版顺序。云端 requirements.toml 使用 要求的优先级。

位置

• Linux/macOS（Unix）：/etc/codex/managed_config.toml
• Windows/非 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 等工具分发设置。 一个简单的部署流程如下：

1. 编写托管载荷的 TOML，并使用 base64 对其编码（不换行）。
2. 将该字符串填入您的 MDM 描述文件中 com.openai.codex 域下的 config_toml_base64（托管默认值）或 requirements_toml_base64（要求）。
3. 推送描述文件，然后请用户重启受支持的本地客户端，并确认启动配置摘要反映了托管值。
4. 撤销或更改策略时，请更新托管载荷；客户端会在下次启动时读取更新后的偏好设置。

避免在载荷中嵌入机密信息或频繁变化的动态值。与其他 MDM 设置一样，应将托管 TOML 纳入变更控制。

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 与托管策略之间的差异，以发现配置偏移；托管层应优先于本地标志和文件。