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 do 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 de sandbox personalizados (por exemplo, .qwen/sandbox-macos-custom.sb, .qwen/sandbox.Dockerfile).
• Agent Skills em .qwen/skills/ (cada Skill é um diretório contendo um SKILL.md).

Migração de configuração

O Qwen Code migra automaticamente as configurações legadas para o novo formato. Os arquivos de configuração antigos são copiados 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 das configurações 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. A maioria das configurações deve ser colocada dentro do objeto de categoria de nível superior correspondente no seu arquivo settings.json. Algumas configurações de nível superior, como proxy e plansDirectory, permanecem como chaves raiz diretas para compatibilidade.

general

output

ui

ide

privacy

model

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

timeout (tempo limite da requisição):

timeout é o tempo limite por requisição em milissegundos (padrão 120000). Defina como 0 para desativar o tempo limite da requisição — seguindo a convenção QWEN_STREAM_IDLE_TIMEOUT_MS=0 — em vez de abortar a requisição. Também pode ser definido via variável de ambiente QWEN_CODE_API_TIMEOUT_MS. Isso é distinto de QWEN_STREAM_IDLE_TIMEOUT_MS, que limita a inatividade entre chunks transmitidos.

max_tokens (limite de tokens de saída):

Quando nem samplingParams.max_tokens nem QWEN_CODE_MAX_OUTPUT_TOKENS está definido, o Qwen Code geralmente usa o limite de saída declarado do modelo selecionado como o limite de saída padrão da requisição. Se a resposta ainda atingir esse limite, o Qwen Code pode tentar novamente com um limite maior (usando um piso de 64K) e então se recuperar ao longo dos turnos de continuação.

Para provedores compatíveis com OpenAI, samplingParams também é uma válvula de escape de formato de rede (wire-shape): quando definido, suas chaves são passadas literalmente e o Qwen Code não sintetiza um padrão para max_tokens. Use isso para parâmetros específicos do provedor, como max_completion_tokens.

Para forçar um limite de saída fixo, defina samplingParams.max_tokens nas suas configurações ou use a variável de ambiente QWEN_CODE_MAX_OUTPUT_TOKENS. Limites explícitos desativam a escalação automática de tokens de saída.

toolResultContentFormat:

Controla como resultados de ferramentas apenas de texto são serializados em requisições compatíveis com OpenAI. O padrão "parts" mantém o formato padrão de array de partes de conteúdo. Defina como "string" apenas para runtimes legados compatíveis com OpenAI cujos templates de ferramentas ignoram partes de conteúdo de texto, como templates mais antigos do GLM-5.1 vLLM/SGLang. Mídia retornada por ferramentas ainda é controlada por splitToolMedia.

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 integrados baseados 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 for diferente do padrão do Qwen Code. Este valor define a capacidade máxima de contexto assumida do modelo, não um limite de tokens por requisição.

Quando o modelo selecionado é definido em modelProviders, defina contextWindowSize no generationConfig dessa entrada do provedor em vez do model.generationConfig de nível superior. As entradas de modelo do provedor são seladas, então as configurações de geração de nível superior não preenchem os campos ausentes do provedor.

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ões do nome do modelo. Use esta configuração quando a detecção automática estiver incorreta — por exemplo, para habilitar 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-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 de gateway de API ou quando diferentes modelos exigem cabeçalhos diferentes. Para modelos de provedor, defina customHeaders em modelProviders[].generationConfig.customHeaders. Para modelos de runtime sem uma entrada de provedor correspondente, defina-o em model.generationConfig.customHeaders. Não ocorre mesclagem entre os dois níveis.

O campo extra_body permite adicionar parâmetros personalizados ao corpo da requisição enviado para a 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. Para modelos de provedor, defina extra_body em modelProviders[].generationConfig.extra_body. Para modelos de runtime sem uma entrada de provedor correspondente, defina-o em model.generationConfig.extra_body.

Exemplos de model.openAILoggingDir:

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

fastModel

visionModel

voiceModel

modelFallbacks

modelPricing

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 as 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 um arquivo de ignore: Crie um .qwenignore ou um arquivo de ignore personalizado configurado na raiz do seu projeto para excluir diretórios que contêm 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 maneira mais eficaz de melhorar o desempenho.
2. Desative a pesquisa fuzzy: Se ignorar arquivos não for suficiente, você pode desativar a pesquisa 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 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 para os arquivos ao usar as conclusões @.

tools

memory

Consulte Memory para detalhes sobre como a auto-memory funciona e como usar os comandos /memory, /remember e /dream.

permissions

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

Prioridade de decisão (da maior para a menor): deny > ask > allow > (padrão/modo interativo)

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

Aliases de nomes de ferramentas (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 comandos 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 poderá contornar isso via cat .env em um comando shell. Os comandos shell suportados incluem cat, grep, curl, wget, cp, mv, rm, chmod e muitos outros. Comandos desconhecidos/seguros (por exemplo, git) não são afetados pelas regras de arquivo/rede.

Migrando das configurações legadas:

Configuração de exemplo:

{
  "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 no CLI interativo para visualizar, adicionar e remover regras sem editar o settings.json diretamente.

slashCommands

Controla quais slash commands estão disponíveis no CLI. Útil para restringir a superfície de comandos em implantações multi-tenant ou corporativas.

A mesma denylist também pode ser fornecida via flag de CLI --disabled-slash-commands (separada por vírgulas ou repetida) e a variável de ambiente QWEN_DISABLED_SLASH_COMMANDS; os valores das três fontes são unidos.

Exemplo — restringir comandos integrados para uma implantação em sandbox:

{
  "slashCommands": {
    "disabled": ["auth", "mcp", "extensions", "ide", "quit"]
  }
}

Com esses valores em um settings.json no nível do sistema (/etc/qwen-code/settings.json ou QWEN_CODE_SYSTEM_SETTINGS_PATH), os usuários não podem reduzir a denylist a partir de seu próprio escopo, e os comandos desabilitados não aparecerão no autocomplete nem serão executados quando digitados.

[!note] Esta configuração apenas controla o acesso aos slash commands (por exemplo, /auth, /mcp). Ela não afeta as permissões de ferramentas — consulte permissions.deny para isso. Também não intercepta atalhos de teclado como Ctrl+C ou Esc.

skills

Controla quais Skills são expostas ao modelo.

mcp

lsp

[!warning] Recurso experimental: O suporte a LSP é atualmente experimental e está 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 a 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, e não através do settings.json. Consulte a documentação do LSP para detalhes de configuração e exemplos.

security

advanced

experimental

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 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 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 e, em seguida, command.

telemetria

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

Exemplo de settings.json

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

{
  "proxy": "http://localhost:7890",
  "plansDirectory": "./.qwen/plans",
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  },
  "ui": {
    "theme": "GitHub",
    "hideTips": false,
    "customWittyPhrases": [
      "You forget a thousand things every day. Make sure this is one of 'em",
      "Connecting to AGI"
    ]
  },
  "tools": {
    "approvalMode": "yolo",
    "sandbox": "docker",
    "sandboxImage": "ghcr.io/qwenlm/qwen-code:0.14.1",
    "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,
    "includeSensitiveSpanAttributes": false,
    "sensitiveSpanAttributeMaxLength": 1048576
  },
  "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

O 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 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 a partir 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 sobrescrever outras configurações para aquela sessão específica.

Para a seleção da imagem do sandbox, a precedência é: --sandbox-image > QWEN_SANDBOX_IMAGE > tools.sandboxImage > imagem padrão integrada.

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 (que por padrão são QWEN.md, mas podem ser configurados via setting context.fileName) são cruciais para configurar o contexto instrucional (também chamado de “memória”). Esse recurso poderoso permite que você forneça instruções específicas do projeto, guias de estilo de código ou qualquer informação de contexto relevante para a IA, tornando suas respostas mais personalizadas e precisas para as suas necessidades. A CLI inclui elementos de UI, como um indicador no rodapé mostrando o número de arquivos de contexto carregados, para mantê-lo informado sobre o contexto ativo.

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

Exemplo de Conteúdo de Arquivo de Contexto (ex.: QWEN.md)

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

# Project: My Awesome TypeScript Library

## General Instructions:
- When generating new TypeScript code, please follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
- All code should be compatible with TypeScript 5.0 and Node.js 22+.

## Coding Style:
- Use 2 spaces for indentation.
- Interface names should be prefixed with `I` (e.g., `IUserService`).
- Private class members should be prefixed with an underscore (`_`).
- Always use strict equality (`===` and `!==`).

## Specific Component: `src/api/client.ts`
- This file handles all outbound API requests.
- When adding new API call functions, ensure they include robust error handling and logging.
- Use the existing `fetchWithRetry` utility for all GET requests.

## Regarding Dependencies:
- Avoid introducing new external dependencies unless absolutely necessary.
- If a new dependency is required, please state the reason.

Este exemplo demonstra como você pode fornecer contexto geral do projeto, convenções de código específicas e até mesmo 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 recomendados para estabelecer convenções e contexto.

• Carregamento Hierárquico e Precedência: A CLI implementa um sistema de memória hierárquico carregando arquivos de contexto (ex.: QWEN.md) de vários locais. O conteúdo de arquivos mais abaixo nesta lista (mais específicos) geralmente substitui ou complementa o conteúdo de arquivos mais acima (mais gerais). A ordem exata de concatenação e o contexto final podem ser inspecionados no diálogo /memory. A ordem de carregamento típica é:
  1. Arquivo de Contexto Global:
     • Localização: ~/.qwen/<configured-context-filename> (ex.: ~/.qwen/QWEN.md no diretório home do seu 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 o arquivo de contexto configurado no diretório de trabalho atual e, em seguida, em cada diretório pai até a raiz do projeto (identificada por uma pasta .git) ou o seu diretório home.
     • Escopo: Fornece contexto relevante para todo o projeto ou uma parte significativa dele.
• Concatenação e Indicação na UI: 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, dando a você um indicador visual rápido sobre o contexto instrucional ativo.
• Importando Conteúdo: Você pode modularizar seus arquivos de contexto importando outros arquivos Markdown usando a sintaxe @path/to/file.md. Para mais detalhes, consulte a documentação do Memory.
• Comandos para Gerenciamento de Memória:
  • Use /memory para abrir o diálogo de gerenciamento de memória.
  • Atualize a memória a partir do diálogo para reescanear e recarregar os arquivos de contexto de todos os locais configurados.
  • Consulte a documentação de Commands para detalhes completos sobre o comando /memory.

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 para 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 o seu sistema.

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

• Usando a flag --sandbox ou -s.
• Definindo a variável de ambiente QWEN_SANDBOX.
• Definindo tools.sandbox nas configurações.

⚠️ --yolo não habilita automaticamente um sandbox. O modo YOLO apenas aprova automaticamente as chamadas de ferramentas; o sandbox ainda precisa ser ativado explicitamente via --sandbox, QWEN_SANDBOX ou tools.sandbox. Em execuções headless / não interativas com --yolo (ou --approval-mode=yolo) e sem sandbox, o modelo pode executar ferramentas de shell, write e edit no nível de privilégio do processo atual — o Qwen Code imprime um aviso no stderr nesse caso. Suprima com QWEN_CODE_SUPPRESS_YOLO_WARNING=1 depois de revisar os prós e contras.

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

Para necessidades de sandbox específicas 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
# Add your custom dependencies or configurations here
# For example:
# RUN apt-get update && apt-get install -y some-package
# 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 de sandbox personalizada:

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 é usada, identificar problemas comuns e priorizar novos recursos.

O que coletamos:

• Chamadas de Ferramentas: Registramos os nomes das ferramentas que são chamadas, se elas têm sucesso ou falham, e quanto tempo levam para executar. Não coletamos os argumentos passados para as ferramentas nem nenhum dado retornado por elas.
• Requisições de API: Registramos o modelo usado para 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 de Identificação Pessoal (PII): Não coletamos nenhuma informação pessoal, como seu nome, endereço de e-mail ou API keys.
• 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 nenhum arquivo que seja 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
  }
}