Zed Editor Setup

Connect QCode.cc to the Zed editor via the Agent Client Protocol (ACP) or settings.json, enabling the Opus 4.8 / 4.7 1M-context agent panel and OpenAI-compatible upstreams

Zed Editor Setup¶

Zed is a high-performance modern code editor written in Rust that, since Q1 2026, has natively supported the Agent Client Protocol (ACP) — 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 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:

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

Prerequisites¶

• Zed installed (macOS / Linux)
• Claude Code CLI 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
• Claude Code CLI already configured with QCode environment variables (per the 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:

export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_xxxxxxxx"
claude --version   # should print a version number (currently 2.1.187)
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:

{
  "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.

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:

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

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

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:

{
  "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:

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:

• 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 and gpt-image-2 Image Generation.

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 4.8 / Sonnet 4.6 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.

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.

Headless / Automation Output Formats¶

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

# 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.

Fallback Endpoints¶

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

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.

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 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 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. If you need to reach Antigravity from Zed via an OpenAI-compatible endpoint, see that tool's official docs.

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-4-8, 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¶

Next Steps¶

• Claude Code Tutorial — full CLI feature reference
• Endpoints and API Paths — full reference for all four ingress domains
• Subagents — Dynamic Workflows and multi-agent orchestration
• Automation & CI/CD — headless mode and output formats
• gpt-image-2 Image Generation — image generation (distinct from vision input)
• VS Code Integration — comparison with Electron-based editors
• Billing — shared quota rules

Want live pricing and context specs for each model? Head to the QCode pricing page.