Codex Custom Model Proxy

Configure OpenAI Codex CLI to work with custom model providers that use OpenAI Chat Completions API format (like MiniMax) by setting up a local SSE proxy server.

When to Use This Skill

• User wants to use Codex with a custom model provider (not OpenAI)
• User's model provider uses OpenAI Chat Completions API format (/v1/chat/completions)
• User sees errors like Stream disconnected before completion or Model metadata not found
• User needs to convert between Codex Responses API format and OpenAI API format
• User wants to configure ~/.codex/config.toml for custom endpoints

Overview

Codex CLI uses OpenAI Responses API format (/v1/responses) with SSE streaming, but many custom model providers (like MiniMax) use OpenAI Chat Completions API format (/v1/chat/completions). This skill provides a Python proxy server that:

1. Listens on http://127.0.0.1:5005 (configurable)
2. Accepts Codex Responses API requests
3. Converts to OpenAI Chat Completions API format
4. Forwards to the upstream provider
5. Converts streaming responses back to Codex SSE event format
6. Handles model metadata, UTF-8 encoding, and timeout issues

Quick Start

1. Configure Codex

Edit ~/.codex/config.toml:

[model]
model = "MiniMax-M2.7-highspeed"

[api]
base_url = "http://127.0.0.1:5005/v1"
api_key = "YOUR_API_KEY_HERE"

2. Start the Proxy Server

cd ~/.codex
python3 scripts/sse_proxy.py

Or use the bundled script:

python3 ~/.workbuddy/skills/codex-custom-model-proxy/scripts/sse_proxy.py

3. Run Codex

codex

Proxy Script Usage

The proxy script (scripts/sse_proxy.py) supports configuration via environment variables:

# Custom upstream endpoint
export UPSTREAM_HOST="your-upstream-host.com"
export UPSTREAM_PATH="/v1/chat/completions"
export UPSTREAM_TIMEOUT=180

# Custom listen port
export LISTEN_PORT=5005

# API key
export API_KEY="your-api-key-here"

# Start proxy
python3 scripts/sse_proxy.py

Troubleshooting

"Stream disconnected before completion: idle timeout waiting for SSE"

Cause: Upstream timeout too short, or proxy not converting SSE format correctly.

Fix:

1. Increase UPSTREAM_TIMEOUT to 180+ seconds
2. Ensure proxy sends proper SSE events: response.created, response.in_progress, response.output_text.delta, response.output_text.done, response.completed
3. Check that X-Accel-Buffering: no header is set

"Model metadata for XXX not found"

Cause: Codex can't find model metadata in its model catalog.

Fix (optional, warning only):

1. Read ~/.codex/model_catalog_gpt55.json
2. Add model entry with correct schema (see references/model-catalog-schema.md)

Note: This is a warning only, Codex will still work with fallback metadata.

"Skill descriptions were shortened to fit the 2% skills context budget"

Cause: Too many skills enabled, context budget exceeded.

Fix:

1. Disable unused skills: codex disable
2. Or increase context budget in config

Advanced Configuration

Custom Model Parameters

Edit the MODEL_META dict in scripts/sse_proxy.py:

MODEL_META = {
    "id": "MiniMax-M2.7-highspeed",
    "context_window": 128000,
    "max_output_tokens": 4096,
    # ... see script for full schema
}

Multiple Models

To support multiple models, modify the /v1/models endpoint in the proxy to return all available models.

HTTPS Upstream

For HTTPS upstream endpoints, ensure SSL certificates are properly configured. The proxy uses requests library which respects system CA bundles.

File Reference

• scripts/sse_proxy.py - The main proxy server script
• references/codex-api-format.md - Codex API format documentation
• references/model-catalog-schema.md - Model catalog JSON schema