Last reviewed: November 4, 2026 (Asia/Shanghai); sources fetched November 3 UTC.

Direct answer

Connect Zed to CometAPI by adding a provider under language_models.openai_compatible, setting its api_url to the documented CometAPI v1 base URL , and declaring an exact current CometAPI model ID. Enter the credential through Zed’s provider settings so it goes into the system keychain, or supply the provider’s generated environment variable. Keep the credential out of settings.json.

This configures the Zed Agent and other Zed-owned model features. External agents and terminal-based agents generally manage their own model access. Zed’s Use API Access guide explicitly distinguishes those paths and documents custom OpenAI-compatible providers. CometAPI’s OpenAI-compatible quickstart supplies the corresponding base URL and Chat Completions contract.

Start with a text-only model entry and the Minimal profile. Then verify a separate file-reading task before enabling broader agent work. A reply in the panel establishes less than a completed tool call.

Who this is for

Use this guide when you already have Zed installed and want its own AI features to use CometAPI. You need a CometAPI credential, access to Zed’s settings, and a disposable folder containing only harmless test material.

The procedure is based on the official documentation fetched for this review. The public model catalog was also read successfully. No Zed desktop session or authenticated CometAPI generation was run here; the acceptance checks below are instructions for verifying your installation.

Local checks confirmed that the settings example parses as JSON and that the catalog command returns the stated model record. They do not validate Zed’s installed settings schema, request construction, or streaming behavior.

Key takeaways

  • Configure openai_compatible and a named provider, then select that provider’s model in a fresh thread.
  • Use the v1 base URL; let the client construct the operation path.
  • Treat model IDs, context limits, output limits, and capability flags as separate settings.
  • Check the local Zed process environment when a saved key appears to be ignored.
  • Disable advertised tool support for the first text check. Enable it only for a separately verified tool workflow.
  • Record observed setup results without saving credentials, source contents, or full request bodies.

Contract details to verify

Choose a current Chat Completions model

The CometAPI catalog reference documents public GET /api/models access without an authorization header. Inspect the exact id, model type, endpoint hints, context limit, and output limit. Endpoint metadata can be an object, a list, or a JSON-encoded string; inspect its content rather than assuming every record has the same representation.

For example, the catalog read on November 3 UTC included claude-haiku-4-5-20251001 as a text model, with 200K context, 8K maximum completion metadata, and an explicit /v1/chat/completions endpoint hint. That observation supports the concrete configuration below. It does not prove account access, tool compatibility, or successful generation. Refresh the record before adopting it.

To inspect just that record, set a local shell variable named COMETAPI_CATALOG_URL to the public catalog endpoint , then run this command. This public read sends no credential:

curl --fail --silent --show-error "${COMETAPI_CATALOG_URL:?Set the public catalog URL first}" |
  jq '.data[] | select(.id == "claude-haiku-4-5-20251001") |
      {id, model_type, context_length, max_completion_tokens, endpoints, upcoming}'

If no record appears, stop and choose a current text model with the required route. For a broader selection process, use the model catalog validation guide , checking its examples against the current official reference.

Add a provider without adding a secret

Run zed: open settings file from Zed’s command palette. Merge this provider into your existing settings; preserve any other provider entries. Before saving, replace COMETAPI_V1_BASE_URL with the full base URL from the CometAPI quickstart : HTTPS, host api.cometapi.com, and path /v1. The placeholder is not an environment-variable expression that Zed expands:

{
  "language_models": {
    "openai_compatible": {
      "cometapi": {
        "api_url": "COMETAPI_V1_BASE_URL",
        "available_models": [
          {
            "name": "claude-haiku-4-5-20251001",
            "display_name": "CometAPI Haiku text check",
            "max_tokens": 64000,
            "max_output_tokens": 1024,
            "capabilities": {
              "tools": false,
              "images": false,
              "parallel_tool_calls": false,
              "prompt_cache_key": false,
              "chat_completions": true,
              "interleaved_reasoning": false,
              "max_tokens_parameter": true
            }
          }
        ]
      }
    }
  }
}

The provider ID is cometapi; the display name is a human label. The model’s name is the routing ID sent to the service. Keeping those identities distinct helps diagnose a model that appears in the picker but fails remotely.

The 64000 context setting is a deliberately conservative local budget below the catalog’s advertised context, rather than a claim that the model’s full window is 64,000 tokens. The 1024 output setting is also a local choice below the listed completion maximum. These values are setup limits, not measured usage or a price estimate.

Zed’s documentation distinguishes the context setting max_tokens from max_output_tokens. It also documents capabilities.max_tokens_parameter: setting it to true sends the output limit as the API field max_tokens instead of max_completion_tokens. The CometAPI Chat Completions reference lists max_tokens as a legacy output parameter. Confirm the accepted parameter for any replacement model; do not copy this mapping into every model family.

The explicit capability block matters because Zed defaults custom OpenAI-compatible models to tools: true. Here it advertises no tool support during initial setup. chat_completions: true keeps this entry on Chat Completions; Zed documents false as the switch to Responses. Changing that flag changes the protocol being tested.

Supply the key to the correct process

Run agent: open settings, find LLM Providers, and locate or add the custom OpenAI-compatible provider. Use the same provider identity and enter the CometAPI key in its credential field. Zed documents that keys saved through this interface are stored in the system keychain.

For provider ID cometapi, the documented environment-variable rule produces COMETAPI_API_KEY. This differs from COMETAPI_KEY, the variable used in CometAPI’s standalone quickstart examples. A variable that works in a command-line example is not automatically the variable Zed reads.

Nonempty provider environment variables take precedence over saved keys. If Zed keeps using an old credential after a keychain update, inspect whether its local process inherited COMETAPI_API_KEY. Remove or update that value through your normal local secret process and restart Zed. Do not print the environment or the key to troubleshoot it.

For SSH and dev-container projects, Zed says its own LLM providers are initialized locally and read the local app’s keychain and environment. Setting a key only on the remote host may therefore leave this integration unconfigured. External agent processes can have different rules.

Apply the same repository boundary described in keeping CometAPI keys out of tutorial repositories : share setting names and nonsecret configuration, while keeping credential values in protected local storage.

Happy-path operator workflow

Open a fresh Zed Agent thread, select the configured CometAPI model, and select Minimal. The Agent Profiles reference describes Minimal as having no project tools and Ask as focusing on read-only codebase questions.

Send a short prompt such as:

Reply with ZED_ROUTE_OK and one short sentence. Do not use tools.

Accept the text stage only when a nonempty answer completes and the intended provider and model remain selected. The marker is a convenient fixture, not a guarantee of exact model output. Record the Zed version, provider ID, exact model ID, configured endpoint family, and observed outcome. Where approved diagnostics expose the destination, verify api.cometapi.com and the Chat Completions path without capturing authorization or content. An unavailable diagnostic field should remain unknown.

To add repository tools, first confirm that the selected model and route support the required function-call behavior. Set capabilities.tools to true for that model, open another fresh thread, and choose Ask. Review the active profile’s tools: profiles are configurable, and a familiar profile name alone does not establish its contents.

Create a harmless local file named zed-provider-check.txt with the line fixture-heading: amber-pine. Leave the file unattached so the task needs a tool read. Ask:

Read zed-provider-check.txt using the file-reading tool and report its
fixture-heading value. Do not edit files or run terminal commands.

Require an observed file-read tool event, its completed result, and an answer matching the fixture. Inspect the folder afterward for unexpected changes. If the model merely guesses a value without a tool event, the tool stage has not passed.

Zed distinguishes tool availability in profiles from permission decisions. Enabling a tool makes it available; it does not define automatic approval. Preserve your existing permission policy while testing. Text success and tool success should be recorded separately.

Error-path operator workflow

Stop after the first failure and identify its stage: settings loading, credential lookup, remote text generation, or tool execution. Change one relevant setting, then repeat the smallest corresponding check in a fresh thread.

For a controlled local negative check, keep tools: false and Minimal selected, then request the unattached fixture read. The application should not execute a project file tool in this configuration. A model may still produce text, so judge the absence of a tool event rather than expecting a particular refusal sentence. Restore tool availability only when proceeding to the separate tool acceptance stage.

Keep a small evidence record with observed time, Zed version, provider ID, model ID, profile, test stage, outcome, tool-event presence, and status code when actually exposed. Do not include key values, authorization headers, full errors that echo content, prompts from real work, file contents, or generated answers. A timeout does not establish that the remote request never ran; avoid repeated retries while the outcome is unclear.

Failure modes

The provider or model is missing from the picker. Check the nesting under language_models.openai_compatible, the provider ID, and the available_models array. Confirm that the settings being edited belong to the local Zed installation running the thread.

A saved key appears ineffective. Check the generated environment-variable name and its precedence. Do not rotate a working key merely because Zed inherited an older one.

The service reports a missing model or route. Refresh the exact catalog ID and endpoint hints. Keep api_url at the v1 base; do not append /chat/completions to that base setting. Confirm that the model has not been configured for Responses while you are testing Chat Completions.

A request rejects an output parameter. Recheck the model’s accepted output-limit field and max_tokens_parameter. Increasing the context-window setting will not repair an unsupported API parameter.

Text works but file reading fails. Check all three boundaries: model-and-route tool support, capabilities.tools, and the active profile’s available tools and permissions. Enable only the capability needed for the fixture check, then repeat it.

A remote project has no usable key. Check the local app environment and local keychain. Credentials installed for a remote CLI do not establish credentials for Zed’s own model provider.

FAQ

Does this configure every agent launched inside Zed?

It configures Zed-owned model features. External agents and terminal threads generally own their authentication and model configuration. Check the agent path before changing provider settings.

Is max_tokens the output limit in this JSON?

The model entry uses it for context capacity. max_output_tokens sets the output limit. The separate max_tokens_parameter capability selects which API field carries that output limit.

Can I enable tools because Zed defaults them to true?

That default is a client capability assumption, not proof about your selected service route. Confirm support and require the fixture’s tool event and result before depending on repository tools.

Can I use a different model?

Yes. Update the routing ID, context and output budgets, endpoint family, and relevant capability settings together from current documentation. Repeat the text and tool stages for the new combination.

Reader next step

Add one provider entry, store the key through Zed’s protected interface, and complete the Minimal text check. Keep tools disabled until you can verify the separate file-read stage. Save the nonsecret configuration and the observed stage outcomes as your baseline.

If you still need an account or credential for this setup, Start with CometAPI , then return to the same small acceptance checks.

Sources checked

  • Zed: Use API Access — fetched November 3, 2026 UTC. Supports custom provider settings, capability defaults, endpoint and output-parameter switches, key storage, environment precedence, and local credential lookup for remote projects.
  • Zed: Agent Profiles — fetched November 3, 2026 UTC. Supports Minimal and Ask profiles, configurable tool availability, and the distinction between availability and permission.
  • CometAPI: OpenAI-compatible API quickstart — fetched November 3, 2026 UTC. Supports the v1 base URL, bearer authentication, Chat Completions, streaming, and the standalone COMETAPI_KEY example.
  • CometAPI: List available models — fetched November 3, 2026 UTC. Supports public catalog access and the meanings and variable shapes of model metadata. The public catalog response supplied the dated model observation used above.
  • CometAPI: Create a chat completion — fetched November 3, 2026 UTC. Supports the Chat Completions operation, legacy max_tokens, completion-token limits, and function-call contracts for supporting models.

These are current primary references for an evergreen setup task. This article does not announce a release or claim a completed desktop integration. The conservative limits, two-stage acceptance procedure, fixture, and troubleshooting order are recommendations derived from the documented contracts.