configure-glm-vision

August 12, 2026 · View on GitHub

A Codex skill that gives non-vision models (e.g. deepseek-v4-flash) image recognition inside Codex, powered by the free glm-4.6v-flash vision model (Zhipu AI / BigModel) through a local MCP server with a single analyze_image tool.

Optionally, if the OPENCODE_API_KEY environment variable is set, requests first go to the MiMo V2.5 Free vision model and automatically fall back to GLM-4.6V-Flash on failure — keeping single-key (GLM only) setups working.

The skill performs the whole setup for you: scaffold the MCP server, build it, register it in ~/.codex/config.toml, configure your Zhipu API key, apply the known DeepSeek models.json fix (issue #36382), and verify everything with automated tests.

How it works

User / Codex gets an image path or URL
  → non-vision model calls the MCP tool analyze_image
  → local MCP server reads the image (base64 data URI) or uses the URL directly
  → tries MiMo V2.5 Free first if OPENCODE_API_KEY is set (fallback chain)
  → calls GLM-4.6V-Flash (OpenAI-compatible endpoint)
  → returns the visual understanding as text to the model

Features

One tool, five knobs: image, question, detail, thinking, language, region
Supports local images (jpg/jpeg/png/webp/gif/bmp, ≤ 10 MB) and http(s) URLs
OCR, scene description, UI/screenshot analysis, attribute recognition
Regional analysis: region crops a nine-grid area (or a pixel/percentage rectangle) and analyzes it zoomed-in, so fine details aren't lost in compression/rescaling during handoff
Dual-model fallback: optional MiMo V2.5 Free (via OPENCODE_API_KEY) with automatic GLM-4.6V-Flash fallback
Auto-compression: local images > 512 KB are resized (longest edge ≤ 1280 px) and re-encoded to JPEG 85% before upload — smaller payloads, faster responses, fewer timeouts
Built-in retry for the free tier's rate limits (HTTP 429 / transient errors)
Clear error messages (401 / 429 / missing file / bad format / oversized)
Automated verification via scripts/verify.py

Prerequisites

Node.js ≥ 18
Codex (CLI or desktop app)
A free Zhipu API key from bigmodel.cn (register → verify identity → API Keys → create; the glm-4.6v-flash model is free)

Installation

Clone this repository into your Codex skills directory and restart Codex:

# Windows
git clone https://github.com/LinHaiJ/configure-glm-vision "$env:USERPROFILE\.codex\skills\configure-glm-vision"

# macOS / Linux
git clone https://github.com/LinHaiJ/configure-glm-vision "$HOME/.codex/skills/configure-glm-vision"

If CODEX_HOME is set, use $CODEX_HOME/skills instead. Fully quit and reopen Codex (closing the window may not be enough), then start a new session so the skill is discovered.

Alternatively, use the Codex skill-installer skill with this repository URL.

Usage

In a new Codex session, ask:

Use configure-glm-vision to set up GLM image recognition.

The skill will:

Copy the bundled MCP server template to your target directory (default: <workspace>/outputs/glm-vision-mcp)
Run npm install and npm run build
Register [mcp_servers.glm-vision] in ~/.codex/config.toml with your ZHIPU_API_KEY (a placeholder is used until you provide one)
Run scripts/fix_models_json.py to repair the DeepSeek models.json bug (see below)
Verify with scripts/verify.py, then tell you to restart Codex

You can also run the steps manually:

cd "$env:USERPROFILE\.codex\skills\configure-glm-vision"
python scripts/fix_models_json.py     # fixes supports_search_tool (issue #36382)
python scripts/verify.py              # offline checks + smoke tests
$env:ZHIPU_API_KEY = "<your-key>"
python scripts/verify.py --full       # live tests: local image / URL / OCR

Known issue: DeepSeek `models.json` hides all MCP tools (#36382)

DeepSeek's official setup script writes "supports_search_tool": true + "tool_mode": null into ~/.codex/models.json. On recent Codex versions this combination silently removes every MCP tool from the model's visible tool set (the model can still list MCP resource tools, but no mcp__* callable tools). See openai/codex#36382.

Fix:

Set "supports_search_tool": false in every entry of ~/.codex/models.json — or simply run:
```
python scripts/fix_models_json.py
```
Fully quit and reopen Codex, then start a new session.

Related desktop-app issues: #19425 and #34018. If tools still do not appear after a full restart, check those.

Troubleshooting

Symptom	Cause / fix
`401 API Key invalid`	`ZHIPU_API_KEY` in `config.toml` is incomplete; copy it again
`429 too many requests`	Free-tier rate limit; the server retries automatically, wait and retry
Tools do not appear	Not a full restart; or `models.json` not fixed (see above)
Image too large / unsupported	GLM requires ≤ 10 MB and jpg/png/webp/gif/bmp
`view_image` rejected	Normal for non-vision models; use `analyze_image` instead
`-32001 Request timed out`	MCP tool call exceeded the client timeout. In opencode, raise it via `experimental.mcp_timeout` (ms) in `opencode.jsonc`, or in Codex raise `startup_timeout_sec`. Auto-compression already reduces payloads to lower this risk

Security

Never commit a real API key. The repo only contains placeholders (REPLACE_WITH_YOUR_REAL_KEY). Your key lives in the env section of your local ~/.codex/config.toml.
OPENCODE_API_KEY (if used) is likewise read from your local environment only — never hardcode it in source files.
scripts/fix_models_json.py and scripts/verify.py only read/write your local ~/.codex files; nothing is uploaded anywhere.
The bundled test image is generated locally and contains no third-party assets.

License

MIT