GitHub 开源 Qwen-MM-Plugins 小白入门，给 Codex 装上多模态工具箱

把一张 4K 仪表盘截图交给 AI 编程助手，要求它读出所有数字。这个任务看着只差一句提示词，程序真正做起来却要连续解决几件事。图片怎样缩放，细小文字要不要再放大，什么时候该转 OCR，返回结果又怎样送回模型。换成两小时视频、带图表的 PDF 或 3D 模型，文件处理还会继续变复杂。

Qwen 团队新开源的 Qwen-MM-Plugins 就在处理这一段。它给 Codex、Claude Code、Qwen Code 等 Agent Harness 提供 Skill 和 MCP 工具，让 AI 可以按任务读取图片、视频和文档，也能接入 OCR、目标定位、语音识别、联网搜索、视频记忆与 3D 软件。

我在 2026 年 8 月 10 日核对了仓库的中英文 README、安装文档、pyproject.toml、插件清单、核心 Skill、MCP 框架和多个工具处理器，也查看了 Issues、许可证与安全说明。GitHub API 当晚显示 831 Stars、42 Forks 。仓库创建于 2026 年 7 月 29 日，当前源码版本写作 1.0.0，尚未发布正式 Release，main 分支仍在快速更新。

📚 专栏介绍《GitHub小白开源成长课》

这个专栏写给计算机初学者、大学生和刚接触 AI 开源项目的读者。

每篇文章挑一个值得动手的 GitHub 项目，读源码，查依赖，也把费用、许可证和使用边界讲清楚。读完以后，你至少能判断这个项目解决什么问题，自己能不能跑，以及下一步该从哪个文件学起。

如果你正在从"会收藏项目"走向"能读懂项目"，可以关注这个专栏。后面还会继续拆解 AI 编程、多模态工具和 AI 内容创作方向的开源项目。

AI 编程助手为什么还要装一套多模态插件

一个 Agent 能不能读图片，通常取决于三处条件。模型本身要支持视觉输入，宿主程序要能把文件交给模型，任务复杂时还要有负责渲染、抽帧或识别的工具。任何一处缺失，用户都可能得到一句"我无法直接查看这个文件"。

Qwen-MM-Plugins 把第三处整理成了可单独安装的能力包。当前插件市场列出七项可用能力。

能力	适合处理的任务	小白要先知道的条件
`core`	读图片、视频、文档与 3D 文件，提供 OCR、目标定位、ASR 和搜索	最适合作为第一站，部分功能需要 API Key
`video-memory`	为长视频构建层次化图记忆，再按时间和语义检索	构建与查询都需要 DashScope Key
`omni-av`	音视频转写、分段描述、时间定位、事件计数与音乐标签	默认调用 Qwen-Omni 服务
`video-edit`	视频剪辑工作流与图片、视频、音频生成	生成类服务会产生费用
`blender`	驱动正在运行的 Blender 建模、加材质和渲染	工具可以在 Blender 内执行 Python
`freecad`	驱动正在运行的 FreeCAD 建模、导出与 FEM 分析	需要 FreeCAD 与随包插件
`edu-agent`	把数学或理科题做成中文讲解视频或交互页面	纯 Skill，Node、Chromium、TTS 等依赖要手动准备

项目名里的 MM 可以理解为 MultiModal，也就是多模态。这里的插件也不局限于"让 Qwen 模型看图"。仓库已经为 Codex 等多种 Harness 准备了插件清单，MCP 工具返回的内容会继续交给当前 Harness 使用的模型。

这也带来第一个判断。只想让 Codex 读一张图片的人，先装 core 就够了。七项能力一次装齐，会提前拉入 3D、视频生成和长视频记忆所需的依赖，排错范围随之变大。

Skill 指路，MCP 工具动手

Qwen-MM-Plugins 的每项能力通常由两部分组成。

Skill 是一份写给模型看的使用说明。src/capabilities/core/skill/SKILL.md 会告诉 Agent 当前有哪些工具，遇到图片、视频、网页或 PDF 时应该怎样选择，还写了分辨率预算和视频抽帧策略。

MCP Server 是真正执行工作的 Python 程序。它通过标准输入输出与 Harness 通信，把 read_image、visualize、ocr 等函数暴露给 Agent。模型选定工具后，Harness 传入文件路径与参数，MCP Server 读取或处理文件，再把文字、图片或生成文件送回来。

可以把 Codex 看成工作台。Skill 放着操作手册，MCP Server 放着扳手和仪器。只复制 Skill，模型会知道应该做什么，手边仍然没有可调用的工具。只注册 MCP Server，工具虽然存在，模型缺少完整的选择和使用说明，调用质量也可能下降。

当前 core 源码会自动发现 15 个工具。它们分布在读取器、可视化器、外部 API 和结果生成器四组目录中。

一组工具	代表工具	做了什么
本地读取	`read_image`、`read_video`、`media_info`	读取图片，按时间抽视频帧，查看编码和时长
文件可视化	`visualize`	把 PDF、Office、代码、表格、3D 等文件转成模型可读的内容
外部识别	`vision_chat`、`ocr`、`grounding`、`transcribe_audio`	调用 DashScope 模型理解画面和声音
联网能力	`web_search`、`web_extractor`、`image_search`	通过 Serper 搜网页或反向搜图
结果处理	`crop`、`draw_bbox`、`save_view`	裁图、画框和保存指定页面或视频帧

源码里的动态分辨率也很具体。read_image 会按 small、normal、large 三档预算缩放图片，并把宽高对齐到 32 像素的网格。默认 normal 大约按 1024 个视觉 Token 的像素预算处理。它随后把图片编码成内容块返回给模型。

这套处理可以减少过大图片占用的上下文，也能把很小的图片适当放大。它不会凭空恢复已经丢失的文字。原图模糊、压缩严重或截图缺了一角，模型仍然只能根据现有像素判断。

官方 Codex 案例里发生了什么

项目的 core Cookbook 给出了一段 Codex 官方轨迹。用户先让 Codex 找出图片中的蛋糕并画框，随后又让它识别另一张图片中的地点，并用联网搜索交叉核对。

这是一个很合适的入门案例，因为它连续用到了观察、定位、标注和验证。仓库没有在 README 里给出统一准确率，也没有公布这组案例的完整评测数据，所以我们可以学习调用流程，不能拿一段演示证明它对所有图片都可靠。

蛋糕定位对应 grounding 工具。处理器会把图片和定位提示发给默认模型 qwen3.7-plus，要求模型返回归一化到 0 至 1000 的边界框。源码再根据原图宽高换算成像素坐标。用户需要可视化结果时，draw_bbox 使用 Pillow 在原图副本上画框，并尝试寻找支持中文的字体。

地点识别多了一步外部核对。模型先根据画面形成候选，再用搜索结果确认。这里能看出插件对工具边界的态度。画面相似不等于身份已经确认，特定地点、人物、物种或事件需要额外证据。

反向搜图的隐私代价也藏在这条流程里。Serper Lens 需要公开图片网址。image_search.py 发现输入是本地文件时，会先要求 allow_public_upload=true。用户同意后，图片或裁剪区域会上传到第三方公共图床 uguu.se，再进入搜索。源码和工具描述都提醒内容会离开本机并公开可访问。

因此，第一次练习可以用自己画的几何图或公开素材。身份证、实验原图、未公开论文截图和公司内部页面都不适合拿来试反向搜图。

本地读取和云端识别走的是两条路

README 写着"原生读图、视频、文档不需要 Key"。这句话只描述插件自身是否调用 DashScope。文件经过 read_image 或 visualize 处理以后，返回内容仍要交给 Agent 使用的模型。你在云端模型上运行 Codex，图片或渲染页面仍可能进入该模型的请求。

数据去向可以按下面这张表理解。

操作	插件会访问的外部服务	还要检查什么
`read_image`、`read_video`、`visualize`	插件处理阶段不要求 DashScope	Harness 使用的模型是否在云端，返回内容怎样保存
`ocr`、`grounding`、`vision_chat`	DashScope	账户地域、模型价格和服务数据政策
`transcribe_audio`	DashScope，或用户配置的自建 ASR 服务	音频是否包含个人信息和未公开谈话
`web_search`、`web_extractor`	Serper	查询词会发送给搜索服务
`image_search`	Serper，必要时还会访问 `uguu.se`	本地图公共上传需要用户明确同意
`blender`、`freecad`	本机正在运行的 3D 软件，也可能访问素材服务	工具可以执行 Python，要按本地代码执行管理权限

项目提供了一些默认上限来控制资源占用。visualize 默认最多处理 20 页，read_video 的返回帧数默认硬上限为 600，单次工具响应默认上限为 15 MiB。vision_chat 处理本地视频时默认最多抽 128 帧，参数会限制在 250 帧以内。源码建议超过约 40 分钟的视频改用 read_video，长视频问答则可以考虑 video-memory。

这些数值都是当前版本的工程默认值。提高上限会增加内存、传输和模型上下文开销，也可能触发更高 API 费用。

安装前先看清自己的系统

pyproject.toml 要求 Python 3.10 及以上。日常安装由 uvx 在第一次启动某项能力时创建隔离的 Python 环境。你还需要一个受支持的 Agent Harness，例如 Codex，以及能访问 GitHub 和 Python 包源的网络。

不同文件类型还会用到系统工具。

系统工具	相关功能	Ubuntu 安装提示	macOS 安装提示
`ffmpeg` 与 `ffprobe`	视频读取、媒体信息、ASR、长视频记忆和视频编辑	`sudo apt install ffmpeg`	`brew install ffmpeg`
LibreOffice	Office 与 DrawIO 可视化	`sudo apt install libreoffice`	`brew install --cask libreoffice`
Blender	3D 文件的高质量渲染	`sudo apt install blender`	`brew install --cask blender`
TeX Live	编译 LaTeX 文件	`sudo apt install texlive-latex-base texlive-latex-extra`	按 TeX Live 官方说明安装
Chromium	网页截图	`playwright install chromium`	`playwright install chromium`

Blender 属于可选项。没有它时，部分 3D 可视化会回退到 matplotlib。Office、LaTeX 和网页截图则要准备各自的外部程序。

仓库当前没有 Dockerfile 或 docker-compose.yml，也没有 .env.example。官方路线是插件市场加 uvx，密钥与参数写进 ~/.qwen-mm-plugins/config，或通过系统环境变量提供。

Windows 用户要多走一步。官方文档当前只支持 WSL2，原生 Windows 尚未验证。先在管理员 PowerShell 安装 Ubuntu。

powershell 复制代码

wsl --install -d Ubuntu

重启 Windows 和 Codex 后，把 Codex 的 Agent 环境切到 WSL2。仓库应该克隆到 WSL 的 home 目录，例如 ~/code，不要放在 /mnt/c 这类 Windows 挂载盘下。

一条稳妥的安装路线

官方 README 给出的快捷命令会把远程脚本直接交给 Bash。

bash 复制代码

curl -fsSL https://raw.githubusercontent.com/QwenLM/Qwen-MM-Plugins/main/install.sh | bash

这条命令很省事，也要求你在执行前信任远端 main 分支。初学者可以多走两步，先克隆并查看脚本，再运行同一份官方安装器。

bash 复制代码

cd ~
git clone https://github.com/QwenLM/Qwen-MM-Plugins.git
cd Qwen-MM-Plugins
git rev-parse HEAD
less install.sh
bash install.sh

安装器会让你选择 Harness 和能力。第一次只勾选 core。它还可以执行配置、自检和卸载，配置文件写到 ~/.qwen-mm-plugins/config。

想直接使用 Codex 自己的插件命令，也可以执行当前 README 提供的两条命令。

bash 复制代码

codex plugin marketplace add https://github.com/QwenLM/Qwen-MM-Plugins.git
codex plugin add qwen-mm-plugins-core@qwen-mm-plugins

已经添加过这个 Marketplace，准备获取后来新增的能力时，先更新市场信息。

bash 复制代码

codex plugin marketplace upgrade qwen-mm-plugins

随后在克隆目录运行配置和验证。

bash 复制代码

bash install.sh configure
bash install.sh verify

verify 会预拉取所选能力的 uvx 环境，检查 API Key 和系统工具。第一次启动可能花一段时间，因为 core 会带上 PDF、表格、GIS、3D 与网页可视化所需的一批 Python 包。

需要使用云端工具时，配置文件大致会出现下面这些字段。示例全部使用占位符。

env 复制代码

DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY
SERPER_API_KEY=YOUR_SERPER_API_KEY
SAM3_SERVER_URL=http://127.0.0.1:8787

日常只读图片和文档，可以先不填任何 Key。OCR、目标定位、视觉对话和 DashScope ASR 需要 DASHSCOPE_API_KEY。联网搜索需要 SERPER_API_KEY。图像分割要自己启动 SAM3 服务并填写地址。

密钥不要写进提示词、截图或仓库文件。安装器会尝试把配置权限设为 0600，提交代码前仍应检查 git status。

费用从哪里产生

Qwen-MM-Plugins 本身采用 Apache-2.0 许可证，不收软件许可费。实际使用成本来自 Agent 模型、外部 API、本机计算和下载依赖。

read_image 与 visualize 不会额外调用 DashScope，返回内容会占用 Agent 模型的上下文。OCR、目标定位和视觉对话默认使用 qwen3.7-plus。阿里云百炼在 2026 年 8 月 10 日的华北 2 北京标准价表中，256K Token 以内的输入标价为每百万 Token 2 元，输出标价为每百万 Token 8 元。页面还可能出现限时折扣，模型别名、地域和价格也会变化，使用前应重新查看百炼模型价格。

语音识别、Omni 音视频理解、TTS 和图片视频生成使用各自模型，计费口径并不相同。video-memory 构建阶段还会做多次视觉理解与嵌入计算。项目因此没有给出"一段视频多少钱"的固定答案。

控制费用可以从任务规模入手。先处理一张公开小图，再试一页 PDF。视频先看媒体信息，限制时间范围和抽帧数。准备调用 API 时开启服务商的费用告警，任务结束后查看账单明细。免费额度只适合当作试用条件，不能写进长期预算。

安全和许可证边界

这个项目有几处权限很高的能力。

Blender 的主要建模工具可以在正在运行的 Blender 内执行任意 Python。FreeCAD 也提供执行 Python 的工具。脚本能访问什么，取决于对应应用进程拥有的权限。用于陌生仓库或不受信任提示时，应先使用隔离环境，并限制可访问目录。重要模型文件要保留备份。

插件清单当前通过 git+https://github.com/QwenLM/Qwen-MM-Plugins.git@main 启动 uvx 环境。帮助文本也说明每次启动会重新解析这个 Git 引用。仓库当前没有 Python 锁文件，多数可选依赖也没有固定到精确版本。个人学习可以跟随更新，团队和生产环境更适合审查源码后固定提交哈希与依赖版本，避免同一条命令在不同日期拉到不同代码。

Apache-2.0 允许使用、修改和分发，也包含专利授权条款。重新分发修改版时，需要附带许可证，修改过的文件应留下醒目标记，并保留相关版权、专利和署名说明。Blender 与 FreeCAD 能力还内置了第三方 MIT 许可代码，仓库分别提供 NOTICE.md。

代码许可证只约束这份项目源码。Qwen 模型、DashScope、Serper、公共图床和其他素材服务各有自己的条款。准备商用或提供在线服务时，要把这些条款分开检查。

我喜欢它的地方，也要接受它现在的限制

Qwen-MM-Plugins 最有价值的设计，是把能力拆成独立插件。一个刚入门的人可以只装 core，等真的要处理长视频或 3D 模型时再加新能力。Skill 与 MCP 的分工也很清楚，适合拿来学习 Agent 怎样发现工具、传参并接收结果。

文件支持范围很宽。PDF、Office、代码、表格、字幕、DrawIO、GIS 和 3D 文件都有对应路径。缺少外部程序时，工具会尽量返回明确提示，其他能力仍能继续用。仓库还提供测试、格式检查、贡献说明和私密漏洞报告入口。

现实限制同样明显。

项目创建还不到两周，当前没有正式 Release 或版本 Tag，main 更新速度很快。
Windows 原生环境尚未验证，Windows 用户需要 WSL2。
core 的完整可视化依赖较多，首次 uvx 冷启动可能较慢，也会占用更多磁盘空间。
新加入的 omni-av 已进入 README 和源码，架构图与部分安装说明还没有同步更新。一些 Cookbook 也仍标着待补充。
README 没有提供系统性的准确率、延迟或成本基准。
视觉模型会误读小字，也可能给出错误边界框。涉及票据、科研数据和工程尺寸时，必须保留人工核对。
GitHub 页面当前没有未关闭的 Issue 报告，但这只能说明当时没有公开待处理项。新项目的真实兼容性还要靠更多环境验证。

它适合愿意理解工具调用过程的初学者，也适合正在学习 MCP、计算机视觉应用或 AI Agent 的大学生。只想在原生 Windows 上点一下按钮、完全离线处理敏感材料，或者马上用于生产系统的人，可以先观望一段时间。

文件	先看什么
`README.zh.md`	能力清单、安装入口和快速示例
`docs/zh/installation.md`	Windows WSL2、各 Harness 配置和系统依赖
`.claude-plugin/marketplace.json`	七项可安装能力怎样登记到插件市场
`src/capabilities/core/skill/SKILL.md`	模型怎样选择读图、视频、搜索和 API 工具
`src/mcp_framework.py`	MCP 工具怎样自动注册、启动和检查系统环境
`src/shared/image.py`	动态分辨率、坐标换算和画框的基础函数
`src/capabilities/core/qwen_mm_plugins_core/readers/image.py`	一张图片怎样缩放并返回给模型
`src/capabilities/core/qwen_mm_plugins_core/visualizers/visualize.py`	文件扩展名怎样分派到不同渲染器
`src/capabilities/core/qwen_mm_plugins_core/apis/image_search.py`	公共上传同意怎样在代码里强制执行
`pyproject.toml`	Python 版本、依赖分组和七个命令行入口

第一次实践只做一件小事

准备一张自己制作的公开图片，里面放几行文字和一个简单图形。安装 core 后，在 Codex 中引用它，并明确限制工具范围。

text 复制代码

@sample.png 请使用 read_image 读取这张图片，列出能确认的文字和图形。不要联网，不要调用 image_search，也不要上传文件。

观察 Codex 有没有调用 read_image，工具返回了怎样的尺寸变化，最终回答是否忠于原图。第一轮先不配置 DashScope Key，也不碰真实票据。

读图链跑通后，再换一张公开的模拟票据，配置限额很低的测试 Key，尝试 OCR。

text 复制代码

@receipt-demo.png 请使用 ocr 提取文字，保留原有顺序，并单独列出无法确认的字符。不要调用 image_search。

把 OCR 结果和原图逐行对照。发现错字时，记录原图分辨率、工具参数和错误位置。这样的练习很小，却能让你真正看懂一次多模态工具调用经历了哪些环节。

如果你想继续学习这类项目，可以关注 《GitHub小白开源成长课》。后面还会继续拆解适合初学者动手的 AI 编程、MCP 与多模态开源工具。

关键官方资料

本文项目状态、Star 数、源码和价格页面核对日期为 2026 年 8 月 10 日。所有配图均根据当前源码流程重新绘制，未复制项目官方宣传图。

GitHub Qwen-MM-Plugins Codex MCP 多模态 AI Agent 开源项目 Python

GitHub 开源 Qwen-MM-Plugins 小白入门，给 Codex 装上多模态工具箱