> ## Documentation Index
> Fetch the complete documentation index at: https://nvd-54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 权限

> 使用声明式权限规则控制深度智能体的文件系统访问

使用声明式权限规则控制智能体可以读写哪些文件和目录。将规则列表传入 `permissions=`，智能体的内置文件系统工具就会遵守这些规则。

<Note>
  权限需要 `deepagents>=1.9.1`。
</Note>

权限仅适用于内置文件系统工具（`ls`、`read_file`、`glob`、`grep`、`write_file`、`edit_file`）。自定义工具和访问文件系统的 MCP 工具不受覆盖。权限也不适用于[沙箱后端](/oss/javascript/deepagents/sandboxes)，因为沙箱通过 `execute` 工具支持任意命令执行。

<Tip>
  当你需要对内置文件系统工具的**基于路径的允许/拒绝规则**时，请使用 `permissions`。当你需要自定义验证逻辑（速率限制、审计日志、内容检查）或需要控制自定义工具时，请使用[后端策略钩子](/oss/javascript/deepagents/backends#add-policy-hooks)。
</Tip>

## 基本用法

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

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("basic: agent not created");
```

## 规则结构

每个 `FilesystemPermission` 有三个字段：

| 字段           | 类型                      | 描述                                                                                         |
| ------------ | ----------------------- | ------------------------------------------------------------------------------------------ |
| `operations` | `("read" \| "write")[]` | 此规则适用的操作。`"read"` 覆盖 `ls`、`read_file`、`glob`、`grep`。`"write"` 覆盖 `write_file`、`edit_file`。 |
| `paths`      | `string[]`              | 用于匹配文件路径的 glob 模式（例如 `["/workspace/**"]`）。支持 `**` 递归匹配和 `{a,b}` 交替。                        |
| `mode`       | `"allow" \| "deny"`     | 是允许还是拒绝匹配的操作。默认为 `"allow"`。                                                                |

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

路径必须是绝对路径（以 `/` 开头），不能包含 `..` 或 `~`。无效路径会在智能体构建时抛出异常。

## 示例

### 隔离到工作区目录

仅允许在 `/workspace/` 下进行读写，拒绝其他所有操作：

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/workspace/**"],
      mode: "allow",
    },
    {
      operations: ["read", "write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("isolate-workspace: agent not created");
```

### 保护特定文件

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/workspace/.env", "/workspace/examples/**"],
      mode: "deny",
    },
    {
      operations: ["read", "write"],
      paths: ["/workspace/**"],
      mode: "allow",
    },
    {
      operations: ["read", "write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("protect-files: agent not created");
```

### 只读记忆

允许智能体读取记忆文件但阻止其修改。这对于组织范围的策略或共享知识库很有用，这些内容只应由应用代码更新。更多上下文请参阅[只读与可写记忆](/oss/javascript/deepagents/memory#read-only-vs-writable-memory)。

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const store = new InMemoryStore();
const agent = createDeepAgent({
  model,
  backend: new CompositeBackend(new StateBackend(), {
    "/memories/": new StoreBackend({
      namespace: (rt) => [rt.serverInfo.user.identity],
    }),
    "/policies/": new StoreBackend({
      namespace: (rt) => [rt.context.orgId],
    }),
  }),
  permissions: [
    {
      operations: ["write"],
      paths: ["/memories/**", "/policies/**"],
      mode: "deny",
    },
  ],
  store,
});
if (!agent) throw new Error("read-only-memory: agent not created");
```

### 拒绝所有访问

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

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("deny-all: agent not created");
```

### 规则排序

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

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const correctPermissions: FilesystemPermission[] = [
  { operations: ["read", "write"], paths: ["/workspace/.env"], mode: "deny" },
  {
    operations: ["read", "write"],
    paths: ["/workspace/**"],
    mode: "allow",
  },
  { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
];

const incorrectPermissions: FilesystemPermission[] = [
  {
    operations: ["read", "write"],
    paths: ["/workspace/**"],
    mode: "allow",
  },
  {
    operations: ["read", "write"],
    paths: ["/workspace/.env"],
    mode: "deny",
  },
  { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
];
```

## 子智能体权限

[子智能体](/oss/javascript/deepagents/subagents)默认继承父智能体的权限。要给子智能体不同的权限，请在其规格中设置 `permissions` 字段。这将**完全替换**父级的规则。

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/workspace/**"],
      mode: "allow",
    },
    { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
  ],
  subagents: [
    {
      name: "auditor",
      description: "Read-only code reviewer",
      systemPrompt: "Review the code for issues.",
      permissions: [
        { operations: ["write"], paths: ["/**"], mode: "deny" },
        { operations: ["read"], paths: ["/workspace/**"], mode: "allow" },
        { operations: ["read"], paths: ["/**"], mode: "deny" },
      ],
    },
  ],
});
if (!agent) throw new Error("subagent: agent not created");
```

要显式授予子智能体不受限制的访问，请设置 `permissions: []`。空数组会用无限制覆盖父级规则。省略 `permissions` 则从父级继承。

## 复合后端

当使用带沙箱默认后端的 `CompositeBackend` 时，每个权限路径必须限定在已知的路由前缀下。沙箱支持任意命令执行，因此仅基于路径的限制无法阻止通过 shell 命令的文件系统访问。将权限限定到特定路由的[后端](/oss/javascript/deepagents/backends)可以避免这种冲突。

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const sandbox = new StateBackend();
const memoriesBackend = new StateBackend();
const composite = new CompositeBackend(sandbox, {
  "/memories/": memoriesBackend,
});
const agent = createDeepAgent({
  model,
  backend: composite,
  permissions: [
    { operations: ["write"], paths: ["/memories/**"], mode: "deny" },
  ],
});
if (!agent) throw new Error("composite-backend: agent not created");
```

包含任何路由之外路径的权限会在构建时抛出异常：

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const sandbox = new StateBackend();
const memoriesBackend = new StateBackend();
const composite = new CompositeBackend(sandbox, {
  "/memories/": memoriesBackend,
});

createDeepAgent({
  model,
  backend: composite,
  permissions: [
    { operations: ["write"], paths: ["/workspace/**"], mode: "deny" },
  ],
});

createDeepAgent({
  model,
  backend: composite,
  permissions: [{ operations: ["read"], paths: ["/**"], mode: "deny" }],
});
```

***

<div className="source-links">
  <Callout icon="terminal-2">
    [连接这些文档](/use-these-docs)到 Claude、VSCode 等工具，通过 MCP 获取实时解答。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/permissions.mdx)或[提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>