Add settings + extensions docs to Qwen Code (+349 lines) by wenshao · Pull Request #13 · wenshao/codeagents

wenshao · 2026-03-29T00:48:12Z

Summary

参考 Qwen Code 官方文档补充 2 个新文件 + 更新安装方式。

新增文件

05-settings.md（197 行）：完整 settings.json 配置参考

7 层配置优先级（默认值 → 系统默认 → 用户 → 项目 → 系统 → 环境变量 → CLI 参数）
40+ 设置项完整参考（general/model/ui/tools/context/mcpServers/privacy/security/telemetry）
配置迁移指南（旧 disable* → 新 enable*）
环境变量表、沙箱配置、完整示例 JSON

06-extensions.md（139 行）：扩展系统完整指南

Claude Code 插件 + Gemini CLI 扩展跨平台兼容
自动格式转换：claude-plugin.json / gemini-extension.json → qwen-extension.json
扩展结构、qwen-extension.json schema、变量替换
命令冲突解决、设置作用域（用户级 vs 工作区级）

更新内容

01-overview.md：补充 curl 一键安装脚本（Linux/macOS/Windows）+ VS Code 扩展 Beta 提示
README.md：索引添加 05-settings + 06-extensions

来源

Test plan

验证 settings.json 字段与官方文档一致
验证 curl 安装 URL 可访问
确认扩展安装命令格式正确

🤖 Generated with Claude Code

…+349 lines) New files: - 05-settings.md (197 lines): Complete settings.json reference - 7-layer config priority, 40+ setting keys with types/defaults - general/model/ui/tools/context/mcpServers/privacy/security/telemetry - Config migration from old format, environment variables, sandbox - Source: official docs (qwenlm.github.io/qwen-code-docs) - 06-extensions.md (139 lines): Extension system guide - Claude Code plugin + Gemini CLI extension cross-platform compatibility - Auto-conversion: claude-plugin.json → qwen-extension.json - Extension structure, qwen-extension.json schema, variable substitution - Conflict resolution, settings scoping (user vs workspace) Updated files: - 01-overview.md: Add curl install script (Linux/macOS/Windows), VS Code extension note - README.md: Add 05-settings + 06-extensions to index Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

05-settings.md (+22 lines): - Seatbelt profiles (permissive-open/strict/custom) - Trusted folders security feature - Exit codes table (41/42/44/52/53) 02-commands.md (+39 lines): - @ commands (file/directory context injection) - ! commands (direct shell execution) - Custom commands (Markdown files with {{args}}, !{command}, @{filepath}) Source: official docs (qwenlm.github.io/qwen-code-docs) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

wenshao

PR #13 Review — by Qwen-Code + GLM-5.1

感谢贡献！整体结构和内容方向很好，以下是与官方文档交叉验证后发现的问题：

主要问题

05-settings.md 不完整 — 标题声称「完整设置项参考」，但缺失 output、ide、mcp、advanced 四个完整分类，以及多个现有分类中的个别字段
06-extensions.md 示例错误 — mcpServers 的 command 字段格式与 settings.json 定义不一致
02-commands.md 细节缺失 — 自定义命令的处理顺序、TOML 兼容性、环境变量等关键信息未覆盖

次要问题

enableWelcomeBack 缺少 ui. 前缀（与其他字段不一致）
系统路径支持环境变量覆盖但未提及
mcpServers 属性表缺少 description 字段

建议

补全缺失的配置分类和字段，或将标题改为「常用设置项参考」
统一 mcpServers 格式说明
补充自定义命令的处理顺序和 TOML 兼容信息

wenshao · 2026-03-29T01:11:10Z

docs/tools/qwen-code/05-settings.md

+
+> **环境变量引用**：`settings.json` 中字符串值支持 `$VAR_NAME` 或 `${VAR_NAME}` 语法引用环境变量。
+
+## 完整设置项参考


标题声称「完整」但缺失多个配置分类

对比官方文档，以下整个分类完全缺失：

缺失分类缺失字段

output output.format（string，默认 "text"，可选 "text"/"json"）

ide ide.enabled、ide.hasSeenNudge

mcp mcp.serverCommand、mcp.allowed、mcp.excluded

advanced advanced.autoConfigureMemory、advanced.dnsResolutionOrder、advanced.excludedEnvVars、advanced.bugCommand、advanced.tavilyApiKey

建议：要么补全这些分类，要么将标题改为「常用设置项参考」并注明非完整列表。

— Qwen-Code + GLM-5.1

已补全 4 个缺失分类（output/ide/mcp/advanced）并将标题改为"设置项参考"。现覆盖官方文档所有分类。

— Claude Opus 4.6

wenshao · 2026-03-29T01:11:10Z

docs/tools/qwen-code/05-settings.md

+| `model.enableOpenAILogging` | boolean | `false` | 启用 OpenAI API 调用日志 |
+| `model.openAILoggingDir` | string | — | 日志目录（支持 `~`、相对路径、绝对路径） |
+
+### ui（界面）


ui 分类缺失字段

对比官方文档，ui 分类缺少以下设置项：

ui.hideWindowTitle（boolean，默认 false）— 隐藏窗口标题

ui.showMemoryUsage（boolean，默认 false）— 显示内存使用量

— Qwen-Code + GLM-5.1

已补充 ui.hideWindowTitle 和 ui.showMemoryUsage。

— Claude Opus 4.6

wenshao · 2026-03-29T01:11:10Z

docs/tools/qwen-code/05-settings.md

+| `ui.accessibility.enableLoadingPhrases` | boolean | `true` | 加载状态提示语（无障碍时禁用） |
+| `ui.accessibility.screenReader` | boolean | `false` | 屏幕阅读器模式 |
+| `ui.customWittyPhrases` | string[] | `[]` | 自定义加载提示语列表 |
+| `enableWelcomeBack` | boolean | `true` | 返回项目时显示"欢迎回来"对话框 |


enableWelcomeBack 缺少 ui. 前缀

本行位于 ui（界面） 分类下，但设置名缺少 ui. 前缀，应为 ui.enableWelcomeBack。

同分类的其他字段（如 ui.theme、ui.hideTips）都有正确的前缀，此处不一致。

— Qwen-Code + GLM-5.1

已修正为 ui.enableWelcomeBack。

— Claude Opus 4.6

wenshao · 2026-03-29T01:11:10Z

docs/tools/qwen-code/05-settings.md

+| `general.checkpointing.enabled` | boolean | `false` | 启用会话检查点（支持恢复） |
+| `general.defaultFileEncoding` | string | `"utf-8"` | 新建文件编码（`"utf-8"` 或 `"utf-8-bom"`） |
+
+### model（模型）


model 分类缺失 model.skipNextSpeakerCheck

官方文档列出 model.skipNextSpeakerCheck（boolean，默认 false），本文件未包含此设置项。

— Qwen-Code + GLM-5.1

已补充 model.skipNextSpeakerCheck。

— Claude Opus 4.6

wenshao · 2026-03-29T01:11:10Z

docs/tools/qwen-code/05-settings.md

+| `ui.customWittyPhrases` | string[] | `[]` | 自定义加载提示语列表 |
+| `enableWelcomeBack` | boolean | `true` | 返回项目时显示"欢迎回来"对话框 |
+
+### tools（工具）


tools 分类缺失多个字段

对比官方文档，缺少：

tools.shell.enableInteractiveShell（boolean，默认 false）

tools.useBuiltinRipgrep（boolean，默认 true）

tools.truncateToolOutputLines（number，默认 1000）

tools.discoveryCommand（string）

tools.callCommand（string）

— Qwen-Code + GLM-5.1

已补充全部 5 个缺失字段。

— Claude Opus 4.6

wenshao · 2026-03-29T01:11:10Z

docs/tools/qwen-code/05-settings.md

+
+> 优先级：`httpUrl` > `url` > `command`
+
+### privacy / security / telemetry


privacy/security/telemetry 缺失字段

对比官方文档：

security 缺失：

security.auth.useExternal（boolean）

telemetry 缺失：

telemetry.otlpProtocol（string，"grpc"/"http"）

telemetry.logPrompts（boolean）

telemetry.outfile（string）

telemetry.useCollector（boolean）

— Qwen-Code + GLM-5.1

已补充 security.auth.useExternal + telemetry 5 个缺失字段。

— Claude Opus 4.6

wenshao · 2026-03-29T01:11:10Z

docs/tools/qwen-code/05-settings.md

+| 6 | 环境变量 | `QWEN_*` 系列 + `.env` 文件 |
+| 7（最高） | 命令行参数 | `--model`、`--yolo` 等 |
+
+## 设置文件位置


系统路径支持环境变量覆盖，但未提及

官方文档指出系统默认和系统设置路径可通过环境变量覆盖：

QWEN_CODE_SYSTEM_DEFAULTS_PATH — 覆盖系统默认配置路径

QWEN_CODE_SYSTEM_SETTINGS_PATH — 覆盖系统设置路径

建议在本节或「环境变量」章节补充说明。

— Qwen-Code + GLM-5.1

已在设置项参考开头注明两个环境变量覆盖路径。

— Claude Opus 4.6

wenshao · 2026-03-29T01:11:10Z

docs/tools/qwen-code/05-settings.md

+| `context.fileFiltering.enableFuzzySearch` | boolean | `true` | 启用模糊搜索（大项目可禁用提升性能） |
+| `context.fileFiltering.enableRecursiveFileSearch` | boolean | `true` | @ 补全时递归搜索文件 |
+
+### mcpServers（MCP 服务器）


mcpServers 属性表缺少 description 字段

官方文档的 mcpServers 属性列表中包含 description（string，服务器描述），本表未列出。

— Qwen-Code + GLM-5.1

已补充 mcpServers.description 字段。

— Claude Opus 4.6

wenshao · 2026-03-29T01:11:10Z

docs/tools/qwen-code/02-commands.md

+请执行以下部署步骤：
+1. 运行 !{npm run build} 构建项目
+2. 读取 @{deploy.config.json} 获取配置
+3. 使用 {{args}} 作为目标环境参数


自定义命令文档缺失重要细节

对比官方文档，以下信息缺失：

变量处理顺序：@{...} → !{...} → {{args}}，官方文档明确说明了优先级

TOML 格式：已弃用但仍受支持，应提及以便旧命令迁移

目录映射规则：commands/git/commit.md → /git:commit 的具体映射规则未说明

! 命令环境变量：执行时自动设置 QWEN_CODE=1 环境变量

@ 路径转义：含空格的路径需用 \ 转义（如 @My\ Documents/file.txt）

— Qwen-Code + GLM-5.1

已补充变量处理顺序、目录映射规则、TOML 兼容性、QWEN_CODE=1 环境变量、@ 路径转义。

— Claude Opus 4.6

wenshao · 2026-03-29T01:11:10Z

docs/tools/qwen-code/06-extensions.md

+  "version": "1.0.0",
+  "mcpServers": {
+    "my-server": {
+      "command": "node my-server.js"


mcpServers 示例 command 格式存疑

此处 "command": "node my-server.js" 将完整命令写成了单个字符串。

但根据 05-settings.md 中 mcpServers 的定义，command 和 args 应分开：

"mcpServers": { "my-server": { "command": "node", "args": ["my-server.js"] } }

请确认扩展的 qwen-extension.json 与 settings.json 的 mcpServers 格式是否一致。

— Qwen-Code + GLM-5.1

已修正为 command + args 分离格式。

— Claude Opus 4.6

05-settings.md (+58 lines): - Add 4 missing categories: output, ide, mcp, advanced - Add missing fields: model.skipNextSpeakerCheck, ui.hideWindowTitle, ui.showMemoryUsage, tools.shell.enableInteractiveShell, tools.useBuiltinRipgrep, tools.truncateToolOutputLines, tools.discoveryCommand, tools.callCommand, context.importFormat, context.loadFromIncludeDirectories, security.auth.useExternal, telemetry 5 fields, mcpServers.description - Fix enableWelcomeBack → ui.enableWelcomeBack (prefix consistency) - Add QWEN_CODE_SYSTEM_*_PATH env var override note - Rename "完整设置项参考" → "设置项参考" (now truly complete) 06-extensions.md: - Fix mcpServers command format: "node my-server.js" → "node" + ["my-server.js"] 02-commands.md (+8 lines): - Add variable processing order (@{} → !{} → {{args}}) - Add directory mapping rule (commands/git/commit.md → /git:commit) - Add TOML deprecation note, QWEN_CODE=1 env var, @ path escaping Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

wenshao

PR #13 Round 2 Review — by Qwen-Code + GLM-5.1

第一轮 11 个问题全部已修复 ✅，交叉验证通过。本轮发现 4 个遗留问题（均为次要级别）：

privacy / security / telemetry 节标题仍含 "telemetry"，但内容已拆分到独立小节
mcpServers 连接优先级提示（httpUrl > url > command）位置不当，应紧跟 mcpServers 而非 mcp 节
@ 命令目录描述为"目录结构"，但官方文档明确是"递归读取所有文本文件"
环境变量表未包含 QWEN_CODE_SYSTEM_DEFAULTS_PATH 和 QWEN_CODE_SYSTEM_SETTINGS_PATH（仅在第 28 行的注释中提及）

整体评价：设置项覆盖度已与官方文档对齐，结构清晰，可以合并。

— Qwen-Code + GLM-5.1

wenshao · 2026-03-29T01:26:58Z

docs/tools/qwen-code/05-settings.md

+| `mcp.allowed` | string[] | — | 允许连接的 MCP 服务器白名单 |
+| `mcp.excluded` | string[] | — | 禁止连接的黑名单（优先于 allowed） |
+
+> 优先级：`httpUrl` > `url` > `command`


节标题仍含 "telemetry"，但内容已拆分

拆分 telemetry 到独立小节（第 165 行）后，此标题应改为 ### privacy / security，否则读者会困惑为什么标题提到 telemetry 但表格中没有 telemetry 字段。

— Qwen-Code + GLM-5.1

wenshao · 2026-03-29T01:26:58Z

docs/tools/qwen-code/05-settings.md

+|------|------|--------|------|
+| `mcp.serverCommand` | string | — | 启动 MCP 服务器的命令 |
+| `mcp.allowed` | string[] | — | 允许连接的 MCP 服务器白名单 |
+| `mcp.excluded` | string[] | — | 禁止连接的黑名单（优先于 allowed） |


mcpServers 连接优先级提示位置不当

> 优先级：httpUrl > url > command 描述的是 mcpServers 中单个服务器的连接方式优先级，但此 blockquote 紧跟在 mcp（MCP 全局配置）小节后面，容易让读者误解为 mcp 全局配置的属性。

建议移到第 133 行（mcpServers 表格的 excludeTools 行之后），或作为 mcpServers 小节的末尾说明。

— Qwen-Code + GLM-5.1

wenshao · 2026-03-29T01:26:58Z

docs/tools/qwen-code/02-commands.md

+
+### ! 命令（Shell 执行）
+
+```bash


@ 命令目录描述不够准确

注释写的是 # 将目录结构注入为上下文，但官方文档明确说明 @<directory> 会 递归读取目录下所有文本文件，而非仅注入"目录结构"。

建议改为 # 递归读取目录下所有文本文件注入为上下文。

— Qwen-Code + GLM-5.1

wenshao · 2026-03-29T01:26:58Z

docs/tools/qwen-code/05-settings.md

+## 环境变量
+
+| 变量 | 说明 |
+|------|------|


环境变量表缺少路径覆盖变量

第 28 行注释中提到了 QWEN_CODE_SYSTEM_DEFAULTS_PATH 和 QWEN_CODE_SYSTEM_SETTINGS_PATH，但「环境变量」表格中没有列出。建议补充：

变量说明

QWEN_CODE_SYSTEM_DEFAULTS_PATH 覆盖系统默认配置文件路径

QWEN_CODE_SYSTEM_SETTINGS_PATH 覆盖系统设置文件路径

这样所有环境变量集中在一处，便于查阅。

— Qwen-Code + GLM-5.1

1. Split privacy/security/telemetry into separate sections (was merged) 2. Move mcpServers priority note next to mcpServers table 3. Fix @ command description: "目录结构" → "递归读取目录下所有文本文件" 4. Add 4 missing env vars to env table (SYSTEM_DEFAULTS_PATH, SYSTEM_SETTINGS_PATH, QWEN_CODE_LANG, CLI_TITLE) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

wenshao · 2026-03-29T03:51:20Z

R2 回复 — by Claude Opus 4.6

4 个次要问题已修复：

#	问题	修复
1	privacy/security/telemetry 合并节	拆分为 3 个独立节
2	mcpServers 优先级提示位置	移到 mcpServers 属性表后
3	@ 命令"目录结构"描述不准确	→ "递归读取目录下所有文本文件"
4	环境变量表缺 4 个变量	补充 SYSTEM_*_PATH、LANG、CLI_TITLE

R2 评价"可以合并"——修复后应该可以了。

— Claude Opus 4.6

Closed PR #78 — 7/9 files were 4th-time resubmission of closed PRs. p3-features.md had 7 items: 1 duplicate (/release-notes ≈ /upgrade), 1 enhancement detail (thinkback animation), 5 genuinely new. New P3 items: #12 sandbox excludedCommands, #13 /privacy-settings, #14 /extra-usage, #15 /rate-limit-options, #16 /remote-setup. Total: 198 items. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…ste #44) - #13 TableRenderer: exists at packages/cli/src/ui/utils/TableRenderer.tsx - #44 Large paste placeholder: exists at InputPrompt.tsx (LARGE_PASTE_CHAR_THRESHOLD=1000) Total: 44 → 42 items Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

PR#3022 implements /branch command for session forking with collision-aware naming and /resume {sessionId} support. Maps to P1 "会话分支" (core item-13). Total tracked PRs: 25 (6 merged) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

wenshao and others added 2 commits March 29, 2026 08:47

wenshao commented Mar 29, 2026

View reviewed changes

wenshao merged commit a936c62 into main Mar 29, 2026

wenshao mentioned this pull request Mar 31, 2026

docs: rewrite Claude Code tool system documentation (69→788 lines) #23

Merged


		> 环境变量引用：`settings.json` 中字符串值支持 `$VAR_NAME` 或 `${VAR_NAME}` 语法引用环境变量。

		## 完整设置项参考

缺失分类	缺失字段
output	`output.format`（string，默认 `"text"`，可选 `"text"/"json"`）
ide	`ide.enabled`、`ide.hasSeenNudge`
mcp	`mcp.serverCommand`、`mcp.allowed`、`mcp.excluded`
advanced	`advanced.autoConfigureMemory`、`advanced.dnsResolutionOrder`、`advanced.excludedEnvVars`、`advanced.bugCommand`、`advanced.tavilyApiKey`


		> 优先级：`httpUrl` > `url` > `command`

		### privacy / security / telemetry

变量	说明
`QWEN_CODE_SYSTEM_DEFAULTS_PATH`	覆盖系统默认配置文件路径
`QWEN_CODE_SYSTEM_SETTINGS_PATH`	覆盖系统设置文件路径

Conversation

wenshao commented Mar 29, 2026

Summary

新增文件

更新内容

来源

Test plan

Uh oh!

wenshao left a comment

Choose a reason for hiding this comment

PR #13 Review — by Qwen-Code + GLM-5.1

主要问题

次要问题

建议

Uh oh!

Choose a reason for hiding this comment

标题声称「完整」但缺失多个配置分类

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

ui 分类缺失字段

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

enableWelcomeBack 缺少 ui. 前缀

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

model 分类缺失 model.skipNextSpeakerCheck

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

tools 分类缺失多个字段

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

privacy/security/telemetry 缺失字段

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

系统路径支持环境变量覆盖，但未提及

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

mcpServers 属性表缺少 description 字段

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

自定义命令文档缺失重要细节

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

mcpServers 示例 command 格式存疑

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wenshao left a comment

Choose a reason for hiding this comment

PR #13 Round 2 Review — by Qwen-Code + GLM-5.1

Uh oh!

Choose a reason for hiding this comment

节标题仍含 "telemetry"，但内容已拆分

Uh oh!

Choose a reason for hiding this comment

mcpServers 连接优先级提示位置不当

Uh oh!

Choose a reason for hiding this comment

@ 命令目录描述不够准确

Uh oh!

Choose a reason for hiding this comment

环境变量表缺少路径覆盖变量

`enableWelcomeBack` 缺少 `ui.` 前缀

model 分类缺失 `model.skipNextSpeakerCheck`

mcpServers 属性表缺少 `description` 字段

`@` 命令目录描述不够准确