Codex Image Bridge

Let Codex diagnose and repair image generation for third-party Responses API providers that do not implement the standalone Images API required by newer Codex versions.

Let Codex Fix It

Send this prompt to Codex:

Use https://github.com/zhyongrui/codex-image-bridge to fix image generation for
my current Codex provider. Read and follow the repository instructions.

All safety, preflight, installation, validation, rollback, and credential rules live in AGENTS.md and the bundled skill. Codex will read them from the repository instead of requiring a long user prompt.

Install As A Reusable Skill

You can also ask Codex:

Install the codex-image-bridge skill from
https://github.com/zhyongrui/codex-image-bridge/tree/main/skills/codex-image-bridge
and tell me when to open a new task.

Then invoke:

$codex-image-bridge repair image generation for my active provider

What It Changes

• ~/.codex/config.toml: changes only the active provider base_url
• ~/.codex/image-bridge/: installs credential-free runtime files and state
• macOS: ~/Library/LaunchAgents/com.codex.image-bridge.plist runs the service
• Windows: a per-user Codex Image Bridge Scheduled Task runs the service

The bridge listens only on loopback and forwards Codex's existing authorization headers in memory. It never stores credentials in its source, state, or service definition. Failed installs restore the prior config and service.

The bridge translates standalone Images requests to the Responses image_generation tool. A single-image n=1 request is normalized without forwarding n, which is not a Responses image-tool parameter. Requests for multiple images are rejected locally rather than silently under-delivered or expanded into multiple billable upstream calls.

Manual Commands

On macOS:

/usr/bin/python3 skills/codex-image-bridge/scripts/bridge_manager.py preflight
/usr/bin/python3 skills/codex-image-bridge/scripts/bridge_manager.py install
~/.codex/image-bridge/bridge_manager.py doctor
~/.codex/image-bridge/bridge_manager.py uninstall

On Windows PowerShell with Python 3.12 (use its absolute path if python is not yet on PATH):

python skills\codex-image-bridge\scripts\bridge_manager.py preflight
python skills\codex-image-bridge\scripts\bridge_manager.py install
python "$HOME\.codex\image-bridge\bridge_manager.py" doctor
python "$HOME\.codex\image-bridge\bridge_manager.py" uninstall

Automatic installation is natively validated on macOS and Windows. Windows uses a per-user Scheduled Task and runs the bridge with pythonw.exe when available, so no console window remains open. The proxy uses only the Python standard library.

Development

python3 -m unittest -v tests/test_bridge.py tests/test_manager.py

See README.zh-CN.md for Chinese instructions.