智能体审批与安全

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

默认情况下，智能体运行时会关闭网络访问。在本地，Codex 使用由操作系统强制执行的沙箱来限制其可访问的范围（通常仅限当前工作区），并通过审批策略控制它必须在何时停止操作并先征得你的同意。

如需从整体上了解沙箱在 ChatGPT 桌面应用、 Codex CLI 和 IDE 扩展中的工作方式，请参阅沙箱。 如需更全面的企业安全概述，请参阅 Codex 安全白皮书。

沙箱与审批

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

• 沙箱模式：Codex 执行模型生成的命令时，在技术层面能够执行哪些操作（例如可写入哪些位置以及能否访问网络）。
• 审批策略：Codex 在执行操作前必须于何时征得你的同意（例如离开沙箱、使用网络或运行受信任集合之外的命令）。

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

• Codex cloud：在由 OpenAI 管理的隔离容器中运行，无法访问你的主机系统或无关数据。它采用两阶段运行时模型：设置阶段先于智能体阶段运行，并且可以访问网络以安装指定的依赖项；随后，智能体阶段默认离线运行，除非你为该环境启用互联网访问。为云环境配置的密钥仅在设置阶段可用，并会在智能体阶段开始前移除。
• Codex CLI / IDE 扩展：由操作系统级机制强制执行沙箱策略。默认设置包括禁止网络访问，并将写入权限限制在当前工作区。你可以根据自己的风险承受能力配置沙箱、审批策略和网络设置。

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

Codex 在编辑工作区之外的文件或运行需要网络访问的命令前会征求批准。如果你只想聊天或制定计划而不进行更改，请使用 /permissions 命令切换到 read-only 模式。

对于声明会产生副作用的应用（连接器）工具调用，Codex 也可以请求审批，即使该操作并非 shell 命令或文件更改。只要工具声明了破坏性注解，破坏性的应用/MCP 工具调用始终需要审批（除非工具同时声明了优先级更高的读取注解）。

网络访问

对于 Codex cloud，请参阅智能体互联网访问，了解如何启用完整互联网访问或域名允许列表。

对于 ChatGPT 桌面应用、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 及 workspace-write 配置来决定命令究竟能否访问网络：

• 网络关闭 + network_proxy 开启：网络仍保持关闭，该功能不起作用。
• 网络开启 + network_proxy 关闭：网络保持开启，并可不受限制地直接 向外访问。
• 网络开启 + network_proxy 开启：网络保持开启，出站流量 受已配置的网络策略约束。

代理功能也适用于权限配置文件。 配置文件中的 network.enabled = true 授予命令网络访问权限，而 features.network_proxy = true 会启用对该配置文件域名 规则的强制执行：

default_permissions = "project-edit"

[features]
network_proxy = true

[permissions.project-edit]
extends = ":workspace"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"

如果在此示例中省略代理功能，命令将拥有直接网络 访问权限，且 api.openai.com 允许规则不会限制其目标地址。

由管理员管理的 experimental_network 要求与用户的 功能开关相互独立。它们可以在没有 features.network_proxy 的情况下配置并启动沙箱网络，但当当前 沙箱保持网络关闭时，它们不会开启网络访问。有关管理员侧 requirements.toml 的结构，请参阅托管配置。

网络策略

域名规则以允许列表优先：

• 精确主机规则仅匹配该主机本身。
• *.example.com 匹配 api.example.com 等子域名，但不匹配 example.com。
• **.example.com 同时匹配顶级域名和子域名。
• 全局 * 允许规则匹配任何未被拒绝的公共主机。请将 * 视为宽泛的网络访问，并尽可能优先使用范围明确的规则。
• deny 的优先级始终高于 allow，且全局 * 仅可用于允许规则。

本地和私有目标

默认情况下，allow_local_binding = false 会阻止环回、链路本地和 私有目标：

• 特定例外：当命令需要访问某个本地目标时，添加精确的本地 IP 字面量或 localhost 允许规则。
• 更宽泛的访问：仅当你有意允许更广泛的本地/私有访问时，才设置 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 默认关闭。启用后：

命令网络代理之外的流量

网络代理会过滤在本地命令沙箱内运行的脚本、程序和 子进程。它不会过滤网页搜索、应用或 连接器工具调用、MCP 服务器连接、浏览器或 Computer Use 活动、 Codex cloud 任务，也不会过滤客户端的模型请求和身份验证请求。这些 功能面使用各自独立的服务连接、功能设置、工作区 策略或环境控制。

对于托管用户，请将命令网络策略与 allowed_web_search_modes、已批准的 mcp_servers 以及针对应用、插件、浏览器或 Computer Use 的 功能要求等控制措施结合使用。请参阅 托管配置。

你还可以单独控制网页搜索工具，而无需向启动的命令授予完整网络访问权限。Codex 默认使用网页搜索缓存来访问结果。该缓存是由 OpenAI 维护的网页结果索引，因此缓存模式返回预先建立索引的结果，而不是实时获取页面。这可以减少任意实时内容中提示词注入带来的风险，但你仍应将网页结果视为不可信内容。如果你使用 --yolo 或其他完整访问沙箱设置，网页搜索将默认返回实时结果。使用 --search 或将 web_search = "live" 设置为允许实时浏览，也可以将其设置为 "disabled" 以关闭该工具：

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

如果外部网页访问应由搜索索引把关，请设置 web_search = "indexed"。 在 Codex 中启用网络访问或网页搜索时请保持谨慎。 提示词注入可能导致智能体获取并遵循不可信的指令。

默认设置与建议

• 启动时，Codex 会检测文件夹是否受版本控制，并建议：
  • 受版本控制的文件夹：Auto（工作区写入 + 按请求审批）
  • 不受版本控制的文件夹：read-only
• 根据你的设置，在你明确将工作目录设为可信之前（例如通过初始设置提示或 /permissions），Codex 也可能以 read-only 启动。
• 工作区包括当前目录以及 /tmp 等临时目录。使用 /status 命令查看工作区包含哪些目录。
• 要接受默认设置，请运行 codex。
• 你也可以明确设置：
  • codex --sandbox workspace-write --ask-for-approval on-request
  • codex --sandbox read-only --ask-for-approval on-request

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

在默认的 workspace-write 沙箱策略中，可写根目录仍包含受保护路径：

• 无论 <writable_root>/.git 是目录还是文件，都会受到只读保护。
• 如果 <writable_root>/.git 是指针文件（gitdir: ...），解析后的 Git 目录路径也会受到只读保护。
• 如果 <writable_root>/.agents 以目录形式存在，则受到只读保护。
• 如果 <writable_root>/.codex 以目录形式存在，则受到只读保护。
• 保护是递归的，因此这些路径下的所有内容均为只读。

在没有审批提示的情况下运行

你可以使用 --ask-for-approval never 或 -a never（简写）禁用审批提示。

此选项适用于所有 --sandbox 模式，因此你仍可控制 Codex 的自主程度。Codex 会在你设定的限制内尽力完成任务。

如果需要让 Codex 在不显示审批提示的情况下读取文件、进行编辑并运行需要网络访问的命令，请使用 --sandbox danger-full-access（或 --dangerously-bypass-approvals-and-sandbox 标志）。使用前请务必谨慎。

作为折中方案，approval_policy = { granular = { ... } } 允许你让特定类别的审批提示保持交互，同时自动拒绝其他类别。精细化策略涵盖沙箱审批、execpolicy 规则提示、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 提示，或 会产生副作用的应用和 MCP 工具调用。沙箱内的操作 无需额外审查即可继续执行。

审查器策略会检查数据外泄、凭据探测、持续性的 安全弱化以及破坏性操作。策略允许时，低风险和中风险操作 可以继续执行。策略会拒绝严重风险操作。 高风险操作必须获得充分的用户授权，且不能匹配任何拒绝规则。 提示词构建、审查会话和解析失败时会以拒绝方式安全终止。超时会 单独显示，但相应操作仍不会运行。

默认审查器策略 位于开源 Codex 仓库中。企业可以在托管要求中使用 guardian_policy_config 替换其中的租户专属部分。 也支持本地 [auto_review].policy 文本，但托管要求的优先级 更高。有关设置详情，请参阅 托管配置。

在 ChatGPT 桌面应用中，这些审查会显示为自动审查项，其状态 可能为 Reviewing、Approved、Denied、Aborted 或 Timed out。它们还可以 包含风险等级以及对受审查请求的用户授权评估。

自动审查会额外调用模型，因此可能增加 Codex 用量。管理员 可以使用 allowed_approvals_reviewers 对其进行限制。

常见的沙箱与审批组合

对于非交互式运行，请使用 codex exec --sandbox workspace-write；Codex 会将旧版 codex exec --full-auto 调用保留为已弃用的兼容路径，并显示警告。

使用 --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]...

sandbox 命令也可以写作 codex debug，平台辅助工具也有别名（例如 codex sandbox seatbelt 和 codex sandbox landlock）。

操作系统级沙箱

Codex 会根据你的操作系统以不同方式强制执行沙箱：

• macOS 使用 Seatbelt 策略，并通过 sandbox-exec 使用与你选择的 --sandbox 模式对应的配置文件（-p）运行命令。当受限读取访问启用平台默认规则时，Codex 会追加一组精选的 macOS 平台策略（而不是宽泛地允许 /System），以保持常用工具的兼容性。
• Linux 默认使用 bwrap 加 seccomp。
• Windows 在 Windows Subsystem for Linux 2 (WSL2) 中运行时使用 Linux 沙箱实现。WSL1 的支持持续到 Codex 0.114；从 0.115 开始，Linux 沙箱迁移到了 bwrap，因此不再支持 WSL1。在 Windows 上以原生方式运行时，Codex 使用 Windows 沙箱实现。

如果你在 Windows 上使用 Codex IDE 扩展，该扩展可直接支持 WSL2。在 VS Code 设置中添加以下内容，使智能体在 WSL2 可用时始终在其中运行：

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

这样可以确保即使主机操作系统是 Windows，IDE 扩展也会沿用 Linux 的命令、审批和文件系统访问沙箱语义。有关更多信息，请参阅 WSL 指南。

在 Windows 上以原生方式运行时，请在 config.toml 中配置原生沙箱模式：

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

有关详情，请参阅 Windows 设置指南。

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

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

在 Dev Containers 中运行 Codex

如果你的主机无法直接运行 Linux 沙箱，或者你的组织已统一采用容器化开发，请使用 Dev Containers 运行 Codex，并由 Docker 提供外层隔离边界。此方式适用于 Visual Studio Code Dev Containers 及兼容工具。

请以 Codex 安全 devcontainer 示例作为参考实现。该示例会安装 Codex、常用开发工具、bubblewrap 以及基于防火墙的出站控制。

参考实现包括：

• 安装了 Codex 和常用开发工具的 Ubuntu 24.04 基础镜像；
• 由允许列表驱动的出站访问防火墙配置；
• 用于在容器中重新打开工作区的 VS Code 设置和扩展建议；
• 用于保存命令历史记录和 Codex 配置的持久挂载；
• bubblewrap，使容器授予所需能力时，Codex 仍可使用其 Linux 沙箱。

试用步骤：

1. 安装 Visual Studio Code 和 Dev Containers 扩展。
2. 将 Codex 示例 .devcontainer 设置复制到你的仓库中，或直接从 Codex 仓库开始。
3. 在 VS Code 中运行 Dev Containers: Open Folder in Container...，然后选择 .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) 的监控，帮助团队审计使用情况、调查问题并满足合规要求，同时不削弱本地安全默认设置。遥测默认关闭；请在配置中明确启用。

概述

• Codex 默认关闭 OTel 导出，使本地运行保持自包含状态。
• 启用后，Codex 会发出结构化日志事件，涵盖聊天、API 请求、SSE/WebSocket 流活动、用户提示词（默认遮盖）、工具审批决策和工具结果。
• Codex 会使用 service.name（发起方）、CLI 版本和环境标签标记导出的事件，以区分开发/预发布/生产流量。

启用 OTel（选择启用）

在 Codex 配置（通常为 ~/.codex/config.toml）中添加 [otel] 块，并选择导出器以及是否记录提示词文本。

[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（流事件类型、成功/失败、持续时间，以及 response.completed 上的 token 计数）
• codex.websocket_request 和 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 中进行遮盖。
• 如果你不希望 Codex 将会话记录保存在 CODEX_HOME 下，请检查本地数据保留设置（例如 history.persistence / history.max_bytes）。请参阅高级配置和配置参考。
• 如果运行 CLI 时关闭了网络访问，OTel 导出将无法连接到收集器。要导出数据，请在 workspace-write 模式下允许访问 OTel 端点的网络，或者从 Codex cloud 导出，并将收集器域名加入已批准列表。
• 定期检查事件，关注审批/沙箱变更和意外的工具执行。

OTel 是可选功能，旨在补充而非取代上述沙箱和审批保护措施。

托管配置

企业管理员可以在托管配置中为其工作区配置 Codex 安全设置。有关设置和策略详情，请参阅该页面。