Managing Channels in the AI Gateway

A "Channel" is the configuration for a single provider connection point in the AI Gateway. It stores that provider's endpoint URL, real API Key, available models, and pricing and quota details. The Gateway uses these channels to route requests sent by your applications to the right provider. This article explains how to add, configure, test, and manage channels.

Prerequisites

• ServBay is installed and running, and you are signed in to your ServBay account (sign-in is required before adding a channel).
• You have the real API Key for the target provider (local providers such as Ollama / LM Studio can be left blank).
• If you are new to the overall architecture of the AI Gateway, we recommend reading Introduction to the AI Gateway first.

Adding a Channel

Go to AI Gateway → Channels, then click Add to open the wizard. The wizard has three steps.

Step 1: Choose a Provider

Providers are grouped by category. Just click a card to select it:

• Mainstream: OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, OpenRouter.
• China: DeepSeek, Qwen, Zhipu GLM, Kimi, Doubao / Volcano, ERNIE Bot, Hunyuan, MiniMax, 01.AI, StepFun.
• Local: Ollama, LM Studio.
• Custom: OpenAI Compatible, Custom.

Once you select a provider, the Gateway automatically fills in that provider's default Base URL.

Dual-region switching

Chinese providers such as Qwen, Zhipu GLM, Kimi, Doubao / Volcano, Hunyuan, MiniMax, and StepFun offer both domestic and global endpoint sets. When you select one of these providers, a "Region" selector appears in the wizard (🇨🇳 Domestic / 🌐 Global). Switching it automatically updates the Base URL to the address for that region.

Step 2: Fill In the Configuration

• Channel name (required) — Used to identify the channel in the list; you can name it whatever you like.
• Base URL (required) — The provider's API address. Most providers are pre-filled automatically; Azure OpenAI and Custom require you to enter it manually.
• API Key (optional) — The provider's real key. If you leave it blank, you can only test whether the endpoint is reachable, not whether the key is valid. Local providers (Ollama / LM Studio) usually don't need one.
• Models — Two options; pick one:
  • Automatic discovery: After you click discover, the Gateway calls the provider's model listing API to fetch available models, and you select multiple ones as chips.
  • Manual entry: Type the model name directly. For Azure channels, enter the Deployment name, not the model name.
• Priority / Weight — When multiple channels can serve the same model, the Gateway uses these to decide routing and how to distribute load.

Note for Azure OpenAI

For Azure channels, the "Models" field should contain the Deployment name you created in the Azure portal, not the underlying model name. The Base URL must also be your Azure resource endpoint.

Step 3: Confirm and Submit

Review the configuration summary, then submit. Once submitted successfully, the new channel appears in the channel list with its real-time health status.

Capability Probing and Routing Strategy

After a channel is added, the Gateway performs capability probing on it — this is the AI Gateway's most important intelligent routing mechanism. The probing results determine whether tools like Claude Code can be used directly or need model mappings, as well as how target models are chosen.

The Two Key Probe Metrics

The Gateway probes each channel for two core facts (both are tri-state: true / false / unknown):

Probe item	Meaning	true	false	Unknown
Accepts Claude model names (accepts_claude_names)	Whether the channel natively recognizes model names like claude-opus-* / claude-sonnet-* / claude-haiku-*	Connect directly, no mapping needed	Not recognized; you must create mappings to translate claude-* names into the upstream's real model names	Probing hasn't run or failed, so no conclusion can be drawn
Tier-aware (tier_aware)	Whether the upstream itself returns different models by opus / sonnet / haiku tier	Upstream already differentiates tiers; just let it handle it	No tier differentiation (returns the same model for all tiers); the Gateway needs to create mappings	Can't be detected or hasn't been probed

Why probe instead of guess

Provider behavior varies widely. OpenAI natively doesn't recognize claude-* model names; some relay providers recognize them through forwarding; and coding-plan providers (such as Claude Pro/Max subscriptions) may only recognize the specific model names bound to the subscription. The Gateway doesn't guess based on channel type — it probes first, then decides the routing strategy.

Route Determination: Five States

When you use "one-click takeover" for Claude Code under AI Gateway → Access Management → Client, the Gateway aggregates the probe results of all candidate channels to produce a route determination:

Candidate channel state	Determination	Meaning
No usable candidate channels (no channels / all unhealthy / no channels within the virtual key's scope)	No candidate channels	You need to add or fix channels first
Any candidate channel's probe value is unknown	Not tested	You need to run a probe first; mappings cannot be created without verification
All candidate channels accept Claude model names	Direct	No mappings created; requests are forwarded as-is
No candidate channel accepts Claude model names	Mapping required	The Gateway creates mappings for all three tiers, translating claude-* into the upstream's real model names
Some candidates accept and some don't	Mixed	A human decision is needed (those that accept go direct; those that don't go through mappings)

Model Mapping: Translating claude-* into the Upstream's Real Models

When the determination is "mapping required," the Gateway creates three model mapping rules for Claude Code, one for each tier:

Model name sent by Claude Code	Mapping rule (wildcard)	Maps to
claude-opus-*	Matches all opus-tier requests	The flagship model among the candidate channels
claude-sonnet-*	Matches all sonnet-tier requests	The flagship model or standard model among the candidate channels
claude-haiku-*	Matches all haiku-tier requests	The lightweight model among the candidate channels

Rules for choosing the target model (falling back in priority order):

1. Family preset: If a known family keyword appears among the candidates (such as glm), take that family's flagship model (e.g. glm-5.2) as the opus/sonnet target, and that family's lightweight model (e.g. glm-4.7-flash) as the haiku target.
2. Keyword matching: When there's no family preset, opus/sonnet take the first model in the candidate list; haiku takes the first candidate matching a lightweight keyword (flash / mini / lite / air / small / turbo / haiku).
3. Fallback: If neither matches, all three tiers take the first model in the candidate list.

A misconfigured haiku tier is the costliest mistake

Claude Code's haiku tier has the highest call volume (every conversation's lightweight calls use it). If you accidentally put a flagship model in the haiku tier, your bill could multiply several times over. The Gateway's keyword matching table covers 7 lightweight suffixes (flash / mini / lite / air / small / turbo / haiku), making sure heavyweight models never land in the haiku tier.

How Mappings Are Written

After takeover is confirmed, the Gateway writes mapping records through the /admin/model-mappings API. Each mapping record contains:

• Source protocol (source_protocol): anthropic (requests from Claude Code are in Anthropic format)
• Source model pattern (source_model_pattern): A wildcard such as claude-opus-*
• Target protocol (target_protocol): openai (converted to OpenAI format before sending upstream)
• Target model (target_model): The specific model name chosen by probing

Writes are idempotent — repeating takeover won't create duplicate mappings; the existing mapping list is fetched and compared before writing.

Runtime Routing Rules: Failover and Degradation

Besides the static mappings written during takeover, the Gateway also supports runtime routing rules that make decisions dynamically as requests pass through the Gateway:

Rule field	Purpose
Trigger condition (condition_type)	When to trigger degradation, such as the channel's quota being exhausted (quota_exhausted)
Cost threshold (cost_threshold_usd)	Optional: triggers when the channel's cumulative cost exceeds the threshold
Action (action_type)	What to do after triggering, such as switching to a specified backup channel (switch_to)
Target channel (target_channel_id)	The backup channel to degrade to
Target model (target_model)	Optional: also switch the model when degrading to the backup channel

By combining multiple routing rules, you can, for example, automatically switch to Channel B's pay-as-you-go endpoint when Channel A's subscription quota runs out, or degrade to a cheaper model when a channel's 24-hour cost exceeds the limit.

Load Balancing and Priority

When multiple healthy channels can serve the same model, the Gateway selects among them as follows:

• Priority mode (default): Only the highest-priority channel is used; among channels with equal priority, the Gateway distributes according to internal weights.
• Round-robin mode (round_robin): Requests are rotated across all healthy candidate channels.

Priority is set in the channel configuration (a higher number means higher priority), and a virtual key's allowed_channels restricts which channels are eligible.

Connectivity Testing

You can run a connectivity test on an individual channel from the channel list. The test covers two dimensions:

• Endpoint reachability (reachable) — Checks whether the Base URL is reachable (whether the network and address are correct).
• Key validity (authenticated) — Actually calls the provider's API to verify whether the API Key is valid. This is only checked when an API Key has been entered.

Test results show the round-trip latency (in milliseconds), a status badge, and any error messages.

TIP

In the add wizard, if the endpoint is unreachable, you'll be blocked from proceeding to the next step; if the endpoint is reachable but the key is invalid, you'll only get a warning and can still continue (for example, if you plan to add the key later).

Advanced Configuration

When adding or editing a channel, you can expand the advanced configuration for cost accounting and quota control:

• Rate Multiplier — Multiplies the provider's official pricing by a factor, making it easy to account for your real cost or resale price. Defaults to 1.0.
• Billing structure — Describes how the channel is billed, such as pay as you go, subscription, or package.
• Balance — The balance source can be a fixed value, an OSS bill, or manually maintained; when you choose OSS bill, you can also specify the bill type. The balance and its update time are shown read-only in the channel details.
• Subscription expiry — Subscription / package channels can record an expiry date.
• Quota limits — You can set an upper limit by token count, request count, or amount, and choose a period (daily / weekly / monthly / custom). Once a quota is used up, that channel is automatically excluded from routing — a safety valve against unexpected overspending.

Editing and Deleting Channels

• Edit — Open a channel in the channel list to change its name, Base URL, API Key, models, and advanced configuration.
• Delete — After deleting a channel, virtual keys that depend on it can no longer route to it, so proceed with caution.

Health Status

The channel list and the Overview page show each channel's health status in real time (healthy / degraded / unavailable), helping you quickly spot broken provider configurations.

FAQ

• Q: Why does it ask me to sign in when adding a channel?
  • A: The AI Gateway is a value-added ServBay feature, so you need to sign in to your ServBay account before adding channels or keys. Just follow the on-screen prompts to sign in.
• Q: It says I've reached the channel limit?
  • A: The number of channels you can create depends on your account plan. If you hit the limit, delete channels you don't use or upgrade your plan.
• Q: Automatic model discovery isn't returning a list?
  • A: First make sure the Base URL is correct and the API Key is valid (you can verify this with the "key validity" connectivity test) — some providers require a valid key to return the model list. You can also switch to entering model names manually.
• Q: Do I need to enter a key to connect to local Ollama / LM Studio?
  • A: Usually not. Just make sure the local service is running and listening on the default port (Ollama 11434, LM Studio 1234).

Summary

Channels are the foundation of request routing in the AI Gateway. With the three-step wizard, you can quickly connect to nearly 20 providers; dual-region switching, automatic model discovery, and two-dimension connectivity tests make sure your configuration is correct; and advanced settings such as pricing and quotas let you manage costs precisely. Once your channels are set up, you can create virtual keys for your applications and tools to use.