Agent 审批与安全
如需完整文档索引，请参阅 llms.txt。文档页面的 Markdown 版本可通过在页面后追加
.md来获取 URL。
Codex 有助于保护你的代码和数据，并降低滥用风险。
本页介绍如何安全地操作 Codex ，包括沙箱、审批、 以及网络访问。如果你在寻找 Codex Security，即用于 扫描已连接 GitHub 代码仓库的产品，请参阅 Codex Security。
默认情况下，Agent 运行时会关闭网络访问。在本地， Codex 使用一个由 OS强制执行的沙箱来限制它可以接触的内容（通常限于当前工作区），并配合审批策略来控制它在执行操作前何时必须停止并询问你。
如需了解沙箱如何在 ChatGPT 桌面应用、 Codex CLI和 IDE 扩展中工作的高层说明，请参阅 沙箱。 如需更全面的企业安全概览，请参阅 Codex 安全白皮书。
Codex 的安全控制来自两个协同工作的层面：
- 沙箱模式：Codex 执行模型生成的命令时，在技术层面能够执行的操作（例如可以在哪里写入，以及是否能够访问网络）。
- 审批策略：Codex 在执行操作前必须向你询问的时机（例如离开沙箱、使用网络或运行受信任集合之外的命令）。
Codex 会根据运行位置使用不同的沙箱模式：
- Codex cloud：在隔离的 OpenAI托管容器中运行，防止访问你的主机系统或无关数据。使用两阶段运行时模型：设置阶段在 Agent 阶段之前运行，并且可以访问网络来安装指定依赖；随后 Agent 阶段默认离线运行，除非你为该环境启用互联网访问。为云环境配置的密钥仅在设置阶段可用，并会在 Agent 阶段开始前移除。
- Codex CLI / IDE 扩展： OS级机制会强制执行沙箱策略。默认设置包括无网络访问，并且写入权限仅限于活动工作区。你可以根据自己的风险承受能力配置沙箱、审批策略和网络设置。
在 Auto 预设中（例如 --sandbox workspace-write --ask-for-approval on-request），Codex 可以自动读取文件、进行编辑，并在工作目录中运行命令。
Codex 会在编辑工作区外的文件，或运行需要网络访问的命令时请求审批。如果你想在不进行更改的情况下聊天或制定计划，请使用 read-only 命令切换到 /permissions 模式。
Codex 还可以对声明具有副作用的应用（连接器）工具调用触发审批，即使该操作不是 shell 命令或文件更改。当工具声明了破坏性注解时，破坏性的 app/MCP 工具调用始终需要审批，即使它同时声明了其他提示（例如只读提示）。
交互内容： ElevatedRiskBadge 的动态演示请参阅页面顶部的官方原文链接。
对于 Codex cloud，请参阅 代理互联网访问，以启用完整的互联网访问或域名允许列表。
对于 ChatGPT 桌面应用、Codex CLI 或 IDE extension，默认的 workspace-write 沙箱模式会保持网络访问关闭，除非你在配置中启用网络访问：
[sandbox_workspace_write]network_access = true网络访问通过目标规则控制，这些规则适用于脚本、
程序，以及由命令生成的子进程。当命令网络访问
已启用时，开启 network_proxy 功能以将该流量限制
在你配置的网络策略内。
[features.network_proxy]enabled = truedomains = { "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开启：网络保持开启，出站流量 受配置的网络策略限制。
管理员管理的 experimental_network 要求独立于用户
功能开关。它们可以在没有
features.network_proxy的情况下配置并启动沙箱网络，但当活动
沙箱保持网络关闭时，它们不会开启网络访问。请参阅 托管配置
了解管理员侧的 requirements.toml 形式。
域名规则以允许列表优先：
- 精确主机仅匹配其自身。
*.example.com会匹配诸如api.example.com这样的子域名，但不匹配example.com。**.example.com会同时匹配根域和子域名。- 全局
*允许规则会匹配任何未被拒绝的公共主机。请将*视为宽泛的网络访问，并尽可能优先使用限定范围的规则。 deny始终优先于allow，并且全局*仅对允许规则有效。
本地和私有目标
Section titled “本地和私有目标”默认情况下， allow_local_binding = false 会阻止环回、链路本地和
私有目标：
- 特定例外：添加精确的本地 IP 字面量或
localhost允许规则 ，当命令需要一个本地目标时。 - 更广泛的访问：仅在你有意
allow_local_binding = true希望获得更宽泛的 访问范围时，才设置 local/private 。 - 通配符：通配符规则不算作显式本地例外。
- 解析后的地址：解析到 local/private IPs 的主机名会保持被阻止 ，即使它们匹配允许列表。
DNS 重绑定保护
Section titled “DNS 重绑定保护”在允许某个主机名之前， Codex 会执行尽力而为的 DNS 和 IP 分类检查：
- 失败或超时的查询会被阻止。
- 解析到非公共地址的主机名会被阻止。
- 该检查会降低 DNS 重绑定风险，但无法消除它。要完全防止 重绑定，需要固定解析后的 IPs 并贯穿传输 层。
如果恶意 DNS 属于威胁范围，还应在更低层级强制执行出站控制。
以下两个设置会有意扩大信任边界：
dangerously_allow_non_loopback_proxy = true可以将代理监听器暴露到 环回之外。dangerously_allow_all_unix_sockets = true会绕过 Unix 套接字允许列表。
仅在严格受控的环境中使用它们。当 Unix 套接字代理 启用时，即使请求了非环回绑定，监听器也会保持仅限环回， 因此沙箱网络不会成为通向本地守护进程的远程桥接。
默认情况下，network_proxy 处于关闭状态。启用后：
| 设置 | 默认值 | 行为 |
|---|---|---|
enabled |
false |
仅当命令网络访问已开启时，才启动沙箱网络。 |
domains |
未设置 | 使用允许列表行为，因此在你添加 allow 规则之前，不允许访问任何外部目标。支持精确主机、限定范围的通配符，以及全局 * 允许规则； deny 始终优先。 |
unix_sockets |
未设置 | 在你添加显式 allow 规则之前，不允许任何 Unix 套接字目标。 |
allow_local_binding |
false |
阻止本地和私有网络目标，除非你添加精确的本地 IP 字面量或 localhost 允许规则，或明确选择更广泛的 local/private 访问。 |
enable_socks5 |
true |
在策略允许时暴露 SOCKS5 支持。 |
enable_socks5_udp |
true |
允许 UDP 通过 SOCKS5 使用，当 SOCKS5 可用时。 |
allow_upstream_proxy |
true |
让沙箱网络遵循环境中的上游代理。 |
dangerously_allow_non_loopback_proxy |
false |
除非你有意将监听端点暴露到 localhost 之外，否则会将其保持在环回上。 |
dangerously_allow_all_unix_sockets |
false |
除非你有意绕过该保护，否则会让 Unix 套接字访问保持基于允许列表。 |
你还可以控制网页搜索工具，而无需授予已启动命令完整的网络访问权限。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中启用网络访问或网页搜索时请谨慎。
提示注入可能导致 Agent 获取并遵循不可信指令。
默认设置与建议
Section titled “默认设置与建议”- 启动时，Codex 会检测文件夹是否受版本控制，并给出建议：
- 受版本控制的文件夹：
Auto（工作区写入 + 按请求审批） - 不受版本控制的文件夹：
read-only
- 受版本控制的文件夹：
- 根据你的设置，Codex 也可能先以
read-only模式启动，直到你明确信任工作目录（例如通过引导提示或/permissions）。 - 工作区包括当前目录和
/tmp等临时目录。使用/status命令查看哪些目录位于工作区中。 - 要接受默认设置，请运行
codex。 - 你可以显式设置：
codex --sandbox workspace-write --ask-for-approval on-requestcodex --sandbox read-only --ask-for-approval on-request
可写根目录中的受保护路径
Section titled “可写根目录中的受保护路径”在默认的 workspace-write 沙箱策略下，可写根目录仍包含受保护路径：
<writable_root>/.git无论以目录还是文件形式出现，都会作为只读受到保护。- 如果
<writable_root>/.git是一个指针文件（gitdir: ...），解析出的 Git 目录路径也会作为只读受到保护。 <writable_root>/.agents当它作为目录存在时，会作为只读受到保护。<writable_root>/.codex当它作为目录存在时，会作为只读受到保护。- 保护是递归的，因此这些路径下的所有内容都是只读的。
在不显示审批提示的情况下运行
Section titled “在不显示审批提示的情况下运行”你可以使用 --ask-for-approval never 或简写形式 -a never 禁用审批提示。
此选项适用于所有 --sandbox 模式，因此你仍然可以控制 Codex 的自主程度。Codex 会在你设定的约束范围内尽力运行。
如果你需要 Codex 在不显示审批提示的情况下读取文件、进行编辑并使用网络访问运行命令，请使用 --sandbox danger-full-access（或 --dangerously-bypass-approvals-and-sandbox 标志）。使用前请谨慎评估。
作为折中方案，approval_policy = { granular = { ... } } 允许你保留特定审批提示类别的交互式确认，同时自动拒绝其他类别。细粒度策略涵盖沙箱审批、execpolicy-rule 提示、MCP 提示、request_permissions 提示和技能脚本审批。
自动审批审查
Section titled “自动审批审查”默认情况下，审批请求会转交给你：
approvals_reviewer = "user"当审批是交互式时，例如
approval_policy = "on-request" 或细粒度审批策略，自动审批审查会生效。设置
approvals_reviewer = "auto_review" 可在
运行请求之前，通过审查 Agent 路由符合条件的审批请求 Codex ：
approval_policy = "on-request"approvals_reviewer = "auto_review"如需完整的审查器生命周期、触发条件、配置优先级 和失败行为，请参阅 自动审查。
审查器只评估已经需要审批的操作，例如沙箱
提权、被阻止的网络请求、 request_permissions 提示，或
具有副作用的应用和 MCP 工具调用。保持在沙箱内的操作
会继续执行，不会增加额外的审查步骤。
审查器策略会检查数据外泄、凭据探测、持久性 安全削弱，以及破坏性操作。当策略允许时，低风险和中风险操作 可以继续执行。该策略会拒绝严重风险操作。 高风险操作需要足够的用户授权，并且没有匹配的拒绝规则。 提示构建、审查会话和解析失败会失败关闭。超时会 单独显示，但操作仍不会运行。
该 默认审查器策略
位于开源 Codex 代码仓库中。企业可以将其
租户特定部分替换为 guardian_policy_config ，在托管要求中使用。
也支持本地 [auto_review].policy 文本，但托管要求
优先。有关设置详情，请参阅
托管配置。
在 ChatGPT 桌面应用中，这些审查会显示为自动审查项，并带有 “正在审查”、“已批准”、“已拒绝”、“已中止”或“已超时”等状态。它们还可以 包含被审查 请求的风险级别和用户授权评估。
自动审查会使用额外的模型调用，因此可能增加 Codex 用量。管理员
可以使用 allowed_approvals_reviewers对其进行限制。
常见沙箱与审批组合
Section titled “常见沙箱与审批组合”| 意图 | 标志 / 配置 | 效果 |
|---|---|---|
| 自动（预设） | 无需标志 或 --sandbox workspace-write --ask-for-approval on-request |
Codex 可以读取文件、进行编辑，并在工作区中运行命令。 Codex 需要审批才能编辑工作区之外的内容或访问网络。 |
| 安全的只读浏览 | --sandbox read-only --ask-for-approval on-request |
Codex 可以读取文件并回答问题。 Codex 需要审批才能进行编辑、运行命令或访问网络。 |
| 只读非交互式（CI） | --sandbox read-only --ask-for-approval never |
Codex 只能读取文件；从不请求审批。 |
| 自动编辑，但运行不受信任的命令前请求审批 | --sandbox workspace-write --ask-for-approval untrusted |
Codex 可以读取和编辑文件，但在运行不受信任的命令前会请求审批。 |
| 自动审查模式 | --sandbox workspace-write --ask-for-approval on-request -c approvals_reviewer=auto_review 或 approvals_reviewer = "auto_review" |
沙箱边界与标准的按需请求模式相同，但符合条件的审批请求会由自动审查来审查，而不是呈现给用户。 |
| 危险的完全访问权限 | --dangerously-bypass-approvals-and-sandbox （别名： --yolo） |
交互内容： ElevatedRiskBadge 的动态演示请参阅页面顶部的官方原文链接。 无沙箱；无审批 （不推荐） |
对于非交互式运行，请使用 codex exec --sandbox workspace-write；Codex 会将旧版 codex exec --full-auto 调用保留为已弃用的兼容路径，并显示警告。
使用 --ask-for-approval untrusted时， Codex 只会自动运行已知安全的读取操作。可能改变状态或触发外部执行路径的命令（例如破坏性的 Git 操作或 Git output/config-override 标志）需要审批。
config.toml 中的配置
Section titled “config.toml 中的配置”# Always ask for approval modeapproval_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 选择它们：
approval_policy = "on-request"sandbox_mode = "workspace-write"approval_policy = "never"sandbox_mode = "read-only"在本地测试沙箱
Section titled “在本地测试沙箱”要了解命令在 Codex 沙箱中运行时的情况，请使用以下 Codex CLI 命令：
# macOScodex sandbox macos [--permissions-profile <name>] [--log-denials] [COMMAND]...# Linuxcodex sandbox linux [--permissions-profile <name>] [COMMAND]...# Windowscodex sandbox windows [--permissions-profile <name>] [COMMAND]...sandbox 命令也可通过 codex debug 使用，并且平台辅助工具提供了别名（例如 codex sandbox seatbelt 和 codex sandbox landlock）。
Codex 会根据你的 OS以不同方式强制执行沙箱：
- macOS 使用 Seatbelt 策略，并通过
sandbox-exec配合某个配置文件（-p）来运行命令，该配置文件对应你选择的--sandbox模式。当受限读取访问启用平台默认值时， 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 extension，它可以直接支持 WSL2。请在 VS Code 设置中添加以下配置，以便在 WSL2 可用时始终让代理在其中运行：
{ "chatgpt.runCodexInWindowsSubsystemForLinux": true}这确保 IDE 扩展在命令、审批和文件系统访问方面继承 Linux 沙箱语义，即使主机 OS 是 Windows。请在 WSL 指南中了解更多。
在 Windows 原生运行时，请在 config.toml 中配置原生沙箱模式：
[windows]sandbox = "unelevated" # or "elevated"# sandbox_private_desktop = true # default; set false only for compatibility详情请参阅 Windows 设置指南。
当你在 Docker 等容器化环境中运行 Linux 时，如果主机或容器配置阻止了 bwrap所需的命名空间、setuid seccomp 或 Codex 操作，沙箱可能无法工作。
在这种情况下，请配置你的 Docker 容器以提供所需的隔离，然后在容器内使用 codex 运行 --sandbox danger-full-access （或使用 --dangerously-bypass-approvals-and-sandbox 标志）。
在 Dev Containers 中运行 Codex
Section titled “在 Dev Containers 中运行 Codex”如果你的主机无法直接运行 Linux 沙箱，或者你的组织已经统一采用容器化开发，请使用 Dev Containers 运行 Codex，并让 Docker 提供外层隔离边界。此方式适用于 Visual Studio Code Dev Containers 和兼容工具。
请将 Codex 安全 devcontainer 示例作为参考实现。该示例会安装 Codex、常用开发工具、bubblewrap 以及基于防火墙的出站控制。
Devcontainer 提供了大量保护，但不能阻止所有
攻击。如果你在容器内使用 Codex 或 --sandbox danger-full-access 运行
--dangerously-bypass-approvals-and-sandbox ，恶意的
项目可能会窃取 devcontainer 内可用的任何内容，包括
Codex 凭据。仅对受信任的仓库使用此模式，并像在任何其他提权环境中一样
监控 Codex 活动。
参考实现包含：
- 一个 Ubuntu 24.04 基础镜像，其中安装了 Codex 和常用开发工具；
- 基于允许列表的出站访问防火墙配置；
- VS 用于在容器中重新打开工作区的 Code 设置和扩展建议；
- 用于命令历史记录和 Codex 配置的持久挂载；
bubblewrap，因此当容器授予所需能力时， Codex 仍可使用其 Linux 沙箱。
尝试使用：
- 安装 Visual Studio Code 和 Dev Containers 扩展。
- 将 Codex 示例中的
.devcontainer设置复制到你的代码仓库，或直接从 Codex 代码仓库开始。 - 在 VS Code 中运行 Dev Containers: Open Folder in Container…，然后选择
.devcontainer/devcontainer.secure.json。 - 容器启动后，打开终端并运行
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 rebinding 和 DNS 刷新保护，例如支持 TTL 的刷新机制或 DNS 感知型防火墙。
在容器内，选择以下模式之一：
- 如果 Dev Container 配置文件授予了 Codex创建内部沙箱所需的能力，请保持
bwrap的 Linux 沙箱启用。 - 如果容器是你预期的安全边界，请在容器内使用 Codex 运行
--sandbox danger-full-access，这样 Codex 就不会尝试创建第二层沙箱。
Codex 最适合配合版本控制工作流使用：
- 在功能分支上工作，并在委托前保持
git status干净。这能让 Codex 补丁更容易隔离和回滚。 - 优先使用基于补丁的工作流（例如
git diff/git apply），而不是直接编辑已跟踪文件。频繁提交，这样你可以按小增量回滚。 - 像对待任何其他 Codex 建议一样对待 PR：运行有针对性的验证、审查差异，并在提交消息中记录决策以便审计。
Codex 支持通过 OpenTelemetry (OTel) 选择性启用监控，帮助团队审计使用情况、调查问题并满足合规要求，同时不削弱本地安全默认设置。遥测默认关闭；请在配置中明确启用。
- Codex 默认关闭 OTel 导出，以保持本地运行自包含。
- 启用后， Codex 会发出结构化日志事件，涵盖聊天、 API 请求、 SSE/WebSocket 流活动、用户提示（默认已脱敏）、工具审批决策和工具结果。
- Codex 会用
service.name（发起者）、 CLI 版本和环境标签标记导出的事件，以区分 dev/staging/prod 流量。
启用 OTel（选择性启用）
Section titled “启用 OTel（选择性启用）”向你的 [otel] 配置添加一个 Codex 块（通常是 ~/.codex/config.toml），选择导出器以及是否记录提示文本。
[otel]environment = "staging" # dev | staging | prodexporter = "none" # none | otlp-http | otlp-grpclog_user_prompt = false # redact prompt text unless policy allowsexporter = "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（模型、推理设置、 sandbox/approval 策略）codex.api_request（尝试、 status/success、时长和错误详情）codex.sse_event（流事件类型、 success/failure、时长，以及response.completed上的 token 计数）codex.websocket_request和codex.websocket_event（请求时长以及每条消息的 kind/success/error）codex.user_prompt（长度；除非明确启用，否则内容会被脱敏）codex.tool_decision（approved/denied，来源：配置与用户）codex.tool_result（时长、成功状态、输出片段）
关联的 OTel 指标（计数器与持续时间直方图成对出现）包括 codex.api_request、codex.sse_event、codex.websocket.request、codex.websocket.event 和 codex.tool.call（以及对应的 .duration_ms 指标）。
有关完整事件目录和配置参考，请参阅 Codex 上的配置文档 GitHub。
安全与隐私指南
Section titled “安全与隐私指南”- 保持
log_user_prompt = false，除非策略明确允许存储提示内容。提示可能包含源代码和敏感数据。 - 仅将遥测路由到你控制的收集器；应用与你的合规要求一致的保留期限和访问控制。
- 将工具参数和输出视为敏感内容。尽可能优先在收集器或 SIEM 处进行脱敏。
- 如果你不希望
history.persistence/history.max_bytes将会话转录保存到 Codex 下，请审查本地数据保留设置（例如CODEX_HOME）。请参阅 高级配置 和 配置参考。 - 如果你在关闭网络访问的情况下运行 CLI ， OTel 导出无法连接到你的收集器。要导出，请在
workspace-write模式下允许访问 OTel 端点，或从 Codex cloud 导出，并将收集器域名加入你的批准列表。 - 定期审查事件，检查 approval/sandbox 变更和意外的工具执行。
OTel 是可选功能，旨在补充而非替代上述沙箱和审批保护措施。
企业管理员可以在 Codex 托管配置 中为其工作区配置安全设置。请参阅该页面了解设置和策略详情。