Codex 安全边界实战：权限、沙箱、密钥泄露防护指南

你的项目根目录有一个 .env 文件，里面是数据库密码和第三方 API key。你打开了 Codex，准备让它帮忙重构测试代码。下拉框里有 read-only、workspace-write、danger-full-access 三个选项。选哪个？

选 workspace-write 之后，Codex 提示要安装 npm install。你点了批准。你有没有想过，package.json 里那个没注意过的 postinstall 脚本，会不会在这一步读取你的环境变量，或者发一个请求到你不知道的服务？

你把 Codex 放到 GitHub Actions 里自动化 PR review。workflow 文件里写 OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}。你觉得 secrets 是安全的。但你有没有想过，同一个 job 里跑的测试脚本、第三方 action、依赖安装 hooks 都可能读到这个 key？

三个边界直接回答这些问题：指令不是权限、审批不是隔离、sandbox 不是审计。接下来是本地、Cloud、CI 三个场景的最小权限清单。

权限不是靠口头约束——理解 sandbox、approval、permission profile 三层边界

很多人以为在 AGENTS.md 里写一句”不要读取 .env 文件”就能阻止 Codex 访问敏感信息。这不是权限控制，而是项目规则指导。真正的安全边界来自三层：sandbox 约束 spawned commands 的范围，approval policy 决定什么时候停下来问，permission profile 是强制访问控制。

Codex 的安全不是一层就够了。sandbox 决定了 git、包管理器、test runner 这些 spawned commands 能访问什么；approval policy 决定 Codex 在执行关键操作前是否需要你批准；permission profile 才是真正能写 "**/*.env" = "deny" 的配置层。三层叠加，才是实际权限。

sandbox 模式对照：read-only、workspace-write、danger-full-access

sandbox 模式	定义	适用场景	风险
read-only	只允许读文件，不允许写或执行命令	代码审阅、架构梳理、文档生成、CI 只读检查	不能保护 runner 上所有 secrets；仍在 runner 上运行
workspace-write	允许写 active workspace，网络默认关闭	日常本地开发、改代码、跑测试	默认可读 workspace 下所有文件，包括 .env；需配 deny glob
danger-full-access	移除文件系统和网络边界	isolated CI runner/container、完全受控的测试环境	可访问 ~/.ssh、/tmp、环境变量、本地服务；不作为日常默认

sandbox 约束的是 spawned commands，不只是 Codex 内置文件操作。git、包管理器、test runner 都继承 sandbox 边界。平台前提会影响可靠性：Linux/WSL2 依赖 bubblewrap 或 user namespace，macOS 依赖系统 sandbox，Windows 平台前提影响 sandbox 可用性。

approval policy 决定何时停下来问：

approval policy	定义	常见组合	实际权限
on-request	执行操作前暂停并请求批准	workspace-write + on-request 本地自动化	低风险；需人工确认写文件、执行命令、网络请求
never	不弹交互审批，直接执行	read-only + never CI 只读检查；danger-full-access + never 受控环境	高风险；workspace-write + never 无 permission profile 时风险较高

低风险组合：read-only + never（CI 只读）、workspace-write + on-request（本地开发）。高风险组合：danger-full-access + never（仅受控环境）。

permission profile 配置：filesystem deny、network rules

permission profile 是强制访问控制，不是口头约束。filesystem 权限支持 read/write/deny，更具体规则覆盖更宽规则，deny 优先。

.env deny glob 配置示例：

{
  "filesystem": {
    "rules": {
      "**/*.env": "deny",
      "**/.env.local": "deny",
      "**/secrets/**": "deny",
      "workspace/**": "write"
    }
  }
}

这个配置让 .env 文件在 workspace-write 下仍不可读，即使 workspace 默认可写。deny 优先，具体规则覆盖宽规则。

network profile 可配置 enabled = true 与 domain allow/deny，deny 优先。local/private network 默认有防护；允许 localhost 或 Docker socket 属于显式例外。Docker socket 是本地 escape hatch，可访问本地服务、容器、网络，应谨慎开启。

network proxy 约束已开启的命令网络访问，不单独授予网络。全局 * allow 是宽网络访问，应谨慎。

本地场景最小权限清单：从只读审阅到全访问的判断标准

本地开发不是权限越大越省事。审批能拦住一部分操作，但 sandbox 和 permission profile 才是真正隔离。从最窄权限开始，按任务逐步扩大。

权限选择决策表：什么时候用 read-only、什么时候用 workspace-write

场景	sandbox 模式	approval policy	permission profile	风险等级
代码审阅/架构梳理	read-only	never	无需配置	低
日常开发/改代码	workspace-write	on-request	配 .env deny	中低
跑测试/装依赖	workspace-write	on-request	配 .env deny、审计脚本	中
CI 只读检查	read-only	never	无需配置	低
CI 需写文件	workspace-write	never	配 deny、用 isolated runner	中高
需要 full access	danger-full-access	never	仅受控环境	高

.env 和密钥文件保护配置步骤：

1. 确定你使用的 permission profile 配置文件路径（参考 Codex Permissions 文档）
2. 在 filesystem 权限配置中添加 "**/*.env" = "deny"
3. 确认更具体规则覆盖更宽规则，deny 优先
4. 测试：用 workspace-write 模式尝试读取 .env，应被 deny
5. 扩展：可添加 "**/.env.local" = "deny"、"**/secrets/**" = "deny" 等

不要靠口头约束。AGENTS.md 是指导，不是强制访问控制。Codex 可能遵循指导，也可能因其他原因读取。只有 permission profile 的 deny 才是强制。

依赖安装风险：npm postinstall、pip hooks、Docker socket

依赖安装不是简单下载文件。npm/pnpm 的 postinstall、prepare，pip install 的 hooks 在安装时自动执行。这些脚本可能读取环境变量、发网络请求、修改系统文件。

风险清单：

• 未知 postinstall 可能读环境变量：即使你配置了 .env deny，postinstall 在 spawned commands 环境里执行，仍可能接触环境变量
• 可能发网络请求：下载额外二进制、上报统计、连接私有仓库
• 可能修改系统文件：写入全局配置、修改 PATH

审计建议：

1. 先审脚本和来源：检查 package.json 的 scripts 字段、pip 包的 setup.py
2. 使用可信源：锁定依赖版本，避免自动升级到未知版本
3. 在受控环境批准：本地开发用 workspace-write + on-request，批准前看清楚 Codex 要装什么

Docker socket 是本地 escape hatch。允许 Docker socket 属于显式例外，可访问本地服务、容器、网络。明确需要才配置，不要默认开启。

Cloud 场景边界：setup vs agent phase、secrets 生命周期

Cloud task 不是在本地跑，而是在 OpenAI 托管的隔离容器里。sandbox 能约束 spawned commands，但真正的密钥安全来自 Cloud secrets 的生命周期设计：setup 阶段可用，agent 阶段前移除。sandbox 不是审计，真正的安全来自分层。

Cloud container 生命周期：

1. 创建 container
2. checkout repo
3. 运行 setup script
4. 应用网络设置
5. agent 执行命令循环
6. 输出 answer/diff

setup vs agent phase 边界：secrets 只在 setup 可用

阶段	网络访问	secrets 可用	environment variables	依赖安装
setup scripts	可联网	可用	全程存在	可安装依赖
agent phase	默认离线	已移除	全程存在	默认离线

setup 阶段可联网、可安装依赖、secrets 可用。agent 阶段默认离线、secrets 已移除、只有 environment variables。

setup scripts 运行在单独 Bash session，export 不会自动带进 agent phase。如果你在 setup 里 export MY_KEY=xxx，agent phase 不会继承这个变量。只有 Cloud secrets 和 environment variables 会在两个阶段间传递。

secrets vs environment variables：关键差异

类型	加密	可用阶段	用途	生命周期
environment variables	无额外加密	setup + agent 全程	非敏感配置、路径、开关	container 生命周期内始终存在
secrets	额外加密	只在 setup scripts 可用	私有仓库访问、依赖安装认证	agent phase 前移除

secrets 只在 setup scripts 可用，适合安装依赖、连接私有仓库。agent phase 不应有生产密钥。environment variables 全程存在，适合非敏感配置。

依赖安装边界：

• setup 阶段可联网安装依赖
• agent 阶段默认离线
• setup scripts 可访问 secrets，未知脚本可能泄露
• 建议：先审脚本和来源，使用可信源，避免在 setup 里运行未知脚本

container cache 最长 12 小时。setup/maintenance/env/secrets 改动会触发 cache invalidation。

CI 场景与 GitHub Action：codex exec、API key 禁忌、official Action 安全策略

codex exec 默认 read-only sandbox，但很多人会在 workflow 里把 OPENAI_API_KEY 设成 job-level environment variable。同一个 job 里跑的测试脚本、第三方 action、依赖安装 hooks 都可能读到这个 key。sandbox 不是审计，真正的安全来自最小权限和 key 保护。

API key 禁忌：不要设 job-level env

不要在 checkout 或运行仓库代码的 workflow 中把 OPENAI_API_KEY 或 CODEX_API_KEY 设为 job-level environment variable。仓库代码、测试、依赖生命周期脚本、第三方 action 在同一 job 里仍可能接触环境变量。

禁忌清单：

• 不要把 OPENAI_API_KEY 设成 job-level env
• 不要在 checkout 或运行仓库代码的 workflow 里设置 job-level key
• auth.json / ChatGPT-managed auth 不适合 public/open-source repo workflow
• 不要让同一 process environment 运行不可信代码

正确做法：

1. 单次 invocation inline：只在单次 codex exec invocation 中设置 CODEX_API_KEY

- name: Run Codex
  run: CODEX_API_KEY=${{ secrets.CODEX_API_KEY }} codex exec "review PR #${{ github.event.number }}"

2. official Action proxy：使用 openai/codex-action@v1 的 proxy

- uses: openai/codex-action@v1
  with:
    prompt: "review PR #${{ github.event.number }}"
    sandbox: read-only
    safety-strategy: drop-sudo

danger-full-access 在 CI 中只适合 isolated CI runner/container。不作为默认选项。可访问 runner 上所有资源。

GitHub Action 安全清单：限制触发者、保护 key、轮换 key

official Action 参数：

参数	默认值	说明
safety-strategy	drop-sudo	移除 sudo 权限
sandbox	-	选择 read-only/workspace-write/danger-full-access
allow-users	write access 用户	只有特定用户可触发
allow-bots	-	是否允许 bot 触发

read-only 不等于能保护 runner 上所有 secrets。Action 仍在 runner 上运行，只是约束文件系统只读。drop-sudo 移除 sudo 权限。sandbox 应选择完成任务所需的最窄模式。

GitHub Action 安全清单：

• 限制触发者：allow-users 只有特定用户，allow-bots 谨慎开启
• 清洗 PR/issue/prompt 输入：防 prompt injection，不直接把不可信输入喂给 Codex
• 保护 API key：不在 job-level env，单次 invocation inline 或用 proxy
• 最后一步运行 Codex：减少 key 暴露时间
• 怀疑泄露时轮换 key：不要先排查，先止损

PR/issue/prompt 输入视为不可信，需清洗。不直接把 PR comment 或 issue body 喂给 Codex prompt。

密钥泄露处理：发现疑似泄露后的第一步

发现疑似泄露后，第一步不是排查，而是轮换 key。先止损，再审计。sandbox 能约束 spawned commands，但不能阻止 Codex 把 key 输出到日志、PR comment、answer。

密钥泄露处理步骤：轮换 key、审计、撤销

第一步：轮换 key。不要先排查来源，先让旧 key 失效。

后续步骤：

1. 审计日志：检查 key 使用记录，看有没有异常调用
2. 撤销 token：确保旧 key 完全失效，不能有残留有效 session
3. 排查来源：检查 Codex log、GitHub Action 输出、依赖安装脚本、第三方 action

预防措施：

• 不要把 API key 放进前端代码或仓库
• 不要把 API key 设为 job-level env（CI）
• 使用 permission profile deny .env
• 定期轮换 key（OWASP Secrets Management Cheat Sheet 建议）

Codex Security 边界：不替代 SAST、不自动应用 patch

Codex Security 是 LLM-driven security analysis toolkit，运行于 ephemeral isolated container，输出结构化 finding 和 patch 建议。它能辅助发现/验证漏洞，但不能替代 SAST 或人工安全审查。

局限清单：

• 不替代 SAST
• 不替代 manual security review
• proposed patch 需用户 review，不会自动应用
• 用途：辅助发现/验证/建议，不是自动化修复

不要把 Codex Security 当成万能安全扫描。AI-driven 分析能发现一些问题，但真正的安全来自分层：可读范围、可写范围、网络、密钥、审批、review、撤销。

结论

Codex 的安全边界来自三层：sandbox 约束 spawned commands 的范围，approval policy 决定什么时候停下来问，permission profile 是强制访问控制。三层叠加，才是实际权限。

三个边界要记住：

• 指令不是权限：AGENTS.md 是指导，不是强制访问控制。不要靠口头约束保护 .env 和 API key。
• 审批不是隔离：approval policy 能拦住一部分操作，但 sandbox 和 permission profile 才是真正隔离。
• sandbox 不是审计：sandbox 能约束 spawned commands，但不能阻止 Codex 把 key 输出到日志、PR comment、answer。真正的安全来自分层。

快速自查清单：

• 是否配置了 .env deny glob？
• CI 里是否避免了 job-level API key？
• 是否限制了 GitHub Action 触发者？
• 是否审计了依赖安装脚本？
• 是否有 key 轮换计划？

安全边界挡不住逻辑错误。Codex 可能遵循所有权限规则，但生成的代码仍有 bug、测试仍可能失败、回滚仍需要准备。验收 diff、跑测试、准备回滚方案，是安全边界之外的第二道防线。

下一步建议：

• 失败复盘与验收流程：理解 Codex 出错时的处理流程、diff 验收方法、回滚策略。
• codex exec 自动化与 CI：深入 CI 场景的非交互模式、workflow 设计、错误处理。
• AGENTS.md 项目规则：学习如何写项目规则，但要记住它只是指导，不是权限系统。

相关阅读：

• AI coding 工具全景 2026：理解 AI coding 工具的全局生态。
• GitHub Actions CI 基础：复习 CI workflow 的基础概念。
• GitHub Actions 部署策略：理解 secrets 在部署中的使用边界。
• 前端 API key 泄露风险：了解密钥不要进前端/仓库的背景。