Configuração do Qwen Code

Camadas de configuração

A configuração é aplicada na seguinte ordem de precedência (números menores são substituídos por números maiores):

Arquivos de configuração

O Qwen Code usa arquivos de configuração JSON para configurações persistentes. Existem quatro locais para esses arquivos:

O diretório .qwen no seu projeto

Além de um arquivo de configuração do projeto, o diretório .qwen de um projeto pode conter outros arquivos específicos do projeto relacionados à operação do Qwen Code, como:

• Perfis de sandbox personalizados (ex.: .qwen/sandbox-macos-custom.sb, .qwen/sandbox.Dockerfile).
• Skills de Agente em .qwen/skills/ (cada Skill é um diretório contendo um SKILL.md).

Migração de configuração

O Qwen Code migra automaticamente configurações legadas para o novo formato. Os arquivos de configuração antigos são salvos como backup antes da migração. As seguintes configurações foram renomeadas de nomenclatura negativa (disable*) para positiva (enable*):

Política de consolidação para disableAutoUpdate e disableUpdateNag

Quando ambas as configurações legadas estão presentes com valores diferentes, a migração segue esta política: se qualquer uma (disableAutoUpdate ou disableUpdateNag) for true, então enableAutoUpdate se torna false:

Configurações disponíveis no settings.json

As configurações são organizadas em categorias. Todas as configurações devem ser colocadas dentro do objeto de categoria de nível superior correspondente no seu arquivo settings.json.

general

output

ui

ide

privacy

model

Exemplo de model.generationConfig:

{
  "model": {
    "generationConfig": {
      "timeout": 60000,
      "contextWindowSize": 128000,
      "modalities": {
        "image": true
      },
      "enableCacheControl": true,
      "customHeaders": {
        "X-Client-Request-ID": "req-123"
      },
      "extra_body": {
        "enable_thinking": true
      },
      "samplingParams": {
        "temperature": 0.2,
        "top_p": 0.8,
        "max_tokens": 1024
      }
    }
  }
}

max_tokens (tokens de saída adaptativos):

Quando samplingParams.max_tokens não está definido, o Qwen Code usa uma estratégia adaptativa de tokens de saída para otimizar o uso de recursos da GPU:

1. As solicitações começam com um limite padrão de 8K tokens de saída
2. Se a resposta for truncada (o modelo atinge o limite), o Qwen Code tenta novamente automaticamente com 64K tokens
3. A saída parcial é descartada e substituída pela resposta completa da nova tentativa

Isso é transparente para os usuários — você pode ver brevemente um indicador de nova tentativa se a escalação ocorrer. Como 99% das respostas têm menos de 5K tokens, a nova tentativa acontece raramente (<1% das solicitações).

Para substituir esse comportamento, defina samplingParams.max_tokens nas suas configurações ou use a variável de ambiente QWEN_CODE_MAX_OUTPUT_TOKENS.

contextWindowSize:

Substitui o tamanho padrão da janela de contexto para o modelo selecionado. O Qwen Code determina a janela de contexto usando padrões internos com base na correspondência do nome do modelo, com um valor de fallback constante. Use esta configuração quando o limite de contexto efetivo de um provedor diferir do padrão do Qwen Code. Este valor define a capacidade máxima de contexto assumida pelo modelo, não um limite de tokens por solicitação.

modalities:

Substitui as modalidades de entrada detectadas automaticamente para o modelo selecionado. O Qwen Code detecta automaticamente as modalidades suportadas (imagem, PDF, áudio, vídeo) com base na correspondência de padrão do nome do modelo. Use esta configuração quando a detecção automática estiver incorreta — por exemplo, para ativar pdf para um modelo que o suporta, mas não é reconhecido. Formato: { "image": true, "pdf": true, "audio": true, "video": true }. Omita uma chave ou defina como false para tipos não suportados.

customHeaders:

Permite adicionar cabeçalhos HTTP personalizados a todas as solicitações de API. Isso é útil para rastreamento de solicitações, monitoramento, roteamento de gateway de API ou quando diferentes modelos exigem cabeçalhos diferentes. Se customHeaders estiver definido em modelProviders[].generationConfig.customHeaders, ele será usado diretamente; caso contrário, os cabeçalhos de model.generationConfig.customHeaders serão usados. Não ocorre mesclagem entre os dois níveis.

O campo extra_body permite adicionar parâmetros personalizados ao corpo da solicitação enviada à API. Isso é útil para opções específicas do provedor que não são cobertas pelos campos de configuração padrão. Nota: Este campo é suportado apenas para provedores compatíveis com OpenAI (openai, qwen-oauth). É ignorado para provedores Anthropic e Gemini. Se extra_body estiver definido em modelProviders[].generationConfig.extra_body, ele será usado diretamente; caso contrário, os valores de model.generationConfig.extra_body serão usados.

Exemplos de model.openAILoggingDir:

• "~/qwen-logs" - Registra no diretório ~/qwen-logs
• "./custom-logs" - Registra em ./custom-logs relativo ao diretório atual
• "/tmp/openai-logs" - Registra no caminho absoluto /tmp/openai-logs

fastModel

context

Solução de problemas de desempenho na busca de arquivos

Se você estiver enfrentando problemas de desempenho na busca de arquivos (ex.: com conclusões @), especialmente em projetos com um número muito grande de arquivos, aqui estão algumas coisas que você pode tentar, em ordem de recomendação:

1. Use .qwenignore: Crie um arquivo .qwenignore na raiz do seu projeto para excluir diretórios que contêm um grande número de arquivos que você não precisa referenciar (ex.: artefatos de build, logs, node_modules). Reduzir o número total de arquivos indexados é a maneira mais eficaz de melhorar o desempenho.
2. Desative a Busca Fuzzy: Se ignorar arquivos não for suficiente, você pode desativar a busca fuzzy definindo enableFuzzySearch como false no seu arquivo settings.json. Isso usará um algoritmo de correspondência mais simples e não fuzzy, que pode ser mais rápido.
3. Desative a Busca Recursiva de Arquivos: Como último recurso, você pode desativar completamente a busca recursiva de arquivos definindo enableRecursiveFileSearch como false. Esta será a opção mais rápida, pois evita uma varredura recursiva do seu projeto. No entanto, significa que você precisará digitar o caminho completo dos arquivos ao usar conclusões @.

tools

permissions

O sistema de permissões fornece controle granular sobre quais ferramentas podem ser executadas, quais exigem confirmação e quais são bloqueadas.

Prioridade de decisão (maior primeiro): deny > ask > allow > (padrão/modo interativo)

A primeira regra correspondente vence. As regras usam o formato "ToolName" ou "ToolName(specifier)".

Aliases de nome de ferramenta (qualquer um destes funciona nas regras):

Meta-categorias:

Alguns nomes de regras cobrem automaticamente várias ferramentas:

[!important] Read(/path/**) corresponde a todas as quatro ferramentas de leitura (leitura de arquivo, grep, glob e listagem de diretório). Para restringir apenas a leitura de arquivos, use ReadFile(/path/**) ou read_file(/path/**).

Exemplos de sintaxe de regras:

Prefixos de padrão de caminho:

Prevenção de bypass de comando shell:

As regras de permissão para Read, Edit e WebFetch também são aplicadas quando o agente executa comandos shell equivalentes. Por exemplo, se Read(./.env) estiver em deny, o agente não pode ignorá-lo via cat .env em um comando shell. Comandos shell suportados incluem cat, grep, curl, wget, cp, mv, rm, chmod e muitos outros. Comandos desconhecidos/seguros (ex.: git) não são afetados pelas regras de arquivo/rede.

Migrando de configurações legadas:

Exemplo de configuração:

{
  "permissions": {
    "allow": ["Bash(git *)", "Bash(npm run *)", "Read(//Users/alice/code/**)"],
    "ask": ["Bash(git push *)", "Edit"],
    "deny": ["Bash(rm -rf *)", "Read(.env)", "WebFetch(malicious.com)"]
  }
}

[!tip] Use /permissions na CLI interativa para visualizar, adicionar e remover regras sem editar o settings.json diretamente.

mcp

lsp

[!warning] Recurso Experimental: O suporte a LSP é atualmente experimental e desativado por padrão. Ative-o usando o sinalizador de linha de comando --experimental-lsp.

O Language Server Protocol (LSP) fornece recursos de inteligência de código como ir para definição, encontrar referências e diagnósticos.

A configuração do servidor LSP é feita através de arquivos .lsp.json no diretório raiz do seu projeto, não através do settings.json. Consulte a documentação do LSP para detalhes e exemplos de configuração.

security

advanced

mcpServers

Configura conexões com um ou mais servidores Model-Context Protocol (MCP) para descobrir e usar ferramentas personalizadas. O Qwen Code tenta se conectar a cada servidor MCP configurado para descobrir ferramentas disponíveis. Se vários servidores MCP expuserem uma ferramenta com o mesmo nome, os nomes das ferramentas serão prefixados com o alias do servidor que você definiu na configuração (ex.: serverAlias__actualToolName) para evitar conflitos. Observe que o sistema pode remover certas propriedades de schema das definições de ferramentas MCP para compatibilidade. Pelo menos um de command, url ou httpUrl deve ser fornecido. Se vários forem especificados, a ordem de precedência é httpUrl, depois url, depois command.