外部代理

Zed 通过代理客户端协议 (ACP) 支持基于终端的代理。

目前，Gemini CLI 作为参考实现。默认情况下也包含了Claude Code 和Codex，你也可以添加自定义的 ACP 兼容代理。

请注意，Zed 对外部代理的支持严格基于 UI；计费和法律/条款安排直接在您和代理提供商之间进行。Zed 不收取使用外部代理的费用，我们的零数据保留协议/隐私保证仅适用于 Zed 的托管模型。

Gemini CLI

Zed 提供了直接在代理面板中运行Gemini CLI 的能力。

在底层，我们在后台运行 Gemini CLI，并通过 ACP 与其通信。这意味着您运行的是真实的 Gemini CLI，具有所有优势，但您可以在编辑器中查看和交互文件。

入门

从 Zed Stable v0.201.5 开始，您应该能够直接从 Zed 使用 Gemini CLI。首先使用 cmd-?|ctrl-? 打开代理面板，然后使用右上角的 + 按钮启动一个新的 Gemini CLI 线程。

如果您想将其绑定到键盘快捷键，可以通过 zed: open keymap 命令编辑您的 keymap.json 文件来添加以下内容

[
  {
    "bindings": {
      "cmd-alt-g": ["agent::NewExternalAgentThread", { "agent": "gemini" }]
    }
  }
]

安装

首次创建 Gemini CLI 线程时，Zed 将安装 @google/gemini-cli。此安装仅对 Zed 可用，并会在您使用代理时保持最新。

默认情况下，即使您全局安装了 Gemini CLI，Zed 也会使用此托管版本。但是，您可以通过在设置中添加以下内容来将其配置为使用您 PATH 中的版本

{
  "agent_servers": {
    "gemini": {
      "ignore_system_version": false
    }
  }
}

认证

运行 Gemini CLI 后，系统会提示您选择身份验证方法。

大多数用户应点击“使用 Google 登录”。这将弹出一个浏览器窗口并直接通过 Gemini CLI 进行身份验证。在这种情况下，Zed 不会看到您的 OAuth 或访问令牌。

您还可以使用“Gemini API Key”。如果您选择此项并设置了 GEMINI_API_KEY，我们将使用该密钥。否则，Zed 将提示您输入 API 密钥，该密钥将安全地存储在您的钥匙串中，并用于从 Zed 启动 Gemini CLI。

“Vertex AI”选项适用于使用 Vertex AI 且已正确配置环境的用户。

欲了解更多信息，请参阅 Gemini CLI 文档。

使用

与 Zed 的第一方代理类似，您可以使用 Gemini CLI 执行您需要的任何操作。为了提供上下文，您可以 @-提及文件、最近的线程、符号或抓取网页。

请注意，某些第一方代理功能尚不适用于 Gemini CLI：编辑过去的邮件、从历史记录中恢复线程和检查点。我们希望在不久的将来添加这些功能。

Claude Code

与 Gemini CLI 类似，您也可以通过 Zed 的代理面板直接运行Claude Code。在底层，Zed 运行 Claude Code 并通过专用适配器通过 ACP 与其通信。

入门

使用 cmd-?|ctrl-? 打开代理面板，然后使用右上角的 + 按钮启动一个新的 Claude Code 线程。

如果您想将其绑定到键盘快捷键，可以通过 zed: open keymap 命令编辑您的 keymap.json 文件来添加以下内容

[
  {
    "bindings": {
      "cmd-alt-c": ["agent::NewExternalAgentThread", { "agent": "claude_code" }]
    }
  }
]

认证

截至版本 0.202.7（稳定版）和 0.203.2（预览版），Zed 的 Claude Code 安装的身份验证完全与 Zed 的代理分离。也就是说，通过 Zed 代理设置添加的 Anthropic API 密钥将不会被 Claude Code 用于身份验证和计费。

为了确保您使用您选择的计费方式，打开一个新的 Claude Code 线程。然后，运行 /login，并通过 API 密钥或通过 Log in with Claude Code 进行身份验证，以使用 Claude Pro/Max 订阅。

安装

首次创建 Claude Code 线程时，Zed 将安装 @zed-industries/claude-code-acp。此安装仅对 Zed 可用，并会在您使用代理时保持最新。

Zed 将始终使用此托管版本的 Claude Code 适配器，其中包含一个供应商版本的 Claude Code CLI，即使您已全局安装它也是如此。

如果您想覆盖适配器使用的可执行文件，您可以在设置中将 CLAUDE_CODE_EXECUTABLE 环境变量设置为您首选可执行文件的路径。

{
  "agent_servers": {
    "claude": {
      "env": {
        "CLAUDE_CODE_EXECUTABLE": "/path/to/alternate-claude-code-executable"
      }
    }
  }
}

使用

与 Zed 的第一方代理类似，您可以使用 Claude Code 执行您需要的任何操作。为了提供上下文，您可以 @-提及文件、最近的线程、符号或抓取网页。

除了通过 ACP 与其通信之外，Zed 还依赖于 Claude Code SDK 来支持其某些特定功能。但是，SDK 尚未公开完全支持所有这些功能所需的一切

斜杠命令：支持内置命令的一个子集，同时完全支持自定义斜杠命令。
支持子代理。
钩子目前不支持。

另请注意，某些第一方代理功能尚不适用于 Claude Code：编辑过去的邮件、从历史记录中恢复线程和检查点。我们希望在不久的将来添加这些功能。

[
  {
    "bindings": {
      "cmd-alt-c": ["agent::NewExternalAgentThread", { "agent": "codex" }]
    }
  }
]

认证

Zed 的 Codex 安装的身份验证完全与 Zed 的代理分离。也就是说，通过 Zed 代理设置添加的 OpenAI API 密钥将不会被 Codex 用于身份验证和计费。

为了确保您使用您选择的计费方式，打开一个新的 Codex 线程。首次系统会提示您使用以下三种方法之一进行身份验证

使用 ChatGPT 登录 - 允许您使用现有的付费 ChatGPT 订阅。注意：此方法目前在远程项目中不受支持
CODEX_API_KEY - 使用您在环境变量 CODEX_API_KEY 下设置的 API 密钥。
OPENAI_API_KEY - 使用您在环境变量 OPENAI_API_KEY 下设置的 API 密钥。

如果您已登录并想更改身份验证方法，请在线程中键入 /logout 并重新进行身份验证。

安装

首次创建 Codex 线程时，Zed 将安装 codex-acp。此安装仅对 Zed 可用，并会在您使用代理时保持最新。

Zed 将始终使用此托管版本的 Codex，即使您已全局安装它也是如此。

使用

与 Zed 的第一方代理类似，您可以使用 Codex 执行您需要的任何操作。为了提供上下文，您可以 @-提及文件、符号或抓取网页。

请注意，某些第一方代理功能尚不适用于 Codex：编辑过去的邮件、从历史记录中恢复线程和检查点。我们希望在不久的将来添加这些功能。

添加自定义代理

您可以通过如下更改您的设置来运行任何使用 ACP 的代理

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

如果您正在开发一个使用该协议的新代理并想对其进行调试，这也会很有用。

您还可以使用 claude 和 gemini 名称为内置集成指定自定义路径、参数或环境。

调试代理

在 Zed 中使用外部代理时，您可以从命令面板通过 dev: open acp logs 访问调试视图。这使您可以看到 Zed 和代理之间发送和接收的消息。

The debug view for ACP logs.

MCP 服务器

请注意，对于外部代理，对从 Zed 安装的 MCP 服务器的访问可能因 ACP 代理实现而异。

关于内置代理，Claude Code 和 Codex 都支持，而 Gemini CLI 尚不支持。同时，通过他们的文档了解如何向 Gemini CLI 添加 MCP 服务器支持。