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 文件中其对应的一级类别对象内。

常规

输出

UI

IDE

隐私

模型

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：
覆盖所选模型的默认上下文窗口大小。Qwen Code 依据模型名称匹配内置默认值，并设有固定后备值来确定上下文窗口。当服务提供商的实际上下文限制与 Qwen Code 默认值不一致时，请使用此设置。该值定义的是模型假设的最大上下文容量，而非单次请求的 token 限制。

modalities：
覆盖所选模型自动检测的输入模态。Qwen Code 会基于模型名称模式匹配，自动识别支持的模态（图像、PDF、音频、视频）。当自动检测结果不正确时，请使用此设置 —— 例如，为一个实际支持 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 请求体中添加自定义参数，适用于标准配置字段未涵盖的供应商特定选项。注意：该字段仅支持 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

上下文

文件搜索性能问题排查

如果在进行文件搜索（例如使用 @ 补全）时遇到性能问题，尤其是在包含大量文件的项目中，可按以下推荐顺序尝试以下方法：

1. 使用 .qwenignore 文件： 在项目根目录下创建 .qwenignore 文件，排除那些包含大量无需引用的文件的目录（例如构建产物、日志、node_modules）。减少被扫描的文件总数是提升性能最有效的方式。
2. 禁用模糊搜索： 如果仅忽略文件仍不足以改善性能，可在 settings.json 文件中将 enableFuzzySearch 设为 false 来禁用模糊搜索。这将改用更简单、非模糊的匹配算法，从而加快搜索速度。
3. 禁用递归文件搜索： 作为最后手段，可将 enableRecursiveFileSearch 设为 false，完全禁用递归文件搜索。这是最快的选择，因为它避免了对整个项目的递归遍历；但代价是使用 @ 补全时需手动输入文件的完整路径。

工具

MCP

LSP

[!warning] 实验性功能：LSP 支持目前为实验性功能，默认处于禁用状态。请使用 --experimental-lsp 命令行参数启用该功能。

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

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

安全性

高级配置

mcpServers

配置与一个或多个模型上下文协议（MCP）服务器的连接，用于发现和使用自定义工具。Qwen Code 会尝试连接每个已配置的 MCP 服务器以发现可用工具。若多个 MCP 服务器暴露了同名工具，则工具名将被加上你在配置中定义的服务器别名前缀（例如 serverAlias__actualToolName），以避免冲突。请注意，系统可能会为兼容性目的从 MCP 工具定义中移除某些 schema 属性。command、url 和 httpUrl 中至少需提供一项；若同时指定多项，则优先级顺序为：httpUrl > url > command。

遥测（Telemetry）

配置 Qwen Code 的日志记录与指标收集功能。更多信息，请参阅遥测（Telemetry）。

示例 settings.json

以下是 v0.3.0 版本起引入的嵌套结构 settings.json 文件示例：

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  },
  "ui": {
    "theme": "GitHub",
    "hideTips": false,
    "customWittyPhrases": [
      "你每天都会忘记上千件事。确保这件事也在其中",
      "正在连接 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 文件

环境变量是一种常见的应用程序配置方式，尤其适用于敏感信息（例如令牌）或在不同环境中可能发生变化的设置。

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

环境变量表

命令行参数

在运行 CLI 时直接传入的参数，可覆盖该次会话中的其他配置。

命令行参数表

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

虽然上下文文件（默认为 QWEN.md，但可通过 context.fileName 配置项自定义）并非严格意义上的 CLI 行为 配置，但它对配置 指令上下文（也称为“记忆”）至关重要。这一强大功能允许你向 AI 提供项目特定的指令、编码风格指南或任何相关背景信息，从而使其响应更贴合你的实际需求且更加准确。CLI 提供了若干 UI 元素（例如页脚中显示已加载上下文文件数量的指示器），以便让你随时掌握当前生效的上下文。

• 用途： 这些 Markdown 文件包含你希望 Qwen 模型在交互过程中知晓的指令、指南或上下文信息。系统采用分层方式管理此类指令上下文。

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

以下是一个概念性示例，展示 TypeScript 项目根目录下上下文文件可能包含的内容：

# 项目：我的优秀 TypeScript 库

## 通用说明：
- 生成新的 TypeScript 代码时，请遵循现有编码风格。
- 确保所有新函数和类均带有 JSDoc 注释。
- 在合适的情况下优先采用函数式编程范式。
- 所有代码需兼容 TypeScript 5.0 和 Node.js 20+。

## 编码风格：
- 使用 2 个空格进行缩进。
- 接口名称应以 `I` 开头（例如：`IUserService`）。
- 私有类成员应以下划线 `_` 开头（例如：`_privateField`）。
- 始终使用严格相等比较（`===` 和 `!==`）。

## 特定组件：`src/api/client.ts`
- 该文件负责处理所有出站 API 请求。
- 新增 API 调用函数时，须确保包含健壮的错误处理与日志记录。
- 所有 GET 请求均应使用现有的 `fetchWithRetry` 工具函数。

关于依赖项：

• 尽量避免引入新的外部依赖，除非绝对必要。
• 如果确实需要新依赖，请说明具体原因。

此示例展示了如何提供通用的项目背景、特定的编码规范，甚至关于特定文件或组件的备注。您的上下文文件越相关、越精准，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 Import Processor 文档。
• 内存管理命令：
  • 使用 /memory refresh 强制重新扫描并从所有已配置位置重新加载全部上下文文件，从而更新 AI 的指令上下文。
  • 使用 /memory show 查看当前已加载的完整指令上下文，以便验证 AI 正在使用的上下文层级与具体内容。
  • 有关 /memory 命令及其子命令（show 和 refresh）的完整说明，请参阅 Commands 文档。

通过理解并善用这些配置层级以及上下文文件的分层特性，您可以高效地管理 AI 的记忆，并使 Qwen Code 的响应精准契合您的具体需求与项目场景。

沙箱

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

沙箱 默认处于禁用状态，但您可通过以下几种方式启用它：

• 使用 --sandbox 或 -s 参数。
• 设置 QWEN_SANDBOX 环境变量。
• 当使用 --yolo 或 --approval-mode=yolo 时，沙箱默认启用。

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

如需满足项目特定的沙箱需求，您可在项目根目录下的 .qwen/sandbox.Dockerfile 中创建自定义 Dockerfile。该 Dockerfile 可基于基础沙箱镜像构建：

FROM qwen-code-sandbox

# 在此处添加您的自定义依赖项或配置

# 例如：

# 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 请求： 我们记录每次请求所使用的模型、请求耗时以及请求是否成功。我们不会收集提示词（prompt）或响应（response）的内容。
• 会话信息： 我们收集 CLI 的配置信息，例如已启用的工具和审批模式。

我们明确不收集的内容：

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

如何退出统计收集：

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

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