Codex 排除敏感文件怎么做：在官方 ignore 完善前的务实方案

GitHub issue #2847（及关联讨论）反复出现同一需求：像 .gitignore 那样，确定性、可提交进仓库地标记「Agent 不得读、不得送模」的路径——.env、密钥、*.pem、.aws/** 等。讨论里有人实测：即使写了文档约定，Codex 一旦 rg/grep 扫到内容，仍可能上传。功能在演进中，本文给现状认知 + 上线前能做的隔离，而不是假装已有完美开关。

你到底要防什么

两件事经常被混谈：

1. 机密不外泄：密钥、客户数据、内网 URL
2. 噪音不进上下文：node_modules、构建缓存、巨型生成物

#2847 侧重 1，并希望仓库级 + 用户级配置可共享。命名争论包括 .codexignore、更中性的 .agentignore，以及向 Google .aiexclude 看齐。Cursor 侧已有 .cursorignore 生态；Codex 用户不要假设「gitignore 自动等于 model-ignore」。

风险	例子	gitignore 能防吗
未跟踪 .env	本地 API key	否，Agent 仍可 read
已跟踪历史密钥	误 commit 的 token	部分，需 git 清理
环境变量注入	export 在 shell	否
grep 扫到日志	debug.log 含 token	否

官方能力到位前：务实防护层

按强度从高到低：

A. 物理隔离（最稳）

• 密钥只放本机环境变量 / 密钥管理器，从不落盘进仓库工作树
• 用例数据用脱敏夹具；真生产库连接串不进 Agent 可见目录
• 在 Codespace/干净 worktree 跑 Agent，挂载最小文件集
• 敏感 repo 用 sparse checkout 或子目录 worktree，Agent 只开 apps/web 不含 infra/secrets

B. 权限与沙箱

• 关不必要的网络；生产凭证不配进 Agent 环境
• 审批高危命令（读 ~/.ssh、打包上传、curl 外传）
• YOLO 只在无密钥沙箱开——与 Copilot harness 建议 同理
• Codex 文档中的 sandbox / approval 选项能开全开；国内用户别因「麻烦」默认 Allow All

C. 约定与钩子（防君子）

• AGENTS.md 写明禁读列表（不能单靠它）
• pre-commit 扫密钥（gitleaks、detect-secrets）；CI 拒明文 secret
• 若产品日后支持 ignore 文件，尽早采用官方格式并提交入库
• .env.example 只放占位符，不放真值

D. 监控

• 定期轮换可能暴露过的 token
• 对「Agent 是否读过某路径」保持怀疑，重要泄露按已暴露处理
• 云厂商 IAM：Agent 用的 key 单独一条 policy，可一键 revoke

凭证网关类思路见 OneCLI 凭证网关：让 Agent 拿短时票据，而不是长寿明文文件。

和其它工具 ignore 对照

工具	常见机制	注意
Cursor	.cursorignore 等	仍要验证是否覆盖 Agent 全路径
Gemini Code Assist	.aiexclude	跨工具未统一
Cline	.clineignore	名称分裂
Codex	社区诉求 ignore；以当前版本文档为准	勿假设 = gitignore
Git	.gitignore	只管版本库，不管 Agent read

团队若多 Agent 并行，维护一份「禁入路径」源（YAML 或 Makefile 生成），再生成各工具 ignore 文件，比五处手写少漏。示例禁入列表：

.env*
**/*.pem
**/.aws/**
**/secrets/**
**/id_rsa*

检查清单（今天就能做）

1. git ls-files | rg '\.env|id_rsa|\.pem' —— 已跟踪的立刻撤（git rm --cached + 轮换密钥）
2. Agent 环境 env | rg -i 'key|secret|token|password' —— 生产密钥不应出现
3. 演示仓与客户仓分开 worktree，物理路径不同
4. 读官方 Codex 文档「sandbox / approvals」章节，打开能开的限制
5. 关注 #2847 与 release note，官方 ignore 落地后立刻迁移
6. 用假数据跑一遍 Agent「全仓搜索 API_KEY」，看会不会读到 .env.local

泄露后应急（按顺序）

1. 立即 revoke 暴露的 key（假设已外传）
2. 查云厂商访问日志，看异常调用窗口
3. /git history 若含密钥，git filter-repo 或 BFG 清理后再轮换
4. 复盘：是 read 路径、grep 还是 paste 进 prompt
5. 更新禁入列表与 pre-commit，写进 incident 笔记供团队

国内合规场景：客户数据一旦进境外模型上下文，可能触发数据出境评估——物理隔离比事后解释便宜。

国内开发者注意

• .env 与微信/支付宝密钥：常放同一目录，Agent 一次 read .env 全暴露
• 公司 VPN 内网 URL：写进 .env 的 API_BASE 也会进上下文，脱敏成 https://api.example.internal 占位
• 多人共用 Relay：会话日志可能在服务商侧，密钥别出现在任何 prompt
• 开源贡献：fork 上游前确认本地无公司 .env；用 direnv 且 .envrc 不提交

常见问题

只把 .env 写进 .gitignore 够吗？

不够。gitignore 管 Git，不管 Agent 工具读盘。未跟踪文件仍可能被 read。还要配合物理隔离与审批。

AGENTS.md 写「不要读 .env」有用吗？

有一点提示作用，不是强制。模型可能忽略；工具层若允许读，仍会读。与 #2847 诉求一致：要工具层 blocklist。

开源贡献者怎么保护本地密钥？

克隆用干净目录；密钥用 direnv/1Password 注入；永远不要在含公司 .env 的目录里对公网模型开满权限。贡献 PR 前 git diff 扫一眼是否夹带 env。

Codex grep 到密钥算泄露吗？

按已暴露处理：grep 输出可能进上下文并上传。别在含真密钥的文件名上试 Agent「帮我找配置」。

和 Cursor 的 .cursorignore 能共用吗？

格式可能不同；可同源生成。迁移工具前逐条验证 Agent 路径是否覆盖 run_terminal_cmd 间接读取。

工作区布局示例（推荐）

把「Agent 可见」与「密钥」拆到不同目录：

~/work/
  myapp/          ← Agent 在此开 Codex/Cursor
  myapp-secrets/  ← .env 真值，不在 Agent cwd 内

启动 Agent 前 cd ~/work/myapp；密钥用 direnv 从上级或 1Password 注入到 shell，而不是写进 repo 内 .env。CI 同样：密钥在 runner secret，不在 checkout 树里。

多 Agent 并行时的最小政策

角色	规则
开发者本机	无 YOLO；.env 不进 repo
演示/录屏	专用脱敏 clone
CI Agent	只读 token；scope 最小
外包/实习	独立 IAM；不可访问 prod

#2847 要的是工具层 ignore；在官方落地前，组织政策 + 物理布局 仍是主防线。ignore 文件将来只是把已有政策机器可读化。

误操作场景速查

• 「帮我找项目里 API key 在哪」 → 可能 grep 全仓含 .env，立刻停会话并轮换
• Agent 建议把密钥写进 .env.example → 拒绝；example 只放 YOUR_KEY_HERE
• 复制生产日志进 chat 排错 → 日志常含 token；用 sed 打码后再贴
• monorepo 根目录开 Agent → 易扫到 packages/*/secrets；改在子包目录开

上线前让同事用 fresh Agent 会话执行：「列出你读过的所有含 password/key 的文件路径」。若列表出现 .env 或 credentials.json，说明隔离层未生效，先修布局再谈 ignore 文件。

Codex CLI 与 IDE 插件差异

同一仓库在 Codex CLI、Cursor Agent、VS Code Copilot 下，读盘路径可能不一致。.cursorignore 对 Codex 不一定生效；Copilot 在 Codespace 里可能另有挂载。多工具团队应维护「禁入路径」主清单，并在每个工具文档更新后做一次交叉验证：在同一测试 repo 放假 .env，分别开 Agent 尝试读取，记录是否 blocked。

合规与审计留痕

金融、医疗、政企项目常要求「谁何时把什么送进了模型」。在官方 ignore 完善前：

• 敏感操作走人工 PR，不经 Agent 自动改
• 会话导出策略写进安全制度（能否复制 chat 到工单）
• 与法务确认：客户合同是否禁止代码片段出境

这不是 scare tactic——#2847 讨论里已有「grep 命中即上传」的实测反馈，审计假设应是「可能已泄露」，而不是「应该没读」。

参考资料

• openai/codex#2847 A way to exclude sensitive files
• AI Agent 凭证网关 OneCLI
• GitHub Copilot harness 是什么