沙箱看不到我的文件？Git 盲区与 .env

让 AI 智能体检视项目，它说「这个文件不存在」；可文件明明躺在目录里。类似困惑在 Codex 用户里高频出现：沙箱能看到什么，与你想当然以为它能看到什么，中间隔着一层规则。按排障手册的说法，沙箱的可见范围与 Git 的跟踪名单高度相关：主要看得到被 Git 跟踪的文件，没入库的新文件、被 .gitignore 忽略的配置都可能整个不在视野里。这篇按误区文的惯例，先把三种常见说法原样摆出来，再逐条对照纠正，最后给一份让文件「入视野」的操作清单；被拦与看不见是两类问题，拦了怎么放开见PermissionError 排查一篇。

说法一：文件在目录里，它就该看得见

直觉上，智能体跑在我的项目目录里，目录下的一切都该尽收眼底。对照看，沙箱的视野更像一份名单：以 Git 跟踪状态为主要参照，跟踪的文件在名单上，未跟踪的新文件、被 .gitignore 忽略的文件默认不在。你刚写了一半没 add 的模块、本地起的草稿目录、构建产物，对它而言可能等于不存在——它读不到、搜不到，自然也不会改。这并非沙箱坏了，是可见性规则在起作用。相应的解法也简单：让文件进名单，git add 一次（不用提交），未跟踪文件进入 Git 的视野，沙箱随即可见；临时验证的需求，add 完继续干活就行。

说法二：.env 看不见是 Bug

第二种说法把 .env 不可见当成缺陷。对照看，这是有意设计：.env、密钥文件、本地凭据这类敏感内容几乎都在 .gitignore 的默认名单里，随 ignore 规则一起对沙箱隐身。好处明显：智能体做全库检索、批量读取时，不会顺手把密钥读进上下文，也不会把密钥内容写进日志、补丁与回答里——上下文里的敏感信息一旦进入，就可能随对话记录走远。代价是你真要让它读配置时得显式安排。相关的纪律一脉相承：密钥不该进仓库，也不该借「让它看见」而进上下文，配置与凭据的分离原则见密钥别进仓库一篇。

说法三：启动在哪，项目就在哪

第三种说法认为智能体的工作范围跟着当前 shell 的位置走。对照看，边界在启动那一刻划定：可写工作区按启动目录算，你在仓库的子目录里随手启动，边界就划在了子目录，写上层文件被拦、路径解析怪异都是这个原因。解法是用 --cd 把工作目录显式指到项目根再启动，一步到位。顺带说清两个相邻限制：家目录默认不在可写范围，智能体的改动落不到你的个人配置上；/tmp 一类临时目录有独立空间，放中间产物可以，别把交付物只存在那里。把「圈怎么划」复习一遍，见沙箱模式一篇。

对照之后：一份入视野清单

三种说法对照下来，共同的根子是把沙箱的可见性当成了「文件系统全量」，而它实际是「Git 名单加启动边界」。排查「看不到」按这份清单走：第一步，文件是否被 Git 跟踪，没有就 git add；第二步，启动目录是否是项目根，不是就 --cd 重启；第三步，目标路径是否在家目录或工作区之外，是就用附加目录参数；第四步，是否是被 ignore 的敏感文件，是就别让它读，改走显式配置注入。沙箱与环境隔离的通用逻辑，见智能体沙箱一篇的对照。动手验证很快：可以让豆包模拟一次「新增文件智能体看不到」的对话场景整理成复现步骤，再让 DeepSeek 把这份清单与 Git 状态对照成一张速查表，贴给团队当排障起点。

Git 盲区速查

• 沙箱可见性以 Git 跟踪名单为主要参照，未跟踪文件可能看不见
• git add 即入视野，不必等提交
• .env 与被 ignore 的敏感文件隐身是有意设计，别硬让它读
• 启动目录决定工作区边界，--cd 指到项目根再开工
• 家目录默认不可写，/tmp 只放中间产物

关于 Git 盲区的三问三答

• git add 之后要提交才算数吗？：不用。进入跟踪状态即被沙箱看见，add 而不提交足够日常排障用；确认可见后再决定要不要真提交，避免把半成品带进历史。
• 智能体看不到没跟踪的新文件，会有什么连锁风险？：看不见的文件改不了，风险主要在判断侧——它按「文件缺失」推理可能跑偏，比如重复建一个已存在的模块。先 add 再派任务，结果稳得多。
• 真要让它读 .env 里的某个值怎么办？：别放开 ignore 规则，把需要的值以显式方式注入环境变量或配置项，只给最小的一个；密钥本体不进上下文，用完轮换的习惯也要有。