智能体审批与安全

Codex 有助于保护您的代码和数据，并降低被滥用的风险。

默认情况下，代理在关闭网络访问的状态下运行。在本地，Codex 使用操作系统级别的沙盒来限制其可访问的范围（通常限制在当前工作区），并结合审批策略来控制其在执行操作前必须暂停并征求您同意的时机。

有关沙盒在 Codex 应用程序、IDE 扩展和 CLI 中如何工作的宏观说明，请参阅 沙盒。如需更广泛的企业安全概述，请参阅 Codex 安全白皮书.

沙盒与审批

Codex 的安全控制由两个协同工作的层面组成：

• 沙盒模式: Codex 在执行模型生成的命令时能够执行的技术操作（例如，可以在哪里进行写入以及是否可以访问网络）。
• 审批策略: Codex 在执行操作前必须征得您同意的情况（例如，离开沙盒、使用网络或运行受信集合之外的命令）。

Codex 会根据您的运行位置使用不同的沙盒模式：

• Codex 云端: 在隔离的 OpenAI 托管容器中运行，防止访问您的主机系统或无关数据。采用两阶段运行时模型：设置阶段在代理阶段之前运行，并可访问网络以安装指定的依赖项；随后代理阶段默认在离线状态下运行，除非您为该环境启用了互联网访问。为云环境配置的密钥仅在设置阶段可用，并会在代理阶段开始前被移除。
• Codex CLI / IDE 扩展: 操作系统级别的机制会强制执行沙盒策略。默认设置包括无网络访问权限，且写入权限仅限于当前活动的工作区。您可以根据自身的风险承受能力，配置沙盒、审批策略和网络设置。

In the Auto 预设（例如， --sandbox workspace-write --ask-for-approval on-request）时，Codex 可以在工作目录中自动读取文件、进行编辑和运行命令。

对于在工作区外编辑文件或运行需要网络访问的命令，Codex 会请求批准。如果您只想进行聊天或规划而不做更改，请使用 read-only 模式的 /permissions command.

即使操作不是 shell 命令或文件更改，Codex 也会针对声明会产生副作用的 App（连接器）工具调用请求批准。当工具声明具有破坏性注解时，即使它同时声明了其他提示（例如只读提示），破坏性的 App/MCP 工具调用也始终需要批准。

网络访问 高风险

For Codex cloud, see 代理互联网访问 以启用完整的互联网访问或设置域名白名单。

对于 Codex 应用程序、CLI 或 IDE 扩展，默认的 workspace-write 沙盒模式会保持网络访问关闭，除非您在配置中将其启用：

[sandbox_workspace_write]
network_access = true

网络隔离

网络访问通过目标规则进行控制，这些规则适用于由命令生成的脚本、程序和子进程。当命令的网络访问已启用时，请开启 network_proxy 功能，以将流量限制在您配置的网络策略内。

[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow", "example.com" = "deny" }

对于一次性 CLI 会话，如果只需开启开关，请使用布尔简写形式；如果同时需要设置策略选项，请使用表单形式：

codex \
  -c 'features.network_proxy=true' \
  -c 'sandbox_workspace_write.network_access=true'

codex \
  -c 'features.network_proxy.enabled=true' \
  -c 'features.network_proxy.domains={ "api.openai.com" = "allow", "example.com" = "deny" }' \
  -c 'sandbox_workspace_write.network_access=true'

此功能改变了启用网络访问的强制执行方式；它本身并不授予网络访问权限。使用 sandbox_workspace_write.network_access with workspace-write 配置来决定命令是否具有网络访问权限：

• 网络关闭 + network_proxy 开启：网络保持关闭，此功能不执行任何操作。
• 网络开启 + network_proxy 关闭：网络保持开启，具有不受限制的直接出站访问权限。
• 网络开启 + network_proxy 开启：网络保持开启，出站流量受已配置的网络策略限制。

管理员管理的 experimental_network 要求独立于用户的功能开关。他们无需 features.network_proxy, 但当活动沙盒保持网络关闭时，它们并不会开启网络访问。请参阅 托管配置 for the administrator-side requirements.toml shape.

即可配置并启动沙盒网络

网络策略

• 域名规则以允许列表优先：
• *.example.com 精确的主机仅匹配其自身。 api.example.com, 但不包括 example.com.
• **.example.com 匹配子域名，例如
• A global * 同时匹配主域名和子域名。 * 允许规则会匹配任何未被拒绝的公共主机。将此视为
• deny 广泛的网络访问，并在条件允许时优先使用限定范围的规则。 allow, 以及全局 * 始终优先于

仅对允许规则有效。

默认情况下， allow_local_binding = false 本地和私有目标

• 阻止环回地址、链路本地地址和私有目标： localhost 特定例外：当命令需要访问某个本地目标时，添加精确的本地 IP 字面量或
• 允许规则。 allow_local_binding = true 更广泛的访问：仅在有意扩大本地/私有访问范围时才设置
• 通配符：通配符规则不计入显式的本地例外。
• 已解析的地址：解析为本地/私有 IP 的主机名仍会被阻止，即使它们与允许列表匹配也是如此。

DNS 重绑定保护

在允许主机名之前，Codex 会尽力执行 DNS 和 IP 分类检查：

• 失败或超时的查找请求将被阻止。
• 解析为非公共地址的主机名将被阻止。
• 该检查降低了 DNS 重绑定风险，但并不能完全消除它。要完全防止重绑定，需要通过传输层固定解析出的 IP 地址。

如果恶意 DNS 在攻击范围内，请同时在更底层实施出站控制。

危险配置

有两项设置会刻意扩大信任边界：

• dangerously_allow_non_loopback_proxy = true 可能会将代理监听器暴露在回环地址之外。
• dangerously_allow_all_unix_sockets = true 会绕过 Unix 套接字白名单。

请仅在严格受控的环境中使用它们。当启用 Unix 套接字代理时，即使请求绑定到非回环地址，监听器也仅限于回环地址，因此沙盒网络不会成为远程访问本地守护进程的桥接。

network_proxy 默认关闭。当你启用它时：

您还可以控制 网页搜索工具 而无需向生成的命令授予完全的网络访问权限。Codex 默认使用网络搜索缓存来访问结果。该缓存是由 OpenAI 维护的网络结果索引，因此缓存模式会返回预先索引的结果，而不是获取实时页面。这减少了对任意实时内容的提示注入风险，但您仍应将网络结果视为不受信任的内容。如果您正在使用 --yolo or another 完全访问沙盒设置, 网页搜索默认返回实时结果。使用 --search or set web_search = "live" 以允许实时浏览，或者将其设置为 "disabled" 以关闭该工具：

web_search = "cached"  # default
# web_search = "disabled"
# web_search = "live"  # same as --search

在 Codex 中启用网络访问或网络搜索时请务必谨慎。提示注入可能会导致代理获取并遵循不受信任的指令。

默认设置与建议

• 启动时，Codex 会检测文件夹是否受版本控制，并建议：
  • 版本控制的文件夹： Auto (工作区写入 + 按需批准)
  • 非版本控制的文件夹： read-only
• 根据您的配置，Codex 可能也会在 read-only 中启动，直到您显式信任该工作目录（例如，通过引导提示或 /permissions).
• 工作区包括当前目录以及临时目录，如 /tmp。使用 /status 命令查看工作区中包含哪些目录。
• 要接受默认设置，请运行 codex.
• 您可以显式设置它们：
  • codex --sandbox workspace-write --ask-for-approval on-request
  • codex --sandbox read-only --ask-for-approval on-request

可写根目录中的受保护路径

In the default workspace-write 沙盒策略下，可写根目录仍包含受保护路径：

• <writable_root>/.git 无论作为目录还是文件存在，都受只读保护。
• If <writable_root>/.git 是指针文件 (gitdir: ...），解析后的 Git 目录路径也受只读保护。
• <writable_root>/.agents 当作为目录存在时，受只读保护。
• <writable_root>/.codex 当作为目录存在时，受只读保护。
• 保护是递归的，因此这些路径下的所有内容均为只读。

运行而无需批准提示

您可以使用 --ask-for-approval never or -a never (简写形式) 禁用批准提示。

此选项适用于所有 --sandbox 模式，因此您仍然可以控制 Codex 的自主级别。Codex 会在您设置的约束内尽最大努力执行。

如果您需要 Codex 在无批准提示的情况下读取文件、进行编辑并在具有网络访问权限的情况下运行命令，请使用 --sandbox danger-full-access (或 --dangerously-bypass-approvals-and-sandbox 标志)。请在操作前谨慎考虑。

For a middle ground, approval_policy = { granular = { ... } } 允许您保持特定批准提示类别为交互式，同时自动拒绝其他类别。细粒度策略涵盖沙盒批准、execpolicy-rule 提示、MCP 提示、 request_permissions 提示和技能脚本批准。

自动批准审查

默认情况下，批准请求会路由给您：

approvals_reviewer = "user"

当批准为交互式时，自动批准审查适用，例如 approval_policy = "on-request" 或细粒度批准策略。请设置 approvals_reviewer = "auto_review" 将符合条件的审批请求路由至审查者代理，然后再由 Codex 执行该请求：

approval_policy = "on-request"
approvals_reviewer = "auto_review"

有关完整的审查者生命周期、触发条件、配置优先级和失败行为，请参阅 自动审查.

审查者仅评估已需要审批的操作，例如沙箱提权、被阻止的网络请求、 request_permissions 提示或具有副作用的 App 和 MCP 工具调用。在沙箱内执行的操作无需额外审查步骤即可继续。

审查者策略会检查数据外泄、凭证探测、持续性的安全削弱以及破坏性操作。低风险和中等风险的操作在策略允许时可以继续执行。策略会拒绝严重风险的操作。高风险操作需要足够的用户授权且没有匹配的拒绝规则。提示构建、审查会话和解析失败时一律安全拒绝（fail closed）。超时会单独提示，但相关操作同样不会运行。

The 默认审查者策略 位于开源 Codex 仓库中。企业可以替换其特定租户的部分，使用 guardian_policy_config in managed requirements. Local [auto_review].policy 也支持文本，但托管要求的优先级更高。有关设置的详细信息，请参阅 托管配置.

在 Codex 应用中，这些审查会显示为自动审查项，其状态包括审查中、已批准、已拒绝、已中止或已超时。它们还可能包含所审查请求的风险级别和用户授权评估。

自动审查会使用额外的模型调用，因此可能会增加 Codex 的用量。管理员可以通过以下方式进行限制： allowed_approvals_reviewers.

常见的沙箱和审批组合

For non-interactive runs, use codex exec --sandbox workspace-write；Codex 会保留较旧的 codex exec --full-auto 调用作为已弃用的兼容路径，并打印警告。

With --ask-for-approval untrusted, Codex 仅自动执行已知安全的读取操作。可能会改变状态或触发外部执行路径的命令（例如，破坏性的 Git 操作或 Git 输出/配置覆盖标志）需要经过审批。

配置位于 config.toml

有关更广泛的配置工作流程，请参阅 配置基础, 高级配置, 以及 配置参考.

# Always ask for approval mode
approval_policy = "untrusted"
sandbox_mode    = "read-only"
allow_login_shell = false # optional hardening: disallow login shells for shell-based tools

# Optional: Allow network in workspace-write mode
[sandbox_workspace_write]
network_access = true

# Optional: granular approval policy
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

您还可以将预设保存为 配置文件, 然后使用 codex --profile profile-name:

# ~/.codex/full_auto.config.toml
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

# ~/.codex/readonly_quiet.config.toml
approval_policy = "never"
sandbox_mode    = "read-only"

在本地测试沙盒

要查看在 Codex 沙盒中运行命令时会发生什么，请使用以下 Codex CLI 命令：

# macOS
codex sandbox macos [--permissions-profile <name>] [--log-denials] [COMMAND]...
# Linux
codex sandbox linux [--permissions-profile <name>] [COMMAND]...
# Windows
codex sandbox windows [--permissions-profile <name>] [COMMAND]...

The sandbox 命令也可用作 codex debug 进行选择，并且平台辅助程序具有别名（例如 codex sandbox seatbelt and codex sandbox landlock).

操作系统级沙盒

Codex 根据您的操作系统以不同方式执行沙盒：

• macOS 使用 Seatbelt 策略，并使用以下工具运行命令： sandbox-exec with a profile (-p) 对应于您选择的 --sandbox 模式。当受限读取访问启用平台默认值时，Codex 会附加精心设计的 macOS 平台策略（而不是广泛地允许 /System) 以保持常见工具的兼容性。
• Linux 默认使用 bwrap 以及 seccomp 默认情况下。
• Windows 在以下环境中运行时使用 Linux 沙盒实现： 适用于 Linux 2 的 Windows 子系统 (WSL2)。Codex 一直支持通过 WSL1 直至 0.114；从 0.115开始，Linux 沙盒已迁移至 bwrap, 因此不再支持 WSL1。当在 Windows 上原生运行时，Codex 使用 Windows 沙盒 implementation.

如果您在 Windows 上使用 Codex IDE 扩展，它直接支持 WSL2。请在 VS Code 设置中进行以下配置，以便在 WSL2 可用时将代理保留在 WSL2 内：

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

这确保了即使主机操作系统是 Windows，IDE 扩展在命令、审批和文件系统访问方面也能继承 Linux 沙盒语义。了解更多信息，请参阅 Windows 设置指南.

在 Windows 上原生运行时，请在以下位置配置原生沙盒模式： config.toml:

[windows]
sandbox = "unelevated" # or "elevated"
# sandbox_private_desktop = true  # default; set false only for compatibility

参阅 GitHub 上的 Windows 设置指南 for details.

当您在 Docker 等容器化环境中运行 Linux 时，如果主机或容器配置阻止了 Codex 所需的命名空间、setuid bwrap, or seccomp 操作，沙盒可能无法工作。

在这种情况下，请配置您的 Docker 容器以提供所需的隔离，然后运行 codex with --sandbox danger-full-access (或 --dangerously-bypass-approvals-and-sandbox 标志）在容器内部运行。

在开发容器中运行 Codex

如果你的宿主机无法直接运行 Linux 沙箱，或者你的组织已将容器化开发作为标准，请使用 Dev Containers 运行 Codex，让 Docker 提供外部隔离边界。此方案兼容 Visual Studio Code Dev Containers 及相关兼容工具。

使用 Codex 安全开发容器示例 作为参考实现。该示例安装了 Codex 及常用的开发工具， bubblewrap, 以及基于防火墙的出站控制。

The reference implementation includes:

• 基于 Ubuntu 24.04 的基础镜像，并预装了 Codex 及常用开发工具；
• 基于允许列表的出站访问防火墙策略；
• 用于在容器中重新打开工作区的 VS Code 设置和扩展推荐；
• 用于持久化命令历史记录和 Codex 配置的挂载卷；
• bubblewrap, 因此当容器授予所需权限时，Codex 仍然可以使用其 Linux 沙盒。

To try it:

1. 安装 Visual Studio Code 和 Dev Containers 扩展.
2. 将 Codex 示例 .devcontainer 配置复制到你的仓库中，或者直接基于 Codex 仓库进行操作。
3. In VS Code, run 开发容器：在容器中打开文件夹… and select .devcontainer/devcontainer.secure.json.
4. 容器启动后，打开终端并运行 codex.

你也可以通过 CLI 启动容器：

devcontainer up --workspace-folder . --config .devcontainer/devcontainer.secure.json

该示例包含三个主要部分：

• .devcontainer/devcontainer.secure.json 控制容器设置、功能、挂载、环境变量以及 VS Code 扩展。
• .devcontainer/Dockerfile.secure 定义了基于 Ubuntu 的镜像和已安装的工具。
• .devcontainer/init-firewall.sh 应用出站网络策略。

参考防火墙配置仅作为一个起点。如果你依赖域名允许列表来实现隔离，请实施适合你环境的 DNS 重绑定和 DNS 刷新保护机制，例如感知 TTL 的刷新或感知 DNS 的防火墙。

在容器内，请选择以下模式之一：

• 如果 Dev Container 配置文件授予了 bwrap 创建内部沙箱所需的权限，请保持 Codex 的 Linux 沙箱处于启用状态。
• 如果容器就是你预设的安全边界，请在容器内使用 --sandbox danger-full-access 运行 Codex，这样 Codex 就不会尝试创建第二层沙箱。

版本控制

Codex 在版本控制工作流下效果最佳：

• 在功能分支上工作，并在委托操作前保持 git status 干净。这会让 Codex 的补丁更容易隔离和还原。
• 优先使用基于补丁的工作流（例如， git diff/git apply) 而不是直接编辑被跟踪的文件。频繁提交，以便您能够以小增量回滚。
• 像对待任何其他 PR 一样对待 Codex 建议：运行针对性验证，审查差异，并在提交消息中记录决策以便审计。

监控与遥测

Codex 支持通过 OpenTelemetry (OTel) 进行选择性启用（opt-in）的监控，帮助团队审计使用情况、排查问题并满足合规要求，同时不会削弱本地安全默认设置。遥测默认处于关闭状态；请在配置中显式启用。

概览

• Codex 默认关闭 OTel 导出，以保持本地运行的自包含性。
• 启用后，Codex 会发出结构化日志事件，涵盖对话、API 请求、SSE/WebSocket 流活动、用户提示（默认脱敏）、工具批准决策以及工具结果。
• Codex 会为导出的事件添加 service.name （发起者）、CLI 版本和环境标签等标记，以区分开发/预发布/生产流量。

启用 OTel（选择性启用）

在您的 Codex 配置（通常是 [otel] ）中添加一个 ~/.codex/config.toml块，选择一个导出器并决定是否记录提示文本。

[otel]
environment = "staging"   # dev | staging | prod
exporter = "none"          # none | otlp-http | otlp-grpc
log_user_prompt = false     # redact prompt text unless policy allows

• exporter = "none" 会使检测保持活动状态，但不会将数据发送到任何地方。
• 要将事件发送到您自己的收集器，请从以下选项中选择一项：

[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}

[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

Codex 会批量处理事件并在关闭时清空。Codex 仅导出由其 OTel 模块生成的遥测数据。

事件类别

代表性事件类型包括：

• codex.conversation_starts (模型、推理设置、沙箱/审批策略)
• codex.api_request (尝试、状态/成功、持续时间以及错误详情)
• codex.sse_event (流事件类型、成功/失败、持续时间，以及以下对象的 token 计数： response.completed)
• codex.websocket_request and codex.websocket_event (请求持续时间，以及按消息划分的类型/成功/错误)
• codex.user_prompt （长度；内容已被隐去，除非明确启用）
• codex.tool_decision （已批准/已拒绝，来源：配置与用户）
• codex.tool_result （持续时间，是否成功，输出片段）

关联的 OTel 指标（计数器加上持续时间直方图对）包括 codex.api_request, codex.sse_event, codex.websocket.request, codex.websocket.event，且 codex.tool.call （带有相应的 .duration_ms 仪表）。

有关完整的事件目录和配置参考，请参见 GitHub 上的 Codex 配置文档.

安全和隐私指南

• 保持 log_user_prompt = false 除非策略明确允许存储提示词内容。提示词可能包含源代码和敏感数据。
• 仅将遥测数据路由至您控制的收集器；应用符合您合规要求的保留期限和访问控制。
• 将工具参数和输出视为敏感信息。尽可能在收集器或 SIEM 中进行脱敏处理。
• 查看本地数据保留设置（例如， history.persistence / history.max_bytes）如果您不希望 Codex 将会话记录保存在 CODEX_HOME。请参阅 高级配置 and 配置参考.
• 如果您在关闭网络访问的情况下运行 CLI，OTel 导出将无法连接到您的收集器。要进行导出，请在 workspace-write 模式下为 OTel 端点允许网络访问，或者通过 Codex 云端导出并将收集器域名添加到您的批准列表中。
• 定期审查事件，以检查审批/沙箱的更改以及意外的工具执行情况。

OTel 是可选的，旨在补充而非替代上述的沙箱和审批保护机制。

托管配置

企业管理员可以在以下位置为其工作区配置 Codex 安全设置： 托管配置。请参阅该页面以了解设置和策略详情。