Codex-Launcher---Any-AI-Porovider/README.md

Get 10% OFF Z.AI coding plans
z.ai/subscribe

---

Codex Launcher — Any AI Provider

Run OpenAI Codex CLI & Desktop with any AI provider.
OpenCode • Z.AI • Anthropic • OpenRouter • Crof.ai • NVIDIA NIM • Kilo.ai • and more

---

The Problem

OpenAI's Codex CLI v2.0+ exclusively uses the Responses API — a protocol that is incompatible with virtually every other AI provider:

Provider	API	Works with Codex?
OpenAI	Responses API	✅
Z.AI	Chat Completions	❌
OpenCode	Chat Completions	❌
Anthropic	Messages API	❌
Ollama	Chat Completions	❌
OpenRouter	Chat Completions	❌
NVIDIA NIM	Chat Completions	❌
Crof.ai	Chat Completions	❌

The protocols differ in endpoint paths, message formats, tool-call structures, streaming events, and completion semantics. You can't just swap a base URL.

The Solution

A three-component system:

1. Translation Proxy — translates Responses API ↔ Chat Completions / Anthropic Messages in real-time
2. Config Engine — generates Codex config files on-the-fly per provider, with backup/restore
3. GTK Launcher — manages endpoints, launches Desktop or CLI, handles the full lifecycle

┌─────────────────────────────────────────────────────────────────────┐
│                         Codex Launcher GUI                          │
│                    (endpoint management + lifecycle)                │
└──────────┬─────────────────┬──────────────────┬────────────────────┘
           │                 │                  │
    ┌──────▼──────┐  ┌──────▼──────┐  ┌────────▼─────────┐
    │  Codex      │  │  Native     │  │  Translation     │
    │  Default    │  │  OpenAI     │  │  Proxy           │
    │  (remove    │  │  (direct    │  │  (port 8080)     │
    │  config)    │  │  URL)       │  │                  │
    └──────┬──────┘  └──────┬──────┘  └────────┬─────────┘
           │                │                   │
           ▼                ▼          ┌────────┴────────┐
    ┌──────────────┐ ┌───────────┐    │                 │
    │ Built-in     │ │ config.   │    ▼                 ▼
    │ Codex OAuth  │ │ toml      │ ┌────────────┐ ┌───────────┐
    └──────────────┘ └───────────┘ │ OpenAI     │ │ Anthropic │
                                   │ Chat Comp. │ │ Messages  │
                                   └────────────┘ └───────────┘

---

Features

Multi-Provider Support

• Native OpenAI — direct connection, no proxy needed
• OpenAI-compatible — Z.AI, OpenCode Zen/Go, Crof.ai, NVIDIA NIM, Kilo.ai, OpenRouter, Ollama, Together, Groq, and any provider with a Chat Completions endpoint
• Anthropic — Claude models via the Messages API
• Codex Default — built-in Codex OAuth with official models, zero config

Translation Proxy (translate-proxy.py)

• Full Responses API ↔ Chat Completions / Anthropic Messages bidirectional translation
• Streaming SSE support with proper event sequencing (response.created → response.output_text.delta → response.completed)
• Tool calls — full function calling support including parallel tool calls
• Reasoning content — forwards reasoning_content fields from providers that support it
• Browser UA injection — bypasses Cloudflare bot detection for providers like OpenCode
• Smart URL construction — prevents double-path bugs (/v1/chat/completions/chat/completions)
• Header forwarding — preserves client identity headers while filtering hop-by-hop headers
• Zero dependencies — pure Python stdlib

GTK Launcher (codex-launcher-gui)

• Endpoint manager — add, edit, delete, set default providers
• Provider presets — one-click setup for 10+ providers with pre-filled URLs and model lists
• Model auto-fetch — pulls available models directly from provider APIs
• Bulk model import — paste a comma/newline-separated list of model IDs
• Launch Desktop — starts Codex Desktop with the selected provider and model
• Launch CLI — opens Codex CLI in a terminal with the selected provider
• Codex Default — launch with built-in OAuth, no proxy or custom config
• Profile backup/import — export and import endpoint configurations as portable JSON bundles
• Threaded operations — model refresh runs in background, UI stays responsive
• Process lifecycle — stall detection, kill/cleanup, config backup/restore around sessions
• Config normalization — automatically strips stale API path suffixes from URLs

Process Management

• Kills stale electron/webview/app-server processes from previous sessions
• Removes stale PID files and sockets
• Manages proxy lifecycle (start, health-check, stop)
• Config backup before launch, automatic restore after exit

---

Technology Stack

Component	Technology	Why
Translation Proxy	Python 3 stdlib (http.server, urllib, json)	Zero dependencies, runs anywhere
GUI Launcher	Python 3 + GTK 3.0 (PyGObject/gi)	Native Linux desktop integration
Config Engine	Python 3 (toml generation, json catalogs)	Dynamic, no hardcoded configs
Process Mgmt	bash + os.setsid/os.killpg	Unix process group lifecycle
Streaming	Server-Sent Events (SSE)	Required by Codex Responses API
API Translation	Responses API ↔ Chat Completions / Anthropic Messages	Protocol bridging

Zero pip dependencies. Everything uses Python stdlib + system GTK bindings.

---

Quick Start

Prerequisites

• Codex CLI ≥ 2.0 (npm install -g @openai/codex or bundled with Codex Desktop)
• Codex Desktop installed at /opt/codex-desktop/ (optional, for Desktop mode)
• Python 3.8+ (stdlib only)
• python3-gi for GTK (sudo apt install python3-gi)
• bash, curl, lsof

Install

git clone https://github.rommark.dev/admin/Codex-Launcher---Any-AI-Porovider.git
cd Codex-Launcher---Any-AI-Porovider
./install.sh

Run

Open Codex Launcher from your app grid, or:

codex-launcher-gui

First Launch

1. Click Manage Endpoints → Add
2. Select a provider preset (e.g., "OpenCode Zen (OpenAI-compatible)")
3. Enter your API key
4. Click Fetch from API to auto-discover models, or add them manually
5. Click Save
6. Select the endpoint and model from the dropdowns
7. Click Launch Desktop or Launch CLI

---

Development Journey

Phase 1: The Z.AI Proxy — Protocol Reverse Engineering

Problem: Codex CLI v2.0 switched exclusively to the Responses API. Z.AI (and every other provider) uses Chat Completions. They are fundamentally incompatible.

Approach:

1. Captured Codex's HTTP traffic to understand the exact Responses API request/response shape
2. Mapped the protocol differences:
   • /v1/responses → /chat/completions (endpoint)
   • input array with typed items → messages array with role/content (message format)
   • function_call items → tool_calls array on assistant messages (tool format)
   • SSE response.output_text.delta events → delta.content chunks (streaming)
3. Built the initial zai-proxy.py — a 200-line HTTP server that translates in both directions
4. Hit a critical bug: Codex hung in "thinking" state. Discovered that merely emitting response.done is insufficient — the response.completed event must contain the full output item array
5. Added streaming SSE with proper event sequencing — this was the breakthrough that made it work

Testing: Manual end-to-end testing with curl, Codex CLI --profile zai, and Codex Desktop. Verified streaming, tool calls, and reasoning content.

Phase 2: Multi-Provider Architecture — The Unified Proxy

Problem: Maintaining separate proxies for each provider (Z.AI, Anthropic, OpenRouter, etc.) was unmaintainable.

Approach:

1. Abstracted the translation into a backend plugin architecture:
   • openai-compat backend: translates Responses → Chat Completions (works for any OpenAI-compatible API)
   • anthropic backend: translates Responses → Anthropic Messages API
2. Unified config loading: JSON config file, CLI arguments, and environment variables
3. Shared HTTP server, model serving, and SSE framework
4. Per-backend: message conversion, tool conversion, response conversion, stream conversion

Key design decisions:

• Pure Python stdlib — no Flask, no aiohttp, no pip dependencies. The proxy must work on any system with Python 3.
• http.server.BaseHTTPRequestHandler — simple, synchronous, but sufficient for single-user desktop use
• Config via JSON file — the launcher writes a proxy config to ~/.cache/codex-proxy/ for each endpoint

Phase 3: The GTK Launcher — Desktop Integration

Problem: Users had to manage config files, start proxies manually, and remember which wrapper script to use.

Approach:

1. Built a GTK 3.0 GUI with three layers: main window, endpoint manager dialog, edit endpoint dialog
2. Implemented dynamic config generation: for each launch, generate config.toml with the right provider definition, profile, and model catalog
3. Model catalog generation with dual field naming (slug + model, supported_reasoning_levels + supportedReasoningEfforts) — required because Codex CLI and Codex Desktop use different field names
4. Process lifecycle: backup config → cleanup stale processes → start proxy → write config → launch Codex → wait → restore config → stop proxy

Threading challenges:

• GTK requires all UI updates on the main loop. Used GLib.idle_add() for all cross-thread communication
• Model refresh was blocking the UI — moved to a background thread with idle_add completion callbacks
• Proxy startup waits up to 15 seconds with health checks before proceeding

Phase 4: Endpoint Management & Provider Presets

Approach:

1. JSON-based endpoint storage (~/.codex/endpoints.json)
2. Provider presets with pre-filled URLs and model lists for common providers
3. Auto-fetch models from provider /v1/models endpoints
4. Bulk model import (paste comma/newline-separated model IDs)
5. Profile backup/import — portable JSON bundles with endpoints + config

URL normalization: Discovered that saved URLs sometimes had /chat/completions appended from manual entry. Added normalize_base_url() that strips trailing API path suffixes to prevent double-path bugs.

Phase 5: Cloudflare Bot Detection — The OpenCode 403 Saga

Problem: OpenCode Zen/Go returned 403 (Cloudflare error 1010) for all requests.

Investigation:

1. Tested direct curl requests — all returned 403 regardless of auth header type (Bearer, x-api-key, both, none)
2. Examined Codex logs — found turn.has_metadata_header=true and error code: 1010
3. Error 1010 is Cloudflare's "Access denied" — bot detection based on User-Agent and browser headers
4. Python's urllib sends User-Agent: Python-urllib/3.x which triggers the block

Solution:

1. Added _BROWSER_HEADERS — a set of Chrome-like headers (User-Agent, Sec-Ch-Ua, Sec-Fetch-*)
2. forwarded_headers() with browser_ua=True — injects browser headers while preserving incoming client headers and filtering hop-by-hop headers
3. Applied only to openai-compat backend where Cloudflare is common
4. This resolved the 403 — upstream now returns 401 (auth) instead of 403 (bot block), confirming the headers work

Phase 6: Codex Default Mode — OAuth Without Config

Problem: Users wanted to quickly switch back to built-in Codex OAuth without maintaining a separate endpoint.

Approach:

1. Added "Codex Default (Desktop)" and "Codex Default (CLI)" buttons
2. On launch: backup config → delete config.toml entirely → start Codex → restore config after exit
3. Key insight: writing empty strings (model = "", model_provider = "") causes Codex to error with "Model provider `` not found". The config must not exist at all for Codex to fall back to built-in defaults.

---

Architecture Deep Dive

Request Flow (OpenAI-compatible provider)

Codex CLI/Desktop
    │
    │ POST /responses (Responses API)
    │ Body: { model: "glm-5.1", input: [...], stream: true }
    ▼
┌─────────────────────────────────┐
│  translate-proxy.py (port 8080) │
│                                 │
│  1. Parse Responses API body    │
│  2. Convert input → messages    │
│  3. Convert tools format        │
│  4. Inject browser UA headers   │
│                                 │
│  POST /v1/chat/completions      │──→  Upstream Provider
│  Body: { model, messages, ... }│      (opencode.ai, z.ai, etc.)
│                                 │
│  5. Receive Chat Comp. response │  ←── SSE stream or JSON
│  6. Convert response format     │
│  7. Emit Responses API SSE      │
│                                 │
└─────────────────────────────────┘
    │
    │ SSE: response.created
    │ SSE: response.output_text.delta  (streamed tokens)
    │ SSE: response.output_text.done
    │ SSE: response.completed
    ▼
Codex CLI/Desktop (receives Responses API events)

Config Lifecycle

┌─────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌─────────┐
│ Backup   │───→│ Cleanup  │───→│ Generate │───→│ Launch   │───→│ Restore │
│ config   │    │ stale    │    │ config   │    │ Codex    │    │ config  │
│ .toml    │    │ processes│    │ + models │    │ process  │    │ from    │
│          │    │          │    │          │    │          │    │ backup  │
└─────────┘    └──────────┘    └──────────┘    └──────────┘    └─────────┘

Model Catalog Format

The launcher generates model catalog JSON with dual field naming to satisfy both Codex CLI and Codex Desktop:

{
  "models": [{
    "slug": "glm-5.1",          // CLI reads this
    "model": "glm-5.1",         // Desktop reads this
    "supported_reasoning_levels": [...],  // CLI
    "supportedReasoningEfforts": [...],   // Desktop
    ...
  }]
}

---

Provider Presets

Preset	Backend	Base URL
OpenAI	Native	https://api.openai.com/v1
Anthropic	Anthropic	https://api.anthropic.com/v1
OpenCode Zen	OpenAI-compat	https://opencode.ai/zen/v1
OpenCode Go	OpenAI-compat	https://opencode.ai/zen/go/v1
Crof.ai	OpenAI-compat	https://crof.ai/v1
NVIDIA NIM	OpenAI-compat	https://integrate.api.nvidia.com/v1
Kilo.ai	OpenAI-compat	https://api.kilo.ai/api/gateway
OpenRouter	OpenAI-compat	https://openrouter.ai/api/v1
Z.AI	OpenAI-compat	https://api.z.ai/api/coding/paas/v4
Custom	Any	User-defined

---

File Structure

src/
├── translate-proxy.py            # Translation proxy (openai-compat + anthropic)
├── codex-launcher-gui            # GTK launcher GUI
├── cleanup-codex-stale.sh        # Stale process cleanup
└── codex-launcher.desktop.template  # Desktop entry template

install.sh                        # One-command installer
README.md                         # This file

Installed Locations

~/.local/bin/translate-proxy.py       # Proxy
~/.local/bin/codex-launcher-gui       # Launcher
~/.local/bin/cleanup-codex-stale.sh   # Cleanup
~/.local/share/applications/codex-launcher.desktop  # App grid entry
~/.codex/endpoints.json               # Endpoint storage
~/.codex/config.toml                  # Codex config (auto-generated)
~/.cache/codex-proxy/                 # Proxy configs + model catalogs

---

Troubleshooting

Issue	Cause	Fix
Window opens then disappears	Stale processes from previous session	Click Kill && Cleanup
Window never opens	Startup freeze	Kill && Cleanup, then retry
"Model provider `` not found"	Empty strings in config	V2 deletes config entirely for Default mode
403 Forbidden from OpenCode	Cloudflare bot detection	Proxy injects browser UA headers
401 Unauthorized from OpenCode	Invalid key or no credits	Check API key and billing
Double path in URL	Stale /chat/completions in base URL	normalize_base_url() strips suffixes
Proxy stops when terminal closes	SIGHUP to subprocess	Launcher uses os.setsid process groups
Models not showing in picker	Wrong model catalog format	Must have both slug + model fields
Codex hangs in "thinking"	Missing response.completed	Proxy emits full SSE event sequence

---

Adding a New Provider

1. Click Manage Endpoints → Add
2. Choose a preset or set Custom
3. Set backend type: OpenAI-compatible, Anthropic, or Native
4. Enter base URL and API key
5. Click Fetch from API or add models manually
6. Save and launch

For providers behind Cloudflare, the proxy automatically injects browser headers. For providers with non-standard APIs, add a new backend module to translate-proxy.py following the oa_* / an_* pattern.

---

Manual Proxy Usage

# Start proxy for any OpenAI-compatible provider
python3 src/translate-proxy.py \
  --backend openai-compat \
  --target-url https://api.your-provider.com/v1 \
  --api-key YOUR_KEY \
  --port 8080

# Or use a JSON config
python3 src/translate-proxy.py --config my-proxy-config.json

# Then run Codex
codex --profile my-profile -c model=my-model

---

Requirements

• Python ≥ 3.8
• python3-gi (sudo apt install python3-gi)
• Codex CLI ≥ 2.0
• Codex Desktop (optional, for Desktop mode)
• bash, curl, lsof

No pip dependencies. Zero. Pure stdlib + system GTK.

---

License

MIT

---

Get 10% OFF Z.AI coding plans