# Подключение редактора Zed

[Zed](https://zed.dev) — это высокопроизводительный современный редактор кода, написанный на Rust. С Q1 2026 он нативно поддерживает [Agent Client Protocol (ACP)](https://github.com/agentclientprotocol/agent-client-protocol) — открытый стандарт, который разделяет коммуникацию между IDE и AI-агентом, аналогично тому, как LSP работает с языковыми серверами. Через ACP Zed интегрирует Claude Code и предоставляет agent panel для оркестрации многошаговых задач по работе с кодом. В этом руководстве описано, как настроить QCode.cc в качестве вышестоящего шлюза для Claude Code в Zed, а также как добавить QCode напрямую как Anthropic-совместимый / OpenAI-совместимый provider в `settings.json` редактора Zed.

QCode на всём пути использует один API Key (начинается с `cr_`). Один и тот же ключ поддерживает протоколы Anthropic, OpenAI Chat, OpenAI Responses, Gemini и изображений и сопоставлен с четырьмя входными доменами — `api` / `asia` / `us` / `eu` (пользователям материкового Китая следует предпочитать `asia.qcode.cc`).

## Зачем использовать Zed

- **Нативная интеграция ACP**: открывайте сессии Claude Code в agent panel и наблюдайте за рассуждениями агента и вызовами инструментов прямо в редакторе
- **Контекст 1M**: режим BYOK поддерживает полное окно контекста 1M токенов для Opus 5 / 4.8 / 4.7
- **Производительность Rust**: чрезвычайно быстрый холодный старт; потребление памяти на порядок ниже, чем у редакторов на VS Code/Electron
- **Многопанельная компоновка**: редактор + терминал + agent panel в три колонки рядом — компактный рабочий процесс
- **Два пути подключения**: через Claude Code CLI (полный набор инструментов) либо как встроенный provider в `settings.json`

## Сравнение двух способов подключения

В Zed есть два взаимодополняющих пути к QCode — выбирайте по своим задачам:

| Путь | Описание | Подходит для |
|------|----------|--------------|
| **A. ACP / Claude Code** (рекомендуется) | Agent panel спавнит дочерний процесс CLI `claude`, повторно используя переменные окружения CLI | Полные hooks / skills / MCP, совместное использование конфигурации с терминальным процессом |
| **B. provider в settings.json** | Указать base URL + ключ прямо в настройках Zed, используя встроенный HTTP-клиент Zed | Не хочется ставить CLI; чистый assistant / inline-автодополнение внутри IDE |

Раздел «Шаги настройки» ниже описывает путь A; «Настройка provider в settings.json» — путь B.

## Предварительные требования

- Установлен [Zed](https://zed.dev/download) (macOS / Linux)
- Установлен [Claude Code CLI](/docs/getting-started/installation) (интеграция ACP в Zed использует CLI как бэкенд; можно пропустить, если используете только путь B)
- Имеется API Key QCode.cc (начинается с `cr_`), полученный в [личном кабинете](https://qcode.cc/dashboard)
- Claude Code CLI настроен с переменными окружения QCode (см. [Быстрый старт](/docs/getting-started/quick-start))

## Шаги настройки (путь A: ACP / Claude Code)

### Шаг 1. Сначала убедитесь, что Claude Code CLI работает в терминале

Zed запускает ACP, спавня процесс `claude`, поэтому сначала проверьте работу в терминале:

```bash
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_xxxxxxxx"
claude --version   # должен вывести номер версии (смотрите эту машину и официальные Releases)
echo "ping" | claude   # простой echo-тест
```

> В конце `ANTHROPIC_BASE_URL` **не должно быть** слеша; Anthropic SDK сам добавляет `/v1/messages`. Сохраните эти две переменные окружения в конфиге shell (`~/.zshrc` / `~/.bashrc`), чтобы Zed мог их унаследовать при запуске.

### Шаг 2. Откройте agent panel в Zed

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

При первом открытии будет предложено выбрать agent provider — выберите **Claude Code** (не выбирайте BYOK Anthropic API: этот путь не использует CLI и требует отдельной настройки base URL в параметрах Zed — см. путь B).

### Шаг 3. Проверьте сессию агента

В поле ввода agent panel введите: «Перечислить экспортируемые символы текущего файла». Zed передаст текущий открытый файл в качестве контекста Claude Code, агент вызовет инструменты `read` / `grep` для анализа и даст ответ.

Если agent panel сообщает, что не может найти команду `claude`, добавьте в настройках Zed (`Cmd+,`) параметр `agent.path`, указывающий на полный путь к бинарнику CLI:

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

> Настройки agent / assistant в Zed быстро меняются от релиза к релизу; точные имена ключей сверяйте с [официальной документацией Zed](https://zed.dev/docs/ai/overview).

## Настройка provider в settings.json (путь B)

Если вы не хотите устанавливать CLI, можно добавить QCode как встроенный provider в Zed прямо в `settings.json` (открывается через `Cmd+,`). QCode поддерживает и Anthropic-совместимый, и OpenAI-совместимый протоколы, используя для обоих **один и тот же ключ `cr_`**.

### Anthropic-совместимый provider

Направьте base встроенного в Zed Anthropic provider на Anthropic-эндпоинт QCode:

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

Ключ передаётся через переменную окружения (наследуется 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, через который можно обращаться к моделям семейства GPT в QCode. Направьте base на OpenAI Chat-эндпоинт QCode:

```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 }
      ]
    }
  }
}
```

Ключ также берётся из переменной окружения:

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

> Base протокола OpenAI Chat — `https://api.qcode.cc/openai/v1` (SDK затем добавляет `/chat/completions`). Без слеша в конце. Имена полей в `available_models` (`name` / `max_tokens` и т. д.) сверяйте с официальной документацией Zed.

## Выбор модели

Один и тот же ключ QCode открывает доступ к моделям нескольких вендоров. Переключайтесь по необходимости из выпадающего списка моделей в 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 токенов) | Контекст | Применение |
|--------|------------------------------|----------|------------|
| `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 | Специализация на коде |

> Таблица выше — текущая рекомендация. Идентификаторы 4.x (`claude-sonnet-4-6`, `claude-opus-4-8`, `claude-opus-4-7`) по-прежнему в продаже; актуальный список — [qcode.cc/models](https://qcode.cc/models).

- На пути A (Claude Code) модель определяется собственной конфигурацией Claude Code (переключение через `/model` или переменная `ANTHROPIC_MODEL`).
- На пути B с Anthropic provider используйте ID моделей `claude-*`; с OpenAI provider — ID моделей `gpt-*`.
- Протоколы Gemini и изображений (`gpt-image-2`) не обязательно доступны нативно в assistant Zed; вызывайте их напрямую из CLI / скриптов — см. [Эндпоинты и форматы API](/docs/getting-started/endpoints-and-api-paths) и [Генерация изображений gpt-image-2](/docs/usage/image-2).

## Примеры использования

### Agent panel: задачи между файлами

Agent panel особенно хорош для многошаговых задач, охватывающих несколько файлов. Например:

> «Перевести весь синхронный IO в `utils/` на async и обновить вызывающий код.»

Агент сам выполнит `grep` для поиска, `read` для изучения и `edit` для изменения, пошагово показывая diff в редакторе, чтобы вы могли принимать / отклонять каждое изменение.

### Передача скриншотов агенту (визуальный ввод)

Claude Opus 5 / Sonnet 5 и GPT-5.x — все они поддерживают зрение. Вы можете передавать агенту макеты UI, скриншоты ошибок или архитектурные диаграммы как **ввод**:

- Вставьте изображение (`Ctrl+V`) или перетащите его в поле ввода agent panel
- Либо укажите путь к локальному файлу изображения в промпте

Типичные сценарии: собрать UI по макету, отладить по скриншоту ошибки, прочитать архитектурные диаграммы / графики.

> Примечание: речь о **передаче** изображений модели (визуальный ввод), а не о **генерации** изображений. Для генерации используйте `gpt-image-2` — см. [Генерация изображений gpt-image-2](/docs/usage/image-2).

### Dynamic Workflows (оркестрация фоновых субагентов)

Claude Code поддерживает Dynamic Workflows: оркестрацию от десятков до сотен фоновых субагентов, что идеально для задач масштаба всей кодовой базы — ревью, миграции, исследования. Запуск: включите ключевое слово `ultracode` в промпт или просто попросите «запустить workflow»; просматривайте активные запуски командой `/workflows`. Субагенты продолжают работать в фоне, пока вы занимаетесь другими делами. Workflow выполняется на той модели, на которую настроен Claude Code — поэтому он работает, когда Claude Code указывает на QCode. Дополнительно: [Субагенты](/docs/advanced/subagents).

### Форматы вывода для headless / автоматизации

При вызове Claude Code в CI / скриптах используйте `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` (или `api_url` в settings.json):

| Эндпоинт | 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).

## Общая квота

Агент Claude Code в Zed использует тот же API Key QCode, что и CLI / Claude Desktop / Codex CLI, и расходует общую квоту — двойного списания не происходит. Путь A и путь B также делят квоту одного ключа. Подробнее см. в разделе [Биллинг](/docs/reference/billing).

## Ограничения и замечания

- **Режим BYOK Anthropic в Zed** использует встроенный в Zed Anthropic provider и **не идёт через Claude Code CLI**; для него потребуется вручную указать `api_url` со значением эндпоинта QCode в настройках Zed (путь 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, спавн дочернего процесса `claude` может быть ограничен песочницей. Рекомендуется использовать пакеты .deb / AppImage / Homebrew напрямую.
- Gemini CLI выведен из эксплуатации (EOL 2026-06-18 для Pro/бесплатных; корпоративные платные ключи не затронуты); его преемник — 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`

### provider в settings.json возвращает 401 / ошибку авторизации

- Убедитесь, что соответствующая переменная окружения (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`) задана и является ключом QCode с префиксом `cr_`
- Унаследовал ли Zed эту переменную окружения? Запустите Zed из терминала для проверки
- Не появился ли случайно слеш в конце `api_url`? Удалите его

### Нужной модели нет в выпадающем списке

- OpenAI provider пути B требует, чтобы модели были явно перечислены в `available_models`, прежде чем они появятся в списке
- Доступные модели пути A определяет Claude Code; используйте `/model` для просмотра и переключения

### «Invalid model» / 404

- Перепроверьте написание ID модели — оно должно точно совпадать с таблицей (например, `claude-opus-5`, `gpt-5.6-mini`)
- Убедитесь, что протокол base URL соответствует модели: `claude-*` использует Anthropic-эндпоинт, `gpt-*` — OpenAI-эндпоинт

### Чем отличается от режима BYOK Anthropic

| Параметр | Режим ACP / Claude Code (путь A) | Режим BYOK provider в Zed (путь B) |
|---|---|---|
| Бэкенд | Спавн дочернего процесса CLI `claude` | Встроенный HTTP-клиент Zed |
| Поддержка инструментов | Полная (все hooks / skills / MCP из CLI) | Ограничена встроенным фреймворком агента Zed |
| Расположение конфигурации | Переменные окружения Claude Code CLI | Параметр Zed `language_models.*.api_url` |
| Набор моделей | Модели, настроенные в Claude Code | Модели Anthropic / OpenAI, перечисленные в settings.json |
| Рекомендуемый сценарий | Совместное использование конфигурации с терминальным 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) — headless-режим и форматы вывода
- [Генерация изображений gpt-image-2](/docs/usage/image-2) — генерация изображений (отлична от визуального ввода)
- [Интеграция с VS Code](/docs/ide/vscode) — сравнение с редакторами на базе Electron
- [Биллинг](/docs/reference/billing) — правила общей квоты

> Хотите узнать актуальные цены и параметры контекста для каждой модели? Загляните на [страницу тарифов QCode](https://qcode.cc/pricing).