使用声明式权限规则控制代理可以读取或写入的文件和目录。将规则列表传递给 permissions= ，代理的内置文件系统工具会遵守这些规则。

权限仅适用于内置文件系统工具（ls, read_file, glob, grep, write_file, edit_file）。自定义工具和访问文件系统的 MCP 工具不受覆盖。权限也不适用于 沙盒后端，它支持通过以下方式执行任意命令 execute tool.

基本用法

将 FilesystemPermission 规则列表传递给 createDeepAgent。规则按声明顺序评估。第一个匹配的规则生效。如果没有规则匹配，则允许操作。

规则结构

每个 FilesystemPermission 有三个字段：

规则使用首次匹配优先评估：第一个匹配的规则 operations 和 paths 匹配当前调用的规则决定结果。如果没有规则匹配，则该调用 **被允许** （宽容默认）。

路径必须是绝对路径（以 /开头），且不能包含 .. or ~。无效路径在代理构造时抛出异常。

示例

隔离到工作区目录

仅允许在以下位置进行读写 /workspace/ 并拒绝其他一切操作：

保护特定文件

只读内存

允许智能体读取内存文件但阻止其修改它们。这对于组织范围的策略或仅应由应用程序代码更新的共享知识库很有用。请参阅 只读内存与可写内存 获取更多上下文。

拒绝所有访问

阻止所有读写操作。这是一个限制性的基线，您可以在其上叠加更具体的允许规则：

规则排序

由于采用优先匹配原则，规则的顺序很重要。请将更具体的规则放在更宽泛的规则之前：

子代理权限

子代理 默认继承父代理的权限。若要为子代理设置不同的权限，请在 permissions 字段中设置。这将 **替换** 父代理的规则。

若要显式授予子代理无限制访问权限，请设置 permissions: []。空数组会覆盖父规则且不施加任何限制。若省略 permissions ，则继承父代理的权限。

复合后端

使用带有沙箱默认值的 CompositeBackend 时，每个权限路径都必须限定在已知路由前缀下。沙箱支持任意命令执行，因此仅靠基于路径的限制无法通过 shell 命令防止文件系统访问。将权限限定到特定路由的 后端 可避免此冲突。

包含在任何路由外部路径的权限会在构造时抛出错误：