Skip to Content
用户指南扩展简介

Qwen Code 扩展

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

来自 Gemini CLI Extensions Gallery 、Claude Code Marketplace 、Qoder 以及可移植的 Agent Plugins v1 格式的扩展和插件可以直接安装到 Qwen Code 中。这种跨平台兼容性让你能够访问丰富的扩展和插件生态，极大地扩展 Qwen Code 的功能，而无需扩展作者维护单独的版本。

扩展管理

我们提供了一套扩展管理工具，包括 qwen extensions CLI 命令以及交互式 CLI 中的 /extensions 斜杠命令。

运行时扩展管理（斜杠命令）

你可以在交互式 CLI 中使用 /extensions 斜杠命令在运行时管理扩展。这些命令支持热重载，即更改会立即生效，无需重启应用。

命令描述
/extensions 或 /extensions manage管理所有已安装的扩展
/extensions install <source>从 git URL、本地路径或归档、归档 URL、npm 包或市场安装扩展
/extensions explore [source]在浏览器中打开扩展来源页面（Gemini 或 ClaudeCode）

交互式扩展管理器

运行 /extensions（或 /extensions manage）会打开一个带有三个选项卡的交互式管理器。按 Tab 或 ←/→ 箭头键在它们之间切换。

  • 发现 — 浏览来自已配置市场来源的插件。输入进行搜索，按 Enter 查看插件详情并安装（系统会要求你选择安装范围）。按 Ctrl+R 重新获取列表，按 Esc 返回。
  • 已安装 — 已安装的扩展，按范围分组（用户级别、项目级别和收藏夹）。使用 ↑/↓ 导航，按 Space 启用/禁用扩展，按 f 收藏，按 Enter 打开详情。扩展捆绑的 MCP 服务器会嵌套显示在父扩展下，并显示实时连接状态；你可以在此处单独启用或禁用每个服务器。
  • 来源 — 管理“发现”选项卡所使用的市场来源。使用 ↑/↓ 导航，按 Enter 选择来源，按 d 删除来源。这些来源与下述 qwen extensions sources CLI 命令管理的来源相同。

在此处所做的更改会立即热重载，无需重启 Qwen Code。

CLI 扩展管理

你也可以使用 qwen extensions CLI 命令管理扩展。请注意，通过 CLI 命令所做的更改将在重启后反映到活动的 CLI 会话中。

安装扩展

你可以使用 qwen extensions install 从多个来源安装扩展：

从 Claude Code 市场

Qwen Code 也支持来自 Claude Code Marketplace  的插件。从市场安装并选择一个插件：

qwen extensions install <marketplace-name>
# 或
qwen extensions install <marketplace-github-url>

如果你想安装特定的插件，可以使用带插件名称的格式：

qwen extensions install <marketplace-name>:<plugin-name>
# 或
qwen extensions install <marketplace-github-url>:<plugin-name>

例如，从 f/awesome-chatgpt-prompts  市场安装 prompts.chat 插件：

qwen extensions install f/awesome-chatgpt-prompts:prompts.chat
# 或
qwen extensions install https://github.com/f/awesome-chatgpt-prompts:prompts.chat

Claude 插件在安装过程中会自动转换为 Qwen Code 格式：

  • claude-plugin.json 转换为 qwen-extension.json
  • 代理配置转换为 Qwen 子代理格式
  • 技能配置转换为 Qwen 技能格式
  • 工具映射会自动处理

你可以使用 /extensions explore 命令快速浏览不同市场的可用扩展：

# 打开 Gemini CLI Extensions 市场
/extensions explore Gemini
 
# 打开 Claude Code 市场
/extensions explore ClaudeCode

该命令会在默认浏览器中打开相应的市场，让你发现新的扩展来增强 Qwen Code 体验。

跨平台兼容性：这让你能够利用来自 Gemini CLI 和 Claude Code 的丰富扩展生态，极大地扩展 Qwen Code 用户可用的功能。

从 Gemini CLI Extensions

Qwen Code 完全支持来自 Gemini CLI Extensions Gallery  的扩展。只需使用 git URL 安装它们：

qwen extensions install <gemini-cli-extension-github-url>
# 或
qwen extensions install <owner>/<repo>

Gemini 扩展在安装过程中会自动转换为 Qwen Code 格式：

  • gemini-extension.json 转换为 qwen-extension.json
  • TOML 命令文件自动迁移为 Markdown 格式
  • MCP 服务器、上下文文件和设置保持不变

从 Qoder 插件

Qwen Code 支持包含 .qoder-plugin/plugin.json 清单的 Qoder 插件 。使用现有的 qwen extensions install 命令安装本地目录、归档、Git 仓库、归档 URL 或 scoped npm 包：

qwen extensions install ./sample-qoder-plugin
qwen extensions install ./sample-qoder-plugin.zip
qwen extensions install owner/sample-qoder-plugin

安装器会将 Qoder 清单转换为 qwen-extension.json，并保留标准的 commands/、agents/ 和 skills/ 目录。在根 .mcp.json 文件中声明的 MCP 服务器会作为扩展 MCP 服务器包含在内。

当 Qoder 插件在其根目录包含 system-prompt.md 时，Qwen Code 会将其作为扩展上下文加载。如果插件还包含 QWEN.md 或声明了其他上下文文件，所有上下文文件都会被保留并去重。

从 Agent Plugins v1

Qwen Code 原生加载可移植的 Agent Plugins v1 包，不会转换或重写 plugin.json、mcp.json 或 SKILL.md 文件：

qwen extensions install ./my-agent-plugin
qwen extensions link ./my-agent-plugin
qwen extensions install owner/my-agent-plugin

该可移植运行时支持 Agent Skills 以及 stdio 和 Streamable HTTP MCP 服务器。Commands、agents、hooks、client namespaces 和旧版 SSE MCP 不会被激活。完整的支持矩阵请参阅 Agent Plugins v1。

从 npm 注册表

Qwen Code 支持使用 scoped 包名从 npm 注册表安装扩展。这对于拥有私有注册表、且已有认证、版本管理和发布基础设施的团队来说非常理想。

# 安装最新版本
qwen extensions install @scope/my-extension
 
# 安装特定版本
qwen extensions install @scope/my-extension@1.2.0
 
# 从自定义注册表安装
qwen extensions install @scope/my-extension --registry https://your-registry.com

仅支持 scoped 包（@scope/package-name），以避免与 owner/repo GitHub 简写格式产生歧义。

注册表解析按以下优先级顺序进行：

  1. --registry CLI 标志（显式覆盖）
  2. 来自 .npmrc 的 scope 注册表（例如 @scope:registry=https://...）
  3. 来自 .npmrc 的默认注册表
  4. 回退：https://registry.npmjs.org/

身份认证会自动通过 NPM_TOKEN 环境变量或 .npmrc 中的注册表特定 _authToken 条目处理。

注意： npm 扩展必须在包根目录包含原生 qwen-extension.json 或 Agent Plugins v1 plugin.json。有关打包细节，请参阅 扩展发布。

从 Git 仓库

对于需要认证的、非 GitHub 的、嵌套市场、子模块和 Git LFS 来源，Git 2.37 或更新版本是必需的，因为 Qwen Code 使用 http.curloptResolve 将 Git 连接固定到已验证的 DNS 结果。在较旧的 Git 版本上，Qwen Code 仅支持匿名的公共 https://github.com/{owner}/{repo}[.git] 根仓库，方法是将请求的 ref 解析为 commit 并使用相同的公共网络和归档安全检查下载 GitHub 的源代码归档。

由于旧版 Git 回退从源代码归档而非克隆安装，因此无法安装依赖子模块或 Git LFS 的仓库，并且下载上限为压缩后 100 MiB，归档上限为 100,000 个条目 / 展开后 1 GiB / 8 MiB 路径元数据，包括从最多 100 个符号链接物化的文件。在允许创建符号链接的系统上，支持直接指向仓库中常规文件的符号链接；Windows 可能需要开发者模式或提升的权限。回退会拒绝目录链接、链式链接、悬空链接、绝对链接、逃逸链接、硬链接以及 POSIX 字面反斜杠目标链接。其他 Agent Plugin 安装路径继续省略符号链接。当仓库发布 release 时，仍然优先使用基于 release 的安装。

qwen extensions install https://github.com/github/github-mcp-server

这将安装 github mcp 服务器扩展。

从本地路径

qwen extensions install /path/to/your/extension

也支持本地的 .zip 和 .tar.gz 归档：

qwen extensions install /path/to/your/extension.zip
qwen extensions install /path/to/your/extension.tar.gz

归档必须在其根目录包含一个完整的扩展，或者包含一个包含扩展的顶级目录。

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

从归档 URL

qwen extensions install https://example.com/your/extension.zip
qwen extensions install https://example.com/your/extension.tar.gz

只要 URL 持续指向同一扩展的新归档，就可以稍后更新归档 URL。

选择安装范围

默认情况下，已安装的扩展在全局范围内启用（用户范围）。传递 --scope project 以仅针对当前工作区启用：

qwen extensions install <source> --scope project

--scope workspace 可以作为 --scope project 的别名接受。这与从 /extensions manage 的“发现”选项卡安装时提供的范围选择相匹配。

管理市场来源

市场来源（Claude 插件市场）为 /extensions manage 中的“发现”选项卡提供支持。你也可以从 CLI 管理它们：

# 添加市场（owner/repo、git URL、marketplace.json 的 https URL 或本地路径）
qwen extensions sources add <source>
 
# 列出已配置的市场
qwen extensions sources list
 
# 重新获取市场的插件列表
qwen extensions sources update <name>
 
# 删除市场
qwen extensions sources remove <name>

卸载扩展

要卸载，运行 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 为该工作区启用扩展。

如果你在顶层禁用了某个扩展，但希望在特定位置启用它，这将非常有用。

更新扩展

对于从本地路径或归档、归档 URL、git 仓库或 npm 注册表安装的扩展，你可以使用 qwen extensions update extension-name 显式更新到最新版本。对于未固定版本（例如 @scope/pkg）安装的 npm 扩展，更新会检查 latest 发行标签。对于使用特定发行标签（例如 @scope/pkg@beta）安装的扩展，更新会跟踪该标签。固定到确切版本（例如 @scope/pkg@1.2.0）的扩展始终被视为最新。

你可以使用以下命令更新所有扩展：

qwen extensions update --all

工作原理

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

原生 Qwen 扩展以包含 qwen-extension.json 文件的目录形式存在。Agent Plugins v1 包则保留其根 plugin.json；请参阅 Agent Plugins v1。

例如，原生 Qwen Code 扩展存储在：

<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"
    }
  },
  "channels": {
    "my-platform": {
      "entry": "dist/index.js",
      "displayName": "My Platform Channel"
    }
  },
  "contextFileName": "QWEN.md",
  "commands": "commands",
  "skills": "skills",
  "agents": "agents",
  "workflows": "workflows",
  "settings": [
    {
      "name": "API Key",
      "description": "Your API key for the service",
      "envVar": "MY_API_KEY",
      "sensitive": true
    }
  ]
}
  • name：扩展的名称。用于唯一标识扩展，并在扩展命令与用户或项目命令同名时进行冲突解决。名称应为小写或数字，并使用短横线代替下划线或空格。这是用户在 CLI 中引用扩展的方式。注意，我们期望此名称与扩展目录名称匹配。
  • version：扩展的版本。
  • mcpServers：要配置的 MCP 服务器映射。键是服务器名称，值是服务器配置。这些服务器将在启动时加载，就像在 settings.json 文件 中配置的 MCP 服务器一样。如果扩展和 settings.json 文件都配置了同名的 MCP 服务器，则以 settings.json 文件中定义的服务器为准。
    • 注意，除了 trust 之外，所有 MCP 服务器配置选项均受支持。
  • channels：自定义通道适配器的映射。键是通道类型名称，值包含 entry（编译后的 JS 入口点的路径）和可选的 displayName。入口点必须导出一个符合 ChannelPlugin 接口的 plugin 对象。请参阅 通道插件 以获取完整指南。
  • contextFileName：包含扩展上下文的文件名。用于从扩展目录加载上下文。如果未使用此属性但扩展目录中存在 QWEN.md 文件，则将加载该文件。
  • commands：包含自定义指令的目录（默认值：commands）。指令是定义提示词的 .md 文件。
  • skills：包含自定义技能的目录（默认值：skills）。技能会自动发现，并通过 /skills 命令可用。
  • agents：包含自定义子代理的目录（默认值：agents）。子代理是定义专门的 AI 助手的 .yaml 或 .md 文件。
  • workflows：一个目录，或包含 workflow 脚本的目录和 .js 文件列表（默认值：workflows）。请参阅自定义工作流。
  • settings：扩展所需的设置数组。安装时，系统会提示用户为这些设置提供值。这些值会安全存储，并作为环境变量传递给 MCP 服务器。
    • 每个设置具有以下属性：
      • name：设置的显示名称
      • description：此设置用途的描述
      • envVar：将要设置的环境变量名称
      • sensitive：布尔值，指示是否应隐藏该值（例如 API key、密码）

管理扩展设置

扩展可能需要通过设置（例如 API key 或凭证）进行配置。这些设置可以使用 qwen extensions settings CLI 命令进行管理：

设置设置值：

qwen extensions settings set <extension-name> <setting-name> [--scope user|workspace]

列出扩展的所有设置和当前值：

qwen extensions settings list <extension-name>

设置可以在两个级别进行配置：

  • 用户级别（默认）：设置适用于所有项目（~/.qwen/.env）
  • 工作区级别：设置仅适用于当前项目（.qwen/.env）

工作区设置优先于用户设置。敏感设置会安全存储，绝不会以明文形式显示。

当 Qwen Code 启动时，它会加载所有扩展并合并其配置。如果存在任何冲突，则以工作区配置为准。

自定义指令

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

注意： 指令格式已从 TOML 更新为 Markdown。TOML 文件已弃用，但仍受支持。你可以使用检测到 TOML 文件时出现的自动迁移提示来迁移现有的 TOML 指令。

示例

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

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

将提供以下指令：

  • /deploy - 在帮助中显示为 [gcp] Custom command from deploy.md
  • /gcs:sync - 在帮助中显示为 [gcp] Custom command from sync.md

自定义技能

扩展可以通过在扩展目录内的 skills/ 子目录中放置技能文件来提供自定义技能。每个技能应包含一个带有 YAML 前置元数据的 SKILL.md 文件，定义技能的名称和描述。

示例

.qwen/extensions/my-extension/
├── qwen-extension.json
└── skills/
    └── pdf-processor/
        └── SKILL.md   # frontmatter: name: pdf-processor

提供一个技能，注册为 gcp:pdf-processor —— 即扩展的 name、一个冒号、然后是 SKILL.md 作者所起的名称。使用 /gcp:pdf-processor 运行它；/skills 会列出它并以扩展的显示名称标注，当清单未声明显示名称时回退到 name。

与扩展的自定义指令不同（自定义指令按文件名命名——如上述的 /deploy 和 /gcs:sync，仅在冲突时添加前缀——参见下文冲突解决），扩展技能始终携带其所有者：两个扩展都附带 pdf-processor 会给你两个技能，而不是一个遮蔽另一个。前缀在技能加载时添加，因此 SKILL.md 中的 name 永远不会在磁盘上被改写。

以技能名称为参数的设置对两种拼写的处理是不对称的：skills.disabled 在任一名称下都会阻止技能，而 skills.enabled 仅在带前缀的名称下将其启用。请参阅扩展技能。

自定义子代理

扩展可以通过在扩展目录内的 agents/ 子目录中放置代理配置文件来提供自定义子代理。代理使用 YAML 或 Markdown 文件定义。

示例

.qwen/extensions/my-extension/
├── qwen-extension.json
└── agents/
    └── testing-expert.yaml

扩展子代理会出现在子代理管理器对话框的“扩展代理”部分。

自定义工作流

扩展可以通过在 workflows/ 子目录中放置 .js 文件，或者在清单的 workflows 中列出的目录和文件中放置 .js 文件来发布 workflow 脚本。它们仅在通过 tools.workflowsEnabled 设置启用 Workflows 时才会显示，该设置默认关闭；安装同意提示无论如何都会列出它们。

示例

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

.qwen/extensions/gcp/
├── qwen-extension.json
└── workflows/
    └── deep-research.js

当其脚本声明一个静态 meta 对象且 name: 'deep-research' 时，提供一个 workflow，注册为 gcp:deep-research —— 即扩展的 name、一个冒号、然后是 meta.name。使用 /gcp:deep-research 运行它，从另一个 workflow 中使用 workflow('gcp:deep-research') 调用它，或让模型通过 Workflow({ name: 'gcp:deep-research' }) 按名称运行它。与扩展 skill 类似，扩展 workflow 始终携带其所有者，因此它永远不会遮蔽你的项目或用户 workflow。如果同一扩展还附带了同名的 skill，该 skill 保留 /gcp:deep-research，而 workflow 的斜杠命令被重命名为 /gcp.gcp:deep-research，与任何冲突的扩展命令一样；写为 gcp:deep-research 的 slashCommands.disabled 条目仍然会同时移除两者。具有相同名称的用户或项目自定义命令（例如 commands/gcp/deep-research.md）最后加载并获得斜杠命令，此时 workflow 仍可通过 workflow('gcp:deep-research') 访问。

每个脚本必须声明一个静态 export const meta = { name, description } 块。description 显示在安装同意提示和命令列表中。文件名可以与 meta.name 不同；调用始终使用元数据名称。如果多个脚本声明相同的 meta.name，则保留第一个发现的脚本。超过 500 字符的 description 会在显示时被缩短。

脚本还可以声明 whenToUse，一个说明 workflow 何时适用的句子：

export const meta = {
  name: 'deep-research',
  description: 'Researches a question across the codebase and the web',
  whenToUse:
    'When the user asks for a sourced, multi-angle answer to an open question',
};

只有声明了 whenToUse 的 workflow 才会连同其描述一起被列给模型，以便模型在请求匹配时启动它；每次运行仍需经过 workflow 审批。没有它，模型看不到该 workflow，此时它仅在你调用它、按名称请求它或另一个 workflow 调用它时运行。whenToUse 超过 500 字符时会被缩短，与 description 一样，并且由于它存在于脚本中，更改它会使下次更新再次请求同意。

在交互式 UI 中，/gcp:deep-research 直接启动 workflow。在无头模式和通过 ACP 时，同一命令会要求模型按名称运行它，随后进行审批。

要让模型启动你扩展的 workflows 而不允许它编写和运行自己的脚本，请使用 tools.workflowNameOnly（或 QWEN_CODE_WORKFLOW_NAME_ONLY=1）进行部署，并按名称允许 workflows，例如 Workflow(name:gcp:deep-research)。该锁使模型启动的每次运行都可通过此类规则寻址；它本身不会批准任何内容，因此请继续请求你尚未允许的名称。

发现过程刻意保持狭窄：

  • 仅读取每个目录内的 .js 文件；子目录会被忽略。
  • meta.name 必须使用小写字母、数字和短横线，以字母开头，最多包含 41 个字符。
  • 每个声明的路径必须保持在扩展目录内。链接的扩展（qwen extensions link）会跳过符号链接的 workflow 文件和目录；已安装的扩展是一个副本，其中每个符号链接都已被其指向的文件替换。
  • 大于 256 KiB 的脚本或缺少有效 meta 块的脚本会被跳过并显示警告。

安装扩展会在同意提示中列出其 workflows。当更新添加或移除 workflow、更改 workflow 的名称或描述或更改脚本的代码时会再次请求同意；当仅代码更改时，提示会命名已更改的脚本。扩展 workflows 遵循与你自己的已保存 workflows 相同的规则：它们在不受信任的文件夹中和在 bare 模式下被隐藏，每次运行都经过通常的 workflow 审批，该审批显示脚本的开头。按名称或路径运行的“始终允许”被保存为固定到脚本内容的规则，例如 Workflow(name:gcp:deep-research,sha256:3f2a9c1d0b4e5f67)，因此一旦脚本更改它就会停止应用。你不带 sha256 编写的规则，例如 Workflow(name:gcp:deep-research)，允许该脚本的每个版本。

对默认 workflows/ 目录中文件的编辑会被自动获取。其他声明路径下的更改在 /reload-plugins 或重启后生效。

附带 workflows 的 Claude Code 插件会在安装时被转换。未声明 workflows 的插件保留其 workflows/ 目录，该目录作为默认值被发现。当插件声明 workflows 时，声明的文件保留其相对路径并在转换后的扩展清单中显式列出，并且仅发现这些文件：不同目录中具有相同基本名称的文件在其 meta.name 值下保持不同，插件同时附带的 workflows/ 目录会被复制但不会被读取。声明目录内的符号链接在其目标保持在插件内时会被复制为常规文件。

冲突解决

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

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

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

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

变量

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

支持的变量：

变量描述
${extensionPath}扩展在用户文件系统中的完整路径，例如 ‘/Users/username/.qwen/extensions/example-extension’。不会解引用符号链接。
${workspacePath}当前工作区的完整路径。
${/} 或 ${pathSeparator}路径分隔符（因操作系统而异）。
Last updated on
主题Agent 插件