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

Agent 审批与安全

如何通过沙箱、审批和网络控制来安全地运行 Codex

Codex 可帮助保护您的代码和数据，并降低被误用的风险。

本页介绍如何安全地运行 Codex，包括沙箱、审批和网络访问。如果您要查找的是 Codex Security（用于扫描已连接 GitHub 仓库的产品），请参阅 Codex Security。

默认情况下，agent 在关闭网络访问的状态下运行。在本地，Codex 使用由操作系统强制实施的沙箱来限制它可接触的内容（通常仅限于当前工作区），并配合审批策略来控制它何时必须停止并在执行前征求您的同意。

如需了解 Codex app、IDE 扩展和 CLI 中沙箱工作方式的高层说明，请参阅 sandboxing。 如需更广泛的企业安全概览，请参阅 Codex 安全白皮书。

沙箱与审批

Codex 的安全控制来自协同工作的两层：

• 沙箱模式：当 Codex 执行模型生成的命令时，它在技术上能做什么（例如，它可以写入哪里，以及它是否可以访问网络）。
• 审批策略：Codex 在执行某项操作前何时必须征求您的同意（例如，离开沙箱、使用网络，或运行不在受信任集合内的命令）。

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

• Codex cloud：在由 OpenAI 管理的隔离容器中运行，防止访问您的主机系统或无关数据。使用两阶段运行时模型：setup 在 agent 阶段之前运行，并可访问网络以安装指定依赖；然后 agent 阶段默认离线运行，除非您为该环境启用互联网访问。为 cloud 环境配置的 secrets 仅在 setup 期间可用，并会在 agent 阶段开始前被移除。
• Codex CLI / IDE extension：由操作系统级机制实施沙箱策略。默认包括无网络访问，以及写权限仅限于活动工作区。您可以根据自身的风险承受能力配置沙箱、审批策略和网络设置。

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

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

对于带有副作用声明的 app（connector）工具调用，即使该操作不是 shell 命令或文件更改，Codex 也可以请求审批。具有破坏性的 app/MCP 工具调用在工具声明了 destructive annotation 时始终需要审批，即使它还声明了其他提示（例如 read-only 提示）也是如此。

网络访问

对于 Codex cloud，请参阅 agent internet access 以启用完整互联网访问或域名允许列表。

对于 Codex app、CLI 或 IDE Extension，默认的 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'

该功能会改变已启用网络访问的实施方式；它本身不会授予网络访问权限。请结合 workspace-write 配置中的 sandbox_workspace_write.network_access 来决定命令是否具有任何网络访问能力：

• 网络关闭 + network_proxy 开启：网络仍保持关闭，该功能不起作用。
• 网络开启 + network_proxy 关闭：网络仍保持开启，并具有不受限制的直接出站访问。
• 网络开启 + network_proxy 开启：网络仍保持开启，且出站流量会受所配置网络策略的限制。

由管理员管理的 experimental_network requirement 与用户功能开关是分开的。它们可以在不使用 features.network_proxy 的情况下配置并启动沙箱网络，但当当前沙箱保持网络关闭时，它们不会开启网络访问。有关管理员侧 requirements.toml 的格式，请参阅 Managed configuration。

网络策略

域名规则采用“允许列表优先”：

• 精确主机名仅匹配其自身。
• *.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 socket 允许列表。

仅应在严格受控的环境中使用它们。启用 Unix socket 代理时，即使请求了非回环绑定，监听端点也仍仅限于回环，因此沙箱网络不会成为通向本地守护进程的远程桥梁。

network_proxy 默认关闭。启用后：

设置	默认值	行为
enabled	false	仅当命令网络访问已开启时才启动沙箱网络。
domains	unset	使用允许列表行为，因此在您添加 allow 规则之前，不允许任何外部目标。支持精确主机、带范围的通配符以及全局 * 允许规则；deny 始终优先。
unix_sockets	unset	在您添加显式 allow 规则之前，不允许任何 Unix socket 目标。
allow_local_binding	false	阻止本地和私有网络目标，除非您添加精确的本地 IP 字面量或 localhost 允许规则，或显式选择更广泛的本地/私有访问。
enable_socks5	true	当策略允许时，提供 SOCKS5 支持。
enable_socks5_udp	true	当 SOCKS5 可用时，允许通过 SOCKS5 使用 UDP。
allow_upstream_proxy	true	允许沙箱网络遵循环境中的上游代理。
dangerously_allow_non_loopback_proxy	false	将监听端点保持在回环接口上，除非您有意将其暴露到 localhost 之外。
dangerously_allow_all_unix_sockets	false	保持 Unix socket 访问基于允许列表，除非您有意绕过该保护。

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

web_search = "cached"  # 默认
# web_search = "disabled"
# web_search = "live"  # 等同于 --search

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

默认值与建议

• 启动时，Codex 会检测文件夹是否受版本控制，并建议：
  • 受版本控制的文件夹：Auto（workspace write + 按请求审批）
  • 不受版本控制的文件夹：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

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

在默认的 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-rule 提示、MCP 提示、request_permissions 提示以及 skill-script 审批。

自动审批审查

默认情况下，审批请求会路由给你：

approvals_reviewer = "user"

自动审批审查适用于审批是交互式的情况，例如 approval_policy = "on-request" 或细粒度审批策略。设置 approvals_reviewer = "auto_review"，可在 Codex 执行请求前，先将符合条件的审批请求 路由给审查代理：

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

有关完整的审查器生命周期、触发条件、配置优先级 以及失败行为，请参阅 Auto-review。

审查器仅评估那些本来就需要审批的操作，例如沙箱 提权、被阻止的网络请求、request_permissions 提示，或 具有副作用的应用和 MCP 工具调用。停留在沙箱内的操作 会继续执行，而不会增加额外的审查步骤。

审查器策略会检查数据外泄、凭证探测、持久性 安全弱化以及破坏性操作。低风险和中风险操作 在策略允许时可以继续执行。策略会拒绝关键风险操作。 高风险操作需要足够的用户授权，且没有匹配的拒绝规则。 提示构建、审查会话和解析失败都会以失败关闭（fail closed）的方式处理。 超时会单独显示，但该操作仍不会执行。

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

在 Codex 应用中，这些审查会显示为自动审查项，状态 可能包括 Reviewing、Approved、Denied、Aborted 或 Timed out。 它们还可能包含所审查请求的风险级别和用户授权评估。

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

常见沙箱与审批组合

目的	标志 / 配置	效果
Auto（预设）	无需标志 或 --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 可以读取和编辑文件，但在运行不可信命令前会请求审批。
Auto-review 模式	--sandbox workspace-write --ask-for-approval on-request -c approvals_reviewer=auto_review 或 approvals_reviewer = "auto_review"	与标准按请求模式具有相同的沙箱边界，但符合条件的审批请求会由 Auto-review 审查，而不是直接呈现给用户。
危险的完全访问	--dangerously-bypass-approvals-and-sandbox（别名：--yolo）	无沙箱；无审批 （不推荐）

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

使用 --ask-for-approval untrusted 时，Codex 只会自动运行已知安全的读取操作。可能改变状态或触发外部执行路径的命令（例如，破坏性的 Git 操作，或 Git 输出/config-override 标志）需要审批。

config.toml 中的配置

有关更广泛的配置工作流，请参阅 Config basics、Advanced Config 和 Configuration Reference。

# 始终询问审批模式
approval_policy = "untrusted"
sandbox_mode    = "read-only"
allow_login_shell = false # 可选强化：禁止基于 shell 的工具使用 login shell

# 可选：在 workspace-write 模式下允许网络
[sandbox_workspace_write]
network_access = true

# 可选：细粒度审批策略
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

你也可以将预设保存为 profile，然后用 codex --profile 选择它们：

[profiles.full_auto]
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

[profiles.readonly_quiet]
approval_policy = "never"
sandbox_mode    = "read-only"

在本地测试 sandbox

要查看命令在 Codex sandbox 下运行时会发生什么，请使用这些 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）。

操作系统级 sandbox

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

• macOS 使用 Seatbelt 策略，并通过带有配置文件（-p）的 sandbox-exec 运行命令，该配置文件对应你所选择的 --sandbox 模式。当受限读取访问启用平台默认值时，Codex 会附加一个经过筛选的 macOS 平台策略（而不是宽泛地允许 /System），以保持常见工具的兼容性。
• Linux 默认使用 bwrap 加 seccomp。
• Windows 在 Windows Subsystem for Linux 2 (WSL2) 中运行时使用 Linux sandbox 实现。WSL1 通过 Codex 0.114 受支持；从 0.115 开始，Linux sandbox 切换为 bwrap，因此不再支持 WSL1。原生在 Windows 上运行时，Codex 使用 Windows sandbox 实现。

如果你在 Windows 上使用 Codex IDE 扩展，它可直接支持 WSL2。请在 VS Code 设置中添加以下内容，以便在可用时始终将 agent 保持在 WSL2 内部：

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

这样可以确保即使主机操作系统是 Windows，IDE 扩展在命令、审批和文件系统访问方面仍继承 Linux sandbox 语义。更多信息请参阅 Windows 设置指南。

当原生在 Windows 上运行时，请在 config.toml 中配置原生 sandbox 模式：

[windows]
sandbox = "unelevated" # 或 "elevated"
# sandbox_private_desktop = true  # 默认值；仅在兼容性需要时设为 false

详情请参阅 Windows 设置指南。

当你在 Docker 等容器化环境中运行 Linux 时，如果宿主机或容器配置阻止了 Codex 所需的 namespace、setuid bwrap 或 seccomp 操作，sandbox 可能无法工作。

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

在 Dev Containers 中运行 Codex

如果你的主机无法直接运行 Linux sandbox，或者你的组织已经标准化使用容器化开发，请结合 Dev Containers 运行 Codex，并让 Docker 提供外层隔离边界。这适用于 Visual Studio Code Dev Containers 及兼容工具。

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

Devcontainers 提供了相当强的保护，但它们并不能阻止所有 攻击。如果你在容器内使用 --sandbox danger-full-access 或 --dangerously-bypass-approvals-and-sandbox 运行 Codex，恶意 项目可能会窃取 devcontainer 内可用的任何内容，包括 Codex 凭据。仅在受信任的仓库中使用此模式，并且 像在任何其他高权限环境中一样监控 Codex 活动。

参考实现包括：

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

试用方法：

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 rebinding 和 DNS 刷新保护，例如基于 TTL 的刷新或具备 DNS 感知能力的防火墙。

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

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

版本控制

Codex 最适合与版本控制工作流配合使用：

• 在功能分支上工作，并在委派前保持 git status 干净。这会让 Codex 生成的补丁更容易隔离和回退。
• 优先采用基于补丁的工作流（例如 git diff/git apply），而不是直接编辑已跟踪文件。频繁提交，以便你可以按较小增量回滚。
• 像对待任何其他 PR 一样对待 Codex 建议：运行有针对性的验证、审查 diff，并在提交消息中记录决策以供审计。

监控与遥测

Codex 通过 OpenTelemetry (OTel) 支持选择加入的监控，帮助团队在不削弱本地安全默认设置的情况下审计使用情况、调查问题并满足合规要求。默认关闭遥测；请在配置中显式启用。

概览

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

启用 OTel（选择加入）

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

[otel]
environment = "staging"   # dev | staging | prod
exporter = "none"          # none | otlp-http | otlp-grpc
log_user_prompt = false     # 除非策略允许，否则对提示词文本进行脱敏

• exporter = "none" 会保持 instrumentation 处于启用状态，但不会将数据发送到任何地方。
• 若要将事件发送到你自己的 collector，请选择以下之一：

[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/审批策略）
• 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` instrument）。

有关完整事件目录和配置参考，请参阅 [GitHub 上的 Codex 配置文档](https://github.com/openai/codex/blob/main/docs/config.md#otel)。

### 安全与隐私指南

- 除非策略明确允许存储提示内容，否则请保持 `log_user_prompt = false`。提示可能包含源代码和敏感数据。
- 仅将遥测路由到你控制的 collector；应用与合规要求一致的保留限制和访问控制。
- 将工具参数和输出视为敏感数据。尽可能优先在 collector 或 SIEM 处进行脱敏。
- 如果你不希望 Codex 在 `CODEX_HOME` 下保存会话记录，请检查本地数据保留设置（例如 `history.persistence` / `history.max_bytes`）。请参阅 [Advanced Config](/codex/configuration/config-file/advanced-config#history-persistence) 和 [Configuration Reference](/codex/configuration/config-file/config-reference)。
- 如果你在关闭网络访问的情况下运行 CLI，OTel 导出将无法到达你的 collector。要进行导出，请在 `workspace-write` 模式下为 OTel 端点允许网络访问，或者从 Codex cloud 导出，并将 collector 域名加入你的批准列表。
- 定期审查事件，以发现审批/沙箱变更和意外的工具执行。

OTel 是可选的，旨在作为上述沙箱和审批保护的补充，而不是替代。

## 托管配置

企业管理员可以在[托管配置](/codex/administration/enterprise/managed-configuration)中为其工作区配置 Codex 安全设置。有关设置和策略详情，请参阅该页面。