openclaw - 💡(How to fix) Fix [Bug] Image tool uses openai-completions instead of provider-zai-endpoint, causing 404 on zai VL models [1 comments, 2 participants]

Summary

The image analysis tool (image) routes zai VL models (e.g. zai/glm-4.6v, zai/glm-5v-turbo) through the generic openai-completions API surface instead of the dedicated provider-zai-endpoint transport. This causes two problems:

1. baseUrl /v1 appending: The openai-completions API surface normalizes provider base URLs by appending /v1. For zai, the correct base URL is https://api.z.ai/api/paas/v4 and the chat completions endpoint is https://api.z.ai/api/paas/v4/chat/completions. The normalization produces https://api.z.ai/api/paas/v4/v1/chat/completions, which returns 404 Not Found.

2. models.json regeneration overwrite: On every Gateway restart, OpenClaw regenerates models.json and the merge logic overwrites the corrected zai baseUrl with the /v1-appended version. The shouldPreserveExistingBaseUrl function returns false for providers that have an explicit baseUrl in openclaw.json, allowing the discovery-generated (incorrect) URL to take precedence.

Steps to Reproduce

1. Configure imageModel with zai VL models as fallbacks:

{
  "agents": {
    "defaults": {
      "imageModel": {
        "primary": "ollama/qwen3-vl:8b",
        "fallbacks": ["zai/glm-4.6v", "ollama/qwen3-vl:235b-instruct-cloud", "zai/glm-5v-turbo"]
      }
    }
  }
}

1. Restart the Gateway
2. Use the image tool (or send an image via Discord)
3. If primary fails, zai VL models fail with 404

Expected Behavior

The image tool should route zai VL models through provider-zai-endpoint (which uses the correct URL https://api.z.ai/api/paas/v4/chat/completions), just as the text model tool already does.

Actual Behavior

The image tool routes zai VL models through pi-ai openai-completions, which uses models.json baseUrl + /chat/completions. After Gateway restart, models.json contains https://api.z.ai/api/paas/v4/v1/chat/completions → 404.

Workaround

After every Gateway restart, manually fix models.json:

# Remove trailing /v1 from zai baseUrl
python3 -c "
import json
path = \"\$HOME/.openclaw-main/agents/main/agent/models.json\"
with open(path) as f: data = json.load(f)
zai = data[\"providers\"][\"zai\"]
if zai[\"baseUrl\"].endswith(\"/v1\"):
    zai[\"baseUrl\"] = zai[\"baseUrl\"][:-3]
    with open(path, \"w\") as f: json.dump(data, f, indent=2)
"

Added as ExecStartPost in the systemd service, but this only fixes the file — the running Gateway process has already cached the incorrect URL at startup.

Root Cause Analysis

There are two code paths in OpenClaw for zai model requests:

The text model works because it goes through provider-zai-endpoint which has the correct URL hardcoded. The image tool bypasses this and uses the generic openai-completions handler, which reads baseUrl from models.json and appends /chat/completions.

Suggested Fix

The image tool should check if a dedicated provider transport (like provider-zai-endpoint) exists for the model's provider, and route through it instead of falling back to the generic openai-completions surface.

Environment

• OpenClaw: 2026.4.15
• OS: Ubuntu 24.04 (ARM64, NVIDIA GB10)
• Provider: zai (Z.AI / Zhipu)
• Models affected: zai/glm-4.6v, zai/glm-5v-turbo, zai/glm-4.5v
• Models NOT affected: zai/glm-5.1, zai/glm-5-turbo (text-only, go through provider-zai-endpoint)