跳到主要内容

本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/enterprise/managed-configuration

托管配置

配置受管的 Codex 要求和默认值

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

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

管理员强制要求（requirements.toml）​

要求会约束对安全敏感的设置（approval policy、approvals reviewer、automatic review policy、sandbox mode、web search mode、managed hooks，以及可选的用户可启用哪些 MCP 服务器）。在解析配置时（例如来自 config.toml、profiles 或 CLI 配置覆盖），如果某个值与强制规则冲突，Codex 会回退到兼容值并通知用户。如果你配置了 mcp_servers allowlist，Codex 仅会在 MCP 服务器的名称和身份都匹配已批准条目时启用它；否则，Codex 会禁用它。

要求还可以通过 requirements.toml 中的 [features] 表来约束 feature flags。请注意，feature 不一定总是安全敏感的，但企业可按需固定其值。省略的键保持不受约束。

要查看确切的键列表，请参阅配置参考中的 requirements.toml 部分。

位置与优先级​

Codex 按以下顺序应用要求层（每个字段以前者为准）：

  1. 云端受管要求（ChatGPT Business 或 Enterprise）
  2. 通过 com.openai.codex:requirements_toml_base64 提供的 macOS 受管偏好设置（MDM）
  3. 系统 requirements.toml（Unix 系统上的 /etc/codex/requirements.toml，包括 Linux/macOS，或 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 Extension。

配置云端受管要求​

前往 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"]

按主机覆盖 sandbox 要求​

当一个受管策略应在不同主机上应用不同的 sandbox 要求时，使用 [[remote_sandbox_config]]。例如，你可以为笔记本电脑保持更严格的默认设置，同时允许在匹配的开发机或 CI runners 上进行 workspace 写入。当前主机专用条目仅覆盖 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。主机名匹配仅用于策略选择；不要将其视为经过认证的设备证明。

你还可以约束 web search mode：

allowed_web_search_modes = ["cached"] # "disabled" 仍然被隐式允许

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

配置网络访问要求​

当管理员应集中定义网络访问要求时，在 requirements.toml 中使用 [experimental_network]。这些要求独立于用户的 features.network_proxy 开关：它们可以在不启用该 feature flag 的情况下配置 sandboxed networking，但当活动 sandbox 仍关闭网络时，它们不会授予命令网络访问权限。

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，并希望该 allowlist 成为排他性列表时，才使用 experimental_network.managed_allowed_domains_only = true。如果在没有受管允许规则的情况下将其设为 true，用户添加的域名允许规则将不再生效。

域名语法、本地/私有目标规则、deny-over-allow 行为以及 DNS rebinding 限制，与Agent approvals & security 中描述的 sandboxed networking 行为相同。

固定 feature flags​

你还可以为接收受管 requirements.toml 的用户固定 feature flags：

[features]
personality = true
unified_exec = false

# 在需要时禁用特定的 Codex feature 界面。
browser_use = false
in_app_browser = false
computer_use = false

使用 config.toml 的 [features] 表中的规范 feature 键。Codex 会将结果 feature 集标准化以满足这些固定值，并拒绝对 config.toml 或 profile 范围 feature 设置的冲突写入。

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

如果省略，这些 feature 会被策略允许，但仍受正常的客户端、平台和 rollout 可用性限制。

配置 automatic review policy​

使用 allowed_approvals_reviewers 来要求或允许 automatic review。将其设置为 ["auto_review"] 可要求 automatic review，或者在用户可选择手动审批时包含 "user"。

设置 guardian_policy_config 可替换 automatic review policy 中租户专属的部分。Codex 仍会使用内置 reviewer 模板和输出契约。受管 guardian_policy_config 优先于本地 [auto_review].policy。

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

guardian_policy_config = """
## 环境配置文件
- 受信任的内部目标包括 github.com/my-org、artifacts.example.com，
  以及内部 CI 系统。

## 租户风险分类和允许/拒绝规则
- 将上传到未批准的第三方文件共享服务视为高风险。
- 拒绝将凭据或私有源代码暴露给不受信任目标的操作。
"""

强制执行 deny-read 要求​

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

[permissions.filesystem]
deny_read = [
  # 值可以是绝对路径……
  "/**/*.env",
  # ……也可以使用 `~` 表示相对于 $HOME/%USERPROFILE% 的路径。
  "~/.ssh",
  # 但是不允许以 `./` 开头的相对路径。
]

当存在 deny-read 要求时，Codex 会将本地沙箱模式限制为 read-only 或 workspace-write，以便 Codex 能够强制执行这些要求。在原生 Windows 上，托管的 deny_read 适用于直接文件工具；shell 子进程读取不使用此沙箱规则。

从 requirements 强制执行托管 hooks​

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

若要即使对本地已禁用 hooks 的用户也强制执行托管 hooks，请在 [hooks] 旁边固定设置 [features].hooks = 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"
timeout = 30
statusMessage = "Checking managed Bash command"

注意：

  • Codex 会强制执行来自 requirements.toml 的 hook 配置，但不会分发 managed_dir 中的脚本。
  • 请使用你的 MDM 或设备管理方案单独下发这些脚本。
  • 托管 hook 命令应引用已配置托管目录下的绝对脚本路径。

从 requirements 强制执行命令规则​

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

与 .rules 不同，requirements 规则必须指定 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 覆盖会应用到基础层，但托管层会覆盖它们。这意味着即使你提供了本地标志，每次运行仍会从托管默认值开始。

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

位置​

  • 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（requirements）

Codex 会将这些“托管偏好设置”负载解析为 TOML。对于托管默认值（config_toml_base64），托管偏好设置具有最高优先级。对于 requirements（requirements_toml_base64），优先级遵循上文所述的云托管 requirements 顺序。requirements 侧同一个 [features] 表也适用于 requirements_toml_base64；同样请在那里使用规范特性键。

MDM 设置工作流​

Codex 遵循标准的 macOS MDM 负载，因此你可以使用 Jamf Pro、Fleet 或 Kandji 等工具分发设置。一个轻量级部署如下所示：

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

避免在负载中嵌入密钥或高频变化的动态值。应像对待其他受变更控制的 MDM 设置一样对待托管 TOML。

managed_config.toml 示例​

# 设置保守的默认值
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

[sandbox_workspace_write]
network_access = false             # 除非明确允许，否则保持网络禁用

[otel]
environment = "prod"
exporter = "otlp-http"            # 指向你的收集器
log_user_prompt = false            # 保持提示词被隐藏
# exporter 详细信息位于 exporter 表下；参见上文“监控与遥测”
  • 对大多数用户，优先使用带审批的 workspace-write；为受控容器保留完全访问权限。
  • 保持 network_access = false，除非你的安全审查允许连接收集器或你的工作流所需的域名。
  • 使用托管配置固定 OTel 设置（exporter、environment），但除非你的策略明确允许存储提示词内容，否则保持 log_user_prompt = false。
  • 定期审计本地 config.toml 与托管策略之间的差异以发现漂移；托管层应覆盖本地标志和文件。