codex-cli-model-bridge

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: codex-cli-model-bridge
description: Install, audit, repair, and manage Codex custom model
  Providers and model catalogs backed by a loopback CLIProxyAPI or Codex
  Router. Use whenever the user asks to add, remove, upgrade, restore, or
  diagnose third-party models in Codex or the Codex desktop model picker;
  mentions Grok, OpenCode Go, DeepSeek, Gemini, GLM Coding Plan, GLM-5.3,
  subscription-backed CLI models, custom model_provider, model_catalog_json,
  or Codex Fast mode; or wants the same local proxy models synchronized
  between Codex and WorkBuddy. Preserve unrelated Codex configuration and
  credentials. Isolated profile is the default Windows path.
---

# Codex CLI Model Bridge

Manage subscription-backed or local proxy models in Codex without treating Codex like WorkBuddy. Codex uses a Responses API Provider plus a model catalog; WorkBuddy uses independent JSON entries. Share CLIProxyAPI infrastructure and verified Provider facts, but keep each application's writer and state separate.

Codex selects one `model_provider` for a task. Model catalog entries do not carry per-model Provider routing. Preserve the Provider identity that owns the majority of indexed task history (normally `openai`). For normal Desktop use, the supported bridge design keeps `model_provider = "openai"`, keeps ChatGPT subscription auth intact, and points the built-in Provider's `openai_base_url` at an owner-only loopback header-rewriting proxy. CLIProxyAPI then routes native GPT subscription models and verified third-party models behind one catalog without changing the task Provider identity. Keep the isolated `$CODEX_HOME/cli-proxy.config.toml` profile as the default path on Windows and as a fallback everywhere else.

This is transparent single-Provider routing, not per-model Provider routing. Never set the Desktop default to `cli_proxy` or vendor `ZAI` when most history belongs to `openai`.

When the user wants GLM-5.3 from a Coding Plan key, read [glm-coding-plan.md](references/glm-coding-plan.md). If Desktop already uses Codex Router on port 4202, add `zai-coding` there and keep the OpenAI Provider identity. Do not run `npx @z_ai/coding-helper`.

On Windows, start with the isolated profile. Read [windows.md](references/windows.md). Do not require Homebrew, LaunchAgents, or Codex Router.

## Resolve the Skill directory

Resolve this loaded Skill's directory as `<skill-dir>`. Resolve `<python>` as the first available of `python3`, `py -3`, and `python`. Use the deterministic entry point:

```bash
<python> <skill-dir>/scripts/bridge.py
```

Examples below use `python3`. Substitute `<python>` when that command is missing.

## Default workflow

### 1. Audit before mutation

```bash
python3 <skill-dir>/scripts/bridge.py audit
```

The audit must redact secrets and verify:

- Codex CLI version, `~/.codex/config.toml`, file permissions, and TOML validity
- default `model_provider`, indexed task counts by Provider, SQLite integrity, and the dominant history Provider
- active bridge mode: Desktop-transparent or isolated-profile
- Desktop-transparent `openai_base_url`, ChatGPT auth continuity, loopback health, or the isolated profile's command-backed authentication
- loopback-only CLIProxyAPI reachability and live `/v1/models`
- the active catalog's validity, visible model IDs, and bridge ownership state
- stale catalog entries, missing live routes for managed models, listed native models, or the current default model, and models present in the proxy but absent from Codex

Codex officially supports only the Responses wire API for custom Providers. Do not register a Chat Completions-only route and call it Codex-compatible.

If the default Provider differs from the dominant indexed-history Provider, treat history restoration as the first repair. Do not edit task rows to make the current Provider fit.

### 2. Restore the desktop default and history

Preview:

```bash
python3 <skill-dir>/scripts/bridge.py restore-default
```

The preview repor