Configure providers and model routing

xcsh resolves a requested model against available providers and credentials. A provider-qualified model name is the most explicit route.

How do I confirm a route?

Run xcsh --list-models <PROVIDER>, then pass one returned name to --model. Environment keys and supported subscription sessions authenticate providers; never store tokens in committed settings.

How do I select a model in a conversation?

Open /model. Tab and Shift+Tab browse providers; typing searches across them. The active conversation model and saved role badges are shown separately. Configured providers remain visible when discovery is empty, unavailable, or requires authentication. Use Ctrl+R to refresh the current provider or Ctrl+L to open login.

Choose a model with Enter, then choose its scope:

• Use in this conversation is preselected. It changes this session, including resume, without changing saved role assignments.
• Save as default changes the current conversation and the default for future sessions.
• Assign to role saves Default, Fast/SMOL, Thorough/SLOW, Plan, or another existing role. Roles other than Default leave the current conversation unchanged.

Choose a reasoning level supported by that exact model and press Enter to confirm. Inherit displays the provider default; an existing supported reasoning selection is preselected. Escape backs out without applying an unfinished choice. Failed writes are reported before badges show success.

Claude Fable 5 and 5.1 use adaptive thinking on every request. Their default is high; supported choices are low, medium, high, xhigh, and max, with xcsh’s minimal choice mapped to Anthropic low. off is rejected because the Fable API does not support disabling thinking. Fable also does not accept temperature or forced tool selection, so xcsh omits temperature and normalizes any or a named forced tool to auto while retaining strict tool schemas.

When the authenticated ChatGPT subscription catalog includes GPT-6 Astra, /model presents it as an additional premium option under ChatGPT Subscription. Astra does not replace the existing Luna, Terra, Sol, or role assignments unless you explicitly assign it.

A manual conversation choice remains in effect under automatic routing. Entering planning mode uses the Plan assignment; exiting restores the prior conversation model and reasoning. Explicit --models scopes still limit the picker.

Open /login to see providers that are configured, credential-backed, allowlisted, active, or freshly detected. Optional local runtimes do not appear merely because xcsh attempted an automatic probe. Choose Add provider… to search the complete built-in catalog.

Provider rows use human status labels. Press Right on a row to inspect its credential source, last verification, sanitized failure reason, model visibility, and any grouped routes. /logout lists only providers with stored credentials that xcsh can remove; environment and configuration credentials are not presented as removable.

Provider grouping in models.yml is also used by the management view:

providers:
  litellm:
    picker:
      groupId: litellm
      groupLabel: LiteLLM
      sectionLabel: OpenAI
    modelAllowlist:
      - gpt-6-luna
      - gpt-5.6-terra
      - gpt-6-sol
      - gpt-6-astra
      - gpt-5.6-luna
      - gpt-5.6-sol
  anthropic:
    picker:
      groupId: litellm
      groupLabel: LiteLLM
      sectionLabel: Anthropic
    modelAllowlist:
      - claude-haiku-4-5
      - claude-sonnet-5
      - claude-opus-5-5
      - claude-opus-5

modelProviderAllowlist is a settings key that limits normal /model visibility. An empty list means no picker restriction; it does not make every built-in provider relevant in /login. Explicit provider-qualified command-line selection and direct /login <provider> remain available.

xcsh config set modelProviderAllowlist '["litellm", "anthropic"]'
xcsh config set modelProviderOrder '["litellm", "anthropic", "google-vertex"]'

For command-line selection, qualify the provider whenever several usable providers expose the same model ID. A bare --model value succeeds only when one usable provider matches; otherwise xcsh prints the qualified choices and exits nonzero in noninteractive mode.

The two explicit Fable aliases are an exception to general fuzzy selection:

xcsh --model fable
xcsh --model anthropic/fable

Both select anthropic/claude-fable-5-1 deterministically.

Where does LiteLLM fit?

LiteLLM is an optional provider proxy installed or checked with xcsh setup litellm. Its base uniform resource locator (URL) and credential belong in the runtime environment. Successful text Responses support does not imply Realtime or audio support; test the exact endpoint your workflow uses.

Generated LiteLLM configuration shows seven current internal models: GPT-6 Luna, GPT-5.6 Terra, GPT-6 Sol, GPT-6 Astra, Claude Haiku 4.5, Claude Sonnet 5, and Claude Opus 5.5. Older GPT-5.6 Luna/Sol and Claude Opus 5 selectors remain resolvable for historical sessions but are hidden from ordinary browsing.

GPT-6 Luna, Sol, and Astra use LiteLLM’s OpenAI Responses endpoint (/openai/v1/responses), while GPT-5.6 Terra keeps the discovered OpenAI-compatible Chat Completions base path. The generated Anthropic provider uses the native Messages route. Internal routes keep zero-cost metadata until the gateway publishes authoritative chargeback pricing.

The four current internal OpenAI models use a 272,000-token effective context window by default. Enable LiteLLM Maximum Context under Providers to use their verified 1,050,000-token window with up to 128,000 output tokens. This setting is independent from OpenAI Codex Maximum Context, which applies only to ChatGPT subscription routing. Claude Haiku 4.5 retains its 200,000-token context and 64,000-token output limits; Sonnet 5 and Opus 5.5 retain 1,000,000-token context and 128,000-token output limits.

How do I test licensed Vertex locally?

bun run dev and local coding-agent binary builds load the licensed Vertex OAuth client pair automatically. Explicit XCSH_VERTEX_OAUTH_CLIENT_ID and XCSH_VERTEX_OAUTH_CLIENT_SECRET build inputs take precedence; supply both together.

For local UAT, the first launch can recover the embedded client pair from an installed official xcsh binary and retain it in $XDG_CONFIG_HOME/xcsh/vertex-build.json (default ~/.config/xcsh/vertex-build.json). The file is outside the checkout, shared by local sessions and worktrees for the same operating-system user, and created with owner-only permissions. Each worktree needs this development/build launcher to load it automatically. Later launches reuse it even if the installed binary changes. XCSH_VERTEX_OAUTH_CREDENTIALS_FILE selects another private local file containing clientId and clientSecret fields.

The source-runtime preload keeps the pair in process memory; local compiled candidates embed it. Do not copy this file or its values into source control, logs, or UAT reports. CI does not read or recover workstation credentials: official release builds continue to receive the pair through GitHub secrets. Unit tests use fixture credentials; the live provider smoke script uses the same local preload as development UAT.

Route selection is complete only when the provider, account, and model all match the intended boundary. Use /model in the TUI or the explicit model flag shown by xcsh --help, send a no-tool identity prompt, and inspect the session metadata. Switching a model affects subsequent turns; it does not rewrite earlier entries. Remove temporary route overrides and start a new session to verify the default path independently.