托管配置 – Codex

企业管理员可以通过两种方式控制本地 Codex 的行为

要求 (Requirements)：由管理员强制执行的约束，用户无法覆盖。
托管默认值 (Managed defaults)：Codex 启动时应用的起始值。用户仍可在会话期间更改设置，但在下次启动时，Codex 会重新应用这些托管默认值。

管理员强制执行的要求 (requirements.toml)

要求会限制与安全敏感相关的设置（审批策略、审批审查者、自动审查策略、沙盒模式、网络搜索模式、托管钩子，以及可选的用户可启用的 MCP 服务器）。在解析配置（例如从 config.toml、配置文件或 CLI 配置覆盖项）时，如果值与强制规则冲突，Codex 将回退到兼容的值并通知用户。如果您配置了 mcp_servers 允许列表，Codex 仅在服务器的名称和身份均匹配已批准条目时才会启用它；否则，Codex 将禁用该服务器。

要求还可以通过 requirements.toml 中的 [features] 表来限制功能标志 (feature flags)。请注意，功能并不总是安全敏感的，但企业可以根据需要锁定其值。未指定的键保持不受限制。

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

位置与优先级

Codex 按照以下顺序应用要求层（每个字段中，较早的层级优先）：

云托管要求 (ChatGPT Business 或 Enterprise)
macOS 托管偏好设置 (MDM)，通过 com.openai.codex:requirements_toml_base64
系统 requirements.toml (Unix 系统（包括 Linux/macOS）上的 /etc/codex/requirements.toml，或 Windows 上的 %ProgramData%\OpenAI\Codex\requirements.toml)

在各个层级之间，Codex 会针对每个字段合并要求：如果较早的层级设置了一个字段（包括空列表），后面的层级不会覆盖该字段，但较低的层级仍可以填充未设置的字段。

为了向后兼容，Codex 也会将旧版 managed_config.toml 中的 approval_policy 和 sandbox_mode 字段解释为要求（仅允许该单一值）。

云托管要求

当您使用 ChatGPT Business 或 Enterprise 计划登录时，Codex 还可以从 Codex 服务获取管理员强制执行的要求。这是 requirements.toml 兼容要求的另一个来源。这适用于 Codex 的各个界面，包括 CLI、App 和 IDE 扩展。

配置云托管要求

前往 Codex 托管配置页面。

创建一个新的托管要求文件，使用与 requirements.toml 相同的格式和键。

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 entrypoints" },
]

保存配置。保存后，更新的托管要求将立即应用于匹配的用户。有关更多示例，请参阅示例 requirements.toml。

为组分配要求

管理员可以为不同的用户组配置不同的托管要求，还可以设置默认的回退要求策略。

如果用户匹配多条特定于组的规则，则适用第一条匹配的规则。Codex 不会从后续匹配的组规则中填充未设置的字段。

例如，如果第一条匹配的组规则仅设置了 allowed_sandbox_modes = ["read-only"]，而后续的匹配组规则设置了 allowed_approval_policies = ["on-request"]，则 Codex 仅应用第一条匹配规则，不会从后续规则中填充 allowed_approval_policies。

Codex 如何在本地应用云托管要求

当用户启动 Codex 并使用 ChatGPT Business 或 Enterprise 计划登录时，Codex 会尽力应用托管要求。Codex 首先检查是否存在有效且未过期的本地托管要求缓存条目，并在可用时使用它。如果缓存缺失、过期、损坏或与当前的授权身份不匹配，Codex 会尝试从服务获取托管要求（并进行重试），并在成功后写入一个新的已签名缓存条目。如果没有有效的缓存条目可用，且获取失败或超时，Codex 将在没有托管要求层的情况下继续运行。

缓存解析后，Codex 会将托管要求作为上述常规要求分层的一部分进行强制执行。

示例 requirements.toml

此示例禁止 --ask-for-approval never 和 --sandbox danger-full-access（包括 --yolo）。

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

按主机覆盖沙盒要求

当一个托管策略需要在不同主机上应用不同的沙盒要求时，请使用 [[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"]

Codex 将每个 hostname_patterns 条目与尽力解析的主机名进行比较。它优先使用完全限定域名（若可用），并回退到本地主机名。匹配是不区分大小写的；* 匹配任意字符序列，? 匹配单个字符。

在同一个要求来源中，第一条匹配的 [[remote_sandbox_config]] 条目生效。如果没有条目匹配，Codex 将保持顶层的 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 会话中也是如此。

配置网络访问要求

当管理员需要集中定义网络访问要求时，请在 requirements.toml 中使用 [experimental_network]。这些要求与用户 features.network_proxy 开关分开：它们可以在没有该功能标志的情况下配置沙盒网络，但在活动沙盒保持网络关闭时，它们不会授予命令网络访问权限。

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

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

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

锁定功能标志

您还可以为接收托管 requirements.toml 的用户锁定功能标志。

[features]
personality = true
unified_exec = false

# Disable specific Codex feature surfaces when needed.
browser_use = false
in_app_browser = false
computer_use = false

使用 config.toml 的 [features] 表中的规范功能键。Codex 会规范化生成的功能集以满足这些锁定，并拒绝与 config.toml 或配置文件范围的功能设置冲突的写入。

in_app_browser = false 禁用应用内浏览器面板。
browser_use = false 禁用 Browser Use 和 Browser Agent 的可用性。
computer_use = false 禁用 Computer Use 的可用性及相关的安装或设置流程。

如果省略，这些功能在策略上是被允许的，受限于正常的客户端、平台和发布可用性。

配置自动审查策略

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

设置 guardian_policy_config 以替换自动审查策略中特定于租户的部分。Codex 仍使用内置的审查者模板和输出契约。托管的 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] 拒绝特定路径或通配符模式的读取权限。用户无法通过本地配置削弱这些要求。

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

当存在读取拒绝要求时，Codex 会将本地沙盒模式限制为 read-only 或 workspace-write，以便 Codex 能够强制执行这些要求。在原生 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"

备注

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

从要求中强制执行命令规则

管理员还可以使用 [rules] 表从 requirements.toml 中强制执行严格的命令规则。这些规则与常规的 .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." },
]

若要限制 Codex 可以启用的 MCP 服务器，请添加 mcp_servers 批准列表。对于 stdio 服务器，按 command 匹配；对于可流式传输的 HTTP 服务器，按 url 匹配。

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

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

如果 mcp_servers 存在但为空，Codex 将禁用所有 MCP 服务器。

托管默认值 (managed_config.toml)

托管默认值会合并在用户本地的 config.toml 之上，并优先于任何 CLI --config 覆盖项，从而设定 Codex 启动时的起始值。用户仍可在会话期间更改这些设置，但在下次启动时，Codex 会重新应用这些托管默认值。

请确保您的托管默认值满足您的要求；Codex 会拒绝不允许的值。

优先级与分层

Codex 按照以下顺序组合有效配置（顶部覆盖底部）：

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

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

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

位置

Linux/macOS (Unix): /etc/codex/managed_config.toml
Windows/非 Unix: ~/.codex/managed_config.toml

如果该文件缺失，Codex 将跳过托管层。

macOS 托管偏好设置 (MDM)

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

偏好设置域: com.openai.codex
键
- config_toml_base64 (托管默认值)
- requirements_toml_base64 (要求)

Codex 将这些“托管偏好设置”负载解析为 TOML。对于托管默认值 (config_toml_base64)，托管偏好设置具有最高优先级。对于要求 (requirements_toml_base64)，优先级遵循上述云托管要求的顺序。同样的 [features] 表也可用于 requirements_toml_base64；请也在那里使用规范的功能键。

MDM 设置工作流程

Codex 支持标准的 macOS MDM 负载，因此您可以使用 Jamf Pro、Fleet 或 Kandji 等工具分发设置。轻量级部署如下：

构建托管负载 TOML 并使用 base64 进行编码（无换行）。
将该字符串放入您的 MDM 配置文件中，置于 com.openai.codex 域下的 config_toml_base64（托管默认值）或 requirements_toml_base64（要求）中。
推送配置文件，然后要求用户重启 Codex，并确认启动配置摘要反映了托管值。
当撤销或更改策略时，更新托管负载；CLI 会在下次启动时读取刷新的偏好设置。

避免在负载中嵌入机密或高频变化的动态值。应像对待任何其他受变更控制的 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

推荐

开始使用

核心概念

Agents SDK

工具

运行与扩展

评估

实时与音频

模型优化

专用模型

上线

遗留 API

资源