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.

Run bash install.sh configure for the interactive menu, or pass one or more catalog fields for non-interactive configuration:

bash install.sh configure DASHSCOPE_API_KEY="$DASHSCOPE_API_KEY" QWEN_MM_NATIVE_MODE=1
bash install.sh configure 'QWEN_MM_CACHE=/path/with spaces/cache'
bash install.sh configure QWEN_MM_CACHE=  # remove the override and restore the default

All arguments are validated before writing. Values must be single-line strings; spaces and = are supported. The command preserves other settings, keeps permissions at 600, and prints only key names, never values. Environment variables continue to take precedence.

Installed MCP entry points also support --set KEY=VALUE and --unset KEY, for example qwen-mm-plugins-blender --set BLENDER_PORT=9876. --set rejects empty or whitespace-only values with exit status 2 before writing any entries. To remove an override and restore its default, use qwen-mm-plugins-blender --unset BLENDER_PORT.

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, OpenRouter uses OPENROUTER_API_KEY, and Cheaper Inference uses CHEAPER_INFERENCE_API_KEY. Any other OpenAI-compatible endpoint set as DASHSCOPE_BASE_URL uses DASHSCOPE_API_KEY, which is sent only to that URL's origin (scheme, host, port). 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

Omni ChatCut

Search providers

Runtime paths & limits

OSS storage (serve large media by URL)

Video-memory

Omni-memory

Blender / FreeCAD hosts

edu-agent (Node / headless Chromium)

Advanced environment-only switches

These switches are intentionally not written by Configure. Set them only for the named compatibility or runtime behavior.

Capability-specific context and prerequisites remain in each capability's Skill and cookbook.