Claude Code in Zed: connecting an external agent to your own key

In the Zed editor, Claude Code can be started in three ways, and each has its own authentication rules. If you want the agent to go through your gateway and spend your dollar balance, you need to know which way reads which settings. Below we go through Zed and Claude Code according to Zed's documentation as of 18 October 2026 and connect each option to a fetch_... key.

Zed command and menu names change quickly. If something on your screen looks different, check the AI section of Zed's documentation.

What Zed AI is and where the agents fit

Zed is an editor with an Agent Panel and a Threads Sidebar. According to the documentation, the AI side has three tracks:

In short, what Zed AI is: not a single button but a set of ways to attach an agent. For your task the key rule is this: Zed does not pass its keys to external agents or terminal threads, which take their settings from their own configuration.

First prepare Claude Code following the Zukko guide↗.

The common part: configuring Claude Code itself

The most reliable approach for all three options is to put the connection into Claude Code's user settings rather than into Zed. The file is ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.zukko.pro",
    "ANTHROPIC_AUTH_TOKEN": "fetch_your_key",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5"
  }
}

Three rules people most often trip over:

• the address has no /v1: Claude Code adds the path itself, and with an extra /v1 requests go to /v1/v1/messages and return 404;
• the key goes through ANTHROPIC_AUTH_TOKEN, not through a variable with API_KEY in its name;
• use model ids from the Zukko catalog; GET /v1/models returns the current list.

If Claude Code still asks you to sign in to Anthropic, find the cause using Claude Code asks to log in↗.

Option 1: a terminal thread (simplest)

A Terminal Thread runs a regular CLI right inside Zed. The documentation says that authentication, the model provider, keys and MCP belong to the CLI itself, and keys from Zed's provider settings are not copied into the terminal. For a gateway that is convenient: everything is determined by the file above or by your shell's environment variables.

1. In the Agent Panel open the new-thread menu (the agent button on the left or the + icon on the right of the panel) and choose Terminal.
2. In the terminal, run claude.
3. Ask the model what it is, and compare with the dashboard (the "Usage" section): the request should show up in your key's spend.

To make Claude Code start automatically in every new terminal thread, Zed has a setting:

{
  "agent": {
    "terminal_init_command": "claude"
  }
}

The command is sent to the shell as if you had typed it by hand. One more detail from Zed's documentation: to get a notification when Claude Code finishes a task, set "preferredNotifChannel": "terminal_bell" in Claude Code's user settings.

Option 2: Claude Agent as an external agent (ACP)

Claude Agent is installed from the ACP registry: open the registry with zed: acp registry or via the agent settings (External Agents, Add Agent, Install from Registry). After installation it appears in the new-thread menu.

What matters from the documentation: Claude Agent handles its own authentication and billing, and an Anthropic key configured for Zed Agent does not apply to it. Inside a thread, the /login command lets you choose how to sign in. The description says Claude Agent may use Claude Code's authentication and native configuration, and reads files like CLAUDE.md itself.

So for a gateway a sensible approach is: keep the connection in ~/.claude/settings.json (see above), start a thread and immediately check that the request shows up in the key's spend in the dashboard. Zed's documentation gives no guarantee that Claude Agent picks up exactly this env block. If the request did not go to the gateway, switch to option 1: a terminal thread reads the same settings for sure.

Option 3: Zed Agent with an Anthropic-compatible provider

Here Claude Code is not involved: Zed's built-in agent does the work and Zukko is connected as a provider. Zed's documentation has a section on Anthropic-compatible endpoints: the service must implement the Messages API (/v1/messages), and you set the address, model and key. Via settings.json:

{
  "language_models": {
    "anthropic_compatible": {
      "Zukko": {
        "api_url": "https://api.zukko.pro",
        "available_models": [
          {
            "name": "claude-sonnet-5-5",
            "display_name": "Claude Sonnet 5.5 (Zukko)",
            "max_tokens": 1000000,
            "max_output_tokens": 32000,
            "capabilities": {
              "tools": true,
              "images": true,
              "prompt_caching": true
            }
          }
        ]
      }
    }
  }
}

The key is entered in the provider UI or taken from an environment variable whose name Zed builds from the provider name: for "Zukko" that is ZUKKO_API_KEY. You should not put keys in settings.json, the documentation says so. The prompt_caching setting enables explicit cache breakpoints; if requests start getting rejected, you can turn it off.

If you need models such as gpt-6.1-sol or deepseek-v4.1-flash, add an openai_compatible section with api_url https://api.zukko.pro/v1. For Claude in agent work the Anthropic format is preferable: the gateway then sees cache reads and writes and bills them at their own prices, while in the OpenAI format all input is billed at the input price.

What it costs

Prices as of 18 October 2026, dollars per 1M tokens. claude-sonnet-5-5: input 0.4, output 2, cache read 0.05, cache write 0.5. For comparison, claude-opus-5-5: input 0.8, output 4.

An agent session in which 200K tokens arrived fresh, 3M were read from the cache, 150K were written to the cache, and the model produced 60K tokens:

• Anthropic format: 0.2 × 0.4 + 3 × 0.05 + 0.15 × 0.5 + 0.06 × 2 = 0.08 + 0.15 + 0.075 + 0.12 = $0.425;
• the same volume in the OpenAI format: (0.2 + 3 + 0.15) × 0.4 + 0.06 × 2 = 1.34 + 0.12 = $1.46.

Real numbers depend on your session, but the gap shows why Claude should use the Anthropic format. A detailed calculation is in How much a Claude Code agent costs↗. So the agent cannot overspend, create a separate key for the editor and set a daily limit.

If something does not work

Access from Russia goes through the gateway, with payment by SBP (the payment page adds 8.5% on top), MasterCard, or crypto. Create a key in the dashboard↗ and connect any of the options above. If you only need Zed Agent without Claude Code, see setting up the AI assistant in Zed↗.

FAQ

Which option should I choose if I specifically need Claude Code?

The terminal thread: it runs the real claude and reads your settings. An external agent over ACP is nicer in the interface, but check its behavior with your key against the spend in the dashboard.

Is Claude Code required for Zed to work with models?

No. The built-in Zed Agent works without Claude Code: it needs a provider with a key and a model (option 3).

Can I use a non-Claude model in Claude Code?

The gateway accepts any model in the Anthropic format, but Claude Code is designed around Claude models, so test how other models behave on your own tasks. For model ids without the claude- prefix, Claude Code may guess the context window wrongly; for GLM with its 128K window see the CLAUDE_CODE_MAX_CONTEXT_TOKENS variable in Claude Code's documentation.

Is Zed paid?

Check Zed's terms and plans on its site: we do not quote them, since they change. Paying for gateway tokens does not depend on that.