> Source: Onevium official documentation
> Article: Add a custom provider
> Original URL: https://onevium.com/docs/providers/custom
> Language: English
> Updated: 2026-09-09
> Applies to: 1.1.22+

---

# Add a custom provider

Configure a Claude-compatible gateway with its endpoint, authentication, real model IDs, role mappings, and explicit environment overrides.

## When to use a custom connection

Use **Custom Provider** when your team supplies a Claude-compatible gateway or you need to configure an endpoint and authentication manually. If the service already appears in the [preset list](https://onevium.com/docs/providers#supported-providers), prefer its preset to reduce configuration mistakes.

Custom chat connections use the Anthropic/Claude-compatible protocol. A service offering only OpenAI Chat Completions or Responses cannot be entered directly; its gateway must expose a Claude-compatible interface. Renaming a provider does not convert its protocol.

## Confirm three things with the provider

1. **Endpoint:** the API base URL for Claude/Anthropic-compatible access, not a website, console, or complete messages path.
2. **Authentication:** whether it expects `x-api-key` or `Authorization: Bearer`, and the corresponding raw credential.
3. **Models:** the real model IDs your account can access, with streaming and the tool support your tasks require.

For example, DeepSeek's compatible base URL is `https://api.deepseek.com/anthropic`. Do not append `/v1/messages`; the request flow handles the messages path. A network proxy address is not a model API base URL.

## Fill in the configuration fields

Open **Settings → Providers → Add Provider → Custom Provider → Connect**.

| Field or location                              | What to enter                                                     | Important detail                                                                                       |
| ---------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Name                                           | A recognizable connection name, such as “Team gateway”            | Identifies the account or gateway; it is not a model ID                                                |
| Provider Type                                  | `Custom`                                                          | Use this for ordinary custom chat. `Google Gemini (Image)` is a separate image feature                 |
| Base URL                                       | The provider's Claude-compatible API base URL                     | Initially empty for custom connections. Do not enter a full `/v1/messages` or `/chat/completions` path |
| API Key                                        | The provider's raw credential                                     | Do not add `Bearer ` or paste an OAuth token from Claude's login cache                                 |
| Advanced Options → Authentication Field        | `API Key (x-api-key)` or `Bearer Token (ANTHROPIC_AUTH_TOKEN)`    | Custom connections initially use API Key. Change it when the provider requires Bearer                  |
| Advanced Options → Model Mapping               | Real model IDs for Opus, Sonnet, Haiku, and Subagent              | Without explicit configuration, Claude defaults may appear. The role meanings are explained below      |
| Advanced Options → Fallback Model              | A different model available through the same connection, or blank | Blank disables it. It cannot equal the main model and does not switch to another provider              |
| Advanced Options → Extra Environment Variables | A JSON object with string values                                  | Leave `{}` when no override is needed. Use the dedicated credential fields above                       |
| Notes                                          | An optional description of the connection's purpose               | Do not store keys or other credentials here                                                            |

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

![Custom provider base configuration](https://onevium.com/assets/docs/providers-custom-basic-en.png "Original components with isolated example data: name, Claude-compatible base URL, and raw credential. The key shown is fictitious.")

## Example: configure DeepSeek manually

This example uses a real preset endpoint and model identifier to show how the custom fields fit together. You can use the DeepSeek preset instead; manual configuration is optional.

First confirm that your DeepSeek account can use `deepseek-v4-flash`. If your account exposes a different ID, use the provider-confirmed identifier rather than copying a display name.

1. Set Name to `DeepSeek manual` and keep Provider Type as `Custom`.
2. Enter `https://api.deepseek.com/anthropic` as Base URL.
3. Enter your own raw API key.
4. In Advanced Options, change Authentication Field to **Bearer Token**.
5. For this example, assign the same model to all four roles: enter `deepseek-v4-flash` for Opus, Sonnet, Haiku, and Subagent.
6. Leave Fallback Model empty and Extra Environment Variables as `{}`, then click **Add Provider**.
7. Return to the chat model menu, find **DeepSeek manual**, and select **DeepSeek V4 Flash**. If you need to add the model entry manually, follow the next section.

The model identifier illustrates configuration; it is not a live check of your account's access. Send a real request after saving.

![Custom authentication and role mappings](https://onevium.com/assets/docs/providers-custom-advanced-en.png "Scrolled 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 model menu. Click **Models** beside the connected provider to change visibility, add an entry, or expand a row's **Advanced** fields:

| Model field       | Purpose                                       | Recommended value                                                                                                                                                  |
| ----------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Model ID          | The identifier selected and used for requests | Enter the provider-confirmed real ID directly, such as `deepseek-v4-flash`                                                                                         |
| Display name      | The label shown in the interface              | Use a recognizable label, such as `DeepSeek V4 Flash`                                                                                                              |
| Upstream model ID | An advanced upstream identifier field         | This guide uses a real Model ID and leaves this field empty. Do not assume an arbitrary custom alias will be translated merely because its real ID is entered here |
| Shown / Hidden    | Whether the model appears in the menu         | Keep at least one model visible, then save                                                                                                                         |

**Role mappings** determine which model Claude Code uses when it requests a role:

- **Opus and Sonnet:** requests for these model roles. When mapped to another vendor, the model you entered runs; it is not Claude.
- **Haiku (background):** also used for some title, summary, and other background work. Configure it so background requests do not fall through to a Claude ID the provider does not support.
- **Subagent:** the model for spawned subagents. Select the needed capability and verify an actual delegated task.
- **Fallback Model:** passed to the SDK for applicable main-model overload conditions. It is not an automatic remedy for every error.

A valid model ID does not prove image, every reasoning level, or universal tool support. Capability and pricing configuration in the advanced model options does not change the upstream model's actual abilities.

**Explicit environment variables override matching role settings.** Normally leave `{}` and use the mapping fields. Add a variable only when you intend an explicit override, for example:

```json
{
  "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-flash"
}
```

This takes priority over the Sonnet mapping field. Connected presets may already have default model variables in their advanced JSON. If a mapping change appears ineffective, inspect and remove conflicting variables. The priority order is current environment overrides → legacy environment configuration → role mappings → preset fallback values.

Do not put `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or `GEMINI_API_KEY` in the JSON; the form strips those secret entries. This form is also not an arbitrary custom HTTP-header editor.

## Verify real requests

1. Open **Provider Doctor** beside the entry and resolve configuration issues with the endpoint, authentication, and models. It checks local configuration, not the upstream key or quota.
2. Create a conversation, confirm 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:

```text
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. If you need subagents, images, or channel delivery, verify those paths separately; a text response is not a substitute.

## Troubleshoot by symptom

| Symptom                                 | What to do                                                                                                                         |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 401                                     | Check Authentication Field, the raw key, account, and region. Look for an accidentally added `Bearer ` prefix                      |
| Path not found or protocol error        | Check the base URL and avoid duplicating `/v1/messages`. Confirm Anthropic compatibility, not merely OpenAI compatibility          |
| Model not found                         | Put the real upstream ID in Model ID. Check the main model and Haiku/Subagent mappings; do not use display names as IDs            |
| A changed role still uses the old model | Check the current conversation's selected model and matching model-variable overrides in advanced JSON                             |
| Requests time out                       | Check network access and **Settings → Network proxy**. Changing a timeout does not fix authentication or protocol errors           |
| You need another connection             | Add and verify the new entry, then switch the target conversation, channel, or automation. Do not use Disconnect as a pause button |

## Next steps

Return to the [provider overview](https://onevium.com/docs/providers#models) to manage models and connections. Before starting real work, review [permissions](https://onevium.com/docs/permissions) and [settings and data](https://onevium.com/docs/settings-and-data).