# Zed 编辑器接入

[Zed](https://zed.dev) 是一款用 Rust 编写的高性能现代代码编辑器，2026 Q1 起原生支持 [Agent Client Protocol (ACP)](https://github.com/agentclientprotocol/agent-client-protocol)——这是一个开放标准，让 IDE 与 AI agent 解耦通信，类似 LSP 之于语言服务器。Zed 通过 ACP 集成 Claude Code，提供 agent panel 来编排多步骤代码任务。本文介绍如何把 QCode.cc 配置为 Zed 中 Claude Code 的上游，以及如何把 QCode 作为 Anthropic 兼容 / OpenAI 兼容 provider 直接填进 Zed 的 `settings.json`。

QCode 全程使用同一把 API Key（`cr_` 开头），同一把 Key 同时支持 Anthropic、OpenAI Chat、OpenAI Responses、Gemini 与图像协议，并对应 `api` / `asia` / `us` / `eu` 四个接入域（中国大陆用户优先用 `asia.qcode.cc`）。

## 为什么用 Zed

- **原生 ACP 集成**：agent panel 内开 Claude Code 会话，在编辑器里直接看 agent 推理 + 工具调用
- **1M 上下文**：BYOK 模式支持 Opus 5 / 4.8 / 4.7 的全 1M token 上下文窗口
- **Rust 性能**：冷启动极快、内存占用比 VS Code/Electron 系列小一个量级
- **多面板布局**：编辑器 + 终端 + agent panel 三栏并列，工作流紧凑
- **两条接入路径**：既可走 Claude Code CLI（保留全部工具），也可在 `settings.json` 里把 QCode 当作内置 provider

## 两种接入方式对比

Zed 接入 QCode 有两条互补的路径，按需选择：

| 路径 | 说明 | 适合 |
|------|------|------|
| **A. ACP / Claude Code**（推荐） | agent panel spawn `claude` CLI 子进程，复用 CLI 的环境变量 | 想要完整 hooks / skills / MCP，与终端工作流共享配置 |
| **B. settings.json provider** | 在 Zed 设置里直接填 base URL + Key，走 Zed 内置 HTTP 客户端 | 不想装 CLI，纯 IDE 内的 assistant / inline 补全 |

下文「配置步骤」覆盖路径 A，「在 settings.json 中配置 provider」覆盖路径 B。

## 前置条件

- 已安装 [Zed](https://zed.dev/download)（macOS / Linux）
- 已安装 [Claude Code CLI](/docs/getting-started/installation)（Zed 的 ACP 集成走 CLI 后端；仅用路径 B 时可跳过）
- 拥有 QCode.cc API Key（`cr_` 开头），在 [控制台](https://qcode.cc/dashboard) 获取
- Claude Code CLI 已配置 QCode 环境变量（按 [快速上手](/docs/getting-started/quick-start)）

## 配置步骤（路径 A：ACP / Claude Code）

### 第 1 步：先确保 Claude Code CLI 在终端里能跑通

Zed 通过 spawn `claude` 进程把 ACP 跑起来，所以先在终端里验证：

```bash
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_xxxxxxxx"
claude --version   # 应输出版本号（以本机与官方 Releases 为准）
echo "ping" | claude   # 简单回响测试
```

> `ANTHROPIC_BASE_URL` 末尾**不要**带斜杠；Anthropic SDK 会自己拼 `/v1/messages`。在 shell 配置（`~/.zshrc` / `~/.bashrc`）里持久化这两个环境变量，确保 Zed 启动时也能继承。

### 第 2 步：打开 Zed 的 agent panel

- macOS：`Cmd + ?`
- Linux：`Ctrl + ?`

第一次打开会要求选择 agent provider，选 **Claude Code** 即可（不要选 BYOK Anthropic API，那条路径不走 CLI、需要在 Zed 设置里另填 base URL，详见路径 B）。

### 第 3 步：验证 agent 会话

在 agent panel 输入框打："列出当前文件的导出符号"。Zed 会把当前打开的文件作为上下文传给 Claude Code，agent 调用 `read` / `grep` 工具解析后答复。

如果 agent panel 提示找不到 `claude` 命令，需要在 Zed 设置（`Cmd+,`）里加 `agent.path` 指向 CLI 二进制完整路径：

```json
{
  "agent": {
    "path": "/usr/local/bin/claude"
  }
}
```

> Zed 的 agent / assistant 配置项随版本迭代较快，具体键名以 [Zed 官方文档](https://zed.dev/docs/ai/overview) 为准。

## 在 settings.json 中配置 provider（路径 B）

如果你不想装 CLI，可以把 QCode 当作 Zed 内置 provider 直接填进 `settings.json`（`Cmd+,` 打开）。QCode 同时支持 Anthropic 兼容与 OpenAI 兼容两种协议，二者用的是**同一把 `cr_` Key**。

### Anthropic 兼容 provider

把 Zed 内置 Anthropic provider 的 base 指向 QCode 的 Anthropic 端点：

```json
{
  "language_models": {
    "anthropic": {
      "api_url": "https://api.qcode.cc/api"
    }
  }
}
```

Key 通过环境变量提供（Zed 启动时继承）：

```bash
export ANTHROPIC_API_KEY="cr_xxxxxxxx"
```

> 不同 Zed 版本里这个键可能是 `language_models.anthropic.api_url` 或 `assistant.providers.anthropic.api_url`；填法以官方文档为准。base URL 填到 `/api` 即可，SDK 自动追加 `/v1/messages`。

### OpenAI 兼容 provider

Zed 也支持 OpenAI 兼容 provider，可以接入 QCode 的 GPT 系模型。把 base 指向 QCode 的 OpenAI Chat 端点：

```json
{
  "language_models": {
    "openai": {
      "api_url": "https://api.qcode.cc/openai/v1",
      "available_models": [
        { "name": "gpt-5.5",      "max_tokens": 1000000 },
        { "name": "gpt-5.4",      "max_tokens": 1000000 },
        { "name": "gpt-5.6-mini", "max_tokens": 272000 },
        { "name": "gpt-5.6-terra","max_tokens": 272000 }
      ]
    }
  }
}
```

Key 同样走环境变量：

```bash
export OPENAI_API_KEY="cr_xxxxxxxx"
```

> OpenAI Chat 协议的 base 是 `https://api.qcode.cc/openai/v1`（SDK 再拼 `/chat/completions`）。末尾不要带斜杠。`available_models` 的字段名（`name` / `max_tokens` 等）以 Zed 官方文档为准。

## 模型选择

QCode 的同一把 Key 暴露多家模型。在 agent panel 或 assistant 的模型下拉里按需切换：

> **哪条腿**：`claude-*` 只能走 Anthropic provider（`https://api.qcode.cc/api`）；`gpt-*` 只能走 OpenAI provider（`https://api.qcode.cc/openai/v1`）。填反了会收到 `model_not_available_on_endpoint`。

| 模型 | 输入 / 输出（每 1M token）| 上下文 | 适用 |
|------|------|------|------|
| `claude-opus-5` | $5 / $25 | 1M | 旗舰，复杂推理、大型重构 |
| `claude-opus-4-7` | 同档 | 1M | 旗舰备选 |
| `claude-sonnet-5` | $2 / $10 | 1M | 日常编码主力，性价比高 |
| `claude-haiku-4-5` | $1 / $5 | 200K | 快速补全、轻量任务 |
| `gpt-5.5` | $5 / $30 | 1M | GPT 旗舰 |
| `gpt-5.4` | $2.5 / $15 | 1M | GPT 通用 |
| `gpt-5.6-mini` | — | 272K | GPT 轻量 |
| `gpt-5.6-terra` | — | 272K | 代码专精 |

> 上表是当前推荐。`claude-sonnet-4-6`、`claude-opus-4-8`、`claude-opus-4-7` 等 4.x 仍在售，完整清单以 [qcode.cc/models](https://qcode.cc/models) 为准。

- 走路径 A（Claude Code）时，模型由 Claude Code 自身配置决定（`/model` 切换或 `ANTHROPIC_MODEL` 环境变量）。
- 走路径 B 且用 Anthropic provider 时，填 `claude-*` 模型 ID；用 OpenAI provider 时填 `gpt-*` 模型 ID。
- Gemini 与图像（`gpt-image-2`）协议在 Zed 的 assistant 里不一定原生暴露，可在 CLI / 脚本里直接调用，详见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) 与 [gpt-image-2 图像生成](/docs/usage/image-2)。

## 用法示例

### agent panel：跨文件任务

agent panel 适合多步、跨文件的任务。例如：

> "把 `utils/` 下所有同步 IO 改成 async，并更新调用方。"

agent 会自动 `grep` 定位、`read` 读取、`edit` 修改，并在编辑器里逐步展示 diff，你可以逐条 accept / reject。

### 把截图喂给 agent（视觉输入）

Claude Opus 5 / Sonnet 5 与 GPT-5.x 都是视觉模型。你可以把 UI 稿、报错截图、架构图作为**输入**交给 agent：

- 粘贴图片（`Ctrl+V`）或拖拽进 agent panel 输入框
- 或在 prompt 里引用本地图片文件路径

典型场景：照着设计稿生成 UI、看报错截图定位 bug、读架构图/图表。

> 注意：这里说的是把图片**喂给**模型（视觉输入），不是**生成**图片。要生成图片请用 `gpt-image-2`，见 [gpt-image-2 图像生成](/docs/usage/image-2)。

### Dynamic Workflows（后台子代理编排）

Claude Code 支持 Dynamic Workflows：编排几十到上百个后台子代理，适合全仓评审、迁移、调研类大任务。触发方式是在 prompt 里包含关键词 `ultracode` 或直接说"跑一个 workflow"；用 `/workflows` 命令查看运行中的任务。子代理在后台持续跑，你可以继续别的工作。它跑在 Claude Code 当前配置的模型上——所以当 Claude Code 指向 QCode 时同样可用。相关阅读：[子代理](/docs/advanced/subagents)。

### 无头 / 自动化输出格式

需要在 CI / 脚本里调用 Claude Code 时，用 `claude -p` 配合 `--output-format`：

```bash
# JSON：单个结构化对象，含 result / total_cost_usd / usage / session_id
claude -p "总结这次改动" --output-format json | jq .result

# stream-json：换行分隔的 JSON 事件流，适合实时管线
claude -p "重构这个模块" --output-format stream-json

# text：默认纯文本
claude -p "解释这段代码" --output-format text
```

更多用法见 [自动化与 CI/CD](/docs/advanced/headless)。

## 备用节点

主推节点访问异常时可切换 `ANTHROPIC_BASE_URL`（或 settings.json 里的 `api_url`）：

| 节点 | Anthropic Base URL |
|------|---------|
| 全球通用 | `https://api.qcode.cc/api` |
| 北美 | `https://us.qcode.cc/api` |
| 欧洲 | `https://eu.qcode.cc/api` |
| 亚洲（大陆用户首选） | `https://asia.qcode.cc/api` |

OpenAI 兼容路径把域名同理替换即可，例如亚洲节点的 OpenAI Chat base 为 `https://asia.qcode.cc/openai/v1`。完整接入点列表见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

## 共享配额

Zed 中的 Claude Code agent 与 CLI / Claude Desktop / Codex CLI 使用同一个 QCode API Key 共享配额，不会重复扣费。路径 A 与路径 B 也共享同一把 Key 的配额。详见 [计费说明](/docs/reference/billing)。

## 限制与注意

- **Zed 的 BYOK Anthropic 直连模式**走的是 Zed 内置的 Anthropic provider，**不通过 Claude Code CLI**，需要在 Zed 设置里手填 `api_url` 为 QCode 端点（路径 B）。本文聚焦的 ACP / Claude Code 模式（路径 A）更推荐——保留了 CLI 全部工具（hooks、skills、MCP）。
- **base URL 末尾不要带斜杠**。自检时直接访问 base 路径返回 `401` 是正常的（说明路径对、只是没带鉴权）。
- ACP 集成处于 Public Beta（2026-04 起），少数 API 可能仍有变动；如发现行为差异以 [Zed 官方文档](https://zed.dev/docs/ai/models) 为准。
- Linux 沙箱用户：若 Zed 通过 Flatpak 安装，spawn `claude` 子进程可能受沙箱限制。建议直接下载 .deb / AppImage / Homebrew 版本。
- Gemini CLI 已退役（Pro/免费版 EOL 2026-06-18，企业付费 Key 不受影响），其后继为 Google Antigravity CLI。**注意 Antigravity CLI 只认 Gemini 兼容端点**（环境变量 `GOOGLE_GEMINI_BASE_URL`），不是 OpenAI 兼容端点；接法见 [Antigravity CLI 接入](/docs/ide/antigravity)。

## 常见问题

### agent panel 报 "Failed to start agent"

- 终端里手动 `claude` 是否能正常启动？先排除 CLI 自身配置问题
- Zed 是否继承了 `ANTHROPIC_*` 环境变量？从终端 `open -a Zed` 启动可保证继承（macOS）
- 设置里 `agent.path` 填的路径是否存在？`which claude` 验证

### settings.json provider 报 401 / 鉴权失败

- 确认对应环境变量（`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`）已设置且为 `cr_` 开头的 QCode Key
- Zed 是否继承了该环境变量？从终端启动 Zed 验证
- `api_url` 末尾是否误带了斜杠？去掉斜杠

### 模型下拉里看不到想要的模型

- 路径 B 的 OpenAI provider 需要在 `available_models` 里显式列出模型才会出现在下拉
- 路径 A 的可选模型由 Claude Code 决定，用 `/model` 查看与切换

### 提示模型名无效 / 404

- 核对模型 ID 拼写是否与上表完全一致（如 `claude-opus-5`、`gpt-5.6-mini`）
- 确认 base URL 协议与模型匹配：`claude-*` 走 Anthropic 端点，`gpt-*` 走 OpenAI 端点

### 与 BYOK Anthropic 模式的区别

| 维度 | ACP / Claude Code 模式（路径 A）| Zed BYOK provider 模式（路径 B）|
|---|---|---|
| 后端 | spawn `claude` CLI 子进程 | Zed 内置 HTTP 客户端 |
| 工具支持 | 完整（CLI 全部 hooks / skills / MCP）| 受 Zed 内置 agent 框架限制 |
| 配置位置 | Claude Code CLI 环境变量 | Zed 设置 `language_models.*.api_url` |
| 模型范围 | Claude Code 配置的模型 | settings.json 里填的 Anthropic / OpenAI 模型 |
| 推荐场景 | 与终端 CLI 工作流共享配置 | 不想装 CLI、纯 IDE 集成 |

## 下一步

- [Claude Code 完整教程](/docs/getting-started/claude-code-tutorial) — CLI 全功能用法
- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) — 四个接入域全表
- [子代理](/docs/advanced/subagents) — Dynamic Workflows 与多代理编排
- [自动化与 CI/CD](/docs/advanced/headless) — 无头模式与输出格式
- [gpt-image-2 图像生成](/docs/usage/image-2) — 图像生成（区别于视觉输入）
- [VS Code 集成](/docs/ide/vscode) — 对比 Electron 系编辑器
- [计费说明](/docs/reference/billing) — 共享配额规则

> 想看不同模型的实时价格与上下文规格？前往 [QCode 定价页](https://qcode.cc/pricing)。