# Zed Editor Setup

[Zed](https://zed.dev) is a high-performance modern code editor written in Rust that, since Q1 2026, has natively supported the [Agent Client Protocol (ACP)](https://github.com/agentclientprotocol/agent-client-protocol) — an open standard that decouples IDE-to-AI-agent communication, much like LSP did for language servers. Zed integrates Claude Code over ACP, exposing an agent panel for orchestrating multi-step coding tasks. This guide shows how to configure QCode.cc as the upstream for Claude Code inside Zed, and how to add QCode directly as an Anthropic-compatible / OpenAI-compatible provider in Zed's `settings.json`.

QCode uses a single API Key throughout (starting with `cr_`). The same key supports the Anthropic, OpenAI Chat, OpenAI Responses, Gemini, and image protocols, and maps to four ingress domains — `api` / `asia` / `us` / `eu` (mainland-China users should prefer `asia.qcode.cc`).

## Why Use Zed

- **Native ACP integration**: open Claude Code sessions inside the agent panel and watch agent reasoning plus tool calls live in the editor
- **1M context**: BYOK mode supports the full 1M-token context window of Opus 5 / 4.8 / 4.7
- **Rust performance**: blazingly fast cold start and an order of magnitude lower memory footprint than VS Code / Electron-based editors
- **Multi-pane layout**: editor + terminal + agent panel side-by-side for a compact workflow
- **Two integration paths**: run via the Claude Code CLI (full tool surface), or add QCode as a built-in provider in `settings.json`

## Comparing the Two Integration Paths

Zed offers two complementary paths to reach QCode — pick based on your needs:

| Path | Description | Best for |
|------|-------------|----------|
| **A. ACP / Claude Code** (recommended) | The agent panel spawns the `claude` CLI subprocess, reusing the CLI's environment variables | Wanting full hooks / skills / MCP, sharing config with the terminal workflow |
| **B. settings.json provider** | Fill in the base URL + key directly in Zed settings, using Zed's built-in HTTP client | Not wanting to install the CLI; pure in-IDE assistant / inline completion |

The "Configuration Steps" section below covers Path A; "Configuring a Provider in settings.json" covers Path B.

## Prerequisites

- [Zed](https://zed.dev/download) installed (macOS / Linux)
- [Claude Code CLI](/docs/getting-started/installation) installed (Zed's ACP integration uses the CLI as the backend; skip this if you only use Path B)
- A QCode.cc API Key (starts with `cr_`), available from the [dashboard](https://qcode.cc/dashboard)
- Claude Code CLI already configured with QCode environment variables (per the [Quick Start](/docs/getting-started/quick-start))

## Configuration Steps (Path A: ACP / Claude Code)

### Step 1: Verify the Claude Code CLI Works in Your Terminal

Zed launches ACP by spawning a `claude` process, so verify the CLI works in a terminal first:

```bash
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_xxxxxxxx"
claude --version   # should print a version number (trust this machine + official Releases)
echo "ping" | claude   # simple echo test
```

> `ANTHROPIC_BASE_URL` must **not** have a trailing slash; the Anthropic SDK appends `/v1/messages` itself. Persist these two environment variables in your shell config (`~/.zshrc` / `~/.bashrc`) so Zed inherits them at startup.

### Step 2: Open Zed's Agent Panel

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

The first time you open it, Zed asks you to choose an agent provider — pick **Claude Code** (do not pick BYOK Anthropic API; that path bypasses the CLI and requires you to fill in a base URL separately in Zed settings — see Path B).

### Step 3: Verify the Agent Session

Type into the agent panel input: "List the exported symbols in the current file." Zed passes the currently open file as context to Claude Code, and the agent invokes the `read` / `grep` tools to parse and respond.

If the agent panel reports that it cannot find the `claude` command, add `agent.path` in Zed settings (`Cmd+,`) pointing to the full path of the CLI binary:

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

> Zed's agent / assistant settings evolve quickly between releases; for exact key names, defer to the [Zed official docs](https://zed.dev/docs/ai/overview).

## Configuring a Provider in settings.json (Path B)

If you'd rather not install the CLI, you can add QCode as a built-in Zed provider directly in `settings.json` (open with `Cmd+,`). QCode supports both Anthropic-compatible and OpenAI-compatible protocols, using the **same `cr_` key** for both.

### Anthropic-Compatible Provider

Point Zed's built-in Anthropic provider base at QCode's Anthropic endpoint:

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

Supply the key via an environment variable (inherited by Zed at startup):

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

> Depending on the Zed version, this key may be `language_models.anthropic.api_url` or `assistant.providers.anthropic.api_url`; defer to the official docs. The base URL ends at `/api` — the SDK appends `/v1/messages`.

### OpenAI-Compatible Provider

Zed also supports an OpenAI-compatible provider, which can reach QCode's GPT-family models. Point the base at QCode's OpenAI Chat endpoint:

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

The key also comes from an environment variable:

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

> The OpenAI Chat base is `https://api.qcode.cc/openai/v1` (the SDK then appends `/chat/completions`). No trailing slash. The field names in `available_models` (`name` / `max_tokens`, etc.) should follow the Zed official docs.

## Model Selection

The same QCode key exposes models from multiple vendors. Switch as needed from the model dropdown in the agent panel or assistant:

> **Which leg**: `claude-*` only works on the Anthropic provider (`https://api.qcode.cc/api`); `gpt-*` only works on the OpenAI provider (`https://api.qcode.cc/openai/v1`). Mixing them returns `model_not_available_on_endpoint`.

| Model | Input / Output (per 1M tokens) | Context | Use for |
|-------|--------------------------------|---------|---------|
| `claude-opus-5` | $5 / $25 | 1M | Flagship — complex reasoning, large refactors |
| `claude-opus-4-7` | same tier | 1M | Flagship alternative |
| `claude-sonnet-5` | $2 / $10 | 1M | Daily coding workhorse, great value |
| `claude-haiku-4-5` | $1 / $5 | 200K | Fast completion, lightweight tasks |
| `gpt-5.5` | $5 / $30 | 1M | GPT flagship |
| `gpt-5.4` | $2.5 / $15 | 1M | GPT general purpose |
| `gpt-5.6-mini` | — | 272K | GPT lightweight |
| `gpt-5.6-terra` | — | 272K | Code-specialized |

> The table above is the current recommendation. 4.x IDs such as `claude-sonnet-4-6`, `claude-opus-4-8`, and `claude-opus-4-7` remain on sale; the live list is [qcode.cc/models](https://qcode.cc/models).

- On Path A (Claude Code), the model is determined by Claude Code's own configuration (switch with `/model` or set `ANTHROPIC_MODEL`).
- On Path B with the Anthropic provider, use `claude-*` model IDs; with the OpenAI provider, use `gpt-*` model IDs.
- The Gemini and image (`gpt-image-2`) protocols aren't necessarily exposed natively in Zed's assistant; call them directly from the CLI / scripts — see [Endpoints and API Paths](/docs/getting-started/endpoints-and-api-paths) and [gpt-image-2 Image Generation](/docs/usage/image-2).

## Usage Examples

### Agent Panel: Cross-File Tasks

The agent panel shines on multi-step, cross-file tasks. For example:

> "Convert all synchronous IO under `utils/` to async and update the callers."

The agent will `grep` to locate, `read` to inspect, and `edit` to modify, showing diffs step by step in the editor so you can accept / reject each one.

### Feeding Screenshots to the Agent (Vision Input)

Claude Opus 5 / Sonnet 5 and GPT-5.x are all vision-capable. You can hand UI mockups, error screenshots, or architecture diagrams to the agent as **input**:

- Paste an image (`Ctrl+V`) or drag-drop it into the agent panel input
- Or reference a local image file path in your prompt

Typical use cases: build UI from a mockup, debug from an error screenshot, read architecture diagrams / charts.

> Note: this is about **feeding** images to the model (vision input), not **generating** images. To generate images use `gpt-image-2` — see [gpt-image-2 Image Generation](/docs/usage/image-2).

### Dynamic Workflows (Background Sub-Agent Orchestration)

Claude Code supports Dynamic Workflows: orchestrate tens to hundreds of background sub-agents, ideal for codebase-wide review, migration, and research tasks. Trigger it by including the keyword `ultracode` in your prompt or simply asking to "run a workflow"; view active runs with the `/workflows` command. Sub-agents keep running in the background while you continue other work. It runs on whatever model Claude Code is configured with — so it works when Claude Code points at QCode. Further reading: [Subagents](/docs/advanced/subagents).

### Headless / Automation Output Formats

When calling Claude Code in CI / scripts, use `claude -p` with `--output-format`:

```bash
# JSON: one structured object with result / total_cost_usd / usage / session_id
claude -p "Summarize this change" --output-format json | jq .result

# stream-json: newline-delimited JSON event stream, good for real-time pipelines
claude -p "Refactor this module" --output-format stream-json

# text: plain text (default)
claude -p "Explain this code" --output-format text
```

More usage in [Automation & CI/CD](/docs/advanced/headless).

## Fallback Endpoints

If the primary endpoint is unreachable, switch `ANTHROPIC_BASE_URL` (or the `api_url` in settings.json):

| Endpoint | Anthropic Base URL |
|----------|--------------------|
| Global | `https://api.qcode.cc/api` |
| North America | `https://us.qcode.cc/api` |
| Europe | `https://eu.qcode.cc/api` |
| Asia (preferred for CN users) | `https://asia.qcode.cc/api` |

For the OpenAI-compatible path, swap the domain the same way — e.g., the Asia OpenAI Chat base is `https://asia.qcode.cc/openai/v1`. For the full endpoint reference, see [Endpoints and API Paths](/docs/getting-started/endpoints-and-api-paths).

## Shared Quota

The Claude Code agent inside Zed shares the same QCode API Key and quota with the CLI / Claude Desktop / Codex CLI — there is no double-billing. Path A and Path B also share the same key's quota. See [Billing](/docs/reference/billing) for details.

## Limitations and Notes

- **Zed's BYOK Anthropic direct mode** uses Zed's built-in Anthropic provider and **does not go through the Claude Code CLI**. It requires you to manually set `api_url` in Zed settings to point at QCode (Path B). The ACP / Claude Code mode covered here (Path A) is preferred — it preserves the full CLI tool surface (hooks, skills, MCP).
- **The base URL must not have a trailing slash.** A self-check request hitting a base path returns `401`, which is expected (the path is correct, it just lacks auth).
- The ACP integration is in Public Beta (since 2026-04); a few APIs may still change. If you observe behavioral differences, the [Zed official documentation](https://zed.dev/docs/ai/models) is authoritative.
- Linux sandbox users: if Zed is installed via Flatpak, spawning the `claude` subprocess may be blocked by the sandbox. We recommend installing the .deb / AppImage / Homebrew build directly.
- The Gemini CLI is retired (EOL 2026-06-18 for Pro/free; enterprise paid keys unaffected); its successor is the Google Antigravity CLI. **Note that Antigravity CLI only accepts a Gemini-compatible endpoint** (via `GOOGLE_GEMINI_BASE_URL`), not an OpenAI-compatible one — see [Antigravity CLI](/docs/ide/antigravity).

## FAQ

### Agent panel reports "Failed to start agent"

- Does `claude` start correctly in your terminal? Rule out CLI-side configuration issues first.
- Did Zed inherit the `ANTHROPIC_*` environment variables? On macOS, launching Zed via `open -a Zed` from the terminal guarantees inheritance.
- Does the `agent.path` in your settings point to a valid path? Verify with `which claude`.

### settings.json provider returns 401 / auth failure

- Confirm the relevant environment variable (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`) is set and is a `cr_`-prefixed QCode key.
- Did Zed inherit that environment variable? Launch Zed from the terminal to verify.
- Did `api_url` accidentally get a trailing slash? Remove it.

### The model I want isn't in the dropdown

- The Path B OpenAI provider requires models to be listed explicitly in `available_models` before they appear in the dropdown.
- Path A's available models are determined by Claude Code; use `/model` to view and switch.

### "Invalid model" / 404

- Double-check the model ID spelling matches the table exactly (e.g., `claude-opus-5`, `gpt-5.6-mini`).
- Make sure the base URL protocol matches the model: `claude-*` uses the Anthropic endpoint, `gpt-*` uses the OpenAI endpoint.

### Difference vs. BYOK Anthropic Mode

| Dimension | ACP / Claude Code mode (Path A) | Zed BYOK provider mode (Path B) |
|-----------|---------------------------------|---------------------------------|
| Backend | spawns the `claude` CLI subprocess | Zed's built-in HTTP client |
| Tool support | full (all CLI hooks / skills / MCP) | constrained by Zed's built-in agent framework |
| Configuration location | Claude Code CLI environment variables | Zed setting `language_models.*.api_url` |
| Model range | models configured in Claude Code | the Anthropic / OpenAI models you list in settings.json |
| Recommended for | sharing config with the terminal CLI workflow | users who don't want to install the CLI and prefer pure IDE integration |

## Next Steps

- [Claude Code Tutorial](/docs/getting-started/claude-code-tutorial) — full CLI feature reference
- [Endpoints and API Paths](/docs/getting-started/endpoints-and-api-paths) — full reference for all four ingress domains
- [Subagents](/docs/advanced/subagents) — Dynamic Workflows and multi-agent orchestration
- [Automation & CI/CD](/docs/advanced/headless) — headless mode and output formats
- [gpt-image-2 Image Generation](/docs/usage/image-2) — image generation (distinct from vision input)
- [VS Code Integration](/docs/ide/vscode) — comparison with Electron-based editors
- [Billing](/docs/reference/billing) — shared quota rules

> Want live pricing and context specs for each model? Head to the [QCode pricing page](https://qcode.cc/pricing).