Provedores de Modelos

O Qwen Code permite configurar múltiplos provedores de modelos por meio da configuração modelProviders no seu settings.json. Isso permite alternar entre diferentes modelos e provedores de IA usando o comando /model.

Visão Geral

Use modelProviders para declarar listas curadas de modelos por tipo de autenticação que o seletor /model pode alternar. As chaves devem ser tipos de autenticação válidos (openai, anthropic, gemini, etc.). Cada entrada requer um id e deve incluir envKey, com name, description, baseUrl e generationConfig opcionais. As credenciais nunca são persistidas nas configurações; o runtime as lê de process.env[envKey]. Os modelos Qwen OAuth permanecem hard-coded e não podem ser sobrescritos.

Exemplos de Configuração por Tipo de Autenticação

Abaixo estão exemplos completos de configuração para diferentes tipos de autenticação, mostrando os parâmetros disponíveis e suas combinações.

Tipos de Autenticação Suportados

As chaves do objeto modelProviders devem ser valores válidos de authType. Os tipos de autenticação suportados atualmente são:

[!warning] Se uma chave de tipo de autenticação inválida for usada (ex.: um erro de digitação como "openai-custom"), a configuração será ignorada silenciosamente e os modelos não aparecerão no seletor /model. Sempre use um dos valores de tipo de autenticação suportados listados acima.

SDKs Usados para Requisições de API

O Qwen Code usa os seguintes SDKs oficiais para enviar requisições a cada provedor:

Isso significa que o baseUrl configurado deve ser compatível com o formato de API esperado pelo SDK correspondente. Por exemplo, ao usar o tipo de autenticação openai, o endpoint deve aceitar requisições no formato da API OpenAI.

Provedores compatíveis com OpenAI (openai)

Este tipo de autenticação suporta não apenas a API oficial da OpenAI, mas também qualquer endpoint compatível com OpenAI, incluindo provedores agregados de modelos como o OpenRouter.

{
  "env": {
    "OPENAI_API_KEY": "sk-your-actual-openai-key-here",
    "OPENROUTER_API_KEY": "sk-or-your-actual-openrouter-key-here"
  },
  "modelProviders": {
    "openai": [
      {
        "id": "gpt-4o",
        "name": "GPT-4o",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1",
        "generationConfig": {
          "timeout": 60000,
          "maxRetries": 3,
          "enableCacheControl": true,
          "contextWindowSize": 128000,
          "modalities": {
            "image": true
          },
          "customHeaders": {
            "X-Client-Request-ID": "req-123"
          },
          "extra_body": {
            "enable_thinking": true,
            "service_tier": "priority"
          },
          "samplingParams": {
            "temperature": 0.2,
            "top_p": 0.8,
            "max_tokens": 4096,
            "presence_penalty": 0.1,
            "frequency_penalty": 0.1
          }
        }
      },
      {
        "id": "gpt-4o-mini",
        "name": "GPT-4o Mini",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1",
        "generationConfig": {
          "timeout": 30000,
          "samplingParams": {
            "temperature": 0.5,
            "max_tokens": 2048
          }
        }
      },
      {
        "id": "openai/gpt-4o",
        "name": "GPT-4o (via OpenRouter)",
        "envKey": "OPENROUTER_API_KEY",
        "baseUrl": "https://openrouter.ai/api/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 3,
          "samplingParams": {
            "temperature": 0.7
          }
        }
      }
    ]
  }
}

Anthropic (anthropic)

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-your-actual-anthropic-key-here"
  },
  "modelProviders": {
    "anthropic": [
      {
        "id": "claude-3-5-sonnet",
        "name": "Claude 3.5 Sonnet",
        "envKey": "ANTHROPIC_API_KEY",
        "baseUrl": "https://api.anthropic.com/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 3,
          "contextWindowSize": 200000,
          "samplingParams": {
            "temperature": 0.7,
            "max_tokens": 8192,
            "top_p": 0.9
          }
        }
      },
      {
        "id": "claude-3-opus",
        "name": "Claude 3 Opus",
        "envKey": "ANTHROPIC_API_KEY",
        "baseUrl": "https://api.anthropic.com/v1",
        "generationConfig": {
          "timeout": 180000,
          "samplingParams": {
            "temperature": 0.3,
            "max_tokens": 4096
          }
        }
      }
    ]
  }
}

Google Gemini (gemini)

{
  "env": {
    "GEMINI_API_KEY": "AIza-your-actual-gemini-key-here"
  },
  "modelProviders": {
    "gemini": [
      {
        "id": "gemini-2.0-flash",
        "name": "Gemini 2.0 Flash",
        "envKey": "GEMINI_API_KEY",
        "baseUrl": "https://generativelanguage.googleapis.com",
        "capabilities": {
          "vision": true
        },
        "generationConfig": {
          "timeout": 60000,
          "maxRetries": 2,
          "contextWindowSize": 1000000,
          "schemaCompliance": "auto",
          "samplingParams": {
            "temperature": 0.4,
            "top_p": 0.95,
            "max_tokens": 8192,
            "top_k": 40
          }
        }
      }
    ]
  }
}

Modelos Locais Self-Hosted (via API compatível com OpenAI)

A maioria dos servidores de inferência locais (vLLM, Ollama, LM Studio, etc.) fornece um endpoint de API compatível com OpenAI. Configure-os usando o tipo de autenticação openai com um baseUrl local:

{
  "env": {
    "OLLAMA_API_KEY": "ollama",
    "VLLM_API_KEY": "not-needed",
    "LMSTUDIO_API_KEY": "lm-studio"
  },
  "modelProviders": {
    "openai": [
      {
        "id": "qwen2.5-7b",
        "name": "Qwen2.5 7B (Ollama)",
        "envKey": "OLLAMA_API_KEY",
        "baseUrl": "http://localhost:11434/v1",
        "generationConfig": {
          "timeout": 300000,
          "maxRetries": 1,
          "contextWindowSize": 32768,
          "samplingParams": {
            "temperature": 0.7,
            "top_p": 0.9,
            "max_tokens": 4096
          }
        }
      },
      {
        "id": "llama-3.1-8b",
        "name": "Llama 3.1 8B (vLLM)",
        "envKey": "VLLM_API_KEY",
        "baseUrl": "http://localhost:8000/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 2,
          "contextWindowSize": 128000,
          "samplingParams": {
            "temperature": 0.6,
            "max_tokens": 8192
          }
        }
      },
      {
        "id": "local-model",
        "name": "Local Model (LM Studio)",
        "envKey": "LMSTUDIO_API_KEY",
        "baseUrl": "http://localhost:1234/v1",
        "generationConfig": {
          "timeout": 60000,
          "samplingParams": {
            "temperature": 0.5
          }
        }
      }
    ]
  }
}

Para servidores locais que não exigem autenticação, você pode usar qualquer valor placeholder para a API key:

# For Ollama (no auth required)
export OLLAMA_API_KEY="ollama"
 
# For vLLM (if no auth is configured)
export VLLM_API_KEY="not-needed"

Alibaba Cloud Coding Plan

O Alibaba Cloud Coding Plan fornece um conjunto pré-configurado de modelos Qwen otimizados para tarefas de codificação. Este recurso está disponível para usuários com acesso à API do Alibaba Cloud Coding Plan e oferece uma experiência de configuração simplificada com atualizações automáticas de configuração de modelos.

Visão Geral

Quando você se autentica com uma API key do Alibaba Cloud Coding Plan usando o comando /auth, o Qwen Code configura automaticamente os seguintes modelos:

Configuração

1. Obtenha uma API key do Alibaba Cloud Coding Plan:
   • China: https://bailian.console.aliyun.com/?tab=model#/efm/coding_plan 
   • International: https://modelstudio.console.alibabacloud.com/?tab=dashboard#/efm/coding_plan 
2. Execute o comando /auth no Qwen Code
3. Selecione Alibaba Cloud Coding Plan
4. Selecione sua região
5. Insira sua API key quando solicitado

Os modelos serão configurados automaticamente e adicionados ao seu seletor /model.

Regiões

O Alibaba Cloud Coding Plan suporta duas regiões:

A região é selecionada durante a autenticação e armazenada no settings.json em codingPlan.region. Para alternar regiões, execute novamente o comando /auth e selecione uma região diferente.

Armazenamento da API Key

Quando você configura o Coding Plan por meio do comando /auth, a API key é armazenada usando o nome de variável de ambiente reservado BAILIAN_CODING_PLAN_API_KEY. Por padrão, ela é armazenada no campo env do seu arquivo settings.json.

# ~/.qwen/.env
BAILIAN_CODING_PLAN_API_KEY=sua-api-key-aqui

Atualizações Automáticas

As configurações de modelo do Coding Plan são versionadas. Quando o Qwen Code detecta uma versão mais recente do template de modelo, você será solicitado a atualizar. Aceitar a atualização irá:

• Substituir as configurações de modelo do Coding Plan existentes pelas versões mais recentes
• Preservar quaisquer configurações de modelo customizadas que você adicionou manualmente
• Alternar automaticamente para o primeiro modelo na configuração atualizada

O processo de atualização garante que você sempre tenha acesso às configurações e recursos de modelo mais recentes sem intervenção manual.

Configuração Manual (Avançado)

Se preferir configurar manualmente os modelos do Coding Plan, você pode adicioná-los ao seu settings.json como qualquer provedor compatível com OpenAI:

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3-coder-plus",
        "name": "qwen3-coder-plus",
        "description": "Qwen3-Coder via Alibaba Cloud Coding Plan",
        "envKey": "YOUR_CUSTOM_ENV_KEY",
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1"
      }
    ]
  }
}

Camadas de Resolução e Atomicidade

Os valores efetivos de auth/modelo/credenciais são escolhidos por campo usando a seguinte precedência (o primeiro presente vence). Você pode combinar --auth-type com --model para apontar diretamente para uma entrada de provedor; essas flags de CLI são executadas antes de outras camadas.

*Quando presentes, as flags de auth da CLI substituem as configurações. Caso contrário, security.auth.selectedType ou o padrão implícito determinam o tipo de autenticação. Qwen OAuth e OpenAI são os únicos tipos de autenticação expostos sem configuração extra.

Camadas de Configuração de Geração: A Camada Impermeável do Provedor

A resolução de configuração segue um modelo de camadas estrito com uma regra crucial: a camada modelProvider é impermeável.

Como funciona

1. Quando um modelo modelProvider É selecionado (ex.: via comando /model escolhendo um modelo configurado por provedor):
   • Todo o generationConfig do provedor é aplicado atomicamente
   • A camada do provedor é completamente impermeável — camadas inferiores (CLI, env, configurações) não participam da resolução do generationConfig de forma alguma
   • Todos os campos definidos em modelProviders[].generationConfig usam os valores do provedor
   • Todos os campos não definidos pelo provedor são definidos como undefined (não herdados das configurações)
   • Isso garante que as configurações do provedor atuem como um “pacote selado” completo e autossuficiente
2. Quando NENHUM modelo modelProvider é selecionado (ex.: usando --model com um ID de modelo bruto, ou usando CLI/env/configurações diretamente):
   • A resolução passa para as camadas inferiores
   • Os campos são preenchidos a partir de CLI → env → configurações → padrões
   • Isso cria um Modelo de Runtime (veja a próxima seção)

Precedência por campo para generationConfig

Tratamento atômico de campos

Os seguintes campos são tratados como objetos atômicos - os valores do provedor substituem completamente o objeto inteiro, sem mesclagem:

• samplingParams - Temperature, top_p, max_tokens, etc.
• customHeaders - Headers HTTP customizados
• extra_body - Parâmetros extras do corpo da requisição

Exemplo

// User settings (~/.qwen/settings.json)
{
  "model": {
    "generationConfig": {
      "timeout": 30000,
      "samplingParams": { "temperature": 0.5, "max_tokens": 1000 }
    }
  }
}
 
// modelProviders configuration
{
  "modelProviders": {
    "openai": [{
      "id": "gpt-4o",
      "envKey": "OPENAI_API_KEY",
      "generationConfig": {
        "timeout": 60000,
        "samplingParams": { "temperature": 0.2 }
      }
    }]
  }
}

Quando gpt-4o é selecionado em modelProviders:

• timeout = 60000 (do provedor, substitui configurações)
• samplingParams.temperature = 0.2 (do provedor, substitui completamente o objeto de configurações)
• samplingParams.max_tokens = undefined (não definido no provedor, e a camada do provedor não herda das configurações — campos são explicitamente definidos como undefined se não fornecidos)

Ao usar um modelo bruto via --model gpt-4 (não de modelProviders, cria um Modelo de Runtime):

• timeout = 30000 (das configurações)
• samplingParams.temperature = 0.5 (das configurações)
• samplingParams.max_tokens = 1000 (das configurações)

A estratégia de merge para o próprio modelProviders é REPLACE: todo o modelProviders das configurações do projeto substituirá a seção correspondente nas configurações do usuário, em vez de mesclar os dois.

Modelos de Provedor vs Modelos de Runtime

O Qwen Code distingue entre dois tipos de configurações de modelo:

Modelo de Provedor

• Definido na configuração modelProviders
• Possui um pacote de configuração completo e atômico
• Quando selecionado, sua configuração é aplicada como uma camada impermeável
• Aparece na lista do comando /model com metadados completos (nome, descrição, capabilities)
• Recomendado para fluxos de trabalho com múltiplos modelos e consistência em equipe

Modelo de Runtime

• Criado dinamicamente ao usar IDs de modelo brutos via CLI (--model), variáveis de ambiente ou configurações
• Não definido em modelProviders
• A configuração é construída “projetando” através das camadas de resolução (CLI → env → configurações → padrões)
• Capturado automaticamente como um RuntimeModelSnapshot quando uma configuração completa é detectada
• Permite reutilização sem precisar inserir credenciais novamente

Ciclo de vida do RuntimeModelSnapshot

Quando você configura um modelo sem usar modelProviders, o Qwen Code cria automaticamente um RuntimeModelSnapshot para preservar sua configuração:

# This creates a RuntimeModelSnapshot with ID: $runtime|openai|my-custom-model
qwen --auth-type openai --model my-custom-model --openaiApiKey $KEY --openaiBaseUrl https://api.example.com/v1

O snapshot:

• Captura o ID do modelo, API key, base URL e configuração de geração
• Persiste entre sessões (armazenado em memória durante o runtime)
• Aparece na lista do comando /model como uma opção de runtime
• Pode ser alternado usando /model $runtime|openai|my-custom-model

Principais diferenças

Quando usar cada um

• Use Modelos de Provedor quando: Você tem modelos padrão compartilhados em uma equipe, precisa de configurações consistentes ou quer evitar substituições acidentais
• Use Modelos de Runtime quando: Testar rapidamente um novo modelo, usar credenciais temporárias ou trabalhar com endpoints ad-hoc

Persistência de Seleção e Recomendações

• /model e /auth persistem model.name (quando aplicável) e security.auth.selectedType no escopo gravável mais próximo que já define modelProviders; caso contrário, fazem fallback para o escopo do usuário. Isso mantém os arquivos de workspace/usuário sincronizados com o catálogo de provedores ativo.
• Sem modelProviders, o resolvedor mistura as camadas CLI/env/configurações, criando Modelos de Runtime. Isso é aceitável para configurações de provedor único, mas trabalhoso ao alternar frequentemente. Defina catálogos de provedores sempre que fluxos de trabalho com múltiplos modelos forem comuns, para que as alternâncias permaneçam atômicas, com origem atribuída e depuráveis.