第20章 Zed 中的 AI Agent：三种执行路径详解

Zed 支持三种智能体（Agent）执行路径。你可以根据希望智能体任务以何种方式运行，来选择合适的路径。

智能体路径有时也被称为“harness”（承载框架）。它决定了智能体任务在 Zed 中如何启动、展示、配置和控制。

智能体路径 vs LLM 提供商

Zed Agent 使用在 Zed 中配置的模型。外部智能体 和 终端线程 可能使用它们各自的模型配置。

线程类型

线程是 线程侧边栏中显示的基本单元。线程类型包括：

• Zed Agent 线程
• 外部智能体 线程
• 终端线程

使用并行智能体可一次性运行并管理多个线程。

Zed 智能体

Zed 智能体是 Zed 的原生智能体路径。它运行在智能体面板和线程侧边栏中，使用通过LLM 提供商配置的模型，并与 Zed 的项目、编辑器、终端及代码审查界面集成。

在希望智能体执行以下操作时，请使用 Zed 智能体：

• 读取并搜索项目
• 编辑文件
• 运行终端命令
• 使用 Zed 托管的 MCP 工具
• 遵循智能体配置
• 使用 Zed 的技能和指令
• 在 Zed 的代码审查界面中展示更改

Zed 智能体的使用依赖

与其他 Agent 使用方式的区别

完整对比请参见 Agents。

External Agents - Zed

External Agents 是通过 Agent Client Protocol (ACP) 与 Zed 集成的 agent。Zed 负责在 Agent Panel 和 Threads Sidebar 中承载会话线程，而 External Agent 通常自行管理运行时、认证、模型选择、工具和原生配置。

如果你想直接在终端驱动的线程中运行 CLI 或 TUI，请改用 Terminal Threads。

External Agents 通过各自的进程和提供商关系运行。计费、法律条款、数据保留和处理等事宜由你与 agent 提供商之间自行约定，Zed 不对 External Agents 收费。

关于 Zed 托管的模型和 Zed 管理的 AI 功能，请参见 AI Privacy 和 Feedback and Training Data。

从 ACP Registry 安装

ACP Registry 是在 Zed 中安装常见 External Agents 的主要途径。

使用 {#action zed::AcpRegistry} 打开注册表，或通过 {#action agent::OpenSettings} 打开 Agent Settings。进入 External Agents 页面，点击 Add Agent，然后选择 Install from Registry。

安装完成后，该 Agent 会出现在 Agent Panel 和 Threads Sidebar 的新线程菜单中。

常用 Agents

常见的外部 Agents 包括：

• Claude
• Codex
• OpenCode
• Copilot
• Cursor
• Pi Coding Agent

此列表经精选，并非详尽无遗。请在 Zed 中打开 ACP Registry 查看当前可用的完整列表。

如需查看针对各公司的特定设置路径（包括 Claude、Codex、Gemini、OpenCode、Copilot、Cursor、Pi 和 Poolside），请参阅 AI by Company。

Claude Agent

希望 Claude 作为 ACP 集成的外部 Agent 在 Zed 中运行时，请使用 Claude Agent。

从 ACP Registry 安装 Claude Agent，然后从 Agent Panel 或 Threads Sidebar 启动 Claude Agent 线程。Claude Agent 拥有独立的认证和计费体系。为 Zed Agent 配置的 Anthropic API key 不会自动配置 Claude Agent。

选择计费方式时，请打开 Claude Agent 线程，运行 /login，并通过 API key 或（在支持的情况下）Claude Code 进行认证。Claude 特有的文件（如 CLAUDE.md）可由 Claude Agent 直接读取。

Codex

希望 Codex 作为 ACP 集成的外部 Agent 在 Zed 中运行时，请使用 Codex。

从 ACP Registry 安装 Codex，然后从 Agent Panel 或 Threads Sidebar 启动 Codex 线程。Codex 拥有独立的认证和计费体系。为 Zed Agent 配置的 OpenAI API key 不会自动配置 Codex。

根据安装版本和环境不同，Codex 可能支持 ChatGPT 登录、Codex API key、OpenAI API key 或 Codex 原生配置。如需更改认证方式，请使用 Codex 线程原生的登录/注销流程。

Gemini CLI

如果你希望在 Zed 中让 Gemini 以 ACP 集成的外部 Agent 身份运行，请使用 Gemini CLI。

从 ACP Registry 安装 Gemini CLI，然后从 Agent Panel 或 Threads Sidebar 启动一个 Gemini CLI 线程。Gemini CLI 管理自身的认证，可能会提示你通过 Google、Vertex AI 或其他 Gemini 支持的流程登录。

如果 Agent 进程能访问 GEMINI_API_KEY 或 GOOGLE_AI_API_KEY，Gemini CLI 会使用这些密钥。否则，若你已为 Zed 的 Google AI provider 配置了 API key，Zed 会将该密钥作为 GEMINI_API_KEY 传递给 Gemini CLI。

OpenCode

如果你希望在 Zed 中让 OpenCode 以 ACP 集成的外部 Agent 身份运行，请使用 OpenCode。

从 ACP Registry 安装 OpenCode，然后从 Agent Panel 或 Threads Sidebar 启动一个 OpenCode 线程。OpenCode 管理自身的认证、模型选择和订阅行为。若要改用 Zed Agent 中的 OpenCode 模型，请配置 OpenCode API 访问权限。

Copilot

如果可用，在你希望 Copilot 以 ACP 集成的外部 Agent 身份运行于 Zed 时，请使用 Copilot External Agents。

Copilot Agent 的认证由 Copilot 集成方负责。若要在 Zed Agent 或 Copilot 编辑预测中使用 Copilot Chat 模型，请参阅 使用现有订阅。

Cursor

如果可用，在你希望 Cursor 以 ACP 集成的外部 Agent 身份运行于 Zed 时，请使用 Cursor External Agents。

Cursor 的订阅不会配置 Zed 的 LLM provider 设置。请在可用时使用 Cursor 的外部 Agent 或 CLI/TUI 配置。

Pi Coding Agent

如果你希望在 Zed 中让 Pi 以 ACP 集成的外部 Agent 身份运行，请使用 Pi Coding Agent。

Pi 是一个 Agent 运行框架，而非 Zed 的 LLM 订阅。请在 Pi 中配置任何 provider 认证、订阅、工具或模型选择。

Poolside

如果你希望在 Zed 中让 Poolside 以 ACP 集成的外部 Agent 身份运行，请使用 Poolside。

从 ACP Registry 安装 Poolside，然后在 Agent Panel 或 Threads Sidebar 中新建一个 Poolside 线程。如果还没有完成认证，线程里会提供 Log in to Poolside 选项，它会在终端中运行 pool login。认证和模型选择都通过 Poolside 配置，而不是 Zed。

如果想改在终端里配置 Poolside，可以先安装 Poolside Agent CLI，然后运行：

pool acp setup --editor zed

这条命令始终写入 ~/.config/zed/settings.json，即 macOS 以及未自定义 XDG_CONFIG_HOME 的 Linux 上的 Zed 配置文件。如果你用的是 Windows，或者自定义了配置目录，请改用从 Registry 安装的方式，或参考下面的手动配置方法。配置完成后无需重启 Zed，它会自动检测到配置变更。之后在新建线程菜单中选择 Poolside 即可。

如需手动配置，先安装 Poolside Agent CLI，确保 pool 在你的 PATH 中，然后将其添加为 Custom Agent：

{
  "agent_servers": {
    "Poolside": {
      "command": "pool",
      "args": ["acp"],
      "type": "custom"
    }
  }
}

更多配置细节请参阅 Poolside 的 Zed 文档。

启动 External Agent 线程

打开 Agent Panel，通过 agent 选择器或新建线程菜单，即可使用已安装的 External Agent 开启一个线程。

你还可以借助 {#action agent::NewExternalAgentThread} 为特定 agent 创建快捷键。

配置边界

External Agent 以独立进程运行，通过 ACP 与 Zed 通信。这在 Zed 配置和 agent 自身配置之间划出了边界。

关于 Zed 原生 agent 的配置，请参见 Zed Agent。

针对各 Agent 的身份验证与配置

外部 Agent 可能拥有独立的登录流程、API 密钥设置、订阅行为、环境变量及配置文件。

示例：

• Claude Agent 可能使用 Claude Code 身份验证及 Claude 原生配置。
• Codex 可能使用 ChatGPT 登录、Codex API 密钥、OpenAI API 密钥或 Codex 原生配置。
• Cursor 的订阅不会配置 Zed 的 LLM 提供商设置；如有可用，请通过 Cursor 的 agent 或 CLI 进行设置。
• Pi Coding Agent 是一个 agent 框架（harness）。请在 Pi 中配置提供商身份验证。

如果外部 Agent 支持基于订阅的行为，请在该 agent 中完成相关配置，除非其 Zed 集成说明另有规定。

远程项目

外部 Agent 可以在本地读取凭据，也可以在远程读取，或通过其自身的登录流程获取。在使用 SSH、开发容器或其他远程项目时，请检查特定 agent 的配置路径。

保存在本地钥匙串中的 Zed LLM 提供商 API 密钥，并不自动等同于外部 Agent 的凭据。

自定义 Agent

当你正在开发兼容 ACP 的 agent，或需要运行注册表中尚未收录的 agent 时，可以使用自定义 agent。

打开 Agent 设置，前往 外部 Agent 页面，点击 添加 Agent，然后选择 添加自定义 Agent。Zed 将打开你的设置文件，其中包含一个 agent_servers 条目。

{
  "agent_servers": {
    "my-agent": {
      "type": "custom",
      "command": "node",
      "args": ["~/projects/agent/index.js", "--acp"],
      "env": {}
    }
  }
}

通过 Registry 安装的 agent 也可以在 agent_servers.<agent-id> 下拥有针对特定 agent 的设置。

由扩展提供的 Agent

扩展提供的 agent 已不再使用。现在安装 agent 的方式是通过 ACP Registry，先前安装的扩展 agent 会自动迁移到对应的 registry 版本。

详情参见 Agent Server Extensions。

导入线程

Zed 可以从已配置的 External Agents 导入现有的线程，使它们与你的其他线程一起出现在 线程历史中。

通过 {#kb multi_workspace::ToggleWorkspaceSidebar} 打开线程侧边栏，然后点击侧边栏底部的时钟图标或从命令面板运行 {#action agents_sidebar::ToggleThreadHistory} 来打开线程历史。点击导入线程，选择你要导入的 agent，然后再次点击导入线程。

Zed 会通过 ACP 连接每个选定的 agent，并添加那些尚未出现在你的历史中的会话。导入的线程是已归档的条目；打开其中一个即可恢复它，并从中断处继续。

只有已配置的 External Agents 才会显示在导入对话框中。没有关联工作目录的会话将被跳过，重复导入是安全的，因为已存在于历史中的线程会被跳过。

MCP

在 Zed 中配置的 MCP 服务器 可能会通过 ACP 转发给 External Agents。External Agents 也可以读取其自身的原生 MCP 配置。

如果某个 MCP 工具未出现在 External Agent 中，请同时检查 Zed 的 MCP 服务器配置和该 agent 的原生 MCP 配置。

调试

从命令面板使用 {#action dev::OpenAcpLogs} 来检查 Zed 与 External Agent 之间的消息。

在报告 External Agents 的问题时，请附上 ACP 日志。

终端线程 - Zed

终端线程（Terminal Threads）是线程侧边栏中基于终端的线程。当你想在 Zed 中直接运行 agent 的 CLI 或 TUI 时，可以使用它。

终端线程与外部代理（External Agents）不同。外部代理通过 ACP 与 Zed 集成，以 agent 线程的形式呈现；而终端线程是在终端里运行原生命令行工具，由 Zed 将其组织为一个线程。

Zed 负责的部分

Zed 负责线程的呈现层面：

• 线程侧边栏中基于终端的线程
• 按项目对线程分组
• 终端会话与其他线程之间的切换和整理

CLI 负责的部分

终端内运行的 CLI 或 TUI 自行管理：

• 身份认证
• 模型/提供商配置
• 订阅或 API 密钥
• 工具配置
• skills 和指令文件
• MCP 配置

Zed Agent 的配置文件（profiles）、工具权限、Zed Skills 以及 Zed Agent 的 MCP 设置，不会自动应用到终端线程。

打开终端线程

在Agent Panel 中打开新建线程菜单：点击左侧的 agent 选择按钮，或面板工具栏右上角的 + 图标，然后选择 Terminal。终端线程会在面板主体中打开，就像切换到某个 agent 线程一样。

你可以打开任意多个终端线程，每个线程都会在线程侧边栏中有自己的条目。

自动运行命令

如果你在终端线程中总是运行同一个 CLI，可以设置 agent.terminal_init_command，让 Zed 在每次创建终端线程的 shell 时自动执行一条命令：

{
  "agent": {
    "terminal_init_command": "claude"
  }
}

该命令会像用户手动输入一样发送给 Shell，因此会由你配置的 Shell 进行解释——包括在 Windows 以及远程或 WSL 项目环境中——且命令执行完毕后，终端仍保持为常规交互式 Shell。此机制在创建新的 Terminal Thread 时触发，以及在重新打开项目并恢复已保存的 Terminal Thread 时也会触发。

你还可以通过设置界面中 AI 下的“Terminal Thread Init Command”字段进行配置。

Terminal Thread 标题

工具栏中的终端标题会根据当前运行的 Shell 或进程自动更新。你可以点击标题或悬停时出现的铅笔图标来自定义名称。在 Threads Sidebar 中，右键点击某个 Terminal Thread 并选择 Rename Title，或者选中该 Thread 后按下 {#kb agent::RenameSelectedThread}。

若要从 Agent Panel 编辑当前活跃 Terminal Thread 的标题，请在 keymap.json 中为 {#action agent::RenameSelectedThread} 自定义映射。该操作的默认快捷键仅作用于 Threads Sidebar。

通知

当终端在失焦状态下产生铃字符时，Zed 会以与 Agent 完成工作相同的方式通知你：显示视觉弹窗，并可选播放声音。点击通知会将终端聚焦并清除指示器。

此处同样适用 agent.notify_when_agent_waiting 和 agent.play_sound_when_agent_done 设置。

关闭 Terminal Thread

与 Agent Thread 不同，Terminal Thread 是被“关闭”而非“归档”，它们不会进入 Thread History。要关闭某个 Thread，请在 Threads Sidebar 中悬停该 Thread 并点击 × 按钮，或者选中该 Thread 后按下 {#kb agent::ArchiveSelectedThread}。

CLI/TUI 配置说明

某些 Agent CLI 和 TUI 可以发送终端信号（如铃通知或标题更新），Zed 会利用这些信号在侧边栏中显示有用的上下文信息。

Claude Code 通知

Claude Code 可以在任务完成或等待权限时通知你。要启用此功能，请在 Claude Code 的用户设置中将 preferredNotifChannel 设置为 "terminal_bell"：

{
  "preferredNotifChannel": "terminal_bell"
}

你也可以在 Claude Code 内部通过运行 /config、选择 Local Notifications 并勾选 Terminal Bell 来设置此选项。

如果在 tmux 内运行 Claude Code，除非启用了透传（passthrough），否则终端铃声通知可能无法传递到外层终端。请在 ~/.tmux.conf 中添加以下内容：

set -g allow-passthrough on

更多详情，请参见 Claude Code 文档。

Amp 通知

Amp 会自动更新终端标题，并且在你需要关注时发送通知。要在 Zed 终端线程中启用通知，请在终端环境设置中添加 AMP_FORCE_BEL=1：

{
  "terminal": {
    "env": {
      "AMP_FORCE_BEL": "1"
    }
  }
}

添加环境变量后，请重启 Amp。

OpenCode 通知

OpenCode 可以自动更新终端标题。对于 Zed 通知，请添加一个 OpenCode 插件，以便在 OpenCode 需要您关注时发出终端铃声。

在您的项目中创建 .opencode/plugins/zed-bell.js，或者创建 ~/.config/opencode/plugins/zed-bell.js 以全局使用：

export const ZedBell = async () => {
  return {
    event: async ({ event }) => {
      if (process.env.OPENCODE_CLIENT === "acp") return;

      if (event.type === "session.idle" || event.type === "permission.asked") {
        process.stdout.write("\x07");
      }
    },
  };
};

添加插件后，请重启 OpenCode。

Pi 通知

Pi 可以使用扩展在回合结束时发出通知。在您的项目中创建 .pi/extensions/zed-bell.ts，或者创建 ~/.pi/agent/extensions/zed-bell.ts 以全局使用：

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("agent_end", async () => {
    process.stdout.write("\x07");
  });
}

添加扩展后，请重启 Pi；如果扩展位于 Pi 的自动发现扩展目录中，则运行 /reload 即可。

Codex 终端标题

Codex 在工作时可以更新终端标题，Zed 利用这一点，在侧边栏为 Codex Terminal Threads 显示有用的上下文信息，比如项目、当前状态、分支、模型或任务进度。

要在 Codex 内部配置这个功能，运行 /title，然后通过选择器决定显示哪些字段以及它们的顺序。Codex 会把选择保存到 ~/.codex/config.toml 的 tui.terminal_title 中。你也可以直接编辑：

[tui]
terminal_title = ["spinner", "project-name", "run-state", "thread-title"]

凭证与远程项目

凭证来自终端会话以及在其中运行的 CLI/TUI。

在远程项目中，CLI 可能会读取远程 shell 环境和远程配置文件。在本地 Terminal Threads 中，它读取的是本地 shell 环境和本地配置文件。Zed 不会把 LLM 提供商设置中的 API key 复制到 Terminal Threads 里。

什么时候用 Terminal Threads

以下情况适合使用 Terminal Threads：

• 你想要工具原生的 CLI/TUI 体验
• 没有对应的 ACP 集成
• 你希望订阅行为由 CLI 自己管理
• 你希望 CLI 使用它自己的原生配置文件

关于 ACP 集成的 agent，参见 External Agents。