[FEATURE] Native multi-provider model routing in settings.json (per-subagent / per-model-alias provider selection)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code's model configuration assumes a single upstream: ANTHROPIC_BASE_URL (and the auth token that goes with it) applies to the entire session, including every subagent. There's no way to point different models at different endpoints from within Claude Code itself.

This breaks down for anyone running a mixed setup: real Claude models for planning/orchestration, plus one or more self-hosted OpenAI-compatible inference servers for cheaper bulk/mechanical work (e.g. two separate local LLM servers on a LAN, each serving several model sizes). Today the only way to mix providers in one session is to stand up an external translating proxy (e.g. LiteLLM) in front of Claude Code that fakes a single Anthropic-compatible endpoint and internally re-routes by model name. That works, but it means:

• running and maintaining an extra service just to do request translation Claude Code could reasonably do natively
• an extra network hop and failure point
• no visibility into provider routing from Claude Code's own config, /model picker, or docs — it's all hidden in a shim

Proposed Solution

Let settings.json define multiple named model providers (base URL + auth + protocol), and let any model reference (main session model, subagent frontmatter model:, ANTHROPIC_DEFAULT_*_MODEL) specify which provider it targets. Rough shape:

{
  "modelProviders": {
    "anthropic": {
      "baseUrl": "https://api.anthropic.com",
      "authToken": "env:ANTHROPIC_API_KEY"
    },
    "providerA": {
      "baseUrl": "http://192.168.1.1:8000/v1",
      "protocol": "openai",
      "authToken": "sk-local-a"
    },
    "providerB": {
      "baseUrl": "http://192.168.1.2:8000/v1",
      "protocol": "openai",
      "authToken": "sk-local-b"
    }
  },
  "model": "anthropic/claude-opus-4-8"
}

And in subagent frontmatter:

model: providerA/70b-instruct

Claude Code would handle the OpenAI-format translation for protocol: openai providers internally (same translation logic a proxy like LiteLLM does today), so no external shim is needed. The /model picker would list models grouped by provider.

Alternative Solutions

Currently workable, but external and imperfect:

• Run a local translating proxy (e.g. LiteLLM proxy) that exposes a single Anthropic-format /v1/messages endpoint and fans requests out to multiple upstream providers based on model name, then point ANTHROPIC_BASE_URL at it. Works, but requires maintaining a separate service, adds a hop, and provider routing lives outside Claude Code's own config entirely.

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

I run two self-hosted Claude or even OpenAI-compatible inference servers on my LAN (192.168.1.1 and 192.168.1.2), each serving 4-5 model sizes. I want Claude Code's main session to plan using a real Claude model, then delegate mechanical/bulk work to whichever local subagent model fits the task — different sizes for different jobs, across both servers — all from one settings.json, without running a separate translation proxy just to make that possible.

Additional Context

• Related prior art: LiteLLM's proxy config (model_list with per-entry api_base) does roughly this shape of multi-provider routing already; something similar natively in Claude Code would remove the need for that extra layer.
• Would also need: a per-provider protocol field (Anthropic Messages vs. OpenAI chat completions) since local servers are typically OpenAI-compatible, not Anthropic-format.

• This feature request is real, but this issue writing is assisted by claude chat

There's an issue with the selected model (qwen3.8-max-preview). It may not exist or you may not have access to it.

export ANTHROPIC_BASE_URL=http://127.0.0.1:7926/c/claude-code
export ANTHROPIC_API_KEY=unused
export ANTHROPIC_DEFAULT_OPUS_MODEL=orchestrator
export ANTHROPIC_DEFAULT_HAIKU_MODEL=local-subagent

claude --model opus