Add Router One models to the Zed Agent with a custom LLM provider

Find the right settings surface in Zed 1.21

Zed 1.21 has two settings surfaces. agent: open settings (the agent::OpenSettings action, also in the Agent Panel's top-right menu) opens the graphical Settings Editor on its AI page, where LLM Providers → Add Provider asks for a provider name, API URL, model ID and context window. That form is enough for a single model. For several models, capability flags and background-feature models, edit the JSON instead: zed: open settings file (zed::OpenSettingsFile) opens settings.json, which lives at ~/.config/zed/settings.json on macOS and Linux unless XDG_CONFIG_HOME points elsewhere. zed: open settings, the command older guides mention, now opens the graphical editor rather than the file. Before you start, create a Router One key for Zed with a maxSpend cap: agent threads send one request per model turn, and the background features add requests of their own.

Configure Zed to use the Router One base URL

Add an openai_compatible entry under language_models. router-one is the provider ID: it labels the models in the picker and names the environment variable for the key. api_url is the /v1 base URL, because Zed appends /chat/completions itself. Each available_models entry is one model in the picker. name is the exact catalog ID, sent as the model field; display_name is only the label; max_tokens is the model's context window as an integer. The model page on /models shows the window rounded (1.05M, 200K), so write it as a whole number rounded down (1000000, 200000); Zed also uses it to decide when to compact a thread, by default at 90% of the window. Zed's capability defaults for a custom model, tools on, images off, chat_completions on and max_tokens_parameter off, fit most text work, so the example leaves them alone; the next sections cover when to change them. reasoning_effort (none, minimal, low, medium, high, xhigh or max) turns on thinking for that model in the Agent Panel and is sent as reasoning_effort. Router One does not turn it into a thinking setting for Claude IDs, except on Claude Opus 5.5, where it maps the value to output_config.effort (none and minimal become low); other models may ignore it or reject the request with 400. Leave max_output_tokens out unless you choose your own cap, and never put the key in settings.json:

{
  "language_models": {
    "openai_compatible": {
      "router-one": {
        "api_url": "https://api.router.one/v1",
        "available_models": [
          {
            "name": "anthropic/claude-sonnet-5",
            "display_name": "Claude Sonnet 5 · Router One",
            "max_tokens": 1000000
          },
          {
            "name": "openai/gpt-5.5",
            "display_name": "GPT-5.5 · Router One",
            "max_tokens": 1000000,
            "reasoning_effort": "medium"
          }
        ]
      }
    }
  }
}

Give Zed the key: keychain or ROUTER_ONE_API_KEY

Zed keeps provider keys out of settings.json. Paste the key on the Settings → AI → LLM Providers page, next to the router-one provider, and Zed stores it in the system keychain. Alternatively, set an environment variable in the environment Zed starts from: its name is the provider ID in upper snake case followed by _API_KEY, so router-one reads ROUTER_ONE_API_KEY. A non-empty environment variable takes precedence over the keychain value, which is the usual reason a newly pasted key seems to have no effect; unset the variable and restart Zed to stop using it. For SSH, dev container and other remote projects, Zed reads keys from the local keychain and from the local Zed process's environment, not from the remote machine. Either way the key sits on your computer, so a dedicated key with a maxSpend cap limits what a leaked key can cost.

Choose the agent's default model and the background models

agent.default_model sets the model a new Zed Agent thread starts with. Zed's background features can each use their own model: commit_message_model writes Git commit messages, thread_summary_model summarizes threads, inline_assistant_model runs the Inline Assistant, subagent_model runs subagents and compaction_model summarizes long threads. The openai_compatible provider declares no fast model of its own, so name these explicitly if you want them on a cheaper ID, each as a provider and model pair; every model you name must also be listed in available_models. Zed's docs ask for a compaction model whose context window is at least as large as the thread's model, so a thread on a 1M-window model needs a 1M-window compaction model such as deepseek-v4-flash, not anthropic/claude-haiku-4.5 with its 200K window. Commit messages and thread summaries have no such constraint. Automatic compaction runs at 90% of the window by default; agent.auto_compact.threshold changes that, and /compact in the message editor compacts a thread by hand.

{
  "agent": {
    "default_model": { "provider": "router-one", "model": "anthropic/claude-sonnet-5" },
    "commit_message_model": { "provider": "router-one", "model": "anthropic/claude-haiku-4.5" },
    "thread_summary_model": { "provider": "router-one", "model": "anthropic/claude-haiku-4.5" },
    "compaction_model": { "provider": "router-one", "model": "deepseek-v4-flash" }
  }
}

What each capability flag changes on the gateway

The capability flags decide what Zed puts into each request, so they are where most Router One problems with Zed start. To change one, add a capabilities object to that model's entry in available_models. Copy the object whole from the OpenAI-compatible example in Zed's docs rather than writing only the flag you want: most of its flags have no default inside the object, so a partial one does not load. Then change the flags below; the others in Zed's example can stay as they are.

Optional: Claude and DeepSeek over /v1/messages

Zed also has an anthropic_compatible provider for services that implement Anthropic's Messages API, and Router One serves the currently listed Claude-family IDs and DeepSeek IDs natively on /v1/messages. Its api_url is the host root, https://api.router.one, because Zed appends /v1/messages itself and sends the key in the X-Api-Key header along with Anthropic-Version 2023-06-01. An api_url ending in /v1 produces /v1/v1/messages, which Router One answers with 404 and a hint to remove the trailing /v1. Give this provider its own ID, such as router-one-messages, so its key variable becomes ROUTER_ONE_MESSAGES_API_KEY. The ID must differ from your openai_compatible entry: when the same name is configured under both, Zed keeps the OpenAI-compatible entry and logs the Anthropic one as shadowed. Its capabilities default to tools true and images false; to set images to true for Claude IDs, whose model pages list image input, write the object with all three of its flags, as in the example. The OpenAI-compatible provider above already reaches the same models, so add this one only if you want the native Messages API for them, and check that the model page lists POST /v1/messages before adding an ID.

{
  "language_models": {
    "anthropic_compatible": {
      "router-one-messages": {
        "api_url": "https://api.router.one",
        "available_models": [
          {
            "name": "anthropic/claude-sonnet-5",
            "display_name": "Claude Sonnet 5 · Messages",
            "max_tokens": 1000000,
            "capabilities": { "tools": true, "images": true, "prompt_caching": false }
          }
        ]
      }
    }
  }
}

What this provider does not configure: External Agents

The LLM providers you add serve the Zed Agent, the Inline Assistant, commit messages and thread summaries. External Agents, which Zed runs over the Agent Client Protocol, own their authentication and billing: Zed's docs state that an Anthropic API key configured for the Zed Agent does not configure Claude Agent, and an OpenAI API key does not configure Codex. Those agents keep their own login flow or configuration, and how they pick up a custom endpoint depends on the agent; the Claude Code and Codex guides cover the standalone tools' own settings. In Dashboard → Logs, the Zed Agent's turns appear under the key you gave Zed, with each request's model, tokens, cost, status, total time and, for a streamed request that produced output, time to first token (TTFT).

Which model ID should Zed send?

Copy the exact model ID from /models, preserving case, hyphens, and version suffixes; do not substitute a display name. Open its detail page and match the supported API endpoints, context window, and capabilities such as tool calling to the provider and features selected in Zed. A catalog listing does not mean the client can use every feature of that model. Give each client or application a dedicated API key with a maxSpend cap.

Which API protocol is Zed using?

OpenAI-compatible describes an interface format; it does not make Chat Completions (/v1/chat/completions), Responses (/v1/responses), and Anthropic Messages (/v1/messages) interchangeable. Check the installed client version, provider configuration, and actual request path against the model detail page and API compatibility fact sheet. A successful plain-text chat does not establish support for hosted tools, conversation state, or file-editing features.

Verify the Zed call in your request trace

Send a simple text request from Zed, then match its trace in Dashboard → Logs by time, model, and request_id: tokens, cost, latency, and status. Next, test streaming, tool calls, and multi-turn history separately. For failures, retain the actual request path, full error message, and request_id. If there is no matching log, check client configuration and connectivity before attributing the error to the gateway or upstream.

FAQ