Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

codex-cli-model-bridge

Install, audit, repair, and manage Codex custom model

zjp1997720 · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add zjp1997720/zhijian-skills --skill codex-cli-model-bridge

About this skill


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. 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. 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:

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

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

Default workflow

1. Audit before mutation

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:

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

The preview reports one finding ID, the current config SHA-256, the exact single-file diff, and the before-state thread inventory. Apply only after the repair is authorized and the SHA is still current:

python3 <skill-dir>/scripts/bridge.py restore-default \
  --expected-sha256 <approved-sha256> \
  --apply

The default target is the Provider with the largest indexed task count. The command refuses a minority Provider unless --allow-minority-provider is explicit, restores a native model, removes the custom root catalog override, preserves unrelated TOML, creates a 0600 backup, and proves the task inventory digest did not change.

3. Configure or repair the isolated CLIProxyAPI profile

This is the default path on Windows. Preview and apply:

python3 <skill-dir>/scripts/bridge.py configure
python3 <skill-dir>/scripts/bridge.py configure --apply

The command does not rewrite ~/.codex/config.toml. It preserves unrelated profile sections, creates timestamped 0600 backups, installs an owner-only credential helper that reads the existing CLIProxyAPI client key without copying it, and configures ~/.codex/cli-proxy.config.toml with:

  • model_provider = "cli_proxy"
  • model_catalog_json = "~/.codex/model-catalog-cli-proxy.json"
  • [model_providers.cli_proxy] with a loopback URL and wire_api = "responses"
  • [model_providers.cli_proxy.auth] using the local helper command

The helper is Python by default so Windows does not need Ruby. An existing .rb helper is left in place. Do not set or change the user's default model unless they explicitly ask. Do not overwrite built-in Provider IDs. After this profile exists, use codex --profile cli-proxy.

4. Synchronize the profile model catalog

Preview bundled models:

python3 <skill-dir>/scripts/bridge.py sync

Apply after live route verification:

python3 <skill-dir>/scripts/bridge.py sync --apply

The sync command starts with Codex's native model cache only to inherit requ

Read the complete source ↗