第23章 Zed AI Agent 工具指南：内置功能、权限配置与自定义 MCP 支持

你可以采取措施来缓解这些问题。例如：

• 禁用那些会从项目中执行用户定义代码（如 Rust 过程宏）的语言服务器。
• 使用一种不执行仓库定义程序来报告 Git 状态的 Shell 提示符。
• 在运行 git commit 之前审查 diff。

但这些都无法改变一个基本原则：沙箱不能替代良好的安全实践。它只是纵深防御策略中的一层。

Zed 的默认配置文件旨在平衡安全性和便利性，但我们鼓励你根据自己的安全需求和风险状况调整设置。未启用的沙箱不是一个有效的沙箱。

审批提示

当 agent 需要访问默认沙箱之外的资源时，Zed 会在工具操作运行前显示沙箱审批提示。 根据工具的具体请求，提示可能会要求你允许：

• 访问特定主机（如 github.com 或 *.npmjs.org）的网络连接
• 访问任何主机的网络连接
• 访问特定文件系统路径的写入权限
• 不受限的文件系统写入，但受保护的 Git 元数据除外
• 在沙箱外运行终端命令

你可以为沙箱请求授予以下权限：

• 单个工具动作
• 当前线程的剩余部分
• 始终允许

针对线程剩余部分的批准仅在该线程内有效。选择“始终允许”的批准会保存在 settings.json 文件的 agent.sandbox_permissions 字段下。

持久化沙箱权限

如果你希望预先批准常见的沙箱请求，请在你的设置文件中添加持久化权限：

{
  "agent": {
    "sandbox_permissions": {
      "network_hosts": ["github.com", "*.npmjs.org"],
      "write_paths": ["/Users/you/.cache/my-tool"]
    }
  }
}

可用的选项如下：

建议优先授予窄范围的权限，例如特定主机或写入路径，而非使用 allow_all_hosts、allow_fs_write_all 或 allow_unsandboxed。

Git 元数据

当终端命令在沙箱中运行时，无法授予 Git 元数据的写入权限。这包括对 .git 目录、关联的 worktree 元数据、refs、索引、hooks、本地 Git 配置以及其他由 Git 控制的元数据文件的写入。即使批准了特定的可写路径或 allow_fs_write_all，Git 元数据仍然不可写。

平台支持

沙箱机制在每个操作系统平台上使用不同的底层实现。用户看到的提示类似，但具体的执行细节有所差异。

macOS

在 macOS 上，Zed 通过 sandbox-exec 使用 Apple 的 Seatbelt 沙箱。

沙箱化的终端命令：

• 可以读取文件系统
• 可以在已打开的项目目录内写入，受保护的 Git 元数据除外
• 可以写入通过 $TMPDIR、$TMP、$TEMP 暴露的每线程临时目录
• 可以读取受保护的 Git 元数据
• 不能写入受保护的 Git 元数据，即使你批准了更宽泛的写权限也不行
• 不能写入其他位置，除非你批准了额外路径或更宽泛的写权限
• 不能访问网络，除非你批准了网络访问
• 只能访问开发者工具所需的 macOS 系统（Mach）服务白名单；可能被用来逃逸沙箱的服务（LaunchServices 和 launchd，它们可以在沙箱外启动进程）、读取剪贴板的服务（pasteboard）以及捕获音频的服务均不可访问

在 macOS 上批准网络访问后，Zed 会使用 HTTP/HTTPS 代理，从而将访问限制在已批准的主机内。 不遵循代理环境变量的工具（如 SSH、FTP 和原始 socket 客户端）即使批准了特定主机的网络访问，也可能无法正常工作。 对于需要联网的终端命令，尽量优先使用 HTTPS URL 而非 SSH URL。

Linux

在 Linux 上，Zed 使用 Bubblewrap（bwrap）实现沙箱。

Zed 只使用非 setuid 的 bwrap 二进制文件。其沙箱完全基于非特权 user namespace 构建，因此 setuid-root 的 bwrap 并不提供额外功能，运行它反而意味着以 root 权限执行参数部分来自模型影响输入的设置操作。如果 PATH 中找到的 bwrap 只有 setuid-root 版本，Zed 会拒绝运行；请安装非 setuid 的 Bubblewrap 以启用沙箱。

沙箱化的终端命令：

• 可以读取文件系统，包括受保护的 Git 元数据内容
• 可以在已打开的项目目录内写入，受保护的 Git 元数据除外
• 可写入 /tmp 目录，该目录由全新的临时文件系统提供支持，并在每次终端工具调用之间被清空（如果你批准了不受限的文件系统写入权限，/tmp 将指向宿主机上真实的 /tmp 目录，而非全新的临时文件系统）
• 无法写入受保护的 Git 元数据
• 除非你批准了额外的路径或更广泛的写入权限，否则无法写入其他位置
• 除非你批准了网络访问权限，否则无法访问网络

在 Linux 上，如果批准了针对特定主机的网络访问，Zed 会使用 HTTP/HTTPS 代理，以便将访问限制在已批准的主机范围内。对于不遵循代理环境变量的工具（如 SSH、FTP 和原始套接字客户端），即使获批特定主机的网络访问，也可能无法正常工作。

如果 Bubblewrap 不可用或无法在当前环境中创建沙箱，Zed 可能会在无操作系统沙箱限制的情况下运行命令，并在工具输出中显示警告。

警告：在 Linux 和 WSL 上，对文件系统对象的限制是在沙箱创建时确定的。这意味着，除了其他情况外，如果代理被授予对非 Git 仓库目录 /foo 的访问权限，它可能会创建 /foo/.git。有关此限制的更详细影响，请参阅 我能多大程度信任沙箱？。

安装 Bubblewrap

Zed 需要你的 $PATH 中有一个可运行的、非 setuid 的 bwrap 二进制文件。通常，只需通过发行版的包管理器安装 bubblewrap 即可。

你可以通过以下命令测试其是否正常工作：

bwrap --ro-bind / / -- echo "working"

此处的“非 setuid”指的是setuid 位。历史上，bubblewrap 同时发布过 setuid 和非 setuid 二进制文件。出于安全考虑，setuid 二进制文件正在逐步被淘汰，因此 Zed 的沙箱明确拒绝使用 setuid 版本的 bwrap 二进制文件。

Ubuntu 特定要求

注意：以下内容不适用于 WSL 上的 Ubuntu。

Bubblewrap 依赖 Linux 内核中一项名为“命名空间”（namespaces）的特性。在许多系统上，非特权用户也可以创建命名空间，但历史上，该特性曾被用于多种攻击手段。

作为应对措施，Canonical 在 Ubuntu 23.10 中 增加了一项安全措施，用于限制非特权用户命名空间。这些限制由 AppArmor 强制执行。

因此，安装 bubblewrap 后，您可能还需要为其安装一个 AppArmor 配置文件。该配置文件赋予 bubblewrap 创建命名空间的权限，无需使用 sudo 提权。

sudo apt install bubblewrap

# On Ubuntu 25.04 and later, `apparmor` ships with a profile for bubblewrap by default.
# Make sure you're up-to-date
sudo apt install --only-upgrade apparmor

# On older versions, manually install the profile
sudo apt update
sudo apt install apparmor-profiles apparmor-utils
sudo install -m 0644 \
  /usr/share/apparmor/extra-profiles/bwrap-userns-restrict \
  /etc/apparmor.d/bwrap-userns-restrict
sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict

Windows

在 Windows 上，Zed Agent 沙箱功能仅在代理操作运行于 WSL 内部时受到支持。

警告：受限于 WSL 的实现机制，如果用户对位于 NTFS 驱动器上的任意路径拥有写权限，终端命令可能会在沙箱授权范围之外进行写入操作。这包括存储在 NTFS 上的当前项目授权。发生此类情况时，Zed 会显示警告。实际上，我们认为利用此缺陷进行攻击难度较大，但无法保证绝对安全。更多技术细节请参阅下文。

在 WSL 内部，Zed 使用 Linux 的 Bubblewrap 沙箱，因为 WSL 提供了 Bubblewrap 所需的 Linux 进程和文件系统原语。目前，原生 Windows 进程在 Zed 中尚不支持相同的沙箱集成，因此原生 Windows 命令无法像代理操作那样被 Zed Agent 的操作系统沙箱严格限制。

在 WSL 中运行时，将应用 Linux 的沙箱机制，包括要求 bwrap 不能被设置为 setuid-root：

• 文件系统隔离由 Bubblewrap 提供
• 受保护的 Git 元数据内容保持可读，但禁止写入
• 沙箱化终端调用中的 /tmp 目录是临时的
• 网络访问是全有或全无的，无法按主机区分，所以针对特定主机的网络请求会被拒绝，需要联网时代理必须申请完全开放的网络访问权限

如果未安装 WSL，或者你选择不在沙箱中运行命令，Zed 会退回到标准终端行为，在本地 shell 中运行。它会按常规的优先级顺序选择 shell：安装了 bash（scoop 的 bash 或 Git Bash）就用 bash，否则用 PowerShell，最后是 cmd.exe。此时命令运行在原生 Windows 路径下而非 WSL 的 Linux 文件系统，路径约定也会随之变化（例如 C:\... 或 /c/...，而不是 WSL 的 /mnt/c/...），因此为沙箱化 WSL shell 编写的命令可能会表现不同。

为什么 NTFS 对象会破坏沙箱？

总的来说，文件系统沙箱的安全性依赖两项内容的匹配：

• 用户批准时看到的路径
• 实际被授权访问的文件系统对象

如果用户以为自己授权的是 /foo/hello，实际上授权的却是 /bar/world，那沙箱就失效了。

在 Linux 上，这个"文件系统对象"叫做 inode。

但 /foo/hello 并不指向某个 inode。粗略地说，它指向的是一个 inode 可能存在的位置。它在某一时刻可能对应一个 inode，之后又对应另一个。

而且由于符号链接的存在，一个拥有 /foo 写权限的代理，即使没有 /secret 的写权限，也可能把 /foo/bar 改为指向 /secret。一旦发生这种情况，即使代理有 /foo 的访问权限，我们也不能再授予它 /foo/bar 的访问权限，因为那等于间接授权访问 /secret。

这意味着我们只能引用满足以下条件的路径：

• 规范化（即不含符号链接）
• 绝对路径
• 自验证后未发生变化

在非 WSL 的 Linux 上，我们可以直接打开路径获取"文件描述符"，它能直接标识 inode，持有该文件描述符就相当于"锁定"了正确的 inode。当路径指向 Linux 文件系统中的对象时，这个方法在 WSL 上同样有效。

不过，WSL 允许访问存储于 Windows 磁盘中的文件。例如，Windows 路径 C:\foo\bar.txt 对应于 Linux 下的 /mnt/c/foo/bar.txt，其机制类似于网络驱动器。遗憾的是，针对这类文件的 inode 锁定无法保证生效。虽然我们可以锁定 /mnt/c/foo/bar.txt 的 inode，但这并不等同于锁定了底层的 Windows 文件系统对象。因此，在沙箱生命周期内，该对象仍可能发生变动，从而可能允许写入操作突破沙箱边界。

实际中这一风险有多大？

在测试中，我们无法利用此漏洞逃逸出沙箱。

在实际使用中，这种映射关系往往相当稳定。原因在于，Linux 文件系统中生成的 inode 源自文件引用（非常粗略地讲，类似“Windows inode”），其稳定性与 Linux inode 相近。标准的“重命名子组件”攻击似乎会产生不同的 inode 编号，导致沙箱内的检查采取 fail-closed 策略。

但关键在于，这并非绝对保证。这只是我们在测试中观察到的行为，却找不到任何文档能保证此行为在所有情况下、对所有新旧版本的 Windows/WSL 以及任意配置选项均有效。

Zed 的沙箱设计目标是为做到完全不可攻破，即使面对一个具备完全控制力、能完全操纵项目文件并运行于标准用户环境下的有动机攻击者。它不假设代理是“总体善意但偶尔粗心”的。

鉴于此，我们无法像对待更常规场景那样，对沙箱安全性做出同等保证。然而，即使保证程度有所削弱，沙箱仍能让你比不启用时安全得多，因此值得保持启用。

选择批准内容

审查沙箱提示时，优先选择能让任务继续进行的最小权限：

• 当目标主机已知时，仅批准特定主机而非所有主机
• 仅批准特定写入路径，而非无限制的文件系统写入
• 仅当命令在沙箱内无法运行时，才批准无沙箱执行
• 对不熟悉的命令使用一次性批准
• 仅对预期会复用的访问使用线程级或永久批准

如果命令因沙箱阻止访问而失败，在批准更广泛的请求之前，请先询问 Agent 为什么需要该权限。

Zed 中的 Model Context Protocol (MCP)

Zed 使用 Model Context Protocol 与上下文服务器进行交互。

Model Context Protocol (MCP) 是一种开放协议，用于通过标准接口将 LLM 应用连接到外部工具和数据源。

支持的功能

Zed 目前支持 MCP 的 Tools 和 Prompts 功能。我们欢迎有助于推进 Zed MCP 功能覆盖范围（如 Discovery、Sampling、Elicitation 等）的贡献。

Zed 还处理来自 MCP 服务器的 notifications/tools/list_changed 通知。当服务器在运行时添加、移除或修改其可用工具时，Zed 会自动重新加载工具列表，无需重启服务器。

Agent 路径支持

安装 MCP 服务器

作为扩展

在 Zed 中使用 MCP 服务器的方式之一是将其暴露为扩展。查看 MCP Server Extensions 页面以了解如何创建自己的扩展。

许多 MCP 服务器提供为扩展。您可以通过以下方式查找：

1. Zed 网站
2. 在应用中，打开 Command Palette 并运行 {#action zed::Extensions} 操作
3. 在应用中打开 Settings → AI → MCP Servers，点击 Add Server，然后选择 Install from Extensions

以下是一些以扩展形式提供的常用 MCP 服务器：

• Context7
• GitHub
• Puppeteer
• Gem
• Brave Search
• Prisma
• Framelink Figma
• Resend

以自定义服务器方式添加

创建扩展并不是在 Zed 中使用 MCP 服务器的唯一方式。你可以在 Settings → AI → MCP Servers 中连接本地和远程 MCP 服务器（也可以通过 {#action agent::OpenSettings} 操作打开设置，然后选择 MCP Servers）。点击页面顶部的 Add Server，再选择 Add Local Server 或 Add Remote Server。你指定的配置会在设置文件中（可通过 {#action zed::OpenSettingsFile} 打开）生成类似下面这样的条目：

{
  "context_servers": {
    "local-mcp-server": {
      "command": "some-command",
      "args": ["arg-1", "arg-2"],
      "env": {}
    },
    "remote-mcp-server": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    },
    "remote-mcp-server-with-oauth": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}

注意：如果远程 MCP 服务器没有配置 "Authorization" 请求头，Zed 会提示你通过标准的 MCP OAuth 流程对服务器进行身份验证。

使用 MCP 服务器

配置检查

大多数 MCP 服务器在安装后还需要进行配置。

安装扩展后，Zed 会弹出窗口，提示你需要完成哪些设置才能正确使用该扩展。例如，GitHub MCP 扩展要求你添加一个个人访问令牌。

对于自定义服务器，请务必查阅提供商的文档，确定 JSON 中需要添加的命令、参数和环境变量类型。

要检查 MCP 服务器是否配置正确，请打开设置 → AI → MCP 服务器，并留意名称旁边的指示点。如果运行正常，指示点会显示绿色，且提示信息为“Server is active”。若不正常，其他颜色及提示信息会指示当前状态。

使用 Agent 面板

安装完成后，你可以返回 Agent 面板开始输入提示词。

MCP 工具调用的可靠性因模型而异。在提示中提及 MCP 服务器名称，有助于模型选择该服务器提供的工具。

然而，若希望确保使用某个 MCP 服务器，你可以创建自定义配置，关闭所有内置工具（或可能与服务器工具产生冲突的工具），仅开启该 MCP 服务器提供的工具。

例如，Dagger 团队建议对其Container Use MCP 服务器采用此方式：

"agent": {
  "profiles": {
    "container-use": {
      "name": "Container Use",
      "tools": {
        "fetch": true,
        "copy_path": false,
        "find_path": false,
        "delete_path": false,
        "create_directory": false,
        "list_directory": false,
        "diagnostics": false,
        "read_file": false,
        "move_path": false,
        "grep": false,
        "edit_file": false,
        "terminal": false
      },
      "enable_all_context_servers": false,
      "context_servers": {
        "container-use": {
          "tools": {
            "environment_create": true,
            "environment_add_service": true,
            "environment_update": true,
            "environment_run_cmd": true,
            "environment_open": true,
            "environment_file_write": true,
            "environment_file_read": true,
            "environment_file_list": true,
            "environment_file_delete": true,
            "environment_checkpoint": true
          }
        }
      }
    }
  }
}

工具权限

注意：在 Zed v0.224.0 及以上版本中，工具审批由 agent.tool_permissions.default 控制。 在早期版本中，该行为由布尔值 agent.always_allow_tool_actions（默认 false）控制。

Zed 的 Agent 面板提供 agent.tool_permissions.default 设置，用于控制原生 Zed agent 的工具审批行为：

• "confirm"（默认）— 在执行任何工具操作（包括 MCP 工具调用）前提示批准
• "allow" — 自动批准工具操作，无需提示
• "deny" — 阻止所有工具操作

如果想对具体的 MCP 工具进行细粒度控制，可以为每个工具配置权限规则。MCP 工具使用 mcp:<server>:<tool_name> 这样的键格式，例如 mcp:github:create_issue。对 MCP 工具来说，每个工具条目中的 default 键是主要的配置方式，因为基于模式的规则在匹配 MCP 工具时会匹配空字符串，大多数模式都无法命中。

了解更多关于工具权限的工作原理、进一步的定制方法及其他细节。

External Agents

在 Zed 中配置的 MCP 服务器会通过 Agent Client Protocol 转发给 External Agents。External Agents 也可以通过自身的原生配置文件访问 MCP 服务器。

关于 Zed 与 External Agents 之间共享哪些配置，详见配置边界。

错误处理

当 MCP 服务器在处理工具调用时出错，agent 会直接收到错误信息，操作失败。常见错误场景包括：

• 传给工具的参数无效
• 服务器端故障（数据库连接问题、速率限制）
• 操作不受支持或资源缺失

context server 的错误信息会显示在 agent 的回复中，方便你诊断并修复问题。具体错误代码的含义，请查阅 context server 的日志或文档。