Qwen Code 配置

配置层级

配置按以下优先级顺序应用（数字较小的会被数字较大的覆盖）：

设置文件

Qwen Code 使用 JSON 设置文件进行持久化配置。这些文件有四个存放位置：

项目中的 .qwen 目录

除了项目设置文件外，项目的 .qwen 目录还可以包含与 Qwen Code 运行相关的其他项目特定文件，例如：

• 自定义沙盒配置文件（例如 .qwen/sandbox-macos-custom.sb、.qwen/sandbox.Dockerfile）。
• .qwen/skills/ 下的 Agent Skills（每个 Skill 是一个包含 SKILL.md 的目录）。

配置迁移

Qwen Code 会自动将旧版配置设置迁移到新格式。迁移前会备份旧设置文件。以下设置已从否定命名（disable*）更改为肯定命名（enable*）：

disableAutoUpdate 和 disableUpdateNag 的合并策略

当两个旧版设置同时存在且值不同时，迁移遵循以下策略：如果 disableAutoUpdate 或 disableUpdateNag 中任意一个为 true，则 enableAutoUpdate 将变为 false：

settings.json 中的可用设置

设置按类别组织。所有设置都应放置在 settings.json 文件中对应的顶级类别对象内。

general

output

ui

ide

privacy

model

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（自适应输出 token）：

当未设置 samplingParams.max_tokens 时，Qwen Code 使用自适应输出 token 策略以优化 GPU 资源使用：

1. 请求以 8K 输出 token 的默认限制开始
2. 如果响应被截断（模型达到限制），Qwen Code 会自动使用 64K token 重试
3. 部分输出将被丢弃，并替换为重试后的完整响应

这对用户是透明的——如果发生升级，你可能会短暂看到重试指示器。由于 99% 的响应低于 5K token，重试极少发生（<1% 的请求）。

要覆盖此行为，请在设置中设置 samplingParams.max_tokens 或使用 QWEN_CODE_MAX_OUTPUT_TOKENS 环境变量。

contextWindowSize：

覆盖所选模型的默认上下文窗口大小。Qwen Code 根据模型名称匹配使用内置默认值，并带有常量回退值。当提供商的有效上下文限制与 Qwen Code 的默认值不同时，请使用此设置。此值定义模型假设的最大上下文容量，而非每次请求的 token 限制。

modalities：

覆盖所选模型的自动检测输入模态。Qwen Code 会根据模型名称模式匹配自动检测支持的模态（图像、PDF、音频、视频）。当自动检测不正确时使用此设置——例如，为支持但未识别的模型启用 pdf。格式：{ "image": true, "pdf": true, "audio": true, "video": true }。省略键或将其设置为 false 表示不支持的类型。

customHeaders：

允许你向所有 API 请求添加自定义 HTTP 标头。这对于请求追踪、监控、API 网关路由或不同模型需要不同标头时非常有用。如果 modelProviders[].generationConfig.customHeaders 中定义了 customHeaders，将直接使用它；否则将使用 model.generationConfig.customHeaders 中的标头。两个层级之间不会合并。

extra_body 字段允许你向发送到 API 的请求 body 添加自定义参数。这对于标准配置字段未涵盖的提供商特定选项非常有用。注意：此字段仅支持兼容 OpenAI 的提供商（openai、qwen-oauth）。Anthropic 和 Gemini 提供商将忽略此字段。 如果 modelProviders[].generationConfig.extra_body 中定义了 extra_body，将直接使用它；否则将使用 model.generationConfig.extra_body 中的值。

model.openAILoggingDir 示例：

• "~/qwen-logs" - 记录到 ~/qwen-logs 目录
• "./custom-logs" - 记录到相对于当前目录的 ./custom-logs
• "/tmp/openai-logs" - 记录到绝对路径 /tmp/openai-logs

fastModel

context

排查文件搜索性能问题

如果你在文件搜索（例如 @ 补全）时遇到性能问题，尤其是在文件数量非常多的项目中，可以尝试以下方法（按推荐顺序排列）：

1. 使用 .qwenignore： 在项目根目录创建 .qwenignore 文件，以排除包含大量无需引用文件的目录（例如构建产物、日志、node_modules）。减少爬取的文件总数是提升性能最有效的方法。
2. 禁用模糊搜索： 如果忽略文件仍不够，可以在 settings.json 中将 enableFuzzySearch 设置为 false 来禁用模糊搜索。这将使用更简单的非模糊匹配算法，速度更快。
3. 禁用递归文件搜索： 作为最后手段，你可以将 enableRecursiveFileSearch 设置为 false 完全禁用递归文件搜索。这将是最快的选项，因为它避免了对项目的递归爬取。但这也意味着在使用 @ 补全时，你需要输入文件的完整路径。

tools

permissions

权限系统提供对哪些工具可以运行、哪些需要确认以及哪些被阻止的细粒度控制。

决策优先级（从高到低）：deny > ask > allow > (默认/交互模式)

第一个匹配的规则生效。规则格式为 "ToolName" 或 "ToolName(specifier)"。

工具名称别名（规则中均可使用）：

元类别：

某些规则名称会自动覆盖多个工具：

[!important] Read(/path/**) 匹配所有四个读取工具（文件读取、grep、glob 和目录列表）。 要仅限制文件读取，请使用 ReadFile(/path/**) 或 read_file(/path/**)。

规则语法示例：

路径模式前缀：

Shell 命令绕过防护：

当 agent 运行等效的 shell 命令时，也会强制执行 Read、Edit 和 WebFetch 的权限规则。例如，如果 deny 中包含 Read(./.env)，agent 无法通过 shell 命令中的 cat .env 绕过它。支持的 shell 命令包括 cat、grep、curl、wget、cp、mv、rm、chmod 等。未知/安全的命令（如 git）不受文件/网络规则影响。

从旧版设置迁移：

配置示例：

{
  "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] 在交互式 CLI 中使用 /permissions 可查看、添加和删除规则，无需直接编辑 settings.json。

mcp

lsp

[!warning] 实验性功能：LSP 支持目前处于实验阶段，默认禁用。请使用 --experimental-lsp 命令行标志启用它。

语言服务器协议（LSP）提供代码智能功能，如转到定义、查找引用和诊断。

LSP 服务器配置通过项目根目录中的 .lsp.json 文件完成，而非通过 settings.json。有关配置详情和示例，请参阅 LSP 文档。

security

advanced

mcpServers

配置与一个或多个模型上下文协议（MCP）服务器的连接，以发现和使用自定义工具。Qwen Code 会尝试连接到每个配置的 MCP 服务器以发现可用工具。如果多个 MCP 服务器公开了同名工具，工具名称将使用你在配置中定义的服务器别名作为前缀（例如 serverAlias__actualToolName）以避免冲突。注意，系统可能会为了兼容性从 MCP 工具定义中剥离某些 schema 属性。必须提供 command、url 或 httpUrl 中的至少一个。如果指定了多个，优先级顺序为 httpUrl，然后是 url，最后是 command。

telemetry

配置 Qwen Code 的日志记录和指标收集。更多信息请参阅 遥测。

settings.json 示例

以下是具有嵌套结构的 settings.json 文件示例（自 v0.3.0 起新增）：

{
  "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",
    "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"]
  }
}

Shell 历史记录

CLI 会保留你运行的 shell 命令历史记录。为避免不同项目之间的冲突，此历史记录存储在你用户主文件夹内的项目特定目录中。

• 位置： ~/.qwen/tmp/<project_hash>/shell_history
  • <project_hash> 是根据项目根路径生成的唯一标识符。
  • 历史记录存储在名为 shell_history 的文件中。

环境变量与 .env 文件

环境变量是配置应用程序的常用方式，尤其适用于敏感信息（如 token）或可能在不同环境之间更改的设置。

Qwen Code 可以自动从 .env 文件加载环境变量。 有关身份验证相关的变量（如 OPENAI_*）和推荐的 .qwen/.env 方法，请参阅 身份验证。

环境变量表

命令行参数

运行 CLI 时直接传入的参数可以覆盖该特定会话的其他配置。

命令行参数表

上下文文件（分层指令上下文）

虽然严格来说不是 CLI 行为 的配置，但上下文文件（默认为 QWEN.md，但可通过 context.fileName 设置配置）对于配置 指令上下文（也称为“记忆”）至关重要。此强大功能允许你向 AI 提供项目特定的指令、编码风格指南或任何相关背景信息，使其响应更贴合你的需求并更准确。CLI 包含 UI 元素（例如页脚中显示已加载上下文文件数量的指示器），以便让你了解当前活动的上下文。

• 目的： 这些 Markdown 文件包含你希望 Qwen 模型在交互过程中知晓的指令、指南或上下文。该系统旨在分层管理此指令上下文。

上下文文件内容示例（例如 QWEN.md）

以下是 TypeScript 项目根目录下上下文文件可能包含的概念示例：

# 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 20+.

## 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.

此示例展示了如何提供通用项目上下文、特定编码约定，甚至关于特定文件或组件的说明。你的上下文文件越相关、越精确，AI 就能越好地协助你。强烈建议使用项目特定的上下文文件来建立约定和上下文。

• 分层加载与优先级： CLI 通过从多个位置加载上下文文件（例如 QWEN.md）实现分层记忆系统。此列表中较低位置（更具体）的文件内容通常会覆盖或补充较高位置（更通用）的文件内容。确切的拼接顺序和最终上下文可使用 /memory show 命令检查。典型的加载顺序为：
  1. 全局上下文文件：
     • 位置：~/.qwen/<configured-context-filename>（例如用户主目录中的 ~/.qwen/QWEN.md）。
     • 作用域：为所有项目提供默认指令。
  2. 项目根目录及祖先目录上下文文件：
     • 位置：CLI 会在当前工作目录中搜索配置的上下文文件，然后向上搜索每个父目录，直到项目根目录（由 .git 文件夹标识）或你的主目录。
     • 作用域：提供与整个项目或项目重要部分相关的上下文。
• 拼接与 UI 指示： 所有找到的上下文文件的内容会被拼接（带有指示其来源和路径的分隔符），并作为系统提示的一部分提供。CLI 页脚显示已加载上下文文件的数量，为你提供关于活动指令上下文的快速视觉提示。
• 导入内容： 你可以使用 @path/to/file.md 语法导入其他 Markdown 文件来模块化你的上下文文件。有关详细信息，请参阅 记忆导入处理器文档。
• 记忆管理命令：
  • 使用 /memory refresh 强制重新扫描并从所有配置位置重新加载所有上下文文件。这将更新 AI 的指令上下文。
  • 使用 /memory show 显示当前加载的组合指令上下文，允许你验证 AI 使用的层次结构和内容。
  • 有关 /memory 命令及其子命令（show 和 refresh）的完整详情，请参阅 命令文档。

通过了解并利用这些配置层以及上下文文件的分层特性，你可以有效管理 AI 的记忆，并根据你的特定需求和项目定制 Qwen Code 的响应。

沙盒

Qwen Code 可以在沙盒环境中执行潜在的不安全操作（如 shell 命令和文件修改），以保护你的系统。

沙盒 默认禁用，但你可以通过以下几种方式启用它：

• 使用 --sandbox 或 -s 标志。
• 设置 QWEN_SANDBOX 环境变量。
• 默认情况下，使用 --yolo 或 --approval-mode=yolo 时会启用沙盒。

默认情况下，它使用预构建的 qwen-code-sandbox Docker 镜像。

对于项目特定的沙盒需求，你可以在项目根目录创建自定义 Dockerfile：.qwen/sandbox.Dockerfile。此 Dockerfile 可以基于基础沙盒镜像：

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

当 .qwen/sandbox.Dockerfile 存在时，你可以在运行 Qwen Code 时使用 BUILD_SANDBOX 环境变量自动构建自定义沙盒镜像：

BUILD_SANDBOX=1 qwen -s

使用统计

为了帮助我们改进 Qwen Code，我们会收集匿名使用统计信息。这些数据有助于我们了解 CLI 的使用方式、识别常见问题并优先开发新功能。

我们收集的内容：

• 工具调用： 我们记录被调用的工具名称、成功或失败状态以及执行耗时。我们不会收集传递给工具的参数或工具返回的任何数据。
• API 请求： 我们记录每次请求使用的模型、请求持续时间以及是否成功。我们不会收集提示或响应的内容。
• 会话信息： 我们收集有关 CLI 配置的信息，例如启用的工具和审批模式。

我们不会收集的内容：

• 个人身份信息（PII）： 我们不会收集任何个人信息，如你的姓名、电子邮件地址或 API 密钥。
• 提示和响应内容： 我们不会记录你的提示内容或模型的响应内容。
• 文件内容： 我们不会记录 CLI 读取或写入的任何文件的内容。

如何退出：

你可以随时通过在 settings.json 文件的 privacy 类别下将 usageStatisticsEnabled 属性设置为 false 来退出使用统计信息收集：

{
  "privacy": {
    "usageStatisticsEnabled": false
  }
}