Qwen Code 配置

配置层级

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

设置文件

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

项目中的 .qwen 目录

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

• 自定义沙箱配置文件（如 .qwen/sandbox-macos-custom.sb、.qwen/sandbox.Dockerfile）。
• .qwen/skills/ 下的 Agent 技能（实验性功能）（每个技能都是一个包含 SKILL.md 的目录）。

settings.json 中可用的设置

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

general

output

ui

ide

privacy

model

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

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

model.openAILoggingDir 示例：

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

modelProviders

使用 modelProviders 为每种认证类型声明精选的模型列表，以便 /model 选择器可以在它们之间切换。键必须是有效的认证类型（如 openai、anthropic、gemini、vertex-ai 等）。每个条目都需要一个 id 并且必须包含 envKey，还可以选择性地包括 name、description、baseUrl 和 generationConfig。凭证永远不会保存在设置中；运行时会从 process.env[envKey] 中读取它们。Qwen OAuth 模型仍然是硬编码的，无法被覆盖。

示例

{
  "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] 只有 /model 命令暴露非默认的认证类型。Anthropic、Gemini、Vertex AI 等必须通过 modelProviders 定义。/auth 命令有意只列出内置的 Qwen OAuth 和 OpenAI 流程。

解析层级和原子性

有效的 auth/model/credential 值按字段使用以下优先级选择（首先出现的生效）。你可以将 --auth-type 与 --model 结合使用，直接指向提供程序条目；这些 CLI 标志在其他层级之前运行。

* 当存在时，CLI 认证标志会覆盖设置。否则，security.auth.selectedType 或隐式默认值确定认证类型。无需额外配置即可显示的唯一认证类型是 Qwen OAuth 和 OpenAI。

模型提供程序来源的值以原子方式应用：一旦提供程序模型处于活动状态，它定义的每个字段都将受到保护，免受较低层级的影响，直到你通过 /auth 手动清除凭据。最终的 generationConfig 是跨所有层级的投影——较低层级仅填充较高级别留下的空白，并且提供程序层级保持不可穿透。

modelProviders 的合并策略是 REPLACE：项目设置中的整个 modelProviders 将覆盖用户设置中的相应部分，而不是合并两者。

生成配置分层

generationConfig 的字段优先级顺序：

1. 编程覆盖（例如运行时的 /model、/auth 更改）
2. modelProviders[authType][].generationConfig
3. settings.model.generationConfig
4. 内容生成器默认值（OpenAI 使用 getDefaultGenerationConfig，Gemini 使用 getParameterValue 等）

samplingParams 和 customHeaders 都被视为原子对象；提供者值会替换整个对象。如果 modelProviders[].generationConfig 定义了这些字段，则直接使用它们；否则，使用来自 model.generationConfig 的值。提供者和全局配置级别之间不会发生合并。内容生成器的默认值最后应用，因此每个提供者都能保持其调优的基础配置。

选择持久化和建议

[!重要] 尽可能在用户范围的 ~/.qwen/settings.json 中定义 modelProviders，并避免在任何范围内持久化凭证覆盖。将提供程序目录保存在用户设置中可以防止项目范围和用户范围之间的合并/覆盖冲突，并确保 /auth 和 /model 更新始终写回到一致的作用域。

• /model 和 /auth 将 model.name（如适用）和 security.auth.selectedType 持久化到已定义 modelProviders 的最近可写作用域；否则它们会回退到用户作用域。这使工作区/用户文件与活动的提供程序目录保持同步。
• 没有 modelProviders 时，解析器会混合 CLI/env/settings 层，这对于单提供程序设置来说是可以的，但在频繁切换时会很麻烦。当多模型工作流程很常见时，请定义提供程序目录，以便切换保持原子性、源归因和可调试性。

context

故障排除：文件搜索性能

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

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

工具

mcp

安全性

高级

experimental

mcpServers

配置到一个或多个模型上下文协议（MCP）服务器的连接，用于发现和使用自定义工具。Qwen Code 尝试连接到每个配置的 MCP 服务器以发现可用的工具。如果多个 MCP 服务器公开具有相同名称的工具，则工具名称将使用你在配置中定义的服务器别名作为前缀（例如，serverAlias__actualToolName），以避免冲突。请注意，系统可能会从 MCP 工具定义中删除某些模式属性以确保兼容性。必须提供 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": [
      "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",
    "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"]
  }
}

Shell 历史记录

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

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

环境变量和 .env 文件

环境变量是配置应用程序的常用方式，特别是对于敏感信息（如令牌）或可能在不同环境之间变化的设置。

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

环境变量表

命令行参数

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

命令行参数表

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

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

• 用途： 这些 Markdown 文件包含你在交互过程中希望 Qwen 模型了解的指令、指南或上下文。该系统设计为以分层方式管理此指令上下文。

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

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

# 项目：我的超棒 TypeScript 库

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

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

## 特定组件：`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 文件来模块化你的上下文文件。更多详情请参见[内存导入处理器文档](../configuration/memory)。
- **内存管理命令：**
  - 使用 `/memory refresh` 强制重新扫描和重新加载所有配置位置的所有上下文文件。这会更新 AI 的指令上下文。
  - 使用 `/memory show` 显示当前加载的组合指令上下文，让你验证 AI 正在使用的层次结构和内容。
  - 有关 `/memory` 命令及其子命令（`show` 和 `refresh`）的完整详细信息，请参见[命令文档](../features/commands)。

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

## 沙箱

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

[沙箱](../features/sandbox) 默认是禁用的，但您可以通过以下几种方式启用它：

- 使用 `--sandbox` 或 `-s` 标志。
- 设置 `GEMINI_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 请求： 我们记录每次请求使用的模型、请求持续时间以及是否成功。我们不会收集提示内容或响应内容。
• 会话信息： 我们收集有关 CLI 配置的信息，例如启用的工具和审批模式。

我们不收集的内容：

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

如何退出：

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

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