openclaw - 💡(How to fix) Fix [Bug]: Media understanding (vision/image analysis) fails with Codex OAuth ``OPENAI_API_KEY required`` [2 comments, 2 participants]

Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

While #70885 fixed OpenAI image generation (gpt-image-2) to work through Codex OAuth, the media understanding / vision subsystem still requires OPENAI_API_KEY and does not route through the Codex OAuth provider.

The image tool and read tool (for images) fail with:

No API key found for provider "openai". You are authenticated with OpenAI Codex OAuth; OpenAI agent model runs use openai/gpt-* through the Codex runtime. Set OPENAI_API_KEY only for direct OpenAI API-key surfaces.

The Codex plugin includes a media-understanding-provider.js that correctly routes vision through the Codex app server (using runBoundedCodexVisionTurn), but the core media-understanding subsystem appears to bypass it and resolve auth through the standard OpenAI API key path instead.

Steps to reproduce

1. Install OpenClaw 2026.5.18 with Codex OAuth authentication (no OPENAI_API_KEY set).
2. Install @openclaw/[email protected] plugin.
3. Run openclaw doctor --fix to ensure config is clean.
4. Send an image to the agent (via Telegram, Discord, or use the image tool with a local file).
5. Observe the error: No API key found for provider "openai".

Expected behavior

The image tool should route through the Codex media-understanding provider (buildCodexMediaUnderstandingProvider -> describeCodexImages -> runBoundedCodexVisionTurn) when Codex OAuth is the only OpenAI auth available, similar to how image generation now routes through generateOpenAICodexImage.

Actual behavior

The media-understanding subsystem resolves the OpenAI provider directly, finds no OPENAI_API_KEY, and errors out. The Codex plugin's media-understanding-provider is not invoked for the vision path.

OpenClaw version

2026.5.18 (50a2481)

Operating system

Linux 6.12.88+deb13-amd64 (Debian 13)

Install method

npm global install

Model

Default agent model (zai/glm-5.1), with OpenAI as configured vision fallback

Provider / routing chain

Core media-understanding → OpenAI provider → resolveApiKey → fails (no OPENAI_API_KEY). Codex OAuth available but not routed. Expected: media-understanding → Codex plugin → Codex app server → Codex OAuth.

Additional provider/model setup details

No response

Logs, screenshots, and evidence

Gateway log on image tool invocation:

[tools] image failed: No API key found for provider "openai". You are authenticated with OpenAI Codex OAuth; OpenAI agent model runs use openai/gpt-* through the Codex runtime. Set OPENAI_API_KEY only for direct OpenAI API-key surfaces.

`image_generate action=list` shows OpenAI as `configured: true, selected: true` (image generation fix works):

{"available":true,"configured":true,"selected":true,"id":"openai","label":"OpenAI","defaultModel":"gpt-image-2"}

But the image tool (vision) fails every time.

Impact and severity

No response

Additional information

• Image generation was fixed in #70885 via generateOpenAICodexImage in extensions/openai/image-generation-provider.ts. • The Codex plugin has the infrastructure for Codex-based vision (media-understanding-provider.js with describeCodexImages and runBoundedCodexVisionTurn), but it appears the core does not delegate to this provider when resolving vision requests. • This affects all users relying solely on Codex OAuth without a separate OPENAI_API_KEY.