Model Providers

Full reference for the modelProviders configuration schema in settings.json.

Overview

modelProviders declares which models are available for each authentication protocol. Keys must be valid auth types: openai, anthropic, or gemini.

{
  "modelProviders": {
    "openai": [{ "id": "gpt-4o", "envKey": "OPENAI_API_KEY" }],
    "anthropic": [
      { "id": "claude-sonnet-4-20250514", "envKey": "ANTHROPIC_API_KEY" }
    ],
    "gemini": [{ "id": "gemini-2.5-pro", "envKey": "GEMINI_API_KEY" }]
  }
}

Model entry fields

Field	Required	Description
id	Yes	Model ID sent to the API (also used as the config identifier)
name	No	Display name in /model picker (defaults to id)
envKey	Yes	Name of the environment variable holding the API key
baseUrl	No	API endpoint override (for proxies, local servers, or custom endpoints)
description	No	Description shown in /model picker
generationConfig	No	Fine-tuning options (see below)

IMPORTANT

envKey specifies the name of an environment variable, not the key itself. Set the variable separately via shell export, .proto/.env, or the env field.

generationConfig fields

Field	Type	Description
timeout	number	Request timeout in ms
maxRetries	number	Max retries on failure
enableCacheControl	boolean	Enable prompt caching
contextWindowSize	number	Declared context window size
samplingParams	object	temperature, top_p, max_tokens, presence_penalty, frequency_penalty, top_k
customHeaders	object	Extra HTTP headers per request
extra_body	object	Extra fields added to the request body (OpenAI only)
schemaCompliance	string	Gemini-specific schema compliance mode
modalities	object	{ image: true } to enable vision

Important: the impermeable provider layer

When a model is selected from modelProviders, its generationConfig is applied atomically — global settings.model.generationConfig is not merged in. Fields not specified by the provider are undefined, not inherited.

This ensures provider configurations are self-contained and predictable.

Auth types and SDKs

Key	API format	SDK
openai	OpenAI-compatible	openai npm package
anthropic	Anthropic	@anthropic-ai/sdk
gemini	Google GenAI	@google/genai

WARNING

If an auth type key contains a typo (e.g. openai-custom), the configuration is silently skipped and models will not appear in /model. Always use exactly openai, anthropic, or gemini.

Duplicate model IDs

Duplicate id values within the same auth type are not supported. The first occurrence wins; subsequent duplicates are skipped with a warning.

Example: multiple providers

{
  "modelProviders": {
    "openai": [
      {
        "id": "gpt-4o",
        "name": "GPT-4o",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1",
        "generationConfig": {
          "timeout": 60000,
          "samplingParams": { "temperature": 0.2, "max_tokens": 4096 }
        }
      },
      {
        "id": "openai/gpt-4o",
        "name": "GPT-4o via OpenRouter",
        "envKey": "OPENROUTER_API_KEY",
        "baseUrl": "https://openrouter.ai/api/v1"
      }
    ],
    "anthropic": [
      {
        "id": "claude-sonnet-4-20250514",
        "name": "Claude Sonnet 4",
        "envKey": "ANTHROPIC_API_KEY"
      }
    ],
    "gemini": [
      {
        "id": "gemini-2.5-pro",
        "name": "Gemini 2.5 Pro",
        "envKey": "GEMINI_API_KEY",
        "generationConfig": { "contextWindowSize": 1000000 }
      }
    ]
  }
}

Example: local model (Ollama)

{
  "modelProviders": {
    "openai": [
      {
        "id": "llama3",
        "name": "Llama 3 (Ollama)",
        "envKey": "OLLAMA_API_KEY",
        "baseUrl": "http://localhost:11434/v1"
      }
    ]
  },
  "env": { "OLLAMA_API_KEY": "ollama" }
}

Settings merge strategy

modelProviders from project settings replaces (not merges with) user settings. Define modelProviders in ~/.proto/settings.json to avoid conflicts.

Resolution precedence (full)

Priority	Source	Takes precedence for
1 (highest)	CLI flags	--model, --auth-type, --openai-api-key, etc.
2	modelProviders entry	All generationConfig fields (impermeable)
3	settings.model.generationConfig	Runtime models only
4	Provider SDK defaults	Runtime models only

See Guides → Configure Models & Auth for a practical quick-start.