Add a custom provider

When to use a custom connection#

Use Custom Provider when your team supplies an API address and key, or the service is missing from the preset list. Prefer an existing preset when available; you normally only need an API key.

Custom chat supports Anthropic Messages, OpenAI Responses, OpenAI Chat Completions, and Google Gemini connection types. Match the service's actual API format. A model's name alone does not tell you which format its gateway exposes.

Confirm three things with the provider#

1. API format and address: which interface it supports and its API base URL. A website, console, or network proxy address cannot replace this.
2. Authentication: the correct API key. For an Anthropic-compatible service, also confirm x-api-key versus Bearer authentication.
3. Models: real IDs your account can access, with streaming and the tool support your tasks require.

Enter a base URL without appending /v1/messages, /responses, or /chat/completions. For example, DeepSeek's compatible API uses https://api.deepseek.com/anthropic; the official OpenAI preset uses https://api.openai.com/v1.

Choose the connection type, then fill in the fields#

Open Settings → Providers → Add AI service → Custom Provider → Connect. Select Connection type before entering the address and key.

An existing entry may show Legacy custom connection; it retains Anthropic-compatible behavior. For ordinary chat, do not choose OpenAI (Image) or Google Gemini (Image). Image services are configured separately.

OpenAI Responses, Chat Completions, and Gemini connections use the entered address, key, and models. Their read-only Saved environment variables retain old settings but do not participate in these requests. Claude role mappings are not required for these connection types.

When editing an existing entry, leaving API Key empty preserves the saved key. It is cleared only after you explicitly remove it and save.

The retained screenshot below is from an earlier version. Field names and positions may differ; follow the current Connection type and API address fields.

Enlarge imageOriginal components with isolated example data: name, Claude-compatible base URL, and raw credential. The key shown is fictitious.

Example: configure DeepSeek manually#

You can use the DeepSeek preset if you have a DeepSeek account. This manual example shows how the fields fit together, using deepseek-flash for chat and background work.

1. Set Name to DeepSeek manual and Connection type to Anthropic Messages (Claude Code compatible).
2. Set API address to https://api.deepseek.com/anthropic and enter your own raw API key.
3. Open Advanced Options and select Bearer Token under Authentication method.
4. Under Claude Code model overrides, enter deepseek-flash for Opus, Fable, Sonnet, Haiku, and Subagent.
5. Leave Backup model empty and Extra Environment Variables as {}, then save.
6. Open Manage Models for the connection. Add or check the ID deepseek-flash, optionally name it DeepSeek V4.1 Flash, keep at least one model enabled, and save.
7. In chat, choose it under DeepSeek manual, then verify it as described below.

This is an ordinary-context example. The preset uses deepseek-flash[1m] for main tasks and deepseek-flash for background tasks. When using the preset, keep its configuration. Do not paste a display name as an ID or assume adding [1m] gives another model long-context support.

The screenshot below shows older advanced fields. Use deepseek-flash as described above, and include Fable and the other roles shown in the current app.

Enlarge imageScrolled original fields for Bearer authentication, four model roles, fallback, and environment overrides. This example does not establish model access for your account.

Separate model entries from role mappings#

Model entries determine what appears in the chat menu. Click Manage Models beside the provider, then add an entry or expand a row's Advanced fields:

Claude Code role mappings apply to Anthropic-compatible connections. For OpenAI Responses, Chat Completions, and Gemini, configure models directly in Manage Models.

• Opus, Fable, and Sonnet: the models used for these role requests. Mapping a role to another vendor runs that vendor's model.
• Haiku (background): also used for some title, summary, and other background tasks. Avoid falling through to a Claude ID the service does not support.
• Subagent: the model used by spawned subagents. Verify delegated tasks separately when you need them.
• Backup model: passed to the SDK for applicable main-model overload conditions. It does not switch to another service or remedy every error.

Use Manage Models → Default reasoning effort to set defaults for new conversations. Changes save immediately; existing conversations retain their own choices. Available effort levels depend on the model.

For Anthropic-compatible connections, explicit environment variables override matching role settings. For example:

{
  "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-flash"
}

This takes priority over the Sonnet role field. Normally leave {}. If a changed role does not take effect, check the conversation's selected model and matching settings in advanced JSON. Do not put credentials in JSON or treat it as an arbitrary HTTP-header editor.

Verify real requests#

1. Click the stethoscope icon, Check configuration, beside the entry. Resolve local address, authentication, and model issues. This does not verify the upstream key or quota.
2. Create a conversation, check the selected connection and model, and send “Reply only: received.” Verify a successful text response.
3. In a test project, request a read-only operation:

Read only README.md in the project root and summarize its run instructions.
If it does not exist, say so. Do not create or modify files or run commands.

Check the actual file-reading tool call and result. Verify subagents, images, or channels separately if needed. Being able to enter a model ID does not establish that all its capabilities have been tested.

Troubleshoot by symptom#

Next steps#

Return to the provider overview to manage models and connections. Before starting real work, review permissions and settings and data.