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 文件中对应的顶级类别对象内。为了保持兼容性，少数顶级设置（如 proxy 和 plansDirectory）仍保留为直接的根键。

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（请求超时）：

timeout 是每次请求的超时时间，单位为毫秒（默认值为 120000）。将其设置为 0 可禁用请求超时（与 QWEN_STREAM_IDLE_TIMEOUT_MS=0 的约定一致），而不是中止请求。也可以通过 QWEN_CODE_API_TIMEOUT_MS 环境变量进行设置。这与 QWEN_STREAM_IDLE_TIMEOUT_MS 不同，后者限制的是流式传输块_之间_的不活动时间。

max_tokens（输出 token 限制）：

当未设置 samplingParams.max_tokens 和 QWEN_CODE_MAX_OUTPUT_TOKENS 时，Qwen Code 通常会使用所选模型声明的输出限制作为请求的默认输出限制。如果响应仍然达到该限制，Qwen Code 可能会使用提升后的限制（下限为 64K）进行重试，并在后续对话轮次中恢复。

对于兼容 OpenAI 的提供商，samplingParams 也是一种直接透传参数的机制：设置后，其键值将原样传递，Qwen Code 不会合成默认的 max_tokens。可用于传递特定于提供商的参数，例如 max_completion_tokens。

要强制使用固定的输出限制，请在设置中配置 samplingParams.max_tokens 或使用 QWEN_CODE_MAX_OUTPUT_TOKENS 环境变量。显式设置限制会禁用自动输出 token 升级机制。

toolResultContentFormat：

控制在兼容 OpenAI 的请求中如何序列化纯文本工具结果。默认值 "parts" 保持标准的内容部分（content-part）数组结构。仅当使用旧版兼容 OpenAI 的运行时（其工具模板会忽略文本内容部分，例如旧版 GLM-5.1 vLLM/SGLang 模板）时，才将其设置为 "string"。工具返回的媒体内容仍由 splitToolMedia 控制。

contextWindowSize：

覆盖所选模型的默认上下文窗口大小。Qwen Code 通过基于模型名称匹配的内置默认值以及一个固定的回退值来确定上下文窗口。当提供商的有效上下文限制与 Qwen Code 的默认值不同时，请使用此设置。此值定义的是模型假设的最大上下文容量，而不是每次请求的 token 限制。

当所选模型在 modelProviders 中定义时，请在该提供商条目的 generationConfig 中设置 contextWindowSize，而不是在顶层的 model.generationConfig 中设置。提供商模型条目是封闭的，因此顶层生成设置不会填充缺失的提供商字段。

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

fastModel

visionModel

voiceModel

modelFallbacks

modelPricing

context

排查文件搜索性能问题

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

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

tools

memory

有关 auto-memory 的工作原理以及如何使用 /memory、/remember 和 /dream 命令的详细信息，请参阅 Memory。

permissions

permissions 系统提供了细粒度的控制，用于决定哪些工具可以运行、哪些需要确认、哪些被阻止。

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

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

工具名称别名（在规则中使用以下任意一个均可）：

元类别：

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

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

规则语法示例：

路径模式前缀：

防止绕过 shell 命令：

当 agent 运行等效的 shell 命令时，也会强制执行 Read、Edit 和 WebFetch 的权限规则。例如，如果 Read(./.env) 在 deny 中，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。

slashCommands

控制在 CLI 中可用的 slash commands。在多租户或企业级部署中锁定命令范围时非常有用。

相同的拒绝列表也可以通过 --disabled-slash-commands CLI 参数（逗号分隔或重复使用）和 QWEN_DISABLED_SLASH_COMMANDS 环境变量提供；来自所有这三个来源的值会合并为并集。

示例 — 在沙盒部署中锁定内置命令：

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

将这些值配置在系统级的 settings.json（/etc/qwen-code/settings.json 或 QWEN_CODE_SYSTEM_SETTINGS_PATH）中后，用户无法从其自身的作用域缩小拒绝列表，并且被禁用的命令不会出现在自动补全中，输入时也不会执行。

[!note] 此设置仅控制 slash commands（例如 /auth、/mcp）。它不影响工具权限——相关配置请参阅 permissions.deny。它也不会拦截 Ctrl+C 或 Esc 等键盘快捷键。

skills

控制向模型暴露哪些 Skills。

mcp

lsp

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

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

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

security

advanced

experimental

mcpServers

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

telemetry

配置 Qwen Code 的日志和指标收集。更多信息，请参阅 telemetry。

settings.json 示例

以下是具有嵌套结构的 settings.json 文件示例，该结构自 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"]
  }
}

Shell 历史记录

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

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

环境变量与 .env 文件

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

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

环境变量表

命令行参数

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

对于沙箱镜像选择，优先级为： --sandbox-image > QWEN_SANDBOX_IMAGE > tools.sandboxImage > 内置默认镜像。

命令行参数表

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

虽然上下文文件严格来说不是用于配置 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 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.

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

• 分层加载与优先级： CLI 通过从多个位置加载上下文文件（例如 QWEN.md）来实现分层记忆系统。此列表中位置靠后（更具体）的文件内容通常会覆盖或补充位置靠前（更通用）的文件内容。确切的拼接顺序和最终上下文可以通过 /memory 对话框进行检查。典型的加载顺序如下：
  1. 全局上下文文件：
     • 位置：~/.qwen/<configured-context-filename>（例如用户主目录中的 ~/.qwen/QWEN.md）。
     • 作用域：为你的所有项目提供默认指令。
  2. 项目根目录及祖先目录上下文文件：
     • 位置：CLI 会在当前工作目录中搜索配置的上下文文件，然后向上搜索每个父目录，直到项目根目录（通过 .git 文件夹识别）或你的主目录。
     • 作用域：提供与整个项目或其重要部分相关的上下文。
• 拼接与 UI 指示： 所有找到的上下文文件的内容会被拼接在一起（带有指示其来源和路径的分隔符），并作为系统提示词的一部分提供。CLI 页脚会显示已加载上下文文件的数量，让你快速直观地了解当前激活的指令上下文。
• 导入内容： 你可以使用 @path/to/file.md 语法导入其他 Markdown 文件，从而将上下文文件模块化。更多详情请参阅记忆文档。
• 记忆管理命令：
  • 使用 /memory 打开记忆管理对话框。
  • 在对话框中刷新记忆，以重新扫描并从所有配置的位置重新加载上下文文件。
  • 有关 /memory 命令的完整详细信息，请参阅命令文档。

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

沙盒

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

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

• 使用 --sandbox 或 -s 标志。
• 设置 QWEN_SANDBOX 环境变量。
• 在设置中配置 tools.sandbox。

⚠️ --yolo 不会 自动启用沙盒。 YOLO 模式仅自动批准工具调用；仍必须通过 --sandbox、QWEN_SANDBOX 或 tools.sandbox 来选择启用沙盒。在使用 --yolo（或 --approval-mode=yolo）且没有沙盒的无头/非交互式运行中，模型可以在当前进程的权限级别执行 shell、写入和编辑工具——在这种情况下，Qwen Code 会向 stderr 打印警告。在权衡利弊后，可以使用 QWEN_CODE_SUPPRESS_YOLO_WARNING=1 来抑制此警告。

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

对于特定于项目的沙盒需求，你可以在项目根目录的 .qwen/sandbox.Dockerfile 处创建一个自定义 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
  }
}