OpenAI Codex 中文文档（4.14更新）
联系我 ↗
官方文档 ↗

托管配置

管理员可以用统一的强制规则和默认设置，控制本地 Codex 的行为。

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

  • 强制规则（Requirements）：管理员规定哪些值可以使用，用户不能覆盖
  • 托管默认值（Managed defaults）：Codex 启动时先采用这些默认值。用户在当前会话中仍可修改，但下次启动时会重新回到管理员设定的默认值

管理员强制规则（requirements.toml）

requirements.toml 用来限制安全相关设置，例如 approval_policy、sandbox_mode、Web 搜索模式，以及允许启用哪些 MCP server。Codex 在汇总配置时，例如读取 config.toml、profile 或 CLI 覆盖参数，如果发现某个值和强制规则冲突，就会自动改用符合要求的值，并提示用户。

如果你为 mcp_servers 配置了允许列表，只有当 server 的名称和身份信息都与允许项匹配时，Codex 才会启用它；否则会将其禁用。

你也可以通过 requirements.toml 的 [features] 表固定功能开关（feature flags）的取值。功能开关不一定都与安全相关，但如果企业希望统一行为，也可以在这里锁定。没有写出的键不会受到限制。

完整键列表请参见配置参考中的 requirements.toml。

位置与优先级

Codex 会按下面的顺序读取并应用强制规则；对同一个字段来说，越靠前优先级越高：

  1. 云端托管强制规则（ChatGPT Business 或 Enterprise）
  2. 通过 com.openai.codex:requirements_toml_base64 下发的 macOS managed preferences（MDM）
  3. 系统级 requirements.toml，例如 Unix 系统（包括 Linux / macOS）上的 /etc/codex/requirements.toml

不同来源会按字段合并。如果更高优先级的一层已经写了某个字段，即使它是空列表，后面的层也不能再改这个字段；但仍然可以补充那些尚未设置的字段。

为了兼容旧版本，Codex 也会把旧式 managed_config.toml 里的 approval_policy 和 sandbox_mode 视为强制规则，也就是只允许这一个取值。

云端托管强制规则

当用户用 ChatGPT 账号登录 Business 或 Enterprise 计划时，Codex 还可以从服务端获取管理员设置的强制规则。这一层与 requirements.toml 兼容，并会同时作用于 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 示例。

把强制规则分配给用户组

管理员可以为不同的用户组设置不同的托管强制规则，也可以配置一条默认规则作为兜底。

如果某个用户同时匹配多条分组规则，只会采用第一条命中的规则。后面命中的规则不会再补齐前面没写的字段。

例如，如果第一条命中的规则只设置了 allowed_sandbox_modes = ["read-only"]，而后面另一条命中的规则设置了 allowed_approval_policies = ["on-request"]，那么 Codex 只会应用第一条规则，不会再从后面的规则补充 allowed_approval_policies。

Codex 如何在本地应用云端托管强制规则

当用户启动 Codex，并用 ChatGPT 登录 Business 或 Enterprise 计划时，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"]

你也可以限制 Web 搜索模式：

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

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

例如，allowed_web_search_modes = ["cached"] 会禁止实时 Web 搜索，即使用户当前会话运行在 danger-full-access 模式下也一样。

你也可以固定功能开关（feature flags）的取值：

[features]
personality = true
unified_exec = false

这里要使用 config.toml 的 [features] 表中定义的标准键名。Codex 会确保最终生效的功能开关符合这些固定值，并拒绝把冲突设置写入 config.toml 或 profile 级配置。

通过 requirements 强制执行命令规则

管理员还可以在 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 server，可以为 mcp_servers 配置允许列表。对于 stdio server，要匹配 command；对于 streamable HTTP server，要匹配 url：

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

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

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

托管默认值（managed_config.toml）

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，优先级则遵循上文“云端托管强制规则”的顺序。

在 requirements_toml_base64 里同样可以使用 [features] 表，这里也要使用标准键名。

MDM 设置流程

Codex 兼容标准 macOS MDM 配置格式，所以你可以用 Jamf Pro、Fleet 或 Kandji 这类工具统一下发设置。一个轻量的部署流程通常如下：

  1. 写好要下发的 TOML，再用 base64 编码，编码结果不要换行。
  2. 把编码后的字符串放进 MDM 配置描述文件的 com.openai.codex 域，写到 config_toml_base64（托管默认值）或 requirements_toml_base64（强制规则）。
  3. 下发 profile 后，让用户重启 Codex，并确认启动时显示的配置摘要已经反映管理员设置的值。
  4. 如果需要撤销或调整策略，更新这份托管内容；CLI 会在下次启动时读取新的偏好设置。

不要在这份内容里写入 secret 或频繁变动的动态值。应把这份托管 TOML 当作正式受控配置来管理，和其他需要走变更流程的 MDM 设置保持同样的管理方式。

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；只有在受控容器环境中，才考虑开放完全访问。
  • 除非你的安全评估已经允许访问 OTel 采集端或工作流所需域名，否则应保持 network_access = false。
  • 可以用托管配置固定 OTel 的 exporter、environment 等设置，但除非策略明确允许保存 prompt 内容，否则应保持 log_user_prompt = false。
  • 应定期检查本地 config.toml 与托管策略之间的差异，及时发现配置漂移；最终应始终以托管层覆盖本地文件和命令行参数。

来源：https://developers.openai.com/codex/enterprise/managed-configuration