Qwen Code 扩展

Qwen Code 扩展将提示、MCP 服务器和自定义命令打包成一种熟悉且用户友好的格式。通过扩展，你可以扩展 Qwen Code 的功能并与他人分享这些功能。它们被设计为易于安装和共享。

扩展管理

我们提供了一套使用 qwen extensions 命令的扩展管理工具。

请注意，这些命令在 CLI 内部不受支持，但你可以使用 /extensions list 子命令列出已安装的扩展。

请注意，所有这些命令只有在重启后才会在活动的 CLI 会话中生效。

安装扩展

你可以使用 qwen extensions install 命令，通过 GitHub URL 或本地路径来安装扩展。

请注意，我们会创建已安装扩展的副本，因此你需要运行 qwen extensions update 来拉取本地定义的扩展和 GitHub 上扩展的更改。

qwen extensions install https://github.com/qwen-cli-extensions/security

这将安装 Qwen Code Security 扩展，该扩展提供对 /security:analyze 命令的支持。

卸载扩展

要卸载，请运行 qwen extensions uninstall extension-name，所以对于上面的安装示例：

qwen extensions uninstall qwen-cli-security

禁用扩展

默认情况下，扩展在所有工作区中都是启用的。你可以完全禁用一个扩展或仅为特定工作区禁用。

例如，qwen extensions disable extension-name 将在用户级别禁用该扩展，因此它会在所有地方被禁用。qwen extensions disable extension-name --scope=workspace 只会在当前工作区中禁用该扩展。

启用扩展

你可以使用 qwen extensions enable extension-name 来启用扩展。你也可以使用 qwen extensions enable extension-name --scope=workspace 从该工作区内部为特定工作区启用扩展。

如果你有一个在顶层禁用但在特定位置启用的扩展，这将非常有用。

更新扩展

对于从本地路径或 Git 仓库安装的扩展，你可以通过 qwen extensions update extension-name 明确更新到最新版本（反映在 qwen-extension.json 的 version 字段中）。

你可以通过以下命令更新所有扩展：

qwen extensions update --all

扩展创建

我们提供了一些命令来简化扩展开发。

创建模板扩展

我们提供了几个示例扩展：context、custom-commands、exclude-tools 和 mcp-server。你可以在这里 查看这些示例。

要将这些示例中的一个复制到开发目录中，请运行：

qwen extensions new path/to/directory custom-commands

链接本地扩展

qwen extensions link 命令会在扩展安装目录和开发路径之间创建一个符号链接。

这样你就不需要每次修改后都运行 qwen extensions update 来测试更改。

qwen extensions link path/to/directory

工作原理

启动时，Qwen Code 会在 <home>/.qwen/extensions 中查找扩展。

扩展以包含 qwen-extension.json 文件的目录形式存在。例如：

<home>/.qwen/extensions/my-extension/qwen-extension.json

qwen-extension.json

qwen-extension.json 文件包含扩展的配置。该文件具有以下结构：

{
  "name": "my-extension",
  "version": "1.0.0",
  "mcpServers": {
    "my-server": {
      "command": "node my-server.js"
    }
  },
  "contextFileName": "QWEN.md",
  "excludeTools": ["run_shell_command"]
}

• name: 扩展的名称。用于唯一标识扩展，并在扩展命令与用户或项目命令同名时进行冲突解决。名称应为小写字母或数字，使用短横线而不是下划线或空格。这是用户在 CLI 中引用你的扩展的方式。请注意，我们期望此名称与扩展目录名称匹配。
• version: 扩展的版本。
• mcpServers: 要配置的 MCP 服务器映射。键是服务器的名称，值是服务器配置。这些服务器将在启动时加载，就像在 settings.json 文件 中配置的 MCP 服务器一样。如果扩展和 settings.json 文件都配置了同名的 MCP 服务器，则 settings.json 文件中定义的服务器优先。
  • 请注意，除了 trust 之外，支持所有 MCP 服务器配置选项。
• contextFileName: 包含扩展上下文的文件名称。这将用于从扩展目录加载上下文。如果未使用此属性但扩展目录中存在 QWEN.md 文件，则会加载该文件。
• excludeTools: 要从模型中排除的工具名称数组。你也可以为支持的工具指定特定命令的限制，比如 run_shell_command 工具。例如，"excludeTools": ["run_shell_command(rm -rf)"] 将阻止 rm -rf 命令。请注意，这与 MCP 服务器的 excludeTools 功能不同，后者可以在 MCP 服务器配置中列出。重要： 在 excludeTools 中指定的工具将在整个对话上下文中被禁用，并会影响当前会话中的所有后续查询。

当 Qwen Code 启动时，它会加载所有扩展并合并它们的配置。如果有任何冲突，工作区配置优先。

自定义命令

扩展可以通过在扩展目录内的 commands/ 子目录中放置 TOML 文件来提供自定义命令。这些命令遵循与用户和项目自定义命令相同的格式，并使用标准命名约定。

示例

一个名为 gcp 的扩展，具有以下结构：

.qwen/extensions/gcp/
├── qwen-extension.json
└── commands/
    ├── deploy.toml
    └── gcs/
        └── sync.toml

将提供以下命令：

• /deploy - 在帮助中显示为 [gcp] 来自 deploy.toml 的自定义命令
• /gcs:sync - 在帮助中显示为 [gcp] 来自 sync.toml 的自定义命令

冲突解决

扩展命令具有最低优先级。当与用户或项目命令发生冲突时：

1. 无冲突：扩展命令使用其自然名称（例如，/deploy）
2. 有冲突：扩展命令使用扩展前缀重命名（例如，/gcp.deploy）

例如，如果用户和 gcp 扩展都定义了一个 deploy 命令：

• /deploy - 执行用户的部署命令
• /gcp.deploy - 执行扩展的部署命令（标记有 [gcp] 标签）

变量

Qwen Code 扩展允许在 qwen-extension.json 中进行变量替换。例如，如果你需要当前目录来运行 MCP 服务器，可以使用 "cwd": "${extensionPath}${/}run.ts"。

支持的变量：