# 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`, `DASHSCOPE_API_KEY`, and `QWEN_MM_API_VL_MODEL`, and requires a non-empty API
key for every configured endpoint. For an authentication-free local endpoint, set an explicit
non-empty placeholder key. Missing credentials or a failed caption call produce 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. Set it to `serper`, `tavily`, or `exa` 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`](../../src/shared/env.py); `—` means unset or disabled.

<!-- BEGIN GENERATED CONFIG CATALOG -->
<!-- Generated by scripts/gen_env_docs.py from src/shared/env.py CONFIG_FIELDS. -->

### Media APIs & endpoints

| Variable | Default | Purpose |
|---|---|---|
| `DASHSCOPE_API_KEY` | — | vision, OCR, grounding, text-only image captions, ASR, generation, memory builds *(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 |
| `SAM3_SERVER_URL` | — | segmentation SAM3 server URL |
| `ASR_SERVER_URLS` | — | self-hosted ASR fallback URLs (comma-separated) |

### Search providers

| Variable | Default | Purpose |
|---|---|---|
| `QWEN_MM_SEARCH_BACKEND` | auto | text search backend (auto: serper > tavily > exa; 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)* |

### 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 |

### 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 |

<!-- END GENERATED CONFIG CATALOG -->

## 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.