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ções

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

O diretório .qwen em 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, tais como:

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

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 de nível superior correspondente em seu arquivo settings.json.

geral

output

ui

ide

privacidade

modelo

Exemplo model.generationConfig:

{
  "model": {
    "generationConfig": {
      "timeout": 60000,
      "disableCacheControl": false,
      "customHeaders": {
        "X-Request-ID": "req-123",
        "X-User-ID": "user-456"
      },
      "samplingParams": {
        "temperature": 0.2,
        "top_p": 0.8,
        "max_tokens": 1024
      }
    }
  }
}

O campo customHeaders permite adicionar cabeçalhos HTTP personalizados a todas as requisições de API. Isso é útil para rastreamento de requisiçõ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, serão usados os cabeçalhos de model.generationConfig.customHeaders. Não ocorre mesclagem entre os dois níveis.

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

modelProviders

Use modelProviders para declarar listas de modelos curadas por tipo de autenticação que o seletor /model pode alternar. As chaves devem ser tipos de autenticação válidos (openai, anthropic, gemini, vertex-ai, 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 tempo de execução as lê de process.env[envKey]. Os modelos OAuth da Qwen permanecem codificados e não podem ser substituídos.

Exemplo

{
  "modelProviders": {
    "openai": [
      {
        "id": "gpt-4o",
        "name": "GPT-4o",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1",
        "generationConfig": {
          "timeout": 60000,
          "maxRetries": 3,
          "customHeaders": {
            "X-Model-Version": "v1.0",
            "X-Request-Priority": "high"
          },
          "samplingParams": { "temperature": 0.2 }
        }
      }
    ],
    "anthropic": [
      {
        "id": "claude-3-5-sonnet",
        "envKey": "ANTHROPIC_API_KEY",
        "baseUrl": "https://api.anthropic.com/v1"
      }
    ],
    "gemini": [
      {
        "id": "gemini-2.0-flash",
        "name": "Gemini 2.0 Flash",
        "envKey": "GEMINI_API_KEY",
        "baseUrl": "https://generativelanguage.googleapis.com"
      }
    ],
    "vertex-ai": [
      {
        "id": "gemini-1.5-pro-vertex",
        "envKey": "GOOGLE_API_KEY",
        "baseUrl": "https://generativelanguage.googleapis.com"
      }
    ]
  }
}

[!note] Apenas o comando /model expõe tipos de autenticação não padrão. Anthropic, Gemini, Vertex AI, etc., devem ser definidos via modelProviders. O comando /auth lista intencionalmente apenas os fluxos OAuth embutidos do Qwen e OpenAI.

Camadas de resolução e atomicidade

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

*Quando presentes, as flags de autenticação 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 exibidos sem configuração adicional.

Valores provenientes do provedor de modelo são aplicados atomicamente: uma vez que um modelo de provedor está ativo, todos os campos que ele define são protegidos contra camadas inferiores até que você limpe manualmente as credenciais via /auth. A generationConfig final é a projeção entre todas as camadas—camadas inferiores apenas preenchem lacunas deixadas pelas superiores, e a camada do provedor permanece intransponível.

A estratégia de mesclagem para modelProviders é 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.

Camadas de configuração de geração

Precedência por campo para generationConfig:

1. Substituições programáticas (por exemplo, alterações em tempo de execução em /model, /auth)
2. modelProviders[authType][].generationConfig
3. settings.model.generationConfig
4. Padrões do gerador de conteúdo (getDefaultGenerationConfig para OpenAI, getParameterValue para Gemini, etc.)

samplingParams e customHeaders são tratados atomicamente; os valores do provedor substituem o objeto inteiro. Se modelProviders[].generationConfig definir esses campos, eles serão usados diretamente; caso contrário, serão utilizados os valores de model.generationConfig. Não ocorre mesclagem entre os níveis de configuração do provedor e global. Os padrões do gerador de conteúdo são aplicados por último, de forma que cada provedor mantenha sua linha de base ajustada.

Persistência de seleção e recomendações

[!important] Defina modelProviders no escopo do usuário em ~/.qwen/settings.json sempre que possível e evite persistir substituições de credenciais em qualquer escopo. Manter o catálogo de provedores nas configurações do usuário evita conflitos de mesclagem/substituição entre os escopos de projeto e usuário e garante que atualizações em /auth e /model sejam sempre escritas de volta para um escopo consistente.

• /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, 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 camadas CLI/env/configurações, o que é adequado para configurações de único provedor, 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, atribuídas por fonte e depuráveis.

contexto

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

Se você estiver enfrentando problemas de desempenho com a pesquisa de arquivos (por exemplo, com preenchimentos automáticos usando @), especialmente em projetos com um número muito grande de arquivos, aqui estão algumas coisas que você pode tentar, por 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 dos quais você não precisa fazer referência (por exemplo, artefatos de compilação, logs, node_modules). Reduzir o número total de arquivos pesquisados é a maneira mais eficaz de melhorar o desempenho.
2. Desative a Pesquisa Difusa: Se ignorar arquivos não for suficiente, você pode desativar a pesquisa difusa definindo disableFuzzySearch como true no seu arquivo settings.json. Isso usará um algoritmo de correspondência mais simples e não difuso, 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. Esta 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 preenchimentos automáticos com @.

ferramentas

mcp

segurança

avançado

experimental

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 exporem uma ferramenta com o mesmo nome, os nomes das ferramentas serão prefixados com o alias do servidor que você definiu 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 por compatibilidade. Pelo menos um dos campos command, url ou httpUrl deve ser fornecido. Se múltiplos forem especificados, a ordem de precedência é httpUrl, depois url, e então command.

telemetria

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

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",
    "hideTips": false,
    "customWittyPhrases": [
      "Você esquece milhares de coisas todos os dias. Certifique-se de que esta seja uma delas",
      "Conectando ao 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 inicial 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 maneira 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 de .qwen/.env, veja 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 uma configuração para o comportamento da CLI, os arquivos de contexto (cujo nome padrão é QWEN.md, mas pode ser configurado através da opção context.fileName) são cruciais 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, para mantê-lo informado sobre o contexto ativo.

• Finalidade: Esses arquivos Markdown contêm instruções, diretrizes ou contexto que você deseja que o modelo Qwen tenha em mente 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)

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

# Projeto: Minha Biblioteca TypeScript Incrível

## Instruções Gerais:
- Ao gerar novo código TypeScript, siga o estilo de codificação existente.
- Garanta 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 ter o prefixo `I` (por exemplo, `IUserService`).
- Membros privados de classes devem ter o prefixo sublinhado (`_`).
- Sempre utilize 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, garanta que elas incluam tratamento robusto de erros e logging.
- Utilize o utilitário existente `fetchWithRetry` 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 justifique o motivo.

Este exemplo demonstra como você pode fornecer contexto geral do projeto, convenções específicas de codificação e até notas 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 encorajados 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 (ex: `QWEN.md`) de diversos locais. O conteúdo de arquivos mais abaixo nesta lista (mais específicos) normalmente substitui ou complementa o conteúdo de arquivos 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-arquivo-configurado-contexto>` (ex: `~/.qwen/QWEN.md` no seu diretório home de usuário).
     - Escopo: Fornece instruções padrão para todos os seus projetos.
  2. **Arquivos de Contexto da Raiz do Projeto & Ancestrais:**
     - Localização: A CLI busca pelo arquivo de contexto configurado no diretório de trabalho atual e então em cada diretório pai até chegar à raiz do projeto (identificada por uma pasta `.git`) ou ao seu diretório home.
     - Escopo: Fornece contexto relevante para todo o projeto ou uma parte significativa dele.
- **Concatenação & Indicação na UI:** Os conteúdos de todos os arquivos de contexto encontrados são concatenados (com separadores indicando sua origem e caminho) e fornecidos como parte do prompt do sistema. O rodapé da CLI exibe a contagem dos arquivos de contexto carregados, fornecendo uma dica 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, veja a [documentação do Processador de Importação de Memória](../configuration/memory).
- **Comandos para Gerenciamento de Memória:**
  - Use `/memory refresh` para forçar uma nova varredura e recarregamento de todos os arquivos de contexto de todas as localizações configuradas. Isso atualiza o contexto instrucional da IA.
  - Use `/memory show` para exibir o contexto instrucional combinado atualmente carregado, permitindo que você verifique a hierarquia e o conteúdo sendo usado pela IA.
  - Veja a [documentação de Comandos](../features/commands) para detalhes completos sobre o comando `/memory` e seus sub-comandos (`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 adaptar as respostas do Qwen Code às 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 sandbox para proteger seu sistema.

O [Sandbox](../features/sandbox) está desabilitado por padrão, mas você pode habilitá-lo de algumas formas:

- Usando a flag `--sandbox` ou `-s`.
- Configurando a variável de ambiente `GEMINI_SANDBOX`.
- O sandbox é habilitado 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 sandbox por 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` existe, 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 anônimas. 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 tiveram sucesso ou falharam e quanto tempo levaram para ser executadas. Não coletamos os argumentos passados às ferramentas nem nenhum dado retornado por elas.
- **Solicitações de API:** Registramos o modelo utilizado em cada solicitação, a duração da solicitação e se foi bem-sucedida. Não coletamos o conteúdo dos prompts ou 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 as respostas do modelo.
- **Conteúdo de Arquivos:** Não registramos o conteúdo de quaisquer arquivos lidos ou escritos pela CLI.

**Como desativar:**

Você pode optar por não participar da 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 ativadas, os eventos são enviados a um endpoint de coleta do Alibaba Cloud RUM.