代理审批与安全

Codex 有助于保护你的 code 和 data，并降低误用风险。

本页说明如何安全地运行 Codex，包括 sandboxing、approvals 和 network access。如果你要找用于扫描已连接 GitHub repositories 的 Codex Security 产品，请参阅 Codex Security 。

默认情况下，agent 会在 network access 关闭的状态下运行。在本地，Codex 使用 OS-enforced sandbox 限制它能接触的内容（通常限制在当前 workspace），并配合 approval policy 控制它在行动前何时必须停下来询问你。

关于 sandboxing 在 Codex app、IDE extension 和 CLI 中如何工作的 high-level explanation，请参阅 sandboxing 。更宽泛的 enterprise security overview 请参阅 Codex security white paper 。

Codex security controls 来自两个协同工作的 layers：

Codex 会根据运行位置使用不同的 sandbox modes：

在 Auto preset 中，例如 --sandbox workspace-write --ask-for-approval on-request，Codex 可以自动读取 files、进行 edits，并在 working directory 中运行 commands。

如果要编辑 workspace 之外的 files，或运行需要 network access 的 commands，Codex 会请求 approval。如果你只想 chat 或 plan 而不做改动，可以用 /permissions command 切换到 read-only mode。

Codex 也可以针对声明有 side effects 的 app connector tool calls 请求 approval，即使该 action 不是 shell command 或 file change。当 tool 声明 destructive annotation 时，destructive app/MCP tool calls 始终需要 approval，即使它同时声明了其他 hints（例如 read-only hints）。

对于 Codex cloud，请参阅 agent internet access ，以启用 full internet access 或 domain allow list。

对于 Codex app、CLI 或 IDE Extension，默认 workspace-write sandbox mode 会保持 network access 关闭，除非你在 configuration 中启用它：

[sandbox_workspace_write]
network_access = true

Network access 由 destination rules 控制，这些 rules 会应用于 commands 派生出的 scripts、programs 和 subprocesses。当 command network access 已启用时，打开 network_proxy feature 可以把该 traffic 限制到你配置的 network policy。

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

对于一次性的 CLI session，如果只需要 toggle，请使用 boolean shorthand；如果还要设置 policy options，请使用 table form：

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'

这个 feature 会改变已启用 network access 的 enforcement 方式；它本身不会授予 network access。请使用 workspace-write config 中的 sandbox_workspace_write.network_access 来决定 commands 是否有 network access：

Admin-managed experimental_network requirements 与 user feature toggle 分开。它们可以在没有 features.network_proxy 的情况下配置并启动 sandboxed networking，但当 active sandbox 保持 network 关闭时，它们不会打开 network access。administrator-side requirements.toml 的形状请参阅 Managed configuration 。

Domain rules 采用 allowlist-first：

默认情况下，allow_local_binding = false 会 block loopback、link-local 和 private destinations：

在允许 hostname 之前，Codex 会执行 best-effort DNS 和 IP classification check：

如果 hostile DNS 属于你的 threat model，也应在更低层 enforce egress controls。

有两个 settings 会有意扩大 trust boundary：

只应在 tightly controlled environments 中使用它们。当 Unix socket proxying 启用时，即使请求了 non-loopback binding，listeners 也会保持 loopback-only，因此 sandboxed networking 不会变成通向 local daemons 的 remote bridge。

network_proxy 默认关闭。启用后：

你也可以在不向 spawned commands 授予 full network access 的情况下控制 web search tool 。Codex 默认使用 web search cache 访问 results。该 cache 是 OpenAI-maintained web results index，因此 cached mode 返回预先索引的 results，而不是抓取 live pages。这会降低来自任意 live content 的 prompt injection 暴露，但仍应把 web results 视为 untrusted。如果你使用 --yolo 或其他 full access sandbox setting ，web search 默认使用 live results。使用 --search 或设置 web_search = "live" 可允许 live browsing；设置为 "disabled" 可关闭该 tool：

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

在 Codex 中启用 network access 或 web search 时请谨慎。Prompt injection 可能导致 agent fetch 并遵循 untrusted instructions。

在默认 workspace-write sandbox policy 中，writable roots 仍然包含 protected paths：

你可以用 --ask-for-approval never 或 shorthand -a never 关闭 approval prompts。

这个 option 适用于所有 --sandbox modes，因此你仍然可以控制 Codex 的 autonomy level。Codex 会在你设置的 constraints 内尽力执行。

如果你需要 Codex 在没有 approval prompts 的情况下读取 files、进行 edits，并以 network access 运行 commands，请使用 --sandbox danger-full-access（或 --dangerously-bypass-approvals-and-sandbox flag）。使用前请谨慎。

作为折中方案，approval_policy = { granular = { ... } } 可让特定 approval prompt categories 保持 interactive，同时自动 reject 其他类别。granular policy 覆盖 sandbox approvals、execpolicy-rule prompts、MCP prompts、request_permissions prompts 和 skill-script approvals。

默认情况下，approval requests 会 routed to you：

approvals_reviewer = "user"

当 approvals 是 interactive 时，例如 approval_policy = "on-request" 或 granular approval policy，automatic approval reviews 会生效。设置 approvals_reviewer = "auto_review"，可以在 Codex 运行 request 前，把 eligible approval requests 交给 reviewer agent：

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

完整 reviewer lifecycle、trigger conditions、configuration precedence 和 failure behavior 请参阅 Auto-review 。

Reviewer 只评估已经需要 approval 的 actions，例如 sandbox escalations、blocked network requests、request_permissions prompts，或有 side effects 的 app 和 MCP tool calls。留在 sandbox 内的 actions 会继续执行，不会额外触发 review step。

Reviewer policy 会检查 data exfiltration、credential probing、persistent security weakening 和 destructive actions。Policy 允许时，low-risk 和 medium-risk actions 可以继续。Policy 会 deny critical-risk actions。High-risk actions 需要足够的 user authorization 且没有匹配的 deny rule。Prompt-build、review-session 和 parse failures 会 fail closed。Timeouts 会单独 surfaced，但 action 仍不会运行。

Default reviewer policy 位于 open-source Codex repository 中。Enterprises 可以用 managed requirements 中的 guardian_policy_config 替换其 tenant-specific section。也支持 local [auto_review].policy text，但 managed requirements 优先级更高。Setup details 请参阅 Managed configuration 。

在 Codex app 中，这些 reviews 会显示为 automatic review items，状态包括 Reviewing、Approved、Denied、Aborted 或 Timed out。它们还可以包含 risk level 和针对被 review request 的 user-authorization assessment。

Automatic review 会使用额外 model calls，因此可能增加 Codex usage。Admins 可以用 allowed_approvals_reviewers 约束它。

对于 non-interactive runs，请使用 codex exec --sandbox workspace-write；Codex 会把较旧的 codex exec --full-auto invocations 保留为 deprecated compatibility path，并打印 warning。

使用 --ask-for-approval untrusted 时，Codex 只会自动运行 known-safe read operations。可能 mutate state 或触发 external execution paths 的 commands（例如 destructive Git operations 或 Git output/config-override flags）需要 approval。

更完整的 configuration workflow 请参阅 Config basics 、 Advanced Config 和 Configuration Reference 。

# 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
# } }

你也可以把 presets 保存为 profile files ，然后用 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"

要查看 command 在 Codex sandbox 下运行时会发生什么，请使用这些 Codex CLI commands：

# 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 command 也可作为 codex debug 使用，platform helpers 有 aliases，例如 codex sandbox seatbelt 和 codex sandbox landlock。

Codex 会根据你的 OS 以不同方式 enforce sandbox：

如果你在 Windows 上使用 Codex IDE extension，它直接支持 WSL2。请在 VS Code settings 中设置以下内容，让 agent 在 WSL2 可用时始终留在 WSL2 内：

{ "chatgpt.runCodexInWindowsSubsystemForLinux": true }

这会确保 IDE extension 继承 Linux sandbox semantics，用于 commands、approvals 和 filesystem access，即使 host OS 是 Windows。请在 Windows setup guide 中了解更多。

Native Windows 运行时，请在 config.toml 中配置 native sandbox mode：

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

详情请参阅 Windows setup guide 。

当你在 Docker 等 containerized environment 中运行 Linux 时，如果 host 或 container configuration 阻止 Codex 所需的 namespace、setuid bwrap 或 seccomp operations，sandbox 可能无法工作。

这种情况下，请配置 Docker container 来提供你需要的 isolation，然后在 container 内使用 --sandbox danger-full-access（或 --dangerously-bypass-approvals-and-sandbox flag）运行 codex。

如果你的 host 无法直接运行 Linux sandbox，或 organization 已标准化 containerized development，请使用 Dev Containers 运行 Codex，并让 Docker 提供外层 isolation boundary。这适用于 Visual Studio Code Dev Containers 和兼容 tools。

请使用 Codex secure devcontainer example 作为 reference implementation。该示例会安装 Codex、common development tools、bubblewrap 和 firewall-based outbound controls。

Devcontainers 提供 substantial protection，但不能阻止所有 attack。如果你在 container 内使用 --sandbox danger-full-access 或 --dangerously-bypass-approvals-and-sandbox 运行 Codex，malicious project 可以 exfiltrate devcontainer 内可用的一切，包括 Codex credentials。只应对 trusted repositories 使用该 pattern，并像监控其他 elevated environment 一样监控 Codex activity。

Reference implementation 包括：

要试用它：

你也可以从 CLI 启动 container：

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

该 example 有三个主要部分：

Reference firewall 有意只是 starting point。如果你依赖 domain allowlisting 做 isolation，请实现适合你环境的 DNS rebinding 和 DNS refresh protections，例如 TTL-aware refreshes 或 DNS-aware firewall。

在 container 内，选择以下模式之一：

Codex 与 version control workflow 配合效果最好：

Codex 支持通过 OpenTelemetry (OTel) 进行 opt-in monitoring，帮助 teams audit usage、investigate issues，并在不削弱 local security defaults 的情况下满足 compliance requirements。Telemetry 默认关闭；请在 configuration 中显式启用。

在 Codex configuration（通常是 ~/.codex/config.toml）中添加 [otel] block，选择 exporter，并决定是否记录 prompt text。

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

[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 会 batch events 并在 shutdown 时 flush。Codex 只 export 由其 OTel module 产生的 telemetry。

Representative event types 包括：

Associated OTel metrics（counter plus duration histogram pairs）包括 codex.api_request、codex.sse_event、codex.websocket.request、codex.websocket.event 和 codex.tool.call（带对应 .duration_ms instruments）。

完整 event catalog 和 configuration reference 请参阅 GitHub 上的 Codex configuration documentation。

OTel 是 optional 的，设计目标是 complement 而不是替代上文所述 sandbox 和 approval protections。

Enterprise admins 可以在 Managed configuration 中为 workspace 配置 Codex security settings。Setup 和 policy details 请参阅该页面。