Configuração do Qwen Code

Camadas de configuração

A configuração é aplicada na seguinte ordem de precedência (níveis mais baixos são substituídos por níveis mais altos):

Arquivos de configurações

O Qwen Code usa arquivos de configuração no formato JSON para definições persistentes. Há quatro locais possíveis para esses arquivos:

O diretório .qwen no seu projeto

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

• Perfis personalizados de sandbox (por exemplo, .qwen/sandbox-macos-custom.sb, .qwen/sandbox.Dockerfile).
• Habilidades de Agente sob .qwen/skills/ (cada Habilidade é um diretório contendo um arquivo SKILL.md).

Migração de configuração

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

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

Quando ambas as configurações legadas estiverem presentes com valores diferentes, a migração seguirá esta política: se qualquer uma das configurações disableAutoUpdate ou disableUpdateNag for true, então enableAutoUpdate passará a ser false:

Configurações disponíveis em 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.

geral

saída

ui

ide

privacidade

modelo

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
      }
    }
  }
}

contextWindowSize:

Sobrescreve o tamanho padrão da janela de contexto para o modelo selecionado. O Qwen Code determina a janela de contexto usando valores padrão embutidos com base na correspondência do nome do modelo, com um valor constante como fallback. Use esta configuração quando o limite efetivo de contexto do provedor diferir do padrão do Qwen Code. Esse valor define a capacidade máxima assumida de contexto do modelo, não um limite de tokens por requisição.

modalities:

Sobrescreve 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ões no nome do modelo. Use esta configuração quando a detecção automática estiver incorreta — por exemplo, para habilitar pdf em um modelo que o suporta, mas não é reconhecido. Formato: { "image": true, "pdf": true, "audio": true, "video": true }. Omita uma chave ou defina-a como false para tipos não suportados.

customHeaders:

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

O campo extra_body permite adicionar parâmetros personalizados ao corpo da requisiçã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. Observação: Este campo é suportado apenas por provedores compatíveis com OpenAI (openai, qwen-oauth). Ele é ignorado por provedores Anthropic e Gemini. Se extra_body for definido em modelProviders[].generationConfig.extra_body, ele será usado diretamente; caso contrário, os valores de model.generationConfig.extra_body serão utilizados.

Exemplos de model.openAILoggingDir:

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

contexto

Solução de Problemas de Desempenho na Pesquisa de Arquivos

Se você estiver enfrentando problemas de desempenho ao pesquisar arquivos (por exemplo, com as conclusões @), especialmente em projetos com um número muito grande de arquivos, experimente as seguintes soluções, listadas na ordem recomendada:

1. Use .qwenignore: Crie um arquivo .qwenignore na raiz do seu projeto para excluir diretórios que contenham um grande número de arquivos desnecessários para referência (por exemplo, artefatos de build, logs, node_modules). Reduzir o número total de arquivos analisados é a maneira mais eficaz de melhorar o desempenho.
2. Desative a Pesquisa Difusa (Fuzzy Search): Se ignorar arquivos não for suficiente, você pode desativar a pesquisa difusa definindo enableFuzzySearch como false no seu arquivo settings.json. Isso usará um algoritmo de correspondência mais simples e não difuso, o que pode ser mais rápido.
3. Desative a Pesquisa Recursiva de Arquivos: Como último recurso, você pode desativar totalmente a pesquisa recursiva de arquivos definindo enableRecursiveFileSearch como false. Essa será a opção mais rápida, pois evita a análise recursiva do seu projeto. No entanto, isso significa que você precisará digitar o caminho completo dos arquivos ao usar as conclusões @.

ferramentas

mcp

lsp

[!warning] Funcionalidade Experimental: O suporte a LSP está atualmente em fase experimental e desabilitado por padrão. Habilite-o usando a flag 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 por meio de arquivos .lsp.json no diretório raiz do seu projeto, e não através do arquivo settings.json. Consulte a documentação do LSP para obter detalhes de configuração e exemplos.

segurança

avançado

mcpServers

Configura conexões com um ou mais servidores do Model-Context Protocol (MCP) para descobrir e usar ferramentas personalizadas. O Qwen Code tenta se conectar a cada servidor MCP configurado para descobrir as ferramentas disponíveis. Se vários servidores MCP expuserem uma ferramenta com o mesmo nome, os nomes das ferramentas serão prefixados com o apelido do servidor definido na configuração (por exemplo, apelidoDoServidor__nomeRealDaFerramenta) para evitar conflitos. Observe que o sistema pode remover certas propriedades de esquema das definições de ferramentas MCP por questões de compatibilidade. Pelo menos uma das propriedades command, url ou httpUrl deve ser fornecida. Se várias forem especificadas, a ordem de precedência é httpUrl, seguida de url, seguida de command.

telemetria

Configura o registro de logs e a coleta de métricas para o Qwen Code. Para obter mais informações, consulte telemetria.

Exemplo de settings.json

Abaixo está um exemplo de arquivo settings.json com a estrutura aninhada, nova a partir da versão 0.3.0:

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  },
  "ui": {
    "theme": "GitHub",
    "hideTips": false,
    "customWittyPhrases": [
      "Você esquece mil coisas todos os dias. Certifique-se de que esta é uma delas",
      "Conectando-se à AGI"
    ]
  },
  "tools": {
    "approvalMode": "yolo",
    "sandbox": "docker",
    "discoveryCommand": "bin/get_tools",
    "callCommand": "bin/call_tool",
    "exclude": ["write_file"]
  },
  "mcpServers": {
    "mainServer": {
      "command": "bin/mcp_server.py"
    },
    "anotherServer": {
      "command": "node",
      "args": ["mcp_server.js", "--verbose"]
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "http://localhost:4317",
    "logPrompts": true
  },
  "privacy": {
    "usageStatisticsEnabled": true
  },
  "model": {
    "name": "qwen3-coder-plus",
    "maxSessionTurns": 10,
    "enableOpenAILogging": false,
    "openAILoggingDir": "~/qwen-logs",
  },
  "context": {
    "fileName": ["CONTEXT.md", "QWEN.md"],
    "includeDirectories": ["path/to/dir1", "~/path/to/dir2", "../path/to/dir3"],
    "loadFromIncludeDirectories": true,
    "fileFiltering": {
      "respectGitIgnore": false
    }
  },
  "advanced": {
    "excludedEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"]
  }
}

Histórico do Shell

A CLI mantém um histórico dos comandos de shell que você executa. Para evitar conflitos entre diferentes projetos, esse histórico é armazenado em um diretório específico do projeto dentro da pasta inicial do seu usuário.

• Localização: ~/.qwen/tmp/<project_hash>/shell_history
  • <project_hash> é um identificador exclusivo gerado a partir do caminho raiz do seu projeto.
  • O histórico é armazenado em um arquivo chamado shell_history.

Variáveis de ambiente e arquivos .env

Variáveis de ambiente são uma forma comum de configurar aplicações, especialmente para informações sensíveis (como tokens) ou para configurações que podem variar entre ambientes.

O Qwen Code pode carregar automaticamente variáveis de ambiente a partir de arquivos .env.

Para variáveis relacionadas à autenticação (como OPENAI_*) e para a abordagem recomendada com o arquivo .qwen/.env, consulte Autenticação.

Tabela de Variáveis de Ambiente

Argumentos de Linha de Comando

Argumentos passados diretamente ao executar a CLI podem substituir outras configurações para aquela sessão específica.

Tabela de Argumentos de Linha de Comando

Arquivos de Contexto (Contexto Instrucional Hierárquico)

Embora não sejam, estritamente falando, uma configuração do comportamento da CLI, os arquivos de contexto (que, por padrão, têm o nome QWEN.md, mas podem ser configurados via a opção context.fileName) são fundamentais para configurar o contexto instrucional (também chamado de “memória”). Esse recurso poderoso permite fornecer ao modelo instruções específicas do projeto, diretrizes de estilo de codificação ou qualquer outra informação de fundo relevante, tornando as respostas da IA mais personalizadas e precisas às suas necessidades. A CLI inclui elementos de interface, como um indicador no rodapé que mostra a quantidade de arquivos de contexto carregados, para mantê-lo informado sobre o contexto ativo.

• Finalidade: Esses arquivos em Markdown contêm instruções, diretrizes ou informações contextuais que você deseja que o modelo Qwen conheça durante suas interações. O sistema foi projetado para gerenciar esse contexto instrucional de forma hierárquica.

Exemplo de Conteúdo de Arquivo de Contexto (por exemplo, QWEN.md)

Abaixo está um exemplo conceitual do que um arquivo de contexto na raiz de um projeto TypeScript pode conter:

# Projeto: Minha Incrível Biblioteca TypeScript

## Instruções Gerais:
- Ao gerar novo código TypeScript, siga o estilo de codificação já existente.
- Certifique-se de que todas as novas funções e classes tenham comentários JSDoc.
- Prefira paradigmas de programação funcional quando apropriado.
- Todo o código deve ser compatível com TypeScript 5.0 e Node.js 20+.

## Estilo de Codificação:
- Use 2 espaços para indentação.
- Nomes de interfaces devem começar com `I` (por exemplo, `IUserService`).
- Membros privados de classes devem começar com um sublinhado (`_`).
- Sempre use igualdade estrita (`===` e `!==`).

## Componente Específico: `src/api/client.ts`
- Este arquivo lida com todas as requisições de API de saída.
- Ao adicionar novas funções de chamada de API, certifique-se de que incluam tratamento robusto de erros e registro (logging).
- Use o utilitário existente `fetchWithRetry` para todas as requisições GET.

## Sobre Dependências:
- Evite introduzir novas dependências externas, a menos que sejam absolutamente necessárias.
- Se uma nova dependência for necessária, especifique o motivo.

Este exemplo demonstra como você pode fornecer um contexto geral do projeto, convenções específicas de codificação e até mesmo observações sobre arquivos ou componentes particulares. Quanto mais relevantes e precisos forem seus arquivos de contexto, melhor o assistente de IA poderá ajudá-lo. Arquivos de contexto específicos do projeto são altamente recomendados para estabelecer convenções e contexto.

• Carregamento Hierárquico e Precedência: A CLI implementa um sistema hierárquico de memória ao carregar arquivos de contexto (por exemplo, QWEN.md) de diversos locais. O conteúdo dos arquivos listados abaixo (mais específicos) normalmente substitui ou complementa o conteúdo dos arquivos listados acima (mais gerais). A ordem exata de concatenação e o contexto final podem ser inspecionados usando o comando /memory show. A ordem típica de carregamento é:
  1. Arquivo de Contexto Global:
     • Localização: ~/.qwen/<nome-do-arquivo-de-contexto-configurado> (por exemplo, ~/.qwen/QWEN.md no diretório home do usuário).
     • Escopo: Fornece instruções padrão para todos os seus projetos.
  2. Arquivos de Contexto da Raiz do Projeto e de Diretórios Ancestrais:
     • Localização: A CLI procura pelo arquivo de contexto configurado no diretório de trabalho atual e, em seguida, em cada diretório pai até encontrar a raiz do projeto (identificada por uma pasta .git) ou o diretório home do usuário.
     • Escopo: Fornece contexto relevante para o projeto inteiro ou para uma parte significativa dele.
• Concatenação e Indicação na Interface do Usuário: O conteúdo de todos os arquivos de contexto encontrados é concatenado (com separadores indicando sua origem e caminho) e fornecido como parte do prompt do sistema. O rodapé da CLI exibe a contagem de arquivos de contexto carregados, oferecendo uma indicação visual rápida sobre o contexto instrucional ativo.
• Importação de Conteúdo: Você pode modularizar seus arquivos de contexto importando outros arquivos Markdown usando a sintaxe @caminho/para/arquivo.md. Para mais detalhes, consulte a documentação do Processador de Importação de Memória.
• Comandos para Gerenciamento de Memória:
  • Use /memory refresh para forçar uma nova verificação e recarregamento de todos os arquivos de contexto de todos os locais configurados. Isso atualiza o contexto instrucional do assistente de IA.
  • Use /memory show para exibir o contexto instrucional combinado atualmente carregado, permitindo que você verifique a hierarquia e o conteúdo sendo utilizado pelo assistente de IA.
  • Consulte a documentação de Comandos para obter detalhes completos sobre o comando /memory e seus subcomandos (show e refresh).

Ao compreender e utilizar essas camadas de configuração e a natureza hierárquica dos arquivos de contexto, você pode gerenciar efetivamente a memória do assistente de IA e personalizar as respostas do Qwen Code conforme suas necessidades e projetos específicos.

Sandbox

O Qwen Code pode executar operações potencialmente inseguras (como comandos de shell e modificações de arquivos) dentro de um ambiente isolado (sandbox) para proteger seu sistema.

O Sandbox está desabilitado por padrão, mas você pode habilitá-lo de algumas maneiras:

• Usando a flag --sandbox ou -s.
• Definindo a variável de ambiente QWEN_SANDBOX.
• O sandbox é habilitado automaticamente ao usar --yolo ou --approval-mode=yolo.

Por padrão, ele usa uma imagem Docker pré-construída chamada qwen-code-sandbox.

Para necessidades específicas de sandboxing em projetos, você pode criar um Dockerfile personalizado em .qwen/sandbox.Dockerfile no diretório raiz do seu projeto. Esse Dockerfile pode ser baseado na imagem base do sandbox:

FROM qwen-code-sandbox

# Adicione aqui suas dependências ou configurações personalizadas

# Por exemplo:

# RUN apt-get update && apt-get install -y some-package

COPIAR ./my-config /app/my-config

Quando o arquivo `.qwen/sandbox.Dockerfile` existir, você pode usar a variável de ambiente `BUILD_SANDBOX` ao executar o Qwen Code para criar automaticamente a imagem personalizada do sandbox:

BUILD_SANDBOX=1 qwen -s

## Estatísticas de Uso

Para nos ajudar a melhorar o Qwen Code, coletamos estatísticas de uso anonimizadas. Esses dados nos ajudam a entender como a CLI é utilizada, identificar problemas comuns e priorizar novos recursos.

**O que coletamos:**

- **Chamadas de Ferramentas:** Registramos os nomes das ferramentas chamadas, se tiveram sucesso ou falharam e quanto tempo levaram para ser executadas. Não coletamos os argumentos passados para as ferramentas nem quaisquer dados retornados por elas.
- **Solicitações à API:** Registramos o modelo usado em cada solicitação, a duração da solicitação e se ela foi bem-sucedida. Não coletamos o conteúdo dos prompts nem das respostas.
- **Informações da Sessão:** Coletamos informações sobre a configuração da CLI, como as ferramentas habilitadas e o modo de aprovação.

**O que NÃO coletamos:**

- **Informações Pessoalmente Identificáveis (PII):** Não coletamos nenhuma informação pessoal, como seu nome, endereço de e-mail ou chaves de API.
- **Conteúdo de Prompts e Respostas:** Não registramos o conteúdo dos seus prompts nem das respostas do modelo.
- **Conteúdo de Arquivos:** Não registramos o conteúdo de quaisquer arquivos lidos ou gravados pela CLI.

**Como recusar a coleta:**

Você pode desativar a coleta de estatísticas de uso a qualquer momento definindo a propriedade `usageStatisticsEnabled` como `false` na categoria `privacy` do seu arquivo `settings.json`:

{ “privacy”: { “usageStatisticsEnabled”: false } }

> [!note]
>
> Quando as estatísticas de uso estão habilitadas, os eventos são enviados a um endpoint de coleta RUM da Alibaba Cloud.