PermissionError：沙箱拦了什么怎么放开

用 AI 智能体跑任务，中途冒出一个 PermissionError，很多人的第一反应是任务失败了、工具坏了。恰恰相反：这类报错多数时候说明沙箱在正常工作——智能体试图做一个当前档位不允许的动作，被拦下来并告诉你拦在哪。它不是终点，是路标：报错上下文里通常带着路径与动作类型，顺着读就知道是哪个操作越了界。这篇给一条固定的排查顺序，从定位到放开逐层走，避免一被拦就跳到全权档；为什么批了还拦，两层机制的关系见审批与沙箱一篇。

排查第一步：先读报错，定位被拦的操作

PermissionError 的价值在上下文：报错通常指向具体路径与动作——写哪个文件、访问哪个目录、发什么网络请求。拿到报错先分类：文件类，看路径在工作区内还是外；网络类，看是装依赖、拉接口还是访问文档。分类的目的是别调错旋钮：写文件被拦，调权限档；联网被拦，调网络开关，两件事不相干。还有一个前置判断：动作是卡在等你确认（审批层），还是报错终止（沙箱层），前者是模式问题，后者才是沙箱问题。审批只解决「要不要问你」，批准之后动作仍在沙箱圈里执行，批了还被拦的机制与误区，见批准等于放行一篇。

排查第二步：检查当前沙箱档位

最常见的拦截原因是档位不对：只读档下任何写文件动作都会被拦，这属于设计行为。先确认当前档位，再决定调不调：任务需要改代码、跑构建，就把档位升到 workspace-write，项目目录内的读写随之放开。这里要分清「该放」与「不该放」：工作区内的常规改动，升级档位是正常操作；智能体要写的是工作区之外的系统路径或别的项目，先问一句为什么，任务描述与路径对不上时，警惕是它理解偏了，而不是权限太紧。

排查第三步：路径与目录对不上

第二类高发拦截是路径越界：要写的文件不在启动时划定的项目目录里。两个常规解法：一是用 --add-dir 把额外目录附加进可写范围，适合跨仓库改动的任务；二是回头检查启动位置，用 --cd 把工作目录指到项目根，边界划正了，绝大多数路径报错自然消失。临时产物还有一条路：/tmp 一类的临时目录有独立的可写空间，中间文件放那里不占工作区预算。如果智能体声称「看不到你的文件」，先别怀疑权限，可能是文件没进 Git 跟踪，盲区机制见Git 盲区一篇。

排查第四步：网络被拦，开 network_access

workspace-write 档默认断网，这是刻意设计：能写文件又能联网的智能体，风险面立刻变大。任务确实要联网（装依赖、调接口），在配置里把 workspace-write 下的 network_access 开关打开，范围仅限当前档位，别为了联网直接跳全权。网络类问题还有一个变体：表现相近但根子不同——连接不稳、流式中断属于网络环境问题，与沙箱无关，别拧错旋钮。排查到底仍是异常时，再考虑版本因素：跨版本的沙箱行为有差异，截至发稿版本，以官方更新日志为准。

放开的纪律：逐层走，留退路

把四步合起来是一条固定顺序：先读报错定位操作，再查档位，然后对路径（--add-dir 与 --cd），最后开网络开关。顺序的意义在于每次只动一层，动完重跑任务验证，问题在哪一层清清楚楚；跳着调，最后连是哪层的问题都说不清。三条纪律附送：全权档不是排查工具，别用它「验证」问题；放开前想清楚这层风险是否可承受；每放开一层，diff 都要人工过目。三档各自的边界回顾见沙箱模式一篇；批准与隔离两种约束的对照，见沙箱与直连一篇。想让排查顺序变成团队资产，可以让 DeepSeek 把四步整理成一页决策树贴进内部文档，再让豆包出几个模拟报错考一考新人，顺序感练一次就成型。

PermissionError 速查

• 报错是路标：上下文带路径与动作，先定位再动手
• 顺序：读报错 → 查档位 → 对路径（--add-dir/--cd）→ 开 network_access
• 审批卡住是等你确认，沙箱拦截是报错终止，先分清两层
• workspace-write 默认断网，联网要显式打开开关
• 每次只放开一层并重跑验证，全权档不当排查工具

关于 PermissionError 的三问三答

• 升级到 workspace-write 还报被拦，为什么？：先看路径：这一档只放开项目目录，写工作区外的路径仍会被拦，用 --add-dir 附加目录；再看动作：联网请求默认也拦，要单独开 network_access。两处都对上还拦，再按平台差异查版本支持。
• 把全权档打开，报错就不见了，说明问题解决了吗？：说明不了。全权只是把所有拦截都关掉，报错消失不等于问题被定位，下次换回工作区可写还会复发，按四步顺序排查才是解决。
• 被拦的动作可以放着不管吗？：可以。拦截发生时任务通常停在那一步，处理完对应层再让智能体重试即可，已完成的改动不会丢；反复拦同一路径，多半是启动目录划错了。