Provedores de Modelos

O Qwen Code permite configurar vários 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 modelos por tipo de autenticação que podem ser alternados no seletor /model. As chaves devem ser tipos de autenticação válidos (openai, anthropic, gemini, etc.). Cada tipo de autenticação mapeia para um objeto ProviderConfig com um campo protocol e um campo models (o array de definições de modelos). Cada entrada em models requer um id; envKey é opcional e recomendado (quando omitido, usa a chave de ambiente padrão do tipo de autenticação, por exemplo, OPENAI_API_KEY para openai), 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 abrangentes 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 desconhecida for usada (por exemplo, um erro de digitação como "openai-custom"), uma chave não vazia é aceita como está em seu próprio grupo de tipo de autenticação, mas não mapeará para um protocolo conhecido — portanto, seus modelos não funcionarão como pretendido e não se comportarão corretamente no seletor /model. Apenas chaves em branco (vazias ou apenas com espaços em branco) são ignoradas. 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 para 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 de modelos agregados como OpenRouter e Requesty.

{
  "env": {
    "OPENAI_API_KEY": "sk-your-actual-openai-key-here",
    "OPENROUTER_API_KEY": "sk-or-your-actual-openrouter-key-here",
    "REQUESTY_API_KEY": "sk-your-actual-requesty-key-here"
  },
  "modelProviders": {
    "openai": {
      "protocol": "openai",
      "models": [
        {
          "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
            }
          }
        },
        {
          "id": "openai/gpt-4o-mini",
          "name": "GPT-4o Mini (via Requesty)",
          "envKey": "REQUESTY_API_KEY",
          "baseUrl": "https://router.requesty.ai/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": {
      "protocol": "anthropic",
      "models": [
        {
          "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": {
      "protocol": "gemini",
      "models": [
        {
          "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 Auto-hospedados Locais (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": {
      "protocol": "openai",
      "models": [
        {
          "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 requerem autenticação, você pode usar qualquer valor de espaço reservado (placeholder) para a chave de API:

# 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 oferece 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 da configuração dos modelos.

Visão geral

Ao autenticar com uma chave de API do Alibaba Cloud Coding Plan usando o comando /auth, o Qwen Code configura automaticamente os seguintes modelos:

Configuração

1. Obtenha uma chave de API do Alibaba Cloud Coding Plan:
   • China: https://bailian.console.aliyun.com/?tab=model#/efm/coding_plan 
   • Internacional: https://modelstudio.console.alibabacloud.com/?tab=dashboard#/efm/coding_plan 
2. Execute o comando /auth no Qwen Code
3. Selecione Alibaba ModelStudio e, em seguida, escolha Coding Plan no submenu
4. Selecione sua região
5. Insira sua chave de API quando solicitado

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

Regiões

O Alibaba Cloud Coding Plan oferece suporte a duas regiões:

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

Armazenamento da chave de API

Ao configurar o Coding Plan por meio do comando /auth, a chave de API é 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-chave-de-api-aqui

Atualizações automáticas

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

• Substituir as configurações existentes dos modelos do Coding Plan pelas versões mais recentes
• Preservar quaisquer configurações de modelos personalizados 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 aos recursos de modelos 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": {
      "protocol": "openai",
      "models": [
        {
          "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/model/credential 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 de CLI substituem as configurações. Caso contrário, security.auth.selectedType ou o padrão implícito determinam o tipo de auth. Qwen OAuth e OpenAI são os únicos tipos de auth exibidos 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 ESTÁ selecionado (por exemplo, via comando /model escolhendo um modelo configurado pelo 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
   • 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

   Se um modelo estiver listado em modelProviders, coloque todas as configurações de geração específicas do modelo na entrada do provedor correspondente. Os valores de model.generationConfig de nível superior, incluindo contextWindowSize, modalities, customHeaders e extra_body, são ignorados para modelos do provedor. Configure esses campos em modelProviders[authType][].generationConfig para que sejam aplicados.

2. Quando NENHUM modelo modelProvider está selecionado (por exemplo, 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 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 de campos atômicos

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

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

Exemplo

// Configurações do usuário (~/.qwen/settings.json)
{
  "model": {
    "generationConfig": {
      "timeout": 30000,
      "samplingParams": { "temperature": 0.5, "max_tokens": 1000 }
    }
  }
}
 
// Configuração de modelProviders
{
  "modelProviders": {
    "openai": {
      "protocol": "openai",
      "models": [{
        "id": "gpt-4o",
        "envKey": "OPENAI_API_KEY",
        "generationConfig": {
          "timeout": 60000,
          "samplingParams": { "temperature": 0.2 }
        }
      }]
    }
  }
}

Quando gpt-4o é selecionado em modelProviders:

• timeout = 60000 (do provedor, sobrescreve as 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 — os campos são explicitamente definidos como undefined se não forem fornecidos)

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

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

A estratégia de mesclagem para o próprio modelProviders é REPLACE (substituir): 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.

Configuração de reasoning / thinking

O campo opcional reasoning em generationConfig controla o quão agressivamente o modelo raciocina antes de responder. Os conversores da Anthropic e do Gemini sempre o respeitam. O pipeline compatível com OpenAI o respeita a menos que generationConfig.samplingParams esteja definido — veja a ressalva “Interação com samplingParams” abaixo.

{
  "modelProviders": {
    "openai": {
      "protocol": "openai",
      "models": [
        {
          "id": "deepseek-v4-pro",
          "name": "DeepSeek V4 Pro",
          "baseUrl": "https://api.deepseek.com/v1",
          "envKey": "DEEPSEEK_API_KEY",
          "generationConfig": {
            // A escala de quatro níveis:
            //   'low'    | 'medium' — mapeado pelo servidor para 'high' no DeepSeek
            //   'high'   — intensidade de raciocínio padrão
            //   'max'    — nível extra-forte específico do DeepSeek
            // Ou defina como `false` para desativar o raciocínio completamente.
            "reasoning": { "effort": "max" },
          },
        },
      ],
    },
  },
}

Comportamento por provedor

reasoning: false

Definir reasoning: false (o booleano literal) desativa explicitamente o thinking em todos os provedores — útil para consultas secundárias baratas que não se beneficiam do raciocínio. Isso também é respeitado no nível da requisição via request.config.thinkingConfig.includeThoughts: false para chamadas pontuais (por exemplo, geração de sugestões).

Em um baseURL api.deepseek.com, o pipeline OpenAI emite o campo explícito thinking: { type: 'disabled' } que o DeepSeek V4+ exige — o padrão do lado do servidor é 'enabled', então simplesmente omitir reasoning_effort ainda incorreria em latência/custo de thinking. Backends DeepSeek auto-hospedados (sglang/vllm) e outros servidores compatíveis com OpenAI não recebem este campo; se você precisar desativar o thinking neles, injete thinking: { type: 'disabled' } (ou qualquer outro controle que seu framework de inferência exponha) via samplingParams/extra_body.

Interação com samplingParams (apenas compatível com OpenAI)

budget_tokens

Você pode fixar um orçamento exato de tokens de thinking incluindo budget_tokens junto com effort:

"reasoning": { "effort": "high", "budget_tokens": 50000 }

Para a Anthropic, isso se torna thinking.budget_tokens. Para OpenAI/DeepSeek, o campo é preservado, mas atualmente ignorado pelo servidor — reasoning_effort é o controle principal.

Provider Models vs Runtime Models

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

Provider Model

• 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 de comandos /model com metadados completos (nome, descrição, capacidades)
• Recomendado para fluxos de trabalho multimodelo e consistência da equipe

Runtime Model

• 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 → settings → defaults)
• Capturado automaticamente como um RuntimeModelSnapshot quando uma configuração completa é detectada
• Permite reutilização sem a necessidade de inserir as 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:

# Isso cria um RuntimeModelSnapshot com o ID: $runtime|openai|my-custom-model
qwen --auth-type openai --model my-custom-model --openai-api-key $KEY --openai-base-url 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 a execução)
• Aparece na lista de comandos /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 Provider Models quando: Você tem modelos padrão compartilhados em uma equipe, precisa de configurações consistentes ou deseja evitar substituições acidentais
• Use Runtime Models quando: Testando rapidamente um novo modelo, usando credenciais temporárias ou trabalhando 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, eles recorrem ao 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/settings, criando Runtime Models. Isso é adequado para configurações de provedor único, mas trabalhoso ao alternar com frequência. Defina catálogos de provedores sempre que fluxos de trabalho multimodelo forem comuns, para que as alternâncias permaneçam atômicas, com origem atribuída e depuráveis.