Configuração do Qwen Code

Camadas de configuração

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

Arquivos de configurações

O Qwen Code utiliza arquivos de configuração em formato JSON para armazenar configurações persistentes. Existem 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 à operação do Qwen Code, como:

• Perfis personalizados de sandbox (por exemplo, .qwen/sandbox-macos-custom.sb, .qwen/sandbox.Dockerfile).

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 da categoria correspondente no nível superior no seu arquivo settings.json.

geral

output

ui

ide

privacidade

model

Exemplo de model.generationConfig:

{
  "model": {
    "generationConfig": {
      "timeout": 60000,
      "disableCacheControl": false,
      "samplingParams": {
        "temperature": 0.2,
        "top_p": 0.8,
        "max_tokens": 1024
      }
    }
  }
}

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

context

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

Se você estiver enfrentando problemas de desempenho na pesquisa de arquivos (por exemplo, com os recursos de autocompletar usando @), 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 contenham um grande número de arquivos que você não precisa referenciar (por exemplo, artefatos de build, logs, node_modules). Reduzir o número total de arquivos indexados é a forma mais eficaz de melhorar o desempenho.
2. Desative a Pesquisa Aproximada (Fuzzy Search): Se ignorar arquivos não for suficiente, você pode desativar a pesquisa aproximada definindo disableFuzzySearch como true no seu arquivo settings.json. Isso fará com que uma lógica de correspondência mais simples e não aproximada seja usada, o que pode ser mais rápido.
3. Desative a Pesquisa Recursiva de Arquivos: Como último recurso, você pode desativar completamente a pesquisa recursiva de arquivos definindo enableRecursiveFileSearch como false. Essa será a opção mais rápida, pois evita uma varredura recursiva do seu projeto. No entanto, isso significa que você precisará digitar o caminho completo dos arquivos ao usar os recursos de autocompletar com @.

tools

mcp

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 alias do servidor definido na configuração (por exemplo, serverAlias__actualToolName) para evitar conflitos. Observe que o sistema pode remover certas propriedades de esquema das definições de ferramentas MCP para fins de compatibilidade. Pelo menos uma das opções command, url ou httpUrl deve ser fornecida. Se várias forem especificadas, a ordem de precedência é httpUrl, depois url e, por fim, command.

telemetry

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

Exemplo de settings.json

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

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  },
  "ui": {
    "theme": "GitHub",
    "hideBanner": true,
    "hideTips": false,
    "customWittyPhrases": [
      "Você esquece mil coisas por dia. Certifique-se de que esta é uma delas",
      "Conectando à 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",
    "summarizeToolOutput": {
      "run_shell_command": {
        "tokenBudget": 100
      }
    }
  },
  "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 do 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 home do seu usuário.

• Localização: ~/.qwen/tmp/<project_hash>/shell_history
  • <project_hash> é um identificador único 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 mudar entre ambientes.

O Qwen Code pode carregar automaticamente variáveis de ambiente de arquivos .env. Para variáveis relacionadas à autenticação (como OPENAI_*) e a abordagem recomendada com .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 da Linha de Comando

Arquivos de Contexto (Contexto Instrucional Hierárquico)

Embora não sejam estritamente uma configuração para o comportamento da CLI, os arquivos de contexto (por padrão QWEN.md, mas configuráveis através da opção context.fileName) são essenciais para configurar o contexto instrucional (também chamado de “memória”). Este recurso poderoso permite que você forneça instruções específicas do projeto, guias de estilo de codificação ou qualquer informação relevante ao modelo de IA, tornando suas respostas mais adaptadas e precisas às suas necessidades. A CLI inclui elementos de interface, como um indicador no rodapé mostrando o número de arquivos de contexto carregados, mantendo você informado sobre o contexto ativo.

• Propósito: Esses arquivos Markdown contêm instruções, diretrizes ou contexto que você deseja que o modelo Qwen leve em consideração durante as interações. O sistema é projetado para gerenciar esse contexto instrucional de forma hierárquica.

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

Aqui 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 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 ser prefixados com `I` (por exemplo, `IUserService`).
- Membros privados de classe devem ser prefixados 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 incluir tratamento de erro robusto e registro em log.
- Use o utilitário `fetchWithRetry` existente para todas as requisições GET.

## Sobre Dependências:
- Evite introduzir novas dependências externas, a menos que seja absolutamente necessário.
- Se uma nova dependência for necessária, por favor, informe o motivo.

Este exemplo demonstra como você pode fornecer 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 a 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 sofisticado de memória carregando arquivos de contexto (por exemplo, QWEN.md) de diversos locais. O conteúdo dos arquivos mais abaixo nesta lista (mais específicos) geralmente substitui ou complementa o conteúdo dos arquivos mais 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 Ancestrais:
     • Localização: A CLI procura pelo arquivo de contexto configurado no diretório de trabalho atual e depois em cada diretório pai até encontrar a raiz do projeto (identificada por uma pasta .git) ou seu diretório home.
     • Escopo: Fornece contexto relevante para todo o projeto ou uma parte significativa dele.
  3. Arquivos de Contexto de Subdiretórios (Contextuais/Locais):
     • Localização: A CLI também verifica a existência do arquivo de contexto configurado em subdiretórios abaixo do diretório de trabalho atual (respeitando padrões comuns de exclusão como node_modules, .git, etc.). A amplitude desta busca é limitada a 200 diretórios por padrão, mas pode ser configurada com a opção context.discoveryMaxDirs no seu arquivo settings.json.
     • Escopo: Permite instruções altamente específicas relevantes para um componente, módulo ou subseção específica do seu projeto.
• Concatenação e Indicação na Interface: 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 mostra 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/o/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 recarregar todos os arquivos de contexto de todos os locais configurados. Isso atualiza o contexto instrucional da IA.
  • Use /memory show para exibir o contexto instrucional combinado atualmente carregado, permitindo verificar a hierarquia e o conteúdo utilizado pela 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 da IA e personalizar as respostas do Qwen Code de acordo com suas necessidades e projetos específicos.

Sandbox

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

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

• Usando a flag --sandbox ou -s.
• Definindo a variável de ambiente GEMI_SANDBOX.
• O sandbox é ativado por padrão ao usar --yolo ou --approval-mode=yolo.

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

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

FROM qwen-code-sandbox

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

# Por exemplo:

# RUN apt-get update && apt-get install -y algum-pacote

# COPY ./my-config /app/my-config

Quando .qwen/sandbox.Dockerfile existir, você pode usar a variável de ambiente BUILD_SANDBOX ao executar o Qwen Code para construir 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 elas foram bem-sucedidas ou falharam e quanto tempo levaram para serem executadas. Não coletamos os argumentos passados para as ferramentas nem nenhum dado retornado por elas.
• Requisições de API: Registramos o modelo usado em cada requisição, a duração da requisição e se ela foi bem-sucedida. Não coletamos o conteúdo dos prompts ou 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 ou das respostas do modelo.
• Conteúdo de Arquivos: Não registramos o conteúdo de nenhum arquivo lido ou escrito pela CLI.

Como desativar:

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