Tutorial · Zed

Zed with a custom OpenAI-compatible model

Zed's agent is only as good as the model declaration behind it. A settings block with the right base URL, context window and capabilities avoids most connection and tool-call failures.

Short answer. In Zed, open Agent Settings with agent: open settings, add an OpenAI-compatible provider, set the API URL to https://api.plugsky.com/v1, and declare plugsky-coder with max_tokens: 262144 and max_output_tokens: 16384. Put the key in PLUGSKY_API_KEY or the provider UI, then select the model in the Agent Panel.

1. Add the provider

Zed offers two paths to the same configuration: the provider UI and settings.json. The UI is faster; the file is easier to review and share with a team. Keys entered in the UI go to the system keychain, not settings.json. If you use an environment variable, Zed derives the name from the provider ID: plugsky becomes PLUGSKY_API_KEY.

export PLUGSKY_API_KEY="your-key-here"

Do not put the key in settings.json or commit it to a dotfiles repository. Environment variables take precedence over a keychain value, so unset the variable and restart Zed if you switch back to the UI-managed key.

2. The settings.json block

Add the provider under language_models.openai_compatible. The provider ID is yours to choose; this example uses plugsky.

{
  "language_models": {
    "openai_compatible": {
      "plugsky": {
        "api_url": "https://api.plugsky.com/v1",
        "available_models": [
          {
            "name": "plugsky-coder",
            "display_name": "Plugsky Coder",
            "max_tokens": 262144,
            "max_output_tokens": 16384,
            "capabilities": {
              "tools": true,
              "images": false,
              "parallel_tool_calls": false,
              "prompt_cache_key": false,
              "chat_completions": true,
              "interleaved_reasoning": false,
              "max_tokens_parameter": false
            }
          }
        ]
      }
    }
  }
}

api_url is the base URL. name must match the model ID exactly; display_name is only for the picker. max_tokens is the context window, not the output limit. That naming is the source of many bad configurations.

3. Capabilities decide what the agent can do

CapabilityDefaultWhat to set for Plugsky
toolstruetrue. The agent needs tool calls to edit files and run commands.
imagesfalsefalse for plugsky-coder; true only if the model accepts image input.
parallel_tool_callsfalseLeave false unless the model and endpoint both support parallel calls.
prompt_cache_keyfalseLeave false unless the provider documents this field.
chat_completionstruetrue. Set false only for a Responses-only endpoint.
interleaved_reasoningfalseLeave false unless thinking is returned in a reasoning field.
max_tokens_parameterfalseSet true if the endpoint expects max_tokens instead of max_completion_tokens.

Start from these defaults and change only what you can test. Turning on a capability the endpoint ignores produces silent failures, not a clear error.

4. Context and output limits

Set max_tokens to the model's real context window. For the Plugsky coder models that is 262,144. Set max_output_tokens to the generation cap: 16,384 for plugsky-coder, 4,096 for plugsky-coder-fast. If max_tokens is too low, Zed trims context early and the agent forgets files. If it is too high, requests fail at the provider with a context-length error. Neither failure is obvious from the UI.

In Zed's custom model schema, max_tokens is the context window and max_output_tokens is the generation cap. Provide both. If you copy a configuration from a chat-completion example, check which field you are pasting into: a 16,384 value in max_tokens will make the agent forget files long before the model's real limit.

5. Tool use and streaming

Zed streams chat-completions responses by default. The agent needs tool calls to read files, run commands and apply edits. If your endpoint only implements the Responses API, set capabilities.chat_completions to false; Zed will use the Responses endpoint. Plugsky's compatible API is chat completions, so leave it true.

If tool calls fail, check the model first, then parallel_tool_calls. A model that supports one tool call at a time should not be told to emit several. Set parallel_tool_calls to false and keep prompts narrow. If the model emits tool calls as text, Zed will not execute them; switch to a model with function calling.

6. Troubleshooting

SymptomLikely causeFix
401 UnauthorizedKey missing or wrong environment variableCheck PLUGSKY_API_KEY; restart Zed after exporting it.
Model missing from pickerProvider or model not savedRe-open settings, confirm the JSON parses, and restart.
Context-length errormax_tokens higher than the real windowSet it to 262,144 or lower.
Tool calls never runTools disabled or model lacks supportSet tools: true; use a coder model.
404 on every requestURL includes /chat/completionsUse the base URL ending in /v1.
Replies cut offOutput cap too lowRaise max_output_tokens for the model.

For the agent workflow itself, see what to look for in a coding agent. For a first request outside Zed, use the quickstart, and check pricing before a long session.

FAQ

Where does Zed store the API key?

Keys entered in the provider UI are stored in the system keychain. If you use an environment variable, Zed reads PLUGSKY_API_KEY for a provider whose ID is plugsky.

Why doesn't my model appear in Zed?

The settings JSON may be invalid, the provider may not be saved, or the model entry may be missing. Re-check the JSON and restart Zed, then open the model picker again.

What does max_tokens mean in Zed?

For custom models, max_tokens is the context window, not the output limit. Set it to the model's real context size and use max_output_tokens for the generation cap.

Does Zed support tool calling with custom models?

Yes, when capabilities.tools is true and the model and endpoint return OpenAI-style tool calls. Set parallel_tool_calls to false unless you have tested parallel calls.

Why do I get a 404 from the endpoint?

The API URL usually includes a path that the client appends again. Use the base URL ending in /v1, not the full /chat/completions URL.

Sources checked 20 November 2026: Zed use API access; Zed LLM providers; Zed agent settings. Product behavior, endpoint support and plan limits can change; re-check the primary documentation before production rollout.