Zed Setup Guide: Wiring Up a Custom Model Endpoint

Zed ships an agent panel that reads your repository, proposes edits and calls tools. Pointing it at a model that is not one of its built-in providers is a configuration-file job rather than a form-filling job, and that is the part people are unprepared for.

Whatever the panel looks like in your build, the integration needs the same three facts every OpenAI-compatible client needs: a base URL, an API key, and a model identifier the endpoint recognises. Everything after that is Zed deciding how to behave around those three, and most of the failures are in that second layer rather than the credentials.

Zed keeps model configuration in JSON

Zed is configured through a JSON settings file rather than a preferences dialog. Open the command palette and look for the settings entry; it opens the file as a normal editor buffer. Most builds have a user-level file and a project-level override that can be committed alongside the code.

Inside that file, model providers live under a language-model section, with one named block per provider. The block for a generic OpenAI-compatible endpoint takes an API URL and a list of the models you are declaring available. Exact key names shift between releases, so lean on the schema completion Zed offers as you type rather than pasting a block from a post that may be a year old — including this one.

The upside of JSON configuration is that it is reviewable and version-controllable. A project-level settings file that pins the provider and model for everyone working in the repository eliminates a whole category of "it works on my machine" reports, and makes a model change a pull request rather than a Slack message.

The three fields that actually matter

The base URL should point at the root of the OpenAI-compatible surface, ending at the version segment, with no path for a specific operation appended. If your endpoint is documented as https://api.example.com/v1, that whole string is the value; adding /chat/completions yourself produces a 404 that looks like an authentication problem but is not. Our piece on what OpenAI compatibility actually covers goes through the rest of that surface.

The API key is passed as a bearer token. Zed can read it from an environment variable in most configurations, which is the option to prefer — a key pasted into a settings file that is committed to the repository is a key you will be rotating.

The model identifier is passed through to the endpoint verbatim. There is no fuzzy matching and no fallback: a name the provider does not publish comes back as an error, not as a substitute model. Ask the endpoint what it serves rather than guessing, usually through its model list route.

You have to describe the model yourself

For its built-in providers, Zed ships metadata about each model. For an endpoint it has never seen, it knows nothing, so the provider block asks you to declare each model along with at least its context window and often a maximum output size.

These are not cosmetic. The declared context window is what Zed uses to decide when to trim or summarise a conversation. Set it well below the real window and long sessions get compacted for no reason, throwing away detail the agent needed; set it above the real window and requests start failing partway through a task. If you are unsure what the real number is, check the provider page rather than assuming, and read how context windows are actually consumed before picking a value.

The maximum output setting caps a single response. Too low and a large file write stops halfway, which surfaces as a corrupted edit rather than a clean error — one of the more confusing failure modes because nothing reports a problem.

Tools, and why the agent might only talk

An agent panel is only useful if the model can call tools. If your endpoint or your chosen model does not negotiate tool calls, Zed degrades into something that describes the change it would make instead of making it.

Some provider blocks expose a capability flag for tool support, precisely because it cannot be inferred for an unknown model. If the agent is narrating rather than editing, that flag and the model choice are the two things to check, in that order. The mechanics are covered in the tool calling walkthrough.

Streaming is the other capability worth confirming early. If tokens arrive in one lump at the end rather than progressively, something between you and the model is buffering the response, which makes the editor feel broken even though the output is correct.

Verifying the connection before you trust it

Do the smallest possible test first. Open the agent panel, select your provider and model explicitly rather than leaving whatever default is selected, and ask for a one-sentence answer. That confirms the base URL, key and model name together.

Then ask it to read a specific file in the repository and quote a line back. That confirms tool calling and file access, which is a different code path from plain chat.

Only then give it a real task, and give it one on a branch. Zed edits files directly, and version control is the only undo that survives a multi-file agent session.

What commonly goes wrong

A 401 usually means the key belongs to a different provider or picked up whitespace from the paste. A 404 on the endpoint is nearly always a duplicated or missing version segment in the base URL; a 404 mentioning the model is a name the provider does not serve. If everything works in a terminal but not in Zed, the environment variable holding your key is probably not visible to the editor process, which matters when Zed is launched from a desktop launcher rather than a shell.

If the model responds but the agent never edits anything, treat it as a tool-calling problem, not a prompt problem. If you are configuring several tools against the same endpoint, keeping one key across your tooling saves a surprising amount of rotation work.

The takeaway

Base URL, key, model name, then declare the context window honestly. Put the provider block in the project settings so the whole team gets the same configuration, keep the key in the environment, and confirm a file read before you trust a refactor. The same three facts port to every other editor, which is the real reason to learn them once — the Cline configuration asks for exactly the same things in a different shape.