下发托管配置

Enterprise admins 可以用两种方式控制 local Codex 的行为：

Requirements：由 admin 强制执行的 constraints，users 不能覆盖。
Managed defaults：Codex 启动时应用的初始值。users 仍然可以在当前 session 中修改 settings；下次启动时，Codex 会重新应用 managed defaults。

Admin-Enforced Requirements (`requirements.toml`)

Requirements 用来约束 security-sensitive settings，包括 approval policy、approvals reviewer、automatic review policy、sandbox mode、web search mode、managed hooks，以及可选的 MCP servers enable list。

Codex 解析 configuration 时，会把 config.toml、profiles、CLI config overrides 等来源合并起来。如果某个值和 enforced rule 冲突，Codex 会回退到 compatible value，并提示 user。

如果你配置了 mcp_servers allowlist，Codex 只会在 MCP server 的 name 和 identity 都匹配 approved entry 时启用它；否则会禁用该 server。

Requirements 也可以通过 requirements.toml 中的 [features] table 约束 feature flags。feature flag 不一定都是 security-sensitive，但 enterprise 可以按需要固定某些值。未出现的 keys 不受约束。

完整 key list 见 Configuration Reference 的 requirements.toml section。

位置 and Precedence

Codex 按下面顺序应用 requirements layers；同一个 field 里，越靠前优先级越高：

优先级	来源
1	Cloud-managed requirements，适用于 ChatGPT Business 或 Enterprise
2	macOS managed preferences，通过 MDM 写入 `com.openai.codex:requirements_toml_base64`
3	System `requirements.toml`，Unix 系统含 Linux/macOS 为 `/etc/codex/requirements.toml`，Windows 为 `%ProgramData%\OpenAI\Codex\requirements.toml`

多层 requirements 会按 field merge：如果前面的 layer 设置了某个 field，包括 empty list，后面的 layer 不能覆盖它；但后面的 layer 仍可补上前面没有设置的 fields。

为了兼容旧配置，Codex 也会把 legacy managed_config.toml 中的 approval_policy 和 sandbox_mode 解释成 requirements，也就是只允许对应的单一值。

Cloud-Managed Requirements

当 user 使用 ChatGPT Business 或 Enterprise plan 登录时，Codex 还可以从 Codex service 获取 admin-enforced requirements。这也是一个兼容 requirements.toml 的 requirements 来源。

它适用于 Codex 的各个 surface，包括 CLI、App 和 IDE Extension。

Configure Cloud-Managed Requirements

进入 Codex managed-config page。

创建一个新的 managed requirements file，使用和 requirements.toml 相同的 format 与 keys。

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

保存 configuration 后，updated managed requirements 会立即应用到 matching users。更多示例见 Example requirements.toml。

Assign Requirements to Groups

Admins 可以给不同 user groups 配置不同的 managed requirements，也可以设置 default fallback requirements policy。

如果一个 user 同时匹配多个 group-specific rules，Codex 使用第一个 matching rule。Codex 不会从后面的 matching group rules 里补齐 unset fields。

例如，第一个 matching group rule 只设置：

allowed_sandbox_modes = ["read-only"]

后面的 matching group rule 设置：

allowed_approval_policies = ["on-request"]

Codex 只应用第一个 matching group rule，不会从后面的 rule 补入 allowed_approval_policies。

How Codex Applies Cloud-Managed Requirements Locally

user 启动 Codex，并使用 ChatGPT Business 或 Enterprise plan 登录时，Codex 会 best-effort 应用 managed requirements。

Codex 会先检查本地是否存在 valid、unexpired 的 managed requirements cache entry；如果有，就直接使用。

如果 cache 缺失、过期、损坏，或和当前 auth identity 不匹配，Codex 会尝试从 service 获取 managed requirements，并带 retries。获取成功后，Codex 会写入新的 signed cache entry。

如果没有 valid cached entry，且 fetch 失败或超时，Codex 会继续运行，但不会应用 managed requirements layer。

cache resolution 结束后，Codex 会把 managed requirements 纳入前面描述的正常 requirements layering。

Example `requirements.toml`

下面的例子会阻止 --ask-for-approval never 和 --sandbox danger-full-access，包括 --yolo：

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

Override Sandbox Requirements by Host

如果同一套 managed policy 需要在不同 hosts 上应用不同 sandbox requirements，可以使用 [[remote_sandbox_config]]。

例如，你可以对 laptops 保持更严格的 default，同时允许匹配的 devboxes 或 CI runners 使用 workspace writes。host-specific entries 目前只覆盖 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 entry 和 best-effort resolved host name 进行匹配。能拿到 fully qualified domain name 时优先使用 FQDN，否则退回 local host name。

matching 是 case-insensitive：

* 匹配任意长度的 characters。
? 匹配单个 character。

在同一个 requirements source 内，第一个 matching [[remote_sandbox_config]] entry 生效。

如果没有 entry 命中，Codex 保留 top-level allowed_sandbox_modes。

hostname matching 只用于选择 policy，不要把它当成 authenticated device proof。

你也可以约束 web search mode：

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

allowed_web_search_modes = [] 表示只允许 "disabled"。

例如，allowed_web_search_modes = ["cached"] 会阻止 live web search，即使当前 session 使用 danger-full-access。

Pin Feature Flags

你也可以为接收 managed requirements.toml 的 users 固定 feature flags。

[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] table 里的 canonical feature keys。Codex 会 normalize 最终 feature set，让它满足这些 pinned values，并拒绝写入和它们冲突的 config.toml 或 profile-scoped feature settings。

in_app_browser = false 会禁用 in-app browser pane。
browser_use = false 会禁用 Browser Use 和 Browser Agent availability。
computer_use = false 会禁用 Computer Use availability，以及相关 install 或 enablement flows。

如果 omitted，这些 features 在 policy 层面就是 allowed，但仍受 normal client、platform 和 rollout availability 影响。

Configure Automatic Review Policy

使用 allowed_approvals_reviewers 要求或允许 automatic review。

设置为 ["auto_review"]，表示必须使用 automatic review；如果包含 "user"，则 users 可以选择 manual approval。

使用 guardian_policy_config 替换 automatic review policy 中 tenant-specific 的 section。Codex 仍然使用 built-in reviewer template 和 output contract。managed guardian_policy_config 的优先级高于 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.
"""

Enforce Deny-Read Requirements

Admins 可以通过 [permissions.filesystem] deny exact paths 或 glob patterns 的 reads。users 不能用 local configuration 放宽这些 requirements。

[permissions.filesystem]
deny_read = [
  "/Users/alice/.ssh",
  "./private/**/*.txt",
]

存在 deny-read requirements 时，Codex 会把 local sandbox mode 限制在 read-only 或 workspace-write，这样 Codex 才能 enforce 它们。

在 native Windows 上，managed deny_read 适用于 direct file tools；shell subprocess reads 不使用这条 sandbox rule。

Enforce Managed Hooks from Requirements

Admins 也可以直接在 requirements.toml 中定义 managed lifecycle hooks。

使用 [hooks] 写 hook configuration 本身，并把 managed_dir 指向你的 MDM 或 endpoint-management tooling 安装 referenced scripts 的目录。

[features]
codex_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"
timeout = 30
statusMessage = "Checking managed Bash command"

Notes:

Codex 会 enforce requirements.toml 中的 hook configuration，但不会分发 managed_dir 中的 scripts。
这些 scripts 需要通过你的 MDM 或 device-management solution 单独交付。
Managed hook commands 应该引用 configured managed directory 下面的 absolute script paths。

Enforce Command Rules from Requirements

Admins 还可以通过 requirements.toml 中的 [rules] table enforce restrictive command rules。这些 rules 会和常规 .rules files merge，最终仍然是 most restrictive decision 生效。

和 .rules 不同，requirements 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 可以 enable 哪些 MCP servers，请添加 mcp_servers approved list。stdio servers 按 command 匹配；streamable HTTP servers 按 url 匹配：

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

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

如果 mcp_servers 存在但为空，Codex 会禁用所有 MCP servers。

Managed Defaults (`managed_config.toml`)

Managed defaults 会 merge 到 user local config.toml 之上，并优先于任何 CLI --config overrides，作为 Codex 启动时的 starting values。

users 仍然可以在当前 session 修改这些 settings；Codex 会在下次启动时重新应用 managed defaults。

请确认 managed defaults 满足你的 requirements；Codex 会拒绝 disallowed values。

优先级和层级

Codex 按下面顺序组装 effective configuration；越靠上优先级越高：

优先级	配置来源
1	Managed preferences，macOS MDM，最高优先级
2	`managed_config.toml`，system/managed file
3	`config.toml`，user's base configuration

CLI --config key=value overrides 会应用到底层 base，但 managed layers 会覆盖它们。这意味着即使你提供 local flags，每次运行仍会从 managed defaults 开始。

Cloud-managed requirements 影响 requirements layer，而不是 managed defaults。precedence 见前面的 Admin-enforced requirements section。

位置

系统	路径
Linux/macOS (Unix)	`/etc/codex/managed_config.toml`
Windows/non-Unix	`~/.codex/managed_config.toml`

如果文件不存在，Codex 会跳过 managed layer。

macOS Managed Preferences (MDM)

在 macOS 上，admins 可以推送 device profile，在下面位置提供 base64-encoded TOML payloads：

Preference domain：com.openai.codex
Keys：
- config_toml_base64，用于 managed defaults。
- requirements_toml_base64，用于 requirements。

Codex 会把这些 "managed preferences" payloads 解析为 TOML。

对 managed defaults，也就是 config_toml_base64，managed preferences 拥有最高优先级。

对 requirements，也就是 requirements_toml_base64，precedence 遵循前面 cloud-managed requirements 的顺序。

requirements 侧的 [features] table 同样适用于 requirements_toml_base64；这里也要使用 canonical feature keys。

MDM Setup Workflow

Codex honors standard macOS MDM payloads，因此你可以用 Jamf Pro、Fleet 或 Kandji 这类 tooling 分发 settings。

一个轻量 deployment 可以这样做：

构建 managed payload TOML，并用 base64 encode，注意 no wrapping。
把 encoded string 放到 MDM profile 的 com.openai.codex domain 下。managed defaults 写入 config_toml_base64，requirements 写入 requirements_toml_base64。
推送 profile，然后让 users restart Codex，并确认 startup config summary 已反映 managed values。
revoke 或变更 policy 时，更新 managed payload；CLI 会在下次启动时读取 refreshed preference。

不要在 payload 中嵌入 secrets 或高频变化的 dynamic values。把 managed TOML 当作任何其他受 change control 管理的 MDM setting。

Example `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