Configuration via environment variables

Every setting can also be set through environment variables instead of config files. They apply to all consumers — the Claude Code hook, the MCP server plugin clients launch, and the describe CLI all read the same merged config — and you do not need to re-run the installer after changing them.

Variable	What it sets	Example value
VISION_BASE_URL	The vision service address	https://api.moonshot.cn/v1
VISION_MODEL	The vision model id	moonshot-v1-32k-vision-preview
VISION_API_KEY	Your secret API key	sk-...
VISION_TIMEOUT_MS	How long to wait for one description (ms)	120000
VISION_MAX_BYTES	Pictures bigger than this are skipped	10485760
VISION_FALLBACKS	Fallback models, model@baseUrl comma-separated	qwen/qwen2.5-vl-72b-instruct@https://api.siliconflow.cn/v1
VISION_DISABLE	Switch vision off entirely (1 / true)	1

Precedence: environment variables override the config files field by field — VISION_* > project .deepseek-vl/config.json > global ~/.deepseek-vl/config.json > built-in defaults. This is also the simplest way to configure vision after the GitHub prompt install described above, which creates no config file at all.

Bash:

export VISION_BASE_URL="https://api.moonshot.cn/v1"
export VISION_MODEL="moonshot-v1-32k-vision-preview"
export VISION_API_KEY="sk-..."

PowerShell:

$env:VISION_BASE_URL = "https://api.moonshot.cn/v1"
$env:VISION_MODEL = "moonshot-v1-32k-vision-preview"
$env:VISION_API_KEY = "sk-..."

skip endpoint configuration entirely (same as the wizard's "Decide later")

npx deepseek-vl-support@latest install --non-interactive --target opencode --preset later

`--target` takes a comma-separated agent list
(`claude`, `codex`, `opencode`, `trae`, `pi`, `omp`, `dsh`, `qwen`,
`reasonix`, `kilo`, `workbuddy`, `devin`, `copilot`, `cursor`, `kiro`,
`openclaw`, `hermes`, `vscode`, `chatgpt-codex`, `grok`, `nanoclaw`,
`other`);
the default is `claude,codex` plus the agents detected on this machine. Any
combination is allowed — e.g. `--target claude,copilot` installs the Claude
Code hook AND registers the plugin with Copilot in one run. To skip the
endpoint configuration entirely, pass `--preset later`.

## Skill-based agents (OpenCode / Trae / Pi / Oh My Pi / DeepSeek Harness)

Five agents read [Agent Skills](https://agent-skills.org) but do not implement
the Agent Plugins open standard, so they get their own integration (`--target
opencode,trae,pi,omp,dsh`). OpenCode is a native agent, so its artifacts
(`opencode.json` + the shared skill) follow the install scope you choose. The
skill agents trae/pi/omp/dsh are **project scope only** and never trigger the
install-scope question:

| Agent | What the installer does | Verify / notes |
|---|---|---|
| OpenCode (`opencode`) | MCP server entry in `opencode.json` (`mcp.deepseek-vl`, `type: local`, `npx -y deepseek-vl-support mcp`, `enabled: true`) + the shared `.agents/skills/` skill. Project or global by the install scope; the file is deep-merged (your other keys and MCP servers are never touched) and backed up to `opencode.json.bak` before the first change | OpenCode reads `.agents/skills/` natively; restart OpenCode, then ask for a screenshot description |
| Trae (`trae`) | skill copied to `.trae/skills/deepseek-vision/` + manual import guidance (Settings → Rules & Skills → Create/Import) + optional manual MCP setup (Settings → MCP) | Trae is an IDE — there is no CLI automation; the MCP entry is manual (Trae's config paths are unverified) |
| Pi Coding Agent (`pi`) | shared `.agents/skills/` skill; guidance prefers the native package (`pi install npm:deepseek-vl-support`) — one command gives pi the user-level skill and a native extension (automatic image description); writes `mcpServers.deepseek-vl` to `~/.pi/agent/mcp.json` **only when the pi-mcp-adapter extension is detected** (file or `~/.pi/agent/npm/` present) | pi core has no MCP — the packaged skill works without it; for MCP tools add the adapter (`pi install npm:pi-mcp-adapter`), restart pi |
| Oh My Pi (`omp`) | shared `.agents/skills/` skill (omp reads it at priority 70) + guidance `omp install npm:deepseek-vl-support` — one command gives omp the skill, automatic MCP tools **and** the native extension (the package's `.mcp.json` is auto-registered); no config file is written (omp's user-level MCP paths are unverified) | omp is a pi fork with built-in MCP; activate with `/reload-plugins` — no restart needed |
| DeepSeek Harness (`dsh`) | shared `.agents/skills/` skill (dsh reads `
/.agents/skills` at rank 200); guidance prefers the native package (`dsh plugin --profile web add deepseek-vl-support@latest`) — one command gives dsh the `describe_image` + `vision_status` native tools | `dsh plugin --profile web add deepseek-vl-support@latest` → restart the dsh web session; the wizard skill path keeps working alongside |

Five more CLI agents got native support in 0.2.3 (`--target
qwen,reasonix,kilo,workbuddy,devin`). All are project or global by the install
scope; every file change is a JSON deep-merge (foreign keys never touched,
`.bak` backup before the first change) and re-runs are idempotent:

| Agent | What the installer does | Verify / notes |
|---|---|---|
| Qwen Code (`qwen`) | skill copied to `.qwen/skills/deepseek-vision/` + `settings.json` `mcpServers.deepseek-vl` (npx) + a `PreToolUse` hook (matcher `Read`) that routes image reads to the MCP server (`node ""`); global scope uses `~/.qwen/` | Qwen does **not** read `.agents/skills/`, so the skill lives in `.qwen/skills/`; a commented (`JSONC`) `settings.json` is reported as manual — file bytes untouched |
| Reasonix (`reasonix`) | shared `.agents/skills/` skill + project `.mcp.json` `mcpServers` entry + `.reasonix/settings.json` hook; global scope writes a `[[plugins]]` block into `~/.reasonix/config.toml` + `~/.agents/skills/` | The plugin block is wrapped in managed `# deepseek-vl-support:start/end` markers and updated in place; a foreign block without our markers is left untouched (manual) |
| Kilo Code (`kilo`) | shared `.agents/skills/` skill + `mcp.deepseek-vl` entry in project `.kilo/kilo.json` (`type: local`, command as an **array** `["npx","-y","deepseek-vl-support","mcp"]`, `enabled: true`); global scope probes `~/.config/kilo/kilo.json` then `kilo.jsonc` and writes to whichever exists | Kilo uses the `mcp` key (not `mcpServers`); the config file is created as `kilo.json` when neither exists |
| WorkBuddy / CodeBuddy Code (`workbuddy`) | skill copied to `.codebuddy/skills/deepseek-vision/` + project `.mcp.json` `mcpServers` entry (`type: stdio`); global scope uses `~/.codebuddy/.mcp.json` | Shares the project `.mcp.json` with Reasonix — either agent's entry is seen as present by the other; a JSONC `.mcp.json` is reported as manual (bytes untouched) |
| Devin (`devin`) | shared `.agents/skills/` skill + `mcpServers` entry in project `.devin/mcp_config.json`; global scope uses `%APPDATA%\devin` (win32) or `~/.config/devin` (posix) | The Devin CLI has no official npm package — `https://devin.ai/download` |

Selected-but-undetected agents are flagged non-blockingly at install time:
`⚠  was not detected on this machine — install it first ().`

Uninstall ownership: `uninstall --target opencode|pi|omp|dsh` removes each
agent's own artifacts (the opencode.json / mcp.json entries) but **keeps** the
shared `.agents/skills/deepseek-vision/` tree — it may be used by other
agents. The native CLI agents (qwen/reasonix/kilo/workbuddy/devin) follow the
same rule, and qwen/workbuddy also remove their own skill copies
(`.qwen/skills/`, `.codebuddy/skills/`) and hook files. Only
`uninstall --target codex` removes the shared skill tree (or delete the
directory yourself).

## Pi and Oh My Pi native packages

Since 0.2.4 the npm package and this repo double as a native plugin for both
agents — no wizard needed:

### Pi Coding Agent

```bash
pi install npm:deepseek-vl-support          # published package
pi install git:github.com/limccn/deepseek-vl-support@   # from git (pinned)

• What you get: the deepseek-vision skill at user level and a native extension — pi loads only what its pi manifest lists ("pi": { "extensions": ["./extensions"], "skills": ["./skills"] }). The skill is self-contained: it calls npx deepseek-vl-support describe, so it works without any MCP setup. The extension makes vision transparent: pasting or dragging an image into a prompt describes it automatically and injects the description into the conversation; read on an image file returns [Vision: …] text instead of a "model does not support images" note; /vision shows the endpoint + model status and a startup self-check notifies you when the vision setup is incomplete.
• The extension delegates every description to the packaged CLI (node …/dist/cli.js describe), so it shares the exact same endpoint configuration, size guard, cache and fallback chain as the skill and the MCP server — configure once (deepseek-vl-support config set … or the VISION_* env vars), use everywhere. The extension (transparent), the skill (explicit call) and MCP tools run in parallel and never conflict.
• MCP tools are not included — pi core has no MCP. If you want the describe_image / vision_status tools too, install the community adapter (pi install npm:pi-mcp-adapter, restart pi) and re-run this installer, or use the wizard's adapter-aware path.
• Uninstall: pi remove deepseek-vl-support (the adapter is a separate package — remove it with pi remove pi-mcp-adapter).
• Notes: restart pi after installing — the extension module loads at startup (and after every pi update); trust the project on first run for project-level skills. If you already installed the project-level skill via the wizard, the packaged skill is equivalent — no need to install twice.

Oh My Pi

omp install npm:deepseek-vl-support         # published package
omp install github:limccn/deepseek-vl-support@  # from git (pinned)

• What you get: the deepseek-vision skill and automatic MCP tools — omp (a pi fork with built-in MCP) reads the package's .mcp.json and registers the deepseek-vl server with describe_image / vision_status — plus the same native extension as pi (omp loads the pi manifest entry, so pi.extensions applies here too): pasted images and image reads are described automatically, /vision and the startup self-check are available. Activate with /reload-plugins — no restart needed.
• omp falls back to the pi manifest key, so the same package works for both agents; it also reads the project .agents/skills/ shared tree (priority 70), so a wizard-installed project skill is picked up as well. The extension shares the same configuration as the skill and MCP tools — one deepseek-vl-support config set … or VISION_* setup covers all paths.
• Uninstall: omp plugin uninstall deepseek-vl-support.
• Note: omp iterates very fast — if a future version stops accepting the pi key fallback (extensions and skills both), report it; the wizard path (shared skill + guidance) keeps working regardless.

DeepSeek Harness native plugin

Since 0.2.6 the npm package and this repo double as a native cordis tool plugin for DeepSeek Harness (dsh) — no wizard needed:

dsh plugin --profile web add deepseek-vl-support@latest    # published package
dsh plugin --profile web add github:limccn/deepseek-vl-support@  # from git (pinned)

• What you get: two native tools, describe_image and vision_status, registered in-process (no npx subprocess), with the exact same names, descriptions and output format as the MCP server. They read the same configuration as every other surface — one deepseek-vl-support config set … or VISION_* env setup covers the plugin too (the wizard does not write any dsh-specific config).
• Activation: the package's dsh manifest key (bundle.patch) points at cordis.patch.yml, whose insert row loads the plugin through the package main entry (dist/dsh-plugin.js). The dsh profile closure injects @deepseek-ai/cordis + @deepseek-ai/dsh-tools at runtime — the plugin ships no copies of the official packages.
• The wizard skill path still works and complements the plugin: the shared .agents/skills/deepseek-vision/ skill (rank 200) is read by dsh for team repos; native tools and skill coexist without conflict.
• Verify: dsh --profile web --dump-config shows the deepseek-vl layer in the bundle patch stack.
• Uninstall: dsh plugin --profile web remove deepseek-vl-support (then restart the dsh web session).
• Notes: restart the dsh web session after install; editing a local add . install is a pnpm file: copy, not a link — remove then add . again to pick up changes.

Agent Plugins mode (10 compatible clients)

Beyond Claude Code and Codex, the package ships as a portable Agent Plugins v1.0.0 package (root plugin.json

• mcp.json + skills/deepseek-vision/SKILL.md), so agents that load plugins get vision too — the deepseek-vision skill plus the describe_image / vision_status MCP tools backed by the same endpoint configuration. The MCP server is launched as npx -y deepseek-vl-support mcp (your environment needs npm/npx), and a .mcp.json copy of the server config is shipped for Copilot's native MCP convention.