Introduction

Many developers attempt to connect domestic foundation models such as DeepSeek, Kimi, GLM and MiniMax to the Codex desktop client, yet most run into persistent configuration failures. Two hidden technical mechanisms create the primary roadblocks: Codex Desktop filters visible model options according to authenticated login identity, and domestic LLM providers expose the standard Chat Completions interface while newer Codex releases expect the Responses protocol. Direct forwarding will trigger model list failures, streaming parsing errors and 404 responses.

CC Switch solves both challenges with a local protocol conversion routing layer running on 127.0.0.1:15721. The complete workflow consists of six standardized steps: complete official Codex authentication, activate application enhancement mode, add domestic LLM providers, enable local routing, activate configured model endpoints, and fully restart Codex. This tutorial covers all configuration details, common pitfalls, validation standards and troubleshooting workflows, built for CC Switch v3.18.0 and the latest Codex Desktop and CLI releases. When operating multi-protocol LLM routing pipelines, teams can leverage Treerouter to standardize request transformation logic across heterogeneous client applications.

1. Two Critical Hidden Mechanisms Behind Configuration Failures

Nearly all unsuccessful deployments stem from misunderstanding these two built-in behaviors, not simple parameter mistakes.

1. Codex Desktop Client Model Visibility Gate

Observed phenomenon: After switching CC Switch to a domestic model provider, the graphical Codex client only displays official default models. Custom configured models vanish from the selection menu, although CLI invocations via codex /model operate normally.

Official CC Switch documentation confirms this behavior originates inside Codex, not the forwarding middleware. The desktop UI filters available models based on active official login sessions. If the platform detects no valid ChatGPT / Codex official account authentication record, it hides third-party model definitions. The Codex development team marked native display of custom providers inside the graphical interface as a low-priority feature, meaning we cannot resolve this purely via CC Switch UI adjustments. The viable workaround is retaining persistent official Codex authentication while routing real inference traffic to domestic LLMs.

2. Protocol Mismatch Between Two API Standards

Protocol Consumer Endpoint Path
Responses API New Codex Desktop / CLI /v1/responses
Chat Completions DeepSeek, Kimi, GLM, MiniMax domestic services /v1/chat/completions

The two protocols adopt distinct request schemas, streaming event formats and response structures. Directly forwarding Chat Completions traffic into Codex will break streaming parsing, return 404 errors or hide model entries. CC Switch addresses this by deploying a local bidirectional conversion layer:

  1. Codex sends Requests-format payloads to the local gateway
  2. The router transforms traffic into Chat Completions format and forwards to domestic LLM endpoints
  3. Incoming model responses are converted back into Responses schema before relaying to Codex

2. Pre-Deployment Preparation Checklist

Follow official requirements to gather all necessary resources before starting configuration:

  1. Install CC Switch v3.16.1 or newer; v3.18.0 is recommended for full feature support.
  2. Complete installation of Codex Desktop and Codex CLI.
  3. Register a valid official ChatGPT / Codex account; free subscription tiers satisfy authentication requirements.
  4. Obtain API keys for your selected domestic LLM: DeepSeek, Kimi, GLM or MiniMax.

Important security reminder: Avoid copying or sharing ~/.codex/auth.json. This file stores official authentication sessions and access tokens containing sensitive credentials.

3. Six-Step Standard Deployment Workflow

Step 1: Switch to OpenAI Official and Complete Codex Login

Inside CC Switch, navigate to the Codex tab, select OpenAI Official and set it as active provider. Launch Codex Desktop or CLI and finish official account login.

Successful authentication creates persistent session data within ~/.codex/auth.json. Our subsequent configuration will preserve this authentication file to bypass Codex’s model visibility gate, while routing actual inference traffic to domestic foundation models.

Step 2: Activate Codex Application Enhancement Mode

Inside CC Switch settings, open General → Codex Application Enhancement, and enable the toggle named "Preserve official login when switching third-party providers". This option is disabled by default.

After activation, switching providers only updates config.toml with model endpoints, provider identifiers and bearer tokens, without overwriting the official authentication data stored inside auth.json.

Step 3: Add Domestic LLM Providers Using Built-in Presets

On the Codex provider management page, click to add new providers. Predefined presets are strongly recommended: templates contain validated base URLs, default model identifiers, reasoning parameters and automatic local routing toggles. Core preset reference data:

Provider Preset Name Base URL Default Model Native Protocol
DeepSeek DeepSeek https://api.deepseek.com DeepSeek V4 Flash Chat Completions
Kimi Open Platform kimi https://api.moonshot.cn/v1 kimi-k2.7-code Chat Completions
Kimi For Coding Kimi For Coding https://api.kimi.com/coding/v1 kimi-for-coding Chat Completions
GLM GLM https://open.bigmodel.cn/api/paas/v4 GLM-5.2 Chat Completions
MiniMax MiniMax Official preset available Default variant Chat Completions

After selecting a preset, simply input your API secret key and save the provider configuration.

Step 4: Enable Local Routing and Codex Relay

Navigate to Settings → Routing → Local Routing and activate two core switches:

  1. Global routing master toggle: Starts local conversion service at default address 127.0.0.1:15721.
  2. Codex relay toggle: Enables protocol transformation for traffic targeting domestic Chat Completions endpoints.

Critical note: Providers using native Responses API do not require relay activation. All domestic LLMs listed above rely on Chat Completions and must use the relay.

Step 5: Activate The Newly Configured Provider

Return to the provider list and activate your domestic LLM entry. If the UI displays the label Requires Routing, confirm the local routing service is active.

Step 6: Fully Exit and Restart Codex

A simple window close is insufficient. Terminate all Codex background processes and relaunch. Codex loads config.toml and refreshes the model catalog only during startup.

4. Validation Checklist For Successful Deployment

Execute these checks to confirm end-to-end functionality:

Inspection Item Expected Result
Codex official account status Still displays official logged-in identity (normal behavior, not a failure)
CC Switch active provider Shows the domestic LLM you configured
Local routing access logs Capture Codex request traffic passing through the conversion layer
Third-party platform backend logs Record model invocation traffic originating from your client
Codex CLI /model command Lists all imported domestic model identifiers

Under the hood, auth.json retains official login credentials so the Codex UI permits model selection. All real inference traffic follows the transformed routing defined inside config.toml toward domestic LLM endpoints.

5. Key Side Effects & Common Misunderstandings

  1. UI shows official account identity, traffic routes to domestic models The enhancement mode separates authentication identity from inference backend. The desktop client reads auth.json for UI access control, while actual requests use the endpoint defined inside config.toml. Do not judge routing success purely based on visible account information. Inspect gateway traffic logs for confirmation.

  2. Official authentication sessions will eventually expire Long periods without opening Codex invalidate cached tokens. When this happens, model lists may disappear. Repeating the official login workflow restores normal operation.

  3. Codex only supports one active provider per launch Multiple domestic models cannot run simultaneously within a single Codex instance. Switching providers requires restarting the application. Teams requiring concurrent multi-model access should launch separate Codex processes pointing to independent configuration directories.

6. Systematic Troubleshooting Guide

Problem 1: Custom models remain invisible after enabling enhancement mode

  1. Verify the application enhancement toggle is enabled; this setting resets after CC Switch restarts.
  2. Confirm official authentication tokens are still valid; repeat Codex login.
  3. Test via codex /model CLI command. If the terminal lists models correctly, the configuration works, and only the graphical UI gate restriction remains.

Problem 2: Requests return 404 errors

Most frequently caused by duplicated /v1 path segments. Double-check preset base URL formatting and confirm local routing relay is activated for Chat Completions providers.

Problem 3: Streaming responses parse incorrectly

Confirmed root cause: missing protocol conversion. Re-enable the Codex relay switch inside local routing settings.

7. How To Select Between The Four Domestic LLM Providers

DeepSeek V4 Flash

Best suited for daily engineering tasks, general knowledge QA, lightweight repository analysis; metered token billing.

Kimi k2.7-code

Optimized for long document comprehension and multi-file code iteration; available via open platform pay-as-you-go billing.

Kimi For Coding

Targeted at large-scale agentic software development; subscription-based access model.

GLM-5.2

Balanced general-purpose and coding capabilities; flexible subscription and metered options.

Recommended rollout strategy: Validate one provider end-to-end first, stabilize routing and protocol conversion, then add additional model entries to avoid overlapping troubleshooting variables.

8. Conclusion

Connecting domestic Chinese foundation models to Codex Desktop hinges on overcoming two fundamental obstacles: the client’s identity-based model visibility filtering, and the mismatch between Responses and Chat Completions API schemas. CC Switch resolves both via persistent authentication retention and local bidirectional protocol conversion.

The six-step standardized workflow eliminates most misconfiguration risks, but operators must remember critical operational rules: fully restart Codex after every configuration change, keep local routing activated for all Chat Completions providers, and never rely purely on UI account status to audit real traffic destinations.

As domestic LLM ecosystems mature, unified protocol translation gateways become essential middleware for mixing international desktop AI clients and regional model services. With proper routing layering, developers can retain familiar tooling while leveraging local, cost-effective foundation model deployments.