claude-code - 💡(How to fix) Fix [DOCS] Model picker docs missing gateway `/v1/models` discovery behavior [1 comments, 1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/model-config

Section/Topic

"Add a custom model option" and LLM gateway model selection behavior for /model

Current Documentation

The model configuration page currently documents manually adding one custom picker entry:

Use ANTHROPIC_CUSTOM_MODEL_OPTION to add a single custom entry to the /model picker without replacing the built-in aliases. This is useful for LLM gateway deployments or testing model IDs that Claude Code does not list by default.

It also says:

The custom entry appears at the bottom of the /model picker. ANTHROPIC_CUSTOM_MODEL_OPTION_NAME and ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION are optional. If omitted, the model ID is used as the name and the description defaults to Custom model (<model-id>).

The LLM gateway page currently says:

By default, Claude Code will use standard model names for the selected API format.

If you have configured custom model names in your gateway, use the environment variables documented in Model configuration to match your custom names.

What's Wrong or Missing?

Claude Code v2.1.126 added behavior where the /model picker lists models from a gateway's /v1/models endpoint when ANTHROPIC_BASE_URL points at an Anthropic-compatible gateway.

The current docs still describe gateway model selection as a manual environment-variable workflow and do not mention:

• that Claude Code can discover gateway models from /v1/models
• what response shape or compatibility expectations the gateway's /v1/models endpoint must satisfy
• how discovered gateway models interact with ANTHROPIC_CUSTOM_MODEL_OPTION, availableModels, pinned default model environment variables, and _NAME / _DESCRIPTION / _SUPPORTED_CAPABILITIES
• what users should expect in /model when the endpoint is absent, inaccessible, or returns no usable models

This leaves gateway administrators with the older mental model that every custom gateway model must be manually exposed through environment variables.

Suggested Improvement

Add a subsection under "Add a custom model option" or the LLM gateway "Model selection" section, for example:

Gateway model discovery

When ANTHROPIC_BASE_URL points at an Anthropic-compatible gateway, Claude Code v2.1.126 and later can populate the /model picker from the gateway's /v1/models endpoint.

Document:

• the /v1/models endpoint requirement for gateways that want automatic picker population
• whether Claude Code calls <ANTHROPIC_BASE_URL>/v1/models directly and what authentication headers are sent
• the expected model-list response fields Claude Code uses for picker ID, display name, and description
• fallback behavior when the endpoint is unavailable
• precedence and interaction with ANTHROPIC_CUSTOM_MODEL_OPTION, availableModels, ANTHROPIC_DEFAULT_*_MODEL, and _SUPPORTED_CAPABILITIES

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Version context: This behavior was added in Claude Code v2.1.126.