Configuration
For most setups, open Configure in install.sh. It stores shared settings in
~/.qwen-mm-plugins/config as KEY=VALUE lines with mode 600. Qwen-MM-Plugins components launched
by any harness read that file. A process environment variable overrides the same key in the file.
Use QWEN_MM_CONFIG=/path/to/file to select another file, or QWEN_MM_CONFIG_DIR=/path/to/dir to
change the directory containing the default config file. These bootstrap variables must be set
in the process environment because they determine which file is read.
Model output mode
QWEN_MM_NATIVE_MODE=1 is the default. MCP tools return native image content blocks so a
multimodal host model can inspect the original visual result directly.
Set QWEN_MM_NATIVE_MODE=0 when the host model is text-only. Every returned image block is replaced
at the same position by a generated caption, while existing text blocks (file metadata, PDF text
layers, video timestamps, and similar context) are preserved. The caption path uses
DASHSCOPE_BASE_URL and QWEN_MM_API_VL_MODEL. Credentials are selected by endpoint: DashScope uses
DASHSCOPE_API_KEY, OrcaRouter uses ORCAROUTER_API_KEY, and OpenRouter uses OPENROUTER_API_KEY.
Authentication-free local endpoints need no key configuration. A failed caption call produces an explicit
Visual content unavailable text block instead of exposing base64 or silently dropping the image.
Enabling text-only mode sends tool-result images—including local files and application or desktop screenshots—to the configured VL endpoint. Use it only when that data may be shared with the endpoint. Invalid mode values fail safe to native mode and do not trigger an upload.
Search selection
Leave QWEN_MM_SEARCH_BACKEND unset or set it to auto to select the first configured key in this
fixed order: Serper, Tavily, Exa, Serply. Set it to serper, tavily, exa, or serply to pin one
provider; a
missing matching key then raises an error instead of falling back. image_search always uses
Serper Lens and therefore always requires SERPER_API_KEY.
Configure catalog
This is the complete catalog shown by the installer's Configure action. Defaults and grouping
come from CONFIG_FIELDS; — means unset or disabled.
Media APIs & endpoints
| Variable | Default | Purpose |
|---|---|---|
DASHSCOPE_API_KEY | — | vision, OCR, grounding, text-only image captions, ASR, generation, memory builds (secret) |
ORCAROUTER_API_KEY | — | OpenAI-compatible calls to api.orcarouter.ai (secret) |
OPENROUTER_API_KEY | — | OpenAI-compatible calls to openrouter.ai (secret) |
MINIMAX_API_KEY | — | MiniMax text-to-speech generation (secret) |
DASHSCOPE_BASE_URL | DashScope compat URL | override the DashScope OpenAI-compatible base URL |
QWEN_MM_API_VL_MODEL | qwen3.7-plus | default VL model for vision_chat, OCR, grounding, and text-only image captions |
QWEN_MM_API_OMNI_MODEL | qwen3.5-omni-plus | default Omni model for audio/video understanding tools, omni-memory, and Omni ChatCut |
SAM3_SERVER_URL | — | segmentation SAM3 server URL |
ASR_SERVER_URLS | — | self-hosted ASR fallback URLs (comma-separated) |
Omni ChatCut
| Variable | Default | Purpose |
|---|---|---|
QWEN_MM_OMNI_CHATCUT_MODEL_CONFIG | — | path to the shared Omni, image-provider, and video-provider connection JSON |
QWEN_MM_DUBBING_SERVER_URL | — | external IndexTTS2/Demucs/TEN-VAD service used by video translation |
Search providers
| Variable | Default | Purpose |
|---|---|---|
QWEN_MM_SEARCH_BACKEND | auto | text search backend (auto: serper > tavily > exa > serply; or choose one) |
SERPER_API_KEY | — | Serper web_search / web_extractor and Serper-only image_search (secret) |
TAVILY_API_KEY | — | Tavily web_search / web_extractor (secret) |
EXA_API_KEY | — | Exa web_search / web_extractor (secret) |
SERPLY_API_KEY | — | Serply web_search / web_extractor (secret) |
Runtime paths & limits
| Variable | Default | Purpose |
|---|---|---|
QWEN_MM_CACHE | OS cache dir | cache dir for derived render artifacts |
QWEN_MM_FFMPEG_TIMEOUT | 120 | ffmpeg/ffprobe timeout seconds |
QWEN_MM_CHAT_TIMEOUT | tool-specific (600; Omni 1800) | OpenAI-compatible chat request timeout seconds |
QWEN_MM_NATIVE_MODE | 1 | 1 returns MCP images; 0 sends images to the VL endpoint and returns captions |
QWEN_MM_MAX_TOTAL_FRAMES | 600 | max frames sampled from a video |
OSS storage (serve large media by URL)
| Variable | Default | Purpose |
|---|---|---|
OSS_AK | — | OSS access key id (secret) |
OSS_SK | — | OSS access key secret (secret) |
OSS_ENDPOINT | — | OSS endpoint |
OSS_BUCKET | — | upload destination for build clips and oversized API media |
OSS_VIDEO_CLIP_PREFIX | tmp/video_clips | key prefix for uploaded video clips |
OSS_URL_EXPIRY | 7200 | signed-URL TTL seconds |
Video-memory
| Variable | Default | Purpose |
|---|---|---|
GRAPH_MEMORY_PATH | — | graph_memory.json path (overrides a passed video path) |
EMBEDDINGS_PATH | — | embeddings.npz path |
CUTOFF_SEC | — | time cutoff (seconds) for retrieval |
Omni-memory
| Variable | Default | Purpose |
|---|---|---|
MEM_LOCAL_DIR | video directory | optional shared root for namespace memories; defaults beside the input video |
Blender / FreeCAD hosts
| Variable | Default | Purpose |
|---|---|---|
BLENDER_BINARY | — | path to the Blender executable |
BLENDER_HOST | localhost | Blender addon host |
BLENDER_PORT | 9876 | Blender addon port |
FREECAD_BINARY | — | path to the FreeCAD executable |
FREECAD_RPC_HOST | localhost | FreeCAD RPC host |
FREECAD_RPC_PORT | 9875 | FreeCAD RPC port |
FREECAD_MOD_DIR | — | FreeCAD Mod dir for the bundled addon |
edu-agent (Node / headless Chromium)
| Variable | Default | Purpose |
|---|---|---|
NODE_PATH | — | Node.js module resolution path |
PUPPETEER_EXECUTABLE_PATH | — | headless Chromium executable for Puppeteer |
Advanced environment-only switches
These switches are intentionally not written by Configure. Set them only for the named compatibility or runtime behavior.
| Variable | Default | Purpose |
|---|---|---|
QWEN_MM_AUDIO_RAW_B64 | off | Send Omni audio as raw base64 for OpenAI-spec servers such as vLLM; DashScope uses data:;base64,<payload> |
QWEN_MM_AUTOLAUNCH | off | Launch a local Blender/FreeCAD application on the first tool call; plugin manifests may preset it |
QWEN_MM_NO_AUTO_INSTALL | off | Disable automatic Blender/FreeCAD binary downloads |
FREECAD_ONLY_TEXT_FEEDBACK | off | Omit screenshots normally attached to FreeCAD tool results |
OSS_BUCKET_NAME | — | Legacy video-memory alias; OSS_BUCKET takes precedence |
Capability-specific context and prerequisites remain in each capability's Skill and cookbook.